@instruments/materia-ui 0.1.0

package/dist/components/toast/toast-manager.d.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+/** The kinds of toast; each shows its own icon on the shared neutral surface. */
+export type ToastType = "error" | "info" | "loading" | "success" | "warning";
+/** Options for {@link toast} and its typed variants. */
+export interface ToastOptions {
+    /** Secondary line under the message. */
+    description?: ReactNode;
+    /** How long the toast stays, in milliseconds; `0` keeps it until dismissed. @default 4000 */
+    duration?: number;
+    /** Reuse an id to update a toast in place instead of adding another. */
+    id?: string;
+    /** A button on the toast, such as Undo. */
+    action?: {
+        label: ReactNode;
+        onClick: () => void;
+    };
+    /** Called when the toast closes, by timeout or by the user. */
+    onClose?: () => void;
+}
+/** What a promise toast shows while pending, once fulfilled and once rejected. */
+export interface ToastPromiseMessages {
+    loading: ReactNode;
+    success: ReactNode;
+    error: ReactNode;
+}
+/**
+ * The one manager every `Toaster` renders from. Toasts can be queued from
+ * anywhere - event handlers, effects or plain functions - without a hook.
+ */
+export declare const toastManager: import("@base-ui/react").ToastManager<any>;
+/**
+ * Shows a toast with `message` as its title and returns its id. Mount one
+ * `Toaster` to render them.
+ *
+ * @example
+ * ```tsx
+ * import { toast } from "@instruments/materia-ui/components/toast";
+ *
+ * toast("Changes saved");
+ * toast.success("Sample requested", { description: "Arrives Thursday" });
+ * toast.promise(upload(), {
+ *   loading: "Uploading…",
+ *   success: "Uploaded",
+ *   error: "Upload failed",
+ * });
+ * ```
+ */
+export declare const toast: ((message: ReactNode, options?: ToastOptions) => string) & {
+    /** Closes the toast with `id`, or every toast when `id` is omitted. */
+    dismiss: (id?: string) => void;
+    error: (message: ReactNode, options?: ToastOptions) => string;
+    info: (message: ReactNode, options?: ToastOptions) => string;
+    /** A loading toast that tracks `promise`, then shows its success or error message. */
+    promise: <Value>(promise: Promise<Value>, messages: ToastPromiseMessages) => Promise<Value>;
+    success: (message: ReactNode, options?: ToastOptions) => string;
+    warning: (message: ReactNode, options?: ToastOptions) => string;
+};

package/dist/components/toast/toast-manager.js

@@ -0,0 +1,62 @@
+import { Toast as ToastPrimitive } from "@base-ui/react/toast";
+/**
+ * The one manager every `Toaster` renders from. Toasts can be queued from
+ * anywhere - event handlers, effects or plain functions - without a hook.
+ */
+export const toastManager = ToastPrimitive.createToastManager();
+const toAddOptions = (message, type, { action, description, duration, id, onClose } = {}) => {
+    const options = { title: message };
+    if (action !== undefined) {
+        options.actionProps = { children: action.label, onClick: action.onClick };
+    }
+    if (description !== undefined) {
+        options.description = description;
+    }
+    if (duration !== undefined) {
+        options.timeout = duration;
+    }
+    if (id !== undefined) {
+        options.id = id;
+    }
+    if (onClose !== undefined) {
+        options.onClose = onClose;
+    }
+    if (type !== undefined) {
+        options.type = type;
+    }
+    return options;
+};
+const show = (type) => (message, options) => toastManager.add(toAddOptions(message, type, options));
+/**
+ * Shows a toast with `message` as its title and returns its id. Mount one
+ * `Toaster` to render them.
+ *
+ * @example
+ * ```tsx
+ * import { toast } from "@instruments/materia-ui/components/toast";
+ *
+ * toast("Changes saved");
+ * toast.success("Sample requested", { description: "Arrives Thursday" });
+ * toast.promise(upload(), {
+ *   loading: "Uploading…",
+ *   success: "Uploaded",
+ *   error: "Upload failed",
+ * });
+ * ```
+ */
+export const toast = Object.assign(show(), {
+    /** Closes the toast with `id`, or every toast when `id` is omitted. */
+    dismiss: (id) => {
+        toastManager.close(id);
+    },
+    error: show("error"),
+    info: show("info"),
+    /** A loading toast that tracks `promise`, then shows its success or error message. */
+    promise: async (promise, messages) => await toastManager.promise(promise, {
+        error: { title: messages.error },
+        loading: { title: messages.loading },
+        success: { title: messages.success },
+    }),
+    success: show("success"),
+    warning: show("warning"),
+});

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

@@ -0,0 +1,39 @@
+import type * as React from "react";
+/** Where a `Toaster` shows its toasts. */
+export type ToasterPosition = "bottom-center" | "bottom-left" | "bottom-right" | "top-center" | "top-left" | "top-right";
+/** Props for {@link Toaster}. */
+export interface ToasterProps {
+    /** Where the toasts appear. @default "bottom-center" */
+    position?: ToasterPosition;
+    /** How long a toast stays, in milliseconds, unless it sets its own `duration`. @default 4000 */
+    duration?: number;
+    /** How many toasts show at once; older ones fade out of the stack. @default 3 */
+    limit?: number;
+    /** Extra classes for the viewport the toasts stack in. */
+    className?: string;
+}
+/**
+ * Renders the toasts queued with `toast()`: light bordered cards on the neutral
+ * popover surface, each with a per-type coloured icon and a close button,
+ * stacked at the bottom centre by default. Built on Base UI Toast.
+ *
+ * @example
+ * ```tsx
+ * import { Toaster } from "@instruments/materia-ui/components/toast";
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <>
+ *       {children}
+ *       <Toaster />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @bestPractice Use toasts for transient, auto-dismissing notifications; a persistent inline message is an `Alert`.
+ * @bestPractice Mount `<Toaster />` exactly once near the app root, then fire toasts with `toast()` from `@instruments/materia-ui/components/toast` - don't render a `Toaster` per view.
+ * @bestPractice Press F6 to move focus into the toasts; hovering or focusing the stack pauses dismissal and fans it open.
+ * @category feedback
+ */
+export declare const Toaster: ({ position, duration, limit, className, }: ToasterProps) => React.JSX.Element;

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

@@ -0,0 +1,109 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Toast as ToastPrimitive } from "@base-ui/react/toast";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { CheckIcon, InfoIcon, Loader2Icon, TriangleAlertIcon, XIcon, } from "lucide-react";
+import { Button } from "../button.js";
+import { Flex } from "../flex.js";
+import { Icon } from "../icon.js";
+import { toastManager } from "./toast-manager.js";
+const VIEWPORT_POSITION = {
+    "bottom-center": "bottom-4 sm:bottom-8 sm:left-1/2 sm:-translate-x-1/2",
+    "bottom-left": "bottom-4 sm:bottom-8 sm:left-8",
+    "bottom-right": "bottom-4 sm:right-8 sm:bottom-8 sm:left-auto",
+    "top-center": "top-4 sm:top-8 sm:left-1/2 sm:-translate-x-1/2",
+    "top-left": "top-4 sm:top-8 sm:left-8",
+    "top-right": "top-4 sm:top-8 sm:right-8 sm:left-auto",
+};
+const TYPE_ICON = {
+    error: _jsx(Icon, { className: "text-destructive", icon: XIcon, size: "xs" }),
+    info: _jsx(Icon, { className: "text-info-accent", icon: InfoIcon, size: "xs" }),
+    loading: (_jsx(Icon, { className: "text-muted-foreground animate-spin", icon: Loader2Icon, size: "xs" })),
+    success: (_jsx(Icon, { className: "text-affirmative-accent", icon: CheckIcon, size: "xs" })),
+    warning: (_jsx(Icon, { className: "text-amber-500", icon: TriangleAlertIcon, size: "xs" })),
+};
+const isToastType = (type) => type !== undefined && Object.hasOwn(TYPE_ICON, type);
+const GAP = "0.75rem";
+const PEEK = "0.75rem";
+const SCALE = "max(0, 1 - var(--toast-index) * 0.1)";
+const SWIPE_X = "var(--toast-swipe-movement-x)";
+const SWIPE_Y = "var(--toast-swipe-movement-y)";
+const FRONT_HEIGHT = "var(--toast-frontmost-height, var(--toast-height))";
+/** Transform for a toast that has been swiped or closed, by its exit direction. */
+const exitTransform = (direction, offscreen, expandedY) => {
+    if (direction === undefined) {
+        return `translateY(${offscreen})`;
+    }
+    const swiped = {
+        down: `translateY(calc(${SWIPE_Y} + 150%))`,
+        left: `translateX(calc(${SWIPE_X} - 150%)) translateY(${expandedY})`,
+        right: `translateX(calc(${SWIPE_X} + 150%)) translateY(${expandedY})`,
+        up: `translateY(calc(${SWIPE_Y} - 150%))`,
+    };
+    return swiped[direction];
+};
+/**
+ * Stacking geometry from Base UI's toast CSS variables. Toasts fan away from
+ * the screen edge they sit on: collapsed, each one peeks behind the front toast
+ * at a smaller scale; expanded (hover or focus), they lay out in a column.
+ */
+const toastStyle = (edge) => (state) => {
+    const sign = edge === "bottom" ? "-" : "+";
+    const expandedY = `calc(${sign === "-" ? "-1 * " : ""}var(--toast-offset-y) ${sign} var(--toast-index) * ${GAP} + ${SWIPE_Y})`;
+    const collapsed = `translateX(${SWIPE_X}) translateY(calc(${SWIPE_Y} ${sign} var(--toast-index) * ${PEEK} ${sign} (1 - ${SCALE}) * ${FRONT_HEIGHT})) scale(${SCALE})`;
+    const expanded = `translateX(${SWIPE_X}) translateY(${expandedY})`;
+    const offscreen = edge === "bottom" ? "150%" : "-150%";
+    let transform = state.expanded ? expanded : collapsed;
+    if (state.transitionStatus === "starting") {
+        transform = `translateY(${offscreen})`;
+    }
+    else if (state.transitionStatus === "ending" && !state.limited) {
+        transform = exitTransform(state.swipeDirection, offscreen, expandedY);
+    }
+    return {
+        height: state.expanded ? "var(--toast-height)" : FRONT_HEIGHT,
+        opacity: state.transitionStatus === "ending" || state.limited ? 0 : undefined,
+        transform,
+        transition: state.swiping
+            ? "none"
+            : "transform 0.5s cubic-bezier(0.22, 1, 0.36, 1), opacity 0.5s, height 0.15s",
+        zIndex: `calc(1000 - var(--toast-index))`,
+    };
+};
+const ToastList = ({ edge }) => {
+    const { toasts } = ToastPrimitive.useToastManager();
+    const style = toastStyle(edge);
+    return toasts.map((item) => (_jsx(ToastPrimitive.Root, { className: cn("bg-popover text-popover-foreground text-paragraph-sm absolute inset-x-0 w-full rounded-2xl border shadow-sm select-none", 
+        // Bridges the gap between expanded toasts so the stack stays open under the pointer.
+        "after:absolute after:left-0 after:h-3.5 after:w-full", edge === "bottom"
+            ? "bottom-0 origin-bottom after:top-full"
+            : "top-0 origin-top after:bottom-full"), "data-component": "toast", "data-slot": "toast", style: style, swipeDirection: edge === "bottom" ? ["down", "right"] : ["up", "right"], toast: item, children: _jsxs(ToastPrimitive.Content, { className: "duration-normal flex items-center gap-2 overflow-hidden px-4 py-3 transition-opacity data-behind:opacity-0 data-expanded:opacity-100", children: [isToastType(item.type) ? (_jsx(Flex, { as: "span", className: "mr-2 shrink-0", "data-slot": "toast-icon", inline: true, children: TYPE_ICON[item.type] })) : null, _jsxs(Flex, { className: "min-w-0 flex-1", direction: "column", gap: "2xs", children: [_jsx(ToastPrimitive.Title, { className: "font-medium" }), _jsx(ToastPrimitive.Description, { className: "text-muted-foreground" })] }), item.actionProps ? (_jsx(ToastPrimitive.Action, { className: "bg-primary text-primary-foreground hover:bg-primary/90 text-caption h-6 shrink-0 rounded-full px-4 font-medium" })) : null, _jsx(ToastPrimitive.Close, { render: _jsx(Button, { "aria-label": "Close", emphasis: "ghost", icon: XIcon, size: "icon-2xs", tone: "neutral" }) })] }) }, item.id)));
+};
+/**
+ * Renders the toasts queued with `toast()`: light bordered cards on the neutral
+ * popover surface, each with a per-type coloured icon and a close button,
+ * stacked at the bottom centre by default. Built on Base UI Toast.
+ *
+ * @example
+ * ```tsx
+ * import { Toaster } from "@instruments/materia-ui/components/toast";
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <>
+ *       {children}
+ *       <Toaster />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @bestPractice Use toasts for transient, auto-dismissing notifications; a persistent inline message is an `Alert`.
+ * @bestPractice Mount `<Toaster />` exactly once near the app root, then fire toasts with `toast()` from `@instruments/materia-ui/components/toast` - don't render a `Toaster` per view.
+ * @bestPractice Press F6 to move focus into the toasts; hovering or focusing the stack pauses dismissal and fans it open.
+ * @category feedback
+ */
+export const Toaster = ({ position = "bottom-center", duration = 4000, limit = 3, className, }) => {
+    const edge = position.startsWith("top") ? "top" : "bottom";
+    return (_jsx(ToastPrimitive.Provider, { limit: limit, timeout: duration, toastManager: toastManager, children: _jsx(ToastPrimitive.Portal, { children: _jsx(ToastPrimitive.Viewport, { className: cn("fixed inset-x-4 z-50 mx-auto sm:inset-x-auto sm:mx-0 sm:w-90", VIEWPORT_POSITION[position], className), "data-component": "toaster", "data-position": position, "data-slot": "toaster", children: _jsx(ToastList, { edge: edge }) }) }) }));
+};

package/dist/components/toast.d.ts

@@ -0,0 +1,2 @@
+export { Toaster, type ToasterPosition, type ToasterProps, } from "./toast/toast-root.js";
+export { toast, type ToastOptions, type ToastPromiseMessages, type ToastType, } from "./toast/toast-manager.js";

package/dist/components/toast.js

@@ -0,0 +1,2 @@
+export { Toaster, } from "./toast/toast-root.js";
+export { toast, } from "./toast/toast-manager.js";

package/dist/components/toggle/toggle-group-context.d.ts

@@ -0,0 +1,15 @@
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ToggleRadius, ToggleSize, ToggleVariant } from "./toggle-root.js";
+/** How the toggles of a `ToggleGroup` sit together. */
+export type ToggleGroupLayout = "joined" | "separated" | "wrap";
+/**
+ * What a `ToggleGroup` shares with the `Toggle`s inside it. `null` outside a
+ * group, so a lone Toggle keeps its own props.
+ */
+export interface ToggleGroupContextValue {
+    layout: ToggleGroupLayout;
+    radius: ToggleRadius;
+    size: ResponsiveValue<ToggleSize>;
+    variant: ToggleVariant;
+}
+export declare const ToggleGroupContext: import("react").Context<ToggleGroupContextValue | null>;

package/dist/components/toggle/toggle-group-context.js

@@ -0,0 +1,3 @@
+"use client";
+import { createContext } from "react";
+export const ToggleGroupContext = createContext(null);

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

@@ -0,0 +1,68 @@
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import type { VariantProps } from "class-variance-authority";
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { Radius } from "../../tokens/radius.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ComponentSize } from "../../tokens/size.js";
+/** Toggle sizes - subset of the shared ComponentSize scale. */
+export type ToggleSize = Extract<ComponentSize, "sm" | "base" | "lg">;
+/**
+ * Toggle radius - the shared {@link Radius} members the toggle exposes. Its
+ * corners are always soft, so `"rounded"` (the default, `rounded-lg`) and
+ * `"full"` (pill, `rounded-full`) are the only two; there is no sharp variant.
+ */
+export type ToggleRadius = Extract<Radius, "rounded" | "full">;
+/** How a pressed Toggle shows it is on. */
+export type ToggleVariant = "default" | "secondary";
+/**
+ * Per-size class map for Toggle. Kept as a named export so the component can
+ * layer per-breakpoint `md:*` overrides on top of the cva's base size via
+ * `getResponsiveSizeOverrides`. The cva still references this map as its `size`
+ * variant (compound `data-[icon-only]` sizing depends on it), so static output
+ * is unchanged.
+ */
+export declare const TOGGLE_SIZE_CLASSES: Record<ToggleSize, string>;
+/** Default Toggle size. */
+export declare const DEFAULT_TOGGLE_SIZE: ToggleSize;
+/**
+ * toggleVariants variant class helper for Toggle.
+ * Import from "@instruments/materia-ui/components/toggle".
+ * Built on Base UI primitives for accessible behaviour.
+ * Uses variant-based styling via class-variance-authority.
+ */
+declare const toggleVariants: (props?: ({
+    variant?: "default" | "secondary" | null | undefined;
+    size?: ToggleSize | null | undefined;
+    radius?: "full" | "rounded" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * Two-state pressable button (on/off) built on Base UI Toggle, with an optional
+ * icon alongside the label.
+ *
+ * Pass `icon` with no children to get a square icon-only toggle (auto-detected
+ * and sized to match its height); pass both for an icon + label. Controlled via
+ * `pressed`/`onPressedChange`, uncontrolled via `defaultPressed`.
+ *
+ * Inside a `ToggleGroup` it is the group's item, as in Base UI: give it a
+ * `value`, and it takes the group's `size`, `radius`, `variant` and layout in
+ * place of its own. An icon-only toggle needs an `aria-label`; a dev warning
+ * fires without one.
+ *
+ * @bestPractice One independent on/off is a `Toggle`; a mutually-exclusive or multi-select set is `ToggleGroup` with `Toggle`s inside it; an instantly-applied setting is `Switch`.
+ * @bestPractice Pass `icon` with no children for a square icon-only toggle (auto-sized); with a label, order it via `iconPlacement`.
+ * @category actions
+ */
+declare const Toggle: ({ className, variant, size, radius, icon, iconPlacement, children, ...props }: TogglePrimitive.Props & Omit<VariantProps<typeof toggleVariants>, "size"> & {
+    /** Icon rendered beside the label, or alone for an icon-only toggle. */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Icon position relative to the label. @default "start" */
+    iconPlacement?: "start" | "end";
+    /**
+     * Toggle size - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "lg" }`. Icon-only sizing follows the base breakpoint.
+     * @default "base"
+     */
+    size?: ResponsiveValue<ToggleSize>;
+}) => React.JSX.Element;
+export { Toggle, toggleVariants };

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

@@ -0,0 +1,128 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { use } from "react";
+import { DISABLED } from "../../tokens/input-shell.js";
+import { getResponsiveSizeOverrides, resolveResponsiveBase, } from "../../tokens/responsive.js";
+import { warnMissingAriaLabel } from "../../utils/warn-missing-aria-label.js";
+import { Icon } from "../icon.js";
+import { ToggleGroupContext } from "./toggle-group-context.js";
+/**
+ * Per-size class map for Toggle. Kept as a named export so the component can
+ * layer per-breakpoint `md:*` overrides on top of the cva's base size via
+ * `getResponsiveSizeOverrides`. The cva still references this map as its `size`
+ * variant (compound `data-[icon-only]` sizing depends on it), so static output
+ * is unchanged.
+ */
+export const TOGGLE_SIZE_CLASSES = {
+    sm: "h-8 gap-2 px-3 [&_svg:not([class*='size-'])]:size-4",
+    base: "h-9 gap-2 px-3 [&_svg:not([class*='size-'])]:size-4",
+    lg: "h-10 gap-2 px-3 [&_svg:not([class*='size-'])]:size-4",
+};
+/** Default Toggle size. */
+export const DEFAULT_TOGGLE_SIZE = "base";
+/**
+ * toggleVariants variant class helper for Toggle.
+ * Import from "@instruments/materia-ui/components/toggle".
+ * Built on Base UI primitives for accessible behaviour.
+ * Uses variant-based styling via class-variance-authority.
+ */
+const toggleVariants = cva(cn(focusRing(), "border-border text-foreground bg-background hover:border-foreground/30 text-paragraph-sm inline-flex cursor-pointer items-center justify-center gap-2 border font-medium whitespace-nowrap shadow-xs transition focus-visible:ring-offset-2 data-pressed:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0", DISABLED), {
+    compoundVariants: [
+        { class: "data-icon-only:size-8 data-icon-only:p-0", size: "sm" },
+        {
+            class: "data-icon-only:size-9 data-icon-only:p-0",
+            size: "base",
+        },
+        { class: "data-icon-only:size-10 data-icon-only:p-0", size: "lg" },
+    ],
+    defaultVariants: {
+        radius: "rounded",
+        size: "base",
+        variant: "default",
+    },
+    variants: {
+        variant: {
+            default: "data-pressed:border-muted-foreground data-pressed:bg-muted",
+            secondary: "data-pressed:border-foreground data-pressed:bg-background",
+        },
+        size: TOGGLE_SIZE_CLASSES,
+        // Old `shape` values map onto the shared Radius vocabulary by their actual
+        // class: old `square` was `rounded-lg` → "rounded"; old `round` was
+        // `rounded-full` → "full". Appearance is preserved exactly.
+        radius: {
+            rounded: "rounded-lg",
+            full: "rounded-full",
+        },
+    },
+});
+/**
+ * In a joined group the toggles share their borders: each overlaps the one
+ * before by a pixel, only the ends are rounded, and a pressed or focused toggle
+ * rises so its outline owns all four edges.
+ */
+const joinedClasses = (layout, radius) => layout === "joined" &&
+    cn("-ms-px rounded-none shadow-none first:ms-0", "focus-visible:z-10 data-pressed:z-10", radius === "full"
+        ? "first:rounded-s-full last:rounded-e-full"
+        : "first:rounded-s-lg last:rounded-e-lg");
+/**
+ * A Toggle's classes. Inside a group the group's settings win over the
+ * toggle's own, so a row stays uniform.
+ */
+const toggleClasses = (group, own) => {
+    const size = group?.size ?? own.size;
+    const radius = group?.radius ?? own.radius ?? "rounded";
+    return cn(toggleVariants({
+        radius,
+        size: resolveResponsiveBase(size, DEFAULT_TOGGLE_SIZE),
+        variant: group?.variant ?? own.variant,
+    }), getResponsiveSizeOverrides(size, TOGGLE_SIZE_CLASSES), group !== null && "shrink-0", joinedClasses(group?.layout, radius));
+};
+/** Resolves the inner content of a Toggle based on icon/children placement. */
+const ToggleContent = ({ isIconOnly, iconElement, hasIcon, hasChildren, iconPlacement, children, }) => {
+    // Icon-only toggle
+    if (isIconOnly) {
+        return iconElement;
+    }
+    // Labelled toggle with icon
+    if (hasIcon && hasChildren) {
+        if (iconPlacement === "start") {
+            return (_jsxs(_Fragment, { children: [iconElement, children] }));
+        }
+        return (_jsxs(_Fragment, { children: [children, iconElement] }));
+    }
+    return children;
+};
+/**
+ * Two-state pressable button (on/off) built on Base UI Toggle, with an optional
+ * icon alongside the label.
+ *
+ * Pass `icon` with no children to get a square icon-only toggle (auto-detected
+ * and sized to match its height); pass both for an icon + label. Controlled via
+ * `pressed`/`onPressedChange`, uncontrolled via `defaultPressed`.
+ *
+ * Inside a `ToggleGroup` it is the group's item, as in Base UI: give it a
+ * `value`, and it takes the group's `size`, `radius`, `variant` and layout in
+ * place of its own. An icon-only toggle needs an `aria-label`; a dev warning
+ * fires without one.
+ *
+ * @bestPractice One independent on/off is a `Toggle`; a mutually-exclusive or multi-select set is `ToggleGroup` with `Toggle`s inside it; an instantly-applied setting is `Switch`.
+ * @bestPractice Pass `icon` with no children for a square icon-only toggle (auto-sized); with a label, order it via `iconPlacement`.
+ * @category actions
+ */
+const Toggle = ({ className, variant, size, radius, icon, iconPlacement = "start", children, ...props }) => {
+    // Empty means no node at all: `null`/`undefined` or an empty list.
+    const hasChildren = Array.isArray(children)
+        ? children.length > 0
+        : children !== undefined && children !== null;
+    const isIconOnly = icon && !hasChildren;
+    warnMissingAriaLabel(icon, children, props["aria-label"], props["aria-labelledby"]);
+    // Icon element - let CSS handle sizing via [&_svg]:size-4
+    const iconElement = icon ? _jsx(Icon, { icon: icon }) : null;
+    const group = use(ToggleGroupContext);
+    return (_jsx(TogglePrimitive, { className: cn(toggleClasses(group, { radius, size, variant }), className), "data-component": "toggle", "data-icon-only": isIconOnly === true ? "true" : undefined, "data-slot": group ? "toggle-group-item" : "toggle", ...props, children: _jsx(ToggleContent, { hasChildren: hasChildren, hasIcon: Boolean(icon), iconElement: iconElement, iconPlacement: iconPlacement, isIconOnly: isIconOnly === true, children: children }) }));
+};
+export { Toggle, toggleVariants };

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

@@ -0,0 +1,38 @@
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ToggleGroupLayout } from "../toggle/toggle-group-context.js";
+import type { ToggleRadius, ToggleSize, ToggleVariant } from "../toggle/toggle-root.js";
+/** Extra props {@link ToggleGroup} layers on top of the Base UI root. */
+interface ToggleGroupOwnProps {
+    /** How items sit together. @default "joined" */
+    layout?: ToggleGroupLayout;
+    /**
+     * Single-selection only: the active item cannot be deselected
+     * (Tabs/RadioGroup semantics). Dev-warns if used with `multiple`.
+     * @default false
+     */
+    required?: boolean;
+    /** Toggle's scale - a single token or a per-breakpoint object. @default "base" */
+    size?: ResponsiveValue<ToggleSize>;
+    /** Toggle radius shared by every item. @default "rounded" */
+    radius?: ToggleRadius;
+    /** Visual style forwarded to `toggleVariants`. @default "default" */
+    variant?: ToggleVariant;
+}
+type ToggleGroupProps = ToggleGroupPrimitive.Props & ToggleGroupOwnProps;
+/**
+ * A literal group of {@link Toggle}s: several two-state pressable buttons that
+ * share one selection, laid out `joined` (a seamless segmented row),
+ * `separated`, or `wrap`ped. Built on Base UI ToggleGroup - by default one
+ * item is pressed at a time (radio-like), `multiple` makes it checkbox-like;
+ * `value` is always an array. The `Toggle`s inside take
+ * `size` / `radius` / `variant` from the group through context.
+ *
+ * @bestPractice An always-one-selected mode switcher is `SegmentedControl`, not `ToggleGroup` - reach here for multi-select toolbars and deselectable choice chips.
+ * @bestPractice `layout="wrap"` + `required` (without `multiple`) is the wizard choice-chip recipe.
+ * @bestPractice Put plain `Toggle`s inside, each with a `value`, as Base UI does.
+ * @bestPractice Icon-only toggles need an `aria-label` (a dev warning fires otherwise).
+ * @category actions
+ */
+declare const ToggleGroup: ({ className, layout, required, variant, size, radius, children, multiple, onValueChange, ...props }: ToggleGroupProps) => import("react").JSX.Element;
+export { ToggleGroup };

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

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useMemo } from "react";
+import { isDevelopmentBrowser } from "../../utils/is-development-browser.js";
+import { ToggleGroupContext } from "../toggle/toggle-group-context.js";
+import { DEFAULT_TOGGLE_SIZE } from "../toggle/toggle-root.js";
+/** Root-layout class strings keyed by {@link ToggleGroupLayout}. */
+const LAYOUT_CLASSES = {
+    joined: "inline-flex max-w-full items-center",
+    separated: "flex flex-wrap items-center gap-2 data-[orientation=vertical]:flex-col data-[orientation=vertical]:items-start",
+    wrap: "flex flex-wrap items-center gap-2",
+};
+/**
+ * A literal group of {@link Toggle}s: several two-state pressable buttons that
+ * share one selection, laid out `joined` (a seamless segmented row),
+ * `separated`, or `wrap`ped. Built on Base UI ToggleGroup - by default one
+ * item is pressed at a time (radio-like), `multiple` makes it checkbox-like;
+ * `value` is always an array. The `Toggle`s inside take
+ * `size` / `radius` / `variant` from the group through context.
+ *
+ * @bestPractice An always-one-selected mode switcher is `SegmentedControl`, not `ToggleGroup` - reach here for multi-select toolbars and deselectable choice chips.
+ * @bestPractice `layout="wrap"` + `required` (without `multiple`) is the wizard choice-chip recipe.
+ * @bestPractice Put plain `Toggle`s inside, each with a `value`, as Base UI does.
+ * @bestPractice Icon-only toggles need an `aria-label` (a dev warning fires otherwise).
+ * @category actions
+ */
+const ToggleGroup = ({ className, layout = "joined", required = false, variant = "default", size = DEFAULT_TOGGLE_SIZE, radius = "rounded", children, multiple = false, onValueChange, ...props }) => {
+    const enforcedSingle = required && !multiple;
+    if (required && multiple && isDevelopmentBrowser()) {
+        console.warn("ToggleGroup: `required` has no effect with `multiple` - " +
+            "a checkbox-like group has no single active item to protect. Drop " +
+            "`multiple` for enforced selection.");
+    }
+    // Base UI emits an empty array when the active single item is re-clicked.
+    // When `required`, cancel that change so one option is ALWAYS selected.
+    const handleValueChange = (next, details) => {
+        if (enforcedSingle && next.length === 0) {
+            details.cancel();
+            return;
+        }
+        onValueChange?.(next, details);
+    };
+    const contextValue = useMemo(() => ({ layout, radius, size, variant }), [layout, size, radius, variant]);
+    return (_jsx(ToggleGroupPrimitive, { className: cn(LAYOUT_CLASSES[layout], className), "data-slot": "toggle-group", multiple: multiple, onValueChange: handleValueChange, ...props, children: _jsx(ToggleGroupContext.Provider, { value: contextValue, children: children }) }));
+};
+export { ToggleGroup };

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

@@ -0,0 +1 @@
+export { ToggleGroup } from "./toggle-group/toggle-group-root.js";

package/dist/components/toggle-group.js

@@ -0,0 +1 @@
+export { ToggleGroup } from "./toggle-group/toggle-group-root.js";

package/dist/components/toggle.d.ts

@@ -0,0 +1 @@
+export { Toggle, type ToggleRadius, type ToggleSize, toggleVariants, } from "./toggle/toggle-root.js";

package/dist/components/toggle.js

@@ -0,0 +1 @@
+export { Toggle, toggleVariants, } from "./toggle/toggle-root.js";