@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+export type LogoSize = Extract<ComponentSize, "sm" | "base" | "lg" | "xl">;
+interface LogoProps extends React.SVGProps<SVGSVGElement> {
+    /**
+     * Accessible name announced for the mark. Set it when you replace `mark`.
+     * @default "Material Bank"
+     */
+    label?: string;
+    /**
+     * Replaces the Material Bank mark: SVG shapes (`<path>`, `<g>`…) drawn in a
+     * 48x48 viewBox that fill from `currentColor`, rendered inside the `Logo`
+     * `<svg>` so `size` and `text-*` colour classes keep working.
+     * @default the Material Bank mark
+     */
+    mark?: ReactNode;
+    /** Size preset */
+    size?: LogoSize;
+}
+/**
+ * Brand mark. Renders the Material Bank logo by default; pass `mark` (and
+ * `label`) to show your own. Uses currentColor for fill, so colour can be
+ * controlled via text-* classes.
+ *
+ * @bestPractice Recolour the mark with a `text-*` class - it fills from `currentColor`; passing `fill`/a hex defeats the single-source colour and breaks dark-mode inheritance.
+ * @bestPractice Size with the `size` preset (`sm`–`xl`), not a `className` width/height - presets keep the mark on the shared `ComponentSize` scale.
+ * @bestPractice Don't add your own `aria-label`/`role` - `Logo` already ships `role="img"` + "Material Bank" (change the name with `label`); wrap it in a link only when you need a click target.
+ * @bestPractice To use your own brand, pass `mark` as SVG shapes in a 48x48 viewBox filled with `currentColor`, and a matching `label` - don't wrap or overlay the default mark.
+ * @example
+ * ```tsx
+ * <Logo label="Acme" mark={<path d="M8 40 24 8l16 32z" fill="currentColor" />} />
+ * ```
+ * @category color
+ */
+export declare const Logo: ({ className, label, mark, size, ...props }: LogoProps) => import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "../../utils/cn.js";
+const SIZE_MAP = {
+    base: { height: 32, width: 32 },
+    lg: { height: 40, width: 40 },
+    sm: { height: 24, width: 24 },
+    xl: { height: 48, width: 48 },
+};
+const DEFAULT_MARK = (_jsx("path", { clipRule: "evenodd", d: "M33.52 6.5H44.28C44.35 6.5 44.41 6.56 44.41 6.64V41.36C44.41 41.44 44.35 41.5 44.28 41.5H33.52C33.44 41.5 33.38 41.44 33.38 41.36V6.64C33.38 6.56 33.44 6.5 33.52 6.5ZM31.68 21.1C31.71 21.12 31.72 21.16 31.72 21.19C31.72 21.23 31.71 21.26 31.68 21.29L24.08 28.83C24.05 28.86 24.01 28.87 23.98 28.87C23.94 28.87 23.91 28.86 23.88 28.83L9.25 14.33C9.23 14.3 9.21 14.27 9.21 14.23C9.21 14.2 9.23 14.16 9.25 14.14L16.86 6.6C16.87 6.58 16.89 6.57 16.9 6.57C16.92 6.56 16.94 6.56 16.96 6.56C16.97 6.56 16.99 6.56 17.01 6.57C17.03 6.57 17.04 6.58 17.05 6.6L31.68 21.1ZM3.72 20.72H14.48C14.51 20.72 14.55 20.73 14.58 20.76C14.6 20.78 14.62 20.82 14.62 20.85V41.36C14.62 41.4 14.6 41.43 14.58 41.46C14.55 41.48 14.52 41.5 14.48 41.5H3.72C3.68 41.5 3.65 41.48 3.62 41.46C3.59 41.43 3.58 41.4 3.58 41.36V20.85C3.58 20.82 3.59 20.78 3.62 20.76C3.65 20.73 3.68 20.72 3.72 20.72V20.72Z", fill: "currentColor", fillRule: "evenodd" }));
+/**
+ * Brand mark. Renders the Material Bank logo by default; pass `mark` (and
+ * `label`) to show your own. Uses currentColor for fill, so colour can be
+ * controlled via text-* classes.
+ *
+ * @bestPractice Recolour the mark with a `text-*` class - it fills from `currentColor`; passing `fill`/a hex defeats the single-source colour and breaks dark-mode inheritance.
+ * @bestPractice Size with the `size` preset (`sm`–`xl`), not a `className` width/height - presets keep the mark on the shared `ComponentSize` scale.
+ * @bestPractice Don't add your own `aria-label`/`role` - `Logo` already ships `role="img"` + "Material Bank" (change the name with `label`); wrap it in a link only when you need a click target.
+ * @bestPractice To use your own brand, pass `mark` as SVG shapes in a 48x48 viewBox filled with `currentColor`, and a matching `label` - don't wrap or overlay the default mark.
+ * @example
+ * ```tsx
+ * <Logo label="Acme" mark={<path d="M8 40 24 8l16 32z" fill="currentColor" />} />
+ * ```
+ * @category color
+ */
+export const Logo = ({ className, label = "Material Bank", mark = DEFAULT_MARK, size = "lg", ...props }) => {
+    const dimensions = SIZE_MAP[size];
+    return (_jsx("svg", { "aria-label": label, className: cn("shrink-0", className), fill: "none", height: dimensions.height, 
+        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- inline <svg> with currentColor fill cannot be a self-contained <img>; role="img"+aria-label is the correct a11y pattern here
+        role: "img", viewBox: "0 0 48 48", width: dimensions.width, xmlns: "http://www.w3.org/2000/svg", ...props, children: mark }));
+};

package/dist/components/logo.d.ts

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

package/dist/components/logo.js

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

package/dist/components/marquee-text/marquee-text-root.d.ts

@@ -0,0 +1,37 @@
+export interface MarqueeTextProps {
+    children: string;
+    className?: string;
+    /** Scroll speed in px/sec. @default 40 */
+    speedPxPerSec?: number;
+    /** Gap in px between the two copies. @default 24 */
+    gap?: number;
+}
+/**
+ * A clipped single-line label that becomes a hover-triggered marquee when its
+ * text is wider than the clip box, and stays a plain truncated label when it
+ * fits. On overflow it renders a duplicate `aria-hidden` copy and scrolls the
+ * pair for a seamless loop; a `ResizeObserver` on both the clip box and the
+ * text node re-measures on resize and on content change, setting
+ * `--marquee-duration` / `--marquee-shift`.
+ *
+ * Extracted from `product-card-category`'s `CategoryLabel`.
+ *
+ * @example
+ * ```tsx
+ * <div className="group w-40">
+ *   <MarqueeText>A very long product category that overflows its column</MarqueeText>
+ * </div>
+ * ```
+ *
+ * @bestPractice The scroll is gated on a `.group` ancestor's hover (the
+ * `.animate-marquee` utility runs only under `.group:hover`, plus a
+ * `data-play="running"` escape hatch) - a lone `MarqueeText` will not animate on
+ * its own hover. Wrap it in a `.group` element (typically the hoverable card) to
+ * trigger the reveal.
+ * @bestPractice It only scrolls when the text overflows; short text that fits
+ * stays a static clipped label with no duplicate copy and no animation.
+ * @bestPractice Honours `prefers-reduced-motion` automatically via the shared
+ * `.animate-marquee` utility, which disables the animation.
+ * @category data
+ */
+export declare const MarqueeText: ({ children, className, speedPxPerSec, gap, }: MarqueeTextProps) => import("react").JSX.Element;

package/dist/components/marquee-text/marquee-text-root.js

@@ -0,0 +1,73 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useEffect, useRef, useState } from "react";
+import { Flex } from "../flex.js";
+/**
+ * A clipped single-line label that becomes a hover-triggered marquee when its
+ * text is wider than the clip box, and stays a plain truncated label when it
+ * fits. On overflow it renders a duplicate `aria-hidden` copy and scrolls the
+ * pair for a seamless loop; a `ResizeObserver` on both the clip box and the
+ * text node re-measures on resize and on content change, setting
+ * `--marquee-duration` / `--marquee-shift`.
+ *
+ * Extracted from `product-card-category`'s `CategoryLabel`.
+ *
+ * @example
+ * ```tsx
+ * <div className="group w-40">
+ *   <MarqueeText>A very long product category that overflows its column</MarqueeText>
+ * </div>
+ * ```
+ *
+ * @bestPractice The scroll is gated on a `.group` ancestor's hover (the
+ * `.animate-marquee` utility runs only under `.group:hover`, plus a
+ * `data-play="running"` escape hatch) - a lone `MarqueeText` will not animate on
+ * its own hover. Wrap it in a `.group` element (typically the hoverable card) to
+ * trigger the reveal.
+ * @bestPractice It only scrolls when the text overflows; short text that fits
+ * stays a static clipped label with no duplicate copy and no animation.
+ * @bestPractice Honours `prefers-reduced-motion` automatically via the shared
+ * `.animate-marquee` utility, which disables the animation.
+ * @category data
+ */
+export const MarqueeText = ({ children, className, speedPxPerSec = 40, gap = 24, }) => {
+    const clipRef = useRef(null);
+    const textRef = useRef(null);
+    // px distance of one copy + gap; 0 means the text fits (no marquee).
+    const [shift, setShift] = useState(0);
+    useEffect(() => {
+        const clip = clipRef.current;
+        const text = textRef.current;
+        if (!clip || !text) {
+            return () => {
+                // Nothing mounted to observe.
+            };
+        }
+        const measure = () => {
+            const textWidth = text.scrollWidth;
+            const overflowing = textWidth - clip.clientWidth > 1;
+            setShift(overflowing ? textWidth + gap : 0);
+        };
+        measure();
+        // Observing the text node (natural width) also catches content changes,
+        // since new text re-sizes that node even when the clip box is unchanged.
+        const observer = new ResizeObserver(measure);
+        observer.observe(clip);
+        observer.observe(text);
+        return () => {
+            observer.disconnect();
+        };
+        // `gap` is a runtime prop, so the measurement re-runs when it changes. The
+        // duration is derived from `shift` and `speedPxPerSec` at render time.
+    }, [gap]);
+    const isMarquee = shift > 0;
+    const trackStyle = isMarquee
+        ? {
+            "--marquee-duration": `${shift / speedPxPerSec}s`,
+            "--marquee-shift": `-${shift}px`,
+            gap: `${gap}px`,
+        }
+        : undefined;
+    return (_jsx("span", { className: cn("block min-w-0 overflow-hidden", className), "data-component": "marquee-text", "data-slot": "marquee-text", ref: clipRef, children: _jsxs(Flex, { as: "span", className: cn("w-max whitespace-nowrap", isMarquee && "animate-marquee"), style: trackStyle, children: [_jsx("span", { className: "shrink-0", ref: textRef, children: children }), isMarquee ? (_jsx("span", { "aria-hidden": true, className: "shrink-0", children: children })) : null] }) }));
+};

package/dist/components/marquee-text.d.ts

@@ -0,0 +1 @@
+export { MarqueeText, type MarqueeTextProps, } from "./marquee-text/marquee-text-root.js";

package/dist/components/marquee-text.js

@@ -0,0 +1 @@
+export { MarqueeText, } from "./marquee-text/marquee-text-root.js";

package/dist/components/media-frame/media-frame-embed.d.ts

@@ -0,0 +1,29 @@
+import type React from "react";
+export interface MediaFrameEmbedProps extends Omit<React.ComponentProps<"iframe">, "title"> {
+    /** Accessible name for the embedded document. Required. */
+    title: string;
+    /**
+     * Restrictions on the embedded document. Defaults to scripts and same-origin
+     * access only: enough for a live preview of your own pages, with no forms,
+     * pop-ups or top-level navigation. Widen it deliberately for other content.
+     * @default "allow-scripts allow-same-origin"
+     */
+    sandbox?: string;
+}
+/**
+ * An embedded document (an `<iframe>`) as `MediaFrame` media: borderless,
+ * block-level and lazy-loaded by default. Size and any scaling come from the
+ * caller - pass a device-sized `style` and a `transform` to preview a page at a
+ * real viewport inside a smaller plate.
+ *
+ * @example
+ * ```tsx
+ * <MediaFrame className="rounded-xl border">
+ *   <MediaFrameEmbed src="/frames/default" title="Default frame preview" />
+ * </MediaFrame>
+ * ```
+ *
+ * @bestPractice A decorative preview belongs inside an `inert` wrapper with the real link beside it, so keyboard and screen-reader users never land inside the embedded page.
+ * @bestPractice Always give `title` a name that says what the document is; it is the frame's only accessible name.
+ */
+export declare const MediaFrameEmbed: ({ className, loading, sandbox, title, ...props }: MediaFrameEmbedProps) => React.JSX.Element;

package/dist/components/media-frame/media-frame-embed.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * An embedded document (an `<iframe>`) as `MediaFrame` media: borderless,
+ * block-level and lazy-loaded by default. Size and any scaling come from the
+ * caller - pass a device-sized `style` and a `transform` to preview a page at a
+ * real viewport inside a smaller plate.
+ *
+ * @example
+ * ```tsx
+ * <MediaFrame className="rounded-xl border">
+ *   <MediaFrameEmbed src="/frames/default" title="Default frame preview" />
+ * </MediaFrame>
+ * ```
+ *
+ * @bestPractice A decorative preview belongs inside an `inert` wrapper with the real link beside it, so keyboard and screen-reader users never land inside the embedded page.
+ * @bestPractice Always give `title` a name that says what the document is; it is the frame's only accessible name.
+ */
+export const MediaFrameEmbed = ({ className, loading = "lazy", sandbox = "allow-scripts allow-same-origin", title, ...props }) => (_jsx("iframe", { className: cn("block border-0", className), "data-component": "media-frame-embed", "data-slot": "media-frame-embed", loading: loading, sandbox: sandbox, title: title, ...props }));

package/dist/components/media-frame/media-frame-root.d.ts

@@ -0,0 +1,56 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { LayoutElement } from "../../tokens/element.js";
+export interface MediaFrameProps 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 <MediaFrame as="figure" />
+     */
+    as?: LayoutElement;
+    /**
+     * Draw an inset hairline over the media. It is painted by an overlay
+     * pseudo-element, so it sits above the media child rather than behind it (an
+     * inset shadow on the frame is hidden by any media that fills the box).
+     * Translucent dark in light mode, translucent light in dark mode.
+     * Inset edge adapted from @patternmode/thumbnail.
+     * @default false
+     */
+    edge?: boolean;
+    /**
+     * Lift the frame slightly off the surface with one tight downward shadow.
+     * @default false
+     */
+    raised?: boolean;
+}
+/**
+ * A rounded clip frame for media (image or video). Establishes a
+ * `relative overflow-hidden` positioning context and clips its single child to a
+ * rounded corner - but it is a dumb box: it does NOT size or cover-fill the
+ * child. Give it one media child with `size-full object-cover` (identical
+ * contract to `AspectRatio`). Radius, size, and positioning all come from the
+ * `className` you pass (`rounded-2xl`, `size-full`, `absolute inset-0`, …) -
+ * there is no `radius` prop.
+ *
+ * Extracted from the product-card and editorial-card media frames; available to
+ * any composition that needs a rounded overflow-clip layer.
+ *
+ * @example
+ * ```tsx
+ * <MediaFrame className="rounded-2xl">
+ *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * </MediaFrame>
+ * ```
+ *
+ * @bestPractice MediaFrame is a dumb clip box - it does not size or cover-fill the child; give it one media child with `size-full object-cover`, like AspectRatio.
+ * @bestPractice Set radius, size, and positioning through `className` (`rounded-3xl`, `size-full`, `absolute inset-0`) - there is no `radius` prop.
+ * @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.
+ * @bestPractice Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
+ * @bestPractice Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+ * @category layout
+ */
+export declare const MediaFrame: ({ as, className, children, edge, raised, ref, render, ...props }: MediaFrameProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/media-frame/media-frame-root.js

@@ -0,0 +1,47 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * A rounded clip frame for media (image or video). Establishes a
+ * `relative overflow-hidden` positioning context and clips its single child to a
+ * rounded corner - but it is a dumb box: it does NOT size or cover-fill the
+ * child. Give it one media child with `size-full object-cover` (identical
+ * contract to `AspectRatio`). Radius, size, and positioning all come from the
+ * `className` you pass (`rounded-2xl`, `size-full`, `absolute inset-0`, …) -
+ * there is no `radius` prop.
+ *
+ * Extracted from the product-card and editorial-card media frames; available to
+ * any composition that needs a rounded overflow-clip layer.
+ *
+ * @example
+ * ```tsx
+ * <MediaFrame className="rounded-2xl">
+ *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * </MediaFrame>
+ * ```
+ *
+ * @bestPractice MediaFrame is a dumb clip box - it does not size or cover-fill the child; give it one media child with `size-full object-cover`, like AspectRatio.
+ * @bestPractice Set radius, size, and positioning through `className` (`rounded-3xl`, `size-full`, `absolute inset-0`) - there is no `radius` prop.
+ * @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.
+ * @bestPractice Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
+ * @bestPractice Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+ * @category layout
+ */
+export const MediaFrame = ({ as, className, children, edge = false, raised = false, ref, render, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("MediaFrame: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn("relative overflow-hidden", edge &&
+                "after:rounded-inherit after:ring-border-subtle after:pointer-events-none after:absolute after:inset-0 after:ring-1 after:ring-inset", raised && "shadow-2xs", className),
+            "data-component": "media-frame",
+            "data-slot": "media-frame",
+            ...props,
+            children,
+        },
+        ref,
+        render,
+    });
+};

package/dist/components/media-frame/media-frame.test-d.d.ts

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

package/dist/components/media-frame/media-frame.test-d.js

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

package/dist/components/media-frame.d.ts

@@ -0,0 +1,2 @@
+export { MediaFrameEmbed, type MediaFrameEmbedProps, } from "./media-frame/media-frame-embed.js";
+export { MediaFrame, type MediaFrameProps, } from "./media-frame/media-frame-root.js";

package/dist/components/media-frame.js

@@ -0,0 +1,2 @@
+export { MediaFrameEmbed, } from "./media-frame/media-frame-embed.js";
+export { MediaFrame, } from "./media-frame/media-frame-root.js";

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

@@ -0,0 +1,10 @@
+import type { ComponentSize } from "../../tokens/size.js";
+/**
+ * Visual-only checkbox sized like Checkbox (the shared square-control ramp).
+ * A `<span>` rather than a `<button>`, since MenuItem is already a `<button>`.
+ */
+declare const MenuItemCheckbox: ({ checked, size, }: {
+    checked?: boolean;
+    size: ComponentSize;
+}) => import("react").JSX.Element;
+export { MenuItemCheckbox };

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

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check } from "lucide-react";
+import { INPUT_SHELL } from "../../tokens/input-shell.js";
+import { SQUARE_CONTROL_SIZE_CLASSES } from "../../tokens/square-control.js";
+import { Center } from "../center.js";
+import { Icon } from "../icon.js";
+/**
+ * Visual-only checkbox sized like Checkbox (the shared square-control ramp).
+ * A `<span>` rather than a `<button>`, since MenuItem is already a `<button>`.
+ */
+const MenuItemCheckbox = ({ checked, size, }) => (_jsx(Center, { "aria-hidden": true, as: "span", className: cn(`shrink-0 ${INPUT_SHELL} shadow-xs`, checked === true && "border-primary bg-primary text-primary-foreground", SQUARE_CONTROL_SIZE_CLASSES[size]), children: checked === true && _jsx(Icon, { icon: Check }) }));
+export { MenuItemCheckbox };

package/dist/components/menu-item/menu-item-indicators.d.ts

@@ -0,0 +1,14 @@
+import type * as React from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+/** Absolutely-positioned indicator / checkbox / radio / active markers. */
+declare const MenuItemIndicators: ({ activeIndicator, checked, hasIndicator, iconSize, indicator, active, resolvedSize, selectionMode, }: {
+    activeIndicator: "dot" | "check" | "none";
+    checked?: boolean | undefined;
+    hasIndicator: boolean;
+    iconSize: ComponentSize;
+    indicator: React.ReactNode;
+    active: boolean;
+    resolvedSize: ComponentSize;
+    selectionMode?: "checkbox" | "radio" | undefined;
+}) => React.JSX.Element;
+export { MenuItemIndicators };

package/dist/components/menu-item/menu-item-indicators.js

@@ -0,0 +1,12 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check } from "lucide-react";
+import { Center } from "../center.js";
+import { Dot } from "../dot.js";
+import { Icon } from "../icon.js";
+import { MenuItemCheckbox } from "./menu-item-checkbox.js";
+import { MenuItemRadio } from "./menu-item-radio.js";
+import { MENU_ITEM_INDICATOR_LEFT, MENU_ITEM_INDICATOR_SIZE, } from "./menu-item-variants.js";
+/** Absolutely-positioned indicator / checkbox / radio / active markers. */
+const MenuItemIndicators = ({ activeIndicator, checked, hasIndicator, iconSize, indicator, active, resolvedSize, selectionMode, }) => (_jsxs(_Fragment, { children: [hasIndicator && (_jsx(Center, { as: "span", className: cn("pointer-events-none absolute", MENU_ITEM_INDICATOR_SIZE[resolvedSize], MENU_ITEM_INDICATOR_LEFT[resolvedSize]), children: indicator })), checked !== undefined && selectionMode === "radio" && (_jsx(MenuItemRadio, { checked: checked, size: iconSize })), checked !== undefined && selectionMode !== "radio" && (_jsx(MenuItemCheckbox, { checked: checked, size: iconSize })), active && activeIndicator === "dot" && (_jsx(Dot, { className: "shrink-0", size: "base", tone: "success" })), active && activeIndicator === "check" && (_jsx(Icon, { className: "text-affirmative shrink-0", icon: Check, size: "xs" }))] }));
+export { MenuItemIndicators };

package/dist/components/menu-item/menu-item-radio.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentSize } from "../../tokens/size.js";
+/** Visual-only radio indicator (no RadioGroup context needed). */
+declare const MenuItemRadio: ({ checked, size, }: {
+    checked?: boolean;
+    size: ComponentSize;
+}) => import("react").JSX.Element;
+export { MenuItemRadio };

package/dist/components/menu-item/menu-item-radio.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Center } from "../center.js";
+import { RADIO_DOT_SIZE_CLASSES, RADIO_SIZE_CLASSES, } from "../radio/radio-root.js";
+/** Visual-only radio indicator (no RadioGroup context needed). */
+const MenuItemRadio = ({ checked, size, }) => (_jsx(Center, { as: "span", className: cn("border-border bg-card shrink-0 rounded-full border shadow-xs", checked === true && "border-primary", RADIO_SIZE_CLASSES[size]), children: checked === true && (_jsx("span", { className: cn("bg-primary rounded-full", RADIO_DOT_SIZE_CLASSES[size]) })) }));
+export { MenuItemRadio };

package/dist/components/menu-item/menu-item-root.d.ts

@@ -0,0 +1,14 @@
+import type * as React from "react";
+import type { MenuItemProps } from "./menu-item-types.js";
+/**
+ * A standalone menu item component for use in popovers, sheets, and custom menus.
+ * This is the base component that DropdownMenuItem and other menu items build upon.
+ *
+ * @bestPractice `MenuItem` is the standalone base for custom menus (popovers, sheets); inside a `DropdownMenu` / `ContextMenu` use that family's `*Item` for built-in roving focus.
+ * @bestPractice Pass glyphs via the `icon` / `dot` / `avatar` / `kbd` / `suffixIcon` props, not as children - with `render` they render around `children`, which is the label only.
+ * @category overlays
+ */
+declare const MenuItem: ({ className, size, variant, tone, radius, inset, render, active, activeIndicator, loading, indicator, selectionMode, checked, avatar, dot, icon, iconClassName, suffixIcon, kbd, kbdTone, kbdEmphasis, suffix, children, disabled, ref, ...props }: MenuItemProps) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export type { MenuItemProps } from "./menu-item-types.js";
+export { MENU_ITEM_ICON_CONTAINER_CLASSES, MENU_ITEM_ICON_SIZES, MENU_ITEM_INDICATOR_LEFT, MENU_ITEM_INDICATOR_SIZE, MENU_ITEM_INSET_CLASSES, MENU_ITEM_KBD_SIZES, MENU_ITEM_SIZE_CLASSES, menuItemVariants, } from "./menu-item-variants.js";
+export { MenuItem };

package/dist/components/menu-item/menu-item-root.js

@@ -0,0 +1,85 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { isPresent } from "../../utils/type-guards.js";
+import { MenuItemIndicators } from "./menu-item-indicators.js";
+import { MenuItemStartGlyph } from "./menu-item-start-glyph.js";
+import { MenuItemSuffix } from "./menu-item-suffix.js";
+import { MENU_ITEM_ICON_CONTAINER_CLASSES, MENU_ITEM_ICON_SIZES, MENU_ITEM_KBD_SIZES, menuItemVariants, } from "./menu-item-variants.js";
+/** Indicators, leading glyph, label and suffix laid out around `label`. */
+const menuItemContent = (p, label) => (_jsxs(_Fragment, { children: [_jsx(MenuItemIndicators, { ...p }), _jsx(MenuItemStartGlyph, { ...p }), isPresent(label) ? _jsx("span", { className: "flex-1 truncate", children: label }) : null, _jsx(MenuItemSuffix, { ...p })] }));
+/**
+ * A standalone menu item component for use in popovers, sheets, and custom menus.
+ * This is the base component that DropdownMenuItem and other menu items build upon.
+ *
+ * @bestPractice `MenuItem` is the standalone base for custom menus (popovers, sheets); inside a `DropdownMenu` / `ContextMenu` use that family's `*Item` for built-in roving focus.
+ * @bestPractice Pass glyphs via the `icon` / `dot` / `avatar` / `kbd` / `suffixIcon` props, not as children - with `render` they render around `children`, which is the label only.
+ * @category overlays
+ */
+const MenuItem = ({ className, size = "sm", variant, tone, radius, inset, render, active = false, activeIndicator = "none", loading = false, indicator, selectionMode, checked, avatar, dot, icon, iconClassName, suffixIcon, kbd, kbdTone, kbdEmphasis, suffix, children, disabled, ref, ...props }) => {
+    const resolvedSize = size ?? "sm";
+    const iconSize = MENU_ITEM_ICON_SIZES[resolvedSize];
+    const iconContainerClass = MENU_ITEM_ICON_CONTAINER_CLASSES[resolvedSize];
+    const kbdSize = MENU_ITEM_KBD_SIZES[resolvedSize];
+    const hasIndicator = isPresent(indicator);
+    const isLoading = loading ?? false;
+    const hasAvatar = isPresent(avatar);
+    // `false`/undefined hide the dot; `true` or a Tone show it.
+    const hasDot = dot !== undefined && dot !== false;
+    // Auto-enable inset when indicator is present
+    const resolvedInset = hasIndicator || inset;
+    // Disable when loading
+    const isDisabled = isLoading || disabled;
+    const computedClassName = cn(menuItemVariants({
+        className,
+        inset: resolvedInset,
+        radius,
+        size,
+        tone,
+        variant,
+    }));
+    const glyphProps = {
+        activeIndicator,
+        avatar,
+        checked,
+        dot,
+        hasAvatar,
+        hasDot,
+        hasIndicator,
+        icon,
+        iconClassName,
+        iconContainerClass,
+        iconSize,
+        indicator,
+        active,
+        isLoading,
+        kbd,
+        kbdSize,
+        kbdTone,
+        kbdEmphasis,
+        resolvedSize,
+        selectionMode,
+        suffix,
+        suffixIcon,
+    };
+    const buttonProps = render === undefined
+        ? { disabled: isDisabled, type: "button" }
+        : { disabled: undefined, type: undefined };
+    return useRender({
+        defaultTagName: "button",
+        props: {
+            className: computedClassName,
+            "data-active": active,
+            "data-component": "menu-item",
+            "data-slot": "menu-item",
+            ...buttonProps,
+            ...props,
+            children: menuItemContent(glyphProps, children),
+        },
+        ref,
+        render,
+    });
+};
+export { MENU_ITEM_ICON_CONTAINER_CLASSES, MENU_ITEM_ICON_SIZES, MENU_ITEM_INDICATOR_LEFT, MENU_ITEM_INDICATOR_SIZE, MENU_ITEM_INSET_CLASSES, MENU_ITEM_KBD_SIZES, MENU_ITEM_SIZE_CLASSES, menuItemVariants, } from "./menu-item-variants.js";
+export { MenuItem };

package/dist/components/menu-item/menu-item-start-glyph.d.ts

@@ -0,0 +1,17 @@
+import type * as React from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+import type { Tone } from "../../tokens/tone.js";
+import type { MenuItemIcon } from "./menu-item-types.js";
+/** Leading glyph with priority: loading > avatar > dot > icon. */
+declare const MenuItemStartGlyph: ({ avatar, dot, hasAvatar, hasDot, icon, iconClassName, iconContainerClass, iconSize, isLoading, }: {
+    avatar: React.ReactNode;
+    dot: boolean | Tone | undefined;
+    hasAvatar: boolean;
+    hasDot: boolean;
+    icon: MenuItemIcon;
+    iconClassName?: string | undefined;
+    iconContainerClass: string;
+    iconSize: ComponentSize;
+    isLoading: boolean;
+}) => React.ReactNode;
+export { MenuItemStartGlyph };

package/dist/components/menu-item/menu-item-start-glyph.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Center } from "../center.js";
+import { Dot } from "../dot.js";
+import { Icon } from "../icon.js";
+import { Spinner } from "../spinner.js";
+/** Leading glyph with priority: loading > avatar > dot > icon. */
+const MenuItemStartGlyph = ({ avatar, dot, hasAvatar, hasDot, icon, iconClassName, iconContainerClass, iconSize, isLoading, }) => {
+    if (isLoading) {
+        return _jsx(Spinner, { className: "shrink-0", size: iconSize });
+    }
+    if (hasAvatar) {
+        return _jsx("span", { className: "shrink-0", children: avatar });
+    }
+    if (hasDot) {
+        return (_jsx(Center, { as: "span", className: cn("shrink-0", iconContainerClass), children: _jsx(Dot, { size: "sm", tone: dot === true || dot === false ? undefined : dot }) }));
+    }
+    if (icon) {
+        return (_jsx(Icon, { className: cn("shrink-0", iconClassName), icon: icon, size: iconSize }));
+    }
+    return null;
+};
+export { MenuItemStartGlyph };

package/dist/components/menu-item/menu-item-suffix.d.ts

@@ -0,0 +1,15 @@
+import type * as React from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+import type { KbdProps } from "../kbd.js";
+import type { MenuItemIcon } from "./menu-item-types.js";
+/** Trailing suffix icon, keyboard shortcut group, or custom suffix node. */
+declare const MenuItemSuffix: ({ iconSize, kbd, kbdSize, kbdTone, kbdEmphasis, suffix, suffixIcon, }: {
+    iconSize: ComponentSize;
+    kbd?: string[] | undefined;
+    kbdSize: ComponentSize;
+    kbdTone?: KbdProps["tone"] | undefined;
+    kbdEmphasis?: KbdProps["emphasis"] | undefined;
+    suffix: React.ReactNode;
+    suffixIcon: MenuItemIcon;
+}) => React.JSX.Element;
+export { MenuItemSuffix };

package/dist/components/menu-item/menu-item-suffix.js

@@ -0,0 +1,6 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Icon } from "../icon.js";
+import { Kbd, KbdGroup } from "../kbd.js";
+/** Trailing suffix icon, keyboard shortcut group, or custom suffix node. */
+const MenuItemSuffix = ({ iconSize, kbd, kbdSize, kbdTone, kbdEmphasis, suffix, suffixIcon, }) => (_jsxs(_Fragment, { children: [suffixIcon ? (_jsx(Icon, { className: "shrink-0", icon: suffixIcon, size: iconSize })) : null, !suffixIcon && kbd && kbd.length > 0 ? (_jsx(KbdGroup, { size: kbdSize, children: kbd.map((key) => (_jsx(Kbd, { emphasis: kbdEmphasis, tone: kbdTone, children: key }, key))) })) : null, suffix] }));
+export { MenuItemSuffix };