@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/lib/markdown/reconcile.d.ts

@@ -0,0 +1,63 @@
+import type { PNode } from "./project";
+/**
+ * Thrown when a patch would have had to disturb the node the browser is
+ * composing into.
+ *
+ * Loud rather than silent because the caller's contract is to DEFER the patch
+ * until `compositionend`, and a reconciler that quietly skipped the change
+ * would leave the DOM disagreeing with the model — which is the same corruption
+ * one step later, with nothing pointing at the cause.
+ */
+export declare class CompositionConflictError extends Error {
+    constructor(message: string);
+}
+export interface PatchOptions {
+    /**
+     * The text node the browser is composing into. Never written, moved or
+     * removed; a patch that would need to do any of those throws.
+     */
+    protect?: Text | null;
+}
+export interface PatchStats {
+    /** Text nodes whose `data` was assigned. */
+    textUpdated: number;
+    /** Text nodes left alone because their data already matched. */
+    textUntouched: number;
+    /** Elements reused in place. */
+    elementsReused: number;
+    /** Nodes created, which is the number the caret can be disturbed by. */
+    created: number;
+    removed: number;
+}
+/**
+ * Brings `parent`'s children into agreement with `nodes`.
+ *
+ * Positional rather than keyed, deliberately. A keyed diff by source offset
+ * looks more sophisticated and is worse here: every offset after an edit shifts
+ * by the length of that edit, so keys change for the whole rest of the document
+ * on every keystroke and the diff replaces everything the user has not touched.
+ * Position is stable under exactly the edits that matter — a change in the
+ * middle of a paragraph leaves the paragraph at the same index.
+ */
+export declare function patch(parent: HTMLElement, nodes: readonly PNode[], options: PatchOptions): PatchStats;
+/**
+ * The source range a text node carries, or null if it was not built here.
+ *
+ * The range is stamped on the node rather than looked up in a side table on
+ * purpose: a WeakMap keyed by node is the same information one indirection
+ * away, and the indirection is where a stale entry hides. A node that has no
+ * stamp is a node the browser created — which is a real event during
+ * composition, and the caller must treat it as one rather than guess.
+ */
+export declare function rangeOf(node: Node): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Reads every text node under `root` in document order and joins it.
+ *
+ * This is the projection invariant, asserted against the REAL DOM rather than
+ * against the projection tree — which is a different claim and the one that
+ * actually matters. The tree can be right while the reconciler drops a node.
+ */
+export declare function domText(root: Node): string;

package/dist/types/lib/markdown/surface.d.ts

@@ -0,0 +1,236 @@
+import { type CaretMap } from "./caret-map";
+import { type Projection, type ProjectOptions } from "./project";
+import { type SourceSelection } from "./position";
+import { type EditKind, type HistoryOptions } from "./history";
+export interface SurfaceOptions {
+    /** Called after every committed change, with the new source. */
+    onChange?: (source: string) => void;
+    /** Undo tuning. The defaults are the constants the mature editors landed on. */
+    history?: HistoryOptions;
+    /**
+     * Highlights a fenced block. Injected, never imported: reaching for the
+     * grammar registry from the pure layer would make a projection depend on
+     * which languages happened to be registered when it ran. The component
+     * passes the real tokenizer; a test can pass none and get plain text.
+     */
+    highlight?: ProjectOptions["highlight"];
+    /**
+     * Called when the DOM stopped agreeing with the model and could not be
+     * repaired from it. Loud by default: this is the one failure that silently
+     * eats the user's text if it is swallowed.
+     */
+    onDesync?: (detail: string) => void;
+}
+export interface Splice {
+    start: number;
+    end: number;
+    text: string;
+}
+export declare class MarkdownSurface {
+    readonly root: HTMLElement;
+    private source;
+    private readonly options;
+    /**
+     * Upload swaps that arrived mid-composition, applied at `compositionend`.
+     *
+     * DX-3134: the composing text node carries the source range it came from,
+     * and `reconcileComposed` writes the composed text back into exactly that
+     * range. A swap applied mid-composition changes the length of the source
+     * before the node — the range would then point at the wrong characters, and
+     * the composed text would land inside a URL. So the swap waits, and runs
+     * right after the composition has been read back.
+     */
+    private pendingSubstitutions;
+    /** The text node the browser is composing into, if any. */
+    private composing;
+    /** A projection that arrived while composing, applied at `compositionend`. */
+    private deferred;
+    private observer;
+    /** Depth of "this mutation is ours, ignore it". */
+    private writing;
+    private readonly history;
+    /** True while applying an undo, so the undo is not itself recorded. */
+    private restoring;
+    /**
+     * Where the caret is allowed to be, rebuilt with every projection.
+     *
+     * Held rather than recomputed per keystroke because every deletion and every
+     * arrow key needs it, and it is a pure function of the projection that was
+     * just built anyway. It is never mutated — a new projection replaces it
+     * whole, which is the same "nothing is kept in step so nothing can drift"
+     * argument the projection itself rests on.
+     */
+    private caretStops;
+    /**
+     * The projection those stops were built from.
+     *
+     * Held for the same reason and handed to callers rather than re-derived: a
+     * deletion has to know which characters are markup and which construct owns
+     * them, and re-projecting to ask would parse the document twice per keypress.
+     */
+    private projection;
+    constructor(root: HTMLElement, source: string, options: SurfaceOptions);
+    getSource(): string;
+    /** The projection the DOM currently shows, for callers that must read it. */
+    getProjection(): Projection;
+    /** Where the caret may legally be, for callers that have to reason about it. */
+    getCaretMap(): CaretMap;
+    /**
+     * The selection, snapped to positions that exist.
+     *
+     * SNAPPED RATHER THAN RETURNED RAW, because a click can land anywhere — the
+     * browser will happily put the caret at the edge of a zero-width marker, and
+     * every offset inside markup is now a place with no geometry. Normalising on
+     * the way IN means no caller downstream has to remember to.
+     */
+    getSelection(): SourceSelection | null;
+    /**
+     * Applies one splice and puts the caret where the inserted text ends.
+     *
+     * The caret is computed from the MODEL, never preserved from the DOM. That is
+     * the whole point of the design and also why it must be tested with a real
+     * caret in a real browser rather than asserted: a model-derived caret is
+     * exactly right or exactly wrong, with nothing in between.
+     */
+    apply(splice: Splice, select?: SourceSelection, kind?: EditKind): void;
+    /**
+     * Replaces every occurrence of `from` with `to` — in the document AND in
+     * every undo and redo entry — without recording an edit.
+     *
+     * THIS IS THE UPLOAD SWAP (DX-3134), and it is deliberately not an edit.
+     * When an image finishes uploading, its object URL is replaced by the stored
+     * URL. Recorded as an ordinary edit, Ctrl+Z would hand the object URL back —
+     * and a document holding it is a document that cannot be saved, for an image
+     * that WAS saved. Rewriting the history too means no undo, redo or later
+     * edit can resurrect a URL that no longer means anything.
+     *
+     * The caret stays where it was in the text the user can see: it is mapped
+     * through the substitution rather than moved, and only written back if it was
+     * in this surface to begin with — an upload finishing must never pull focus
+     * out of whatever the user moved on to. `onChange` fires, because the value
+     * genuinely changed and the consumer is the one who saves it.
+     *
+     * WHILE COMPOSING, the swap is queued and applied at `compositionend` — see
+     * `pendingSubstitutions`. A caller that needs to know when it has landed
+     * watches for `from` to leave the source (`onChange` fires when it does).
+     */
+    substitute(from: string, to: string): void;
+    /**
+     * The selection, but only while this surface HAS FOCUS.
+     *
+     * DX-3134: a render that is not the user's own edit — an upload finishing, an
+     * image's state moving — writes the caret back only when the author is
+     * actually in this document. The document selection can still sit inside the
+     * surface after focus has gone to a button or another field, and writing a
+     * selection into an editing host is one of the things that pulls focus back
+     * into it: an upload landing would then yank the author out of whatever they
+     * moved on to.
+     */
+    private focusedSelection;
+    /** Whether any undo or redo entry still holds `text` — see `History.includes`. */
+    remembers(text: string): boolean;
+    /** Replaces the whole document, e.g. when the consumer's value prop changes. */
+    setSource(source: string): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    /**
+     * Ends the current undo group.
+     *
+     * Called when the user moves the caret deliberately, because an edit after a
+     * selection change is a different thought however soon it arrives — one of
+     * the three coalescing rules, and the one a timer alone cannot express.
+     */
+    breakUndoGroup(): void;
+    private restore;
+    /**
+     * Re-projects and patches, then restores the caret.
+     *
+     * Refuses outright while composing. The deferral is recorded rather than
+     * dropped, so `compositionend` knows it owes a render — a skipped render that
+     * nobody remembers is a DOM that disagrees with the model forever.
+     */
+    private render;
+    /**
+     * Puts the caret back on a legal position after the USER moved it.
+     *
+     * A click, a drag or a vertical arrow key can leave the browser's selection
+     * at the edge of a collapsed marker, which is a place with no geometry and no
+     * meaning. Snapping costs one write and no re-projection — re-rendering here
+     * would be wasted work AND a risk, since every patch is a chance to disturb a
+     * caret that was already where it belonged.
+     *
+     * Replaces `refreshActive`, which existed only to move the reveal.
+     */
+    snapCaret(): void;
+    /**
+     * Moves the caret one VISIBLE character, in the model, and writes the result.
+     *
+     * Returns false when there is no selection to move, so the caller can let the
+     * browser have the key rather than swallowing it.
+     *
+     * One press crosses a whole marker, however many characters it holds, because
+     * the positions inside it are not positions. That is the difference between
+     * this and the grapheme step it replaces: `stepOffset` counted source
+     * characters, and under a contract where markup is never shown, counting
+     * source characters makes the caret appear to stall.
+     */
+    moveCaret(direction: 1 | -1, extend: boolean): boolean;
+    /**
+     * Moves the caret to the start or end of its current line, in the model,
+     * and writes the result. Home and End both have to be computed here rather
+     * than left to the browser — SG-799 — because a block's leading markup
+     * renders as a zero-size `inline-block` (`styles/markdown.css`), which
+     * Chromium treats as an atomic box for its own native line navigation, and
+     * a real Chromium probe caught End landing the browser's OWN selection
+     * inside that leading box instead of at the true end of the line.
+     *
+     * Returns false when there is no selection to move, matching `moveCaret`.
+     */
+    moveToLineEdge(edge: "start" | "end", extend: boolean): boolean;
+    /**
+     * Detects the third caret rule's failure: our own write left the browser's
+     * selection somewhere that is no longer a position in this document.
+     *
+     * Both mature codebases carry a detector for this because Chrome does it, and
+     * because the symptom — a caret that has silently moved to the top of the
+     * document — is indistinguishable from a bug in the edit itself.
+     */
+    private verifySelection;
+    /**
+     * Binds the composition lifecycle. Returns the unbind function.
+     *
+     * `compositionstart` captures the node the browser will mutate — read from
+     * the live selection, because that is the only place the browser says which
+     * one it chose.
+     */
+    bind(): () => void;
+    /**
+     * Reads a finished composition back into the model.
+     *
+     * A composition is confined to ONE text node inside one inline element, and
+     * that node carries the source range it came from — so reconciling is
+     * "replace source characters a..b with this node's current text". A handful
+     * of lines against a known range, rather than the 407-line document-wide
+     * DOM-to-markdown serialiser this design exists to avoid.
+     */
+    private reconcileComposed;
+    /**
+     * Everything `preventDefault` could not cancel arrives here.
+     *
+     * This path is not a safety net, it is a REQUIREMENT: Chrome on Android
+     * reports `cancelable: true` on `deleteContentBackward` and deletes anyway,
+     * `insertCompositionText` is non-cancelable by spec, and iOS dictation fires
+     * no composition events at all. An editor with no observation path is simply
+     * broken on those inputs, and cannot be told that it is.
+     *
+     * The repair is deliberately narrow: a character-data change to a stamped
+     * node is read back into its range. Anything structural means the browser
+     * built nodes we cannot map, and the honest response is to re-project from
+     * the model we still trust, not to guess at what it did.
+     */
+    private onMutations;
+    /** Runs `fn` with our own mutations invisible to the observer. */
+    private write;
+}

package/dist/types/lib/motion.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The one reduced-motion answer, read from `--motion-scale`.
+ *
+ * WHY THE TOKEN AND NOT `matchMedia` DIRECTLY. `--motion-scale` is the single
+ * place where the OS media query and the app-level `data-motion` override are
+ * reconciled (see `styles/motion.css`). Reading the media query alone would
+ * ignore the in-app preference control, so a user who set "reduced" in the app
+ * on a machine with no OS setting would get full-speed motion — the exact case
+ * that control exists for. It is also why a raw `motion-reduce:` utility is the
+ * wrong tool for anything this system builds (see the note on `Choice`'s
+ * thumb): that variant reads the OS query alone and fires even for someone who
+ * has explicitly chosen `data-motion="full"`.
+ *
+ * ONLY THE COMPARISON IS EVER USED, never the value. Multiplying a SPEED by the
+ * scale would be backwards — a slower auto-scroll ramp holds the user at the
+ * edge longer and produces MORE motion overall — and a scroll has no "half"
+ * anyway: it is smooth or it is a jump.
+ *
+ * ITS OWN MODULE because two unrelated layers need it. The drag engine's edge
+ * auto-scroll had the only copy, and the tab strip's reveal-the-active-tab
+ * scroll needs exactly the same question answered exactly the same way. A
+ * second copy is a second place for the token name to go stale.
+ */
+export declare function reducedMotion(): boolean;
+export declare const OS_REDUCE = "(prefers-reduced-motion: reduce)";
+/**
+ * The effective reduced-motion state, live: it re-renders when the OS preference changes and when any
+ * `useMotionPreference` anywhere in the page writes a new `data-motion`.
+ */
+export declare function useReducedMotion(): boolean;

package/dist/types/lib/pad.d.ts

@@ -0,0 +1,6 @@
+/** Zero-pad a non-negative integer to `width` digits — `pad(9)` → `"09"`,
+ *  `pad(7, 3)` → `"007"`. Internal only: shared by the time and value
+ *  formatters that print fixed-width calendar/clock fields, not part of the
+ *  public package surface (DX-3254 — this one-liner used to be redefined
+ *  independently in four places). */
+export declare function pad(n: number, width?: number): string;

package/dist/types/lib/paged-window/index.d.ts

@@ -0,0 +1,2 @@
+export { PAGED_WINDOW_SETTLE_MS, PagedWindowStore, windowPageNumbers, type LoadCount, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindowMode, type PagedWindowRecordsOptions, type PlacementEdges, type PagedWindowOptions, type PagedWindowSnapshot, } from "./store";
+export { usePagedWindow, type PagedWindow, type UsePagedWindowOptions } from "./use-paged-window";

package/dist/types/lib/paged-window/layout.d.ts

@@ -0,0 +1,21 @@
+import type { PageSnapshot } from "./store";
+/**
+ * What a page's block is showing. One name for every case, so the list renders
+ * ONE kind of block and only this changes:
+ *   ready    the page's cards are shown
+ *   loading  resident, its request is in flight
+ *   error    resident, its request failed
+ *   waiting  resident and ready, but past a hole in the loaded run — not shown until
+ *            the page that closes the hole arrives (see the store header)
+ *   unheld   outside the window (its rows may be kept, not drawn): empty space of the right height
+ */
+export type BlockStatus = "ready" | "loading" | "error" | "waiting" | "unheld";
+export declare function blockStatus<T>(page: PageSnapshot<T> | undefined): BlockStatus;
+/**
+ * How many page blocks to render. One per page of the list; before the first
+ * response the length is unknown but page 0 is being asked for, and one block
+ * stands in for it, so a new query does not flash an empty list.
+ */
+export declare function blockCountFor(pageCount: number, drawnPageCount: number): number;
+/** The height of a page's placeholder: the items it holds (the last page is short) times one item's height. */
+export declare function placeholderHeight(page: number, pageSize: number, total: number, pitch: number): number;

package/dist/types/lib/paged-window/list-owner.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+export interface ListOwner {
+    /** Called with +1 when a window under this list starts loading and -1 when it stops. */
+    reportBusy: (delta: 1 | -1) => void;
+}
+export declare function ListOwnerProvider({ value, children }: {
+    value: ListOwner;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useListOwner(): ListOwner | null;
+/** Tell the enclosing list (if any) whether this window is loading. */
+export declare function useReportBusy(owner: ListOwner | null, busy: boolean): void;

package/dist/types/lib/paged-window/records-binding.d.ts

@@ -0,0 +1,102 @@
+import type { RecordPayload, RecordTypeToken } from "../records/types";
+export interface PagedWindowRecordsOptions<T> {
+    /** The record type the rows are stored as. */
+    type: RecordTypeToken<T>;
+    /** The field-set tag the page fetch satisfies (the `needs` of a read). */
+    tag: string;
+    /** A loaded row as the store's payload shape: the app's `toRecord`, which stamps `__type` and `__timestamp`. */
+    toPayload: (row: T) => RecordPayload;
+    /** A hydrated record (the payload shape, nested records resolved) as the row type. Called once per stored state of a record. */
+    fromRecord: (hydrated: unknown) => T;
+    /**
+     * Which rows belong in this window and where. Without it a layer never moves a row between windows.
+     * `placeIn(row, run, edges)` answers where the row is drawn: an index from 0 to `run.length` in `run` (the loaded run's rows in drawn order, without
+     * the row, rows placed earlier in the same build included), or null for no place in it. Anything else throws. `edges` says whether the run starts
+     * and ends the list, so a consumer that places by sort order can still answer null past an unloaded edge. A held row answered null or its own
+     * index stays at its page position; an arrived row answered null is not drawn and still counts.
+     */
+    membership?: {
+        belongs: (row: T) => boolean;
+        placeIn: (row: T, run: readonly T[], edges: PlacementEdges) => number | null;
+    };
+    /**
+     * Whether a staleness mark on a held record re-reads the window. Default true. A window whose consumer answers an event itself sets false;
+     * `reissueMountedReads` (events were missed) still reaches it.
+     */
+    reReadOnStale?: boolean;
+}
+/** Whether the loaded run reaches the list's first and last row. */
+export interface PlacementEdges {
+    startsList: boolean;
+    endsList: boolean;
+}
+/** One drawn row of the loaded run, and the page whose items it is drawn in. */
+export interface RunRow<T> {
+    row: T;
+    page: number;
+}
+export declare class RecordsBinding<T> {
+    private readonly getKey;
+    private readonly typeName;
+    private readonly tag;
+    private options;
+    private readonly onChange;
+    /** key -> the row built from the stored state last seen; the same state gives the same row object. */
+    private readonly rowCache;
+    private readonly placed;
+    /** Keys carrying a layer that mattered at the last look (placed, or held and left out): the ones whose last layer going means a re-read. */
+    private watched;
+    private readonly subscriptions;
+    private retainedKeys;
+    private releaseRetain;
+    private stopLayers;
+    private unregisterRead;
+    constructor(options: PagedWindowRecordsOptions<T>, onChange: () => void, getKey: (row: T) => string | number);
+    /** The functions may close over fresh state; the type and the tag are fixed for the life of the window. */
+    update(options: PagedWindowRecordsOptions<T>): void;
+    /** Start hearing layers, and let a staleness event on a held record re-read the window. */
+    attach(roots: () => readonly string[], request: () => void): void;
+    detach(): void;
+    /** A query change or a stop: nothing placed, nothing remembered. */
+    reset(): void;
+    /** Whether an answer stamped with `tenant` may still be written: the store's own rule, so an empty page is judged like any other. */
+    static tenantIsCurrent(tenant: string | number | undefined): boolean;
+    /** Write a page's rows; the keys come back in page order. */
+    write(rows: readonly T[], tenant: string | number | undefined): string[];
+    private read;
+    /** The store has nothing (never written, swept, or cleared) for a held key: not a deletion. */
+    isUnknown(key: string): boolean;
+    private belongs;
+    /** The record without its writes in flight is a row of this list already. */
+    private baseBelongs;
+    /** The rows of one page that are drawn from its own position: present, not deleted, belonging here. */
+    rowsOf(keys: readonly string[]): T[];
+    /** Every present row of a page, belonging or not: what a consumer's row test asks about. */
+    loadedRowsOf(keys: readonly string[]): T[];
+    /** Held keys that are deleted, or that no longer belong: they are out of their page, and the list is one shorter for each. */
+    countLeftOut(held: ReadonlySet<string>): number;
+    /** Arrived rows no page holds yet: the list is one longer for each, until a read sent after the change answers. */
+    countArrived(held: ReadonlySet<string>): number;
+    placedKeys(): string[];
+    /**
+     * A layer moved, or a held record changed: who joined the window, who left, and whether a record's last layer went.
+     * Returns true when the window must be re-read (a displaced placed row's, or a left-out row's, last layer went).
+     * `waitSeq` is the token counter now: a read sent from here on is a read sent after the removal.
+     */
+    followLayers(held: ReadonlySet<string>, waitSeq: number): boolean;
+    /** Joins and drops, from the layers now; called whenever the window is rebuilt, so a record that becomes readable later still joins. */
+    refreshPlacement(held: ReadonlySet<string>, layered?: ReadonlySet<string>): void;
+    /** A placed row leaves the set once every page has been answered by a read sent after its last layer went. `answeredSince(seq)` says so. */
+    settlePlacement(answeredSince: (seq: number) => boolean): void;
+    /**
+     * Draw the placed rows into the loaded run. `run` is the shown pages' rows in order; the result is the same rows with each placed row at the
+     * place `placeIn` gives, or `run` itself when nothing moved. A row whose last layer has gone is not asked: it is redrawn where it was (below the
+     * row that was above it, else at its index), or left at its page position / undrawn when it had no place.
+     */
+    place(run: RunRow<T>[], firstPage: number, lastPage: number, lastPageOfList: number): RunRow<T>[];
+    /**
+     * Keep the store subscriptions on `subscribe` (the resident pages' keys and the placed ones) and the roots on
+     * `retain` (every key held, resident or retained) in step with what the window holds now.
+     */
+    reconcile(subscribe: ReadonlySet<string>, retain: ReadonlySet<string>): void;
+}