entangle-ui 0.8.2 → 0.10.0

package/dist/types/components/navigation/Breadcrumbs/Breadcrumbs.types.d.ts

@@ -64,6 +64,13 @@ interface BreadcrumbItemBaseProps extends BaseComponent<HTMLElement> {
      * Truncate a string label when it exceeds this many characters.
      */
     maxLength?: number;
+    /**
+     * Optional content rendered after the label, as a sibling of (not inside)
+     * the navigable link/button. Use it for a trailing affordance such as a
+     * dropdown trigger: because it sits outside the interactive element,
+     * activating it does not trigger the item's `onClick`/navigation.
+     */
+    endContent?: React.ReactNode;
     /**
      * Breadcrumb label.
      */

package/dist/types/components/navigation/ContextMenu/ContextMenu.d.ts

@@ -1,6 +1,21 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ContextMenuProps } from './ContextMenu.types.js';
+import React from 'react';
+import { ContextMenuProps, ContextMenuTriggerProps, ContextMenuContentProps } from './ContextMenu.types.js';
 
-declare function ContextMenu<TPayload = unknown>({ config, selectedItems, onChange, children, payload, checkboxIcon, radioIcon, disabled, className, style, testId, ref, ...rest }: ContextMenuProps<TPayload>): react_jsx_runtime.JSX.Element;
+/**
+ * Compound ContextMenu API. Items reuse the shared `Menu.*` primitives.
+ */
+declare const ContextMenu: {
+    ({ children, open, defaultOpen, onOpenChange, disabled, gap, ref, }: ContextMenuProps): React.ReactElement;
+    displayName: string;
+} & {
+    Trigger: {
+        ({ children, render, className, style, testId, ref, ...rest }: ContextMenuTriggerProps): React.ReactElement;
+        displayName: string;
+    };
+    Content: {
+        ({ children, className, testId, ref, ...rest }: ContextMenuContentProps): React.ReactElement;
+        displayName: string;
+    };
+};
 
 export { ContextMenu };

package/dist/types/components/navigation/ContextMenu/ContextMenu.types.d.ts

@@ -1,74 +1,66 @@
-import React from 'react';
-import { Prettify } from '../../../types/utilities.js';
+import { MenuHandle } from '../Menu/Menu.types.js';
 import { BaseComponent } from '../../../types/common.js';
-import { MenuConfig, MenuSelection } from '../Menu/Menu.types.js';
+import { Prettify } from '../../../types/utilities.js';
+import React from 'react';
 
-interface ContextMenuTargetDetails<TPayload = unknown> {
-    /**
-     * Native browser contextmenu event from the latest trigger interaction.
-     * Null until the first right click.
-     */
-    event: MouseEvent | null;
-    /**
-     * Element that initiated the context menu interaction.
-     */
-    target: HTMLElement | null;
+/**
+ * Root of a context menu. Owns open/close state for one trigger area.
+ *
+ * Scope a menu to an area by giving that area its own `ContextMenu` — there is
+ * no per-target config resolver. For advanced panels, drop any custom node
+ * (tabs, search, etc.) inside `ContextMenu.Content`.
+ */
+interface ContextMenuRootBaseProps {
+    /** `ContextMenu.Trigger` and `ContextMenu.Content`. */
+    children?: React.ReactNode;
+    /** Controlled open state. */
+    open?: boolean;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: boolean;
+    /** Called when the menu opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Disables opening the context menu. */
+    disabled?: boolean;
     /**
-     * Optional payload associated with the trigger area.
+     * Gap in px between submenu popups and their anchor. Inherited by any
+     * `Menu.SubContent` rendered inside the content.
+     * @default 8
      */
-    payload?: TPayload;
+    gap?: number;
+    /** Imperative handle for closing the menu from app code. */
+    ref?: React.Ref<MenuHandle>;
 }
-type ContextMenuConfig<TPayload = unknown> = MenuConfig | ((context: ContextMenuTargetDetails<TPayload>) => MenuConfig);
-interface ContextMenuBaseProps<TPayload = unknown> extends Omit<BaseComponent<HTMLDivElement>, 'children' | 'onChange'> {
-    /**
-     * Static menu config or resolver function called with trigger context.
-     */
-    config: ContextMenuConfig<TPayload>;
-    /**
-     * Currently selected items grouped by id.
-     */
-    selectedItems?: MenuSelection;
-    /**
-     * Called when selection state changes.
-     */
-    onChange?: (selection: MenuSelection) => void;
-    /**
-     * Content that acts as the right-click trigger area.
-     */
+type ContextMenuProps = Prettify<ContextMenuRootBaseProps>;
+/**
+ * Area that opens the menu on right click or long press.
+ *
+ * By default the children are wrapped in a `display: contents` element so the
+ * trigger is transparent to layout. Pass `render` to make the trigger render
+ * *as* your own element instead — no wrapper, and the element stays fully
+ * stylable (positioning, margins, etc.).
+ */
+interface ContextMenuTriggerBaseProps extends BaseComponent {
+    /** The right-click target area. */
     children?: React.ReactNode;
     /**
-     * Optional data attached to this trigger area and passed to config resolver.
-     */
-    payload?: TPayload;
-    /**
-     * Custom icon for checkbox selected state.
-     */
-    checkboxIcon?: React.ReactNode;
-    /**
-     * Custom icon for radio selected state.
-     */
-    radioIcon?: React.ReactNode;
-    /**
-     * Disables opening the context menu.
-     * @default false
+     * Render the trigger as this element instead of wrapping the children in a
+     * `display: contents` element. The element carries its own children.
      */
-    disabled?: boolean;
+    render?: React.ReactElement;
 }
-type ContextMenuProps<TPayload = unknown> = Prettify<ContextMenuBaseProps<TPayload>>;
-interface UseContextMenuTargetResult<TPayload = unknown> {
-    /**
-     * Latest target context captured from right click interaction.
-     */
-    context: ContextMenuTargetDetails<TPayload>;
-    /**
-     * Attach this to an element if you want to capture context manually.
-     */
-    onContextMenuCapture: (event: React.MouseEvent<HTMLElement>) => void;
-    /**
-     * Callback ref that captures native right-click interactions on a node.
-     * Useful when you want ref-based wiring.
-     */
-    targetRef: (node: HTMLElement | null) => void;
+type ContextMenuTriggerProps = Prettify<ContextMenuTriggerBaseProps>;
+/**
+ * Styled popup surface positioned at the pointer. Place items or any custom
+ * node inside.
+ *
+ * Unlike `Menu.Content`, this exposes no `side` / `align` / `sideOffset`: a
+ * context menu opens *at the pointer* (the cursor is the anchor), so there is
+ * no trigger edge to align against. Submenus still honour the root `gap`.
+ */
+interface ContextMenuContentBaseProps extends BaseComponent {
+    /** Items, groups, or custom panel content. */
+    children?: React.ReactNode;
 }
+type ContextMenuContentProps = Prettify<ContextMenuContentBaseProps>;
 
-export type { ContextMenuBaseProps, ContextMenuConfig, ContextMenuProps, ContextMenuTargetDetails, UseContextMenuTargetResult };
+export type { ContextMenuContentBaseProps, ContextMenuContentProps, ContextMenuProps, ContextMenuRootBaseProps, ContextMenuTriggerBaseProps, ContextMenuTriggerProps };

package/dist/types/components/navigation/Menu/Menu.d.ts

@@ -1,42 +1,45 @@
 import React from 'react';
-import { MenuProps } from './Menu.types.js';
+import { MenuRootProps, MenuTriggerProps, MenuContentProps, MenuItemProps, MenuGroupProps, MenuSeparatorProps, MenuRadioGroupProps, MenuRadioItemProps, MenuCheckboxItemProps, MenuSubProps, MenuSubTriggerProps } from './Menu.types.js';
 
 /**
- * A configuration-driven menu component for editor interfaces.
+ * Compound Menu API.
  *
- * Automatically handles radio/checkbox selection states, grouping,
- * and nested submenus based on provided configuration object.
- *
- * @example
- * ```tsx
- * const config = {
- *   groups: [{
- *     id: 'actions',
- *     items: [
- *       {
- *         id: 'copy',
- *         label: 'Copy',
- *         onClick: handleCopy,
- *         subMenu: nestedConfig,
- *         submenuTrigger: 'hover' // Opens on hover (default)
- *       },
- *       {
- *         id: 'paste',
- *         label: 'Paste',
- *         onClick: handlePaste,
- *         subMenu: nestedConfig,
- *         submenuTrigger: 'click' // Opens on click only
- *       }
- *     ],
- *     itemSelectionType: 'none'
- *   }]
- * };
- *
- * <Menu config={config}>
- *   <Button>Options</Button>
- * </Menu>
- * ```
+ * `Content` and `SubContent` are the same popup surface. The gap from the
+ * anchor is set once on the `Menu` root (`gap` prop) and inherited by both.
  */
-declare const Menu: React.FC<MenuProps>;
+declare const Menu: {
+    ({ children, open, defaultOpen, onOpenChange, modal, disabled, gap, ref, }: MenuRootProps): React.ReactElement;
+    displayName: string;
+} & {
+    Trigger: {
+        ({ children, render, disabled, openOnHover, className, testId, ...rest }: MenuTriggerProps): React.ReactElement;
+        displayName: string;
+    };
+    Content: {
+        ({ children, className, side, align, sideOffset, alignOffset, testId, ref, ...rest }: MenuContentProps): React.ReactElement;
+        displayName: string;
+    };
+    Item: React.MemoExoticComponent<({ children, icon, shortcut, endContent, disabled, closeOnClick, onClick, onSelect, className, testId, ref, ...rest }: MenuItemProps) => React.ReactElement>;
+    Group: {
+        ({ children, label, className, testId, ...rest }: MenuGroupProps): React.ReactElement;
+        displayName: string;
+    };
+    Separator: React.MemoExoticComponent<({ className, testId, ...rest }: MenuSeparatorProps) => React.ReactElement>;
+    RadioGroup: {
+        ({ children, value, defaultValue, onValueChange, className, testId, ...rest }: MenuRadioGroupProps): React.ReactElement;
+        displayName: string;
+    };
+    RadioItem: React.MemoExoticComponent<({ children, value, indicator, shortcut, endContent, disabled, closeOnClick, onClick, onSelect, className, testId, ref, ...rest }: MenuRadioItemProps) => React.ReactElement>;
+    CheckboxItem: React.MemoExoticComponent<({ children, checked, defaultChecked, onCheckedChange, indicator, shortcut, endContent, disabled, closeOnClick, onClick, onSelect, className, testId, ref, ...rest }: MenuCheckboxItemProps) => React.ReactElement>;
+    Sub: {
+        ({ children, defaultOpen, }: MenuSubProps): React.ReactElement;
+        displayName: string;
+    };
+    SubTrigger: React.MemoExoticComponent<({ children, icon, disabled, onClick, className, testId, ref, ...rest }: MenuSubTriggerProps) => React.ReactElement>;
+    SubContent: {
+        ({ children, className, side, align, sideOffset, alignOffset, testId, ref, ...rest }: MenuContentProps): React.ReactElement;
+        displayName: string;
+    };
+};
 
 export { Menu };

package/dist/types/components/navigation/Menu/Menu.types.d.ts

@@ -1,94 +1,213 @@
-import React from 'react';
-import { Prettify } from '../../../types/utilities.js';
 import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+import React from 'react';
 
+/** Side of the trigger the popup is placed against. */
+type MenuSide = 'top' | 'right' | 'bottom' | 'left';
+/** Alignment of the popup relative to the trigger. */
+type MenuAlign = 'start' | 'center' | 'end';
 /**
- * How submenus should be triggered.
- * - `hover`: Submenu opens on hover
- * - `click`: Submenu opens on click only
+ * Imperative handle exposed on the `Menu` / `ContextMenu` root `ref`. Lets app
+ * code close an open menu from outside React's render flow (e.g. after a long
+ * task finishes).
  */
-type SubmenuTrigger = 'hover' | 'click';
+interface MenuHandle {
+    /** Close the menu programmatically. */
+    close: () => void;
+}
 /**
- * Configuration for a single menu item.
+ * Root of the menu. Groups the trigger and content, owns open/close state.
  */
-type MenuItem = {
-    /** Unique identifier for the menu item */
-    id: string;
-    /** Display text for the menu item */
-    label: string;
-    /** Click handler called with item id and event */
-    onClick: (id: string, event: MouseEvent) => void;
-    /** Optional icon rendered before the label */
-    icon?: React.ReactNode;
-    /** Whether the item is disabled */
+interface MenuRootBaseProps {
+    /** Trigger and content of the menu. */
+    children?: React.ReactNode;
+    /** Controlled open state. */
+    open?: boolean;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: boolean;
+    /** Called when the menu opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Whether the menu traps interaction while open.
+     * @default true
+     */
+    modal?: boolean;
+    /** Disables opening the menu. */
     disabled?: boolean;
-    /** Nested submenu configuration */
-    subMenu?: MenuConfig;
-    /** How submenu should be triggered when subMenu is present */
-    submenuTrigger?: SubmenuTrigger;
-};
+    /**
+     * Gap in px between every popup (the menu and its submenus) and its anchor.
+     * Set once here for the whole menu; overridable per popup via
+     * `Menu.Content`'s `sideOffset`.
+     * @default 8
+     */
+    gap?: number;
+    /** Imperative handle for closing the menu from app code. */
+    ref?: React.Ref<MenuHandle>;
+}
+type MenuRootProps = Prettify<MenuRootBaseProps>;
 /**
- * Type of item selection behavior within a group.
- * - `radio`: Single selection within group
- * - `checkbox`: Multiple selection within group
- * - `none`: No selection state, just click handlers
+ * Button that opens the menu. Defaults to the library `Button`; pass `render`
+ * to compose with another element (e.g. `IconButton`).
  */
-type ItemSelectionType = 'radio' | 'checkbox' | 'none';
+interface MenuTriggerBaseProps extends BaseComponent<HTMLButtonElement> {
+    /** Trigger content. */
+    children?: React.ReactNode;
+    /** Disables the trigger. */
+    disabled?: boolean;
+    /** Also open the menu when the trigger is hovered. */
+    openOnHover?: boolean;
+    /** Replace the default Button with a custom element. */
+    render?: React.ReactElement;
+}
+type MenuTriggerProps = Prettify<MenuTriggerBaseProps>;
 /**
- * Configuration for a group of menu items.
- * Groups are visually separated and can have different selection behaviors.
+ * Styled popup surface. Place items or any custom node inside.
  */
-type MenuGroup = {
-    /** Unique identifier for the group */
-    id: string;
-    /** Optional label displayed above the group */
-    label?: string;
-    /** Array of menu items in this group */
-    items: MenuItem[];
-    /** Selection behavior for items in this group */
-    itemSelectionType: ItemSelectionType;
-    /** Whether to close menu when any item in group is clicked */
-    closeOnItemClick?: boolean;
-};
+interface MenuContentBaseProps extends BaseComponent {
+    /** Items, groups, or custom panel content. */
+    children?: React.ReactNode;
+    /** Preferred side relative to the trigger. */
+    side?: MenuSide;
+    /** Alignment along the chosen side. */
+    align?: MenuAlign;
+    /** Gap in px between trigger and popup. @default 4 */
+    sideOffset?: number;
+    /** Offset in px along the alignment axis. */
+    alignOffset?: number;
+}
+type MenuContentProps = Prettify<MenuContentBaseProps>;
 /**
- * Configuration for a menu component.
- * Defines structure, behavior, and selection state.
+ * Single actionable row. Icon on the left, label in the center, shortcut and
+ * action on the right.
  */
-type MenuConfig = {
-    /** Whether to open menu on hover instead of click */
-    openOnHover?: boolean;
-    /** Array of menu groups */
-    groups: MenuGroup[];
-};
+interface MenuItemBaseProps extends Omit<BaseComponent<HTMLElement>, 'onClick'> {
+    /** Label content. */
+    children?: React.ReactNode;
+    /** Icon rendered in the left slot. */
+    icon?: React.ReactNode;
+    /** Keyboard shortcut hint rendered on the right. */
+    shortcut?: React.ReactNode;
+    /** Arbitrary node rendered on the right (badge, switch, etc.). */
+    endContent?: React.ReactNode;
+    /** Disables the item. */
+    disabled?: boolean;
+    /** Whether clicking the item closes the menu. @default true */
+    closeOnClick?: boolean;
+    /** Click handler. Fires on pointer click and keyboard activation. */
+    onClick?: React.MouseEventHandler<HTMLElement>;
+    /**
+     * Activation handler — alias of `onClick` with clearer intent. Fires on the
+     * same pointer and keyboard (Enter/Space) activation. Both run if provided.
+     */
+    onSelect?: React.MouseEventHandler<HTMLElement>;
+}
+type MenuItemProps = Prettify<MenuItemBaseProps>;
 /**
- * Selected items state organized by group.
- * Maps group ID to array of selected item IDs.
+ * Wraps a set of radio items, owns the selected value.
  */
-type MenuSelection = Record<string, string[]>;
+interface MenuRadioGroupBaseProps extends Omit<BaseComponent, 'onChange'> {
+    /** Radio items. */
+    children?: React.ReactNode;
+    /** Controlled selected value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    /** Called when the selected value changes. */
+    onValueChange?: (value: string) => void;
+}
+type MenuRadioGroupProps = Prettify<MenuRadioGroupBaseProps>;
+/**
+ * Radio row. Shows a selection indicator in the left slot when active.
+ */
+interface MenuRadioItemBaseProps extends Omit<BaseComponent<HTMLElement>, 'onClick'> {
+    /** Value this item represents within its `RadioGroup`. */
+    value: string;
+    /** Label content. */
+    children?: React.ReactNode;
+    /** Indicator shown when selected. @default CircleIcon */
+    indicator?: React.ReactNode;
+    /** Keyboard shortcut hint rendered on the right. */
+    shortcut?: React.ReactNode;
+    /** Arbitrary node rendered on the right. */
+    endContent?: React.ReactNode;
+    /** Disables the item. */
+    disabled?: boolean;
+    /** Whether clicking the item closes the menu. @default false */
+    closeOnClick?: boolean;
+    /** Click handler. Fires on pointer click and keyboard activation. */
+    onClick?: React.MouseEventHandler<HTMLElement>;
+    /**
+     * Activation handler — alias of `onClick` with clearer intent. Fires on the
+     * same pointer and keyboard (Enter/Space) activation. Both run if provided.
+     */
+    onSelect?: React.MouseEventHandler<HTMLElement>;
+}
+type MenuRadioItemProps = Prettify<MenuRadioItemBaseProps>;
 /**
- * Base props for the Menu component.
+ * Checkbox row. Shows a selection indicator in the left slot when ticked.
  */
-interface MenuBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'onChange'> {
-    /** Menu configuration object */
-    config: MenuConfig;
-    /** Currently selected items organized by group */
-    selectedItems?: MenuSelection;
-    /** Callback when selection changes */
-    onChange?: (selection: MenuSelection) => void;
-    /** Menu trigger element */
+interface MenuCheckboxItemBaseProps extends Omit<BaseComponent<HTMLElement>, 'onClick'> {
+    /** Label content. */
     children?: React.ReactNode;
-    /** Custom icon for checkbox selected state */
-    checkboxIcon?: React.ReactNode;
-    /** Custom icon for radio selected state */
-    radioIcon?: React.ReactNode;
-    /** Whether the menu is disabled */
+    /** Controlled checked state. */
+    checked?: boolean;
+    /** Uncontrolled initial checked state. */
+    defaultChecked?: boolean;
+    /** Called when toggled. */
+    onCheckedChange?: (checked: boolean) => void;
+    /** Indicator shown when ticked. @default CheckIcon */
+    indicator?: React.ReactNode;
+    /** Keyboard shortcut hint rendered on the right. */
+    shortcut?: React.ReactNode;
+    /** Arbitrary node rendered on the right. */
+    endContent?: React.ReactNode;
+    /** Disables the item. */
     disabled?: boolean;
-    /** Whether this menu is a submenu */
-    isSubmenu?: boolean;
+    /** Whether clicking the item closes the menu. @default false */
+    closeOnClick?: boolean;
+    /** Click handler. Fires on pointer click and keyboard activation. */
+    onClick?: React.MouseEventHandler<HTMLElement>;
+    /**
+     * Activation handler — alias of `onClick` with clearer intent. Fires on the
+     * same pointer and keyboard (Enter/Space) activation. Both run if provided.
+     */
+    onSelect?: React.MouseEventHandler<HTMLElement>;
 }
+type MenuCheckboxItemProps = Prettify<MenuCheckboxItemBaseProps>;
 /**
- * Props for the Menu component using Prettify utility type.
+ * Visually separated group of items with an optional label.
  */
-type MenuProps = Prettify<MenuBaseProps>;
+interface MenuGroupBaseProps extends BaseComponent {
+    /** Group items. */
+    children?: React.ReactNode;
+    /** Label rendered above the group. */
+    label?: React.ReactNode;
+}
+type MenuGroupProps = Prettify<MenuGroupBaseProps>;
+type MenuSeparatorProps = Prettify<BaseComponent>;
+/**
+ * Groups a submenu trigger with its content.
+ */
+interface MenuSubBaseProps {
+    /** `SubTrigger` and `SubContent`. */
+    children?: React.ReactNode;
+    /** Uncontrolled initial open state of the submenu. */
+    defaultOpen?: boolean;
+}
+type MenuSubProps = Prettify<MenuSubBaseProps>;
+/**
+ * Row that opens a submenu. Renders a chevron in the right slot.
+ */
+interface MenuSubTriggerBaseProps extends Omit<BaseComponent<HTMLElement>, 'onClick'> {
+    /** Label content. */
+    children?: React.ReactNode;
+    /** Icon rendered in the left slot. */
+    icon?: React.ReactNode;
+    /** Disables the submenu trigger. */
+    disabled?: boolean;
+    /** Click handler. */
+    onClick?: React.MouseEventHandler<HTMLElement>;
+}
+type MenuSubTriggerProps = Prettify<MenuSubTriggerBaseProps>;
 
-export type { ItemSelectionType, MenuBaseProps, MenuConfig, MenuGroup, MenuItem, MenuProps, MenuSelection, SubmenuTrigger };
+export type { MenuAlign, MenuCheckboxItemBaseProps, MenuCheckboxItemProps, MenuContentBaseProps, MenuContentProps, MenuGroupBaseProps, MenuGroupProps, MenuHandle, MenuItemBaseProps, MenuItemProps, MenuRadioGroupBaseProps, MenuRadioGroupProps, MenuRadioItemBaseProps, MenuRadioItemProps, MenuRootBaseProps, MenuRootProps, MenuSeparatorProps, MenuSide, MenuSubBaseProps, MenuSubProps, MenuSubTriggerBaseProps, MenuSubTriggerProps, MenuTriggerBaseProps, MenuTriggerProps };

package/dist/types/components/navigation/Pagination/Pagination.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { PaginationProps } from './Pagination.types.js';
+export { PaginationSize } from './Pagination.types.js';
+
+/**
+ * Page navigator with sibling/boundary ellipsis logic. Controlled when `page`
+ * is set, otherwise uncontrolled with `defaultPage`. Pages are 1-based.
+ *
+ * @example
+ * ```tsx
+ * <Pagination count={20} defaultPage={1} onChange={(_, p) => setPage(p)} />
+ *
+ * // Compact: only prev/next + numbers
+ * <Pagination count={20} siblingCount={0} boundaryCount={1} />
+ *
+ * // Full controls
+ * <Pagination count={50} showFirstButton showLastButton />
+ * ```
+ */
+declare const Pagination: React.FC<PaginationProps>;
+
+export { Pagination };

package/dist/types/components/navigation/Pagination/Pagination.types.d.ts

@@ -0,0 +1,49 @@
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+import React from 'react';
+
+type PaginationSize = 'sm' | 'md' | 'lg';
+type PaginationItemType = 'page' | 'ellipsis' | 'first' | 'previous' | 'next' | 'last';
+/**
+ * A single item resolved by the pagination algorithm. `page` is `null` for
+ * ellipsis items and for prev/next/first/last when the corresponding action
+ * is not available (e.g. `previous` while on page 1).
+ */
+interface PaginationItem {
+    type: PaginationItemType;
+    page: number | null;
+    selected: boolean;
+    disabled: boolean;
+}
+type PaginationItemAriaLabelGetter = (type: PaginationItemType, page: number | null, selected: boolean) => string;
+interface PaginationBaseProps extends Omit<BaseComponent<HTMLElement>, 'onChange'> {
+    /** Total number of pages. */
+    count: number;
+    /** Currently selected page (1-based). Controls the component when set. */
+    page?: number;
+    /** Default selected page in uncontrolled mode (1-based). @default 1 */
+    defaultPage?: number;
+    /** Called when the user requests a new page. */
+    onChange?: (event: React.SyntheticEvent, page: number) => void;
+    /** Pages shown on each side of the current page. @default 1 */
+    siblingCount?: number;
+    /** Pages always shown at the start and end of the list. @default 1 */
+    boundaryCount?: number;
+    /** Show the "jump to first" button. @default false */
+    showFirstButton?: boolean;
+    /** Show the "jump to last" button. @default false */
+    showLastButton?: boolean;
+    /** Hide the previous-page button. @default false */
+    hidePrevButton?: boolean;
+    /** Hide the next-page button. @default false */
+    hideNextButton?: boolean;
+    /** Visual size. @default "md" */
+    size?: PaginationSize;
+    /** Disable the whole control. @default false */
+    disabled?: boolean;
+    /** Custom aria-label generator for each item. */
+    getItemAriaLabel?: PaginationItemAriaLabelGetter;
+}
+type PaginationProps = Prettify<PaginationBaseProps>;
+
+export type { PaginationBaseProps, PaginationItem, PaginationItemAriaLabelGetter, PaginationItemType, PaginationProps, PaginationSize };

package/dist/types/components/navigation/PathBar/PathBar.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+import { PathBarProps } from './PathBar.types.js';
+
+/**
+ * File-path breadcrumbs, like the VS Code editor breadcrumb bar.
+ *
+ * PathBar specializes {@link Breadcrumbs}: give it a path — a delimited string
+ * or a structured segment array — and it renders each segment as a crumb.
+ * Folder crumbs navigate on click (`onNavigate`); the final segment is the
+ * current location. Provide `getSiblings` to add a VS-Code-style dropdown that
+ * swaps a segment for one of its siblings. Long paths reuse the Breadcrumbs
+ * collapse / ellipsis machinery via `maxItems`.
+ *
+ * The current path is controllable: pass `value` to drive it, or `defaultValue`
+ * to let PathBar track it (clicking an ancestor truncates the trail).
+ *
+ * @example
+ * ```tsx
+ * <PathBar
+ *   defaultValue="src/components/Button/Button.tsx"
+ *   rootIcon={<HomeIcon size="sm" decorative />}
+ *   onNavigate={path => router.push(path)}
+ * />
+ * ```
+ */
+declare const PathBar: {
+    ({ value, defaultValue, delimiter, onNavigate, getSiblings, rootIcon, separator, maxItems, itemsBeforeCollapse, itemsAfterCollapse, expandable, size, className, style, testId, ref, ...rest }: PathBarProps): React.ReactElement;
+    displayName: string;
+};
+
+export { PathBar };