From 5dc34f5efd4c93b7f195c4de1ee616535c190276 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Mon, 30 Oct 2017 20:57:01 +0900 Subject: [PATCH 01/13] =?UTF-8?q?Add=20domintro=20blocks=20for=20=E2=80=9C?= =?UTF-8?q?Web=20storage=E2=80=9D=20interfaces?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This change adds domintro blocks in the “Web storage” section and adds markup to cause more implementor-specific parts of that section of the spec to be supressed in the developer edition. --- source | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 117 insertions(+), 6 deletions(-) diff --git a/source b/source index ec7db8fca23..0001a1009fc 100755 --- a/source +++ b/source @@ -98129,7 +98129,7 @@ interface WorkerLocation { -->

The second storage mechanism is designed for storage that spans multiple windows, and lasts - beyond the current session. In particular, Web applications may wish to store megabytes of user + beyond the current session. In particular, Web applications might wish to store megabytes of user data, such as entire user-authored documents or a user's mailbox, on the client side for performance reasons.

@@ -98197,6 +98197,62 @@ interface Storage { implementing the Storage interface can all be associated with the same list of key/value pairs simultaneously.

+
+ +
localStorage . length
+
sessionStorage . length
+
+

Returns the number of key/value pairs currently present in the list associated with the + object.

+
+ +
localStorage . key ( n )
+
sessionStorage . key ( n )
+
+

Returns the name of the nth key in the list, or null if n is greater + than or equal to the number of key/value pairs in the object

+
+ +
localStorage . getItem ( key )
+
sessionStorage . getItem ( key )
+
+

Returns the current value associated with the given key, or null if the given + key does not exist in the list associated with the object.

+
+ +
localStorage . setItem ( key, value )
+
sessionStorage . setItem ( key, value )
+
+

Checks if a key/value pair with the given key already exists in the list associated + with the object.

+ +

If the given key does not exist, then adds a new key/value pair to the list, with + the given key and with its value set to value.

+ +

If the given key does exist in the list, and its value is not + equal to value, then updates its value to value.

+ +

Throws a "QuotaExceededError" DOMException exception + if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage + for the site, or if the quota has been exceeded.)

+ +
localStorage . removeItem ( key )
+
sessionStorage . removeItem ( key )
+
+

Removes the key/value pair with the given key from the list associated with the + object, if a key/value pair with the given key exists.

+
+ +
localStorage . clear()
+
sessionStorage . clear()
+
+

Empties the list associated with the object of all key/value pairs, if there are any.

+
+ +
+ +
+

The length attribute must return the number of key/value pairs currently present in the list associated with the object.

@@ -98228,8 +98284,7 @@ interface Storage { the method must do nothing.

If it couldn't set the new value, the method must throw a - "QuotaExceededError" DOMException exception. (Setting could - fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)

+ "QuotaExceededError" DOMException exception.

The removeItem(key) method must cause the key/value pair with the given key to be removed from the @@ -98245,6 +98300,8 @@ interface Storage { list associated with the object to be emptied of all key/value pairs, if there are any. If there are none, then the method must do nothing.

+
+

When the setItem(), removeItem(), and clear() methods are invoked, events are fired on the @@ -98274,6 +98331,8 @@ interface WindowSessionStorage {

Each top-level browsing context has a unique set of session storage areas, one for each origin.

+
+

User agents should not expire data from a browsing context's session storage areas, but may do so when the user requests that such data be deleted, or when the UA detects that it has limited storage space, or for security reasons. User agents should always avoid deleting data while a @@ -98312,6 +98371,8 @@ interface WindowSessionStorage { Window object's sessionStorage attribute's Storage object is associated with the same storage area, other than x, send a storage notification.

+
+

The localStorage attribute

@@ -98327,6 +98388,8 @@ interface WindowLocalStorage {

+
+

User agents must have a set of local storage areas, one for each origin.

User agents should expire data from the local storage areas only for security reasons or when @@ -98368,6 +98431,8 @@ interface WindowLocalStorage { Window object's localStorage attribute's Storage object is associated with the same storage area, other than x, send a storage notification. +

+

The localStorage attribute provides access to shared state. This specification does not define the interaction with other browsing contexts in a multiprocess user agent, and authors are encouraged to assume that there is no @@ -98380,9 +98445,11 @@ interface WindowLocalStorage {

The storage event

The storage event is fired on a Document's - Window object when a storage area changes, as described in the previous two sections - (for session storage, for local - storage).

+ Window object when a storage area changes, as described in the previous + two sections (for session storage, for local storage).

+ +

When a user agent is to send a storage notification for a Document, the user agent must queue a task to fire an @@ -98418,6 +98485,8 @@ interface WindowLocalStorage { Document that represents the same kind of Storage area as was affected (i.e. session or local).

+
+
The StorageEvent interface
@@ -98439,6 +98508,42 @@ dictionary StorageEventInit : EventInit { Storage? storageArea = null; }; +
+ +
event . key
+ +
+

Returns the key being changed.

+
+ +
event . oldValue
+ +
+

Returns the old value of the key being changed.

+
+ +
event . newValue
+ +
+

Returns the new value of the key being changed.

+
+ +
event . url
+ +
+

Returns the URL of the document whose key changed.

+
+ +
event . storageArea
+ +
+

Returns the Storage object that was affected.

+
+ +
+ +
+

The key attribute must return the value it was initialized to. It represents the key being changed.

@@ -98595,6 +98700,8 @@ dictionary StorageEventInit : EventInit {

To this end, user agents should ensure that when deleting data, it is promptly deleted from the underlying storage.

+
+

Security

@@ -98620,6 +98727,8 @@ dictionary StorageEventInit : EventInit { path.

+
+

Implementation risks

The two primary risks when implementing these persistent storage features are letting hostile @@ -98640,6 +98749,8 @@ dictionary StorageEventInit : EventInit { important for user security.

+
+

The HTML syntax

From 0c1067a761f7bd54b5e11f87140257338cbbdff1 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 18:09:41 +0900 Subject: [PATCH 02/13] Use Storage instead of s --- source | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/source b/source index 0001a1009fc..5c67b769020 100755 --- a/source +++ b/source @@ -98199,29 +98199,25 @@ interface Storage {
-
localStorage . length
-
sessionStorage . length
+
Storage . length

Returns the number of key/value pairs currently present in the list associated with the object.

-
localStorage . key ( n )
-
sessionStorage . key ( n )
+
Storage . key ( n )

Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object

-
localStorage . getItem ( key )
-
sessionStorage . getItem ( key )
+
Storage . getItem ( key )

Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.

-
localStorage . setItem ( key, value )
-
sessionStorage . setItem ( key, value )
+
Storage . setItem ( key, value )

Checks if a key/value pair with the given key already exists in the list associated with the object.

@@ -98236,15 +98232,13 @@ interface Storage { if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)

-
localStorage . removeItem ( key )
-
sessionStorage . removeItem ( key )
+
Storage . removeItem ( key )

Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.

-
localStorage . clear()
-
sessionStorage . clear()
+
Storage . clear()

Empties the list associated with the object of all key/value pairs, if there are any.

From a97cb5c7f5b1e4e2dee24decf4efe1d4528a35b5 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 18:28:45 +0900 Subject: [PATCH 03/13] Add missing period --- source | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source b/source index 5c67b769020..aa9a37faa06 100755 --- a/source +++ b/source @@ -98208,7 +98208,7 @@ interface Storage {
Storage . key ( n )

Returns the name of the nth key in the list, or null if n is greater - than or equal to the number of key/value pairs in the object

+ than or equal to the number of key/value pairs in the object.

Storage . getItem ( key )
From 774aa64aba5dae44db6d9061a4a6244ec5e64d03 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 18:32:32 +0900 Subject: [PATCH 04/13] Streamline the domintro for Storage.setItem --- source | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/source b/source index aa9a37faa06..878c5f8e12b 100755 --- a/source +++ b/source @@ -98219,14 +98219,8 @@ interface Storage {
Storage . setItem ( key, value )
-

Checks if a key/value pair with the given key already exists in the list associated - with the object.

- -

If the given key does not exist, then adds a new key/value pair to the list, with - the given key and with its value set to value.

- -

If the given key does exist in the list, and its value is not - equal to value, then updates its value to value.

+

Sets the value of the pair identified by key to value, creating a new + key/value pair if none existed for key previously.

Throws a "QuotaExceededError" DOMException exception if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage From 3d64cce611840e17b7f8afee491dd4fd046a2ea3 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 18:43:39 +0900 Subject: [PATCH 05/13] Restore event-firing requirements to dev edition --- source | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source b/source index 878c5f8e12b..9c708de231d 100755 --- a/source +++ b/source @@ -98352,6 +98352,8 @@ interface WindowSessionStorage {

While creating a new browsing context, the session storage area is sometimes copied over.

+ +

When the setItem(), removeItem(), and clear() methods are called on a Storage object x that is associated with a session storage area, if the methods did not throw an @@ -98359,8 +98361,6 @@ interface WindowSessionStorage { Window object's sessionStorage attribute's Storage object is associated with the same storage area, other than x, send a storage notification.

- -

The localStorage attribute

From 7c36915c111c80556b7349d4a284ba6bfe313550 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 18:46:17 +0900 Subject: [PATCH 06/13] Restore data-expiration paragraph to dev edition --- source | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source b/source index 9c708de231d..bfd7b168801 100755 --- a/source +++ b/source @@ -98319,8 +98319,6 @@ interface WindowSessionStorage {

Each top-level browsing context has a unique set of session storage areas, one for each origin.

-
-

User agents should not expire data from a browsing context's session storage areas, but may do so when the user requests that such data be deleted, or when the UA detects that it has limited storage space, or for security reasons. User agents should always avoid deleting data while a @@ -98329,6 +98327,8 @@ interface WindowSessionStorage { be discarded with it, as the API described in this specification provides no way for that data to ever be subsequently retrieved.

+
+

The lifetime of a browsing context can be unrelated to the lifetime of the actual user agent process itself, as the user agent can support resuming sessions after a restart.

From 44cfce5b1c023747d1d8c83f772b932e8bcce2bf Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 18:55:00 +0900 Subject: [PATCH 07/13] Include Disk Space, Privacy section in dev edition --- source | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source b/source index bfd7b168801..b460a25f901 100755 --- a/source +++ b/source @@ -98548,6 +98548,8 @@ dictionary StorageEventInit : EventInit { return the value it was initialized to. It represents the Storage object that was affected.

+
+

Disk space

@@ -98678,6 +98680,7 @@ dictionary StorageEventInit : EventInit { user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.

+

Sensitivity of data

From ecd5178dd2b9389334f30337cf8f31ec1b061267 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 20:03:33 +0900 Subject: [PATCH 08/13] Add domintro for window.localStorage --- source | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/source b/source index b460a25f901..1812bdf1ca3 100755 --- a/source +++ b/source @@ -98376,6 +98376,18 @@ interface WindowLocalStorage {

+
+
window . localStorage
+
+

Returns the Storage object associated with that origin's local storage + area.

+

Throws a "SecurityError" DOMException if the + Document's origin is an opaque + origin or if the request violates a policy decision (e.g. if the user agent is + configured to not allow the page to persist data).

+
+
+

User agents must have a set of local storage areas, one for each origin.

@@ -98392,10 +98404,10 @@ interface WindowLocalStorage {
    -

  1. The user agent may throw a "SecurityError" - DOMException instead of returning a Storage - object if the request violates a policy decisions (e.g. if the user agent is configured to not - allow the page to persist data).

    2. +

  2. If the request violates a policy decision (e.g. if the user agent is configured to not + allow the page to persist data), the user agent may throw a + "SecurityError" DOMException instead of returning a + Storage object

  3. If the Document's origin is an opaque origin, then throw a From 269ac43c78b909cebd4d57bff4432fdb6b33cb84 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 20:12:12 +0900 Subject: [PATCH 09/13] =?UTF-8?q?Reword=20in=20terms=20of=20=E2=80=9Cstora?= =?UTF-8?q?ge=20item=E2=80=9D=20being=20changed?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source b/source index 1812bdf1ca3..f3f6445b03f 100755 --- a/source +++ b/source @@ -98513,25 +98513,25 @@ dictionary StorageEventInit : EventInit {

    event . key
    -

    Returns the key being changed.

    +

    Returns the key of the storage item being changed.

    event . oldValue
    -

    Returns the old value of the key being changed.

    +

    Returns the old value of the key of the storage item whose value is being changed.

    event . newValue
    -

    Returns the new value of the key being changed.

    +

    Returns the new value of the key of the storage item whose value is being changed.

    event . url
    -

    Returns the URL of the document whose key changed.

    +

    Returns the URL of the document whose storage item changed.

    event . storageArea
    From 0de841abb1d2871c8990bfc911a30b4fb1b4d193 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Thu, 23 Nov 2017 20:19:13 +0900 Subject: [PATCH 10/13] Streamline StorageEvent attributes normative text --- source | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/source b/source index f3f6445b03f..59f6c3fa3eb 100755 --- a/source +++ b/source @@ -98544,21 +98544,12 @@ dictionary StorageEventInit : EventInit {
    -

    The key attribute must return the value - it was initialized to. It represents the key being changed.

    - -

    The oldValue attribute must return - the value it was initialized to. It represents the old value of the key being changed.

    - -

    The newValue attribute must return - the value it was initialized to. It represents the new value of the key being changed.

    - -

    The url attribute must return the value - it was initialized to. It represents the URL of the document whose key changed.

    - -

    The storageArea attribute must - return the value it was initialized to. It represents the Storage object that was - affected.

    +

    The key, oldValue, newValue, url, and storageArea attributes must return the values + they were initialized to.

    From 7932bad38174eef0853dd51a281ce58dc9a75d68 Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Fri, 24 Nov 2017 04:28:41 +0900 Subject: [PATCH 11/13] =?UTF-8?q?Add=20dev-edition=20=E2=80=9Csend=20a=20s?= =?UTF-8?q?torage=20notification=E2=80=9D=20dfn?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/source b/source index 59f6c3fa3eb..08a8026074a 100755 --- a/source +++ b/source @@ -98359,7 +98359,8 @@ interface WindowSessionStorage { data-x="dom-Storage-clear">clear() methods are called on a Storage object x that is associated with a session storage area, if the methods did not throw an exception or "do nothing" as defined above, then for every Document object whose Window object's sessionStorage attribute's - Storage object is associated with the same storage area, other than x, send a storage notification.

    + Storage object is associated with the same storage area, other than x, + user agents send a storage notification.

    The localStorage attribute

    @@ -98424,14 +98425,15 @@ interface WindowLocalStorage {
+
+

When the setItem(), removeItem(), and clear() methods are called on a Storage object x that is associated with a local storage area, if the methods did not throw an exception or "do nothing" as defined above, then for every Document object whose Window object's localStorage attribute's - Storage object is associated with the same storage area, other than x, send a storage notification. - -

+ Storage object is associated with the same storage area, other than x, + user agents send a storage notification.

The localStorage attribute provides access to shared state. This specification does not define the interaction with other browsing @@ -98444,10 +98446,11 @@ interface WindowLocalStorage {

The storage event

-

The storage event is fired on a Document's - Window object when a storage area changes, as described in the previous - two sections (for session storage, for local storage).

+

The storage event is fired on a Document's + Window object when a storage area changes, as described in the previous two + sections (for session storage, for + local storage).

From f477a83927002c143e469496650be9f0abf35d1a Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Wed, 29 Nov 2017 13:52:07 +0900 Subject: [PATCH 12/13] Respond to review comments --- source | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/source b/source index 08a8026074a..26cb8d6a73b 100755 --- a/source +++ b/source @@ -3060,6 +3060,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
  • The eval() function
  • The [[IsHTMLDDA]] internal slot
  • The typeof operator
    • +
  • The delete operator
  • The TypedArray Constructors table
    • @@ -98199,25 +98200,27 @@ interface Storage {
    -
    Storage . length
    +
    storage . length

    Returns the number of key/value pairs currently present in the list associated with the object.

    -
    Storage . key ( n )
    +
    storage . key ( n )

    Returns the name of the nth key in the list, or null if n is greater than or equal to the number of key/value pairs in the object.

    -
    Storage . getItem ( key )
    +
    storage . getItem ( key )
    +
    storage[key]

    Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.

    -
    Storage . setItem ( key, value )
    +
    storage . setItem ( key, value )
    +
    storage[key] = value

    Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.

    @@ -98226,13 +98229,14 @@ interface Storage { if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)

    -
    Storage . removeItem ( key )
    +
    storage . removeItem ( key )
    +
    delete  storage[key]

    Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.

    -
    Storage . clear()
    +
    storage . clear()

    Empties the list associated with the object of all key/value pairs, if there are any.

    From 13cde4548cfb4f835b47c5d329ed37e32f0a06f0 Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Thu, 30 Nov 2017 20:06:59 -0500 Subject: [PATCH 13/13] Some last domintro tweaks --- source | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/source b/source index 26cb8d6a73b..47da9bd0968 100755 --- a/source +++ b/source @@ -98212,8 +98212,8 @@ interface Storage { than or equal to the number of key/value pairs in the object.

    -
    storage . getItem ( key )
    -
    storage[key]
    +
    value = storage . getItem ( key )
    +
    value = storage[key]

    Returns the current value associated with the given key, or null if the given key does not exist in the list associated with the object.

    @@ -98230,7 +98230,7 @@ interface Storage { for the site, or if the quota has been exceeded.)

    storage . removeItem ( key )
    -
    delete  storage[key]
    +
    delete storage[key]

    Removes the key/value pair with the given key from the list associated with the object, if a key/value pair with the given key exists.

    @@ -98320,6 +98320,14 @@ interface WindowSessionStorage {

    The sessionStorage attribute represents the set of storage areas specific to the current top-level browsing context.

    +
    +
    window . sessionStorage
    +
    +

    Returns the Storage object associated with that origin's session storage + area.

    +
    +
    +

    Each top-level browsing context has a unique set of session storage areas, one for each origin.

    @@ -98349,9 +98357,8 @@ interface WindowSessionStorage {

    The sessionStorage attribute must return a Storage object associated with the Document's assigned session storage - area, if any, or null if there isn't one. Each Document object must have a separate - object for its Window's sessionStorage - attribute.

    + area. Each Document object must have a separate object for its Window's + sessionStorage attribute.

    While creating a new browsing context, the session storage area is sometimes copied over.