@nizivo/react 0.0.0-stage → 0.2.0

package/dist/_internal/glyphs.js

@@ -0,0 +1,87 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/_internal/glyphs.tsx
+function svg(name, paths) {
+	return /* @__PURE__ */ jsx("svg", {
+		className: `nz-glyph nz-glyph-${name}`,
+		viewBox: "0 0 24 24",
+		width: "1em",
+		height: "1em",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: 1.92,
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: paths
+	});
+}
+const SpinnerGlyph = () => svg("spinner", /* @__PURE__ */ jsx("path", { d: "M21 12a9 9 0 1 1-6.219-8.56" }));
+/** Lucide's `chevron-right`: the Breadcrumb separator, and Pagination's next (turned for previous). */
+const ChevronGlyph = () => svg("chevron", /* @__PURE__ */ jsx("path", { d: "m9 18 6-6-6-6" }));
+const ChevronsUpDownGlyph = () => svg("chevrons-up-down", /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("path", { d: "m7 15 5 5 5-5" }), /* @__PURE__ */ jsx("path", { d: "m7 9 5-5 5 5" })] }));
+const CircleXGlyph = () => svg("circle-x", /* @__PURE__ */ jsxs(Fragment, { children: [
+	/* @__PURE__ */ jsx("circle", {
+		cx: "12",
+		cy: "12",
+		r: "10"
+	}),
+	/* @__PURE__ */ jsx("path", { d: "m15 9-6 6" }),
+	/* @__PURE__ */ jsx("path", { d: "m9 9 6 6" })
+] }));
+const CircleCheckGlyph = () => svg("circle-check", /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("circle", {
+	cx: "12",
+	cy: "12",
+	r: "10"
+}), /* @__PURE__ */ jsx("path", { d: "m9 12 2 2 4-4" })] }));
+const InfoGlyph = () => svg("info", /* @__PURE__ */ jsxs(Fragment, { children: [
+	/* @__PURE__ */ jsx("circle", {
+		cx: "12",
+		cy: "12",
+		r: "10"
+	}),
+	/* @__PURE__ */ jsx("path", { d: "M12 16v-4" }),
+	/* @__PURE__ */ jsx("path", { d: "M12 8h.01" })
+] }));
+const CloseGlyph = () => svg("close", /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("path", { d: "M18 6 6 18" }), /* @__PURE__ */ jsx("path", { d: "m6 6 12 12" })] }));
+const CheckGlyph = () => svg("check", /* @__PURE__ */ jsx("path", { d: "M20 6 9 17l-5-5" }));
+const MinusGlyph = () => svg("minus", /* @__PURE__ */ jsx("path", { d: "M5 12h14" }));
+/** PasswordInput's toggle while the password is hidden. */
+const EyeGlyph = () => svg("eye", /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("path", { d: "M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0" }), /* @__PURE__ */ jsx("circle", {
+	cx: "12",
+	cy: "12",
+	r: "3"
+})] }));
+/** PasswordInput's toggle while the password is shown. */
+const EyeOffGlyph = () => svg("eye-off", /* @__PURE__ */ jsxs(Fragment, { children: [
+	/* @__PURE__ */ jsx("path", { d: "M10.733 5.076a10.744 10.744 0 0 1 11.205 6.575 1 1 0 0 1 0 .696 10.747 10.747 0 0 1-1.444 2.49" }),
+	/* @__PURE__ */ jsx("path", { d: "M14.084 14.158a3 3 0 0 1-4.242-4.242" }),
+	/* @__PURE__ */ jsx("path", { d: "M17.479 17.499a10.75 10.75 0 0 1-15.417-5.151 1 1 0 0 1 0-.696 10.75 10.75 0 0 1 4.446-5.143" }),
+	/* @__PURE__ */ jsx("path", { d: "m2 2 20 20" })
+] }));
+/** SearchField's magnifier. */
+const SearchGlyph = () => svg("search", /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("path", { d: "m21 21-4.34-4.34" }), /* @__PURE__ */ jsx("circle", {
+	cx: "11",
+	cy: "11",
+	r: "8"
+})] }));
+/** Lucide's `ellipsis` (Feather's `more-horizontal`): MobileTabBar's More. */
+const EllipsisGlyph = () => svg("ellipsis", /* @__PURE__ */ jsxs(Fragment, { children: [
+	/* @__PURE__ */ jsx("circle", {
+		cx: "12",
+		cy: "12",
+		r: "1"
+	}),
+	/* @__PURE__ */ jsx("circle", {
+		cx: "19",
+		cy: "12",
+		r: "1"
+	}),
+	/* @__PURE__ */ jsx("circle", {
+		cx: "5",
+		cy: "12",
+		r: "1"
+	})
+] }));
+//#endregion
+export { CheckGlyph, ChevronGlyph, ChevronsUpDownGlyph, CircleCheckGlyph, CircleXGlyph, CloseGlyph, EllipsisGlyph, EyeGlyph, EyeOffGlyph, InfoGlyph, MinusGlyph, SearchGlyph, SpinnerGlyph };

package/dist/_internal/keys.js

@@ -0,0 +1,62 @@
+//#region src/_internal/keys.ts
+/**
+* `"mod+shift+d"` → `["mod", "shift", "d"]`. The plus key is `plus`, or a `+` where a key is due:
+* `"mod++"` and `"mod+plus"` are both ⌘ and +.
+*/
+function splitKeys(keys) {
+	const parts = keys.split("+").map((part) => part.trim());
+	const out = [];
+	for (let index = 0; index < parts.length; index += 1) {
+		const part = parts[index] ?? "";
+		if (part !== "") out.push(part);
+		else if (parts[index + 1] === "") {
+			out.push("+");
+			index += 1;
+		}
+	}
+	return out;
+}
+/** Key name → its `aria-keyshortcuts` name (WAI-ARIA 1.2, UI Events `key` values). */
+const ARIA = {
+	cmd: "Meta",
+	command: "Meta",
+	meta: "Meta",
+	ctrl: "Control",
+	control: "Control",
+	alt: "Alt",
+	option: "Alt",
+	shift: "Shift",
+	enter: "Enter",
+	return: "Enter",
+	esc: "Escape",
+	escape: "Escape",
+	tab: "Tab",
+	backspace: "Backspace",
+	delete: "Delete",
+	space: "Space",
+	plus: "Plus",
+	"+": "Plus",
+	up: "ArrowUp",
+	down: "ArrowDown",
+	left: "ArrowLeft",
+	right: "ArrowRight"
+};
+/** One key's `aria-keyshortcuts` name; `mod` is the platform's command key, given by the caller. */
+function ariaName(key, mod) {
+	const lower = key.toLowerCase();
+	if (lower === "mod") return mod;
+	return ARIA[lower] ?? (key.length === 1 ? key.toUpperCase() : key);
+}
+/**
+* `"mod+b"` → `"Meta+B Control+B"`. The server does not know the platform, so `mod` lists both
+* alternatives (space-separated, as the attribute allows); one letter is uppercased.
+*/
+function ariaKeyShortcuts(keys) {
+	const parts = splitKeys(keys);
+	if (parts.length === 0) return void 0;
+	const apple = parts.map((key) => ariaName(key, "Meta")).join("+");
+	const other = parts.map((key) => ariaName(key, "Control")).join("+");
+	return apple === other ? apple : `${apple} ${other}`;
+}
+//#endregion
+export { ariaKeyShortcuts, splitKeys };

package/dist/_internal/modal.client.js

@@ -0,0 +1,54 @@
+"use client";
+import { createContext, use, useLayoutEffect, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/_internal/modal.client.tsx
+const NestingContext = createContext(null);
+/**
+* The nesting state of one modal popup: the modal it was opened from (`parent`, null at the root),
+* whether a modal opened from it is open (`childOpen`), and its own `nesting`, which
+* `ModalNestingScope` hands to the modals opened inside it.
+*/
+function useModalNesting() {
+	const parent = use(NestingContext);
+	const [openChildren, setOpenChildren] = useState(0);
+	return {
+		parent,
+		nesting: useMemo(() => ({ childOpened: (delta) => setOpenChildren((n) => n + delta) }), []),
+		childOpen: openChildren > 0
+	};
+}
+/** Wraps a modal popup's children: modals opened inside report to it, and it reports to its parent. */
+function ModalNestingScope({ parent, nesting, children }) {
+	return /* @__PURE__ */ jsxs(NestingContext, {
+		value: nesting,
+		children: [parent !== null && /* @__PURE__ */ jsx(OpenSignal, { parent }), children]
+	});
+}
+/** Mounted only while this popup's content is mounted, i.e. while it is open. */
+function OpenSignal({ parent }) {
+	useLayoutEffect(() => {
+		parent.childOpened(1);
+		return () => parent.childOpened(-1);
+	}, [parent]);
+	return null;
+}
+const TABBABLE = "a[href], button, input, select, textarea, summary, [tabindex], [contenteditable]:not([contenteditable=\"false\"])";
+/** The first tabbable, enabled, rendered element inside `root`, if any. */
+function firstTabbable(root) {
+	if (root === null) return null;
+	for (const element of root.querySelectorAll(TABBABLE)) if (element.tabIndex >= 0 && !element.matches(":disabled") && element.getClientRects().length > 0) return element;
+	return null;
+}
+/**
+* Focus on open (§12.2) for a modal leaf whose slots start with `name`: an element the consumer
+* marked `autoFocus` keeps it (the engine sees focus inside and leaves it); an alertdialog focuses
+* its least destructive action, the first `<name>-close` in its footer, else any; a dialog focuses
+* the first tabbable element in its `<name>-body`; otherwise the engine focuses the popup itself, so
+* a long text starts at its top.
+*/
+function initialFocus(name, role) {
+	const close = `[data-slot="${name}-close"]:not(:disabled)`;
+	return (content) => role === "alertdialog" ? content.querySelector(`[data-slot="${name}-footer"] ${close}`) ?? content.querySelector(close) : firstTabbable(content.querySelector(`[data-slot="${name}-body"]`));
+}
+//#endregion
+export { ModalNestingScope, firstTabbable, initialFocus, useModalNesting };

package/dist/_internal/nested-focus.js

@@ -0,0 +1,33 @@
+//#region src/_internal/nested-focus.ts
+/**
+* True while an input's keydown is being handled. An arrow key moves focus to the next radio as the
+* keydown's default action, in the same task, so a focus seen while this is set came from a key.
+*/
+let keyDown = false;
+function markKeyDown() {
+	keyDown = true;
+	setTimeout(() => {
+		keyDown = false;
+	}, 0);
+}
+/**
+* WebKit does not match :focus-visible on a radio reached with an arrow key, so the label marks a
+* keyboard focus itself (nz.base draws the outline for `[data-focus-visible]`). Written on the DOM,
+* not through state: re-rendering a focused radio makes React re-write its `name`, and Chromium then
+* stops treating an unchecked group as one Tab stop.
+*/
+function markFocus(event) {
+	const visible = event.currentTarget.matches(":focus-visible") || keyDown;
+	event.currentTarget.parentElement?.toggleAttribute("data-focus-visible", visible);
+}
+function clearFocus(event) {
+	event.currentTarget.parentElement?.removeAttribute("data-focus-visible");
+}
+/** Drops `undefined` values, so a spread never writes an empty attribute or handler. */
+function definedProps(props) {
+	const out = {};
+	for (const [key, value] of Object.entries(props)) if (value !== void 0) out[key] = value;
+	return out;
+}
+//#endregion
+export { clearFocus, definedProps, markFocus, markKeyDown };

package/dist/_internal/overlay.d.ts

@@ -0,0 +1,9 @@
+import { CSSProperties, ReactElement, ReactNode, RefObject } from "react";
+//#region src/_internal/overlay.d.ts
+/**
+ * Where focus goes when an overlay closes (§12.2 Focus return): `true` follows the chain (the
+ * trigger, else the parent overlay's trigger), an element ref or a function returning an element
+ * goes there first while it is on the page, and `false` leaves focus alone.
+ */
+export type ReturnFocusTarget = boolean | RefObject<HTMLElement | null> | (() => HTMLElement | null | undefined);
+//#endregion

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/alert/alert-dismiss.client.d.ts

@@ -0,0 +1,32 @@
+import { RenderProp } from "../contracts/render.js";
+import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+//#region src/alert/alert-dismiss.client.d.ts
+/** Strings this part renders (§16.4). */
+export interface AlertDismissLabels {
+  /** The button's accessible name. @default 'Dismiss' */
+  dismiss: string;
+}
+export interface AlertDismissProps extends Omit<ComponentPropsWithRef<"button">, "children"> {
+  /**
+   * Called with no arguments, so a Server Component can pass a Server Action. The Alert does not hide
+   * itself: the caller stops rendering it.
+   */
+  onDismiss?: () => void;
+  labels?: Partial<AlertDismissLabels>;
+  /** The close glyph, decorative. Defaults to the internal `close` glyph (Lucide's `x`). */
+  children?: ReactNode;
+  /**
+   * Your element in place of the default IconButton; it must render a `<button>`. A plain element
+   * keeps its own look. An IconButton, for example
+   * `render={<IconButton icon={<X />} label="Dismiss" variant="tertiary" size="sm" />}` to add its
+   * tooltip, keeps its variant and size, and in an Alert takes the dismiss slot's placement (made for
+   * `sm`) and icon/secondary glyph colour, as a composed IconButton does in `Dialog.Close`.
+   */
+  render?: RenderProp<Record<string, never>>;
+}
+/**
+ * With no `render`, an IconButton (tertiary, `sm`: the 16 px glyph Figma draws, in a 32 px target)
+ * with no tooltip, as `Dialog.Close` does.
+ */
+export declare function AlertDismiss({ onDismiss, labels: labelsProp, "aria-label": ariaLabel, type, render, className, onClick, children, ...rest }: AlertDismissProps): ReactElement;
+//#endregion

package/dist/alert/alert-dismiss.client.js

@@ -0,0 +1,38 @@
+"use client";
+import { cx } from "../_internal/cx.js";
+import { renderElement } from "../contracts/render.js";
+import { useLabels } from "../config/config.client.js";
+import { CloseGlyph } from "../_internal/glyphs.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/alert/alert-dismiss.client.tsx
+/**
+* With no `render`, an IconButton (tertiary, `sm`: the 16 px glyph Figma draws, in a 32 px target)
+* with no tooltip, as `Dialog.Close` does.
+*/
+function AlertDismiss({ onDismiss, labels: labelsProp, "aria-label": ariaLabel, type, render, className, onClick, children, ...rest }) {
+	const labels = useLabels("alertDismiss", labelsProp);
+	const own = render === void 0;
+	return renderElement("button", render, {}, {
+		"data-slot": "alert-dismiss",
+		...own && {
+			"data-variant": "tertiary",
+			"data-size": "sm"
+		},
+		...rest,
+		type: own ? type ?? "button" : void 0,
+		"aria-label": ariaLabel ?? labels?.dismiss ?? "Dismiss",
+		className: cx("nz-alert-dismiss", own && "nz-icon-button", "nz-hit-target", className),
+		onClick: (event) => {
+			onClick?.(event);
+			if (!event.defaultPrevented) onDismiss?.();
+		},
+		children: /* @__PURE__ */ jsx("span", {
+			className: "nz-icon-button-icon",
+			"data-slot": "icon-button-icon",
+			"aria-hidden": "true",
+			children: children ?? /* @__PURE__ */ jsx(CloseGlyph, {})
+		})
+	});
+}
+//#endregion
+export { AlertDismiss };

package/dist/alert/alert.d.ts

@@ -0,0 +1,28 @@
+import { RenderProp } from "../contracts/render.js";
+import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+//#region src/alert/alert.d.ts
+/** Figma "Tone". */
+export type AlertTone = "info" | "success" | "warning" | "critical";
+export interface AlertState {
+  tone: AlertTone;
+}
+export interface AlertProps extends Omit<ComponentPropsWithRef<"div">, "title"> {
+  /** @default 'info' */
+  tone?: AlertTone;
+  /** One line, Label/M Strong. The description is `children`. */
+  title?: ReactNode;
+  /** Decorative tone glyph, for example `<CircleX />` for `critical`; the text carries the meaning. */
+  icon?: ReactNode;
+  /** Controls under the text, for example `<Button size="sm">Retry</Button>`. */
+  action?: ReactNode;
+  /** `<AlertDismiss onDismiss={…}>…</AlertDismiss>`; leave it out for an alert that cannot be dismissed. */
+  dismiss?: ReactNode;
+  /**
+   * There is no live role by default: an alert present on page load must not interrupt. Pass
+   * `role="status"` or `role="alert"` for one injected after a user action.
+   */
+  role?: ComponentPropsWithRef<"div">["role"];
+  render?: RenderProp<AlertState>;
+}
+export declare function Alert({ tone, title, icon, action, dismiss, render, className, children, ...rest }: AlertProps): ReactElement;
+//#endregion

package/dist/alert/alert.js

@@ -0,0 +1,44 @@
+import { cx } from "../_internal/cx.js";
+import { renderElement } from "../contracts/render.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/alert/alert.tsx
+function Alert({ tone = "info", title, icon, action, dismiss, render, className, children, ...rest }) {
+	return renderElement("div", render, { tone }, {
+		"data-slot": "alert",
+		"data-tone": tone,
+		...rest,
+		className: cx("nz-alert", className),
+		children: /* @__PURE__ */ jsxs(Fragment, { children: [
+			icon != null && /* @__PURE__ */ jsx("span", {
+				className: "nz-alert-icon",
+				"data-slot": "alert-icon",
+				"aria-hidden": "true",
+				children: icon
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "nz-alert-content",
+				"data-slot": "alert-content",
+				children: [
+					title != null && /* @__PURE__ */ jsx("div", {
+						className: "nz-alert-title",
+						"data-slot": "alert-title",
+						children: title
+					}),
+					children != null && children !== false && children !== "" && /* @__PURE__ */ jsx("div", {
+						className: "nz-alert-description",
+						"data-slot": "alert-description",
+						children
+					}),
+					action != null && /* @__PURE__ */ jsx("div", {
+						className: "nz-alert-action",
+						"data-slot": "alert-action",
+						children: action
+					})
+				]
+			}),
+			dismiss
+		] })
+	});
+}
+//#endregion
+export { Alert };

package/dist/alert/index.d.ts

@@ -0,0 +1,3 @@
+import { Alert, AlertProps, AlertState, AlertTone } from "./alert.js";
+import { AlertDismiss, AlertDismissLabels, AlertDismissProps } from "./alert-dismiss.client.js";
+export { Alert, AlertDismiss, type AlertDismissLabels, type AlertDismissProps, type AlertProps, type AlertState, type AlertTone };

package/dist/alert/index.js

@@ -0,0 +1,3 @@
+import { Alert } from "./alert.js";
+import { AlertDismiss } from "./alert-dismiss.client.js";
+export { Alert, AlertDismiss };

package/dist/app-shell/app-shell.d.ts

@@ -0,0 +1,24 @@
+import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+//#region src/app-shell/app-shell.d.ts
+/** Strings this part renders (§16.4). */
+export interface AppShellLabels {
+  /** The skip link, the first Tab stop. @default 'Skip to content' */
+  skip: string;
+}
+export interface AppShellProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  /** A `Sidebar`, shown from 640 px. */
+  sidebar?: ReactNode;
+  /** A `TopBar`, shown from 640 px. */
+  topBar?: ReactNode;
+  /** A `MobileTopBar`, shown below 640 px. */
+  mobileTopBar?: ReactNode;
+  /** A `MobileTabBar`, pinned to the bottom below 640 px. */
+  tabBar?: ReactNode;
+  /** The `<main>` element's id, the skip link's target. Generated when absent. */
+  mainId?: string;
+  labels?: Partial<AppShellLabels>;
+  /** The page, inside `<main>`. */
+  children: ReactNode;
+}
+export declare function AppShell({ sidebar, topBar, mobileTopBar, tabBar, mainId, labels, className, children, ...rest }: AppShellProps): ReactElement;
+//#endregion

package/dist/app-shell/app-shell.js

@@ -0,0 +1,56 @@
+import { cx } from "../_internal/cx.js";
+import { useId } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/app-shell/app-shell.tsx
+function AppShell({ sidebar, topBar, mobileTopBar, tabBar, mainId, labels, className, children, ...rest }) {
+	const generated = useId();
+	const main = mainId ?? `nz-main${generated.replaceAll(/[^\w-]/g, "")}`;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "app-shell",
+		...rest,
+		className: cx("nz-app-shell", className),
+		children: [
+			/* @__PURE__ */ jsx("a", {
+				className: "nz-app-shell-skip",
+				"data-slot": "app-shell-skip",
+				href: `#${main}`,
+				children: labels?.skip ?? "Skip to content"
+			}),
+			sidebar != null && /* @__PURE__ */ jsx("div", {
+				className: "nz-app-shell-sidebar",
+				"data-slot": "app-shell-sidebar",
+				children: sidebar
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "nz-app-shell-frame",
+				"data-slot": "app-shell-frame",
+				children: [
+					topBar != null && /* @__PURE__ */ jsx("div", {
+						className: "nz-app-shell-top-bar",
+						"data-slot": "app-shell-top-bar",
+						children: topBar
+					}),
+					mobileTopBar != null && /* @__PURE__ */ jsx("div", {
+						className: "nz-app-shell-mobile-top-bar",
+						"data-slot": "app-shell-mobile-top-bar",
+						children: mobileTopBar
+					}),
+					/* @__PURE__ */ jsx("main", {
+						id: main,
+						tabIndex: -1,
+						className: "nz-app-shell-main",
+						"data-slot": "app-shell-main",
+						children
+					})
+				]
+			}),
+			tabBar != null && /* @__PURE__ */ jsx("div", {
+				className: "nz-app-shell-tab-bar",
+				"data-slot": "app-shell-tab-bar",
+				children: tabBar
+			})
+		]
+	});
+}
+//#endregion
+export { AppShell };

package/dist/app-shell/index.d.ts

@@ -0,0 +1,2 @@
+import { AppShell, AppShellLabels, AppShellProps } from "./app-shell.js";
+export { AppShell, type AppShellLabels, type AppShellProps };

package/dist/app-shell/index.js

@@ -0,0 +1 @@
+export { AppShell } from "./app-shell.js";

package/dist/augment.d.ts

@@ -0,0 +1,13 @@
+//#region src/augment.d.ts
+/** Button variants, as lowercase Figma names. Augment this interface to add one. */
+export interface ButtonVariantMap {
+  primary: true;
+  secondary: true;
+  tertiary: true;
+  critical: true;
+  accent: true;
+}
+export type ButtonVariant = keyof ButtonVariantMap;
+/** Control heights 32 / 40 / 48 px. */
+export type ControlSize = "sm" | "md" | "lg";
+//#endregion

package/dist/avatar/avatar.d.ts

@@ -0,0 +1,96 @@
+import { RenderProp } from "../contracts/render.js";
+import { PluralLabel } from "../i18n/format-label.js";
+import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+//#region src/avatar/avatar.d.ts
+/** Figma "Size": Sm 24, Md 32, Lg 40, XL 56 px. */
+export type AvatarSize = "sm" | "md" | "lg" | "xl";
+export interface AvatarState {
+  size: AvatarSize;
+  /** An image source or `image` element was given. */
+  image: boolean;
+  decorative: boolean;
+}
+export interface AvatarProps extends Omit<ComponentPropsWithRef<"span">, "children"> {
+  /**
+   * The person's or store's name. It is the avatar's accessible name (unless `decorative`) and the
+   * source of the initials.
+   */
+  name: string;
+  /**
+   * The photo. Without it (or `image`), the initials show. Pass it only when the image is known to
+   * load: if it fails, Chromium and Firefox show the initials, but WebKit (Safari) draws its
+   * broken-image mark over them, and no script-free markup avoids that. For a URL that may be gone,
+   * check it on the server and leave `src` out (the initials render), or render the initials alone.
+   */
+  src?: string;
+  /** Passed to the `<img>` with `src`. */
+  srcSet?: string;
+  sizes?: string;
+  /**
+   * A framework image element in place of `src`, for example `image={<NextImage src={photo} alt="" />}`.
+   * It is cloned with the image slot's class and `alt=""`, and laid over the initials like `src`.
+   */
+  image?: ReactElement<{
+    className?: string | undefined;
+  }>;
+  /**
+   * Replaces the initials derived from `name` (the first letters of the first and last words).
+   * Figma: at most two letters.
+   */
+  initials?: string;
+  /** @default 'md' */
+  size?: AvatarSize;
+  /**
+   * The name is printed next to the avatar, so the avatar is hidden from assistive technology
+   * (Figma: `alt=""` when the name is printed next to it). @default false
+   */
+  decorative?: boolean;
+  /** Composition of the root `<span>`. */
+  render?: RenderProp<AvatarState>;
+}
+/**
+ * A person's or store's photo laid over their initials, with no script: the initials are always
+ * rendered, so a missing photo needs no `onError`. Known limit: a `src` that fails to load shows
+ * WebKit's (Safari's) broken-image mark over the initials, with no script-free fix; pass `src` only
+ * when it is known to load, or leave it out and the initials show.
+ */
+export declare function Avatar({ name, src, srcSet, sizes, image, initials, size, decorative, render, className, ...rest }: AvatarProps): ReactElement;
+/**
+ * AvatarGroup's own strings (§16.4): serialisable, English defaults. `{count}` is replaced by the
+ * formatted count, and a `PluralLabel` (`{ one, few, many, other }`, the locale's CLDR categories)
+ * picks its template by that count through `formatLabel`.
+ */
+export interface AvatarGroupLabels {
+  /** The visible count after the shown avatars. @default '+{count}' */
+  overflow: string | PluralLabel;
+  /** The count's words in the group's accessible name ("Maya, Jonah, Priya and 4 more"). @default '{count} more' */
+  more: string | PluralLabel;
+}
+export interface AvatarGroupState {
+  size: AvatarSize;
+  /** People not shown as an avatar. */
+  hidden: number;
+}
+export interface AvatarGroupProps extends ComponentPropsWithRef<"span"> {
+  /** How many avatars to show before the count. Figma: up to 3. @default 3 */
+  max?: number;
+  /**
+   * Everyone in the group, when it is more than the avatars passed (the server sends three faces and
+   * a count). @default the number of avatars
+   */
+  total?: number;
+  /** Applied to every avatar and the count. @default 'md' */
+  size?: AvatarSize;
+  /** BCP 47 tag for the count and the list of names. @default 'en-US' */
+  locale?: string;
+  labels?: Partial<AvatarGroupLabels>;
+  render?: RenderProp<AvatarGroupState>;
+  /** `Avatar` elements. */
+  children?: ReactNode;
+}
+/**
+ * A stack of avatars and a count, announced as one item (Figma: "Maya, Jonah, Priya and 4 more"):
+ * the root is `role="img"` named by the list of names, and every avatar inside is decorative.
+ */
+export declare function AvatarGroup({ max, total, size, locale, labels, render, className, children, ...rest }: AvatarGroupProps): ReactElement;
+//#endregion