@tap-payments/os-micro-frontend-shared 0.3.23 → 0.3.25

package/build/components/_v2/primitives/Button/Button.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+import type { ButtonBaseProps } from '@mui/material/ButtonBase';
+import type { SxProps, Theme } from '@mui/material/styles';
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+export interface ButtonProps extends Omit<ButtonBaseProps, 'children'> {
+    /** Button label or content */
+    children?: ReactNode;
+    /** Visual style — primary (blue), secondary (outlined), ghost (text), danger (red) */
+    variant?: ButtonVariant;
+    /** Height and font size — sm: 24px, md: 32px, lg: 40px */
+    size?: ButtonSize;
+    /** Shows a spinner and disables the button */
+    loading?: boolean;
+    /** Icon placed before the label */
+    startIcon?: ReactNode;
+    /** Icon placed after the label */
+    endIcon?: ReactNode;
+    /** Stretches button to 100% of its container */
+    fullWidth?: boolean;
+    /** MUI sx style overrides */
+    sx?: SxProps<Theme>;
+}
+declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>>;
+export default _default;

package/build/components/_v2/primitives/Button/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './Button';
+export type { ButtonProps, ButtonVariant, ButtonSize } from './Button';

package/build/components/_v2/primitives/Calender/Calender.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="react" />
+import { type PopperPlacementType } from '@mui/material/Popper';
+import type { BoxProps } from '@mui/material/Box';
+import { type CalendarProps as MDPickerProps, DateObject } from 'react-multi-date-picker';
+export interface CalenderProps extends MDPickerProps {
+    /** Render in right-to-left / Hijri calendar mode */
+    isAr?: boolean;
+    /** Controlled selected date */
+    value?: DateObject;
+    /** Called with the confirmed date when the user clicks OK */
+    setValue?: (v: DateObject) => void;
+    /** Popper anchor placement relative to the trigger */
+    placement?: PopperPlacementType;
+    /** MUI sx overrides for the trigger wrapper */
+    sx?: BoxProps['sx'];
+}
+/**
+ * Single-date calendar picker rendered in a Popper. Supports Hijri (Arabic) calendar via `isAr`.
+ * Pass `value` / `setValue` for controlled state and `placement` to anchor the Popper.
+ * Use RHFCalender for React Hook Form integration.
+ */
+declare function Calender({ isAr, value, setValue, placement, sx, ...props }: CalenderProps): import("react").JSX.Element;
+declare namespace Calender {
+    var displayName: string;
+}
+export type { DateObject };
+declare const _default: import("react").MemoExoticComponent<typeof Calender>;
+export default _default;

package/build/components/_v2/primitives/Calender/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './Calender';
+export type { CalenderProps, DateObject } from './Calender';

package/build/components/_v2/primitives/Calender/style.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="react" />
+export declare const ArrowButton: import("@emotion/styled").StyledComponent<import("@mui/material/Button").ButtonOwnProps & Omit<import("@mui/material").ButtonBaseOwnProps, "classes"> & import("@mui/material/OverridableComponent").CommonProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+    ref?: ((instance: HTMLButtonElement | null) => void) | import("react").RefObject<HTMLButtonElement> | null | undefined;
+}, "color" | "disabled" | "classes" | "className" | "style" | "tabIndex" | "children" | "sx" | "variant" | "size" | "fullWidth" | "href" | "action" | "centerRipple" | "disableRipple" | "disableTouchRipple" | "focusRipple" | "focusVisibleClassName" | "LinkComponent" | "onFocusVisible" | "TouchRippleProps" | "touchRippleRef" | "disableElevation" | "disableFocusRipple" | "endIcon" | "startIcon"> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, {}, {}>;
+export declare const Wrapper: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme>> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, {}, {}>;
+export declare const CalenderWrapper: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme>> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme> & {
+    open: boolean;
+}, {}, {}>;
+export declare const SelectedDate: import("@emotion/styled").StyledComponent<import("@mui/material/Button").ButtonOwnProps & Omit<import("@mui/material").ButtonBaseOwnProps, "classes"> & import("@mui/material/OverridableComponent").CommonProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+    ref?: ((instance: HTMLButtonElement | null) => void) | import("react").RefObject<HTMLButtonElement> | null | undefined;
+}, "color" | "disabled" | "classes" | "className" | "style" | "tabIndex" | "children" | "sx" | "variant" | "size" | "fullWidth" | "href" | "action" | "centerRipple" | "disableRipple" | "disableTouchRipple" | "focusRipple" | "focusVisibleClassName" | "LinkComponent" | "onFocusVisible" | "TouchRippleProps" | "touchRippleRef" | "disableElevation" | "disableFocusRipple" | "endIcon" | "startIcon"> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme> & {
+    open: boolean;
+}, {}, {}>;
+export declare const ButtonsWrapper: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme>> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, {}, {}>;
+export declare const CancelButton: import("@emotion/styled").StyledComponent<import("@mui/material/Button").ButtonOwnProps & Omit<import("@mui/material").ButtonBaseOwnProps, "classes"> & import("@mui/material/OverridableComponent").CommonProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+    ref?: ((instance: HTMLButtonElement | null) => void) | import("react").RefObject<HTMLButtonElement> | null | undefined;
+}, "color" | "disabled" | "classes" | "className" | "style" | "tabIndex" | "children" | "sx" | "variant" | "size" | "fullWidth" | "href" | "action" | "centerRipple" | "disableRipple" | "disableTouchRipple" | "focusRipple" | "focusVisibleClassName" | "LinkComponent" | "onFocusVisible" | "TouchRippleProps" | "touchRippleRef" | "disableElevation" | "disableFocusRipple" | "endIcon" | "startIcon"> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, {}, {}>;
+export declare const OkayButton: import("@emotion/styled").StyledComponent<import("@mui/material/Button").ButtonOwnProps & Omit<import("@mui/material").ButtonBaseOwnProps, "classes"> & import("@mui/material/OverridableComponent").CommonProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+    ref?: ((instance: HTMLButtonElement | null) => void) | import("react").RefObject<HTMLButtonElement> | null | undefined;
+}, "color" | "disabled" | "classes" | "className" | "style" | "tabIndex" | "children" | "sx" | "variant" | "size" | "fullWidth" | "href" | "action" | "centerRipple" | "disableRipple" | "disableTouchRipple" | "focusRipple" | "focusVisibleClassName" | "LinkComponent" | "onFocusVisible" | "TouchRippleProps" | "touchRippleRef" | "disableElevation" | "disableFocusRipple" | "endIcon" | "startIcon"> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, {}, {}>;
+export declare const FooterButtonsWrapper: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme>> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, {}, {}>;

package/build/components/_v2/primitives/Checkbox/Checkbox.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import type { CheckboxProps as MuiCheckboxProps } from '@mui/material/Checkbox';
+import type { SxProps, Theme } from '@mui/material/styles';
+export interface CheckboxProps extends MuiCheckboxProps {
+    /** Optional label rendered inline next to the checkbox */
+    label?: ReactNode;
+    /** Position of the label relative to the checkbox */
+    labelPlacement?: 'end' | 'start' | 'top' | 'bottom';
+    /** MUI sx style overrides */
+    sx?: SxProps<Theme>;
+}
+declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>>;
+export default _default;

package/build/components/_v2/primitives/Checkbox/icons.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="react" />
+/** Filled blue box with white checkmark — checked state. */
+export declare const CheckboxCheckedIcon: import("react").JSX.Element;
+/** White box with grey border and grey checkmark — unchecked state. */
+export declare const CheckboxUncheckedIcon: import("react").JSX.Element;
+/**
+ * White box with grey border, no inner mark — used as the unchecked icon in
+ * MultiSelect option rows where the checkbox mark is always shown alongside
+ * separate checked/unchecked visuals.
+ */
+export declare const CheckboxEmptyIcon: import("react").JSX.Element;

package/build/components/_v2/primitives/Checkbox/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './Checkbox';
+export type { CheckboxProps } from './Checkbox';
+export { CheckboxCheckedIcon, CheckboxUncheckedIcon, CheckboxEmptyIcon } from './icons';

package/build/components/_v2/primitives/Chip/Chip.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import type { ChipProps } from './type';
+declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<ChipProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>>;
+export default _default;

package/build/components/_v2/primitives/Chip/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './Chip';
+export type { ChipProps, ChipVariant } from './type';

package/build/components/_v2/primitives/Chip/style.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+import type { ChipProps } from './type';
+type ChipShellProps = Pick<ChipProps, 'variant' | 'icon' | 'isSelected' | 'disableAnimation'>;
+export declare const ChipShell: import("@emotion/styled").StyledComponent<Omit<ChipShellProps & import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme> & import("@mui/material/OverridableComponent").CommonProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/material/OverridableComponent").CommonProps | keyof import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme>>, "ref"> & import("react").RefAttributes<HTMLDivElement> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme> & ChipShellProps, {}, {}>;
+export declare const ChipTextWrapper: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<import("@mui/material/styles").Theme>> & import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, {}, {}>;
+export {};

package/build/components/_v2/primitives/Chip/type.d.ts

@@ -0,0 +1,25 @@
+import type { BoxProps } from '@mui/material/Box';
+import type { PropsWithChildren, ReactElement } from 'react';
+export type ChipVariant = 'text' | 'circular' | 'pill-icon';
+export interface ChipProps extends PropsWithChildren<BoxProps> {
+    /** Visual shape — `text` (default), `circular` (avatar-style), or `pill-icon` */
+    variant?: ChipVariant;
+    /** Icon element shown to the left of the chip label */
+    icon?: ReactElement | null;
+    /** Dims the chip and disables pointer interaction */
+    disabled?: boolean;
+    /** Marks the chip as selected — shows a drop-shadow */
+    isSelected?: boolean;
+    /**
+     * When provided, a copy icon is rendered alongside the label.
+     * Clicking it copies this string and briefly shows a green checkmark.
+     */
+    copyText?: string;
+    /**
+     * i18n key shown when `children` is empty/undefined.
+     * Defaults to the `'unknown'` translation key.
+     */
+    unknownText?: string;
+    /** Disable all transitions and animations (useful in tests or dense tables) */
+    disableAnimation?: boolean;
+}

package/build/components/_v2/primitives/ChipStack/ChipStack.d.ts

@@ -0,0 +1,73 @@
+/// <reference types="react" />
+import type { ChipStackProps } from './type';
+/**
+ * Overlapping chip row for avatars, logos, flags, or any circular content.
+ *
+ * ### Variant
+ * Pick one of four variants — the variant encodes both the render mode and fan-out direction:
+ *
+ * | Variant | Behavior |
+ * |---|---|
+ * | `"static"` *(default)* | Overlapping row, no animation |
+ * | `"fanout-right"` | Fans right on hover (anchor: leftmost chip) |
+ * | `"fanout-left"` | Fans left on hover (anchor: rightmost chip) |
+ * | `"fanout-center"` | Fans both ways on hover (anchor: middle chip) |
+ *
+ * Add `compact` to show only the anchor chip until hovered.
+ *
+ * ### Input styles
+ * - **Data-driven** — `items` + `getItemKey` + `renderItem`
+ * - **Compositional** — `children` (wrap in `<OverlapChip>` for static, or pass raw nodes)
+ *
+ * When both are provided, `children` takes precedence. Face avatars: `ChipStackFaceSlot` in `renderItem` with `getChipStackFaceItemKey` as `getItemKey`.
+ * Hoist `renderItem` to module scope when referential stability matters.
+ *
+ * ---
+ *
+ * ### Examples
+ *
+ * ```tsx
+ * <ChipStack
+ *   variant="fanout-right"
+ *   items={members}
+ *   getItemKey={getChipStackFaceItemKey}
+ *   renderItem={(item, index, { slotSize }) => (
+ *     <ChipStackFaceSlot item={item} sourceIndex={index} slotSize={slotSize} />
+ *   )}
+ * />
+ * ```
+ *
+ * ```tsx
+ * // Brand logos — static overlap row
+ * <ChipStack variant="static" maxItems={4}>
+ *   {methods.map((m) => (
+ *     <OverlapChip key={m.id} title={m.label}>
+ *       <img src={m.logo} alt={m.label} />
+ *     </OverlapChip>
+ *   ))}
+ * </ChipStack>
+ * ```
+ *
+ * ```tsx
+ * // Custom overflow slot
+ * <ChipStack
+ *   variant="fanout-right"
+ *   items={assignees}
+ *   getItemKey={(a) => a.id}
+ *   renderItem={renderFaceItem}
+ *   maxItems={3}
+ *   renderOverflow={({ overflowItems, size }) => (
+ *     <MyBadge count={overflowItems.length} size={size} />
+ *   )}
+ * />
+ * ```
+ */
+/**
+ * Displays a stack of Chip items with overflow handling and optional fan-out animation.
+ * Items beyond `maxVisible` are collapsed into an overflow chip showing the remaining count.
+ * Supports `static` (simple row) and `animated` (fan-out reveal) variants.
+ * Use `ChipStackFaceSlot` to customise the overflow chip rendering.
+ */
+declare function ChipStack<T = unknown>(props: Readonly<ChipStackProps<T>>): import("react").JSX.Element | null;
+export default ChipStack;
+export { ChipStack };

package/build/components/_v2/primitives/ChipStack/components/AnimatedStack.d.ts

@@ -0,0 +1,34 @@
+import type { BoxProps } from '@mui/material/Box';
+import type { ReactNode } from 'react';
+import type { ChipStackOverflowRenderArgs, ChipStackFanOutDirection, ChipStackItemRenderContext, ChipStackSlotProps } from '../type';
+type AnimatedStackProps<T> = {
+    /** Compositional children (used when not supplying `items`) */
+    children?: ReactNode;
+    /** Data array for the data-driven usage pattern */
+    items?: readonly T[];
+    /** Maximum number of visible chips before collapsing into an overflow slot */
+    maxItems?: number;
+    /** Returns a stable string key for each data item */
+    getItemKey?: (item: T, index: number) => string;
+    /** Renders a chip for each data item */
+    renderItem?: (item: T, index: number, ctx: ChipStackItemRenderContext) => ReactNode;
+    /** Custom renderer for the overflow `+N` slot */
+    renderOverflow?: (args: ChipStackOverflowRenderArgs<T>) => ReactNode;
+    /** Fan-out direction derived from `variant` in the parent. */
+    fanOutDirection: ChipStackFanOutDirection;
+    /**
+     * When `true` (`compact` prop on `ChipStack`), only the anchor chip is
+     * visible while idle. Hovering reveals all chips with the fan-out animation.
+     */
+    compact?: boolean;
+    /** Test ID forwarded to the inner track element */
+    'data-testid'?: string;
+    /** MUI sx style overrides for the outer shell */
+    sx?: BoxProps['sx'];
+    /** Additional CSS class name applied to the outer shell */
+    className?: string;
+    /** Fine-grained slot and layout overrides */
+    slotProps?: Pick<ChipStackSlotProps, 'shell' | 'track' | 'layout'>;
+};
+export default function AnimatedStack<T>({ items, children, maxItems, getItemKey, renderItem, renderOverflow, fanOutDirection, compact, 'data-testid': dataTestId, sx, className, slotProps, }: Readonly<AnimatedStackProps<T>>): import("react").JSX.Element | null;
+export {};

package/build/components/_v2/primitives/ChipStack/components/ChipStackFaceSlot.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="react" />
+import type { ChipStackFaceItem } from '../type';
+export type ChipStackFaceSlotProps = {
+    /** Face item data (name, optional photo URL, optional tooltip) */
+    item: ChipStackFaceItem;
+    /** Zero-based index of this chip within the data array */
+    sourceIndex: number;
+    /** Chip diameter in pixels; the avatar is rendered at this size */
+    slotSize: number;
+};
+/** Face chip for `ChipStack` `renderItem`. */
+declare function ChipStackFaceSlot({ item, sourceIndex, slotSize }: ChipStackFaceSlotProps): import("react").JSX.Element;
+export default ChipStackFaceSlot;

package/build/components/_v2/primitives/ChipStack/components/OverlapChip.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentProps } from 'react';
+import { StyledOverlapChip } from '../style';
+/**
+ * Single circular chip used inside `ChipStack` (**static** variant). Pass an icon, image, or text node as children.
+ * Use a `title` for the hover tooltip.
+ */
+declare function OverlapChip(props: ComponentProps<typeof StyledOverlapChip>): import("react").JSX.Element;
+declare const _default: import("react").MemoExoticComponent<typeof OverlapChip>;
+export default _default;

package/build/components/_v2/primitives/ChipStack/components/StaticStack.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { BoxProps } from '@mui/material/Box';
+import type { ReactNode } from 'react';
+import type { ChipStackOverflowRenderArgs } from '../type';
+export type StaticStackProps = BoxProps & {
+    /** Maximum number of visible chips before collapsing into an overflow slot */
+    maxItems?: number;
+    /** Custom renderer for the overflow `+N` chip slot */
+    renderOverflow?: (args: ChipStackOverflowRenderArgs<ReactNode>) => ReactNode;
+    /** Chip diameter in pixels used to size the overflow chip consistently */
+    slotSize?: number;
+};
+declare function StaticStack({ children, maxItems, renderOverflow, slotSize, sx, ...props }: StaticStackProps): React.JSX.Element;
+declare const _default: React.MemoExoticComponent<typeof StaticStack>;
+export default _default;

package/build/components/_v2/primitives/ChipStack/constants.d.ts

@@ -0,0 +1,14 @@
+/** Default circular slot size (px); used to derive stack step, gap, and min track width. */
+export declare const OVERLAP_STACK_SIZE_PX = 24;
+export declare const OVERLAP_STACK_GAP_PX = 3;
+export declare const OVERLAP_STACK_MIN_TRACK_WIDTH_PX = 60;
+/** Fan-out animation duration (s) for the animated variant (per-slot translate transitions). */
+export declare const CHIP_STACK_ANIMATED_DURATION_S = 0.22;
+/** Hover-leave debounce (ms) before collapsing the row, to absorb pointer jitter between slots. */
+export declare const CHIP_STACK_HOVER_LEAVE_MS = 120;
+/** Default elevated z-index applied to the track while hovered. */
+export declare const CHIP_STACK_DEFAULT_HOVER_Z_INDEX = 1000;
+/** Minimum legible font size for the overflow chip. */
+export declare const CHIP_STACK_OVERFLOW_MIN_FONT_PX = 8;
+/** Reference font size for the overflow chip at the default slot size. */
+export declare const CHIP_STACK_OVERFLOW_REF_FONT_PX = 8.5;

package/build/components/_v2/primitives/ChipStack/hooks/useAnimatedStack.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="react" />
+export type UseAnimatedStackArgs = {
+    slotCount: number;
+    /** Anchor slot index — resolved from fan direction in `AnimatedStack`. */
+    anchorIndex: number;
+    size: number;
+    stackStep: number;
+    gap: number;
+    /** Whether hover should expand the row into the fanned layout. */
+    fanOutEnabled: boolean;
+    /**
+     * When `true` (`compact` prop on `ChipStack`), non-anchor chips are
+     * invisible while idle and animate into view on hover.
+     */
+    compact: boolean;
+};
+export declare function useAnimatedStack({ slotCount, anchorIndex, size, stackStep, gap, fanOutEnabled, compact }: UseAnimatedStackArgs): {
+    isHovering: boolean;
+    handleMouseEnter: () => void;
+    handleMouseLeave: () => void;
+    slotRefs: import("react").MutableRefObject<(HTMLDivElement | null)[]>;
+    translateX: number[];
+    slotOpacity: number[];
+    collapsedStackWidthPx: number;
+    fannedRowWidthPx: number;
+    trackWidth: number;
+    hoverZIndexActive: boolean;
+};

package/build/components/_v2/primitives/ChipStack/index.d.ts

@@ -0,0 +1,10 @@
+import ChipStack from './ChipStack';
+export default ChipStack;
+export { ChipStack };
+export { default as OverlapChip } from './components/OverlapChip';
+export { default as ChipStackFaceSlot } from './components/ChipStackFaceSlot';
+export type { ChipStackFaceSlotProps } from './components/ChipStackFaceSlot';
+export { getChipStackFaceItemKey } from './util';
+export { OVERLAP_STACK_SIZE_PX, CHIP_STACK_ANIMATED_DURATION_S } from './constants';
+export { CHIP_STACK_VARIANTS, DEFAULT_CHIP_STACK_VARIANT } from './type';
+export type { ChipStackProps, ChipStackFaceItem, ChipStackVariant, ChipStackSlotProps, ChipStackItemRenderContext, ChipStackOverflowRenderArgs, } from './type';

package/build/components/_v2/primitives/ChipStack/style.d.ts

@@ -0,0 +1,31 @@
+import { type BoxProps } from '@mui/material/Box';
+import type { Theme } from '@mui/material/styles';
+import type { ReactNode } from 'react';
+import type { ChipStackOverflowRenderArgs } from './type';
+export declare const AnimatedStackShell: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<Theme>> & import("@mui/system").MUIStyledCommonProps<Theme>, {}, {}>;
+export declare const AnimatedStackTrack: import("@emotion/styled").StyledComponent<import("@mui/system").MUIStyledCommonProps<Theme> & {
+    trackWidth: number;
+    minTrackWidth: number;
+    slotSize: number;
+    hoverZIndex?: number | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const OverlapChipRow: import("@emotion/styled").StyledComponent<import("@mui/system").BoxOwnProps<Theme> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, keyof import("@mui/system").BoxOwnProps<Theme>> & import("@mui/system").MUIStyledCommonProps<Theme>, {}, {}>;
+export declare const StyledOverlapChip: import("@emotion/styled").StyledComponent<Omit<BoxProps, "title"> & {
+    title?: ReactNode;
+} & import("@mui/system").MUIStyledCommonProps<Theme>, {}, {}>;
+/** Default styled `+N` chip for the **static** variant overflow slot. */
+export declare const ChipStackStaticOverflowChip: import("@emotion/styled").StyledComponent<Omit<BoxProps, "title"> & {
+    title?: ReactNode;
+} & import("@mui/system").MUIStyledCommonProps<Theme>, {}, {}>;
+/** Default overflow renderer used when `renderOverflow` is not provided. */
+export declare function ChipStackOverflowDefault({ overflowItems, size }: Readonly<ChipStackOverflowRenderArgs>): import("react").JSX.Element;
+export declare const ChipStackFace: import("@emotion/styled").StyledComponent<import("@mui/material/Avatar").AvatarOwnProps & import("@mui/material/Avatar").AvatarSlotsAndSlotProps & import("@mui/material/OverridableComponent").CommonProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    ref?: ((instance: HTMLDivElement | null) => void) | import("react").RefObject<HTMLDivElement> | null | undefined;
+}, "classes" | "className" | "style" | "children" | "sx" | "variant" | "slotProps" | "slots" | "sizes" | "src" | "alt" | "srcSet" | "imgProps"> & import("@mui/system").MUIStyledCommonProps<Theme> & {
+    faceSize: number;
+    avatarFill: string;
+}, {}, {}>;

package/build/components/_v2/primitives/ChipStack/type.d.ts

@@ -0,0 +1,132 @@
+import type { BoxProps } from '@mui/material/Box';
+import type { HTMLAttributes, ReactNode } from 'react';
+/**
+ * Controls both the render mode and (for fanout variants) the fan-out direction.
+ *
+ * - `"static"` — overlapping row, no hover animation **(default)**
+ * - `"fanout-right"` — fans right on hover (anchor: leftmost chip)
+ * - `"fanout-left"` — fans left on hover (anchor: rightmost chip)
+ * - `"fanout-center"` — fans both ways on hover (anchor: middle chip)
+ */
+export type ChipStackVariant = 'static' | 'fanout-right' | 'fanout-left' | 'fanout-center';
+/** All variant values — useful for building selects/controls. */
+export declare const CHIP_STACK_VARIANTS: readonly ["static", "fanout-right", "fanout-left", "fanout-center"];
+/** Default variant when `variant` is omitted. */
+export declare const DEFAULT_CHIP_STACK_VARIANT: ChipStackVariant;
+/** Resolved internally from `variant` — not exposed as a prop. */
+export type ChipStackFanOutDirection = 'right' | 'left' | 'center';
+/** Passed to `renderItem` so the callback knows how large to render each chip. */
+export type ChipStackItemRenderContext = {
+    slotSize: number;
+};
+/**
+ * Passed to `renderOverflow` when items exceed `maxItems`.
+ *
+ * @template T — matches the `items` array type on `ChipStackProps<T>`.
+ *               `ReactNode` for compositional (children) usage.
+ */
+export type ChipStackOverflowRenderArgs<T = unknown> = {
+    /** The full `items` array passed to `ChipStack`. */
+    items: readonly T[];
+    /** The hidden items that overflowed past `maxItems`. */
+    overflowItems: readonly T[];
+    /** Chip diameter in px — size your overflow chip to this value. */
+    size: number;
+};
+export type ChipStackFaceItem = {
+    /** Optional stable key — defaults to `first-last-index`. */
+    id?: string;
+    first: string;
+    last: string;
+    /** Omitted or broken → initials on gradient. */
+    logo?: string;
+    /** Custom tooltip content — defaults to `"First Last"`. Pass `null` to disable. */
+    tooltip?: ReactNode | null;
+};
+/**
+ * Fine-grained style/prop overrides for internal slots.
+ */
+export type ChipStackSlotProps = {
+    /** Outer flex shell wrapping the chip track (`Box`). */
+    shell?: BoxProps;
+    /** Positioned `<div>` holding all chip slots — use for `aria-label` and other HTML attributes. */
+    track?: HTMLAttributes<HTMLDivElement>;
+    /**
+     * Layout dimensions for the animated track.
+     * Pass here instead of as top-level props to keep the component surface clean.
+     */
+    layout?: {
+        /** Z-index of the track while hovered. @default 1000 */
+        zIndex?: number;
+        /** Chip diameter in px. @default 24 */
+        size?: number;
+        /** Horizontal distance between stacked chips in px. */
+        stackStep?: number;
+        /** Space between chips when fully expanded in px. */
+        gap?: number;
+        /** Minimum width of the chip track container in px. */
+        minTrackWidth?: number;
+    };
+};
+/**
+ * Props for `ChipStack`.
+ *
+ * Two input styles:
+ * - **Data-driven** — `items` + `getItemKey` + `renderItem`
+ * - **Compositional** — `children` (wrap in `OverlapChip` for static, or pass raw nodes)
+ *
+ * When both are provided, `children` takes precedence and `items` is ignored.
+ */
+export type ChipStackProps<T = unknown> = {
+    /**
+     * Controls render mode and fan-out direction.
+     *
+     * - `"static"` — overlapping row, no animation **(default)**
+     * - `"fanout-right"` — fans right on hover
+     * - `"fanout-left"` — fans left on hover
+     * - `"fanout-center"` — fans both ways on hover
+     */
+    variant?: ChipStackVariant;
+    /** Data array. Requires `getItemKey` and `renderItem`. */
+    items?: readonly T[];
+    /** Returns a stable string key for each data item (required when using `items`) */
+    getItemKey?: (item: T, index: number) => string;
+    /** Renders a chip for each data item; receives the item, its index, and the slot size context */
+    renderItem?: (item: T, index: number, ctx: ChipStackItemRenderContext) => ReactNode;
+    /** Rendered as-is. Wrap in `OverlapChip` for static variants. */
+    children?: ReactNode;
+    /** Cap visible chips; collapse the rest into a `+N` indicator. */
+    maxItems?: number;
+    /**
+     * **Fanout variants only.** When `true`, only the anchor chip is visible while idle.
+     * Hovering reveals all chips with the fan-out animation defined by `variant`.
+     *
+     * Pairs with any `fanout-*` variant:
+     * ```tsx
+     * <ChipStack variant="fanout-right" compact items={apps} ... />
+     * ```
+     *
+     * @default false
+     */
+    compact?: boolean;
+    /**
+     * Fully replace the `+N` overflow slot.
+     * Receives `{ items, overflowItems, size }` where `items` is the full data array
+     * and `overflowItems` is the hidden slice.
+     *
+     * ```tsx
+     * renderOverflow={({ items, overflowItems, size }) => (
+     *   <MyPopover trigger={`+${overflowItems.length}`} chipSize={size} data={items} />
+     * )}
+     * ```
+     */
+    renderOverflow?: (args: ChipStackOverflowRenderArgs<T>) => ReactNode;
+    /** MUI sx style overrides for the outer wrapper */
+    sx?: BoxProps['sx'];
+    /** Additional CSS class name applied to the outer wrapper */
+    className?: string;
+    /** Style/prop overrides for internal slots and layout dimensions. */
+    slotProps?: ChipStackSlotProps;
+    /** Test ID forwarded to the inner track element */
+    'data-testid'?: string;
+};

package/build/components/_v2/primitives/ChipStack/util.d.ts

@@ -0,0 +1,74 @@
+import type { MutableRefObject, ReactNode } from 'react';
+import type { ChipStackFaceItem, ChipStackFanOutDirection, ChipStackOverflowRenderArgs, ChipStackVariant } from './type';
+type ChipStackAnimatedLayout = {
+    size: number;
+    stackStep: number;
+    gap: number;
+    minTrackWidth: number;
+};
+type ChipStackAnimatedLayoutOverrides = Partial<ChipStackAnimatedLayout>;
+export type ChipStackSlotModel = {
+    key: string;
+    render: () => ReactNode;
+};
+/** Three exclusive render paths resolved from props. */
+export declare enum ChipStackRenderMode {
+    StaticChildren = "static-children",
+    StaticItems = "static-items",
+    AnimatedChildren = "animated-children",
+    AnimatedItems = "animated-items"
+}
+/** Returns true when the variant is any of the animated variants. */
+export declare function isAnimatedVariant(variant: ChipStackVariant): boolean;
+/**
+ * Extracts the fan-out direction from the variant string.
+ * Only meaningful for fanout variants.
+ */
+export declare function getFanOutDirection(variant: ChipStackVariant): ChipStackFanOutDirection;
+/**
+ * Resolves which render path `ChipStack` should take.
+ * Returns `null` when there is nothing to render.
+ */
+export declare function resolveChipStackMode(variant: ChipStackVariant, hasChildren: boolean, hasItems: boolean): ChipStackRenderMode | null;
+export declare function getChipStackAnimatedLayout({ size: sizeProp, stackStep: stackStepProp, gap: gapProp, minTrackWidth: minTrackWidthProp, }: ChipStackAnimatedLayoutOverrides): ChipStackAnimatedLayout;
+export declare function getFanOutAnchorIndex(slotCount: number, direction: ChipStackFanOutDirection): number;
+/** True when `maxItems` forces overflow handling. */
+export declare function isChipStackAnimatedCapped(sourceCount: number, maxItems: number | undefined): boolean;
+/**
+ * Splits `items` into visible and hidden slices based on `maxItems`.
+ *
+ * Overflow triggers when `items.length >= maxItems` and `maxItems >= 1`.
+ * The first `maxItems - 1` items are visible; the rest are hidden.
+ * When `maxItems` is undefined or `< 1`, all items are visible and hidden is empty.
+ */
+export declare function splitChipStackOverflow<T>(items: readonly T[], maxItems: number | undefined): {
+    visibleItems: readonly T[];
+    hiddenItems: readonly T[];
+};
+export declare function getReactChildKey(child: unknown, index: number): string;
+export declare function buildChipStackSlots<T>({ items, maxItems, getItemKey, renderItem, renderOverflow, slotSize, }: {
+    items: readonly T[];
+    maxItems: number | undefined;
+    getItemKey: (item: T, sourceIndex: number) => string;
+    renderItem: (item: T, sourceIndex: number, ctx: {
+        slotSize: number;
+    }) => ReactNode;
+    renderOverflow: (args: ChipStackOverflowRenderArgs<T>) => ReactNode;
+    slotSize: number;
+}): ChipStackSlotModel[];
+export declare function buildChipStackSlotsFromChildren({ children, maxItems, slotSize, renderOverflow, }: {
+    children: ReactNode;
+    maxItems: number | undefined;
+    slotSize: number;
+    renderOverflow: (args: ChipStackOverflowRenderArgs<ReactNode>) => ReactNode;
+}): ChipStackSlotModel[];
+export declare function areSlotWidthArraysEqual(a: number[], b: number[]): boolean;
+export declare function computeFannedOutLeftPositionsPx(slotCount: number, anchorIndex: number, slotWidthsPx: number[], gap: number, stackStep: number, fallbackSlotWidthPx: number): number[];
+export declare function computeCollapsedStackWidthPx(slotCount: number, stackStep: number, faceSize: number): number;
+export declare function computeFanOutTranslateXPx(slotCount: number, isHovering: boolean, fannedLeftPositionsPx: number[], stackStep: number): number[];
+export declare function computeFannedRowWidthPx(slotCount: number, fannedLeftPositionsPx: number[], slotWidthsPx: number[], collapsedWidthPx: number, fallbackSlotWidthPx: number): number;
+export declare function readMeasuredSlotWidthsPx(slotCount: number, slotRefs: MutableRefObject<Array<HTMLDivElement | null>>, fallbackSlotWidthPx: number): number[];
+export declare function getChipStackFaceItemKey(item: ChipStackFaceItem, index: number): string;
+export declare function getChipStackFaceInitials(item: ChipStackFaceItem): string;
+export declare function getChipStackFaceItemTooltipContent(item: ChipStackFaceItem): ReactNode | null;
+export {};