@c9up/nebula 0.1.0

package/dist/organisms/MessageScroller.js

@@ -0,0 +1,124 @@
+/**
+ * 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 { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { ChevronDownIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { read } from "../lib/props.js";
+/** How far from the true bottom still counts as "at the bottom", in px. */
+const BOTTOM_TOLERANCE = 24;
+export const MessageScroller = component((props) => {
+    const viewportId = uid("message-scroller");
+    const contentId = uid("message-scroller-content");
+    const pinned = signal(true);
+    function viewport() {
+        return document.getElementById(viewportId);
+    }
+    function isAtBottom(element) {
+        const distance = element.scrollHeight - element.scrollTop - element.clientHeight;
+        return distance <= BOTTOM_TOLERANCE;
+    }
+    function scrollToBottom(smooth) {
+        const element = viewport();
+        if (element === null)
+            return;
+        element.scrollTo({
+            top: element.scrollHeight,
+            behavior: smooth ? "smooth" : "auto",
+        });
+        pinned(true);
+    }
+    function onScroll() {
+        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() {
+        if (!pinned())
+            return;
+        scrollToBottom(false);
+    }
+    let observer;
+    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/dist/organisms/NavigationMenu.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 type { Child } from "../lib/children.js";
+import { type Slot } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+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 declare 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 declare const NavigationMenu: (props?: NavigationMenuProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/NavigationMenu.js

@@ -0,0 +1,139 @@
+/**
+ * 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 { 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 { read } from "../lib/props.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+const OPEN_DELAY_MS = 150;
+const CLOSE_DELAY_MS = 250;
+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((props) => {
+    const contentId = uid("navigation-menu-content");
+    const triggerIds = props.items.map(() => uid("navigation-menu-trigger"));
+    const openIndex = signal(-1);
+    let timer;
+    function clear() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function schedule(index, delay) {
+        clear();
+        timer = setTimeout(() => openIndex(index), delay);
+    }
+    onUnmount(clear);
+    function close() {
+        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, index) {
+        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) => {
+            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) {
+    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/dist/organisms/Popover.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { type Slot } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+import type { Placement } from "../primitives/floating.js";
+export declare 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 declare const Popover: (props?: PopoverProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/Popover.js

@@ -0,0 +1,58 @@
+/**
+ * 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 { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.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 const Popover = component((props) => {
+    const triggerId = uid("popover-trigger");
+    const contentId = uid("popover-content");
+    const state = controllable({
+        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>`;
+});

package/dist/organisms/Questionnaire.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Questionnaire — a survey, one question per step.
+ *
+ * Composed rather than reimplemented: `RadioGroup`, `Checkbox`, `Input`,
+ * `Textarea`, `Progress` and `Button` already exist, so this file is the state
+ * machine over them — which question is showing, what has been answered, and
+ * whether the reader may move on.
+ *
+ * Three decisions worth stating, because each has an obvious wrong answer:
+ *
+ * **The step counter is announced.** A visual progress bar tells a sighted
+ * reader they are on question 3 of 8. `aria-live="polite"` on the counter is
+ * what tells everyone else, and without it the survey is a series of
+ * unexplained page changes.
+ *
+ * **Answers survive going back.** Moving to the previous question and forward
+ * again keeps what was typed. The alternative — clearing on navigation —
+ * punishes the reader for checking what they said a moment ago.
+ *
+ * **A required question blocks Next, and says why.** Disabling the button
+ * silently is the common version, and it leaves the reader clicking a dead
+ * control with no explanation. The message appears only after an attempt, so
+ * the survey does not open by telling you that you have done nothing wrong yet.
+ */
+import type { Child } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+export interface QuestionOption {
+    value: string;
+    label: Child;
+    description?: Child;
+}
+interface BaseQuestion {
+    /** Stable key. The answer is filed under it. */
+    id: string;
+    prompt: Child;
+    description?: Child;
+    /** Blocks Next until answered. */
+    required?: boolean;
+}
+export interface SingleChoiceQuestion extends BaseQuestion {
+    type: "single";
+    options: readonly QuestionOption[];
+}
+export interface MultipleChoiceQuestion extends BaseQuestion {
+    type: "multiple";
+    options: readonly QuestionOption[];
+}
+export interface FreeformQuestion extends BaseQuestion {
+    type: "text";
+    placeholder?: string;
+    /** Renders a textarea instead of a single-line input. */
+    multiline?: boolean;
+}
+export type Question = SingleChoiceQuestion | MultipleChoiceQuestion | FreeformQuestion;
+/** One answer: a value for single/text, a set for multiple. */
+export type Answer = string | readonly string[];
+export type Answers = Readonly<Record<string, Answer>>;
+export interface QuestionnaireProps {
+    questions: readonly Question[];
+    onComplete: (answers: Answers) => void;
+    onAnswerChange?: (id: string, answer: Answer) => void;
+    /** Allow skipping questions that are not required. Default `true`. */
+    skippable?: boolean;
+    showProgress?: boolean;
+    backLabel?: string;
+    nextLabel?: string;
+    skipLabel?: string;
+    submitLabel?: string;
+    class?: Reactive<string>;
+}
+/** Has this question been answered at all? */
+export declare function isAnswered(question: Question, answer: Answer | undefined): boolean;
+export declare const Questionnaire: (props?: QuestionnaireProps | undefined) => import("@c9up/aurora").TemplateResult;
+export {};