@fusion.dev/helix 0.7.2 → 0.8.0

package/dist/orb/root/orb-shapes.js

@@ -0,0 +1,150 @@
+export const ORB_STATES = ['thinking', 'fetching', 'working', 'done'];
+export const ORB_PARAMS = {
+    done: {
+        belt: 1,
+        edge: 0,
+        jitter: 1,
+        rate: 1.1,
+        rot: 0,
+        scan: 0,
+        shear: 0,
+        squash: 1,
+        waveA: 0,
+        waveB: 0,
+    },
+    fetching: {
+        belt: 1,
+        edge: 0,
+        jitter: 0,
+        rate: 2.4,
+        rot: 0,
+        scan: 1,
+        shear: 0,
+        squash: 1,
+        waveA: 0,
+        waveB: 0,
+    },
+    thinking: {
+        belt: 0.47,
+        edge: 1,
+        jitter: 0,
+        rate: 2.1,
+        rot: 1.52,
+        scan: 0,
+        shear: 0,
+        squash: 1,
+        waveA: 0.16,
+        waveB: 0.07,
+    },
+    working: {
+        belt: 1,
+        edge: 0,
+        jitter: 0,
+        rate: 2.4,
+        rot: 0.5,
+        scan: 0,
+        shear: 1.3,
+        squash: 0.72,
+        waveA: 0,
+        waveB: 0,
+    },
+};
+const KEYS = Object.keys(ORB_PARAMS.thinking);
+export const blendParams = (a, b, k) => {
+    const out = {};
+    for (const key of KEYS) {
+        out[key] = a[key] + (b[key] - a[key]) * k;
+    }
+    return out;
+};
+export const paramsFor = (state) => ORB_PARAMS[state] ?? ORB_PARAMS.thinking;
+const TAU = Math.PI * 2;
+export const smoother = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+export const fibonacci = (i, n) => {
+    const k = Math.PI * (3 - Math.sqrt(5));
+    const y = 1 - (2 * (i + 0.5)) / n;
+    const r = Math.sqrt(Math.max(0, 1 - y * y));
+    return [r * Math.cos(i * k), y, r * Math.sin(i * k)];
+};
+const evenCache = new Map();
+export const evenSphere = (lanes, segs) => {
+    const key = `${lanes}x${segs}`;
+    const hit = evenCache.get(key);
+    if (hit) {
+        return hit;
+    }
+    const total = lanes * segs;
+    const points = [];
+    for (let i = 0; i < total; i++) {
+        points.push(fibonacci(i, total));
+    }
+    points.sort((a, b) => a[1] - b[1]);
+    const azimuth = (q) => (Math.atan2(q[2], q[0]) + TAU) % TAU;
+    const out = new Array(total);
+    for (let b = 0; b < lanes; b++) {
+        const band = points.slice(b * segs, (b + 1) * segs);
+        band.sort((a, c) => azimuth(a) - azimuth(c));
+        for (let s = 0; s < segs; s++) {
+            out[b * segs + s] = band[s];
+        }
+    }
+    evenCache.set(key, out);
+    return out;
+};
+const SPAN = 1.86;
+export const orbPoint = (u, v, phase, p, index, even) => {
+    const th = v * TAU + p.shear * phase * 0.55 * (u - 0.5) * 2;
+    const wave = p.waveA * Math.sin(th * 3 - phase * 1.7 + u * 3.1) + p.waveB * Math.sin(th * 5 + phase * 1.1);
+    const y = Math.max(-0.995, Math.min(0.995, (u - 0.5) * SPAN * p.belt + wave));
+    const r = Math.sqrt(Math.max(0, 1 - y * y));
+    let point = [r * Math.cos(th), y * p.squash, r * Math.sin(th)];
+    if (p.rot) {
+        const c = Math.cos(p.rot);
+        const s = Math.sin(p.rot);
+        point = [point[0], point[1] * c - point[2] * s, point[1] * s + point[2] * c];
+    }
+    if (p.jitter > 0.001) {
+        const e = even[index];
+        point = [
+            point[0] + (e[0] - point[0]) * p.jitter,
+            point[1] + (e[1] - point[1]) * p.jitter,
+            point[2] + (e[2] - point[2]) * p.jitter,
+        ];
+        const len = Math.hypot(point[0], point[1], point[2]) || 1;
+        point = [point[0] / len, point[1] / len, point[2] / len];
+    }
+    return point;
+};
+export const meshFor = (size) => {
+    const budget = (size / 64) ** 1.366;
+    const axis = Math.sqrt(budget);
+    const small = Math.min(1, Math.max(0, (64 - size) / 44));
+    return {
+        aMin: 0.4 + 0.2 * small,
+        ghostAlpha: 0.14,
+        ghostAlphaSpan: 0.3,
+        ghostCount: Math.max(30, Math.round(80 * budget)),
+        ghostRadius: 0.8,
+        ghostShade: 0.66,
+        lanes: Math.max(4, Math.round(14 * axis)),
+        radiusBase: 0.8,
+        radiusDepth: 1.35,
+        radiusScale: (size / 300) ** 0.6 * 0.85 * (64 / size) ** 0.26,
+        segs: Math.max(10, Math.round(78 * axis)),
+        shadeFar: 0.6 - 0.16 * small,
+        shadeSpan: 0.56 - 0.14 * small,
+    };
+};
+const TILT = 0.55;
+const ROLL = 0.3;
+export const project = (size, x, y, z) => {
+    const c = size / 2;
+    const radius = (size / 2) * 0.78;
+    const st = Math.sin(TILT);
+    const ct = Math.cos(TILT);
+    const sr = Math.sin(ROLL);
+    const cr = Math.cos(ROLL);
+    const dx = x * cr + z * sr;
+    const dz = -x * sr + z * cr;
+    return [c + dx * radius, c - (y * ct - dz * st) * radius, y * st + dz * ct];
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,14 +46,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.7.2",
-    "@fusion.dev/helix-headless": "0.7.2",
-    "@fusion.dev/helix-styles": "0.7.2"
+    "@fusion.dev/helix-core": "0.8.0",
+    "@fusion.dev/helix-headless": "0.8.0",
+    "@fusion.dev/helix-styles": "0.8.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.7.2",
-    "@fusion.dev/helix-testing": "0.7.2",
+    "@fusion.dev/helix-cem": "0.8.0",
+    "@fusion.dev/helix-testing": "0.8.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^3.3.0",

package/types/jsx.d.ts

@@ -87,6 +87,7 @@ import type {
   HelixNumberInput,
   HelixOption,
   HelixOptionGroup,
+  HelixOrb,
   HelixOutline,
   HelixPagination,
   HelixPaginationSize,
@@ -10578,6 +10579,63 @@ on, which is a change of its own rather than a property being added. */
   textContent?: (string | number) | undefined;
 };
 
+export type HelixOrbProps = {
+  /** Accessible name, where the state's own word is not the right one.
+
+Empty is the state's word, which is what most callers want and none of them
+should have to write. A caller with something better to say says it here:
+the name of the tool being run, or the file being read. */
+  label?: (HelixOrb["label"]) | undefined;
+  /** Diameter relative to the surrounding text.
+
+Reflected because the stylesheet selects on it. The mesh is chosen from the
+rendered box rather than from this, so `--orb-size` and a consumer's own
+`inline-size` get the same treatment as the three named steps. */
+  size?: (HelixOrb["size"]) | undefined;
+  /** What the agent is doing.
+
+**A name we do not draw is drawn as `thinking` rather than as nothing.**
+The set of things an agent can be doing grows faster than this list, and a
+verb we have not made a shape for should cost a reader a less specific
+indicator, not an empty box where the indicator was.
+
+Not reflected: no rule selects on it, because the state is drawn rather than
+styled. A consumer writing the attribute can still select on their own
+markup. */
+  state?: (HelixOrb["state"]) | undefined;
+};
+
+export type HelixOrbSolidJsProps = {
+  /** Accessible name, where the state's own word is not the right one.
+
+Empty is the state's word, which is what most callers want and none of them
+should have to write. A caller with something better to say says it here:
+the name of the tool being run, or the file being read. */
+  "prop:label"?: (HelixOrb["label"]) | undefined;
+  /** Diameter relative to the surrounding text.
+
+Reflected because the stylesheet selects on it. The mesh is chosen from the
+rendered box rather than from this, so `--orb-size` and a consumer's own
+`inline-size` get the same treatment as the three named steps. */
+  "prop:size"?: (HelixOrb["size"]) | undefined;
+  /** What the agent is doing.
+
+**A name we do not draw is drawn as `thinking` rather than as nothing.**
+The set of things an agent can be doing grows faster than this list, and a
+verb we have not made a shape for should cost a reader a less specific
+indicator, not an empty box where the indicator was.
+
+Not reflected: no rule selects on it, because the state is drawn rather than
+styled. A consumer writing the attribute can still select on their own
+markup. */
+  "prop:state"?: (HelixOrb["state"]) | undefined;
+
+  /** Set the innerHTML of the element */
+  innerHTML?: (string) | undefined;
+  /** Set the textContent of the element */
+  textContent?: (string | number) | undefined;
+};
+
 /** `HelixOutline` component event */
 export type HelixOutlineElementEvent<E = Event> = TypedEvent<HelixOutline, E>;
 /** `helix-before-activate` event type */
@@ -26736,6 +26794,88 @@ export type CustomElements = {
     HelixOptionProps & BaseProps<HelixOption> & BaseEvents<HelixOption>
   >;
 
+  /**
+   * A cloud of dots on a sphere, drawn to a canvas, with one shape per state:
+   * `thinking` is a narrow sash with a wave running through it, `fetching` spreads
+   * into a globe with a highlight sweeping pole to pole, `working` flattens and
+   * tilts with its bands shearing past each other, and `done` settles into an even
+   * ball.
+   *
+   * **None of them is a separate drawing.** Each is the same banded sphere given
+   * different numbers, so changing state interpolates the numbers and every frame
+   * in between is a whole shape. A loader that cuts between pictures says the
+   * work restarted; one that carries a shape into the next says it moved on.
+   *
+   * **Nothing spins.** All the movement is inside the shape, which is what makes
+   * it read as thought rather than as a thing being rotated.
+   *
+   * **The palette is read from the tokens**, not given as colors: a dot's ink is
+   * mixed toward the ground by how far away it is, and both ends come from
+   * `--orb-color` and `--orb-ground`. That is what makes depth survive a theme
+   * change without the consumer restating anything.
+   *
+   * **It stops when nobody is looking**, off screen and in a background tab, and
+   * `prefers-reduced-motion` gets one still frame rather than an empty box.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `label`: Accessible name, where the state's own word is not the right one.
+   *
+   * Empty is the state's word, which is what most callers want and none of them
+   * should have to write. A caller with something better to say says it here:
+   * the name of the tool being run, or the file being read.
+   * - `size`: Diameter relative to the surrounding text.
+   *
+   * Reflected because the stylesheet selects on it. The mesh is chosen from the
+   * rendered box rather than from this, so `--orb-size` and a consumer's own
+   * `inline-size` get the same treatment as the three named steps.
+   * - `state`: What the agent is doing.
+   *
+   * **A name we do not draw is drawn as `thinking` rather than as nothing.**
+   * The set of things an agent can be doing grows faster than this list, and a
+   * verb we have not made a shape for should cost a reader a less specific
+   * indicator, not an empty box where the indicator was.
+   *
+   * Not reflected: no rule selects on it, because the state is drawn rather than
+   * styled. A consumer writing the attribute can still select on their own
+   * markup.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang race it
+   * against a timeout; `readyToMove` does exactly that. (property only) (readonly)
+   *
+   * ## CSS Custom Properties
+   *
+   * CSS variables available for styling the component.
+   *
+   * - `--orb-color`: Ink of the nearest dots. Defaults to `currentColor`. (default: `undefined`)
+   * - `--orb-ground`: What the far dots are mixed toward. Defaults to the page's background. (default: `undefined`)
+   * - `--orb-size`: Diameter. Overrides `size`. (default: `undefined`)
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `canvas`: The surface the cloud is drawn into.
+   */
+  "helix-orb": Partial<HelixOrbProps & BaseProps<HelixOrb> & BaseEvents<HelixOrb>>;
+
   /**
    * A rule down the leading edge with the current section lit along it, which is
    * the shape a table of contents has taken since printed marginalia: the line
@@ -42553,6 +42693,90 @@ export type CustomElementsSolidJs = {
       BaseEvents<HelixOption>
   >;
 
+  /**
+   * A cloud of dots on a sphere, drawn to a canvas, with one shape per state:
+   * `thinking` is a narrow sash with a wave running through it, `fetching` spreads
+   * into a globe with a highlight sweeping pole to pole, `working` flattens and
+   * tilts with its bands shearing past each other, and `done` settles into an even
+   * ball.
+   *
+   * **None of them is a separate drawing.** Each is the same banded sphere given
+   * different numbers, so changing state interpolates the numbers and every frame
+   * in between is a whole shape. A loader that cuts between pictures says the
+   * work restarted; one that carries a shape into the next says it moved on.
+   *
+   * **Nothing spins.** All the movement is inside the shape, which is what makes
+   * it read as thought rather than as a thing being rotated.
+   *
+   * **The palette is read from the tokens**, not given as colors: a dot's ink is
+   * mixed toward the ground by how far away it is, and both ends come from
+   * `--orb-color` and `--orb-ground`. That is what makes depth survive a theme
+   * change without the consumer restating anything.
+   *
+   * **It stops when nobody is looking**, off screen and in a background tab, and
+   * `prefers-reduced-motion` gets one still frame rather than an empty box.
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `label`: Accessible name, where the state's own word is not the right one.
+   *
+   * Empty is the state's word, which is what most callers want and none of them
+   * should have to write. A caller with something better to say says it here:
+   * the name of the tool being run, or the file being read.
+   * - `size`: Diameter relative to the surrounding text.
+   *
+   * Reflected because the stylesheet selects on it. The mesh is chosen from the
+   * rendered box rather than from this, so `--orb-size` and a consumer's own
+   * `inline-size` get the same treatment as the three named steps.
+   * - `state`: What the agent is doing.
+   *
+   * **A name we do not draw is drawn as `thinking` rather than as nothing.**
+   * The set of things an agent can be doing grows faster than this list, and a
+   * verb we have not made a shape for should cost a reader a less specific
+   * indicator, not an empty box where the indicator was.
+   *
+   * Not reflected: no rule selects on it, because the state is drawn rather than
+   * styled. A consumer writing the attribute can still select on their own
+   * markup.
+   * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
+   *
+   * **Named `whenSettled` because `settled` is taken four times over**, by
+   * Image, Splitter and both color controls, none of them about transitions. A
+   * base class takes the name every subclass then cannot use.
+   *
+   * **The state it reports cannot be watched, which is why this exists.** A
+   * custom state is deliberately not in the DOM, so there is no
+   * `MutationObserver` equivalent for `ElementInternals.states`. Await this
+   * instead.
+   *
+   * Separate from `updateComplete`, which resolves in the microtask checkpoint
+   * the suppression is still active in. That is the distinction `readyToMove`
+   * in `@fusion.dev/helix-testing` is written around.
+   *
+   * It never resolves where `requestAnimationFrame` never fires, which is a
+   * server, a hidden tab, and happy-dom. Callers that must not hang race it
+   * against a timeout; `readyToMove` does exactly that. (property only) (readonly)
+   *
+   * ## CSS Custom Properties
+   *
+   * CSS variables available for styling the component.
+   *
+   * - `--orb-color`: Ink of the nearest dots. Defaults to `currentColor`. (default: `undefined`)
+   * - `--orb-ground`: What the far dots are mixed toward. Defaults to the page's background. (default: `undefined`)
+   * - `--orb-size`: Diameter. Overrides `size`. (default: `undefined`)
+   *
+   * ## CSS Parts
+   *
+   * Custom selectors for styling elements within the component.
+   *
+   * - `canvas`: The surface the cloud is drawn into.
+   */
+  "helix-orb": Partial<
+    HelixOrbProps & HelixOrbSolidJsProps & BaseProps<HelixOrb> & BaseEvents<HelixOrb>
+  >;
+
   /**
    * A rule down the leading edge with the current section lit along it, which is
    * the shape a table of contents has taken since printed marginalia: the line
@@ -50169,6 +50393,12 @@ export type CustomCssProperties = {
   "--option-padding"?: (string) | undefined;
   /** Corner radius of the row. A listbox and a select flatten it. */
   "--option-radius"?: (string) | undefined;
+  /** Ink of the nearest dots. Defaults to `currentColor`. */
+  "--orb-color"?: (string) | undefined;
+  /** What the far dots are mixed toward. Defaults to the page's background. */
+  "--orb-ground"?: (string) | undefined;
+  /** Diameter. Overrides `size`. */
+  "--orb-size"?: (string) | undefined;
   /** How far each level is inset from the one above. */
   "--outline-indent"?: (string) | undefined;
   /** Width of the gutter the rule and the traveling mark share. */

package/types/svelte.d.ts

@@ -72,6 +72,7 @@ declare module 'svelte/elements' {
     'helix-number-input': CustomElements['helix-number-input']
     'helix-option-group': CustomElements['helix-option-group']
     'helix-option': CustomElements['helix-option']
+    'helix-orb': CustomElements['helix-orb']
     'helix-outline': CustomElements['helix-outline']
     'helix-pagination': CustomElements['helix-pagination']
     'helix-pagination-size': CustomElements['helix-pagination-size']

package/types/vue.d.ts

@@ -64,6 +64,7 @@ import type {
   HelixNumberInput,
   HelixOptionGroup,
   HelixOption,
+  HelixOrb,
   HelixOutline,
   HelixPagination,
   HelixPaginationSize,
@@ -5403,6 +5404,34 @@ export type HelixOptionVueEvents = {
   "helix-select": HelixOptionHelixSelectElementEvent;
 };
 
+export type HelixOrbVueProps = {
+  /** Accessible name, where the state's own word is not the right one.
+
+Empty is the state's word, which is what most callers want and none of them
+should have to write. A caller with something better to say says it here:
+the name of the tool being run, or the file being read. */
+  label?: (HelixOrb["label"]) | undefined;
+  /** Diameter relative to the surrounding text.
+
+Reflected because the stylesheet selects on it. The mesh is chosen from the
+rendered box rather than from this, so `--orb-size` and a consumer's own
+`inline-size` get the same treatment as the three named steps. */
+  size?: (HelixOrb["size"]) | undefined;
+  /** What the agent is doing.
+
+**A name we do not draw is drawn as `thinking` rather than as nothing.**
+The set of things an agent can be doing grows faster than this list, and a
+verb we have not made a shape for should cost a reader a less specific
+indicator, not an empty box where the indicator was.
+
+Not reflected: no rule selects on it, because the state is drawn rather than
+styled. A consumer writing the attribute can still select on their own
+markup. */
+  state?: (HelixOrb["state"]) | undefined;
+};
+
+export type HelixOrbVueEvents = {};
+
 /** `HelixOutline` component event */
 export type HelixOutlineElementEvent<E = Event> = TypedEvent<HelixOutline, E>;
 /** `helix-before-activate` event type */
@@ -9755,6 +9784,12 @@ export type CustomCssProperties = {
   "--option-padding"?: (string) | undefined;
   /** Corner radius of the row. A listbox and a select flatten it. */
   "--option-radius"?: (string) | undefined;
+  /** Ink of the nearest dots. Defaults to `currentColor`. */
+  "--orb-color"?: (string) | undefined;
+  /** What the far dots are mixed toward. Defaults to the page's background. */
+  "--orb-ground"?: (string) | undefined;
+  /** Diameter. Overrides `size`. */
+  "--orb-size"?: (string) | undefined;
   /** How far each level is inset from the one above. */
   "--outline-indent"?: (string) | undefined;
   /** Width of the gutter the rule and the traveling mark share. */
@@ -10517,6 +10552,12 @@ export interface WcToolkitVueGlobalComponents {
     HelixOptionVueProps,
     HelixOptionVueEvents
   >;
+  /** A cloud of dots on a sphere, drawn to a canvas, with one shape per state: 'thinking' is a narrow sash with a wave running through it, 'fetching' spreads into a globe with a highlight sweeping pole to pole, 'working' flattens and tilts with its bands shearing past each other, and 'done' settles into an even ball.  **None of them is a separate drawing.** Each is the same banded sphere given different numbers, so changing state interpolates the numbers and every frame in between is a whole shape. A loader that cuts between pictures says the work restarted; one that carries a shape into the next says it moved on.  **Nothing spins.** All the movement is inside the shape, which is what makes it read as thought rather than as a thing being rotated.  **The palette is read from the tokens**, not given as colors: a dot's ink is mixed toward the ground by how far away it is, and both ends come from '--orb-color' and '--orb-ground'. That is what makes depth survive a theme change without the consumer restating anything.  **It stops when nobody is looking**, off screen and in a background tab, and 'prefers-reduced-motion' gets one still frame rather than an empty box. */
+  "helix-orb": DefineCustomElement<
+    HelixOrb,
+    HelixOrbVueProps,
+    HelixOrbVueEvents
+  >;
   /** A rule down the leading edge with the current section lit along it, which is the shape a table of contents has taken since printed marginalia: the line says the list is one thing, and the lit segment says where in it you are.  Nesting is the consumer's, expressed as 'data-level' on a link. An outline that read heading levels itself would have to look at the document, and the document is not always where the headings are. */
   "helix-outline": DefineCustomElement<
     HelixOutline,