Skip to content

Commit

Permalink
Editorial: Properly format enum strings (#418)
Browse files Browse the repository at this point in the history 
Before: `{{PermissionState/"granted"}}`
After: `"{{PermissionState/granted}}"`

See whatwg/fs#133. Also called out here: #417 (comment)
  • Loading branch information
@a-sully
a-sully committed Jun 20, 2023
1 parent a350a87 commit 44df0c4
Showing 1 changed file with 71 additions and 53 deletions.
124 changes: 71 additions & 53 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -151,7 +155,7 @@ To <dfn lt="querying file system permission|query file system permission">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=].
Expand All @@ -163,17 +167,20 @@ To <dfn lt="requesting file system permission|request file system permission">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 <a spec=permissions>create a PermissionStatus</a> 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=].

</div>

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}

Expand All @@ -192,25 +199,32 @@ partial interface FileSystemHandle {
### The {{FileSystemHandle/queryPermission()}} method ### {#api-filesystemhandle-querypermission}

<div class="note domintro">
: |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.
</div>

Advisement: The integration with the permissions API's {{Permissions/query()}} method is not yet implemented in Chrome.
Expand All @@ -230,21 +244,25 @@ The <dfn method for=FileSystemHandle>queryPermission(|descriptor|)</dfn> method,
### The {{FileSystemHandle/requestPermission()}} method ### {#api-filesystemhandle-requestpermission}

<div class="note domintro">
: |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.
</div>

<div algorithm>
Expand Down Expand Up @@ -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}}".

<div algorithm>
To verify that an |environment| <dfn>is allowed to show a file picker</dfn>, run these steps:
Expand Down Expand Up @@ -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 = {
<l>{{FilePickerOptions/id}}</l>: 'foo', // Unmapped.
<l>{{FilePickerOptions/startIn}}</l>: <l>{{WellKnownDirectory/"downloads"}}</l>, // Start here.
<l>{{FilePickerOptions/startIn}}</l>: "<l>{{WellKnownDirectory/downloads}}</l>", // Start here.
};

// Later...
Expand All @@ -546,7 +564,7 @@ const options = {
// might have been evicted.
const options = {
<l>{{FilePickerOptions/id}}</l>: 'foo', // Maybe mapped. If so, start here.
<l>{{FilePickerOptions/startIn}}</l>: <l>{{WellKnownDirectory/"downloads"}}</l>, // Otherwise, start here.
<l>{{FilePickerOptions/startIn}}</l>: "<l>{{WellKnownDirectory/downloads}}</l>", // Otherwise, start here.
};
</pre>

Expand Down Expand Up @@ -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 <a spec=html>activation notification</a> steps in |global|'s [=Window/browsing context=].
Expand Down

0 comments on commit 44df0c4

Please sign in to comment.