@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,140 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import useEmblaCarousel from "embla-carousel-react";
+import { WheelGesturesPlugin as wheelGesturesPlugin } from "embla-carousel-wheel-gestures";
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+import { createContext, use, useCallback, useMemo, useSyncExternalStore, } from "react";
+import { Button } from "../button.js";
+import { Flex } from "../flex.js";
+import { createCarouselStore, EMPTY_CAROUSEL_STORE } from "./carousel-store.js";
+const CarouselContext = createContext(null);
+/**
+ * Reads the nearest Carousel's scroll state and controls; throws if used
+ * outside a Carousel.
+ */
+const useCarousel = () => {
+    const context = use(CarouselContext);
+    if (!context) {
+        throw new Error("useCarousel must be used within a Carousel");
+    }
+    return context;
+};
+/**
+ * Embla-backed carousel that shares scroll state and controls with its parts
+ * (CarouselContent, CarouselPrevious/Next, CarouselDots) via context - they
+ * must render inside it.
+ *
+ * @bestPractice Render `CarouselContent`/`CarouselItem`/`CarouselPrevious`/`CarouselNext`/`CarouselDots` only inside `Carousel` - they read scroll state from context and throw ("must be used within a Carousel") outside it.
+ * @bestPractice Set `slidesToShow` to show multiple items at once (it drives each item's `flex-basis`); don't fake a multi-item view with CSS widths on `CarouselItem`.
+ * @bestPractice Tune scroll behaviour via `opts` (Embla options like `loop`/`align`) and enable `wheelScroll`/`freeScroll` deliberately - free-scroll drops snap points, so pass `slideCount` if the dots miscount.
+ * @bestPractice Give a descriptive `aria-label` when the region isn't self-evidently "Carousel" (e.g. `"Product images"`).
+ * @category data
+ */
+const Carousel = ({ "aria-label": ariaLabel = "Carousel", opts, plugins, orientation = "horizontal", slidesToShow = 1, slideCount, freeScroll = false, wheelScroll = false, className, children, }) => {
+    const allPlugins = useMemo(() => {
+        const base = plugins ?? [];
+        if (!wheelScroll) {
+            return base;
+        }
+        return [
+            ...base,
+            wheelGesturesPlugin({
+                forceWheelAxis: orientation === "horizontal" ? "x" : "y",
+            }),
+        ];
+    }, [plugins, wheelScroll, orientation]);
+    const [carouselRef, api] = useEmblaCarousel({
+        ...opts,
+        axis: orientation === "horizontal" ? "x" : "y",
+        dragFree: freeScroll,
+    }, allPlugins);
+    const store = useMemo(() => (api ? createCarouselStore(api) : EMPTY_CAROUSEL_STORE), [api]);
+    const { canScrollNext, canScrollPrev, scrollSnaps, selectedIndex } = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    const scrollPrev = useCallback(() => {
+        api?.scrollPrev();
+    }, [api]);
+    const scrollNext = useCallback(() => {
+        api?.scrollNext();
+    }, [api]);
+    // CSS variable for slides to show (used for flex-basis calculation).
+    // `style` is typed to carry the custom `--*` property CSSProperties lacks.
+    const style = {
+        "--carousel-slides-to-show": slidesToShow,
+    };
+    const contextValue = useMemo(() => ({
+        api,
+        canScrollNext,
+        canScrollPrev,
+        carouselRef,
+        scrollNext,
+        scrollPrev,
+        scrollSnaps,
+        selectedIndex,
+        slideCount,
+    }), [
+        carouselRef,
+        api,
+        scrollPrev,
+        scrollNext,
+        canScrollPrev,
+        canScrollNext,
+        selectedIndex,
+        scrollSnaps,
+        slideCount,
+    ]);
+    return (_jsx(CarouselContext.Provider, { value: contextValue, children: _jsx(Flex, { as: "section", "aria-label": ariaLabel, "aria-roledescription": "carousel", className: cn("relative", className), "data-orientation": orientation, "data-slot": "carousel", direction: "column", style: style, children: children }) }));
+};
+/**
+ * Scroll viewport wrapping the slide track; attaches the Embla ref and clips
+ * overflow. Holds the CarouselItem children.
+ */
+const CarouselContent = ({ className, ...props }) => {
+    const { carouselRef } = useCarousel();
+    return (_jsx(Flex, { className: "flex-1 overflow-hidden", direction: "column", ref: carouselRef, children: _jsx(Flex, { className: cn("flex-1", className), "data-slot": "carousel-content", ...props }) }));
+};
+/**
+ * A single slide; its width follows the parent Carousel's `slidesToShow`.
+ */
+const CarouselItem = ({ className, ...props }) => (_jsx("div", { "aria-roledescription": "slide", className: cn("min-w-0 shrink-0 grow-0 self-stretch", 
+    // Use CSS calc with the variable for flex-basis
+    "basis-[calc(100%/var(--carousel-slides-to-show))]", className), "data-slot": "carousel-item", 
+    // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role -- APG carousel pattern: each slide is a role="group" with aria-roledescription="slide"; the suggested semantic tags (address/fieldset/hgroup) carry the wrong meaning
+    role: "group", ...props }));
+/**
+ * The arrows draw at 32px; an invisible pseudo-element grows the tap target to
+ * 44px without enlarging the control.
+ */
+const ARROW_HIT_AREA = "after:absolute after:-inset-1.5";
+/**
+ * Button that scrolls to the previous slide; auto-disables (and fades out) at
+ * the start of the carousel.
+ */
+const CarouselPrevious = ({ className, ...props }) => {
+    const { scrollPrev, canScrollPrev } = useCarousel();
+    return (_jsx(Button, { "aria-label": "Previous slide", className: cn("absolute top-1/2 left-3 z-10 -translate-y-1/2", ARROW_HIT_AREA, className), "data-slot": "carousel-previous", disabled: !canScrollPrev, emphasis: "outline", icon: ChevronLeftIcon, onClick: scrollPrev, radius: "full", size: "icon-sm", square: true, tone: "neutral", type: "button", ...props }));
+};
+/**
+ * Button that scrolls to the next slide; auto-disables (and fades out) at the
+ * end of the carousel.
+ */
+const CarouselNext = ({ className, ...props }) => {
+    const { scrollNext, canScrollNext } = useCarousel();
+    return (_jsx(Button, { "aria-label": "Next slide", className: cn("absolute top-1/2 right-3 z-10 -translate-y-1/2", ARROW_HIT_AREA, className), "data-slot": "carousel-next", disabled: !canScrollNext, emphasis: "outline", icon: ChevronRightIcon, onClick: scrollNext, radius: "full", size: "icon-sm", square: true, tone: "neutral", type: "button", ...props }));
+};
+/**
+ * Pagination dots that jump to a slide on click; renders nothing when there is
+ * one slide or fewer.
+ */
+const CarouselDots = ({ className, ...props }) => {
+    const { api, selectedIndex, scrollSnaps, slideCount } = useCarousel();
+    // Use explicit slideCount if provided, otherwise fall back to scrollSnaps
+    const dotCount = slideCount ?? scrollSnaps.length;
+    if (dotCount <= 1) {
+        return null;
+    }
+    return (_jsx(Flex, { className: cn("gap-1.5 py-2", className), "data-slot": "carousel-dots", justify: "center", ...props, children: Array.from({ length: dotCount }, (_, i) => i).map((dotIndex) => (_jsx("button", { "aria-current": dotIndex === selectedIndex ? true : undefined, "aria-label": `Go to slide ${String(dotIndex + 1)}`, className: cn("size-2 rounded-full transition-colors", dotIndex === selectedIndex
+                ? "bg-foreground"
+                : "bg-foreground/20 hover:bg-foreground/40"), onClick: () => api?.scrollTo(dotIndex), type: "button" }, dotIndex))) }));
+};
+export { Carousel, CarouselContent, CarouselDots, CarouselItem, CarouselNext, CarouselPrevious, useCarousel, };

package/dist/components/carousel/carousel-store.d.ts

@@ -0,0 +1,22 @@
+import type { UseEmblaCarouselType } from "embla-carousel-react";
+type EmblaApi = NonNullable<UseEmblaCarouselType[1]>;
+/** What the carousel parts render from, read off the Embla API. */
+export interface CarouselSnapshot {
+    canScrollNext: boolean;
+    canScrollPrev: boolean;
+    scrollSnaps: number[];
+    selectedIndex: number;
+}
+interface CarouselStore {
+    getSnapshot: () => CarouselSnapshot;
+    subscribe: (onChange: () => void) => () => void;
+}
+/** Stand-in store used until Embla has produced its API. */
+export declare const EMPTY_CAROUSEL_STORE: CarouselStore;
+/**
+ * Expose an Embla API as an external store: the snapshot is rebuilt only when
+ * Embla reports `select` or `reInit`, so it stays referentially stable between
+ * events. The snap list is read once, when the API arrives.
+ */
+export declare const createCarouselStore: (api: EmblaApi) => CarouselStore;
+export {};

package/dist/components/carousel/carousel-store.js

@@ -0,0 +1,45 @@
+const EMPTY_SNAPSHOT = {
+    canScrollNext: false,
+    canScrollPrev: false,
+    scrollSnaps: [],
+    selectedIndex: 0,
+};
+/** Stand-in store used until Embla has produced its API. */
+export const EMPTY_CAROUSEL_STORE = {
+    getSnapshot: () => EMPTY_SNAPSHOT,
+    subscribe: () => () => {
+        // nothing to observe yet
+    },
+};
+/**
+ * Expose an Embla API as an external store: the snapshot is rebuilt only when
+ * Embla reports `select` or `reInit`, so it stays referentially stable between
+ * events. The snap list is read once, when the API arrives.
+ */
+export const createCarouselStore = (api) => {
+    const scrollSnaps = api.scrollSnapList();
+    const read = () => ({
+        canScrollNext: api.canScrollNext(),
+        canScrollPrev: api.canScrollPrev(),
+        scrollSnaps,
+        selectedIndex: api.selectedScrollSnap(),
+    });
+    let snapshot = read();
+    return {
+        getSnapshot: () => snapshot,
+        subscribe: (onChange) => {
+            const handleChange = () => {
+                snapshot = read();
+                onChange();
+            };
+            // Events may have fired between creating the store and subscribing.
+            snapshot = read();
+            api.on("reInit", handleChange);
+            api.on("select", handleChange);
+            return () => {
+                api.off("select", handleChange);
+                api.off("reInit", handleChange);
+            };
+        },
+    };
+};

package/dist/components/carousel.d.ts

@@ -0,0 +1,2 @@
+export type { CarouselApi, CarouselContentProps, CarouselDotsProps, CarouselItemProps, CarouselNextProps, CarouselPreviousProps, CarouselProps, } from "./carousel/carousel-root.js";
+export { Carousel, CarouselContent, CarouselDots, CarouselItem, CarouselNext, CarouselPrevious, useCarousel, } from "./carousel/carousel-root.js";

package/dist/components/carousel.js

@@ -0,0 +1 @@
+export { Carousel, CarouselContent, CarouselDots, CarouselItem, CarouselNext, CarouselPrevious, useCarousel, } from "./carousel/carousel-root.js";

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

@@ -0,0 +1,62 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement, LayoutHostAttributes, LayoutHostKey } from "../../tokens/element.js";
+export interface CenterProps extends Omit<useRender.ComponentProps<"div">, LayoutHostKey>, LayoutHostAttributes {
+    /**
+     * 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 <Center as="section" />
+     */
+    as?: LayoutElement;
+    /**
+     * Use inline-flex instead of flex for inline centring
+     */
+    inline?: boolean;
+}
+/**
+ * Center centres its children both vertically and horizontally using flexbox.
+ *
+ * **Important:** Children that use CSS Grid with `fr` units must define their own
+ * width (e.g., `w-96`, `max-w-md`). This is because `fr` units require a defined
+ * container width to calculate available space, but flex items without explicit
+ * width use intrinsic sizing - creating a circular dependency where the grid
+ * collapses to minimum content width.
+ *
+ * @example
+ * ```tsx
+ * <Center>
+ *   <Button>Centered Button</Button>
+ * </Center>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Grid children need explicit width
+ * <Center>
+ *   <Card className="w-96">...</Card>
+ * </Center>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Center inline>
+ *   <Icon name="check" />
+ *   <span>Inline centered content</span>
+ * </Center>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Center as="section">Centered section</Center>
+ * ```
+ *
+ * @bestPractice `Center` centres a single child on both axes; grid children using `fr` units need an explicit width (e.g. `w-96`) or they collapse to min-content.
+ * @bestPractice `as`/`render` are mutually exclusive (`render` wins, dev-warned); use `inline` to center inline-level content without breaking the text flow.
+ * @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 Center: ({ as, className, inline, ref, render, ...props }: CenterProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

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

@@ -0,0 +1,61 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * Center centres its children both vertically and horizontally using flexbox.
+ *
+ * **Important:** Children that use CSS Grid with `fr` units must define their own
+ * width (e.g., `w-96`, `max-w-md`). This is because `fr` units require a defined
+ * container width to calculate available space, but flex items without explicit
+ * width use intrinsic sizing - creating a circular dependency where the grid
+ * collapses to minimum content width.
+ *
+ * @example
+ * ```tsx
+ * <Center>
+ *   <Button>Centered Button</Button>
+ * </Center>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Grid children need explicit width
+ * <Center>
+ *   <Card className="w-96">...</Card>
+ * </Center>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Center inline>
+ *   <Icon name="check" />
+ *   <span>Inline centered content</span>
+ * </Center>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Center as="section">Centered section</Center>
+ * ```
+ *
+ * @bestPractice `Center` centres a single child on both axes; grid children using `fr` units need an explicit width (e.g. `w-96`) or they collapse to min-content.
+ * @bestPractice `as`/`render` are mutually exclusive (`render` wins, dev-warned); use `inline` to center inline-level content without breaking the text flow.
+ * @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 Center = ({ as, className, inline = false, ref, render, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("Center: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn("items-center justify-center", inline ? "inline-flex" : "flex", className),
+            "data-component": "center",
+            "data-slot": "center",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

package/dist/components/center.d.ts

@@ -0,0 +1 @@
+export { Center, type CenterProps } from "./center/center-root.js";

package/dist/components/center.js

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

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

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

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

@@ -0,0 +1,34 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * chartAnatomy helper for Chart.
+ * Import from "@instruments/materia-ui/components/chart".
+ */
+export const chartAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Per-series --color-<key> CSS variables emitted from config",
+            label: "ChartStyle",
+            slot: "chart-style",
+        },
+        {
+            children: [
+                {
+                    description: "Themed tooltip surface resolving labels/colors by key",
+                    label: "ChartTooltipContent",
+                    slot: "chart-tooltip-content",
+                },
+                {
+                    description: "Themed legend row of swatches + labels",
+                    label: "ChartLegendContent",
+                    slot: "chart-legend-content",
+                },
+            ],
+            description: "The recharts chart element (BarChart, LineChart, …)",
+            label: "ResponsiveContainer",
+            slot: "chart-surface",
+        },
+    ],
+    description: "Responsive frame + config provider for a recharts chart",
+    label: "Chart",
+    slot: "chart",
+});

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

@@ -0,0 +1,82 @@
+import type * as React from "react";
+/**
+ * Format: `{ THEME_NAME: CSS_SELECTOR }`. Drives {@link ChartStyle}: the empty
+ * light selector emits base vars, the `.dark` selector overrides them under the
+ * design system's dark class (`@custom-variant dark (&:is(.dark *))`).
+ */
+export declare const THEMES: {
+    readonly light: "";
+    readonly dark: ".dark";
+};
+/**
+ * Maps each series key to how it renders in chrome (tooltip, legend): an
+ * optional `label` and `icon`, plus its colour. Supply either a single `color`
+ * (same in light and dark) or a `theme` map of per-mode colours. {@link Chart}
+ * turns each entry into a `--color-<key>` CSS variable the recharts marks read.
+ */
+export type ChartConfig = Record<string, {
+    label?: React.ReactNode;
+    icon?: React.ComponentType;
+} & ({
+    color?: string;
+    theme?: never;
+} | {
+    color?: never;
+    theme: Record<keyof typeof THEMES, string>;
+})>;
+interface ChartContextValue {
+    config: ChartConfig;
+}
+export declare const ChartContext: React.Context<ChartContextValue | null>;
+/**
+ * Read the enclosing {@link Chart}'s config. Throws outside a `<Chart>`, so
+ * tooltip / legend content can resolve labels, icons, and colours by series key.
+ */
+export declare const useChart: () => ChartContextValue;
+/** What recharts offers as a series name: a key, an index, or an accessor. */
+type ConfigKeyCandidate = string | number | ((...args: never[]) => void);
+/**
+ * A recharts series item or datum. Recharts types its data as `any`; the only
+ * structure read from it is the nested `payload` datum, and every other field
+ * is read by name through {@link readStringField}. `dataKey` and `name` are
+ * declared so call sites can describe an item by hand.
+ */
+export interface ChartPayloadSource {
+    readonly dataKey?: ConfigKeyCandidate | undefined;
+    readonly name?: ConfigKeyCandidate | undefined;
+    readonly payload?: ChartPayloadSource | null | undefined;
+}
+type MaybePayloadSource = ChartPayloadSource | null | undefined;
+/**
+ * Read a string field off a payload item or datum (e.g. a recharts datum's
+ * `fill`), returning undefined when it is absent or not a string.
+ */
+export declare const readStringField: (source: MaybePayloadSource, field: string) => string | undefined;
+/** {@link readStringField} on the datum nested in a payload item. */
+export declare const readDatumStringField: (item: ChartPayloadSource, field: string) => string | undefined;
+/**
+ * The config-entry key a payload item resolves to: the string in the item's
+ * `key` field (or its nested datum's), else `key` itself. With
+ * `nameKey="browser"` and a datum `{ browser: "chrome" }` this yields
+ * `"chrome"` - unique per row, so it also serves as the row's React key. Lets
+ * tooltip / legend rows find their label, icon, and colour regardless of how
+ * the series is keyed.
+ */
+export declare const resolveEntryKey: (payload: MaybePayloadSource, key: string) => string;
+export declare const getPayloadConfigFromPayload: (config: ChartConfig, payload: MaybePayloadSource, key: string) => ({
+    label?: React.ReactNode;
+    icon?: React.ComponentType;
+} & ({
+    color?: string;
+    theme?: never;
+} | {
+    color?: never;
+    theme: Record<keyof typeof THEMES, string>;
+})) | undefined;
+/**
+ * First string among the candidates (an explicit `nameKey`/`labelKey`, a
+ * recharts `name`/`dataKey`), falling back to `"value"`. Recharts keys can be
+ * numbers or accessor functions; only a string names a config entry.
+ */
+export declare const resolveConfigKey: (...candidates: readonly (ConfigKeyCandidate | undefined)[]) => string;
+export {};

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

@@ -0,0 +1,60 @@
+"use client";
+import { createContext, useContext } from "react";
+import { isString } from "../../utils/type-guards.js";
+/**
+ * Format: `{ THEME_NAME: CSS_SELECTOR }`. Drives {@link ChartStyle}: the empty
+ * light selector emits base vars, the `.dark` selector overrides them under the
+ * design system's dark class (`@custom-variant dark (&:is(.dark *))`).
+ */
+export const THEMES = { light: "", dark: ".dark" };
+export const ChartContext = createContext(null);
+/**
+ * Read the enclosing {@link Chart}'s config. Throws outside a `<Chart>`, so
+ * tooltip / legend content can resolve labels, icons, and colours by series key.
+ */
+export const useChart = () => {
+    const context = useContext(ChartContext);
+    if (!context) {
+        throw new Error("useChart must be used within a <Chart />");
+    }
+    return context;
+};
+const hasStringValue = (descriptor) => typeof descriptor?.value === "string";
+/**
+ * Read a string field off a payload item or datum (e.g. a recharts datum's
+ * `fill`), returning undefined when it is absent or not a string.
+ */
+export const readStringField = (source, field) => {
+    if (source === null || source === undefined) {
+        return undefined;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(source, field);
+    return hasStringValue(descriptor) ? descriptor.value : undefined;
+};
+/** {@link readStringField} on the datum nested in a payload item. */
+export const readDatumStringField = (item, field) => readStringField(item.payload, field);
+/**
+ * The config-entry key a payload item resolves to: the string in the item's
+ * `key` field (or its nested datum's), else `key` itself. With
+ * `nameKey="browser"` and a datum `{ browser: "chrome" }` this yields
+ * `"chrome"` - unique per row, so it also serves as the row's React key. Lets
+ * tooltip / legend rows find their label, icon, and colour regardless of how
+ * the series is keyed.
+ */
+export const resolveEntryKey = (payload, key) => readStringField(payload, key) ??
+    readStringField(payload?.payload, key) ??
+    key;
+export const getPayloadConfigFromPayload = (config, payload, key) => config[resolveEntryKey(payload, key)] ?? config[key];
+/**
+ * First string among the candidates (an explicit `nameKey`/`labelKey`, a
+ * recharts `name`/`dataKey`), falling back to `"value"`. Recharts keys can be
+ * numbers or accessor functions; only a string names a config entry.
+ */
+export const resolveConfigKey = (...candidates) => {
+    for (const candidate of candidates) {
+        if (isString(candidate) && candidate.length > 0) {
+            return candidate;
+        }
+    }
+    return "value";
+};

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

@@ -0,0 +1,16 @@
+import type * as React from "react";
+import type { DefaultLegendContentProps, LegendProps } from "recharts";
+/** recharts `Legend` - pair it with {@link ChartLegendContent} via `content`. */
+export { Legend as ChartLegend } from "recharts";
+/**
+ * Themed legend row for a {@link Chart}. Pass it to `ChartLegend`'s `content`
+ * prop; it draws one swatch + label per series, resolved from the chart's
+ * `config`. Use `hideIcon` to force colour swatches over any config `icon`, and
+ * `nameKey` to resolve names from a different config key.
+ */
+export declare const ChartLegendContent: ({ className, hideIcon, payload, position, nameKey, }: React.ComponentProps<"div"> & {
+    /** Draw colour swatches even when a series has a config `icon`. */
+    hideIcon?: boolean;
+    /** Config key to resolve each entry's name from (defaults to the datum key). */
+    nameKey?: string;
+} & Pick<DefaultLegendContentProps, "payload"> & Pick<LegendProps, "position">) => React.JSX.Element | null;

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

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Center } from "../center.js";
+import { Flex } from "../flex.js";
+import { getPayloadConfigFromPayload, resolveConfigKey, resolveEntryKey, useChart, } from "./chart-context.js";
+/** recharts `Legend` - pair it with {@link ChartLegendContent} via `content`. */
+export { Legend as ChartLegend } from "recharts";
+/**
+ * Themed legend row for a {@link Chart}. Pass it to `ChartLegend`'s `content`
+ * prop; it draws one swatch + label per series, resolved from the chart's
+ * `config`. Use `hideIcon` to force colour swatches over any config `icon`, and
+ * `nameKey` to resolve names from a different config key.
+ */
+export const ChartLegendContent = ({ className, hideIcon = false, payload, position, nameKey, }) => {
+    const { config } = useChart();
+    if (payload === undefined || payload.length === 0) {
+        return null;
+    }
+    const items = payload.filter((item) => item.type !== "none");
+    return (_jsx(Center, { className: cn("gap-4", position === "top" ? "pb-3" : "pt-3", className), "data-component": "chart-legend-content", "data-slot": "chart-legend-content", children: items.map((item) => {
+            const key = resolveConfigKey(nameKey, item.dataKey);
+            const itemConfig = getPayloadConfigFromPayload(config, item, key);
+            return (_jsxs(Flex, { align: "center", className: "[&>svg]:text-muted-foreground gap-1.5 [&>svg]:h-3 [&>svg]:w-3", children: [itemConfig?.icon && !hideIcon ? (_jsx(itemConfig.icon, {})) : (_jsx("div", { className: "h-2 w-2 shrink-0 rounded-xs", style: { backgroundColor: item.color } })), itemConfig?.label] }, resolveEntryKey(item, key)));
+        }) }));
+};

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

@@ -0,0 +1,31 @@
+import type * as React from "react";
+import { ResponsiveContainer } from "recharts";
+import type { ChartConfig } from "./chart-context.js";
+/**
+ * Responsive frame for a recharts chart. Wraps recharts' `ResponsiveContainer`,
+ * provides the `config` (series keys → label / icon / colour) to every
+ * descendant `ChartTooltipContent` / `ChartLegendContent`, and injects a
+ * `--color-<key>` CSS variable per series so recharts marks can be coloured with
+ * `fill="var(--color-desktop)"`. Pass a single recharts chart element as the
+ * child. It is dimensionless - set the aspect / height with `className`
+ * (defaults to `aspect-video`).
+ *
+ * @bestPractice Colour every series through `config` (`{ desktop: { label, color } }`) and reference `var(--color-<key>)` on the marks - never hardcode a hex on a `Bar` / `Line`; that keeps light/dark theming and the legend/tooltip swatches in sync.
+ * @bestPractice Reach for `Chart` only to render a recharts data visualization; for a static value + delta use `Stat`, and for a progress bar use `Progress`.
+ * @category data
+ */
+export declare const Chart: ({ id, className, children, config, initialDimension, ...props }: React.ComponentProps<"div"> & {
+    /** Series keys → label / icon / colour, injected as `--color-<key>` variables. */
+    config: ChartConfig;
+    /** A single recharts chart element (e.g. `<BarChart>`). */
+    children: React.ComponentProps<typeof ResponsiveContainer>["children"];
+    /**
+     * Width / height the container assumes before it has measured itself - keeps
+     * the first paint (and SSR) from rendering at zero size.
+     * @default { width: 320, height: 200 }
+     */
+    initialDimension?: {
+        width: number;
+        height: number;
+    };
+}) => React.JSX.Element;

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

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useId, useMemo } from "react";
+// oxlint-disable-next-line react-doctor/prefer-dynamic-import -- recharts is the chart's whole purpose; consumers lazy-load the Chart entry point themselves
+import { ResponsiveContainer } from "recharts";
+import { Flex } from "../flex.js";
+import { ChartContext } from "./chart-context.js";
+import { ChartStyle } from "./chart-style.js";
+const INITIAL_DIMENSION = { width: 320, height: 200 };
+/**
+ * Responsive frame for a recharts chart. Wraps recharts' `ResponsiveContainer`,
+ * provides the `config` (series keys → label / icon / colour) to every
+ * descendant `ChartTooltipContent` / `ChartLegendContent`, and injects a
+ * `--color-<key>` CSS variable per series so recharts marks can be coloured with
+ * `fill="var(--color-desktop)"`. Pass a single recharts chart element as the
+ * child. It is dimensionless - set the aspect / height with `className`
+ * (defaults to `aspect-video`).
+ *
+ * @bestPractice Colour every series through `config` (`{ desktop: { label, color } }`) and reference `var(--color-<key>)` on the marks - never hardcode a hex on a `Bar` / `Line`; that keeps light/dark theming and the legend/tooltip swatches in sync.
+ * @bestPractice Reach for `Chart` only to render a recharts data visualization; for a static value + delta use `Stat`, and for a progress bar use `Progress`.
+ * @category data
+ */
+export const Chart = ({ id, className, children, config, initialDimension = INITIAL_DIMENSION, ...props }) => {
+    const uniqueId = useId();
+    const chartId = `chart-${id ?? uniqueId.replaceAll(":", "")}`;
+    const contextValue = useMemo(() => ({ config }), [config]);
+    return (_jsx(ChartContext.Provider, { value: contextValue, children: _jsxs(Flex, { className: cn("[&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground [&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border/50 [&_.recharts-curve.recharts-tooltip-cursor]:stroke-border [&_.recharts-polar-grid_[stroke='#ccc']]:stroke-border [&_.recharts-radial-bar-background-sector]:fill-muted [&_.recharts-rectangle.recharts-tooltip-cursor]:fill-muted [&_.recharts-reference-line_[stroke='#ccc']]:stroke-border text-caption aspect-video [&_.recharts-dot[stroke='#fff']]:stroke-transparent [&_.recharts-layer]:outline-hidden [&_.recharts-sector]:outline-hidden [&_.recharts-sector[stroke='#fff']]:stroke-transparent [&_.recharts-surface]:outline-hidden", className), "data-chart": chartId, "data-component": "chart", "data-slot": "chart", justify: "center", ...props, children: [_jsx(ChartStyle, { config: config, id: chartId }), _jsx(ResponsiveContainer, { initialDimension: initialDimension, children: children })] }) }));
+};

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

@@ -0,0 +1,13 @@
+import type { ChartConfig } 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 declare const ChartStyle: ({ id, config, }: {
+    /** The `data-chart` id the variables are scoped to. */
+    id: string;
+    /** The series-key → colour mapping to emit variables from. */
+    config: ChartConfig;
+}) => import("react").JSX.Element | null;