@notis_ai/cli 0.2.17 → 0.2.19

package/dist/space-sdk/src/ui/list/Row.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Row (toolkit spec 2.5): the content of one list row. Inside a ListReader the list draws the row element (it
+ * carries the keys, pointer rules and states) and Row fills it; on its own Row draws a `nui-row` element with the
+ * looks of its `state` prop.
+ */
+import { type ReactNode } from 'react';
+import { type Locale, type Words } from '../../words';
+import { type RowState } from './rowState';
+export type Tone = 'default' | 'info' | 'success' | 'warning' | 'danger';
+export type RowLabel = string | {
+    label: Words | string;
+    tone?: Tone;
+};
+/**
+ * One thing the row is linked to (a Space, an inbox), drawn as a chip after the title. With `onRemove` the chip ends
+ * in an x that unlinks it without opening the row.
+ */
+export interface RowTag {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    onRemove?: () => void;
+    /** The x's accessible name. Default "Remove {label}". */
+    removeLabel?: string;
+    /** The removal is under way: the x is disabled. */
+    busy?: boolean;
+    /** The link is still being saved: a spinner stands where the x goes. */
+    pending?: boolean;
+}
+export interface RowOwner {
+    name: string;
+    avatarUrl?: string;
+}
+export interface RowProps {
+    /** Lead, 20px. `{ status }` draws the status icon of that status (see `statusGroup`). */
+    icon?: ReactNode | {
+        status: string;
+    };
+    title: ReactNode;
+    /** The start of the muted line under the title (12/16); `labels` follow it after a " · ". */
+    meta?: ReactNode;
+    /** One clamped line (13/18). */
+    snippet?: ReactNode;
+    /**
+     * Words on the meta line, as text joined by ", " (never chips). A warning or danger label comes first and keeps
+     * its tone.
+     */
+    labels?: readonly RowLabel[];
+    /** Links as chips between the title and the trail; they shrink, then clip, before the title does. */
+    tags?: readonly RowTag[];
+    /** A 24px avatar after the time. */
+    owner?: RowOwner;
+    /**
+     * A compact relative time ("12m", "2h", "1d"; French "12 min", "2 h", "1 j") up to 30 days back, else the day and
+     * month this year and the full date before it. A date-only value (a 'YYYY-MM-DD' string, or any value with
+     * `dateOnly`) reads as that local day: "Today", or its day and month.
+     */
+    time?: Date | string | number;
+    /** `time` is a day, not a moment: no relative time, and no shift across time zones. */
+    dateOnly?: boolean;
+    /** The clock `time` is read against. Default the current time; pass it for a stable render (a test, a specimen). */
+    now?: Date;
+    /** First in the trail, before the time (a star). */
+    trailing?: ReactNode;
+    /** The row-more button (28px). Default true when the list has actions. */
+    more?: boolean;
+    /** Injected by ListReader; pass it when drawing a Row on its own. */
+    state?: RowState;
+    /**
+     * 2: a long title (a memory, a note) wraps onto a second line before it ends in an ellipsis; the row then aligns to
+     * its top, with the trail on the first title line. Default 1.
+     */
+    wrap?: 1 | 2;
+    /** Only on a Row drawn on its own; inside a list the list's row element carries the classes. */
+    className?: string;
+}
+/**
+ * Work moves backlog to done (`review`: the work is ready and a person checks it next); `up` and `down` are a service or
+ * a monitor (a health page, an integration).
+ */
+export type StatusGroup = 'backlog' | 'todo' | 'active' | 'review' | 'waiting' | 'done' | 'cancelled' | 'failed' | 'up' | 'down';
+export declare const STATUS_WORDS: Readonly<Record<StatusGroup, Words>>;
+/** The status group of a Space status ('In progress', 'in_progress', 'doing' are all active). Unknown: todo. */
+export declare function statusGroup(status: string): StatusGroup;
+/**
+ * The status icon of one status, labelled for screen readers. `decorative`: hidden from screen readers (the status
+ * is already said in text next to it).
+ */
+export declare function StatusIcon({ status, label, decorative }: {
+    status: string;
+    label?: Words | string;
+    decorative?: boolean;
+}): import("react").JSX.Element;
+/** The words of the star mark. */
+export declare const STAR_WORDS: Readonly<{
+    starred: {
+        en: string;
+        fr: string;
+    };
+}>;
+/** A starred item's filled amber star (14px, labelled "Starred"), for a row's trailing slot or a reader head. */
+export declare function StarMark({ decorative }: {
+    decorative?: boolean;
+}): import("react").JSX.Element;
+/**
+ * The row-more button and its action menu for the current row, for content that is not a Row (a tile, a table
+ * cell). Draws nothing outside a ListReader or when the list has no actions for the item.
+ */
+export declare function RowMore(): import("react").JSX.Element | null;
+/** The words of row and reader times. `{t}` in `ago` is a compact time from `formatRowAgo`. */
+export declare const ROW_TIME_WORDS: Readonly<{
+    today: {
+        en: string;
+        fr: string;
+    };
+    ago: {
+        en: string;
+        fr: string;
+    };
+}>;
+/**
+ * A row time as a Date. A 'YYYY-MM-DD' string (or any value when `dateOnly`) maps to local noon of that day, so a
+ * day never shows as the day before west of UTC.
+ */
+export declare function parseRowDate(value: Date | string | number, dateOnly?: boolean): {
+    date: Date;
+    dateOnly: boolean;
+};
+/**
+ * A compact time since `value`, the deck's: minutes under an hour, hours under a day, else days. English "12m",
+ * "2h", "4d"; French "12 min", "2 h", "4 j". Null for an invalid value or a time ahead of `now`.
+ */
+export declare function formatRowAgo(value: Date | string | number, locale: Locale, now?: Date): string | null;
+/** The long time a reader shows: "45m ago" / "il y a 45 min". Empty for an invalid value or a time ahead of `now`. */
+export declare function formatReaderAgo(value: Date | string | number, locale: Locale, now?: Date): string;
+/**
+ * The compact row time: a relative time up to 30 days back ("12m", "2h", "1d"), else the day and month this year
+ * and the full date before it ("Oct 3", "Oct 3, 2025"; French "3 oct.", "3 oct. 2025"). A date-only value shows
+ * "Today" / "Aujourd’hui" or its day and month; a time ahead of `now` shows its date.
+ */
+export declare function formatRowTime(value: Date | string | number, locale: Locale, now?: Date, timeOptions?: {
+    dateOnly?: boolean;
+}): string;
+/** One list row: lead icon, a title over a meta line, then the trail (trailing, time, avatar, More). */
+export declare function Row({ icon, title, meta, snippet, labels, tags, owner, time, dateOnly, now, trailing, more, state, wrap, className, }: RowProps): import("react").JSX.Element;

package/dist/space-sdk/src/ui/list/SelectionBar.d.ts

@@ -0,0 +1,65 @@
+/**
+ * SelectionBar (toolkit spec 2.6): the locked "today" pill at the bottom of a list while rows are selected.
+ *
+ * "{n} selected", then one button per action (label, then a pill keycap), overflow in a More menu, and X to clear
+ * (its tooltip shows Esc). Where it does not fit the pill drops the keys, then the words (`data-fit`), and every
+ * button then carries a tooltip with both, as in the deck.
+ *
+ * `useSelectionBar` registers the action keys once per key at `collection` with boost 25, so they win over row keys.
+ * With nothing selected the keys act on a fallback (the open item or the cursor row), as in the Manager.
+ */
+import type { ActionOutcome, ActionsController, ResolvedAction } from '../actions/useActions';
+import type { Selection } from './useSelection';
+/** Buttons shown in the pill before the rest go into More. */
+export declare const SELECTION_BAR_MAX_INLINE = 5;
+/** The boost of the bar's keys over row keys (toolkit spec 2.1). */
+export declare const SELECTION_BAR_BOOST = 25;
+export type SelectionBarFit = '' | 'nokeys' | 'icons';
+export interface SelectionBarProps {
+    /** The actions that apply to the selected items, in order. */
+    actions: readonly ResolvedAction<any>[];
+    count: number;
+    onClear(): void;
+    /** `anchor` is the pressed button (a picker action opens its menu there). */
+    onRun(action: ResolvedAction<any>, anchor?: HTMLElement | null): void;
+    /** Ids of the actions running now: their buttons show busy and ignore presses. */
+    busy?: ReadonlySet<string>;
+    /** 'list' (default): the pill centres on its list. 'page': on the whole page. */
+    anchor?: 'list' | 'page';
+    className?: string;
+}
+/** The first fit that leaves `room` px, trying keys and words, then words only, then icons. */
+export declare function chooseFit(measure: (fit: SelectionBarFit) => number, room: number): SelectionBarFit;
+export declare function SelectionBar({ actions, count, onClear, onRun, busy, anchor, className }: SelectionBarProps): import("react").JSX.Element;
+export interface UseSelectionBarOptions<T> {
+    controller: ActionsController<T>;
+    selection: Selection;
+    /** Items by id (the list's items). */
+    getItem(id: string): T | undefined;
+    /** What the keys act on while nothing is selected (the open item, else the cursor row). */
+    fallback?: () => T[];
+    /** Keys off while false (the list is hidden). */
+    when?: () => boolean;
+    /** Owner override (default the nearest ShortcutScope). */
+    owner?: string;
+    /** Called after an action ran on the selection (ListReader moves the cursor off removed rows). */
+    onRan?: (action: ResolvedAction<T>, items: T[], outcome: ActionOutcome<T>) => void;
+    /**
+     * A picker action (one with `options`) was chosen: open its menu at `anchor` (the bar button, null from a key or
+     * the More menu). Without it the action runs at once with no choice.
+     */
+    onPick?: (action: ResolvedAction<T>, items: T[], anchor: HTMLElement | null) => void;
+}
+export interface SelectionBarState<T> {
+    /** Something is selected and the list has bulk actions: draw the bar. */
+    visible: boolean;
+    selectedItems: T[];
+    /** Spread on `<SelectionBar />`. */
+    barProps: SelectionBarProps;
+    /**
+     * Runs an action on the selection (or the fallback when nothing is selected). A picker action goes to `onPick`
+     * instead and resolves null.
+     */
+    runAction(action: ResolvedAction<T>, anchor?: HTMLElement | null): Promise<ActionOutcome<T> | null>;
+}
+export declare function useSelectionBar<T>(options: UseSelectionBarOptions<T>): SelectionBarState<T>;

package/dist/space-sdk/src/ui/list/index.d.ts

@@ -0,0 +1,14 @@
+export { LIST_DRAG_TYPE, LIST_READER_WORDS, ListReader, ListSkeleton, rankActions, successorOf } from './ListReader';
+export type { ListGroup, ListReaderApi, ListReaderProps, ListReorder, ListSearchProps, ListSkeletonProps, OpenChangeReason, OpenChangeVerdict, ReaderAction, ReaderCtx, TileParts, ViewMenuItem, ViewMenuProps, } from './ListReader';
+export { ROW_TIME_WORDS, Row, RowMore, STAR_WORDS, STATUS_WORDS, StarMark, StatusIcon, formatReaderAgo, formatRowAgo, formatRowTime, parseRowDate, statusGroup, } from './Row';
+export type { RowLabel, RowOwner, RowProps, RowTag, StatusGroup, Tone } from './Row';
+export { IDLE_ROW_STATE, RowIdContext, RowStateContext, useRowState } from './rowState';
+export type { RowState, RowStateSource } from './rowState';
+export { ROW_ID_ATTRIBUTE, ROW_INTERACTIVE_SELECTOR, boardStep, findRow, gridColumns, useListKeys } from './useListKeys';
+export type { RowDomProps, UseListKeysOptions } from './useListKeys';
+export { EMPTY_SELECTION, rangeBetween, selectionReducer, useSelection } from './useSelection';
+export type { Selection, SelectionAction, SelectionState, UseSelectionOptions } from './useSelection';
+export { SELECTION_BAR_BOOST, SELECTION_BAR_MAX_INLINE, SelectionBar, chooseFit, useSelectionBar, } from './SelectionBar';
+export type { SelectionBarFit, SelectionBarProps, SelectionBarState, UseSelectionBarOptions } from './SelectionBar';
+export { REORDER_DRAG_TYPE, REORDER_WORDS, chainReorderProps, dropIndex, useReorder } from './useReorder';
+export type { Reorder, ReorderChange, ReorderItemProps, ReorderOrientation, UseReorderOptions } from './useReorder';

package/dist/space-sdk/src/ui/list/rowState.d.ts

@@ -0,0 +1,22 @@
+/** Row state (toolkit spec 2.3, 2.5): what a row needs to draw its cursor, open and selected looks. */
+import { type ReactNode } from 'react';
+export interface RowState {
+    cursor: boolean;
+    open: boolean;
+    selected: boolean;
+    /** Something in the list is selected (rows show their checkbox). */
+    anySelected: boolean;
+    index: number;
+}
+export declare const IDLE_ROW_STATE: RowState;
+export interface RowStateSource {
+    stateOf(id: string): RowState;
+    /** Toggle the row in the selection (the lead checkbox); null when the list is not selectable. */
+    toggle: ((id: string) => void) | null;
+    /** The row-more button content; null when the list has no actions. */
+    more: ((id: string) => ReactNode) | null;
+}
+export declare const RowStateContext: import("react").Context<RowStateSource | null>;
+export declare const RowIdContext: import("react").Context<string | null>;
+/** The state of row `id` inside a ListReader (or a list that provides RowStateContext). */
+export declare function useRowState(id?: string): RowState;

package/dist/space-sdk/src/ui/list/useListKeys.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `useListKeys` (toolkit spec 2.4): J/K, Enter, X, Shift+J/K and Mod+A on a list, plus the row pointer rules,
+ * registered with the keyboard engine (no own keydown listener).
+ *
+ * Behaviour follows the Portal Manager list (`useCollectionInteractions`):
+ * - J/K wrap on a fresh press and stop at the edge while held (`stepCursor`, `repeat: true`).
+ * - With an item open, J/K open the item under the new cursor.
+ * - Only visible rows count (hidden, inert or display none rows are skipped).
+ * - The row under the cursor is focused without scrolling, then scrolled to the nearest edge (scroll padding keeps
+ *   it clear of the selection bar). Focus stays put only inside another toolkit pane or layer, such as the open
+ *   item's reader (`focusStaysOnMove`); from a filter or a tab it goes to the row, so Enter opens the row.
+ * - Mod+press toggles on pointer down and swallows the click; Shift+click selects a range; a plain click clears
+ *   the selection and opens; Space on the row toggles; press and hold on touch toggles (500 ms, 10 px).
+ * - Clicks on a control inside the row (button, link, field) are left to the control.
+ *
+ * Put `data-notis-engine-list` on the list container (role listbox): the engine then keeps its keys working while
+ * a row has focus.
+ */
+import { type RefObject } from 'react';
+import type { FocusEvent as ReactFocusEvent, KeyboardEvent as ReactKeyboardEvent, MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from 'react';
+import { type Scope } from '../../words';
+import type { Selection } from './useSelection';
+/** Clicks on these inside a row belong to them (Manager `INTERACTIVE_SELECTOR`). */
+export declare const ROW_INTERACTIVE_SELECTOR = "button, a, input, textarea, select, [role=\"button\"], [contenteditable]:not([contenteditable=\"false\"])";
+export declare const ROW_ID_ATTRIBUTE = "data-nui-item";
+export interface UseListKeysOptions {
+    ids: readonly string[];
+    cursor: string | null;
+    setCursor(id: string): void;
+    onOpen(id: string): void;
+    /** J on the last row goes to the first (fresh press only). Default true. */
+    wrap?: boolean;
+    /** Default 'collection'. */
+    scope?: Scope;
+    /** The list element (scroll container or the listbox). Keys are live while it is visible. */
+    containerRef: RefObject<HTMLElement | null>;
+    /** Multi-select: X, Shift+J/K, Mod+A, Mod/Shift-click, Space and press and hold. */
+    selection?: Selection | null;
+    /** The open item: J/K then open the next item too. */
+    openId?: string | null;
+    /** Keys off (a background view). Default true. */
+    enabled?: boolean;
+    /** Owner override for the defs (default the nearest ShortcutScope). */
+    owner?: string;
+    /** J on the last row without wrapping (the list has more to load): ListReader loads the next page. */
+    onReachEnd?: () => void;
+    /**
+     * A tile grid: the arrow keys move left, right and by one row up and down (no wrap) while a tile has focus.
+     * J/K still step one tile.
+     */
+    grid?: boolean;
+    /**
+     * A board: the ids of each column, in order (implies `grid`). Up and Down move inside the column (no wrap), Left and
+     * Right go to the nearest column that has tiles, at the same height or its last tile.
+     */
+    board?: readonly (readonly string[])[];
+}
+export interface RowDomProps {
+    role: 'option';
+    'aria-selected': boolean;
+    tabIndex: number;
+    'data-nui-item': string;
+    'data-cursor'?: '';
+    'data-open'?: '';
+    'data-selected'?: '';
+    onMouseDown(event: ReactMouseEvent<HTMLElement>): void;
+    onClick(event: ReactMouseEvent<HTMLElement>): void;
+    onClickCapture(event: ReactMouseEvent<HTMLElement>): void;
+    onKeyDown(event: ReactKeyboardEvent<HTMLElement>): void;
+    onFocus(event: ReactFocusEvent<HTMLElement>): void;
+    onPointerDown(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerMove(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerUp(event: ReactPointerEvent<HTMLElement>): void;
+    onPointerCancel(event: ReactPointerEvent<HTMLElement>): void;
+}
+/** The row element of `id` inside `container`. */
+export declare function findRow(container: HTMLElement | null, id: string): HTMLElement | null;
+/**
+ * The next tile on a board from `current` (`lanes` = the ids of each column, in order). Up and Down stay in the column
+ * and hold at its edge; Left and Right skip empty columns and land at the same index or the column's last tile. Null
+ * when the key has nowhere to go.
+ */
+export declare function boardStep(lanes: readonly (readonly string[])[], current: string | null, dir: 'left' | 'right' | 'up' | 'down'): string | null;
+/** Tiles in the first row of a grid (same top edge as the first tile); 1 when it cannot tell. */
+export declare function gridColumns(container: HTMLElement | null, ids: readonly string[]): number;
+export declare function useListKeys(options: UseListKeysOptions): {
+    getRowProps(id: string): RowDomProps;
+    visibleIds(): string[];
+};

package/dist/space-sdk/src/ui/list/useReorder.d.ts

@@ -0,0 +1,86 @@
+/**
+ * useReorder: drag to reorder, plus Alt and an arrow key, for any ordered list (rows, tiles, a slide rail).
+ *
+ * - Off unless the list asks for it: rows only get reorder props from `getItemProps`, and `enabled: false` returns none.
+ * - Pointer: a row drags with the browser's own drag (so touch scrolling stays the browser's), the row under the
+ *   pointer shows where it lands (`data-drop="before" | "after"`) and the dragged row shows `data-dragging`.
+ * - Keyboard: Alt and an arrow key move the focused item one place (Up and Down for a vertical list, Left and Right
+ *   for a horizontal one, all four for a grid); Alt+Home and Alt+End move it to the start or the end. Focus stays on it.
+ * - Every move is said in the polite live region (`announcer`): "Moved to position 3 of 8.".
+ * - Optimistic: the new order shows at once. `onReorder` may return a promise; when it rejects, the order goes back
+ *   to the list the page passes and `onError` runs (without one, the live region says it could not save). Once a move
+ *   settles, the page's own order wins as soon as it changes.
+ */
+import { type DragEvent as ReactDragEvent, type KeyboardEvent as ReactKeyboardEvent, type ReactNode } from 'react';
+import { type Words } from '../../words';
+/** The drag data type a reorder drag carries (the moved id). */
+export declare const REORDER_DRAG_TYPE = "application/x-notis-reorder";
+/** Every word a reorderable list says, in English and French. */
+export declare const REORDER_WORDS: Readonly<{
+    hint: Words;
+    moved: Words;
+    failed: Words;
+}>;
+/** One move, as `onReorder` gets it. Indexes count the whole list, before (`from`) and after (`to`) the move. */
+export interface ReorderChange<T> {
+    item: T;
+    id: string;
+    from: number;
+    to: number;
+    /** Every id in the new order. */
+    ids: string[];
+}
+export type ReorderOrientation = 'vertical' | 'horizontal' | 'both';
+export interface UseReorderOptions<T> {
+    items: readonly T[];
+    getId: (item: T) => string;
+    /** Save the move. Return a promise to keep the new order until it settles; a rejection puts the old order back. */
+    onReorder: (change: ReorderChange<T>) => void | Promise<unknown>;
+    /** Only these items move (all by default). Any item is still a place to drop. */
+    canReorder?: (item: T) => boolean;
+    /** Which arrow keys move an item. Default 'vertical'. */
+    orientation?: ReorderOrientation;
+    /** Default true. False gives no reorder props, so the list renders as it would without the hook. */
+    enabled?: boolean;
+    /** Called after a rejected move put the old order back. Without it the live region says it could not save. */
+    onError?: (error: unknown) => void;
+}
+/** The props one item spreads (with its own handlers chained, see `chainReorderProps`). */
+export interface ReorderItemProps {
+    draggable?: true;
+    'aria-describedby'?: string;
+    /** Marks a reorderable item (the toolkit fades `[data-reorder][data-dragging]`). */
+    'data-reorder'?: '';
+    'data-drop'?: 'before' | 'after';
+    'data-dragging'?: '';
+    ref?: (element: HTMLElement | null) => void;
+    onDragStart?: (event: ReactDragEvent<HTMLElement>) => void;
+    onDragOver?: (event: ReactDragEvent<HTMLElement>) => void;
+    onDragLeave?: (event: ReactDragEvent<HTMLElement>) => void;
+    onDrop?: (event: ReactDragEvent<HTMLElement>) => void;
+    onDragEnd?: (event: ReactDragEvent<HTMLElement>) => void;
+    onKeyDown?: (event: ReactKeyboardEvent<HTMLElement>) => void;
+}
+export interface Reorder<T> {
+    /** The items in the order to show (the optimistic one while a move saves). */
+    items: T[];
+    ids: string[];
+    /** Props for one item. `movable` overrides `canReorder` for it (false: a drop place only). */
+    getItemProps(id: string, options?: {
+        movable?: boolean;
+    }): ReorderItemProps;
+    /** The hint and the live region; render it once, anywhere inside the page. */
+    announcer: ReactNode;
+    /** Moves an item to an index of the whole list, as a drop or a key would. */
+    move(id: string, to: number): void;
+    /** A move is saving. */
+    pending: boolean;
+}
+/** The new index of an item dropped before or after another. */
+export declare function dropIndex(from: number, over: number, side: 'before' | 'after'): number;
+export declare function useReorder<T>(options: UseReorderOptions<T>): Reorder<T>;
+/**
+ * Spreads reorder props over an item's own: both handlers run (the item's first), and both refs get the element.
+ * `own` holds the item's handlers for the same events (onDragStart, onKeyDown and so on).
+ */
+export declare function chainReorderProps<P extends object>(own: P, reorder: ReorderItemProps): P & ReorderItemProps;

package/dist/space-sdk/src/ui/list/useSelection.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `useSelection` (toolkit spec 2.4): the multi-select state of one list.
+ *
+ * The reducer mirrors the Portal Manager (`useCollectionInteractions`): an anchor where a range starts, and a base
+ * (the selection outside the range being extended) so Shift+J then Shift+K shrinks the range instead of keeping
+ * every row it ever passed. Pure and exported for tests.
+ */
+export interface SelectionState {
+    selected: ReadonlySet<string>;
+    /** Where the next range starts. */
+    anchor: string | null;
+    /** The selection kept outside the range being extended; null when no range is in progress. */
+    base: ReadonlySet<string> | null;
+}
+export type SelectionAction = {
+    type: 'toggle';
+    id: string;
+} | {
+    type: 'set';
+    ids: readonly string[];
+} | {
+    type: 'clear';
+} | {
+    type: 'selectAll';
+    ids: readonly string[];
+}
+/** A plain click: the clicked row becomes the anchor. */
+ | {
+    type: 'activate';
+    id: string;
+}
+/** The cursor moved without Shift: the next extension starts fresh from it. */
+ | {
+    type: 'navigate';
+    id: string;
+}
+/** Shift+J/K from `cursor` to `next`. */
+ | {
+    type: 'extendStep';
+    ids: readonly string[];
+    cursor: string | null;
+    next: string;
+}
+/** Shift+click on `id`. */
+ | {
+    type: 'range';
+    ids: readonly string[];
+    cursor: string | null;
+    id: string;
+}
+/** The list changed: drop ids that left it. */
+ | {
+    type: 'prune';
+    ids: readonly string[];
+};
+export declare const EMPTY_SELECTION: SelectionState;
+/** The ids from `a` to `b` inclusive, in list order; just `b` when either is not in the list. */
+export declare function rangeBetween(ids: readonly string[], a: string, b: string): string[];
+export declare function selectionReducer(state: SelectionState, action: SelectionAction): SelectionState;
+export interface UseSelectionOptions {
+    ids: readonly string[];
+    cursor: string | null;
+    /**
+     * Controlled selection: the ids selected now. With it the hook keeps only the anchor and the range base and
+     * reports every change through `onChange`; leave it out for the hook to own the selection.
+     */
+    selected?: readonly string[] | ReadonlySet<string>;
+    /** Every change of the selection, in list order where the list knows the ids. */
+    onChange?: (ids: string[]) => void;
+}
+export interface Selection {
+    selected: ReadonlySet<string>;
+    isSelected(id: string): boolean;
+    toggle(id: string): void;
+    /** Shift+click: select from the anchor (else the cursor) to `id`. */
+    extendTo(id: string): void;
+    selectAll(): void;
+    clear(): void;
+    count: number;
+    /** Replace the selection. */
+    set(ids: readonly string[]): void;
+    /** Shift+J/K: grow or shrink the range from the anchor to `next`. */
+    extendStep(next: string): void;
+    /** A cursor move without Shift (J/K): the next range starts from `id`. */
+    navigate(id: string): void;
+    /** A plain click on `id`: it becomes the anchor. */
+    activate(id: string): void;
+    anchor: string | null;
+}
+export declare function useSelection({ ids, cursor, selected: controlledSelected, onChange }: UseSelectionOptions): Selection;

package/dist/space-sdk/src/ui/open/OpenAsMenu.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OpenAsMenu (toolkit spec 2.9, round decision alt a): the Notion-style button at the reader's top left. Its menu
+ * offers Side peek, Center peek and Full page with a check on the current mode. Hidden when only one mode is allowed.
+ */
+import { type Words } from '../../words';
+import type { OpenMode } from './openModeStore';
+export declare const OPEN_MODE_WORDS: Readonly<Record<OpenMode, Words>>;
+export declare const OPEN_MODE_ICONS: Readonly<Record<OpenMode, string>>;
+export interface OpenAsMenuProps {
+    allowed?: OpenMode | readonly OpenMode[];
+    mode: OpenMode;
+    onChange(mode: OpenMode): void;
+    className?: string;
+}
+export declare function OpenAsMenu({ allowed, mode, onChange, className }: OpenAsMenuProps): import("react").JSX.Element | null;

package/dist/space-sdk/src/ui/open/index.d.ts

@@ -0,0 +1,6 @@
+export { OPEN_MODES, OPEN_MODE_CACHE_PREFIX, OpenModeStoreProvider, getOpenModeStore, isOpenMode, localStorageOpenModeStore, readOpenModeCache, setOpenModeStore, useOpenModeStore, userSettingsOpenModeStore, writeOpenModeCache, } from './openModeStore';
+export type { OpenMode, OpenModeStore } from './openModeStore';
+export { normalizeAllowed, useOpenMode, useOpenModeKey } from './useOpenMode';
+export type { UseOpenModeOptions } from './useOpenMode';
+export { OPEN_MODE_ICONS, OPEN_MODE_WORDS, OpenAsMenu } from './OpenAsMenu';
+export type { OpenAsMenuProps } from './OpenAsMenu';

package/dist/space-sdk/src/ui/open/openModeStore.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where the chosen open mode lives (toolkit spec 2.9). The mode belongs in Notis user settings, keyed by Space and
+ * list. No user-settings call reaches Space code yet, so this is an adapter: a host (or a test) installs a store with
+ * `setOpenModeStore` or `<OpenModeStoreProvider>`, and the default keeps the choice in this browser's localStorage.
+ * localStorage also stays a cache in front of any remote store, so the mode shows at once on the next visit.
+ */
+import { type ReactNode } from 'react';
+export type OpenMode = 'side' | 'center' | 'full';
+export declare const OPEN_MODES: readonly OpenMode[];
+export declare function isOpenMode(value: unknown): value is OpenMode;
+/** A user-settings backend for open modes. `read` may be async (a settings call); `write` is fire and forget. */
+export interface OpenModeStore {
+    read(key: string): OpenMode | null | Promise<OpenMode | null>;
+    write(key: string, mode: OpenMode): void | Promise<void>;
+    /** Changes made elsewhere (another tab, another device through settings). Returns an unsubscribe. */
+    subscribe?(key: string, onChange: (mode: OpenMode | null) => void): () => void;
+}
+export declare const OPEN_MODE_CACHE_PREFIX = "notis:open-mode:";
+/** The localStorage cache: read synchronously before the store answers. */
+export declare function readOpenModeCache(key: string): OpenMode | null;
+export declare function writeOpenModeCache(key: string, mode: OpenMode): void;
+/** The default store: this browser only, until a Notis user-settings adapter is installed. */
+export declare const localStorageOpenModeStore: OpenModeStore;
+/**
+ * A store over a generic user-settings API (get and set by key), for a host that has one. Values are kept under
+ * `openMode:<key>`.
+ */
+export declare function userSettingsOpenModeStore(settings: {
+    get(key: string): unknown | Promise<unknown>;
+    set(key: string, value: unknown): void | Promise<void>;
+}): OpenModeStore;
+/** Installs the store every `useOpenMode` uses outside an `OpenModeStoreProvider`. Returns the previous one. */
+export declare function setOpenModeStore(store: OpenModeStore | null): OpenModeStore;
+export declare function getOpenModeStore(): OpenModeStore;
+export declare function OpenModeStoreProvider({ store, children }: {
+    store: OpenModeStore;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<OpenModeStore | null>>;
+export declare function useOpenModeStore(): OpenModeStore;

package/dist/space-sdk/src/ui/open/useOpenMode.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `useOpenMode` (toolkit spec 2.9): the open mode of one list (side, center or full), persisted per Space and list.
+ * The cached mode shows at once; the store's answer (user settings) replaces it when it differs.
+ */
+import { type OpenMode } from './openModeStore';
+export interface UseOpenModeOptions {
+    /** The modes this list offers; the first is the default. Default all three, side first. */
+    allowed?: OpenMode | readonly OpenMode[];
+    /** Default `${spaceId}:${listId}` (list id 'list'). Leave out with no Space and nothing persists. */
+    storageKey?: string;
+    /** The list id inside the Space, for the default storage key. Default 'list'. */
+    listId?: string;
+}
+export declare function normalizeAllowed(allowed: OpenMode | readonly OpenMode[] | undefined): OpenMode[];
+/** The storage key: given, else `${spaceId}:${listId}`, else null (nothing persists). */
+export declare function useOpenModeKey(storageKey: string | undefined, listId?: string): string | null;
+export declare function useOpenMode(options?: UseOpenModeOptions): [OpenMode, (mode: OpenMode) => void];