@c9up/nebula 0.1.0

package/dist/organisms/DropdownMenu.js

@@ -0,0 +1,91 @@
+/**
+ * DropdownMenu — a menu opened from a button.
+ *
+ * The panel, its entries and its keyboard model all come from `./menu.js`;
+ * this component contributes the trigger and the open/close state.
+ *
+ * Two behaviours are specific to a button-opened menu:
+ *
+ * - Opening with the keyboard focuses the first item; opening with the pointer
+ *   does not. A keyboard user has no other way in, while pre-highlighting an
+ *   item for a mouse user suggests it is about to be chosen.
+ * - ArrowDown on the trigger opens the menu *and* enters it, which is the
+ *   behaviour of every native menu button and the one users try first.
+ */
+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 { read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { menuPanel, wireMenu } from "../primitives/menu.js";
+export const DropdownMenu = component((props) => {
+    const triggerId = uid("dropdown-trigger");
+    const contentId = uid("dropdown-content");
+    const state = controllable({
+        value: props.open,
+        initial: props.defaultOpen ?? false,
+        onChange: props.onOpenChange,
+    });
+    // Set by the trigger's key handler just before opening, and consumed by
+    // `onOpened`. The panel does not exist yet at the moment of the keypress, so
+    // the intent has to survive the gap.
+    let enterOnOpen = false;
+    let unwire = null;
+    function close() {
+        state.set(false);
+    }
+    floatingSurface({
+        anchor: () => document.getElementById(triggerId),
+        open: () => state.current(),
+        onClose: close,
+        placement: props.placement ?? "bottom-start",
+        offset: 4,
+        content: () => menuPanel({
+            id: contentId,
+            entries: props.entries,
+            onCloseAll: close,
+            labelledBy: triggerId,
+            class: read(props.contentClass),
+        }),
+        onOpened: (panel) => {
+            const enterItems = enterOnOpen;
+            enterOnOpen = false;
+            unwire = wireMenu(panel, {
+                onCloseAll: close,
+                autoFocusFirst: enterItems,
+            });
+            // The panel takes focus only when no item did — it needs to hold focus
+            // so Escape and the arrows reach it rather than the page behind, but
+            // focusing it unconditionally steals focus straight back from the item
+            // `autoFocusFirst` just landed on, and opening with the keyboard would
+            // never reach the first entry.
+            if (!enterItems)
+                panel.focus({ preventScroll: true });
+        },
+        onClosed: () => {
+            unwire?.();
+            unwire = null;
+        },
+    });
+    function onTriggerKeyDown(event) {
+        if (event.key !== "ArrowDown" && event.key !== "Enter" && event.key !== " ")
+            return;
+        event.preventDefault();
+        enterOnOpen = true;
+        state.set(true);
+    }
+    return html `<button
+		type="button"
+		data-slot="dropdown-menu-trigger"
+		id="${triggerId}"
+		aria-haspopup="menu"
+		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())}"
+		@keydown="${onTriggerKeyDown}"
+	>${slot(props.trigger)}</button>`;
+});

package/dist/organisms/Form.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Form — binding between Aurora's form controller and nebula's field markup.
+ *
+ * shadcn's Form is a set of adapters over `react-hook-form`, and none of that
+ * layer is needed here: Aurora already ships `form()`, a reactive controller
+ * with values, per-field errors, touched state, submit-in-flight and optional
+ * rune/zod-shaped validation. Reimplementing it would be a second source of
+ * truth for the same thing.
+ *
+ * So this file is only the join. It wires one field to one `Field` plus one
+ * control, and takes care of the three things that otherwise get forgotten:
+ * `aria-invalid` when the field has an error, `aria-describedby` pointing at
+ * the error element, and marking the field touched on blur so an error appears
+ * after leaving a field rather than while typing in it.
+ *
+ *   const login = form({
+ *     initial: { email: "", password: "" },
+ *     validate: (values) => (values.email === "" ? { email: "Required" } : {}),
+ *     submit: (values) => http.post("/login", values),
+ *   })
+ *
+ *   Form({
+ *     form: login,
+ *     children: [
+ *       TextField({ bind: bind(login, "email"), label: "Email", type: "email" }),
+ *       TextField({ bind: bind(login, "password"), label: "Password", type: "password" }),
+ *       SubmitButton({ form: login, label: "Sign in" }),
+ *     ],
+ *   })
+ */
+import type { Form as AuroraForm, FormField } from "@c9up/aurora";
+import { html } from "@c9up/aurora";
+import type { Child, Slot } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+/**
+ * One field, with a setter that already knows which key it writes to.
+ *
+ * This shape exists so the input components are not generic over the form.
+ * Inside a function generic in `T`, TypeScript cannot prove a `string` is
+ * assignable to `T[K]`, and the usual escape is a cast. `bind()` is called at
+ * a *concrete* call site, where `K` is a literal and `T[K]` resolves to a real
+ * type — so `bind(login, "email")` is a `FieldBinding<string>` and handing it
+ * to a numeric input is a compile error rather than a runtime surprise.
+ */
+export interface FieldBinding<V> {
+    readonly name: string;
+    readonly field: FormField<V>;
+    set(value: V): void;
+}
+/** Bind one key of a form. Call it at the field's own call site. */
+export declare function bind<T, K extends keyof T & string>(form: AuroraForm<T>, name: K): FieldBinding<T[K]>;
+export interface FormProps<T> {
+    form: AuroraForm<T>;
+    children?: Slot;
+    class?: Reactive<string>;
+}
+/**
+ * The `<form>` element itself.
+ *
+ * `novalidate` on purpose. The browser's own validation bubbles cannot be
+ * styled, appear one at a time, and vanish on scroll — and they would fire
+ * before the controller's validation ever runs, so the user would see two
+ * different error presentations for the same field.
+ */
+export declare function Form<T>(props: FormProps<T>): ReturnType<typeof html>;
+interface FieldShellProps {
+    bind: FieldBinding<string>;
+    label: Child;
+    description?: Child;
+    placeholder?: string;
+    required?: boolean;
+    disabled?: Reactive<boolean>;
+}
+export interface TextFieldProps extends FieldShellProps {
+    type?: string;
+    autocomplete?: string;
+}
+/**
+ * A labelled text input bound to one field.
+ *
+ * The error is shown only once the field has been touched, which is what stops
+ * a pristine form opening with "Required" under every empty box.
+ *
+ * When errors actually appear is Aurora's decision, not this file's, and it is
+ * worth knowing: `form()` populates them on `validate()` — which `handleSubmit`
+ * calls — and clears a field's error as soon as it is written to. So the
+ * sequence is: submit, see every problem at once, and watch each one disappear
+ * as it is fixed. Typing into an untouched field does not raise an error, and
+ * `markTouched` on blur does not validate; it only lifts the gate for an error
+ * that validation has already found.
+ */
+export declare const TextField: (props?: TextFieldProps | undefined) => import("@c9up/aurora").TemplateResult;
+export interface TextAreaFieldProps extends FieldShellProps {
+    rows?: number;
+}
+/** The same, with a multi-line control. */
+export declare const TextAreaField: (props?: TextAreaFieldProps | undefined) => import("@c9up/aurora").TemplateResult;
+export interface SubmitButtonProps<T> {
+    form: AuroraForm<T>;
+    label: Child;
+    /** Replaces the label while the submit is in flight. */
+    pendingLabel?: Child;
+    class?: Reactive<string>;
+}
+/**
+ * A submit button that disables itself while the submit is in flight.
+ *
+ * Disabled on `submitting` only — never on `!valid`. A submit button that is
+ * dead until the form is correct gives the user nothing to press and no
+ * explanation; pressing it and seeing every error at once is how a form tells
+ * you what is wrong.
+ */
+export declare function SubmitButton<T>(props: SubmitButtonProps<T>): ReturnType<typeof html>;
+export {};

package/dist/organisms/Form.js

@@ -0,0 +1,151 @@
+/**
+ * Form — binding between Aurora's form controller and nebula's field markup.
+ *
+ * shadcn's Form is a set of adapters over `react-hook-form`, and none of that
+ * layer is needed here: Aurora already ships `form()`, a reactive controller
+ * with values, per-field errors, touched state, submit-in-flight and optional
+ * rune/zod-shaped validation. Reimplementing it would be a second source of
+ * truth for the same thing.
+ *
+ * So this file is only the join. It wires one field to one `Field` plus one
+ * control, and takes care of the three things that otherwise get forgotten:
+ * `aria-invalid` when the field has an error, `aria-describedby` pointing at
+ * the error element, and marking the field touched on blur so an error appears
+ * after leaving a field rather than while typing in it.
+ *
+ *   const login = form({
+ *     initial: { email: "", password: "" },
+ *     validate: (values) => (values.email === "" ? { email: "Required" } : {}),
+ *     submit: (values) => http.post("/login", values),
+ *   })
+ *
+ *   Form({
+ *     form: login,
+ *     children: [
+ *       TextField({ bind: bind(login, "email"), label: "Email", type: "email" }),
+ *       TextField({ bind: bind(login, "password"), label: "Password", type: "password" }),
+ *       SubmitButton({ form: login, label: "Sign in" }),
+ *     ],
+ *   })
+ */
+import { component, html } from "@c9up/aurora";
+import { Button } from "../atoms/Button.js";
+import { Input } from "../atoms/Input.js";
+import { Spinner } from "../atoms/Spinner.js";
+import { Textarea } from "../atoms/Textarea.js";
+import { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { read } from "../lib/props.js";
+import { Field, fieldIds } from "../molecules/Field.js";
+/** Bind one key of a form. Call it at the field's own call site. */
+export function bind(form, name) {
+    return {
+        name,
+        field: form.field(name),
+        set: (value) => form.set(name, value),
+    };
+}
+/**
+ * The `<form>` element itself.
+ *
+ * `novalidate` on purpose. The browser's own validation bubbles cannot be
+ * styled, appear one at a time, and vanish on scroll — and they would fire
+ * before the controller's validation ever runs, so the user would see two
+ * different error presentations for the same field.
+ */
+export function Form(props) {
+    return html `<form
+		data-slot="form"
+		novalidate
+		class="${() => cn("flex flex-col gap-6", read(props.class))}"
+		@submit="${(event) => {
+        void props.form.handleSubmit(event);
+    }}"
+	>${slot(props.children)}</form>`;
+}
+/**
+ * A labelled text input bound to one field.
+ *
+ * The error is shown only once the field has been touched, which is what stops
+ * a pristine form opening with "Required" under every empty box.
+ *
+ * When errors actually appear is Aurora's decision, not this file's, and it is
+ * worth knowing: `form()` populates them on `validate()` — which `handleSubmit`
+ * calls — and clears a field's error as soon as it is written to. So the
+ * sequence is: submit, see every problem at once, and watch each one disappear
+ * as it is fixed. Typing into an untouched field does not raise an error, and
+ * `markTouched` on blur does not validate; it only lifts the gate for an error
+ * that validation has already found.
+ */
+export const TextField = component((props) => {
+    const ids = fieldIds();
+    const { field, set, name } = props.bind;
+    const visibleError = () => field.touched() ? (field.error() ?? undefined) : undefined;
+    return Field({
+        ids,
+        label: props.label,
+        description: props.description,
+        error: visibleError,
+        required: props.required,
+        disabled: props.disabled,
+        children: Input({
+            id: ids.control,
+            name,
+            type: props.type ?? "text",
+            placeholder: props.placeholder,
+            autocomplete: props.autocomplete,
+            required: props.required,
+            disabled: props.disabled,
+            invalid: () => visibleError() !== undefined,
+            describedBy: ids.describedBy,
+            value: () => field.value(),
+            onInput: set,
+            onBlur: () => field.markTouched(),
+        }),
+    });
+});
+/** The same, with a multi-line control. */
+export const TextAreaField = component((props) => {
+    const ids = fieldIds();
+    const { field, set, name } = props.bind;
+    const visibleError = () => field.touched() ? (field.error() ?? undefined) : undefined;
+    return Field({
+        ids,
+        label: props.label,
+        description: props.description,
+        error: visibleError,
+        required: props.required,
+        disabled: props.disabled,
+        children: Textarea({
+            id: ids.control,
+            name,
+            rows: props.rows,
+            placeholder: props.placeholder,
+            required: props.required,
+            disabled: props.disabled,
+            invalid: () => visibleError() !== undefined,
+            describedBy: ids.describedBy,
+            value: () => field.value(),
+            onInput: set,
+            onBlur: () => field.markTouched(),
+        }),
+    });
+});
+/**
+ * A submit button that disables itself while the submit is in flight.
+ *
+ * Disabled on `submitting` only — never on `!valid`. A submit button that is
+ * dead until the form is correct gives the user nothing to press and no
+ * explanation; pressing it and seeing every error at once is how a form tells
+ * you what is wrong.
+ */
+export function SubmitButton(props) {
+    return Button({
+        type: "submit",
+        disabled: () => props.form.submitting(),
+        class: props.class,
+        children: () => props.form.submitting()
+            ? [Spinner({ class: "mr-2" }), props.pendingLabel ?? props.label]
+            : props.label,
+    });
+}

package/dist/organisms/HoverCard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * HoverCard — a rich preview shown on hover.
+ *
+ * A Tooltip carries a phrase; a HoverCard carries content — an avatar, a
+ * summary, a link. That difference drives every behavioural difference between
+ * the two.
+ *
+ * It opens more slowly, because the payload is heavier and a card flashing
+ * past is worse than a tooltip flashing past. It closes more slowly, because
+ * the user is expected to move the pointer *into* it. And it is never the only
+ * route to what it contains: pointer-only content is unreachable by keyboard
+ * and touch, so a hover card must preview something a click already reaches.
+ *
+ * `role="dialog"` rather than `tooltip`, since it holds interactive content —
+ * a tooltip's contents are announced as a description, which is wrong for
+ * something containing a link.
+ */
+import { type Slot } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+import type { Placement } from "../primitives/floating.js";
+export interface HoverCardProps {
+    trigger?: Slot;
+    children?: Slot;
+    placement?: Placement;
+    openDelay?: number;
+    closeDelay?: number;
+    class?: Reactive<string>;
+    contentClass?: Reactive<string>;
+}
+export declare const HoverCard: (props?: HoverCardProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/HoverCard.js

@@ -0,0 +1,68 @@
+/**
+ * HoverCard — a rich preview shown on hover.
+ *
+ * A Tooltip carries a phrase; a HoverCard carries content — an avatar, a
+ * summary, a link. That difference drives every behavioural difference between
+ * the two.
+ *
+ * It opens more slowly, because the payload is heavier and a card flashing
+ * past is worse than a tooltip flashing past. It closes more slowly, because
+ * the user is expected to move the pointer *into* it. And it is never the only
+ * route to what it contains: pointer-only content is unreachable by keyboard
+ * and touch, so a hover card must preview something a click already reaches.
+ *
+ * `role="dialog"` rather than `tooltip`, since it holds interactive content —
+ * a tooltip's contents are announced as a description, which is wrong for
+ * something containing a link.
+ */
+import { component, html, onUnmount, signal } 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 { floatingSurface } from "../primitives/floatingSurface.js";
+const OPEN_DELAY_MS = 700;
+const CLOSE_DELAY_MS = 300;
+export const HoverCard = component((props) => {
+    const triggerId = uid("hover-card-trigger");
+    const contentId = uid("hover-card-content");
+    const open = signal(false);
+    let timer;
+    function clear() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function schedule(next, delay) {
+        clear();
+        timer = setTimeout(() => open(next), delay);
+    }
+    onUnmount(clear);
+    floatingSurface({
+        anchor: () => document.getElementById(triggerId),
+        open: () => open(),
+        onClose: () => {
+            clear();
+            open(false);
+        },
+        placement: props.placement ?? "bottom",
+        offset: 8,
+        content: () => html `<div
+				data-slot="hover-card-content"
+				id="${contentId}"
+				role="dialog"
+				aria-labelledby="${triggerId}"
+				class="${cn("bg-popover text-popover-foreground z-50 w-64 rounded-md border p-4 shadow-md outline-none", zoomInOut, read(props.contentClass))}"
+				@pointerenter="${clear}"
+				@pointerleave="${() => schedule(false, props.closeDelay ?? CLOSE_DELAY_MS)}"
+			>${slot(props.children)}</div>`,
+    });
+    return html `<span
+		data-slot="hover-card-trigger"
+		id="${triggerId}"
+		class="${() => cn("inline-flex", read(props.class))}"
+		@pointerenter="${() => schedule(true, props.openDelay ?? OPEN_DELAY_MS)}"
+		@pointerleave="${() => schedule(false, props.closeDelay ?? CLOSE_DELAY_MS)}"
+	>${slot(props.trigger)}</span>`;
+});

package/dist/organisms/Menubar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Menubar — an application menu bar.
+ *
+ * A row of menu buttons where at most one menu is open. The behaviour that
+ * makes it a menubar rather than a row of independent dropdowns is the
+ * handover: once a menu is open, moving the pointer onto a neighbouring button
+ * switches to it without a click, and ArrowLeft/ArrowRight do the same from
+ * the keyboard. That is how every desktop menu bar behaves, and a row of
+ * dropdowns that each need their own click is the thing users notice.
+ *
+ * One `floatingSurface` for the bar, not one per menu. The open menu is an
+ * index, so switching moves the same surface to a new anchor instead of
+ * closing one and opening another — which would flash, and would lose the
+ * exit animation into the entry animation.
+ */
+import type { Child } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+import { type MenuEntry } from "../primitives/menu.js";
+export interface MenubarMenu {
+    label: Child;
+    entries: readonly MenuEntry[];
+    disabled?: boolean;
+}
+export interface MenubarProps {
+    menus: readonly MenubarMenu[];
+    class?: Reactive<string>;
+}
+export declare const Menubar: (props?: MenubarProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/Menubar.js

@@ -0,0 +1,147 @@
+/**
+ * Menubar — an application menu bar.
+ *
+ * A row of menu buttons where at most one menu is open. The behaviour that
+ * makes it a menubar rather than a row of independent dropdowns is the
+ * handover: once a menu is open, moving the pointer onto a neighbouring button
+ * switches to it without a click, and ArrowLeft/ArrowRight do the same from
+ * the keyboard. That is how every desktop menu bar behaves, and a row of
+ * dropdowns that each need their own click is the thing users notice.
+ *
+ * One `floatingSurface` for the bar, not one per menu. The open menu is an
+ * index, so switching moves the same surface to a new anchor instead of
+ * closing one and opening another — which would flash, and would lose the
+ * exit animation into the entry animation.
+ */
+import { component, html, signal } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { read } from "../lib/props.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { menuPanel, wireMenu } from "../primitives/menu.js";
+export const Menubar = component((props) => {
+    const contentId = uid("menubar-content");
+    const triggerIds = props.menus.map(() => uid("menubar-trigger"));
+    /** Index of the open menu, or `-1`. */
+    const openIndex = signal(-1);
+    let unwire = null;
+    let focusFirstOnOpen = false;
+    function close() {
+        openIndex(-1);
+    }
+    function openAt(index, withKeyboard) {
+        if (props.menus[index]?.disabled === true)
+            return;
+        focusFirstOnOpen = withKeyboard;
+        openIndex(index);
+    }
+    function move(delta) {
+        const count = props.menus.length;
+        if (count === 0)
+            return;
+        const from = openIndex();
+        if (from === -1)
+            return;
+        openAt((from + delta + count) % count, true);
+    }
+    floatingSurface({
+        anchor: () => {
+            const id = triggerIds[openIndex()];
+            return id === undefined ? null : document.getElementById(id);
+        },
+        open: () => openIndex() !== -1,
+        onClose: close,
+        placement: "bottom-start",
+        offset: 4,
+        content: () => menuPanel({
+            id: contentId,
+            entries: props.menus[openIndex()]?.entries ?? [],
+            onCloseAll: close,
+            labelledBy: triggerIds[openIndex()],
+        }),
+        onOpened: (panel) => {
+            const enterItems = focusFirstOnOpen;
+            focusFirstOnOpen = false;
+            unwire = wireMenu(panel, {
+                onCloseAll: close,
+                autoFocusFirst: enterItems,
+            });
+            // Only when no item took focus. Focusing the panel unconditionally
+            // steals focus back from the item `autoFocusFirst` just landed on, and
+            // opening a menu with the keyboard would never reach its first entry.
+            if (!enterItems)
+                panel.focus({ preventScroll: true });
+            // Left/right walk the bar from inside the open panel. `menu.js` claims
+            // ArrowLeft for closing a submenu and stops propagation when it does,
+            // so this only fires at the top level.
+            panel.addEventListener("keydown", onPanelKeyDown);
+        },
+        onClosed: () => {
+            unwire?.();
+            unwire = null;
+        },
+    });
+    function onPanelKeyDown(event) {
+        if (event.key === "ArrowRight") {
+            event.preventDefault();
+            move(1);
+        }
+        else if (event.key === "ArrowLeft") {
+            event.preventDefault();
+            move(-1);
+        }
+    }
+    return html `<div
+		data-slot="menubar"
+		role="menubar"
+		class="${() => cn("bg-background flex h-9 items-center gap-1 rounded-md border p-1 shadow-xs", read(props.class))}"
+	>
+		${props.menus.map((menu, index) => renderTrigger(menu, index))}
+	</div>`;
+    function renderTrigger(menu, index) {
+        return html `<button
+			type="button"
+			role="menuitem"
+			data-slot="menubar-trigger"
+			id="${triggerIds[index]}"
+			aria-haspopup="menu"
+			aria-expanded="${() => (openIndex() === index ? "true" : "false")}"
+			aria-controls="${() => (openIndex() === index ? contentId : undefined)}"
+			data-state="${() => (openIndex() === index ? "open" : "closed")}"
+			?disabled="${menu.disabled === true}"
+			class="focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex select-none items-center rounded-sm px-2 py-1 text-sm font-medium outline-none disabled:pointer-events-none disabled:opacity-50"
+			@click="${() => (openIndex() === index ? close() : openAt(index, false))}"
+			@pointerenter="${() => {
+            // Hover switches menus only while one is already open — otherwise
+            // the bar would spring menus at a pointer merely passing over it.
+            if (openIndex() !== -1)
+                openAt(index, false);
+        }}"
+			@keydown="${(event) => {
+            if (event.key === "ArrowDown" ||
+                event.key === "Enter" ||
+                event.key === " ") {
+                event.preventDefault();
+                openAt(index, true);
+            }
+            else if (event.key === "ArrowRight") {
+                event.preventDefault();
+                focusTrigger(index + 1);
+            }
+            else if (event.key === "ArrowLeft") {
+                event.preventDefault();
+                focusTrigger(index - 1);
+            }
+        }}"
+		>${menu.label}</button>`;
+    }
+    function focusTrigger(index) {
+        const count = props.menus.length;
+        if (count === 0)
+            return;
+        const id = triggerIds[(index + count) % count];
+        if (id === undefined)
+            return;
+        document.getElementById(id)?.focus({ preventScroll: true });
+    }
+});

package/dist/organisms/MessageScroller.d.ts

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