@motifx-community/ui 0.0.0-stage → 0.1.0-beta.0

package/dist/core/connect-i18n.d.ts

@@ -0,0 +1,11 @@
+import type { LocaleSource } from './locale-source';
+import type { UiLocale } from './UiLocale';
+/**
+ * Keeps the kit's language with the app's: the kit switches when the app's translations do (their
+ * `onLocaleChanged`), loading its own pack. Returns what stops it.
+ *
+ * @example
+ * const i18n = createI18n({ locale: 'tr', load: (l) => import(`./locales/${l}.json`) });
+ * connectI18n(i18n);
+ */
+export declare function connectI18n(source: LocaleSource, target?: UiLocale): () => void;

package/dist/core/container.d.ts

@@ -0,0 +1,52 @@
+import type { IBaseProp } from '@motifx/core';
+import { Control, type ControlProps } from './control';
+/**
+ * A control that remembers which control inside it is active and is a scope
+ * for Tab: forms, split panes, later tab pages and document windows.
+ *
+ * - `activeControl` follows focus inside it (a nested container counts as one
+ *   control and keeps its own `activeControl`). Assigning it focuses that control.
+ * - `restoreFocus()` puts focus back where it was the last time the container
+ *   was active: a form switching windows, a tab page coming back.
+ * - The outermost container of a page or window runs Tab order: controls with
+ *   a `tabIndex` go in ascending order, ties in document order. Until some
+ *   control inside sets a `tabIndex`, Tab is left to the browser. A container
+ *   that is a modal window (`cyclesTab`) keeps Tab inside itself.
+ *
+ * Cost: two listeners per container (focusin, keydown), none per control
+ * inside; Tab order is computed only on a Tab press that needs it.
+ */
+export declare class FocusContainer<TElement extends HTMLElement = HTMLElement, TProps extends ControlProps = ControlProps> extends Control<TElement, TProps> {
+    /** The element that had focus last inside this container. */
+    private lastFocused;
+    constructor(element: TElement | string, props?: IBaseProp<TProps>);
+    constructor(props?: IBaseProp<TProps>);
+    /**
+     * The control inside that has focus, or had it last (what
+     * `document.activeElement` is for the page). Reactive. Setting it focuses
+     * that control.
+     */
+    get activeControl(): Control | null;
+    set activeControl(control: Control | null);
+    /**
+     * Whether Tab wraps around inside this container instead of leaving it.
+     * `false` here; a modal window returns `true`.
+     */
+    protected get cyclesTab(): boolean;
+    /**
+     * Focuses what had focus last inside the container, else its active
+     * control, else the first control in Tab order. Returns `false` when
+     * nothing inside can take focus.
+     */
+    restoreFocus(): boolean;
+    private trackFocus;
+    /** The outermost container of its page or window runs Tab. */
+    private get runsTab();
+    private onTabKey;
+}
+/**
+ * The elements Tab visits in `root`: at each level of the control tree,
+ * siblings by ascending `tabIndex`, ties (and plain elements, index 0) in
+ * document order. One radio button per group, as browsers do.
+ */
+export declare function tabOrder(root: Element): HTMLElement[];

package/dist/core/control-map.d.ts

@@ -0,0 +1,7 @@
+import type { Control } from './control';
+/** @internal Called by every Control for its root element. */
+export declare function registerControl(element: Element, control: Control): void;
+/** The Control whose root element is `el`, if any. */
+export declare function controlOf(el: Element): Control | undefined;
+/** The nearest Control at or above `el`, not looking at `boundary` or above it. */
+export declare function closestControl(el: Element | null, boundary?: Element | null): Control | undefined;

package/dist/core/control-size.d.ts

@@ -0,0 +1,2 @@
+/** The height of a control, from the density tokens: `sm`, `md` or `lg`. */
+export type ControlSize = 'sm' | 'md' | 'lg';

package/dist/core/control.d.ts

@@ -0,0 +1,156 @@
+import { Component, type Bind, type IBaseProp } from '@motifx/core';
+import { type ShortcutHandler, type ShortcutOptions } from './keyboard';
+/** Props every {@link Control} understands. Each one is also a settable property. */
+export interface ControlProps {
+    /** The control's text (caption, label, title…); where it shows is up to the control. */
+    text?: Bind<string>;
+    /** `false` disables the control and everything inside it. Default `true`. */
+    enabled?: Bind<boolean>;
+    /** The HTML-style inverse of `enabled`, for habit: `disabled={() => state.busy}`. Ignored when `enabled` is given. */
+    disabled?: Bind<boolean>;
+    /** `false` hides the control (core `hide()`), `true` shows it again. Default `true`. */
+    visible?: Bind<boolean>;
+    /** `false` takes the control out of the Tab order; it can still be focused by code or click. Default `true`. */
+    tabStop?: Bind<boolean>;
+    /**
+     * Order among the controls of the same container: Tab visits them in
+     * ascending order, equal ones (default 0) in document order. Leave it unset
+     * where you can: document order is also the order screen readers read in.
+     */
+    tabIndex?: Bind<number>;
+}
+/**
+ * The base of every `@motifx-community/ui` control: the shared properties
+ * (`text`, `enabled`, `visible`, `tabStop`) work the same whether the control
+ * is written in JSX or created with `new` and changed from code.
+ *
+ * - A prop can be a value or a getter (`enabled={() => !state.busy}`); a
+ *   getter keeps the property in sync with the state.
+ * - Every property can be set from code, with a value (`ctrl.enabled = false`:
+ *   it replaces a getter given before, the code owns the value from then on) or
+ *   with a function (`ctrl.enabled = () => !state.busy`: bound and followed; over plain data, read again on
+ *   `reState()`).
+ * - Every property is reactive to read: `{() => ctrl.text}` or a watch follows it.
+ *
+ * Cost model: a property nobody set or bound costs nothing; a plain value is
+ * written to the DOM once; only a getter prop creates a binding; the change
+ * counter readers track is created on the first read.
+ *
+ * Subclasses render `text` (and their own properties built on the same
+ * storage) with {@link observeProperty}; the root element defaults to a div,
+ * set `static elementTag` for another.
+ */
+export declare class Control<TElement extends HTMLElement = HTMLElement, TProps extends ControlProps = ControlProps> extends Component<TElement, TProps> {
+    static elementTag: string;
+    /**
+     * All of the control's own state, on one symbol-keyed object created on
+     * first use. Not class fields: core calls `ref` callbacks from inside the
+     * base constructor, before field initializers run, and an initializer would
+     * then wipe whatever the ref did (a property set, a reader subscribed).
+     */
+    private get controlState();
+    constructor(element: TElement | string, props?: IBaseProp<TProps>);
+    constructor(props?: IBaseProp<TProps>);
+    /** The control's text (caption, label, title…). Reactive. */
+    get text(): string;
+    set text(value: Bind<string>);
+    /**
+     * This control's own value, as set or bound (like the HTML `disabled`
+     * attribute). Whether it can be used right now also depends on the controls
+     * it sits in: see {@link isEnabled}. Reactive.
+     */
+    get enabled(): boolean;
+    set enabled(value: Bind<boolean>);
+    /** The inverse of {@link enabled}, as in HTML. Reactive. */
+    get disabled(): boolean;
+    set disabled(value: Bind<boolean>);
+    /**
+     * Whether the control can be used now: enabled itself and in every control
+     * it sits in (like CSS `:enabled`; windows opened inside do not inherit it).
+     * Reactive.
+     */
+    get isEnabled(): boolean;
+    /** This control's own visibility (a hidden parent does not change it). Reactive. */
+    get visible(): boolean;
+    set visible(value: Bind<boolean>);
+    /** `false` takes the control out of the Tab order (see the prop). Reactive. */
+    get tabStop(): boolean;
+    set tabStop(value: Bind<boolean>);
+    /** See the prop. Reactive. */
+    get tabIndex(): number;
+    set tabIndex(value: Bind<number>);
+    /**
+     * The nearest ancestor that is a `Control`, not crossing a window (a window
+     * opened inside a disabled control is not disabled by it).
+     */
+    get parentControl(): Control | null;
+    /** The element that takes focus; the root by default. Composite controls override it. */
+    protected get focusElement(): HTMLElement;
+    /** Whether {@link focus} can succeed now: enabled, on the page, visible and focusable. */
+    get canFocus(): boolean;
+    /** Whether this control's focus element has focus. Not reactive (a DOM query). */
+    get focused(): boolean;
+    /** Whether focus is on this control or anything inside it (CSS `:focus-within`). Not reactive. */
+    get focusWithin(): boolean;
+    /** Focuses the control; `false` when it cannot take focus. */
+    focus(): boolean;
+    /**
+     * What the control's access key (`&Save` → Alt+S) does. Focuses it by
+     * default; a button-like control also clicks itself. Returns whether it did something.
+     */
+    onAccessKey(): boolean;
+    /**
+     * A keyboard shortcut active while focus is inside this control, removed
+     * when the control is disposed. See `addShortcut` for the chord syntax and
+     * the rules; returns the remover.
+     *
+     * @example
+     * this.addShortcut('Ctrl+S', () => this.save());
+     */
+    addShortcut(chord: string, handler: ShortcutHandler, options?: Omit<ShortcutOptions, 'scope'>): () => void;
+    /**
+     * Declares the control's access key (from a parsed `&Text`), or none with
+     * `null`: written to `aria-keyshortcuts` on the focus element, next to any
+     * shortcuts the app put there. Subclasses that render `text` call this.
+     */
+    protected setAccessKey(key: string | null): void;
+    /** Reads a property, tracked: reactive readers update when it changes. */
+    protected getProperty<T>(name: string): T;
+    /** Sets a property from code: replaces a getter prop bound to it, then stores and renders. */
+    protected setProperty(name: string, value: unknown): void;
+    /** Stores a value the user entered; a bound getter is kept. */
+    protected changeProperty(name: string, value: unknown): void;
+    /**
+     * What a property setter does: a value is set (`setProperty`), a function is bound in place of
+     * whatever was there (`bindProperty`) and followed. `normalize` shapes the value either way.
+     */
+    protected assignProperty<T>(name: string, value: Bind<T>, normalize?: (value: T) => unknown): void;
+    /**
+     * Binds a property to a prop: a getter is read now and followed by a component binding, so it follows reactive
+     * data by itself and plain data on `reState()`. A plain value is stored once. Subclasses call
+     * this for their own properties, typically from the constructor.
+     */
+    protected bindProperty(name: string, prop: Bind<unknown>): void;
+    private unbind;
+    /**
+     * Renders a property without an effect: `apply` runs now with the current
+     * value and again on every change, whether it comes from a getter prop or
+     * from code. E.g. `this.observeProperty('text', (t) => (label.data = t))`.
+     */
+    protected observeProperty<T>(name: string, apply: (value: T) => void): void;
+    private slot;
+    private store;
+    /**
+     * Renders a property that changed (from a prop, a bound getter or code).
+     * Override it to render your own properties without an effect, and call
+     * `super.applyProperty` for the rest. It can run from the constructor
+     * (props are bound there), before subclass fields exist: touch only
+     * `this.element` and the property storage.
+     */
+    protected applyProperty(name: string, value: unknown): void;
+    /** A property's current value without tracking it. */
+    protected peekProperty<T>(name: string): T | undefined;
+    private applyEnabled;
+    private applyVisible;
+    private applyTabStop;
+}

package/dist/core/document-watch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Calls `moved` (after a microtask) whenever nodes are added to or taken from a connected
+ * document: some may have moved between windows. Returns the function that stops it.
+ */
+export declare function onNodesMoved(moved: () => void): () => void;
+/**
+ * Calls `changed` with the new document once `element` is in another one than before (moved into
+ * a window the app opened, or back). Returns the function that stops watching.
+ */
+export declare function watchDocument(element: Element, changed: (doc: Document) => void): () => void;

package/dist/core/draw-parts.d.ts

@@ -0,0 +1,36 @@
+import { Component, type ComponentBase } from '@motifx/core';
+import type { IconSource } from './icon-source';
+/** A mark written as `"true"`, or taken away. */
+export declare function flag(el: HTMLElement, name: string, on: unknown): void;
+/** An attribute there with no value, or taken away. */
+export declare function mark(el: HTMLElement, name: string, on: unknown): void;
+/** An attribute written as it is, or taken away when there is none. */
+export declare function put(el: HTMLElement, name: string, value: string | null | undefined): void;
+/** A style property (a custom one too); `''` takes it away. */
+export declare function css(el: HTMLElement, name: string, value: string): void;
+/** The text of a part that holds only text. */
+export declare function text(el: HTMLElement, value: string): void;
+/** Shown or not: `hidden` for what reads it, and `display: none` as well, since a part's own rules give it a display. */
+export declare function shown(el: HTMLElement | null, on: boolean): void;
+/** A part drawn by hand: a MotifJS component of a tag and a class, added to `parent`. */
+export declare function part<E extends HTMLElement = HTMLElement>(parent: ComponentBase, tag: string, className: string): Component<E>;
+/** A glyph of the kit's set (`span.mx-glyph`, see `glyph`) as a part of `parent`. */
+export declare function glyphPart(parent: ComponentBase, name: string, className?: string): Component<HTMLSpanElement>;
+/**
+ * An icon as a child of `parent`: an `<img>` for an address (`alt` empty unless given), an element of your own
+ * taken in as a component, or the component itself. It goes with `parent`; dispose the one returned when the
+ * icon changes.
+ */
+export declare function iconPart(parent: ComponentBase, source: IconSource, alt?: string): ComponentBase;
+/**
+ * In the page or not, in its place: taken out, a placeholder keeps its place, and it comes back there. For a part
+ * whose parent is not changed while it is out (what `x-display` does for JSX).
+ */
+export declare function kept(el: HTMLElement, on: boolean): void;
+/**
+ * The value of a control the user changes too (a box, a list, a check box): given only when it is not the one given
+ * last, so what the user typed or picked since stays until the value itself changes.
+ */
+export declare function handOver<V>(control: {
+    value: V;
+}, value: V): void;

package/dist/core/enable.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Disables `root` and everything inside it except windows (<dialog>) opened
+ * within it: native controls get `disabled`, other focusable elements leave
+ * the tab order with `aria-disabled`, and pointer input is swallowed. Content
+ * added later is disabled too. If focus was inside, it moves to the next
+ * usable element instead of falling to <body>. Returns the function that
+ * undoes exactly this call; other disabled roots still covering an element
+ * keep it disabled.
+ */
+export declare function disableSubtree(root: HTMLElement): () => void;
+/**
+ * Where focus goes when `area` stops being usable while it holds focus: the
+ * next tabbable element after it in the same window (or page), else the one
+ * before it. `null` when focus is not inside `area` or nothing else is usable.
+ */
+export declare function rescueTarget(area: Element): HTMLElement | null;

package/dist/core/every.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs `fn` every `ms`, in a promise. The next run is set only when one has ended, so slow work never piles
+ * up runs behind it (a timer that repeats on its own would). Returns what stops it.
+ */
+export declare function every(fn: () => void, ms: number): () => void;

package/dist/core/fill-template.d.ts

@@ -0,0 +1,2 @@
+/** `fillTemplate('At least {min}', { min: 3 })` → `At least 3` */
+export declare function fillTemplate(template: string, values: Record<string, unknown>): string;

package/dist/core/fill-text.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A text of the kit with its values, in ICU: `{name}`, `{count, number}`,
+ * `{count, plural, one {# row} other {# rows}}`, numbers written the way of `locale`. A text that is not valid ICU
+ * (an app's own) is filled as plain `{name}` parts.
+ */
+export declare function fillText(message: string, locale: string, values?: Record<string, unknown>): string;

package/dist/core/focus-guard.d.ts

@@ -0,0 +1,2 @@
+/** Installs the guard in every document of the page; every Control calls this, only the first one does anything. */
+export declare function installFocusGuard(): void;

package/dist/core/focus.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The element that really has focus, descending through open shadow roots
+ * (inside a shadow tree `document.activeElement` is only the host). In the
+ * document of `near` when given; else in the page's document, or in the
+ * connected window (see `connectDocument`) focus went to last.
+ */
+export declare function deepActiveElement(near?: Node | null): HTMLElement | null;
+/** Rendered and not hidden by CSS (`display`, `visibility`, `content-visibility`); true where the API is missing. */
+export declare function isShown(el: Element): boolean;
+/** Focusable elements under `root` in document order, skipping hidden, inert and CSS-hidden ones. */
+export declare function focusableIn(root: Element): HTMLElement[];
+/**
+ * The elements Tab visits under `root`, in document order: focusable, not
+ * `tabindex="-1"`, and not inside another window (<dialog>) nested in `root`.
+ */
+export declare function tabbableIn(root: Element): HTMLElement[];
+/**
+ * The first tabbable element of `scope` after `anchor` in document order
+ * (before it when `forward` is false), skipping `anchor`'s own subtree.
+ */
+export declare function nextTabbable(anchor: Node, scope: Element, forward?: boolean): HTMLElement | null;
+/**
+ * Whether `el` can take focus at all (by Tab or programmatically): a
+ * focusable kind of element, or any `tabindex` including -1, and not
+ * disabled, hidden or inert.
+ */
+export declare function isFocusable(el: Element): boolean;
+/**
+ * Moves focus to the first `[autofocus]` element under `root`, else the first
+ * focusable one. Returns `false` when there is nothing to focus.
+ */
+export declare function focusInitial(root: Element): boolean;

package/dist/core/follow.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentBase } from '@motifx/core';
+/**
+ * Follows `read` with one of `component`'s bindings and hands each value to `write`: now, then by itself when `read`
+ * reads reactive data, and again on the component's `reState()` (plain data), each time the value is not the one
+ * handed last. Returns what stops it.
+ */
+export declare function follow<T>(component: ComponentBase, name: string, read: () => T, write: (value: T) => void): () => void;

package/dist/core/function-value.d.ts

@@ -0,0 +1,6 @@
+import type { Bind } from '@motifx/core';
+/**
+ * For props whose value is itself a function (a field reader, a template): a function that takes
+ * arguments is the value; one without arguments is a getter, followed like any other.
+ */
+export declare function functionValue<F>(value: Bind<F>): Bind<F>;

package/dist/core/given-field.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A field of an object the developer gave. Their object may be reactive or plain and the kit counts on neither, so
+ * the field is read untracked: a change to it reaches the kit through the component's refresh, the same for both. A
+ * function there is their own live value (a `Bind`): it is called, and what it reads is followed.
+ *
+ * Only for fields that are values or `Bind`s; a callback (`click`, `calculate…`) is read with `givenValue`.
+ */
+export declare function givenField<V = unknown>(owner: unknown, key: PropertyKey): V;
+/** A field of an object the developer gave, as it is (a function stays a function), read untracked. */
+export declare function givenValue<V = unknown>(owner: unknown, key: PropertyKey): V;
+/** A list the developer gave, walked without following it: its items as they are, a change through the refresh. */
+export declare function givenList<T>(list: readonly T[] | null | undefined): T[];

package/dist/core/glyphs.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The kit's glyphs, by name: each is a `span.mx-glyph` that CSS draws (a mask of `--mx-icon-<name>`
+ * in the text colour). A design language brings its own set as tokens (`tokens/icons/<language>.icons.json`)
+ * and nothing here changes; the names and the kit's own drawings are in `tokens/icons/kit.icons.json`.
+ */
+export declare function glyph(name: string): HTMLSpanElement;
+/** The arrow of a control that opens something below it. */
+export declare const chevronDown: () => HTMLSpanElement;
+/** The mark of a checked item. */
+export declare const checkMark: () => HTMLSpanElement;
+export declare const chevronUp: () => HTMLSpanElement;
+export declare const dismissMark: () => HTMLSpanElement;
+export declare const eyeOpen: () => HTMLSpanElement;
+export declare const eyeClosed: () => HTMLSpanElement;
+export declare const infoMark: () => HTMLSpanElement;
+export declare const successMark: () => HTMLSpanElement;
+export declare const cautionMark: () => HTMLSpanElement;
+export declare const dangerMark: () => HTMLSpanElement;
+/** The mark of a checkbox that is neither checked nor unchecked. */
+export declare const dashMark: () => HTMLSpanElement;
+export declare const plusMark: () => HTMLSpanElement;
+export declare const calendarMark: () => HTMLSpanElement;
+export declare const clockMark: () => HTMLSpanElement;
+/** The mark of the chosen item of a group. */
+export declare const radioMark: () => HTMLSpanElement;
+/** Three dots: more commands. */
+export declare const moreMark: () => HTMLSpanElement;
+/** The arrow of a branch that opens towards the end (mirrored right to left by CSS). */
+export declare const chevronEnd: () => HTMLSpanElement;
+/** The arrow towards the start: back, earlier (mirrored right to left by CSS). */
+export declare const chevronStart: () => HTMLSpanElement;
+/** A window filling the screen. */
+export declare const maximizeMark: () => HTMLSpanElement;
+/** A window back to its own size. */
+export declare const restoreMark: () => HTMLSpanElement;
+/** A frame cut in two side by side: split. */
+export declare const splitMark: () => HTMLSpanElement;
+/** A window folded away. */
+export declare const minimizeMark: () => HTMLSpanElement;
+/** A funnel: filter by values. */
+export declare const filterMark: () => HTMLSpanElement;
+/** Edit. */
+export declare const pencilMark: () => HTMLSpanElement;
+/** Delete. */
+export declare const trashMark: () => HTMLSpanElement;
+/** Take back. */
+export declare const undoMark: () => HTMLSpanElement;
+/** Save to a file. */
+export declare const downloadMark: () => HTMLSpanElement;
+/** Keep the changes (a disk). */
+export declare const saveMark: () => HTMLSpanElement;
+/** The list of columns. */
+export declare const columnsMark: () => HTMLSpanElement;
+/** Look for something. */
+export declare const searchMark: () => HTMLSpanElement;
+/** A pushpin: a tab kept at the start. */
+export declare const pinMark: () => HTMLSpanElement;
+/** A padlock: closed to new things. */
+export declare const lockMark: () => HTMLSpanElement;
+/** A head and shoulders: someone with no picture or name to show. */
+export declare const personMark: () => HTMLSpanElement;
+/** Two columns of dots: something to take hold of and drag. */
+export declare const gripMark: () => HTMLSpanElement;
+/** A dock guide: a window with the part a drop there would take marked. */
+export declare const dockGuideMark: (side: 'center' | 'left' | 'right' | 'up' | 'down') => HTMLSpanElement;
+/** Two columns of three dots: a row to take hold of and drag. */
+export declare const dragDots: () => HTMLSpanElement;

package/dist/core/icon-node.d.ts

@@ -0,0 +1,10 @@
+import type { IconSource } from './icon-source';
+/**
+ * The node that shows an icon: an `<img>` for an address, the element itself, or the built element
+ * of a component. `release` disposes a component when the icon goes away. `doc`: the document
+ * the `<img>` is made in, the page's by default.
+ */
+export declare function iconNode(source: IconSource, doc?: Document): {
+    node: Node;
+    release: () => void;
+};

package/dist/core/icon-source.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentBase } from '@motifx/core';
+/** An icon: an image address, or any element or component (an `<svg>` written in JSX, an icon font tag). */
+export type IconSource = string | Node | ComponentBase;

package/dist/core/input-mode.d.ts

@@ -0,0 +1,2 @@
+/** The keyboard a touch device shows for a field. */
+export type InputMode = 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';

package/dist/core/keyboard.d.ts

@@ -0,0 +1,55 @@
+import type { ComponentBase } from '@motifx/core';
+/** What `addShortcut` takes besides the chord and the handler. */
+export interface ShortcutOptions {
+    /**
+     * Only while focus is inside this component (and it is enabled). Without
+     * it the shortcut is app-wide.
+     */
+    scope?: ComponentBase;
+    /**
+     * Also when focus is in a text field. By default a chord without Ctrl, Alt
+     * or Meta (Delete, a letter, Escape…) leaves text fields alone; F-keys and
+     * chords with those modifiers always work.
+     */
+    inEditable?: boolean;
+}
+/** Return `false` from a handler to let the key go on (to a less specific shortcut, then the page). */
+export type ShortcutHandler = (e: KeyboardEvent) => void | boolean;
+interface Chord {
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    /** Lower-case `KeyboardEvent.key`, or a single lower-case character. */
+    key: string;
+}
+/**
+ * Parses `'Ctrl+S'`, `'Mod+Shift+P'`, `'F2'`, `'Alt+ArrowUp'`. Modifiers:
+ * Ctrl (Control), Alt (Option), Shift, Meta (Cmd, Win) and Mod (Cmd on
+ * Apple platforms, Ctrl elsewhere). Case does not matter.
+ */
+export declare function parseChord(text: string): Chord;
+/** Parses one chord or chords one after the other, split by spaces: `'Ctrl+K W'`. */
+export declare function parseShortcut(text: string): Chord[];
+/**
+ * Registers a keyboard shortcut. App-wide by default (except while a modal
+ * form is open, and except plain keys while focus is in a window); with
+ * `scope`, only while focus is inside that component. Returns the function
+ * that removes it. `Control.addShortcut` does the same and removes it when the
+ * control is disposed. Two chords split by a space are pressed one after the
+ * other (`'Ctrl+K W'`).
+ *
+ * @example
+ * const remove = addShortcut('Ctrl+S', () => model.save());
+ * addShortcut('Delete', () => grid.deleteSelected(), { scope: grid });
+ * addShortcut('Ctrl+K Ctrl+W', () => docs.closeAll());
+ */
+export declare function addShortcut(chord: string, handler: ShortcutHandler, options?: ShortcutOptions): () => void;
+/**
+ * Whether a key event is one of the chords (`'Shift+Tab'`, `'Ctrl+Alt+ArrowLeft'`), as a shortcut
+ * would match it. For keys a component reads itself while a mode of its own is on.
+ */
+export declare function isChord(chords: readonly string[], e: KeyboardEvent): boolean;
+/** @internal Installs the document listener (once). Access keys call it when they first appear. */
+export declare function installKeyboard(): void;
+export {};

package/dist/core/language-look.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What the design language decides for a control that is not told: keywords read from the control's
+ * slots on its own element (`--_button-variant: ghost`), so the place a control sits in can decide them
+ * too (a toolbar's buttons, a list's search box). Read once the control is in the page and again when
+ * the language, theme or density changes; `changed` runs when a value differs.
+ */
+export declare class LanguageLook<K extends string> {
+    private readonly element;
+    private readonly tokens;
+    private readonly changed;
+    private readonly values;
+    constructor(element: Element, tokens: Record<K, string>, changed: () => void);
+    /** The language's keyword, or null before it is read or when the token is not there. */
+    get(name: K): string | null;
+    read(): void;
+    /** Reads again on every change of language, theme or density; returns the function that stops it. */
+    watch(): () => void;
+}

package/dist/core/later.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Runs `fn` once after `ms`, in a promise: the timer itself only hands the work on. Returns what stops it.
+ */
+export declare function later(fn: () => void, ms?: number): () => void;

package/dist/core/locale-source.d.ts

@@ -0,0 +1,9 @@
+/** What `connectI18n` needs of an app's translations (`@motifx-community/i18n`): the locale, and the event of a change. */
+export interface LocaleSource {
+    readonly locale: string;
+    readonly onLocaleChanged: (listener: (e: {
+        locale: string;
+    }) => unknown) => {
+        dispose(): void;
+    };
+}

package/dist/core/look-watch.d.ts

@@ -0,0 +1,2 @@
+/** Calls `changed` (once per microtask) after a design language, theme or density changes anywhere. Returns the function that stops it. */
+export declare function onLookChanged(changed: () => void): () => void;

package/dist/core/mirror-page.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Gives `target` (the document of a window the app opened) the look of `source`, the page: its
+ * style sheets (`<link rel="stylesheet">`, `<style>` and constructed sheets) and the attributes
+ * of `<html>` and `<body>` the design system reads (`data-theme`, `data-identity`, density, `dir`,
+ * `lang`, classes, inline style). It keeps watching: a sheet added, changed or removed later (a
+ * dev server does that), or a theme changed, shows in `target` too. Returns the function that
+ * stops watching.
+ */
+export declare function mirrorPage(source: Document, target: Document): () => void;

package/dist/core/next-frame.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs `fn` at the next frame of `view` (the window the work is drawn in; the page's by default), in a promise:
+ * the frame itself stays short, the work runs right after it, before the screen is drawn. Where the window has
+ * no frames (a test, a window being closed), it runs after a frame's time. Returns what stops it.
+ */
+export declare function nextFrame(fn: () => void, view?: Window | null): () => void;

package/dist/core/next-id.d.ts

@@ -0,0 +1 @@
+export declare function nextId(prefix: string): string;

package/dist/core/node-kind.d.ts

@@ -0,0 +1,10 @@
+/** Whether `value` is a DOM node, of this window or another. */
+export declare function isNode(value: unknown): value is Node;
+/** Whether `value` is an element, of this window or another. */
+export declare function isElement(value: unknown): value is Element;
+/** Whether `value` is an HTML element (not an SVG one), of this window or another. */
+export declare function isHtmlElement(value: unknown): value is HTMLElement;
+/** Whether `value` is a document, of this window or another. */
+export declare function isDocument(value: unknown): value is Document;
+/** The document a node is in (a document is its own). */
+export declare function documentOf(node: Node): Document;

package/dist/core/on-language.d.ts

@@ -0,0 +1,9 @@
+import { type ComponentBase } from '@motifx/core';
+/**
+ * Runs `draw` now, then again each time the kit's language changes (`uiLocale.onChanged`), while `component` lives:
+ * how a control writes its texts and formats without following anything. Returns what stops it sooner.
+ *
+ * @example
+ * onLanguage(this, () => button.setAttribute('aria-label', uiLocale.strings.close));
+ */
+export declare function onLanguage(component: ComponentBase, draw: () => void): () => void;

package/dist/core/on-re-state.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentBase } from '@motifx/core';
+/**
+ * Runs `run` whenever `component.reState()` (or one of a component it sits in) is called: one of its bindings that
+ * does nothing but that. For a component that reads what it was given through models of its own. Returns what stops it.
+ */
+export declare function onReState(component: ComponentBase, run: () => void): () => void;