@fusion.dev/helix-core 0.0.0-dev

package/dist/utils/elapsed-time/elapsed-time.js

@@ -0,0 +1,117 @@
+/**
+ * A timestamp read the way a feed reads one: short, and a date once short stops
+ * meaning anything.
+ *
+ * **The compact form is ambiguous past a week, and that is why it stops.**
+ * `Intl.NumberFormat` with `unitDisplay: 'narrow'` is the only locale-aware way
+ * to get "42m" rather than "42 minutes ago", and measured across locales it
+ * renders both `minute` and `month` as `m` in en-US: "3m" is three minutes or
+ * three months and a reader cannot tell which. `Intl.RelativeTimeFormat` in its
+ * narrow style disambiguates the month as "3mo" and keeps an affix that cannot
+ * be removed across locales, German prefixing "vor" and Japanese suffixing 前.
+ *
+ * So the compact form covers the range where it is unambiguous, the units up to
+ * a week, and past that this returns a date. Nothing is guessed and nothing is
+ * hand-written: the short units come from `Intl.NumberFormat`, the dates from
+ * `Intl.DateTimeFormat`, and both answer to the caller's locale.
+ *
+ * Cached per locale for the reason `relativeTime` and `formatNumbers` are: the
+ * constructors are expensive, the calls are cheap, and a feed of fifty items
+ * formats fifty times per update.
+ */
+const held = new Map();
+const dated = new Map();
+/** The units the compact form covers, largest last. `week` is deliberately not
+    among them: past six days this returns a date instead, which is both shorter
+    to read and the only reading that cannot be mistaken for minutes. */
+const UNITS = [
+    { ms: 60_000, unit: 'minute' },
+    { ms: 3_600_000, unit: 'hour' },
+    { ms: 86_400_000, unit: 'day' },
+];
+/** Where the compact form gives out, in milliseconds. Seven days. */
+const HORIZON = 604_800_000;
+const compact = (locale) => {
+    let found = held.get(locale);
+    if (!found) {
+        found = UNITS.map(({ unit }) => new Intl.NumberFormat(locale || undefined, {
+            style: 'unit',
+            unit,
+            unitDisplay: 'narrow',
+        }));
+        held.set(locale, found);
+    }
+    return found;
+};
+/** Same day and month for a timestamp inside the year, month and year outside
+    it: "12 Mar" says everything while the year is understood, and "Mar 2023" is
+    what a reader wants once it is not. */
+const calendar = (locale) => {
+    let found = dated.get(locale);
+    if (!found) {
+        found = [
+            new Intl.DateTimeFormat(locale || undefined, { day: 'numeric', month: 'short' }),
+            new Intl.DateTimeFormat(locale || undefined, { month: 'short', year: 'numeric' }),
+        ];
+        dated.set(locale, found);
+    }
+    return found;
+};
+/**
+ * A formatter for one locale, kept.
+ *
+ * `now` is a parameter rather than read from the clock, for the reason
+ * `relativeTime` gives: a function that reads `Date.now()` internally can only
+ * be tested by waiting or by replacing a global, and both produce specs that
+ * fail on a slow machine.
+ */
+export const elapsedTime = (locale) => {
+    const short = compact(locale);
+    const dates = calendar(locale);
+    /* "now" rather than a count of seconds, and taken from `Intl` rather than
+       written here so it is a word in the reader's language. Under a minute a feed
+       that reports 3, then 4, then 5 seconds is a feed moving under somebody
+       trying to read it, and nobody acts differently at seven seconds than four. */
+    const zero = new Intl.RelativeTimeFormat(locale || undefined, { numeric: 'auto' });
+    return (from, now) => {
+        const elapsed = now.getTime() - from.getTime();
+        if (!Number.isFinite(elapsed)) {
+            return { next: Number.POSITIVE_INFINITY, text: '' };
+        }
+        const size = Math.abs(elapsed);
+        if (size < 60_000) {
+            /* Floored like every other branch. At 59,999 milliseconds the remainder is
+               one, and a caller handed a one is re-armed inside the callback that
+               fired it. `relativeTime` shipped without this floor on the same branch
+               and its own `Relative.next` claimed to have it; only the shared ticker's
+               own `Math.max(1000, ...)` was standing between that and a busy loop. */
+            return { next: Math.max(1000, 60_000 - size), text: zero.format(0, 'second') };
+        }
+        /* A date, and it will not change again. `Infinity` is the whole point of
+           saying so: the caller schedules nothing, so a feed of old notifications
+           left open overnight wakes for none of them. */
+        if (size >= HORIZON) {
+            const sameYear = from.getFullYear() === now.getFullYear();
+            const format = sameYear ? dates[0] : dates[1];
+            return { next: Number.POSITIVE_INFINITY, text: format.format(from) };
+        }
+        let index = 0;
+        for (let at = 0; at < UNITS.length; at += 1) {
+            if (size >= UNITS[at].ms) {
+                index = at;
+            }
+        }
+        const chosen = UNITS[index];
+        const count = Math.trunc(size / chosen.ms);
+        /* Time until the count ticks over, which is the remainder of the current
+           unit rather than the whole of one: read at 90 seconds an item is "1m" for
+           another 30 seconds, not another 60. Capped where `relativeTime` caps it,
+           and floored at a second so nobody is handed a zero and schedules a busy
+           loop. */
+        const remaining = Math.min(chosen.ms - (size % chosen.ms), HORIZON - size);
+        return {
+            next: Math.max(1000, Math.min(remaining, 3_600_000)),
+            text: short[index].format(count),
+        };
+    };
+};

package/dist/utils/focusable-elements/focusable-elements.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Everything inside `root` the reader can reach with Tab, in document order.
+ *
+ * Separate from the focus trap because finding is the half most callers want:
+ * roving tabindex, arrow-key navigation and "focus the first thing" all need
+ * this list and none of them traps anything.
+ *
+ * Visibility is tested with `getClientRects()` rather than `offsetParent`,
+ * which is null for anything inside a `position: fixed` container. A drawer is
+ * exactly that, so the `offsetParent` test excluded every control in the thing
+ * being trapped.
+ */
+export declare const focusableElements: (root: HTMLElement) => HTMLElement[];
+/**
+ * The truly focused element, following shadow roots down.
+ *
+ * `document.activeElement` stops at the outermost host, so a button inside two
+ * shadow roots reports as the component rather than as itself.
+ */
+export declare const deepActiveElement: () => Element | null;
+/**
+ * Whether `node` sits inside `root`, following shadow boundaries upward.
+ *
+ * `Node.contains` walks `parentNode` and a shadow root's `parentNode` is null,
+ * so it answers false for anything inside a component. Paired with
+ * `deepActiveElement`, which returns exactly such a node, that pairing is a trap
+ * of its own: the two look like they belong together and one of them crosses.
+ *
+ * `FocusTrapController` had precisely that, `contains(deepActiveElement())`,
+ * and it is why every dialog and drawer in the library leaked. Focus on a
+ * `helix-button` reports as the `<button>` in its shadow root, which is in no
+ * light-DOM container anywhere, so the trap read every reader as already
+ * outside it.
+ *
+ * `host` is reached without naming `ShadowRoot`, which the server has no global
+ * for. This runs from a keydown handler and would never execute there, but a
+ * bare reference is the kind that surfaces as a crash in Lit's result collector
+ * the first time something calls it early.
+ */
+export declare const deepContains: (root: Node, node: Node | null) => boolean;

package/dist/utils/focusable-elements/focusable-elements.js

@@ -0,0 +1,88 @@
+/**
+ * Elements the platform will focus, without naming a single component.
+ *
+ * Custom elements are covered separately below: one with `delegatesFocus` is
+ * focusable as a host, and that is readable from outside through `shadowRoot`.
+ * Listing tag names instead would mean a utility in `core` that only worked for
+ * the components `core` happens to know about.
+ */
+const NATIVE_FOCUSABLE = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+/**
+ * Everything inside `root` the reader can reach with Tab, in document order.
+ *
+ * Separate from the focus trap because finding is the half most callers want:
+ * roving tabindex, arrow-key navigation and "focus the first thing" all need
+ * this list and none of them traps anything.
+ *
+ * Visibility is tested with `getClientRects()` rather than `offsetParent`,
+ * which is null for anything inside a `position: fixed` container. A drawer is
+ * exactly that, so the `offsetParent` test excluded every control in the thing
+ * being trapped.
+ */
+export const focusableElements = (root) => 
+/* One pass asking both questions, rather than two passes concatenated.
+ *
+ * Two lists joined end to end is not document order, and this said "in
+ * document order" while returning every native element followed by every
+ * delegating host: measured, `b d a c` for a tree holding `a b c d`. The
+ * trap reads `items[0]` and `items.at(-1)` as its boundaries, so a surface
+ * whose last control is a plain `<button>` and whose first is a Helix
+ * component had a last that was not last, and forward Tab off the real end
+ * did not wrap. Focus left the dialog.
+ *
+ * It is invisible in a set that is all one kind, which is what every example
+ * and every spec had. A single filtered walk cannot express the fault, and
+ * dedup comes free with it: a delegating host that also matches the native
+ * selector is visited once because it is one node. */
+[...root.querySelectorAll('*')].filter((node) => (node.matches(NATIVE_FOCUSABLE) || node.shadowRoot?.delegatesFocus === true) &&
+    node.getClientRects().length > 0);
+/**
+ * The truly focused element, following shadow roots down.
+ *
+ * `document.activeElement` stops at the outermost host, so a button inside two
+ * shadow roots reports as the component rather than as itself.
+ */
+export const deepActiveElement = () => {
+    let active = document.activeElement;
+    while (active?.shadowRoot?.activeElement) {
+        active = active.shadowRoot.activeElement;
+    }
+    return active;
+};
+/**
+ * Whether `node` sits inside `root`, following shadow boundaries upward.
+ *
+ * `Node.contains` walks `parentNode` and a shadow root's `parentNode` is null,
+ * so it answers false for anything inside a component. Paired with
+ * `deepActiveElement`, which returns exactly such a node, that pairing is a trap
+ * of its own: the two look like they belong together and one of them crosses.
+ *
+ * `FocusTrapController` had precisely that, `contains(deepActiveElement())`,
+ * and it is why every dialog and drawer in the library leaked. Focus on a
+ * `helix-button` reports as the `<button>` in its shadow root, which is in no
+ * light-DOM container anywhere, so the trap read every reader as already
+ * outside it.
+ *
+ * `host` is reached without naming `ShadowRoot`, which the server has no global
+ * for. This runs from a keydown handler and would never execute there, but a
+ * bare reference is the kind that surfaces as a crash in Lit's result collector
+ * the first time something calls it early.
+ */
+export const deepContains = (root, node) => {
+    let current = node;
+    while (current) {
+        if (current === root) {
+            return true;
+        }
+        current = current.parentNode ?? current.host ?? null;
+    }
+    return false;
+};

package/dist/utils/format-numbers/format-numbers.d.ts

@@ -0,0 +1 @@
+export declare const formatNumbers: (locale: string) => ((value: number) => string);

package/dist/utils/format-numbers/format-numbers.js

@@ -0,0 +1,29 @@
+/**
+ * A number formatter for a locale, built once and kept.
+ *
+ * `Intl.NumberFormat` is expensive to construct and cheap to call, and a
+ * pagination renders its count on every update, so building one per render is
+ * the whole cost of the component. Three files in one family had worked that
+ * out separately and each kept its own two-line cache, which is three places to
+ * find the day the caching rule changes and three chances for one of them to be
+ * subtly different.
+ *
+ * Keyed on the locale, so a component that never changes locale builds one
+ * formatter for its life and one that does builds a second and drops the first.
+ * Shared across components rather than per instance: a table of a hundred rows
+ * asking for the same locale gets the same object, which is what a cache is
+ * for and what a private field per element cannot do.
+ *
+ * An empty string means the runtime's own, which is what every caller was
+ * already passing `|| undefined` to say.
+ */
+const held = new Map();
+export const formatNumbers = (locale) => {
+    let format = held.get(locale);
+    if (!format) {
+        format = new Intl.NumberFormat(locale || undefined);
+        held.set(locale, format);
+    }
+    const found = format;
+    return (value) => found.format(value);
+};

package/dist/utils/host-aria/host-aria.d.ts

@@ -0,0 +1,38 @@
+/** What a host can say about itself. Anything omitted is left alone. */
+export interface HostAria {
+    /** Elements describing it. Cleared with an empty array. */
+    describedBy?: Element[];
+    /** The accessible name, as a string. `''` clears it. */
+    label?: string;
+    /** Elements naming it, which beat `label` where both are set. */
+    labelledBy?: Element[];
+    /** The role, which is what the host is. `''` clears it. */
+    role?: string;
+}
+/**
+ * Writes a host's semantics onto its `ElementInternals`.
+ *
+ * Onto internals rather than onto the host, which is the whole point: an
+ * attribute written at upgrade is markup a React consumer's server output never
+ * had, and hydration reports the difference. Internals carry the same meaning
+ * to the accessibility tree and leave the element as the consumer wrote it.
+ *
+ * **Empty means absent, and that is the trap this exists for.** Assigning `''`
+ * to `ariaLabel` is not the same as not naming the element: it is a name of no
+ * characters, which a screen reader announces as an unnamed control while every
+ * check for "is it labeled" passes. Every caller had written
+ * `this.label === '' ? null : this.label` and one of them would eventually not.
+ *
+ * **Element references are feature-tested rather than assumed.** They are the
+ * only way a host in the light DOM can point at a node in its own shadow root,
+ * an IDREF cannot cross that boundary, and the plain `element.aria*Elements`
+ * reflection drops the reference where `ElementInternals` keeps it. Older
+ * engines have neither, and assigning to a property they do not implement is a
+ * silent no-op rather than an error, so the guard is what makes the absence
+ * visible to anything reading this.
+ *
+ * Omitted keys are left alone, so a component that sets its role once in
+ * `willUpdate` and its references later in `updated` does not have to repeat
+ * itself or risk clearing what the other call wrote.
+ */
+export declare const hostAria: (internals: ElementInternals, semantics: HostAria) => void;

package/dist/utils/host-aria/host-aria.js

@@ -0,0 +1,41 @@
+/**
+ * Writes a host's semantics onto its `ElementInternals`.
+ *
+ * Onto internals rather than onto the host, which is the whole point: an
+ * attribute written at upgrade is markup a React consumer's server output never
+ * had, and hydration reports the difference. Internals carry the same meaning
+ * to the accessibility tree and leave the element as the consumer wrote it.
+ *
+ * **Empty means absent, and that is the trap this exists for.** Assigning `''`
+ * to `ariaLabel` is not the same as not naming the element: it is a name of no
+ * characters, which a screen reader announces as an unnamed control while every
+ * check for "is it labeled" passes. Every caller had written
+ * `this.label === '' ? null : this.label` and one of them would eventually not.
+ *
+ * **Element references are feature-tested rather than assumed.** They are the
+ * only way a host in the light DOM can point at a node in its own shadow root,
+ * an IDREF cannot cross that boundary, and the plain `element.aria*Elements`
+ * reflection drops the reference where `ElementInternals` keeps it. Older
+ * engines have neither, and assigning to a property they do not implement is a
+ * silent no-op rather than an error, so the guard is what makes the absence
+ * visible to anything reading this.
+ *
+ * Omitted keys are left alone, so a component that sets its role once in
+ * `willUpdate` and its references later in `updated` does not have to repeat
+ * itself or risk clearing what the other call wrote.
+ */
+export const hostAria = (internals, semantics) => {
+    if (semantics.role !== undefined) {
+        internals.role = semantics.role === '' ? null : semantics.role;
+    }
+    if (semantics.label !== undefined) {
+        internals.ariaLabel = semantics.label === '' ? null : semantics.label;
+    }
+    if (semantics.labelledBy !== undefined && 'ariaLabelledByElements' in internals) {
+        internals.ariaLabelledByElements = semantics.labelledBy.length > 0 ? semantics.labelledBy : null;
+    }
+    if (semantics.describedBy !== undefined && 'ariaDescribedByElements' in internals) {
+        internals.ariaDescribedByElements =
+            semantics.describedBy.length > 0 ? semantics.describedBy : null;
+    }
+};

package/dist/utils/inherit-disabled/inherit-disabled.d.ts

@@ -0,0 +1,33 @@
+/** The least a member must be for a group to disable it. */
+export interface DisableableItem extends HTMLElement {
+    /** Whether the item is out of play, from either source. */
+    disabled: boolean;
+}
+/**
+ * Disables a group's members without forgetting what they said themselves.
+ *
+ * A group and its members are two sources for one fact: a member is out of play
+ * if either says so. Written the obvious way that is
+ * `item.disabled = group || item.disabled`, and it latches. The first pass with
+ * the group disabled writes `true` onto every member; the next pass reads its
+ * own writing back as the member's own answer; and enabling the group leaves
+ * every member disabled for good. Nothing about it is visible until something
+ * re-enables a group, which is rare enough to ship and miserable to find.
+ *
+ * So what a member said itself is recorded before it is first overridden, and
+ * given back when the group lets go. Restoring is the half that matters: a
+ * version that only recorded would read the overridden value as the member's
+ * own the moment the group was enabled, which is the same latch by a longer
+ * route.
+ *
+ * Once given back, the record is dropped, so a consumer disabling a member
+ * afterwards is its own answer again and is left alone.
+ */
+export declare const inheritDisabled: (disabled: boolean, items: DisableableItem[]) => void;
+/**
+ * Forgets what a group recorded about an item.
+ *
+ * For an item leaving a group, which would otherwise carry the group's last
+ * word into wherever it goes next.
+ */
+export declare const forgetDisabled: (item: Element) => void;

package/dist/utils/inherit-disabled/inherit-disabled.js

@@ -0,0 +1,55 @@
+/**
+ * What each item declared for itself, before any group wrote to it.
+ *
+ * A `WeakMap` because the alternative is reading the attribute back, and the
+ * attribute is the thing being written: `disabled` reflects, so the second pass
+ * would read what the first pass wrote and the item would never come back.
+ */
+const own = new WeakMap();
+/**
+ * Disables a group's members without forgetting what they said themselves.
+ *
+ * A group and its members are two sources for one fact: a member is out of play
+ * if either says so. Written the obvious way that is
+ * `item.disabled = group || item.disabled`, and it latches. The first pass with
+ * the group disabled writes `true` onto every member; the next pass reads its
+ * own writing back as the member's own answer; and enabling the group leaves
+ * every member disabled for good. Nothing about it is visible until something
+ * re-enables a group, which is rare enough to ship and miserable to find.
+ *
+ * So what a member said itself is recorded before it is first overridden, and
+ * given back when the group lets go. Restoring is the half that matters: a
+ * version that only recorded would read the overridden value as the member's
+ * own the moment the group was enabled, which is the same latch by a longer
+ * route.
+ *
+ * Once given back, the record is dropped, so a consumer disabling a member
+ * afterwards is its own answer again and is left alone.
+ */
+export const inheritDisabled = (disabled, items) => {
+    for (const item of items) {
+        if (disabled) {
+            if (!own.has(item)) {
+                own.set(item, item.disabled);
+            }
+            item.disabled = true;
+            continue;
+        }
+        /* Only where this held it down. An item nothing overrode is the consumer's
+           business and is not touched, which is what keeps a group that was never
+           disabled from writing to its members at all. */
+        if (own.has(item)) {
+            item.disabled = own.get(item) ?? false;
+            own.delete(item);
+        }
+    }
+};
+/**
+ * Forgets what a group recorded about an item.
+ *
+ * For an item leaving a group, which would otherwise carry the group's last
+ * word into wherever it goes next.
+ */
+export const forgetDisabled = (item) => {
+    own.delete(item);
+};

package/dist/utils/line-path/line-path.d.ts

@@ -0,0 +1,23 @@
+/** How a line gets from one point to the next. */
+export type Curve = 'smooth' | 'step' | 'straight';
+/** A point in a drawing's own coordinates. */
+export type Point = readonly [number, number];
+/**
+ * Builds an SVG path through a set of points.
+ *
+ * Shared by every chart that draws a line, so the choice of curve is one
+ * implementation rather than one per chart. Pure: it takes points and returns a
+ * string, and knows nothing about elements or lifecycles.
+ *
+ * `straight` joins the readings and claims nothing between them, which is why
+ * it is the default. `smooth` is easier to follow across a long series and
+ * invents the values in between, so it is a reading aid rather than a neutral
+ * one. `step` claims the opposite, that a reading holds until the next one, and
+ * changes at the midpoint rather than at either end, since a chart's x axis is
+ * an order and neither neighbor has a better claim on the moment it moved.
+ *
+ * Fewer than two points is an empty string rather than a partial path: one
+ * reading is not a line, and `M0,0` alone draws nothing while still being a
+ * path element that looks like it should.
+ */
+export declare const linePath: (points: readonly Point[], curve?: Curve) => string;

package/dist/utils/line-path/line-path.js

@@ -0,0 +1,107 @@
+/** Two decimals, which is more than a 100 unit view box can show. */
+const round = (value) => Math.round(value * 100) / 100;
+/**
+ * Tangents that cannot overshoot, by Fritsch and Carlson.
+ *
+ * **The reason `smooth` is monotone cubic and not a Catmull-Rom spline, which
+ * is the shorter code.** A spline through the points is free to bulge past them
+ * between two of them, so a series whose lowest reading is 40 draws a curve
+ * that dips to 32 on the way there. Every value on that curve is a claim about
+ * a measurement, and the ones between the readings are the chart's own
+ * invention either way; a curve that stays inside the data at least invents
+ * nothing the data contradicts.
+ *
+ * Two rules do it. A tangent at a turning point is flat, so the curve arrives
+ * and leaves level rather than carrying on past the peak; and where a tangent
+ * is steep enough relative to its neighbours to bulge anyway, the pair is
+ * scaled back until it cannot.
+ */
+const tangents = (xs, ys) => {
+    const count = xs.length;
+    const secant = [];
+    for (let index = 0; index < count - 1; index += 1) {
+        secant.push((ys[index + 1] - ys[index]) /
+            (xs[index + 1] - xs[index]));
+    }
+    const slope = new Array(count);
+    slope[0] = secant[0];
+    slope[count - 1] = secant[count - 2];
+    for (let index = 1; index < count - 1; index += 1) {
+        const before = secant[index - 1];
+        const after = secant[index];
+        // Flat at a turning point, which is what keeps the curve off the outside.
+        slope[index] = before * after <= 0 ? 0 : (before + after) / 2;
+    }
+    for (let index = 0; index < count - 1; index += 1) {
+        const run = secant[index];
+        if (run === 0) {
+            slope[index] = 0;
+            slope[index + 1] = 0;
+            continue;
+        }
+        const from = slope[index] / run;
+        const to = slope[index + 1] / run;
+        const reach = Math.hypot(from, to);
+        if (reach > 3) {
+            const scale = 3 / reach;
+            slope[index] = scale * from * run;
+            slope[index + 1] = scale * to * run;
+        }
+    }
+    return slope;
+};
+/**
+ * Builds an SVG path through a set of points.
+ *
+ * Shared by every chart that draws a line, so the choice of curve is one
+ * implementation rather than one per chart. Pure: it takes points and returns a
+ * string, and knows nothing about elements or lifecycles.
+ *
+ * `straight` joins the readings and claims nothing between them, which is why
+ * it is the default. `smooth` is easier to follow across a long series and
+ * invents the values in between, so it is a reading aid rather than a neutral
+ * one. `step` claims the opposite, that a reading holds until the next one, and
+ * changes at the midpoint rather than at either end, since a chart's x axis is
+ * an order and neither neighbor has a better claim on the moment it moved.
+ *
+ * Fewer than two points is an empty string rather than a partial path: one
+ * reading is not a line, and `M0,0` alone draws nothing while still being a
+ * path element that looks like it should.
+ */
+export const linePath = (points, curve = 'straight') => {
+    if (points.length < 2) {
+        return '';
+    }
+    const [first] = points;
+    const move = `M${round(first[0])},${round(first[1])}`;
+    if (curve === 'step') {
+        return (move +
+            points
+                .slice(1)
+                .map(([x, y], index) => {
+                const middle = round(((points[index][0] ?? 0) + x) / 2);
+                return `H${middle}V${round(y)}H${round(x)}`;
+            })
+                .join(''));
+    }
+    if (curve === 'smooth') {
+        const xs = points.map(([x]) => x);
+        const ys = points.map(([, y]) => y);
+        const slope = tangents(xs, ys);
+        let drawing = move;
+        for (let index = 0; index < points.length - 1; index += 1) {
+            const reach = (xs[index + 1] - xs[index]) / 3;
+            const fromX = round(xs[index] + reach);
+            const fromY = round(ys[index] + slope[index] * reach);
+            const toX = round(xs[index + 1] - reach);
+            const toY = round(ys[index + 1] - slope[index + 1] * reach);
+            drawing += `C${fromX},${fromY} ${toX},${toY} ${round(xs[index + 1])},${round(ys[index + 1])}`;
+        }
+        return drawing;
+    }
+    return (move +
+        points
+            .slice(1)
+            .map(([x, y]) => `L${round(x)},${round(y)}`)
+            .join(''));
+};

package/dist/utils/on-unless-false/on-unless-false.d.ts

@@ -0,0 +1,28 @@
+import type { ComplexAttributeConverter } from 'lit';
+/**
+ * For a boolean property that is on unless a consumer says otherwise.
+ *
+ * **Lit's boolean converter cannot express false, and that is the whole
+ * problem.** It answers `value !== null`, so an attribute is true by being
+ * there: `modal` is true, `modal=""` is true, and `modal="false"` is true as
+ * well, because it is present. A property defaulting to `true` therefore has no
+ * attribute that turns it off at all, and a consumer who writes the obvious
+ * thing gets the opposite of what they asked for, silently.
+ *
+ * Found on `Drawer.modal`, where it mattered: a tour cannot point inside a
+ * modal, so `modal="false"` is exactly what a consumer reaches for, and it left
+ * the drawer modal. Two others have the same shape, `Video.playsInline` and the
+ * sandbox source's `tabIndents`.
+ *
+ * So: absent is the default, present is on, and the one string that means off
+ * is the one a consumer would write. `"false"` only, and not `"0"` or `"no"`,
+ * because a converter that accepts a vocabulary invites a consumer to guess at
+ * it, and the one they guess wrong is the one that silently means on.
+ *
+ * **The other answer is to invert the property, and it is worse.** `Drawer`
+ * would take `modeless`, absent meaning modal, which satisfies the rule that a
+ * reflected property takes no default. It also renames the thing every consumer
+ * already writes, to a word nobody reaches for, so that markup can express a
+ * state that is rare. The name stays and the attribute learns to say no.
+ */
+export declare const onUnlessFalse: ComplexAttributeConverter<boolean>;

package/dist/utils/on-unless-false/on-unless-false.js

@@ -0,0 +1,32 @@
+/**
+ * For a boolean property that is on unless a consumer says otherwise.
+ *
+ * **Lit's boolean converter cannot express false, and that is the whole
+ * problem.** It answers `value !== null`, so an attribute is true by being
+ * there: `modal` is true, `modal=""` is true, and `modal="false"` is true as
+ * well, because it is present. A property defaulting to `true` therefore has no
+ * attribute that turns it off at all, and a consumer who writes the obvious
+ * thing gets the opposite of what they asked for, silently.
+ *
+ * Found on `Drawer.modal`, where it mattered: a tour cannot point inside a
+ * modal, so `modal="false"` is exactly what a consumer reaches for, and it left
+ * the drawer modal. Two others have the same shape, `Video.playsInline` and the
+ * sandbox source's `tabIndents`.
+ *
+ * So: absent is the default, present is on, and the one string that means off
+ * is the one a consumer would write. `"false"` only, and not `"0"` or `"no"`,
+ * because a converter that accepts a vocabulary invites a consumer to guess at
+ * it, and the one they guess wrong is the one that silently means on.
+ *
+ * **The other answer is to invert the property, and it is worse.** `Drawer`
+ * would take `modeless`, absent meaning modal, which satisfies the rule that a
+ * reflected property takes no default. It also renames the thing every consumer
+ * already writes, to a word nobody reaches for, so that markup can express a
+ * state that is rare. The name stays and the attribute learns to say no.
+ */
+export const onUnlessFalse = {
+    fromAttribute: (value) => value !== null && value !== 'false',
+    /* Written out so it survives being reflected later. `''` rather than
+       `'true'`, which is what a boolean attribute looks like everywhere else. */
+    toAttribute: (value) => (value ? '' : 'false'),
+};