@tpc-mare/mare-ui-components-react 1.0.2 → 1.0.3

package/dist/keyboard-commands.d.ts

@@ -0,0 +1,264 @@
+export declare function attachTooltips(element: HTMLElement, commands: KeyboardCommand[]): void;
+
+export declare type BothTriggerDedupBucket = number | 'scroll:up' | 'scroll:down';
+
+declare interface BothTriggerDedupEntry {
+    bucket: BothTriggerDedupBucket;
+    phase: 'keydown' | 'keyup';
+    time: number;
+    modifiers?: KeydownModifierSnapshot;
+}
+
+export declare interface BothTriggerDedupReference {
+    current: BothTriggerDedupEntry | null;
+}
+
+export declare function buildAriaKeyshortcuts(commands: KeyboardCommand[]): string;
+
+export declare function buildParsedChordLists(keys: (string | string[])[]): ParsedChord[][];
+
+export declare function detachTooltips(element: HTMLElement): void;
+
+export declare function ensureTabindex(element: HTMLElement): void;
+
+export declare function findScrollableAncestor(element: HTMLElement): HTMLElement | null;
+
+export declare function formatKeyDescriptor(descriptor: string | string[]): string[][];
+
+/** 0 = base page (no overlay open); higher = topmost overlay depth. */
+export declare function getActiveDepth(): ScopeDepth;
+
+/**
+ * Returns the modifier snapshot captured from the preceding keydown event,
+ * when `triggerOn` is 'both' and the current event is a keyup. This lets
+ * matchesChord use the original modifier state even if the user released a
+ * modifier key before releasing the main key.
+ */
+export declare function getKeydownModifiersForKeyup(triggerOn: 'keydown' | 'keyup' | 'both' | undefined, last: BothTriggerDedupReference, event: KeyboardEvent): KeydownModifierSnapshot | undefined;
+
+export declare function injectAriaOnElement(element: HTMLElement, options: InjectAriaOptions): void;
+
+export declare interface InjectAriaOptions {
+    commands: KeyboardCommand[];
+    depth: number;
+    context?: KbdHintContext;
+    hintCommands?: KbdHintEntry[];
+    ariaAttributes?: Record<string, string>;
+}
+
+export declare function injectKbdHintAttribute(element: HTMLElement, commands: KeyboardCommand[], depth: number, context?: KbdHintContext, hintCommands?: KbdHintEntry[]): void;
+
+export declare function isBrowser(): boolean;
+
+export declare function isElementDisabled(element: HTMLElement): boolean;
+
+export declare const isMac: boolean;
+
+export declare function isScrollable(element: HTMLElement): boolean;
+
+export declare function isTooltipEligibleTarget(target: KeyboardCommandTarget | null | undefined): target is HTMLElement;
+
+export declare const KBD_HINT_ATTR = "data-mare-kbd-hint";
+
+export declare type KbdHintContext = 'onDefault' | 'onBrand' | 'onMedia' | 'onInverse' | 'onDanger';
+
+export declare interface KbdHintEntry {
+    keys: string | string[];
+    description?: string;
+}
+
+export declare interface KbdHintPayload {
+    depth: number;
+    commands: KbdHintEntry[];
+    context?: KbdHintContext;
+}
+
+export declare const KEYBOARD_BOTH_TRIGGER_DEDUP_MS = 450;
+
+export declare interface KeyboardCommand {
+    keys: string | string[];
+    handler: (event: KeyboardEvent) => void;
+    description?: string;
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    tooltip?: KeyboardCommandTooltipOption;
+    when?: () => boolean;
+}
+
+export declare type KeyboardCommandTarget = HTMLElement | Document | EventTarget;
+
+export declare interface KeyboardCommandTooltip {
+    label?: string | false;
+    placement?: 'prefix' | 'suffix';
+    position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    showDelay?: number;
+    hideDelay?: number;
+}
+
+export declare type KeyboardCommandTooltipOption = boolean | KeyboardCommandTooltip | null | undefined;
+
+export declare interface KeydownModifierSnapshot {
+    altKey: boolean;
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}
+
+export declare function matchesChord(event: KeyboardEvent, chord: ParsedChord, isMacOverrideOrOptions?: boolean | MatchesChordOverrides): boolean;
+
+export declare interface MatchesChordOverrides {
+    isMac?: boolean;
+    /** Modifier state from a prior keydown, used when modifiers are released before the main key in keyup events. */
+    keydownModifiers?: {
+        altKey: boolean;
+        shiftKey: boolean;
+        ctrlKey: boolean;
+        metaKey: boolean;
+    };
+}
+
+export declare interface NavGridCell {
+    row: number;
+    col: number;
+}
+
+export declare function normalizeScrollAreaOptions(scrollable: boolean | ScrollAreaOptions): ScrollAreaOptions;
+
+/** Subscribe to active-depth changes. Returns an unsubscribe function. */
+export declare function onScopeDepthChange(function_: (depth: ScopeDepth) => void): () => void;
+
+export declare function parseChord(descriptor: string): ParsedChord;
+
+export declare interface ParsedChord {
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    mod: boolean;
+    key: string;
+}
+
+export declare function prefersReducedMotion(): boolean;
+
+export declare function registerScope(id: string, depth: ScopeDepth): void;
+
+export declare function removeAriaOnElement(element: HTMLElement, ariaAttributes?: Record<string, string>): void;
+
+export declare function resolveScrollBehavior(opt: ScrollAreaOptions): 'auto' | 'smooth';
+
+/**
+ * `opt.container` here is already a resolved value (see ScrollAreaOptions) —
+ * the caller (each framework's adapter) is responsible for unwrapping its own
+ * reactive reference (Vue Ref, React state) before calling this function.
+ */
+export declare function resolveScrollContainer(target: HTMLElement, opt: ScrollAreaOptions): HTMLElement | null;
+
+export declare function resolveTriggerEventNames(triggerOn?: 'keydown' | 'keyup' | 'both'): ('keydown' | 'keyup')[];
+
+export declare type ScopeDepth = number;
+
+/**
+ * Framework-agnostic (already-resolved) scroll options. `container` here is
+ * a plain value, not a reactive reference — each framework adapter resolves
+ * its own reactive container (Vue Ref, React state) to a plain value before
+ * calling into this package's scroll utilities.
+ */
+export declare interface ScrollAreaOptions {
+    container?: HTMLElement | null | string;
+    scrollUpKeys?: string[];
+    scrollDownKeys?: string[];
+    scrollStep?: number;
+    scrollBehavior?: 'auto' | 'smooth';
+}
+
+export declare function suppressDuplicateBothTrigger(triggerOn: 'keydown' | 'keyup' | 'both' | undefined, last: BothTriggerDedupReference, bucket: BothTriggerDedupBucket, event: KeyboardEvent): boolean;
+
+export declare function unregisterScope(id: string): void;
+
+/**
+ * React adapter for the keyboard-commands engine — same core (chord
+ * matching, ARIA injection, scroll handling, overlay depth-guard) as the Vue
+ * `useKeyboardCommands` composable, wired with hooks instead of Vue
+ * reactivity. `targetReference` is a plain ref object (window, or an element ref
+ * attached via JSX `ref={...}`); bind/rebind happens once on mount.
+ */
+export declare function useKeyboardCommands(targetReference: {
+    current: KeyboardCommandTarget | null;
+}, options?: UseKeyboardCommandsOptions): {
+    commandGroupId: string;
+    isActive: boolean;
+};
+
+export declare interface UseKeyboardCommandsOptions {
+    commands?: KeyboardCommand[];
+    hintContext?: KbdHintContext;
+    hintCommands?: KbdHintEntry[];
+    depth?: number;
+    /** Default: true. */
+    visible?: boolean;
+    autoFocus?: boolean;
+    scrollable?: boolean | ScrollAreaOptions;
+    ariaAttributes?: Record<string, string>;
+    capture?: boolean;
+    triggerOn?: 'keydown' | 'keyup' | 'both';
+}
+
+export declare function useKeyboardNavGrid(options: UseKeyboardNavGridOptions): UseKeyboardNavGridReturn;
+
+export declare interface UseKeyboardNavGridOptions {
+    rows: number;
+    cols: number;
+    depth?: number;
+    wrap?: boolean;
+    onSelect?: (cell: NavGridCell) => void;
+    onActivate?: (cell: NavGridCell) => void;
+}
+
+export declare interface UseKeyboardNavGridReturn {
+    focused: NavGridCell;
+    containerRef: (node: HTMLElement | null) => void;
+    focus: (cell: NavGridCell, instant?: boolean) => void;
+    isFocused: (row: number, col: number) => boolean;
+}
+
+export declare function useKeyboardNavList<T>(options: UseKeyboardNavListOptions<T>): UseKeyboardNavListReturn<T>;
+
+export declare interface UseKeyboardNavListOptions<T> {
+    items: readonly T[];
+    depth?: number;
+    wrap?: boolean;
+    onSelect?: (item: T, index: number) => void;
+    onActivate?: (item: T, index: number) => void;
+}
+
+export declare interface UseKeyboardNavListReturn<T> {
+    focusedIndex: number;
+    focusedItem: T | null;
+    containerRef: (node: HTMLElement | null) => void;
+    focus: (index: number) => void;
+    focusFirst: () => void;
+    focusLast: () => void;
+    clearFocus: () => void;
+}
+
+/**
+ * Registers/unregisters this component's keyboard scope with the global
+ * stack shared across both the Vue and React adapters. Use this inside
+ * overlay components so keyboard commands only fire when the overlay is the
+ * topmost one.
+ *
+ * @example
+ * const { scopeId } = useKeyboardScope({ visible: isOpen, depth: 1 });
+ */
+export declare function useKeyboardScope(options?: UseKeyboardScopeOptions): {
+    scopeId: string;
+};
+
+export declare interface UseKeyboardScopeOptions {
+    /** Higher number = closer to the user (like z-index). Default: 1. Base page = 0. */
+    depth?: ScopeDepth;
+    /** When false, this scope is removed from the global stack. Default: true. */
+    visible?: boolean;
+}
+
+export { }

package/dist/menu/index.js

@@ -1,4 +1,4 @@
-import { M as r } from "../shared/Menu-Cv9dU1iA.js";
+import { M as r } from "../shared/Menu-DBHlDgtQ.js";
 export {
   r as Menu
 };

package/dist/menu.d.ts

@@ -0,0 +1,48 @@
+import { JSX as JSX_2 } from 'react';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+
+export declare function Menu({ trigger, items, onSelect, renderItem, portalContainer, }: MenuProperties): JSX_2.Element;
+
+export declare type MenuEntry = MenuItemData | MenuSeparatorEntry | MenuGroupEntry;
+
+export declare interface MenuGroupEntry {
+    type: 'group';
+    label?: string;
+    items: MenuItemData[];
+}
+
+export declare interface MenuItemData {
+    type?: 'item';
+    value: string;
+    label: string;
+    disabled?: boolean;
+    /** Persistent highlight (e.g. current page) — distinct from the
+     * hover/keyboard `ark-highlighted` state. */
+    active?: boolean;
+    /** Consumer-defined extras (icon, href, target…) resolved in the adapter. */
+    [key: string]: unknown;
+}
+
+export declare interface MenuProperties {
+    /** The element that opens the menu on click — typically a `<Button>`. */
+    trigger: ReactNode;
+    items: MenuEntry[];
+    /** Called with the selected item's `value` when an item (or an item
+     * inside a group) is chosen. */
+    onSelect?: (value: string) => void;
+    /** Custom render for an item's content (icon + label). Defaults to
+     * `item.icon` (if any) + `item.label`. */
+    renderItem?: (item: MenuItemData) => ReactNode;
+    /** Where the menu portals to. Ark defaults to `document.body` — override
+     * this if your app scopes `data-theme` (or any other CSS custom property)
+     * to a sub-tree rather than the document root, otherwise the portaled
+     * menu renders outside that scope and loses the tokens. */
+    portalContainer?: RefObject<HTMLElement | null>;
+}
+
+export declare interface MenuSeparatorEntry {
+    type: 'separator';
+}
+
+export { }

package/dist/message/index.js

@@ -1,4 +1,4 @@
-import { M as a } from "../shared/Message-CQUdM9rR.js";
+import { M as a } from "../shared/Message-B36kcrfu.js";
 export {
   a as Message
 };

package/dist/message.d.ts

@@ -0,0 +1,28 @@
+import { JSX as JSX_2 } from 'react';
+import { ReactNode } from 'react';
+
+export declare function Message({ severity, variant, title, icon, disabled, closable, onClose, children, }: MessageProperties): JSX_2.Element;
+
+declare const MESSAGE_SEVERITIES: readonly ["neutral", "brand", "positive", "warning", "danger"];
+
+export declare interface MessageProperties {
+    /** @default 'neutral' */
+    severity?: MessageSeverity;
+    /** @default 'simple' */
+    variant?: MessageVariant;
+    title?: string;
+    icon?: ReactNode;
+    /** @default false */
+    disabled?: boolean;
+    /** @default false */
+    closable?: boolean;
+    onClose?: () => void;
+    children?: ReactNode;
+}
+
+export declare type MessageSeverity = (typeof MESSAGE_SEVERITIES)[number];
+
+/** @default 'simple' */
+export declare type MessageVariant = 'simple' | 'filled';
+
+export { }

package/dist/multi-select/index.js

@@ -1,4 +1,4 @@
-import { M as l } from "../shared/MultiSelect-DlaYWcPo.js";
+import { M as l } from "../shared/MultiSelect-CfKm_FPp.js";
 export {
   l as MultiSelect
 };

package/dist/{multi-select/MultiSelect.types.d.ts → multi-select.d.ts}

@@ -1,31 +1,62 @@
-import { MultiSelectSize, MultiSelectItemSize, MultiSelectDisplay, MultiSelectOptionItem } from '@tpc-development/mare-ui-components-core/multi-select';
-export type { MultiSelectSize, MultiSelectItemSize, MultiSelectDisplay, MultiSelectOptionItem, } from '@tpc-development/mare-ui-components-core/multi-select';
-export interface MultiSelectProperties {
-    options: MultiSelectOptionItem[];
-    placeholder?: string;
-    /** Placeholder for the search input inside the panel (shown when `filterable`). */
-    searchPlaceholder?: string;
-    size?: MultiSelectSize;
-    /** Size of each option row, independent from the control `size`. @default 'medium' */
-    itemSize?: MultiSelectItemSize;
-    disabled?: boolean;
-    invalid?: boolean;
-    /** Shows a spinner in place of the chevron. @default false */
-    loading?: boolean;
-    /** Shows a '×' button in the trigger to clear all selected values. @default false */
-    clearable?: boolean;
-    /** Shows a search input inside the panel. @default false */
-    filterable?: boolean;
-    /** Shows a checkbox next to each option (and the header toggle-all). @default true */
-    hasCheckbox?: boolean;
-    /** Shows a "select all" row at the top of the panel. @default false */
-    showToggleAll?: boolean;
-    /** Label next to the header toggle-all checkbox. */
-    headerLabel?: string;
-    /** How the selected values render in the trigger. @default 'text' */
-    display?: MultiSelectDisplay;
-    /** Max labels joined in `display: 'text'` before falling back to "N items selected". @default 3 */
-    maxSelectedLabels?: number;
-    label?: string;
-    emptyText?: string;
-}
+import { ForwardRefExoticComponent } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+
+declare const MULTI_SELECT_SIZES: readonly ["small", "medium"];
+
+export declare const MultiSelect: ForwardRefExoticComponent<MultiSelectReactProperties & RefAttributes<HTMLDivElement>>;
+
+export declare type MultiSelectDisplay = 'chip' | 'text';
+
+export declare type MultiSelectItemSize = 'small' | 'medium';
+
+export declare interface MultiSelectOptionItem {
+    label: string;
+    value: string;
+    disabled?: boolean;
+    /** Consumer-defined extras (icon, description…) resolved in the option slot. */
+    [key: string]: unknown;
+}
+
+export declare interface MultiSelectProperties {
+    options: MultiSelectOptionItem[];
+    placeholder?: string;
+    /** Placeholder for the search input inside the panel (shown when `filterable`). */
+    searchPlaceholder?: string;
+    size?: MultiSelectSize;
+    /** Size of each option row, independent from the control `size`. @default 'medium' */
+    itemSize?: MultiSelectItemSize;
+    disabled?: boolean;
+    invalid?: boolean;
+    /** Shows a spinner in place of the chevron. @default false */
+    loading?: boolean;
+    /** Shows a '×' button in the trigger to clear all selected values. @default false */
+    clearable?: boolean;
+    /** Shows a search input inside the panel. @default false */
+    filterable?: boolean;
+    /** Shows a checkbox next to each option (and the header toggle-all). @default true */
+    hasCheckbox?: boolean;
+    /** Shows a "select all" row at the top of the panel. @default false */
+    showToggleAll?: boolean;
+    /** Label next to the header toggle-all checkbox. */
+    headerLabel?: string;
+    /** How the selected values render in the trigger. @default 'text' */
+    display?: MultiSelectDisplay;
+    /** Max labels joined in `display: 'text'` before falling back to "N items selected". @default 3 */
+    maxSelectedLabels?: number;
+    label?: string;
+    emptyText?: string;
+}
+
+declare interface MultiSelectReactProperties extends MultiSelectProperties {
+    value?: string[];
+    onValueChange?: (value: string[]) => void;
+    indicator?: ReactNode;
+    clearIcon?: ReactNode;
+    filterIcon?: ReactNode;
+    renderOption?: (option: MultiSelectOptionItem) => ReactNode;
+}
+
+export declare type MultiSelectSize = (typeof MULTI_SELECT_SIZES)[number];
+
+export { }

package/dist/overlay-badge/index.js

@@ -1,4 +1,4 @@
-import { O as r } from "../shared/OverlayBadge-Dkosm3Il.js";
+import { O as r } from "../shared/OverlayBadge-CnQI_NE0.js";
 export {
   r as OverlayBadge
 };

package/dist/{overlay-badge/OverlayBadge.types.d.ts → overlay-badge.d.ts}

@@ -1,17 +1,25 @@
-import { ReactNode } from 'react';
-import { BadgeSeverity } from '@tpc-development/mare-ui-components-core/badge';
-export type { BadgeSeverity } from '@tpc-development/mare-ui-components-core/badge';
-export interface OverlayBadgeProperties {
-    /** Element the badge overlays. */
-    children: ReactNode;
-    /** @default 'accent' */
-    severity?: BadgeSeverity;
-    /** Shown inside the badge, next to (or instead of) `value`. */
-    icon?: ReactNode;
-    /** Badge content (count/label). A bare dot renders when neither this nor `icon` is set. */
-    value?: ReactNode;
-    /** Horizontal nudge (px) off the default corner position. @default 0 */
-    offsetX?: number;
-    /** Vertical nudge (px) off the default corner position. @default 0 */
-    offsetY?: number;
-}
+import { JSX as JSX_2 } from 'react';
+import { ReactNode } from 'react';
+
+declare const BADGE_SEVERITIES: readonly ["accent", "danger", "warning", "highlight", "positive"];
+
+export declare type BadgeSeverity = (typeof BADGE_SEVERITIES)[number];
+
+export declare function OverlayBadge({ children, severity, icon, value, offsetX, offsetY, }: OverlayBadgeProperties): JSX_2.Element;
+
+export declare interface OverlayBadgeProperties {
+    /** Element the badge overlays. */
+    children: ReactNode;
+    /** @default 'accent' */
+    severity?: BadgeSeverity;
+    /** Shown inside the badge, next to (or instead of) `value`. */
+    icon?: ReactNode;
+    /** Badge content (count/label). A bare dot renders when neither this nor `icon` is set. */
+    value?: ReactNode;
+    /** Horizontal nudge (px) off the default corner position. @default 0 */
+    offsetX?: number;
+    /** Vertical nudge (px) off the default corner position. @default 0 */
+    offsetY?: number;
+}
+
+export { }

package/dist/paginator/index.js

@@ -1,4 +1,4 @@
-import { P as r } from "../shared/Paginator-QTDpAJ-N.js";
+import { P as r } from "../shared/Paginator-BRQx1GRQ.js";
 export {
   r as Paginator
 };

package/dist/{paginator/Paginator.types.d.ts → paginator.d.ts}

@@ -1,21 +1,27 @@
-export interface PaginatorProperties {
-    /** Total number of data items (rows), NOT page count. */
-    count: number;
-    /** Controlled current page, 1-indexed. Omit to let Ark manage it. */
-    page?: number;
-    defaultPage?: number;
-    onPageChange?: (page: number) => void;
-    /** Items per page. */
-    pageSize?: number;
-    defaultPageSize?: number;
-    onPageSizeChange?: (pageSize: number) => void;
-    /** Numbered buttons shown at once — shrinks to fit a narrow container. */
-    pageLinkSize?: number;
-    /** Shows the jump-to-first/last-page buttons.
-     * @default true */
-    showFirstLastLinks?: boolean;
-    /** Shows the "rows per page" select when given 1+ options. */
-    rowsPerPageOptions?: number[];
-    /** @default 'Rows per page' */
-    rowsPerPageOptionsLabel?: string;
-}
+import { JSX as JSX_2 } from 'react';
+
+export declare function Paginator({ count, page, defaultPage, onPageChange, pageSize, defaultPageSize, onPageSizeChange, pageLinkSize, showFirstLastLinks, rowsPerPageOptions, rowsPerPageOptionsLabel, }: PaginatorProperties): JSX_2.Element;
+
+export declare interface PaginatorProperties {
+    /** Total number of data items (rows), NOT page count. */
+    count: number;
+    /** Controlled current page, 1-indexed. Omit to let Ark manage it. */
+    page?: number;
+    defaultPage?: number;
+    onPageChange?: (page: number) => void;
+    /** Items per page. */
+    pageSize?: number;
+    defaultPageSize?: number;
+    onPageSizeChange?: (pageSize: number) => void;
+    /** Numbered buttons shown at once — shrinks to fit a narrow container. */
+    pageLinkSize?: number;
+    /** Shows the jump-to-first/last-page buttons.
+     * @default true */
+    showFirstLastLinks?: boolean;
+    /** Shows the "rows per page" select when given 1+ options. */
+    rowsPerPageOptions?: number[];
+    /** @default 'Rows per page' */
+    rowsPerPageOptionsLabel?: string;
+}
+
+export { }

package/dist/panel-menu/index.js

@@ -1,4 +1,4 @@
-import { P as n } from "../shared/PanelMenu-BpjNM7O_.js";
+import { P as n } from "../shared/PanelMenu-Dw-K6H2C.js";
 export {
   n as PanelMenu
 };

package/dist/panel-menu.d.ts

@@ -0,0 +1,29 @@
+import { JSX as JSX_2 } from 'react';
+import { ReactNode } from 'react';
+
+export declare function PanelMenu({ items, expandedValue, defaultExpandedValue, onExpandedChange, renderItem, }: PanelMenuProperties): JSX_2.Element;
+
+export declare interface PanelMenuItemData {
+    value: string;
+    label: string;
+    disabled?: boolean;
+    /** Persistent highlight (e.g. current route) — distinct from Ark's own
+     * open/closed state on branches. Same pattern as Menu's `active` field. */
+    active?: boolean;
+    /** Nested entries — presence of this (non-empty) makes the node a branch. */
+    items?: PanelMenuItemData[];
+    /** Consumer-defined extras (icon, href, target…) resolved in the adapter. */
+    [key: string]: unknown;
+}
+
+export declare interface PanelMenuProperties {
+    items: PanelMenuItemData[];
+    /** Controlled expanded branch values. Omit to let Ark manage it (uncontrolled). */
+    expandedValue?: string[];
+    defaultExpandedValue?: string[];
+    onExpandedChange?: (value: string[]) => void;
+    /** Override the default icon + label row entirely. */
+    renderItem?: (item: PanelMenuItemData) => ReactNode;
+}
+
+export { }

package/dist/password/index.js

@@ -1,4 +1,4 @@
-import { P as a, a as r } from "../shared/Password-D4PRaleH.js";
+import { P as a, a as r } from "../shared/Password-BWNvygrO.js";
 export {
   a as Password,
   r as PasswordFooterItem