@fusion.dev/helix-core 0.0.0-dev

package/dist/controllers/popover-controller/popover-controller.js

@@ -0,0 +1,150 @@
+import { DismissController } from '../dismiss-controller/dismiss-controller.js';
+import { FloatingController } from '../floating-controller/floating-controller.js';
+/**
+ * A surface that floats against something, in the top layer, until dismissed.
+ *
+ * Three things always travel together and were written out longhand three
+ * times: the popover API, a `FloatingController` and a `DismissController`.
+ * Individually each is small, which is exactly why the copies drifted rather
+ * than being noticed. **`Select` never called `showPopover` at all**, so its
+ * list was an ordinary positioned panel and any ancestor with `overflow:
+ * hidden` clipped it, while a menu two folders away in the same position did
+ * not. That is not a difference anyone chose.
+ *
+ * **The top layer is the whole point.** A floating panel has to escape every
+ * clipping ancestor between it and the page, and `position: fixed` does not do
+ * that: it is clipped by `overflow` on any ancestor and re-anchored entirely by
+ * an ancestor carrying `transform`, `filter` or `contain`. The popover API
+ * lifts the element out of the tree's paint order for real, and it is the only
+ * thing that does.
+ *
+ * `manual` rather than `auto`, because the host owns dismissal. `auto`
+ * popovers light-dismiss themselves and close each other, which is close to
+ * what is wanted and not the same: a select that closed itself before its own
+ * change event landed, or a submenu that closed its parent, are both things the
+ * platform would do here and neither is right.
+ *
+ * **The order matters on the way up.** `showPopover` first, then position:
+ * measuring an element that is still `display: none` gives zeroes, so a surface
+ * positioned before it is shown lands at the origin and slides into place on
+ * the next frame. On the way down it is the reverse, and stopping the observer
+ * before hiding avoids a final measurement of an element on its way out.
+ *
+ * What this does not own is *when*. Opening is the host's, because a menu opens
+ * on click, a tooltip on hover and a select on either, and none of that is
+ * about surfaces.
+ */
+export class PopoverController {
+    constructor(host, options) {
+        /** Whether the surface is currently shown, so the calls can be idempotent. */
+        this.shown = false;
+        this.options = options;
+        this.floating = new FloatingController(host, {
+            anchor: options.anchor,
+            ...(options.arrow === undefined ? {} : { arrow: options.arrow }),
+            floating: options.surface,
+            ...(options.offset === undefined ? {} : { offset: options.offset }),
+            ...(options.placement === undefined ? {} : { placement: options.placement }),
+            ...(options.within === undefined ? {} : { within: options.within }),
+        });
+        this.dismisser = new DismissController(host, {
+            boundary: options.boundary ?? options.surface,
+            onDismiss: options.onDismiss,
+        });
+        host.addController(this);
+    }
+    /** Whether the surface is showing. */
+    get open() {
+        return this.shown;
+    }
+    /** Whether this one is placed by measurement, read fresh so it may change. */
+    get places() {
+        const asked = this.options.place;
+        if (asked === undefined) {
+            return true;
+        }
+        return typeof asked === 'function' ? asked() : asked;
+    }
+    /**
+     * Shows the surface, positions it, and starts listening for a way out.
+     *
+     * Safe to call when already open, so a host may call it from whatever
+     * combination of a property, an event and a command it likes without keeping
+     * track of which one got there first.
+     */
+    show() {
+        const surface = this.options.surface();
+        if (this.shown || !surface) {
+            return;
+        }
+        this.shown = true;
+        /* Feature-detected rather than assumed. The popover API is recent enough
+           that a browser without it should still get a positioned panel, which is
+           what every one of these was before the API existed: worse, because it can
+           be clipped, and not broken. */
+        if (typeof surface.showPopover === 'function') {
+            /* And said plainly where the surface is not one. `showPopover` on an
+               element with no `popover` attribute throws `NotSupportedError`, from
+               inside the promise the host called this in, so it surfaces as an
+               unhandled rejection naming a method rather than as the thing that is
+               actually wrong. Which is how `Select` looked for as long as it was
+               broken: no error at all, just a panel that could be clipped. */
+            if (!surface.hasAttribute('popover')) {
+                throw new Error('PopoverController: the surface needs a `popover` attribute to reach the top layer');
+            }
+            surface.showPopover();
+        }
+        if (this.places) {
+            this.floating.start();
+        }
+        this.dismisser.activate();
+    }
+    /** Hides the surface and stops everything watching it. */
+    hide() {
+        const surface = this.options.surface();
+        if (!this.shown) {
+            return;
+        }
+        this.shown = false;
+        this.dismisser.deactivate();
+        this.floating.stop();
+        surface?.hidePopover?.();
+    }
+    /** Whichever of the two the surface is not already doing. */
+    toggle() {
+        if (this.shown) {
+            this.hide();
+        }
+        else {
+            this.show();
+        }
+    }
+    /**
+     * Places the surface again, for an anchor that moved without the page moving.
+     *
+     * `autoUpdate` watches scrolling, resizing and layout shift, which covers
+     * everything that moves an anchor *with* its surroundings. It does not cover
+     * an absolutely positioned anchor being moved by an inline style, and that is
+     * exactly what a chart does: the mark walks from reading to reading while the
+     * page holds still, so the bubble was placed once and stayed there.
+     */
+    reposition() {
+        this.floating.update();
+    }
+    /*
+     * Forgets that it was showing, and nothing more, which is the whole job.
+     *
+     * An element removed while its popover is showing is taken out of the top
+     * layer by the platform. The two controllers watching it stop themselves:
+     * both were constructed against this same host and registered with it, so Lit
+     * calls each one's own `hostDisconnected`, and `autoUpdate` in particular
+     * releases the listeners it holds on every scrolling ancestor there.
+     *
+     * Stopping them from here as well would be the same call twice. What is left
+     * is the flag, which nothing else owns, and which has to be cleared or a host
+     * reconnected to the page believes it is still open and refuses to show.
+     */
+    hostDisconnected() {
+        this.shown = false;
+    }
+}

package/dist/controllers/source-controller/source-controller.d.ts

@@ -0,0 +1,55 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type Series } from '../../utils/read-series/read-series.js';
+/** A host that names the element it reads from. */
+export interface SourceHost extends ReactiveControllerHost, HTMLElement {
+    /**
+     * The id of the table or grid to read.
+     */
+    for: string;
+}
+/**
+ * Resolves the element a chart reads from, and follows it.
+ *
+ * **Three charts had written this out separately before it was one thing**, and
+ * the drift had already started: two of them called the lookup `#table` and one
+ * called it `#source`, for the same method with the same body. Every chart that
+ * takes a `for` wants exactly this, and wants it to behave identically, so it is
+ * a controller rather than a paragraph in each of them.
+ *
+ * A controller and not a pure function, by the test the rules set: it reacts to
+ * the host's lifecycle. It has to start watching when the host connects, stop
+ * when it leaves, and re-resolve when `for` changes.
+ *
+ * **What it refuses is as much the point as what it accepts.** A `<table>` or
+ * anything built from grid roles, including this library's own `helix-table`,
+ * whose roles live in `ElementInternals` and therefore write no attribute at
+ * all. Anything else resolves to null, so a `for` pointed at a paragraph draws
+ * nothing rather than something arbitrary.
+ *
+ * The element is watched for `childList` and `characterData` alike, because
+ * renaming a series edits a text node in place rather than replacing a cell,
+ * and nothing in a page has reason to know a chart is reading it.
+ */
+export declare class SourceController implements ReactiveController {
+    #private;
+    constructor(host: SourceHost);
+    /**
+     * The element `for` names, or null where there is nothing to name it in.
+     *
+     * Null on the server as well, since resolving an id wants a document. Every
+     * chart inherits that: the table is served whole and the drawing arrives on
+     * hydration.
+     */
+    get element(): Element | null;
+    /** The series it holds, or none. */
+    get series(): Series[];
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Points the watcher at whatever `for` names now.
+     *
+     * Called on connect and by the host when `for` changes. Safe to call when
+     * there is no `MutationObserver`, which is the server.
+     */
+    watch(): void;
+}

package/dist/controllers/source-controller/source-controller.js

@@ -0,0 +1,94 @@
+import { readSeries } from '../../utils/read-series/read-series.js';
+/**
+ * Resolves the element a chart reads from, and follows it.
+ *
+ * **Three charts had written this out separately before it was one thing**, and
+ * the drift had already started: two of them called the lookup `#table` and one
+ * called it `#source`, for the same method with the same body. Every chart that
+ * takes a `for` wants exactly this, and wants it to behave identically, so it is
+ * a controller rather than a paragraph in each of them.
+ *
+ * A controller and not a pure function, by the test the rules set: it reacts to
+ * the host's lifecycle. It has to start watching when the host connects, stop
+ * when it leaves, and re-resolve when `for` changes.
+ *
+ * **What it refuses is as much the point as what it accepts.** A `<table>` or
+ * anything built from grid roles, including this library's own `helix-table`,
+ * whose roles live in `ElementInternals` and therefore write no attribute at
+ * all. Anything else resolves to null, so a `for` pointed at a paragraph draws
+ * nothing rather than something arbitrary.
+ *
+ * The element is watched for `childList` and `characterData` alike, because
+ * renaming a series edits a text node in place rather than replacing a cell,
+ * and nothing in a page has reason to know a chart is reading it.
+ */
+export class SourceController {
+    #host;
+    #observer;
+    constructor(host) {
+        this.#host = host;
+        host.addController(this);
+    }
+    /**
+     * The element `for` names, or null where there is nothing to name it in.
+     *
+     * Null on the server as well, since resolving an id wants a document. Every
+     * chart inherits that: the table is served whole and the drawing arrives on
+     * hydration.
+     */
+    get element() {
+        const host = this.#host;
+        if (host.for === '') {
+            return null;
+        }
+        const root = host.getRootNode();
+        const found = root.getElementById?.(host.for);
+        if (!found) {
+            return null;
+        }
+        /* `tagName` rather than `instanceof HTMLTableElement`, which is not a guard
+           on the server: the constructor is not defined there, so naming it throws
+           before the comparison can answer false. It is also the check that
+           survives an element from another document. */
+        const role = found.getAttribute('role');
+        return found.tagName === 'TABLE' ||
+            role === 'table' ||
+            role === 'grid' ||
+            /^helix-(headless-)?table$/i.test(found.tagName)
+            ? found
+            : null;
+    }
+    /** The series it holds, or none. */
+    get series() {
+        const element = this.element;
+        return element ? readSeries(element) : [];
+    }
+    hostConnected() {
+        this.watch();
+    }
+    hostDisconnected() {
+        this.#observer?.disconnect();
+        this.#observer = undefined;
+    }
+    /**
+     * Points the watcher at whatever `for` names now.
+     *
+     * Called on connect and by the host when `for` changes. Safe to call when
+     * there is no `MutationObserver`, which is the server.
+     */
+    watch() {
+        this.#observer?.disconnect();
+        const element = this.element;
+        if (!element || typeof MutationObserver === 'undefined') {
+            return;
+        }
+        this.#observer ??= new MutationObserver(() => {
+            this.#host.requestUpdate();
+        });
+        this.#observer.observe(element, {
+            characterData: true,
+            childList: true,
+            subtree: true,
+        });
+    }
+}

package/dist/controllers/token-color-controller/token-color-controller.d.ts

@@ -0,0 +1,63 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** A color as the three channels in `0..1` that a shader or a canvas takes. */
+export type TokenColor = [number, number, number];
+/**
+ * Reads a design token as the sRGB triple a shader or a 2D canvas can take, and
+ * tells the host when the palette underneath it moves.
+ *
+ * **Two hops, and both are load-bearing.** A custom property's own value is the
+ * unevaluated function text, so `getComputedStyle` on a probe is the only way
+ * to see what it resolves to. And what it resolves to is not `rgb()`: the
+ * palette derives from an `oklch()` seed, and Chrome answers `lab(100 0 0)` for
+ * white. Parsing that with a regular expression for numbers reads the three
+ * channels as 100, 0 and 0, which divided by 255 is a dark red.
+ *
+ * That is not hypothetical. It shipped, and `--helix-color-foreground` arrived
+ * as a dark red that painted a warm streak down a shader for an afternoon. It
+ * survived review because a warm cast on a saturated gradient is also what a
+ * screenshot's chroma subsampling produces, so the picture agreed with the bug.
+ *
+ * The conversion is therefore the browser's own: fill a pixel and read it back.
+ * That holds for `lab()`, `oklch()`, `color-mix()` and whatever a token is
+ * written in next, which is the property worth having in a design system whose
+ * palette is derived rather than listed.
+ *
+ * **A controller and not a mixin**, by this repository's own line: it adds no
+ * property or method a consumer sets. It reacts to lifecycle, holding a probe
+ * that has to be created after the host connects and removed when it leaves,
+ * and it watches for the color mode changing so the host can repaint.
+ *
+ * **Client only, and that is the contract rather than a limitation.** There is
+ * no computed style on a server and no canvas to convert with, so `read`
+ * answers the fallback there. Every caller is drawing into a canvas, which does
+ * not exist on a server either.
+ */
+export declare class TokenColorController implements ReactiveController {
+    private readonly host;
+    private readonly onChange?;
+    /** Where a resolved color is converted, one pixel at a time. */
+    private context;
+    /** Watches the document for `data-color-mode`. */
+    private modes;
+    /** The hidden element a token is resolved against. */
+    private probe;
+    /** Watches the operating system's answer, where nothing overrides it. */
+    private scheme;
+    /**
+     * @param host The element to update when the palette changes.
+     * @param onChange Called when the mode moves, after the host has updated. A
+     *   host that paints outside Lit's cycle needs to know, because a canvas
+     *   holds its last frame and no re-render repaints it.
+     */
+    constructor(host: ReactiveControllerHost, onChange?: (() => void) | undefined);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * The token's current value, or the fallback where it cannot be resolved.
+     *
+     * @param token The custom property's name, including its leading dashes.
+     * @param fallback What to answer on a server, or where the token is unset.
+     */
+    read(token: string, fallback: TokenColor): TokenColor;
+    private readonly announce;
+}

package/dist/controllers/token-color-controller/token-color-controller.js

@@ -0,0 +1,105 @@
+/**
+ * Reads a design token as the sRGB triple a shader or a 2D canvas can take, and
+ * tells the host when the palette underneath it moves.
+ *
+ * **Two hops, and both are load-bearing.** A custom property's own value is the
+ * unevaluated function text, so `getComputedStyle` on a probe is the only way
+ * to see what it resolves to. And what it resolves to is not `rgb()`: the
+ * palette derives from an `oklch()` seed, and Chrome answers `lab(100 0 0)` for
+ * white. Parsing that with a regular expression for numbers reads the three
+ * channels as 100, 0 and 0, which divided by 255 is a dark red.
+ *
+ * That is not hypothetical. It shipped, and `--helix-color-foreground` arrived
+ * as a dark red that painted a warm streak down a shader for an afternoon. It
+ * survived review because a warm cast on a saturated gradient is also what a
+ * screenshot's chroma subsampling produces, so the picture agreed with the bug.
+ *
+ * The conversion is therefore the browser's own: fill a pixel and read it back.
+ * That holds for `lab()`, `oklch()`, `color-mix()` and whatever a token is
+ * written in next, which is the property worth having in a design system whose
+ * palette is derived rather than listed.
+ *
+ * **A controller and not a mixin**, by this repository's own line: it adds no
+ * property or method a consumer sets. It reacts to lifecycle, holding a probe
+ * that has to be created after the host connects and removed when it leaves,
+ * and it watches for the color mode changing so the host can repaint.
+ *
+ * **Client only, and that is the contract rather than a limitation.** There is
+ * no computed style on a server and no canvas to convert with, so `read`
+ * answers the fallback there. Every caller is drawing into a canvas, which does
+ * not exist on a server either.
+ */
+export class TokenColorController {
+    /**
+     * @param host The element to update when the palette changes.
+     * @param onChange Called when the mode moves, after the host has updated. A
+     *   host that paints outside Lit's cycle needs to know, because a canvas
+     *   holds its last frame and no re-render repaints it.
+     */
+    constructor(host, onChange) {
+        this.host = host;
+        this.onChange = onChange;
+        /** Where a resolved color is converted, one pixel at a time. */
+        // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read in three places below, and this rule's own automatic fix removed it, which failed `typecheck` immediately. The suppression has to sit under the doc comment rather than over it, being directional.
+        this.context = null;
+        this.announce = () => {
+            this.host.requestUpdate();
+            this.onChange?.();
+        };
+        host.addController(this);
+    }
+    hostConnected() {
+        /* Guarded on `document` rather than on `window`, which the server shim does
+           provide. There is nothing to append a probe to without one. */
+        if (typeof document === 'undefined') {
+            return;
+        }
+        this.probe = document.createElement('span');
+        this.probe.style.display = 'none';
+        document.body.appendChild(this.probe);
+        const swatch = document.createElement('canvas');
+        swatch.width = 1;
+        swatch.height = 1;
+        this.context = swatch.getContext('2d', { willReadFrequently: true });
+        /* The color mode is an attribute, and the system's answer is a media query.
+           Watching only the first leaves a reader on system light with the dark
+           palette, which is the half that is easy to miss because a developer
+           toggling the site's own control never sees it. */
+        this.modes = new MutationObserver(() => this.announce());
+        this.modes.observe(document.documentElement, {
+            attributeFilter: ['data-color-mode'],
+            attributes: true,
+        });
+        this.scheme = window.matchMedia('(prefers-color-scheme: light)');
+        this.scheme.addEventListener('change', this.announce);
+    }
+    hostDisconnected() {
+        this.modes?.disconnect();
+        this.modes = undefined;
+        this.scheme?.removeEventListener('change', this.announce);
+        this.scheme = undefined;
+        this.probe?.remove();
+        this.probe = undefined;
+        this.context = null;
+    }
+    /**
+     * The token's current value, or the fallback where it cannot be resolved.
+     *
+     * @param token The custom property's name, including its leading dashes.
+     * @param fallback What to answer on a server, or where the token is unset.
+     */
+    read(token, fallback) {
+        const { context, probe } = this;
+        if (!context || !probe) {
+            return [...fallback];
+        }
+        probe.style.color = `var(${token})`;
+        /* Reset first. An unparseable value leaves `fillStyle` where it was, which
+           would silently hand back the previous token's color. */
+        context.fillStyle = '#000000';
+        context.fillStyle = getComputedStyle(probe).color;
+        context.fillRect(0, 0, 1, 1);
+        const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
+        return [(r ?? 0) / 255, (g ?? 0) / 255, (b ?? 0) / 255];
+    }
+}

package/dist/controllers/virtualize-controller/virtualize-controller.d.ts

@@ -0,0 +1,127 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What the controller needs of a set and the box it is shown in. */
+export interface VirtualizeOptions {
+    /** The scrolling box, or null before it renders. */
+    container: () => HTMLElement | null | undefined;
+    /** How many items there are in total, shown or not. */
+    count: () => number;
+    /** How tall one item is along the scroll axis, in pixels. */
+    estimate: () => number;
+    /**
+     * Rows kept either side of what fits, so a scroll reveals something drawn
+     * rather than something blank. Four by default, which is roughly a frame of
+     * fast scrolling at a 32 pixel row.
+     */
+    overscan?: number;
+}
+/** Which slice is rendered, and how much empty space stands in for the rest. */
+export interface Window {
+    /** How much room the items before `first` would have taken, in pixels. */
+    before: number;
+    /** How much room the items after `last` would take, in pixels. */
+    after: number;
+    /** Index of the first item rendered. */
+    first: number;
+    /** Index one past the last item rendered. */
+    last: number;
+}
+/**
+ * Works out which slice of a long set is worth rendering.
+ *
+ * **A controller and not an element, which is the whole reason it is here.**
+ * Table, Listbox, Combobox and Tree each need windowing *inside* themselves,
+ * and an element would make each of them nest one in its own shadow root: a
+ * listbox whose options are inside a `<helix-virtual-list>` is a listbox whose
+ * options are no longer its children, so its own keyboard, its own selection
+ * and its own ARIA all have a stranger in the middle of them.
+ *
+ * **A windowed set still reports its true length, and each row its true
+ * position.** This is the part virtualization usually gets wrong and the reason
+ * the arithmetic lives somewhere shared. A reader on row 4,000 of 10,000 must
+ * hear "4,000 of 10,000", so `aria-setsize` is the count and `aria-posinset` is
+ * the real index, never the position within the rendered slice. The window is a
+ * rendering decision and the set is a fact, and a component that lets the first
+ * overwrite the second has told a screen reader the list is twelve long.
+ *
+ * **The spacers are what make the scrollbar honest.** Rendering twelve rows in
+ * a box that should scroll for ten thousand gives a thumb the size of the
+ * track, so the room the absent rows would have taken is left as padding before
+ * and after. A reader dragging that thumb is dragging against the real length.
+ *
+ * **What it does not do, and the reason is narrower than it first looks.** True
+ * virtualization means never creating the rows that are not on screen, and that
+ * needs the set as *data*. Two channels are shut: a consumer's items arrive as
+ * light-DOM children, which exist by the time this could decide not to create
+ * them, and an `items` property cannot survive React hydration, which skips
+ * every property it would have to apply imperatively (see `bindReactHandler`,
+ * and the note in the rules that objects and functions have that bug and are
+ * not fixed).
+ *
+ * **A third is open, and this said otherwise until 21 Aug 2026.** Data as *text*
+ * in the markup, a `<script type="application/json">` child or an attribute, is
+ * neither a property nor a node per row: React's hydration bug cannot touch text
+ * it renders as a child, a server emits it, and the node count is one. The
+ * charts already read data out of the document this way, `for="<id>"` at a real
+ * `<table>`, so the pattern is in the library rather than being invented for
+ * this.
+ *
+ * So the thing actually blocked is the *row template*. Turning an item into
+ * markup wants either a render function, which is a function property and dies
+ * on the same bug, or a `<template>` with named holes, which survives because it
+ * is markup and which no component here asks anyone to write. That is a decision
+ * about what this library is willing to look like, not a platform limit, and it
+ * is open at #71.
+ *
+ * So what this buys is the expensive half rather than all of it: the rows
+ * outside the window are not laid out and not painted, which is where the time
+ * goes in a long list, and the node count stays. That is worth having and it is
+ * not worth calling something it is not. An element that windows children it
+ * was handed is not a virtual list, whatever it is named.
+ *
+ * **One estimate, not per-row measurement.** Measuring every row to place it is
+ * how a virtual list ends up reading the layout it is trying to avoid, and it
+ * is what makes them jump: a row taller than its estimate shifts everything
+ * after it at the moment it renders. A fixed estimate is a straight line
+ * between scroll offset and index, which never disagrees with itself. Rows of
+ * genuinely different heights are a different component and a harder one.
+ */
+export declare class VirtualizeController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    private observer;
+    private watching;
+    /** Consecutive measurements that moved the window with nothing outside asking. */
+    private settling;
+    /** Whether the consumer has been told their box cannot be measured. */
+    private warned;
+    /** The host's own inputs, so a change in them is not read as a runaway. */
+    private last;
+    /** The slice to render, recomputed on scroll and on resize. */
+    window: Window;
+    constructor(host: ReactiveControllerHost, options: VirtualizeOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Attaches to the box the first time there is one to attach to. */
+    private watch;
+    private readonly handleScroll;
+    /**
+     * Reads the scroll offset and settles the window.
+     *
+     * Asks for an update only when the slice actually moved. A scroll fires many
+     * events per frame and most of them land inside the row already at the top,
+     * so requesting one per event would re-render the list for every pixel.
+     */
+    measure(): void;
+    /**
+     * Says once that the box cannot be measured, and why.
+     *
+     * A warning rather than a throw, because the list still works: it holds a
+     * window, it draws rows, and a reader can scroll. What it cannot do is choose
+     * the window well, and that is the consumer's stylesheet to fix, not
+     * something this can decide on their behalf.
+     *
+     * Once per controller, because a warning per frame is one people filter out
+     * and this one has to be believed the day it is right.
+     */
+    private report;
+}