@c9up/nebula 0.1.0

package/src/organisms/DatePicker.ts

@@ -0,0 +1,141 @@
+/**
+ * DatePicker — a Calendar in a popover, behind a button.
+ *
+ * shadcn composes this out of Popover, Button and Calendar rather than
+ * shipping it; nebula ships it, because the composition has three details that
+ * are easy to get wrong and pointless to rediscover per project.
+ *
+ * The popover closes on selection — a date picker that stays open after a
+ * choice leaves the user hunting for the way out. Focus returns to the
+ * trigger, so the tab order does not restart at the top of the page. And the
+ * trigger reads the chosen date through `Intl.DateTimeFormat`, so it renders
+ * in the user's locale rather than an American ordering everyone else has to
+ * decode.
+ *
+ * A hidden input carries the value as ISO `YYYY-MM-DD`, which is what a server
+ * wants — never the localised string on the button.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import { buttonVariants } from "../atoms/Button.js";
+import { cn } from "../lib/cn.js";
+import { CalendarIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { type Reactive, read, readOr } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { focusSilently } from "../primitives/focusable.js";
+import { Calendar, startOfDay } from "./Calendar.js";
+
+export interface DatePickerProps {
+	name?: string;
+	value?: Reactive<Date | undefined>;
+	defaultValue?: Date;
+	placeholder?: string;
+	min?: Date;
+	max?: Date;
+	disabled?: Reactive<boolean>;
+	invalid?: Reactive<boolean>;
+	locale?: string;
+	class?: Reactive<string>;
+	onValueChange?: (date: Date) => void;
+}
+
+/** `YYYY-MM-DD` from a local date, without a timezone round-trip. */
+export function toISODate(date: Date): string {
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${date.getFullYear()}-${month}-${day}`;
+}
+
+export const DatePicker = component<DatePickerProps>((props) => {
+	const triggerId = uid("date-picker-trigger");
+	const contentId = uid("date-picker-content");
+	const open = signal(false);
+
+	const selection = controllable<Date | undefined>({
+		value: props.value,
+		initial: props.defaultValue,
+		onChange: (next) => {
+			if (next !== undefined) props.onValueChange?.(next);
+		},
+	});
+
+	const format = new Intl.DateTimeFormat(props.locale, { dateStyle: "medium" });
+
+	function choose(date: Date): void {
+		selection.set(startOfDay(date));
+		open(false);
+		focusSilently(document.getElementById(triggerId));
+	}
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => open(),
+		onClose: () => open(false),
+		placement: "bottom-start",
+		offset: 4,
+		trapFocus: true,
+		// The cursor cell, not the first focusable — landing on the previous-month
+		// arrow means the first arrow key pages the calendar instead of moving a
+		// day, which is not what a keyboard user reaching a date grid expects.
+		initialFocus: (content) => content.querySelector("[data-cursor]"),
+		content: () =>
+			html`<div
+				data-slot="date-picker-content"
+				id="${contentId}"
+				role="dialog"
+				aria-label="Choose a date"
+				class="${cn(
+					"bg-popover text-popover-foreground z-50 rounded-md border p-0 shadow-md outline-none",
+					zoomInOut,
+				)}"
+			>
+				${Calendar({
+					value: () => selection.current(),
+					defaultMonth: selection.current(),
+					min: props.min,
+					max: props.max,
+					locale: props.locale,
+					onValueChange: choose,
+				})}
+			</div>`,
+	});
+
+	return html`<div data-slot="date-picker" class="${() => cn("inline-flex", read(props.class))}">
+		<button
+			type="button"
+			id="${triggerId}"
+			data-slot="date-picker-trigger"
+			aria-haspopup="dialog"
+			aria-expanded="${() => (open() ? "true" : "false")}"
+			aria-controls="${() => (open() ? contentId : undefined)}"
+			aria-invalid="${() => (read(props.invalid) === true ? "true" : undefined)}"
+			data-placeholder="${() => (selection.current() === undefined ? "" : undefined)}"
+			?disabled="${() => readOr(props.disabled, false)}"
+			class="${buttonVariants({
+				variant: "outline",
+				class:
+					"w-full justify-start gap-2 font-normal data-[placeholder]:text-muted-foreground",
+			})}"
+			@click="${() => open(!open())}"
+		>
+			${CalendarIcon({ class: "size-4" })}
+			<span>${() => {
+				const current = selection.current();
+				return current === undefined
+					? (props.placeholder ?? "Pick a date")
+					: format.format(current);
+			}}</span>
+		</button>
+		<input
+			type="hidden"
+			name="${props.name}"
+			.value="${() => {
+				const current = selection.current();
+				return current === undefined ? "" : toISODate(current);
+			}}"
+		/>
+	</div>`;
+});

package/src/organisms/DateRangePicker.ts

@@ -0,0 +1,149 @@
+/**
+ * DateRangePicker — a Calendar in range mode, behind a button.
+ *
+ * The same shell as `DatePicker`, and deliberately so: the two differ in what
+ * they collect, not in how they behave. Both close on completion, both return
+ * focus to the trigger, both format through `Intl` and both post ISO dates.
+ *
+ * The one behavioural difference is when to close. A single date is done in
+ * one click; a range is not done until the second, so the popover stays open
+ * between them. Closing on the first click and reopening for the second is the
+ * usual bug here, and it makes the control feel broken.
+ *
+ * Two hidden inputs rather than one comma-joined field. A server parsing
+ * `from`/`to` separately never has to split a string, and an empty `to` is
+ * unambiguous.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import { buttonVariants } from "../atoms/Button.js";
+import { cn } from "../lib/cn.js";
+import { CalendarIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { type Reactive, read, readOr } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { focusSilently } from "../primitives/focusable.js";
+import { Calendar, type DateRange, startOfDay } from "./Calendar.js";
+import { toISODate } from "./DatePicker.js";
+
+export interface DateRangePickerProps {
+	/** Base name for the hidden inputs — `"stay"` posts `stay_from` / `stay_to`. */
+	name?: string;
+	value?: Reactive<DateRange | undefined>;
+	defaultValue?: DateRange;
+	placeholder?: string;
+	min?: Date;
+	max?: Date;
+	disabled?: Reactive<boolean>;
+	invalid?: Reactive<boolean>;
+	locale?: string;
+	class?: Reactive<string>;
+	/** Fires on both clicks — `to` is absent after the first. */
+	onValueChange?: (range: DateRange) => void;
+}
+
+export const DateRangePicker = component<DateRangePickerProps>((props) => {
+	const triggerId = uid("date-range-trigger");
+	const contentId = uid("date-range-content");
+	const open = signal(false);
+
+	const selection = controllable<DateRange | undefined>({
+		value: props.value,
+		initial: props.defaultValue,
+		onChange: (next) => {
+			if (next !== undefined) props.onValueChange?.(next);
+		},
+	});
+
+	const format = new Intl.DateTimeFormat(props.locale, { dateStyle: "medium" });
+
+	function pick(range: DateRange): void {
+		selection.set({
+			from: startOfDay(range.from),
+			to: range.to === undefined ? undefined : startOfDay(range.to),
+		});
+		// Only a completed span closes the popover.
+		if (range.to === undefined) return;
+		open(false);
+		focusSilently(document.getElementById(triggerId));
+	}
+
+	function label(): string {
+		const current = selection.current();
+		if (current === undefined) return props.placeholder ?? "Pick a date range";
+		if (current.to === undefined) return `${format.format(current.from)} — …`;
+		return `${format.format(current.from)} — ${format.format(current.to)}`;
+	}
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => open(),
+		onClose: () => open(false),
+		placement: "bottom-start",
+		offset: 4,
+		trapFocus: true,
+		initialFocus: (content) => content.querySelector("[data-cursor]"),
+		content: () =>
+			html`<div
+				data-slot="date-range-picker-content"
+				id="${contentId}"
+				role="dialog"
+				aria-label="Choose a date range"
+				class="${cn(
+					"bg-popover text-popover-foreground z-50 rounded-md border p-0 shadow-md outline-none",
+					zoomInOut,
+				)}"
+			>
+				${Calendar({
+					mode: "range",
+					range: () => selection.current(),
+					defaultMonth: selection.current()?.from,
+					min: props.min,
+					max: props.max,
+					locale: props.locale,
+					onRangeChange: pick,
+				})}
+			</div>`,
+	});
+
+	const isoOf = (date: Date | undefined): string =>
+		date === undefined ? "" : toISODate(date);
+
+	return html`<div
+		data-slot="date-range-picker"
+		class="${() => cn("inline-flex", read(props.class))}"
+	>
+		<button
+			type="button"
+			id="${triggerId}"
+			data-slot="date-range-picker-trigger"
+			aria-haspopup="dialog"
+			aria-expanded="${() => (open() ? "true" : "false")}"
+			aria-controls="${() => (open() ? contentId : undefined)}"
+			aria-invalid="${() => (read(props.invalid) === true ? "true" : undefined)}"
+			data-placeholder="${() => (selection.current() === undefined ? "" : undefined)}"
+			?disabled="${() => readOr(props.disabled, false)}"
+			class="${buttonVariants({
+				variant: "outline",
+				class:
+					"w-full justify-start gap-2 font-normal data-[placeholder]:text-muted-foreground",
+			})}"
+			@click="${() => open(!open())}"
+		>
+			${CalendarIcon({ class: "size-4" })}
+			<span>${label}</span>
+		</button>
+		<input
+			type="hidden"
+			name="${props.name === undefined ? undefined : `${props.name}_from`}"
+			.value="${() => isoOf(selection.current()?.from)}"
+		/>
+		<input
+			type="hidden"
+			name="${props.name === undefined ? undefined : `${props.name}_to`}"
+			.value="${() => isoOf(selection.current()?.to)}"
+		/>
+	</div>`;
+});

package/src/organisms/Dialog.ts

@@ -0,0 +1,162 @@
+/**
+ * Dialog — a modal window over the page.
+ *
+ * `modalSurface` supplies the contract (trap, scroll lock, backdrop dismissal,
+ * hiding the page from assistive technology); this component supplies the
+ * markup and the trigger.
+ *
+ * The `panel` callback matters more than it looks. The overlay's root spans
+ * the viewport so the backdrop can, which means containment has to be answered
+ * against the panel — check the root and every click on the page counts as
+ * inside, and clicking the backdrop silently stops closing the dialog.
+ *
+ * `aria-labelledby` points at the title and `aria-describedby` at the
+ * description, so a screen reader announces what the dialog is for on open. A
+ * dialog with neither announces only "dialog", which is why `title` is
+ * required rather than optional — `srOnlyTitle` is there for designs that show
+ * no visible heading.
+ */
+
+import { component, html, 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 { XIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { fadeInOut, zoomInOut } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { modalSurface } from "../primitives/modalSurface.js";
+
+export const dialogBackdropClasses = "fixed inset-0 z-50 bg-black/50";
+
+export const dialogPanelClasses =
+	"bg-background fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-lg border p-6 shadow-lg outline-none sm:max-w-lg";
+
+export interface DialogProps {
+	/** Rendered inside the trigger button. Omit to drive `open` yourself. */
+	trigger?: Slot;
+	/** Announced on open. Hide it visually with `srOnlyTitle`. */
+	title: Child;
+	description?: Child;
+	children?: Slot;
+	/** Actions, laid out bottom-right. */
+	footer?: Slot;
+	open?: Reactive<boolean>;
+	defaultOpen?: boolean;
+	onOpenChange?: (open: boolean) => void;
+	/** Keep the title for screen readers but out of the layout. */
+	srOnlyTitle?: boolean;
+	/** Hide the corner close button. Escape and the backdrop still work. */
+	hideCloseButton?: boolean;
+	class?: Reactive<string>;
+	triggerClass?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const Dialog = component<DialogProps>((props) => {
+	const triggerId = uid("dialog-trigger");
+	const panelId = uid("dialog-panel");
+	const titleId = uid("dialog-title");
+	const descriptionId = uid("dialog-description");
+
+	const state = controllable<boolean>({
+		value: props.open,
+		initial: props.defaultOpen ?? false,
+		onChange: props.onOpenChange,
+	});
+
+	modalSurface({
+		open: () => state.current(),
+		onClose: () => state.set(false),
+		panel: (root) => root.querySelector(`#${CSS.escape(panelId)}`),
+		returnFocus: () => document.getElementById(triggerId),
+		content: () =>
+			html`<div data-slot="dialog-overlay" class="${cn("fixed inset-0 z-50", fadeInOut)}">
+				<div data-slot="dialog-backdrop" class="${dialogBackdropClasses}"></div>
+				<div
+					data-slot="dialog-content"
+					id="${panelId}"
+					role="dialog"
+					aria-modal="true"
+					aria-labelledby="${titleId}"
+					aria-describedby="${props.description === undefined ? undefined : descriptionId}"
+					tabindex="-1"
+					class="${cn(dialogPanelClasses, zoomInOut, read(props.contentClass))}"
+				>
+					<div data-slot="dialog-header" class="flex flex-col gap-2 text-center sm:text-left">
+						<h2
+							id="${titleId}"
+							data-slot="dialog-title"
+							class="${cn(
+								"text-lg leading-none font-semibold",
+								props.srOnlyTitle === true ? "sr-only" : "",
+							)}"
+						>${props.title}</h2>
+						${
+							props.description === undefined
+								? null
+								: html`<p
+									id="${descriptionId}"
+									data-slot="dialog-description"
+									class="text-muted-foreground text-sm"
+								>${props.description}</p>`
+						}
+					</div>
+					${slot(props.children)}
+					${
+						props.footer === undefined
+							? null
+							: html`<div
+								data-slot="dialog-footer"
+								class="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end"
+							>${slot(props.footer)}</div>`
+					}
+					${
+						props.hideCloseButton === true
+							? null
+							: html`<button
+								type="button"
+								data-slot="dialog-close"
+								class="ring-offset-background focus-visible:ring-ring absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none"
+								@click="${() => state.set(false)}"
+							>
+								${XIcon({ class: "size-4" })}
+								<span class="sr-only">Close</span>
+							</button>`
+					}
+				</div>
+			</div>`,
+	});
+
+	if (props.trigger === undefined) {
+		// No trigger: the dialog is driven entirely by the `open` prop. Something
+		// still has to be in the tree for the component to mount into, and the
+		// surface itself lives in a portal.
+		return html`<span data-slot="dialog" hidden></span>`;
+	}
+
+	return html`<button
+		type="button"
+		data-slot="dialog-trigger"
+		id="${triggerId}"
+		aria-haspopup="dialog"
+		aria-expanded="${() => (state.current() ? "true" : "false")}"
+		class="${() => cn(read(props.triggerClass))}"
+		@click="${() => state.set(true)}"
+	>${slot(props.trigger)}</button>`;
+});
+
+/** A dialog driven purely by a signal, with no trigger of its own. */
+export function useDialog(initial = false): {
+	open: () => boolean;
+	show(): void;
+	hide(): void;
+} {
+	const open = signal(initial);
+	return {
+		open: () => open(),
+		show: () => open(true),
+		hide: () => open(false),
+	};
+}

package/src/organisms/Drawer.ts

@@ -0,0 +1,167 @@
+/**
+ * Drawer — a bottom sheet you can swipe away.
+ *
+ * A Sheet from the bottom edge, plus the one gesture that makes it feel native
+ * on a phone: drag the panel down to dismiss it.
+ *
+ * The drag rules are what separate this from a panel that merely follows the
+ * finger:
+ *
+ * - Downward only. Dragging up would peel the panel off its edge and leave a
+ *   gap under it.
+ * - Released past a threshold, it closes; short of it, it springs back. A
+ *   distance threshold alone punishes a fast flick, so velocity counts too —
+ *   a quick short drag dismisses, which is what the gesture means.
+ * - The transition is disabled during the drag and restored on release.
+ *   Leaving it on makes the panel lag the finger by its own duration, which
+ *   reads as a broken gesture rather than a smooth one.
+ *
+ * The grab handle is decorative. Everything the drag does, the close button,
+ * Escape and the backdrop already do — a gesture must never be the only way
+ * out of a modal surface.
+ */
+
+import { component, html } 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, slideFrom } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { modalSurface } from "../primitives/modalSurface.js";
+import { dialogBackdropClasses } from "./Dialog.js";
+
+/** Drag this far down and release to dismiss, in px. */
+const DISMISS_DISTANCE = 120;
+/** Or release faster than this, in px per millisecond. */
+const DISMISS_VELOCITY = 0.5;
+
+export interface DrawerProps {
+	trigger?: Slot;
+	title: Child;
+	description?: Child;
+	children?: Slot;
+	footer?: Slot;
+	open?: Reactive<boolean>;
+	defaultOpen?: boolean;
+	onOpenChange?: (open: boolean) => void;
+	/** Turn off drag-to-dismiss — for a drawer holding a scrollable list. */
+	disableDrag?: boolean;
+	triggerClass?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const Drawer = component<DrawerProps>((props) => {
+	const triggerId = uid("drawer-trigger");
+	const panelId = uid("drawer-panel");
+	const titleId = uid("drawer-title");
+	const descriptionId = uid("drawer-description");
+
+	const state = controllable<boolean>({
+		value: props.open,
+		initial: props.defaultOpen ?? false,
+		onChange: props.onOpenChange,
+	});
+
+	function onPointerDown(event: PointerEvent): void {
+		if (props.disableDrag === true) return;
+		const panel = document.getElementById(panelId);
+		if (panel === null) return;
+
+		const startY = event.clientY;
+		const startedAt = performance.now();
+		let offset = 0;
+		panel.setPointerCapture(event.pointerId);
+		panel.style.transition = "none";
+
+		const onMove = (move: PointerEvent): void => {
+			offset = Math.max(0, move.clientY - startY);
+			panel.style.transform = `translateY(${offset}px)`;
+		};
+
+		const onUp = (): void => {
+			panel.releasePointerCapture(event.pointerId);
+			panel.removeEventListener("pointermove", onMove);
+			panel.removeEventListener("pointerup", onUp);
+			panel.removeEventListener("pointercancel", onUp);
+
+			// Restore the transition before deciding, so both outcomes animate.
+			panel.style.transition = "";
+			const velocity = offset / Math.max(1, performance.now() - startedAt);
+
+			if (offset > DISMISS_DISTANCE || velocity > DISMISS_VELOCITY) {
+				panel.style.transform = "";
+				state.set(false);
+			} else {
+				panel.style.transform = "";
+			}
+		};
+
+		panel.addEventListener("pointermove", onMove);
+		panel.addEventListener("pointerup", onUp);
+		panel.addEventListener("pointercancel", onUp);
+	}
+
+	modalSurface({
+		open: () => state.current(),
+		onClose: () => state.set(false),
+		panel: (root) => root.querySelector(`#${CSS.escape(panelId)}`),
+		returnFocus: () => document.getElementById(triggerId),
+		content: () =>
+			html`<div data-slot="drawer-overlay" class="${cn("fixed inset-0 z-50", fadeInOut)}">
+				<div class="${dialogBackdropClasses}"></div>
+				<div
+					data-slot="drawer-content"
+					id="${panelId}"
+					role="dialog"
+					aria-modal="true"
+					aria-labelledby="${titleId}"
+					aria-describedby="${props.description === undefined ? undefined : descriptionId}"
+					tabindex="-1"
+					class="${cn(
+						"bg-background fixed inset-x-0 bottom-0 z-50 mt-24 flex max-h-[80vh] touch-none flex-col gap-4 rounded-t-lg border-t p-6 shadow-lg outline-none",
+						slideFrom("bottom"),
+						read(props.contentClass),
+					)}"
+					@pointerdown="${onPointerDown}"
+				>
+					<div
+						data-slot="drawer-handle"
+						aria-hidden="true"
+						class="bg-muted mx-auto h-1.5 w-12 shrink-0 rounded-full"
+					></div>
+					<div class="flex flex-col gap-1.5 text-center sm:text-left">
+						<h2 id="${titleId}" class="text-foreground font-semibold">${props.title}</h2>
+						${
+							props.description === undefined
+								? null
+								: html`<p id="${descriptionId}" class="text-muted-foreground text-sm">
+									${props.description}
+								</p>`
+						}
+					</div>
+					<div class="flex-1 overflow-y-auto">${slot(props.children)}</div>
+					${
+						props.footer === undefined
+							? null
+							: html`<div class="mt-auto flex flex-col gap-2">${slot(props.footer)}</div>`
+					}
+				</div>
+			</div>`,
+	});
+
+	if (props.trigger === undefined) {
+		return html`<span data-slot="drawer" hidden></span>`;
+	}
+
+	return html`<button
+		type="button"
+		data-slot="drawer-trigger"
+		id="${triggerId}"
+		aria-haspopup="dialog"
+		aria-expanded="${() => (state.current() ? "true" : "false")}"
+		class="${() => cn(read(props.triggerClass))}"
+		@click="${() => state.set(true)}"
+	>${slot(props.trigger)}</button>`;
+});