@fusion.dev/helix-core 0.146.0 → 0.148.0

package/dist/utils/scroll-item-into-view/scroll-item-into-view.d.ts

@@ -7,4 +7,54 @@ export interface ScrollItemOptions {
     /** Whether to animate. Ignored where the reader asked for less motion. */
     smooth?: boolean;
 }
+/**
+ * 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.
+ */
+export declare const scrollingAncestor: (item: HTMLElement, options?: ScrollerOptions) => HTMLElement | null;
+/** What `scrollRoom` takes off a box that scrolls. */
+export interface ScrollRoomOptions {
+    /**
+     * How much of the box its own content covers while it scrolls, a sticky row
+     * of headings, in pixels. Defaults to `0`.
+     */
+    covered?: number;
+}
+/**
+ * How much of a list a reader sees at once, for Page Up and Page Down: the
+ * box's own height where it scrolls, less what covers it, and the window's
+ * where it does not and the page scrolls instead.
+ *
+ * **A pixel of slack**, since a box whose content rounds to one pixel more
+ * than its height does not scroll, and was paging by the window's height.
+ */
+export declare const scrollRoom: (box: Element | null | undefined, { covered }?: ScrollRoomOptions) => number;
+/** Where `scrollingAncestor` looks, and what it takes for a scroller. */
+export interface ScrollerOptions {
+    /** The axis whose overflow counts, or either where absent. */
+    readonly axis?: 'x' | 'y';
+    /**
+     * Only a box whose content is larger than it, along `axis`: one that can
+     * scroll now, rather than one that would once it fills. Outline asks this of
+     * the box its links and its sections scroll in.
+     */
+    readonly overflowing?: boolean;
+    /** Where the walk stops, unread: the document's body where absent. */
+    readonly stop?: Element | null;
+}
 export declare const scrollItemIntoView: (item: HTMLElement, options?: ScrollItemOptions) => void;

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

@@ -1,15 +1,26 @@
-const scrollingAncestor = (item) => {
-    const stop = item.ownerDocument.body;
+export const scrollingAncestor = (item, options = {}) => {
+    const { axis, overflowing = false, stop = item.ownerDocument.body } = options;
     let node = climb(item);
     while (node && node !== stop) {
         const style = getComputedStyle(node);
-        if (/\b(auto|scroll|overlay)\b/.test(`${style.overflowX} ${style.overflowY}`)) {
+        const overflow = axis === 'x'
+            ? style.overflowX
+            : axis === 'y'
+                ? style.overflowY
+                : `${style.overflowX} ${style.overflowY}`;
+        if (/\b(auto|scroll|overlay)\b/.test(overflow) && (!overflowing || overflows(node, axis))) {
             return node;
         }
         node = climb(node);
     }
     return null;
 };
+export const scrollRoom = (box, { covered = 0 } = {}) => box && box.scrollHeight > box.clientHeight + 1 ? box.clientHeight - covered : window.innerHeight;
+const overflows = (node, axis) => {
+    const tall = node.scrollHeight > node.clientHeight;
+    const wide = node.scrollWidth > node.clientWidth;
+    return axis === 'x' ? wide : axis === 'y' ? tall : tall || wide;
+};
 const climb = (node) => {
     if (node.parentElement) {
         return node.parentElement;

package/dist/utils/slot-filled/slot-filled.d.ts

@@ -22,3 +22,11 @@
  * anything", and a slot showing its fallback does render.
  */
 export declare const slotFilled: (slot: HTMLSlotElement | null | undefined) => boolean;
+/**
+ * The slot of a name in a shadow root, or its default slot for `''`.
+ *
+ * `slot[name=""]` matches nothing, since the default slot has no `name`
+ * attribute at all, which is the one thing every hand-written lookup had to
+ * remember.
+ */
+export declare const slotNamed: (root: ParentNode | null | undefined, name: string) => HTMLSlotElement | null;

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

@@ -1 +1,2 @@
 export const slotFilled = (slot) => (slot?.assignedNodes({ flatten: true }) ?? []).some((node) => node.nodeType === Node.ELEMENT_NODE || node.textContent?.trim() !== '');
+export const slotNamed = (root, name) => root?.querySelector?.(name === '' ? 'slot:not([name])' : `slot[name="${name}"]`) ?? null;

package/dist/utils/slotted-glyph/slotted-glyph.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A glyph a consumer slots once and a component draws in many places: the
+ * marks of a rating, the remove icon on every row of a file list.
+ *
+ * A slotted element can be assigned to one slot only, so a component that
+ * draws it in several places draws copies. **One copy per place, kept**, so a
+ * render does not make them again: a drag renders on every pointer move, and
+ * handing Lit a fresh node each time swaps every copy on every frame.
+ */
+export declare class SlottedGlyph {
+    /** The copies made so far, by the place each is drawn in. */
+    private readonly copies;
+    /** The element slotted last, which every copy is made from. */
+    private source;
+    /** Whether a glyph is slotted, so the component draws copies of it. */
+    get slotted(): boolean;
+    /**
+     * Reads the slot after a `slotchange`: the first element assigned to it,
+     * through any slot it is forwarded by. The copies made of the last one go.
+     */
+    read(slot: HTMLSlotElement): void;
+    /**
+     * Takes `source` as the glyph, or none, as `read` does from a slot: the
+     * copies made of the last one go. For the first render, which reads the
+     * host's children before any `slotchange` answers.
+     */
+    take(source: Element | undefined): void;
+    /**
+     * The copy for one place, made the first time it is asked for and the same
+     * node after, or `undefined` while nothing is slotted.
+     */
+    copyFor(place: number | string): Node | undefined;
+}

package/dist/utils/slotted-glyph/slotted-glyph.js

@@ -0,0 +1,27 @@
+export class SlottedGlyph {
+    constructor() {
+        this.copies = new Map();
+    }
+    get slotted() {
+        return this.source !== undefined;
+    }
+    read(slot) {
+        this.take(slot.assignedElements({ flatten: true })[0]);
+    }
+    take(source) {
+        this.source = source;
+        this.copies.clear();
+    }
+    copyFor(place) {
+        if (!this.source) {
+            return undefined;
+        }
+        const key = String(place);
+        let copy = this.copies.get(key);
+        if (!copy) {
+            copy = this.source.cloneNode(true);
+            this.copies.set(key, copy);
+        }
+        return copy;
+    }
+}

package/dist/utils/toolbar-around/toolbar-around.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The toolbar an element sits in, or `null`.
+ *
+ * Read from the parent up, so a toolbar is never its own. One answer for every
+ * family that changes inside a toolbar: Toolbar becomes a group of the outer
+ * one, a multiple Toggle Group becomes a group, and Divider turns across the
+ * toolbar's axis. By tag and by role, since a family other than Toolbar cannot
+ * import Toolbar's class; Toolbar adds its own class for a third tag.
+ *
+ * `closest` stops at a shadow root, which is what a slotted child wants: its
+ * toolbar is its light-DOM parent or above.
+ */
+export declare const toolbarAround: (element: Element) => Element | null;
+/**
+ * The axis a toolbar runs along: its own `orientation`, else the page's
+ * `aria-orientation`, else horizontal, which is the role's default.
+ */
+export declare const toolbarAxis: (toolbar: Element) => 'horizontal' | 'vertical';

package/dist/utils/toolbar-around/toolbar-around.js

@@ -0,0 +1,5 @@
+const TOOLBAR = '[role="toolbar"], helix-toolbar, helix-headless-toolbar';
+export const toolbarAround = (element) => element.parentElement?.closest(TOOLBAR) ?? null;
+export const toolbarAxis = (toolbar) => (toolbar.getAttribute('orientation') ?? toolbar.getAttribute('aria-orientation')) === 'vertical'
+    ? 'vertical'
+    : 'horizontal';

package/dist/utils/typeahead/typeahead.d.ts

@@ -65,3 +65,11 @@ export interface TypeaheadBy<Item> {
  * `TypeaheadBy`.
  */
 export declare const typeaheadBy: <Item>(words: (item: Item) => string) => TypeaheadBy<Item>;
+/**
+ * Turns on typeahead for a set whose items carry their own `words`, as List's
+ * rows, Tag Group's tags and Drilldown's items do. An item with none is
+ * passed over.
+ */
+export declare const typeaheadByWords: () => TypeaheadBy<{
+    readonly words?: string;
+}>;

package/dist/utils/typeahead/typeahead.js

@@ -34,3 +34,4 @@ export const typeaheadBy = (words) => ({
     search: new Typeahead(),
     words,
 });
+export const typeaheadByWords = () => typeaheadBy((item) => item.words ?? '');

package/dist/utils/verdict-flags/verdict-flags.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What a picker field finds wrong: a message, reported as `badInput`, or the
+ * validity flag to set and its message. Empty means nothing is wrong.
+ */
+export type PickerVerdict = string | readonly [flag: keyof ValidityStateFlags, message: string];
+/**
+ * A verdict as the flags and the message `setValidity` takes, or `null` where
+ * there is nothing wrong.
+ *
+ * Shared by `MixinPickerField` and `MixinSegmentedField`, the two shapes a
+ * date, time or color field takes, which report the same verdicts.
+ */
+export declare const verdictFlags: (verdict: PickerVerdict) => [flags: ValidityStateFlags, message: string] | null;

package/dist/utils/verdict-flags/verdict-flags.js

@@ -0,0 +1,6 @@
+export const verdictFlags = (verdict) => {
+    if (typeof verdict === 'string') {
+        return verdict === '' ? null : [{ badInput: true }, verdict];
+    }
+    return [{ [verdict[0]]: true }, verdict[1]];
+};

package/dist/utils/written-list/written-list.d.ts

@@ -71,6 +71,37 @@ export declare const toggleValue: (list: readonly string[], value: string, order
  * follows.
  */
 export declare const toggleEvery: (chosen: Iterable<string>, values: readonly string[], order?: readonly string[]) => string[];
+/**
+ * What a select-all box shows for `values`: checked when every one is
+ * chosen, mixed when some are, and neither for none or an empty set.
+ *
+ * Checkbox Group's select-all box and the header boxes of Table and Data
+ * Table each worked this out. A set that does not count its disabled boxes
+ * passes only the enabled values.
+ */
+export declare const everyState: (chosen: Iterable<string>, values: readonly string[]) => {
+    checked: boolean;
+    indeterminate: boolean;
+};
+/**
+ * `keys` in the order the rows are, which is `order`: the keys of the whole
+ * set. A key the set does not hold, a selected row a search has hidden say,
+ * keeps its place after them in the order it was given.
+ *
+ * So a selection reads in row order whatever order its rows were chosen in:
+ * Data Table's, and Table's and Virtual List's, which wrote it in press order
+ * or wrote this again.
+ */
+export declare const inRowOrder: (keys: Iterable<string>, order: readonly string[]) => string[];
+/**
+ * Where a Shift range runs from, as an index into `keys`: the row last chosen
+ * while it is among them, and otherwise the row the reader is on, `from`,
+ * which becomes the one to run from.
+ */
+export declare const anchorAt: (keys: readonly string[], anchorKey: string | undefined, from: number) => {
+    anchor: number;
+    anchorKey: string | undefined;
+};
 /** How many items a set lets a reader select: Tag Group's and List's `selection-mode`. */
 export type SelectionMode = 'multiple' | 'none' | 'single';
 /**

package/dist/utils/written-list/written-list.js

@@ -25,6 +25,22 @@ export const toggleEvery = (chosen, values, order) => {
     }
     return order ? order.filter((value) => next.has(value)) : [...next];
 };
+export const everyState = (chosen, values) => {
+    const held = new Set(chosen);
+    const count = values.filter((value) => held.has(value)).length;
+    const checked = values.length > 0 && count === values.length;
+    return { checked, indeterminate: count > 0 && !checked };
+};
+export const inRowOrder = (keys, order) => {
+    const wanted = new Set(keys);
+    const placed = order.filter((key) => wanted.has(key));
+    const seen = new Set(placed);
+    return [...placed, ...[...wanted].filter((key) => !seen.has(key))];
+};
+export const anchorAt = (keys, anchorKey, from) => {
+    const anchor = anchorKey === undefined ? -1 : keys.indexOf(anchorKey);
+    return anchor < 0 ? { anchor: from, anchorKey: keys[from] } : { anchor, anchorKey };
+};
 export const pressedValue = (mode, value, pressed) => {
     const now = commaList(value);
     if (mode === 'single') {

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.146.0";
+export declare const VERSION = "0.148.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.146.0';
+export const VERSION = '0.148.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.146.0",
+  "version": "0.148.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,11 +34,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.146.0"
+    "@fusion.dev/helix-icons": "0.148.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.146.0",
-    "@fusion.dev/helix-testing": "0.146.0",
+    "@fusion.dev/helix-cem": "0.148.0",
+    "@fusion.dev/helix-testing": "0.148.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },
@@ -54,6 +54,17 @@
       "development": "./dist/utils/audit-name/audit-name.js",
       "helix-development": "./dist/utils/audit-name/audit-name.js",
       "default": "./dist/utils/audit-name/audit-name-off.js"
+    },
+    "#audit-source": {
+      "helix-source": {
+        "development": "./src/utils/audit-source/audit-source.ts",
+        "helix-development": "./src/utils/audit-source/audit-source.ts",
+        "default": "./src/utils/audit-source/audit-source-off.ts"
+      },
+      "types": "./dist/utils/audit-source/audit-source.d.ts",
+      "development": "./dist/utils/audit-source/audit-source.js",
+      "helix-development": "./dist/utils/audit-source/audit-source.js",
+      "default": "./dist/utils/audit-source/audit-source-off.js"
     }
   },
   "keywords": [