themelia-react-ui 0.0.0-stage → 1.0.1

package/dist/components/base/structure/stack.d.ts

@@ -0,0 +1,3 @@
+import type { StackProps } from './structure.types';
+/** Stack — one-dimensional composition with vertical, token-spaced defaults. */
+export declare const Stack: import("react").ForwardRefExoticComponent<Omit<StackProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/base/structure/structure.context.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The nearest Grid publishes its resolved column ladder so a GridCell can clamp
+ * a numeric span to the tracks that exist at each breakpoint. Undefined means
+ * the cell is not inside a Grid.
+ */
+export declare const GridColumnsContext: import("react").Context<Partial<Record<import("./structure.types").StructureBreakpoint, 3 | 1 | 2 | 4>> | undefined>;

package/dist/components/base/structure/structure.recipes.d.ts

@@ -0,0 +1,33 @@
+import type { AdaptiveGridMinimum, GridColumnLadder, ResponsiveValue, StructureAlign, StructureGap, StructureJustify } from './structure.types';
+/** Shared region/peer rhythm for structures and composed surface owners. */
+export declare function gapRecipe({ gap, rowGap, columnGap, }: {
+    gap?: ResponsiveValue<StructureGap>;
+    rowGap?: ResponsiveValue<StructureGap>;
+    columnGap?: ResponsiveValue<StructureGap>;
+}): string[];
+export declare function stackRecipe({ direction, gap, align, justify, wrap, }: {
+    direction?: ResponsiveValue<'vertical' | 'horizontal'>;
+    gap?: ResponsiveValue<StructureGap>;
+    align?: ResponsiveValue<StructureAlign>;
+    justify?: ResponsiveValue<StructureJustify>;
+    wrap?: ResponsiveValue<boolean>;
+}): string[];
+export declare function resolveGridColumns(columns?: ResponsiveValue<1 | 2 | 3 | 4>): GridColumnLadder;
+export declare function gridRecipe({ columns, gap, rowGap, columnGap, align, }: {
+    columns?: ResponsiveValue<1 | 2 | 3 | 4>;
+    gap?: ResponsiveValue<StructureGap>;
+    rowGap?: ResponsiveValue<StructureGap>;
+    columnGap?: ResponsiveValue<StructureGap>;
+    align?: ResponsiveValue<StructureAlign>;
+}): string[];
+export declare function adaptiveGridRecipe({ minColumnWidth, gap, rowGap, columnGap, align, }: {
+    minColumnWidth?: AdaptiveGridMinimum;
+    gap?: ResponsiveValue<StructureGap>;
+    rowGap?: ResponsiveValue<StructureGap>;
+    columnGap?: ResponsiveValue<StructureGap>;
+    align?: ResponsiveValue<StructureAlign>;
+}): string[];
+export declare function spanRecipe({ span, columns, }: {
+    span?: ResponsiveValue<1 | 2 | 3 | 4 | 'full'>;
+    columns?: GridColumnLadder;
+}): string[];

package/dist/components/base/structure/structure.responsive.d.ts

@@ -0,0 +1,5 @@
+import type { ResponsiveValue, StructureBreakpoint } from './structure.types';
+export declare const STRUCTURE_BREAKPOINTS: readonly StructureBreakpoint[];
+export declare function resolveResponsiveEntries<T>(value: ResponsiveValue<T> | undefined, fallback: T): Partial<Record<StructureBreakpoint, T>>;
+export declare function resolveOptionalResponsiveEntries<T>(value: ResponsiveValue<T> | undefined): Partial<Record<StructureBreakpoint, T>>;
+export declare function compileResponsiveClasses<T extends string | number>(entries: Partial<Record<StructureBreakpoint, T>>, classMap: Record<StructureBreakpoint, Record<T, string>>): string[];

package/dist/components/base/structure/structure.types.d.ts

@@ -0,0 +1,51 @@
+import type { useRender } from '@base-ui/react/use-render';
+import type { ComponentScale } from '../../../lib/component-vocabulary';
+export type StructureBreakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type ResponsiveValue<T> = T | Partial<Record<StructureBreakpoint, T>>;
+export type TextGap = 'normal' | 'dense';
+export type StructureGap = TextGap | 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type StructureAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+export type StructureJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+export interface StackProps extends useRender.ComponentProps<'div'> {
+    /** Main axis. Every structure prop also accepts a per-breakpoint object. Defaults to `vertical`. */
+    direction?: ResponsiveValue<'vertical' | 'horizontal'>;
+    /** Space between children, on the semantic spacing scale. Defaults to `md`. */
+    gap?: ResponsiveValue<StructureGap>;
+    /** Cross-axis alignment of children. */
+    align?: ResponsiveValue<StructureAlign>;
+    /** Main-axis distribution of children. */
+    justify?: ResponsiveValue<StructureJustify>;
+    /** Allows children to flow onto more than one line. Horizontal directions wrap by default. */
+    wrap?: ResponsiveValue<boolean>;
+}
+/** Resolved per-breakpoint column count of one Grid, shared privately with its cells. */
+export type GridColumnLadder = Partial<Record<StructureBreakpoint, 1 | 2 | 3 | 4>>;
+export interface GridProps extends useRender.ComponentProps<'div'> {
+    /** Literal or explicitly responsive column count. Defaults to one column, then two from `md`. */
+    columns?: ResponsiveValue<1 | 2 | 3 | 4>;
+    /** Space between peer surfaces. Defaults to the spacious `xl` tier. */
+    gap?: ResponsiveValue<StructureGap>;
+    /** Row gap override. */
+    rowGap?: ResponsiveValue<StructureGap>;
+    /** Column gap override. */
+    columnGap?: ResponsiveValue<StructureGap>;
+    /** Cross-axis alignment for grid items. Defaults to `stretch`. */
+    align?: ResponsiveValue<StructureAlign>;
+}
+export interface GridCellProps extends useRender.ComponentProps<'div'> {
+    /** Columns occupied, clamped to the tracks exposed by the nearest Grid. */
+    span?: ResponsiveValue<1 | 2 | 3 | 4 | 'full'>;
+}
+export type AdaptiveGridMinimum = ComponentScale;
+export interface AdaptiveGridProps extends useRender.ComponentProps<'div'> {
+    /** Minimum equal-column width before auto-fit adds another track. Defaults to `md`. */
+    minColumnWidth?: AdaptiveGridMinimum;
+    /** Space between peer surfaces. Defaults to the spacious `xl` tier. */
+    gap?: ResponsiveValue<StructureGap>;
+    /** Row gap override. */
+    rowGap?: ResponsiveValue<StructureGap>;
+    /** Column gap override. */
+    columnGap?: ResponsiveValue<StructureGap>;
+    /** Cross-axis alignment for grid items. Defaults to `stretch`. */
+    align?: ResponsiveValue<StructureAlign>;
+}

package/dist/components/base/table/index.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { Table as UITable, TableBody as UITableBody, TableCaption as UITableCaption, TableCell as UITableCell, TableFooter as UITableFooter, TableHead as UITableHead, TableHeader as UITableHeader, TableRow as UITableRow } from '../../ui/table';
+export type TableProps = React.ComponentProps<typeof UITable>;
+export type TableHeaderProps = React.ComponentProps<typeof UITableHeader>;
+export type TableBodyProps = React.ComponentProps<typeof UITableBody>;
+export type TableFooterProps = React.ComponentProps<typeof UITableFooter>;
+export type TableRowProps = React.ComponentProps<typeof UITableRow>;
+export type TableHeadProps = React.ComponentProps<typeof UITableHead>;
+export type TableCellProps = React.ComponentProps<typeof UITableCell>;
+export type TableCaptionProps = React.ComponentProps<typeof UITableCaption>;
+export declare function Table({ className, containerClassName, ...props }: TableProps): React.JSX.Element;
+export declare function TableHeader({ className, ...props }: TableHeaderProps): React.JSX.Element;
+export declare function TableBody({ className, ...props }: TableBodyProps): React.JSX.Element;
+export declare function TableFooter({ className, ...props }: TableFooterProps): React.JSX.Element;
+export declare function TableRow({ className, ...props }: TableRowProps): React.JSX.Element;
+export declare function TableHead({ className, children, ...props }: TableHeadProps): React.JSX.Element;
+export declare function TableCell({ className, children, ...props }: TableCellProps): React.JSX.Element;
+export declare function TableCaption({ className, children, ...props }: TableCaptionProps): React.JSX.Element;

package/dist/components/base/text-inputs/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useFormFieldState, type UseFormFieldStateOptions, type UseFormFieldStateReturn } from './use-form-field-state';

package/dist/components/base/text-inputs/hooks/use-form-field-state.d.ts

@@ -0,0 +1,48 @@
+export interface UseFormFieldStateOptions {
+    /** Controlled value from parent */
+    controlledValue?: string;
+    /** Default value for uncontrolled mode */
+    defaultValue?: string;
+    /** Maximum character length */
+    maxLength?: number;
+    /** Whether to show character count */
+    showCharacterCount?: boolean;
+    /** Provided ID or auto-generate */
+    providedId?: string;
+    /** Prefix for auto-generated ID */
+    idPrefix?: string;
+    /** Whether onChange is provided (for react-hook-form detection) */
+    hasOnChange?: boolean;
+}
+export interface UseFormFieldStateReturn {
+    /** Generated or provided ID */
+    id: string;
+    /** Current value (controlled or internal) */
+    value: string;
+    /** Whether component is in controlled mode */
+    isControlled: boolean;
+    /** Whether using react-hook-form (has onChange but no controlled value) */
+    isReactHookForm: boolean;
+    /** Current character count */
+    characterCount: number;
+    /** Whether a character limit is set */
+    hasCharacterLimit: boolean;
+    /** Whether to show character count UI */
+    showCount: boolean;
+    /** Whether the field has a value */
+    hasValue: boolean;
+    /** Update value - returns false if blocked by character limit */
+    updateValue: (newValue: string) => boolean;
+    /** Clear the value */
+    clearValue: () => void;
+    /** Check if a new value would exceed the character limit */
+    wouldExceedLimit: (newValue: string) => boolean;
+}
+/**
+ * Shared hook for managing form field state including:
+ * - Controlled vs uncontrolled value handling
+ * - Character counting and limits
+ * - React Hook Form compatibility detection
+ * - ID generation
+ */
+export declare function useFormFieldState({ controlledValue, defaultValue, maxLength, showCharacterCount, providedId, idPrefix, hasOnChange, }: UseFormFieldStateOptions): UseFormFieldStateReturn;

package/dist/components/base/text-inputs/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * text-inputs — controls for free-form text entry.
+ *
+ * Split out of `base/forms`, which had grown to ~4,950 lines across twenty
+ * controls. The boundary is what the user does, not what the value is called:
+ * everything here accepts arbitrary typing, so they share the same
+ * controlled/uncontrolled bridge, character counting and clear affordance.
+ *
+ * Related families:
+ *   - `themelia-react-ui/base/choice-inputs` — picking from a known set
+ *   - `themelia-react-ui/base/value-inputs` — editing one structured value
+ *   - `themelia-react-ui/base/forms` — the label/control/error row itself
+ *
+ * `useFormFieldState` is intentionally not exported. It is the shared bridge
+ * behind `Input` and `Textarea`, not a composition seam.
+ */
+export { Input, defaultInputStrings, type InputProps, type InputStrings } from './input';
+export { Textarea, type TextareaProps } from './textarea';
+export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, type InputGroupProps, type InputGroupAddonProps, type InputGroupButtonProps, type InputGroupInputProps, type InputGroupTextProps, type InputGroupTextareaProps, } from './input-group';
+export { PasswordInput, defaultPasswordInputStrings, type PasswordInputProps, type PasswordInputStrings, } from './password-input';
+export { SlugField, slugifyValue, type SlugFieldProps, type SlugifyValueOptions, } from './slug-field';

package/dist/components/base/text-inputs/input-group.d.ts

@@ -0,0 +1,46 @@
+/**
+ * InputGroup — base wrapper around the shadcn `ui/input-group` primitive.
+ *
+ * What this layer adds on top of the primitive:
+ *  - Stable BEM hooks on every wrapped part's outermost node
+ *    (`input-group--component`, `input-group-addon--component`, and so on).
+ *  - Design-system typography for the scalar copy inside `InputGroupText`,
+ *    while arbitrary `ReactNode` content (icons, `kbd`, buttons) passes through
+ *    untouched so the compound pattern stays composable.
+ *  - Keeps the primitive's addon alignment and button-size variants, its
+ *    focus-within/aria-invalid ring behaviour, and every native prop by spread.
+ *
+ * Compose it as
+ * `<InputGroup><InputGroupAddon><Icon/></InputGroupAddon><InputGroupInput/></InputGroup>`.
+ *
+ * Reach for it when one control needs inline affordances welded to its frame —
+ * a search icon, a unit suffix, a busy indicator, an inline action. For the
+ * label / control / hint / error row, use `FormField` instead; this wrapper
+ * owns only the control frame.
+ */
+import type { ComponentProps } from 'react';
+import { InputGroup as InputGroupPrimitive, InputGroupAddon as InputGroupAddonPrimitive, InputGroupInput as InputGroupInputPrimitive, InputGroupText as InputGroupTextPrimitive, InputGroupTextarea as InputGroupTextareaPrimitive } from '../../ui/input-group';
+import { type ButtonProps } from '../buttons';
+import type { ComponentScale } from '../../../lib/ui-provider';
+export type InputGroupProps = ComponentProps<typeof InputGroupPrimitive>;
+export type InputGroupAddonProps = ComponentProps<typeof InputGroupAddonPrimitive>;
+export interface InputGroupButtonProps extends Omit<ButtonProps, 'size'> {
+    /** Component scale. Falls back to `UIProvider.density.defaultScale`. */
+    size?: ComponentScale;
+}
+export type InputGroupInputProps = ComponentProps<typeof InputGroupInputPrimitive>;
+export type InputGroupTextProps = ComponentProps<typeof InputGroupTextPrimitive>;
+export type InputGroupTextareaProps = ComponentProps<typeof InputGroupTextareaPrimitive>;
+/** Control frame that welds inline addons onto a single input or textarea. */
+declare function InputGroup({ className, ...props }: InputGroupProps): import("react").JSX.Element;
+/** Leading/trailing (or block start/end) affordance slot inside the frame. */
+declare function InputGroupAddon({ className, align, ...props }: InputGroupAddonProps): import("react").JSX.Element;
+/** Inline action button sized to sit inside the control frame. */
+declare function InputGroupButton({ className, tone, buttonStyle, ...props }: InputGroupButtonProps): import("react").JSX.Element;
+/** Static copy segment — scalar text renders through Typography. */
+declare function InputGroupText({ children, className, ...props }: InputGroupTextProps): import("react").JSX.Element;
+/** Single-line control that inherits the group's frame instead of its own. */
+declare function InputGroupInput({ className, ...props }: InputGroupInputProps): import("react").JSX.Element;
+/** Multi-line control that inherits the group's frame instead of its own. */
+declare function InputGroupTextarea({ className, ...props }: InputGroupTextareaProps): import("react").JSX.Element;
+export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, };

package/dist/components/base/text-inputs/input.d.ts

@@ -0,0 +1,45 @@
+import { type LucideIcon } from 'lucide-react';
+import * as React from 'react';
+import { type FormControlSize } from '../../../lib/ui-provider';
+import { type StringsProp } from '../../../lib/strings';
+export interface InputStrings {
+    /** Accessible label for the clear action. */
+    clear: string;
+}
+export declare const defaultInputStrings: InputStrings;
+export interface InputProps extends Omit<React.ComponentProps<'input'>, 'onChange' | 'size'> {
+    /** Decorative or semantic icon rendered before the value. */
+    startIcon?: LucideIcon;
+    /** Decorative or semantic icon rendered after the value. */
+    endIcon?: LucideIcon;
+    /** Visual text prefix rendered inside the input frame. */
+    startAddon?: string;
+    /** Visual text suffix rendered inside the input frame. */
+    endAddon?: string;
+    /** Maximum accepted character count. */
+    maxLength?: number;
+    /** Shows the current and maximum character count. */
+    showCharacterCount?: boolean;
+    /** Shows an inline clear action when the input has a value. */
+    clearable?: boolean;
+    /** Called after the inline clear action resets the value. */
+    onClear?: () => void;
+    /** Replaces the trailing affordance with a loading indicator. */
+    loading?: boolean;
+    /** Includes visual add-on text in the value exposed by `onChange`. */
+    returnValueWithAddons?: boolean;
+    /** Applies invalid control styling. Validation copy remains owned by FormField. */
+    invalid?: boolean;
+    /** Control-height preset. Falls back to `UIProvider.density.defaultScale`. */
+    size?: FormControlSize;
+    /** Native-style value callback for the controlled raw string. */
+    onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Controlled raw string value. */
+    value?: string;
+    /** Initial raw string value for uncontrolled usage. */
+    defaultValue?: string;
+    /** Accessible copy overrides for input-owned actions. */
+    strings?: StringsProp<InputStrings>;
+}
+declare const Input: React.NamedExoticComponent<Omit<InputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+export { Input };

package/dist/components/base/text-inputs/password-input.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import { type InputProps } from './input';
+export interface PasswordInputStrings {
+    showPassword: string;
+    hidePassword: string;
+}
+export declare const defaultPasswordInputStrings: PasswordInputStrings;
+export interface PasswordInputProps extends Omit<InputProps, 'type' | 'endIcon' | 'strings'> {
+    /** Whether the value is revealed. Controlled. */
+    visible?: boolean;
+    /** Whether the value starts revealed, for uncontrolled use. */
+    defaultVisible?: boolean;
+    /** Fired whenever the reveal state changes. */
+    onVisibleChange?: (visible: boolean) => void;
+    /** Shows the reveal toggle. Turn it off for fields that must stay masked. */
+    revealable?: boolean;
+    /** Merged onto the field wrapper, outside the input frame. */
+    wrapperClassName?: string;
+    /** Merged onto the reveal toggle. */
+    visibilityButtonClassName?: string;
+    /** Copy overrides forwarded to the underlying text input. */
+    inputStrings?: InputProps['strings'];
+    /** Overrides the show/hide accessible names. */
+    strings?: StringsProp<PasswordInputStrings>;
+}
+declare const PasswordInput: React.ForwardRefExoticComponent<Omit<PasswordInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+export { PasswordInput };

package/dist/components/base/text-inputs/slug-field.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { type InputProps } from './input';
+export interface SlugifyValueOptions {
+    /** Character joining words in the generated slug. Default: `-`. */
+    separator?: string;
+    /** Lowercases the generated slug. */
+    lowercase?: boolean;
+    /** Strips leading and trailing separators. */
+    trim?: boolean;
+}
+export declare function slugifyValue(value: string | number | null | undefined, { separator, lowercase, trim, }?: SlugifyValueOptions): string;
+export interface SlugFieldProps extends Omit<InputProps, 'value' | 'defaultValue' | 'onChange' | 'readOnly' | 'type'>, SlugifyValueOptions {
+    /** Current slug. Controlled. */
+    value: string | number | null | undefined;
+    /** Replaces the built-in slug derivation entirely. */
+    slugify?: (value: string | number | null | undefined) => string;
+    /** Merged onto the field wrapper, outside the input frame. */
+    wrapperClassName?: string;
+}
+declare const SlugField: React.ForwardRefExoticComponent<Omit<SlugFieldProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+export { SlugField };

package/dist/components/base/text-inputs/textarea.d.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import { type FormControlSize } from '../../../lib/ui-provider';
+import { type StringsProp } from '../../../lib/strings';
+export interface TextareaStrings {
+    clear: string;
+}
+export declare const defaultTextareaStrings: TextareaStrings;
+export interface TextareaProps extends Omit<React.ComponentProps<'textarea'>, 'onChange'> {
+    /** Overrides the character-count and clear copy. */
+    strings?: StringsProp<TextareaStrings>;
+    /** Character cap, also used as the denominator of the count. */
+    maxLength?: number;
+    /** Shows the current and maximum character count. */
+    showCharacterCount?: boolean;
+    /** Shows an inline clear action when the field has a value. */
+    clearable?: boolean;
+    onClear?: () => void;
+    /** Replaces the trailing affordance with a loading indicator. */
+    loading?: boolean;
+    /** Applies the invalid styling. Validation copy stays with FormField. */
+    invalid?: boolean;
+    /** Control density. Falls back to `UIProvider.density.defaultScale`. */
+    size?: FormControlSize;
+    /** Grows the field with its content, between `minRows` and `maxRows`. */
+    autoResize?: boolean;
+    /** Smallest height, in rows, when `autoResize` is set. */
+    minRows?: number;
+    /** Height at which the field stops growing and starts scrolling. */
+    maxRows?: number;
+    onChange?: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    /** Current text. Controlled. */
+    value?: string;
+    /** Initial text for uncontrolled use. */
+    defaultValue?: string;
+}
+declare const Textarea: React.ForwardRefExoticComponent<Omit<TextareaProps, "ref"> & React.RefAttributes<HTMLTextAreaElement>>;
+export { Textarea };

package/dist/components/base/toaster/index.d.ts

@@ -0,0 +1 @@
+export { Toaster, type ToasterProps } from './toaster';

package/dist/components/base/toaster/toaster.d.ts

@@ -0,0 +1,6 @@
+import type { ToasterProps } from 'sonner';
+export type { ToasterProps };
+export declare function Toaster({ duration: durationProp, position: positionProp, theme: themeProp, closeButton: closeButtonProp, richColors: richColorsProp, visibleToasts: visibleToastsProp, toastOptions, icons, className, style, ...props }: ToasterProps): import("react").JSX.Element;
+export declare namespace Toaster {
+    var displayName: string;
+}

package/dist/components/base/tree/hierarchy.d.ts

@@ -0,0 +1,11 @@
+import type { TreeNode } from './tree.types';
+export interface HierarchyEntry<T> {
+    node: TreeNode<T>;
+    parent: string | null;
+    path: TreeNode<T>[];
+    disabled: boolean;
+}
+/** One canonical traversal for tree focus, cascader paths and local search. */
+export declare function indexHierarchy<T>(items: readonly TreeNode<T>[]): Map<string, HierarchyEntry<T>>;
+export declare function visibleHierarchy<T>(index: Map<string, HierarchyEntry<T>>, expanded: readonly string[]): HierarchyEntry<T>[];
+export declare function isBranch(node: TreeNode): boolean;

package/dist/components/base/tree/index.d.ts

@@ -0,0 +1,2 @@
+export { Tree } from './tree';
+export type { TreeNode, TreeProps, TreeStrings } from './tree.types';

package/dist/components/base/tree/tree.d.ts

@@ -0,0 +1,3 @@
+import type { TreeProps } from './tree.types';
+/** Accessible data-driven hierarchy. Focus moves independently from selection. */
+export declare function Tree<T = unknown>({ items, expandedValues, defaultExpandedValues, onExpandedValuesChange, selectedValues, defaultSelectedValues, onSelectedValuesChange, selectionMode, branchActivation, disabled, density, rowLayout, indent, showGuides, empty, strings, renderLabel, className, onKeyDown, ...props }: TreeProps<T>): import("react").JSX.Element;

package/dist/components/base/tree/tree.types.d.ts

@@ -0,0 +1,47 @@
+import type { ComponentProps, ReactNode } from 'react';
+import type { RowDensity } from '../../../lib/row-recipes';
+/** Stable values must be unique throughout a hierarchy. */
+export interface TreeNode<T = unknown> {
+    value: string;
+    label: string;
+    /** Supporting copy in rich rows; plain strings provide a title/description in line rows. */
+    description?: ReactNode;
+    icon?: ReactNode;
+    /** Non-interactive status or metadata, aligned at the end of the row. */
+    trailing?: ReactNode;
+    children?: readonly TreeNode<T>[];
+    /** Declares an unloaded branch. */
+    hasChildren?: boolean;
+    /** Disables this node and its descendants. */
+    disabled?: boolean;
+    data?: T;
+}
+export interface TreeStrings {
+    expand: (label: string) => string;
+    collapse: (label: string) => string;
+}
+export interface TreeProps<T = unknown> extends Omit<ComponentProps<'div'>, 'children' | 'onSelect'> {
+    items: readonly TreeNode<T>[];
+    expandedValues?: readonly string[];
+    defaultExpandedValues?: readonly string[];
+    onExpandedValuesChange?: (values: string[], node: TreeNode<T>) => void;
+    selectedValues?: readonly string[];
+    defaultSelectedValues?: readonly string[];
+    onSelectedValuesChange?: (values: string[], node: TreeNode<T>) => void;
+    selectionMode?: 'single' | 'multiple' | 'none';
+    /** Clicking or pressing Enter/Space on a branch selects it, or toggles its children. */
+    branchActivation?: 'select' | 'toggle';
+    disabled?: boolean;
+    /** Vertical row rhythm. Compact by default; primary text retains the shared size. */
+    density?: RowDensity;
+    /** Navigation is single-line by default. Rich rows explicitly allow supporting copy and wrapping. */
+    rowLayout?: 'line' | 'rich';
+    /** Explicit per-level indentation in pixels. Omit to inherit shared spacing. */
+    indent?: number;
+    /** Decorative guides retain the hierarchy at every nesting level. */
+    showGuides?: boolean;
+    empty?: ReactNode;
+    strings?: Partial<TreeStrings>;
+    /** Presentation slot only; interactive content should live outside the tree row. */
+    renderLabel?: (node: TreeNode<T>) => ReactNode;
+}

package/dist/components/base/upload/avatar-upload.d.ts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import { type ComponentScale } from '../../../lib/ui-provider';
+export type AvatarUploadSize = ComponentScale;
+export interface AvatarUploadStrings {
+    change: string;
+    remove: string;
+    hint: string;
+    dragOver: string;
+    invalidType: (fileName: string, extension: string) => string;
+    tooSmall: (fileName: string, minimum: string) => string;
+    tooLarge: (fileName: string, maximum: string) => string;
+    tooMany: (fileName: string, maximum: number) => string;
+    duplicate: (fileName: string) => string;
+    customValidationFailed: (fileName: string) => string;
+}
+export declare const defaultAvatarUploadStrings: AvatarUploadStrings;
+export interface AvatarUploadProps {
+    /** Selected file. Controlled. */
+    value?: File;
+    onValueChange?: (file?: File) => void;
+    /** Image shown before anything is chosen — an existing avatar. */
+    initialPreviewUrl?: string;
+    /** Accepted MIME types or extensions. */
+    accept?: string;
+    /** Disables the control and blocks drops. */
+    disabled?: boolean;
+    /** Applies the invalid styling. */
+    invalid?: boolean;
+    /** Diameter preset for the avatar. */
+    size?: AvatarUploadSize;
+    className?: string;
+    /** Overrides the upload and remove copy. */
+    strings?: StringsProp<AvatarUploadStrings>;
+    /** Initials shown when no preview is available. */
+    initials?: string;
+}
+declare const AvatarUpload: React.ForwardRefExoticComponent<AvatarUploadProps & React.RefAttributes<HTMLInputElement>>;
+export { AvatarUpload };

package/dist/components/base/upload/dropzone.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Dropzone — accessible drag-and-drop chrome with a native file-input fallback.
+ * It owns no validation or file state; consumers receive local `File` values.
+ */
+import { type ReactNode } from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import { type ComponentScale } from '../../../lib/ui-provider';
+import { type FilePickerNativeInputProps } from './file-picker-input';
+export type DropzoneSize = ComponentScale;
+export interface DropzoneStrings {
+    instruction: string;
+    helper: string;
+    dragOver: string;
+}
+export declare const defaultDropzoneStrings: DropzoneStrings;
+export type DropzoneInputProps = Omit<FilePickerNativeInputProps, 'accept' | 'disabled' | 'multiple'>;
+export interface DropzoneProps {
+    onDrop: (files: File[]) => void;
+    /** Accepted MIME types or extensions. */
+    accept?: string;
+    /** Allows more than one file to be dropped. */
+    multiple?: boolean;
+    /** Disables the control and blocks drops. */
+    disabled?: boolean;
+    /** Applies the invalid styling. */
+    invalid?: boolean;
+    /** Height preset for the drop target. */
+    size?: DropzoneSize;
+    /** Glyph shown inside the drop target. */
+    icon?: ReactNode;
+    className?: string;
+    /** Native form, ARIA, data, and event attributes forwarded to the file input. */
+    inputProps?: DropzoneInputProps;
+    /** Optional action rendered outside the input label, so nested controls remain valid. */
+    children?: ReactNode;
+    /** Overrides the prompt and constraint copy. */
+    strings?: StringsProp<DropzoneStrings>;
+}
+declare const Dropzone: import("react").ForwardRefExoticComponent<DropzoneProps & import("react").RefAttributes<HTMLInputElement>>;
+export { Dropzone };

package/dist/components/base/upload/file-picker-input.d.ts

@@ -0,0 +1,15 @@
+import { type InputHTMLAttributes } from 'react';
+type DataAttributes = {
+    [key: `data-${string}`]: string | number | boolean | undefined;
+};
+export type FilePickerNativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'defaultValue' | 'onChange' | 'children'> & DataAttributes;
+export type FilePickerInputProps = FilePickerNativeInputProps & {
+    /** Return `false` when the native FileList must be cleared (for example, after rejection). */
+    onFiles: (files: File[]) => boolean | void;
+};
+/** Shared native-input plumbing for FileUpload and Dropzone. Not a public export. */
+export declare const FilePickerInput: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "children" | "value" | "defaultValue" | "onChange" | "type"> & DataAttributes & {
+    /** Return `false` when the native FileList must be cleared (for example, after rejection). */
+    onFiles: (files: File[]) => boolean | void;
+} & import("react").RefAttributes<HTMLInputElement>>;
+export {};

package/dist/components/base/upload/file-upload.d.ts

@@ -0,0 +1,9 @@
+import { defaultFileUploadStrings, type FileUploadStrings } from './file-upload.strings';
+import type { MultipleFileUploadProps, SingleFileUploadProps } from './file-upload.types';
+/** Public discriminated single/multiple contract, declared here for docgen discoverability. */
+export type FileUploadProps = SingleFileUploadProps | MultipleFileUploadProps;
+/** Selects and validates local File values without performing network uploads. */
+export declare const FileUpload: import("react").ForwardRefExoticComponent<FileUploadProps & import("react").RefAttributes<HTMLInputElement>>;
+export { defaultFileUploadStrings };
+export type { FileUploadStrings };
+export type { FileUploadRejection, FileUploadRejectionCode, FileUploadCommonProps, FileUploadSelectionMode, FileUploadValidator, MultipleFileUploadProps, SingleFileUploadProps, } from './file-upload.types';

package/dist/components/base/upload/file-upload.strings.d.ts

@@ -0,0 +1,18 @@
+export interface FileUploadStrings {
+    instruction: string;
+    helper: string;
+    browse: string;
+    replace: string;
+    remove: string;
+    dragOver: string;
+    errorsHeading: string;
+    replaceFileAria: (fileName: string) => string;
+    removeFileAria: (fileName: string) => string;
+    invalidType: (fileName: string, accept: string) => string;
+    fileTooSmall: (fileName: string, minimum: string) => string;
+    fileTooLarge: (fileName: string, maximum: string) => string;
+    tooManyFiles: (fileName: string, maximum: number) => string;
+    duplicateFile: (fileName: string) => string;
+    customValidationFailed: (fileName: string) => string;
+}
+export declare const defaultFileUploadStrings: FileUploadStrings;