From f31e6ec087993ffbf734730d400cd1433c302c8b Mon Sep 17 00:00:00 2001 From: Hixie Date: Tue, 19 May 2015 16:39:32 -0700 Subject: [PATCH] [Specs] Remove all the obsolete specs. TBR=abarth Review URL: https://codereview.chromium.org/1142853006 --- specs/README.md | 39 +- specs/animation.md | 58 --- specs/builtins.md | 112 ----- specs/conventions.md | 6 - specs/elements.md | 288 ----------- specs/frameworks.md | 31 -- specs/markup.md | 222 --------- specs/modules.md | 148 ------ specs/parsing.md | 846 --------------------------------- specs/runloop.md | 144 ------ specs/script.md | 101 ---- specs/style.md | 1082 ------------------------------------------ specs/style2.md | 348 -------------- specs/utils.md | 22 - 14 files changed, 2 insertions(+), 3445 deletions(-) delete mode 100644 specs/animation.md delete mode 100644 specs/builtins.md delete mode 100644 specs/conventions.md delete mode 100644 specs/elements.md delete mode 100644 specs/frameworks.md delete mode 100644 specs/markup.md delete mode 100644 specs/modules.md delete mode 100644 specs/parsing.md delete mode 100644 specs/runloop.md delete mode 100644 specs/script.md delete mode 100644 specs/style.md delete mode 100644 specs/style2.md delete mode 100644 specs/utils.md diff --git a/specs/README.md b/specs/README.md index 2501e6a4eb..95bd287f2f 100644 --- a/specs/README.md +++ b/specs/README.md @@ -1,37 +1,2 @@ -The Sky Environment -=================== - -The main files loaded by the Sky environment are Sky files, though -they can refer to binary resources like images and fonts. - -Sky files ---------- - -Conventional MIME type: ``text/sky``, though this type is neither -necessary nor sufficient to indicate that a file is a Sky file; only -the signature matters for type dispatch of Sky files. - -Conventional extension: ``.sky`` - -Signatures: - -For application files, one of the following: -* ``23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 0a`` ("``#!mojo mojo:sky\n``") -* ``23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 0d`` ("``#!mojo mojo:sky\r``") -* ``23 21 6d 6f 6a 6f 20 6d 6f 6a 6f 3a 73 6b 79 20`` ("``#!mojo mojo:sky ``") - -For module files, one of the following: -* ``53 4b 59 20 4d 4f 44 55 4c 45 0a`` ("``SKY MODULE\n``") -* ``53 4b 59 20 4d 4f 44 55 4c 45 0d`` ("``SKY MODULE\r``") -* ``53 4b 59 20 4d 4f 44 55 4c 45 20`` ("``SKY MODULE ``") - - -Notes ------ - -``` -magical imports: - the mojo fabric API dart:mojo - the mojom for the shell, proxying through C++ so that the shell pipe isn't exposed dart:mojo-shell - the Sky API dart:sky -``` +This file contains documentation for what we hope Sky to support in due course. +It's mostly proposals. It's not intended to be comprehensive. diff --git a/specs/animation.md b/specs/animation.md deleted file mode 100644 index 06f72e6f80..0000000000 --- a/specs/animation.md +++ /dev/null @@ -1,58 +0,0 @@ -Animation API -============= - -```dart -typedef void TimerCallback(); - -external void _addTask({ TimerCallback callback, Duration budget, int bits, int priority, Queue queue }); -// see (runloop.md)[runloop.md] for the semantics of tasks and queues -// _addTask() does the zone magic on callback - -external final Queue get _idleQueue; -external final Queue get _paintQueue; -external final Queue get _nextPaintQueue; - -class AnimationTimer extends Timer { - factory whenIdle(TimerCallback callback, { Duration budget: 1.0 }) { - if (budget.inMilliseconds > 1.0) - budget = new Duration(milliseconds: 1.0); - _addTask(callback: callback, budget: budget, bits: IdleTask, priority: IdlePriority, queue: _idleQueue); - } - - factory beforePaint(TimerCallback callback, { int priority: 0 }) { - _addTask(callback: callback, budget: new Duration(milliseconds: 1.0), bits: PaintTask, priority: priority, queue: _paintQueue); - } - - factory nextFrame(TimerCallback callback, { int priority: 0 }) { - _addTask(callback: callback, budget: new Duration(milliseconds: 1.0), bits: PaintTask, priority: priority, queue: _nextPaintQueue); - } -} -``` - - -Easing Functions ----------------- - -```dart -// part of the framework, not dart:sky - -typedef void AnimationCallback(); - -abstract class EasingFunction { - EasingFunction({double duration: 0.0, AnimationCallback completionCallback: null }); - double getFactor(Float time); - // calls completionCallback if time >= duration - // then returns a number ostensibly in the range 0.0 to 1.0 - // (but it could in practice go outside this range, e.g. for - // animation styles that overreach then come back) -} -``` - -If you want to have two animations simultaneously, e.g. two -transforms, then you can add to the RenderNode's overrideStyles a -StyleValue that combines other StyleValues, e.g. a -"TransformStyleValueCombinerStyleValue", and then add to it the -regular animated StyleValues, e.g. multiple -"AnimatedTransformStyleValue" objects. A framework API could make -setting all that up easy, given the right underlying StyleValue -classes. diff --git a/specs/builtins.md b/specs/builtins.md deleted file mode 100644 index 90ac3dbc3f..0000000000 --- a/specs/builtins.md +++ /dev/null @@ -1,112 +0,0 @@ -Built-In Elements -================= - -```dart -SKY MODULE - - -``` diff --git a/specs/conventions.md b/specs/conventions.md deleted file mode 100644 index 25c24e277d..0000000000 --- a/specs/conventions.md +++ /dev/null @@ -1,6 +0,0 @@ -Best Practices and Conventions for Sky Frameworks -================================================= - -* elements should not expose convenience property accessors that just - reflect content attributes. - diff --git a/specs/elements.md b/specs/elements.md deleted file mode 100644 index 99bd845dd8..0000000000 --- a/specs/elements.md +++ /dev/null @@ -1,288 +0,0 @@ -Sky DOM APIs -============ - -```dart -// ELEMENT TREE API - -abstract class Node extends EventTarget { - @override - external List getEventDispatchChain(); // O(N) in number of ancestors across shadow trees - // implements EventTarget.getEventDispatchChain() - // returns the event dispatch chain (including handling shadow trees) - - external Root get owner; // O(1) - - external ParentNode get parentNode; // O(1) - Element get parentElement { - if (parentNode is Element) - return parentNode as Element; - return null; - } - - external Node get previousSibling; // O(1) - Element get previousElementSibling { - var result = previousSibling; - while (result != null && result is! Element) - result = result.previousSibling; - return result as Element; - } - - external Node get nextSibling; // O(1) - Element get nextElementSibling { - var result = nextSibling; - while (result != null && result is! Element) - result = result.nextSibling; - return result as Element; - } - - // TODO(ianh): rename insertBefore() and insertAfter() since the Web - // has an insertBefore() that means something else. What's a good - // name, though? - - external void _insertBefore(Node node); // O(N) in number of descendants - // node must be Text or Element, parentNode must be non-null - void insertBefore(List nodes) { - List.forEach((node) { - if (node is String) - node = new Text(node); - _insertBefore(node); - }); - } - - external void _insertAfter(Node node); // O(N) in number of arguments plus all their descendants - // node must be Text or Element, parentNode must be non-null - void insertAfter(List nodes) { - var lastNode = this; - List.forEach((node) { - if (node is String) - node = new Text(node); - lastNode._insertAfter(node); - lastNode = node; - }); - } - - void replaceWith(List nodes) { - if (nextSibling != null) { - var anchor = nextSibling; - remove(); // parentNode can't be null here, so this won't throw - anchor.insertBefore(nodes); - } else { - var anchor = parentNode; - remove(); // throws if parentNode is null - anchor.append(nodes); - } - } - - external void remove(); // O(N) in number of descendants - // parentNode must be non-null - - // called when parentNode changes - // this is why insertBefore(), append(), et al, are O(N) -- the whole affected subtree is walked - // mutating the element tree from within this is strongly discouraged, since it will result in the - // callbacks being invoked while the element tree is in a different state than implied by the callbacks - external void parentChangedCallback(ParentNode oldParent, ParentNode newParent); // O(N) in descendants - // default implementation calls attached/detached - void attachedCallback() { } - void detachedCallback() { } - - external List getDestinationInsertionPoints(); // O(N) in number of insertion points the node is in - // returns the elements to which this element was distributed - - external Node cloneNode({bool deep: false}); // O(1) if deep=false, O(N) in the number of descendants if deep=true - - external ElementStyleDeclarationList get style; // O(1) - // for nodes that aren't in the ApplicationRoot's composed tree, - // returns null (so in particular orphaned subtrees and nodes in - // module Roots don't have one, nor do shadow tree Roots) - // also always returns null for ContentElement elements - // -- should be (lazily) updated when the node's parent chain - // changes (same time as, e.g., the id hashtable is marked - // dirty) - - external RenderNode get renderNode; // O(1) - // this will be null until the first time it is rendered - // it becomes null again when it is taken out of the rendering (see style.md) - - Type getLayoutManager() => null; // O(1) - - void resetLayoutManager() { // O(1) - if (renderNode != null) { - renderNode._layoutManager = null; - renderNode._needsManager = true; - } - } -} - -abstract class ParentNode extends Node { - external Node get firstChild; // O(1) - Element get firstElementChild { - var result = firstChild; - while (result != null && result is! Element) - result = result.nextSibling; - return result as Element; - } - - external Node get lastChild; // O(1) - Element get lastElementChild { - var result = lastChild; - while (result != null && result is! Element) - result = result.previousSibling; - return result as Element; - } - - // Returns a new List every time. - external List getChildren(); // O(N) in number of child nodes - List getChildElements() { - // that the following works without a cast is absurd - return getChildren().where((node) => node is Element).toList(); - } - - external void _appendChild(Node node); // O(N) in number of descendants - // node must be Text or Element - void appendChild(node) { - if (node is String) - node = new Text(node); - _appendChild(node); - } - void append(List nodes) { - nodes.forEach(appendChild); - } - - external void _prependChild(Node node); // O(N) in number of descendants - // node must be Text or Element - void prependChild(node) { - if (node is String) - node = new Text(node); - _prependChild(node); - } - void prepend(List nodes) { - // note: not implemented in terms of _prependChild() - if (firstChild != null) - firstChild.insertBefore(nodes); - else - append(nodes); - } - - external void removeChildren(); // O(N) in number of descendants - void setChild(node) { - removeChildren(); - appendChild(node); - } - void setChildren(List nodes) { - removeChildren(); - append(nodes); - } -} - -class Attr { - const Attr (this.name, [this.value = '']); // O(1) - final String name; // O(1) - final String value; // O(1) -} - -// @hasShadow annotation for registering elements -class _HasShadow { - const _HasShadow(); -} -const hasShadow = const _HasShadow(); - -abstract class Element extends ParentNode { - Element({Map attributes: null, - List children: null, - Module hostModule: null}) { // O(M+N), M = number of attributes, N = number of children nodes plus all their descendants - var shadowClass = reflectClass(hasShadow.runtimeType); - var shadowAnnotations = reflect(this).type.metadata.where((mirror) => mirror.type == shadowClass); - if (shadowAnnotations.length > 2) - throw new StateError('@hasShadow specified multiple times on ' + currentMirrorSystem().getName(reflectClass(this.runtimeType).simpleName)); - bool needsShadow = shadowAnnotations.length == 1; - if (children != null) - children = children.map((node) => node is String ? new Text(node) : node).toList(); - this._initElement(attributes, children, hostModule, needsShadow); - } - external void _initElement(Map attributes, List children, Module hostModule, bool needsShadow); - // initialises the internal attributes table, which is a ordered list - // appends the given children nodes - // children must be Text or Element - // if needsShadow is true, creates a shadow tree - - external bool hasAttribute(String name); // O(N) in number of attributes - external String getAttribute(String name); // O(N) in number of attributes - external void setAttribute(String name, [String value = '']); // O(N) in number of attributes - external void removeAttribute(String name); // O(N) in number of attributes - // calling setAttribute() with a null value removes the attribute - // (calling it without a value sets it to the empty string) - - // Returns a new Array and new Attr instances every time. - external List getAttributes(); // O(N) in number of attributes - - external Root get shadowRoot; // O(1) - // returns the shadow root - - void endTagParsedCallback() { } - void attributeChangedCallback(String name, String oldValue, String newValue) { } - // name will never be null when this is called by sky - - // TODO(ianh): does a node ever need to know when it's been redistributed? - - @override - Type getLayoutManager() { // O(1) - if (renderNode) - return renderNode.getProperty(phDisplay); - return super.getLayoutManager(); - } -} - -class Text extends Node { - external Text([String value = '']); // O(1) - - external String get value; // O(1) - external void set (String value); // O(1) - - void valueChangedCallback(String oldValue, String newValue) { } - - @override - Type getLayoutManager() => TextLayoutManager; // O(1) -} - -class Fragment extends ParentNode { - Fragment({List children}); // O(N) in number of arguments plus all their descendants - // children must be String, Text, or Element -} - -class Root extends ParentNode { - Root({List children: null, this.host}) { // O(N) in number of children nodes plus all their descendants - if (children != null) - children = children.map((node) => node is String ? new Text(node) : node).toList(); - this._initRoot(children); - } - external void _initRoot(List children); - // appends the given children nodes - // children must be Text or Element - - final Element host; - - external Element findId(String id); // O(1) - // throws if id is null -} - -class ApplicationRoot extends Root { - ApplicationRoot ({List children}) : super(children: children); // O(N) in number of children nodes arguments plus all their descendants - - @override - Type getLayoutManager() => rootLayoutManager; // O(1) -} - -Type rootLayoutManager = BlockLayoutManager; // O(1) - -class SelectorQuery { - external SelectorQuery(String selector); // O(F()) where F() is the complexity of the selector - - external bool matches(Element element); // O(F()) - external Element find(Node root); // O(N*F())+O(M) where N is the number of descendants and M the average depth of the tree - external List findAll(Node root); // O(N*F())+O(N*M) where N is the number of descendants and M the average depth of the tree - // find() and findAll() throw if the root is not one of the following: - // - Element - // - Fragment - // - Root -} -``` diff --git a/specs/frameworks.md b/specs/frameworks.md deleted file mode 100644 index f7d91a517f..0000000000 --- a/specs/frameworks.md +++ /dev/null @@ -1,31 +0,0 @@ -Frameworks ----------- - -Sky is intended to support multiple frameworks. Here is one way you -could register a custom element using Dart annotations: - -```dart -// @tagname annotation for registering elements -// only useful when placed on classes that inherit from Element -class tagname extends AutomaticMetadata { - const tagname(this.name); - final String name; - void init(DeclarationMirror target, Module module, ScriptElement script) { - assert(target is ClassMirror); - if (!(target as ClassMirror).isSubclassOf(reflectClass(Element))) - throw new UnsupportedError('@tagname can only be used on descendants of Element'); - module.registerElement(name, (target as ClassMirror).reflectedType); - } -} -``` - -A framework that used the above code could use the following code to -get the tag name of an element: - -```dart -String getTagName(Element element) { // O(N) in number of annotations on the class - // throws a StateError if the class doesn't have an @tagname annotation - var tagnameClass = reflectClass(tagname); - return (reflectClass(element.runtimeType).metadata.singleWhere((mirror) => mirror.type == tagnameClass).reflectee as tagname).name; -} -``` diff --git a/specs/markup.md b/specs/markup.md deleted file mode 100644 index b35f937c6f..0000000000 --- a/specs/markup.md +++ /dev/null @@ -1,222 +0,0 @@ -Sky Markup: Syntax -================== - -A Sky file must consist of the following components: - - 1. If the file is intended to be a top-level Sky application, the - string "``#!mojo mojo:sky``" followed by a U+0020, U+000A or - U+000D character. - - If the file is intended to be a module, then the string "SKY", a - U+0020 (space) character, the string "MODULE", and a U+0020, - U+000A or U+000D character. - - These signatures make it more difficult to e.g. embed some Sky - markup into a PNG and then cause someone to import that image as a - module. - - 2. Zero or more of the following, in any order: - - comments - - text - - escapes - - elements - -Sky files must be encoded using UTF-8. - -A file that doesn't begin with the "``#!mojo mojo:sky``" signature -isn't a Sky application file. For example: - - #!mojo https://example.com/runtimes/sky.asmjs - Hello World - -...is not a Sky file, even if ``https://example.com/runtimes/sky.asmjs`` -is an implementation of the Sky runtime: it's just a file intended -specifically for that runtime. - -The ``mojo:sky`` URL represents the generic Sky runtime provided by -your Mojo runtime vendor. - - -Comments --------- - -Comments start with the sequence "````", where the start and end hyphens don't overlap. -In between these characters, any sequence of characters is allowed -except "``-->``", which terminates the comment. Comments cannot, -therefore, be nested. - - -Text ----- - -Any sequence of Unicode characters other than ``<``, ``&``, and -U+0000. - - -Escapes -------- - -There are three kinds of escapes: - -### Hex - -They begin with the sequence ``&#x`` or ``&#X``, followed by a -sequence of hex characters (lowercase or uppercase), followed by a -semicolon. The number 0 is not allowed. - -### Decimal - -They begin with the sequence ``&#`` or ``&#``, followed by a -sequence of decimal characters, followed by a semicolon. The number 0 -is not allowed. - -### Named - -They begin with the sequence ``&``, followed by any characters, -followed by a semicolon. - -The following names work: - -| Name | Character | Unicode | -| ---- | --------- | ------- | -| `lt` | `<` | U+003C LESS-THAN SIGN character | -| `gt` | `>` | U+003E GREATER-THAN SIGN character | -| `amp` | `&` | U+0026 AMPERSAND character | -| `apos` | `'` | U+0027 APOSTROPHE character | -| `quot` | `"` | U+0022 QUOTATION MARK character | - - -Elements --------- - -An element consists of the following: - -1. ``<`` -2. Tag name: A sequence of characters other than ``/``, ``>``, - U+0020, U+000A, U+000D (whitespace). -3. Zero or more of the following: - 1. One or more U+0020, U+000A, U+000D (whitespace). - 2. Attribute name: A sequence of characters other than ``/``, - ``=``, ``>``, U+0020, U+000A, U+000D (whitespace). - 3. Optionally: - 1. Zero or more U+0020, U+000A, U+000D (whitespace) characters. - 2. ``=`` - 3. Zero or more U+0020, U+000A, U+000D (whitespace) characters. - 4. Attribute value: Either: - - ``'`` followed by attribute text other than ``'`` - followed by a terminating ``'``. - - ``"`` followed by attribute text other than ``'`` - followed by a terminating ``"``. - - attribute text other than ``/``, ``>``, - U+0020, U+000A, U+000D (whitespace). - "Attribute text" is escapes or any unicode characters other - than U+0000. -4. Either: - - For a void element: - 1. ``/``, indicating an empty element. - 2. ``>`` - - For a non-void element: - 2. ``>`` - 3. The element's contents: - - If the element's tag name is ``script``, then any sequence of - characters other than U+0000, but there must not be the - substring ```` - - -Sky Markup: Elements -==================== - -The Sky language consists of very few elements, since it is expected -that everything of note would be provided by frameworks. - -The following elements are implicitly registered by default, even if -you haven't imported anything. You can get to their constructors if -you import dart:sky (basically, dart:sky is always imported by defaul; -it's the runtime library). None of these elements have shadow trees. - -```` - - Downloads and imports foo.sky in the background. - -```` - - Downloads and imports foo.sky in the background, using "foo" as its - local name (see ``