@instruments/materia-ui 0.1.0

package/dist/components/chart/chart-style.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { typedKeys } from "../../utils/typed-entries.js";
+import { THEMES } from "./chart-context.js";
+/**
+ * Emits the per-theme `--color-<key>` CSS variables for one chart, scoped to
+ * `[data-chart=<id>]`. {@link Chart} renders it automatically from `config`;
+ * only entries with a `color` or `theme` contribute a variable. Rendered
+ * directly only when you compose recharts by hand outside `<Chart>`.
+ */
+export const ChartStyle = ({ id, config, }) => {
+    const colorConfig = Object.entries(config).filter(([, entry]) => entry.theme !== undefined || entry.color !== undefined);
+    if (colorConfig.length === 0) {
+        return null;
+    }
+    const css = typedKeys(THEMES)
+        .map((theme) => {
+        const declarations = colorConfig
+            .map(([key, entry]) => {
+            const color = entry.theme?.[theme] ?? entry.color;
+            return color === undefined ? null : `  --color-${key}: ${color};`;
+        })
+            .filter((line) => line !== null)
+            .join("\n");
+        return `${THEMES[theme]} [data-chart=${id}] {\n${declarations}\n}`;
+    })
+        .join("\n");
+    return _jsx("style", { "data-slot": "chart-style", children: css });
+};

package/dist/components/chart/chart-tooltip.d.ts

@@ -0,0 +1,26 @@
+import type * as React from "react";
+import type { DefaultTooltipContentProps, Tooltip, TooltipValueType } from "recharts";
+/** recharts `Tooltip` - pair it with {@link ChartTooltipContent} via `content`. */
+export { Tooltip as ChartTooltip } from "recharts";
+type TooltipNameType = number | string;
+type Indicator = "line" | "dot" | "dashed";
+/**
+ * Themed tooltip surface for a {@link Chart}. Pass it to `ChartTooltip`'s
+ * `content` prop; it resolves each series' label / icon / colour from the
+ * chart's `config`. Renders on a `bg-popover` card matching HoverCard's surface
+ * vocabulary. Toggle the leading swatch with `indicator`
+ * (`"dot"` / `"line"` / `"dashed"`), hide the header with `hideLabel`, or hide
+ * the swatches with `hideIndicator`.
+ */
+export declare const ChartTooltipContent: ({ active, payload, className, indicator, hideLabel, hideIndicator, label, labelFormatter, labelClassName, color, nameKey, labelKey, }: React.ComponentProps<typeof Tooltip> & React.ComponentProps<"div"> & {
+    /** Leading swatch style: filled dot, solid rule, or dashed rule. */
+    indicator?: Indicator;
+    /** Hide the tooltip header (the shared axis label). */
+    hideLabel?: boolean;
+    /** Hide the per-series colour swatches. */
+    hideIndicator?: boolean;
+    /** Config key to resolve each row's name from (defaults to the series name). */
+    nameKey?: string;
+    /** Config key to resolve the header label from (defaults to the datum key). */
+    labelKey?: string;
+} & Omit<DefaultTooltipContentProps<TooltipValueType, TooltipNameType>, "accessibilityLayer">) => React.JSX.Element | null;

package/dist/components/chart/chart-tooltip.js

@@ -0,0 +1,62 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { isNumber, isString } from "../../utils/type-guards.js";
+import { Flex } from "../flex.js";
+import { Grid } from "../grid.js";
+import { getPayloadConfigFromPayload, readDatumStringField, resolveConfigKey, useChart, } from "./chart-context.js";
+/** recharts `Tooltip` - pair it with {@link ChartTooltipContent} via `content`. */
+export { Tooltip as ChartTooltip } from "recharts";
+/** One value cell inside the tooltip: swatch (or config icon) + label + value. */
+const TooltipRow = ({ item, indicator, hideIndicator, nestLabel, nestedLabel, color, }) => {
+    const { config } = useChart();
+    const key = resolveConfigKey(item.name, item.dataKey);
+    const itemConfig = getPayloadConfigFromPayload(config, item, key);
+    const swatchColor = color ?? readDatumStringField(item, "fill") ?? item.color;
+    const swatchStyle = {
+        "--color-bg": swatchColor,
+        "--color-border": swatchColor,
+    };
+    return (_jsxs(Flex, { className: cn("[&>svg]:text-muted-foreground w-full [&>svg]:h-2.5 [&>svg]:w-2.5", indicator === "dot" && "items-center"), gap: "xs", wrap: "wrap", children: [itemConfig?.icon ? (_jsx(itemConfig.icon, {})) : (!hideIndicator && (_jsx("div", { className: cn("shrink-0 rounded-xs border-(--color-border) bg-(--color-bg)", {
+                    "h-2.5 w-2.5": indicator === "dot",
+                    "w-1": indicator === "line",
+                    "w-0 border border-dashed bg-transparent": indicator === "dashed",
+                    "my-0.5": nestLabel && indicator === "dashed",
+                }), style: swatchStyle }))), _jsxs(Flex, { className: cn("flex-1", nestLabel ? "items-end" : "items-center"), justify: "space-between", children: [_jsxs(Grid, { className: "gap-1.5", columns: "none", gap: "none", children: [nestLabel ? nestedLabel : null, _jsx("span", { className: "text-muted-foreground", children: itemConfig?.label ?? item.name })] }), item.value === null || item.value === undefined ? null : (_jsx("span", { className: "text-foreground font-mono font-medium tabular-nums", children: isNumber(item.value)
+                            ? item.value.toLocaleString()
+                            : String(item.value) }))] })] }));
+};
+/** The shared header above the rows: the axis label, resolved through `config`. */
+const TooltipLabel = ({ config, label, labelClassName, labelFormatter, labelKey, payload, }) => {
+    const [item] = payload;
+    const key = resolveConfigKey(labelKey, item?.dataKey, item?.name);
+    const itemConfig = getPayloadConfigFromPayload(config, item, key);
+    const value = labelKey === undefined && isString(label)
+        ? (config[label]?.label ?? label)
+        : itemConfig?.label;
+    if (labelFormatter !== undefined) {
+        return (_jsx("div", { className: cn("font-medium", labelClassName), children: labelFormatter(value, payload) }));
+    }
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return _jsx("div", { className: cn("font-medium", labelClassName), children: value });
+};
+/**
+ * Themed tooltip surface for a {@link Chart}. Pass it to `ChartTooltip`'s
+ * `content` prop; it resolves each series' label / icon / colour from the
+ * chart's `config`. Renders on a `bg-popover` card matching HoverCard's surface
+ * vocabulary. Toggle the leading swatch with `indicator`
+ * (`"dot"` / `"line"` / `"dashed"`), hide the header with `hideLabel`, or hide
+ * the swatches with `hideIndicator`.
+ */
+export const ChartTooltipContent = ({ active, payload, className, indicator = "dot", hideLabel = false, hideIndicator = false, label, labelFormatter, labelClassName, color, nameKey, labelKey, }) => {
+    const { config } = useChart();
+    if (active !== true || payload === undefined || payload.length === 0) {
+        return null;
+    }
+    const items = payload.filter((item) => item.type !== "none");
+    const tooltipLabel = hideLabel ? null : (_jsx(TooltipLabel, { config: config, label: label, labelClassName: labelClassName, labelFormatter: labelFormatter, labelKey: labelKey, payload: payload }));
+    const nestLabel = items.length === 1 && indicator !== "dot";
+    return (_jsxs(Grid, { className: cn("bg-popover text-popover-foreground text-caption min-w-32 items-start gap-1.5 rounded-xl border px-2.5 py-1.5 shadow-md dark:shadow-none", className), columns: "none", "data-component": "chart-tooltip-content", "data-slot": "chart-tooltip-content", gap: "none", children: [nestLabel ? null : tooltipLabel, _jsx(Grid, { className: "gap-1.5", columns: "none", gap: "none", children: items.map((item) => (_jsx(TooltipRow, { color: color, hideIndicator: hideIndicator, indicator: indicator, item: item, nestedLabel: tooltipLabel, nestLabel: nestLabel }, resolveConfigKey(nameKey, item.name, item.dataKey)))) })] }));
+};

package/dist/components/chart.d.ts

@@ -0,0 +1,6 @@
+export { chartAnatomy } from "./chart/chart-anatomy.js";
+export type { ChartConfig } from "./chart/chart-context.js";
+export { Chart } from "./chart/chart-root.js";
+export { ChartStyle } from "./chart/chart-style.js";
+export { ChartLegend, ChartLegendContent } from "./chart/chart-legend.js";
+export { ChartTooltip, ChartTooltipContent } from "./chart/chart-tooltip.js";

package/dist/components/chart.js

@@ -0,0 +1,5 @@
+export { chartAnatomy } from "./chart/chart-anatomy.js";
+export { Chart } from "./chart/chart-root.js";
+export { ChartStyle } from "./chart/chart-style.js";
+export { ChartLegend, ChartLegendContent } from "./chart/chart-legend.js";
+export { ChartTooltip, ChartTooltipContent } from "./chart/chart-tooltip.js";

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

@@ -0,0 +1,40 @@
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
+import type { ComponentSize, ResponsiveSize } from "@instruments/materia-ui/tokens/size";
+import type * as React from "react";
+/** Default Checkbox size. */
+export declare const DEFAULT_CHECKBOX_SIZE: ComponentSize;
+export type CheckboxProps = Omit<React.ComponentProps<typeof CheckboxPrimitive.Root>, "size"> & {
+    /**
+     * Checkbox size - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "lg" }`. @default "xs"
+     */
+    size?: ResponsiveSize;
+};
+/**
+ * Renders a checkbox input with support for checked, unchecked, and indeterminate states.
+ *
+ * @param props - The checkbox props
+ * @param props.size - Checkbox size using shared ComponentSize scale. Defaults to "sm".
+ * @param props.checked - Controlled checked state. Use with onCheckedChange.
+ * @param props.indeterminate - Show the mixed state (dash icon). Independent of `checked`.
+ * @param props.defaultChecked - Uncontrolled default checked state.
+ * @param props.onCheckedChange - Callback when checked state changes.
+ * @param props.disabled - Disable the checkbox. Defaults to false.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other Base UI Checkbox.Root props.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox checked={checked} onCheckedChange={setChecked} />
+ * <Checkbox defaultChecked size="lg" />
+ * <Checkbox indeterminate />
+ * ```
+ *
+ * @bestPractice A bare `Checkbox` has no label - pair it with a `Label` (`htmlFor`) or use `CheckboxField`, which wires `id`/`htmlFor`/`aria-describedby` for you.
+ * @bestPractice Set the mixed state via the `indeterminate` prop; `checked` stays a boolean.
+ * @bestPractice Controlled use needs `checked` + `onCheckedChange` together; passing only `checked` freezes the box - use `defaultChecked` for uncontrolled.
+ * @bestPractice For a selectable card or a label+description row, reach for `CheckboxCardGroup`/`CheckboxField` instead of hand-laying-out around `Checkbox`.
+ * @category forms
+ */
+declare const Checkbox: ({ className, size, ...props }: CheckboxProps) => React.JSX.Element;
+export { Checkbox };

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

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { Check, Minus } from "lucide-react";
+import { getResponsiveSizeClasses } from "../../tokens/responsive.js";
+import { SQUARE_CONTROL_SIZE_CLASSES } from "../../tokens/square-control.js";
+import { Icon } from "../icon.js";
+/** Default Checkbox size. */
+export const DEFAULT_CHECKBOX_SIZE = "xs";
+/**
+ * Base checkbox styling (everything except `size`, which is resolved
+ * responsively in the component via the shared `SQUARE_CONTROL_SIZE_CLASSES`
+ * map so `size` can be a single token or a per-breakpoint object).
+ */
+const checkboxVariants = cva(cn("group peer bg-input ring-offset-background shrink-0 rounded-md border border-gray-400 shadow-xs disabled:cursor-not-allowed disabled:opacity-50", focusRing(), "aria-invalid:border-destructive/60 aria-invalid:ring-destructive/10 dark:aria-invalid:border-destructive dark:aria-invalid:ring-destructive/20", "[[data-invalid=true]_&]:border-destructive/60 [[data-invalid=true]_&]:ring-destructive/10 dark:[[data-invalid=true]_&]:border-destructive dark:[[data-invalid=true]_&]:ring-destructive/20", "data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground data-indeterminate:border-primary data-indeterminate:bg-primary data-indeterminate:text-primary-foreground"));
+/**
+ * Renders a checkbox input with support for checked, unchecked, and indeterminate states.
+ *
+ * @param props - The checkbox props
+ * @param props.size - Checkbox size using shared ComponentSize scale. Defaults to "sm".
+ * @param props.checked - Controlled checked state. Use with onCheckedChange.
+ * @param props.indeterminate - Show the mixed state (dash icon). Independent of `checked`.
+ * @param props.defaultChecked - Uncontrolled default checked state.
+ * @param props.onCheckedChange - Callback when checked state changes.
+ * @param props.disabled - Disable the checkbox. Defaults to false.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other Base UI Checkbox.Root props.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox checked={checked} onCheckedChange={setChecked} />
+ * <Checkbox defaultChecked size="lg" />
+ * <Checkbox indeterminate />
+ * ```
+ *
+ * @bestPractice A bare `Checkbox` has no label - pair it with a `Label` (`htmlFor`) or use `CheckboxField`, which wires `id`/`htmlFor`/`aria-describedby` for you.
+ * @bestPractice Set the mixed state via the `indeterminate` prop; `checked` stays a boolean.
+ * @bestPractice Controlled use needs `checked` + `onCheckedChange` together; passing only `checked` freezes the box - use `defaultChecked` for uncontrolled.
+ * @bestPractice For a selectable card or a label+description row, reach for `CheckboxCardGroup`/`CheckboxField` instead of hand-laying-out around `Checkbox`.
+ * @category forms
+ */
+const Checkbox = ({ className, size, ...props }) => (_jsx(CheckboxPrimitive.Root, { nativeButton: true, render: (buttonProps) => _jsx("button", { type: "button", ...buttonProps }), className: cn(checkboxVariants(), getResponsiveSizeClasses(size, SQUARE_CONTROL_SIZE_CLASSES, DEFAULT_CHECKBOX_SIZE), className), "data-slot": "checkbox", ...props, children: _jsxs(CheckboxPrimitive.Indicator, { className: cn("flex items-center justify-center text-current"), children: [_jsx(Icon, { className: "group-data-indeterminate:hidden", icon: Check }), _jsx(Icon, { className: "hidden group-data-indeterminate:block", icon: Minus })] }) }));
+export { Checkbox };

package/dist/components/checkbox-card/checkbox-card-anatomy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * checkboxCardAnatomy helper for CheckboxCard.
+ * Import from "@instruments/materia-ui/components/checkbox-card".
+ */
+export declare const checkboxCardAnatomy: import("../../tokens/anatomy.js").ComponentAnatomy;

package/dist/components/checkbox-card/checkbox-card-anatomy.js

@@ -0,0 +1,41 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * checkboxCardAnatomy helper for CheckboxCard.
+ * Import from "@instruments/materia-ui/components/checkbox-card".
+ */
+export const checkboxCardAnatomy = defineAnatomy({
+    children: [
+        {
+            children: [
+                {
+                    description: "Leading icon or checkbox indicator",
+                    label: "CheckboxCardIcon",
+                    slot: "checkbox-card-icon",
+                },
+                {
+                    children: [
+                        {
+                            description: "Option label",
+                            label: "CheckboxCardTitle",
+                            slot: "checkbox-card-title",
+                        },
+                        {
+                            description: "Supporting detail for the option",
+                            label: "CheckboxCardDescription",
+                            slot: "checkbox-card-description",
+                        },
+                    ],
+                    description: "Text stack with title and description",
+                    label: "CheckboxCardContent",
+                    slot: "checkbox-card-content",
+                },
+            ],
+            description: "Selectable card representing a single option",
+            label: "CheckboxCard",
+            slot: "checkbox-card-item",
+        },
+    ],
+    description: "Multi-select group of option cards",
+    label: "CheckboxCardGroup",
+    slot: "checkbox-card-group",
+});

package/dist/components/checkbox-card/checkbox-card-content.d.ts

@@ -0,0 +1,3 @@
+import type React from "react";
+/** Vertical layout wrapper stacking a card's title and description. */
+export declare const CheckboxCardContent: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

package/dist/components/checkbox-card/checkbox-card-content.js

@@ -0,0 +1,6 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../flex.js";
+/** Vertical layout wrapper stacking a card's title and description. */
+export const CheckboxCardContent = ({ className, ...props }) => (_jsx(Flex, { className: cn("gap-1.5 text-left", className), "data-component": "checkbox-card-content", "data-slot": "checkbox-card-content", direction: "column", ...props }));

package/dist/components/checkbox-card/checkbox-card-context.d.ts

@@ -0,0 +1,29 @@
+import type { LucideIcon } from "lucide-react";
+import type React from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+/** Checkbox card context value type definition */
+export interface CheckboxCardContextValue {
+    /** Whether the group is disabled */
+    disabled?: boolean | undefined;
+    /** Icon to display instead of the indicator */
+    icon?: (LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>) | undefined;
+    /** Position of the indicator/icon */
+    indicatorSide?: "start" | "end" | undefined;
+    /** Name for form submission */
+    name?: string | undefined;
+    /** Callback when checked state changes */
+    onCheckedChange?: ((value: string, checked: boolean) => void) | undefined;
+    /** Whether the group is required */
+    required?: boolean | undefined;
+    /** Show indicator */
+    showIndicator?: boolean | undefined;
+    /** Component size */
+    size?: ComponentSize | undefined;
+    /** Controlled checked values */
+    value?: string[] | undefined;
+}
+/**
+ * CheckboxCardContext UI component.
+ * Import from "@instruments/materia-ui/components/checkbox-card".
+ */
+export declare const CheckboxCardContext: React.Context<CheckboxCardContextValue>;

package/dist/components/checkbox-card/checkbox-card-context.js

@@ -0,0 +1,11 @@
+"use client";
+import { createContext } from "react";
+/**
+ * CheckboxCardContext UI component.
+ * Import from "@instruments/materia-ui/components/checkbox-card".
+ */
+export const CheckboxCardContext = createContext({
+    indicatorSide: "start",
+    showIndicator: true,
+    size: "base",
+});

package/dist/components/checkbox-card/checkbox-card-description.d.ts

@@ -0,0 +1,3 @@
+import type React from "react";
+/** Secondary muted helper text for a checkbox card. */
+export declare const CheckboxCardDescription: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

package/dist/components/checkbox-card/checkbox-card-description.js

@@ -0,0 +1,5 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** Secondary muted helper text for a checkbox card. */
+export const CheckboxCardDescription = ({ className, ...props }) => (_jsx("div", { className: cn("text-muted-foreground text-caption", className), "data-component": "checkbox-card-description", "data-slot": "checkbox-card-description", ...props }));

package/dist/components/checkbox-card/checkbox-card-icon.d.ts

@@ -0,0 +1,8 @@
+import type React from "react";
+/**
+ * CheckboxCardIcon UI component.
+ * Renders a simple icon container without any box styling.
+ * Icons should be 20px (size-5) for standard use.
+ * Import from "@instruments/materia-ui/components/checkbox-card".
+ */
+export declare const CheckboxCardIcon: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

package/dist/components/checkbox-card/checkbox-card-icon.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Center } from "../center.js";
+/**
+ * CheckboxCardIcon UI component.
+ * Renders a simple icon container without any box styling.
+ * Icons should be 20px (size-5) for standard use.
+ * Import from "@instruments/materia-ui/components/checkbox-card".
+ */
+export const CheckboxCardIcon = ({ className, ...props }) => (_jsx(Center, { className: cn("text-muted-foreground shrink-0 [&_svg]:size-5", className), "data-component": "checkbox-card-icon", "data-slot": "checkbox-card-icon", ...props }));

package/dist/components/checkbox-card/checkbox-card-item.d.ts

@@ -0,0 +1,32 @@
+import type { LucideIcon } from "lucide-react";
+import type React from "react";
+export interface CheckboxCardProps extends Omit<React.ComponentProps<"div">, "onChange" | "defaultChecked" | "defaultValue"> {
+    /** Controlled checked state */
+    checked?: boolean | undefined;
+    /** Default checked state for uncontrolled usage */
+    defaultChecked?: boolean | undefined;
+    /** Whether the checkbox is disabled */
+    disabled?: boolean | undefined;
+    /** Icon to display as indicator (overrides group-level icon) */
+    icon?: (LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>) | undefined;
+    /** Name for form submission */
+    name?: string | undefined;
+    /** Callback when checked state changes */
+    onCheckedChange?: ((checked: boolean) => void) | undefined;
+    /** Whether the checkbox is required */
+    required?: boolean | undefined;
+    /** Icon to display at the end of the card */
+    suffixIcon?: (LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>) | undefined;
+    /** Value for form submission */
+    value?: string | undefined;
+}
+/**
+ * A single selectable card within a `CheckboxCardGroup`. The whole card is
+ * the Base UI checkbox (`Checkbox.Root` rendered as an `InputCard`): one tab
+ * stop per card, toggled with Space or a click.
+ *
+ * Checked state resolves controlled (`checked`) → group-controlled (the
+ * group's `checkedValues`, for cards with a `value`) → uncontrolled
+ * (`defaultChecked`).
+ */
+export declare const CheckboxCard: ({ className, children, checked, defaultChecked, onCheckedChange, disabled, value, name, required, icon: itemIcon, suffixIcon, ...props }: CheckboxCardProps) => React.JSX.Element;

package/dist/components/checkbox-card/checkbox-card-item.js

@@ -0,0 +1,54 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check } from "lucide-react";
+import { use } from "react";
+import { CONTROL_LINE_CLASSES } from "../../tokens/control-line.js";
+import { SQUARE_CONTROL_SIZE_CLASSES } from "../../tokens/square-control.js";
+import { Center } from "../center.js";
+import { CheckboxCardContext } from "../checkbox-card/checkbox-card-context.js";
+import { Flex } from "../flex.js";
+import { InputCard, InputCardIcon } from "../input-card/input-card-root.js";
+const hasStringValue = (value) => value !== undefined && value !== null && value !== "";
+/**
+ * The checkbox box drawn inside a card. Purely visual - the card itself is
+ * the checkbox - so it mirrors `Checkbox`'s look at the fixed "xs" size.
+ */
+const CheckboxCardBox = ({ checked }) => (_jsx("span", { className: cn(CONTROL_LINE_CLASSES, "text-paragraph-sm"), children: _jsx(Center, { "aria-hidden": true, as: "span", className: cn("bg-input pointer-events-none shrink-0 rounded-md border border-gray-400 shadow-xs", "data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground", SQUARE_CONTROL_SIZE_CLASSES.xs), "data-checked": checked ? "" : undefined, "data-slot": "checkbox", children: _jsx(CheckboxPrimitive.Indicator, { className: "flex items-center justify-center text-current", children: _jsx(Check, {}) }) }) }));
+/**
+ * A single selectable card within a `CheckboxCardGroup`. The whole card is
+ * the Base UI checkbox (`Checkbox.Root` rendered as an `InputCard`): one tab
+ * stop per card, toggled with Space or a click.
+ *
+ * Checked state resolves controlled (`checked`) → group-controlled (the
+ * group's `checkedValues`, for cards with a `value`) → uncontrolled
+ * (`defaultChecked`).
+ */
+export const CheckboxCard = ({ className, children, checked, defaultChecked, onCheckedChange, disabled, value, name, required, icon: itemIcon, suffixIcon, ...props }) => {
+    const { showIndicator, size = "base", indicatorSide = "start", icon: groupIcon, disabled: groupDisabled, name: groupName, onCheckedChange: onGroupCheckedChange, required: groupRequired, } = use(CheckboxCardContext);
+    const isDisabled = disabled ?? groupDisabled ?? false;
+    const icon = itemIcon ?? groupIcon;
+    const resolvedName = name ?? groupName;
+    const resolvedRequired = required ?? groupRequired;
+    const handleCheckedChange = (state) => {
+        onCheckedChange?.(state);
+        if (hasStringValue(value)) {
+            onGroupCheckedChange?.(value, state);
+        }
+    };
+    return (_jsx(CheckboxPrimitive.Root, { className: className, "data-component": "checkbox-card-item", "data-slot": "checkbox-card-item", disabled: isDisabled, nativeButton: false, onCheckedChange: handleCheckedChange, render: (rootProps, state) => {
+            const isChecked = state.checked;
+            let indicator = null;
+            if (icon) {
+                indicator = (_jsx(InputCardIcon, { icon: icon, selected: isChecked, size: size }));
+            }
+            else if (showIndicator === true) {
+                indicator = _jsx(CheckboxCardBox, { checked: isChecked });
+            }
+            const suffixIconElement = suffixIcon ? (_jsx(InputCardIcon, { icon: suffixIcon, selected: isChecked, size: size })) : null;
+            return (_jsx(InputCard, { ...rootProps, disabled: state.disabled, selected: isChecked, size: size, children: _jsx(Flex, { align: "flex-start", gap: "sm", ...props, children: indicatorSide === "start" ? (_jsxs(_Fragment, { children: [indicator, children, suffixIconElement] })) : (_jsxs(_Fragment, { children: [suffixIconElement, children, indicator] })) }) }));
+        }, ...(checked === undefined ? {} : { checked }), ...(defaultChecked === undefined ? {} : { defaultChecked }), ...(resolvedName === undefined ? {} : { name: resolvedName }), ...(resolvedRequired === undefined
+            ? {}
+            : { required: resolvedRequired }), ...(value === undefined ? {} : { value }) }));
+};

package/dist/components/checkbox-card/checkbox-card-root.d.ts

@@ -0,0 +1,36 @@
+import type { LucideIcon } from "lucide-react";
+import type React from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+export interface CheckboxCardGroupProps extends Omit<React.ComponentProps<"div">, "defaultValue"> {
+    /** Controlled checked values */
+    checkedValues?: string[];
+    /** Whether the group is disabled */
+    disabled?: boolean;
+    /** Icon to display instead of the indicator */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Position of the indicator/icon. @default "start" */
+    indicatorSide?: "start" | "end";
+    /** Name for form submission */
+    name?: string;
+    /** Callback when an item changes */
+    onCheckedChange?: (value: string, checked: boolean) => void;
+    /** Whether the group is required */
+    required?: boolean;
+    /** Show the checkbox indicator on each item. @default true */
+    showIndicator?: boolean;
+    /** @default "base" */
+    size?: ComponentSize;
+}
+/**
+ * Multi-select group of `CheckboxCard`s presented as interactive cards.
+ * Shares size, indicator, icon, and checked state with its items via context.
+ * With `checkedValues` it is a Base UI `CheckboxGroup` (`role="group"`) that
+ * owns which cards with a `value` are checked.
+ *
+ * @bestPractice Use `CheckboxCardGroup` for multi-select cards and `RadioCardGroup` for single-select - a checkbox group lets any number be on at once.
+ * @bestPractice Set `size`/`icon`/`indicatorSide`/`showIndicator` once on the group; every `CheckboxCard` reads them from context - don't repeat them per item.
+ * @bestPractice To control the set, give each card a `value`, drive `checkedValues` (a `string[]`) and toggle inside `onCheckedChange(value, checked)`; without `checkedValues` each card keeps its own `checked`/`defaultChecked`.
+ * @bestPractice Each card is one tab stop and toggles with Space; checkboxes don't rove, so Tab (not the arrow keys) moves between cards.
+ * @category forms
+ */
+export declare const CheckboxCardGroup: ({ className, checkedValues, showIndicator, size, indicatorSide, icon, disabled, name, onCheckedChange, required, ...props }: CheckboxCardGroupProps) => React.JSX.Element;

package/dist/components/checkbox-card/checkbox-card-root.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CheckboxGroup as CheckboxGroupPrimitive } from "@base-ui/react/checkbox-group";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useMemo } from "react";
+import { CheckboxCardContext } from "../checkbox-card/checkbox-card-context.js";
+/**
+ * Multi-select group of `CheckboxCard`s presented as interactive cards.
+ * Shares size, indicator, icon, and checked state with its items via context.
+ * With `checkedValues` it is a Base UI `CheckboxGroup` (`role="group"`) that
+ * owns which cards with a `value` are checked.
+ *
+ * @bestPractice Use `CheckboxCardGroup` for multi-select cards and `RadioCardGroup` for single-select - a checkbox group lets any number be on at once.
+ * @bestPractice Set `size`/`icon`/`indicatorSide`/`showIndicator` once on the group; every `CheckboxCard` reads them from context - don't repeat them per item.
+ * @bestPractice To control the set, give each card a `value`, drive `checkedValues` (a `string[]`) and toggle inside `onCheckedChange(value, checked)`; without `checkedValues` each card keeps its own `checked`/`defaultChecked`.
+ * @bestPractice Each card is one tab stop and toggles with Space; checkboxes don't rove, so Tab (not the arrow keys) moves between cards.
+ * @category forms
+ */
+export const CheckboxCardGroup = ({ className, checkedValues, showIndicator = true, size = "base", indicatorSide = "start", icon, disabled, name, onCheckedChange, required, ...props }) => {
+    const contextValue = useMemo(() => ({
+        disabled,
+        icon,
+        indicatorSide,
+        name,
+        onCheckedChange,
+        required,
+        showIndicator,
+        size,
+        value: checkedValues,
+    }), [
+        disabled,
+        icon,
+        indicatorSide,
+        name,
+        onCheckedChange,
+        required,
+        showIndicator,
+        size,
+        checkedValues,
+    ]);
+    const groupProps = {
+        className: cn("grid gap-3", className),
+        "data-component": "checkbox-card-group",
+        "data-slot": "checkbox-card-group",
+        ...props,
+    };
+    return (_jsx(CheckboxCardContext.Provider, { value: contextValue, children: checkedValues === undefined ? (_jsx("div", { ...groupProps })) : (_jsx(CheckboxGroupPrimitive, { value: checkedValues, ...(disabled === undefined ? {} : { disabled }), ...groupProps })) }));
+};

package/dist/components/checkbox-card/checkbox-card-title.d.ts

@@ -0,0 +1,3 @@
+import type React from "react";
+/** Primary label text for a checkbox card. */
+export declare const CheckboxCardTitle: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

package/dist/components/checkbox-card/checkbox-card-title.js

@@ -0,0 +1,5 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** Primary label text for a checkbox card. */
+export const CheckboxCardTitle = ({ className, ...props }) => (_jsx("div", { className: cn("text-paragraph-sm font-medium", className), "data-component": "checkbox-card-title", "data-slot": "checkbox-card-title", ...props }));

package/dist/components/checkbox-card.d.ts

@@ -0,0 +1,7 @@
+export { checkboxCardAnatomy } from "./checkbox-card/checkbox-card-anatomy.js";
+export { CheckboxCardContent } from "./checkbox-card/checkbox-card-content.js";
+export { CheckboxCardDescription } from "./checkbox-card/checkbox-card-description.js";
+export { CheckboxCardIcon } from "./checkbox-card/checkbox-card-icon.js";
+export { CheckboxCard, type CheckboxCardProps, } from "./checkbox-card/checkbox-card-item.js";
+export { CheckboxCardGroup, type CheckboxCardGroupProps, } from "./checkbox-card/checkbox-card-root.js";
+export { CheckboxCardTitle } from "./checkbox-card/checkbox-card-title.js";

package/dist/components/checkbox-card.js

@@ -0,0 +1,7 @@
+export { checkboxCardAnatomy } from "./checkbox-card/checkbox-card-anatomy.js";
+export { CheckboxCardContent } from "./checkbox-card/checkbox-card-content.js";
+export { CheckboxCardDescription } from "./checkbox-card/checkbox-card-description.js";
+export { CheckboxCardIcon } from "./checkbox-card/checkbox-card-icon.js";
+export { CheckboxCard, } from "./checkbox-card/checkbox-card-item.js";
+export { CheckboxCardGroup, } from "./checkbox-card/checkbox-card-root.js";
+export { CheckboxCardTitle } from "./checkbox-card/checkbox-card-title.js";

package/dist/components/checkbox-field/checkbox-field-root.d.ts

@@ -0,0 +1,26 @@
+import type { CheckboxProps } from "@instruments/materia-ui/components/checkbox";
+import type * as React from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+export type CheckboxFieldProps = Omit<CheckboxProps, "size"> & {
+    /** Clickable label rendered beside the checkbox. */
+    label: React.ReactNode;
+    /** Optional helper text below the label; wired to the checkbox via `aria-describedby`. */
+    description?: React.ReactNode;
+    /** @default "xs" */
+    size?: Extract<ComponentSize, "xs" | "sm">;
+    checkboxClassName?: string;
+    labelClassName?: string;
+    descriptionClassName?: string;
+};
+/**
+ * Checkbox paired with a label and optional description in a Base UI
+ * `Field`, which associates the label with the checkbox and links the
+ * description through `aria-describedby`; forwards checkbox state props to
+ * the underlying Checkbox.
+ *
+ * @bestPractice Use `CheckboxField` for a single labelled checkbox - its `Field` wires the label and `aria-describedby` you'd otherwise hand-roll around a bare `Checkbox`.
+ * @bestPractice Put helper text in `description` (linked via `aria-describedby`), not a separate sibling element the screen reader won't announce with the control.
+ * @bestPractice `size` accepts only `"xs"`/`"sm"`; for a full selectable card use `CheckboxCardGroup`, and render one `CheckboxField` per option for a set.
+ * @category forms
+ */
+export declare const CheckboxField: ({ label, description, className, checkboxClassName, labelClassName, descriptionClassName, size, disabled, ...checkboxProps }: CheckboxFieldProps) => React.JSX.Element;

package/dist/components/checkbox-field/checkbox-field-root.js

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { Checkbox } from "@instruments/materia-ui/components/checkbox";
+import { Grid } from "@instruments/materia-ui/components/grid";
+import { Label } from "@instruments/materia-ui/components/label";
+import { Text } from "@instruments/materia-ui/components/text";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { CONTROL_LINE_CLASSES } from "../../tokens/control-line.js";
+/**
+ * Checkbox paired with a label and optional description in a Base UI
+ * `Field`, which associates the label with the checkbox and links the
+ * description through `aria-describedby`; forwards checkbox state props to
+ * the underlying Checkbox.
+ *
+ * @bestPractice Use `CheckboxField` for a single labelled checkbox - its `Field` wires the label and `aria-describedby` you'd otherwise hand-roll around a bare `Checkbox`.
+ * @bestPractice Put helper text in `description` (linked via `aria-describedby`), not a separate sibling element the screen reader won't announce with the control.
+ * @bestPractice `size` accepts only `"xs"`/`"sm"`; for a full selectable card use `CheckboxCardGroup`, and render one `CheckboxField` per option for a set.
+ * @category forms
+ */
+export const CheckboxField = ({ label, description, className, checkboxClassName, labelClassName, descriptionClassName, size = "xs", disabled, ...checkboxProps }) => {
+    const hasDescription = description !== undefined && description !== null;
+    return (_jsxs(FieldPrimitive.Root, { className: cn("flex items-start gap-3", className), children: [_jsx("span", { className: cn(CONTROL_LINE_CLASSES, "text-paragraph-sm"), children: _jsx(Checkbox, { className: checkboxClassName, disabled: disabled, size: size, ...checkboxProps }) }), _jsxs(Grid, { columns: "none", gap: "2xs", children: [_jsx(FieldPrimitive.Label, { className: cn("cursor-pointer font-medium", disabled === true ? "cursor-not-allowed opacity-60" : null, labelClassName), render: _jsx(Label, {}), children: label }), hasDescription ? (_jsx(FieldPrimitive.Description, { render: _jsx(Text, { className: descriptionClassName, size: "paragraph-sm", variant: "muted" }), children: description })) : null] })] }));
+};