@instruments/materia-ui 0.1.0

package/dist/components/animated-number/mask.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { addScaleCorrector } from "motion/react";
+import * as m from "motion/react-m";
+/** Vertical mask inset; also the digit/symbol vertical padding so heights match. */
+export const maskHeight = "var(--mask-height, 0.15em)";
+const maskWidth = "var(--mask-width, 0.5em)";
+const correctedMaskWidth = `calc(${maskWidth} / var(--invert-x, 1))`;
+const cornerGradient = "#000 0, transparent 71%";
+// Blur-vignette mask. Technique from https://expensive.toys/blog/blur-vignette
+const mask = 
+// Horizontal:
+`linear-gradient(to right, transparent 0, #000 ${correctedMaskWidth}, #000 calc(100% - ${correctedMaskWidth}), transparent),` +
+    // Vertical:
+    `linear-gradient(to bottom, transparent 0, #000 ${maskHeight}, #000 calc(100% - ${maskHeight}), transparent 100%),` +
+    // TL corner
+    `radial-gradient(at bottom right, ${cornerGradient}),` +
+    // TR corner
+    `radial-gradient(at bottom left, ${cornerGradient}), ` +
+    // BR corner
+    `radial-gradient(at top left, ${cornerGradient}), ` +
+    // BL corner
+    `radial-gradient(at top right, ${cornerGradient})`;
+const maskSize = `100% calc(100% - ${maskHeight} * 2),` +
+    `calc(100% - ${correctedMaskWidth} * 2) 100%,` +
+    `${correctedMaskWidth} ${maskHeight},` +
+    `${correctedMaskWidth} ${maskHeight},` +
+    `${correctedMaskWidth} ${maskHeight},` +
+    `${correctedMaskWidth} ${maskHeight}`;
+// Keep the horizontal mask edges crisp under layout scale by inverting the
+// projection scale into a CSS variable the mask width divides by.
+addScaleCorrector({
+    "--invert-x": {
+        correct: (_latest, { treeScale, projectionDelta }) => projectionDelta && treeScale ? projectionDelta.x.scale * treeScale.x : 1,
+    },
+});
+const maskedStyle = {
+    // Activates the scale correction stored in --invert-x.
+    "--invert-x": 1,
+    display: "inline-flex",
+    margin: `0 calc(-1*${maskWidth})`,
+    overflow: "clip",
+    padding: `calc(${maskHeight}/2) ${maskWidth}`,
+    position: "relative",
+    WebkitMaskImage: mask,
+    WebkitMaskPosition: "center, center, top left, top right, bottom right, bottom left",
+    WebkitMaskRepeat: "no-repeat",
+    WebkitMaskSize: maskSize,
+    zIndex: -1,
+};
+const clippedStyle = {
+    display: "inline-flex",
+    // Structural: clip the stacked digits to the current row (no fade).
+    overflow: "clip",
+    position: "relative",
+    zIndex: -1,
+};
+/**
+ * Wraps the integer + fraction sections and clips each digit column to a single
+ * row (`overflow: clip` is structural - it hides the stacked 0–9 above/below the
+ * current digit, always on). When `masked`, it additionally paints the
+ * blur-vignette so the clipped digits fade softly at the edges as they roll;
+ * unmasked, the clip is crisp. Always `aria-hidden` - the accessible label
+ * lives on the root.
+ */
+export const Mask = ({ children, layoutDependency, masked, }) => (_jsx(m.span, { "aria-hidden": true, layout: true, layoutDependency: layoutDependency, style: masked ? maskedStyle : clippedStyle, children: children }));

package/dist/components/animated-number/number-digit.d.ts

@@ -0,0 +1,24 @@
+import type { HTMLMotionProps } from "motion/react";
+interface NumberDigitProps extends HTMLMotionProps<"span"> {
+    value: number;
+    layoutDependency?: unknown;
+    /**
+     * Roll direction: positive always rolls up (wrapping 9 to 0), negative always
+     * rolls down (wrapping 0 to 9), 0 takes the shortest numeric path.
+     */
+    trend?: number | undefined;
+}
+/**
+ * One rolling digit column. Nine digits are rendered above and nine below the
+ * current one, wrapping mod 10 (the motion-plus 3.0.0 strip), so a FLIP
+ * (`animate(scope, { y: [initialY, 0] })`) in a layout effect springs the column
+ * through every intermediate numeral in either direction, including across the
+ * 9/0 wrap when `trend` asks for it. New leading digits enter with
+ * `initialValue={0}` and roll up from zero; exiting digits roll to zero so
+ * removal also animates. Per-digit width animates to the target glyph width so
+ * proportional fonts stay aligned.
+ *
+ * Under reduced motion the FLIP is skipped: the digit snaps to its value.
+ */
+export declare const NumberDigit: ({ value: _value, trend, ...rest }: NumberDigitProps) => import("react").JSX.Element;
+export {};

package/dist/components/animated-number/number-digit.js

@@ -0,0 +1,110 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { animate, MotionConfigContext, PresenceContext, useIsPresent, useReducedMotion, } from "motion/react";
+import * as m from "motion/react-m";
+import { use, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { getWidthInEm } from "./get-width-in-em.js";
+import { maskHeight } from "./mask.js";
+import { targetWidths } from "./target-widths.js";
+const mod = (n, base) => ((n % base) + base) % base;
+/** The nine digits above and below `value`, wrapping mod 10. */
+const ABOVE_OFFSETS = [9, 8, 7, 6, 5, 4, 3, 2, 1];
+const BELOW_OFFSETS = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+const digitFillStyle = {
+    alignItems: "center",
+    display: "flex",
+    flexDirection: "column",
+    position: "absolute",
+    width: "100%",
+};
+/**
+ * One rolling digit column. Nine digits are rendered above and nine below the
+ * current one, wrapping mod 10 (the motion-plus 3.0.0 strip), so a FLIP
+ * (`animate(scope, { y: [initialY, 0] })`) in a layout effect springs the column
+ * through every intermediate numeral in either direction, including across the
+ * 9/0 wrap when `trend` asks for it. New leading digits enter with
+ * `initialValue={0}` and roll up from zero; exiting digits roll to zero so
+ * removal also animates. Per-digit width animates to the target glyph width so
+ * proportional fonts stay aligned.
+ *
+ * Under reduced motion the FLIP is skipped: the digit snaps to its value.
+ */
+export const NumberDigit = ({ value: _value, trend = 0, ...rest }) => {
+    const { transition } = use(MotionConfigContext);
+    const presence = use(PresenceContext);
+    const shouldReduceMotion = useReducedMotion();
+    // The digit to roll from on mount. A digit that mounts with its
+    // `AnimatePresence` (`initial === false`) sits at its value; one added later
+    // rolls up from zero, so a new leading digit counts up. Captured once, like
+    // React's defaultValue props: the presence flag clears after the first render.
+    const startValue = presence !== null && presence.initial !== false ? 0 : _value;
+    const initialValueRef = useRef(startValue);
+    const scope = useRef(null);
+    const ref = useRef(null);
+    const numberRefs = useRef([]);
+    // Exit isn't a normal AnimatePresence exit because it must trigger a resize.
+    const isPresent = useIsPresent();
+    const value = isPresent ? _value : 0;
+    // Set the width to the initial value's width immediately, so the next render
+    // animates from it.
+    useLayoutEffect(() => {
+        const initialEl = numberRefs.current[initialValueRef.current];
+        if (!scope.current || !initialEl) {
+            return;
+        }
+        scope.current.style.width = getWidthInEm(initialEl);
+    }, []);
+    // FLIP the y in a layout effect. initialY is the pixel offset from the new
+    // resting position, including any in-flight offset (inner vs outer rect top)
+    // so mid-roll re-targets stay continuous.
+    const prevValue = useRef(startValue);
+    useLayoutEffect(() => {
+        if (!scope.current || value === prevValue.current) {
+            return;
+        }
+        if (shouldReduceMotion === true) {
+            prevValue.current = value;
+            return;
+        }
+        const box = scope.current.getBoundingClientRect();
+        const refBox = ref.current?.getBoundingClientRect();
+        // Trend-aware delta: force the roll up or down through the 9/0 wrap.
+        const oldValue = prevValue.current;
+        let delta = value - oldValue;
+        if (trend > 0 && value < oldValue) {
+            delta = 10 - oldValue + value;
+        }
+        else if (trend < 0 && value > oldValue) {
+            delta = value - 10 - oldValue;
+        }
+        const initialY = box.height * delta + (box.top - (refBox ? refBox.top || 0 : box.top));
+        animate(scope.current, { y: [initialY, 0] }, transition);
+        // Record the value we animated to, so the next change measures from it
+        // (equivalent to the original's cleanup, without a returned teardown).
+        prevValue.current = value;
+    }, [value, trend, shouldReduceMotion, transition]);
+    const [width, setWidth] = useState();
+    useEffect(() => {
+        const el = numberRefs.current[value];
+        if (!el) {
+            return;
+        }
+        const w = getWidthInEm(el);
+        // Store the target width immediately, so the section resize can use it.
+        if (ref.current) {
+            targetWidths.set(ref.current, w);
+        }
+        // Trigger the layout animation by causing another render.
+        setWidth(w);
+    }, [value]);
+    const renderNumber = (digit) => (_jsx("span", { ref: (r) => {
+            numberRefs.current[digit] = r;
+        }, style: { display: "inline-block", padding: `calc(${maskHeight}/2) 0` }, children: digit }, digit));
+    return (_jsx(m.span, { ...rest, "data-state": isPresent ? undefined : "exiting", layout: "position", ref: ref, style: { display: "inline-flex", justifyContent: "center", width }, children: _jsxs("span", { ref: scope, style: {
+                alignItems: "center",
+                display: "inline-flex",
+                flexDirection: "column",
+                justifyContent: "center",
+                position: "relative",
+            }, children: [_jsx("span", { style: { ...digitFillStyle, bottom: "100%", left: 0 }, children: ABOVE_OFFSETS.map((offset) => renderNumber(mod(value - offset, 10))) }), renderNumber(value), _jsx("span", { style: { ...digitFillStyle, left: 0, top: "100%" }, children: BELOW_OFFSETS.map((offset) => renderNumber(mod(value + offset, 10))) })] }) }));
+};

package/dist/components/animated-number/number-section.d.ts

@@ -0,0 +1,22 @@
+import type { AnimatePresenceProps, HTMLMotionProps } from "motion/react";
+import type { NumberPart } from "./format-parts.js";
+import type { Justify } from "./section-context.js";
+interface NumberSectionProps extends HTMLMotionProps<"span"> {
+    parts: NumberPart[];
+    justify?: Justify;
+    mode?: AnimatePresenceProps["mode"];
+    name: string;
+    layoutDependency?: unknown;
+    /** Resolved roll direction, passed to every digit. */
+    trend?: number | undefined;
+}
+/**
+ * A run of digits/symbols (pre, integer, fraction, post) sharing one anchor.
+ * It holds a fixed measured width so a new glyph is appended at the end before
+ * the layout animation begins - making it look like it was already there - then
+ * re-measures by momentarily removing exiting children and applying the digits'
+ * target widths (the exact resize trick), so reflow accounts for negative
+ * margins between glyphs.
+ */
+export declare const NumberSection: ({ parts, justify, mode, style, name, layoutDependency, trend, ...rest }: NumberSectionProps) => import("react").JSX.Element;
+export {};

package/dist/components/animated-number/number-section.js

@@ -0,0 +1,93 @@
+"use client";
+// Port of Motion+ AnimateNumber (motion-plus 2.0.0).
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { isDigitPart } from "./format-parts.js";
+import { getWidthInEm } from "./get-width-in-em.js";
+import { NumberDigit } from "./number-digit.js";
+import { NumberSymbol } from "./number-symbol.js";
+import { SectionContext } from "./section-context.js";
+import { targetWidths } from "./target-widths.js";
+/**
+ * A run of digits/symbols (pre, integer, fraction, post) sharing one anchor.
+ * It holds a fixed measured width so a new glyph is appended at the end before
+ * the layout animation begins - making it look like it was already there - then
+ * re-measures by momentarily removing exiting children and applying the digits'
+ * target widths (the exact resize trick), so reflow accounts for negative
+ * margins between glyphs.
+ */
+export const NumberSection = ({ parts, justify = "left", mode, style, name, layoutDependency, trend, ...rest }) => {
+    const ref = useRef(null);
+    const context = useMemo(() => ({ justify }), [justify]);
+    const measuredRef = useRef(null);
+    // A fixed width for the section so new characters are added at the end
+    // before the layout animation starts (they look like they were there).
+    const [width, setWidth] = useState();
+    const partsSignature = parts.map((p) => p.value).join("");
+    // On mount, fix the width to the first measured width.
+    useEffect(() => {
+        const measured = measuredRef.current;
+        if (measured && ref.current) {
+            ref.current.style.width = getWidthInEm(measured);
+        }
+    }, []);
+    const measuredSignature = useRef(partsSignature);
+    useEffect(() => {
+        const measured = measuredRef.current;
+        if (!measured || measuredSignature.current === partsSignature) {
+            return;
+        }
+        measuredSignature.current = partsSignature;
+        // Find the new width by removing exiting elements, measuring, then
+        // re-adding them. We query the DOM because AnimatePresence popLayout
+        // overwrites ref props.
+        const undos = [];
+        // Snapshot the children first - we mutate the live collection below.
+        const children = [...measured.children];
+        for (const child of children) {
+            if (!(child instanceof HTMLElement)) {
+                continue;
+            }
+            if (child.dataset.state === "exiting") {
+                const next = child.nextSibling;
+                child.remove();
+                undos.push(() => {
+                    // insertBefore() appends if next is null.
+                    measuredRef.current?.insertBefore(child, next);
+                });
+                continue;
+            }
+            const newWidth = targetWidths.get(child);
+            if (newWidth === undefined) {
+                continue;
+            }
+            const oldWidth = child.style.width;
+            child.style.width = newWidth;
+            undos.push(() => {
+                child.style.width = oldWidth;
+            });
+        }
+        // Measure the resulting width, then undo immediately. This is a
+        // measure-after-render pass (DOM already committed), not a render-phase
+        // adjustment, so the section can hold a fixed width during the animation.
+        setWidth(getWidthInEm(measured));
+        for (let i = undos.length - 1; i >= 0; i -= 1) {
+            undos[i]?.();
+        }
+    }, [partsSignature]);
+    return (_jsx(SectionContext.Provider, { value: context, children: _jsx(m.span, { layoutDependency: layoutDependency, ...rest, className: `number-section-${name}`, ref: ref, style: {
+                ...style,
+                display: "inline-flex",
+                justifyContent: justify,
+                width,
+            }, children: _jsxs("span", { ref: measuredRef, style: {
+                    display: "inline-flex",
+                    justifyContent: "inherit",
+                    position: "relative",
+                }, children: ["\u200B", _jsx(AnimatePresence, { anchorX: justify, initial: false, mode: mode ?? "sync", children: parts.map((part) => isDigitPart(part) ? (_jsx(NumberDigit, { animate: { opacity: 1 }, exit: { opacity: 0 }, initial: { opacity: 0 }, layoutDependency: layoutDependency, trend: trend, value: part.value }, part.key)) : (_jsx(NumberSymbol, { animate: { opacity: 1 }, exit: { opacity: 0 }, initial: { opacity: 0 }, layoutDependency: layoutDependency, partKey: part.key, type: part.type, children: part.value }, part.type === "literal"
+                            ? `${part.key}:${part.value}`
+                            : part.key))) })] }) }) }));
+};

package/dist/components/animated-number/number-symbol.d.ts

@@ -0,0 +1,17 @@
+import type { HTMLMotionProps } from "motion/react";
+interface NumberSymbolProps extends Omit<HTMLMotionProps<"span">, "children"> {
+    partKey: string;
+    type: string;
+    /** The static glyph - a string so it can key the crossfade directly. */
+    children: string;
+    layoutDependency?: unknown;
+}
+/**
+ * A static glyph in a section - group separator, decimal point, sign, currency
+ * or a prefix/suffix character. It fades in and out (via `AnimatePresence`
+ * popLayout) so symbols appearing or disappearing with magnitude changes don't
+ * pop, and `data-state="exiting"` marks it so the section width re-measure can
+ * exclude it.
+ */
+export declare const NumberSymbol: ({ partKey: _partKey, type: _type, children, layoutDependency, ...rest }: NumberSymbolProps) => import("react").JSX.Element;
+export {};

package/dist/components/animated-number/number-symbol.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AnimatePresence, useIsPresent } from "motion/react";
+import * as m from "motion/react-m";
+import { use } from "react";
+import { maskHeight } from "./mask.js";
+import { SectionContext } from "./section-context.js";
+/**
+ * A static glyph in a section - group separator, decimal point, sign, currency
+ * or a prefix/suffix character. It fades in and out (via `AnimatePresence`
+ * popLayout) so symbols appearing or disappearing with magnitude changes don't
+ * pop, and `data-state="exiting"` marks it so the section width re-measure can
+ * exclude it.
+ */
+export const NumberSymbol = ({ partKey: _partKey, type: _type, children, layoutDependency, ...rest }) => {
+    const isPresent = useIsPresent();
+    const { justify } = use(SectionContext);
+    return (_jsx(m.span, { ...rest, "data-state": isPresent ? undefined : "exiting", layout: "position", layoutDependency: layoutDependency, style: {
+            display: "inline-flex",
+            justifyContent: justify,
+            padding: `calc(${maskHeight}/2) 0`,
+            position: "relative",
+        }, children: _jsx(AnimatePresence, { anchorX: justify, initial: false, mode: "popLayout", children: _jsx(m.span, { animate: { opacity: [null, 1] }, exit: { opacity: [null, 0] }, initial: { opacity: 0 }, layout: justify === "right" ? "position" : false, layoutDependency: layoutDependency, style: { display: "inline-block", whiteSpace: "pre" }, children: children }, children) }) }));
+};

package/dist/components/animated-number/section-context.d.ts

@@ -0,0 +1,10 @@
+/** Horizontal anchor for a section - integers anchor right, so digits grow leftward. */
+export type Justify = "left" | "right";
+export interface SectionContextValue {
+    justify: Justify;
+}
+/**
+ * Tells digits and symbols which edge their section anchors to, so mounting and
+ * exiting glyphs animate from the correct side (`anchorX`) and stay put.
+ */
+export declare const SectionContext: import("react").Context<SectionContextValue>;

package/dist/components/animated-number/section-context.js

@@ -0,0 +1,10 @@
+"use client";
+// Port of Motion+ AnimateNumber (motion-plus 2.0.0).
+import { createContext } from "react";
+/**
+ * Tells digits and symbols which edge their section anchors to, so mounting and
+ * exiting glyphs animate from the correct side (`anchorX`) and stay put.
+ */
+export const SectionContext = createContext({
+    justify: "left",
+});

package/dist/components/animated-number/target-widths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Per-digit target widths, written by {@link NumberDigit} the instant a digit's
+ * width changes and read by {@link NumberSection} when it re-measures its fixed
+ * width. A WeakMap keyed by the digit element so entries are collected with the
+ * element.
+ */
+export declare const targetWidths: WeakMap<Element, string>;

package/dist/components/animated-number/target-widths.js

@@ -0,0 +1,8 @@
+// Port of Motion+ AnimateNumber (motion-plus 2.0.0).
+/**
+ * Per-digit target widths, written by {@link NumberDigit} the instant a digit's
+ * width changes and read by {@link NumberSection} when it re-measures its fixed
+ * width. A WeakMap keyed by the digit element so entries are collected with the
+ * element.
+ */
+export const targetWidths = new WeakMap();

package/dist/components/animated-number.d.ts

@@ -0,0 +1 @@
+export { AnimatedNumber, type AnimatedNumberProps, type AnimatedNumberTrend, } from "./animated-number/animated-number-root.js";

package/dist/components/animated-number.js

@@ -0,0 +1 @@
+export { AnimatedNumber, } from "./animated-number/animated-number-root.js";

package/dist/components/aspect-ratio/aspect-ratio-anatomy.d.ts

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

package/dist/components/aspect-ratio/aspect-ratio-anatomy.js

@@ -0,0 +1,10 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * aspectRatioAnatomy helper for AspectRatioAnatomy.
+ * Import from "@instruments/materia-ui/components/aspect-ratio-anatomy".
+ */
+export const aspectRatioAnatomy = defineAnatomy({
+    description: "Frames a single child at a fixed width-to-height ratio",
+    label: "AspectRatio",
+    slot: "aspect-ratio",
+});

package/dist/components/aspect-ratio/aspect-ratio-root.d.ts

@@ -0,0 +1,39 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement } from "../../tokens/element.js";
+interface AspectRatioProps 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.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <AspectRatio as="figure" ratio={4 / 3} />
+     */
+    as?: LayoutElement;
+    /**
+     * Desired width-to-height ratio, expressed as a single number (width / height).
+     * @default 16 / 9
+     */
+    ratio?: number;
+}
+/**
+ * Constrains its content to a fixed width-to-height ratio, sizing itself to the
+ * available width with CSS `aspect-ratio`; drop a single child (image, video,
+ * iframe, or a plain element) inside and size it to fill the framed box.
+ *
+ * @example
+ * ```tsx
+ * <AspectRatio ratio={16 / 9}>
+ *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * </AspectRatio>
+ * ```
+ *
+ * @bestPractice Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
+ * @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
+ */
+declare const AspectRatio: ({ as, className, ratio, ref, render, style, ...props }: AspectRatioProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type { AspectRatioProps };
+export { AspectRatio };

package/dist/components/aspect-ratio/aspect-ratio-root.js

@@ -0,0 +1,39 @@
+"use client";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "../../utils/cn.js";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+const DEFAULT_RATIO = 16 / 9;
+/**
+ * Constrains its content to a fixed width-to-height ratio, sizing itself to the
+ * available width with CSS `aspect-ratio`; drop a single child (image, video,
+ * iframe, or a plain element) inside and size it to fill the framed box.
+ *
+ * @example
+ * ```tsx
+ * <AspectRatio ratio={16 / 9}>
+ *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * </AspectRatio>
+ * ```
+ *
+ * @bestPractice Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
+ * @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
+ */
+const AspectRatio = ({ as, className, ratio = DEFAULT_RATIO, ref, render, style, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("AspectRatio: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn("relative w-full", className),
+            "data-component": "aspect-ratio",
+            "data-slot": "aspect-ratio",
+            style: { aspectRatio: ratio, ...style },
+            ...props,
+        },
+        ref,
+        render,
+    });
+};
+export { AspectRatio };

package/dist/components/aspect-ratio/aspect-ratio.test-d.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Type-level surface guards for AspectRatio'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 { AspectRatio } from "./aspect-ratio-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 AspectRatio props. */
+type Accepts<V> = V extends ComponentProps<typeof AspectRatio> ? true : false;
+export type FigureAccepted = Expect<Accepts<{
+    as: "figure";
+}>>;
+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 AspectRatio>] extends [never] ? true : false>>;
+export {};

package/dist/components/aspect-ratio/aspect-ratio.test-d.js

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

package/dist/components/aspect-ratio.d.ts

@@ -0,0 +1,2 @@
+export { AspectRatio } from "./aspect-ratio/aspect-ratio-root.js";
+export { aspectRatioAnatomy } from "./aspect-ratio/aspect-ratio-anatomy.js";

package/dist/components/aspect-ratio.js

@@ -0,0 +1,2 @@
+export { AspectRatio } from "./aspect-ratio/aspect-ratio-root.js";
+export { aspectRatioAnatomy } from "./aspect-ratio/aspect-ratio-anatomy.js";

package/dist/components/avatar/avatar-badge.d.ts

@@ -0,0 +1,28 @@
+import type { ComponentSize } from "../../tokens/size.js";
+import type { Tone } from "../../tokens/tone.js";
+/** AvatarBadge tone - the canon {@link Tone} subset it fills. */
+export type AvatarBadgeTone = Extract<Tone, "neutral" | "danger" | "brand">;
+export interface AvatarBadgeProps {
+    /** CSS class name */
+    className?: string;
+    /** Number shown in the badge; hidden when 0 or omitted unless `dot` is set. */
+    count?: number;
+    /**
+     * Render a plain dot instead of a number. `true` tints it with the badge's
+     * own `tone`; a {@link Tone} value overrides that with the shared dot tint.
+     * @default false
+     */
+    dot?: boolean | Tone;
+    /** Cap above which the count renders as `{max}+`. @default 99 */
+    max?: number;
+    /** @default "top-right" */
+    position?: "bottom-right" | "top-right" | "bottom-left" | "top-left";
+    /** Component size */
+    size?: ComponentSize;
+    /** Semantic fill tone. @default "danger" */
+    tone?: AvatarBadgeTone;
+}
+/**
+ * Count or status dot overlaid on an avatar corner; renders nothing unless `dot` is set or `count > 0`, and clamps counts above `max` to `{max}+`.
+ */
+export declare const AvatarBadge: ({ count, max, size, className, position, tone, dot, }: AvatarBadgeProps) => import("react").JSX.Element | null;

package/dist/components/avatar/avatar-badge.js

@@ -0,0 +1,54 @@
+"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 { DOT_TONE_BG_CLASSES } from "../dot.js";
+import { VisuallyHidden } from "../visually-hidden.js";
+const BADGE_SIZE = {
+    "2xl": "h-6 min-w-6 text-[12px]",
+    "2xs": "h-3 min-w-3 text-[6px]",
+    "3xl": "h-7 min-w-7 text-[14px]",
+    base: "h-4 min-w-4 text-[9px]",
+    lg: "h-5 min-w-5 text-2xs",
+    sm: "h-4 min-w-4 text-[8px]",
+    xl: "h-5 min-w-5 text-2xs",
+    xs: "h-3.5 min-w-3.5 text-[7px]",
+};
+const DOT_SIZE = {
+    "2xl": "size-3.5",
+    "2xs": "size-2",
+    "3xl": "size-4",
+    base: "size-2.5",
+    lg: "size-3",
+    sm: "size-2.5",
+    xl: "size-3",
+    xs: "size-2",
+};
+const POSITION_CLASS = {
+    "bottom-left": "-bottom-1 -left-1",
+    "bottom-right": "-right-1 -bottom-1",
+    "top-left": "-top-1 -left-1",
+    "top-right": "-top-1 -right-1",
+};
+const TONE_CLASS = {
+    neutral: "bg-secondary text-secondary-foreground",
+    danger: "bg-destructive text-destructive-foreground",
+    brand: "bg-primary text-primary-foreground",
+};
+/**
+ * Count or status dot overlaid on an avatar corner; renders nothing unless `dot` is set or `count > 0`, and clamps counts above `max` to `{max}+`.
+ */
+export const AvatarBadge = ({ count, max = 99, size = "base", className, position = "top-right", tone = "danger", dot = false, }) => {
+    const displayCount = count !== undefined && count > max ? `${max}+` : count;
+    const showBadge = Boolean(dot) || (count !== undefined && count > 0);
+    if (!showBadge) {
+        return null;
+    }
+    if (dot !== false && dot !== undefined) {
+        // `dot === true` keeps the badge-tone fill (unchanged); a Tone value tints
+        // the dot with the shared dot palette instead.
+        const dotColorClass = dot === true ? TONE_CLASS[tone] : DOT_TONE_BG_CLASSES[dot];
+        return (_jsx("span", { "aria-hidden": "true", className: cn("absolute rounded-full", DOT_SIZE[size], dotColorClass, POSITION_CLASS[position], "ring-background ring-2", className), "data-component": "avatar-badge" }));
+    }
+    return (_jsxs(Center, { as: "span", className: cn("absolute rounded-full px-1 font-medium tabular-nums", BADGE_SIZE[size], TONE_CLASS[tone], POSITION_CLASS[position], "ring-background ring-2", className), "data-component": "avatar-badge", children: [_jsx("span", { "aria-hidden": "true", children: displayCount }), _jsx(VisuallyHidden, { children: `${count} notifications` })] }));
+};