@c9up/nebula 0.1.0

package/src/atoms/Spinner.ts

@@ -0,0 +1,28 @@
+/**
+ * Spinner — an indeterminate activity indicator.
+ *
+ * `role="status"` with a visually hidden label, so a screen reader announces
+ * that something is loading. A bare spinning glyph is invisible to a reader
+ * and the user is left with silence where a sighted user sees motion.
+ *
+ * `motion-reduce:animate-none` stops the rotation for users who asked the
+ * system to reduce motion. The glyph stays, so the indicator does not vanish.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { LoaderIcon } from "../lib/icons.js";
+import { type Reactive, read, readOr } from "../lib/props.js";
+
+export interface SpinnerProps {
+	/** Announced to assistive technology. Defaults to `"Loading"`. */
+	label?: Reactive<string>;
+	class?: Reactive<string>;
+}
+
+export const Spinner = component<SpinnerProps>((props) => {
+	return html`<span data-slot="spinner" role="status" class="inline-flex">
+		${LoaderIcon({ class: cn("size-4 animate-spin motion-reduce:animate-none", read(props.class)) })}
+		<span class="sr-only">${() => readOr(props.label, "Loading")}</span>
+	</span>`;
+});

package/src/atoms/Switch.ts

@@ -0,0 +1,56 @@
+/**
+ * Switch — an on/off toggle that applies immediately.
+ *
+ * Same native-input approach as Checkbox, with `role="switch"` so assistive
+ * technology announces "on/off" rather than "checked". The distinction is not
+ * cosmetic: a checkbox is a choice you confirm by submitting, a switch is a
+ * setting that takes effect the moment you flip it.
+ *
+ * The thumb is a sibling translated by `peer-checked:`, not a pseudo-element,
+ * so the travel distance stays expressible in utility classes and a user can
+ * retune the size without leaving the class string.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { accessor, type Reactive, read } from "../lib/props.js";
+
+export const switchTrackClasses =
+	"peer absolute inset-0 size-full appearance-none rounded-full border border-transparent bg-input shadow-xs outline-none transition-colors dark:bg-input/80 checked:bg-primary focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50";
+
+export interface SwitchProps {
+	id?: string;
+	name?: string;
+	checked?: Reactive<boolean>;
+	disabled?: Reactive<boolean>;
+	label?: Reactive<string | undefined>;
+	class?: Reactive<string>;
+	onCheckedChange?: (checked: boolean, event: Event) => void;
+}
+
+function inputChecked(event: Event): boolean {
+	const target = event.target;
+	return target instanceof HTMLInputElement ? target.checked : false;
+}
+
+export const Switch = component<SwitchProps>((props) => {
+	return html`<span
+		data-slot="switch"
+		class="${() => cn("relative inline-flex h-[1.15rem] w-8 shrink-0 items-center", read(props.class))}"
+	>
+		<input
+			type="checkbox"
+			role="switch"
+			id="${props.id}"
+			name="${props.name}"
+			aria-label="${accessor(props.label, undefined)}"
+			?disabled="${accessor(props.disabled, false)}"
+			.checked="${accessor(props.checked, false)}"
+			class="${switchTrackClasses}"
+			@change="${(event: Event) => props.onCheckedChange?.(inputChecked(event), event)}"
+		/>
+		<span
+			class="pointer-events-none ml-px block size-4 rounded-full bg-background shadow-lg ring-0 transition-transform peer-checked:translate-x-[calc(100%-2px)] dark:peer-checked:bg-primary-foreground"
+		></span>
+	</span>`;
+});

package/src/atoms/Textarea.ts

@@ -0,0 +1,58 @@
+/**
+ * Textarea — a multi-line text field.
+ *
+ * Mirrors `Input` deliberately, down to the prop names: a form field should
+ * not need a different shape because it grew a second line. The `field-sizing-
+ * content` utility is the one addition — it lets the browser grow the box with
+ * its content, which used to require a resize observer and a scroll-height
+ * measurement on every keystroke.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { accessor, type Reactive, read } from "../lib/props.js";
+
+export const textareaClasses =
+	"border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm";
+
+export interface TextareaProps {
+	id?: string;
+	name?: string;
+	value?: Reactive<string>;
+	placeholder?: Reactive<string>;
+	rows?: Reactive<number>;
+	disabled?: Reactive<boolean>;
+	readonly?: Reactive<boolean>;
+	required?: Reactive<boolean>;
+	invalid?: Reactive<boolean>;
+	describedBy?: Reactive<string | undefined>;
+	class?: Reactive<string>;
+	onInput?: (value: string, event: Event) => void;
+	onChange?: (value: string, event: Event) => void;
+	onBlur?: (event: FocusEvent) => void;
+}
+
+function inputValue(event: Event): string {
+	const target = event.target;
+	return target instanceof HTMLTextAreaElement ? target.value : "";
+}
+
+export const Textarea = component<TextareaProps>((props) => {
+	return html`<textarea
+		data-slot="textarea"
+		id="${props.id}"
+		name="${props.name}"
+		placeholder="${accessor(props.placeholder, undefined)}"
+		rows="${accessor(props.rows, undefined)}"
+		aria-invalid="${() => (read(props.invalid) === true ? "true" : undefined)}"
+		aria-describedby="${accessor(props.describedBy, undefined)}"
+		?disabled="${accessor(props.disabled, false)}"
+		?readonly="${accessor(props.readonly, false)}"
+		?required="${accessor(props.required, false)}"
+		.value="${accessor(props.value, "")}"
+		class="${() => cn(textareaClasses, read(props.class))}"
+		@input="${(event: Event) => props.onInput?.(inputValue(event), event)}"
+		@change="${(event: Event) => props.onChange?.(inputValue(event), event)}"
+		@blur="${props.onBlur}"
+	></textarea>`;
+});

package/src/atoms/Toggle.ts

@@ -0,0 +1,67 @@
+/**
+ * Toggle — a button that stays pressed.
+ *
+ * `aria-pressed` rather than a checkbox: the control is a button whose effect
+ * applies immediately (bold, mute, filter on), not a value being collected for
+ * submission. Screen readers announce it as "toggle button, pressed", which is
+ * what the user needs to hear.
+ *
+ * The variants are exported for ToggleGroup, which reuses them so a grouped
+ * toggle and a standalone one cannot drift apart.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { type Slot, slot } from "../lib/children.js";
+import { cva, type VariantProps } from "../lib/cva.js";
+import { accessor, type Reactive, read, readOr } from "../lib/props.js";
+
+export const toggleVariants = cva(
+	"inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 aria-pressed:bg-accent aria-pressed:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 whitespace-nowrap",
+	{
+		variants: {
+			variant: {
+				default: "bg-transparent",
+				outline:
+					"border border-input bg-transparent shadow-xs hover:bg-accent hover:text-accent-foreground",
+			},
+			size: {
+				default: "h-9 min-w-9 px-2",
+				sm: "h-8 min-w-8 px-1.5",
+				lg: "h-10 min-w-10 px-2.5",
+			},
+		},
+		defaultVariants: { variant: "default", size: "default" },
+	},
+);
+
+export type ToggleVariants = VariantProps<typeof toggleVariants>;
+
+export interface ToggleProps {
+	children?: Slot;
+	pressed?: Reactive<boolean>;
+	variant?: Reactive<ToggleVariants["variant"]>;
+	size?: Reactive<ToggleVariants["size"]>;
+	disabled?: Reactive<boolean>;
+	label?: Reactive<string | undefined>;
+	value?: string;
+	class?: Reactive<string>;
+	onPressedChange?: (pressed: boolean) => void;
+}
+
+export const Toggle = component<ToggleProps>((props) => {
+	return html`<button
+		type="button"
+		data-slot="toggle"
+		data-value="${props.value}"
+		aria-pressed="${() => (readOr(props.pressed, false) ? "true" : "false")}"
+		aria-label="${accessor(props.label, undefined)}"
+		?disabled="${accessor(props.disabled, false)}"
+		class="${() =>
+			toggleVariants({
+				variant: read(props.variant),
+				size: read(props.size),
+				class: read(props.class),
+			})}"
+		@click="${() => props.onPressedChange?.(!readOr(props.pressed, false))}"
+	>${slot(props.children)}</button>`;
+});

package/src/atoms/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Atoms — one element, no nebula components inside.
+ *
+ * The dividing line the whole library is organised on: an atom renders its own
+ * markup and composes nothing from nebula. It may hold local state (Avatar
+ * tracks whether its image loaded) and it may be interactive (Checkbox,
+ * Slider), but the moment it reaches for another nebula component it belongs a
+ * layer up.
+ *
+ * Applied strictly, that rule puts things where a reader expects them. Card is
+ * a molecule despite being simpler than Slider, because it assembles parts.
+ * Slider is an atom despite being interactive, because it is one input.
+ */
+
+export { AspectRatio, type AspectRatioProps } from "./AspectRatio.js";
+export { Avatar, type AvatarProps } from "./Avatar.js";
+export {
+	Badge,
+	type BadgeProps,
+	type BadgeVariants,
+	badgeVariants,
+} from "./Badge.js";
+export {
+	Button,
+	type ButtonProps,
+	type ButtonVariants,
+	buttonVariants,
+} from "./Button.js";
+export { Checkbox, type CheckboxProps, checkboxClasses } from "./Checkbox.js";
+export { Input, type InputProps, inputClasses } from "./Input.js";
+export { Kbd, type KbdProps } from "./Kbd.js";
+export { Label, type LabelProps, labelClasses } from "./Label.js";
+export {
+	Marker,
+	type MarkerProps,
+	type MarkerVariants,
+	markerVariants,
+} from "./Marker.js";
+export {
+	NativeSelect,
+	type NativeSelectOption,
+	type NativeSelectProps,
+	nativeSelectClasses,
+} from "./NativeSelect.js";
+export { Progress, type ProgressProps } from "./Progress.js";
+export {
+	ScrollArea,
+	type ScrollAreaProps,
+	scrollAreaClasses,
+} from "./ScrollArea.js";
+export { Separator, type SeparatorProps } from "./Separator.js";
+export { Skeleton, type SkeletonProps } from "./Skeleton.js";
+export { Slider, type SliderProps, sliderClasses } from "./Slider.js";
+export { Spinner, type SpinnerProps } from "./Spinner.js";
+export { Switch, type SwitchProps, switchTrackClasses } from "./Switch.js";
+export { Textarea, type TextareaProps, textareaClasses } from "./Textarea.js";
+export {
+	Toggle,
+	type ToggleProps,
+	type ToggleVariants,
+	toggleVariants,
+} from "./Toggle.js";

package/src/cli/add.ts

@@ -0,0 +1,126 @@
+/**
+ * `nebula add <component…>` — copy component sources into the project.
+ *
+ * The point of the registry model: what lands in the project is the source,
+ * and from then on it is the user's. No version, no upgrade path, no wrapper
+ * to fight when a design needs one class changed.
+ *
+ * Copies mirror the package's own layout, so `../lib/cn.js` resolves in the
+ * project exactly as it does here and no import is ever rewritten. Rewriting
+ * is where a copy-the-source CLI accumulates its edge cases; preserving the
+ * shape means there are none.
+ *
+ * Existing files are never overwritten without `--force`. The whole premise is
+ * that the user edits these, and a second `nebula add button` after a week of
+ * changes must not silently discard them.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { defaultPaths, type Language, type NebulaPaths } from "../config.js";
+import { loadRegistry, packageRoot, resolveItems } from "./registry.js";
+
+export interface AddOptions {
+	cwd: string;
+	names: readonly string[];
+	paths?: Partial<NebulaPaths>;
+	/** Overrides both the detected language and the configured one. */
+	language?: Language;
+	force?: boolean;
+	/** Print what would happen and write nothing. */
+	dryRun?: boolean;
+}
+
+export interface AddResult {
+	written: string[];
+	skipped: string[];
+	/** What was actually copied, so the caller can report it. */
+	language: Language;
+}
+
+/**
+ * Which language the project's component tree is written in.
+ *
+ * Read from what is already there rather than configured, because the answer
+ * is sitting on disk and a mismatched setting produces files the project
+ * cannot load. A tree holding `.ts` gets TypeScript; anything else — including
+ * a tree of `.js`, which is what an unbuilt Aurora app has — gets JavaScript.
+ * `undefined` when the directory does not exist yet.
+ */
+export function detectLanguage(componentsRoot: string): Language | undefined {
+	if (!existsSync(componentsRoot)) return undefined;
+
+	const stack = [componentsRoot];
+	let sawJs = false;
+	while (stack.length > 0) {
+		const dir = stack.pop();
+		if (dir === undefined) continue;
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (entry.name === "node_modules") continue;
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+				continue;
+			}
+			if (entry.name.endsWith(".d.ts")) continue;
+			if (entry.name.endsWith(".ts")) return "ts";
+			if (entry.name.endsWith(".js")) sawJs = true;
+		}
+	}
+	return sawJs ? "js" : undefined;
+}
+
+export function add(options: AddOptions): AddResult {
+	const root = packageRoot(join(options.cwd, "package.json"));
+	const registry = loadRegistry(join(root, "registry.json"));
+	const items = resolveItems(registry, options.names);
+
+	const target = join(
+		options.cwd,
+		options.paths?.components ?? defaultPaths.components,
+	);
+	const language = options.language ?? detectLanguage(target) ?? "js";
+
+	// The compiled output is what a browser can load. It ships in the package
+	// and `prepublishOnly` rebuilds it, so an installed copy always has it;
+	// inside this workspace it needs `pnpm build` first.
+	const sourceRoot = join(root, language === "ts" ? "src" : "dist");
+	if (!existsSync(sourceRoot)) {
+		throw new Error(
+			`${sourceRoot} is missing — run \`pnpm build\` in the nebula package before adding in ${language} mode.`,
+		);
+	}
+
+	const written: string[] = [];
+	const skipped: string[] = [];
+	// Shared files — `lib/cn.ts`, the primitives — belong to several items, so
+	// one run reaches the same path repeatedly. Without this, the second visit
+	// finds the file the first visit just wrote and reports it as pre-existing,
+	// which reads as a warning about the user's own work.
+	const handled = new Set<string>();
+
+	for (const item of items) {
+		for (const file of item.files) {
+			if (handled.has(file)) continue;
+			handled.add(file);
+
+			// The registry lists `.ts` paths; the compiled tree mirrors it exactly,
+			// so only the extension changes.
+			const relative = language === "ts" ? file : file.replace(/\.ts$/, ".js");
+			const from = join(sourceRoot, relative);
+			const to = join(target, relative);
+
+			if (existsSync(to) && options.force !== true) {
+				skipped.push(relative);
+				continue;
+			}
+			written.push(relative);
+			if (options.dryRun === true) continue;
+
+			mkdirSync(dirname(to), { recursive: true });
+			copyFileSync(from, to);
+		}
+	}
+
+	return { written, skipped, language };
+}

package/src/cli/index.ts

@@ -0,0 +1,22 @@
+/**
+ * The programmatic surface behind `ream nebula:add`.
+ *
+ * The Rust CLI cannot read `registry.json` or resolve the package's own
+ * install path, so — exactly as `nova.rs` does for VAPID keys — it runs Node
+ * against this entry point and lets the package do its own work. Everything
+ * that knows about the registry stays here, in the package that owns it.
+ */
+
+export {
+	type AddOptions,
+	type AddResult,
+	add,
+	detectLanguage,
+} from "./add.js";
+export {
+	loadRegistry,
+	packageRoot,
+	type Registry,
+	type RegistryItem,
+	resolveItems,
+} from "./registry.js";

package/src/cli/registry.ts

@@ -0,0 +1,116 @@
+/**
+ * Reading `registry.json`.
+ *
+ * The file is generated (`pnpm registry`) and shipped with the package, so it
+ * is data arriving from disk — parsed, then checked before use. A malformed
+ * registry should fail with a sentence saying so, not with an undefined
+ * property three functions later.
+ */
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+export type Layer = "atoms" | "molecules" | "organisms" | "templates";
+
+export interface RegistryItem {
+	name: string;
+	title: string;
+	layer: Layer;
+	files: readonly string[];
+	dependencies: readonly string[];
+}
+
+export interface Registry {
+	name: string;
+	items: readonly RegistryItem[];
+}
+
+function isLayer(value: unknown): value is Layer {
+	return (
+		value === "atoms" ||
+		value === "molecules" ||
+		value === "organisms" ||
+		value === "templates"
+	);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return (
+		Array.isArray(value) && value.every((entry) => typeof entry === "string")
+	);
+}
+
+function isItem(value: unknown): value is RegistryItem {
+	if (typeof value !== "object" || value === null) return false;
+	const name = Reflect.get(value, "name");
+	const title = Reflect.get(value, "title");
+	const layer = Reflect.get(value, "layer");
+	const files = Reflect.get(value, "files");
+	const dependencies = Reflect.get(value, "dependencies");
+	return (
+		typeof name === "string" &&
+		typeof title === "string" &&
+		isLayer(layer) &&
+		isStringArray(files) &&
+		isStringArray(dependencies)
+	);
+}
+
+function isRegistry(value: unknown): value is Registry {
+	if (typeof value !== "object" || value === null) return false;
+	const items = Reflect.get(value, "items");
+	return Array.isArray(items) && items.every(isItem);
+}
+
+/** Load the registry shipped alongside this package. */
+export function loadRegistry(path: string): Registry {
+	const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+	if (!isRegistry(parsed)) {
+		throw new Error(
+			`${path} is not a valid nebula registry — regenerate it with \`pnpm registry\`.`,
+		);
+	}
+	return parsed;
+}
+
+/** Where this package is installed, so its sources and registry can be read. */
+export function packageRoot(from: string): string {
+	const require = createRequire(from);
+	// Resolve through the manifest rather than the entry point: the entry is
+	// `src/index.ts` in this workspace and `dist/index.js` once published, and
+	// only `package.json` is at a fixed place in both.
+	return require
+		.resolve("@c9up/nebula/package.json")
+		.replace(/package\.json$/, "");
+}
+
+/**
+ * An item plus everything it needs, in install order.
+ *
+ * Depth-first with a seen set: Combobox pulls Command, Command pulls nothing
+ * further, and a diamond (two organisms sharing a molecule) copies it once.
+ */
+export function resolveItems(
+	registry: Registry,
+	names: readonly string[],
+): RegistryItem[] {
+	const byName = new Map(registry.items.map((item) => [item.name, item]));
+	const seen = new Set<string>();
+	const ordered: RegistryItem[] = [];
+
+	function visit(name: string): void {
+		if (seen.has(name)) return;
+		seen.add(name);
+		const item = byName.get(name);
+		if (item === undefined) {
+			throw new Error(
+				`unknown component "${name}" — run \`ream nebula:list\` to see what exists.`,
+			);
+		}
+		for (const dependency of item.dependencies) visit(dependency);
+		ordered.push(item);
+	}
+
+	for (const name of names) visit(name);
+	return ordered;
+}

package/src/config.ts

@@ -0,0 +1,102 @@
+/**
+ * nebula's configuration — `config/nebula.ts` in a ream app.
+ *
+ * nebula declares **no CSS dependency at all**, not even a peer one. The app
+ * installs whichever engine it wants and names it here; nebula generates the
+ * stubs and the build command that match. That mirrors how AdonisJS treats its
+ * asset bundler, and it is the reason `tailwindcss` does not appear in this
+ * package's `package.json`.
+ *
+ *   // config/nebula.ts
+ *   import { defineConfig } from '@c9up/nebula'
+ *
+ *   export default defineConfig({
+ *     adapter: 'tailwind',
+ *     paths: {
+ *       components: 'resources/pages',
+ *       css: 'resources/css/app.css',
+ *       output: 'public/app.css',
+ *     },
+ *   })
+ *
+ * The paths are also what the registry copies into: `ream nebula:add button`
+ * writes to `<components>/atoms/Button.ts`, because the atomic layer is a
+ * property of the component, not a choice made at install time.
+ */
+
+export type AdapterName = "tailwind" | "unocss" | "css";
+
+/**
+ * What `nebula add` writes into the project.
+ *
+ * `"js"` copies the compiled output — valid ESM with `.js` specifiers and every
+ * doc comment intact, which a browser loads directly. That is the default,
+ * because an Aurora app serves `resources/pages` to the browser unbuilt; that
+ * zero-build-step promise is the framework's premise, and TypeScript sources
+ * dropped into that tree simply do not run.
+ *
+ * `"ts"` copies the TypeScript sources, for a project that compiles its front
+ * end. `nebula add` infers it from what the components directory already holds
+ * and only falls back to this setting when the directory is empty.
+ */
+export type Language = "ts" | "js";
+
+export interface NebulaPaths {
+	/** Root of the atomic component tree. Layer directories live under it. */
+	components: string;
+	/** The stylesheet the adapter writes and the build compiles. */
+	css: string;
+	/** Where the compiled stylesheet lands. */
+	output: string;
+}
+
+export interface NebulaConfig {
+	/**
+	 * Which CSS engine the app uses.
+	 *
+	 * `tailwind` and `unocss` consume the same class names, so switching
+	 * between them changes the config and nothing else. `css` uses no engine:
+	 * the build emits a stylesheet holding exactly the utilities nebula's
+	 * components reference, and nothing has to be installed.
+	 */
+	adapter: AdapterName;
+	/** Overridden per-run by `--ts` / `--js`, and by what the tree already holds. */
+	language?: Language;
+	paths?: Partial<NebulaPaths>;
+	/**
+	 * Override design tokens. Anything omitted keeps nebula's default, so a
+	 * project can retune `--primary` without restating the palette.
+	 */
+	tokens?: Readonly<Record<string, string>>;
+	/** Same, for `.dark`. */
+	darkTokens?: Readonly<Record<string, string>>;
+}
+
+export interface ResolvedNebulaConfig extends NebulaConfig {
+	paths: NebulaPaths;
+}
+
+export const defaultPaths: NebulaPaths = {
+	components: "resources/pages",
+	css: "resources/css/app.css",
+	output: "public/app.css",
+};
+
+/** Type-checked config helper. Import it in `config/nebula.ts`. */
+export function defineConfig(config: NebulaConfig): NebulaConfig {
+	return config;
+}
+
+/** Fill in the defaults. Used by the CLI and by the adapters. */
+export function resolveConfig(config: NebulaConfig): ResolvedNebulaConfig {
+	return { ...config, paths: { ...defaultPaths, ...config.paths } };
+}
+
+/** The atomic layers, in dependency order. Also the registry's layer names. */
+export const layers = ["atoms", "molecules", "organisms", "templates"] as const;
+
+export type Layer = (typeof layers)[number];
+
+export function isLayer(value: string): value is Layer {
+	return layers.some((layer) => layer === value);
+}