@toteat-eng/ds-react 2026.6.10-2 → 2026.6.10-4

package/dist/components/CloseButton/CloseButton.d.ts

@@ -11,7 +11,7 @@ export interface CloseButtonProps {
 }
 /**
  * Internal dismiss-button primitive. NOT part of the public API — used to
- * de-duplicate the bespoke close buttons across Dialog, Toast, Banner and
+ * de-duplicate the bespoke close buttons across Dialog, Toast, UserNotification and
  * OverlayMessage. Renders a single native `<button>` containing the canonical
  * `close-outline` icon.
  */

package/dist/components/Icon/__stories__/Icon.stories.d.ts

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Icon } from "../Icon";
+declare const meta: Meta<typeof Icon>;
+export default meta;
+type Story = StoryObj<typeof Icon>;
+export declare const Primary: Story;
+/**
+ * Gallery of every icon in the sprite. Use the search box / Ctrl+F to find one,
+ * then copy its name into the `name` prop. Names map 1:1 to the `IconNameType` union.
+ */
+export declare const AllIcons: Story;
+/** The `size` prop accepts a number (px) or any CSS length string. */
+export declare const Sizes: Story;
+/**
+ * Color is driven by `currentColor` by default — set `color` on a parent and the
+ * icon follows. The `color` prop maps a token suffix to `var(--color-<token>)`
+ * and only applies to `-outline` / `-filled` icons.
+ */
+export declare const Colors: Story;
+/**
+ * `currentColor` inheritance: no `color` prop is set on the icons below — they
+ * each inherit the text color of their wrapper, which is the recommended way to
+ * keep icons in sync with surrounding text.
+ */
+export declare const CurrentColorInheritance: Story;
+/**
+ * Accessibility:
+ * - **Decorative (default):** with no `aria-label`, the icon is `aria-hidden="true"`
+ *   and removed from the accessibility tree. Use this when the icon merely
+ *   decorates adjacent text (e.g. a labelled button).
+ * - **Meaningful:** pass `aria-label` to expose the icon as `role="img"` with an
+ *   accessible name. Use this when the icon is the only conveyor of meaning
+ *   (e.g. an icon-only button).
+ */
+export declare const Accessibility: Story;

package/dist/components/StatusBanner/StatusBanner.d.ts

@@ -0,0 +1,18 @@
+import type React from "react";
+import type { IconNameType } from "../Icon";
+export type StatusBannerVariant = "info" | "success" | "warning" | "error" | "neutral";
+export interface StatusBannerProps {
+    variant?: StatusBannerVariant;
+    icon?: IconNameType;
+    action?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+    "data-testid"?: string;
+}
+/**
+ * Persistent, non-dismissable status surface (e.g. POS connectivity).
+ * Shares the notification surface with UserNotification but never renders a
+ * dismiss control. Uses `aria-atomic="true"` so assistive tech re-announces the
+ * full message when its content changes.
+ */
+export declare function StatusBanner({ variant, icon, action, children, className, "data-testid": testId, }: StatusBannerProps): React.ReactElement;

package/dist/components/StatusBanner/__stories__/StatusBanner.stories.d.ts

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { StatusBanner } from "../StatusBanner";
+/**
+ * Persistent, non-dismissable status surface (e.g. POS connectivity).
+ *
+ * a11y note: when `variant="error"` the root is `role="alert"` /
+ * `aria-live="assertive"` / `aria-atomic="true"`. Do NOT mutate `children` on
+ * every render in an error/alert banner — each change re-announces the full
+ * message and floods screen-reader users. Update the text only when the
+ * underlying status actually changes.
+ */
+declare const meta: Meta<typeof StatusBanner>;
+export default meta;
+type Story = StoryObj<typeof StatusBanner>;
+export declare const Info: Story;
+export declare const Success: Story;
+export declare const Warning: Story;
+export declare const Error: Story;
+export declare const Neutral: Story;
+export declare const WithIcon: Story;
+export declare const WithAction: Story;
+export declare const AllVariants: Story;
+export declare const BothThemes: Story;

package/dist/components/StatusBanner/index.d.ts

@@ -0,0 +1,2 @@
+export type { StatusBannerProps, StatusBannerVariant } from "./StatusBanner";
+export { StatusBanner } from "./StatusBanner";

package/dist/components/Tab/Tab.d.ts

@@ -0,0 +1,34 @@
+import type { GroupedButtonSize } from "../GroupedButtons";
+import type { IconName } from "../Icon";
+export type TabValue = string | number;
+export type TabSelectedColor = "primary" | "secondary" | "tertiary" | "neutral-100";
+export interface TabItem {
+    value: TabValue;
+    label: string;
+    disabled?: boolean;
+    icon?: IconName;
+}
+export interface TabProps {
+    /** Tabs to render as a segmented control. */
+    tabs: TabItem[];
+    /** Accessible label for the tablist / button group. */
+    label: string;
+    /** Controlled selected value. When provided the caller owns selection. */
+    selectedTab?: TabValue;
+    /** Size of the control. Defaults to "medium". */
+    size?: GroupedButtonSize;
+    /** Stretch the control to fill its container. Defaults to true (Vue3 parity). */
+    fullWidth?: boolean;
+    /** Color applied to the selected pill. Defaults to "secondary". */
+    selectedColor?: TabSelectedColor;
+    /** Fired whenever a (non-disabled) tab is selected. */
+    onChange?: (value: TabValue) => void;
+    /** Fired on tab click with the full tab descriptor. */
+    onTabClick?: (tab: {
+        value: TabValue;
+        label: string;
+    }) => void;
+    className?: string;
+    "data-testid"?: string;
+}
+export declare function Tab({ tabs, label, selectedTab, size, fullWidth, selectedColor, onChange, onTabClick, className, "data-testid": testId, }: TabProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Tab/__stories__/Tab.stories.d.ts

@@ -0,0 +1,13 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Tab } from "../Tab";
+declare const meta: Meta<typeof Tab>;
+export default meta;
+type Story = StoryObj<typeof Tab>;
+export declare const Default: Story;
+export declare const ControlledExample: Story;
+export declare const Sizes: Story;
+export declare const FitContent: Story;
+export declare const WithIcons: Story;
+export declare const DisabledTab: Story;
+export declare const SelectedColors: Story;
+export declare const BothThemes: Story;

package/dist/components/Tab/index.d.ts

@@ -0,0 +1,2 @@
+export type { TabItem, TabProps, TabSelectedColor, TabValue } from "./Tab";
+export { Tab } from "./Tab";

package/dist/components/TextInput/TextInput.d.ts

@@ -1,9 +1,55 @@
-import { type InputHTMLAttributes } from "react";
+import { type InputHTMLAttributes, type ReactNode } from "react";
+import type { IconNameType } from "../Icon/icons";
 export type TextInputSize = "small" | "medium" | "large";
+/**
+ * Validation state, mirroring the Vue3 DS `TextInput`. `default` is the resting
+ * state; `success` / `warning` / `error` drive the field border, optional status
+ * icon, and (for `error`) `aria-invalid`. The legacy `error` boolean prop is kept
+ * for backward compatibility and is treated as `validationState="error"`.
+ */
+export type TextInputValidationState = "default" | "success" | "warning" | "error";
 export interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+    /** Control height / typography scale. */
+    size?: TextInputSize;
+    /**
+     * Legacy shorthand for an error look. Equivalent to `validationState="error"`.
+     * Kept for backward compatibility — existing consumers pass `error`.
+     */
     error?: boolean;
+    /** Renders an eye toggle for `type="password"` fields. */
     showPasswordToggle?: boolean;
-    size?: TextInputSize;
+    /** Visible `<label>` associated with the input. */
+    label?: ReactNode;
+    /** Shows a red `*` after the label and sets `aria-required`. */
+    required?: boolean;
+    /** Validation state. Takes precedence over the legacy `error` boolean. */
+    validationState?: TextInputValidationState;
+    /** Error message; shown only when the resolved state is `error`. Wires `aria-describedby`. */
+    errorMessage?: ReactNode;
+    /** Helper / hint text shown below the field. Wires `aria-describedby`. */
+    helperText?: ReactNode;
+    /** Alignment of the helper text relative to the character counter. */
+    helperTextAlign?: "left" | "right";
+    /** Icon rendered before the input. */
+    prefixIcon?: IconNameType;
+    /** Icon rendered after the input (suppressed when clear / password / status icon shows). */
+    suffixIcon?: IconNameType;
+    /** Shows a clear (×) button when the field has a value. Requires `value` + `onChange`. */
+    clearable?: boolean;
+    /** Callback fired when the clear button is pressed (after clearing the value). */
+    onClear?: () => void;
+    /** Accessible label for the clear button. @default "Limpiar" */
+    clearLabel?: string;
+    /** Accessible label for the password-reveal button while the password is hidden. @default "Mostrar contraseña" */
+    showPasswordLabel?: string;
+    /** Accessible label for the password-reveal button while the password is shown. @default "Ocultar contraseña" */
+    hidePasswordLabel?: string;
+    /** Shows a character counter. Implicitly enabled when `maxLength` is set. */
+    showCounter?: boolean;
+    /** Renders the status icon (success / warning / error) inside the field. Defaults to `true`. */
+    showValidationIcon?: boolean;
+    /** Makes the field span the full width of its container. */
+    fullWidth?: boolean;
     "data-testid"?: string;
 }
 export declare const TextInput: import("react").ForwardRefExoticComponent<TextInputProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/TextInput/__stories__/TextInput.stories.d.ts

@@ -11,4 +11,15 @@ export declare const EmailInput: Story;
 export declare const PasswordInput: Story;
 export declare const PasswordWithToggle: Story;
 export declare const SearchInput: Story;
+export declare const WithLabel: Story;
+export declare const Required: Story;
+export declare const WithHelperText: Story;
+export declare const WithErrorMessage: Story;
+export declare const ValidationStates: Story;
+export declare const WithPrefixIcon: Story;
+export declare const WithSuffixIcon: Story;
+export declare const Clearable: Story;
+export declare const WithCounter: Story;
+export declare const Sizes: Story;
+export declare const FullWidth: Story;
 export declare const States: Story;

package/dist/components/TextInput/index.d.ts

@@ -1,2 +1,2 @@
-export type { TextInputProps } from "./TextInput";
+export type { TextInputProps, TextInputSize, TextInputValidationState } from "./TextInput";
 export { TextInput } from "./TextInput";

package/dist/components/UserNotification/NotificationBase.d.ts

@@ -0,0 +1,41 @@
+import type React from "react";
+import type { IconNameType } from "../Icon";
+/**
+ * Shared presentational/ARIA shell for notification-surface primitives
+ * (UserNotification, StatusBanner). INTERNAL — never exported from any index.ts.
+ *
+ * Owns only structure + ARIA. Each caller supplies its own CSS-module root
+ * class (`rootClassName`) so visual variance (e.g. enter animation, inline-flex
+ * vs flex) lives entirely in the caller's module.css.
+ */
+export type NotificationVariant = "info" | "success" | "warning" | "error" | "neutral";
+export interface NotificationBaseProps {
+    variant: NotificationVariant;
+    /**
+     * Caller's CSS-module root class (e.g. styles.notification / styles.statusBanner).
+     * Typed loosely because CSS-module lookups widen to `string | undefined` under
+     * `noUncheckedIndexedAccess`.
+     */
+    rootClassName: string | undefined;
+    /** Caller's content span class. */
+    contentClassName: string | undefined;
+    /** Caller's action span class. */
+    actionClassName: string | undefined;
+    icon?: IconNameType;
+    action?: React.ReactNode;
+    children: React.ReactNode;
+    /** Extra consumer-supplied className, merged after the module root class. */
+    className?: string;
+    "data-testid"?: string;
+    /**
+     * Trailing control (e.g. UserNotification passes <CloseButton/>).
+     * StatusBanner omits it — no element is rendered when undefined.
+     */
+    dismissSlot?: React.ReactNode;
+    /**
+     * Adds aria-atomic="true" to the root. Opt-in so callers that must keep a
+     * frozen DOM (UserNotification) are unaffected.
+     */
+    ariaAtomic?: boolean;
+}
+export declare function NotificationBase({ variant, rootClassName, contentClassName, actionClassName, icon, action, children, className, "data-testid": testId, dismissSlot, ariaAtomic, }: NotificationBaseProps): React.ReactElement;

package/dist/components/UserNotification/UserNotification.d.ts

@@ -0,0 +1,15 @@
+import type React from "react";
+import type { IconNameType } from "../Icon";
+export type UserNotificationVariant = "info" | "success" | "warning" | "error" | "neutral";
+export interface UserNotificationProps {
+    variant?: UserNotificationVariant;
+    icon?: IconNameType;
+    /** Required — a user notification is always dismissable. */
+    onDismiss: () => void;
+    dismissLabel?: string;
+    action?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+    "data-testid"?: string;
+}
+export declare function UserNotification({ variant, icon, onDismiss, dismissLabel, action, children, className, "data-testid": testId, }: UserNotificationProps): React.ReactElement;

package/dist/components/{Banner/__stories__/Banner.stories.d.ts → UserNotification/__stories__/UserNotification.stories.d.ts}

@@ -1,16 +1,15 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { Banner } from "../Banner";
-declare const meta: Meta<typeof Banner>;
+import { UserNotification } from "../UserNotification";
+declare const meta: Meta<typeof UserNotification>;
 export default meta;
-type Story = StoryObj<typeof Banner>;
+type Story = StoryObj<typeof UserNotification>;
 export declare const Info: Story;
 export declare const Success: Story;
 export declare const Warning: Story;
 export declare const Error: Story;
 export declare const Neutral: Story;
 export declare const WithIcon: Story;
-export declare const WithDismiss: Story;
 export declare const WithAction: Story;
-export declare const WithDismissAndAction: Story;
+export declare const WithAndAction: Story;
 export declare const AllVariants: Story;
 export declare const BothThemes: Story;

package/dist/components/UserNotification/index.d.ts

@@ -0,0 +1,2 @@
+export type { UserNotificationProps, UserNotificationVariant } from "./UserNotification";
+export { UserNotification } from "./UserNotification";

package/dist/hooks/useDropdown.d.ts

@@ -0,0 +1,59 @@
+export interface UseDropdownOptions {
+    /** Number of navigable items. Used to clamp the active index for roving keyboard nav. */
+    itemCount?: number;
+    /** Called when an item is chosen via keyboard (Enter/Space) at the active index. */
+    onSelectIndex?: (index: number) => void;
+    /** Fired after the dropdown opens. */
+    onOpen?: () => void;
+    /** Fired after the dropdown closes (any cause: toggle, Escape, outside-click, select). */
+    onClose?: () => void;
+    /** When true, toggle/open are no-ops. */
+    disabled?: boolean;
+    /**
+     * When false, the document `mousedown` outside-click handler is disabled.
+     * Defaults to true. (Some legacy components historically used `click` instead of
+     * `mousedown`; this option lets a component skip the shared handler if it must.)
+     */
+    closeOnOutsideClick?: boolean;
+}
+export interface UseDropdownReturn {
+    /** Whether the dropdown is currently open. */
+    isOpen: boolean;
+    /** Attach to the dropdown root: scopes outside-click detection. */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** Attach to the trigger: focus is returned here on Escape / close. */
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
+    /** Index of the keyboard-active item (-1 when none). */
+    activeIndex: number;
+    /** Imperatively set the keyboard-active item index. */
+    setActiveIndex: (index: number) => void;
+    /** Open the dropdown (no-op when disabled). Resets active index to -1. */
+    open: () => void;
+    /** Close the dropdown. Resets active index to -1. Does NOT move focus. */
+    close: () => void;
+    /** Close the dropdown AND return focus to the trigger. */
+    closeAndFocusTrigger: () => void;
+    /** Toggle open/closed (no-op when disabled). */
+    toggle: () => void;
+    /**
+     * Roving keyboard handler modeled on DropdownButton's interaction:
+     * - closed: Enter/Space/ArrowDown open and focus the first item
+     * - open: ArrowDown/ArrowUp move the active index (clamped), Home/End jump to ends,
+     *   Enter/Space select the active item, Escape closes + returns focus, Tab closes.
+     * Components that own a different keyboard model can ignore this and use the
+     * primitives (open/close/activeIndex) directly.
+     */
+    handleTriggerKeyDown: (e: React.KeyboardEvent) => void;
+}
+/**
+ * Shared, headless dropdown interaction core. Internal — NOT part of the public API.
+ *
+ * Models the canonical Toteat dropdown UX used by `DropdownButton` (TRM login's
+ * `LanguageSelector`): open/close/toggle, document outside-click-to-close, Escape-to-close,
+ * roving Arrow/Home/End keyboard navigation with an active index, Enter/Space to select,
+ * and focus-return-to-trigger on close.
+ *
+ * Markup, ARIA, and selection semantics stay in the consuming component; this hook owns
+ * only the behaviour that every dropdown shares.
+ */
+export declare function useDropdown(options?: UseDropdownOptions): UseDropdownReturn;

package/dist/index.d.ts

@@ -9,8 +9,6 @@ export type { BackgroundWrapperProps } from "./components/BackgroundWrapper";
 export { BackgroundWrapper } from "./components/BackgroundWrapper";
 export type { BadgeProps, BadgeSize, BadgeVariant } from "./components/Badge";
 export { Badge } from "./components/Badge";
-export type { BannerProps, BannerVariant } from "./components/Banner";
-export { Banner } from "./components/Banner";
 export type { BreadcrumbItem, BreadcrumbProps } from "./components/Breadcrumb";
 export { Breadcrumb } from "./components/Breadcrumb";
 export type { ButtonProps, ButtonSize, ButtonVariant, } from "./components/Button";
@@ -100,15 +98,19 @@ export type { SpinnerProps, SpinnerSize } from "./components/Spinner";
 export { Spinner } from "./components/Spinner";
 export type { StatusBadgeProps } from "./components/StatusBadge";
 export { StatusBadge } from "./components/StatusBadge";
+export type { StatusBannerProps, StatusBannerVariant } from "./components/StatusBanner";
+export { StatusBanner } from "./components/StatusBanner";
 export type { StepperProps } from "./components/Stepper";
 export { Stepper } from "./components/Stepper";
+export type { TabItem as SegmentedTabItem, TabProps, TabSelectedColor, TabValue, } from "./components/Tab";
+export { Tab } from "./components/Tab";
 export type { TabBarProps, TabBarVariant } from "./components/TabBar";
 export { TabBar } from "./components/TabBar";
 export type { TabItem, TabsProps } from "./components/Tabs";
 export { Tabs } from "./components/Tabs";
 export type { TextareaProps } from "./components/Textarea";
 export { Textarea } from "./components/Textarea";
-export type { TextInputProps } from "./components/TextInput";
+export type { TextInputProps, TextInputSize, TextInputValidationState, } from "./components/TextInput";
 export { TextInput } from "./components/TextInput";
 export type { ThemeGateProps } from "./components/ThemeGate/ThemeGate";
 export { ThemeGate } from "./components/ThemeGate/ThemeGate";
@@ -123,6 +125,8 @@ export { TreeItem } from "./components/TreeItem";
 export type { TreeItemData } from "./components/TreeItem/treeTypes";
 export type { TreeListProps } from "./components/TreeList";
 export { TreeList } from "./components/TreeList";
+export type { UserNotificationProps, UserNotificationVariant, } from "./components/UserNotification";
+export { UserNotification } from "./components/UserNotification";
 export type { AdminPageHeaderProps } from "./layouts/AdminPageHeader";
 export { AdminPageHeader } from "./layouts/AdminPageHeader";
 export type { AppShellProps } from "./layouts/AppShell";