@fusion.dev/helix 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -60,6 +60,7 @@ export * from './navigation/index.js';
 export * from './notifications/index.js';
 export * from './number-input/index.js';
 export * from './option/index.js';
+export * from './orb/index.js';
 export * from './outline/index.js';
 export * from './pagination/index.js';
 export * from './pin-input/index.js';

package/dist/index.js

@@ -55,6 +55,7 @@ export * from './navigation/index.js';
 export * from './notifications/index.js';
 export * from './number-input/index.js';
 export * from './option/index.js';
+export * from './orb/index.js';
 export * from './outline/index.js';
 export * from './pagination/index.js';
 export * from './pin-input/index.js';

package/dist/orb/index.d.ts

@@ -0,0 +1,2 @@
+export * from './root/orb-root.js';
+export * from './root/orb-shapes.js';

package/dist/orb/index.js

@@ -0,0 +1,2 @@
+export * from './root/orb-root.js';
+export * from './root/orb-shapes.js';

package/dist/orb/root/orb-root.css.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

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

@@ -0,0 +1,38 @@
+import { createSheet } from '@fusion.dev/helix-core';
+export const styles = createSheet(`:host {
+
+--_orb-size: calc(var(--helix-size-loader-lg) * 1.5);
+
+--_orb-color: var(--orb-color, currentColor);
+--_orb-ground: var(--orb-ground, var(--helix-color-background));
+
+block-size: var(--orb-size, var(--_orb-size));
+
+display: inline-block;
+flex-shrink: 0;
+inline-size: var(--orb-size, var(--_orb-size));
+vertical-align: middle;
+}
+
+:host([size="sm"]) {
+--_orb-size: var(--helix-size-loader-md);
+}
+
+:host([size="lg"]) {
+--_orb-size: calc(var(--helix-size-loader-lg) * 2);
+}
+
+[part="canvas"] {
+block-size: 100%;
+
+color: var(--_orb-color);
+display: block;
+inline-size: 100%;
+text-decoration-color: var(--_orb-ground);
+}
+
+@media print {
+:host {
+display: none;
+}
+}`);

package/dist/orb/root/orb-root.d.ts

@@ -0,0 +1,142 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
+import { type OrbState } from './orb-shapes.js';
+/**
+ * @summary Says what an agent is doing, as a shape rather than a word.
+ *
+ * @description
+ * 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.
+ *
+ * @since 0.8.0
+ * @status experimental
+ * @category feedback
+ * @aliases Thinking, Activity, Agent, Status
+ * @documentation https://helix.fusion.dev/components/orb
+ *
+ * @csspart canvas - The surface the cloud is drawn into.
+ *
+ * @cssproperty --orb-color - Ink of the nearest dots. Defaults to `currentColor`.
+ * @cssproperty --orb-ground - What the far dots are mixed toward. Defaults to the page's background.
+ * @cssproperty --orb-size - Diameter. Overrides `size`.
+ */
+export declare class HelixOrb extends HelixElement {
+    static styles: CSSResultGroup;
+    /**
+     * 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: string;
+    /**
+     * 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?: 'lg' | 'sm';
+    /**
+     * 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: OrbState;
+    private canvas;
+    private context;
+    private motion;
+    private visible;
+    private sized;
+    private frame;
+    private running;
+    private onScreen;
+    /** The box the canvas was last measured at, in CSS pixels. */
+    private box;
+    /**
+     * Where the cloud is now, and where it is heading.
+     *
+     * **`from` holds numbers rather than the name of a state**, which is what
+     * makes an interruption free: changing state mid-transition snapshots the
+     * blend that is on the screen at that instant and departs from it. Holding a
+     * name forces a choice between the shape being left and the shape being
+     * approached, and either one is a jump the reader sees.
+     */
+    private from;
+    private morphAt;
+    /**
+     * The state's clock, accumulated rather than derived.
+     *
+     * **`elapsed * rate` looks equivalent and is not.** `rate` is one of the
+     * numbers a transition interpolates, and multiplying a running clock by a
+     * changing rate throws the phase forward by the elapsed time times the
+     * change. A minute in, a rate moving from 2.1 to 2.4 skips the wave thirty
+     * seconds ahead, and the orb lurches on every state change. Integrating the
+     * rate has no such term.
+     */
+    private phase;
+    private last;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+    protected firstUpdated(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private start;
+    /**
+     * Matches the drawing buffer to the box, and reports whether it changed.
+     *
+     * Capped at two device pixels: past that the dot count is unchanged and the
+     * fill cost doubles again for a mesh already drawn sub-pixel.
+     */
+    private measure;
+    /** Begins a transition from whatever is on the screen right now. */
+    private turn;
+    /** How far through a transition, `1` when there is not one. */
+    private get progress();
+    private paramsNow;
+    private play;
+    private stop;
+    private readonly tick;
+    private readonly handleVisibility;
+    private readonly handleMotion;
+    /**
+     * One frame.
+     *
+     * Painter's algorithm: every dot is sorted by depth and drawn back to front,
+     * because a near dot has to cover a far one for the cloud to read as a solid
+     * rather than as a smear.
+     */
+    private paint;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-orb': HelixOrb;
+    }
+}

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

@@ -0,0 +1,262 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { styles } from './orb-root.css.js';
+import { blendParams, evenSphere, fibonacci, meshFor, ORB_STATES, orbPoint, paramsFor, project, smoother, } from './orb-shapes.js';
+const MORPH = 700;
+const STILL_PHASE = 1.4;
+const LABELS = {
+    done: 'Done',
+    fetching: 'Fetching',
+    thinking: 'Thinking',
+    working: 'Working',
+};
+let HelixOrb = class HelixOrb extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.label = '';
+        this.state = 'thinking';
+        this.context = null;
+        this.frame = 0;
+        this.running = false;
+        this.onScreen = false;
+        this.box = 0;
+        this.from = paramsFor('thinking');
+        this.morphAt = 0;
+        this.phase = STILL_PHASE;
+        this.last = 0;
+        this.tick = () => {
+            if (!this.running) {
+                return;
+            }
+            const now = performance.now();
+            const dt = Math.min(0.05, (now - this.last) / 1000 || 0.016);
+            this.last = now;
+            this.paint(dt);
+            this.frame = requestAnimationFrame(this.tick);
+        };
+        this.handleVisibility = () => {
+            if (document.visibilityState === 'hidden') {
+                this.stop();
+            }
+            else {
+                this.play();
+            }
+        };
+        this.handleMotion = () => {
+            if (this.motion?.matches) {
+                this.stop();
+                this.phase = STILL_PHASE;
+                this.morphAt = 0;
+                this.paint(0);
+            }
+            else {
+                this.play();
+            }
+        };
+    }
+    static { this.styles = [styles]; }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        const state = ORB_STATES.includes(this.state)
+            ? this.state
+            : 'thinking';
+        hostAria(this.internals, {
+            label: this.label || LABELS[state],
+            role: state === 'done' ? 'img' : 'progressbar',
+        });
+        this.internals.ariaBusy = state === 'done' ? 'false' : 'true';
+        if (changed.has('state') && changed.get('state') !== undefined) {
+            this.turn();
+        }
+    }
+    render() {
+        return html `<canvas part="canvas" aria-hidden="true"></canvas>`;
+    }
+    firstUpdated() {
+        this.start();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.hasUpdated) {
+            this.start();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.stop();
+        this.visible?.disconnect();
+        this.visible = undefined;
+        this.sized?.disconnect();
+        this.sized = undefined;
+        this.motion?.removeEventListener('change', this.handleMotion);
+        this.motion = undefined;
+        document.removeEventListener('visibilitychange', this.handleVisibility);
+    }
+    start() {
+        const canvas = this.renderRoot.querySelector('canvas');
+        if (!canvas) {
+            return;
+        }
+        this.canvas = canvas;
+        this.context ??= canvas.getContext('2d');
+        if (!this.context) {
+            return;
+        }
+        this.motion ??= window.matchMedia('(prefers-reduced-motion: reduce)');
+        this.motion.addEventListener('change', this.handleMotion);
+        this.visible ??= new IntersectionObserver(([entry]) => {
+            this.onScreen = entry?.isIntersecting ?? false;
+            if (this.onScreen && document.visibilityState !== 'hidden') {
+                this.play();
+            }
+            else {
+                this.stop();
+            }
+        });
+        this.visible.observe(this);
+        document.addEventListener('visibilitychange', this.handleVisibility);
+        this.sized ??= new ResizeObserver(() => {
+            this.measure();
+            this.paint(0);
+        });
+        this.sized.observe(this);
+        this.measure();
+        this.paint(0);
+    }
+    measure() {
+        const canvas = this.canvas;
+        if (!canvas) {
+            return false;
+        }
+        const size = Math.round(this.getBoundingClientRect().width);
+        if (size <= 0 || size === this.box) {
+            return false;
+        }
+        this.box = size;
+        const dpr = Math.min(2, window.devicePixelRatio || 1);
+        canvas.width = Math.round(size * dpr);
+        canvas.height = Math.round(size * dpr);
+        this.context?.setTransform(dpr, 0, 0, dpr, 0, 0);
+        return true;
+    }
+    turn() {
+        this.from = this.paramsNow();
+        this.morphAt = performance.now();
+        if (!this.running) {
+            this.paint(0);
+            this.play();
+        }
+    }
+    get progress() {
+        return this.morphAt === 0 ? 1 : Math.min(1, (performance.now() - this.morphAt) / MORPH);
+    }
+    paramsNow() {
+        const to = paramsFor(this.state);
+        const k = this.progress;
+        return k >= 1 ? to : blendParams(this.from, to, smoother(k));
+    }
+    play() {
+        if (this.running || this.motion?.matches || !this.onScreen) {
+            return;
+        }
+        this.running = true;
+        this.last = performance.now();
+        this.frame = requestAnimationFrame(this.tick);
+    }
+    stop() {
+        this.running = false;
+        cancelAnimationFrame(this.frame);
+    }
+    paint(dt) {
+        const ctx = this.context;
+        const size = this.box;
+        if (!ctx || size <= 0) {
+            return;
+        }
+        const still = this.motion?.matches ?? false;
+        const params = still ? paramsFor(this.state) : this.paramsNow();
+        this.phase += dt * params.rate;
+        const painted = getComputedStyle(ctx.canvas);
+        const ink = readColor(painted.color);
+        const ground = readColor(painted.textDecorationColor);
+        const mesh = meshFor(size);
+        const even = evenSphere(mesh.lanes, mesh.segs);
+        const scan = Math.sin(this.phase * 0.85) * 0.93;
+        const shell = still ? 1 : 1 + 0.1 * Math.sin(Math.PI * this.progress);
+        const dots = [];
+        for (let i = 0; i < mesh.ghostCount; i++) {
+            const [x, y, z] = fibonacci(i, mesh.ghostCount);
+            const [px, py, pz] = project(size, x, y, z);
+            dots.push({
+                alpha: mesh.ghostAlpha + mesh.ghostAlphaSpan * ((pz + 1) / 2),
+                radius: mesh.ghostRadius * mesh.radiusScale,
+                shade: mesh.ghostShade,
+                x: px,
+                y: py,
+                z: pz,
+            });
+        }
+        let index = 0;
+        for (let band = 0; band < mesh.lanes; band++) {
+            const u = mesh.lanes < 2 ? 0.5 : band / (mesh.lanes - 1);
+            const edge = params.edge * Math.abs(u - 0.5) * 2;
+            for (let s = 0; s < mesh.segs; s++, index++) {
+                const [x, y, z] = orbPoint(u, s / mesh.segs, this.phase, params, index, even);
+                const [px, py, pz] = project(size, x * shell, y * shell, z * shell);
+                const depth = (pz + 1) / 2;
+                const boost = params.scan * Math.exp(-((y - scan) ** 2) / 0.012) +
+                    params.jitter * (0.1 + 0.1 * Math.sin(this.phase * 0.6));
+                dots.push({
+                    alpha: mesh.aMin + (1 - mesh.aMin) * depth,
+                    radius: (mesh.radiusBase + mesh.radiusDepth * depth) *
+                        (1 - 0.25 * edge) *
+                        (1 + 0.55 * boost) *
+                        mesh.radiusScale,
+                    shade: mesh.shadeFar - mesh.shadeSpan * depth + 0.18 * edge - 0.34 * boost,
+                    x: px,
+                    y: py,
+                    z: pz,
+                });
+            }
+        }
+        dots.sort((a, b) => a.z - b.z);
+        ctx.clearRect(0, 0, size, size);
+        for (const dot of dots) {
+            if (dot.alpha < 0.02) {
+                continue;
+            }
+            const t = Math.min(1, Math.max(0, dot.shade));
+            ctx.fillStyle = `rgba(${Math.round(ink[0] + (ground[0] - ink[0]) * t)},${Math.round(ink[1] + (ground[1] - ink[1]) * t)},${Math.round(ink[2] + (ground[2] - ink[2]) * t)},${dot.alpha})`;
+            ctx.beginPath();
+            ctx.arc(dot.x, dot.y, Math.max(0.3, dot.radius), 0, Math.PI * 2);
+            ctx.fill();
+        }
+    }
+};
+__decorate([
+    property()
+], HelixOrb.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixOrb.prototype, "size", void 0);
+__decorate([
+    property()
+], HelixOrb.prototype, "state", void 0);
+HelixOrb = __decorate([
+    customElement('helix-orb')
+], HelixOrb);
+export { HelixOrb };
+const readColor = (value) => {
+    const parts = value.match(/-?[\d.]+/g);
+    if (!parts || parts.length < 3) {
+        return [128, 128, 128];
+    }
+    return [Number(parts[0]) || 0, Number(parts[1]) || 0, Number(parts[2]) || 0];
+};

package/dist/orb/root/orb-shapes.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The states an orb can be in, in the order a task tends to pass through them.
+ *
+ * Exported so the component can validate an attribute against the same list the
+ * generator reads, rather than keeping a second copy that drifts.
+ */
+export declare const ORB_STATES: readonly ['thinking', 'fetching', 'working', 'done'];
+/** What the agent is doing. */
+export type OrbState = (typeof ORB_STATES)[number];
+/**
+ * The numbers one state is made of.
+ *
+ * **A state is a set of numbers rather than a function**, and that is the whole
+ * design. The first version had a generator per state and interpolated the
+ * points they produced, which is a scramble: two shapes with unrelated
+ * parameterisations hand each dot a destination chosen by its index rather than
+ * by where it is, so the middle of every transition read as a fault. Routing
+ * through a sphere hid it at the midpoint and left the quarter marks broken.
+ *
+ * With one generator and a set of numbers per state, a transition interpolates
+ * the numbers and the generator returns a whole, valid shape at every instant.
+ * There is no in-between left to get wrong.
+ */
+export interface OrbParams {
+    /** How far the bands spread from the equator, `0` a line and `1` a full sphere. */
+    belt: number;
+    /** How far the outer bands fade, which is what makes a sash read as a sash. */
+    edge: number;
+    /** How far toward an even sphere, `0` the banded grid and `1` fully relaxed. */
+    jitter: number;
+    /** How fast this state's own clock runs. */
+    rate: number;
+    /** Which way the axis leans, in radians. */
+    rot: number;
+    /** Where the sweeping highlight is, `0` absent and `1` full strength. */
+    scan: number;
+    /** How hard the bands slide past each other. */
+    shear: number;
+    /** How flattened the ball is along its axis, `1` round. */
+    squash: number;
+    /** The three-lobed ripple's amplitude. */
+    waveA: number;
+    /** The five-lobed counter-ripple's amplitude. */
+    waveB: number;
+}
+/**
+ * Each state, as numbers.
+ *
+ * They are deliberately close together. Two states that differ in every number
+ * take a long, busy route between them; these differ in the two or three that
+ * carry the meaning, so a transition reads as one thing becoming another rather
+ * than as a shuffle.
+ */
+export declare const ORB_PARAMS: Record<OrbState, OrbParams>;
+/** Halfway between two states, key by key. */
+export declare const blendParams: (a: OrbParams, b: OrbParams, k: number) => OrbParams;
+/** The state's numbers, or `thinking`'s where the name is not one we draw. */
+export declare const paramsFor: (state: string | undefined) => OrbParams;
+/** Smootherstep: zero slope and zero acceleration at both ends. */
+export declare const smoother: (t: number) => number;
+/** A point of the Fibonacci sphere, which is the evenest cheap one. */
+export declare const fibonacci: (i: number, n: number) => [number, number, number];
+/**
+ * The even sphere `done` settles into, ordered so the band grid can address it.
+ *
+ * **The azimuth is measured from the same origin and in the same direction as
+ * the generator's longitude**, and that is not a detail. With `atan2`'s own
+ * range the two orderings sit half a turn apart: every dot is handed a
+ * destination across the ball, and the blend carries the whole cloud through its
+ * own axis. It showed as a near-empty frame midway through every transition
+ * into `done`, and nowhere else, because no single state reads this ordering.
+ */
+export declare const evenSphere: (lanes: number, segs: number) => [number, number, number][];
+/**
+ * One dot, from its place in the grid and the state's numbers.
+ *
+ * `u` runs across the bands and `v` around them, both `0` to `1`, and `phase`
+ * is the state's own accumulated clock.
+ */
+export declare const orbPoint: (u: number, v: number, phase: number, p: OrbParams, index: number, even: [number, number, number][]) => [number, number, number];
+/** The mesh and ink of an orb at one size. */
+export interface OrbMesh {
+    aMin: number;
+    ghostAlpha: number;
+    ghostAlphaSpan: number;
+    ghostCount: number;
+    ghostRadius: number;
+    ghostShade: number;
+    lanes: number;
+    radiusBase: number;
+    radiusDepth: number;
+    radiusScale: number;
+    segs: number;
+    shadeFar: number;
+    shadeSpan: number;
+}
+/**
+ * The mesh for a given diameter.
+ *
+ * **The dot budget falls as `size^1.37`** and the two axes of the grid each take
+ * its square root, which is the relationship the reference libraries land on
+ * across their own three tunings. Dots are drawn sub-pixel and their radius
+ * scales as `size^0.6`; small orbs get relatively fatter dots, or the mesh
+ * disappears into the pixel grid.
+ *
+ * **The tonal range is compressed as the orb shrinks.** Depth drawn as a
+ * 0.6-wide gray ramp is legible at 64px and invisible at 20, where the far side
+ * of the sphere is three pixels across: below 64 the ramp narrows and the alpha
+ * floor lifts, trading depth for a mark that is actually on the screen.
+ */
+export declare const meshFor: (size: number) => OrbMesh;
+/** Projects a point on the unit sphere to canvas pixels, with its depth. */
+export declare const project: (size: number, x: number, y: number, z: number) => [number, number, number];