@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,350 @@
+import { cva } from "class-variance-authority";
+import { focusRing } from "../../tokens/focus-ring.js";
+import { RADIUS_CLASSES } from "../../tokens/radius.js";
+import { COMPONENT_SIZES } from "../../tokens/size.js";
+/** Standard button sizes derived from component size scale */
+const BUTTON_STANDARD_SIZES = COMPONENT_SIZES;
+/** Icon button sizes - prefixed versions of standard sizes */
+const BUTTON_ICON_SIZES = COMPONENT_SIZES.map((s) => `icon-${s}`);
+/** All button sizes */
+const BUTTON_SIZES = [...BUTTON_STANDARD_SIZES, ...BUTTON_ICON_SIZES];
+/** Tailwind classes for each button size. Exported so Button can compose responsive size props. */
+// Heights are the canonical CONTROL_HEIGHT_CLASSES ladder (Button is the
+// reference; control-height-alignment.test.tsx guards that Input/Select/etc.
+// stay in lockstep). text steps up to text-paragraph at xl+ (Figma scales it too)
+// so the larger sizes read distinctly. 2xs/xs and 2xl are Materia extras.
+const BUTTON_SIZE_CLASSES = {
+    "2xl": "h-14 gap-2.5 px-6 text-paragraph",
+    "2xs": "h-6 gap-1 px-2 text-caption",
+    "3xl": "h-16 gap-3 px-7 text-paragraph",
+    base: "h-9 gap-2 px-3.5 text-paragraph-sm",
+    "icon-2xl": "h-14 shrink-0 px-5 py-3.5",
+    "icon-2xs": "h-6 shrink-0 px-2 py-1",
+    "icon-3xl": "h-16 shrink-0 px-6 py-4",
+    "icon-base": "h-9 shrink-0 px-3.5 py-2",
+    "icon-lg": "h-10 shrink-0 px-4 py-2.5",
+    "icon-sm": "h-8 shrink-0 px-3 py-2",
+    "icon-xl": "h-12 shrink-0 px-4 py-3",
+    "icon-xs": "h-7 shrink-0 px-2.5 py-1.5",
+    lg: "h-10 gap-2 px-4 text-paragraph-sm",
+    sm: "h-8 gap-1.5 px-3 text-paragraph-sm",
+    xl: "h-12 gap-2 px-5 text-paragraph",
+    xs: "h-7 gap-1.5 px-2.5 text-caption",
+};
+/** Default Button size (matches `defaultVariants.size`). Exported so composed
+ * controls can resolve the responsive base against the same fallback. */
+const DEFAULT_BUTTON_SIZE = "base";
+/* ── Expandable (icon → label on hover) fragments ────────────────────────
+ * `expandable` turns an icon button into one that reveals its label on
+ * hover/focus-visible, sharing the geometry of the text button at the same
+ * size. The label lives in a CSS-grid track that interpolates 0fr→1fr (no JS,
+ * no measurement); the button keeps its size's own flex `gap`, and the track's
+ * negative left-margin cancels that gap while collapsed so the icon stays
+ * centred. All animated properties sit on the ONE track element (grid columns +
+ * margin) so they share a single transition and never fight the root's
+ * `transition duration-quick`. Literal strings so Tailwind's scanner sees the
+ * `group/expand` variants. */
+/** Label track: collapsed (0fr) → expanded (1fr) on hover / focus-visible, plus
+ * the forced `data-[hovered|focused]` states so stories/VR can render expanded. */
+const EXPANDABLE_TRACK = [
+    "duration-normal grid grid-cols-[0fr] transition-[grid-template-columns,margin-left] ease-in-out motion-reduce:transition-none",
+    "group-hover/expand:ml-0 group-hover/expand:grid-cols-[1fr]",
+    "group-focus-visible/expand:ml-0 group-focus-visible/expand:grid-cols-[1fr]",
+    "group-data-[hovered=true]/expand:ml-0 group-data-[hovered=true]/expand:grid-cols-[1fr]",
+    "group-data-[focused=true]/expand:ml-0 group-data-[focused=true]/expand:grid-cols-[1fr]",
+].join(" ");
+/** Clip inside the track so `0fr` truly collapses to zero width. */
+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. */
+const EXPANDABLE_COLLAPSED_MARGIN = {
+    "2xs": "-ml-1",
+    xs: "-ml-1.5",
+    sm: "-ml-1.5",
+    base: "-ml-2",
+    lg: "-ml-2",
+    xl: "-ml-2",
+    "2xl": "-ml-2.5",
+    "3xl": "-ml-3",
+};
+/** Check if a size is an icon size */
+const isIconSize = (size) => size.startsWith("icon-");
+const ICON_SIZE_TO_BASE_SIZE = {
+    "icon-2xl": "2xl",
+    "icon-2xs": "2xs",
+    "icon-3xl": "3xl",
+    "icon-base": "base",
+    "icon-lg": "lg",
+    "icon-sm": "sm",
+    "icon-xl": "xl",
+    "icon-xs": "xs",
+};
+/** Extract base size from an icon size */
+const getBaseSize = (size) => isIconSize(size) ? ICON_SIZE_TO_BASE_SIZE[size] : size;
+/**
+ * Shared class fragments. These are the exact strings the previous
+ * variant/appearance grammar emitted, kept verbatim so the tone/emphasis
+ * rename stays pixel-identical after cn()/tailwind-merge.
+ */
+/** The raised gradient "solid" surface (was `appearance="solid"`). */
+const SOLID_SURFACE = [
+    "relative overflow-hidden",
+    "shadow-[0_1px_2px_rgba(0,0,0,0.05),inset_0_1px_0_var(--color-alpha-20)]",
+    "before:pointer-events-none before:absolute before:inset-0 before:z-[-1] before:rounded-inherit",
+    "before:bg-[linear-gradient(180deg,var(--color-alpha-20)_0%,var(--color-alpha-5)_100%)]",
+    "before:transition-[background] before:duration-quick",
+    "active:shadow-none active:before:bg-none disabled:shadow-none disabled:before:bg-none data-disabled:shadow-none data-disabled:before:bg-none",
+    "data-[pressed=true]:shadow-none data-[pressed=true]:before:bg-none",
+].join(" ");
+/** Drop-shadow + pressed-state reset shared by every solid-surface tone. */
+const SOLID_SHADOW = "shadow-xs active:scale-100 active:shadow-none disabled:shadow-none data-disabled:shadow-none data-[pressed=true]:scale-100 data-[pressed=true]:shadow-none";
+/** Kills the solid surface for outline/ghost/link renders. */
+const FLAT = "shadow-none before:hidden";
+/* ── Neutral-tone colour identities (were dedicated `variant`s) ───────── */
+const NEUTRAL_SOLID = "border-primary bg-primary text-primary-foreground hover:bg-primary/90 data-[hovered=true]:bg-primary/90";
+// Semantic tokens (not fixed gray-*) so the surface, border, and text all flip
+// together in dark mode. In light these resolve to gray-200/gray-100/gray-900 -
+// identical to the previous fixed classes, so light VR baselines are unchanged.
+const NEUTRAL_SOFT = "border-border bg-secondary text-secondary-foreground";
+// The resting top sheen is a solid-white gradient stop, which reads as a bright
+// band over the dark surface; the `dark:` override swaps it for a subtle
+// white-alpha highlight. Light is untouched. (The hover/active gradients use
+// alpha vars that already lighten correctly in both themes.)
+const NEUTRAL_SOFT_GRADIENT = "before:bg-sheen-bright hover:before:bg-sheen-hover active:before:bg-none disabled:before:bg-none data-disabled:before:bg-none data-[hovered=true]:before:bg-sheen-hover data-[pressed=true]:before:bg-none dark:before:bg-sheen-dark";
+const NEUTRAL_OUTLINE = "border-border bg-background text-foreground hover:bg-muted hover:text-accent-foreground data-[hovered=true]:bg-muted data-[hovered=true]:text-accent-foreground";
+const NEUTRAL_GHOST = "border-transparent bg-transparent text-foreground shadow-none hover:bg-muted hover:text-accent-foreground data-[hovered=true]:bg-muted data-[hovered=true]:text-accent-foreground";
+const NEUTRAL_LINK = "border-transparent bg-transparent text-foreground underline-offset-4 shadow-none hover:underline data-[hovered=true]:underline";
+const NEUTRAL_LINK_FLAT = "shadow-none before:hidden active:scale-100 active:underline-offset-5 data-[pressed=true]:scale-100 data-[pressed=true]:underline-offset-5";
+const NEUTRAL_TRANSPARENT = "transform-gpu border-transparent bg-primary/50 backdrop-blur-md will-change-[filter,background-color] hover:bg-primary/60 data-[hovered=true]:bg-primary/60";
+/* ── Danger tone (was `variant="destructive"`) modifiers ────────────── */
+const DANGER_OUTLINE = "border-destructive text-destructive hover:bg-destructive/5 data-[hovered=true]:bg-destructive/5";
+const DANGER_GHOST = "text-destructive hover:bg-destructive/10 hover:text-destructive data-[hovered=true]:bg-destructive/10 data-[hovered=true]:text-destructive";
+const DANGER_TRANSPARENT = "transform-gpu border-transparent bg-destructive/50 backdrop-blur-md will-change-[filter,background-color] hover:bg-destructive/60 data-[hovered=true]:bg-destructive/60";
+/* ── Brand tone (was `variant="brand"`) modifiers ───────────────────── */
+const BRAND_SOLID_GRADIENT = "shadow-button-sheen before:bg-sheen-strong hover:before:bg-sheen-hover active:shadow-none active:before:bg-none disabled:shadow-none disabled:before:bg-none data-disabled:shadow-none data-disabled:before:bg-none data-[hovered=true]:before:bg-sheen-hover data-[pressed=true]:shadow-none data-[pressed=true]:before:bg-none";
+const BRAND_OUTLINE = "border-brand text-brand hover:bg-brand/5 data-[hovered=true]:bg-brand/5";
+const BRAND_GHOST = "text-brand hover:bg-brand/10 hover:text-brand data-[hovered=true]:bg-brand/10 data-[hovered=true]:text-brand";
+const BRAND_TRANSPARENT = "transform-gpu border-transparent bg-brand/50 backdrop-blur-md will-change-[filter,background-color] hover:bg-brand/60 data-[hovered=true]:bg-brand/60";
+/**
+ * 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
+ */
+const buttonVariants = cva([
+    "duration-quick text-paragraph-sm isolate inline-flex shrink-0 cursor-pointer items-center gap-2 border font-medium whitespace-nowrap transition ease-out",
+    "disabled:pointer-events-none disabled:border-transparent disabled:opacity-50",
+    // Twins for a loading button, which stays focusable and so carries
+    // `data-disabled` instead of the native attribute.
+    "data-disabled:pointer-events-none data-disabled:border-transparent data-disabled:opacity-50",
+    "aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40",
+    "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5",
+    // Focus ring (native + data-focused)
+    ...focusRing(),
+    // Pressed state (native + data-pressed)
+    "data-[pressed=true]:scale-[0.97]",
+], {
+    compoundVariants: [
+        // Square icon buttons - aspect-square ensures width = height
+        { class: "aspect-square px-0", size: "icon-2xs", square: true },
+        { class: "aspect-square px-0", size: "icon-xs", square: true },
+        { class: "aspect-square px-0", size: "icon-sm", square: true },
+        { class: "aspect-square px-0", size: "icon-base", square: true },
+        { class: "aspect-square px-0", size: "icon-lg", square: true },
+        { class: "aspect-square px-0", size: "icon-xl", square: true },
+        { class: "aspect-square px-0", size: "icon-2xl", square: true },
+        { class: "aspect-square px-0", size: "icon-3xl", square: true },
+        // Solid surface applies to any solid button that is not an input chip.
+        { asInput: false, class: SOLID_SURFACE, emphasis: "solid" },
+        /* ── Neutral tone ─────────────────────────────────────── */
+        {
+            asInput: false,
+            class: `${NEUTRAL_SOLID} ${SOLID_SHADOW}`,
+            emphasis: "solid",
+            tone: "neutral",
+        },
+        {
+            asInput: false,
+            class: `${NEUTRAL_SOFT} ${SOLID_SURFACE} ${SOLID_SHADOW} ${NEUTRAL_SOFT_GRADIENT}`,
+            emphasis: "soft",
+            tone: "neutral",
+        },
+        {
+            asInput: false,
+            class: `${NEUTRAL_OUTLINE} ${SOLID_SURFACE} ${FLAT}`,
+            emphasis: "outline",
+            tone: "neutral",
+        },
+        {
+            asInput: false,
+            class: `${NEUTRAL_GHOST} ${SOLID_SURFACE} ${FLAT}`,
+            emphasis: "ghost",
+            tone: "neutral",
+        },
+        {
+            asInput: false,
+            class: `${NEUTRAL_LINK} ${SOLID_SURFACE} ${NEUTRAL_LINK_FLAT}`,
+            emphasis: "link",
+            tone: "neutral",
+        },
+        {
+            asInput: false,
+            class: `${NEUTRAL_SOLID} ${SOLID_SHADOW} ${NEUTRAL_TRANSPARENT}`,
+            emphasis: "transparent",
+            tone: "neutral",
+        },
+        /* ── Danger tone (base colours from variants.tone) ────── */
+        {
+            asInput: false,
+            class: SOLID_SHADOW,
+            emphasis: "solid",
+            tone: "danger",
+        },
+        {
+            asInput: false,
+            class: `${SOLID_SHADOW} ${DANGER_OUTLINE}`,
+            emphasis: "outline",
+            tone: "danger",
+        },
+        {
+            asInput: false,
+            class: `${SOLID_SHADOW} ${DANGER_GHOST} ${FLAT}`,
+            emphasis: "ghost",
+            tone: "danger",
+        },
+        {
+            asInput: false,
+            class: `${SOLID_SHADOW} ${DANGER_TRANSPARENT}`,
+            emphasis: "transparent",
+            tone: "danger",
+        },
+        /* ── Brand tone (base colours from variants.tone) ─────── */
+        {
+            asInput: false,
+            class: `${SOLID_SHADOW} ${BRAND_SOLID_GRADIENT}`,
+            emphasis: "solid",
+            tone: "brand",
+        },
+        {
+            asInput: false,
+            class: `${SOLID_SHADOW} ${BRAND_OUTLINE}`,
+            emphasis: "outline",
+            tone: "brand",
+        },
+        {
+            asInput: false,
+            class: `${SOLID_SHADOW} ${BRAND_GHOST} ${FLAT}`,
+            emphasis: "ghost",
+            tone: "brand",
+        },
+        {
+            asInput: false,
+            class: `${SOLID_SHADOW} ${BRAND_TRANSPARENT}`,
+            emphasis: "transparent",
+            tone: "brand",
+        },
+        // Input chips carry the solid drop-shadow (was `variant="default"`).
+        // asInput replaces every tone/emphasis surface (gated `asInput: false`).
+        { asInput: true, class: SOLID_SHADOW },
+        // Smaller border radius for smallest sizes
+        {
+            class: "rounded-sm",
+            radius: "rounded",
+            size: ["2xs", "xs", "icon-2xs", "icon-xs"],
+        },
+    ],
+    defaultVariants: {
+        align: "center",
+        asInput: false,
+        emphasis: "solid",
+        pressed: true,
+        radius: "full",
+        size: "base",
+        square: false,
+        tone: "neutral",
+    },
+    // CVA emits variant classes in KEY ORDER and tailwind-merge keeps the last
+    // conflicting class. `tone` and `emphasis` both set `bg-*`, so `tone`
+    // MUST come before `emphasis`, and `asInput` last so the input surface
+    // wins. Do not alphabetize - sort-keys is disabled here.
+    /* oxlint-disable sort-keys */
+    variants: {
+        // Lockstep: Button subsets the canon - tone is Extract<Tone, neutral|
+        // brand|danger>, emphasis is the full Emphasis plus Button's `link`
+        // extension. The `satisfies Record<…>` fails to compile if these keys
+        // drift from ButtonTone/ButtonEmphasis (declared below).
+        tone: {
+            neutral: "",
+            brand: "border-brand-accent/40 bg-brand text-brand-foreground focus-visible:ring-brand/25 data-[focused=true]:ring-brand/25",
+            danger: "border-destructive bg-destructive text-destructive-foreground hover:bg-destructive/90 data-[hovered=true]:bg-destructive/90 focus-visible:ring-red-400/50 data-[focused=true]:ring-red-400/50",
+        },
+        emphasis: {
+            solid: "",
+            soft: "",
+            outline: "border bg-transparent before:hidden",
+            ghost: "hover:bg-foreground-wash data-[hovered=true]:bg-foreground-wash border-transparent bg-transparent shadow-none before:hidden",
+            transparent: "transform-gpu backdrop-blur-md will-change-[filter,background-color] before:hidden",
+            link: "",
+        },
+        asInput: {
+            true: "border-border bg-input text-foreground hover:bg-input/90 data-[hovered=true]:bg-input/90 before:hidden",
+            false: "",
+        },
+        radius: RADIUS_CLASSES,
+        size: BUTTON_SIZE_CLASSES,
+        align: {
+            center: "justify-center",
+            start: "justify-start",
+            end: "justify-end",
+        },
+        pressed: {
+            true: "active:scale-[0.97]",
+            false: "",
+        },
+        square: {
+            true: "",
+            false: "",
+        },
+    },
+    /* oxlint-enable sort-keys */
+});
+// Map button sizes to icon sizes (icons one step smaller than button)
+const BUTTON_SIZE_TO_ICON_SIZE_MAP = {
+    "2xl": "xs",
+    "2xs": "2xs",
+    "3xl": "xs",
+    base: "xs",
+    "icon-2xl": "xs",
+    "icon-2xs": "2xs",
+    "icon-3xl": "xs",
+    "icon-base": "xs",
+    "icon-lg": "xs",
+    "icon-sm": "xs",
+    "icon-xl": "xs",
+    "icon-xs": "2xs",
+    lg: "xs",
+    sm: "xs",
+    xl: "xs",
+    xs: "2xs",
+};
+const buttonSizeToIconSize = (key = "base") => BUTTON_SIZE_TO_ICON_SIZE_MAP[key] ?? "sm";
+/** All button tones */
+const BUTTON_TONES = ["neutral", "brand", "danger"];
+/** All button emphases */
+const BUTTON_EMPHASES = [
+    "solid",
+    "soft",
+    "outline",
+    "ghost",
+    "transparent",
+    "link",
+];
+export { BUTTON_EMPHASES, BUTTON_SIZE_CLASSES, BUTTON_TONES, buttonSizeToIconSize, buttonVariants, DEFAULT_BUTTON_SIZE, EXPANDABLE_CLIP, EXPANDABLE_COLLAPSED_MARGIN, EXPANDABLE_TRACK, getBaseSize, isIconSize, };

package/dist/components/button/use-has-changed.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True once `value` has differed from its initial value on any render, and
+ * stays true afterwards. Lets a component skip enter/exit animation machinery
+ * until a value actually swaps.
+ */
+export declare const useHasChanged: (value: string) => boolean;

package/dist/components/button/use-has-changed.js

@@ -0,0 +1,16 @@
+"use client";
+import { useState } from "react";
+/**
+ * True once `value` has differed from its initial value on any render, and
+ * stays true afterwards. Lets a component skip enter/exit animation machinery
+ * until a value actually swaps.
+ */
+export const useHasChanged = (value) => {
+    const [previous, setPrevious] = useState(value);
+    const [changed, setChanged] = useState(false);
+    if (previous !== value) {
+        setPrevious(value);
+        setChanged(true);
+    }
+    return changed;
+};

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

@@ -0,0 +1,32 @@
+import { useRender } from "@base-ui/react/use-render";
+import { Separator } from "@instruments/materia-ui/components/separator";
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentProps } from "react";
+/**
+ * buttonGroupVariants variant class helper for ButtonGroup.
+ *  * Uses variant-based styling via class-variance-authority.
+ */
+declare const buttonGroupVariants: (props?: ({
+    variant?: "joined" | "segmented" | null | undefined;
+    orientation?: "horizontal" | "vertical" | null | undefined;
+    radius?: "full" | "rounded" | "square" | null | undefined;
+    dividers?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * Combines related buttons into a single visual unit.
+ * Also composes with Input, Select, and DropdownMenu; `dividers` defaults on for the segmented variant.
+ *
+ * @bestPractice Use `ButtonGroup` to visually join related `Button`s (plus `Input`/`Select`/`DropdownMenu`); for one/many *selection* state reach for `ToggleGroup`.
+ * @bestPractice The `segmented` variant owns the border/background/shadow and defaults `dividers` on, while `joined` (default) lets each child draw its own - don't mix the two.
+ * @category actions
+ */
+declare const ButtonGroup: ({ className, variant, orientation, radius, dividers, ...props }: ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>) => import("react").JSX.Element;
+/**
+ * Non-interactive text/label segment sitting alongside buttons in the group.
+ */
+declare const ButtonGroupText: ({ className, ref, render, ...props }: useRender.ComponentProps<"div">) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/**
+ * Divider between items in a `ButtonGroup`; defaults to vertical orientation.
+ */
+declare const ButtonGroupSeparator: ({ className, orientation, ...props }: ComponentProps<typeof Separator>) => import("react").JSX.Element;
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, };

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

@@ -0,0 +1,153 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { Separator } from "@instruments/materia-ui/components/separator";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+/**
+ * buttonGroupVariants variant class helper for ButtonGroup.
+ *  * Uses variant-based styling via class-variance-authority.
+ */
+const buttonGroupVariants = cva("flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-r-md [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1", {
+    compoundVariants: [
+        // Dividers based on orientation (when dividers: true)
+        // Uses border-l/border-t on children with explicit colour to override ghost button's border-transparent
+        {
+            class: "[&>*:not(:first-child)]:border-l-border [&>*:not(:first-child)]:border-l",
+            dividers: true,
+            orientation: "horizontal",
+        },
+        {
+            class: "[&>*:not(:first-child)]:border-t-border [&>*:not(:first-child)]:border-t",
+            dividers: true,
+            orientation: "vertical",
+        },
+        // Segmented variant uses dividers instead of border overrides.
+        {
+            class: "[&>*:not(:first-child)]:border-l-border [&>*:not(:first-child)]:border-l",
+            orientation: "horizontal",
+            variant: "segmented",
+        },
+        {
+            class: "[&>*:not(:first-child)]:border-t-border [&>*:not(:first-child)]:border-t",
+            orientation: "vertical",
+            variant: "segmented",
+        },
+        // Remove borders from buttons when dividers are disabled (segmented
+        // without dividers), and the divider from every other child too, such
+        // as a quantity field between two steppers.
+        {
+            class: "[&>*:not(:first-child)]:border-t-0 [&>*:not(:first-child)]:border-l-0 [&>[data-slot=button]]:border-0 [&>[data-slot=button]]:shadow-none",
+            dividers: false,
+            variant: "segmented",
+        },
+        // Remove overlapping borders when dividers are disabled (joined variant behaviour)
+        {
+            class: "[&>[data-slot=button]]:border-0",
+            dividers: false,
+            orientation: "horizontal",
+        },
+        {
+            class: "[&>[data-slot=button]]:border-0",
+            dividers: false,
+            orientation: "vertical",
+        },
+        // Optional radius overrides (applies to non-separator items)
+        {
+            class: "[&>*:not([data-slot=button-group-separator])]:rounded-none [&>*:not([data-slot=button-group-separator]):first-child]:rounded-s-md [&>*:not([data-slot=button-group-separator]):last-child]:rounded-e-md",
+            orientation: "horizontal",
+            radius: "rounded",
+        },
+        {
+            class: "[&>*:not([data-slot=button-group-separator])]:rounded-none [&>*:not([data-slot=button-group-separator]):first-child]:rounded-t-md [&>*:not([data-slot=button-group-separator]):last-child]:rounded-b-md",
+            orientation: "vertical",
+            radius: "rounded",
+        },
+        {
+            class: "[&>*:not([data-slot=button-group-separator])]:rounded-none [&>*:not([data-slot=button-group-separator]):first-child]:rounded-s-full [&>*:not([data-slot=button-group-separator]):last-child]:rounded-e-full",
+            orientation: "horizontal",
+            radius: "full",
+        },
+        {
+            class: "[&>*:not([data-slot=button-group-separator])]:rounded-none [&>*:not([data-slot=button-group-separator]):first-child]:rounded-t-full [&>*:not([data-slot=button-group-separator]):last-child]:rounded-b-full",
+            orientation: "vertical",
+            radius: "full",
+        },
+        {
+            class: "[&>*:not([data-slot=button-group-separator])]:rounded-none",
+            radius: "square",
+        },
+        // When segmented, also apply the chosen radius to the container.
+        { class: "rounded-md", radius: "rounded", variant: "segmented" },
+        { class: "rounded-full", radius: "full", variant: "segmented" },
+        { class: "rounded-none", radius: "square", variant: "segmented" },
+    ],
+    defaultVariants: {
+        orientation: "horizontal",
+        radius: "rounded",
+        variant: "joined",
+    },
+    variants: {
+        variant: {
+            /**
+             * Default "joined" behaviour - relies on each child for borders/background,
+             * and simply removes overlapping borders + inner radii.
+             */
+            joined: "",
+            /**
+             * Segmented "pill" group - the container provides border/background/shadow,
+             * and items are visually separated via `divide-*`.
+             */
+            segmented: "border-border bg-card isolate overflow-hidden border shadow-xs [&>[data-slot=button-group-text]]:border-0 [&>[data-slot=button-group-text]]:shadow-none [&>[data-slot=select-trigger]]:border-0 [&>[data-slot=select-trigger]]:shadow-none",
+        },
+        orientation: {
+            horizontal: "flex-row [&>*:not(:first-child)]:rounded-l-none [&>*:not(:last-child)]:rounded-r-none",
+            vertical: "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:last-child)]:rounded-b-none",
+        },
+        radius: {
+            rounded: "",
+            square: "",
+            full: "",
+        },
+        dividers: {
+            true: "",
+            false: "",
+        },
+    },
+});
+/**
+ * Combines related buttons into a single visual unit.
+ * Also composes with Input, Select, and DropdownMenu; `dividers` defaults on for the segmented variant.
+ *
+ * @bestPractice Use `ButtonGroup` to visually join related `Button`s (plus `Input`/`Select`/`DropdownMenu`); for one/many *selection* state reach for `ToggleGroup`.
+ * @bestPractice The `segmented` variant owns the border/background/shadow and defaults `dividers` on, while `joined` (default) lets each child draw its own - don't mix the two.
+ * @category actions
+ */
+const ButtonGroup = ({ className, variant = "joined", orientation = "horizontal", radius = "full", dividers, ...props }) => {
+    // Default dividers to true for segmented variant, false otherwise
+    const dividersValue = dividers === undefined ? variant === "segmented" : dividers;
+    return (_jsx("div", { className: cn(buttonGroupVariants({
+            dividers: dividersValue,
+            orientation,
+            radius,
+            variant,
+        }), className), "data-component": "button-group", "data-orientation": orientation, "data-slot": "button-group", "data-variant": variant, ...props }));
+};
+/**
+ * Non-interactive text/label segment sitting alongside buttons in the group.
+ */
+const ButtonGroupText = ({ className, ref, render, ...props }) => useRender({
+    defaultTagName: "div",
+    props: {
+        className: cn("bg-muted text-paragraph-sm flex items-center gap-2 rounded-md border px-4 font-medium shadow-xs [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4", className),
+        "data-component": "button-group-text",
+        "data-slot": "button-group-text",
+        ...props,
+    },
+    ref,
+    render,
+});
+/**
+ * Divider between items in a `ButtonGroup`; defaults to vertical orientation.
+ */
+const ButtonGroupSeparator = ({ className, orientation = "vertical", ...props }) => (_jsx(Separator, { className: cn("bg-input relative !m-0 self-stretch data-[orientation=vertical]:h-auto", className), "data-component": "button-group-separator", "data-slot": "button-group-separator", orientation: orientation, ...props }));
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, };

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

@@ -0,0 +1 @@
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, } from "./button-group/button-group-root.js";

package/dist/components/button-group.js

@@ -0,0 +1 @@
+export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, } from "./button-group/button-group-root.js";

package/dist/components/button.d.ts

@@ -0,0 +1 @@
+export { BUTTON_EMPHASES, BUTTON_TONES, Button, type ButtonEmphasis, type ButtonProps, type ButtonSize, type ButtonTone, buttonVariants, } from "./button/button-root.js";

package/dist/components/button.js

@@ -0,0 +1 @@
+export { BUTTON_EMPHASES, BUTTON_TONES, Button, buttonVariants, } from "./button/button-root.js";

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

@@ -0,0 +1,8 @@
+import type { ComponentProps } from "react";
+import { DayPicker } from "react-day-picker";
+export type CalendarProps = ComponentProps<typeof DayPicker>;
+declare function Calendar({ className, classNames, showOutsideDays, ...props }: CalendarProps): import("react").JSX.Element;
+declare namespace Calendar {
+    var displayName: string;
+}
+export { Calendar };

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

@@ -0,0 +1,54 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { DayButton, DayPicker } from "react-day-picker";
+import { buttonVariants } from "../button.js";
+import { Icon } from "../icon.js";
+const CalendarChevron = ({ orientation }) => (_jsx(Icon, { icon: orientation === "left" ? ChevronLeft : ChevronRight, size: "xs" }));
+/**
+ * DayPicker marks selection on the grid cell, not the button inside it, so the
+ * button carries its own copy to paint the filled day. A range's middle days
+ * are selected too, but sit on the cell's accent band instead of a fill.
+ */
+const CalendarDayButton = ({ modifiers, ...props }) => (_jsx(DayButton, { "data-selected": modifiers.selected === true && modifiers.range_middle !== true, modifiers: modifiers, ...props }));
+/**
+ * Date picker built on react-day-picker, styled with the shared button variants;
+ * supports `single`, `multiple`, and `range` selection via the `mode` prop.
+ * Accepts all DayPicker props. `showOutsideDays` defaults to `true`.
+ *
+ * @bestPractice Set `mode` explicitly (`single` | `multiple` | `range`) - the selection value shape and `onSelect` signature change with it; a `range` handler never fires in `single` mode.
+ * @bestPractice Restrict selectable dates with react-day-picker matchers (`disabled`/`hidden`/`startMonth`/`endMonth`), not by filtering after the user clicks.
+ * @bestPractice Use `Calendar` for an inline date grid; for a compact click-to-open date field, wrap it in a `Popover` behind a `Button`/`Input` trigger.
+ * @category forms
+ */
+const Calendar = ({ className, classNames, showOutsideDays = true, ...props }) => (_jsx(DayPicker, { className: cn("w-fit p-3", className), classNames: {
+        button_next: cn(buttonVariants({ emphasis: "ghost", tone: "neutral" }), "text-muted-foreground hover:bg-accent hover:text-foreground size-8 p-0"),
+        button_previous: cn(buttonVariants({ emphasis: "ghost", tone: "neutral" }), "text-muted-foreground hover:bg-accent hover:text-foreground size-8 p-0"),
+        caption_label: "text-paragraph-sm font-medium",
+        day: cn("text-paragraph-sm relative w-9 p-0 text-center focus-within:relative focus-within:z-20", props.mode === "range" &&
+            "[&:has([aria-selected])]:bg-accent [&:has([aria-selected].day-outside)]:bg-accent/50 [&:has(>.day-range-end)]:rounded-r-md [&:has(>.day-range-start)]:rounded-l-md first:[&:has([aria-selected])]:rounded-l-md last:[&:has([aria-selected])]:rounded-r-md [&:has([aria-selected].day-range-end)]:rounded-r-md"),
+        day_button: cn(buttonVariants({ emphasis: "ghost" }), "data-[selected=true]:bg-primary data-[selected=true]:text-primary-foreground data-[selected=true]:hover:bg-primary data-[selected=true]:hover:text-primary-foreground size-8 rounded-md p-0 font-normal"),
+        disabled: "text-muted-foreground opacity-50",
+        hidden: "invisible",
+        month: "flex flex-col gap-4",
+        month_caption: "flex h-9 items-center justify-center",
+        month_grid: "w-full border-collapse space-y-1",
+        months: "relative flex flex-col gap-2 sm:flex-row",
+        nav: "absolute inset-x-0 top-0 z-10 flex h-9 items-center justify-between px-1",
+        outside: "day-outside text-muted-foreground opacity-50 aria-selected:bg-accent/50 aria-selected:text-muted-foreground aria-selected:opacity-30",
+        range_end: "day-range-end",
+        range_middle: "aria-selected:bg-accent aria-selected:text-accent-foreground",
+        range_start: "day-range-start",
+        selected: "",
+        today: "bg-accent text-accent-foreground",
+        week: "mt-2 flex w-full",
+        weekday: "w-9 rounded-md text-calendar font-normal text-muted-foreground",
+        weekdays: "flex",
+        ...classNames,
+    }, components: {
+        Chevron: CalendarChevron,
+        DayButton: CalendarDayButton,
+    }, showOutsideDays: showOutsideDays, ...props }));
+Calendar.displayName = "Calendar";
+export { Calendar };

package/dist/components/calendar.d.ts

@@ -0,0 +1,2 @@
+export type { CalendarProps } from "./calendar/calendar-root.js";
+export { Calendar } from "./calendar/calendar-root.js";

package/dist/components/calendar.js

@@ -0,0 +1 @@
+export { Calendar } from "./calendar/calendar-root.js";