@fusion.dev/helix-core 0.58.1 → 0.59.0

package/dist/controllers/aria-forward-controller/aria-forward-controller.js

@@ -1,3 +1,4 @@
+import { elementById } from '../../utils/element-by-id/element-by-id.js';
 const RELATIONSHIPS = [
     ['aria-describedby', 'ariaDescribedByElements'],
     ['aria-labelledby', 'ariaLabelledByElements'],
@@ -19,14 +20,13 @@ export class AriaForwardController {
             this.forwarded.clear();
             this.recorded = target;
         }
-        const root = this.host.getRootNode();
         for (const [attribute, property] of RELATIONSHIPS) {
             if (!(property in target)) {
                 continue;
             }
             const ids = (this.host.getAttribute(attribute) ?? '').split(/\s+/).filter(Boolean);
             const elements = ids
-                .map((id) => root.getElementById?.(id) ?? null)
+                .map((id) => elementById(this.host, id))
                 .filter((element) => element !== null);
             const reflect = target;
             if (elements.length > 0) {

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.d.ts

@@ -101,8 +101,8 @@ export declare class ChartPointerController implements ReactiveController {
      * drawn at 10% of the plot's width stands 10% in from its right edge. What is
      * read against the drawing has to be read the same way: the pointer from the
      * plot's right, and a bubble beside a bar's far end on its left. Asked of the
-     * host's computed `direction`, which is what the table and the splitter read
-     * for their own arrow keys.
+     * host through `isRtl`, which is the one question the table and the splitter
+     * ask for their own arrow keys.
      *
      * On the controller because it is what reads the pointer against the drawing,
      * and a chart deciding which side a bubble goes asks here rather than

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.js

@@ -1,3 +1,4 @@
+import { isRtl } from '../../utils/is-rtl/is-rtl.js';
 export class ChartPointerController {
     constructor(host) {
         this.moved = false;
@@ -60,7 +61,7 @@ export class ChartPointerController {
         return this.plot?.getBoundingClientRect();
     }
     get mirrored() {
-        return typeof getComputedStyle === 'function' && getComputedStyle(this.host).direction === 'rtl';
+        return isRtl(this.host);
     }
     set(at) {
         if (at !== this.at) {

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

@@ -1,3 +1,4 @@
+import { isRtl } from '../../utils/is-rtl/is-rtl.js';
 export class IndicatorController {
     constructor(host, options) {
         this.host = host;
@@ -39,7 +40,7 @@ export class IndicatorController {
         if (box.width === 0 && box.height === 0) {
             return;
         }
-        const rtl = getComputedStyle(surface).direction === 'rtl';
+        const rtl = isRtl(surface);
         const inline = rtl
             ? own.right - box.right - surface.clientLeft
             : box.left - own.left - surface.clientLeft;

package/dist/controllers/paint-gate-controller/paint-gate-controller.d.ts

@@ -0,0 +1,135 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * The longest step one frame is given, in seconds.
+ *
+ * A tab that was throttled and comes back hands the first frame a delta of
+ * several seconds. Integrated whole, an animated canvas teleports: the aura's
+ * field lands wherever the pointer went while nobody was watching, and the
+ * orb's wave jumps a shape. The ceiling is 20 frames a second of simulated
+ * time, so a genuinely slow frame still advances and a resumed one does not
+ * skip ahead.
+ *
+ * Exported because a host that collects several frames into one owes the same
+ * ceiling on what it spends. `Aura` caps its own frame rate and would otherwise
+ * hand its shader exactly the step this number refuses.
+ */
+export declare const MAX_FRAME_STEP = 0.05;
+/** What a painter hands the gate, and what the gate hands back. */
+export interface PaintGateOptions {
+    /**
+     * Whether the host has anything to draw with, asked before every frame.
+     *
+     * The gate knows who is looking and nothing about what the host paints with:
+     * a canvas context, a linked program, a drawing buffer that has been
+     * measured, a context the browser has taken. Each of those is a reason to
+     * refuse a frame that no shared `running` can know, so a host with one says
+     * so here rather than losing a guard.
+     */
+    canRun?: () => boolean;
+    /** One frame, with the step in seconds already clamped. */
+    onFrame: (delta: number) => void;
+    /**
+     * The reader's motion preference, on every change of it.
+     *
+     * The loop is already stopped when `reduced` is true and already asked to
+     * play when it is false. What is left is the still frame, and that is the
+     * host's: a canvas holds whatever was on it when the loop stopped, and
+     * mid-drift is not the resting shape.
+     */
+    onMotion?: (reduced: boolean) => void;
+    /** The host's box changed, which is when a drawing buffer is re-measured. */
+    onResize?: () => void;
+}
+/**
+ * Runs a canvas painter's frame loop, and stops it whenever nobody is looking.
+ *
+ * It holds the five pieces every animated canvas needs and none of which is
+ * about what is drawn: an `IntersectionObserver` for whether the host is on
+ * screen, `visibilitychange` for whether the tab is in front,
+ * `prefers-reduced-motion` and its `change` listener for whether the reader
+ * asked for less, a `ResizeObserver` for the box, and the
+ * `requestAnimationFrame` loop that reports a clamped step. It says whether it
+ * is running, whether the reader asked for less motion, and whether the host is
+ * on screen.
+ *
+ * **Separable because none of it reads a pixel.** `Aura` and `Orb` are the
+ * library's two canvas painters and are otherwise nothing alike, one a WebGL
+ * shader over a full-screen triangle and the other a depth-sorted cloud of 2D
+ * dots. Everything above is the same question in both, which is when a frame is
+ * worth drawing, and the answer never mentions the drawing.
+ *
+ * **Every path to a frame is gated, not only the observer's.** The tab's own
+ * state is asked in `play` rather than in the intersection callback, because a
+ * restored context, a resize, a state change and a preference all play too, and
+ * a check that lives in the observer covers exactly one of them.
+ *
+ * **The next frame is asked for rather than booked blind.** A loop that books
+ * its own next frame unconditionally ends only where something calls `stop`,
+ * which is how a detached element and a host whose context was taken both went
+ * on drawing into nothing.
+ *
+ * **The device-pixel cap is not here.** The aura scales by
+ * `Math.min(devicePixelRatio || 1, 2) * 0.85` and the orb by
+ * `Math.min(2, devicePixelRatio || 1)`, and the difference between them is a
+ * measured fill cost, five octaves of noise per pixel against a disc fill.
+ * Those are decisions about a drawing, not the mechanism around it.
+ *
+ * **Nor is context loss.** The event names differ by context type,
+ * `webglcontextlost` against `contextlost`, and so does the contract: a 2D
+ * context comes back unless the loss is canceled and a WebGL one comes back
+ * only if it is. The aura's deferred release is an argument about a browser's
+ * budget of about sixteen live WebGL contexts, which is nothing a 2D canvas
+ * has.
+ *
+ * Client only, and by contract rather than by a guard: every caller holds a
+ * drawing context before it calls `watch`, and there is no context on a server
+ * or on a machine that refuses one.
+ */
+export declare class PaintGateController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** The booked frame, or `0`, which is also the whole of whether it runs. */
+    private frame;
+    /** When the last reported frame was, so the next one carries the gap. */
+    private last;
+    /**
+     * What the intersection observer last said, kept because it says so only on
+     * a change: every other path to `play` has to ask it.
+     */
+    private intersecting;
+    private motion;
+    private sized;
+    private visible;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: PaintGateOptions);
+    /** Whether the host is on screen, as the intersection observer last said. */
+    get onScreen(): boolean;
+    /** Whether the reader asked for less motion. */
+    get reduced(): boolean;
+    /** Whether a frame is booked. */
+    get running(): boolean;
+    /**
+     * Installs everything that decides whether a frame is wanted.
+     *
+     * Called from the host's own setup rather than from `hostConnected`, because
+     * a host with nothing to draw with has nothing to gate: both painters ask for
+     * a context first and return where there is none, which is a server, a
+     * machine that refuses one, and a renderer the aura declines. Idempotent, so
+     * a host whose setup runs on every connection calls it every time.
+     */
+    watch(): void;
+    hostDisconnected(): void;
+    /** Starts the loop, where it is wanted and can be ended. */
+    play(): void;
+    /**
+     * Ends the loop.
+     *
+     * `last` goes with it, so a loop starting again measures no step against a
+     * stale stamp. What the host accumulated is the host's and is left alone.
+     */
+    stop(): void;
+    /** Whether anybody is looking, and whether the host can draw for them. */
+    private wanted;
+    private readonly tick;
+    private readonly handleMotion;
+    private readonly handleVisibility;
+}

package/dist/controllers/paint-gate-controller/paint-gate-controller.js

@@ -0,0 +1,97 @@
+export const MAX_FRAME_STEP = 0.05;
+const STILL_CLOCK = 0.016;
+export class PaintGateController {
+    constructor(host, options) {
+        this.frame = 0;
+        this.last = 0;
+        this.intersecting = false;
+        this.tick = () => {
+            const now = performance.now();
+            const delta = Math.min(MAX_FRAME_STEP, (now - this.last) / 1000 || STILL_CLOCK);
+            this.last = now;
+            this.frame = 0;
+            this.options.onFrame(delta);
+            if (this.wanted()) {
+                this.frame = requestAnimationFrame(this.tick);
+            }
+        };
+        this.handleMotion = () => {
+            if (this.reduced) {
+                this.stop();
+            }
+            this.options.onMotion?.(this.reduced);
+            this.play();
+        };
+        this.handleVisibility = () => {
+            if (document.hidden) {
+                this.stop();
+            }
+            else {
+                this.play();
+            }
+        };
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    get onScreen() {
+        return this.intersecting;
+    }
+    get reduced() {
+        return this.motion?.matches ?? false;
+    }
+    get running() {
+        return this.frame !== 0;
+    }
+    watch() {
+        this.motion ??= window.matchMedia('(prefers-reduced-motion: reduce)');
+        this.motion.addEventListener('change', this.handleMotion);
+        this.visible ??= new IntersectionObserver(([entry]) => {
+            this.intersecting = entry?.isIntersecting ?? false;
+            if (this.intersecting) {
+                this.play();
+            }
+            else {
+                this.stop();
+            }
+        });
+        this.visible.observe(this.host);
+        document.addEventListener('visibilitychange', this.handleVisibility);
+        this.sized ??= new ResizeObserver(() => {
+            this.options.onResize?.();
+        });
+        this.sized.observe(this.host);
+    }
+    hostDisconnected() {
+        this.stop();
+        this.intersecting = false;
+        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);
+    }
+    play() {
+        if (this.frame || !this.wanted()) {
+            return;
+        }
+        this.last = performance.now();
+        this.frame = requestAnimationFrame(this.tick);
+    }
+    stop() {
+        if (this.frame) {
+            cancelAnimationFrame(this.frame);
+            this.frame = 0;
+        }
+        this.last = 0;
+    }
+    wanted() {
+        return (this.host.isConnected &&
+            this.intersecting &&
+            !this.reduced &&
+            !document.hidden &&
+            (this.options.canRun?.() ?? true));
+    }
+}

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

@@ -1,3 +1,4 @@
+import { elementById } from '../../utils/element-by-id/element-by-id.js';
 import { readRows, readSeries } from '../../utils/read-series/read-series.js';
 export class SourceController {
     constructor(host) {
@@ -18,8 +19,7 @@ export class SourceController {
         if (host.for === '') {
             return null;
         }
-        const root = host.getRootNode();
-        const found = root.getElementById?.(host.for);
+        const found = elementById(host, host.for);
         if (!found) {
             return null;
         }

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { IdleController } from './controllers/idle-controller/idle-controller.js
 export { IndicatorController, type IndicatorOptions, } from './controllers/indicator-controller/indicator-controller.js';
 export { KeyboardNavigationController, type KeyboardNavigationOptions, type NavigableItem, } from './controllers/keyboard-navigation-controller/keyboard-navigation-controller.js';
 export { MediaSessionController, type SessionHandlers, SKIP_SECONDS, } from './controllers/media-session-controller/media-session-controller.js';
+export { MAX_FRAME_STEP, PaintGateController, type PaintGateOptions, } from './controllers/paint-gate-controller/paint-gate-controller.js';
 export { PopoverController, type PopoverOptions, } from './controllers/popover-controller/popover-controller.js';
 export { RemotePlaybackController, type RemoteReport, } from './controllers/remote-playback-controller/remote-playback-controller.js';
 export { SourceController, type SourceHost, } from './controllers/source-controller/source-controller.js';
@@ -37,16 +38,18 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
-export { type Color, type ColorFormat, formatColor, parseColor, splitColors, toCss, } from './utils/css-color/css-color.js';
+export { type Color, type ColorFormat, formatColor, parseColor, toCss, } from './utils/css-color/css-color.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
 export { type DrawIconOptions, drawIcon } from './utils/draw-icon/draw-icon.js';
 export { CHART_PLOT, drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
 export { elapsedTime } from './utils/elapsed-time/elapsed-time.js';
+export { type ElementByIdOptions, elementById, searchableById, } from './utils/element-by-id/element-by-id.js';
 export { deepActiveElement, deepContains, focusableElements, } from './utils/focusable-elements/focusable-elements.js';
 export { formatNumbers } from './utils/format-numbers/format-numbers.js';
 export { type HostAria, hostAria } from './utils/host-aria/host-aria.js';
 export { type DisableableItem, forgetDisabled, inheritDisabled, } from './utils/inherit-disabled/inherit-disabled.js';
 export { inlineStep } from './utils/inline-step/inline-step.js';
+export { isRtl } from './utils/is-rtl/is-rtl.js';
 export { type Curve, linePath, type Point } from './utils/line-path/line-path.js';
 export { markRegion, type RegionOptions } from './utils/mark-region/mark-region.js';
 export { copiesOf, type MediaCopy, sameCopies, } from './utils/media-copy/media-copy.js';
@@ -61,8 +64,10 @@ export { extent, linear, type Scale } from './utils/scale/scale.js';
 export { ticks } from './utils/scale/ticks.js';
 export { type ScrollItemOptions, scrollItemIntoView, } from './utils/scroll-item-into-view/scroll-item-into-view.js';
 export { slotFilled } from './utils/slot-filled/slot-filled.js';
+export { splitValues } from './utils/split-values/split-values.js';
 export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
 export { subscribe } from './utils/ticker/ticker.js';
 export { type HelixStatusTone, TONE_MARKS, type ToneMark, toneMark, } from './utils/tone-marks/tone-marks.js';
-export { dateAsValue, isDateValue, numberAsValue, timeAsValue, valueAsDate, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
-export { writtenList } from './utils/written-list/written-list.js';
+export { dateAsValue, isDateValue, isTimeValue, minutesAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsMinutes, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
+export { writeTime } from './utils/write-time/write-time.js';
+export { writtenList, writtenNumbers } from './utils/written-list/written-list.js';

package/dist/index.js

@@ -12,6 +12,7 @@ export { IdleController } from './controllers/idle-controller/idle-controller.js
 export { IndicatorController, } from './controllers/indicator-controller/indicator-controller.js';
 export { KeyboardNavigationController, } from './controllers/keyboard-navigation-controller/keyboard-navigation-controller.js';
 export { MediaSessionController, SKIP_SECONDS, } from './controllers/media-session-controller/media-session-controller.js';
+export { MAX_FRAME_STEP, PaintGateController, } from './controllers/paint-gate-controller/paint-gate-controller.js';
 export { PopoverController, } from './controllers/popover-controller/popover-controller.js';
 export { RemotePlaybackController, } from './controllers/remote-playback-controller/remote-playback-controller.js';
 export { SourceController, } from './controllers/source-controller/source-controller.js';
@@ -37,16 +38,18 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
-export { formatColor, parseColor, splitColors, toCss, } from './utils/css-color/css-color.js';
+export { formatColor, parseColor, toCss, } from './utils/css-color/css-color.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
 export { drawIcon } from './utils/draw-icon/draw-icon.js';
 export { CHART_PLOT, drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
 export { elapsedTime } from './utils/elapsed-time/elapsed-time.js';
+export { elementById, searchableById, } from './utils/element-by-id/element-by-id.js';
 export { deepActiveElement, deepContains, focusableElements, } from './utils/focusable-elements/focusable-elements.js';
 export { formatNumbers } from './utils/format-numbers/format-numbers.js';
 export { hostAria } from './utils/host-aria/host-aria.js';
 export { forgetDisabled, inheritDisabled, } from './utils/inherit-disabled/inherit-disabled.js';
 export { inlineStep } from './utils/inline-step/inline-step.js';
+export { isRtl } from './utils/is-rtl/is-rtl.js';
 export { linePath } from './utils/line-path/line-path.js';
 export { markRegion } from './utils/mark-region/mark-region.js';
 export { copiesOf, sameCopies, } from './utils/media-copy/media-copy.js';
@@ -61,8 +64,10 @@ export { extent, linear } from './utils/scale/scale.js';
 export { ticks } from './utils/scale/ticks.js';
 export { scrollItemIntoView, } from './utils/scroll-item-into-view/scroll-item-into-view.js';
 export { slotFilled } from './utils/slot-filled/slot-filled.js';
+export { splitValues } from './utils/split-values/split-values.js';
 export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
 export { subscribe } from './utils/ticker/ticker.js';
 export { TONE_MARKS, toneMark, } from './utils/tone-marks/tone-marks.js';
-export { dateAsValue, isDateValue, numberAsValue, timeAsValue, valueAsDate, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
-export { writtenList } from './utils/written-list/written-list.js';
+export { dateAsValue, isDateValue, isTimeValue, minutesAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsMinutes, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
+export { writeTime } from './utils/write-time/write-time.js';
+export { writtenList, writtenNumbers } from './utils/written-list/written-list.js';

package/dist/mixins/mixin-chart-source/mixin-chart-source.d.ts

@@ -113,8 +113,8 @@ export declare class MixinChartSourceInterface {
     /**
      * The id of the table to read.
      *
-     * Resolved through `getRootNode()`, so a chart inside another component's
-     * shadow root names a table in that root rather than in the document. A
+     * Names a table in the same tree, so a chart inside another component's
+     * shadow root reads a table in that root rather than one in the document. A
      * `<table>` or anything built from grid roles, including `helix-table`.
      *
      * **In React this arrives as a property and not as an attribute**, the way

package/dist/utils/css-color/css-color.d.ts

@@ -41,20 +41,6 @@ export interface Color {
 }
 /** The syntaxes a value can be written in. */
 export type ColorFormat = 'hex' | 'hsl' | 'rgb';
-/**
- * Splits a comma-separated list of colors, ignoring the commas inside them.
- *
- * A plain `split(',')` cannot hold the legacy syntaxes:
- * `#ef4444, rgb(249 115 22), rgba(34,197,94,.5)` comes apart into six fragments,
- * four of them not colors, and the row quietly renders three swatches instead of
- * four. The modern space-separated forms survive it, which is what makes such a
- * list look like it works.
- *
- * Depth rather than a regular expression, because the thing that matters is
- * whether a comma is inside a function call and that is exactly what a counter
- * answers. No color syntax nests, so a single counter is enough.
- */
-export declare const splitColors: (value: string) => string[];
 /**
  * Any of the syntaxes to the working model, or `null` where it is not a color.
  *

package/dist/utils/css-color/css-color.js

@@ -74,28 +74,6 @@ const toHsl = (color) => {
             : (brightness - lightness) / Math.min(lightness, 1 - lightness)) * 100),
     };
 };
-export const splitColors = (value) => {
-    const found = [];
-    let depth = 0;
-    let current = '';
-    for (const character of value) {
-        if (character === '(') {
-            depth += 1;
-        }
-        else if (character === ')') {
-            depth = Math.max(0, depth - 1);
-        }
-        if (character === ',' && depth === 0) {
-            found.push(current.trim());
-            current = '';
-        }
-        else {
-            current += character;
-        }
-    }
-    found.push(current.trim());
-    return found.filter(Boolean);
-};
 export const parseColor = (value) => {
     const text = value.trim().toLowerCase();
     if (text === '') {

package/dist/utils/draw-tooltip/draw-tooltip.d.ts

@@ -6,8 +6,8 @@ import type { Row } from '../read-series/read-series.js';
  *
  * **A name six templates and this file have to agree on is a name that will
  * stop agreeing**, which is `PALETTE`'s argument and it holds harder here: the
- * failure is silent. `within` resolves through `getElementById`, so a plot
- * renamed on one side returns null, the boundary falls back to the viewport,
+ * failure is silent. `within` resolves by id, so a plot renamed on one side
+ * returns null, the boundary falls back to the viewport,
  * and the bubble goes back to hanging past the drawing with nothing reported
  * anywhere.
  *
@@ -64,10 +64,10 @@ export interface TooltipAt {
  * chart. Escaping that means reimplementing `PopoverController`, which is
  * `Tooltip` with extra steps and a second copy of the hard part.
  *
- * **`for` was already the anchor and needed nothing added.** It resolves through
- * `getRootNode().getElementById()`, and a chart's shadow root *is* a
- * `ShadowRoot`, so a chart names an element inside itself and `Tooltip` finds
- * it. What the chart provides is an invisible mark at the reading's point.
+ * **`for` was already the anchor and needed nothing added.** It resolves in the
+ * tree the tooltip sits in, and the mark is in the same shadow root, so a chart
+ * names an element inside itself and `Tooltip` finds it. What the chart
+ * provides is an invisible mark at the reading's point.
  *
  * **An HTML mark rather than the `<rect>` or `<circle>` already there.**
  * `FloatingController` types its anchor as `HTMLElement` and an SVG element is

package/dist/utils/element-by-id/element-by-id.d.ts

@@ -0,0 +1,64 @@
+/** What `elementById` may do beyond searching the tree it was asked about. */
+export interface ElementByIdOptions {
+    /**
+     * Also search the document, where the tree the node sits in holds no such id.
+     *
+     * **For a fragment on a real anchor, and for nothing else.** The platform
+     * resolves `<a href="#main">` against the document whatever tree the anchor
+     * sits in, so a component that calls `preventDefault()` and performs that
+     * navigation itself has to land on the element the browser would have.
+     * `SkipLink` is the one that does, and it is the whole of its difference from
+     * the callers below: inside an app shell's shadow root it would otherwise
+     * decline the press, the browser would scroll to the document's `#main` and
+     * leave focus behind, and moving focus is the entire reason the component
+     * exists.
+     *
+     * **Off by default, because an id matched across trees is an id matched by
+     * coincidence.** Every other caller takes an id as a property, wires the
+     * element it names, and has no platform behavior to agree with, so `null` is
+     * the honest answer and reaching into the document would point a tooltip, a
+     * chart or a command button at whatever else on the page shares the name.
+     * `Outline` reads `href`s too and still does not pass this: it intercepts no
+     * press, it observes sections in its own tree and marks the link pointing at
+     * one.
+     */
+    orDocument?: boolean;
+}
+/**
+ * The element an id names, looked up in the tree the node sits in.
+ *
+ * **`getRootNode()` rather than `document`, which is what makes a component
+ * composable.** An id is unique to a tree and not to a page, so a component
+ * inside another component's shadow root names an element in that root. Asking
+ * the document finds nothing there, and on a page where the name is taken it
+ * finds an element in somebody else's tree.
+ *
+ * **What `getRootNode()` returns need not be able to answer, and that guard is
+ * load-bearing in both environments this library runs in.** Measured 18 Sep
+ * 2026, and held by the two specs beside this file. Under Lit SSR's DOM shim
+ * `getRootNode()` returns a `Document` carrying no `getElementById` at all, so
+ * an unguarded call is a `TypeError` rather than a miss and takes the whole
+ * server render down the first time a component resolves `for`. In Chromium and
+ * in happy-dom alike an element that is not connected is its own root, and an
+ * `HTMLElement` has no lookup either, which is the reading every caller here is
+ * one detached element away from.
+ *
+ * A `DocumentFragment` is not a case, which is worth saying because it looks
+ * like the obvious one: `getElementById` comes from `NonElementParentNode`, so a
+ * bare fragment and a `<template>`'s content both carry it.
+ *
+ * **Decoding stays at the call site.** `SkipLink` and `Outline` take an `href`
+ * and owe it a `decodeURIComponent`; the callers that take an id property do
+ * not, and a utility that decoded would corrupt a literal `%` in one of theirs.
+ */
+export declare const elementById: (from: Node, id: string, options?: ElementByIdOptions) => HTMLElement | null;
+/**
+ * Whether ids resolve at all in the tree this node sits in.
+ *
+ * The same platform fact as `elementById`'s guard, asked as a question, for a
+ * component that has to tell "no such element" from "no tree to look in".
+ * `Heatmap` is the case and its note gives the cost: an empty state served
+ * because a server could not resolve `for` is a crawler reading "No readings"
+ * over ninety days of them.
+ */
+export declare const searchableById: (from: Node) => boolean;

package/dist/utils/element-by-id/element-by-id.js

@@ -0,0 +1,10 @@
+export const elementById = (from, id, options) => {
+    const root = from.getRootNode();
+    const found = root.getElementById?.(id) ?? null;
+    if (found || options?.orDocument !== true) {
+        return found;
+    }
+    const page = globalThis.document;
+    return page?.getElementById?.(id) ?? null;
+};
+export const searchableById = (from) => typeof from.getRootNode().getElementById === 'function';

package/dist/utils/inline-step/inline-step.js

@@ -1,7 +1,7 @@
+import { isRtl } from '../is-rtl/is-rtl.js';
 export const inlineStep = (element, key) => {
     if (key !== 'ArrowLeft' && key !== 'ArrowRight') {
         return 0;
     }
-    const rtl = getComputedStyle(element).direction === 'rtl';
-    return (key === 'ArrowRight') !== rtl ? 1 : -1;
+    return (key === 'ArrowRight') !== isRtl(element) ? 1 : -1;
 };

package/dist/utils/is-rtl/is-rtl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether the line of text an element sits on runs right to left.
+ *
+ * **The computed `direction`, not `:dir()` and not the `dir` attribute.** The
+ * three part only where a sheet sets `direction` without an attribute, and
+ * there the row on screen is laid out by `direction`: a flex row and a grid
+ * both follow it. `inlineStep` makes that argument in full, and it is the same
+ * question in every caller here, which is why there is one answer to it.
+ *
+ * **Guarded, because a server shim need not have `getComputedStyle`.** Most
+ * callers reach this from a pointer handler and so only ever in a browser, but
+ * `ScatterChart` asks inside `renderTooltip`, one early return from the render
+ * path. Without the function there is no layout to read, so the answer is the
+ * direction a document has before anything says otherwise.
+ *
+ * Asked at the moment it is needed rather than held, so a page that changes its
+ * direction is answered in the new one without anything having to watch it.
+ */
+export declare const isRtl: (element: Element) => boolean;

package/dist/utils/is-rtl/is-rtl.js

@@ -0,0 +1 @@
+export const isRtl = (element) => typeof getComputedStyle === 'function' && getComputedStyle(element).direction === 'rtl';

package/dist/utils/split-values/split-values.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One CSS value list split into its values, never inside a function or a
+ * bracket.
+ *
+ * The separator is the one the property uses: a comma for a list of colors, a
+ * space for a list of grid tracks. Whichever it is, the trap is the same one
+ * from opposite sides. `split(',')` turns
+ * `#ef4444, rgb(249 115 22), rgba(34,197,94,.5)` into six fragments, four of
+ * them not colors, and a row of swatches quietly draws three instead of four.
+ * `split(/\s+/)` turns `minmax(0, 1fr)` into two tracks, and a grid given a
+ * track it cannot read draws one column. Both spellings look like they work,
+ * because the modern space-separated color forms and the single-keyword tracks
+ * survive them.
+ *
+ * Depth rather than a regular expression, because what matters is whether the
+ * separator is inside a call and that is exactly what a counter answers.
+ * Brackets count with parentheses, since a grid's line names are written in
+ * them. Nesting is counted rather than assumed away: `minmax(0, calc(1px + 1%))`
+ * is one value.
+ *
+ * Empty values are dropped, so a leading, doubled or trailing separator leaves
+ * nothing behind to be parsed as a value nobody wrote.
+ */
+export declare const splitValues: (text: string, separator: ',' | ' ') => string[];

package/dist/utils/split-values/split-values.js

@@ -0,0 +1,23 @@
+export const splitValues = (text, separator) => {
+    const values = [];
+    let depth = 0;
+    let current = '';
+    for (const character of text.trim()) {
+        if (character === '(' || character === '[') {
+            depth += 1;
+        }
+        else if (character === ')' || character === ']') {
+            depth = Math.max(0, depth - 1);
+        }
+        const separates = separator === ' ' ? /\s/.test(character) : character === separator;
+        if (depth === 0 && separates) {
+            values.push(current.trim());
+            current = '';
+        }
+        else {
+            current += character;
+        }
+    }
+    values.push(current.trim());
+    return values.filter((one) => one !== '');
+};