animl-cli 0.0.0-stage → 0.1.0

package/modules/text-effects/capabilities/text-range-run/example.ani

@@ -0,0 +1,37 @@
+{
+  "anima": "0.1",
+  "name": "text-range-run",
+  "grid": 20,
+  "requires": ["text", "texteffects"],
+  "nodes": [
+    {
+      "id": "label",
+      "type": "text",
+      "styles": {
+        "s": {
+          "size": 1
+        }
+      },
+      "runs": [
+        {
+          "id": "first",
+          "text": "ab ",
+          "style": "s"
+        },
+        {
+          "id": "last",
+          "text": "cd",
+          "style": "s"
+        }
+      ],
+      "effects": [
+        {
+          "start": 1,
+          "end": 2,
+          "run": "last",
+          "opacity": 0
+        }
+      ]
+    }
+  ]
+}

package/modules/text-effects/capabilities/text-range-run/example.animl

@@ -0,0 +1,8 @@
+<anima version="0.1" name="text-range-run" grid="20" requires="text texteffects">
+  <text id="label">
+    <style id="s" size="1"/>
+    <run id="first" text="ab " style="s"/>
+    <run id="last" text="cd" style="s"/>
+    <text-effect start="1" end="2" run="last" opacity="0"/>
+  </text>
+</anima>

package/modules/text-effects/capabilities/text-range-units/example.ani

@@ -0,0 +1,37 @@
+{
+  "anima": "0.1",
+  "name": "text-range-units",
+  "grid": 20,
+  "requires": ["text", "texteffects"],
+  "nodes": [
+    {
+      "id": "label",
+      "type": "text",
+      "styles": {
+        "s": {
+          "size": 1
+        }
+      },
+      "runs": [
+        {
+          "id": "first",
+          "text": "ab ",
+          "style": "s"
+        },
+        {
+          "id": "last",
+          "text": "cd",
+          "style": "s"
+        }
+      ],
+      "effects": [
+        {
+          "start": 1,
+          "end": 2,
+          "units": "words",
+          "opacity": 0
+        }
+      ]
+    }
+  ]
+}

package/modules/text-effects/capabilities/text-range-units/example.animl

@@ -0,0 +1,8 @@
+<anima version="0.1" name="text-range-units" grid="20" requires="text texteffects">
+  <text id="label">
+    <style id="s" size="1"/>
+    <run id="first" text="ab " style="s"/>
+    <run id="last" text="cd" style="s"/>
+    <text-effect start="1" end="2" units="words" opacity="0"/>
+  </text>
+</anima>

package/modules/text-effects/capabilities/text-script-direction/example.ani

@@ -0,0 +1,30 @@
+{
+  "anima": "0.1",
+  "name": "text-script-direction",
+  "grid": 20,
+  "requires": ["text", "texteffects"],
+  "nodes": [
+    {
+      "id": "label",
+      "type": "text",
+      "direction": "rtl",
+      "styles": {
+        "s": {
+          "size": 1
+        }
+      },
+      "runs": [
+        {
+          "id": "first",
+          "text": "ab ",
+          "style": "s"
+        },
+        {
+          "id": "last",
+          "text": "cd",
+          "style": "s"
+        }
+      ]
+    }
+  ]
+}

package/modules/text-effects/capabilities/text-script-direction/example.animl

@@ -0,0 +1,7 @@
+<anima version="0.1" name="text-script-direction" grid="20" requires="text texteffects">
+  <text id="label" direction="rtl">
+    <style id="s" size="1"/>
+    <run id="first" text="ab " style="s"/>
+    <run id="last" text="cd" style="s"/>
+  </text>
+</anima>

package/modules/text-effects/examples/title-wave.ani

@@ -0,0 +1,68 @@
+{
+  "anima": "0.1",
+  "name": "title-wave",
+  "grid": 20,
+  "requires": ["text", "texteffects"],
+  "nodes": [
+    {
+      "id": "title",
+      "type": "text",
+      "x": 1,
+      "y": 4,
+      "styles": {
+        "h": {
+          "size": 2,
+          "fill": {
+            "color": "#141413"
+          }
+        }
+      },
+      "runs": [
+        {
+          "id": "heading",
+          "text": "Search card",
+          "style": "h"
+        }
+      ],
+      "effects": [
+        {
+          "end": 2,
+          "units": "words",
+          "y": 2,
+          "opacity": 0,
+          "ranges": [
+            {
+              "start": 0,
+              "units": "glyphs",
+              "falloff": 3,
+              "combine": "intersect"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "timelines": {
+    "entrance": {
+      "duration": 1.2,
+      "tracks": {
+        "title.effects.0.ranges.0.start": [
+          [0, 0],
+          [1.2, 14]
+        ]
+      }
+    }
+  },
+  "machine": {
+    "layers": {
+      "entrance": {
+        "initial": "wave",
+        "states": {
+          "wave": {
+            "play": "entrance"
+          }
+        }
+      }
+    }
+  }
+}

package/modules/text-effects/examples/title-wave.animl

@@ -0,0 +1,15 @@
+<anima version="0.1" name="title-wave" grid="20" requires="text texteffects">
+  <text id="title" x="1" y="4">
+    <style id="h" size="2" fill="#141413"/>
+    <run id="heading" text="Search card" style="h"/>
+    <text-effect end="2" units="words" y="2" opacity="0">
+      <text-range start="0" units="glyphs" falloff="3" combine="intersect"/>
+    </text-effect>
+  </text>
+  <timeline name="entrance" duration="1.2">
+    <track target="title.effects.0.ranges.0.start">0 0; 1.2 14</track>
+  </timeline>
+  <layer name="entrance" initial="wave">
+    <state name="wave" play="entrance"/>
+  </layer>
+</anima>

package/modules/text-effects/manifest.source

@@ -0,0 +1,58 @@
+export const after = ['text'];
+export default {
+  ...{
+    name: 'text-effects',
+    summary:
+      'Text effects: per-character modifiers (offset, opacity, follow path) over animated ranges.',
+    core: {
+      entry: 'core/index.ts',
+      export: 'textEffects',
+      svg: 'core/svg.ts',
+      svgExport: 'textEffectsSVG',
+    },
+    web: [
+      { name: 'text-effects', budget: 4096, over: 'text' },
+      { name: 'markup-text-effects', budget: 256, over: 'markup-text', authoring: true },
+    ],
+    adapters: {
+      'packages/core/src/modules/text-effects/index.ts': 'core/index.ts',
+      'packages/core/src/modules/text-effects/svg.ts': 'core/svg.ts',
+      'packages/markup/src/text-effects.ts': 'markup/index.ts',
+      'packages/web/src/text-effects.ts': 'web/index.ts',
+      'packages/web/src/texteffects.ts': 'web/index.ts',
+      'packages/web/src/markup-text-effects.ts': 'web/markup.ts',
+    },
+    exports: {
+      'core:./text-effects': 'packages/core/src/modules/text-effects/index.ts',
+      'markup:./text-effects': 'packages/markup/src/text-effects.ts',
+      'web:./text-effects': 'packages/web/src/text-effects.ts',
+      'web:./texteffects': 'packages/web/src/texteffects.ts',
+      'web:./markup-text-effects': 'packages/web/src/markup-text-effects.ts',
+    },
+    tests: [
+      'modules/text-effects/test/**/*.test.ts',
+      'packages/markup/test/corpus.test.ts',
+      'packages/markup/test/names.test.ts',
+      'packages/markup/test/compile.test.ts',
+      'packages/markup/test/decompile.test.ts',
+    ],
+    conformance: [
+      'text-modifier-translation',
+      'text-modifier-rotation',
+      'text-modifier-scale',
+      'text-modifier-opacity',
+      'text-modifier-origin',
+      'text-modifier-variation',
+      'text-modifier-follow-path',
+      'text-range-units',
+      'text-range-falloff',
+      'text-range-easing',
+      'text-range-combine',
+      'text-range-run',
+      'text-background',
+      'text-script-direction',
+    ],
+    docs: ['spec/SPEC.md', 'modules/text-effects/SPEC.md'],
+  },
+  after,
+};

package/modules/text-input/SPEC.md

@@ -0,0 +1,189 @@
+# DOM-backed text input (`textinput` feature, heavy `text-input` entry)
+
+Import text, focus, a11y, a11y-actions and text-input browser entries. SVG selection/caret
+drawing uses the optional text-input-svg entry; Canvas2D drawing uses text-input-canvas with
+the canvas entry. Clipboard host helpers use text-input-clipboard. All four field entries are heavy.
+Descriptor-only markup has its own markup-text-input authoring entry (with markup-text for runs/styles). A fixed-size text node with one literal run
+accepts `textInput` (AniML `<text-input/>`). Its initial run is the default value; `writeText`
+(`write-text`) optionally names a writable string input or data path. Fields infer a focus item
+and their own text-field semantics; do not add an `a11y` object. The native field owns its label.
+
+`editable` defaults true; false makes the field readonly. `multiline` selects textarea instead of
+input. `obscured` masks the drawn value and uses a password input for single-line fields.
+`placeholder` draws when empty. `placeholderColor` (`placeholder-color`) authors a separate solid
+placeholder paint: a hexadecimal colour (3/4/6/8 digits) or `currentColor`. It replaces the run's
+fill/stroke only while the value is empty. When omitted, the placeholder uses the field's normal
+ink (including gradients, strokes, colour slots and authored alpha) at 50% opacity. This opacity
+affects only glyphs; caret, selection and node opacity retain their normal values. Typing restores
+the normal paint; clearing restores the placeholder. JSON and AniML use the same renderer-neutral
+drawing data in tool SVG/outlines, browser SVG and Canvas2D. Invalid placeholder colours use the
+registry diagnostic at `/nodes/<index>/textInput/placeholderColor`.
+`maxLength` (`max-length`) counts UTF-16 code units as HTML does;
+truncation drops a trailing high surrogate. `maxLines` (`max-lines`, multiline only) counts explicit
+newline-delimited lines. CRLF/CR normalize to LF; single-line fields drop line separators.
+`selectOnFocus` (`select-on-focus`) selects the entire native value on focus. Selection offsets
+are UTF-16. `caretColor`, `selectionColor`, `selectionRadius` (`caret-color`, `selection-color`,
+`selection-radius`) style the drawing overlay; the caret is 0.06 grid units wide. See the live field behavior below for blinking.
+
+The browser handles clipboard, IME, dead keys and keyboard selection. The native text and native
+caret are transparent. Selection and caret boxes use text layout clusters, and selection is drawn
+behind text with optional rounded corners. Composition updates drawing but does not write data or
+fire listeners until compositionend. A committed change queues write-text first, then `on="text"`
+listener actions for the same field in declaration order, resolved on the next Player.step. Limits
+are enforced for edits through the field API and headless commands as well as native edits.
+As with HTML, direct model or initial-value assignment can exceed maxlength until the next edit. `textInput(id)` on the web host
+returns the native element, including standard value/selection/clipboard event APIs. Assigning its
+value requires an input event to commit. Browser clipboard permission remains the browser's policy.
+
+Headless scripts focus a field with `focus target <id>` then `type "text"`, `compose "text"` or
+`select <start> <end>`. Type replaces the current selection; compose simulates one completed IME
+transaction (no intermediate committed writes). Semantic snapshots include text-field, value,
+multiline, obscured, readonly, focused, label and transformed bounds. Obscured snapshots omit value.
+The DOM field is the accessible textbox; its drawing SVG remains hidden from assistive technology.
+
+Validation uses `text-input-config`, the precise offending JSON pointer, message and repair hint
+for missing text/focus/a11y, unsupported runs, invalid boxes, duplicate semantic ownership, a line limit
+on single-line fields, and invalid write targets. Registry validation handles types, whole limits
+and nonnegative radii through the usual diagnostics. Both JSON and AniML spellings are normative.
+
+Limits: one plain run per field; mixed-direction selection geometry needs further browser validation. The native field, not Anima, owns visual bidi navigation.
+No native Rive equivalence is claimed. See docs/research/rive-web-runtime.md (host routing and
+semantic proxies): Anima delegates editing to the DOM and does not copy that implementation.
+
+`clipboardText(id, cut=false)` returns the native selected substring, or an empty string for
+obscured fields. Cut removes the selection and commits through the same input event unless the
+field is readonly. Native copy/cut on obscured inputs is prevented without stopping propagation.
+Multiline obscured fields are rejected (`text-input-config` at `/textInput/obscured`): HTML has no
+password textarea, and exposing its raw value as an accessible multiline textbox would leak it.
+
+For substring search, see `anima docs bind`, "Filtering a list by typed text".
+The complete `modules/bind/examples/filtering-list.animl` recipe uses
+`contains(lower($label0), lower($query))` for case-insensitive matching, with an empty query
+showing all rows and a derived result count. Validate it with
+`anima validate modules/bind/examples/filtering-list.animl`; sample it with
+`anima sample modules/bind/examples/filtering-list.animl --font sans-serif=fixtures/fonts/anima-test.ttf`.
+The older `modules/text-input/examples/search-card.animl` demonstrates exact-label equality;
+use the bind recipe for substring filtering.
+Browser clipboard grants, mobile keyboard and real OS IME sessions are outside the automated proof.
+Nested/repeated native field mounting and mixed-direction selection geometry are
+not yet implemented. Those limits block full parity closure.
+
+Caret and selection colors accept hexadecimal colors (3/4/6/8 digits) or currentColor; other paints are rejected by registry validation. Font shorthand is assigned through its CSS property setter rather than interpolated into a style declaration list.
+
+### Commit scheduling (P6-9b)
+
+A native input/composition-end commit and the headless `type`/`compose` commands queue the
+source write and committed-text listeners before the next `Player.step`. That single step
+applies the source write, derives computed properties before guards, then resolves visual bindings.
+There is no additional field-specific settling step: count, visibility and guard state agree with
+the new source in the first completed step, just as for a queued host `set`. A host inspecting
+the player immediately after dispatching a DOM input event must allow that scheduled step to run;
+`icon.invalidate()` draws without consuming queued writes. `input-write-text` conformance checks
+nonempty, cleared and external writes against derived counts, opacity and a machine guard.
+
+### Native comparison disposition (P6-9b)
+
+Original-font native captures compare the independent text layer, bound field values, explicit
+multiline content and obscured content. The fixture does not contain U+2022, so the obscured
+probe deliberately compares missing-glyph outlines; it does not certify a particular dot design.
+Caret width remains Anima's 0.06 grid units (steady in headless captures). Selection uses SVG rx (or the equivalent
+canvas rounded rectangle) over logical cluster intervals; the native capture's caret coverage
+and selection rounding differ. Those drawable comparisons remain pending with no passing
+budget. P7-8 adds selected-text color and reusable style paint references; see below.
+
+IME, DOM host handles, clipboard routing and native field accessibility use the browser contract
+rather than a native window proxy. The permitted headless native command route rejects text,
+compose and clipboard delivery; its semantic JSON is not a browser DOM accessibility tree.
+Row-specific `tests/oracle/*/skip.json` files link the attempted commands and both-engine tests.
+These skips do not certify actual OS IME sessions, clipboard grants, mobile keyboards or
+screen-reader announcements. Four conformance cases project the field state used by these
+DOM APIs; their README files explicitly distinguish that projection from executing a DOM API in Node.
+
+### P7 comparison boundaries
+
+The caret deliberately remains a steady **0.06 grid units**, transformed like the text, rather
+than a capture-pixel hairline. Core drawing has no host pixel ratio or viewport, and this choice
+keeps headless, SVG and canvas geometry consistent. The native probe draws a 1-pixel caret even
+with scaleX 0.72; that difference is retained, not covered by an antialiasing tolerance.
+
+Edit limits deliberately follow HTML UTF-16 maxlength and explicit paragraph counts. Wrapped-line
+limits would change accepted input when a host resizes or a font loads; Anima does not make stored
+input validity depend on those events. The native schema uses scalar counts and displayed lines.
+The local headless route cannot deliver native text-edit transactions, so it cannot faithfully
+compare that alternative. Existing surrogate, newline, composition and direct-write regressions
+specify Anima's contract. A direct data write or initial value can exceed limits until an edit.
+
+The local native TextInput authoring surface rejects placeholder and placeholderColor (see
+`tests/oracle/text-input-placeholder/rive/verify.txt`). A static label cannot prove placeholder
+switching or independent paint. This row uses an evidenced native-observation skip plus original-
+font conformance and both-engine SVG/canvas regressions, not a substitute static-text comparison.
+
+Selection rounding is intentionally the SVG/canvas rounded rectangle of each selected line:
+use the authored radius (default zero), with the renderer's half-extent clamp. Native authored
+radii 0 and 2.4 retain identical rounding in the captured controls; Anima honors its radius rather
+than emulating that observation. This keeps line metrics, selected logical clusters and drawing
+consistent in both backends. Select-on-focus selects the full value; its native capture already
+confirms the interaction. Its remaining pixel difference shares this documented geometry choice.
+P7-8 adds separate selected paint and reusable text-style paint references, specified below.
+
+### Separate selected text paint (P7-8)
+
+`selectedTextColor` (`selected-text-color`) is an optional hexadecimal/currentColor paint for
+selected glyphs, independent of the `selectionColor` background. Omission keeps normal text ink.
+While focused with a nonempty value and selection, intersecting grapheme clusters receive the
+selected fill in shared draw data; nonselected clusters keep their original fill/stroke. The
+selected fill replaces the original stroke. Collapsing the selection, blurring, or clearing the
+value restores normal ink. The cached measured layout is not mutated. SVG and canvas consume
+the same split paint runs. Registry errors use `/nodes/N/textInput/selectedTextColor`.
+
+Paint boundaries follow grapheme clusters. As with the existing run renderer, a font's ligatures
+across different paint runs may be reshaped; no fractional-glyph painting is implied. `selectedTextStyle` (`selected-text-style`) optionally names a local or shared text style whose
+fill/stroke paints replace selected ink, including gradients and color slots. Only its paints are
+used: font, size, axes and metrics stay those of the original text. A missing style produces
+`text-input-config` with a precise field pointer and repair hint. A color, when both are supplied,
+overrides the style. Styles with no paint make selected glyphs transparent. This reuses declared
+text styles rather than a reference to a rendered scene node. Both backends consume the same
+resolved fill/stroke; no special selected-font layout is introduced.
+
+### Live field behavior (issues #31, #35)
+
+`textInput.obscured` is a bindable bool address on a text field, e.g.
+`<bind target="q.textInput.obscured" value="$secret"/>`. Its rest value is the
+authored `obscured` (default false). It switches drawn UTF-16 masking and semantic
+value redaction on the same completed step. The browser switches the existing
+input between text and password without replacing it, preserving selection offsets,
+direction and focus. Copy/cut suppression follows the resolved obscured value.
+Static `multiline=true, obscured=true` still raises `text-input-config` at
+`/nodes/N/textInput/obscured`; a true binding on a multiline field is ignored
+(the effective value remains false), because the DOM has no password textarea.
+
+`selectionTextColor` (`selection-text-color`) is the preferred spelling of the
+existing `selectedTextColor` paint; both are accepted. When both occur,
+`selectionTextColor` wins. Omission keeps the original field foreground. It
+replaces only selected cluster ink, above `selectionColor`, with the same
+hex/currentColor validation and paint precedence over `selectedTextStyle`.
+
+Import the optional heavy `@anima-format/web/text-input-extra` entry after
+`text-input` for viewport scrolling and browser caret blinking. It extends the
+existing `textinput` feature; no extra document requirement is necessary. Tooling
+includes its pure viewport projection automatically. This split keeps the base
+entry inside its unchanged byte ceiling.
+
+`caretBlink` (`caret-blink`) defaults true. In the browser extra entry, a focused
+field's collapsed caret alternates 530 ms visible / 530 ms hidden. Every edit or
+caret/selection move restarts the visible phase. Selection replaces the caret.
+Reduced motion, paused/static hosts and CLI/headless draws show a steady caret.
+Blink repainting uses a focus-scoped timer, never a Player clock or busy flag;
+blur, pause, reload and destruction cancel it. Idle/unfocused scenes settle as
+before. `Player.step` does not sample wall-clock time.
+
+Single-line fields do not wrap. The extra entry scrolls their drawn text
+horizontally just enough to expose the active selection end (or collapsed caret);
+multiline fields keep their normal wrapping and scroll vertically. The viewport
+is the fixed field box, accounting for its text origin. Glyphs, highlights and
+caret are clipped to it. Scroll is clamped after edits or box changes and is
+retained on blur. It translates a copy of measured cluster positions; it never
+changes the box, cached measurement, layout of siblings, or input value. Oversized
+line heights show the portion fitting the box. Native editing/navigation remains
+the DOM's responsibility, as in `docs/research/rive-web-runtime.md` §3; the timer
+follows that note's sleeping scheduler and reduced-motion recommendations.

package/modules/text-input/capabilities/text-input-placeholder/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "text-input-placeholder",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/text-input/capabilities/text-input-placeholder/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="text-input-placeholder" grid="20" requires="text textinput a11y focus data assets fonts">
+  <asset name="sans-serif" type="font" src="../../../../fixtures/fonts/anima-test.ttf"/>
+  <text-style id="s" font="sans-serif" size="1"/>
+  <model name="Search">
+    <string name="query" default=""/>
+  </model>
+  <instance name="main" model="Search" default="true"/>
+  <text id="q" sizing="fixed" width="10" height="4" x="2" y="3">
+    <run text="" style="s"/>
+    <text-input placeholder="Find" placeholder-color="#336699" write-text="$query" label="Search"/>
+  </text>
+  <listener on="text" target="q" emit="committed"/>
+</anima>

package/modules/text-input/capabilities/text-input-selection/example.ani

@@ -0,0 +1,66 @@
+{
+  "anima": "0.1",
+  "name": "text-input-selection",
+  "grid": 20,
+  "requires": ["text", "textinput", "a11y", "focus", "data", "assets", "fonts"],
+  "nodes": [
+    {
+      "id": "q",
+      "type": "text",
+      "x": 2,
+      "y": 3,
+      "sizing": "fixed",
+      "width": 10,
+      "height": 4,
+      "runs": [
+        {
+          "text": "",
+          "style": "s"
+        }
+      ],
+      "textInput": {
+        "writeText": "$query",
+        "label": "Search",
+        "selectedTextColor": "#ff0000"
+      }
+    }
+  ],
+  "listeners": [
+    {
+      "on": "text",
+      "target": "q",
+      "emit": "committed"
+    }
+  ],
+  "assets": {
+    "sans-serif": {
+      "type": "font",
+      "source": "../../../../fixtures/fonts/anima-test.ttf"
+    }
+  },
+  "data": {
+    "models": {
+      "Search": {
+        "properties": {
+          "query": {
+            "type": "string",
+            "default": ""
+          }
+        }
+      }
+    },
+    "instances": {
+      "main": {
+        "model": "Search",
+        "default": true,
+        "values": {}
+      }
+    }
+  },
+  "textStyles": {
+    "s": {
+      "font": "sans-serif",
+      "size": 1
+    }
+  }
+}

package/modules/text-input/capabilities/text-input-selection/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="text-input-selection" grid="20" requires="text textinput a11y focus data assets fonts">
+  <asset name="sans-serif" type="font" src="../../../../fixtures/fonts/anima-test.ttf"/>
+  <text-style id="s" font="sans-serif" size="1"/>
+  <model name="Search">
+    <string name="query" default=""/>
+  </model>
+  <instance name="main" model="Search" default="true"/>
+  <text id="q" sizing="fixed" width="10" height="4" x="2" y="3">
+    <run text="" style="s"/>
+    <text-input write-text="$query" label="Search" selected-text-color="#ff0000"/>
+  </text>
+  <listener on="text" target="q" emit="committed"/>
+</anima>