@c9up/nebula 0.1.0

package/src/configure.ts

@@ -0,0 +1,127 @@
+/**
+ * `ream configure @c9up/nebula` — the house setup hook.
+ *
+ * Every package in this workspace is installed the same way: `ream add <pkg>`
+ * installs it and dispatches to this hook, which writes the files the package
+ * needs through the codemods the CLI hands in. nebula follows that rather than
+ * shipping a setup command of its own — one way to install a ream package, not
+ * one per package.
+ *
+ * Pass the adapter through the installer:
+ *
+ *     ream add @c9up/nebula --adapter unocss
+ *
+ * There is no provider to register. A provider binds runtime services into the
+ * container, and nebula has none: its components are client-side templates and
+ * its adapters run at build time. An empty provider would be ceremony.
+ */
+
+import { adapterFor, isAdapterName } from "./adapters/index.js";
+import { type AdapterName, resolveConfig } from "./config.js";
+
+/**
+ * The subset of the CLI's codemods this hook uses.
+ *
+ * Declared structurally rather than imported: `@c9up/ream-cli` is a Rust
+ * binary that injects this object at runtime, so there is no type to import
+ * and a dependency on the CLI would be a lie. Same shape the other packages'
+ * hooks declare.
+ */
+interface Codemods {
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+/** Flags forwarded from `ream add` / `ream configure`, as the CLI encodes them. */
+type Flags = Record<string, string[] | undefined>;
+
+function configFile(adapter: AdapterName): string {
+	return `import { defineConfig } from '@c9up/nebula'
+
+/**
+ * nebula — component registry and style adapter.
+ *
+ * Changing \`adapter\` and re-running \`ream configure @c9up/nebula\` swaps the
+ * CSS engine. The components themselves are untouched: all three adapters
+ * consume the same class names.
+ */
+export default defineConfig({
+  adapter: '${adapter}',
+  paths: {
+    // Where \`ream nebula:add\` copies components. The atomic layers live under it.
+    components: 'resources/pages',
+    css: 'resources/css/app.css',
+    output: 'public/app.css',
+  },
+})
+`;
+}
+
+/**
+ * Read the adapter from the forwarded flags.
+ *
+ * An unrecognised name is refused rather than silently defaulted: a typo in
+ * `--adapter tailwnid` would otherwise write a Tailwind setup and leave the
+ * user hunting for why their UnoCSS config never appeared.
+ */
+function adapterFrom(flags: Flags): AdapterName {
+	const requested = flags.adapter?.[0];
+	if (requested === undefined) return "tailwind";
+	if (!isAdapterName(requested)) {
+		throw new Error(
+			`[@c9up/nebula] unknown adapter "${requested}" — one of tailwind, unocss, css`,
+		);
+	}
+	return requested;
+}
+
+export async function configure(
+	codemods: Codemods,
+	flags: Flags = {},
+): Promise<void> {
+	const name = adapterFrom(flags);
+	const adapter = adapterFor(name);
+	const config = resolveConfig({ adapter: name });
+
+	await codemods.writeFile("config/nebula.ts", configFile(name));
+	for (const file of adapter.files(config)) {
+		await codemods.writeFile(file.path, file.contents);
+	}
+
+	// On stderr, and never installed on the user's behalf. nebula declares no
+	// CSS dependency at all — the app owns its build tooling, and a UI library
+	// quietly adding one to someone's dependency tree is how a tree gets away
+	// from them.
+	const lines = [
+		"",
+		"[@c9up/nebula] configured with the " + name + " adapter.",
+	];
+
+	if (adapter.packages.length > 0) {
+		lines.push(
+			"  Install the engine yourself:",
+			`    pnpm add -D ${adapter.packages.join(" ")}`,
+		);
+	}
+
+	const commands = adapter.commands(config);
+	if (commands === null) {
+		lines.push("  No build step — the stylesheet ships prebuilt.");
+	} else {
+		lines.push(
+			"  Register the build in config/assets.ts:",
+			`    build:     ${commands.build.command} ${commands.build.args.join(" ")}`,
+			`    devServer: ${commands.dev.command} ${commands.dev.args.join(" ")}`,
+		);
+	}
+
+	lines.push(
+		"  Then add components with `ream nebula:add button card` — they are copied",
+		"  into your project and are yours to edit.",
+		"",
+	);
+	process.stderr.write(lines.join("\n"));
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @c9up/nebula — shadcn/ui, ported to Aurora, organised as atomic design.
+ *
+ * Three things are worth knowing before reading further.
+ *
+ * **It adds no runtime dependency.** shadcn stands on Radix, `clsx`,
+ * `tailwind-merge`, `class-variance-authority`, `lucide-react`,
+ * `@floating-ui/dom`, `cmdk`, `sonner`, `recharts`, `@tanstack/react-table` and
+ * `react-day-picker`. None of them are React-agnostic, and the workspace had
+ * already made the call that `cn` was worth writing by hand rather than
+ * installing two packages. So `cva` is reimplemented, the Radix behaviour layer
+ * lives in `primitives/`, the placement engine is `primitives/floating.ts`, the
+ * icons are inlined, and the date maths is `Date` and `Intl`.
+ *
+ * **Compound components take data, not children.** shadcn composes through
+ * React context — `<Tabs><TabsList><TabsTrigger>`. Aurora has no context, and
+ * the workarounds are worse than the problem, so those components take an
+ * `items` array and named slots. The rendered markup is unchanged, which means
+ * shadcn's CSS and its examples still read across.
+ *
+ * **The atomic layer is a property of the component.** An atom renders its own
+ * markup and composes nothing from nebula; a molecule assembles atoms or owns
+ * state spanning several elements; an organism portals, traps focus, or floats;
+ * a template is page layout. `nebula add button` knows Button is an atom and
+ * puts it in `atoms/` without being told.
+ *
+ * Import from the layer barrels — `@c9up/nebula/atoms` — or take the source
+ * with `nebula add`, which is the mode this library is really built for.
+ */
+
+export * from "./adapters/index.js";
+export * from "./atoms/index.js";
+export {
+	type AdapterName,
+	defaultPaths,
+	defineConfig,
+	isLayer,
+	type Layer,
+	layers,
+	type NebulaConfig,
+	type NebulaPaths,
+	type ResolvedNebulaConfig,
+	resolveConfig,
+} from "./config.js";
+export { type Child, type Slot, slot } from "./lib/children.js";
+export * from "./lib/icons.js";
+export * from "./lib/index.js";
+export { fadeInOut, slideFrom, zoomInOut } from "./lib/motion.js";
+export { type StyledProps, styledDiv, styledSpan } from "./lib/styled.js";
+export * from "./molecules/index.js";
+export * from "./organisms/index.js";
+export * from "./primitives/index.js";
+export * from "./templates/index.js";

package/src/lib/children.ts

@@ -0,0 +1,43 @@
+/**
+ * What a component accepts as content.
+ *
+ * Aurora's renderer already handles the whole union in a text slot: nested
+ * templates, raw nodes, primitives, and arrays of any of those, with `null`,
+ * `undefined` and `false` rendering nothing. `Child` names that union so a
+ * component's props say what they mean instead of falling back to `unknown`,
+ * and so passing a value the renderer would silently drop is a type error at
+ * the call site rather than a blank space on the page.
+ *
+ * `Slot` is the reactive form. Content that changes must arrive as an accessor
+ * — Aurora never re-renders a component, so a plain value read at setup is
+ * frozen for the lifetime of the node.
+ */
+
+import type { TemplateResult } from "@c9up/aurora";
+import type { Reactive } from "./props.js";
+
+export type Child =
+	| TemplateResult
+	| Node
+	| string
+	| number
+	| boolean
+	| null
+	| undefined
+	| readonly Child[];
+
+/** Content that may be constant or recomputed. */
+export type Slot = Reactive<Child>;
+
+/**
+ * Bind content into a template so it stays live.
+ *
+ * Returns the accessor form unchanged and wraps a constant in one. Templates
+ * should always interpolate `${slot(props.children)}`: handing the renderer a
+ * bare value works until a sibling prop makes the content dynamic, at which
+ * point the binding quietly stops updating and nothing points at why.
+ */
+export function slot(content: Slot | undefined): () => Child {
+	if (content === undefined) return () => null;
+	return typeof content === "function" ? content : () => content;
+}

package/src/lib/cn.ts

@@ -0,0 +1,14 @@
+/**
+ * Class composition — re-exported from Aurora rather than reimplemented here.
+ *
+ * `@c9up/aurora` already ships `clsx` + `tailwind-merge` written from scratch
+ * with no dependencies (its `src/cn.ts`, targeting the Tailwind v4 utility
+ * set). nebula is a peer of aurora, never a fork of it: one class-merge
+ * implementation in the workspace, one place to fix a mis-grouped utility.
+ *
+ * This module exists so every nebula component imports `./lib/cn.js` and not
+ * `@c9up/aurora` directly. That indirection is what lets the registry rewrite
+ * a single import line when it copies a component into a host app.
+ */
+
+export { type ClassValue, clsx, cn, twMerge } from "@c9up/aurora";

package/src/lib/cva.ts

@@ -0,0 +1,249 @@
+/**
+ * `cva` — class-variance-authority, reimplemented from scratch with ZERO
+ * dependencies.
+ *
+ * shadcn/ui is built on two class helpers: `cn` (clsx + tailwind-merge) and
+ * `cva` (variant → class-list resolution). Aurora already ships `cn` written
+ * from scratch in `@c9up/aurora` (src/cn.ts), so this file is the other half.
+ * Between them, nebula pulls in no runtime dependency at all.
+ *
+ *   const button = cva(
+ *     "inline-flex items-center rounded-md text-sm font-medium",
+ *     {
+ *       variants: {
+ *         variant: { default: "bg-primary text-primary-foreground",
+ *                    ghost:   "hover:bg-accent" },
+ *         size:    { sm: "h-8 px-3", lg: "h-10 px-8" },
+ *       },
+ *       compoundVariants: [
+ *         { variant: "ghost", size: "sm", class: "px-2" },
+ *       ],
+ *       defaultVariants: { variant: "default", size: "sm" },
+ *     },
+ *   )
+ *
+ *   button()                                  // base + default variants
+ *   button({ variant: "ghost" })              // ghost, still size sm
+ *   button({ size: "lg", class: "w-full" })   // caller classes win
+ *
+ * Differences from the upstream package, both deliberate:
+ *
+ * 1. The result runs through Aurora's `cn`, so a variant that sets `px-2`
+ *    genuinely overrides a base `px-3` instead of emitting both and leaving
+ *    the winner to CSS source order. Upstream cva only concatenates; every
+ *    real shadcn component then wraps the call in `cn(...)` to get here
+ *    anyway. Doing it inside removes that ceremony from ~50 components.
+ * 2. `class` and `className` are both accepted. Aurora templates use `class`;
+ *    `className` exists only so code pasted over from a React codebase keeps
+ *    working.
+ */
+
+import { type ClassValue, cn } from "./cn.js";
+
+/**
+ * One variant axis: a variant name mapped to the classes each of its values
+ * contributes. `{ size: { sm: "h-8", lg: "h-10" } }` is one axis with two
+ * values.
+ */
+export type VariantShape = Record<string, Record<string, ClassValue>>;
+
+/**
+ * The value accepted for one axis.
+ *
+ * An axis keyed by `"true"` / `"false"` is a boolean axis — the caller passes
+ * a real `boolean`, not the string. That mapping is what lets
+ * `{ disabled: { true: "opacity-50" } }` be driven by `disabled: true`.
+ */
+type VariantValue<T> =
+	Extract<keyof T, string> extends "true" | "false"
+		? boolean
+		: Extract<keyof T, string>;
+
+/** Props selecting one value per axis. Every axis is optional. */
+export type VariantSelection<V extends VariantShape> = {
+	[K in keyof V]?: VariantValue<V[K]> | null | undefined;
+};
+
+/**
+ * A compound rule matches when EVERY axis it names matches. An axis may list
+ * several accepted values, in which case any of them matches.
+ */
+export type CompoundVariant<V extends VariantShape> = {
+	[K in keyof V]?: VariantValue<V[K]> | ReadonlyArray<VariantValue<V[K]>>;
+} & ClassOverrides;
+
+/** Extra keys every generated function accepts on top of its own axes. */
+export interface ClassOverrides {
+	class?: ClassValue;
+	className?: ClassValue;
+}
+
+export interface VariantConfig<V extends VariantShape> {
+	variants?: V;
+	compoundVariants?: ReadonlyArray<CompoundVariant<V>>;
+	defaultVariants?: VariantSelection<V>;
+}
+
+/** The props a `cva()` result accepts, minus the two class escape hatches. */
+export type VariantProps<F> = F extends (props?: infer P) => string
+	? Omit<NonNullable<P>, "class" | "className">
+	: never;
+
+/** A compound rule flattened into "conditions + classes it contributes". */
+interface CompoundRule {
+	/** Each entry is one axis and the set of values that satisfy it. */
+	readonly conditions: ReadonlyArray<readonly [string, readonly string[]]>;
+	readonly classes: readonly ClassValue[];
+}
+
+/**
+ * Build a variant resolver. Returns a function from a variant selection to a
+ * single, conflict-resolved class string.
+ */
+export function cva<V extends VariantShape>(
+	base?: ClassValue,
+	config?: VariantConfig<V>,
+): (props?: VariantSelection<V> & ClassOverrides) => string {
+	// Widening to the non-generic shapes up front is what keeps the body free
+	// of casts: `V` cannot be indexed by a plain `string`, `VariantShape` can.
+	const variants: VariantShape = config?.variants ?? {};
+	const axes = Object.keys(variants);
+	const defaults = toValueMap(config?.defaultVariants);
+	const compounds = normaliseCompounds(config?.compoundVariants);
+
+	return (props?: VariantSelection<V> & ClassOverrides): string => {
+		const selection = selectionFor(defaults, props);
+		const parts: ClassValue[] = [base];
+
+		for (const axis of axes) {
+			const chosen = selection[axis];
+			if (chosen === undefined) continue;
+			// Indexed by the *string form* of the value, so a boolean axis reaches
+			// its `"true"` / `"false"` entry here.
+			const classesForValue = variants[axis]?.[chosen];
+			if (classesForValue !== undefined) parts.push(classesForValue);
+		}
+
+		for (const rule of compounds) {
+			if (satisfies(rule, selection)) parts.push(...rule.classes);
+		}
+
+		// Caller overrides come last so they win the tailwind-merge pass.
+		parts.push(props?.class, props?.className);
+		return cn(parts);
+	};
+}
+
+/**
+ * Read an object's own enumerable entries with honest `unknown` values.
+ *
+ * Variant selections are generic mapped types, which TypeScript will not let
+ * you index with a plain `string`. Funnelling every read through one helper
+ * typed `object → [string, unknown][]` gets the values out without a cast at
+ * any call site, and forces each one to narrow before use.
+ */
+function entriesOf(source: object): ReadonlyArray<readonly [string, unknown]> {
+	return Object.entries(source);
+}
+
+/**
+ * Collapse a selection object down to `axis → string value`.
+ *
+ * Normalising to strings here is what keeps boolean-axis handling in a single
+ * place: `true` becomes `"true"`, and every lookup downstream — variant
+ * classes and compound matching alike — is a plain string compare.
+ */
+function toValueMap(source: object | undefined): Record<string, string> {
+	const out: Record<string, string> = {};
+	if (!source) return out;
+	for (const [key, value] of entriesOf(source)) {
+		if (isClassKey(key)) continue;
+		if (value === undefined || value === null) continue;
+		out[key] = String(value);
+	}
+	return out;
+}
+
+/**
+ * Merge caller props over the defaults.
+ *
+ * An omitted axis (or an explicit `undefined`) keeps its default; an explicit
+ * `null` clears it, which is how upstream cva lets a caller opt out of a
+ * default variant entirely.
+ */
+function selectionFor(
+	defaults: Record<string, string>,
+	props: object | undefined,
+): Record<string, string | undefined> {
+	const selection: Record<string, string | undefined> = { ...defaults };
+	if (!props) return selection;
+
+	for (const [key, value] of entriesOf(props)) {
+		if (isClassKey(key)) continue;
+		if (value === undefined) continue;
+		selection[key] = value === null ? undefined : String(value);
+	}
+	return selection;
+}
+
+/** Flatten compound rules once, at construction, rather than on every call. */
+function normaliseCompounds<V extends VariantShape>(
+	compounds: ReadonlyArray<CompoundVariant<V>> | undefined,
+): readonly CompoundRule[] {
+	if (!compounds) return [];
+
+	const out: CompoundRule[] = [];
+	for (const rule of compounds) {
+		const conditions: Array<readonly [string, readonly string[]]> = [];
+		const classes: ClassValue[] = [];
+
+		for (const [key, value] of entriesOf(rule)) {
+			if (isClassKey(key)) {
+				if (isClassValue(value)) classes.push(value);
+				continue;
+			}
+			if (value === undefined || value === null) continue;
+			const accepted = Array.isArray(value)
+				? value.map((one) => String(one))
+				: [String(value)];
+			conditions.push([key, accepted]);
+		}
+		out.push({ conditions, classes });
+	}
+	return out;
+}
+
+/** Does every condition of a compound rule hold for this selection? */
+function satisfies(
+	rule: CompoundRule,
+	selection: Record<string, string | undefined>,
+): boolean {
+	for (const [axis, accepted] of rule.conditions) {
+		const actual = selection[axis];
+		if (actual === undefined) return false;
+		if (!accepted.includes(actual)) return false;
+	}
+	return true;
+}
+
+function isClassKey(key: string): boolean {
+	return key === "class" || key === "className";
+}
+
+/**
+ * Narrow a compound rule's `class` / `className` back to `ClassValue`.
+ *
+ * The value arrives as `unknown` from `entriesOf`; `ClassValue` covers every
+ * shape `cn` accepts, so anything that is not a rejected primitive passes
+ * through untouched and `cn` does the rest of the work.
+ */
+function isClassValue(value: unknown): value is ClassValue {
+	return (
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean" ||
+		value === null ||
+		value === undefined ||
+		typeof value === "object"
+	);
+}

package/src/lib/icons.ts

@@ -0,0 +1,138 @@
+/**
+ * Inline icons.
+ *
+ * shadcn/ui pulls every glyph from `lucide-react`. nebula cannot: it is a
+ * React package, and taking a dependency for fifteen paths would undo the
+ * point of writing `cn` and `cva` by hand.
+ *
+ * So the glyphs the component set actually needs are inlined here, traced from
+ * Lucide's own 24×24 grid so they sit correctly next to Lucide icons in an app
+ * that also uses the real thing. Nothing else is added — this is not an icon
+ * library, and an app wanting a hundred more should install one and pass the
+ * markup in as content.
+ *
+ * `currentColor` throughout and no hardcoded size: an icon inherits the text
+ * colour of whatever it sits in, and the `[&_svg]:size-4` rules on Button and
+ * friends set the size from the component. That is what lets the same icon
+ * work in a button, a menu item and a badge without a variant each.
+ */
+
+import { html, type TemplateResult } from "@c9up/aurora";
+
+export interface IconProps {
+	class?: string;
+	/** Icons are decorative by default; give a label to expose one to a reader. */
+	label?: string;
+}
+
+/**
+ * Wrap path data in a Lucide-shaped `<svg>`.
+ *
+ * `aria-hidden` unless labelled, because an icon beside its own text label is
+ * noise to a screen reader — it reads the glyph's name and then the text. The
+ * exceptions are icon-only controls, which pass a label.
+ */
+function svg(body: TemplateResult, props: IconProps = {}): TemplateResult {
+	return html`<svg
+		xmlns="http://www.w3.org/2000/svg"
+		viewBox="0 0 24 24"
+		fill="none"
+		stroke="currentColor"
+		stroke-width="2"
+		stroke-linecap="round"
+		stroke-linejoin="round"
+		class="${props.class}"
+		aria-hidden="${props.label === undefined ? "true" : undefined}"
+		aria-label="${props.label}"
+		role="${props.label === undefined ? undefined : "img"}"
+	>${body}</svg>`;
+}
+
+export const CheckIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="M20 6 9 17l-5-5" />`, props);
+
+export const MinusIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="M5 12h14" />`, props);
+
+export const XIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="M18 6 6 18" /><path d="m6 6 12 12" />`, props);
+
+export const ChevronDownIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="m6 9 6 6 6-6" />`, props);
+
+export const ChevronUpIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="m18 15-6-6-6 6" />`, props);
+
+export const ChevronLeftIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="m15 18-6-6 6-6" />`, props);
+
+export const ChevronRightIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="m9 18 6-6-6-6" />`, props);
+
+export const ChevronsUpDownIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" />`, props);
+
+export const SearchIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />`, props);
+
+export const CircleIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<circle cx="12" cy="12" r="10" />`, props);
+
+/** Filled dot — the selected marker inside a radio. */
+export const DotIcon = (props?: IconProps): TemplateResult =>
+	svg(
+		html`<circle cx="12" cy="12" r="4" fill="currentColor" stroke="none" />`,
+		props,
+	);
+
+export const MoreHorizontalIcon = (props?: IconProps): TemplateResult =>
+	svg(
+		html`<circle cx="12" cy="12" r="1" /><circle cx="19" cy="12" r="1" /><circle
+				cx="5"
+				cy="12"
+				r="1"
+			/>`,
+		props,
+	);
+
+export const ArrowLeftIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="m12 19-7-7 7-7" /><path d="M19 12H5" />`, props);
+
+export const ArrowRightIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="M5 12h14" /><path d="m12 5 7 7-7 7" />`, props);
+
+export const CalendarIcon = (props?: IconProps): TemplateResult =>
+	svg(
+		html`<path d="M8 2v4" /><path d="M16 2v4" /><rect
+				width="18"
+				height="18"
+				x="3"
+				y="4"
+				rx="2"
+			/><path d="M3 10h18" />`,
+		props,
+	);
+
+export const PanelLeftIcon = (props?: IconProps): TemplateResult =>
+	svg(
+		html`<rect width="18" height="18" x="3" y="3" rx="2" /><path d="M9 3v18" />`,
+		props,
+	);
+
+export const GripVerticalIcon = (props?: IconProps): TemplateResult =>
+	svg(
+		html`<circle cx="9" cy="12" r="1" /><circle cx="9" cy="5" r="1" /><circle
+				cx="9"
+				cy="19"
+				r="1"
+			/><circle cx="15" cy="12" r="1" /><circle cx="15" cy="5" r="1" /><circle
+				cx="15"
+				cy="19"
+				r="1"
+			/>`,
+		props,
+	);
+
+/** The arc Lucide uses for `loader-circle`; spun by the Spinner's animation. */
+export const LoaderIcon = (props?: IconProps): TemplateResult =>
+	svg(html`<path d="M21 12a9 9 0 1 1-6.219-8.56" />`, props);

package/src/lib/id.ts

@@ -0,0 +1,44 @@
+/**
+ * Stable element ids.
+ *
+ * Radix leans on React's `useId` to wire ARIA relationships — a trigger's
+ * `aria-controls` has to name the id its content actually carries. Aurora has
+ * no equivalent, and nebula needs one for two reasons: the ARIA wiring above,
+ * and element lookup. Aurora templates have no `ref` directive, so a component
+ * that must measure or focus a node finds it by id inside `onMount()`.
+ *
+ * The counter is monotonic per module instance, so the sequence depends only
+ * on the order components are constructed in. That order is identical on the
+ * server and in the browser for the same tree, which is what makes the ids
+ * survive hydration — the same property React's `useId` relies on.
+ *
+ * `resetIds()` exists for the server: a long-lived process renders many
+ * requests, and without a reset the counter climbs forever and every response
+ * ships different markup, defeating any HTML cache. Call it once per render
+ * pass, before the tree is built.
+ */
+
+let counter = 0;
+
+/** Mint an id unique within this render pass. */
+export function uid(prefix = "nebula"): string {
+	counter += 1;
+	return `${prefix}-${counter}`;
+}
+
+/** Restart the sequence. Call once per SSR render, before building the tree. */
+export function resetIds(): void {
+	counter = 0;
+}
+
+/**
+ * Look an element up by the id a component minted for it.
+ *
+ * Returns `null` off the DOM (SSR) or before mount rather than throwing, so
+ * callers can run the same code in both environments. Every consumer inside
+ * nebula is in `onMount`, where the node is live.
+ */
+export function byId(id: string): HTMLElement | null {
+	if (typeof document === "undefined") return null;
+	return document.getElementById(id);
+}

package/src/lib/index.ts

@@ -0,0 +1,21 @@
+/**
+ * The two class helpers shadcn is built on, plus the prop plumbing Aurora
+ * needs in their place.
+ *
+ * `cn` comes from aurora (clsx + tailwind-merge, already written from scratch
+ * there); `cva` is reimplemented here. Between them nebula adds no runtime
+ * dependency at all — the same call the workspace made for `cn` itself.
+ */
+
+export { type ClassValue, clsx, cn, twMerge } from "./cn.js";
+export {
+	type ClassOverrides,
+	type CompoundVariant,
+	cva,
+	type VariantConfig,
+	type VariantProps,
+	type VariantSelection,
+	type VariantShape,
+} from "./cva.js";
+export { byId, resetIds, uid } from "./id.js";
+export { accessor, callHandler, type Reactive, read, readOr } from "./props.js";