themelia-react-ui 0.0.0-stage → 1.0.1

package/dist/components/base/action-menu/action-menu.d.ts

@@ -0,0 +1,147 @@
+/**
+ * ActionMenu — centralized action chrome for page, card, table, and row
+ * overflow menus.
+ *
+ * Primary API is definition-driven: pass `actions={[...]}` and the component
+ * renders the trigger, menu surface, grouping, checkbox rows, destructive
+ * separation, links, disabled state, and density. `ActionButtons` renders the
+ * same definitions as inline buttons for page/toolbars that need visible
+ * actions plus an overflow menu.
+ */
+import type { LucideIcon } from 'lucide-react';
+import React, { type ComponentType, type ReactElement, type ReactNode } from 'react';
+import { Button, type ButtonSize } from '../buttons';
+import { type CollectionDensity } from '../popover/popover.recipes';
+import { DropdownMenuTrigger } from '../navigation/dropdown-menu';
+import type { ActionPresentation } from '../../../lib/action-presentation';
+import { type StringsProp } from '../../../lib/strings';
+import { type ActionMenuStrings } from './action-menu.strings';
+type ActionMenuButtonProps = Partial<React.ComponentPropsWithoutRef<typeof Button>> & {
+    [key: `data-${string}`]: string | boolean | undefined;
+    'aria-label'?: string;
+    onPointerDown?: React.PointerEventHandler<HTMLButtonElement>;
+};
+export type ActionMenuDensity = CollectionDensity | 'table';
+export type ActionMenuLabelVisibility = 'visible' | 'responsive' | 'hidden';
+export interface ActionMenuLinkRenderProps extends React.ComponentPropsWithoutRef<'a'> {
+    href: string;
+    disabled?: boolean;
+    external?: boolean;
+}
+export type ActionMenuIcon = LucideIcon | ComponentType<{
+    className?: string;
+}> | ReactNode;
+export interface ActionMenuAction extends ActionPresentation {
+    /** Stable React key. Falls back to a string `label`, then the index. */
+    id?: string;
+    /** Visible label for the entry. */
+    label: ReactNode;
+    /** Leading glyph. Accepts a Lucide icon, a component, or a rendered node. */
+    icon?: ActionMenuIcon;
+    /** `'checkbox'` renders a toggle driven by `checked`/`onCheckedChange`. Defaults to `'item'`. */
+    type?: 'item' | 'checkbox';
+    /**
+     * Renders the entry as a link. By default this is a native `<a href>`, so it
+     * performs a full page navigation; pass `renderLink` on `ActionMenu` to route
+     * it through your framework's router instead.
+     */
+    href?: string;
+    /** Anchor target forwarded to the rendered link. Requires `href`. */
+    target?: string;
+    /** Anchor rel forwarded to the rendered link. Requires `href`. */
+    rel?: string;
+    /** Marks the destination as leaving the app; forwarded to `renderLink`. */
+    external?: boolean;
+    /** Runs when the entry is chosen. This is the handler for a normal item. */
+    onClick?: () => void;
+    /** Checked state for a `'checkbox'` entry. */
+    checked?: boolean;
+    /** Fires with the next checked state for a `'checkbox'` entry. */
+    onCheckedChange?: (checked: boolean) => void;
+    /**
+     * Starts a new group, drawing a separator above this entry. A string also
+     * captions the group; `true` rules off without a heading, for the common
+     * case of holding one entry apart (a sign-out, a delete) with no label to
+     * write.
+     */
+    group?: string | true;
+    /** Overrides the button size when the action renders as a button. */
+    buttonSize?: ButtonSize;
+    /** Escape hatch merged onto the entry root. */
+    className?: string;
+    /** Escape hatch merged onto the entry's inner content. */
+    contentClassName?: string;
+    /** Overrides the menu's `closeOnSelect` for this entry. */
+    closeOnSelect?: boolean;
+    /** Replaces the rendered entry, e.g. to emit a framework `<Link>`. */
+    render?: ReactNode;
+}
+export interface ActionMenuProps {
+    /**
+     * Commands to offer. Destructive entries are moved last unless
+     * `preserveOrder` is set.
+     */
+    actions: readonly ActionMenuAction[];
+    /** Trigger text. Omit for an icon-only trigger, and set `srText` instead. */
+    label?: string;
+    /** Trigger glyph. Defaults to the horizontal ellipsis. */
+    icon?: ActionMenuIcon;
+    /** Accessible name when the trigger shows no visible `label`. */
+    srText?: string;
+    /** Escape hatch forwarded to the trigger button. */
+    buttonProps?: ActionMenuButtonProps;
+    /** Menu alignment against the trigger. Defaults to `end`. */
+    align?: 'center' | 'start' | 'end';
+    /** Which edge of the trigger the menu opens from. Defaults to `bottom`. */
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    /** Merged onto the menu surface. */
+    contentClassName?: string;
+    /** Fixed menu width. Defaults to sizing from the widest item. */
+    width?: string;
+    /** Closes the menu after an action runs. Defaults to `true`. */
+    closeOnSelect?: boolean;
+    /** Vertical row rhythm; table preserves the legacy tight action spacing. Inline room stays stable. */
+    density?: ActionMenuDensity;
+    /** Whether the trigger's `label` is visible, hidden, or responsive. */
+    labelVisibility?: ActionMenuLabelVisibility;
+    /** Preserve incoming action order instead of moving destructive items last. */
+    preserveOrder?: boolean;
+    /**
+     * Renders actions carrying an `href` through the consumer's router, keeping
+     * this component framework-agnostic. Without it, such actions render as
+     * plain anchors.
+     */
+    renderLink?: (props: ActionMenuLinkRenderProps) => ReactElement;
+    /**
+     * Replaces the default trigger button entirely, so a menu can hang off a
+     * shape that is not a button with a glyph — an account block, a sidebar
+     * row, a tab that has to match its siblings.
+     *
+     * Takes Base UI's `render` contract: either an element, whose props are
+     * merged for you, or a function receiving the props to spread. Either way
+     * the ARIA wiring, the open/close handlers and the popup's anchor ref reach
+     * a real DOM node without anyone cloning anything.
+     *
+     * For a plain button that just needs different words or a different glyph,
+     * `label`, `icon` and `buttonProps` are the smaller tools; reach for this
+     * only when the trigger is a different thing.
+     */
+    renderTrigger?: React.ComponentProps<typeof DropdownMenuTrigger>['render'];
+    /** Overrides the menu's own copy (the default trigger label). */
+    strings?: StringsProp<ActionMenuStrings>;
+}
+export interface ActionButtonsProps {
+    /** Commands to render side by side rather than collapsed into a menu. */
+    actions: readonly ActionMenuAction[];
+    /** Merged onto the button group. */
+    className?: string;
+    /** Merged onto every button in the group. */
+    buttonClassName?: string;
+    /** Height preset applied to each button. */
+    size?: ButtonSize;
+    /** Renders actions carrying an `href` through the consumer's router. */
+    renderLink?: (props: ActionMenuLinkRenderProps) => ReactElement;
+}
+export declare const ActionMenu: React.ForwardRefExoticComponent<ActionMenuProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const ActionButtons: React.ForwardRefExoticComponent<ActionButtonsProps & React.RefAttributes<HTMLDivElement>>;
+export { defaultActionMenuStrings, type ActionMenuStrings, } from './action-menu.strings';

package/dist/components/base/action-menu/action-menu.strings.d.ts

@@ -0,0 +1,4 @@
+export interface ActionMenuStrings {
+    openMenuLabel: string;
+}
+export declare const defaultActionMenuStrings: ActionMenuStrings;

package/dist/components/base/action-menu/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Action menu — one definition-driven action surface for page, card, table,
+ * and row actions.
+ *
+ * `ActionMenu` renders an `actions` array as an overflow menu; `ActionButtons`
+ * renders the same definitions as inline buttons. They are action affordances
+ * rather than navigation, so they own their own family instead of sitting
+ * beside breadcrumbs and tab bars.
+ */
+export { ActionButtons, ActionMenu, type ActionButtonsProps, type ActionMenuAction, type ActionMenuIcon, type ActionMenuLinkRenderProps, type ActionMenuProps, } from './action-menu';
+export { defaultActionMenuStrings, type ActionMenuStrings, } from './action-menu.strings';

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

@@ -0,0 +1,17 @@
+import { type ProgressProps } from '../feedback';
+import { type ItemMediaProps, type ItemContentProps, type ItemTitleProps, type ItemDescriptionProps, type ItemActionsProps } from '../item';
+import { type AttachmentProps, type AttachmentKind } from './attachment.types';
+/** Filename categorization is display-only and does not trust a file's extension for validation. */
+export declare function getAttachmentKind(name: string): AttachmentKind;
+export declare function AttachmentFileIcon({ name, kind }: {
+    name: string;
+    kind?: AttachmentKind;
+}): import("react").JSX.Element;
+export declare const AttachmentMedia: import("react").ForwardRefExoticComponent<Omit<ItemMediaProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const AttachmentContent: import("react").ForwardRefExoticComponent<Omit<ItemContentProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const AttachmentTitle: import("react").ForwardRefExoticComponent<Omit<ItemTitleProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const AttachmentDescription: import("react").ForwardRefExoticComponent<Omit<ItemDescriptionProps, "ref"> & import("react").RefAttributes<HTMLParagraphElement>>;
+export declare const AttachmentActions: import("react").ForwardRefExoticComponent<Omit<ItemActionsProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare function AttachmentProgress({ className, ...props }: ProgressProps): import("react").JSX.Element;
+/** File presentation; callbacks own preview, transfer and removal. Card framing belongs to the caller. */
+export declare const Attachment: import("react").ForwardRefExoticComponent<AttachmentProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,49 @@
+import type { ComponentPropsWithoutRef, ReactNode, ReactElement } from 'react';
+import type { StringsProp } from '../../../lib/strings';
+import type { ItemDensity, ItemSize, ItemVariant } from '../item';
+export type AttachmentKind = 'image' | 'document' | 'audio' | 'video' | 'code' | 'archive' | 'generic';
+export type AttachmentStatus = 'queued' | 'uploading' | 'done' | 'error' | 'cancelled';
+export interface AttachmentStrings {
+    preview: (name: string) => string;
+    download: (name: string) => string;
+    remove: (name: string) => string;
+    queued: string;
+    uploading: string;
+    done: string;
+    error: string;
+    cancelled: string;
+}
+export declare const defaultAttachmentStrings: AttachmentStrings;
+export interface AttachmentProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title' | 'onError'> {
+    /** Display filename. Omit only when assembling children using Attachment anatomy. */
+    name?: string;
+    /** Caller-formatted metadata takes precedence over bytes. */
+    meta?: ReactNode;
+    bytes?: number;
+    locale?: string;
+    kind?: AttachmentKind;
+    media?: ReactNode;
+    thumbnailUrl?: string;
+    status?: AttachmentStatus;
+    /** Upload progress in the 0–100 range. A missing uploading value is indeterminate. */
+    progress?: number | null;
+    error?: ReactNode;
+    /** Override generated status copy while preserving status/progress behavior. */
+    description?: ReactNode;
+    /** Additional sibling actions. */
+    actions?: ReactNode;
+    /** Open or preview the whole body, with independent sibling action buttons. Uses the preview string for its accessible name. */
+    onOpen?: () => void;
+    onPreview?: () => void;
+    onDownload?: () => void;
+    onRemove?: () => void;
+    disabled?: boolean;
+    /** Compact horizontal chip, full list row, or a media-first gallery tile. */
+    layout?: 'compact' | 'list' | 'gallery';
+    size?: ItemSize;
+    density?: ItemDensity;
+    variant?: ItemVariant;
+    /** Element used for a list item without wrapping or inspecting children. */
+    render?: ReactElement;
+    strings?: StringsProp<AttachmentStrings>;
+}

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

@@ -0,0 +1,2 @@
+export { Attachment, AttachmentMedia, AttachmentFileIcon, AttachmentContent, AttachmentTitle, AttachmentDescription, AttachmentActions, AttachmentProgress, getAttachmentKind } from './attachment';
+export { defaultAttachmentStrings, type AttachmentProps, type AttachmentKind, type AttachmentStatus, type AttachmentStrings } from './attachment.types';

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

@@ -0,0 +1,24 @@
+/**
+ * Avatar — tokenized base wrapper around the shadcn/Base UI avatar primitive.
+ * Public sizing uses the shared component scale.
+ */
+import * as React from 'react';
+import { Avatar as PrimitiveAvatar, AvatarBadge as PrimitiveAvatarBadge, AvatarFallback as PrimitiveAvatarFallback, AvatarGroup as PrimitiveAvatarGroup, AvatarGroupCount as PrimitiveAvatarGroupCount, AvatarImage as PrimitiveAvatarImage } from '../../ui/avatar';
+import { type ComponentScale } from '../../../lib/ui-provider';
+export type AvatarSize = ComponentScale;
+export interface AvatarProps extends Omit<React.ComponentPropsWithoutRef<typeof PrimitiveAvatar>, 'size'> {
+    /** Size preset. */
+    size?: AvatarSize;
+}
+export type AvatarImageProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarImage>;
+export type AvatarFallbackProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarFallback>;
+export type AvatarBadgeProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarBadge>;
+export type AvatarGroupProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarGroup>;
+export type AvatarGroupCountProps = React.ComponentPropsWithoutRef<typeof PrimitiveAvatarGroupCount>;
+declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLSpanElement>>;
+declare const AvatarImage: React.ForwardRefExoticComponent<Omit<import("@base-ui/react").AvatarImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
+declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<import("@base-ui/react").AvatarFallbackProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare const AvatarBadge: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLSpanElement> & React.HTMLAttributes<HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare const AvatarGroup: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const AvatarGroupCount: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarBadge, };

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

@@ -0,0 +1,14 @@
+/**
+ * Identity media.
+ *
+ * `Avatar` is the compound primitive — image, initials fallback, status badge,
+ * and the group/overflow parts — for one person or entity. `StackedAvatars` is
+ * the recipe on top of it: hand it an array of users and it renders the
+ * standard overlap, fallbacks, and overflow count.
+ *
+ * Neither knows anything about titles, descriptions, or actions. An avatar that
+ * heads a complete identity row belongs in `Item` from
+ * `themelia-react-ui/base/item`, with the avatar passed as its media slot.
+ */
+export * from './avatar';
+export { StackedAvatars, type StackedAvatarsProps, type StackedAvatarUser, type StackedAvatarTone, type StackedAvatarsSize, } from './stacked-avatars';

package/dist/components/base/avatar/stacked-avatars.d.ts

@@ -0,0 +1,39 @@
+/**
+ * StackedAvatars — overlapping avatar group with optional `+N` overflow chip,
+ * configurable size, and an optional semantic `tone` for fallbacks (initials)
+ * when the consumer hasn't passed `imageUrl`.
+ *
+ * Wraps the shadcn AvatarGroup primitive with library-default sizes and a
+ * deterministic tone picker so fallbacks stay stable without raw hue utilities.
+ */
+import * as React from 'react';
+import { type ComponentScale } from '../../../lib/ui-provider';
+import type { SemanticTone } from '../../../lib/component-vocabulary';
+export type StackedAvatarsSize = ComponentScale;
+export type StackedAvatarTone = SemanticTone;
+export interface StackedAvatarUser {
+    /** Stable identity for this entry. */
+    id?: string;
+    /** Form field name, forwarded for native submits. */
+    name: string;
+    imageUrl?: string;
+    /** Optional semantic tone override for this user's fallback. Numeric values map to the token set. */
+    tone?: StackedAvatarTone | number;
+}
+export interface StackedAvatarsProps {
+    users: StackedAvatarUser[];
+    max?: number;
+    /** Size preset. */
+    size?: StackedAvatarsSize;
+    className?: string;
+    /** Whether to render a `+N` count when `users.length > max`. Default `true`. */
+    showOverflow?: boolean;
+    /** Provide custom overflow text (e.g. "+12 more"). Default `+N`. */
+    overflowFormatter?: (overflow: number) => React.ReactNode;
+    /** Extra class names applied to each avatar root. */
+    avatarClassName?: string;
+}
+export declare function StackedAvatars({ users, max, size: sizeProp, className, showOverflow, overflowFormatter, avatarClassName, }: StackedAvatarsProps): React.JSX.Element;
+export declare namespace StackedAvatars {
+    var displayName: string;
+}

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

@@ -0,0 +1,22 @@
+import * as React from "react";
+import { type BadgeSize, type BadgeTone } from '../../../lib/ui-provider';
+export interface BadgeProps extends Omit<React.ComponentProps<'span'>, 'content'> {
+    /** Semantic tone. Falls back to `UIProvider.badge.defaultTone`, then `primary`. */
+    tone?: BadgeTone;
+    /** Display scale. Falls back to `UIProvider.density.defaultScale`. */
+    size?: BadgeSize;
+    /** Renders inline with surrounding text rather than as a standalone chip. */
+    inline?: boolean;
+    /** Shows a status dot before the label. */
+    dot?: boolean;
+    /** Animates the dot, for live or in-progress states. Requires `dot`. */
+    pulse?: boolean;
+    /** Draws the dot hollow, marking a state that has not started. Requires `dot`. */
+    pending?: boolean;
+    /** Swaps in a warning icon ahead of the label. */
+    important?: boolean;
+}
+/**
+ * Blocks Badge using shared Tailwind recipes and stable semantic BEM hooks.
+ */
+export declare const Badge: React.ForwardRefExoticComponent<Omit<BadgeProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;

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

@@ -0,0 +1,20 @@
+/** Private Tailwind recipes; public props and DOM hooks remain owned by the component. */
+export declare const badgeRecipes: {
+    readonly root: "inline-flex items-center justify-center shrink-0 self-center rounded-radius font-sans font-medium border border-transparent w-fit max-w-full whitespace-nowrap overflow-visible box-border align-middle";
+    readonly sizeSm: "h-auto min-h-0 py-space-2xs px-control-xs gap-space-xs text-xs leading-none";
+    readonly sizeMd: "h-auto min-h-0 py-space-2xs px-control-xs gap-space-xs text-xs leading-tight";
+    readonly sizeLg: "h-auto min-h-0 py-space-xs px-control-sm gap-space-sm text-sm leading-tight";
+    readonly isInline: "inline-flex align-baseline text-xs py-space-2xs px-control-xs leading-none";
+    readonly isPending: "[&_.badge-dot]:bg-transparent [&_.badge-dot]:border-[1.5px] [&_.badge-dot]:border-current";
+    readonly isPulse: "[&_.badge-dot]:animate-badge-pulse motion-reduce:[&_.badge-dot]:animate-none";
+    readonly dot: "badge-dot size-1.5 rounded-full shrink-0 bg-current";
+    readonly icon: "size-icon-sm shrink-0";
+    readonly label: "inline-flex min-w-0 max-w-full items-center gap-space-xs overflow-hidden text-ellipsis whitespace-nowrap";
+    readonly tonePrimary: "bg-primary text-primary-foreground border-primary";
+    readonly toneNeutral: "bg-foreground/8 text-foreground border-transparent";
+    readonly toneSecondary: "bg-foreground/8 text-foreground border-transparent";
+    readonly toneSuccess: "bg-success/20 text-success border-success/30";
+    readonly toneInfo: "bg-info/10 text-info border-info/30";
+    readonly toneWarning: "bg-warning/20 text-warning-accent border-warning/35";
+    readonly toneDestructive: "bg-destructive/10 text-destructive border-destructive/30";
+};

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

@@ -0,0 +1,2 @@
+export { Badge, type BadgeProps } from './badge';
+export type { BadgeTone } from '../../../lib/ui-provider';

package/dist/components/base/buttons/base-button.d.ts

@@ -0,0 +1,24 @@
+import { type AnchorHTMLAttributes, type ElementType, type ReactNode } from 'react';
+import { Button as PrimitiveButton } from '../../ui/button';
+import { type ButtonSize, type ButtonStyle, type ButtonTone } from '../../../lib/ui-provider';
+export type { ButtonSize, ButtonStyle, ButtonTone } from '../../../lib/ui-provider';
+export type IconPosition = 'left' | 'right';
+interface PresentationProps {
+    tone?: ButtonTone;
+    buttonStyle?: ButtonStyle;
+    size?: ButtonSize;
+    iconOnly?: boolean;
+    fullWidth?: boolean;
+    icon?: ElementType;
+    iconPosition?: IconPosition;
+    children?: ReactNode;
+}
+export interface BaseButtonProps extends Omit<PrimitiveButton.Props, 'children' | 'size' | 'variant'>, PresentationProps {
+}
+export interface BaseButtonLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'children' | 'href'>, PresentationProps {
+    href: string;
+    disabled?: boolean;
+}
+export declare const BaseButton: import("react").ForwardRefExoticComponent<Omit<BaseButtonProps, "ref"> & import("react").RefAttributes<HTMLElement>>;
+/** Navigation remains an anchor: Base UI's Button render API deliberately enforces button semantics. */
+export declare const BaseButtonLink: import("react").ForwardRefExoticComponent<BaseButtonLinkProps & import("react").RefAttributes<HTMLAnchorElement>>;

package/dist/components/base/buttons/button-group.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ButtonGroup — base wrapper around the shadcn `ui/button-group` primitive.
+ *
+ * What this layer adds on top of the primitive:
+ *  - Stable BEM hooks (`button-group--component`, `button-group-text--component`,
+ *    `button-group-separator--component`) on each wrapped part's outermost node.
+ *  - Design-system typography for the scalar copy inside `ButtonGroupText`,
+ *    while arbitrary `ReactNode` content (icons, `kbd`, nested controls) passes
+ *    through untouched so the compound pattern stays composable.
+ *  - Keeps the primitive's `orientation` variant, segmented-radius handling, and
+ *    every native `div` prop by spread.
+ *
+ * Compose it as `<ButtonGroup><Button/><ButtonGroupSeparator/><Button/></ButtonGroup>`.
+ * Reach for it when adjacent buttons must read as one segmented control; use
+ * `Stack` when the buttons are merely peers with a gap between them.
+ */
+import type { ComponentProps } from 'react';
+import { ButtonGroup as ButtonGroupPrimitive, ButtonGroupSeparator as ButtonGroupSeparatorPrimitive, ButtonGroupText as ButtonGroupTextPrimitive, buttonGroupVariants } from '../../ui/button-group';
+export type ButtonGroupProps = ComponentProps<typeof ButtonGroupPrimitive>;
+export type ButtonGroupTextProps = ComponentProps<typeof ButtonGroupTextPrimitive>;
+export type ButtonGroupSeparatorProps = ComponentProps<typeof ButtonGroupSeparatorPrimitive>;
+/** Segmented shell that joins adjacent buttons into a single control. */
+declare function ButtonGroup({ className, ...props }: ButtonGroupProps): import("react").JSX.Element;
+/** Non-interactive label segment — scalar copy renders through Typography. */
+declare function ButtonGroupText({ children, className, ...props }: ButtonGroupTextProps): import("react").JSX.Element;
+/** Hairline divider between two segments of the group. */
+declare function ButtonGroupSeparator({ className, ...props }: ButtonGroupSeparatorProps): import("react").JSX.Element;
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants };

package/dist/components/base/buttons/button-group.recipes.d.ts

@@ -0,0 +1,6 @@
+/** Private Tailwind recipes; public props and DOM hooks remain owned by the component. */
+export declare const buttonGroupRecipes: {
+    readonly root: "inline-flex items-stretch rounded-radius box-border data-[orientation=vertical]:flex-col [&[data-orientation=horizontal]>:not(:last-child)]:rounded-e-none [&[data-orientation=horizontal]>:not(:first-child)]:rounded-s-none [&[data-orientation=horizontal]>:not(:first-child)]:-ms-px [&[data-orientation=vertical]>:not(:last-child)]:rounded-b-none [&[data-orientation=vertical]>:not(:first-child)]:rounded-t-none [&[data-orientation=vertical]>:not(:first-child)]:-mt-px";
+    readonly text: "inline-flex items-center px-control-sm py-0 bg-muted border border-border text-sm text-muted-foreground";
+    readonly separator: "bg-border w-px self-stretch";
+};

package/dist/components/base/buttons/button.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Button — everyday action/link wrapper around the base button presentation.
+ *
+ * Action mode renders one native `<button>`. Supplying `href` switches to one
+ * native `<a>` with the same provider-driven variants, sizes, loading state,
+ * and optional tooltip. The link path deliberately does not use Base UI
+ * Button's non-native `render` mode because that mode adds button semantics to
+ * the replacement element; navigation keeps native link semantics instead.
+ */
+import * as React from 'react';
+import { type BaseButtonLinkProps, type BaseButtonProps } from './base-button';
+import { type LoaderButtonProps } from './loader-button';
+type ButtonEnhancementProps = Pick<LoaderButtonProps, 'loading' | 'handlesLoading' | 'strings'> & {
+    /** Tooltip copy shown on hover and focus. Supply it for icon-only buttons. */
+    withTooltip?: string;
+};
+type ButtonAnchorAttributes = Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'download' | 'hrefLang' | 'media' | 'ping' | 'referrerPolicy' | 'rel' | 'target'>;
+/** Shared all-mode props for generic wrappers that accept either action mode or link mode. */
+export type ButtonProps = BaseButtonProps & ButtonEnhancementProps & ButtonAnchorAttributes & {
+    /** Destination for the entry, when it navigates. */
+    href?: string;
+};
+/** Precise props for consumers that explicitly model a navigation button. */
+export type ButtonLinkProps = Omit<BaseButtonLinkProps, 'href' | 'type'> & ButtonEnhancementProps & {
+    /** Destination for the entry, when it navigates. */
+    href: string;
+};
+/** Precise props for consumers that explicitly model an action button. */
+export type ButtonActionProps = BaseButtonProps & ButtonEnhancementProps & {
+    /** Destination for the entry, when it navigates. */
+    href?: undefined;
+    download?: never;
+    hrefLang?: never;
+    media?: never;
+    ping?: never;
+    referrerPolicy?: never;
+    rel?: never;
+    target?: never;
+};
+type ButtonComponent = {
+    (props: ButtonLinkProps & React.RefAttributes<HTMLAnchorElement>): React.ReactElement | null;
+    (props: ButtonActionProps & React.RefAttributes<HTMLButtonElement>): React.ReactElement | null;
+    (props: ButtonProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>): React.ReactElement | null;
+    displayName?: string;
+};
+declare const Button: ButtonComponent;
+export { Button };

package/dist/components/base/buttons/button.recipes.d.ts

@@ -0,0 +1,23 @@
+/** Private Tailwind recipes; public props and DOM hooks remain owned by the component. */
+export declare const buttonRecipes: {
+    readonly root: "inline-flex items-center justify-center font-[inherit] font-medium leading-tight whitespace-nowrap no-underline select-none border border-transparent rounded-radius box-border align-middle outline-none cursor-pointer transition-[background-color,color,border-color,box-shadow] duration-150 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none aria-disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:pointer-events-none";
+    readonly isDisabled: "opacity-50 cursor-not-allowed pointer-events-none";
+    readonly sizeSm: "h-action-sm min-h-0 px-control-sm gap-space-sm text-sm [&_.base-button-icon]:size-icon-sm";
+    readonly sizeMd: "h-action min-h-0 px-control gap-space-md text-sm [&_.base-button-icon]:size-icon";
+    readonly sizeLg: "h-action-lg min-h-0 px-control gap-space-lg text-sm [&_.base-button-icon]:size-icon-lg";
+    readonly isIconOnly: "w-auto aspect-square p-0";
+    readonly isFullWidth: "w-full";
+    readonly isLoading: "cursor-wait";
+    readonly styleSolid: "";
+    readonly styleOutline: "";
+    readonly styleGhost: "";
+    readonly icon: "base-button-icon pointer-events-none shrink-0";
+    readonly spinner: "animate-spin me-space-md";
+    readonly toneNeutral: "data-[style=solid]:bg-foreground data-[style=solid]:text-background data-[style=solid]:[&:hover:not(:disabled):not([aria-disabled=true])]:brightness-95 data-[style=outline]:bg-transparent data-[style=outline]:border-border data-[style=outline]:text-foreground data-[style=outline]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-muted data-[style=ghost]:bg-transparent data-[style=ghost]:text-foreground data-[style=ghost]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-muted";
+    readonly tonePrimary: "data-[style=solid]:bg-primary data-[style=solid]:text-primary-foreground data-[style=solid]:[&:hover:not(:disabled):not([aria-disabled=true])]:brightness-95 data-[style=outline]:bg-transparent data-[style=outline]:border-primary data-[style=outline]:text-primary-accent data-[style=outline]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-primary/10 data-[style=ghost]:bg-transparent data-[style=ghost]:text-primary-accent data-[style=ghost]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-primary/10";
+    readonly toneSecondary: "data-[style=solid]:bg-secondary data-[style=solid]:text-secondary-foreground data-[style=solid]:[&:hover:not(:disabled):not([aria-disabled=true])]:brightness-95 data-[style=outline]:bg-transparent data-[style=outline]:border-border data-[style=outline]:text-foreground data-[style=outline]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-secondary data-[style=ghost]:bg-transparent data-[style=ghost]:text-foreground data-[style=ghost]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-secondary";
+    readonly toneDestructive: "data-[style=solid]:bg-destructive data-[style=solid]:text-destructive-foreground data-[style=solid]:[&:hover:not(:disabled):not([aria-disabled=true])]:brightness-95 data-[style=outline]:bg-transparent data-[style=outline]:border-destructive data-[style=outline]:text-destructive data-[style=outline]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-destructive/10 data-[style=ghost]:bg-transparent data-[style=ghost]:text-destructive data-[style=ghost]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-destructive/10";
+    readonly toneSuccess: "data-[style=solid]:bg-success data-[style=solid]:text-success-foreground data-[style=solid]:[&:hover:not(:disabled):not([aria-disabled=true])]:brightness-95 data-[style=outline]:bg-transparent data-[style=outline]:border-success data-[style=outline]:text-success data-[style=outline]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-success/10 data-[style=ghost]:bg-transparent data-[style=ghost]:text-success data-[style=ghost]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-success/10";
+    readonly toneWarning: "data-[style=solid]:bg-warning data-[style=solid]:text-warning-foreground data-[style=solid]:[&:hover:not(:disabled):not([aria-disabled=true])]:brightness-95 data-[style=outline]:bg-transparent data-[style=outline]:border-warning data-[style=outline]:text-warning-accent data-[style=outline]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-warning/10 data-[style=ghost]:bg-transparent data-[style=ghost]:text-warning-accent data-[style=ghost]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-warning/10";
+    readonly toneInfo: "data-[style=solid]:bg-info data-[style=solid]:text-info-foreground data-[style=solid]:[&:hover:not(:disabled):not([aria-disabled=true])]:brightness-95 data-[style=outline]:bg-transparent data-[style=outline]:border-info data-[style=outline]:text-info data-[style=outline]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-info/10 data-[style=ghost]:bg-transparent data-[style=ghost]:text-info data-[style=ghost]:[&:hover:not(:disabled):not([aria-disabled=true])]:bg-info/10";
+};

package/dist/components/base/buttons/button.variants.d.ts

@@ -0,0 +1,8 @@
+/** Shared geometry and semantic tone/treatment pairs; no extra component tokens. */
+export declare const buttonVariants: (props?: ({
+    tone?: "neutral" | "primary" | "secondary" | "info" | "success" | "warning" | "destructive" | null | undefined;
+    buttonStyle?: "outline" | "solid" | "ghost" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
+    iconOnly?: boolean | null | undefined;
+    fullWidth?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

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

@@ -0,0 +1,7 @@
+export type { ButtonTone, ButtonStyle, ButtonSize, IconPosition } from './base-button';
+export type { ButtonLoadingStrings } from './loader-button';
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, type ButtonGroupProps, type ButtonGroupSeparatorProps, type ButtonGroupTextProps, } from './button-group';
+export { Button, type ButtonActionProps, type ButtonLinkProps, type ButtonProps } from './button';
+export { TextButton, type TextButtonProps } from './text-button';
+export { BaseButton, BaseButtonLink } from './base-button';
+export type { BaseButtonProps, BaseButtonLinkProps } from './base-button';

package/dist/components/base/buttons/loader-button.d.ts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import { type BaseButtonProps, type ButtonSize } from './base-button';
+export interface ButtonLoadingStrings {
+    /** Shows the spinner and blocks activation. */
+    loading: string;
+    completed: string;
+}
+export declare const defaultButtonLoadingStrings: ButtonLoadingStrings;
+export interface LoaderButtonProps extends BaseButtonProps {
+    /** Shows the spinner and blocks activation. */
+    loading?: boolean;
+    /** Opts into the loading-capable button even before `loading` is true, so the first press does not swap component identity. */
+    handlesLoading?: boolean;
+    /** Overrides the loading announcement copy. */
+    strings?: StringsProp<ButtonLoadingStrings>;
+}
+interface UseLoaderButtonStateOptions {
+    /** Shows the spinner and blocks activation. */
+    loading?: boolean;
+    /** Opts into the loading-capable button even before `loading` is true, so the first press does not swap component identity. */
+    handlesLoading?: boolean;
+    /** Overrides the loading announcement copy. */
+    strings?: StringsProp<ButtonLoadingStrings>;
+}
+export declare function useLoaderButtonState({ loading, handlesLoading, strings: stringsProp, }: UseLoaderButtonStateOptions): {
+    isLoading: boolean;
+    strings: ButtonLoadingStrings;
+};
+interface LoaderButtonContentProps {
+    isLoading: boolean;
+    loadingText: string;
+    icon?: BaseButtonProps['icon'];
+    iconPosition?: BaseButtonProps['iconPosition'];
+    size?: ButtonSize;
+    children: React.ReactNode;
+}
+export declare function LoaderButtonContent({ isLoading, loadingText, icon: Icon, iconPosition, size: _size, children, }: LoaderButtonContentProps): React.JSX.Element;
+declare const LoaderButton: React.ForwardRefExoticComponent<Omit<LoaderButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export { LoaderButton };

package/dist/components/base/buttons/text-button.d.ts

@@ -0,0 +1,19 @@
+/**
+ * TextButton — link-styled button (underline, primary tint, no padding).
+ *
+ * Wraps `BaseButton` with `tone="primary" buttonStyle="ghost"`. Routine
+ * usage omits `size`; the shared component scale controls typography.
+ */
+import * as React from 'react';
+import { type ComponentScale } from '../../../lib/ui-provider';
+export type TextButtonSize = ComponentScale;
+export type TextButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'size'> & {
+    /** Size preset. */
+    size?: TextButtonSize;
+    children: React.ReactNode;
+};
+export declare const TextButton: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "size"> & {
+    /** Size preset. */
+    size?: TextButtonSize;
+    children: React.ReactNode;
+} & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/base/buttons/tooltip-button.d.ts

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { type BaseButtonProps } from './base-button';
+export interface TooltipButtonProps extends BaseButtonProps {
+    withTooltip: string;
+}
+declare const TooltipButton: React.ForwardRefExoticComponent<Omit<TooltipButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export { TooltipButton };