@fusion.dev/helix-core 0.1.0 → 0.3.0

package/dist/utils/restore-value/restore-value.js

@@ -1,56 +1,7 @@
-/*
- * Puts a value back into a text control without moving the reader's caret.
- *
- * A controlled input has to restore what the element holds whenever the native
- * control has moved and the answer has not followed, which is a refusal or a
- * consumer who owns the value and has not answered yet. Assigning `value` is
- * how that is done, and per spec assigning a *different* string moves the text
- * entry cursor to the end. Measured: caret at index three in `abcdef`, assign
- * `abcXdef`, caret at seven. Assigning the same string leaves it alone, which
- * is why this only shows against a consumer that is slow to answer.
- *
- * The offset is adjusted by the length difference rather than clamped, because
- * the common case is exactly one character wide: the reader typed, the element
- * restored the shorter previous string, and the caret belongs one place back.
- * Clamping alone would leave it one to the right of where the reader was, which
- * is the same bug at a smaller size.
- *
- * Nothing is restored when the value already matches, since the assignment
- * itself is what moves the caret and there is nothing to assign.
- */
-/**
- * Holds the caret across a write the element does not make itself.
- *
- * **Lit's `.value` binding moves the caret to the end, and only a controlled
- * field notices.** Measured in Chrome with real typing: place the caret after
- * `Ada` in `Ada Lovelace` and press one key, and an uncontrolled field reports
- * `AdaX Lovelace` with the caret at 4, while a controlled one reports the same
- * text with the caret at 13. Editing the middle of a controlled field was
- * impossible: every keystroke threw the caret to the end.
- *
- * The asymmetry is the interesting part. Uncontrolled, `handleInput` runs
- * `restoreValue` after the state has moved, so the control already holds the
- * new text and the call returns early; when Lit's binding then assigns the same
- * string, Chrome leaves the selection alone. Controlled, the control has been
- * put *back* to the old text while the consumer decides, so Lit assigns a
- * genuinely different string and the platform resets the selection, as it does
- * for any assignment to `value`.
- *
- * So the selection is taken before the update and put back after it, mapped by
- * however much the text grew or shrank, which is the same arithmetic
- * `restoreValue` does in one step. Returned as a closure rather than a pair of
- * fields so the two halves cannot be called out of order.
- *
- * The binding itself has to stay: it is what Lit SSR serializes, and a field
- * that filled in at hydration would flash empty for every reader on a slow
- * connection.
- */
 export const holdCaret = (control) => {
     const { selectionDirection, selectionEnd, selectionStart } = control;
     const held = control.value.length;
     return () => {
-        /* Null on a control with no selection, `<input type="range">` among them,
-           where `setSelectionRange` throws rather than declining. */
         if (selectionStart === null || selectionEnd === null) {
             return;
         }
@@ -66,11 +17,6 @@ export const restoreValue = (control, next) => {
     const { selectionDirection, selectionEnd, selectionStart } = control;
     const delta = next.length - control.value.length;
     control.value = next;
-    /* A control with no selection is done here, and this is a guard rather than a
-       tidiness: `<input type="range">` reports `selectionStart` as null and
-       *throws* `InvalidStateError` from `setSelectionRange`. Measured. The slider
-       restores through this same util, which is what makes the check load-bearing
-       rather than defensive. */
     if (selectionStart === null || selectionEnd === null) {
         return;
     }

package/dist/utils/scale/scale.js

@@ -1,26 +1,7 @@
-/** The smallest and largest of a set of numbers, as a scale's domain. */
 export const extent = (values) => [
     Math.min(...values),
     Math.max(...values),
 ];
-/**
- * Maps a domain onto a range, linearly.
- *
- * A pure function rather than a controller, which is the distinction the rules
- * draw: a controller reacts to a host's lifecycle, and this is arithmetic on
- * four numbers. It holds nothing, subscribes to nothing, and can be called from
- * `render` without anything being wired up first.
- *
- * The range is given rather than assumed, so an inverted one is ordinary: SVG
- * counts down from the top, so a chart passes `[height, 0]` and gets a larger
- * value drawn higher without anything here knowing why.
- *
- * **A flat domain maps to the middle of the range, and that is the case worth
- * naming.** Every value being equal makes the domain zero wide, and the obvious
- * arithmetic divides by it: seven identical readings drew a line at `NaN`, which
- * an `<svg>` renders as no line at all rather than as an error. A flat series is
- * a real thing to plot and it should come out as a flat line halfway up.
- */
 export const linear = (domain, range) => {
     const [from, to] = domain;
     const [start, end] = range;

package/dist/utils/scale/ticks.js

@@ -1,34 +1,5 @@
-/**
- * The round numbers a reader would infer inside a domain.
- *
- * **A gridline at an arbitrary number is worse than no gridline.** The point of
- * a rule across a chart is that a reader can name the level it sits at without
- * being told, so it has to land on a number a person would have picked: 0, 250,
- * 500, not 187.4. Dividing the domain into equal parts gives the second, and
- * that is what makes this arithmetic rather than a loop.
- *
- * The step is the power of ten below the rough interval, multiplied by whichever
- * of 1, 2, 5 or 10 lands nearest the count asked for. Those four because they
- * are the multipliers that keep every tick short in decimal, which is the whole
- * property being bought: 2.5 divides as evenly as 2 and reads as a worse number.
- *
- * **The count is a target and not a promise**, which is the usual surprise.
- * Asking for five over a domain of 0 to 1000 gives six (0, 200, ... 1000);
- * asking for five over 0 to 12 gives seven at a step of 2. Forcing the count
- * would mean forcing the step, which is the thing worth keeping round. A caller
- * that needs an exact number of rules wants equal division and not this.
- *
- * Ticks outside the domain are dropped rather than clamped, so nothing is drawn
- * off the end of the box and no two rules land on the same line.
- *
- * A pure function, for the reason `linear` gives beside it: it holds nothing,
- * subscribes to nothing, and can be called from `render`.
- */
 export const ticks = (domain, count = 5) => {
     const [low, high] = domain;
-    /* A flat domain has no levels to name. Zero rules rather than one, because a
-       single rule lying exactly under a flat line is a rule nobody can see and a
-       line a reader may take for the grid. */
     if (!Number.isFinite(low) || !Number.isFinite(high) || low === high || count < 1) {
         return [];
     }
@@ -37,14 +8,7 @@ export const ticks = (domain, count = 5) => {
     const eased = rough / magnitude;
     const step = magnitude * (eased >= 7.5 ? 10 : eased >= 3 ? 5 : eased >= 1.5 ? 2 : 1);
     const found = [];
-    /* From the first multiple of the step at or above the floor, so the run is
-       anchored to the number line rather than to wherever the data happens to
-       start. Two charts of the same shape over different ranges then draw rules
-       at the same levels, which is what makes them comparable at a glance. */
     for (let at = Math.ceil(low / step) * step; at <= high; at += step) {
-        /* Floating point makes 0.30000000000000004 out of three tenths, and a
-           gridline is a number a reader sees. Rounded to the step's own precision,
-           which is as fine as any tick can legitimately be. */
         const places = Math.max(0, -Math.floor(Math.log10(step)));
         found.push(Number(at.toFixed(places)));
     }

package/dist/utils/scroll-item-into-view/scroll-item-into-view.js

@@ -1,53 +1,8 @@
-/*
- * Brings an item into view inside its own scroller, and moves nothing else.
- *
- * **Not `Element.scrollIntoView`, and the difference is the whole reason this
- * exists.** That method walks every scrollable ancestor and scrolls all of
- * them, so bringing the current item into a tree also scrolls the page the tree
- * sits on, and on a phone it takes the address bar with it. A reader who
- * pressed Down in a sidebar did not ask the document to move.
- *
- * It also does nothing when the item is already visible, where `scrollIntoView`
- * with `block: 'nearest'` still nudges. Nudging on every keypress is what makes
- * a long list feel like it is fighting the reader.
- *
- * Both axes, because the components that need this do not agree on one: a
- * carousel scrolls sideways and a tree scrolls down, and a menu that has run
- * out of room does both.
- *
- * `smooth` is a request rather than an instruction. Animating a scroll the
- * reader triggered by pressing a key means the list is still moving when the
- * next press arrives, so this follows `prefers-reduced-motion` and is off by
- * default for exactly that case.
- */
-/**
- * The nearest ancestor that actually scrolls, crossing shadow boundaries.
- *
- * **Not `item.offsetParent`**, which is the nearest *positioned* ancestor and
- * has nothing whatever to do with overflow. The two coincide often enough to
- * look right, because a scroller frequently is positioned, and they come apart
- * exactly where it matters: put anything `position: relative` between the item
- * and the box that scrolls, and the util scrolls the thing in between, which
- * does not scroll, and reports nothing.
- *
- * The walk crosses shadow boundaries through the host, because the item is
- * almost always in one and `parentElement` is null at the root. Without that
- * step, a component whose scroller is its own `[part]` would find nothing.
- *
- * It stops before the document. Scrolling the page is the one thing this whole
- * util exists not to do, so finding nothing inside the component and returning
- * null is the honest answer: the caller no-ops rather than taking the address
- * bar with it.
- */
 const scrollingAncestor = (item) => {
     const stop = item.ownerDocument.body;
     let node = climb(item);
     while (node && node !== stop) {
         const style = getComputedStyle(node);
-        /* Both axes, since the caller may need either, and `overlay` because a
-           scroller styled with it scrolls exactly as `auto` does. `clip` and
-           `hidden` are deliberately not here: they cut the content off and are not
-           something a reader can move. */
         if (/\b(auto|scroll|overlay)\b/.test(`${style.overflowX} ${style.overflowY}`)) {
             return node;
         }
@@ -55,7 +10,6 @@ const scrollingAncestor = (item) => {
     }
     return null;
 };
-/** Up one, through a shadow root where that is what is above. */
 const climb = (node) => {
     if (node.parentElement) {
         return node.parentElement;
@@ -69,10 +23,6 @@ export const scrollItemIntoView = (item, options = {}) => {
     if (!scroller) {
         return;
     }
-    /* Measured from the boxes rather than from `offsetLeft`, which is relative to
-       the offset parent and is only the scroller when nothing between them is
-       positioned. The rectangles are relative to the viewport, so the difference
-       between them is the distance regardless of what sits in between. */
     const box = item.getBoundingClientRect();
     const view = scroller.getBoundingClientRect();
     const before = { block: view.top - box.top + padding, inline: view.left - box.left + padding };
@@ -80,9 +30,6 @@ export const scrollItemIntoView = (item, options = {}) => {
         block: box.bottom - view.bottom + padding,
         inline: box.right - view.right + padding,
     };
-    /* Whichever edge it is past, and nothing when it is past neither. A scroll of
-       zero still fires a `scroll` event and still cancels a smooth one already
-       running, so the early return is behavior rather than an optimization. */
     const inline = before.inline > 0 ? -before.inline : after.inline > 0 ? after.inline : 0;
     const block = before.block > 0 ? -before.block : after.block > 0 ? after.block : 0;
     if (inline === 0 && block === 0) {

package/dist/utils/slot-filled/slot-filled.js

@@ -1,24 +1 @@
-/**
- * Whether a consumer put anything in a slot.
- *
- * **There is no selector for this**, which is why it is script. `slot:empty`
- * looks like the answer and is not: a slot's children are its *fallback*, and
- * assigned nodes are not children, so `:empty` is true whenever the fallback is
- * absent whether or not the consumer slotted anything. `:host(:has(...))` is
- * invalid CSS, and the server has no children to inspect.
- *
- * The answer matters because an empty wrapper is not free. A region that
- * generates a box is a flex item or a grid item whether or not it holds
- * anything, so it takes the container's gap: an announcement with no actions
- * pays the row gap twice. `display: none` is the only fix, because only a box
- * that is not generated has no gap beside it.
- *
- * Text or an element, because neither alone is the test. An element on its own
- * counts a whitespace-only span as content; text on its own counts an icon as
- * nothing.
- *
- * `flatten` is deliberate here, unlike the tooltip's emptiness test: this asks
- * "will anything render", where that one asks "did the consumer provide
- * anything", and a slot showing its fallback does render.
- */
 export const slotFilled = (slot) => (slot?.assignedNodes({ flatten: true }) ?? []).some((node) => node.nodeType === Node.ELEMENT_NODE || node.textContent?.trim() !== '');

package/dist/utils/tell-disclosure/tell-disclosure.js

@@ -1,61 +1,8 @@
-/** Triggers already told they cannot carry the state, so it is said once. */
 const warned = new WeakSet();
-/**
- * Tells a slotted trigger that it opens something, and whether it is open.
- *
- * **Writing `aria-expanded` onto the consumer's element is a hydration
- * mismatch, so it is not written.** The gap that answer was reaching for is
- * real: a consumer who has to mirror `open` back onto their own trigger is a
- * consumer who will forget, and the failure is silent to everyone who can see
- * the screen. It is still the wrong answer, because a component decorating a
- * consumer's markup after upgrading is one whose output a React consumer's
- * hydration disagrees with.
- *
- * **Measured 28 Aug 2026 against React 19.2.8.** Four
- * families were server-rendered as React emits them and hydrated with the
- * element definitions loaded either side of `hydrateRoot`:
- *
- * ```
- * case        writes to trigger   hydration mismatch
- * megamenu    aria-expanded       yes, both load orders
- * speed dial  aria-expanded       yes, both load orders
- * popover     nothing             no
- * menu        nothing             no
- * ```
- *
- * React reports "some attributes of the server rendered HTML didn't match the
- * client properties. This won't be patched up", and the cost is not the console
- * line: it answers a mismatch by discarding the server's HTML for that subtree
- * and rebuilding it, which is what the carousel's own note records blinding an
- * `<helix-aura>` two sections away.
- *
- * **A property crosses the gap that an attribute cannot.** React diffs the
- * attributes it rendered and never looks at a property, so the state reaches
- * the trigger, lands as `aria-expanded` inside *that element's* shadow root,
- * and the consumer's markup is exactly what they served. Both positions get
- * what they were protecting: nothing is written onto the consumer's element,
- * and the reader is still told what the control does.
- *
- * **Set before upgrade is safe**, which is what lets this run without waiting
- * for a definition: `ReactiveElement` captures an instance property assigned
- * before it upgrades and re-applies it, so a trigger whose module has not
- * loaded yet still ends up with the value.
- *
- * **A plain element is warned about rather than written to.** A
- * `<button slot="trigger">` has no shadow root to keep the state out of the
- * markup and no property to take it, and a consumer cannot mirror it themselves
- * because the open state belongs to the component. Saying so once is the same
- * answer `Tooltip` gives about the link it will not write for them.
- */
 export const tellDisclosure = (trigger, open) => {
     if (!trigger) {
         return;
     }
-    /* A custom element, which is the only kind that can hold this without putting
-       it in the markup. The tag is the test rather than `'expanded' in trigger`,
-       because the trigger may not have upgraded yet and the property lives on the
-       prototype: asking too early would fall through to the warning for an
-       element that is about to be perfectly capable. */
     if (trigger.localName.includes('-')) {
         ;
         trigger.expanded = open;

package/dist/utils/ticker/ticker.js

@@ -15,16 +15,6 @@ const ticker = () => {
     }
     return found;
 };
-/**
- * Replaces the ticker with an empty one on the given clock, and hands back the
- * way to put the real one back.
- *
- * **On `globalThis` with the rest of it, deliberately.** The spec bundler emits
- * one bundle per family and the runner loads them all into one page, so a
- * module-level clock would have the reach of one bundle while the timer it
- * schedules has the reach of the document. That is the fault the arrangement
- * above exists to avoid, and this must not reintroduce it.
- */
 export const withClock = (clock) => {
     const global = globalThis;
     const before = global[KEY];
@@ -33,7 +23,6 @@ export const withClock = (clock) => {
         global[KEY] = before;
     };
 };
-/** Sets the one timeout, for the soonest thing anybody is waiting on. */
 const schedule = () => {
     const held = ticker();
     if (held.timer !== undefined) {
@@ -44,14 +33,10 @@ const schedule = () => {
         return;
     }
     const soonest = Math.min(...[...held.waiting].map((one) => one.at));
-    /* Floored at a second: a subscriber handed a zero would be re-armed inside the
-       callback that fired it, which is a busy loop wearing a timer's clothes. */
     const wait = Math.max(1000, soonest - held.clock.now());
     held.timer = held.clock.setTimer(() => {
         held.timer = undefined;
         const now = held.clock.now();
-        /* Copied before iterating, because every callback re-subscribes and would
-           otherwise be walked again inside the same pass. */
         for (const one of [...held.waiting]) {
             if (one.at <= now) {
                 held.waiting.delete(one);
@@ -61,13 +46,6 @@ const schedule = () => {
         schedule();
     }, wait);
 };
-/**
- * Asks to be run in `delay` milliseconds, and returns the way to stop asking.
- *
- * The returned function is the whole of the contract: an element that forgets to
- * call it on disconnect leaks a closure over itself for the life of the page,
- * and a panel that opens and closes leaks one per open.
- */
 export const subscribe = (delay, run) => {
     const held = ticker();
     const entry = { at: held.clock.now() + delay, run };

package/dist/utils/tone-marks/tone-marks.js

@@ -1,32 +1,8 @@
 import { checkCircleFill, infoFill, warningFill, xCircleFill, } from '@fusion.dev/helix-icons';
-/**
- * The one status vocabulary.
- *
- * A reader meets these marks in a passage and in a message and has to read them
- * as the same four things, so there is one place they come from.
- *
- * **Filled at every tone**, or a set meant to be read as one vocabulary has a
- * member drawn a different way. Filled because a tone mark is a status
- * indicator and not an action: it wants to read at a glance and at a small
- * size, where an outline at this weight loses its interior.
- *
- * **The label is not the tone name.** `danger` is announced as "Error",
- * because that is the word a reader understands and `danger` is the word the API
- * uses. Both matter and they are not the same string.
- */
 export const TONE_MARKS = {
     danger: { icon: xCircleFill, label: 'Error' },
     info: { icon: infoFill, label: 'Information' },
     success: { icon: checkCircleFill, label: 'Success' },
     warning: { icon: warningFill, label: 'Warning' },
 };
-/**
- * The mark for a tone, or `undefined` where the name is not one of the four.
- *
- * A lookup rather than direct indexing, because `tone` reaches a component as an
- * attribute and an attribute can say anything, including the three tones that
- * have no mark. Callers decide what an unknown one means: `Callout` falls back
- * to `info`, since a callout is always *about* something, and `Toast.Item` draws
- * nothing, since a message is just the next thing that happened.
- */
 export const toneMark = (tone) => tone ? TONE_MARKS[tone] : undefined;

package/dist/utils/value-as/value-as.js

@@ -1,39 +1,6 @@
-/*
- * A date or time control's string value, read as the platform reads it.
- *
- * Shared, because six families hold three formats between them and separate
- * implementations of one conversion are chances to disagree about what an
- * invalid value returns. A pure function of a string, so it sits here beside
- * `formatNumbers` and `relativeTime` rather than under `helix/headless`.
- *
- * **UTC throughout, which is the platform's own choice and looks wrong until it
- * is explained.** `<input type="date">.valueAsDate` returns midnight UTC rather
- * than midnight local, so a date that is the same date everywhere does not
- * become a different one by crossing a timezone. Constructing through
- * `new Date('2026-08-26')` happens to do this and `new Date(2026, 7, 26)` does
- * not, and the difference is a whole day for anybody west of Greenwich: the
- * local constructor gives a `Date` whose UTC date is the 25th. `Date.UTC` says
- * which one is meant rather than relying on a parse rule.
- *
- * **Invalid is `null` and `NaN`, never a thrown error and never a guess.** That
- * is what the platform answers for a half-typed date, which is most of the
- * keystrokes a reader makes in one: a control that threw on the way to a valid
- * value would be unusable, and one that guessed would submit a date nobody
- * chose.
- */
-/** `YYYY-MM-DD`, and nothing that merely starts like it. */
 const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
-/** `HH:mm`, optionally with seconds, which is what a step under a minute produces. */
 const ISO_TIME = /^(\d{2}):(\d{2})(?::(\d{2}(?:\.\d{1,3})?))?$/;
-/** Milliseconds in one day, for a time value, which is an offset rather than an instant. */
 const DAY = 86_400_000;
-/**
- * The date a `YYYY-MM-DD` value names, at midnight UTC, or `null`.
- *
- * The range check is not decoration. `2026-02-31` matches the pattern and
- * `Date.UTC` rolls it forward to 3 March, so without reading the parts back a
- * control would report a date the reader never typed and never saw.
- */
 export const valueAsDate = (value) => {
     const parts = ISO_DATE.exec(value);
     if (!parts) {
@@ -44,20 +11,12 @@ export const valueAsDate = (value) => {
     const rolled = date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day;
     return rolled ? null : date;
 };
-/** The `YYYY-MM-DD` value for a date, or the empty string, which is how a control says nothing. */
 export const dateAsValue = (date) => {
     if (!date || Number.isNaN(date.getTime())) {
         return '';
     }
     return date.toISOString().slice(0, 10);
 };
-/**
- * The time an `HH:mm` value names, on 1 January 1970 UTC, or `null`.
- *
- * The platform's own answer for `<input type="time">`, and the epoch day is
- * what makes `valueAsNumber` come out as milliseconds since midnight rather
- * than as an instant nobody meant.
- */
 export const valueAsTime = (value) => {
     const parts = ISO_TIME.exec(value);
     if (!parts) {
@@ -70,13 +29,6 @@ export const valueAsTime = (value) => {
     }
     return new Date(Date.UTC(1970, 0, 1, hours, minutes, Math.floor(seconds), (seconds % 1) * 1000));
 };
-/**
- * The `HH:mm` value for a time, or the empty string.
- *
- * Seconds are written only where there are any, because `HH:mm` is what this
- * library's time controls hold and a trailing `:00` on every value would be a
- * format change dressed as a conversion.
- */
 export const timeAsValue = (date) => {
     if (!date || Number.isNaN(date.getTime())) {
         return '';
@@ -88,13 +40,5 @@ export const timeAsValue = (date) => {
     const hm = `${pad(clock.getUTCHours())}:${pad(clock.getUTCMinutes())}`;
     return seconds === 0 ? hm : `${hm}:${pad(clock.getUTCSeconds())}`;
 };
-/**
- * The number a value holds, or `NaN`.
- *
- * `Number('')` is zero, which is the trap: an empty control would report a
- * number it does not hold and a form would submit it. The platform answers
- * `NaN` for an empty `<input type="number">` and so does this.
- */
 export const valueAsNumber = (value) => value.trim() === '' ? Number.NaN : Number(value);
-/** The value for a number, or the empty string, which is how a control says nothing. */
 export const numberAsValue = (count) => (Number.isNaN(count) ? '' : String(count));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -26,19 +26,19 @@
   "sideEffects": false,
   "scripts": {
     "analyze": "cem analyze --config custom-elements-manifest.config.ts",
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.types.json",
     "test": "bun test src",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.1.0"
+    "@fusion.dev/helix-icons": "0.3.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.1.0",
-    "@fusion.dev/helix-testing": "0.1.0",
+    "@fusion.dev/helix-cem": "0.3.0",
+    "@fusion.dev/helix-testing": "0.3.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",