@instruments/materia-ui 0.1.0

package/dist/components/grid/grid-col.d.ts

@@ -0,0 +1,33 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement } from "../../tokens/element.js";
+import type { ResponsiveMode, LayoutResponsiveValue } from "../../tokens/responsive.js";
+import type { OrderValue } from "../../tokens/responsive-classes.js";
+export interface GridColProps extends useRender.ComponentProps<"div"> {
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). The set is deliberately closed: `as="button"` is a
+     * type error, because the design-system answer is the Button component. Ref
+     * and event-handler types remain the default element's (HTMLDivElement).
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <GridCol as="li">
+     */
+    as?: LayoutElement;
+    /** CSS order value (1-12, "first", "last", "none"). Can be responsive. */
+    order?: LayoutResponsiveValue<OrderValue>;
+    /** Responsive mode: "screen" (viewport) or "container" (container queries). */
+    responsiveMode?: ResponsiveMode;
+    /** Number of columns this item spans. Can be responsive. */
+    span?: LayoutResponsiveValue<number>;
+    /** Column start position (1-based). Can be responsive. */
+    start?: LayoutResponsiveValue<number>;
+}
+/**
+ * A column within a `Grid` that sets its span, start position, and order; each of
+ * these accepts a responsive object keyed by breakpoint.
+ *
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary.
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ */
+export declare const GridCol: ({ as, className, span, start, order, ref, render, responsiveMode, ...props }: GridColProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/grid/grid-col.js

@@ -0,0 +1,34 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { getResponsiveClasses } from "../../tokens/responsive.js";
+import { ORDER_CLASS } from "../../tokens/responsive-classes.js";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+import { COL_SPAN_CLASS, COL_START_CLASS } from "../grid/grid-utils.js";
+/**
+ * A column within a `Grid` that sets its span, start position, and order; each of
+ * these accepts a responsive object keyed by breakpoint.
+ *
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary.
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ */
+export const GridCol = ({ as, className, span = 1, start, order, ref, render, responsiveMode = "screen", ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("GridCol: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    const classes = [
+        ...getResponsiveClasses(span, COL_SPAN_CLASS, responsiveMode),
+        ...getResponsiveClasses(start, COL_START_CLASS, responsiveMode),
+        ...getResponsiveClasses(order, ORDER_CLASS, responsiveMode),
+    ];
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn(classes.join(" "), className),
+            "data-component": "grid-col",
+            "data-slot": "grid-col",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

package/dist/components/grid/grid-col.test-d.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Type-level surface guards for GridCol's closed `as` vocabulary and `render` prop.
+ *
+ * Evaluated by `tsc --noEmit` (the `typecheck` gate), not by vitest.
+ */
+import type { ComponentProps, ReactElement } from "react";
+import type { GridCol } from "./grid-col.js";
+/** Passes only when `T` is exactly `true`. */
+type Expect<T extends true> = T;
+/** Boolean negation at the type level. */
+type Not<B extends boolean> = B extends true ? false : true;
+/** `true` iff a value of type `V` is accepted as GridCol props. */
+type Accepts<V> = V extends ComponentProps<typeof GridCol> ? true : false;
+export type NavAccepted = Expect<Accepts<{
+    as: "nav";
+}>>;
+export type ButtonRejected = Expect<Not<Accepts<{
+    as: "button";
+}>>>;
+export type AnchorRejected = Expect<Not<Accepts<{
+    as: "a";
+}>>>;
+export type RenderAccepted = Expect<Accepts<{
+    render: ReactElement;
+}>>;
+export type ArgsNonNever = Expect<Not<[ComponentProps<typeof GridCol>] extends [never] ? true : false>>;
+export type SpanBreakpointAccepted = Expect<Accepts<{
+    span: {
+        base: 12;
+        md: 6;
+    };
+}>>;
+export type SpanContainerKeyRejected = Expect<Not<Accepts<{
+    span: {
+        base: 12;
+        "@md": 6;
+    };
+}>>>;
+export {};

package/dist/components/grid/grid-col.test-d.js

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

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

@@ -0,0 +1,65 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { FlexAlign } from "../../tokens/alignment.js";
+import type { LayoutElement, LayoutHostAttributes, LayoutHostKey } from "../../tokens/element.js";
+import type { FlexJustify } from "../../tokens/justify.js";
+import type { ResponsiveMode, LayoutResponsiveValue } from "../../tokens/responsive.js";
+import type { GapSize } from "../../tokens/responsive-classes.js";
+export interface GridProps extends Omit<useRender.ComponentProps<"div">, LayoutHostKey>, LayoutHostAttributes {
+    /** Align items on the block axis. Can be responsive. */
+    align?: LayoutResponsiveValue<FlexAlign>;
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). The set is deliberately closed: `as="button"` is a
+     * type error, because the design-system answer is the Button component. Event handlers
+     * and the ref accept any host element.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <Grid as="section">
+     */
+    as?: LayoutElement;
+    /**
+     * Total columns in the layout. Can be a number or responsive object. Defaults to 12.
+     * `"none"` sets no column template: tracks are implicit (or come from
+     * `className`, such as `grid-cols-[2fr_3fr]` or `grid-rows-[1fr]`), and no
+     * default `align`/`justify` is emitted, so the grid behaves like a plain CSS
+     * grid whose implicit tracks stretch to fill it.
+     */
+    columns?: LayoutResponsiveValue<number> | "none";
+    /** Gap between items. Can be responsive. Defaults to "base" (16px). */
+    gap?: LayoutResponsiveValue<GapSize>;
+    /** When true, columns grow equally to fill available space. */
+    grow?: boolean;
+    /** Render as inline-grid instead of grid. @default false */
+    inline?: boolean;
+    /** Justify items on the inline axis. Can be responsive. */
+    justify?: LayoutResponsiveValue<FlexJustify>;
+    /** Responsive mode: "screen" (viewport) or "container" (container queries). */
+    responsiveMode?: ResponsiveMode;
+    /** Horizontal gap between items. Can be responsive. Overrides gap on inline axis. */
+    xGap?: LayoutResponsiveValue<GapSize>;
+    /** Vertical gap between items. Can be responsive. Overrides gap on block axis. */
+    yGap?: LayoutResponsiveValue<GapSize>;
+}
+/**
+ * CSS Grid layout with configurable columns, gaps, and alignment; `columns`,
+ * the gaps and the alignment props accept a responsive object keyed by
+ * breakpoint. Compose column spans with `GridCol` children.
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={12} gap="base">
+ *   <GridCol span={6}>Half width</GridCol>
+ *   <GridCol span={6}>Half width</GridCol>
+ * </Grid>
+ * <Grid columns={{ base: 1, md: 2, lg: 4 }} responsiveMode="container" />
+ * ```
+ *
+ * @bestPractice `Grid` gives full 2-D control - compose `GridCol` children with `span`/start/order; if you only need equal-width responsive columns, `SimpleGrid` is lighter.
+ * @bestPractice `columns`, `gap`, and alignment each accept a per-breakpoint object; `responsiveMode="container"` resolves them against the nearest container query.
+ * @bestPractice For a grid whose tracks come from its own className or its children (`grid-cols-[...]`, `grid-flow-col`), pass `columns="none"`: it emits no column classes and no default alignment. `"none"` is a whole value, not a breakpoint key. `inline` (a boolean) renders `inline-grid`.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export declare const Grid: ({ as, className, columns, gap, xGap, yGap, grow, inline, align, justify, ref, render, responsiveMode, ...props }: GridProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

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

@@ -0,0 +1,55 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+import { getGridClasses } from "../grid/grid-utils.js";
+/**
+ * CSS Grid layout with configurable columns, gaps, and alignment; `columns`,
+ * the gaps and the alignment props accept a responsive object keyed by
+ * breakpoint. Compose column spans with `GridCol` children.
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={12} gap="base">
+ *   <GridCol span={6}>Half width</GridCol>
+ *   <GridCol span={6}>Half width</GridCol>
+ * </Grid>
+ * <Grid columns={{ base: 1, md: 2, lg: 4 }} responsiveMode="container" />
+ * ```
+ *
+ * @bestPractice `Grid` gives full 2-D control - compose `GridCol` children with `span`/start/order; if you only need equal-width responsive columns, `SimpleGrid` is lighter.
+ * @bestPractice `columns`, `gap`, and alignment each accept a per-breakpoint object; `responsiveMode="container"` resolves them against the nearest container query.
+ * @bestPractice For a grid whose tracks come from its own className or its children (`grid-cols-[...]`, `grid-flow-col`), pass `columns="none"`: it emits no column classes and no default alignment. `"none"` is a whole value, not a breakpoint key. `inline` (a boolean) renders `inline-grid`.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export const Grid = ({ as, className, columns = 12, gap = "base", xGap, yGap, grow = false, inline = false, align, justify, ref, render, responsiveMode = "screen", ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("Grid: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    // An implicit-track grid keeps the browser's own alignment, so its auto
+    // tracks stretch; an explicit template keeps the stretch / start defaults.
+    const implicitTracks = columns === "none";
+    const gridClasses = getGridClasses({
+        align: align ?? (implicitTracks ? undefined : "stretch"),
+        columns,
+        gap,
+        grow,
+        inline,
+        justify: justify ?? (implicitTracks ? undefined : "flex-start"),
+        mode: responsiveMode,
+        xGap,
+        yGap,
+    });
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn(gridClasses, className),
+            "data-component": "grid",
+            "data-slot": "grid",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

package/dist/components/grid/grid-utils.d.ts

@@ -0,0 +1,19 @@
+import type { FlexAlign } from "../../tokens/alignment.js";
+import type { FlexJustify } from "../../tokens/justify.js";
+import type { ResponsiveMode, LayoutResponsiveValue } from "../../tokens/responsive.js";
+import type { GapSize } from "../../tokens/responsive-classes.js";
+export { COL_SPAN_CLASS, COL_START_CLASS, } from "../../tokens/responsive-classes.js";
+/**
+ * Build all grid classes based on grid props
+ */
+export declare const getGridClasses: ({ columns, gap, xGap, yGap, grow, inline, align, justify, mode, }: {
+    columns?: LayoutResponsiveValue<number> | "none" | undefined;
+    gap?: LayoutResponsiveValue<GapSize> | undefined;
+    xGap?: LayoutResponsiveValue<GapSize> | undefined;
+    yGap?: LayoutResponsiveValue<GapSize> | undefined;
+    grow?: boolean | undefined;
+    inline?: boolean | undefined;
+    align?: LayoutResponsiveValue<FlexAlign> | undefined;
+    justify?: LayoutResponsiveValue<FlexJustify> | undefined;
+    mode?: ResponsiveMode | undefined;
+}) => string[];

package/dist/components/grid/grid-utils.js

@@ -0,0 +1,44 @@
+import { getResponsiveClasses } from "../../tokens/responsive.js";
+import { ALIGN_CLASS, GAP_CLASS, GAP_X_CLASS, GAP_Y_CLASS, GRID_COLS_CLASS, JUSTIFY_CLASS, } from "../../tokens/responsive-classes.js";
+export { COL_SPAN_CLASS, COL_START_CLASS, } from "../../tokens/responsive-classes.js";
+/**
+ * Get column classes for the grid based on column configuration
+ */
+const getColumnClasses = (columns, grow, mode) => {
+    if (grow) {
+        return ["grid-cols-[repeat(auto-fit,minmax(0,1fr))]"];
+    }
+    if (columns === "none") {
+        return [];
+    }
+    return getResponsiveClasses(columns, GRID_COLS_CLASS, mode);
+};
+/**
+ * Build all grid classes based on grid props
+ */
+export const getGridClasses = ({ columns = 12, gap = "base", xGap, yGap, grow = false, inline = false, align, justify, mode = "screen", }) => {
+    const classes = [
+        inline ? "inline-grid" : "grid",
+        ...getColumnClasses(columns, grow, mode),
+    ];
+    // Handle gap - if xGap or yGap are specified, use those instead of gap
+    if (xGap !== undefined || yGap !== undefined) {
+        if (xGap === undefined) {
+            classes.push(...getResponsiveClasses(gap, GAP_X_CLASS, mode));
+        }
+        else {
+            classes.push(...getResponsiveClasses(xGap, GAP_X_CLASS, mode));
+        }
+        if (yGap === undefined) {
+            classes.push(...getResponsiveClasses(gap, GAP_Y_CLASS, mode));
+        }
+        else {
+            classes.push(...getResponsiveClasses(yGap, GAP_Y_CLASS, mode));
+        }
+    }
+    else {
+        classes.push(...getResponsiveClasses(gap, GAP_CLASS, mode));
+    }
+    classes.push(...getResponsiveClasses(align, ALIGN_CLASS, mode), ...getResponsiveClasses(justify, JUSTIFY_CLASS, mode));
+    return classes;
+};

package/dist/components/grid/grid.test-d.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Type-level surface guards for Grid's closed `as` vocabulary and `render` prop.
+ *
+ * Evaluated by `tsc --noEmit` (the `typecheck` gate), not by vitest.
+ */
+import type { ComponentProps, ReactElement } from "react";
+import type { Grid } from "./grid-root.js";
+/** Passes only when `T` is exactly `true`. */
+type Expect<T extends true> = T;
+/** Boolean negation at the type level. */
+type Not<B extends boolean> = B extends true ? false : true;
+/** `true` iff a value of type `V` is accepted as Grid props. */
+type Accepts<V> = V extends ComponentProps<typeof Grid> ? true : false;
+export type NavAccepted = Expect<Accepts<{
+    as: "nav";
+}>>;
+export type ButtonRejected = Expect<Not<Accepts<{
+    as: "button";
+}>>>;
+export type AnchorRejected = Expect<Not<Accepts<{
+    as: "a";
+}>>>;
+export type ColumnsNoneAccepted = Expect<Accepts<{
+    columns: "none";
+}>>;
+export type ColumnsAutoRejected = Expect<Not<Accepts<{
+    columns: "auto";
+}>>>;
+export type InlineAccepted = Expect<Accepts<{
+    inline: true;
+}>>;
+export type RenderAccepted = Expect<Accepts<{
+    render: ReactElement;
+}>>;
+export type ArgsNonNever = Expect<Not<[ComponentProps<typeof Grid>] extends [never] ? true : false>>;
+export {};

package/dist/components/grid/grid.test-d.js

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

package/dist/components/grid.d.ts

@@ -0,0 +1,4 @@
+export type { GridColProps } from "./grid/grid-col.js";
+export { GridCol } from "./grid/grid-col.js";
+export type { GridProps } from "./grid/grid-root.js";
+export { Grid } from "./grid/grid-root.js";

package/dist/components/grid.js

@@ -0,0 +1,2 @@
+export { GridCol } from "./grid/grid-col.js";
+export { Grid } from "./grid/grid-root.js";

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

@@ -0,0 +1,60 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { FlexAlign } from "../../tokens/alignment.js";
+import type { LayoutElement, LayoutHostAttributes, LayoutHostKey } from "../../tokens/element.js";
+import type { FlexJustify } from "../../tokens/justify.js";
+import type { ResponsiveMode, LayoutResponsiveValue } from "../../tokens/responsive.js";
+import type { GapSize } from "../../tokens/responsive-classes.js";
+export interface GroupProps extends Omit<useRender.ComponentProps<"div">, LayoutHostKey>, LayoutHostAttributes {
+    /** Align items (vertical alignment). Can be responsive. */
+    align?: LayoutResponsiveValue<FlexAlign>;
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). The set is deliberately closed: `as="button"` is a
+     * type error, because the design-system answer is the Button component. Event handlers
+     * and the ref accept any host element.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <Group as="nav">
+     */
+    as?: LayoutElement;
+    /** Gap between items. Can be responsive. */
+    gap?: LayoutResponsiveValue<GapSize>;
+    /** Justify content (horizontal alignment). Can be responsive. */
+    position?: LayoutResponsiveValue<FlexJustify>;
+    /** Responsive mode: "screen" (viewport) or "container" (container queries). */
+    responsiveMode?: ResponsiveMode;
+    /** Allow items to wrap. Can be responsive. */
+    wrap?: LayoutResponsiveValue<boolean>;
+}
+/**
+ * Horizontal flex container for grouping related elements with consistent spacing.
+ *
+ * @param props - The group props
+ * @param props.position - Justify content (horizontal alignment). Can be responsive.
+ * @param props.align - Align items (vertical alignment). Can be responsive.
+ * @param props.gap - Gap between items. Can be responsive. Defaults to "base" (16px).
+ * @param props.wrap - Allow items to wrap to next line. Can be responsive. Defaults to false.
+ * @param props.as - Host element from the closed layout vocabulary. Mutually exclusive with `render`.
+ * @param props.render - Replace the rendered `div` with another element or component.
+ * @param props.responsiveMode - "screen" (viewport, default) or "container" (container queries).
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Grouped elements.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <Group gap="sm">
+ *   <Button>Save</Button>
+ *   <Button emphasis="outline">Cancel</Button>
+ * </Group>
+ * <Group gap={{ base: "sm", md: "lg" }} responsiveMode="container" />
+ * ```
+ *
+ * @bestPractice `Group` is a horizontal cluster of related controls (buttons, chips) that can `wrap`; for a vertical stack use `Stack`, for full flex control use `Flex`.
+ * @bestPractice Control horizontal distribution with `position` (its justify prop) and vertical alignment with `align`; both `gap` and `wrap` accept per-breakpoint objects.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export declare const Group: ({ as, className, position, align, gap, wrap, ref, render, responsiveMode, ...props }: GroupProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

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

@@ -0,0 +1,86 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { BREAKPOINTS } from "../../tokens/breakpoint.js";
+import { getResponsiveClasses, isResponsiveValue, } from "../../tokens/responsive.js";
+import { ALIGN_CLASS, GAP_CLASS, JUSTIFY_CLASS, } from "../../tokens/responsive-classes.js";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/** Wrap class map for boolean wrap prop */
+const WRAP_BOOL_CLASS = {
+    false: "flex-nowrap",
+    true: "flex-wrap",
+};
+/**
+ * Horizontal flex container for grouping related elements with consistent spacing.
+ *
+ * @param props - The group props
+ * @param props.position - Justify content (horizontal alignment). Can be responsive.
+ * @param props.align - Align items (vertical alignment). Can be responsive.
+ * @param props.gap - Gap between items. Can be responsive. Defaults to "base" (16px).
+ * @param props.wrap - Allow items to wrap to next line. Can be responsive. Defaults to false.
+ * @param props.as - Host element from the closed layout vocabulary. Mutually exclusive with `render`.
+ * @param props.render - Replace the rendered `div` with another element or component.
+ * @param props.responsiveMode - "screen" (viewport, default) or "container" (container queries).
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Grouped elements.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <Group gap="sm">
+ *   <Button>Save</Button>
+ *   <Button emphasis="outline">Cancel</Button>
+ * </Group>
+ * <Group gap={{ base: "sm", md: "lg" }} responsiveMode="container" />
+ * ```
+ *
+ * @bestPractice `Group` is a horizontal cluster of related controls (buttons, chips) that can `wrap`; for a vertical stack use `Stack`, for full flex control use `Flex`.
+ * @bestPractice Control horizontal distribution with `position` (its justify prop) and vertical alignment with `align`; both `gap` and `wrap` accept per-breakpoint objects.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export const Group = ({ as, className, position = "flex-start", align = "center", gap = "base", wrap = false, ref, render, responsiveMode = "screen", ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("Group: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    // Handle wrap - convert boolean(s) to the "true"/"false" class-map keys.
+    // Iterate known keys (no dynamic-key assertion); layout props carry
+    // breakpoint keys only.
+    const getWrapValue = () => {
+        if (wrap === undefined) {
+            return undefined;
+        }
+        if (!isResponsiveValue(wrap)) {
+            return wrap ? "true" : "false";
+        }
+        const out = {};
+        if (wrap.base !== undefined) {
+            out.base = wrap.base ? "true" : "false";
+        }
+        for (const bp of BREAKPOINTS) {
+            const value = wrap[bp];
+            if (value !== undefined) {
+                out[bp] = value ? "true" : "false";
+            }
+        }
+        return out;
+    };
+    const classes = [
+        "flex",
+        ...getResponsiveClasses(position, JUSTIFY_CLASS, responsiveMode),
+        ...getResponsiveClasses(align, ALIGN_CLASS, responsiveMode),
+        ...getResponsiveClasses(gap, GAP_CLASS, responsiveMode),
+        ...getResponsiveClasses(getWrapValue(), WRAP_BOOL_CLASS, responsiveMode),
+    ];
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn(classes.join(" "), className),
+            "data-component": "group",
+            "data-slot": "group",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

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

@@ -0,0 +1,27 @@
+/**
+ * Type-level surface guards for Group's closed `as` vocabulary and `render` prop.
+ *
+ * Evaluated by `tsc --noEmit` (the `typecheck` gate), not by vitest.
+ */
+import type { ComponentProps, ReactElement } from "react";
+import type { Group } from "./group-root.js";
+/** Passes only when `T` is exactly `true`. */
+type Expect<T extends true> = T;
+/** Boolean negation at the type level. */
+type Not<B extends boolean> = B extends true ? false : true;
+/** `true` iff a value of type `V` is accepted as Group props. */
+type Accepts<V> = V extends ComponentProps<typeof Group> ? true : false;
+export type NavAccepted = Expect<Accepts<{
+    as: "nav";
+}>>;
+export type ButtonRejected = Expect<Not<Accepts<{
+    as: "button";
+}>>>;
+export type AnchorRejected = Expect<Not<Accepts<{
+    as: "a";
+}>>>;
+export type RenderAccepted = Expect<Accepts<{
+    render: ReactElement;
+}>>;
+export type ArgsNonNever = Expect<Not<[ComponentProps<typeof Group>] extends [never] ? true : false>>;
+export {};

package/dist/components/group/group.test-d.js

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

package/dist/components/group.d.ts

@@ -0,0 +1 @@
+export { Group, type GroupProps } from "./group/group-root.js";

package/dist/components/group.js

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

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

@@ -0,0 +1,36 @@
+import type * as React from "react";
+import type { HeadingLevel } from "../../tokens/heading-level.js";
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+/** The type roles Heading renders at, smallest first. */
+export declare const HEADING_SIZES: readonly ["paragraph-sm", "paragraph-lg", "subheading", "subheading-lg", "heading-sm", "heading", "heading-lg", "title"];
+/** A type role Heading renders at; see {@link HEADING_SIZES}. */
+export type HeadingSize = (typeof HEADING_SIZES)[number];
+/**
+ * Maps each {@link HeadingSize} to its role class. The role owns the
+ * font-size, line-height and letter-spacing.
+ */
+declare const SIZE_CLASSES: Record<HeadingSize, string>;
+type HeadingProps = Omit<React.ComponentProps<"h1">, "size"> & {
+    /**
+     * Semantic heading tag rendered (`h1`–`h6`); independent of visual `size`.
+     * @default "2"
+     */
+    level?: HeadingLevel | undefined;
+    /**
+     * Type role - a single role or a responsive object like
+     * `{ base: "heading-sm", md: "heading-lg" }`.
+     * @default "subheading"
+     */
+    size?: ResponsiveValue<HeadingSize> | undefined;
+};
+/**
+ * Renders a semantic heading element with configurable level and size.
+ * `size` names a type role and accepts responsive values:
+ * `size={{ base: "heading-sm", md: "heading-lg" }}`.
+ *
+ * @bestPractice Set `level` (`h1`–`h6`) for the document outline and `size` for visual scale independently - don't pick a tag just to get a size; a small-looking heading can still be an `h2`.
+ * @bestPractice Keep one `h1` per page and don't skip levels for styling; use `size` (responsive-capable) to make a lower-level heading look larger.
+ * @category typography
+ */
+declare const Heading: ({ level, size, className, ...props }: HeadingProps) => React.JSX.Element;
+export { Heading, SIZE_CLASSES as headingSizeClasses };

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

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { getResponsiveSizeClasses } from "../../tokens/responsive.js";
+/** The type roles Heading renders at, smallest first. */
+export const HEADING_SIZES = [
+    "paragraph-sm",
+    "paragraph-lg",
+    "subheading",
+    "subheading-lg",
+    "heading-sm",
+    "heading",
+    "heading-lg",
+    "title",
+];
+/**
+ * Maps each {@link HeadingSize} to its role class. The role owns the
+ * font-size, line-height and letter-spacing.
+ */
+const SIZE_CLASSES = {
+    // 14/20
+    "paragraph-sm": "text-paragraph-sm",
+    // 18/24
+    "paragraph-lg": "text-paragraph-lg",
+    // 20/28, -1%
+    subheading: "text-subheading",
+    // 24/32, -1%
+    "subheading-lg": "text-subheading-lg",
+    // 30/36, -1%
+    "heading-sm": "text-heading-sm",
+    // 36/44, -1%
+    heading: "text-heading",
+    // 48/56, -2%
+    "heading-lg": "text-heading-lg",
+    // 60/72, -2%
+    title: "text-title",
+};
+/**
+ * Renders a semantic heading element with configurable level and size.
+ * `size` names a type role and accepts responsive values:
+ * `size={{ base: "heading-sm", md: "heading-lg" }}`.
+ *
+ * @bestPractice Set `level` (`h1`–`h6`) for the document outline and `size` for visual scale independently - don't pick a tag just to get a size; a small-looking heading can still be an `h2`.
+ * @bestPractice Keep one `h1` per page and don't skip levels for styling; use `size` (responsive-capable) to make a lower-level heading look larger.
+ * @category typography
+ */
+const Heading = ({ level = "2", size, className, ...props }) => {
+    const Tag = `h${level}`;
+    return (_jsx(Tag, { className: cn("trim-both font-semibold", getResponsiveSizeClasses(size, SIZE_CLASSES, "subheading"), className), "data-component": "heading", "data-level": level, ...props }));
+};
+export { Heading, SIZE_CLASSES as headingSizeClasses };

package/dist/components/heading.d.ts

@@ -0,0 +1 @@
+export { HEADING_SIZES, Heading, type HeadingSize, headingSizeClasses, } from "./heading/heading-root.js";

package/dist/components/heading.js

@@ -0,0 +1 @@
+export { HEADING_SIZES, Heading, headingSizeClasses, } from "./heading/heading-root.js";