@c9up/nebula 0.1.0

package/src/molecules/Bubble.ts

@@ -0,0 +1,134 @@
+/**
+ * Bubble — conversational content in a speech bubble.
+ *
+ * Alignment is **logical**, not physical: `align: "end"` uses `ms-auto` and an
+ * inline-end tail, so the same message sits on the right in English and on the
+ * left in Arabic without the caller knowing which. Writing `ml-auto` here would
+ * have been shorter and would have put every outgoing message on the wrong side
+ * of an RTL conversation.
+ *
+ * The collapse is `line-clamp` plus a toggle rather than a max-height with
+ * overflow hidden. `line-clamp` cuts at a line boundary and adds the ellipsis
+ * itself; a height cut slices through the middle of a line of text, which is
+ * the tell of a hand-rolled version.
+ *
+ * Reactions are a `<ul>`, and each one is a toggle button with
+ * `aria-pressed` — not a decorative span. A reaction the user can add is a
+ * control, and a count nobody can operate belongs in the message text.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { type Slot, slot } from "../lib/children.js";
+import { cva, type VariantProps } from "../lib/cva.js";
+import { type Reactive, read } from "../lib/props.js";
+
+export const bubbleVariants = cva(
+	"relative w-fit max-w-[min(36rem,80%)] rounded-lg px-3 py-2 text-sm break-words",
+	{
+		variants: {
+			variant: {
+				default: "bg-muted text-foreground",
+				accent: "bg-primary text-primary-foreground",
+				outline: "border bg-background text-foreground",
+				ghost: "text-foreground px-0",
+			},
+			align: {
+				// Logical margins, so the side follows the writing direction.
+				start: "me-auto",
+				end: "ms-auto",
+			},
+		},
+		defaultVariants: { variant: "default", align: "start" },
+	},
+);
+
+export type BubbleVariants = VariantProps<typeof bubbleVariants>;
+
+export interface BubbleReaction {
+	emoji: string;
+	count?: number;
+	/** The current user has reacted with this one. */
+	active?: boolean;
+	onToggle?: () => void;
+}
+
+export interface BubbleProps {
+	children?: Slot;
+	variant?: Reactive<BubbleVariants["variant"]>;
+	align?: Reactive<BubbleVariants["align"]>;
+	reactions?: readonly BubbleReaction[];
+	/** Clamp long content behind a toggle. */
+	collapsible?: boolean;
+	/** Lines shown while collapsed. Default `6`. */
+	collapsedLines?: number;
+	/** Label for the expand toggle. Default `"Show more"`. */
+	expandLabel?: string;
+	collapseLabel?: string;
+	class?: Reactive<string>;
+}
+
+export const Bubble = component<BubbleProps>((props) => {
+	const expanded = signal(false);
+	const lines = props.collapsedLines ?? 6;
+
+	const bodyClass = (): string => {
+		if (props.collapsible !== true || expanded()) return "";
+		// An arbitrary value, because line-clamp-N only exists for 1–6 and the
+		// caller can ask for any depth.
+		return `line-clamp-[${lines}]`;
+	};
+
+	return html`<div
+		data-slot="bubble"
+		class="${() =>
+			bubbleVariants({
+				variant: read(props.variant),
+				align: read(props.align),
+				class: read(props.class),
+			})}"
+	>
+		<div data-slot="bubble-content" class="${bodyClass}">${slot(props.children)}</div>
+		${
+			props.collapsible !== true
+				? null
+				: html`<button
+					type="button"
+					data-slot="bubble-toggle"
+					aria-expanded="${() => (expanded() ? "true" : "false")}"
+					class="mt-1 text-xs font-medium underline-offset-4 hover:underline"
+					@click="${() => expanded(!expanded())}"
+				>${() =>
+					expanded()
+						? (props.collapseLabel ?? "Show less")
+						: (props.expandLabel ?? "Show more")}</button>`
+		}
+		${
+			props.reactions === undefined || props.reactions.length === 0
+				? null
+				: html`<ul data-slot="bubble-reactions" class="mt-1.5 flex flex-wrap gap-1">
+					${props.reactions.map(renderReaction)}
+				</ul>`
+		}
+	</div>`;
+});
+
+function renderReaction(reaction: BubbleReaction): Child {
+	return html`<li>
+		<button
+			type="button"
+			data-slot="bubble-reaction"
+			aria-pressed="${reaction.active === true ? "true" : "false"}"
+			aria-label="${`${reaction.emoji}${reaction.count === undefined ? "" : `, ${reaction.count}`}`}"
+			class="bg-background/60 hover:bg-background aria-pressed:border-primary aria-pressed:bg-primary/10 flex h-6 items-center gap-1 rounded-full border px-1.5 text-xs transition-colors"
+			@click="${() => reaction.onToggle?.()}"
+		>
+			<span aria-hidden="true">${reaction.emoji}</span>
+			${
+				reaction.count === undefined
+					? null
+					: html`<span class="tabular-nums">${reaction.count}</span>`
+			}
+		</button>
+	</li>`;
+}

package/src/molecules/ButtonGroup.ts

@@ -0,0 +1,55 @@
+/**
+ * ButtonGroup — buttons welded into one control.
+ *
+ * `role="group"` with a label, so a screen reader announces the set before its
+ * members rather than three unrelated buttons in a row.
+ *
+ * The rounding and border collapsing are done with `:first-child` /
+ * `:last-child` selectors on the group rather than props on each button. That
+ * is what lets the members stay ordinary `Button` calls — adding one does not
+ * mean re-deciding which button is now on the end.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { type Reactive, read } from "../lib/props.js";
+import { styledDiv } from "../lib/styled.js";
+
+export interface ButtonGroupProps {
+	children?: Slot;
+	orientation?: "horizontal" | "vertical";
+	/** Announced before the group's contents. */
+	label?: string;
+	class?: Reactive<string>;
+}
+
+export const ButtonGroup = component<ButtonGroupProps>((props) => {
+	const vertical = props.orientation === "vertical";
+
+	return html`<div
+		data-slot="button-group"
+		role="group"
+		aria-label="${props.label}"
+		data-orientation="${vertical ? "vertical" : "horizontal"}"
+		class="${() =>
+			cn(
+				"flex w-fit items-stretch",
+				vertical
+					? "flex-col [&>*]:rounded-none [&>*:first-child]:rounded-t-md [&>*:last-child]:rounded-b-md [&>*:not(:first-child)]:-mt-px"
+					: "[&>*]:rounded-none [&>*:first-child]:rounded-l-md [&>*:last-child]:rounded-r-md [&>*:not(:first-child)]:-ml-px",
+				"[&>*]:focus-visible:z-10 [&>*]:focus:z-10",
+				read(props.class),
+			)}"
+	>${slot(props.children)}</div>`;
+});
+
+export const ButtonGroupSeparator = styledDiv(
+	"button-group-separator",
+	"bg-input relative !m-0 self-stretch w-px",
+);
+
+export const ButtonGroupText = styledDiv(
+	"button-group-text",
+	"bg-muted text-muted-foreground flex items-center gap-2 border px-4 text-sm font-medium",
+);

package/src/molecules/Card.ts

@@ -0,0 +1,42 @@
+/**
+ * Card — a bordered surface holding one unit of content.
+ *
+ * Seven parts, all presentational. The only one worth explaining is
+ * `CardAction`: it is grid-positioned into the header's second column so a
+ * button or menu trigger sits opposite the title without the header needing a
+ * flex wrapper and a spacer. The header switches to two columns only when an
+ * action is present, via `has-data-[slot=card-action]`.
+ */
+
+import { styledDiv } from "../lib/styled.js";
+
+export type { StyledProps as CardProps } from "../lib/styled.js";
+
+export const Card = styledDiv(
+	"card",
+	"bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm",
+);
+
+export const CardHeader = styledDiv(
+	"card-header",
+	"@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-1.5 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6",
+);
+
+export const CardTitle = styledDiv("card-title", "leading-none font-semibold");
+
+export const CardDescription = styledDiv(
+	"card-description",
+	"text-muted-foreground text-sm",
+);
+
+export const CardAction = styledDiv(
+	"card-action",
+	"col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+);
+
+export const CardContent = styledDiv("card-content", "px-6");
+
+export const CardFooter = styledDiv(
+	"card-footer",
+	"flex items-center px-6 [.border-t]:pt-6",
+);

package/src/molecules/Collapsible.ts

@@ -0,0 +1,89 @@
+/**
+ * Collapsible — a trigger that shows and hides a panel.
+ *
+ * Two things differ from Radix, both deliberate.
+ *
+ * **The API.** Radix composes through React context: `<Collapsible>` publishes
+ * state that `<CollapsibleTrigger>` and `<CollapsibleContent>` read from
+ * anywhere below it. Aurora has no context, and the usual workarounds — a
+ * factory returning bound parts, or threading a handle through props — trade a
+ * real problem for a clumsier one. So the parts are props: `trigger` and
+ * `children`. The rendered markup is identical to shadcn's; only the call
+ * shape changes.
+ *
+ * **The animation.** Radix measures the content and publishes its height as
+ * `--radix-collapsible-content-height` for the keyframes to interpolate,
+ * because `height: auto` is not animatable. A CSS grid whose single row goes
+ * from `0fr` to `1fr` animates the same transition with no measurement, no
+ * resize observer, and no stale height when the content changes while closed.
+ *
+ * The closed panel stays in the DOM — that is what makes the transition
+ * possible — so it is marked `inert`. Without it the panel keeps its tab stops
+ * and stays in the accessibility tree, and a keyboard user tabs into content
+ * that is not on screen.
+ */
+
+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 { type Reactive, read, readOr } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+
+export interface CollapsibleProps {
+	/** The clickable summary. Rendered inside a button. */
+	trigger?: Slot;
+	/** The panel revealed when open. */
+	children?: Slot;
+	open?: Reactive<boolean>;
+	defaultOpen?: boolean;
+	disabled?: Reactive<boolean>;
+	onOpenChange?: (open: boolean) => void;
+	class?: Reactive<string>;
+	triggerClass?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const Collapsible = component<CollapsibleProps>((props) => {
+	const state = controllable<boolean>({
+		value: props.open,
+		initial: props.defaultOpen ?? false,
+		onChange: props.onOpenChange,
+	});
+
+	const contentId = uid("collapsible-content");
+	const triggerId = uid("collapsible-trigger");
+
+	const toggle = (): void => {
+		if (readOr(props.disabled, false)) return;
+		state.set(!state.current());
+	};
+
+	return html`<div
+		data-slot="collapsible"
+		data-state="${() => (state.current() ? "open" : "closed")}"
+		class="${() => cn("flex flex-col", read(props.class))}"
+	>
+		<button
+			type="button"
+			data-slot="collapsible-trigger"
+			id="${triggerId}"
+			aria-expanded="${() => (state.current() ? "true" : "false")}"
+			aria-controls="${contentId}"
+			?disabled="${() => readOr(props.disabled, false)}"
+			class="${() => cn("flex items-center justify-between gap-2 outline-none disabled:opacity-50", read(props.triggerClass))}"
+			@click="${toggle}"
+		>${slot(props.trigger)}</button>
+		<div
+			data-slot="collapsible-content"
+			id="${contentId}"
+			role="region"
+			aria-labelledby="${triggerId}"
+			?inert="${() => !state.current()}"
+			class="grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none"
+			style="${() => `grid-template-rows: ${state.current() ? "1fr" : "0fr"}`}"
+		>
+			<div class="${() => cn("overflow-hidden", read(props.contentClass))}">${slot(props.children)}</div>
+		</div>
+	</div>`;
+});

package/src/molecules/Empty.ts

@@ -0,0 +1,43 @@
+/**
+ * Empty — the placeholder for a list, table or panel with nothing in it.
+ *
+ * Worth having as a component rather than ad-hoc markup, because an empty
+ * state is where an app most often falls back to a bare "No results" and
+ * leaves the user without a next step. The parts push towards the useful
+ * shape: an icon, a title, a sentence of explanation, and something to do
+ * about it.
+ */
+
+import { styledDiv } from "../lib/styled.js";
+
+export type { StyledProps as EmptyProps } from "../lib/styled.js";
+
+export const Empty = styledDiv(
+	"empty",
+	"flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border-dashed p-6 text-center text-balance md:p-12",
+);
+
+export const EmptyHeader = styledDiv(
+	"empty-header",
+	"flex max-w-sm flex-col items-center gap-2 text-center",
+);
+
+export const EmptyMedia = styledDiv(
+	"empty-media",
+	"bg-muted text-muted-foreground mb-2 flex size-10 shrink-0 items-center justify-center rounded-lg [&_svg:not([class*='size-'])]:size-5",
+);
+
+export const EmptyTitle = styledDiv(
+	"empty-title",
+	"text-lg font-medium tracking-tight",
+);
+
+export const EmptyDescription = styledDiv(
+	"empty-description",
+	"text-muted-foreground text-sm/relaxed [&>a]:underline [&>a]:underline-offset-4",
+);
+
+export const EmptyContent = styledDiv(
+	"empty-content",
+	"flex w-full max-w-sm min-w-0 flex-col items-center gap-4 text-sm text-balance",
+);

package/src/molecules/Field.ts

@@ -0,0 +1,131 @@
+/**
+ * Field — a form control with its label, hint and error.
+ *
+ * The reason this exists rather than each form writing the four elements by
+ * hand is the wiring. A control must point at its description and its error
+ * with `aria-describedby`, and at its own label with `for`/`id`. Done by hand
+ * that is three ids to invent and keep in step per field, and the failure is
+ * silent — a sighted user sees the error, a screen-reader user does not.
+ *
+ * `Field` mints the ids and returns them, so the control gets them by
+ * destructuring rather than by convention:
+ *
+ *   const email = fieldIds()
+ *   Field({
+ *     ids: email,
+ *     label: "Email",
+ *     error: () => errors.email,
+ *     children: Input({ id: email.control, describedBy: email.describedBy, invalid: … }),
+ *   })
+ *
+ * The error slot is reactive and empty-tolerant: passing `() => errors.email`
+ * renders nothing until there is something to render, so a field does not
+ * reserve a blank line for an error that has not happened.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { Label } from "../atoms/Label.js";
+import type { Child, Slot } from "../lib/children.js";
+import { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+import { styledDiv } from "../lib/styled.js";
+
+export interface FieldIds {
+	/** Put on the control. The label's `for` points here. */
+	readonly control: string;
+	readonly label: string;
+	readonly description: string;
+	readonly error: string;
+	/** Ready-made `aria-describedby` naming both the description and the error. */
+	readonly describedBy: string;
+}
+
+/** Mint the id set for one field. Call once, in the component that owns it. */
+export function fieldIds(): FieldIds {
+	const control = uid("field");
+	const description = `${control}-description`;
+	const error = `${control}-error`;
+	return {
+		control,
+		label: `${control}-label`,
+		description,
+		error,
+		// Both are named unconditionally. A screen reader skips an id that
+		// resolves to nothing, so listing an absent error is harmless — whereas
+		// recomputing the attribute when an error appears means the control has to
+		// re-render, which Aurora does not do.
+		describedBy: `${description} ${error}`,
+	};
+}
+
+export interface FieldProps {
+	ids: FieldIds;
+	label?: Child;
+	/** The control itself. */
+	children?: Slot;
+	/** Static help text under the control. */
+	description?: Child;
+	/** Validation message. Reactive — renders nothing while absent. */
+	error?: Reactive<string | undefined>;
+	required?: boolean;
+	disabled?: Reactive<boolean>;
+	orientation?: "vertical" | "horizontal";
+	class?: Reactive<string>;
+}
+
+export const Field = component<FieldProps>((props) => {
+	const horizontal = props.orientation === "horizontal";
+
+	return html`<div
+		data-slot="field"
+		data-disabled="${() => (read(props.disabled) === true ? "true" : undefined)}"
+		class="${() =>
+			cn(
+				"group flex gap-2",
+				horizontal ? "flex-row items-center justify-between" : "flex-col",
+				read(props.class),
+			)}"
+	>
+		${
+			props.label === undefined
+				? null
+				: Label({
+						for: props.ids.control,
+						id: props.ids.label,
+						children: html`${props.label}${
+							props.required === true
+								? html`<span aria-hidden="true" class="text-destructive">*</span>`
+								: null
+						}`,
+					})
+		}
+		${slot(props.children)}
+		${
+			props.description === undefined
+				? null
+				: html`<p
+					data-slot="field-description"
+					id="${props.ids.description}"
+					class="text-muted-foreground text-sm"
+				>${props.description}</p>`
+		}
+		<p
+			data-slot="field-error"
+			id="${props.ids.error}"
+			role="alert"
+			class="text-destructive text-sm empty:hidden"
+		>${() => read(props.error) ?? ""}</p>
+	</div>`;
+});
+
+export const FieldGroup = styledDiv(
+	"field-group",
+	"flex w-full flex-col gap-6",
+);
+
+export const FieldSeparator = styledDiv(
+	"field-separator",
+	"bg-border h-px w-full",
+);

package/src/molecules/InputGroup.ts

@@ -0,0 +1,62 @@
+/**
+ * InputGroup — an input with something attached to it.
+ *
+ * A currency prefix, a `.com` suffix, a search icon, a clear button. The group
+ * carries the border and the focus ring; the input inside is stripped bare.
+ *
+ * `focus-within:` is what moves the ring onto the wrapper, so focusing the
+ * input lights up the whole control including the addons. Styling the input's
+ * own `:focus-visible` would draw a ring around the middle third of a control
+ * that visually reads as one box.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { type Reactive, read } from "../lib/props.js";
+import { styledDiv } from "../lib/styled.js";
+
+export interface InputGroupProps {
+	children?: Slot;
+	/** Before the input — an icon or a static prefix. */
+	leading?: Slot;
+	/** After the input — a unit, a button, a spinner. */
+	trailing?: Slot;
+	invalid?: Reactive<boolean>;
+	disabled?: Reactive<boolean>;
+	class?: Reactive<string>;
+}
+
+/**
+ * Strip the inner input of its own chrome.
+ *
+ * Exported so a caller passing a plain `<input>` rather than nebula's `Input`
+ * can apply it too — without this the input draws a second border inside the
+ * group's, which is the one way this component visibly goes wrong.
+ */
+export const inputGroupControlClasses =
+	"flex-1 border-0 bg-transparent px-0 shadow-none outline-none focus-visible:border-0 focus-visible:ring-0 disabled:opacity-100";
+
+export const InputGroup = component<InputGroupProps>((props) => {
+	return html`<div
+		data-slot="input-group"
+		data-disabled="${() => (read(props.disabled) === true ? "" : undefined)}"
+		aria-invalid="${() => (read(props.invalid) === true ? "true" : undefined)}"
+		class="${() =>
+			cn(
+				"border-input dark:bg-input/30 flex h-9 w-full min-w-0 items-center gap-2 rounded-md border bg-transparent px-3 py-1 text-sm shadow-xs transition-[color,box-shadow]",
+				"focus-within:border-ring focus-within:ring-ring/50 focus-within:ring-[3px]",
+				"aria-invalid:border-destructive aria-invalid:ring-destructive/20",
+				"data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+				`[&_input]:${inputGroupControlClasses.split(" ").join(" [&_input]:")}`,
+				read(props.class),
+			)}"
+	>
+		${slot(props.leading)}${slot(props.children)}${slot(props.trailing)}
+	</div>`;
+});
+
+export const InputGroupAddon = styledDiv(
+	"input-group-addon",
+	"text-muted-foreground flex shrink-0 items-center gap-2 [&_svg:not([class*='size-'])]:size-4",
+);