Initial draft for element definition.

permission-element.bs

@@ -19,7 +19,156 @@ Abstract: A `<permission>` HTML element to request browser permissions in-page.
   the current permission flows.
 </pre>
 
+<style>
+/* Imitate some styles that W3C specs use:*/
+
+/* WHATWG-style element definition class */
+.element { background: #EEFFEE; }
+dt { margin-top: 12px; color: black; }
+dl, dd { padding-left: .5em; }
+
+/* Boxes around algorithms. */
+[data-algorithm]:not(.heading) {
+  padding: .5em;
+  border: thin solid #ddd; border-radius: .5em;
+  margin: .5em calc(-0.5em - 1px);
+}
+[data-algorithm]:not(.heading) > :first-child   margin-top: 0; }
+[data-algorithm]:not(.heading) > :last-child { margin-bottom: 0; }
+[data-algorithm] [data-algorithm] { margin: 1em 0; }
+
+/* vars in italics */
+dfn var { font-style: italic; }
+</style>
+
 # Introduction # {#intro}
-# Framework # {#framwork}
+# The <dfn element export>permission</dfn> element. # {#the-permission-element}
+
+<dl class="element">
+ <dt>[=Categories=]:</dt>
+  <dd>[=Flow content=].</dd>
+  <dd>[=Phrasing content=].</dd>
+  <dd>[=Interactive content=].</dd>
+  <dd>[=Palpable content=].</dd>
+ <dt>[=Contexts in which this element can be used=]:</dt>
+  <dd>Where [=phrasing content=] is expected.</dd>
+ <dt>[=Content model=]:</dt>
+  <dd>[=Nothing=].</dd>
+ <dt>[=Content attributes=]:</dt>
+  <dd>[=Global attributes=]</dd>
+  <dd>{{HTMLPermissionElement/type}} — Type of permission this element applies to.</dd>
+  <dd>{{HTMLPermissionElement/isValid}} — Something about validity.</dd>
+  <dd>{{HTMLPermissionElement/invalidReason}} — Something about reason.</dd>
+  <dd>{{HTMLPermissionElement/ondismiss}} — Event handler.
+  <dd>{{HTMLPermissionElement/onresolve}} — Event handler.
+  <dd>{{HTMLPermissionElement/onvalidationstatuschange}} — Event handler.
+ <dt>[=Accessibility considerations=]:</dt>
+  <dd><p class=XXX>TODO</p></dd>
+ <dt>[=DOM interface=]:</dt>
+  <dd>
+   <pre class=idl>
+    [Exposed=Window]
+    interface HTMLPermissionElement : HTMLElement {
+      [HTMLConstructor] constructor();
+      [CEReactions, Reflect] attribute DOMString type;
+
+      readonly attribute boolean isValid;
+      readonly attribute DOMString invalidReason;
+
+      attribute EventHandler onresolve;
+      attribute EventHandler ondismiss;
+      attribute EventHandler onvalidationstatuschange;
+    };
+   </pre>
+  </dd>
+</dl>
+
+ISSUE: Accessibility considerations
+
+The {{HTMLPermissionElement/type}} attribute controls the behavior of the
+permission element when it is activated. Is is an [=enumerated attribute=],
+whose values are the [=powerful feature/names=] of [=powerful features=]. It
+has neither a
+[=missing value default=] state nor a [=invalid value default=] state.
+
+ISSUE: Is `type` one permission, or a space seperated list of permissions?
+
+ISSUE: What happens on invalid types, or if a type cannot be reset?
+
+ISSUE: Current impl allows `type` to be set only once. Not reflected in spec.
+
+The {{HTMLPermissionElement/isValid}} attribute reflects whether a the permission element is in a valid state.
+
+ISSUE: Define internal states of the permission element.
+
+The {{HTMLPermissionElement/invalidReason}} attribute is an
+[=enumerated attribute=] that reflects the internal state of the permission element. It's possible values are:
+  - `"style"`
+  - `"type_count"`
+  - `"illegal_subframe"`
+  - `"covered"`
+  - `"recently_moved"`
+  - `"recently_created"`
+
+
+The following are the [=event handlers=] (and their corresponding [=event handler event types=]) that must be supported on <{permission}> elements [=event handler IDL attributes=]:
+
+<pre class=simpledef>
+onresolve: Event
+ondismiss: Event
+onvalidationstatuschange: Event
+</pre>
+
+Issue: Are all these really simple event handlers of `Event` type?
+
+
+## <{permission}> element internal state ## {#permission-element-internal-state}
+
+The <{permission}> element [=DOM/represents=] a user-requestable [=permission=],
+which the user can activate to enable (or disable) a particular permission or
+set of permissions. It is core to the <{permission}> element that these
+requests are triggered by the user, and not by the page's script. To enforce
+this, the element checks whether the activcation event is [=trusted=], and
+additionally watches a number of conditions (like whether the element is
+occluded, or it has recently been moved). To accomplish this, the element
+maintains a list of timestamped "blocker" reasons that get checked on
+activation.
+
+## <{permission}> element algorithms ## {#permission-element-algorithms}
+
+<div algorithm="HTMLPermissionElement/constructor">
+The HTMLPermissionElement constructor steps are:
+
+1. Initialize the internal `blocker` list to &laquo;[]&raquo;
+
+</div>
+
+<div algorithm>
+An HTMLPermissionElement's [=blocker=] list's |entry| is <dfn>valid</dfn> if
+
+1. |entry| has no timestamp,
+1. or |entry| has a timestamp, and the timestamp is greater or equal to the [=current high resolution time=]
+
+</div>
+
+<div algorithm="HTMLPermissionElement/blocker">
+To determine a HTMLPermissionElement |element|'s <dfn>blocker</dfn>:
+
+1. If |element|'s [=blocker=] list [=list/contains=] any |entry| which is [=valid=], then return |entry|.
+1. Return nothing.
+
+</div>
+
+<div algorithm=activation>
+A <{permission}> |element|'s [=EventTarget/activation behavior=] given |event| is:
+
+1. If |element|'s [=HTMLPermissionElement/type=] is None, then return.
+1. If |event|'s [=Event/isTrusted=] attribute is not true, then return.
+1. If |element|'s [=blocker=] is not nothing, then return.
+1. [=Request permission to use=] the powerful feature named in |element|'s [=HTMLPermissionElement/type=].
+
+Issue: What about event handlers? 
+</div>
+
 # Algorithms # {#algorithms}
 # Security & Privacy Considerations # {#secpriv}