From 44df0c4eeaca7083b0f4b60ea766cd2a314cd372 Mon Sep 17 00:00:00 2001 From: Austin Sullivan Date: Tue, 20 Jun 2023 17:35:47 -0400 Subject: [PATCH] Editorial: Properly format enum strings (#418) Before: `{{PermissionState/"granted"}}` After: `"{{PermissionState/granted}}"` See whatwg/fs#133. Also called out here: #417 (comment) --- index.bs | 124 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 71 insertions(+), 53 deletions(-) diff --git a/index.bs b/index.bs index 7900368..0e4c4ef 100644 --- a/index.bs +++ b/index.bs @@ -112,16 +112,19 @@ permission-related algorithms and types are defined as follows: 1. Let |entry| be |desc|.{{FileSystemPermissionDescriptor/handle}}'s [=FileSystemHandle/entry=]. 1. If |entry| represents a [=/file system entry=] in a [=/bucket file system=], - this descriptor's [=permission state=] must always be {{PermissionState/"granted"}}. + this descriptor's [=permission state=] must always be + "{{PermissionState/granted}}". 1. Otherwise, if |entry|'s [=file system entry/parent=] is not null, this descriptor's [=permission state=] must be - equal to the [=permission state=] for a descriptor with the same {{FileSystemPermissionDescriptor/mode}}, - and a {{FileSystemPermissionDescriptor/handle}} representing |entry|'s [=file system entry/parent=]. - 1. Otherwise, if |desc|.{{FileSystemPermissionDescriptor/mode}} is {{"readwrite"}}: + equal to the [=permission state=] for a descriptor with the same {{FileSystemPermissionDescriptor/mode}}, + and a {{FileSystemPermissionDescriptor/handle}} representing |entry|'s [=file system entry/parent=]. + 1. Otherwise, if |desc|.{{FileSystemPermissionDescriptor/mode}} is + "{{FileSystemPermissionMode/readwrite}}": 1. Let |read state| be the [=permission state=] for a descriptor - with the same {{FileSystemPermissionDescriptor/handle}}, - but {{FileSystemPermissionDescriptor/mode}} = {{"read"}}. - 1. If |read state| is not {{PermissionState/"granted"}}, this descriptor's [=permission state=] - must be equal to |read state|. + with the same {{FileSystemPermissionDescriptor/handle}}, + but whose {{FileSystemPermissionDescriptor/mode}} is + "{{FileSystemPermissionMode/read}}". + 1. If |read state| is not "{{PermissionState/granted}}", this descriptor's [=permission state=] + must be equal to |read state|. Issue(whatwg/fs#101): Make these checks no longer associated with an entry. @@ -131,7 +134,8 @@ Issue(whatwg/fs#101): Make these checks no longer associated with an entry. run these steps: 1. Run the [=default permission query algorithm=] on |desc| and |status|. - 1. If |status|.{{PermissionStatus/state}} is not {{PermissionState/"prompt"}}, abort. + 1. If |status|.{{PermissionStatus/state}} is not "{{PermissionState/prompt}}", + then abort these steps. 1. Let |settings| be |desc|.{{FileSystemPermissionDescriptor/handle}}'s [=relevant settings object=]. 1. Let |global| be |settings|'s [=environment settings object/global object=]. 1. If |global| is not a {{Window}}, then @@ -151,7 +155,7 @@ To query given a {{FileSystemHandle}} |handle| and a {{FileSystemPermissionMode}} |mode|, run these steps: 1. Let |desc| be a {{FileSystemPermissionDescriptor}}. -1. Set |desc|.{{PermissionDescriptor/name}} to {{"file-system"}}. +1. Set |desc|.{{PermissionDescriptor/name}} to "{{PermissionName/file-system}}". 1. Set |desc|.{{FileSystemPermissionDescriptor/handle}} to |handle|. 1. Set |desc|.{{FileSystemPermissionDescriptor/mode}} to |mode|. 1. Return |desc|'s [=permission state=]. @@ -163,17 +167,20 @@ To re given a {{FileSystemHandle}} |handle| and a {{FileSystemPermissionMode}} |mode|, run these steps: 1. Let |desc| be a {{FileSystemPermissionDescriptor}}. -1. Set |desc|.{{PermissionDescriptor/name}} to {{"file-system"}}. +1. Set |desc|.{{PermissionDescriptor/name}} to "{{PermissionName/file-system}}". 1. Set |desc|.{{FileSystemPermissionDescriptor/handle}} to |handle|. 1. Set |desc|.{{FileSystemPermissionDescriptor/mode}} to |mode|. 1. Let |status| be the result of running create a PermissionStatus for |desc|. -1. Run the [=permission request algorithm=] for the {{"file-system"}} feature, given |desc| and |status|. +1. Run the [=permission request algorithm=] for the + "{{PermissionName/file-system}}" feature, given |desc| and |status|. 1. Return |desc|'s [=permission state=]. -Issue(119): Currently {{FileSystemPermissionMode}} can only be {{"read"}} or {{"readwrite"}}. In -the future we might want to add a "write" mode as well to support write-only handles. +Issue(119): Currently {{FileSystemPermissionMode}} can only be +"{{FileSystemPermissionMode/read}}" or "{{FileSystemPermissionMode/readwrite}}". +In the future we might want to add a "write" mode as well to support write-only +handles. ## The {{FileSystemHandle}} interface ## {#api-filesystemhandle} @@ -192,25 +199,32 @@ partial interface FileSystemHandle { ### The {{FileSystemHandle/queryPermission()}} method ### {#api-filesystemhandle-querypermission}
- : |status| = await |handle| . {{FileSystemHandle/queryPermission()|queryPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : {{"read"}} }) + : |status| = await |handle| . {{FileSystemHandle/queryPermission()|queryPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : "{{FileSystemPermissionMode/read}}" }) : |status| = await |handle| . {{FileSystemHandle/queryPermission()}} - : |status| = (await navigator.{{Navigator/permissions}}.{{Permissions/query()|query}}({ {{PermissionDescriptor/name}} : "file-system", {{FileSystemPermissionDescriptor/handle}} : |handle| })).{{PermissionStatus/state}} - :: Queries the current state of the read permission of this handle. If this returns `"prompt"` - the website will have to call {{FileSystemHandle/requestPermission()}} before any - operations on the handle can be done. If this returns `"denied"` any operations will reject. - - Usually handles returned by the [=local file system handle factories=] will initially return `"granted"` for - their read permission state, however other than through the user revoking permission, a handle - retrieved from IndexedDB is also likely to return `"prompt"`. - - : |status| = await |handle| . {{FileSystemHandle/queryPermission()|queryPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : {{"readwrite"}} }) - : |status| = (await navigator.{{Navigator/permissions}}.{{Permissions/query()|query}}({ {{PermissionDescriptor/name}} : "file-system", {{FileSystemPermissionDescriptor/handle}} : |handle|, {{FileSystemPermissionDescriptor/mode}} : {{"readwrite"}}}).{{PermissionStatus/state}} - :: Queries the current state of the write permission of this handle. If this returns `"prompt"`, - attempting to modify the file or directory this handle represents will require user activation - and will result in a confirmation prompt being shown to the user. However if the state of the - read permission of this handle is also `"prompt"` the website will need to call - {{FileSystemHandle/requestPermission()}}. There is no automatic prompting for read access when - attempting to read from a file or directory. + : |status| = (await navigator.{{Navigator/permissions}}.{{Permissions/query()|query}}({ {{PermissionDescriptor/name}} : "{{PermissionName/file-system}}", {{FileSystemPermissionDescriptor/handle}} : |handle| })).{{PermissionStatus/state}} + :: Queries the current state of the read permission of this handle. + If this returns "{{PermissionState/prompt}}" the website will have to call + {{FileSystemHandle/requestPermission()}} before any operations on the + handle can be done. + If this returns "{{PermissionState/denied}}" any operations will reject. + + Usually handles returned by the [=local file system handle factories=] will + initially return "{{PermissionState/granted}}" for their read permission + state, however other than through the user revoking permission, a handle + retrieved from IndexedDB is also likely to return + "{{PermissionState/prompt}}". + + : |status| = await |handle| . {{FileSystemHandle/queryPermission()|queryPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : "{{FileSystemPermissionMode/readwrite}}" }) + : |status| = (await navigator.{{Navigator/permissions}}.{{Permissions/query()|query}}({ {{PermissionDescriptor/name}} : "{{PermissionName/file-system}}", {{FileSystemPermissionDescriptor/handle}} : |handle|, {{FileSystemPermissionDescriptor/mode}} : "{{FileSystemPermissionMode/readwrite}}" }).{{PermissionStatus/state}} + :: Queries the current state of the write permission of this handle. + If this returns "{{PermissionState/prompt}}", attempting to modify the + file or directory this handle represents will require user activation + and will result in a confirmation prompt being shown to the user. + However if the state of the read permission of this handle is also + "{{PermissionState/prompt}}" the website will need to call + {{FileSystemHandle/requestPermission()}}. + There is no automatic prompting for read access when attempting to + read from a file or directory.
Advisement: The integration with the permissions API's {{Permissions/query()}} method is not yet implemented in Chrome. @@ -230,21 +244,25 @@ The queryPermission(|descriptor|) method, ### The {{FileSystemHandle/requestPermission()}} method ### {#api-filesystemhandle-requestpermission}
- : |status| = await |handle| . {{FileSystemHandle/requestPermission()|requestPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : {{"read"}} }) + : |status| = await |handle| . {{FileSystemHandle/requestPermission()|requestPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : "{{FileSystemPermissionMode/read}}" }) : |status| = await |handle| . {{FileSystemHandle/requestPermission()}} - :: If the state of the read permission of this handle is anything other than `"prompt"`, this - will return that state directly. If it is `"prompt"` however, user activation is needed and - this will show a confirmation prompt to the user. The new read permission state is then - returned, depending on the user's response to the prompt. - - : |status| = await |handle| . {{FileSystemHandle/requestPermission()|requestPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : {{"readwrite"}} }) - :: If the state of the write permission of this handle is anything other than `"prompt"`, this - will return that state directly. If the status of the read permission of this handle is - `"denied"` this will return that. - - Otherwise the state of the write permission is `"prompt"` and this will show a confirmation - prompt to the user. The new write permission state is then returned, depending on what the user - selected. + :: If the state of the read permission of this handle is anything other than + "{{PermissionState/prompt}}", this will return that state directly. + If it is "{{PermissionState/prompt}}" however, user activation is needed and + this will show a confirmation prompt to the user. + The new read permission state is then returned, depending on + the user's response to the prompt. + + : |status| = await |handle| . {{FileSystemHandle/requestPermission()|requestPermission}}({ {{FileSystemHandlePermissionDescriptor/mode}} : "{{FileSystemPermissionMode/readwrite}}" }) + :: If the state of the write permission of this handle is anything other than + "{{PermissionState/prompt}}", this will return that state directly. + If the status of the read permission of this handle is + "{{PermissionState/denied}}" this will return that. + + Otherwise the state of the write permission is "{{PermissionState/prompt}}" + and this will show a confirmation prompt to the user. + The new write permission state is then returned, depending on + what the user selected.
@@ -324,13 +342,13 @@ The fact that the user picked the specific files returned by the [=local file sy should be treated by the user agent as the user intending to grant read access to the website for the returned files. As such, at the time the promise returned by one of the [=local file system handle factories=] resolves, [=permission state=] for a descriptor with {{FileSystemPermissionDescriptor/handle}} set to the returned handle, -and {{FileSystemPermissionDescriptor/mode}} set to {{"read"}} -should be {{PermissionState/"granted"}}. +and {{FileSystemPermissionDescriptor/mode}} set to "{{FileSystemPermissionMode/read}}" +should be "{{PermissionState/granted}}". Additionally for calls to {{showSaveFilePicker}} the [=permission state=] for a descriptor with {{FileSystemPermissionDescriptor/handle}} set to the returned handle, -and {{FileSystemPermissionDescriptor/mode}} set to {{readwrite}} -should be {{PermissionState/"granted"}}. +and {{FileSystemPermissionDescriptor/mode}} set to "{{FileSystemPermissionMode/readwrite}}" +should be "{{PermissionState/granted}}".
To verify that an |environment| is allowed to show a file picker, run these steps: @@ -537,7 +555,7 @@ via the {{WellKnownDirectory}} is used. // The file picker will fall back to opening to the Downloads directory. TODO: link this. const options = { {{FilePickerOptions/id}}: 'foo', // Unmapped. - {{FilePickerOptions/startIn}}: {{WellKnownDirectory/"downloads"}}, // Start here. + {{FilePickerOptions/startIn}}: "{{WellKnownDirectory/downloads}}", // Start here. }; // Later... @@ -546,7 +564,7 @@ const options = { // might have been evicted. const options = { {{FilePickerOptions/id}}: 'foo', // Maybe mapped. If so, start here. - {{FilePickerOptions/startIn}}: {{WellKnownDirectory/"downloads"}}, // Otherwise, start here. + {{FilePickerOptions/startIn}}: "{{WellKnownDirectory/downloads}}", // Otherwise, start here. }; @@ -867,7 +885,7 @@ these steps: 1. [=Request permission to use=] |desc|. 1. Run the [=default permission query algorithm=] on |desc| and |status|. - 1. If |status| is not {{PermissionState/"granted"}}, + 1. If |status| is not "{{PermissionState/granted}}", [=/reject=] |result| with a "{{AbortError}}" {{DOMException}} and abort. 1. Perform the activation notification steps in |global|'s [=Window/browsing context=].