@photonix/basic 2.3.0 → 3.0.0

package/dist/index.d.mts

@@ -1,2 +1,1109 @@
-export { AVATAR_IMAGES, AspectRatio, Avatar, AvatarGroup, AvatarGroupProps, AvatarProps, AvatarSize, AvatarTemplate, AvatarTemplateProps, BackgroundToken, Badge, Box, Button, ButtonProps, Center, Checkbox, Chip, ChipBar, ChipProps, Cluster, Container, CustomScrollbar, Divider, Flex, Grid, GridItem, HStack, Heading, IconButton, Image, LayoutContext, LayoutProvider, Portal, Radio, RadioProps, RadiusToken, ShadowToken, SimpleGrid, Skeleton, SlotPlaceholder, SlotPlaceholderProps, Spacer, SpacingToken, Spinner, Stack, Switch, SwitchProps, Text, TextArea, TextAreaProps, TextField, TextFieldDropdownOption, TextFieldProps, VStack, VisuallyHidden, useLayout } from '@photonix/ultimate';
+import * as React from 'react';
+import React__default from 'react';
 export * from '@photonix/icons';
+
+/**
+ * Layout component type definitions
+ * Provides TypeScript types for design token props used in Box, Stack, Grid, etc.
+ */
+/** Public spacing token names mapped to canonical --space-* CSS variables */
+type SpacingToken = 'none' | '5xs' | '4xs' | '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl' | '8xl';
+/** Public background token names mapped to canonical surface CSS variables */
+type BackgroundToken = ('primary' | 'primary-inverse' | 'secondary' | 'secondary-inverse' | 'tertiary' | 'tertiary-inverse' | 'elevator' | 'neutral-primary' | 'neutral-primary-inverse' | 'neutral-secondary' | 'neutral-secondary-inverse' | 'neutral-tertiary' | 'neutral-tertiary-inverse' | 'neutral-elevator' | 'brand-primary' | 'red' | 'orange' | 'yellow' | 'green' | 'mint' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink' | 'brown') | (string & {});
+/** Page background token names mapped to canonical background CSS variables */
+type PageBackgroundToken = 'primary' | 'primary-inverse' | 'secondary' | 'secondary-inverse' | 'tertiary' | 'tertiary-inverse';
+/** Public radius token names mapped to canonical --radius-* CSS variables */
+type RadiusToken = 'none' | '4xs' | '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | 'full';
+/** Shadow size names matching shadow CSS variables */
+type ShadowToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+type DisplayValue = 'block' | 'flex' | 'grid' | 'inline' | 'inline-block' | 'inline-flex' | 'inline-grid' | 'none';
+type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
+type FlexWrap = 'wrap' | 'nowrap' | 'wrap-reverse';
+type AlignItems = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+type JustifyContent = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+type AlignSelf = 'auto' | 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+type AlignContent = 'start' | 'center' | 'end' | 'between' | 'around' | 'stretch';
+type TextAlign$1 = 'left' | 'center' | 'right' | 'justify';
+type Position = 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
+type Overflow = 'visible' | 'hidden' | 'scroll' | 'auto';
+/** Public border width token names mapped to canonical --border-* CSS variables */
+type BorderWidthToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | (string & {});
+type Breakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+type ResponsiveValue<T> = T | Partial<Record<Breakpoint, T>>;
+
+type AsProp<C extends React.ElementType> = {
+    as?: C;
+};
+type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P);
+type PolymorphicComponentProp<C extends React.ElementType, Props = object> = React.PropsWithChildren<Props & AsProp<C>> & Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>;
+type PolymorphicRef<C extends React.ElementType> = React.ComponentPropsWithRef<C>['ref'];
+type PolymorphicComponentPropWithRef<C extends React.ElementType, Props = object> = PolymorphicComponentProp<C, Props> & {
+    ref?: PolymorphicRef<C>;
+};
+
+interface BoxOwnProps {
+    /** Padding on all sides */
+    p?: ResponsiveValue<SpacingToken>;
+    /** Padding inline (left/right) */
+    px?: ResponsiveValue<SpacingToken>;
+    /** Padding block (top/bottom) */
+    py?: ResponsiveValue<SpacingToken>;
+    /** Padding block start (top) */
+    pt?: ResponsiveValue<SpacingToken>;
+    /** Padding block end (bottom) */
+    pb?: ResponsiveValue<SpacingToken>;
+    /** Padding inline start (left) */
+    pl?: ResponsiveValue<SpacingToken>;
+    /** Padding inline end (right) */
+    pr?: ResponsiveValue<SpacingToken>;
+    /** Margin on all sides */
+    m?: ResponsiveValue<SpacingToken | 'auto'>;
+    /** Margin inline (left/right) */
+    mx?: ResponsiveValue<SpacingToken | 'auto'>;
+    /** Margin block (top/bottom) */
+    my?: ResponsiveValue<SpacingToken | 'auto'>;
+    /** Margin block start (top) */
+    mt?: ResponsiveValue<SpacingToken | 'auto'>;
+    /** Margin block end (bottom) */
+    mb?: ResponsiveValue<SpacingToken | 'auto'>;
+    /** Margin inline start (left) */
+    ml?: ResponsiveValue<SpacingToken | 'auto'>;
+    /** Margin inline end (right) */
+    mr?: ResponsiveValue<SpacingToken | 'auto'>;
+    /** CSS display property */
+    display?: ResponsiveValue<DisplayValue>;
+    /** Aspect Ratio */
+    aspectRatio?: ResponsiveValue<string | number>;
+    /** Flex direction */
+    flexDirection?: ResponsiveValue<FlexDirection>;
+    /** Flex wrap behavior */
+    flexWrap?: ResponsiveValue<FlexWrap | boolean>;
+    /** Shorthand for flex-grow, flex-shrink, flex-basis */
+    flex?: ResponsiveValue<string | number>;
+    /** Flex grow factor */
+    flexGrow?: ResponsiveValue<number>;
+    /** Flex shrink factor */
+    flexShrink?: ResponsiveValue<number>;
+    /** Flex basis */
+    flexBasis?: ResponsiveValue<string | number>;
+    /** Order */
+    order?: ResponsiveValue<number>;
+    /** Gap between items */
+    gap?: ResponsiveValue<SpacingToken>;
+    /** Column gap */
+    columnGap?: ResponsiveValue<SpacingToken>;
+    /** Row gap */
+    rowGap?: ResponsiveValue<SpacingToken>;
+    /** Align items (cross axis) */
+    alignItems?: ResponsiveValue<AlignItems>;
+    /** Align content (multiline) */
+    alignContent?: ResponsiveValue<string>;
+    /** Align self */
+    alignSelf?: ResponsiveValue<AlignSelf>;
+    /** Justify content (main axis) */
+    justifyContent?: ResponsiveValue<JustifyContent>;
+    /** Justify items (grid) */
+    justifyItems?: ResponsiveValue<string>;
+    /** Place items (align-items + justify-items) */
+    placeItems?: ResponsiveValue<string>;
+    /** Place content (align-content + justify-content) */
+    placeContent?: ResponsiveValue<string>;
+    /** Background color using public background tokens mapped to canonical surface vars */
+    bg?: ResponsiveValue<BackgroundToken>;
+    /** Page background using canonical background-* vars for page/root containers */
+    pageBg?: ResponsiveValue<PageBackgroundToken>;
+    /** Border radius using border-radius-* tokens */
+    borderRadius?: ResponsiveValue<RadiusToken>;
+    /** Box shadow using shadow-* tokens */
+    shadow?: ResponsiveValue<ShadowToken>;
+    /** Opacity */
+    opacity?: ResponsiveValue<number>;
+    border?: ResponsiveValue<string>;
+    borderWidth?: ResponsiveValue<BorderWidthToken | number>;
+    borderStyle?: ResponsiveValue<string>;
+    borderColor?: ResponsiveValue<string>;
+    textAlign?: ResponsiveValue<TextAlign$1>;
+    fontSize?: ResponsiveValue<string | number>;
+    fontWeight?: ResponsiveValue<string | number>;
+    lineHeight?: ResponsiveValue<string | number>;
+    color?: ResponsiveValue<string>;
+    /** Width - accepts CSS value */
+    w?: ResponsiveValue<string | number>;
+    /** Height - accepts CSS value */
+    h?: ResponsiveValue<string | number>;
+    /** Min width - accepts CSS value */
+    minW?: ResponsiveValue<string | number>;
+    /** Min height - accepts CSS value */
+    minH?: ResponsiveValue<string | number>;
+    /** Max width - accepts CSS value */
+    maxW?: ResponsiveValue<string | number>;
+    /** Max height - accepts CSS value */
+    maxH?: ResponsiveValue<string | number>;
+    /** CSS position property */
+    position?: ResponsiveValue<Position>;
+    /** Top position */
+    top?: ResponsiveValue<string | number>;
+    /** Right position */
+    right?: ResponsiveValue<string | number>;
+    /** Bottom position */
+    bottom?: ResponsiveValue<string | number>;
+    /** Left position */
+    left?: ResponsiveValue<string | number>;
+    /** Inset shortcut */
+    inset?: ResponsiveValue<string | number>;
+    /** Z-index */
+    zIndex?: ResponsiveValue<number>;
+    /** CSS overflow property */
+    overflow?: ResponsiveValue<Overflow>;
+    /** CSS overflow-x property */
+    overflowX?: ResponsiveValue<Overflow>;
+    /** CSS overflow-y property */
+    overflowY?: ResponsiveValue<Overflow>;
+    cursor?: ResponsiveValue<string>;
+    pointerEvents?: ResponsiveValue<string>;
+    userSelect?: ResponsiveValue<string>;
+    transform?: ResponsiveValue<string>;
+    transition?: ResponsiveValue<string>;
+}
+type BoxProps<C extends React.ElementType = 'div'> = PolymorphicComponentPropWithRef<C, BoxOwnProps>;
+type BoxComponent = <C extends React.ElementType = 'div'>(props: BoxProps<C>) => React.ReactElement | null;
+declare const Box: BoxComponent;
+
+interface FlexOwnProps extends BoxOwnProps {
+    /** Flex direction */
+    direction?: ResponsiveValue<FlexDirection>;
+    /** Gap between children using spacing tokens */
+    gap?: ResponsiveValue<SpacingToken>;
+    /** Column Gap */
+    columnGap?: ResponsiveValue<SpacingToken>;
+    /** Row Gap */
+    rowGap?: ResponsiveValue<SpacingToken>;
+    /** Align items along the cross axis */
+    align?: ResponsiveValue<AlignItems>;
+    /** Justify content along the main axis */
+    justify?: ResponsiveValue<JustifyContent>;
+    /** Flex wrap behavior */
+    wrap?: ResponsiveValue<FlexWrap | boolean>;
+    /** Flex basis */
+    basis?: ResponsiveValue<string | number>;
+    /** Flex grow */
+    grow?: ResponsiveValue<number>;
+    /** Flex shrink */
+    shrink?: ResponsiveValue<number>;
+    /** Align Content */
+    alignContent?: ResponsiveValue<AlignContent>;
+    /** Align Self */
+    alignSelf?: ResponsiveValue<AlignSelf>;
+    /** Order */
+    order?: ResponsiveValue<number>;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+type FlexProps<C extends React.ElementType = 'div'> = PolymorphicComponentPropWithRef<C, FlexOwnProps>;
+type FlexComponent = <C extends React.ElementType = 'div'>(props: FlexProps<C>) => React.ReactElement | null;
+declare const Flex: FlexComponent;
+type SpacerProps = React.HTMLAttributes<HTMLDivElement>;
+/**
+ * Spacer pushes siblings apart by taking all available space.
+ * Use inside Flex or HStack/VStack to create space between elements.
+ */
+declare const Spacer: React.ForwardRefExoticComponent<SpacerProps & React.RefAttributes<HTMLDivElement>>;
+type CenterProps = Omit<FlexProps, 'align' | 'justify'>;
+/**
+ * Center aligns children both horizontally and vertically.
+ */
+declare const Center: React.ForwardRefExoticComponent<Omit<CenterProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+interface GridProps extends BoxOwnProps, Omit<React.HTMLAttributes<HTMLDivElement>, keyof BoxOwnProps> {
+    /** Number of columns or responsive column config */
+    columns?: ResponsiveValue<number>;
+    /** Gap between grid items */
+    gap?: ResponsiveValue<SpacingToken>;
+    /** Row gap (overrides gap for rows) */
+    rowGap?: ResponsiveValue<SpacingToken>;
+    /** Column gap (overrides gap for columns) */
+    columnGap?: ResponsiveValue<SpacingToken>;
+    /** Template columns (CSS grid-template-columns value) */
+    templateColumns?: ResponsiveValue<string>;
+    /** Template rows (CSS grid-template-rows value) */
+    templateRows?: ResponsiveValue<string>;
+    /** Template areas (CSS grid-template-areas value) */
+    templateAreas?: ResponsiveValue<string>;
+    /** Auto rows sizing */
+    autoRows?: ResponsiveValue<string>;
+    /** Auto columns sizing */
+    autoColumns?: ResponsiveValue<string>;
+    /** Auto flow direction */
+    autoFlow?: ResponsiveValue<'row' | 'column' | 'dense' | 'row dense' | 'column dense'>;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+declare const Grid: React.ForwardRefExoticComponent<GridProps & React.RefAttributes<HTMLDivElement>>;
+interface GridItemProps extends BoxOwnProps, Omit<React.HTMLAttributes<HTMLDivElement>, keyof BoxOwnProps> {
+    /** Number of columns to span */
+    colSpan?: ResponsiveValue<number | 'full'>;
+    /** Number of rows to span */
+    rowSpan?: ResponsiveValue<number>;
+    /** Column start position */
+    colStart?: ResponsiveValue<number>;
+    /** Column end position */
+    colEnd?: ResponsiveValue<number>;
+    /** Row start position */
+    rowStart?: ResponsiveValue<number>;
+    /** Row end position */
+    rowEnd?: ResponsiveValue<number>;
+    /** Grid area name */
+    area?: ResponsiveValue<string>;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+declare const GridItem: React.ForwardRefExoticComponent<GridItemProps & React.RefAttributes<HTMLDivElement>>;
+interface SimpleGridProps extends Omit<GridProps, 'columns'> {
+    /** Number of columns (simpler API) */
+    columns?: ResponsiveValue<number>;
+    /** Minimum child width for auto-fit */
+    minChildWidth?: ResponsiveValue<string | number>;
+}
+declare const SimpleGrid: React.ForwardRefExoticComponent<SimpleGridProps & React.RefAttributes<HTMLDivElement>>;
+
+interface StackOwnProps extends BoxOwnProps {
+    /** Flex direction */
+    direction?: ResponsiveValue<FlexDirection>;
+    /** Gap between children using spacing tokens */
+    gap?: ResponsiveValue<SpacingToken>;
+    /** Spacing alias for gap */
+    spacing?: ResponsiveValue<SpacingToken>;
+    /** Align items along the cross axis */
+    align?: ResponsiveValue<AlignItems>;
+    /** Justify content along the main axis */
+    justify?: ResponsiveValue<JustifyContent>;
+    /** Whether to wrap children */
+    wrap?: ResponsiveValue<boolean>;
+    /** Optional divider element between items */
+    divider?: React.ReactNode;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+type StackProps<C extends React.ElementType = 'div'> = PolymorphicComponentPropWithRef<C, StackOwnProps>;
+type StackComponent = <C extends React.ElementType = 'div'>(props: StackProps<C>) => React.ReactElement | null;
+declare const Stack: StackComponent;
+type VStackProps<C extends React.ElementType = 'div'> = Omit<StackProps<C>, 'direction'>;
+type VStackComponent = <C extends React.ElementType = 'div'>(props: VStackProps<C>) => React.ReactElement | null;
+declare const VStack: VStackComponent;
+type HStackProps<C extends React.ElementType = 'div'> = Omit<StackProps<C>, 'direction'>;
+type HStackComponent = <C extends React.ElementType = 'div'>(props: HStackProps<C>) => React.ReactElement | null;
+declare const HStack: HStackComponent;
+
+declare const containerWidths: {
+    readonly sm: "640px";
+    readonly md: "768px";
+    readonly lg: "1024px";
+    readonly xl: "1280px";
+    readonly '2xl': "1536px";
+    readonly full: "100%";
+};
+type ContainerWidth = keyof typeof containerWidths;
+interface ContainerProps extends BoxOwnProps, Omit<React.HTMLAttributes<HTMLDivElement>, keyof BoxOwnProps> {
+    /** Maximum width of the container */
+    maxWidth?: ResponsiveValue<ContainerWidth | string | number>;
+    /** Alias for maxWidth */
+    size?: ResponsiveValue<ContainerWidth | string | number>;
+    /** Whether to take up 100% width (alias for maxWidth="full") */
+    fluid?: boolean;
+    /** Whether to center the content */
+    centerContent?: boolean;
+    /** Padding alias (px usually) */
+    padding?: ResponsiveValue<SpacingToken>;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+declare const Container: React.ForwardRefExoticComponent<ContainerProps & React.RefAttributes<HTMLDivElement>>;
+
+interface AspectRatioOwnProps extends BoxOwnProps {
+    /** Aspect ratio (width / height), e.g., 16/9 */
+    ratio?: number;
+}
+type AspectRatioProps<C extends React.ElementType = 'div'> = PolymorphicComponentPropWithRef<C, AspectRatioOwnProps>;
+declare const AspectRatio$1: React.ForwardRefExoticComponent<Omit<AspectRatioProps<React.ElementType<any, keyof React.JSX.IntrinsicElements>>, "ref"> & React.RefAttributes<any>>;
+
+interface CustomScrollbarProps {
+    children: React__default.ReactNode;
+    /** Scrollbar thumb size: sm = 4px, md = 8px */
+    size?: 'sm' | 'md';
+    /** Maximum height of the container (enables vertical scroll) */
+    maxHeight?: string | number;
+    /** Maximum width of the container (enables horizontal scroll) */
+    maxWidth?: string | number;
+    /**
+     * Fill available space in flex parent container.
+     * Use this instead of maxHeight="100%" when inside a flex layout.
+     * When true, the component will use flex: 1 to fill remaining space.
+     */
+    fill?: boolean;
+    /** Additional className for the container */
+    className?: string;
+    /** Additional className for the content area */
+    contentClassName?: string;
+    /** Additional className for the vertical track */
+    verticalTrackClassName?: string;
+    /** Inline style for the vertical track */
+    verticalTrackStyle?: React__default.CSSProperties;
+    /** Additional className for the horizontal track */
+    horizontalTrackClassName?: string;
+    /** Inline style for the horizontal track */
+    horizontalTrackStyle?: React__default.CSSProperties;
+    /** Whether to show scrollbar only on hover */
+    autoHide?: boolean;
+    /** Callback fired on scroll */
+    onScroll?: (event: React__default.UIEvent<HTMLDivElement>) => void;
+}
+interface CustomScrollbarRef {
+    /** The scrollable content element */
+    contentElement: HTMLDivElement | null;
+    /** Scroll to a specific position */
+    scrollTo: (options: ScrollToOptions) => void;
+}
+declare const CustomScrollbar: React__default.ForwardRefExoticComponent<CustomScrollbarProps & React__default.RefAttributes<CustomScrollbarRef>>;
+
+interface PortalProps {
+    /**
+     * The container to mount the portal into.
+     * Defaults to document.body
+     */
+    container?: HTMLElement | null;
+    /**
+     * Children to render in the portal
+     */
+    children: React.ReactNode;
+    /**
+     * Optional key for the portal
+     */
+    key?: string | null;
+}
+declare const Portal: {
+    ({ container, children, key }: PortalProps): React.ReactElement | null;
+    displayName: string;
+};
+
+interface SlotPlaceholderProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Title text */
+    title?: string;
+    /** Description text */
+    description?: string;
+    /** Custom icon */
+    icon?: React.ReactNode;
+    /** Minimum height */
+    minHeight?: string | number;
+}
+declare const SlotPlaceholder: React.ForwardRefExoticComponent<SlotPlaceholderProps & React.RefAttributes<HTMLDivElement>>;
+
+interface ClusterOwnProps extends Omit<FlexOwnProps, 'wrap'> {
+    /** Whether children should wrap (default: true) */
+    wrap?: boolean;
+}
+type ClusterProps<C extends React.ElementType = 'div'> = PolymorphicComponentPropWithRef<C, ClusterOwnProps>;
+/**
+ * Cluster layout component for inline elements with automatic wrapping and gap.
+ * Useful for tags, buttons, or any group of items that should wrap.
+ */
+declare const Cluster: React.ForwardRefExoticComponent<Omit<ClusterProps<React.ElementType<any, keyof React.JSX.IntrinsicElements>>, "ref"> & React.RefAttributes<any>>;
+
+type TextVariant = 'display-lg' | 'display-md' | 'display-sm' | 'headline-lg' | 'headline-md' | 'headline-sm' | 'title-lg' | 'title-md' | 'title-sm' | 'body-2xl' | 'body-xl' | 'body-lg' | 'body-md' | 'body-sm' | 'label-lg' | 'label-md' | 'label-sm' | 'code-xl' | 'code-lg' | 'code-md' | 'code-sm';
+type TextColor = 'primary' | 'primary-inverse' | 'secondary' | 'secondary-inverse' | 'brand' | 'red' | 'orange' | 'yellow' | 'green' | 'mint' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink' | 'brown';
+type TextWeight = 'regular' | 'medium' | 'bold';
+type TextAlign = 'left' | 'center' | 'right' | 'justify';
+interface TextProps extends Omit<React.AllHTMLAttributes<HTMLElement>, 'color'> {
+    /** Typography variant from typescale tokens */
+    variant?: ResponsiveValue<TextVariant>;
+    /** Text color from text-* tokens */
+    color?: TextColor;
+    /** Font weight override */
+    weight?: TextWeight;
+    /** Text alignment */
+    align?: ResponsiveValue<TextAlign>;
+    /** Truncate text with ellipsis (true = single line, number = line clamp) */
+    truncate?: boolean | number;
+    /** Render as different HTML element */
+    as?: 'p' | 'span' | 'div' | 'label' | 'strong' | 'em' | 'small' | 'code' | 'pre' | 'a';
+    /** Text decoration */
+    decoration?: 'none' | 'underline';
+    /** Children */
+    children?: React.ReactNode;
+}
+declare const Text: React.ForwardRefExoticComponent<TextProps & React.RefAttributes<HTMLElement>>;
+
+type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+type HeadingSize = 'display-lg' | 'display-md' | 'display-sm' | 'headline-lg' | 'headline-md' | 'headline-sm' | 'title-lg' | 'title-md' | 'title-sm';
+interface HeadingProps extends Omit<React.HTMLAttributes<HTMLHeadingElement>, 'color'> {
+    /** Semantic heading level (h1-h6) */
+    as?: HeadingLevel;
+    /** Visual size (can differ from semantic level for styling) */
+    size?: HeadingSize;
+    /** Text color */
+    color?: 'primary' | 'secondary' | 'brand' | 'primary-inverse';
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right';
+    /** Truncate with ellipsis */
+    truncate?: boolean;
+    /** Children */
+    children?: React.ReactNode;
+}
+declare const Heading: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLHeadingElement>>;
+
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Visual variant of the button
+     * - primary: Dark solid background (main action)
+     * - secondary: Border only, transparent background
+     * - tertiary: No border, no background (subtle action)
+     * - brand: Blue brand color background
+     */
+    variant?: 'primary' | 'secondary' | 'tertiary' | 'brand';
+    /**
+     * Size of the button
+     * - large: 48px height
+     * - medium: 44px height, default
+     * - small: 36px height, compact
+     */
+    size?: 'large' | 'medium' | 'small';
+    /**
+     * Icon displayed before the button text
+     */
+    leadingIcon?: React.ReactNode;
+    /**
+     * Icon displayed after the button text
+     */
+    trailingIcon?: React.ReactNode;
+    /**
+     * Badge count to display after the text (for filters, selects, etc.)
+     * Displays as a small text badge next to the button label
+     */
+    badge?: number | string;
+    /**
+     * Shows loading spinner and disables interaction
+     */
+    isLoading?: boolean;
+    /**
+     * Makes button take full width of container
+     */
+    isFullWidth?: boolean;
+    /**
+     * When true, renders children directly instead of button element
+     * Useful for rendering as Link or other components
+     */
+    asChild?: boolean;
+    /**
+     * Border radius shape
+     * - rounded: Default rounded corners
+     * - pill: Fully rounded (pill shape)
+     */
+    shape?: 'rounded' | 'pill';
+}
+/**
+ * Button Component
+ *
+ * A flexible button component with multiple variants, sizes, and icon support.
+ * Structure: leading icon + Group (Text + badge) + trailing icon
+ */
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Visual variant of the button
+     * - primary: Dark solid background (main action)
+     * - secondary: Border only, transparent background
+     * - tertiary: No border, no background (subtle action)
+     * - brand: Blue brand color background
+     */
+    variant?: 'primary' | 'secondary' | 'tertiary' | 'brand';
+    /**
+     * Size of the button (square)
+     * - large: 48×48px
+     * - medium: 44×44px, default
+     * - small: 36×36px
+     */
+    size?: 'large' | 'medium' | 'small';
+    /**
+     * Border radius shape
+     * - rounded: Default rounded corners
+     * - pill: Fully rounded (circle)
+     */
+    shape?: 'rounded' | 'pill';
+    /**
+     * The icon to display
+     */
+    icon: React.ReactNode;
+    /**
+     * Badge count to display at top-right corner.
+     * - Pass a number or string for a numeric/text badge.
+     * - Pass `true` for a simple dot badge.
+     */
+    badge?: number | string | boolean;
+    /**
+     * Shows loading spinner and disables interaction
+     */
+    isLoading?: boolean;
+    /**
+     * Accessible label for the button (required for icon-only buttons)
+     */
+    'aria-label': string;
+    /**
+     * When true, renders children directly instead of button element
+     */
+    asChild?: boolean;
+}
+/**
+ * IconButton Component
+ *
+ * A square button component that displays only an icon.
+ * Shares styling with Button but optimized for icon-only use.
+ */
+declare const IconButton: React.ForwardRefExoticComponent<IconButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+interface CheckboxProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
+    /**
+     * Whether the checkbox is checked (controlled)
+     */
+    checked?: boolean;
+    /**
+     * Initial checked state when uncontrolled
+     */
+    defaultChecked?: boolean;
+    /**
+     * Whether the checkbox is in indeterminate state (for selectAll partial)
+     */
+    indeterminate?: boolean;
+    /**
+     * Size of the checkbox
+     */
+    size?: 'small' | 'medium';
+    /**
+     * Label text for the checkbox
+     */
+    label?: React.ReactNode;
+    /**
+     * Callback when checkbox state changes
+     */
+    onChange?: (checked: boolean) => void;
+}
+/**
+ * Checkbox Component
+ *
+ * A checkbox with three visual states:
+ * - Unchecked: Rectangle outline
+ * - Checked: Filled rectangle with checkmark
+ * - Indeterminate: Filled rectangle with minus sign
+ *
+ * Includes hover state with circular background and click ripple effect.
+ */
+declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLButtonElement>>;
+
+interface RadioProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
+    /**
+     * Whether the radio is selected (controlled)
+     */
+    checked?: boolean;
+    /**
+     * Initial selected state when uncontrolled
+     */
+    defaultChecked?: boolean;
+    /**
+     * Size of the radio
+     */
+    size?: 'small' | 'medium';
+    /**
+     * Label text for the radio
+     */
+    label?: React.ReactNode;
+    /**
+     * Callback when radio state changes
+     */
+    onChange?: (checked: boolean) => void;
+}
+declare const Radio: React.ForwardRefExoticComponent<RadioProps & React.RefAttributes<HTMLButtonElement>>;
+
+interface SwitchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
+    /**
+     * Whether the switch is on (controlled)
+     */
+    checked?: boolean;
+    /**
+     * Initial state when uncontrolled
+     */
+    defaultChecked?: boolean;
+    /**
+     * Size of the switch
+     */
+    size?: 'small' | 'large';
+    /**
+     * Label text for the switch
+     */
+    label?: React.ReactNode;
+    /**
+     * Callback when switch state changes
+     */
+    onChange?: (checked: boolean) => void;
+}
+declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
+
+type InputFormat = 'currency' | 'phone' | 'password' | 'bankAccount' | 'cardNumber';
+interface InputFormatOptions {
+    /** Separator character for currency grouping. Default: ',' */
+    separator?: ',' | '.';
+    /** Maximum number of digits (excluding separators). */
+    maxDigits?: number;
+    /** Allow decimal input for currency. Default: true */
+    allowDecimal?: boolean;
+}
+interface TextFieldDropdownOption {
+    label: string;
+    value: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+}
+interface TextFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'size'> {
+    /** Label text. */
+    label?: string;
+    /** Whether the label is placed inside or outside the input box. Default is 'outside'. */
+    labelStyle?: 'inside' | 'outside';
+    /** Supporting text displayed below the field. */
+    helperText?: string;
+    /** If true, the field will be in error state. */
+    error?: boolean;
+    /** Mark the field as required (shows * indicator). */
+    required?: boolean;
+    /** Show character count (requires maxLength to be set). */
+    showCharacterCount?: boolean;
+    /** Icon to display at the start of the field. */
+    leadingIcon?: React.ReactNode;
+    /** Text/value to display at the start (e.g., country code "+84" or "$"). */
+    leadingText?: string;
+    /** Optional label for a dropdown action at the end of the field. */
+    trailingDropdownLabel?: string;
+    /** Options for the trailing dropdown. */
+    trailingDropdownOptions?: TextFieldDropdownOption[];
+    /** Selected value for the trailing dropdown. */
+    trailingDropdownValue?: string;
+    /** Default value for the trailing dropdown (uncontrolled mode). */
+    defaultTrailingDropdownValue?: string;
+    /** Callback when trailing dropdown value changes. */
+    onTrailingDropdownChange?: (value: string) => void;
+    /** Callback for when the trailing dropdown area is clicked (only if no options provided). */
+    onTrailingDropdownClick?: () => void;
+    /** If true, shows a clear (X) button when there is text and focused. */
+    showClear?: boolean;
+    /** Callback for when the clear button is clicked. */
+    onClear?: () => void;
+    /** Shortcut hint text to display (e.g., "Ctrl + /"). */
+    shortcutHint?: string;
+    /** Custom trailing icon element. */
+    trailingIcon?: React.ReactNode;
+    /** Callback for when the trailing icon is clicked. */
+    onTrailingIconClick?: () => void;
+    /** Size of the field. Default is 'large'. */
+    size?: 'small' | 'medium' | 'large';
+    /** If true, the field will take up the full width of its container. Default is true. */
+    fullWidth?: boolean;
+    /** Fixed width of the field. */
+    width?: string | number;
+    /** Callback when the value changes. */
+    onChange?: (value: string) => void;
+    /** Whether to render the dropdown menu in a portal. Default is true. */
+    portal?: boolean;
+    /** Preset input format for automatic masking/formatting. */
+    inputFormat?: InputFormat;
+    /** Options for the input format preset. */
+    formatOptions?: InputFormatOptions;
+    /**
+     * Select the whole value when the field gains focus, by keyboard or by click,
+     * so typing replaces it. Handy for short numeric fields.
+     */
+    selectOnFocus?: boolean;
+}
+declare const TextField: React.ForwardRefExoticComponent<TextFieldProps & React.RefAttributes<HTMLInputElement>>;
+
+interface TextAreaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'onChange'> {
+    /** Label text. */
+    label?: string;
+    /** Whether the label is placed inside or outside the input box. Default is 'outside'. */
+    labelStyle?: 'inside' | 'outside';
+    /** Mark the field as required (shows * indicator). */
+    required?: boolean;
+    /** Supporting text displayed below the field. */
+    helperText?: string;
+    /** If true, the field will be in error state. */
+    error?: boolean;
+    /** Maximum character count. */
+    maxLength?: number;
+    /** Show character count. */
+    showCount?: boolean;
+    /** Callback when value changes. */
+    onChange?: (value: string) => void;
+    /** Number of visible text lines. Default is 4. */
+    rows?: number;
+    /** Visual size of the textarea. Default is 'large'. */
+    size?: 'small' | 'medium' | 'large';
+    /** Allow resize. Default is 'vertical'. */
+    resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+    /** Fixed width of the textarea. */
+    width?: string | number;
+    /** Whether the textarea takes up full width of container. Default is true. */
+    fullWidth?: boolean;
+}
+declare const TextArea: React.ForwardRefExoticComponent<TextAreaProps & React.RefAttributes<HTMLTextAreaElement>>;
+
+interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Visual style of the badge
+     * - primary: Filled background (Solid)
+     * - secondary: Light background (Subtle)
+     */
+    variant?: 'primary' | 'secondary';
+    /**
+     * Color theme of the badge
+     */
+    color?: 'gray' | 'black' | 'white' | 'red' | 'orange' | 'yellow' | 'green' | 'mint' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink' | 'brown';
+    /**
+     * Shape of the badge
+     * - rounded: Small border radius (6px)
+     * - pill: Fully rounded (capsule) - DEFAULT
+     * - icon: Circle shape with icon only
+     * - text: Pill shape with text only
+     * - dot: Small dot status indicator (8px)
+     */
+    shape?: 'rounded' | 'pill' | 'icon' | 'text' | 'dot';
+    /**
+     * Icon to display (for rounded, pill, icon shapes)
+     */
+    icon?: React.ReactNode;
+    /**
+     * Icon or small control shown after the label (for rounded and pill shapes),
+     * e.g. a remove button on a selected option
+     */
+    trailingIcon?: React.ReactNode;
+    /**
+     * Text label (for rounded, pill, text shapes)
+     */
+    label?: string;
+    /**
+     * Numeric count (alternative to label)
+     */
+    count?: number;
+    /**
+     * Show 2px stroke around badge (useful for overlapping effects)
+     * Creates visual separation when badge overlaps other elements
+     */
+    stroke?: boolean;
+    /**
+     * Force a specific theme's color tokens
+     * Useful when component needs to use Light theme tokens regardless of current theme
+     */
+    forceTheme?: 'light' | 'dark';
+}
+declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;
+
+type AvatarSize = '16' | '24' | '28' | '32' | '40' | '44' | '48' | '64' | '80' | '120';
+interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Image source
+     */
+    src?: string;
+    /**
+     * Alt text for image
+     */
+    alt?: string;
+    /**
+     * Name for initials fallback
+     */
+    name?: string;
+    /**
+     * Icon for fallback
+     */
+    icon?: React.ReactNode;
+    /**
+     * Size of the avatar
+     */
+    size?: AvatarSize;
+    /**
+     * Status indicator
+     */
+    status?: 'online' | 'offline' | 'busy' | 'away' | boolean;
+    /**
+     * Whether to show a border around the avatar (used in groups)
+     */
+    stroke?: boolean;
+}
+declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLDivElement>>;
+
+interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Avatar components
+     */
+    children: React.ReactNode;
+    /**
+     * Size of all avatars in the group
+     */
+    size?: AvatarSize;
+    /**
+     * Maximum number of avatars to display (default: 5)
+     */
+    max?: number;
+    /**
+     * Whether to show status badges on avatars (default: false)
+     * When false, status prop on child avatars will be ignored
+     */
+    showStatus?: boolean;
+}
+declare const AvatarGroup: React.ForwardRefExoticComponent<AvatarGroupProps & React.RefAttributes<HTMLDivElement>>;
+
+declare const AVATAR_IMAGES: string[];
+interface AvatarTemplateProps extends Omit<AvatarProps, 'src'> {
+    /**
+     * Index of the template image (1-6)
+     */
+    templateId?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+/**
+ * AvatarTemplate component that uses the newly imported 3D character images
+ */
+declare const AvatarTemplate: React.ForwardRefExoticComponent<AvatarTemplateProps & React.RefAttributes<HTMLDivElement>>;
+
+interface DividerProps extends React.HTMLAttributes<HTMLHRElement> {
+    /**
+     * Orientation of the divider
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Visual style of the divider
+     * @default 'solid'
+     */
+    variant?: 'solid' | 'dashed';
+    /**
+     * Thickness of the divider line
+     * @default 1
+     */
+    thickness?: 0.5 | 1;
+}
+declare const Divider: React.ForwardRefExoticComponent<DividerProps & React.RefAttributes<HTMLHRElement>>;
+
+interface SpinnerComponentProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Size of the spinner
+     * - small: 16px
+     * - medium: 24px (default)
+     * - large: 32px
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Custom color for the spinner
+     * If not provided, it inherits current text color
+     */
+    color?: string;
+    /**
+     * Visual variant
+     * - default: Standard colors for light backgrounds
+     * - inverse: Inverted colors for dark backgrounds
+     */
+    variant?: 'default' | 'inverse';
+    /**
+     * Force a specific theme's color tokens
+     * Useful when component needs to use Light theme tokens regardless of current theme
+     */
+    forceTheme?: 'light' | 'dark';
+}
+declare const Spinner: React.ForwardRefExoticComponent<SpinnerComponentProps & React.RefAttributes<HTMLDivElement>>;
+
+type AspectRatio = '1:1' | '4:3' | '3:2' | '16:9' | '21:9' | '3:1' | '3:4' | '2:3' | '9:16' | '9:21' | '1:3';
+interface ImageProps {
+    /**
+     * Image source URL
+     */
+    src: string;
+    /**
+     * Alternative text for accessibility
+     */
+    alt: string;
+    /**
+     * Fixed aspect ratio for the image
+     * @default '1:1'
+     */
+    aspectRatio?: AspectRatio;
+    /**
+     * How the image should be resized to fit its container
+     * @default 'cover'
+     */
+    objectFit?: 'cover' | 'contain';
+    /**
+     * Additional CSS class
+     */
+    className?: string;
+    /**
+     * Additional inline styles
+     */
+    style?: React__default.CSSProperties;
+}
+/**
+ * Image component with fixed aspect ratios
+ * Maintains consistent proportions regardless of container size
+ */
+declare const Image: React__default.FC<ImageProps>;
+
+interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Variant of the skeleton
+     * - text: Single line of text (16px height)
+     * - title: Heading text (24px height)
+     * - avatar: Circular avatar (40x40px)
+     * - rectangular: Custom rectangular shape
+     */
+    variant?: 'text' | 'title' | 'avatar' | 'rectangular';
+    /**
+     * Width of the skeleton (can be px, %, etc.)
+     */
+    width?: string | number;
+    /**
+     * Height of the skeleton (can be px, %, etc.)
+     */
+    height?: string | number;
+    /**
+     * Border radius variant
+     * - default: Standard rounded corners
+     * - circular: Perfect circle
+     * - rounded: Fully rounded (pill)
+     */
+    rounded?: 'default' | 'circular' | 'rounded';
+}
+declare const Skeleton: React.ForwardRefExoticComponent<SkeletonProps & React.RefAttributes<HTMLDivElement>>;
+
+interface ChipProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * The content of the chip (text)
+     */
+    label: string;
+    /**
+     * Optional icon on the left
+     */
+    icon?: React.ReactNode;
+    /**
+     * Optional avatar on the left
+     */
+    avatar?: React.ReactNode;
+    /**
+     * Visual style variant
+     * - outline: Default unselected state
+     * - filled: Selected state (dark background)
+     */
+    variant?: 'outline' | 'filled';
+    /**
+     * Badge count/text to display after label
+     */
+    badge?: number | string;
+    /**
+     * Size of the chip
+     */
+    size?: 'medium' | 'large';
+    /**
+     * Whether the chip is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Whether the chip has dropdown functionality
+     * - When true + outline: shows ChevronDownSmall
+     * - When true + filled: shows clear button (X)
+     */
+    hasDropdown?: boolean;
+    /**
+     * Callback when clear button is clicked (only for filled + hasDropdown)
+     */
+    onClear?: (e: React.MouseEvent) => void;
+    /**
+     * Optional action icon shown after the dropdown affordance
+     */
+    actionIcon?: React.ReactNode;
+    /**
+     * Callback for the optional action button
+     */
+    onAction?: (e: React.MouseEvent) => void;
+    /**
+     * Accessible label for the optional action button
+     */
+    actionLabel?: string;
+}
+declare const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLDivElement>>;
+
+interface ChipBarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Element to show on the left, typically a filter Chip or IconButton
+     */
+    leading?: React.ReactNode;
+    /**
+     * Content (Chips) to be scrollable
+     */
+    children: React.ReactNode;
+    /**
+     * Whether to show a divider after the leading element
+     */
+    showDivider?: boolean;
+    /**
+     * Size of the ChipBar
+     * - large: 60px height (default)
+     * - medium: 52px height
+     */
+    size?: 'large' | 'medium';
+    /**
+     * Whether the ChipBar is sticky (position sticky with elevator bg and shadow when stuck)
+     */
+    sticky?: boolean;
+    /**
+     * Optional externally controlled stuck state
+     */
+    stuck?: boolean;
+    /**
+     * Whether the ChipBar has horizontal padding (16px default), or custom value
+     */
+    padded?: boolean | number | string;
+}
+declare const ChipBar: React.ForwardRefExoticComponent<ChipBarProps & React.RefAttributes<HTMLDivElement>>;
+
+interface VisuallyHiddenOwnProps {
+    children?: React.ReactNode;
+}
+type VisuallyHiddenProps<C extends React.ElementType = 'span'> = PolymorphicComponentPropWithRef<C, VisuallyHiddenOwnProps>;
+declare const VisuallyHidden: React.ForwardRefExoticComponent<Omit<VisuallyHiddenProps<React.ElementType<any, keyof React.JSX.IntrinsicElements>>, "ref"> & React.RefAttributes<any>>;
+
+interface LayoutContextValue {
+    /** Whether a NavigationDrawer is present in the layout */
+    hasDrawer: boolean;
+    /** Register a drawer (called by NavigationDrawer on mount) */
+    registerDrawer: () => void;
+    /** Unregister a drawer (called by NavigationDrawer on unmount) */
+    unregisterDrawer: () => void;
+}
+declare const LayoutContext: React.Context<LayoutContextValue | null>;
+interface LayoutProviderProps {
+    children: React.ReactNode;
+}
+/**
+ * LayoutProvider - Provides context for layout-aware components
+ *
+ * Wrap your layout with this provider to enable auto-detection of
+ * NavigationDrawer presence by TopNavigation and other components.
+ *
+ * @example
+ * ```tsx
+ * <LayoutProvider>
+ *   <TopNavigation />
+ *   <NavigationDrawer>...</NavigationDrawer>
+ *   <main>...</main>
+ * </LayoutProvider>
+ * ```
+ */
+declare const LayoutProvider: React.FC<LayoutProviderProps>;
+/**
+ * Hook to access layout context
+ * Returns null if not wrapped in LayoutProvider
+ */
+declare const useLayout: () => LayoutContextValue | null;
+
+export { AVATAR_IMAGES, AspectRatio$1 as AspectRatio, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, AvatarTemplate, type AvatarTemplateProps, type BackgroundToken, Badge, Box, Button, type ButtonProps, Center, Checkbox, Chip, ChipBar, type ChipProps, Cluster, Container, CustomScrollbar, Divider, Flex, Grid, GridItem, HStack, Heading, IconButton, Image, LayoutContext, LayoutProvider, Portal, Radio, type RadioProps, type RadiusToken, type ShadowToken, SimpleGrid, Skeleton, SlotPlaceholder, type SlotPlaceholderProps, Spacer, type SpacingToken, Spinner, Stack, Switch, type SwitchProps, Text, TextArea, type TextAreaProps, TextField, type TextFieldDropdownOption, type TextFieldProps, VStack, VisuallyHidden, useLayout };