@instruments/materia-ui 0.1.0

package/dist/components/button/button-content.js

@@ -0,0 +1,70 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { springs } from "../../tokens/motion.js";
+import { hasText } from "../../utils/type-guards.js";
+import { Center } from "../center.js";
+import { Dot } from "../dot.js";
+import { Icon } from "../icon.js";
+import { Spinner } from "../spinner.js";
+import { EXPANDABLE_CLIP, EXPANDABLE_TRACK } from "./button-variants.js";
+/** Static icon (no animation overhead). */
+const renderStaticIcon = (iconProp, iconSize, extraClassName, containerClassName) => {
+    if (!iconProp) {
+        return null;
+    }
+    return (_jsx(Center, { as: "span", className: containerClassName, inline: true, children: _jsx(Icon, { className: extraClassName, icon: iconProp, size: iconSize }) }));
+};
+/** Animated icon wrapper for smooth vertical transitions. */
+const renderAnimatedIcon = (iconProp, iconKey, iconClassName, iconSize, containerClassName) => (_jsx(AnimatePresence, { initial: false, mode: "popLayout", children: iconProp ? (_jsx(m.span, { animate: { opacity: 1, y: 0 }, className: cn("inline-flex items-center justify-center", containerClassName), exit: { opacity: 0, y: "-100%" }, initial: { opacity: 0, y: "100%" }, transition: springs.swift, children: _jsx(Icon, { className: iconClassName, icon: iconProp, size: iconSize }) }, iconKey)) : null }));
+/** Animated spinner for loading state. */
+const AnimatedSpinner = ({ loading, spinnerSize, }) => (_jsx(AnimatePresence, { initial: false, mode: "popLayout", children: loading ? (_jsx(m.span, { animate: { filter: "blur(0px)", opacity: 1, scale: 1 }, className: "inline-flex items-center justify-center", exit: { filter: "blur(4px)", opacity: 0, scale: 0.5 }, initial: { filter: "blur(4px)", opacity: 0, scale: 0.5 }, transition: springs.swift, children: _jsx(Spinner, { size: spinnerSize }) }, "spinner")) : null }));
+/** Render the leading icon - animated only when it has changed or loading. */
+const renderLeadingIcon = (p) => {
+    if (!p.icon) {
+        return null;
+    }
+    if (p.iconChanged || p.loading) {
+        return renderAnimatedIcon(p.icon, p.iconKey, p.iconClassName, p.iconSize);
+    }
+    return renderStaticIcon(p.icon, p.iconSize, p.iconClassName);
+};
+/** Render the suffix icon - animated only when it has changed. */
+const renderTrailingIcon = (p) => {
+    if (!p.suffixIcon) {
+        return null;
+    }
+    if (p.suffixIconChanged) {
+        return renderAnimatedIcon(p.suffixIcon, p.suffixIconKey, p.suffixIconClassName, p.iconSize);
+    }
+    return renderStaticIcon(p.suffixIcon, p.iconSize, p.suffixIconClassName);
+};
+/**
+ * Compose the button's inner content across loading / icon variants.
+ */
+const renderButtonContent = (p) => {
+    const dotElement = hasText(p.dot) ? (_jsx(Dot, { color: p.dot, size: p.dotSize })) : null;
+    const startDot = p.dotPlacement === "start" ? dotElement : null;
+    const endDot = p.dotPlacement === "end" ? dotElement : null;
+    const leadingIcon = renderLeadingIcon(p);
+    const trailingIcon = renderTrailingIcon(p);
+    // Expandable: leading icon stays put; everything after it lives in the
+    // collapsing grid track so it reveals on hover/focus without shifting the
+    // icon. Loading swaps the spinner for the icon but keeps the same track, so an
+    // expanded button doesn't snap-collapse when it starts loading.
+    if (p.expandable) {
+        return (_jsxs(_Fragment, { children: [startDot, p.loading ? (_jsx(AnimatedSpinner, { loading: p.loading, spinnerSize: p.spinnerSize })) : (leadingIcon), _jsx("span", { className: cn(EXPANDABLE_TRACK, p.expandableCollapsedMargin), children: _jsxs("span", { className: EXPANDABLE_CLIP, children: [p.loading ? (p.loadingLabel ?? p.children) : p.children, trailingIcon, endDot] }) })] }));
+    }
+    if (p.loading) {
+        return (_jsxs(_Fragment, { children: [_jsx(AnimatedSpinner, { loading: p.loading, spinnerSize: p.spinnerSize }), p.isIconButton === true ? null : (p.loadingLabel ?? p.children)] }));
+    }
+    if (p.isIconButton === true) {
+        return p.icon ? (_jsxs(_Fragment, { children: [startDot, leadingIcon, endDot] })) : null;
+    }
+    if (!p.hasChildren) {
+        return p.children;
+    }
+    return (_jsxs(_Fragment, { children: [startDot, leadingIcon, p.children, trailingIcon, endDot] }));
+};
+export { renderButtonContent };

package/dist/components/button/button-helpers.d.ts

@@ -0,0 +1,16 @@
+import type { IconComponent } from "../../tokens/icon-component.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ButtonSize } from "./button-variants.js";
+type ButtonIcon = IconComponent | undefined;
+/** Stable key for an icon component (displayName or name), with fallback. */
+declare const getIconKey: (icon: ButtonIcon, fallback: string) => string;
+/** Map a size (static or responsive object) to its text twin for `expandable`,
+ * applied BEFORE size resolution so an `expandable` icon-* button still renders
+ * its label (isIconButton would otherwise drop it). */
+declare const normalizeExpandableSize: (size: ResponsiveValue<ButtonSize> | null | undefined) => ResponsiveValue<ButtonSize> | null | undefined;
+/** Dev-mode warnings for unsupported/ineffective `expandable` combinations. */
+declare const warnIfInvalidExpandable: (expandable: boolean | undefined, hasChildren: boolean, icon: ButtonIcon, square: boolean | null | undefined) => void;
+/** Dev-mode warning: icon-only buttons must have an accessible name. */
+declare const warnIfMissingAccessibleName: (isIconButton: boolean | ButtonIcon, props: Pick<React.ComponentProps<"button">, "aria-label" | "aria-labelledby">, icon: ButtonIcon) => void;
+export type { ButtonIcon };
+export { getIconKey, normalizeExpandableSize, warnIfInvalidExpandable, warnIfMissingAccessibleName, };

package/dist/components/button/button-helpers.js

@@ -0,0 +1,50 @@
+import { isResponsiveValue } from "../../tokens/responsive.js";
+import { isDevelopmentBrowser } from "../../utils/is-development-browser.js";
+import { hasText } from "../../utils/type-guards.js";
+import { getBaseSize, isIconSize } from "./button-variants.js";
+/** Stable key for an icon component (displayName or name), with fallback. */
+const getIconKey = (icon, fallback) => icon?.displayName ?? icon?.name ?? fallback;
+/** One size → its text twin (icon-sm → sm); text sizes pass through. */
+const toTextSize = (size) => isIconSize(size) ? getBaseSize(size) : size;
+/** Map a size (static or responsive object) to its text twin for `expandable`,
+ * applied BEFORE size resolution so an `expandable` icon-* button still renders
+ * its label (isIconButton would otherwise drop it). */
+const normalizeExpandableSize = (size) => {
+    if (size === null || size === undefined) {
+        return size;
+    }
+    if (!isResponsiveValue(size)) {
+        return toTextSize(size);
+    }
+    const mapped = {};
+    for (const [key, value] of Object.entries(size)) {
+        if (value !== undefined) {
+            mapped[key] = toTextSize(value);
+        }
+    }
+    return mapped;
+};
+/** Dev-mode warnings for unsupported/ineffective `expandable` combinations. */
+const warnIfInvalidExpandable = (expandable, hasChildren, icon, square) => {
+    if (!(isDevelopmentBrowser() && expandable === true)) {
+        return;
+    }
+    if (!icon || !hasChildren) {
+        console.warn("Button: `expandable` needs both an `icon` and children (the label to reveal).");
+    }
+    if (square === true) {
+        console.warn("Button: `expandable` is incompatible with `square`; ignoring `square`.");
+    }
+};
+/** Dev-mode warning: icon-only buttons must have an accessible name. */
+const warnIfMissingAccessibleName = (isIconButton, props, icon) => {
+    if (isDevelopmentBrowser() &&
+        isIconButton === true &&
+        !hasText(props["aria-label"]) &&
+        !hasText(props["aria-labelledby"])) {
+        console.warn("Button: Icon-only button is missing `aria-label` or `aria-labelledby`. " +
+            "Screen readers will announce this as an unlabelled button. " +
+            `Icon: ${icon?.displayName ?? icon?.name ?? "unknown"}`);
+    }
+};
+export { getIconKey, normalizeExpandableSize, warnIfInvalidExpandable, warnIfMissingAccessibleName, };

package/dist/components/button/button-root.d.ts

@@ -0,0 +1,27 @@
+import type { ButtonProps } from "./button-types.js";
+/**
+ * Button styled by a tone × emphasis grammar: `tone` sets the semantic colour
+ * (neutral / brand / danger) and `emphasis` sets the visual weight (solid / soft /
+ * outline / ghost / transparent / link). Any pairing is valid - there is no fixed
+ * "primary/secondary" list; those looks are expressed as tone × emphasis pairs.
+ *
+ * An icon-only button (an `icon-*` size, or `icon` with no children) requires an
+ * `aria-label`; a dev-only console warning fires when it is missing. With `render`,
+ * styling and icon/dot decorations are applied to the element you pass in.
+ *
+ * @bestPractice Express weight with `tone`×`emphasis`, not a `variant` prop - there is no "primary/secondary"; e.g. the destructive confirm is `tone="danger"`.
+ * @bestPractice Icon-only buttons MUST have an `aria-label` (a dev warning fires otherwise).
+ * @bestPractice Use `render` to render a link element (e.g. `render={<Link href="…" />}`) rather than nesting a button inside an anchor.
+ * @bestPractice `loading` keeps the button focusable while it blocks presses, so focus stays put across a submit; a plain `disabled` button leaves the tab order.
+ * @bestPractice Reach for `emphasis="ghost"`/`"link"` in toolbars/headers - they carry `data-edge-comp` so containers can pull them flush to the edge.
+ *
+ * @example
+ * <Button tone="brand">Save</Button>
+ * <Button tone="danger" emphasis="ghost">Delete</Button>
+ * <Button size="icon-sm" icon={X} aria-label="Close" />
+ * @category actions
+ */
+declare const Button: ({ className, pressed, tone, emphasis, asInput, radius, size, align, square, expandable, focused, hovered, render, ref, loading, loadingLabel, icon, iconClassName, suffixIcon, suffixIconClassName, dot, dotPlacement, disabled, children, testId, ...props }: ButtonProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type { ButtonProps } from "./button-types.js";
+export { BUTTON_EMPHASES, BUTTON_TONES, type ButtonEmphasis, type ButtonSize, type ButtonTone, buttonVariants, } from "./button-variants.js";
+export { Button };

package/dist/components/button/button-root.js

@@ -0,0 +1,102 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button as ButtonPrimitive } from "@base-ui/react/button";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { hasChildNodes } from "../../utils/has-child-nodes.js";
+import { renderButtonContent } from "./button-content.js";
+import { getIconKey, warnIfInvalidExpandable, warnIfMissingAccessibleName, } from "./button-helpers.js";
+import { getButtonStateAttributes, resolveButtonSizing } from "./button-sizing.js";
+import { buttonSizeToIconSize, buttonVariants, EXPANDABLE_COLLAPSED_MARGIN, getBaseSize, } from "./button-variants.js";
+import { useHasChanged } from "./use-has-changed.js";
+/**
+ * Button styled by a tone × emphasis grammar: `tone` sets the semantic colour
+ * (neutral / brand / danger) and `emphasis` sets the visual weight (solid / soft /
+ * outline / ghost / transparent / link). Any pairing is valid - there is no fixed
+ * "primary/secondary" list; those looks are expressed as tone × emphasis pairs.
+ *
+ * An icon-only button (an `icon-*` size, or `icon` with no children) requires an
+ * `aria-label`; a dev-only console warning fires when it is missing. With `render`,
+ * styling and icon/dot decorations are applied to the element you pass in.
+ *
+ * @bestPractice Express weight with `tone`×`emphasis`, not a `variant` prop - there is no "primary/secondary"; e.g. the destructive confirm is `tone="danger"`.
+ * @bestPractice Icon-only buttons MUST have an `aria-label` (a dev warning fires otherwise).
+ * @bestPractice Use `render` to render a link element (e.g. `render={<Link href="…" />}`) rather than nesting a button inside an anchor.
+ * @bestPractice `loading` keeps the button focusable while it blocks presses, so focus stays put across a submit; a plain `disabled` button leaves the tab order.
+ * @bestPractice Reach for `emphasis="ghost"`/`"link"` in toolbars/headers - they carry `data-edge-comp` so containers can pull them flush to the edge.
+ *
+ * @example
+ * <Button tone="brand">Save</Button>
+ * <Button tone="danger" emphasis="ghost">Delete</Button>
+ * <Button size="icon-sm" icon={X} aria-label="Close" />
+ * @category actions
+ */
+const Button = ({ className, pressed, tone, emphasis, asInput, radius, size, align, square, expandable = false, focused, hovered, render, ref, loading = false, loadingLabel, icon, iconClassName, suffixIcon, suffixIconClassName, dot, dotPlacement = "start", disabled, children, testId, ...props }) => {
+    const hasChildren = hasChildNodes(children);
+    warnIfInvalidExpandable(expandable, hasChildren, icon, square);
+    const { baseSize, isExpandable, isIconButton, responsiveSizeClasses } = resolveButtonSizing({ expandable, hasChildren, icon, loading, size });
+    warnIfMissingAccessibleName(isIconButton, props, icon);
+    const spinnerSize = getBaseSize(baseSize);
+    const iconSize = buttonSizeToIconSize(baseSize);
+    const dotSize = buttonSizeToIconSize(baseSize);
+    // Get stable keys for icons (use displayName or name)
+    const iconKey = getIconKey(icon, "no-icon");
+    const suffixIconKey = getIconKey(suffixIcon, "no-suffix-icon");
+    // Track whether each icon has ever changed - skip AnimatePresence for static icons
+    const hasIconChanged = useHasChanged(iconKey);
+    const hasSuffixIconChanged = useHasChanged(suffixIconKey);
+    return useRender({
+        defaultTagName: "button",
+        props: {
+            children: renderButtonContent({
+                children,
+                dot,
+                dotPlacement,
+                dotSize,
+                expandable: isExpandable,
+                expandableCollapsedMargin: EXPANDABLE_COLLAPSED_MARGIN[getBaseSize(baseSize)],
+                hasChildren,
+                icon,
+                iconChanged: hasIconChanged,
+                iconClassName,
+                iconKey,
+                iconSize,
+                isIconButton,
+                loading,
+                loadingLabel,
+                spinnerSize,
+                suffixIcon,
+                suffixIconChanged: hasSuffixIconChanged,
+                suffixIconClassName,
+                suffixIconKey,
+            }),
+            className: cn(buttonVariants({
+                align,
+                asInput,
+                emphasis,
+                pressed,
+                radius,
+                size: baseSize,
+                square: isExpandable ? false : square,
+                tone,
+            }), responsiveSizeClasses, 
+            // `group/expand` scopes the track's hover/focus-visible variants to this
+            // button only (nested cards each get their own expansion).
+            isExpandable && "group/expand", className),
+            "data-component": "button",
+            ...getButtonStateAttributes({ emphasis, focused, hovered, pressed }),
+            "data-slot": "button",
+            "data-testid": testId,
+            disabled: loading || disabled,
+            ...props,
+        },
+        ref,
+        // A native button goes through Base UI Button, which keeps a loading button
+        // focusable (`aria-disabled` + `data-disabled`) so keyboard focus survives
+        // the state change. Base UI Button forbids links, so `render` (a link, a
+        // router Link) stays on useRender alone.
+        render: render ?? _jsx(ButtonPrimitive, { focusableWhenDisabled: loading }),
+    });
+};
+export { BUTTON_EMPHASES, BUTTON_TONES, buttonVariants, } from "./button-variants.js";
+export { Button };

package/dist/components/button/button-sizing.d.ts

@@ -0,0 +1,40 @@
+import type { ButtonIcon } from "./button-helpers.js";
+import type { ButtonProps, ButtonSizeProp } from "./button-types.js";
+interface ButtonSizingInput {
+    expandable: boolean;
+    hasChildren: boolean;
+    icon: ButtonIcon;
+    loading: boolean;
+    size: ButtonSizeProp | undefined;
+}
+/**
+ * Resolve the effective size, responsive overrides, and icon-only / expandable
+ * flags. Expandable is only honoured with an icon + label; when active it
+ * renders as a normal text button (collapsed geometry = the icon twin, expanded
+ * = the full text button) so its icon-* sizes resolve to their text twins
+ * before the size / icon-only computation.
+ */
+declare const resolveButtonSizing: ({ expandable, hasChildren, icon, loading, size, }: ButtonSizingInput) => {
+    baseSize: "2xl" | "2xs" | "3xl" | "base" | "icon-2xl" | "icon-2xs" | "icon-3xl" | "icon-base" | "icon-lg" | "icon-sm" | "icon-xl" | "icon-xs" | "lg" | "sm" | "xl" | "xs";
+    isExpandable: boolean;
+    isIconButton: boolean | undefined;
+    responsiveSizeClasses: string;
+};
+/**
+ * Data attributes mirroring the visual state. Ghost/link buttons have
+ * transparent padding, so a container can pull the first/last one flush to its
+ * edge via `:has()` (see edge-compensation utilities). The button only declares
+ * eligibility; the container adjusts.
+ */
+declare const getButtonStateAttributes: ({ emphasis, focused, hovered, pressed, }: {
+    emphasis: ButtonProps["emphasis"];
+    focused: boolean | undefined;
+    hovered: boolean | undefined;
+    pressed: boolean | null | undefined;
+}) => {
+    "data-edge-comp": boolean | undefined;
+    "data-focused": boolean | undefined;
+    "data-hovered": boolean | undefined;
+    "data-pressed": boolean | undefined;
+};
+export { getButtonStateAttributes, resolveButtonSizing };

package/dist/components/button/button-sizing.js

@@ -0,0 +1,44 @@
+import { getResponsiveSizeOverrides, resolveResponsiveBase, } from "../../tokens/responsive.js";
+import { normalizeExpandableSize } from "./button-helpers.js";
+import { BUTTON_SIZE_CLASSES, DEFAULT_BUTTON_SIZE, isIconSize, } from "./button-variants.js";
+// Arbitrary/named container-query size overrides - fully-prefixed literals so
+// Tailwind's scanner emits them (they can't be safelisted). Passed to
+// getResponsiveSizeOverrides as `literalOverrides`, keyed "<key>:<sizeValue>".
+const BUTTON_ARBITRARY_VARIANT_SIZE_CLASSES = {
+    "@[240px]/product-card:icon-lg": "@[240px]/product-card:h-10 @[240px]/product-card:shrink-0 @[240px]/product-card:px-4 @[240px]/product-card:py-2.5",
+    "@[240px]/product-card:icon-sm": "@[240px]/product-card:h-8 @[240px]/product-card:shrink-0 @[240px]/product-card:px-3 @[240px]/product-card:py-2",
+    // Text size for `expandable` tool buttons (icon-sm normalises to sm at this
+    // container query); carries the gap + text the icon size omits.
+    "@[240px]/product-card:sm": "@[240px]/product-card:h-8 @[240px]/product-card:gap-1.5 @[240px]/product-card:px-3 @[240px]/product-card:text-sm",
+};
+/**
+ * Resolve the effective size, responsive overrides, and icon-only / expandable
+ * flags. Expandable is only honoured with an icon + label; when active it
+ * renders as a normal text button (collapsed geometry = the icon twin, expanded
+ * = the full text button) so its icon-* sizes resolve to their text twins
+ * before the size / icon-only computation.
+ */
+const resolveButtonSizing = ({ expandable, hasChildren, icon, loading, size, }) => {
+    const isExpandable = expandable && Boolean(icon) && hasChildren;
+    const resolvedSize = isExpandable ? normalizeExpandableSize(size) : size;
+    const baseSize = resolveResponsiveBase(resolvedSize ?? undefined, DEFAULT_BUTTON_SIZE);
+    const responsiveSizeClasses = getResponsiveSizeOverrides(resolvedSize ?? undefined, BUTTON_SIZE_CLASSES, BUTTON_ARBITRARY_VARIANT_SIZE_CLASSES);
+    // Icon-only: an icon size, or an icon without children. Expandable buttons
+    // always carry a label, so they are never icon-only.
+    const isIconButton = !isExpandable &&
+        (isIconSize(baseSize) || (icon && !hasChildren && !loading));
+    return { baseSize, isExpandable, isIconButton, responsiveSizeClasses };
+};
+/**
+ * Data attributes mirroring the visual state. Ghost/link buttons have
+ * transparent padding, so a container can pull the first/last one flush to its
+ * edge via `:has()` (see edge-compensation utilities). The button only declares
+ * eligibility; the container adjusts.
+ */
+const getButtonStateAttributes = ({ emphasis, focused, hovered, pressed, }) => ({
+    "data-edge-comp": emphasis === "ghost" || emphasis === "link" ? true : undefined,
+    "data-focused": focused === true ? true : undefined,
+    "data-hovered": hovered === true ? true : undefined,
+    "data-pressed": pressed === true ? true : undefined,
+});
+export { getButtonStateAttributes, resolveButtonSizing };

package/dist/components/button/button-types.d.ts

@@ -0,0 +1,58 @@
+import type { useRender } from "@base-ui/react/use-render";
+import type { VariantProps } from "class-variance-authority";
+import type { IconComponent } from "../../tokens/icon-component.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { WithTestId } from "../../utils/with-test-id.js";
+import type { ButtonSize, buttonVariants } from "./button-variants.js";
+type ButtonSizeProp = ResponsiveValue<ButtonSize> | null;
+type ButtonVariantProps = Omit<VariantProps<typeof buttonVariants>, "className" | "size"> & {
+    /**
+     * Size token; `icon-*` variants produce a square icon-only button. Also
+     * accepts a responsive object keyed by viewport breakpoints and/or `@`-prefixed
+     * container queries - e.g. `{ base: "sm", md: "base", "@sm": "lg" }`.
+     * @default "base"
+     */
+    size?: ButtonSizeProp;
+};
+/** Props for {@link Button}; extends the native `<button>` props. */
+type ButtonProps = WithTestId<React.ComponentProps<"button"> & ButtonVariantProps & {
+    /**
+     * Replace the rendered `<button>` with another element or component
+     * (e.g. `<Link href="…" />`); styling, decorations and props are applied to it.
+     */
+    render?: useRender.RenderProp | undefined;
+    /**
+     * Show a spinner and block presses. The button stays focusable (it is
+     * `aria-disabled`, not natively disabled) so keyboard focus is kept.
+     * @default false
+     */
+    loading?: boolean | undefined;
+    /** Label shown in place of `children` while `loading`. */
+    loadingLabel?: string | undefined;
+    /** Leading icon (Lucide or SVG component); with no children it becomes an icon-only button. */
+    icon?: IconComponent | undefined;
+    /** Extra classes for the leading icon. */
+    iconClassName?: string | undefined;
+    /** Trailing icon (Lucide or SVG component) rendered at the end. */
+    suffixIcon?: IconComponent | undefined;
+    /** Extra classes for the trailing icon. */
+    suffixIconClassName?: string | undefined;
+    /** CSS colour for a status dot; empty/undefined renders no dot. */
+    dot?: string | undefined;
+    /** Dot position relative to content. @default "start" */
+    dotPlacement?: "start" | "end" | undefined;
+    /**
+     * Icon-only at rest; expands on hover/focus-visible to reveal the label
+     * to the right of the icon. Collapsed geometry equals the matching icon-*
+     * size, expanded equals the text button of that size - so pass a text
+     * size (`sm`/`base`/`lg`) OR its icon twin (`icon-sm` …); both resolve
+     * identically. Requires both `icon` and children; ignored with `square`. The label stays in the DOM in both states (stable
+     * accessible name). @default false
+     */
+    expandable?: boolean | undefined;
+    /** Force the focus ring on - for documentation/testing only. */
+    focused?: boolean | undefined;
+    /** Force the hover state on - for documentation/testing only. */
+    hovered?: boolean | undefined;
+}>;
+export type { ButtonProps, ButtonSizeProp };

package/dist/components/button/button-types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/button/button-variants.d.ts

@@ -0,0 +1,64 @@
+import type { Emphasis } from "../../tokens/emphasis.js";
+import type { ComponentSize } from "../../tokens/size.js";
+import type { Tone } from "../../tokens/tone.js";
+/** All button sizes */
+declare const BUTTON_SIZES: readonly ["2xs", "xs", "sm", "base", "lg", "xl", "2xl", "3xl", ...("icon-2xl" | "icon-2xs" | "icon-3xl" | "icon-base" | "icon-lg" | "icon-sm" | "icon-xl" | "icon-xs")[]];
+/** Button size type */
+type ButtonSize = (typeof BUTTON_SIZES)[number];
+/** Tailwind classes for each button size. Exported so Button can compose responsive size props. */
+declare const BUTTON_SIZE_CLASSES: Record<ButtonSize, string>;
+/** Default Button size (matches `defaultVariants.size`). Exported so composed
+ * controls can resolve the responsive base against the same fallback. */
+declare const DEFAULT_BUTTON_SIZE: ButtonSize;
+/** Label track: collapsed (0fr) → expanded (1fr) on hover / focus-visible, plus
+ * the forced `data-[hovered|focused]` states so stories/VR can render expanded. */
+declare const EXPANDABLE_TRACK: string;
+/** Clip inside the track so `0fr` truly collapses to zero width. */
+declare const EXPANDABLE_CLIP = "min-w-0 overflow-hidden whitespace-nowrap";
+/** Negative left-margin that cancels each size's flex `gap` while collapsed,
+ * keyed by the (normalised, text) size. MUST mirror the `gap-*` in
+ * BUTTON_SIZE_CLASSES - button-root.test guards the two against drift. */
+declare const EXPANDABLE_COLLAPSED_MARGIN: Record<ComponentSize, string>;
+/** Check if a size is an icon size */
+declare const isIconSize: (size: ButtonSize) => size is `icon-${ComponentSize}`;
+/** Extract base size from an icon size */
+declare const getBaseSize: (size: ButtonSize) => ComponentSize;
+/**
+ * buttonVariants - CVA helper for Button styling.
+ *
+ * Public axes are `tone` (semantic colour) and `emphasis` (visual weight),
+ * plus the `asInput` boolean input-chip state. `tone="neutral"` absorbs the
+ * former default/secondary/outline/ghost/link variants:
+ *   - neutral + solid       → the dark primary button (old `default`)
+ *   - neutral + soft        → the grey button (old `secondary`)
+ *   - neutral + outline     → the bordered button (old `outline` variant)
+ *   - neutral + ghost       → the transparent button (old `ghost` variant)
+ *   - neutral + link        → the inline link button (old `link` variant)
+ *   - neutral + transparent → the blurred translucent button
+ */
+declare const buttonVariants: (props?: ({
+    tone?: "brand" | "danger" | "neutral" | null | undefined;
+    emphasis?: "ghost" | "link" | "outline" | "soft" | "solid" | "transparent" | null | undefined;
+    asInput?: boolean | null | undefined;
+    radius?: "full" | "rounded" | "square" | null | undefined;
+    size?: "2xl" | "2xs" | "3xl" | "base" | "icon-2xl" | "icon-2xs" | "icon-3xl" | "icon-base" | "icon-lg" | "icon-sm" | "icon-xl" | "icon-xs" | "lg" | "sm" | "xl" | "xs" | null | undefined;
+    align?: "center" | "end" | "start" | null | undefined;
+    pressed?: boolean | null | undefined;
+    square?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare const buttonSizeToIconSize: (key?: ButtonSize | undefined) => ComponentSize;
+/**
+ * Button tone type (semantic colour) - the canon subset Button styles, kept in
+ * lockstep with the cva by `satisfies Record<Extract<Tone, …>, string>` above.
+ */
+type ButtonTone = Extract<Tone, "brand" | "danger" | "neutral">;
+/**
+ * Button emphasis type (visual weight) - the full {@link Emphasis} vocabulary
+ * plus Button's `link` extension; lockstep-guarded by the cva `satisfies` above.
+ */
+type ButtonEmphasis = Emphasis | "link";
+/** All button tones */
+declare const BUTTON_TONES: readonly ["neutral", "brand", "danger"];
+/** All button emphases */
+declare const BUTTON_EMPHASES: readonly ["solid", "soft", "outline", "ghost", "transparent", "link"];
+export { BUTTON_EMPHASES, BUTTON_SIZE_CLASSES, BUTTON_TONES, type ButtonEmphasis, type ButtonSize, type ButtonTone, buttonSizeToIconSize, buttonVariants, DEFAULT_BUTTON_SIZE, EXPANDABLE_CLIP, EXPANDABLE_COLLAPSED_MARGIN, EXPANDABLE_TRACK, getBaseSize, isIconSize, };