prime-ui-kit 0.9.0 → 0.9.1

package/dist/components/datepicker/DatepickerPanel.d.ts

@@ -0,0 +1,113 @@
+import { type Locale } from "date-fns";
+import * as React from "react";
+import type { ControlSize } from "@/internal/states";
+import { type DatepickerPreset, type DatepickerRange, type WeekStart } from "./datepickerModel";
+/** System strings and default texts. */
+export type DatepickerLabels = {
+    /** Field text without a value. */
+    placeholder: string;
+    pickStart: string;
+    pickEnd: string;
+    pickDate: string;
+    reset: string;
+    apply: string;
+    prevMonth: string;
+    nextMonth: string;
+    rangeStart: string;
+    rangeEnd: string;
+    date: string;
+    timeStart: string;
+    timeEnd: string;
+    time: string;
+    /** Prefix of a range without a start: «до 6 окт». */
+    until: string;
+    /** Heading of the presets column. */
+    presetsTitle: string;
+    /** Muted marker after the field label when `optional`. */
+    optional: string;
+};
+export declare const DATEPICKER_LABELS: DatepickerLabels;
+export type CalendarOptions = {
+    /** Tier: day cell = the tier's menu item height (`m` → 32 px), text = the tier's text. */
+    size?: ControlSize;
+    /** Months side by side; one when there is no room. */
+    months?: 1 | 2;
+    /** The presets column (`range` only). */
+    presets?: DatepickerPreset[] | false;
+    /** Step prompt under the calendar: «Выберите начальную дату» / «… конечную дату». */
+    prompt?: boolean;
+    /** Footer with date fields and Reset / Apply. Without it a pick applies at once. */
+    footer?: boolean;
+    /** Time fields in the footer (00:00 — 23:59 by default). */
+    withTime?: boolean;
+    /** Days that cannot be picked (a calendar day is a Date at local midnight). */
+    isDayDisabled?: (day: Date) => boolean;
+    /** Future days are muted and cannot be picked. */
+    disableFuture?: boolean;
+    /** An annual day + month: no year, months wrap around inside `YEARLESS_YEAR`. */
+    yearless?: boolean;
+    /** «Today» for highlighting, presets and `disableFuture`; the browser's day by default. */
+    today?: Date;
+    locale?: Locale;
+    weekStartsOn?: WeekStart;
+    labels?: Partial<DatepickerLabels>;
+};
+export type RangeModeProps = {
+    mode: "range";
+    /** Bounds in wall-clock time; `null` — the bound is not set. */
+    value?: DatepickerRange;
+    defaultValue?: DatepickerRange;
+    onValueChange?: (value: DatepickerRange) => void;
+    /** Value applied by «Сбросить»; an empty range by default. */
+    resetValue?: DatepickerRange;
+};
+export type SingleModeProps = {
+    mode: "single";
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onValueChange?: (value: Date | null) => void;
+    /** Value applied by «Сбросить»; `null` by default. */
+    resetValue?: Date | null;
+};
+/** Native attributes and `ref` of the element a part renders (the panel card, the field frame). */
+export type DatepickerDomProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "defaultValue" | "defaultChecked" | "onChange"> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+export type DatepickerPanelProps = CalendarOptions & (RangeModeProps | SingleModeProps) & DatepickerDomProps;
+/** Separates the calendar options from the native attributes of a part. */
+export declare function splitCalendarOptions<T extends CalendarOptions>({ size, months, presets, prompt, footer, withTime, isDayDisabled, disableFuture, yearless, today, locale, weekStartsOn, labels, ...rest }: T): {
+    options: CalendarOptions;
+    rest: Omit<T, keyof CalendarOptions>;
+};
+/** The value a part works with: controlled or internal, with its setter. */
+export type DatepickerValue = {
+    mode: "range";
+    value: DatepickerRange;
+    onChange: (value: DatepickerRange) => void;
+    resetValue?: DatepickerRange | undefined;
+} | {
+    mode: "single";
+    value: Date | null;
+    onChange: (value: Date | null) => void;
+    resetValue?: Date | null | undefined;
+};
+/** Controlled-or-internal value of either mode (a part never switches its mode). */
+export declare function useDatepickerValue(props: RangeModeProps | SingleModeProps): DatepickerValue;
+/** Calendar panel without a field: inline in a page or a card. */
+export declare function DatepickerPanel(props: DatepickerPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace DatepickerPanel {
+    var displayName: string;
+}
+type PanelViewProps = Omit<CalendarOptions, "labels"> & DatepickerValue & {
+    labels: DatepickerLabels;
+    /** `Datepicker.Panel`: the card follows its container; otherwise (the Root popover) it sizes to its content. */
+    embedded: boolean;
+    /** After a value is applied (Root closes the popover). */
+    onDone?: () => void;
+    className?: string;
+    /** Native attributes and `ref` of the panel card (`Datepicker.Panel`). */
+    dom?: Omit<DatepickerDomProps, "className">;
+};
+/** Presets aside (or above when narrow), 1–2 months, the step prompt, the footer. */
+export declare function PanelView(props: PanelViewProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/datepicker/datepickerModel.d.ts

@@ -1,52 +1,47 @@
 import { type Locale } from "date-fns";
 /**
- * Логика Datepicker без часовых поясов: все значения — «настенное» время (локальные поля Date).
- * Календарный день — Date на локальную полночь. Перевод в пояс — задача приложения.
+ * Datepicker logic without time zones: every value is wall-clock time (the local Date fields).
+ * A calendar day is a Date at local midnight. Converting to a zone is up to the application.
  */
 export type DatepickerRange = {
-    /** null — без нижней границы («Всё время»). */
+    /** `null` — no lower bound («Всё время»). */
     from: Date | null;
     to: Date | null;
 };
 export type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
-/** Високосный год для ежегодных дат «день + месяц». */
+/** A leap year for yearly "day + month" dates. */
 export declare const YEARLESS_YEAR = 2000;
 export declare const DAY_START_MINUTES = 0;
 export declare const DAY_END_MINUTES: number;
 export declare function sameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
-export declare function toDay(value: Date): Date;
 export declare function minutesOf(value: Date): number;
-/** День + минуты → Date; `endOfMinute` добивает до 59.999 с. */
+/** Day + minutes → Date; `endOfMinute` fills up to 59.999 s. */
 export declare function withMinutes(day: Date, minutes: number, endOfMinute?: boolean): Date;
-/**
- * Клетка сетки месяца. `day` — день этого месяца или null для клетки соседнего месяца;
- * `outside` — дата соседнего месяца в этой клетке (для приглушённого показа).
- */
+/** A cell of the month grid: its date, and whether it belongs to the month (else it is a muted day of a neighbour). */
 export type MonthCell = {
-    day: Date | null;
-    col: number;
-    outside: Date | null;
+    date: Date;
+    inMonth: boolean;
 };
 export declare function rowsNeeded(month: Date, weekStartsOn: WeekStart): number;
-/** Строки месяца по 7 клеток; `rows` выравнивает высоту соседних месяцев. */
+/** Rows of 7 cells for a month; `rows` evens out the height of side-by-side months. */
 export declare function monthGrid(month: Date, rows: number, weekStartsOn: WeekStart): MonthCell[][];
 export declare function weekdayLabels(locale: Locale, weekStartsOn: WeekStart): string[];
 export declare function monthTitle(month: Date, locale: Locale, yearless?: boolean): string;
-/** «6 окт», «6 окт 2025» — год, только если он не текущий. */
+/** «6 окт», «6 окт 2025»: the year only when it is not the current one. */
 export declare function formatDayShort(day: Date, today: Date, locale: Locale, yearless?: boolean): string;
-/** «HH:mm» → минуты от полуночи; null — неверный формат. */
+/** "HH:mm" → minutes since midnight; `null` for an invalid format. */
 export declare function parseTime(text: string): number | null;
 export declare function formatTime(minutes: number): string;
 export type DatepickerPreset = {
     key: string;
     label: string;
-    /** Календарные дни относительно «сегодня»; from = null — без нижней границы. */
+    /** Calendar days relative to today; `from = null` — no lower bound. */
     days: (today: Date) => {
         from: Date | null;
         to: Date;
     };
 };
-/** Готовые пресеты (неделя с понедельника). Подписи можно заменить через `{ ...preset, label }`. */
+/** Ready presets (the week starts on Monday). Replace a label with `{ ...preset, label }`. */
 export declare const datepickerPresets: {
     today: {
         key: string;
@@ -112,11 +107,10 @@ export declare const datepickerPresets: {
             to: Date;
         };
     };
-    /** «Всё время»: без нижней границы или с явной датой начала. */
+    /** «Всё время»: no lower bound, or an explicit start date. */
     allTime: (start?: Date | null, label?: string) => DatepickerPreset;
 };
-/** Набор периодов по умолчанию. */
+/** The default set of periods. */
 export declare const DEFAULT_DATEPICKER_PRESETS: DatepickerPreset[];
-/** Пресет, ровно совпадающий с выбранными днями. */
+/** The preset that matches the selected days exactly. */
 export declare function matchPreset(presets: DatepickerPreset[], fromDay: Date | null, toDay: Date | null, today: Date): DatepickerPreset | null;
-//# sourceMappingURL=datepickerModel.d.ts.map

package/dist/components/datepicker/panelLayout.d.ts

@@ -0,0 +1,50 @@
+import type { ControlSize } from "@/internal/states";
+/** Buttons and fields inside the panel sit one tier below the panel (m → s, 32 = the day cell). */
+export declare const STEP_DOWN: Record<ControlSize, ControlSize>;
+/** Panel geometry in px, the same numbers the CSS lays out with. */
+export type PanelMetrics = {
+    /** Day cell: `--prime-control-<tier>-item-height`. */
+    cell: number;
+    /** Gap between months: `--prime-space-6`. */
+    monthsGap: number;
+    /** Side padding of `.main` (both sides): `space-3` in the popover, `card-padding-s` embedded. */
+    chrome: number;
+};
+/** Reads the panel geometry from the tokens on the document (theme and app overrides apply). */
+export declare function readPanelMetrics(size: ControlSize, embedded: boolean): PanelMetrics;
+export type PanelLayoutInput = {
+    /** Requested months (`months` prop). */
+    months: 1 | 2;
+    hasPresets: boolean;
+    /** Embedded panel (`Datepicker.Panel`), not the popover of `Datepicker.Root`. */
+    embedded: boolean;
+    /** Available inline size in px; `null` — not measured yet (assume it fits). */
+    available: number | null;
+    metrics: PanelMetrics;
+};
+export type PanelLayout = {
+    monthCount: 1 | 2;
+    presetsAside: boolean;
+    compact: boolean;
+};
+/**
+ * 1 vs 2 months, presets aside vs stacked, compact cells — from the space AVAILABLE to the panel
+ * (the parent's content box for an embedded panel, the viewport for the popover). The panel's own
+ * width never feeds back into the decision, so there is no resize loop. Without readable tokens
+ * (no stylesheet yet) everything is assumed to fit.
+ */
+export declare function resolvePanelLayout({ months, hasPresets, embedded, available, metrics, }: PanelLayoutInput): PanelLayout;
+/** Window width (px) — for the popover panel, which cannot measure itself. */
+export declare function useViewportWidth(enabled: boolean): number | null;
+/**
+ * The wheel over an open calendar does not scroll the page under it; scrolling areas inside (the
+ * presets list) work as usual. `overscroll-behavior: contain` is not enough: it only holds while
+ * the popover itself overflows, and a calendar that fits chains the wheel to the page.
+ */
+export declare function useContainScroll(node: HTMLElement | null): void;
+/**
+ * Available width of an embedded panel: the content box of its PARENT (ResizeObserver), not the
+ * panel's own width (that follows the content) — otherwise «1 or 2 months» would loop. `null` —
+ * not measured yet.
+ */
+export declare function useAvailableWidth(node: HTMLElement | null): number | null;

package/dist/components/digit-input/DigitInput.d.ts

@@ -1,38 +1,43 @@
+import { type FieldFrameProps, type FieldRootDomProps } from "@/internal/FieldFrame";
 import type { ControlSize } from "@/internal/states";
 export type DigitInputLabels = {
-    /** Accessible name of the group. */
+    /** Accessible name of the group when there is no visible `label`. */
     group: string;
     /** Accessible name of a cell; `{index}` (1-based) and `{length}` are replaced. */
     cell: string;
+    /** Muted marker after the label when `optional`. */
+    optional: string;
 };
-export type DigitInputRootProps = {
+export type DigitInputProps = FieldRootDomProps & FieldFrameProps & {
     /** Number of cells. */
     length?: number;
+    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
     size?: ControlSize;
+    /**
+     * Cells share the container width and grow with it (height stays the tier height, so they become
+     * wider than tall). Default `false`: square cells of the tier size, centered.
+     */
+    fullWidth?: boolean;
+    /** Name of the hidden input that carries the joined code in a native form submit. */
+    name?: string;
+    /** Splits the cells into groups of this size with a wider gap between them (`3` → 123 456). */
+    groupSize?: number;
+    /** Hides the digits (PIN): cells are `type="password"`. */
+    mask?: boolean;
+    /** Focuses the first empty cell on mount. */
+    autoFocus?: boolean;
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
     /** Called once when the last empty cell is filled. */
     onComplete?: (value: string) => void;
     disabled?: boolean;
+    /** Invalid state: danger ring on every cell. A non-empty `error` implies it. */
     invalid?: boolean;
-    /**
-     * Draws the focus ring on the focused cell (default). `false` sets `data-focus-ring="false"` on
-     * the fieldset and hides only the visual ring — focus, keyboard and ARIA are unchanged, the error
-     * ring still shows. Turn it off only where focus is otherwise obvious; WCAG 2.4.7.
-     */
-    focusRing?: boolean;
-    /** Id(s) of the hint / error text describing the group. */
+    /** Id of the first cell (the label points at it); generated when omitted. */
+    id?: string;
     "aria-describedby"?: string;
     labels?: Partial<DigitInputLabels>;
-    className?: string;
-};
-declare function DigitInputRoot({ length: lengthProp, size, value: valueProp, defaultValue, onValueChange, onComplete, disabled, invalid, focusRing, "aria-describedby": ariaDescribedBy, labels: labelsProp, className, }: DigitInputRootProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DigitInputRoot {
-    var displayName: string;
-}
-export declare const DigitInput: {
-    Root: typeof DigitInputRoot;
 };
-export {};
-//# sourceMappingURL=DigitInput.d.ts.map
+/** A one-time code or PIN split into cells, with the field label, hint and error. */
+export declare function DigitInput({ length, size: sizeProp, fullWidth, name, groupSize, mask, autoFocus, value: valueProp, defaultValue, onValueChange, onComplete, disabled, invalid, focusRing, label, required, optional, hint, error, id, "aria-describedby": ariaDescribedBy, labels: labelsProp, className, ...rest }: DigitInputProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/divider/Divider.d.ts

@@ -1,23 +1,15 @@
-import * as React from "react";
+import type * as React from "react";
 import type { ControlSize } from "@/internal/states";
 export type DividerOrientation = "horizontal" | "vertical";
 export type DividerAlign = "start" | "center" | "end";
-export type DividerRootProps = {
+export type DividerProps = React.HTMLAttributes<HTMLDivElement> & {
+    /** Default `horizontal`. */
     orientation?: DividerOrientation;
     /** Position of the label (children) on the line. Default `center`. */
     align?: DividerAlign;
+    /** Tier of the label: type, gap and icon size. Default `m`. */
     size?: ControlSize;
-    children?: React.ReactNode;
-    className?: string;
-} & React.HTMLAttributes<HTMLDivElement>;
-export declare const Divider: {
-    Root: React.ForwardRefExoticComponent<{
-        orientation?: DividerOrientation;
-        /** Position of the label (children) on the line. Default `center`. */
-        align?: DividerAlign;
-        size?: ControlSize;
-        children?: React.ReactNode;
-        className?: string;
-    } & React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+    ref?: React.Ref<HTMLDivElement>;
 };
-//# sourceMappingURL=Divider.d.ts.map
+/** A hairline with an optional label; `role="separator"` unless the consumer overrides `role`. */
+export declare function Divider({ orientation, align, size, children, className, role, ...rest }: DividerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/dnd/Dnd.d.ts

@@ -0,0 +1,135 @@
+import * as React from "react";
+import { type DragItem, type DragOutcome } from "./dragSession";
+import type { Point, Rect } from "./geometry";
+import { type DndLabels } from "./labels";
+import { type ReorderReturn } from "./useSortableList";
+export type { DragItem, DragOutcome } from "./dragSession";
+export type { DndLabels } from "./labels";
+export type { DndReorderResult } from "./useSortableList";
+export type DndRootProps = {
+    /** Built-in strings (live region, handle, role description). Russian defaults. */
+    labels?: Partial<DndLabels>;
+    children?: React.ReactNode;
+};
+/**
+ * Owns the one drag session the app shares, the overlay that follows the pointer and the live
+ * region. Mount once above every screen that drags: a drag crosses component boundaries.
+ */
+declare function DndRoot({ labels, children }: DndRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DndRoot {
+    var displayName: string;
+}
+export type DndHandleProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/**
+ * The grip of a `handle` item: a ghost icon-only Button (`xs`), so it is reachable by keyboard
+ * (Alt+arrows reorder).
+ */
+declare function DndHandle({ className, "aria-label": ariaLabel, ref, ...rest }: DndHandleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DndHandle {
+    var displayName: string;
+}
+export type DndSortableProps<T> = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
+    /** Items in their current order. */
+    items: readonly T[];
+    /** Stable unique id of an item. */
+    getId: (item: T) => string;
+    /** Spoken by the live region ("Задача 3: позиция 2 из 5"). Defaults to the id. */
+    getLabel?: (item: T) => string;
+    /** Called when an item lands in front of `beforeId` (`null` = last). Return `{ ok: false }` (or reject) to roll the drawn order back. */
+    onReorder: (id: string, beforeId: string | null) => ReorderReturn | Promise<ReorderReturn>;
+    /** Renders one item; return a `Dnd.SortableItem`. */
+    renderItem: (item: T, index: number) => React.ReactNode;
+    /** Layout direction of the list. */
+    axis?: "x" | "y";
+    /** Only `Dnd.Handle` starts a drag; the rest of the item stays free for clicks and text selection. */
+    handle?: boolean;
+    disabled?: boolean;
+    /**
+     * Drag kind. Lists sharing a `kind` exchange items: an item dropped from another list arrives in
+     * `onReorder` with an `id` that is not in `items` (move it into this list). Defaults to a unique
+     * value per list, so lists stay separate.
+     */
+    kind?: string;
+    /** Refuses an item (by id) the list would otherwise take; the list turns `danger` before the release. */
+    canDrop?: (id: string) => boolean;
+    /** Root element: `ul` / `ol` turn items into `li`. */
+    as?: "div" | "ul" | "ol";
+    /** Accessible name of the list. */
+    "aria-label"?: string;
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * A reorderable list: pointer drag with a gap where the item lands, neighbours that glide aside, an
+ * optimistic order, auto-scroll near the edges and an Alt+arrow keyboard path.
+ */
+declare function DndSortable<T>({ items, getId, getLabel, onReorder, renderItem, axis, handle, disabled, kind, canDrop, as: Tag, className, ref: forwardedRef, ...rest }: DndSortableProps<T>): import("react/jsx-runtime").JSX.Element;
+declare namespace DndSortable {
+    var displayName: string;
+}
+export type DndSortableItemProps = {
+    /** Must match `getId` of the item. */
+    id: string;
+    disabled?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+} & Omit<React.HTMLAttributes<HTMLElement>, "id">;
+/** One item of a `Dnd.Sortable`. Renders `li` inside `ul` / `ol`, `div` otherwise. */
+declare function DndSortableItem({ id, disabled: itemDisabled, className, children, onPointerDown, onKeyDown, ref, ...rest }: DndSortableItemProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DndSortableItem {
+    var displayName: string;
+}
+export type DndDraggableProps<TData = unknown> = {
+    /** What is dragged; a `Dnd.DropZone` accepts it by kind. */
+    kind: string;
+    id: string;
+    /** Payload handed to the drop target. */
+    data?: TData;
+    /** Spoken by the live region. Defaults to the id. */
+    label?: string;
+    disabled?: boolean;
+    /** Only `Dnd.Handle` starts a drag. */
+    handle?: boolean;
+    as?: "div" | "li" | "span" | "article" | "section";
+    onDragStart?: (item: DragItem<TData>, point: Point, origin: Rect) => void;
+    onDragEnd?: (item: DragItem<TData>, outcome: DragOutcome) => void;
+    className?: string;
+    children?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+} & Omit<React.HTMLAttributes<HTMLElement>, "id">;
+/** Something to carry onto a `Dnd.DropZone`. The source stays in place, faded, until the drop. */
+declare function DndDraggable<TData = unknown>({ kind, id, data, label, disabled, handle, as: Tag, onDragStart, onDragEnd, className, children, onPointerDown, ref, ...rest }: DndDraggableProps<TData>): import("react/jsx-runtime").JSX.Element;
+declare namespace DndDraggable {
+    var displayName: string;
+}
+export type DndDropZoneProps<TData = unknown> = {
+    /** Drag kinds this zone takes, or a predicate over the dragged item. */
+    accepts: string | readonly string[] | ((item: DragItem) => boolean);
+    onDrop: (item: DragItem<TData>) => void;
+    /** Refuses an item the zone would otherwise take; the zone turns `danger` before the release. */
+    canDrop?: (item: DragItem<TData>) => boolean;
+    onEnter?: (item: DragItem<TData>) => void;
+    onLeave?: () => void;
+    /** Flashes the zone after a drop, so the eye can follow where the item went. */
+    flashOnDrop?: boolean;
+    disabled?: boolean;
+    as?: "div" | "section" | "li" | "ul" | "ol" | "span";
+    className?: string;
+    children?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+} & Omit<React.HTMLAttributes<HTMLElement>, "onDrop">;
+/** A box that takes dropped items. `data-dnd-over` / `data-dnd-reject` / `data-dnd-flash` mirror its state. */
+declare function DndDropZone<TData = unknown>({ accepts, onDrop, canDrop, onEnter, onLeave, flashOnDrop, disabled, as: Tag, className, children, onAnimationEnd, ref: forwardedRef, ...rest }: DndDropZoneProps<TData>): import("react/jsx-runtime").JSX.Element;
+declare namespace DndDropZone {
+    var displayName: string;
+}
+export declare const Dnd: {
+    Root: typeof DndRoot;
+    Sortable: typeof DndSortable;
+    SortableItem: typeof DndSortableItem;
+    Draggable: typeof DndDraggable;
+    DropZone: typeof DndDropZone;
+    Handle: typeof DndHandle;
+};

package/dist/components/dnd/DragOverlay.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+import type { DragController } from "./dragSession";
+/** The piece that follows the pointer: a clone of the lifted element above every layer. Mounted once by `Dnd.Root`. */
+export declare function DragOverlay({ controller }: {
+    controller: DragController;
+}): React.ReactPortal | null;

package/dist/components/dnd/autoScroll.d.ts

@@ -0,0 +1,5 @@
+import { type Point } from "./geometry";
+/** Scrollable boxes between `element` and the root, innermost first: a list that can still scroll wins over the page. */
+export declare function scrollableAncestors(element: Element | null): HTMLElement[];
+/** Scrolls the innermost container that wants to move and still can. Returns whether anything moved. */
+export declare function autoScrollStep(containers: HTMLElement[], point: Point, elapsedMs: number): boolean;

package/dist/components/dnd/context.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+import { type DragController } from "./dragSession";
+export declare const DragControllerContext: React.Context<DragController | null>;
+/** The one drag session every drag hook runs in, mounted by `Dnd.Root`. */
+export declare function useDragController(): DragController;

package/dist/components/dnd/dragSession.d.ts

@@ -0,0 +1,93 @@
+import { type Point, type Rect } from "./geometry";
+import { type DndLabels } from "./labels";
+import { type Store } from "./store";
+/**
+ * Every gesture runs on pointer events, mouse and finger alike. The HTML5 drag-and-drop API is not
+ * used: it never fires from touch, its preview cannot be styled, and its drop delivery depends on a
+ * preventDefault on the last dragover. One pointer path means one set of rules everywhere.
+ */
+export type PointerKind = "mouse" | "touch" | "pen";
+export type DragItem<TData = unknown> = {
+    /** What is dragged, matched against a target's `accepts`. Unrelated screens never see each other's drags. */
+    kind: string;
+    id: string;
+    data: TData;
+    /** Spoken by the live region; written for someone who cannot see where the item went. */
+    label: string;
+};
+export type DragSnapshot = {
+    item: DragItem | null;
+    pointerKind: PointerKind | null;
+    /** The drop target the pointer is over right now, by registered id. */
+    overId: string | null;
+    canDrop: boolean;
+    /** The rect the lifted element occupied when the drag began: the size of the gap a list opens for it. */
+    origin: Rect | null;
+    /** Where inside that rect the pointer grabbed it. */
+    grab: Point | null;
+    /** The lifted element's `border-radius`, so the gap it leaves is shaped like it. */
+    radius: string | null;
+    /** The live region text; `sequence` makes a repeated message count as new for assistive technology. */
+    announcement: {
+        message: string;
+        sequence: number;
+    };
+};
+export declare const IDLE_SNAPSHOT: DragSnapshot;
+export type DropTargetEntry = {
+    id: string;
+    element: HTMLElement;
+    accepts: (item: DragItem) => boolean;
+    enter: (item: DragItem) => void;
+    /** Called on every resolved pointer position; returns whether a drop here would be accepted. */
+    over: (point: Point, item: DragItem) => boolean;
+    leave: () => void;
+    drop: (point: Point, item: DragItem) => void;
+};
+export type DragPreview = {
+    /** The element the gesture started on, cloned by the overlay. */
+    element: HTMLElement;
+    origin: Rect;
+    /** Where inside the element the pointer grabbed it: the same pixel stays under the finger. */
+    grab: Point;
+    point: Point;
+    pointerKind: PointerKind;
+};
+export type DragOverlayEvent = {
+    type: "start";
+    preview: DragPreview;
+} | {
+    type: "move";
+    point: Point;
+} | {
+    type: "end";
+    item: DragItem;
+    outcome: DragOutcome;
+    origin: Rect | null;
+};
+/**
+ * How a drag ended. `release` is not `cancel`: the pointer was let go deliberately, just not over a
+ * target that took it. `cancel` (Escape, a system-cancelled pointer) means the move was taken back.
+ */
+export type DragOutcome = "drop" | "release" | "cancel";
+export type BeginDragParams<TData> = {
+    event: PointerEvent;
+    /** The element the drag lifts: the whole card, even when the press landed on a handle inside it. */
+    element: HTMLElement;
+    item: DragItem<TData>;
+    /** Fired once the press became a drag, with the press point and the rect the item occupied. */
+    onDragStart?(item: DragItem<TData>, point: Point, origin: Rect): void;
+    onDragEnd?(item: DragItem<TData>, outcome: DragOutcome): void;
+};
+export type DragController = {
+    store: Store<DragSnapshot>;
+    registerTarget: (entry: DropTargetEntry) => () => void;
+    beginPointerDrag: <TData>(params: BeginDragParams<TData>) => void;
+    /** Speaks through the live region without a pointer drag in flight (the keyboard path). */
+    announce: (message: string) => void;
+    labels: () => DndLabels;
+    cancel: () => void;
+    subscribeOverlay: (listener: (event: DragOverlayEvent) => void) => () => void;
+    destroy: () => void;
+};
+export declare function createDragController(getLabels?: () => DndLabels): DragController;

package/dist/components/dnd/geometry.d.ts

@@ -0,0 +1,30 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+export type Rect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+export type Axis = "x" | "y";
+export declare function rectOf(element: Element): Rect;
+/**
+ * Where an element sits in the layout with any animation transform taken back out. Every drop
+ * decision is measured against this: reading the drawn position makes each answer depend on the
+ * animation the previous answer started, and the gap flickers under a pointer that barely moves.
+ */
+export declare function layoutRect(element: Element): Rect;
+export declare function rectContains(rect: Rect, point: Point): boolean;
+export declare function distanceBetween(a: Point, b: Point): number;
+/** Marks the gap a sortable list opens where the dragged item will land. */
+export declare const DROP_GAP_SELECTOR = "[data-dnd-gap]";
+/**
+ * The item a dragged one would land in front of: the first whose midline is past the pointer, or
+ * `null` for "after every item". Measured in the layout the list would have WITHOUT the gap, so the
+ * answer depends only on the pointer, never on where the gap currently stands.
+ */
+export declare function insertionBefore(container: Element, itemSelector: string, point: Point, axis?: Axis, liftedId?: string): string | null;

package/dist/components/dnd/labels.d.ts

@@ -0,0 +1,18 @@
+/** System strings of the drag-and-drop layer. `{label}`, `{position}`, `{total}` are substituted. */
+export type DndLabels = {
+    /** `aria-label` of `Dnd.Handle`. */
+    handle: string;
+    /** `aria-roledescription` of every draggable element. */
+    roleDescription: string;
+    /** Live region: an item was picked up. */
+    grabbed: string;
+    /** Live region: an item was dropped on a target. */
+    dropped: string;
+    /** Live region: an item was released over nothing and went back. */
+    returned: string;
+    /** Live region: the drag was cancelled (Escape, system interruption). */
+    cancelled: string;
+    /** Live region: an item was moved with the keyboard. */
+    moved: string;
+};
+export declare const defaultDndLabels: DndLabels;

package/dist/components/dnd/store.d.ts

@@ -0,0 +1,9 @@
+export type Store<T> = {
+    getSnapshot: () => T;
+    subscribe: (listener: () => void) => () => void;
+    setState: (update: (current: T) => T) => void;
+};
+/** A plain store outside React: the drag session outlives any one component and is shared by many. */
+export declare function createStore<T>(initial: T): Store<T>;
+/** Subscribes to a slice of a store. `select` must return a primitive or a stable reference. */
+export declare function useStoreSelector<T, S>(store: Store<T>, select: (state: T) => S): S;