@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+export interface AvatarContextValue {
+    size: ComponentSize;
+}
+export interface AvatarProviderProps {
+    children: ReactNode;
+    size: ComponentSize;
+}
+/**
+ * AvatarProvider UI component.
+ * Import from "@instruments/materia-ui/components/avatar".
+ */
+export declare const AvatarProvider: ({ children, size }: AvatarProviderProps) => import("react").JSX.Element;
+/**
+ * useAvatarContext React hook.
+ * Import from "@instruments/materia-ui/components/avatar".
+ */
+export declare const useAvatarContext: () => AvatarContextValue;
+/**
+ * The size an enclosing `AvatarGroup` imposes, or `undefined` outside a group.
+ */
+export declare const useAvatarGroupSize: () => ComponentSize | undefined;

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

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useMemo } from "react";
+const AvatarContext = createContext(undefined);
+/**
+ * AvatarProvider UI component.
+ * Import from "@instruments/materia-ui/components/avatar".
+ */
+export const AvatarProvider = ({ children, size }) => {
+    const value = useMemo(() => ({ size }), [size]);
+    return (_jsx(AvatarContext.Provider, { value: value, children: children }));
+};
+/**
+ * useAvatarContext React hook.
+ * Import from "@instruments/materia-ui/components/avatar".
+ */
+export const useAvatarContext = () => {
+    const context = use(AvatarContext);
+    if (!context) {
+        throw new Error("useAvatarContext must be used within an AvatarProvider");
+    }
+    return context;
+};
+/**
+ * The size an enclosing `AvatarGroup` imposes, or `undefined` outside a group.
+ */
+export const useAvatarGroupSize = () => use(AvatarContext)?.size;

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

@@ -0,0 +1,19 @@
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import type * as React from "react";
+import type { AvatarSize } from "../avatar/avatar-root.js";
+export type AvatarFallbackProps = Omit<AvatarPrimitive.Fallback.Props, "style"> & {
+    /** Inline styles merged over the derived colours; a plain object only. */
+    style?: React.CSSProperties | undefined;
+    /** @default "base" */
+    size?: AvatarSize | undefined;
+    /**
+     * Full name or label used to:
+     * - Derive 1–2 letter initials for fallback text (when children not provided)
+     * - Seed deterministic background/text colour for readability
+     */
+    name?: string | undefined;
+};
+/**
+ * Shown when the avatar image is absent or still loading; derives 1–2 initials from `name` (a single initial at `2xs`/`xs`) and seeds a deterministic background/text colour from it.
+ */
+export declare const AvatarFallback: ({ className, size, children, style, name, ...props }: AvatarFallbackProps) => React.JSX.Element;

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

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { getColorFromName, getInitials, getReadableTextColor, } from "../../tokens/color.js";
+import { isString, hasText } from "../../utils/type-guards.js";
+// Avatar fallback background opacity (50%) and hex parsing constants
+const AVATAR_BG_ALPHA = 0.5;
+const HEX_PREFIX_RE_AVATAR = /^#/u;
+const HEX_CHARS_PER_CHANNEL = 2;
+const RED_START = 0;
+const GREEN_START = RED_START + HEX_CHARS_PER_CHANNEL;
+const BLUE_START = GREEN_START + HEX_CHARS_PER_CHANNEL;
+const TEXT_SIZE_CLASS = {
+    "2xl": "text-[19px]",
+    "2xs": "text-[8px]",
+    "3xl": "text-[22px]",
+    "4xl": "text-3xl",
+    "5xl": "text-4xl",
+    "6xl": "text-5xl",
+    base: "text-[13px]",
+    lg: "text-[15px]",
+    sm: "text-2xs",
+    xl: "text-[17px]",
+    xs: "text-[9px]",
+};
+const hexToRgba = (hex, alpha) => {
+    const normalized = hex.replace(HEX_PREFIX_RE_AVATAR, "");
+    const r = Number.parseInt(normalized.slice(RED_START, RED_START + HEX_CHARS_PER_CHANNEL), 16);
+    const g = Number.parseInt(normalized.slice(GREEN_START, GREEN_START + HEX_CHARS_PER_CHANNEL), 16);
+    const b = Number.parseInt(normalized.slice(BLUE_START, BLUE_START + HEX_CHARS_PER_CHANNEL), 16);
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+};
+const computeFallbackColors = (colorSeed) => {
+    const backgroundColor = hasText(colorSeed)
+        ? getColorFromName(colorSeed)
+        : undefined;
+    const color = hasText(backgroundColor)
+        ? getReadableTextColor(backgroundColor)
+        : undefined;
+    const bgWithOpacity = hasText(backgroundColor)
+        ? hexToRgba(backgroundColor, AVATAR_BG_ALPHA)
+        : undefined;
+    return { backgroundColor, bgWithOpacity, color };
+};
+/**
+ * Shown when the avatar image is absent or still loading; derives 1–2 initials from `name` (a single initial at `2xs`/`xs`) and seeds a deterministic background/text colour from it.
+ */
+export const AvatarFallback = ({ className, size = "base", children, style, name, ...props }) => {
+    // children may be a raw string (trimmed, then used both as the displayed
+    // text and to seed the deterministic background/text colour) or arbitrary
+    // nodes. Switching to subcomponents would change the public props API.
+    const providedText = isString(children) ? children.trim() : undefined;
+    const trimmedName = name?.trim();
+    const derivedInitials = !hasText(providedText) && hasText(trimmedName)
+        ? getInitials(trimmedName)
+        : undefined;
+    // For tiny sizes (2xs, xs), show only first initial
+    const shouldShowSingleInitial = size === "2xs" || size === "xs";
+    const finalInitials = shouldShowSingleInitial && hasText(derivedInitials)
+        ? derivedInitials.charAt(0)
+        : derivedInitials;
+    /** fallback content area */
+    const fallbackContent = providedText ?? finalInitials;
+    // Seed colour from full name when available for better distribution; fall back to displayed text.
+    const colorSeed = trimmedName ?? fallbackContent;
+    const { bgWithOpacity, color } = computeFallbackColors(colorSeed);
+    return (_jsx(AvatarPrimitive.Fallback, { className: cn("bg-muted flex size-full items-center justify-center font-medium uppercase", TEXT_SIZE_CLASS[size], className), "data-component": "avatar-fallback", "data-slot": "avatar-fallback", style: { backgroundColor: bgWithOpacity, color, ...style }, ...props, children: children ?? fallbackContent }));
+};

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

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+import type { ComponentSize } from "../../tokens/size.js";
+export type AvatarGroupVariant = "default" | "outline" | "ghost" | "pill";
+export interface AvatarGroupProps {
+    /** Enable hover animation */
+    animate?: boolean | undefined;
+    /**
+     * The avatars to show, in order. Every avatar takes the group's `size`
+     * through context, so pass plain `<Avatar>` elements with a `key`.
+     */
+    avatars: readonly ReactNode[];
+    /** CSS class name */
+    className?: string | undefined;
+    /** Accessibility labels for each avatar */
+    labels?: string[] | undefined;
+    /** Maximum number of avatars to display before showing surplus */
+    max?: number | undefined;
+    /** Selection change handler */
+    onSelect?: ((index: number) => void) | undefined;
+    /** Custom render function for surplus count */
+    renderSurplus?: ((count: number) => ReactNode) | undefined;
+    /** Enable avatar selection */
+    selectable?: boolean | undefined;
+    /** Selected avatar index */
+    selectedIndex?: number | undefined;
+    /** Size as a `ComponentSize` token, or an explicit pixel number. @default "base" */
+    size?: ComponentSize | number | undefined;
+    /** Spacing between avatars */
+    spacing?: "tight" | "normal" | "loose" | undefined;
+    /** Visual variant - controls borders and surplus styling */
+    variant?: AvatarGroupVariant | undefined;
+}
+/**
+ * AvatarGroup displays a collection of avatars with overflow handling.
+ *
+ * @param variant - Visual style: "default" (ring), "outline" (border), "ghost" (no decoration), "pill" (bordered rounded container, animate not supported)
+ * @param size - Size matching button scale: "2xs" | "xs" | "sm" | "base" | "lg" | "xl" | "2xl"
+ * @param max - Maximum avatars to show before displaying "+N" surplus
+ * @param spacing - Overlap amount: "tight" | "normal" | "loose"
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup
+ *   avatars={users.map((user) => (
+ *     <Avatar key={user.id}><AvatarImage src={user.image} /></Avatar>
+ *   ))}
+ *   max={3}
+ *   size="sm"
+ *   variant="outline"
+ * />
+ * ```
+ */
+export declare const AvatarGroup: ({ avatars, className, max, size, spacing, animate, variant, renderSurplus, selectable, selectedIndex, onSelect, labels, ...props }: AvatarGroupProps) => import("react").JSX.Element;

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

@@ -0,0 +1,129 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { isValidElement } from "react";
+import { isNumber, hasText } from "../../utils/type-guards.js";
+import { AVATAR_SIZE_PX } from "../avatar/avatar-root.js";
+import { Center } from "../center.js";
+import { Flex } from "../flex.js";
+import { AvatarProvider } from "./avatar-context.js";
+const SPACING_CLASS = {
+    loose: "-space-x-0.5",
+    normal: "-space-x-1",
+    tight: "-space-x-2",
+};
+const HOVER_SPACING = {
+    loose: "hover:space-x-1",
+    normal: "hover:space-x-0.5",
+    tight: "hover:space-x-0",
+};
+const AVATAR_RING_VARIANT = {
+    default: "ring-2 ring-background",
+    ghost: "",
+    outline: "ring-1 ring-border",
+    pill: "ring-2 ring-background",
+};
+const SURPLUS_VARIANT = {
+    default: "bg-muted text-muted-foreground ring-2 ring-background",
+    ghost: "bg-transparent text-muted-foreground",
+    outline: "bg-transparent text-muted-foreground ring-1 ring-border",
+    pill: "bg-white text-muted-foreground ring-2 ring-white",
+};
+const getItemKey = (child, label, index) => {
+    const childKey = isValidElement(child) ? child.key : null;
+    return childKey ?? (hasText(label) ? `${label}-${index}` : `avatar-${index}`);
+};
+const AvatarGroupItem = ({ animate, children, displayCount, index, label, onSelect, px, ringClass, selectable, selected, }) => {
+    if (selectable) {
+        return (_jsx("button", { "aria-label": label, "aria-pressed": selected, className: cn("relative inline-flex shrink-0 rounded-full border-0 bg-transparent p-0", ringClass, animate && "duration-normal transition-shadow", "hover:ring-primary/50 cursor-pointer", selected && "ring-accent-foreground ring-2 ring-offset-2"), "data-avatar-index": index, onClick: () => {
+                if (onSelect) {
+                    onSelect(index);
+                }
+            }, style: {
+                height: px,
+                width: px,
+                zIndex: selected ? displayCount + 1 : displayCount - index,
+            }, type: "button", children: children }));
+    }
+    return (_jsx(Flex, { className: cn("relative shrink-0 rounded-full", ringClass, animate && "duration-normal transition-shadow"), "data-avatar-index": index, inline: true, style: {
+            height: px,
+            width: px,
+            zIndex: displayCount - index,
+        }, children: children }));
+};
+const AvatarGroupSurplus = ({ animate, count, px, renderSurplus, variant, }) => {
+    if (count <= 0) {
+        return null;
+    }
+    return (_jsx(Center, { className: cn("relative shrink-0 rounded-full", "text-caption font-medium", SURPLUS_VARIANT[variant], animate && "duration-normal transition-shadow"), "data-component": "avatar-surplus", inline: true, style: {
+            height: px,
+            width: px,
+            zIndex: 0,
+        }, children: renderSurplus ? renderSurplus(count) : `+${count}` }));
+};
+const pxToComponentSize = (px) => {
+    const sizeMap = [
+        "2xs",
+        "xs",
+        "sm",
+        "base",
+        "lg",
+        "xl",
+        "2xl",
+    ];
+    const sizes = sizeMap.map((s) => AVATAR_SIZE_PX[s]);
+    let closestIndex = 0;
+    for (let i = 1; i < sizes.length; i += 1) {
+        const candidate = sizes[i] ?? 0;
+        const current = sizes[closestIndex] ?? 0;
+        if (Math.abs(candidate - px) < Math.abs(current - px)) {
+            closestIndex = i;
+        }
+    }
+    return sizeMap[closestIndex] ?? "base";
+};
+/**
+ * AvatarGroup displays a collection of avatars with overflow handling.
+ *
+ * @param variant - Visual style: "default" (ring), "outline" (border), "ghost" (no decoration), "pill" (bordered rounded container, animate not supported)
+ * @param size - Size matching button scale: "2xs" | "xs" | "sm" | "base" | "lg" | "xl" | "2xl"
+ * @param max - Maximum avatars to show before displaying "+N" surplus
+ * @param spacing - Overlap amount: "tight" | "normal" | "loose"
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup
+ *   avatars={users.map((user) => (
+ *     <Avatar key={user.id}><AvatarImage src={user.image} /></Avatar>
+ *   ))}
+ *   max={3}
+ *   size="sm"
+ *   variant="outline"
+ * />
+ * ```
+ */
+export const AvatarGroup = ({ avatars, className, max, size = "base", spacing = "normal", animate = false, variant = "default", renderSurplus, selectable = false, selectedIndex, onSelect, labels, ...props }) => {
+    const totalCount = avatars.length;
+    const displayCount = max === undefined ? totalCount : Math.min(max, totalCount);
+    const surplusCount = max !== undefined && totalCount > max ? totalCount - max : 0;
+    // Handle size as either ComponentSize or number (pixels)
+    const componentSize = isNumber(size)
+        ? pxToComponentSize(size)
+        : size;
+    const px = isNumber(size) ? size : AVATAR_SIZE_PX[componentSize];
+    const ringClass = AVATAR_RING_VARIANT[variant];
+    const displayChildren = avatars
+        .slice(0, displayCount)
+        .map((avatar, index) => {
+        const label = labels?.[index];
+        return (_jsx(AvatarGroupItem, { animate: animate, displayCount: displayCount, index: index, label: label, onSelect: onSelect, px: px, ringClass: ringClass, selectable: selectable, selected: selectable && selectedIndex === index, children: avatar }, getItemKey(avatar, label, index)));
+    });
+    const content = (_jsxs(AvatarProvider, { size: componentSize, children: [displayChildren, _jsx(AvatarGroupSurplus, { animate: animate, count: surplusCount, px: px, renderSurplus: renderSurplus, variant: variant })] }));
+    if (variant === "pill") {
+        return (_jsx(Flex, { align: "center", className: cn("border-border rounded-full border bg-white px-1.5 py-1", className), "data-component": "avatar-group", "data-variant": variant, inline: true, ...props, children: _jsx(Flex, { align: "center", className: SPACING_CLASS[spacing], children: content }) }));
+    }
+    return (_jsx(Flex, { align: "center", className: cn(SPACING_CLASS[spacing], animate && [
+            "*:transition-margin-shadow *:duration-normal",
+            HOVER_SPACING[spacing],
+        ], className), "data-component": "avatar-group", "data-variant": variant, ...props, children: content }));
+};

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

@@ -0,0 +1,23 @@
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+export interface AvatarImageProps extends AvatarPrimitive.Image.Props {
+    /** Accessible alt text describing the avatar. Required for screen readers. */
+    alt: string;
+}
+/**
+ * Image layer of an avatar; Base UI only mounts it once it has loaded, revealing the sibling `AvatarFallback` on error or while loading.
+ *
+ * Supports `render` for custom image components (e.g., Next.js Image).
+ * The rendered element must accept and forward: src, alt, className, onLoad.
+ *
+ * @example
+ * // With Next.js Image
+ * <Avatar size="6xl">
+ *   <AvatarImage
+ *     alt={name}
+ *     render={<Image fill sizes="128px" src={url} alt={name} />}
+ *     src={url}
+ *   />
+ *   <AvatarFallback name={name} size="6xl" />
+ * </Avatar>
+ */
+export declare const AvatarImage: ({ className, ...props }: AvatarImageProps) => import("react").JSX.Element;

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

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Image layer of an avatar; Base UI only mounts it once it has loaded, revealing the sibling `AvatarFallback` on error or while loading.
+ *
+ * Supports `render` for custom image components (e.g., Next.js Image).
+ * The rendered element must accept and forward: src, alt, className, onLoad.
+ *
+ * @example
+ * // With Next.js Image
+ * <Avatar size="6xl">
+ *   <AvatarImage
+ *     alt={name}
+ *     render={<Image fill sizes="128px" src={url} alt={name} />}
+ *     src={url}
+ *   />
+ *   <AvatarFallback name={name} size="6xl" />
+ * </Avatar>
+ */
+export const AvatarImage = ({ className, ...props }) => (_jsx(AvatarPrimitive.Image, { className: cn("aspect-square size-full object-cover", className), "data-component": "avatar-image", "data-slot": "avatar-image", ...props }));

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

@@ -0,0 +1,39 @@
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import type { Radius } from "../../tokens/radius.js";
+import type { ComponentSize } from "../../tokens/size.js";
+/**
+ * Avatar-specific extended sizes beyond ComponentSize.
+ * Use for large display avatars (e.g., brand cards, profiles).
+ */
+export type AvatarExtendedSize = "4xl" | "5xl" | "6xl";
+/**
+ * All available Avatar sizes (standard + extended).
+ */
+export type AvatarSize = ComponentSize | AvatarExtendedSize;
+/**
+ * Maps each {@link AvatarSize} to its Tailwind `size-*` utility class.
+ */
+export declare const AVATAR_SIZE_CLASS: Record<AvatarSize, string>;
+/**
+ * Maps each {@link AvatarSize} to its rendered pixel dimension; used by `AvatarGroup` for pixel-based overlap layout.
+ */
+export declare const AVATAR_SIZE_PX: Record<AvatarSize, number>;
+export type AvatarRootProps = AvatarPrimitive.Root.Props & {
+    /** @default "base" */
+    size?: AvatarSize | undefined;
+    /** Border radius. Defaults to "full" (circular). */
+    radius?: Radius | undefined;
+    /** Show a decorative ring around the avatar. @default false */
+    withRing?: boolean | undefined;
+    /** Tailwind `ring-*` utility for the ring; only applies when `withRing`. @default "ring-primary" */
+    ringColor?: string | undefined;
+};
+/**
+ * Container for a user or entity avatar; compose an `AvatarImage` and `AvatarFallback` inside, and the fallback shows automatically when the image is missing or fails to load.
+ *
+ * @bestPractice Always render an `AvatarFallback` child - it is what shows while the image loads and when `src` is missing or errors; an image-only avatar renders empty on failure.
+ * @bestPractice Give `AvatarImage` a meaningful `alt`; the visual is decorative only when the fallback initials already convey the identity.
+ * @bestPractice Keep the default `radius="full"` for people; use a squared `radius` for brand/entity logos so they read as objects, not users.
+ * @category data
+ */
+export declare const AvatarRoot: ({ className, size: sizeProp, radius, withRing, ringColor, ...props }: AvatarRootProps) => import("react").JSX.Element;

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

@@ -0,0 +1,57 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useAvatarGroupSize } from "./avatar-context.js";
+/**
+ * Maps each {@link AvatarSize} to its Tailwind `size-*` utility class.
+ */
+export const AVATAR_SIZE_CLASS = {
+    "2xl": "size-14",
+    "2xs": "size-5",
+    "3xl": "size-16",
+    "4xl": "size-20",
+    "5xl": "size-24",
+    "6xl": "size-32",
+    base: "size-8",
+    lg: "size-10",
+    sm: "size-7",
+    xl: "size-12",
+    xs: "size-6",
+};
+/**
+ * Maps each {@link AvatarSize} to its rendered pixel dimension; used by `AvatarGroup` for pixel-based overlap layout.
+ */
+export const AVATAR_SIZE_PX = {
+    "2xl": 56,
+    "2xs": 20,
+    "3xl": 64,
+    "4xl": 80,
+    "5xl": 96,
+    "6xl": 128,
+    base: 32,
+    lg: 40,
+    sm: 28,
+    xl: 48,
+    xs: 24,
+};
+const RADIUS_CLASS = {
+    full: "rounded-full",
+    rounded: "rounded-md",
+    square: "rounded-none",
+};
+/**
+ * Container for a user or entity avatar; compose an `AvatarImage` and `AvatarFallback` inside, and the fallback shows automatically when the image is missing or fails to load.
+ *
+ * @bestPractice Always render an `AvatarFallback` child - it is what shows while the image loads and when `src` is missing or errors; an image-only avatar renders empty on failure.
+ * @bestPractice Give `AvatarImage` a meaningful `alt`; the visual is decorative only when the fallback initials already convey the identity.
+ * @bestPractice Keep the default `radius="full"` for people; use a squared `radius` for brand/entity logos so they read as objects, not users.
+ * @category data
+ */
+export const AvatarRoot = ({ className, size: sizeProp = "base", radius = "full", withRing = false, ringColor, ...props }) => {
+    const size = useAvatarGroupSize() ?? sizeProp;
+    return (_jsx(AvatarPrimitive.Root, { className: cn("bg-muted relative flex shrink-0 overflow-hidden", AVATAR_SIZE_CLASS[size], RADIUS_CLASS[radius], withRing && [
+            "ring-offset-background ring-2 ring-offset-2",
+            ringColor ?? "ring-primary",
+        ], className), "data-component": "avatar", "data-radius": radius, "data-size": size, "data-slot": "avatar", ...props }));
+};

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

@@ -0,0 +1,18 @@
+import type { ComponentSize } from "../../tokens/size.js";
+/** Presence states for {@link AvatarStatus}. */
+export type AvatarStatusType = "online" | "offline" | "busy" | "away" | "dnd";
+export interface AvatarStatusProps {
+    /** CSS class name */
+    className?: string;
+    /** @default "bottom-right" */
+    position?: "bottom-right" | "top-right" | "bottom-left" | "top-left";
+    /** Component size */
+    size?: ComponentSize;
+    status: AvatarStatusType;
+    /** Ring separating the dot from the avatar. @default true */
+    withBorder?: boolean;
+}
+/**
+ * Presence dot overlaid on an avatar corner, coloured by `status`; decorative (`aria-hidden`), so surface the status in text elsewhere for screen readers.
+ */
+export declare const AvatarStatus: ({ status, size, className, position, withBorder, }: AvatarStatusProps) => import("react").JSX.Element;

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

@@ -0,0 +1,30 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+const STATUS_COLOR = {
+    away: "bg-warning-accent",
+    busy: "bg-warning-accent",
+    dnd: "bg-destructive",
+    offline: "bg-muted",
+    online: "bg-affirmative-accent",
+};
+const STATUS_SIZE = {
+    "2xl": "size-4",
+    "2xs": "size-1.5",
+    "3xl": "size-5",
+    base: "size-2.5",
+    lg: "size-3",
+    sm: "size-2",
+    xl: "size-3.5",
+    xs: "size-2",
+};
+const POSITION_CLASS = {
+    "bottom-left": "bottom-0 left-0",
+    "bottom-right": "right-0 bottom-0",
+    "top-left": "top-0 left-0",
+    "top-right": "top-0 right-0",
+};
+/**
+ * Presence dot overlaid on an avatar corner, coloured by `status`; decorative (`aria-hidden`), so surface the status in text elsewhere for screen readers.
+ */
+export const AvatarStatus = ({ status, size = "base", className, position = "bottom-right", withBorder = true, }) => (_jsx("span", { "aria-hidden": "true", className: cn("absolute rounded-full", STATUS_SIZE[size], STATUS_COLOR[status], POSITION_CLASS[position], withBorder && "ring-background ring-2", className), "data-component": "avatar-status", "data-status": status }));

package/dist/components/avatar.d.ts

@@ -0,0 +1,6 @@
+export { AvatarBadge } from "./avatar/avatar-badge.js";
+export { AvatarFallback } from "./avatar/avatar-fallback.js";
+export { AvatarGroup, type AvatarGroupVariant } from "./avatar/avatar-group.js";
+export { AvatarImage } from "./avatar/avatar-image.js";
+export { AVATAR_SIZE_CLASS, AVATAR_SIZE_PX, type AvatarExtendedSize, AvatarRoot as Avatar, type AvatarSize, } from "./avatar/avatar-root.js";
+export { AvatarStatus } from "./avatar/avatar-status.js";

package/dist/components/avatar.js

@@ -0,0 +1,6 @@
+export { AvatarBadge } from "./avatar/avatar-badge.js";
+export { AvatarFallback } from "./avatar/avatar-fallback.js";
+export { AvatarGroup } from "./avatar/avatar-group.js";
+export { AvatarImage } from "./avatar/avatar-image.js";
+export { AVATAR_SIZE_CLASS, AVATAR_SIZE_PX, AvatarRoot as Avatar, } from "./avatar/avatar-root.js";
+export { AvatarStatus } from "./avatar/avatar-status.js";

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

@@ -0,0 +1,15 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { VariantProps } from "class-variance-authority";
+import type * as React from "react";
+declare const badgeButtonVariants: (props?: ({
+    variant?: "default" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface BadgeButtonProps extends useRender.ComponentProps<"button">, VariantProps<typeof badgeButtonVariants> {
+    icon?: React.ReactNode;
+}
+/**
+ * Dismiss/action button rendered inside a `Badge` (defaults to an X icon).
+ * Warns in development when icon-only and missing `aria-label`/`aria-labelledby`.
+ */
+export declare const BadgeButton: ({ className, variant, icon, children, ref, render, ...props }: BadgeButtonProps) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export {};

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

@@ -0,0 +1,49 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { X } from "lucide-react";
+import { isDevelopmentBrowser } from "../../utils/is-development-browser.js";
+import { Icon } from "../icon.js";
+const badgeButtonVariants = cva("-me-0.5 inline-flex cursor-pointer items-center justify-center rounded-md border-0 bg-transparent p-0 opacity-60 transition-opacity hover:opacity-100 [&>svg]:opacity-100!", {
+    defaultVariants: {
+        variant: "default",
+    },
+    variants: {
+        variant: {
+            default: "",
+        },
+    },
+});
+const DEFAULT_ICON = _jsx(Icon, { icon: X });
+/**
+ * Dismiss/action button rendered inside a `Badge` (defaults to an X icon).
+ * Warns in development when icon-only and missing `aria-label`/`aria-labelledby`.
+ */
+export const BadgeButton = ({ className, variant, icon = DEFAULT_ICON, children, ref, render, ...props }) => {
+    const hasChildren = Array.isArray(children)
+        ? children.length > 0
+        : children !== undefined && children !== null;
+    if (isDevelopmentBrowser() &&
+        !hasChildren &&
+        (props["aria-label"] === undefined ||
+            props["aria-label"] === null ||
+            props["aria-label"] === "") &&
+        (props["aria-labelledby"] === undefined ||
+            props["aria-labelledby"] === null ||
+            props["aria-labelledby"] === "")) {
+        console.warn("BadgeButton: Icon-only button is missing `aria-label` or `aria-labelledby`.");
+    }
+    return useRender({
+        defaultTagName: "button",
+        props: {
+            children: hasChildren ? children : icon,
+            className: cn(badgeButtonVariants({ className, variant })),
+            "data-slot": "badge-button",
+            type: render === undefined ? "button" : undefined,
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

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

@@ -0,0 +1,6 @@
+import type * as React from "react";
+export type BadgeDotProps = React.HTMLAttributes<HTMLSpanElement>;
+/**
+ * Small status dot for composing inside a `Badge`, tinted by the badge's colour.
+ */
+export declare const BadgeDot: ({ className, ...props }: React.ComponentProps<"span">) => React.JSX.Element;

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

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Small status dot for composing inside a `Badge`, tinted by the badge's colour.
+ */
+export const BadgeDot = ({ className, ...props }) => (_jsx("span", { className: cn("size-1.5 rounded-full bg-current opacity-75", className), "data-slot": "badge-dot", ...props }));