@c9up/nebula 0.1.0

package/src/organisms/MessageScroller.ts

@@ -0,0 +1,145 @@
+/**
+ * MessageScroller — a conversation that stays pinned to the newest message.
+ *
+ * The whole component is one rule and its exception: **follow the bottom, but
+ * never yank the reader.**
+ *
+ * A chat log that always scrolls to the end is unusable the moment you scroll
+ * up to re-read something and a new message arrives. One that never scrolls is
+ * unusable in the ordinary case. So the container remembers whether the reader
+ * was already at the bottom when the content grew: if they were, it follows; if
+ * they had scrolled away, it holds position and offers a button instead.
+ *
+ * Growth is detected with a `ResizeObserver` on the inner wrapper rather than
+ * by counting children. An image finishing its load, a code block wrapping, a
+ * streamed reply growing token by token — none of those change the child count,
+ * and all of them move the bottom.
+ *
+ * `atBottom` carries a tolerance because a scroll position is fractional on a
+ * scaled display: `scrollTop + clientHeight` lands a fraction short of
+ * `scrollHeight` at the true bottom, and an exact comparison would decide the
+ * reader had scrolled away when they had not.
+ *
+ * `role="log"` with `aria-live="polite"`: new turns are announced as they
+ * arrive, without interrupting whatever is being read.
+ */
+
+import { component, html, onMount, onUnmount, signal } from "@c9up/aurora";
+import { buttonVariants } from "../atoms/Button.js";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { ChevronDownIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+
+/** How far from the true bottom still counts as "at the bottom", in px. */
+const BOTTOM_TOLERANCE = 24;
+
+export interface MessageScrollerProps {
+	children?: Slot;
+	/** Announced as the log's name. */
+	label?: string;
+	/** Label for the catch-up button. Default `"Jump to latest"`. */
+	jumpLabel?: string;
+	class?: Reactive<string>;
+}
+
+export const MessageScroller = component<MessageScrollerProps>((props) => {
+	const viewportId = uid("message-scroller");
+	const contentId = uid("message-scroller-content");
+	const pinned = signal(true);
+
+	function viewport(): HTMLElement | null {
+		return document.getElementById(viewportId);
+	}
+
+	function isAtBottom(element: HTMLElement): boolean {
+		const distance =
+			element.scrollHeight - element.scrollTop - element.clientHeight;
+		return distance <= BOTTOM_TOLERANCE;
+	}
+
+	function scrollToBottom(smooth: boolean): void {
+		const element = viewport();
+		if (element === null) return;
+		element.scrollTo({
+			top: element.scrollHeight,
+			behavior: smooth ? "smooth" : "auto",
+		});
+		pinned(true);
+	}
+
+	function onScroll(): void {
+		const element = viewport();
+		if (element === null) return;
+		pinned(isAtBottom(element));
+	}
+
+	/**
+	 * Follow the bottom only if we were already there.
+	 *
+	 * Read from the `pinned` signal rather than re-measuring: by the time the
+	 * observer fires, the content has already grown and the viewport is no
+	 * longer at the bottom by definition. The answer has to come from before.
+	 */
+	function onContentResize(): void {
+		if (!pinned()) return;
+		scrollToBottom(false);
+	}
+
+	let observer: ResizeObserver | undefined;
+
+	onMount(() => {
+		const element = viewport();
+		if (element === null) return;
+
+		element.addEventListener("scroll", onScroll, { passive: true });
+		// Start at the newest message, without animating there.
+		scrollToBottom(false);
+
+		if (typeof ResizeObserver !== "function") return;
+		const content = document.getElementById(contentId);
+		if (content === null) return;
+		observer = new ResizeObserver(onContentResize);
+		observer.observe(content);
+	});
+
+	onUnmount(() => {
+		viewport()?.removeEventListener("scroll", onScroll);
+		observer?.disconnect();
+	});
+
+	return html`<div
+		data-slot="message-scroller"
+		class="${() => cn("relative flex min-h-0 flex-col", read(props.class))}"
+	>
+		<div
+			data-slot="message-scroller-viewport"
+			id="${viewportId}"
+			role="log"
+			aria-live="polite"
+			aria-label="${props.label ?? "Conversation"}"
+			tabindex="0"
+			class="min-h-0 flex-1 overflow-y-auto overscroll-contain outline-none [scrollbar-width:thin]"
+		>
+			<div
+				data-slot="message-scroller-content"
+				id="${contentId}"
+				class="flex flex-col gap-4 p-4"
+			>${slot(props.children)}</div>
+		</div>
+		<button
+			type="button"
+			data-slot="message-scroller-jump"
+			?hidden="${() => pinned()}"
+			class="${cn(
+				buttonVariants({ variant: "secondary", size: "sm" }),
+				"absolute inset-x-0 bottom-3 mx-auto w-fit gap-1 rounded-full shadow-md",
+			)}"
+			@click="${() => scrollToBottom(true)}"
+		>
+			${ChevronDownIcon({ class: "size-4" })}
+			${props.jumpLabel ?? "Jump to latest"}
+		</button>
+	</div>`;
+});

package/src/organisms/NavigationMenu.ts

@@ -0,0 +1,184 @@
+/**
+ * NavigationMenu — a site navigation bar with drop-down panels.
+ *
+ * Not a menu, despite the name Radix gave it, and the distinction changes the
+ * markup. A menu is a list of *commands*; this is a list of *links*. So it is
+ * a `<nav>` containing a list of anchors, with `aria-expanded` on the entries
+ * that open a panel — never `role="menu"`, which would have a screen reader
+ * announce a navigation bar as an application menu and offer the wrong
+ * shortcuts for it.
+ *
+ * Entries are either a plain link or a link with a panel. Hover opens a panel
+ * after a short delay and keeps it open briefly on leave, because the pointer
+ * has to travel from the trigger to the panel and a naive `mouseleave` closes
+ * it in the gap between them.
+ *
+ * Every panel is reachable by keyboard: the trigger is a real button, Enter
+ * and ArrowDown open it, Escape closes it and returns focus.
+ */
+
+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 { ChevronDownIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+
+const OPEN_DELAY_MS = 150;
+const CLOSE_DELAY_MS = 250;
+
+export interface NavigationLink {
+	label: Child;
+	href: string;
+	description?: Child;
+}
+
+export interface NavigationItem {
+	label: Child;
+	/** A plain link. Mutually exclusive with `links` / `content`. */
+	href?: string;
+	/** A panel of links, laid out in a grid. */
+	links?: readonly NavigationLink[];
+	/** Arbitrary panel content, when a link grid is not enough. */
+	content?: Slot;
+}
+
+export interface NavigationMenuProps {
+	items: readonly NavigationItem[];
+	class?: Reactive<string>;
+}
+
+export const triggerClasses =
+	"group inline-flex h-9 w-max items-center justify-center gap-1 rounded-md bg-background px-4 py-2 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus:outline-none disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-accent/50";
+
+export const NavigationMenu = component<NavigationMenuProps>((props) => {
+	const contentId = uid("navigation-menu-content");
+	const triggerIds = props.items.map(() => uid("navigation-menu-trigger"));
+	const openIndex = signal(-1);
+
+	let timer: ReturnType<typeof setTimeout> | undefined;
+
+	function clear(): void {
+		if (timer !== undefined) clearTimeout(timer);
+		timer = undefined;
+	}
+
+	function schedule(index: number, delay: number): void {
+		clear();
+		timer = setTimeout(() => openIndex(index), delay);
+	}
+
+	onUnmount(clear);
+
+	function close(): void {
+		clear();
+		openIndex(-1);
+	}
+
+	floatingSurface({
+		anchor: () => {
+			const id = triggerIds[openIndex()];
+			return id === undefined ? null : document.getElementById(id);
+		},
+		open: () => openIndex() !== -1,
+		onClose: close,
+		placement: "bottom-start",
+		offset: 6,
+		content: () =>
+			html`<div
+				data-slot="navigation-menu-content"
+				id="${contentId}"
+				class="${cn(
+					"bg-popover text-popover-foreground z-50 rounded-md border p-4 shadow-md outline-none",
+					zoomInOut,
+				)}"
+				@pointerenter="${clear}"
+				@pointerleave="${() => schedule(-1, CLOSE_DELAY_MS)}"
+			>${renderPanel(props.items[openIndex()])}</div>`,
+	});
+
+	return html`<nav
+		data-slot="navigation-menu"
+		class="${() => cn("relative flex max-w-max flex-1 items-center justify-center", read(props.class))}"
+	>
+		<ul class="flex flex-1 list-none items-center justify-center gap-1">
+			${props.items.map((item, index) => renderEntry(item, index))}
+		</ul>
+	</nav>`;
+
+	function renderEntry(item: NavigationItem, index: number): Child {
+		if (item.href !== undefined) {
+			return html`<li>
+				<a
+					href="${item.href}"
+					data-slot="navigation-menu-link"
+					class="${triggerClasses}"
+					@pointerenter="${() => {
+						// Hovering a plain link while a panel is open closes it: the
+						// pointer has left the panel's branch of the bar.
+						if (openIndex() !== -1) schedule(-1, CLOSE_DELAY_MS);
+					}}"
+				>${item.label}</a>
+			</li>`;
+		}
+
+		return html`<li>
+			<button
+				type="button"
+				id="${triggerIds[index]}"
+				data-slot="navigation-menu-trigger"
+				aria-expanded="${() => (openIndex() === index ? "true" : "false")}"
+				aria-controls="${() => (openIndex() === index ? contentId : undefined)}"
+				data-state="${() => (openIndex() === index ? "open" : "closed")}"
+				class="${triggerClasses}"
+				@click="${() => (openIndex() === index ? close() : openIndex(index))}"
+				@pointerenter="${() => schedule(index, OPEN_DELAY_MS)}"
+				@pointerleave="${() => schedule(-1, CLOSE_DELAY_MS)}"
+				@keydown="${(event: KeyboardEvent) => {
+					if (
+						event.key === "ArrowDown" ||
+						event.key === "Enter" ||
+						event.key === " "
+					) {
+						event.preventDefault();
+						openIndex(index);
+					}
+				}}"
+			>
+				${item.label}
+				${ChevronDownIcon({
+					class:
+						"relative top-px size-3 transition-transform duration-200 group-data-[state=open]:rotate-180",
+				})}
+			</button>
+		</li>`;
+	}
+});
+
+function renderPanel(item: NavigationItem | undefined): Child {
+	if (item === undefined) return null;
+	if (item.content !== undefined) return slot(item.content)();
+
+	return html`<ul class="grid w-[400px] gap-1 md:w-[500px] md:grid-cols-2">
+		${(item.links ?? []).map(
+			(link) => html`<li>
+				<a
+					href="${link.href}"
+					class="hover:bg-accent hover:text-accent-foreground focus:bg-accent block select-none space-y-1 rounded-md p-3 leading-none no-underline outline-none transition-colors"
+				>
+					<div class="text-sm leading-none font-medium">${link.label}</div>
+					${
+						link.description === undefined
+							? null
+							: html`<p class="text-muted-foreground line-clamp-2 text-sm leading-snug">
+								${link.description}
+							</p>`
+					}
+				</a>
+			</li>`,
+		)}
+	</ul>`;
+}

package/src/organisms/Popover.ts

@@ -0,0 +1,84 @@
+/**
+ * Popover — a floating panel anchored to a trigger.
+ *
+ * The plainest use of `floatingSurface`, and the one to read first: the other
+ * anchored overlays in this directory are this component with a different
+ * opening gesture and different contents.
+ *
+ * `modal` decides whether focus is trapped. A popover holding a form should
+ * trap — tabbing out of a half-filled form into the page behind loses the
+ * user's place. A popover holding a paragraph of help should not, because
+ * trapping focus in something the user can only read is a dead end.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import type { Placement } from "../primitives/floating.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+
+export const popoverContentClasses =
+	"bg-popover text-popover-foreground z-50 w-72 rounded-md border p-4 shadow-md outline-none";
+
+export interface PopoverProps {
+	/** Rendered inside the trigger button. */
+	trigger?: Slot;
+	/** The panel's contents. */
+	children?: Slot;
+	open?: Reactive<boolean>;
+	defaultOpen?: boolean;
+	onOpenChange?: (open: boolean) => void;
+	placement?: Placement;
+	offset?: number;
+	/** Trap focus inside. Use for panels holding form controls. */
+	modal?: boolean;
+	class?: Reactive<string>;
+	triggerClass?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const Popover = component<PopoverProps>((props) => {
+	const triggerId = uid("popover-trigger");
+	const contentId = uid("popover-content");
+
+	const state = controllable<boolean>({
+		value: props.open,
+		initial: props.defaultOpen ?? false,
+		onChange: props.onOpenChange,
+	});
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => state.current(),
+		onClose: () => state.set(false),
+		placement: props.placement ?? "bottom",
+		offset: props.offset ?? 4,
+		trapFocus: props.modal === true,
+		autoFocus: props.modal !== true,
+		content: () =>
+			html`<div
+				data-slot="popover-content"
+				id="${contentId}"
+				role="dialog"
+				aria-labelledby="${triggerId}"
+				tabindex="-1"
+				class="${cn(popoverContentClasses, zoomInOut, read(props.contentClass))}"
+			>${slot(props.children)}</div>`,
+	});
+
+	return html`<button
+		type="button"
+		data-slot="popover-trigger"
+		id="${triggerId}"
+		aria-haspopup="dialog"
+		aria-expanded="${() => (state.current() ? "true" : "false")}"
+		aria-controls="${() => (state.current() ? contentId : undefined)}"
+		data-state="${() => (state.current() ? "open" : "closed")}"
+		class="${() => cn(read(props.triggerClass))}"
+		@click="${() => state.set(!state.current())}"
+	>${slot(props.trigger)}</button>`;
+});