@dungle-scrubs/admin-ui-soft 0.0.0-stage → 0.1.0

package/dist/lib/triage-keys.js

@@ -0,0 +1,229 @@
+import { Kbd, KbdGroup } from "../components/ui/kbd.js";
+import * as React from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "cn";
+import { useLatest } from "ahooks";
+//#region src/lib/triage-keys.tsx
+/** Marks an element as a triage target; its value is the target's key. */
+const TRIAGE_TARGET_ATTRIBUTE = "data-queue-target";
+/** Whether keys pressed in `target` belong to a text field rather than the triage list. */
+function isEditableTarget(target) {
+	if (target instanceof HTMLElement && target.isContentEditable) return true;
+	return target.closest("input, textarea, select, [contenteditable]:not([contenteditable='false'])") !== null;
+}
+/**
+* Widgets that own their arrow and letter keys. A step key pressed with
+* focus inside one of them belongs to the widget, not the page, so the
+* page-level entry into a triage list leaves it alone.
+*/
+const KEY_OWNING_WIDGETS = "[role=dialog], [role=alertdialog], [role=menu], [role=menubar], [role=listbox], [role=combobox], [role=tree], [role=grid], [role=tablist], [role=radiogroup], [role=slider], [role=spinbutton]";
+/** How a key reads in a hint or a key chip. */
+function triageKeyLabel(key) {
+	switch (key) {
+		case "ArrowDown": return "↓";
+		case "ArrowUp": return "↑";
+		case " ": return "Space";
+		default: return key;
+	}
+}
+/**
+* The keys that still navigate, paired by direction: a keymap that takes `j`
+* or `k` for an action leaves just the arrow for that direction.
+*/
+function triageNavigation(keymap) {
+	return [{
+		label: "next",
+		keys: [keymap?.j === void 0 ? "j" : null, "ArrowDown"]
+	}, {
+		label: "previous",
+		keys: [keymap?.k === void 0 ? "k" : null, "ArrowUp"]
+	}].map(({ label, keys }) => ({
+		label,
+		keys: keys.filter((key) => key !== null)
+	}));
+}
+/** The keys mapped to each action, in keymap order, for actions that exist. */
+function triageShortcuts(keymap, hasAction) {
+	const shortcuts = /* @__PURE__ */ new Map();
+	for (const [key, action] of Object.entries(keymap ?? {})) {
+		if (!hasAction(action)) continue;
+		shortcuts.set(action, [...shortcuts.get(action) ?? [], key]);
+	}
+	return shortcuts;
+}
+/** The key as a word, for the copy assistive tech reads. */
+const spokenKeyLabel = (key) => key === " " ? "Space" : key;
+/** The hint line as one sentence, for the copy assistive tech reads. */
+function spokenHints(keymap, hints) {
+	return `Keyboard: ${[...triageNavigation(keymap).map(({ label, keys }) => `${keys.map(spokenKeyLabel).join(" or ")} ${label}`), ...hints.map((hint) => `${spokenKeyLabel(hint.key)} ${hint.label}`)].join(", ")}.`;
+}
+/**
+* The key hints line: navigation keys paired by direction, then each hint in
+* order. The visual line is hidden where there is no keyboard (a touch
+* screen, a narrow list, an empty one), but the `id` it is known by - the
+* list's `aria-describedby` target - lands on a visually hidden copy that is
+* always rendered, so assistive tech always gets the description: an element
+* with `display: none` describes nothing.
+*/
+function TriageKeyHints({ keymap, hints, className, id, hidden, ...props }) {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("p", {
+		id,
+		className: "sr-only",
+		children: spokenHints(keymap, hints)
+	}), /* @__PURE__ */ jsxs("p", {
+		"aria-hidden": "true",
+		hidden,
+		className: cn("flex flex-wrap items-center gap-x-3 gap-y-1 text-muted-foreground pointer-coarse:hidden", className),
+		...props,
+		children: [triageNavigation(keymap).map(({ label, keys }) => /* @__PURE__ */ jsxs("span", {
+			className: "inline-flex items-center gap-1",
+			children: [/* @__PURE__ */ jsx(KbdGroup, { children: keys.map((key, index) => /* @__PURE__ */ jsxs(React.Fragment, { children: [index > 0 ? /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				children: "/"
+			}) : null, /* @__PURE__ */ jsx(Kbd, { children: triageKeyLabel(key) })] }, key)) }), label]
+		}, label)), hints.map((hint) => /* @__PURE__ */ jsxs("span", {
+			className: "inline-flex items-center gap-1",
+			children: [/* @__PURE__ */ jsx(Kbd, { children: triageKeyLabel(hint.key) }), hint.label]
+		}, hint.key))]
+	})] });
+}
+/**
+* The key chip inside an action button. Hidden on touch screens; `className`
+* hides it in other places too, such as a narrow list.
+*/
+function TriageKbd({ shortcut, className }) {
+	return /* @__PURE__ */ jsx(Kbd, {
+		"aria-hidden": "true",
+		className: cn("ml-0.5 h-4 min-w-4 border border-current/25 bg-transparent text-current pointer-coarse:hidden", className),
+		children: triageKeyLabel(shortcut)
+	});
+}
+/**
+* The shared triage key handling. Spread `handlers` on the list's container
+* (and attach `containerRef`), give each target `registerTarget(key)` as its
+* ref and `{ [TRIAGE_TARGET_ATTRIBUTE]: key }`, and render `announcement` in a
+* polite live region. Handled keys never reach window listeners, such as the
+* ThemeProvider's bare `d` dark-mode toggle. Keys are ignored while focus is
+* in a text field and while a modifier is held.
+*
+* A step key also enters the list from the page, through a window listener:
+* `j`/`k` (when the keymap leaves them free) or an arrow pressed with focus
+* anywhere outside the list moves the cursor to the target it is already on,
+* without stepping past it. Action keys never enter - a decision always
+* needs a focused target - and neither do arrows pressed on a focused
+* control (they keep their native behaviour), keys in a text field or in a
+* widget that owns them (a dialog, a menu), or any key while a modal is open
+* or the list is empty; there the key keeps its native behaviour too.
+*/
+function useTriageKeyboard(options) {
+	const { keymap, hasAction, activeKey, modalOpen = false, onAction, onStep, onOtherKey, onFocusTarget } = options;
+	const containerRef = React.useRef(null);
+	const targetElements = React.useRef(/* @__PURE__ */ new Map());
+	const lastFocused = React.useRef(null);
+	const [announcement, setAnnouncement] = React.useState("");
+	const [cursorVisible, setCursorVisible] = React.useState(false);
+	const latest = useLatest({
+		keymap,
+		activeKey,
+		modalOpen,
+		onStep
+	});
+	const registerTarget = React.useCallback((key) => (element) => {
+		if (element) targetElements.current.set(key, element);
+		else targetElements.current.delete(key);
+	}, []);
+	const targetElement = React.useCallback((key) => targetElements.current.get(key), []);
+	const targetKeyOf = React.useCallback((element) => element?.closest(`[data-queue-target]`)?.getAttribute("data-queue-target") ?? null, []);
+	/**
+	* Whether focus fell to the page because the element that had it inside
+	* the list left the DOM (its row was decided away), so the list should
+	* carry focus to the cursor's new target.
+	*/
+	const focusLost = React.useCallback(() => {
+		const focused = document.activeElement;
+		return (!focused || focused === document.body) && lastFocused.current !== null && !lastFocused.current.isConnected;
+	}, []);
+	const consume = (event) => {
+		event.preventDefault();
+		event.stopPropagation();
+	};
+	const onKeyDown = (event) => {
+		const element = event.target;
+		const modified = event.metaKey || event.ctrlKey || event.altKey;
+		if (!containerRef.current?.contains(element)) {
+			if (modalOpen && !modified && event.key !== "Escape" && event.key !== "Tab" && keymap?.[event.key] !== void 0) event.stopPropagation();
+			return;
+		}
+		if (event.defaultPrevented || modified || isEditableTarget(element)) return;
+		if (modalOpen) return;
+		const mapped = keymap?.[event.key];
+		if (mapped !== void 0 && hasAction(mapped)) {
+			consume(event);
+			setCursorVisible(true);
+			const key = targetKeyOf(element) ?? activeKey;
+			if (!event.repeat && key !== null) onAction(mapped, key);
+			return;
+		}
+		const step = event.key === "ArrowDown" || event.key === "j" ? 1 : event.key === "ArrowUp" || event.key === "k" ? -1 : 0;
+		if (step !== 0) {
+			consume(event);
+			setCursorVisible(true);
+			onStep(targetKeyOf(element) ?? activeKey, step);
+			return;
+		}
+		if (onOtherKey?.(event, element)) consume(event);
+	};
+	const onFocus = (event) => {
+		const container = containerRef.current;
+		if (!container?.contains(event.target)) return;
+		lastFocused.current = event.target;
+		setCursorVisible(event.target.matches(":focus-visible"));
+		const key = targetKeyOf(event.target);
+		if (key !== null) {
+			const previous = event.relatedTarget;
+			onFocusTarget(key, !(previous instanceof Node && container.contains(previous)));
+		}
+	};
+	const onBlur = (event) => {
+		const next = event.relatedTarget;
+		if (next && containerRef.current?.contains(next)) return;
+		setAnnouncement("");
+		setCursorVisible(false);
+		if (next) lastFocused.current = null;
+	};
+	React.useEffect(() => {
+		const onPageKeyDown = (event) => {
+			const { keymap, activeKey, modalOpen, onStep } = latest.current;
+			const container = containerRef.current;
+			const target = event.target;
+			if (!container?.isConnected || targetElements.current.size === 0 || modalOpen || event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.isComposing || event.keyCode === 229 || !(target instanceof Element) || container.contains(target) || isEditableTarget(target) || target.closest(KEY_OWNING_WIDGETS) !== null) return;
+			const arrows = event.key === "ArrowDown" || event.key === "ArrowUp";
+			const letters = (event.key === "j" || event.key === "k") && keymap?.[event.key] === void 0;
+			if (!arrows && !letters) return;
+			if (arrows && target !== document.body && target !== document.documentElement) return;
+			event.preventDefault();
+			event.stopPropagation();
+			setCursorVisible(true);
+			onStep(activeKey, 0);
+		};
+		window.addEventListener("keydown", onPageKeyDown);
+		return () => window.removeEventListener("keydown", onPageKeyDown);
+	}, [latest]);
+	return {
+		containerRef,
+		registerTarget,
+		targetElement,
+		targetKeyOf,
+		focusLost,
+		cursorVisible,
+		announcement,
+		announce: setAnnouncement,
+		handlers: {
+			onKeyDown,
+			onFocus,
+			onBlur
+		}
+	};
+}
+//#endregion
+export { TRIAGE_TARGET_ATTRIBUTE, TriageKbd, TriageKeyHints, isEditableTarget, triageKeyLabel, triageNavigation, triageShortcuts, useTriageKeyboard };

package/dist/lib/utils.js

@@ -0,0 +1,2 @@
+import { cn as cn$1 } from "cn";
+export { cn$1 as cn };

package/dist/motion/alert-toast/alert-toast.d.ts

@@ -0,0 +1,51 @@
+import * as React from "react";
+//#region src/motion/alert-toast/alert-toast.d.ts
+export type AlertToastTone = "default" | "success" | "info" | "warning" | "error";
+/** Why the toast asked to close. */
+export type AlertToastCloseReason = "timeout" | "swipe" | "escape" | "close" | "action";
+export type AlertToastSide = "top" | "bottom";
+export interface AlertToastAction {
+  label: string;
+  onClick: () => void;
+}
+export interface AlertToastProps {
+  /** Whether the alert shows (controlled). */
+  open: boolean;
+  /** The alert asked to close; set `open` to false here. */
+  onOpenChange: (open: boolean, reason: AlertToastCloseReason) => void;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  /** Sets the icon and the timeout bar's colour. */
+  tone?: AlertToastTone;
+  /** One action button. Pressing it runs `onClick`, then closes the alert. */
+  action?: AlertToastAction;
+  /**
+   * Milliseconds before the alert closes itself. The timeout bar shows what is
+   * left, and the countdown pauses while the alert is hovered or focused and
+   * while the document is hidden. `0` keeps the alert until it is dismissed.
+   * Default 6000.
+   */
+  duration?: number;
+  /** `high` announces the alert assertively. Default `low`. */
+  priority?: "low" | "high";
+  /**
+   * Screen edge. Default `top`, so alerts never cover the app's `Toaster`
+   * stack at the bottom. A top alert swipes away up or right, a bottom one
+   * down or right.
+   */
+  side?: AlertToastSide;
+  className?: string;
+}
+/**
+ * A single controlled alert for proactive, agent-raised news. It renders
+ * through admin-ui's toast primitives (`components/ui/toast`) in its own
+ * viewport, alongside the app's `Toaster`, never in place of it.
+ *
+ * Swipe or flick it away, press Escape while it has focus, or use its close
+ * button. A timeout bar burns down while it waits; the countdown pauses while
+ * the alert is hovered or focused and while the document is hidden.
+ *
+ * Behavior reference: reactbits swipe-toast.
+ */
+export declare function AlertToast({ open, onOpenChange, title, description, tone, action, duration, priority, side, className }: AlertToastProps): React.JSX.Element;
+//#endregion

package/dist/motion/alert-toast/alert-toast.js

@@ -0,0 +1,226 @@
+import { Button } from "../../components/ui/button.js";
+import { Toast, ToastAction, ToastContent, ToastDescription, ToastPortal, ToastProvider, ToastTitle, ToastViewport, createToastManager, useToastManager } from "../../components/ui/toast.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "cn";
+import { CircleCheckIcon, InfoIcon, OctagonXIcon, TriangleAlertIcon, XIcon } from "lucide-react";
+import { useDocumentVisibility, useLatest } from "ahooks";
+import { animate, motion, useMotionValue, useReducedMotionConfig } from "motion/react";
+//#region src/motion/alert-toast/alert-toast.tsx
+const toneIcon = {
+	default: null,
+	success: /* @__PURE__ */ jsx(CircleCheckIcon, { "aria-hidden": "true" }),
+	info: /* @__PURE__ */ jsx(InfoIcon, { "aria-hidden": "true" }),
+	warning: /* @__PURE__ */ jsx(TriangleAlertIcon, { "aria-hidden": "true" }),
+	error: /* @__PURE__ */ jsx(OctagonXIcon, {
+		"aria-hidden": "true",
+		className: "text-destructive"
+	})
+};
+const fuseTone = {
+	default: "bg-primary",
+	success: "bg-chart-2",
+	info: "bg-muted-foreground",
+	warning: "bg-chart-4 dark:bg-chart-3",
+	error: "bg-destructive"
+};
+const topToast = "top-0 bottom-auto origin-top data-starting-style:[transform:translateY(-150%)] [&[data-ending-style]:not([data-limited]):not([data-swipe-direction])]:[transform:translateY(-150%)] after:top-auto after:bottom-full";
+const topViewport = "top-4 bottom-auto";
+/**
+* A single controlled alert for proactive, agent-raised news. It renders
+* through admin-ui's toast primitives (`components/ui/toast`) in its own
+* viewport, alongside the app's `Toaster`, never in place of it.
+*
+* Swipe or flick it away, press Escape while it has focus, or use its close
+* button. A timeout bar burns down while it waits; the countdown pauses while
+* the alert is hovered or focused and while the document is hidden.
+*
+* Behavior reference: reactbits swipe-toast.
+*/
+function AlertToast({ open, onOpenChange, title, description, tone = "default", action, duration = 6e3, priority = "low", side = "top", className }) {
+	const [manager] = React.useState(() => createToastManager());
+	const idRef = React.useRef(null);
+	const reasonRef = React.useRef(null);
+	const onOpenChangeRef = useLatest(onOpenChange);
+	const tag = React.useCallback((reason) => {
+		reasonRef.current = reason;
+	}, []);
+	const close = React.useCallback((reason) => {
+		reasonRef.current = reason;
+		if (idRef.current) manager.close(idRef.current);
+	}, [manager]);
+	const data = {
+		tone,
+		action
+	};
+	const contentRef = useLatest({
+		title,
+		description,
+		priority,
+		data
+	});
+	React.useEffect(() => {
+		if (open && !idRef.current) {
+			reasonRef.current = null;
+			idRef.current = manager.add({
+				...contentRef.current,
+				timeout: 0,
+				onClose: () => {
+					if (idRef.current === null) return;
+					idRef.current = null;
+					const reason = reasonRef.current ?? "swipe";
+					reasonRef.current = null;
+					onOpenChangeRef.current(false, reason);
+				}
+			});
+		} else if (!open && idRef.current) {
+			const id = idRef.current;
+			idRef.current = null;
+			manager.close(id);
+		}
+	}, [
+		open,
+		manager,
+		contentRef,
+		onOpenChangeRef
+	]);
+	React.useEffect(() => {
+		if (idRef.current) manager.update(idRef.current, {
+			title,
+			description,
+			priority,
+			data
+		});
+	});
+	React.useEffect(() => () => {
+		if (idRef.current) manager.close(idRef.current);
+	}, [manager]);
+	return /* @__PURE__ */ jsx(ToastProvider, {
+		toastManager: manager,
+		timeout: 0,
+		children: /* @__PURE__ */ jsx(ToastPortal, { children: /* @__PURE__ */ jsx(ToastViewport, {
+			"data-slot": "alert-toast-viewport",
+			"aria-label": "Alerts",
+			className: cn(side === "top" && topViewport),
+			children: /* @__PURE__ */ jsx(AlertToastList, {
+				duration,
+				side,
+				className,
+				onClose: close,
+				onTag: tag
+			})
+		}) })
+	});
+}
+function AlertToastList({ duration, side, className, onClose, onTag }) {
+	const { toasts } = useToastManager();
+	return toasts.map((item) => /* @__PURE__ */ jsx(AlertToastItem, {
+		item,
+		duration,
+		side,
+		className,
+		onClose,
+		onTag
+	}, item.id));
+}
+function AlertToastItem({ item, duration, side, className, onClose, onTag }) {
+	const reduced = useReducedMotionConfig() ?? false;
+	const visibility = useDocumentVisibility();
+	const [hovered, setHovered] = React.useState(false);
+	const [focused, setFocused] = React.useState(false);
+	const [pressed, setPressed] = React.useState(false);
+	const progress = useMotionValue(1);
+	const controlsRef = React.useRef(null);
+	const onCloseRef = useLatest(onClose);
+	const onTagRef = useLatest(onTag);
+	const tone = item.data?.tone ?? "default";
+	const action = item.data?.action;
+	const closing = item.transitionStatus === "ending";
+	const timed = duration > 0 && Number.isFinite(duration);
+	const paused = hovered || focused || pressed || visibility === "hidden";
+	React.useEffect(() => {
+		if (!timed) return;
+		progress.set(1);
+		const controls = animate(progress, 0, {
+			duration: duration / 1e3,
+			ease: "linear",
+			onComplete: () => onCloseRef.current("timeout")
+		});
+		controlsRef.current = controls;
+		return () => {
+			controls.stop();
+			controlsRef.current = null;
+		};
+	}, [
+		timed,
+		duration,
+		progress,
+		onCloseRef
+	]);
+	React.useEffect(() => {
+		const controls = controlsRef.current;
+		if (!controls || closing) return;
+		if (paused) controls.pause();
+		else controls.play();
+	}, [paused, closing]);
+	return /* @__PURE__ */ jsx(Toast, {
+		toast: item,
+		swipeDirection: side === "top" ? ["up", "right"] : ["down", "right"],
+		"data-slot": "alert-toast",
+		"data-tone": tone,
+		"data-paused": timed && paused ? "" : void 0,
+		"data-reduced-motion": reduced ? "" : void 0,
+		onPointerEnter: () => setHovered(true),
+		onPointerLeave: () => setHovered(false),
+		onPointerDown: () => setPressed(true),
+		onPointerUp: () => setPressed(false),
+		onPointerCancel: () => setPressed(false),
+		onFocus: () => setFocused(true),
+		onBlur: (event) => {
+			const next = event.relatedTarget;
+			if (!(next instanceof Node && event.currentTarget.contains(next))) setFocused(false);
+		},
+		onKeyDownCapture: (event) => {
+			if (event.key === "Escape") onTagRef.current("escape");
+		},
+		className: cn(side === "top" && topToast, reduced && "[transition:opacity_150ms] data-starting-style:opacity-0", className),
+		children: /* @__PURE__ */ jsxs(ToastContent, {
+			className: "relative items-start rounded-[calc(var(--radius-md)-1px)]",
+			children: [
+				toneIcon[tone] ? /* @__PURE__ */ jsx("span", {
+					"data-slot": "alert-toast-icon",
+					className: "mt-0.5 shrink-0 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+					children: toneIcon[tone]
+				}) : null,
+				/* @__PURE__ */ jsxs("div", {
+					className: "flex min-w-0 flex-1 flex-col gap-1",
+					children: [/* @__PURE__ */ jsx(ToastTitle, {}), /* @__PURE__ */ jsx(ToastDescription, {})]
+				}),
+				action ? /* @__PURE__ */ jsx(ToastAction, {
+					onClick: () => {
+						action.onClick();
+						onCloseRef.current("action");
+					},
+					children: action.label
+				}) : null,
+				/* @__PURE__ */ jsx(Button, {
+					variant: "ghost",
+					size: "icon-sm",
+					"aria-label": "Dismiss",
+					"data-slot": "alert-toast-close",
+					onClick: () => onCloseRef.current("close"),
+					className: "relative shrink-0 text-muted-foreground after:absolute after:-inset-2 after:content-[''] hover:text-foreground",
+					children: /* @__PURE__ */ jsx(XIcon, { "aria-hidden": "true" })
+				}),
+				timed ? /* @__PURE__ */ jsx(motion.span, {
+					"aria-hidden": "true",
+					"data-slot": "alert-toast-fuse",
+					style: { scaleX: progress },
+					className: cn("pointer-events-none absolute inset-x-0 bottom-0 h-0.5 origin-left", fuseTone[tone])
+				}) : null
+			]
+		})
+	});
+}
+//#endregion
+export { AlertToast };

package/dist/motion/branch-menu/branch-menu.d.ts

@@ -0,0 +1,47 @@
+import * as React from "react";
+//#region src/motion/branch-menu/branch-menu.d.ts
+export interface BranchMenuItem {
+  id: string;
+  label: string;
+  /** A lucide icon. */
+  icon?: React.ReactNode;
+  /** A leaf with `href` renders a link; other leaves render buttons. */
+  href?: string;
+  /** Nested items make this item a section that expands and collapses. */
+  children?: readonly BranchMenuItem[];
+  disabled?: boolean;
+}
+export interface BranchMenuProps {
+  items: readonly BranchMenuItem[];
+  /** Accessible name of the navigation landmark. */
+  label: string;
+  /** Ids of the expanded sections (controlled). */
+  expanded?: readonly string[];
+  /** Ids of the sections that start expanded (uncontrolled). Defaults to the active item's ancestors. */
+  defaultExpanded?: readonly string[];
+  onExpandedChange?: (expanded: string[]) => void;
+  /** Id of the current leaf (controlled). */
+  active?: string | null;
+  /** Id of the leaf that starts current (uncontrolled). */
+  defaultActive?: string | null;
+  /** A leaf was chosen. It fires on every activation, even of the current leaf. */
+  onActiveChange?: (id: string, item: BranchMenuItem) => void;
+  className?: string;
+}
+/**
+ * Expandable navigation sections joined by drawn branch lines. The branch to
+ * the current item is drawn in the foreground colour, and a marker slides to
+ * the section that holds it.
+ *
+ * Pattern: a `nav` landmark with disclosure buttons (the APG "Disclosure
+ * Navigation Menu"), not a `tree`. Its items navigate rather than select, so
+ * they stay native links and buttons that every screen reader announces in
+ * browse mode, and Tab reaches each one. The arrow keys add tree-style
+ * movement on top: Up and Down move between visible items, Right expands a
+ * section or enters it, Left collapses it or returns to its parent, and Home
+ * and End jump to the ends. A collapsed section's items are `inert`.
+ *
+ * Behavior reference: reactbits branched-menu.
+ */
+export declare function BranchMenu(props: BranchMenuProps): React.JSX.Element;
+//#endregion