Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(224)

Issues Search
    My Issues | Starred     Open | Closed | All

Side by Side Diff: sky/specs/apis.md

Issue 824773002: Specs: Split apis.md into dom.md, events.md, idl.md, and move the remainder into README.md and modu… (Closed) Base URL: https://github.com/domokit/mojo.git@master
Patch Set: Created 6 years ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « sky/specs/animation.md ('k') | sky/specs/dom.md » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 APIs
2 ====
3
4 The Sky core API
5 ----------------
6
7 ```javascript
8 module 'sky:core' {
9
10 // EVENTS
11
12 class Event {
13 constructor (String type, Boolean bubbles = true, any data = null); // O(1)
14 readonly attribute String type; // O(1)
15 readonly attribute Boolean bubbles; // O(1)
16 attribute any data; // O(1)
17
18 readonly attribute EventTarget target; // O(1)
19 attribute Boolean handled; // O(1)
20 attribute any result; // O(1)
21
22 // TODO(ianh): do events get blocked at scope boundaries, e.g. focus events when both sides are in the scope?
23 // TODO(ianh): do events get retargetted, e.g. focus when leaving a custom e lement?
24 }
25
26 callback EventListener any (Event event);
27 // if the return value is not undefined:
28 // assign it to event.result
29 // set event.handled to true
30
31 abstract class EventTarget {
32 any dispatchEvent(Event event); // O(N) in total number of listeners for thi s type in the chain
33 // sets event.handled to false and event.result to undefined
34 // makes a record of the event target chain by calling getEventDispatchCha in()
35 // invokes all the handlers on the chain in turn
36 // returns event.result
37 virtual Array<EventTarget> getEventDispatchChain(); // O(1) // returns []
38 void addEventListener(String type, EventListener listener); // O(1)
39 void removeEventListener(String type, EventListener listener); // O(N) in ev ent listeners with that type
40 private Array<String> getRegisteredEventListenerTypes(); // O(N)
41 private Array<EventListener> getRegisteredEventListenersForType(String type) ; // O(N)
42 }
43
44 class CustomEventTarget : EventTarget { // implemented in JS
45 constructor (); // O(1)
46 attribute EventTarget parentNode; // getter O(1), setter O(N) in height of t ree, throws if this would make a loop
47
48 virtual Array<EventTarget> getEventDispatchChain(); // O(N) in height of tre e // implements EventTarget.getEventDispatchChain()
49 // let result = [];
50 // let node = this;
51 // while (node) {
52 // result.push(node);
53 // node = node.parentNode;
54 // }
55 // return result;
56
57 // you can inherit from this to make your object into an event target
58 // or you can inherit from EventTarget and implement your own getEventDispat chChain()
59 }
60
61
62
63 // DOM
64
65 typedef ChildNode (Element or Text);
66 typedef ChildArgument (Element or Text or String);
67
68 abstract class Node : EventTarget { // implemented in C++
69 readonly attribute TreeScope? ownerScope; // O(1)
70
71 readonly attribute ParentNode? parentNode; // O(1)
72 readonly attribute Element? parentElement; // O(1) // if parentNode isn't an element, returns null
73 readonly attribute ChildNode? previousSibling; // O(1)
74 readonly attribute ChildNode? nextSibling; // O(1)
75
76 virtual Array<EventTarget> getEventDispatchChain(); // O(N) in number of anc estors across shadow trees // implements EventTarget.getEventDispatchChain()
77 // returns the event dispatch chain (including handling shadow trees)
78
79 // the following all throw if parentNode is null
80 void insertBefore(ChildArgument... nodes); // O(N) in number of arguments pl us all their descendants
81 void insertAfter(ChildArgument... nodes); // O(N) in number of arguments plu s all their descendants
82 void replaceWith(ChildArgument... nodes); // O(N) in number of descendants p lus arguments plus all their descendants
83 void remove(); // O(N) in number of descendants
84 Node cloneNode(Boolean deep = false); // O(1) if deep=false, O(N) in the num ber of descendants if deep=true
85
86 // called when parentNode changes
87 virtual void parentChangeCallback(ParentNode? oldParent, ParentNode? newPare nt, ChildNode? previousSibling, ChildNode? nextSibling); // O(N) in descendants (calls attached/detached)
88 virtual void attachedCallback(); // noop
89 virtual void detachedCallback(); // noop
90 }
91
92 abstract class ParentNode : Node {
93 readonly attribute ChildNode? firstChild; // O(1)
94 readonly attribute ChildNode? lastChild; // O(1)
95
96 // Returns a new Array every time.
97 Array<ChildNode> getChildNodes(); // O(N) in number of child nodes
98 Array<Element> getChildElements(); // O(N) in number of child nodes // TODO( ianh): might not be necessary if we have the parser drop unnecessary whitespace text nodes
99
100 void append(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
101 void prepend(ChildArgument... nodes); // O(N) in number of arguments plus al l their descendants
102 void replaceChildrenWith(ChildArgument... nodes); // O(N) in number of desce ndants plus arguments plus all their descendants
103 }
104
105 class Attr {
106 constructor (String name, String value = ''); // O(1)
107 readonly attribute String name; // O(1)
108 readonly attribute String value; // O(1)
109 }
110
111 abstract class Element : ParentNode {
112 readonly attribute String tagName; // O(1)
113
114 Boolean hasAttribute(String name); // O(N) in number of attributes
115 String getAttribute(String name); // O(N) in number of attributes
116 void setAttribute(String name, String value = ''); // O(N) in number of attr ibutes
117 void removeAttribute(String name); // O(N) in number of attributes
118
119 // Returns a new Array and new Attr instances every time.
120 Array<Attr> getAttributes(); // O(N) in number of attributes
121
122 readonly attribute ShadowRoot? shadowRoot; // O(1) // returns the shadow roo t
123 Array<ContentElement> getDestinationInsertionPoints(); // O(N) in number of insertion points the node is in
124
125 virtual void endTagParsedCallback(); // noop
126 virtual void attributeChangeCallback(String name, String? oldValue, String? newValue); // noop
127 // TODO(ianh): does a node ever need to know when it's been redistributed?
128
129 readonly attribute ElementStyleDeclarationList style; // O(1)
130 virtual LayoutManagerConstructor getLayoutManager(RenderNode renderNode); // O(1)
131 // default implementation looks up the 'display' property and returns the value:
132 // if (renderNode)
133 // return renderNode.getProperty(phDisplay);
134 // return null;
135 readonly attribute RenderNode? renderNode; // O(1)
136 // this will be null until the first time it is rendered
137 void resetLayoutManager(); // O(1)
138 // if renderNode is non-null:
139 // sets renderNode.layoutManager to null
140 // sets renderNode.needsManager to true
141 }
142
143 class Text : Node {
144 constructor (String value = ''); // O(1)
145 attribute String value; // O(1)
146
147 void replaceWith(String node); // O(1) // special case override of Node.repl aceWith()
148
149 virtual void valueChangeCallback(String? oldValue, String? newValue); // noo p
150 }
151
152 class DocumentFragment : ParentNode {
153 constructor (ChildArguments... nodes); // O(N) in number of arguments plus a ll their descendants
154 }
155
156 abstract class TreeScope : ParentNode {
157 readonly attribute Document? ownerDocument; // O(1)
158 readonly attribute TreeScope? parentScope; // O(1)
159
160 Element? findId(String id); // O(1)
161 }
162
163 class ShadowRoot : TreeScope {
164 constructor (Element host); // O(1) // note that there is no way in the API to use a newly created ShadowRoot
165 readonly attribute Element host; // O(1)
166 }
167
168 class Document : TreeScope {
169 constructor (ChildArguments... nodes); // O(N) in number of arguments plus a ll their descendants
170 }
171
172 class SelectorQuery {
173 constructor (String selector); // O(F()) where F() is the complexity of the selector
174
175 Boolean matches(Element element); // O(F())
176 Element? find(Element root); // O(N*F())+O(M) where N is the number of desce ndants and M the average depth of the tree
177 Element? find(DocumentFragment root); // O(N*F())+O(M) where N is the number of descendants and M the average depth of the tree
178 Element? find(TreeScope root); // O(N*F()) where N is the number of descenda nts
179 Array<Element> findAll(Element root); // O(N*F())+O(N*M) where N is the numb er of descendants and M the average depth of the tree
180 Array<Element> findAll(DocumentFragment root); // O(N*F())+O(N*M) where N is the number of descendants and M the average depth of the tree
181 Array<Element> findAll(TreeScope root); // O(N*F()) where N is the number of descendants
182 }
183
184
185 // BUILT-IN ELEMENTS
186
187 class ImportElement : Element {
188 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
189 constructor (ChildArguments... nodes); // shorthand
190 constructor (Dictionary<String> attributes); // shorthand
191 constructor (); // shorthand
192 constructor attribute String tagName; // O(1) // "import"
193 constructor attribute Boolean shadow; // O(1) // false
194 }
195 class TemplateElement : Element {
196 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
197 constructor (ChildArguments... nodes); // shorthand
198 constructor (Dictionary<String> attributes); // shorthand
199 constructor (); // shorthand
200 constructor attribute String tagName; // O(1) // "template"
201 constructor attribute Boolean shadow; // O(1) // false
202
203 readonly attribute DocumentFragment content; // O(1)
204 }
205 class ScriptElement : Element {
206 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
207 constructor (ChildArguments... nodes); // shorthand
208 constructor (Dictionary<String> attributes); // shorthand
209 constructor (); // shorthand
210 constructor attribute String tagName; // O(1) // "script"
211 constructor attribute Boolean shadow; // O(1) // false
212 }
213 class StyleElement : Element {
214 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
215 constructor (ChildArguments... nodes); // shorthand
216 constructor (Dictionary<String> attributes); // shorthand
217 constructor (); // shorthand
218 constructor attribute String tagName; // O(1) // "style"
219 constructor attribute Boolean shadow; // O(1) // false
220
221 Array<Rule> getRules(); // O(N) in rules
222 }
223 class ContentElement : Element {
224 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
225 constructor (ChildArguments... nodes); // shorthand
226 constructor (Dictionary<String> attributes); // shorthand
227 constructor (); // shorthand
228 constructor attribute String tagName; // O(1) // "content"
229 constructor attribute Boolean shadow; // O(1) // false
230
231 Array<Node> getDistributedNodes(); // O(N) in distributed nodes
232 }
233 class ImgElement : Element {
234 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
235 constructor (ChildArguments... nodes); // shorthand
236 constructor (Dictionary<String> attributes); // shorthand
237 constructor (); // shorthand
238 constructor attribute String tagName; // O(1) // "img"
239 constructor attribute Boolean shadow; // O(1) // false
240 }
241 class DivElement : Element {
242 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
243 constructor (ChildArguments... nodes); // shorthand
244 constructor (Dictionary<String> attributes); // shorthand
245 constructor (); // shorthand
246 constructor attribute String tagName; // O(1) // "div"
247 constructor attribute Boolean shadow; // O(1) // false
248 }
249 class SpanElement : Element {
250 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
251 constructor (ChildArguments... nodes); // shorthand
252 constructor (Dictionary<String> attributes); // shorthand
253 constructor (); // shorthand
254 constructor attribute String tagName; // O(1) // "span"
255 constructor attribute Boolean shadow; // O(1) // false
256 }
257 class IframeElement : Element {
258 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
259 constructor (ChildArguments... nodes); // shorthand
260 constructor (Dictionary<String> attributes); // shorthand
261 constructor (); // shorthand
262 constructor attribute String tagName; // O(1) // "iframe"
263 constructor attribute Boolean shadow; // O(1) // false
264 }
265 class TElement : Element {
266 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
267 constructor (ChildArguments... nodes); // shorthand
268 constructor (Dictionary<String> attributes); // shorthand
269 constructor (); // shorthand
270 constructor attribute String tagName; // O(1) // "t"
271 constructor attribute Boolean shadow; // O(1) // false
272 }
273 class AElement : Element {
274 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
275 constructor (ChildArguments... nodes); // shorthand
276 constructor (Dictionary<String> attributes); // shorthand
277 constructor (); // shorthand
278 constructor attribute String tagName; // O(1) // "a"
279 constructor attribute Boolean shadow; // O(1) // false
280 }
281 class TitleElement : Element {
282 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
283 constructor (ChildArguments... nodes); // shorthand
284 constructor (Dictionary<String> attributes); // shorthand
285 constructor (); // shorthand
286 constructor attribute String tagName; // O(1) // "title"
287 constructor attribute Boolean shadow; // O(1) // false
288 }
289 class ErrorElement : Element {
290 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
291 constructor (ChildArguments... nodes); // shorthand
292 constructor (Dictionary<String> attributes); // shorthand
293 constructor (); // shorthand
294 constructor attribute String tagName; // O(1) // "error"
295 constructor attribute Boolean shadow; // O(1) // false
296 }
297
298
299
300 // MODULES
301
302 callback InternalElementConstructor void (Module module);
303 dictionary ElementRegistration {
304 String tagName;
305 Boolean shadow = false;
306 InternalElementConstructor? constructor = null;
307 }
308
309 interface ElementConstructor {
310 constructor (Dictionary<String> attributes, ChildArguments... nodes); // O(M +N), M = number of attributes, N = number of nodes plus all their descendants
311 constructor (ChildArguments... nodes); // shorthand
312 constructor (Dictionary<String> attributes); // shorthand
313 constructor (); // shorthand
314
315 constructor attribute String tagName;
316 constructor attribute Boolean shadow;
317 }
318
319 abstract class AbstractModule : EventTarget {
320 readonly attribute Document document; // O(1) // the Documentof the module o r application
321 Promise<any> import(String url); // O(Yikes) // returns the module's exports
322 private Array<Module> getImports(); O(N) // returns the Module objects of al l the imported modules
323
324 readonly attribute String url;
325
326 ElementConstructor registerElement(ElementRegistration options); // O(1)
327 // if you call registerElement() with an object that was created by
328 // registerElement(), it just returns the object after registering it,
329 // rather than creating a new constructor
330 // otherwise, it proceeds as follows:
331 // 1. let constructor be the constructor passed in, if any
332 // 2. let prototype be the constructor's prototype; if there is no
333 // constructor, let prototype be Element
334 // 3. create a new Function that:
335 // 1. throws if not called as a constructor
336 // 2. creates an actual Element object
337 // 3. initialises the shadow tree if shadow on the options is true
338 // 4. calls constructor, if it's not null, with the module as the argum ent
339 // 4. let that new Function's prototype be the aforementioned prototype
340 // 5. let that new Function have tagName and shadow properties set to
341 // the values passed in on options
342 // 6. register the new element
343
344 readonly attribute ScriptElement? currentScript; // O(1) // returns the <scr ipt> element currently being executed if any, and if it's in this module; else n ull
345 }
346
347 class Module : AbstractModule {
348 constructor (Application application, Document document, String url); // O(1 )
349 readonly attribute Application application; // O(1)
350
351 attribute any exports; // O(1) // defaults to {}
352 }
353
354 class Application : AbstractModule {
355 constructor (Document document, String url); // O(1)
356 attribute String title; // O(1)
357 }
358
359 // see script.md for a description of the global object, though note that
360 // the sky core module doesn't use it or affect it in any way.
361
362 }
363 ```
364
365 TODO(ianh): event loop
366
367 TODO(ianh): define the DOM APIs listed above, including firing the
368 change callbacks
369
370 TODO(ianh): schedule microtask, schedule task, requestAnimationFrame,
371 custom element callbacks...
372
373
374
375 Appendices
376 ==========
377
378 Sky IDL
379 -------
380
381 The Sky IDL language is used to describe JS APIs found in Sky, in
382 particular, the JS APIs exposed by the four magical imports defined in
383 this document.
384
385 Sky IDL definitions are typically compiled to C++ that exposes the C++
386 implementations of the APIs to JavaScript.
387
388 Sky IDL works more or less the same as Web IDL but the syntax is a bit
389 different.
390
391 ```javascript
392 module 'sky:modulename' {
393
394 // this is a comment
395
396 typedef NewType OldType; // useful when OldType is a commonly-used union
397
398 callback CallbackName ReturnType (ArgumentType argumentName);
399
400 class ClassName {
401 // a class corresponds to a JavaScript prototype
402 // corresponds to a WebIDL 'interface'
403 }
404
405 abstract class Superclass {
406 // an abstract class can't have a non-abstract constructor
407 // an abstract class may have abstract constructors and methods
408 // an abstract class may have everything else a class can have
409
410 abstract constructor ();
411 // this indicates that non-abstract subclasses must have a constructor wit h the given arguments
412
413 abstract ReturnType methodCallback();
414 // this method does nothing, but is included to describe the interface tha t subclasses will implement
415 // a non-abstract class must have an explicit implementation of all inheri ted abstract methods
416
417 }
418
419 class Subclass : Superclass {
420 // properties
421 readonly attribute ReturnType attributeName; // getter
422 attribute ReturnType attributeName; // getter and setter
423
424 // methods and constructors
425 constructor ();
426 ReturnType method();
427 // When the platform calls this method, it always invokes the "real" metho d, even if it's been
428 // deleted from the prototypes (as if it took a reference to the method at startup, and stored
429 // state using Symbols)
430 // Calling a method with fewer arguments than defined will throw.
431 // Calling a method with more arguments ignores the extra arguments.
432 virtual ReturnType methodCallback();
433 // when the platform calls this, it actually calls it the way JS would, so author overrides do
434 // affect what gets called. Make sure if you override it that you call the superclass implementation!
435 // The default implementations of 'virtual' methods all end by calling the identically named method
436 // on the superclass, if there is such a method.
437
438 // non-abstract classes cannot have abstract constructors or methods, and in particular, must
439 // have explicit non-abstract versions of any inherited abstract constructor s or methods
440
441 // properties on the constructor
442 constructor readonly attribute ReturnType staticName;
443
444 // private APIs - see below
445 private void method();
446
447 // arguments and overloading are done as follows
448 // note that the argument names are only for documentation purposes
449 ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2);
450 // the last argument's type can have "..." appended to it to indicate a vara rgs-like situation
451 ReturnType method(ArgumentType argumentName1, ArgumentType... allSubsequentA rguments);
452 // trailing arguments can have a default value, which must be a literal of t he given type
453 ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2 = d efaultValue);
454 }
455
456 dictionary Options {
457 String foo; // if there's no default, the property must be specified or it's a TypeError
458 Integer bar = 4; // properties can have default values
459 }
460
461 // the module can have properties and methods also
462 attribute String Foo;
463 void method();
464
465 interface InterfaceName {
466 // describes a template of a prototype, in the same syntax as a class
467 // not actually exposed in the runtime
468 }
469
470 }
471 ```
472
473 ### Private APIs ###
474
475 Private APIs are only accessible via Symbol objects, which are then
476 exposed on the sky:debug module's exports object as the name of the
477 member given in the IDL.
478
479 For example, consider:
480
481 ```javascript
482 class Foo {
483 private void Bar();
484 }
485 ```
486
487 In a script with a ``foo`` object of type ``Foo``, ``foo.Bar`` is
488 undefined. However, it can be obtained as follows:
489
490 ```html
491 <import src="sky:debug" as="debug"/>
492 <!-- ... import whatever defines 'foo' ... -->
493 <script>
494 foo[debug.Bar]
495 </script>
496 ```
497
498 ### Types ###
499
500 The following types are available:
501
502 * ``Integer`` - WebIDL ``long long``
503 * ``Float`` - WebIDL ``double``
504 * ``Infinity`` - singleton type with value ``Infinity``
505 * ``String`` - WebIDL ``USVString``
506 * ``Boolean`` - WebIDL ``boolean``
507 # ``Object`` - WebIDL ``object`` (``ClassName`` can be used as a literal for thi s type)
508 * ``ClassName`` - an instance of the class ClassName
509 * ``Class<ClassName>`` - a class ClassName or one of its subclasses (not an inst ance)
510 * ``DictionaryName`` - an instance of the dictionary DictionaryName
511 * ``Promise<Type>`` - WebIDL ``Promise<T>``
512 * ``Generator<Type>`` - An ECMAScript generator function that returns data of th e given type
513 * ``Array<Type>`` - WebIDL ``sequence<T>``
514 * ``Dictionary<Type>`` - unordered set of name-value String-Type pairs with no d uplicate names
515 * ``Type?`` - union of Type and the singleton type with value ``null`` (WebIDL n ullable)
516 * ``(Type1 or Type2)`` - union of Type1 and Type2 (WebIDL union)
517 * ``any`` - union of all types (WebIDL ``any``)
518
519 Methods that return nothing (undefined, in JS) use the keyword "void"
520 instead of a type.
521
522
523 TODO(ianh): Define in detail how this actually works
524
525
526 Mojom IDL
527 ---------
528
529 The Mojom IDL language is used to describe the APIs exposed over Mojo
530 pipes.
531
532 Mojom IDL definitions are typically compiled to wrappers in each
533 language, which are then used as imports.
534
535 TODO(ianh): Define in detail how this actually works
536
537
538 Notes
539 -----
540 ```javascript
541 global object = {} // with Math, RegExp, etc
542
543 magical imports:
544 the core mojo fabric JS API sky:mojo:fabric:core
545 the asyncWait/cancelWait mojo fabric JS API (interface to IPC thread) sky:moj o:fabric:ipc
546 the mojom for the shell, proxying through C++ so that the shell pipe isn't exp osed sky:mojo:shell
547 the sky API sky:core
548 the sky debug symbols for private APIs sky:debug
549 ```
550
551 TODO(ianh): determine if we want to separate the "this" from the
552 Document, especially for Modules, so that exposing a module's element
553 doesn't expose the module's exports attribute.
OLDNEW
« no previous file with comments | « sky/specs/animation.md ('k') | sky/specs/dom.md » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698