prime-ui-kit 0.9.0 → 0.9.1

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

@@ -0,0 +1,36 @@
+import * as React from "react";
+import type { DragItem, DragOutcome } from "./dragSession";
+import type { Point, Rect } from "./geometry";
+export type DragSourceItem<TData> = {
+    id: string;
+    data: TData;
+    /** What the live region says about the item. */
+    label: string;
+};
+export type DragSourceProps = {
+    "data-dnd-item": string;
+    "data-dragging"?: true | undefined;
+    "aria-roledescription"?: string | undefined;
+    onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
+};
+export type DragSourceOptions<TData> = {
+    kind: string;
+    disabled?: boolean | undefined;
+    /** Only a press on a `[data-dnd-handle]` element starts the drag. */
+    handleOnly?: boolean | undefined;
+    onDragStart?(item: DragItem<TData>, point: Point, origin: Rect): void;
+    onDragEnd?(item: DragItem<TData>, outcome: DragOutcome): void;
+};
+export type DragSourceHandle<TData> = {
+    /** The id in flight from THIS source kind, or null. */
+    draggingId: string | null;
+    /** Stable between renders while `draggingId` and `disabled` stay the same. */
+    props: (item: DragSourceItem<TData>) => DragSourceProps;
+};
+/**
+ * Turns any element into a drag source without a ref and without a component of its own: the element
+ * comes from the press itself, so a list built in `.map()` needs one hook, not one component per row.
+ */
+export declare function useDragSource<TData = unknown>(options: DragSourceOptions<TData>): DragSourceHandle<TData>;
+/** What is in flight right now, for components that react to a drag they did not start. */
+export declare function useDraggedItem(kind: string): DragItem | null;

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

@@ -0,0 +1,39 @@
+import * as React from "react";
+import type { DragItem } from "./dragSession";
+import type { Point } from "./geometry";
+export type DropTargetOptions<TValue, TData = unknown> = {
+    /** Which drag kinds this target answers to. */
+    accepts: string | readonly string[] | ((item: DragItem) => boolean);
+    /** Turns a pointer position into what a drop here would mean (an insertion point, a slot number). `null` means "not over anything droppable". */
+    resolve: (point: Point, item: DragItem<TData>, element: HTMLElement) => TValue | null;
+    /** Whether the resolved spot will take this item. Separate from `resolve` so a preview can still be drawn where the refusal is. */
+    canDrop?: ((value: TValue, item: DragItem<TData>) => boolean) | undefined;
+    onDrop: (value: TValue, item: DragItem<TData>) => void;
+    disabled?: boolean | undefined;
+    onEnter?: ((item: DragItem<TData>) => void) | undefined;
+    onLeave?: (() => void) | undefined;
+    /** Flashes the target once a drop lands, so the eye can follow where the item went. */
+    flashOnDrop?: boolean | undefined;
+};
+export type DropTargetProps = {
+    ref: React.RefCallback<HTMLElement | null>;
+    "data-dnd-over"?: true | undefined;
+    "data-dnd-reject"?: true | undefined;
+    "data-dnd-flash"?: true | undefined;
+    /** Ends the drop flash when its animation finishes. */
+    onAnimationEnd: (event: React.AnimationEvent<HTMLElement>) => void;
+};
+export type DropTargetHandle = {
+    /** The id the target registered under; `DragSnapshot.overId` names it while the pointer is over. */
+    id: string;
+    /** True while a pointer carrying an accepted item is inside, whether or not the spot can take a drop. */
+    isOver: boolean;
+    /** The registered element, for callers that also measure it. */
+    element: HTMLElement | null;
+    props: DropTargetProps;
+};
+/**
+ * Registers an element as somewhere a drag can land. The target owns the meaning of a drop. Only
+ * «over / can drop» is React state: a pointer move that changes neither re-renders nothing.
+ */
+export declare function useDropTarget<TValue, TData = unknown>(options: DropTargetOptions<TValue, TData>): DropTargetHandle;

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

@@ -0,0 +1,11 @@
+/**
+ * WAAPI timing from the motion tokens (`--prime-motion-duration-<token>`,
+ * `--prime-motion-easing-standard`), read at animation time so theme and app overrides apply;
+ * WAAPI cannot take `var()`.
+ */
+export declare function motionTiming(duration: "fast" | "base"): KeyframeAnimationOptions;
+/**
+ * Animates layout changes of list items from the position currently on screen. Hit testing still uses
+ * `layoutRect`, so visual easing never changes a drop decision.
+ */
+export declare function useFlipList(container: HTMLElement | null, layoutKey: string, selector: string, enabled: boolean): void;

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

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { type Axis } from "./geometry";
+import { type DragSourceProps } from "./useDragSource";
+import { type DropTargetProps } from "./useDropTarget";
+/**
+ * Where a dragged item would land: in front of `before`, or last when that is null. `moves` is false
+ * while that answer is the place the item already occupies: the gap is still drawn there (the lifted
+ * item is out of the layout), but nothing is reordered.
+ */
+export type InsertionPoint = {
+    before: string | null;
+    moves: boolean;
+};
+/** What a caller's own write may answer. Answering is optional; `{ ok: false }` rolls the drawn order back at once. */
+export type DndReorderResult = {
+    ok: boolean;
+} | undefined;
+export type ReorderReturn = DndReorderResult | void;
+export type SortableListOptions = {
+    kind: string;
+    /** The ids in the order they are drawn. */
+    items: readonly string[];
+    labelOf: (id: string) => string;
+    onReorder: (id: string, beforeId: string | null) => ReorderReturn | Promise<ReorderReturn>;
+    axis?: Axis | undefined;
+    disabled?: boolean | undefined;
+    /** Refuses an item of this kind (typically one from another list); the container turns `danger` before the release. */
+    canDrop?: ((id: string) => boolean) | undefined;
+    /** Only a press on a `[data-dnd-handle]` element starts a drag. */
+    handleOnly?: boolean | undefined;
+};
+export type SortableItemProps = DragSourceProps & {
+    "data-lifted"?: true | undefined;
+    onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
+};
+export type SortableListHandle = {
+    containerProps: DropTargetProps;
+    itemProps: (id: string) => SortableItemProps;
+    draggingId: string | null;
+    /** The item the gap precedes; null means the end, undefined means idle. */
+    gapBefore: string | null | undefined;
+    /** The hole the lifted item left, in px. Set only while a drag is in flight. */
+    gap: {
+        width: number;
+        height: number;
+        radius: string | null;
+    } | null;
+    isOver: boolean;
+    /**
+     * The order to DRAW: `items`, except right after a drop, when the owner answers a beat later and
+     * drawing the old order until then would snap the item back and then jump again.
+     */
+    order: readonly string[];
+};
+/** `items` with `id` pulled out and put in front of `beforeId`, or last when that is null. */
+export declare function moveBefore<T>(items: readonly T[], id: string, beforeId: string | null, getId: (item: T) => string): T[];
+/**
+ * Reordering, complete: the pointer drag, the gap that opens where the item will land, the settle
+ * animation, and an Alt+arrow path for anyone who cannot drag (WCAG 2.2 "Dragging Movements").
+ * The list container is the drop target, not each item: items come and go mid-drag.
+ */
+export declare function useSortableList(options: SortableListOptions): SortableListHandle;

package/dist/components/drawer/Drawer.d.ts

@@ -1,7 +1,7 @@
-import * as React from "react";
-import { DialogBody, DialogClose, DialogDescription, DialogFooter, DialogHeader, DialogIcon, DialogTitle } from "@/components/modal/DialogParts";
+import type * as React from "react";
+import { DialogBody, DialogClose, DialogDescription, DialogFooter, DialogHeader, DialogIcon, DialogTitle, DialogTrigger } from "@/components/modal/DialogParts";
 import type { ControlSize } from "@/internal/states";
-export type { DialogBodyProps as DrawerBodyProps, DialogCloseProps as DrawerCloseProps, DialogDescriptionProps as DrawerDescriptionProps, DialogFooterProps as DrawerFooterProps, DialogHeaderProps as DrawerHeaderProps, DialogIconProps as DrawerIconProps, DialogTitleProps as DrawerTitleProps, } from "@/components/modal/DialogParts";
+export type { DialogBodyProps as DrawerBodyProps, DialogCloseProps as DrawerCloseProps, DialogDescriptionProps as DrawerDescriptionProps, DialogFooterProps as DrawerFooterProps, DialogHeaderProps as DrawerHeaderProps, DialogIconProps as DrawerIconProps, DialogTitleProps as DrawerTitleProps, DialogTriggerProps as DrawerTriggerProps, } from "@/components/modal/DialogParts";
 export type DrawerSide = "left" | "right";
 export type DrawerLabels = {
     /** `aria-label` of the header close button. */
@@ -13,27 +13,15 @@ export type DrawerRootProps = {
     onOpenChange?: (open: boolean) => void;
     /** Escape closes the drawer. Default `true`. */
     closeOnEscape?: boolean;
-    /** A click on the scrim (any pointerdown outside the panel) closes the drawer. Default `true`. */
+    /** A click on the scrim closes the drawer. Default `true`. */
     closeOnOutsideClick?: boolean;
     labels?: Partial<DrawerLabels>;
     children?: React.ReactNode;
 };
-declare function DrawerRoot({ open, defaultOpen, onOpenChange, closeOnEscape, closeOnOutsideClick, labels, children, }: DrawerRootProps): import("react/jsx-runtime").JSX.Element;
+declare function DrawerRoot({ labels, children, ...options }: DrawerRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DrawerRoot {
     var displayName: string;
 }
-export type DrawerTriggerProps = {
-    children: React.ReactElement<{
-        onClick?: React.MouseEventHandler;
-    }>;
-};
-/** Opens the drawer on the child's click (unless the child prevents default). */
-declare function DrawerTrigger({ children }: DrawerTriggerProps): React.ReactElement<{
-    onClick?: React.MouseEventHandler;
-}, string | React.JSXElementConstructor<any>>;
-declare namespace DrawerTrigger {
-    var displayName: string;
-}
 export type DrawerContentProps = React.HTMLAttributes<HTMLDivElement> & {
     /** Edge the panel slides from. Default `right`. */
     side?: DrawerSide;
@@ -41,6 +29,8 @@ export type DrawerContentProps = React.HTMLAttributes<HTMLDivElement> & {
     size?: Exclude<ControlSize, "xs">;
     /** Class on the full-screen scrim. */
     overlayClassName?: string;
+    /** The `role="dialog"` panel. */
+    ref?: React.Ref<HTMLDivElement>;
 };
 declare function DrawerContent(props: DrawerContentProps): import("react/jsx-runtime").JSX.Element | null;
 declare namespace DrawerContent {
@@ -48,7 +38,7 @@ declare namespace DrawerContent {
 }
 export declare const Drawer: {
     Root: typeof DrawerRoot;
-    Trigger: typeof DrawerTrigger;
+    Trigger: typeof DialogTrigger;
     Content: typeof DrawerContent;
     Header: typeof DialogHeader;
     Icon: typeof DialogIcon;
@@ -58,4 +48,3 @@ export declare const Drawer: {
     Footer: typeof DialogFooter;
     Close: typeof DialogClose;
 };
-//# sourceMappingURL=Drawer.d.ts.map

package/dist/components/dropdown/Dropdown.d.ts

@@ -1,143 +1,120 @@
 import * as React from "react";
 import type { PositionAlign, PositionSide } from "@/hooks/usePosition";
+import { type MenuGroupProps } from "@/internal/MenuGroup";
 import type { ControlSize, Tone } from "@/internal/states";
 export type DropdownRootProps = {
     open?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
-    /** A pointerdown outside the panel and its trigger closes it. Default `true`. */
+    /** A pointerdown outside the menu and its trigger closes it. Default `true`. */
     closeOnOutsideClick?: boolean;
+    /** Escape closes the menu. Default `true`. */
+    closeOnEscape?: boolean;
     children: React.ReactNode;
 };
-declare function DropdownRoot({ open, defaultOpen, onOpenChange, closeOnOutsideClick, children, }: DropdownRootProps): import("react/jsx-runtime").JSX.Element;
+declare function DropdownRoot({ open, defaultOpen, onOpenChange, closeOnOutsideClick, closeOnEscape, children, }: DropdownRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownRoot {
     var displayName: string;
 }
 export type DropdownTriggerProps = {
-    /** The element that opens the panel (usually a Button); it receives ref, ARIA and the click handler. */
+    /** The element that opens the menu (usually a Button); it receives ref, ARIA and the click handler. */
     children: React.ReactElement;
-};
-declare function DropdownTrigger({ children }: DropdownTriggerProps): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+    ref?: React.Ref<HTMLElement>;
+} & Omit<React.HTMLAttributes<HTMLElement>, "children">;
+/** Other props (handlers, ARIA, `ref`) are forwarded to the child, e.g. from a wrapping `Tooltip.Trigger`. */
+declare function DropdownTrigger({ children, ...forwarded }: DropdownTriggerProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownTrigger {
     var displayName: string;
 }
-export type DropdownContentProps = {
-    align?: PositionAlign;
+export type DropdownContentProps = Omit<React.HTMLAttributes<HTMLElement>, "role"> & {
     side?: PositionSide;
-    sameMinWidthAsTrigger?: boolean;
+    align?: PositionAlign;
+    /** Row tier: item height, text, icon. */
     size?: ControlSize;
-    children: React.ReactNode;
-    className?: string;
+    /** The menu is at least as wide as the trigger. */
+    matchTriggerWidth?: boolean;
+    ref?: React.Ref<HTMLDivElement>;
 };
-declare function DropdownContent({ align, side, sameMinWidthAsTrigger, size, children, className, }: DropdownContentProps): import("react/jsx-runtime").JSX.Element | null;
+declare function DropdownContent({ side, align, size, matchTriggerWidth, className, children, onKeyDown, ...rest }: DropdownContentProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownContent {
     var displayName: string;
 }
-export type DropdownItemProps = {
+export type DropdownItemProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "role" | "onSelect"> & {
+    /** Runs the action; the menu closes after it. */
     onSelect?: () => void;
     disabled?: boolean;
-    /** `danger` — destructive action (delete, revoke). Default `neutral`. */
+    /** `danger` — destructive action (delete, revoke). */
     tone?: Extract<Tone, "neutral" | "danger">;
-    children: React.ReactNode;
-    className?: string;
+    ref?: React.Ref<HTMLButtonElement>;
 };
-declare function DropdownItem({ onSelect, disabled, tone, children, className, }: DropdownItemProps): import("react/jsx-runtime").JSX.Element;
+declare function DropdownItem({ onSelect, disabled, tone, className, onClick, ...rest }: DropdownItemProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownItem {
     var displayName: string;
 }
-export type DropdownItemIconProps = {
-    as?: React.ElementType;
-    className?: string;
-    children?: React.ReactNode;
-} & Record<string, unknown>;
-export type DropdownItemShortcutProps = React.HTMLAttributes<HTMLElement>;
-/** Сочетание клавиш справа в пункте (стиль Kbd, приглушённый). Только подсказка — не обработчик. */
-declare function DropdownItemShortcut({ className, ...rest }: DropdownItemShortcutProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownItemShortcut {
-    var displayName: string;
-}
-export type DropdownGroupProps = React.HTMLAttributes<HTMLDivElement>;
-declare function DropdownGroup({ className, ...rest }: DropdownGroupProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownGroup {
-    var displayName: string;
-}
-export type DropdownGroupLabelProps = {
-    children: React.ReactNode;
-    className?: string;
+type DivProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
 };
-declare function DropdownGroupLabel({ children, className }: DropdownGroupLabelProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownGroupLabel {
-    var displayName: string;
-}
-export type DropdownSeparatorProps = {
-    className?: string;
+export type DropdownItemIconProps = React.HTMLAttributes<HTMLSpanElement> & {
+    ref?: React.Ref<HTMLSpanElement>;
 };
-declare function DropdownSeparator({ className }: DropdownSeparatorProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownSeparator {
+/** Leading glyph of an item at the menu's icon size (a kit `Icon` follows it). */
+declare function DropdownItemIcon({ className, ...rest }: DropdownItemIconProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownItemIcon {
     var displayName: string;
 }
-export type DropdownBlockProps = React.HTMLAttributes<HTMLDivElement>;
-declare function DropdownBlock({ className, ...rest }: DropdownBlockProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownBlock {
-    var displayName: string;
-}
-export type DropdownHeaderProps = React.HTMLAttributes<HTMLDivElement>;
-declare function DropdownHeader({ className, ...rest }: DropdownHeaderProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownHeader {
-    var displayName: string;
-}
-export type DropdownHeaderRowProps = React.HTMLAttributes<HTMLDivElement>;
-declare function DropdownHeaderRow({ className, ...rest }: DropdownHeaderRowProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownHeaderRow {
+export type DropdownItemShortcutProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
+    children: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+};
+/** Key hint at the end of an item (a Kbd one tier below the menu). A hint only — not a handler. */
+declare function DropdownItemShortcut({ className, ...rest }: DropdownItemShortcutProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownItemShortcut {
     var displayName: string;
 }
-export type DropdownHeaderLeadingProps = React.HTMLAttributes<HTMLDivElement>;
-declare function DropdownHeaderLeading({ className, ...rest }: DropdownHeaderLeadingProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownHeaderLeading {
+export type DropdownGroupProps = MenuGroupProps;
+declare function DropdownGroup(props: DropdownGroupProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownGroup {
     var displayName: string;
 }
-export type DropdownHeaderMainProps = React.HTMLAttributes<HTMLDivElement>;
-declare function DropdownHeaderMain({ className, ...rest }: DropdownHeaderMainProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownHeaderMain {
+export type DropdownSeparatorProps = Omit<DivProps, "children">;
+/** A full-bleed hairline between items or groups. */
+declare function DropdownSeparator({ className, ...rest }: DropdownSeparatorProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownSeparator {
     var displayName: string;
 }
-export type DropdownHeaderTitleProps = React.HTMLAttributes<HTMLDivElement>;
-declare function DropdownHeaderTitle({ className, ...rest }: DropdownHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownHeaderTitle {
+export type DropdownTitleProps = DivProps;
+/** Heading line of `Dropdown.Header` (a name, a plan). */
+declare function DropdownTitle({ className, ...rest }: DropdownTitleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownTitle {
     var displayName: string;
 }
-export type DropdownHeaderDescriptionProps = React.HTMLAttributes<HTMLDivElement> & {
-    truncate?: boolean;
-};
-declare function DropdownHeaderDescription({ className, truncate, ...rest }: DropdownHeaderDescriptionProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownHeaderDescription {
+export type DropdownDescriptionProps = DivProps;
+/** Muted line under `Dropdown.Title` (an email, a quota); truncates with an ellipsis. */
+declare function DropdownDescription({ className, ...rest }: DropdownDescriptionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownDescription {
     var displayName: string;
 }
-export type DropdownHeaderTrailingProps = React.HTMLAttributes<HTMLDivElement> & {
-    alignSelf?: "start" | "center";
-};
-declare function DropdownHeaderTrailing({ className, alignSelf, ...rest }: DropdownHeaderTrailingProps): import("react/jsx-runtime").JSX.Element;
-declare namespace DropdownHeaderTrailing {
+export type DropdownHeaderProps = DivProps;
+/**
+ * A non-interactive row at the top of the menu (who is signed in, the current plan): an avatar or
+ * icon, `Dropdown.Title` + `Dropdown.Description` stacked in one column, and a trailing badge or
+ * button — in the order written.
+ */
+declare function DropdownHeader({ className, children, ...rest }: DropdownHeaderProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownHeader {
     var displayName: string;
 }
 export declare const Dropdown: {
     Root: typeof DropdownRoot;
     Trigger: typeof DropdownTrigger;
     Content: typeof DropdownContent;
-    Block: typeof DropdownBlock;
     Header: typeof DropdownHeader;
-    HeaderRow: typeof DropdownHeaderRow;
-    HeaderLeading: typeof DropdownHeaderLeading;
-    HeaderMain: typeof DropdownHeaderMain;
-    HeaderTitle: typeof DropdownHeaderTitle;
-    HeaderDescription: typeof DropdownHeaderDescription;
-    HeaderTrailing: typeof DropdownHeaderTrailing;
+    Title: typeof DropdownTitle;
+    Description: typeof DropdownDescription;
+    Group: typeof DropdownGroup;
     Item: typeof DropdownItem;
-    ItemIcon: React.ForwardRefExoticComponent<Omit<DropdownItemIconProps, "ref"> & React.RefAttributes<HTMLElement>>;
+    ItemIcon: typeof DropdownItemIcon;
     ItemShortcut: typeof DropdownItemShortcut;
-    Group: typeof DropdownGroup;
-    GroupLabel: typeof DropdownGroupLabel;
     Separator: typeof DropdownSeparator;
 };
 export {};
-//# sourceMappingURL=Dropdown.d.ts.map

package/dist/components/empty-page/EmptyPage.d.ts

@@ -1,64 +1,64 @@
-import * as React from "react";
+import type * as React from "react";
 import type { ControlSize, Tone } from "@/internal/states";
-export type EmptyPageRootProps = {
-    /** Высота контролов, кегль и отступы; по умолчанию `m`. */
+type EmptyPageLayout = "default" | "fill" | "compact";
+export type EmptyPageRootProps = React.HTMLAttributes<HTMLDivElement> & {
+    /** Control height, type and spacing tier. Default `m`. */
     size?: ControlSize;
     /**
-     * `fill` — блок растягивается по высоте родителя и центрирует содержимое (пустое состояние внутри таблицы, скролла, карточки).
-     * `default` — компактный блок по содержимому.
+     * `default` — a block sized by its content.
+     * `fill` — stretches to the parent's height and centers the content (inside a table, a scroll area, a card).
+     * `compact` — a quiet state inside a menu, listbox or command list: panel padding, body-s title,
+     * caption description, a small icon and no entrance motion.
      */
-    layout?: "default" | "fill";
-    className?: string;
-    children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-export type EmptyPageIconProps = {
-    /** Подложка иконки: `neutral` (по умолчанию), `accent` — приглашение к действию, `danger` — ошибка. */
+    layout?: EmptyPageLayout;
+    ref?: React.Ref<HTMLDivElement>;
+};
+/** Parts rise in on first render, except in `compact` (it appears on every keystroke). */
+declare function EmptyPageRoot({ size, layout, className, children, ...rest }: EmptyPageRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace EmptyPageRoot {
+    var displayName: string;
+}
+export type EmptyPageIconProps = React.HTMLAttributes<HTMLDivElement> & {
+    /** Tile fill: `neutral` (default), `accent` — an invitation to start, `danger` — a failure. */
     tone?: Extract<Tone, "neutral" | "accent" | "danger">;
-    className?: string;
-    children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-declare function EmptyPageIcon({ tone, className, children, ...rest }: EmptyPageIconProps): import("react/jsx-runtime").JSX.Element;
+    ref?: React.Ref<HTMLDivElement>;
+};
+declare function EmptyPageIcon({ tone, className, ...rest }: EmptyPageIconProps): import("react/jsx-runtime").JSX.Element;
 declare namespace EmptyPageIcon {
     var displayName: string;
 }
-export type EmptyPageTitleProps = {
-    className?: string;
-    children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-export type EmptyPageDescriptionProps = {
-    className?: string;
-    children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLParagraphElement>;
-export type EmptyPageActionsProps = {
-    className?: string;
-    children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-declare function EmptyPageActions({ className, children, ...rest }: EmptyPageActionsProps): import("react/jsx-runtime").JSX.Element;
+type EmptyPageTitleAs = "h2" | "h3" | "h4" | "p";
+export type EmptyPageTitleProps = React.HTMLAttributes<HTMLElement> & {
+    /**
+     * Tag that fits the outline; the look does not change. `p` inside menus, lists and table cells,
+     * where a heading would break the page outline.
+     */
+    as?: EmptyPageTitleAs;
+    ref?: React.Ref<HTMLElement>;
+};
+declare function EmptyPageTitle({ as: Tag, className, ref, ...rest }: EmptyPageTitleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace EmptyPageTitle {
+    var displayName: string;
+}
+export type EmptyPageDescriptionProps = React.HTMLAttributes<HTMLParagraphElement> & {
+    ref?: React.Ref<HTMLParagraphElement>;
+};
+declare function EmptyPageDescription({ className, ...rest }: EmptyPageDescriptionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace EmptyPageDescription {
+    var displayName: string;
+}
+export type EmptyPageActionsProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+declare function EmptyPageActions({ className, ...rest }: EmptyPageActionsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace EmptyPageActions {
     var displayName: string;
 }
 export declare const EmptyPage: {
-    Root: React.ForwardRefExoticComponent<{
-        /** Высота контролов, кегль и отступы; по умолчанию `m`. */
-        size?: ControlSize;
-        /**
-         * `fill` — блок растягивается по высоте родителя и центрирует содержимое (пустое состояние внутри таблицы, скролла, карточки).
-         * `default` — компактный блок по содержимому.
-         */
-        layout?: "default" | "fill";
-        className?: string;
-        children?: React.ReactNode;
-    } & React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+    Root: typeof EmptyPageRoot;
     Icon: typeof EmptyPageIcon;
-    Title: React.ForwardRefExoticComponent<{
-        className?: string;
-        children?: React.ReactNode;
-    } & React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLHeadingElement>>;
-    Description: React.ForwardRefExoticComponent<{
-        className?: string;
-        children?: React.ReactNode;
-    } & React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+    Title: typeof EmptyPageTitle;
+    Description: typeof EmptyPageDescription;
     Actions: typeof EmptyPageActions;
 };
 export {};
-//# sourceMappingURL=EmptyPage.d.ts.map

package/dist/components/example-frame/ExampleFrame.d.ts

@@ -1,11 +1,18 @@
 import * as React from "react";
-export type ExampleFrameViewport = "desktop" | "tablet" | "mobile";
+declare const VIEWPORTS: readonly ["desktop", "tablet", "mobile"];
+export type ExampleFrameViewport = (typeof VIEWPORTS)[number];
 type ColorScheme = "light" | "dark";
-/** Раскладка содержимого превью — чтобы в сниппетах не оборачивать компоненты в div.stack/row. */
-export type ExampleFramePreviewLayout = "default" | "stack" | "stack-center" | "stack-narrow" | "dense-stack" | "row" | "row-start" | "row-wrap";
+/**
+ * Layout of the preview children, so snippets need no wrapper divs for rows and stacks.
+ * `matrix`: labelled specimens — every direct child is a row, its children are cells (a specimen
+ * above its caption), and cells line up in columns across rows.
+ */
+export type ExampleFramePreviewLayout = "default" | "stack" | "stack-narrow" | "full" | "row" | "matrix";
 export type ExampleFrameLabels = {
+    paneSwitch: string;
     preview: string;
     code: string;
+    viewportSwitch: string;
     desktop: string;
     tablet: string;
     mobile: string;
@@ -16,12 +23,12 @@ export type ExampleFrameLabels = {
     themeLight: string;
     codeRegion: string;
 };
-export type ExampleFrameRootProps = {
+export type ExampleFrameProps = Omit<React.HTMLAttributes<HTMLDivElement>, "onCopy"> & {
     /** Source shown on the code pane (TS/TSX highlighting) and copied by the copy button. */
     code: string;
-    children?: React.ReactNode;
-    className?: string;
-    /** Управляемая цветовая схема превью (light/dark). */
+    /** The outer `<div>`. */
+    ref?: React.Ref<HTMLDivElement>;
+    /** Preview color scheme (controlled). */
     colorScheme?: ColorScheme;
     defaultColorScheme?: ColorScheme;
     onColorSchemeChange?: (scheme: ColorScheme) => void;
@@ -29,31 +36,17 @@ export type ExampleFrameRootProps = {
     viewport?: ExampleFrameViewport;
     defaultViewport?: ExampleFrameViewport;
     onViewportChange?: (v: ExampleFrameViewport) => void;
-    /** Показывать ли кнопку переключения light/dark в тулбаре. */
+    /** Show the light / dark toggle in the toolbar. Default `true`. */
     showThemeToggle?: boolean;
-    /** Вызывается после успешного копирования `code` в буфер. */
+    /** Called after `code` was copied to the clipboard. */
     onCopy?: () => void;
-    /**
-     * Как выстроить детей внутри превью. По умолчанию — по центру (один блок).
-     * Для списков из нескольких компонентов используйте `stack` / `stack-center` / `row`.
-     */
+    /** How the preview lays out its children. Default `default`: one centered block. */
     previewLayout?: ExampleFramePreviewLayout;
     labels?: Partial<ExampleFrameLabels>;
 };
-declare function ExampleFrameRoot({ code, children, className, colorScheme: colorSchemeProp, defaultColorScheme, onColorSchemeChange, viewport: viewportProp, defaultViewport, onViewportChange, showThemeToggle, onCopy, previewLayout, labels: labelsProp, }: ExampleFrameRootProps): import("react/jsx-runtime").JSX.Element;
-declare namespace ExampleFrameRoot {
+/** Documentation frame: a toolbar (pane, theme, copy, device width) above the preview or the code. */
+export declare function ExampleFrame({ code, children, className, colorScheme: colorSchemeProp, defaultColorScheme, onColorSchemeChange, viewport: viewportProp, defaultViewport, onViewportChange, showThemeToggle, onCopy, previewLayout, labels: labelsProp, ref, ...rest }: ExampleFrameProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ExampleFrame {
     var displayName: string;
 }
-export type ExampleFrameStageProps = {
-    children: React.ReactNode;
-};
-declare function ExampleFrameStage({ children }: ExampleFrameStageProps): import("react/jsx-runtime").JSX.Element;
-declare namespace ExampleFrameStage {
-    var displayName: string;
-}
-export declare const ExampleFrame: {
-    Root: typeof ExampleFrameRoot;
-    Stage: typeof ExampleFrameStage;
-};
 export {};
-//# sourceMappingURL=ExampleFrame.d.ts.map