@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,71 @@
+import type { useRender } from "@base-ui/react/use-render";
+import type { VariantProps } from "class-variance-authority";
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+import type { Tone } from "../../tokens/tone.js";
+import type { KbdProps } from "../kbd.js";
+import type { menuItemVariants } from "./menu-item-variants.js";
+type MenuItemIcon = LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>> | undefined;
+type MenuItemProps = Omit<React.ComponentProps<"button">, "children"> & VariantProps<typeof menuItemVariants> & {
+    /** Replace the default `<button>` with another element or component. Glyph props render inside it, around `children`; the element should carry no children of its own. */
+    render?: useRender.RenderProp | undefined;
+    /** Whether the item is in an active/selected state */
+    active?: boolean | undefined;
+    /** Visual indicator for active state. "dot" shows grey dot normally, green when active. "check" shows green checkmark only when active. */
+    activeIndicator?: "dot" | "check" | "none" | undefined;
+    /** Show loading spinner in place of icon */
+    loading?: boolean | undefined;
+    /** Indicator element for checkbox/radio items (absolutely positioned on left). Automatically enables inset. */
+    indicator?: React.ReactNode;
+    /** Selection visual: "checkbox" renders Checkbox, "radio" renders radio circle. Defaults to "checkbox" when `checked` is set. */
+    selectionMode?: "checkbox" | "radio" | undefined;
+    /** Checked state. Renders the selectionMode indicator inline. When undefined, no indicator renders. */
+    checked?: boolean | undefined;
+    /** Avatar element to display at the start (takes precedence over icon and dot) */
+    avatar?: React.ReactNode;
+    /** Dot indicator at the start, centred in the icon space (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it. */
+    dot?: boolean | Tone | undefined;
+    /** Icon to display at the start */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>> | undefined;
+    /** Additional className for the icon */
+    iconClassName?: string | undefined;
+    /** Icon to display at the end (e.g., checkmark, chevron). Takes precedence over kbd. */
+    suffixIcon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>> | undefined;
+    /** Keyboard shortcut keys to display (e.g., ["⌘", "C"]). Ignored if suffixIcon is provided. */
+    kbd?: string[] | undefined;
+    /** Tone for kbd elements. Options: "neutral" (default), "brand", "danger". */
+    kbdTone?: KbdProps["tone"] | undefined;
+    /** Emphasis for kbd elements. Options: "solid" (default), "soft", "outline", "ghost". */
+    kbdEmphasis?: KbdProps["emphasis"] | undefined;
+    /** Content to display at the end after suffixIcon/kbd (e.g., custom content) */
+    suffix?: React.ReactNode;
+    /** Text label for the menu item. Use `icon` prop for icons, not children. */
+    children?: React.ReactElement | string | number | undefined;
+};
+/** Everything the glyph parts need, resolved once by MenuItem. */
+interface MenuItemContentProps {
+    activeIndicator: "dot" | "check" | "none";
+    avatar: React.ReactNode;
+    checked?: boolean | undefined;
+    dot: boolean | Tone | undefined;
+    hasAvatar: boolean;
+    hasDot: boolean;
+    hasIndicator: boolean;
+    icon: MenuItemIcon;
+    iconClassName?: string | undefined;
+    iconContainerClass: string;
+    iconSize: ComponentSize;
+    indicator: React.ReactNode;
+    active: boolean;
+    isLoading: boolean;
+    kbd?: string[] | undefined;
+    kbdSize: ComponentSize;
+    kbdTone?: KbdProps["tone"] | undefined;
+    kbdEmphasis?: KbdProps["emphasis"] | undefined;
+    resolvedSize: ComponentSize;
+    selectionMode?: "checkbox" | "radio" | undefined;
+    suffix: React.ReactNode;
+    suffixIcon: MenuItemIcon;
+}
+export type { MenuItemContentProps, MenuItemIcon, MenuItemProps };

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

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

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

@@ -0,0 +1,43 @@
+import type { ComponentSize } from "../../tokens/size.js";
+/**
+ * Size classes for menu items - shared across MenuItem, DropdownMenuItem, etc.
+ */
+declare const MENU_ITEM_SIZE_CLASSES: Record<ComponentSize, string>;
+/**
+ * Icon size mapping for menu items.
+ */
+declare const MENU_ITEM_ICON_SIZES: Record<ComponentSize, ComponentSize>;
+/**
+ * Icon container size classes for centring dots within icon space.
+ */
+declare const MENU_ITEM_ICON_CONTAINER_CLASSES: Record<ComponentSize, string>;
+/**
+ * Kbd size mapping for menu items.
+ */
+declare const MENU_ITEM_KBD_SIZES: Record<ComponentSize, ComponentSize>;
+/**
+ * Inset padding for menu items without icons (aligns with items that have icons).
+ */
+declare const MENU_ITEM_INSET_CLASSES: Record<ComponentSize, string>;
+/**
+ * Indicator container size for checkbox/radio items.
+ */
+declare const MENU_ITEM_INDICATOR_SIZE: Record<ComponentSize, string>;
+/**
+ * Indicator left position for checkbox/radio items.
+ */
+declare const MENU_ITEM_INDICATOR_LEFT: Record<ComponentSize, string>;
+/**
+ * menuItemVariants variant class helper for MenuItem.
+ * Import from "@instruments/materia-ui/components/menu-item".
+ * Composes with Base UI parts through `render`.
+ * Uses variant-based styling via class-variance-authority.
+ */
+declare const menuItemVariants: (props?: ({
+    size?: "2xl" | "2xs" | "3xl" | "base" | "lg" | "sm" | "xl" | "xs" | null | undefined;
+    variant?: "default" | "input" | "outline" | null | undefined;
+    tone?: "danger" | "neutral" | null | undefined;
+    radius?: "full" | "rounded" | "square" | null | undefined;
+    inset?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+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, };

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

@@ -0,0 +1,157 @@
+import { cva } from "class-variance-authority";
+import { DISABLED } from "../../tokens/input-shell.js";
+import { RADIUS_CLASSES } from "../../tokens/radius.js";
+/**
+ * Size classes for menu items - shared across MenuItem, DropdownMenuItem, etc.
+ */
+const MENU_ITEM_SIZE_CLASSES = {
+    "2xl": "min-h-12 gap-3 px-5 py-3.5 text-paragraph",
+    "2xs": "min-h-6 gap-1 px-2 py-0.5 text-caption",
+    "3xl": "min-h-14 gap-4 px-5 py-4 text-paragraph-lg",
+    base: "min-h-9 gap-2 px-3 py-2 text-paragraph-sm",
+    lg: "min-h-10 gap-2.5 px-3.5 py-2.5 text-paragraph-sm",
+    sm: "min-h-8 gap-2 px-2.5 py-1.5 text-paragraph-sm",
+    xl: "min-h-11 gap-2 px-4 py-3 text-paragraph-sm",
+    xs: "min-h-7 gap-1.5 px-2.5 py-1 text-caption",
+};
+/**
+ * Icon size mapping for menu items.
+ */
+const MENU_ITEM_ICON_SIZES = {
+    "2xl": "base",
+    "2xs": "2xs",
+    "3xl": "base",
+    base: "xs",
+    lg: "sm",
+    sm: "xs",
+    xl: "xs",
+    xs: "2xs",
+};
+/**
+ * Icon container size classes for centring dots within icon space.
+ */
+const MENU_ITEM_ICON_CONTAINER_CLASSES = {
+    // matches Icon base
+    "2xl": "size-5",
+    // matches Icon 2xs
+    "2xs": "size-3",
+    // matches Icon base
+    "3xl": "size-5",
+    // matches Icon xs
+    base: "size-4",
+    // matches Icon sm
+    lg: "size-4.5",
+    // matches Icon xs
+    sm: "size-4",
+    // matches Icon xs
+    xl: "size-4",
+    // matches Icon 2xs
+    xs: "size-3",
+};
+/**
+ * Kbd size mapping for menu items.
+ */
+const MENU_ITEM_KBD_SIZES = {
+    "2xl": "base",
+    "2xs": "2xs",
+    "3xl": "base",
+    base: "xs",
+    lg: "sm",
+    sm: "xs",
+    xl: "sm",
+    xs: "2xs",
+};
+/**
+ * Inset padding for menu items without icons (aligns with items that have icons).
+ */
+const MENU_ITEM_INSET_CLASSES = {
+    "2xl": "pl-14",
+    "2xs": "pl-6",
+    "3xl": "pl-16",
+    base: "pl-9",
+    lg: "pl-11",
+    sm: "pl-8",
+    xl: "pl-12",
+    xs: "pl-7",
+};
+/**
+ * Indicator container size for checkbox/radio items.
+ */
+const MENU_ITEM_INDICATOR_SIZE = {
+    "2xl": "size-5",
+    "2xs": "size-3",
+    "3xl": "size-6",
+    base: "size-4",
+    lg: "size-4.5",
+    sm: "size-3.5",
+    xl: "size-5",
+    xs: "size-3",
+};
+/**
+ * Indicator left position for checkbox/radio items.
+ */
+const MENU_ITEM_INDICATOR_LEFT = {
+    "2xl": "left-4",
+    "2xs": "left-1",
+    "3xl": "left-5",
+    base: "left-2.5",
+    lg: "left-3",
+    sm: "left-2",
+    xl: "left-3.5",
+    xs: "left-1.5",
+};
+/**
+ * menuItemVariants variant class helper for MenuItem.
+ * Import from "@instruments/materia-ui/components/menu-item".
+ * Composes with Base UI parts through `render`.
+ * Uses variant-based styling via class-variance-authority.
+ */
+const menuItemVariants = cva(`duration-quick hover:duration-instant focus:duration-instant focus-visible:duration-instant relative flex w-full cursor-default items-center text-left whitespace-nowrap transition-colors outline-none select-none data-disabled:pointer-events-none data-disabled:opacity-50 ${DISABLED}`, {
+    compoundVariants: [
+        { className: MENU_ITEM_INSET_CLASSES["2xs"], inset: true, size: "2xs" },
+        { className: MENU_ITEM_INSET_CLASSES.xs, inset: true, size: "xs" },
+        { className: MENU_ITEM_INSET_CLASSES.sm, inset: true, size: "sm" },
+        { className: MENU_ITEM_INSET_CLASSES.base, inset: true, size: "base" },
+        { className: MENU_ITEM_INSET_CLASSES.lg, inset: true, size: "lg" },
+        { className: MENU_ITEM_INSET_CLASSES.xl, inset: true, size: "xl" },
+        { className: MENU_ITEM_INSET_CLASSES["2xl"], inset: true, size: "2xl" },
+        { className: MENU_ITEM_INSET_CLASSES["3xl"], inset: true, size: "3xl" },
+        // Smaller border radius for smallest sizes when using rounded
+        { className: "rounded-sm", radius: "rounded", size: "2xs" },
+        { className: "rounded-sm", radius: "rounded", size: "xs" },
+    ],
+    defaultVariants: {
+        inset: false,
+        radius: "full",
+        size: "sm",
+        tone: "neutral",
+        variant: "default",
+    },
+    variants: {
+        size: MENU_ITEM_SIZE_CLASSES,
+        // Surface axis (background/hover treatment). The former `destructive`
+        // member split off onto the orthogonal `tone` axis below, so a
+        // destructive item of any surface is now expressible.
+        variant: {
+            default: "hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground data-[active=true]:bg-accent data-[active=true]:text-accent-foreground data-[active=true]:font-medium",
+            input: "hover:bg-input hover:text-foreground focus:bg-input focus:text-foreground focus-visible:bg-input focus-visible:text-foreground data-[active=true]:bg-input data-[active=true]:text-foreground data-[active=true]:font-medium",
+            outline: "bg-background ring-border hover:bg-accent hover:text-accent-foreground hover:ring-accent focus:bg-accent focus:text-accent-foreground focus:ring-accent focus-visible:bg-accent focus-visible:text-accent-foreground focus-visible:ring-accent data-[active=true]:bg-accent data-[active=true]:text-accent-foreground data-[active=true]:ring-accent ring-1 data-[active=true]:font-medium",
+        },
+        // Semantic tone axis. `danger` carries the former destructive-variant
+        // classes verbatim; layered over a surface it overrides the surface's
+        // hover/focus colours via tailwind-merge to reproduce the destructive
+        // look. Active keeps the danger signal - destructive foreground on a
+        // destructive tint one step stronger than hover (/20 vs /10) - instead
+        // of falling through to the surface's neutral `bg-accent` active state.
+        tone: {
+            neutral: "",
+            danger: "text-destructive hover:bg-destructive/10 hover:text-destructive focus:bg-destructive/10 focus:text-destructive focus-visible:bg-destructive/10 focus-visible:text-destructive data-[active=true]:bg-destructive/20 data-[active=true]:text-destructive [&_svg:not([class*='text-'])]:text-destructive data-[active=true]:font-medium",
+        },
+        radius: RADIUS_CLASSES,
+        inset: {
+            true: "",
+            false: "",
+        },
+    },
+});
+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, };

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

@@ -0,0 +1 @@
+export { MENU_ITEM_ICON_SIZES, MENU_ITEM_INDICATOR_LEFT, MENU_ITEM_INDICATOR_SIZE, MENU_ITEM_INSET_CLASSES, MENU_ITEM_KBD_SIZES, MENU_ITEM_SIZE_CLASSES, MenuItem, type MenuItemProps, menuItemVariants, } from "./menu-item/menu-item-root.js";

package/dist/components/menu-item.js

@@ -0,0 +1 @@
+export { MENU_ITEM_ICON_SIZES, MENU_ITEM_INDICATOR_LEFT, MENU_ITEM_INDICATOR_SIZE, MENU_ITEM_INSET_CLASSES, MENU_ITEM_KBD_SIZES, MENU_ITEM_SIZE_CLASSES, MenuItem, menuItemVariants, } from "./menu-item/menu-item-root.js";

package/dist/components/menu-parts.d.ts

@@ -0,0 +1,151 @@
+import { Menu as MenuPrimitive } from "@base-ui/react/menu";
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { MenuContentWidth, MenuOverflow, MenuSurface } from "../tokens/menu-content.js";
+import type { Radius } from "../tokens/radius.js";
+import type { ComponentSize } from "../tokens/size.js";
+import type { Tone } from "../tokens/tone.js";
+import type { MenuItemProps } from "./menu-item/menu-item-root.js";
+/**
+ * Internal factory for the menu families (DropdownMenu / ContextMenu /
+ * Menubar). The three compose the same Base UI Menu parts (ContextMenu's and
+ * Menubar's popups are Menu's own) and wrap them identically, apart from the
+ * family Context, the `data-slot` identity and a few Content defaults, so every
+ * shared part is built here once from a family identity by {@link makeMenuParts}.
+ *
+ * Like `overlay-primitives.ts` this is a plain `.ts` under `components/`, so it
+ * is invisible to the `.tsx`-only api-report scan and consumed only by sibling
+ * menu part files. Unlike that module the parts read React context, so it
+ * carries a `"use client"` directive.
+ */
+/** Positioning props accepted on every menu `*Content` and forwarded to the Base UI Positioner. */
+type MenuPositionProps = Pick<MenuPrimitive.Positioner.Props, "align" | "alignOffset" | "anchor" | "arrowPadding" | "collisionAvoidance" | "collisionBoundary" | "collisionPadding" | "disableAnchorTracking" | "side" | "sideOffset" | "sticky">;
+/** Base UI Popup props plus the positioning props, with a string `className`. */
+export type MenuPopupProps = Omit<MenuPrimitive.Popup.Props, "className"> & MenuPositionProps & {
+    className?: string;
+};
+/** Default Positioner offsets/alignment a family applies when the caller omits them. */
+interface MenuPositionDefaults {
+    align?: MenuPositionProps["align"];
+    alignOffset?: MenuPositionProps["alignOffset"];
+    sideOffset?: MenuPositionProps["sideOffset"];
+}
+/** Minimum shape every menu family's context value shares. */
+interface MenuContextValue {
+    itemRadiusClass: string;
+    size: ComponentSize;
+}
+/** Props for a menu SubContent: the Content's popup props plus a `size` override. */
+export type MenuSubContentProps = MenuPopupProps & {
+    size?: ComponentSize;
+};
+/** Props for a menu Label: Base UI `GroupLabel` props with a string `className`. */
+export type MenuLabelProps = Omit<MenuPrimitive.GroupLabel.Props, "className"> & {
+    className?: string;
+};
+/** Props for a menu Item. */
+export type MenuItemPartProps = Omit<MenuPrimitive.Item.Props, "children" | "className" | "render"> & {
+    className?: string;
+    inset?: boolean;
+    tone?: Extract<Tone, "neutral" | "danger">;
+    avatar?: React.ReactNode;
+    /** Dot indicator at the start (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it. */
+    dot?: boolean | Tone;
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    suffixIcon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    kbd?: string[];
+    suffix?: React.ReactNode;
+    /** Whether the item is in an active/selected state */
+    active?: boolean;
+    /** Visual indicator for active state. "dot" shows grey dot normally, green when active. "check" shows green checkmark only when active. */
+    activeIndicator?: "dot" | "check" | "none";
+    /** Replace the default `<button>` row (e.g. with a link); glyph props render inside it, around `children`. */
+    render?: MenuItemProps["render"];
+    /** Text label. Use `icon` prop for icons, not children. */
+    children?: React.ReactElement | string | number;
+};
+/** Props shared by the CheckboxItem, RadioItem and SubTrigger rows over their Base UI part. */
+type MenuRowProps<P> = Omit<P, "children" | "className" | "render"> & {
+    className?: string;
+    /** Replace the default `<button>` row; glyph props render inside it, around `children`. */
+    render?: MenuItemProps["render"];
+    /** Text label. Use `icon` prop for icons, not children. */
+    children?: React.ReactElement | string | number;
+};
+/** Props for a menu CheckboxItem. */
+export type MenuCheckboxItemProps = MenuRowProps<MenuPrimitive.CheckboxItem.Props>;
+/** Props for a menu RadioItem. */
+export type MenuRadioItemProps = MenuRowProps<MenuPrimitive.RadioItem.Props>;
+/** Props for a menu SubTrigger. */
+export type MenuSubTriggerProps = MenuRowProps<MenuPrimitive.SubmenuTrigger.Props> & {
+    inset?: boolean;
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+};
+/** Props for a menu Separator. */
+export type MenuSeparatorProps = Omit<React.ComponentProps<typeof MenuPrimitive.Separator>, "className"> & {
+    className?: string;
+    spacing?: "default" | "compact";
+};
+/** Props for a menu Content. */
+export type MenuContentProps = MenuPopupProps & {
+    size?: ComponentSize;
+    /** Border radius for menu items. When "full", items become pill-shaped. */
+    itemRadius?: Radius;
+    /** Surface density. Compact maps to the 16px-radius, 4px-padding menu surface. */
+    surface?: MenuSurface;
+    /** Named content widths from the design system. */
+    contentWidth?: MenuContentWidth;
+    /** Outer content overflow behaviour. Use hidden when a child owns scrolling. */
+    overflow?: MenuOverflow;
+};
+/** The Content defaults that differ between families. */
+interface MenuContentConfig {
+    /** Positioner defaults applied when the caller omits them. */
+    positioning: MenuPositionDefaults;
+    /** Popup minimum width class, e.g. "min-w-32". Must appear literally in the family's source for Tailwind. */
+    minWidthClass: string;
+    /** Item radius class used when `itemRadius` is unset; omit to follow the surface's concentric radius. */
+    defaultItemRadiusClass?: string;
+}
+/** A family's identity: its names, its context and its Content defaults. */
+interface MenuFamilyConfig {
+    /** Component-name prefix for `displayName`, e.g. "DropdownMenu". */
+    name: string;
+    /** `data-slot` prefix, e.g. "dropdown-menu". */
+    slot: string;
+    /** The family's context object, provided by Content and SubContent. */
+    Context: React.Context<MenuContextValue>;
+    /** The family's context hook, read by every part for `size` / `itemRadiusClass`. */
+    useMenuContext: () => MenuContextValue;
+    /** Content defaults that differ between families. */
+    content: MenuContentConfig;
+}
+/** The parts {@link makeMenuParts} builds for one family. */
+/** A built menu part: a component taking `P`. */
+type MenuPart<P> = (props: P) => React.JSX.Element;
+export interface MenuFamilyParts {
+    CheckboxItem: MenuPart<MenuCheckboxItemProps>;
+    Content: MenuPart<MenuContentProps>;
+    Group: MenuPart<React.ComponentProps<typeof MenuPrimitive.Group>>;
+    Item: MenuPart<MenuItemPartProps>;
+    Label: MenuPart<MenuLabelProps & {
+        inset?: boolean;
+    }>;
+    Portal: MenuPart<React.ComponentProps<typeof MenuPrimitive.Portal>>;
+    RadioGroup: MenuPart<React.ComponentProps<typeof MenuPrimitive.RadioGroup>>;
+    RadioItem: MenuPart<MenuRadioItemProps>;
+    Separator: MenuPart<MenuSeparatorProps>;
+    Shortcut: MenuPart<React.ComponentProps<"span">>;
+    Sub: MenuPart<React.ComponentProps<typeof MenuPrimitive.SubmenuRoot>>;
+    SubContent: MenuPart<MenuSubContentProps>;
+    SubTrigger: MenuPart<MenuSubTriggerProps>;
+}
+/**
+ * Builds every part a menu family shares with the other two, stamped with the
+ * family's `data-slot` identity and reading the family's context: Content,
+ * Item, CheckboxItem, RadioItem, RadioGroup, Group, Label, Separator, Shortcut,
+ * Portal, Sub, SubTrigger and SubContent. Each family calls this once and its
+ * part files re-export the results under the public names.
+ */
+export declare const makeMenuParts: (family: MenuFamilyConfig) => MenuFamilyParts;
+export {};