@nizivo/react 0.1.0 → 0.2.1

package/dist/toast/toast.contract.d.ts

@@ -0,0 +1,56 @@
+import "./seam.js";
+import { RefObject } from "react";
+//#region src/toast/toast.contract.d.ts
+/** Figma "Tone". Critical is announced assertively and stays until dismissed. */
+export type ToastTone = "neutral" | "success" | "critical";
+/** How a message is spoken: `polite` waits for the reader to finish, `assertive` interrupts. */
+export type Politeness = "polite" | "assertive";
+export interface ToastAction {
+  /** The button's text, one or two words: "Undo", "View". */
+  label: string;
+  /** Runs on press; the toast then closes. */
+  onAction: () => void;
+}
+export interface ToastOptions {
+  /** @default 'neutral' */
+  tone?: ToastTone;
+  /** A second line under the message. */
+  description?: string;
+  /**
+   * One action, a real button. A toast with an action stays until it is dismissed (WCAG 2.2.1,
+   * §12.6), whatever `timeout` says.
+   */
+  action?: ToastAction;
+  /**
+   * Milliseconds before a toast without an action, and not critical, leaves. The time stops while
+   * the pointer is over the stack, while focus is in it and while the page is hidden.
+   * @default 5000
+   */
+  timeout?: number;
+  /**
+   * Updates the toast with this id in place, if it is still shown, instead of adding one:
+   * `toast('Saving…', { id: 'save' })`, then `toast('Saved', { id: 'save', tone: 'success' })`.
+   */
+  id?: string;
+  /** Called once when the toast leaves, however it left. */
+  onClose?: () => void;
+}
+/** Strings the Toaster renders (§16.4). */
+export interface ToasterLabels {
+  /** The region's accessible name, which names its shortcut. @default 'Notifications (F8)' */
+  region: string;
+  /** Each toast's close button. @default 'Dismiss' */
+  dismiss: string;
+}
+export interface ToasterProps {
+  labels?: Partial<ToasterLabels>;
+  /** Toasts shown at once, newest last. Older ones wait, their time stopped, until one leaves. @default 3 */
+  limit?: number;
+  /**
+   * The key that moves focus into the stack and, pressed again there, back to where it was (the
+   * `KeyboardEvent.key` value). @default 'F8'
+   */
+  hotkey?: string;
+  className?: string;
+}
+//#endregion

package/dist/toast/toaster.client.d.ts

@@ -0,0 +1,10 @@
+import { ToasterProps } from "./toast.contract.js";
+import { ReactElement } from "react";
+//#region src/toast/toaster.client.d.ts
+/**
+ * Shows the toasts `toast()` adds, bottom-centre, newest last, and speaks each once. F8 moves focus
+ * to the stack; Tab moves within it; Escape dismisses the focused toast; F8 again, or Escape on the
+ * stack itself, returns focus to where it was. Render one, in the root layout.
+ */
+export declare function Toaster({ labels, limit, hotkey, className }: ToasterProps): ReactElement;
+//#endregion

package/dist/toast/toaster.client.js

@@ -0,0 +1,305 @@
+"use client";
+import { cx } from "../_internal/cx.js";
+import { useLabels } from "../config/config.client.js";
+import { CircleCheckGlyph, CircleXGlyph, CloseGlyph, InfoGlyph } from "../_internal/glyphs.js";
+import { Button } from "../button/button.js";
+import { markTopLayer } from "../_engines/react-aria/overlay.client.js";
+import { iconButtonElement } from "../icon-button/icon-button-static.js";
+import { useItem, useRegion } from "../_engines/react-aria/toast.client.js";
+import { attach, getServerSnapshot, getSnapshot, pause, resume, show, speakThrough, subscribe, toast } from "./store.js";
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
+//#region src/toast/toaster.client.tsx
+const LABELS = {
+	region: "Notifications (F8)",
+	dismiss: "Dismiss"
+};
+/** How long a spoken message stays in the announcer, as React Aria's announcer keeps it. */
+const SPOKEN_FOR = 7e3;
+const GLYPHS = {
+	neutral: InfoGlyph,
+	success: CircleCheckGlyph,
+	critical: CircleXGlyph
+};
+const popoverApi = (element) => "showPopover" in element;
+const noSubscription = () => () => {};
+/** On the page in the browser only: the queue, the portals and the announcer are client state. */
+function useHydrated() {
+	return useSyncExternalStore(noSubscription, () => true, () => false);
+}
+/** Focus back to where it was before F8, if that element is still on the page. */
+function returnFocus(returnTo) {
+	const to = returnTo.current;
+	returnTo.current = null;
+	if (to?.isConnected === true) to.focus();
+}
+/**
+* Two visually hidden live regions, polite and assertive, on the page from the Toaster's mount
+* before any message, and marked top layer so a modal's aria-hidden never silences them (O-06).
+*/
+function Announcer() {
+	const ref = useRef(null);
+	const [said, setSaid] = useState({
+		polite: "",
+		assertive: ""
+	});
+	useLayoutEffect(() => {
+		const element = ref.current;
+		return element === null ? void 0 : markTopLayer(element);
+	}, []);
+	useEffect(() => {
+		const timers = /* @__PURE__ */ new Set();
+		const later = (ms, run) => {
+			const timer = setTimeout(() => {
+				timers.delete(timer);
+				run();
+			}, ms);
+			timers.add(timer);
+		};
+		const unregister = speakThrough((text, politeness) => {
+			setSaid((current) => ({
+				...current,
+				[politeness]: ""
+			}));
+			later(100, () => setSaid((current) => ({
+				...current,
+				[politeness]: text
+			})));
+			later(SPOKEN_FOR, () => setSaid((current) => current[politeness] === text ? {
+				...current,
+				[politeness]: ""
+			} : current));
+		});
+		return () => {
+			unregister();
+			for (const timer of timers) clearTimeout(timer);
+		};
+	}, []);
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		className: "nz-toast-announcer nz-visually-hidden",
+		"data-slot": "toast-announcer",
+		"data-nz-top-layer": "",
+		children: [/* @__PURE__ */ jsx("div", {
+			"aria-live": "polite",
+			"aria-atomic": "true",
+			children: said.polite
+		}), /* @__PURE__ */ jsx("div", {
+			"aria-live": "assertive",
+			"aria-atomic": "true",
+			children: said.assertive
+		})]
+	});
+}
+function ToastItem({ toast, options, labels }) {
+	const ref = useRef(null);
+	const { toastProps, messageProps, descriptionProps } = useItem(toast, options, ref);
+	const { close } = options;
+	const { id } = toast;
+	useEffect(() => {
+		const element = ref.current;
+		if (element === null) return void 0;
+		const onKey = (event) => {
+			if (event.key !== "Escape" || event.isComposing) return;
+			event.preventDefault();
+			event.stopPropagation();
+			close(id);
+		};
+		element.addEventListener("keydown", onKey);
+		return () => element.removeEventListener("keydown", onKey);
+	}, [close, id]);
+	const Glyph = GLYPHS[toast.tone];
+	const closePart = {
+		"data-slot": "toast-close",
+		className: "nz-toast-close"
+	};
+	const { action } = toast;
+	return /* @__PURE__ */ jsxs("div", {
+		...toastProps,
+		ref,
+		className: "nz-toast",
+		"data-slot": "toast",
+		"data-tone": toast.tone,
+		"data-nz-scheme": "inverse",
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: "nz-toast-icon",
+				"data-slot": "toast-icon",
+				"aria-hidden": "true",
+				children: /* @__PURE__ */ jsx(Glyph, {})
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "nz-toast-content",
+				"data-slot": "toast-content",
+				children: [/* @__PURE__ */ jsx("div", {
+					...messageProps,
+					className: "nz-toast-message",
+					"data-slot": "toast-message",
+					children: toast.message
+				}), toast.description !== void 0 && /* @__PURE__ */ jsx("div", {
+					...descriptionProps,
+					className: "nz-toast-description",
+					"data-slot": "toast-description",
+					children: toast.description
+				})]
+			}),
+			action !== void 0 && /* @__PURE__ */ jsx(Button, {
+				variant: "tertiary",
+				size: "sm",
+				className: "nz-toast-action",
+				"data-slot": "toast-action",
+				onClick: () => {
+					action.onAction();
+					options.close(toast.id);
+				},
+				children: action.label
+			}),
+			iconButtonElement({
+				label: labels.dismiss,
+				icon: /* @__PURE__ */ jsx(CloseGlyph, {}),
+				variant: "tertiary",
+				size: "sm",
+				...closePart,
+				onClick: () => options.close(toast.id)
+			})
+		]
+	});
+}
+/** The region and its toasts, once the page has hydrated. */
+function Stack({ toasts, strings, hotkey, className }) {
+	const region = useRef(null);
+	const returnTo = useRef(null);
+	const count = toasts.length;
+	const showing = useRef(count);
+	useLayoutEffect(() => {
+		showing.current = count;
+	});
+	useEffect(() => {
+		const onKey = (event) => {
+			if (event.key !== hotkey || event.altKey || event.ctrlKey || event.metaKey) return;
+			const element = region.current;
+			if (element === null || showing.current === 0) return;
+			event.preventDefault();
+			const active = document.activeElement;
+			if (active !== null && element.contains(active)) returnFocus(returnTo);
+			else {
+				returnTo.current = active instanceof HTMLElement ? active : null;
+				element.focus();
+			}
+		};
+		document.addEventListener("keydown", onKey);
+		return () => document.removeEventListener("keydown", onKey);
+	}, [hotkey]);
+	useEffect(() => {
+		const element = region.current;
+		if (element === null) return void 0;
+		const onKey = (event) => {
+			if (event.key !== "Escape" || event.target !== element) return;
+			event.preventDefault();
+			event.stopPropagation();
+			returnFocus(returnTo);
+		};
+		element.addEventListener("keydown", onKey);
+		return () => element.removeEventListener("keydown", onKey);
+	}, []);
+	const latest = toasts.at(-1)?.id;
+	useLayoutEffect(() => {
+		const element = region.current;
+		if (element === null) return;
+		element.hidden = latest === void 0;
+		if (!popoverApi(element)) return;
+		const open = element.matches(":popover-open");
+		if (latest === void 0) {
+			if (open) element.hidePopover();
+			return;
+		}
+		if (open && !element.contains(document.activeElement)) element.hidePopover();
+		if (!element.matches(":popover-open")) element.showPopover();
+	}, [latest]);
+	useLayoutEffect(() => {
+		const element = region.current;
+		return () => {
+			if (element === null) return;
+			element.hidden = true;
+			if (popoverApi(element) && element.matches(":popover-open")) element.hidePopover();
+		};
+	}, []);
+	useLayoutEffect(() => {
+		const element = region.current;
+		const root = document.documentElement;
+		if (element === null || count === 0) {
+			root.style.removeProperty("--nz-toast-inset");
+			return;
+		}
+		const measure = () => {
+			const inset = Math.max(0, window.innerHeight - element.getBoundingClientRect().top);
+			root.style.setProperty("--nz-toast-inset", `${Math.ceil(inset)}px`);
+		};
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(element);
+		window.addEventListener("resize", measure);
+		return () => {
+			observer.disconnect();
+			window.removeEventListener("resize", measure);
+			root.style.removeProperty("--nz-toast-inset");
+		};
+	}, [count]);
+	const options = {
+		toasts,
+		label: strings.region,
+		close: toast.dismiss,
+		pause: () => pause("region"),
+		resume: () => resume("region")
+	};
+	const regionProps = useRegion(options, region);
+	return /* @__PURE__ */ jsx("section", {
+		...regionProps,
+		ref: region,
+		popover: "manual",
+		hidden: count === 0,
+		className: cx("nz-toast-region", className),
+		"data-slot": "toast-region",
+		"data-nz-top-layer": "",
+		children: toasts.map((toast) => /* @__PURE__ */ jsx(ToastItem, {
+			toast,
+			options,
+			labels: strings
+		}, toast.id))
+	});
+}
+/**
+* Shows the toasts `toast()` adds, bottom-centre, newest last, and speaks each once. F8 moves focus
+* to the stack; Tab moves within it; Escape dismisses the focused toast; F8 again, or Escape on the
+* stack itself, returns focus to where it was. Render one, in the root layout.
+*/
+function Toaster({ labels, limit = 3, hotkey = "F8", className }) {
+	const toasts = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot).slice(-limit);
+	const hydrated = useHydrated();
+	const ids = toasts.map((toast) => toast.id).join(" ");
+	const strings = {
+		...LABELS,
+		...useLabels("toaster", labels)
+	};
+	useEffect(attach, []);
+	useEffect(() => show(ids === "" ? [] : ids.split(" ")), [ids]);
+	useEffect(() => {
+		const update = () => document.hidden ? pause("hidden") : resume("hidden");
+		update();
+		document.addEventListener("visibilitychange", update);
+		return () => {
+			document.removeEventListener("visibilitychange", update);
+			resume("hidden");
+		};
+	}, []);
+	if (!hydrated) return /* @__PURE__ */ jsx(Fragment, {});
+	return /* @__PURE__ */ jsxs(Fragment, { children: [createPortal(/* @__PURE__ */ jsx(Stack, {
+		toasts,
+		strings,
+		hotkey,
+		className
+	}), document.body), createPortal(/* @__PURE__ */ jsx(Announcer, {}), document.body)] });
+}
+//#endregion
+export { Toaster };

package/dist/tooltip/tooltip.contract.d.ts

@@ -1,7 +1,7 @@
 import { RenderProp } from "../contracts/render.js";
 import { ChangeDetails, OpenReason } from "../contracts/details.js";
-import { Align, Side } from "../contracts/state.js";
 import "../_internal/engine-part.js";
+import { Align, Side } from "../contracts/state.js";
 import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
 //#region src/tooltip/tooltip.contract.d.ts
 /** Logical side; the resolved physical side is `data-side` on the popup. */

package/dist/top-bar/index.d.ts

@@ -0,0 +1,2 @@
+import { TopBar, TopBarProps } from "./top-bar.js";
+export { TopBar, type TopBarProps };

package/dist/top-bar/index.js

@@ -0,0 +1 @@
+export { TopBar } from "./top-bar.js";

package/dist/top-bar/top-bar.d.ts

@@ -0,0 +1,17 @@
+import { RenderProp } from "../contracts/render.js";
+import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+//#region src/top-bar/top-bar.d.ts
+export interface TopBarProps extends Omit<ComponentPropsWithRef<"header">, "title" | "children"> {
+  /** The page's name, in Heading/H3's look (Figma's Title). Not a heading element. */
+  title?: ReactNode;
+  /** In place of `title`, for example a Breadcrumb for a page deeper in the app. */
+  start?: ReactNode;
+  /** The search, usually a `SearchField` (M49: a real input). 360 px at most. */
+  search?: ReactNode;
+  /** At the end: the notifications IconButton, the account's Avatar or menu. */
+  actions?: ReactNode;
+  render?: RenderProp<Record<string, never>>;
+}
+/** The bar above the page on screens 640 px and wider (AppShell's `topBar`). */
+export declare function TopBar({ title, start, search, actions, render, className, ...rest }: TopBarProps): ReactElement;
+//#endregion

package/dist/top-bar/top-bar.js

@@ -0,0 +1,35 @@
+import { cx } from "../_internal/cx.js";
+import { renderElement } from "../contracts/render.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/top-bar/top-bar.tsx
+/** The bar above the page on screens 640 px and wider (AppShell's `topBar`). */
+function TopBar({ title, start, search, actions, render, className, ...rest }) {
+	return renderElement("header", render, {}, {
+		"data-slot": "top-bar",
+		...rest,
+		className: cx("nz-top-bar", className),
+		children: /* @__PURE__ */ jsxs(Fragment, { children: [
+			/* @__PURE__ */ jsx("div", {
+				className: "nz-top-bar-start",
+				"data-slot": "top-bar-start",
+				children: start ?? (title != null && /* @__PURE__ */ jsx("span", {
+					className: "nz-top-bar-title",
+					"data-slot": "top-bar-title",
+					children: title
+				}))
+			}),
+			search != null && /* @__PURE__ */ jsx("div", {
+				className: "nz-top-bar-search",
+				"data-slot": "top-bar-search",
+				children: search
+			}),
+			actions != null && /* @__PURE__ */ jsx("div", {
+				className: "nz-top-bar-actions",
+				"data-slot": "top-bar-actions",
+				children: actions
+			})
+		] })
+	});
+}
+//#endregion
+export { TopBar };

package/dist/trend-card/index.d.ts

@@ -0,0 +1,2 @@
+import { TrendCard, TrendCardProps, TrendCardState } from "./trend-card.js";
+export { TrendCard, type TrendCardProps, type TrendCardState };

package/dist/trend-card/index.js

@@ -0,0 +1 @@
+export { TrendCard } from "./trend-card.js";

package/dist/trend-card/trend-card.d.ts

@@ -0,0 +1,34 @@
+import { RenderProp } from "../contracts/render.js";
+import { CardTone } from "../card/card.js";
+import { DataStatus } from "../_internal/data-status.js";
+import { MetricDataProps } from "../metric/metric.js";
+import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+//#region src/trend-card/trend-card.d.ts
+export interface TrendCardState {
+  /** The status as rendered: `'empty'` when a ready card has no value. */
+  status: DataStatus;
+  pending: boolean;
+  tone: CardTone;
+}
+export interface TrendCardProps extends MetricDataProps, Omit<ComponentPropsWithRef<"div">, "children"> {
+  /** Card's tone; `inverse` scopes the inverse scheme. @default 'surface' */
+  tone?: CardTone;
+  /** The control at the end of the header, for example the period `Select` or a `SegmentedControl`. */
+  action?: ReactNode;
+  /**
+   * The chart, for example `<AreaChart … />` from `@nizivo/charts`. Rendered in every status, so the
+   * box stays put: give the chart the same `status` (ChartFrame keeps its box in all four).
+   */
+  chart?: ReactNode;
+  /** The legend under the chart, for example `<Legend items={…} />`. */
+  legend?: ReactNode;
+  /** A last row, for example a link to the report. */
+  footer?: ReactNode;
+  render?: RenderProp<TrendCardState>;
+}
+/**
+ * A headline number with its change, a period control and a comparison chart. A `role="group"`
+ * named by the label. The status contract (§16.5) applies to the headline; the slots render as given.
+ */
+export declare function TrendCard({ label, value, format, locale, delta, comparison, tone, action, chart, legend, footer, status, pending, empty, error, labels, render, className, ...rest }: TrendCardProps): ReactElement;
+//#endregion

package/dist/trend-card/trend-card.js

@@ -0,0 +1,74 @@
+import { cx } from "../_internal/cx.js";
+import { renderElement } from "../contracts/render.js";
+import { dataStatusAttrs } from "../_internal/data-status.js";
+import { Metric, resolveStatus } from "../metric/metric.js";
+import { useId } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/trend-card/trend-card.tsx
+/**
+* A headline number with its change, a period control and a comparison chart. A `role="group"`
+* named by the label. The status contract (§16.5) applies to the headline; the slots render as given.
+*/
+function TrendCard({ label, value, format, locale, delta, comparison, tone = "surface", action, chart, legend, footer, status = "ready", pending = false, empty, error, labels, render, className, ...rest }) {
+	const labelId = useId();
+	const st = resolveStatus(status, value);
+	const busy = st === "ready" && pending;
+	return renderElement("div", render, {
+		status: st,
+		pending: busy,
+		tone
+	}, {
+		"data-slot": "trend-card",
+		"data-tone": tone,
+		"data-padding": "md",
+		"data-nz-scheme": tone === "inverse" ? "inverse" : void 0,
+		...dataStatusAttrs(st, busy),
+		role: "group",
+		"aria-labelledby": labelId,
+		...rest,
+		className: cx("nz-card", "nz-trend-card", className),
+		children: /* @__PURE__ */ jsxs(Fragment, { children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "nz-trend-card-header",
+				"data-slot": "trend-card-header",
+				children: [/* @__PURE__ */ jsx(Metric, {
+					size: "display",
+					reserveChange: true,
+					labelId,
+					label,
+					value,
+					format,
+					locale,
+					delta,
+					comparison,
+					status,
+					pending,
+					empty,
+					error,
+					labels
+				}), action != null && /* @__PURE__ */ jsx("div", {
+					className: "nz-trend-card-action",
+					"data-slot": "trend-card-action",
+					children: action
+				})]
+			}),
+			chart != null && /* @__PURE__ */ jsx("div", {
+				className: "nz-trend-card-chart",
+				"data-slot": "trend-card-chart",
+				children: chart
+			}),
+			legend != null && /* @__PURE__ */ jsx("div", {
+				className: "nz-trend-card-legend",
+				"data-slot": "trend-card-legend",
+				children: legend
+			}),
+			footer != null && /* @__PURE__ */ jsx("div", {
+				className: "nz-trend-card-footer",
+				"data-slot": "trend-card-footer",
+				children: footer
+			})
+		] })
+	});
+}
+//#endregion
+export { TrendCard };