@c9up/nebula 0.1.0

package/src/organisms/Toaster.ts

@@ -0,0 +1,246 @@
+/**
+ * Toaster — transient notifications.
+ *
+ * shadcn delegates this to `sonner`. nebula keeps it in-house, and the shape
+ * is the same: one region mounted once near the app root, and a `toast()`
+ * function callable from anywhere with no reference to it.
+ *
+ * That decoupling is the whole design. A queue in module state, a signal the
+ * region subscribes to, and `toast.error(…)` works from a route handler's
+ * error branch without threading a handle down to it.
+ *
+ * The accessibility rules are stricter than they look, and the region is
+ * static so they can be satisfied:
+ *
+ * - The live region must exist **before** the toast does. A live region
+ *   inserted with content already in it is not announced by most screen
+ *   readers, which is why the region mounts empty and stays.
+ * - `polite` for ordinary toasts, `assertive` for errors. Everything
+ *   interrupting the user is the fastest way to make a screen reader
+ *   unusable — so there are two regions, and each toast picks one.
+ * - Hovering pauses the timers. A toast that vanishes while being read is the
+ *   single most common complaint about the pattern.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { XIcon } from "../lib/icons.js";
+import { fadeInOut } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+
+export type ToastVariant = "default" | "success" | "error" | "warning";
+
+export interface ToastOptions {
+	title: Child;
+	description?: Child;
+	variant?: ToastVariant;
+	/** Milliseconds on screen. `0` keeps it until dismissed. */
+	duration?: number;
+	action?: { label: string; onClick: () => void };
+}
+
+interface ActiveToast extends ToastOptions {
+	readonly id: number;
+	readonly variant: ToastVariant;
+}
+
+const DEFAULT_DURATION_MS = 5000;
+
+const queue = signal<readonly ActiveToast[]>([]);
+const timers = new Map<number, ReturnType<typeof setTimeout>>();
+/** When each toast is due to disappear, as an epoch timestamp. */
+const deadlines = new Map<number, number>();
+/** Time each toast had left when the pointer entered the region. */
+const remainders = new Map<number, number>();
+let nextId = 0;
+
+function dismiss(id: number): void {
+	clearTimer(id);
+	deadlines.delete(id);
+	remainders.delete(id);
+	queue(queue().filter((entry) => entry.id !== id));
+}
+
+function clearTimer(id: number): void {
+	const timer = timers.get(id);
+	if (timer !== undefined) clearTimeout(timer);
+	timers.delete(id);
+}
+
+function schedule(id: number, duration: number): void {
+	// A duration of zero means "stays until dismissed", so no timer and no
+	// deadline — which is also what keeps pause/resume from resurrecting one.
+	if (duration <= 0) return;
+	clearTimer(id);
+	timers.set(
+		id,
+		setTimeout(() => dismiss(id), duration),
+	);
+	deadlines.set(id, Date.now() + duration);
+}
+
+/** Hold every countdown while the pointer is over the region. */
+function pauseAll(): void {
+	const now = Date.now();
+	for (const [id, deadline] of deadlines) {
+		clearTimer(id);
+		remainders.set(id, Math.max(deadline - now, 0));
+	}
+}
+
+/**
+ * Resume every held countdown.
+ *
+ * A minimum is applied: a toast the pointer rested on until its time ran out
+ * would otherwise vanish the instant the pointer left, which reads as the
+ * hover having dismissed it.
+ */
+function resumeAll(minimumMs: number): void {
+	for (const [id, remaining] of remainders) {
+		schedule(id, Math.max(remaining, minimumMs));
+	}
+	remainders.clear();
+}
+
+function show(options: ToastOptions): number {
+	nextId += 1;
+	const id = nextId;
+	const entry: ActiveToast = {
+		...options,
+		id,
+		variant: options.variant ?? "default",
+	};
+	queue([...queue(), entry]);
+	schedule(id, options.duration ?? DEFAULT_DURATION_MS);
+	return id;
+}
+
+/**
+ * Raise a toast. Returns its id, which `dismiss` accepts.
+ *
+ * Callable from anywhere — no component, no context, no handle.
+ */
+export const toast = {
+	show,
+	dismiss,
+	success: (title: Child, description?: Child): number =>
+		show({ title, description, variant: "success" }),
+	error: (title: Child, description?: Child): number =>
+		// Errors stay twice as long: the user has to read them, and often act.
+		show({
+			title,
+			description,
+			variant: "error",
+			duration: DEFAULT_DURATION_MS * 2,
+		}),
+	warning: (title: Child, description?: Child): number =>
+		show({ title, description, variant: "warning" }),
+	/** Clear everything — on navigation, say. */
+	clear(): void {
+		for (const timer of timers.values()) clearTimeout(timer);
+		timers.clear();
+		deadlines.clear();
+		remainders.clear();
+		queue([]);
+	},
+};
+
+const variantClasses: Record<ToastVariant, string> = {
+	default: "bg-popover text-popover-foreground border",
+	success:
+		"bg-popover text-popover-foreground border-l-4 border-l-primary border",
+	error: "bg-popover text-destructive border-l-4 border-l-destructive border",
+	warning:
+		"bg-popover text-popover-foreground border-l-4 border-l-chart-4 border",
+};
+
+export interface ToasterProps {
+	/** Which corner. Default `"bottom-right"`. */
+	position?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+	class?: Reactive<string>;
+}
+
+const positionClasses: Record<NonNullable<ToasterProps["position"]>, string> = {
+	"top-right": "top-0 right-0 flex-col",
+	"top-left": "top-0 left-0 flex-col",
+	"bottom-right": "bottom-0 right-0 flex-col-reverse",
+	"bottom-left": "bottom-0 left-0 flex-col-reverse",
+};
+
+/**
+ * Mount once, near the root of the app.
+ *
+ * `data-nebula-live` marks it as exempt from the `aria-hidden` sweep a modal
+ * performs over its siblings — a toast raised while a dialog is open still has
+ * to be announced.
+ */
+export const Toaster = component<ToasterProps>((props) => {
+	const position = props.position ?? "bottom-right";
+
+	return html`<div
+		data-slot="toaster"
+		data-nebula-live
+		class="${() =>
+			cn(
+				"pointer-events-none fixed z-100 flex max-h-screen w-full p-4 sm:max-w-sm",
+				positionClasses[position],
+				read(props.class),
+			)}"
+		@pointerenter="${pauseAll}"
+		@pointerleave="${() => resumeAll(1000)}"
+	>
+		<div role="status" aria-live="polite" aria-atomic="false" class="contents">
+			${() =>
+				queue()
+					.filter((entry) => entry.variant !== "error")
+					.map(renderToast)}
+		</div>
+		<div role="alert" aria-live="assertive" aria-atomic="false" class="contents">
+			${() =>
+				queue()
+					.filter((entry) => entry.variant === "error")
+					.map(renderToast)}
+		</div>
+	</div>`;
+});
+
+function renderToast(entry: ActiveToast): Child {
+	return html`<div
+		data-slot="toast"
+		data-variant="${entry.variant}"
+		data-state="open"
+		class="${cn(
+			"pointer-events-auto mt-2 flex w-full items-start gap-3 rounded-md p-4 shadow-lg",
+			variantClasses[entry.variant],
+			fadeInOut,
+		)}"
+	>
+		<div class="flex-1 text-sm">
+			<div class="font-medium">${entry.title}</div>
+			${
+				entry.description === undefined
+					? null
+					: html`<div class="text-muted-foreground mt-1">${entry.description}</div>`
+			}
+		</div>
+		${
+			entry.action === undefined
+				? null
+				: html`<button
+					type="button"
+					class="text-sm font-medium underline-offset-4 hover:underline"
+					@click="${() => {
+						entry.action?.onClick();
+						dismiss(entry.id);
+					}}"
+				>${entry.action.label}</button>`
+		}
+		<button
+			type="button"
+			aria-label="Dismiss notification"
+			class="opacity-60 transition-opacity hover:opacity-100"
+			@click="${() => dismiss(entry.id)}"
+		>${XIcon({ class: "size-4" })}</button>
+	</div>`;
+}

package/src/organisms/Tooltip.ts

@@ -0,0 +1,124 @@
+/**
+ * Tooltip — a label that appears on hover or focus.
+ *
+ * Three rules separate a usable tooltip from an irritating one, and all three
+ * are about time rather than appearance:
+ *
+ * - An **open delay**, so moving the pointer across a toolbar does not fire
+ *   six tooltips on the way past.
+ * - A **close delay**, so travelling from the trigger to the tooltip — which a
+ *   user does to read a long one, or click a link inside — does not dismiss it
+ *   halfway.
+ * - **No delay between neighbours.** Once one tooltip is showing, the next one
+ *   appears instantly; the user has clearly decided to browse the toolbar, and
+ *   re-serving the delay each time makes the interface feel stuck. That is why
+ *   `lastClosedAt` is module state and not per-component.
+ *
+ * Focus opens it with no delay at all. A keyboard user landing on a control
+ * has already committed to it, and a delay just looks like lag.
+ *
+ * `role="tooltip"` plus `aria-describedby` — never `aria-labelledby`. A
+ * tooltip supplements a control's name; it is not the name. A button labelled
+ * only by its tooltip is unlabelled to anything that does not hover.
+ */
+
+import { component, html, onUnmount, signal } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { fadeInOut } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+import type { Placement } from "../primitives/floating.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+
+const OPEN_DELAY_MS = 500;
+const CLOSE_DELAY_MS = 150;
+/** How long after one closes that the next opens instantly. */
+const GRACE_MS = 300;
+
+/** Shared across every tooltip on the page — see the "no delay" rule above. */
+let lastClosedAt = 0;
+
+export interface TooltipProps {
+	/** The control being described. */
+	trigger?: Slot;
+	/** The tooltip text. Keep it to a phrase. */
+	content?: Child;
+	placement?: Placement;
+	openDelay?: number;
+	closeDelay?: number;
+	class?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const Tooltip = component<TooltipProps>((props) => {
+	const triggerId = uid("tooltip-trigger");
+	const contentId = uid("tooltip-content");
+	const open = signal(false);
+
+	let timer: ReturnType<typeof setTimeout> | undefined;
+
+	function clear(): void {
+		if (timer !== undefined) clearTimeout(timer);
+		timer = undefined;
+	}
+
+	function scheduleOpen(immediate: boolean): void {
+		clear();
+		const withinGrace = Date.now() - lastClosedAt < GRACE_MS;
+		const delay =
+			immediate || withinGrace ? 0 : (props.openDelay ?? OPEN_DELAY_MS);
+		if (delay === 0) {
+			open(true);
+			return;
+		}
+		timer = setTimeout(() => open(true), delay);
+	}
+
+	function scheduleClose(): void {
+		clear();
+		timer = setTimeout(() => {
+			open(false);
+			lastClosedAt = Date.now();
+		}, props.closeDelay ?? CLOSE_DELAY_MS);
+	}
+
+	onUnmount(clear);
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => open(),
+		onClose: () => {
+			clear();
+			open(false);
+		},
+		placement: props.placement ?? "top",
+		offset: 6,
+		outsidePointer: false,
+		content: () =>
+			html`<div
+				data-slot="tooltip-content"
+				id="${contentId}"
+				role="tooltip"
+				class="${cn(
+					"bg-primary text-primary-foreground z-50 w-fit rounded-md px-3 py-1.5 text-xs text-balance",
+					fadeInOut,
+					read(props.contentClass),
+				)}"
+				@pointerenter="${clear}"
+				@pointerleave="${scheduleClose}"
+			>${props.content}</div>`,
+	});
+
+	return html`<span
+		data-slot="tooltip-trigger"
+		id="${triggerId}"
+		aria-describedby="${() => (open() ? contentId : undefined)}"
+		class="${() => cn("inline-flex", read(props.class))}"
+		@pointerenter="${() => scheduleOpen(false)}"
+		@pointerleave="${scheduleClose}"
+		@focusin="${() => scheduleOpen(true)}"
+		@focusout="${scheduleClose}"
+	>${slot(props.trigger)}</span>`;
+});

package/src/organisms/index.ts

@@ -0,0 +1,134 @@
+/**
+ * Organisms — components that escape their own DOM position.
+ *
+ * The line that separates these from molecules: an organism portals, traps
+ * focus, floats against an anchor, or coordinates several molecules into one
+ * working unit. Dialog is an organism though its markup is simpler than
+ * Table's, because it renders into `<body>` and takes over the page while it
+ * is open.
+ *
+ * Almost all of them are assembled from two shared surfaces —
+ * `floatingSurface` for the anchored overlays, `modalSurface` for the modal
+ * ones — so the parts that are easy to get wrong (teardown order, focus
+ * restoration, hiding the page from assistive technology) exist once.
+ */
+
+export { AlertDialog, type AlertDialogProps } from "./AlertDialog.js";
+export {
+	addDays,
+	addMonths,
+	Calendar,
+	type CalendarProps,
+	type DateRange,
+	isSameDay,
+	monthGrid,
+	startOfDay,
+} from "./Calendar.js";
+export { Carousel, type CarouselProps } from "./Carousel.js";
+export {
+	Chart,
+	type ChartDatum,
+	type ChartProps,
+	type ChartSeries,
+	valueRange,
+} from "./Chart.js";
+export {
+	Combobox,
+	type ComboboxOption,
+	type ComboboxProps,
+} from "./Combobox.js";
+export {
+	Command,
+	type CommandItem,
+	type CommandProps,
+	defaultFilter,
+} from "./Command.js";
+export { CommandDialog, type CommandDialogProps } from "./CommandDialog.js";
+export { ContextMenu, type ContextMenuProps } from "./ContextMenu.js";
+export { type Column, DataTable, type DataTableProps } from "./DataTable.js";
+export { DatePicker, type DatePickerProps, toISODate } from "./DatePicker.js";
+export {
+	DateRangePicker,
+	type DateRangePickerProps,
+} from "./DateRangePicker.js";
+export {
+	Dialog,
+	type DialogProps,
+	dialogBackdropClasses,
+	dialogPanelClasses,
+	useDialog,
+} from "./Dialog.js";
+export { Drawer, type DrawerProps } from "./Drawer.js";
+export { DropdownMenu, type DropdownMenuProps } from "./DropdownMenu.js";
+export {
+	bind,
+	type FieldBinding,
+	Form,
+	type FormProps,
+	SubmitButton,
+	type SubmitButtonProps,
+	TextAreaField,
+	type TextAreaFieldProps,
+	TextField,
+	type TextFieldProps,
+} from "./Form.js";
+export { HoverCard, type HoverCardProps } from "./HoverCard.js";
+export { Menubar, type MenubarMenu, type MenubarProps } from "./Menubar.js";
+export {
+	MessageScroller,
+	type MessageScrollerProps,
+} from "./MessageScroller.js";
+export {
+	type NavigationItem,
+	type NavigationLink,
+	NavigationMenu,
+	type NavigationMenuProps,
+} from "./NavigationMenu.js";
+export {
+	Popover,
+	type PopoverProps,
+	popoverContentClasses,
+} from "./Popover.js";
+export {
+	type Answer,
+	type Answers,
+	type FreeformQuestion,
+	isAnswered,
+	type MultipleChoiceQuestion,
+	type Question,
+	Questionnaire,
+	type QuestionnaireProps,
+	type QuestionOption,
+	type SingleChoiceQuestion,
+} from "./Questionnaire.js";
+export {
+	Select,
+	type SelectOption,
+	type SelectProps,
+	selectTriggerClasses,
+} from "./Select.js";
+export { Sheet, type SheetProps } from "./Sheet.js";
+export {
+	Sidebar,
+	SidebarGroup,
+	SidebarGroupLabel,
+	SidebarMenu,
+	SidebarMenuAction,
+	SidebarMenuItem,
+	type SidebarMenuItemProps,
+	SidebarMenuSub,
+	SidebarMenuSubItem,
+	type SidebarProps,
+	SidebarTrigger,
+	type SidebarTriggerProps,
+	sidebarCollapsed,
+	sidebarState,
+} from "./Sidebar.js";
+export {
+	Toaster,
+	type ToasterProps,
+	type ToastOptions,
+	type ToastVariant,
+	toast,
+} from "./Toaster.js";
+export { Tooltip, type TooltipProps } from "./Tooltip.js";

package/src/primitives/controllable.ts

@@ -0,0 +1,64 @@
+/**
+ * Controlled / uncontrolled state.
+ *
+ * Every stateful shadcn component takes the same trio: `open` (the caller
+ * owns the state), `defaultOpen` (the component owns it) and `onOpenChange`
+ * (told either way). Radix folds that into `useControllableState`; this is the
+ * Aurora equivalent, and the reason a Dialog can be opened either by its own
+ * trigger or by a signal somewhere else in the app without changing shape.
+ *
+ *   // uncontrolled — nebula holds the state
+ *   Dialog({ defaultOpen: false })
+ *
+ *   // controlled — the app holds it, nebula only asks
+ *   const open = signal(false)
+ *   Dialog({ open, onOpenChange: open })
+ *
+ * The rule is one line: a `value` that reads as anything other than
+ * `undefined` wins over the internal signal, on every read. Deciding once at
+ * setup instead would freeze a component whose prop only becomes defined after
+ * an async load.
+ */
+
+import { memo, type ReadSignal, signal } from "@c9up/aurora";
+import { type Reactive, read } from "../lib/props.js";
+
+export interface ControllableOptions<T> {
+	/** The caller's value. Present means controlled. */
+	value?: Reactive<T | undefined>;
+	/** Starting value when uncontrolled. */
+	initial: T;
+	/** Notified on every change, controlled or not. */
+	onChange?: (next: T) => void;
+}
+
+export interface Controllable<T> {
+	/** Current value — the caller's when controlled, ours otherwise. */
+	readonly current: ReadSignal<T>;
+	/** Request a change. Always notifies; only writes internally when uncontrolled. */
+	set(next: T): void;
+}
+
+export function controllable<T>(
+	options: ControllableOptions<T>,
+): Controllable<T> {
+	const internal = signal(options.initial);
+
+	const current = memo(() => {
+		if (options.value === undefined) return internal();
+		const external = read(options.value);
+		return external === undefined ? internal() : external;
+	});
+
+	return {
+		current,
+		set(next: T): void {
+			// Written even when controlled. The caller may ignore `onChange` and
+			// leave its own state put — a "cancel" on a confirm dialog does exactly
+			// that — and the internal value has to stay in step for the moment the
+			// caller stops controlling it.
+			internal(next);
+			options.onChange?.(next);
+		},
+	};
+}