@c9up/nebula 0.1.0

package/dist/organisms/Calendar.js

@@ -0,0 +1,353 @@
+/**
+ * Calendar — a month grid for picking a date.
+ *
+ * shadcn wraps `react-day-picker`, which brings `date-fns` with it. nebula
+ * uses `Date` and `Intl`, which cover everything this needs: month lengths and
+ * leap years come from `Date`, and weekday and month names come from
+ * `Intl.DateTimeFormat` in the user's locale for free — which is more than a
+ * hardcoded English array would give.
+ *
+ * Dates are handled at local midnight throughout. A calendar cell means "this
+ * day", not "this instant", and mixing the two is how a date picker ends up
+ * off by one for users west of UTC: `new Date("2026-03-14")` parses as UTC
+ * midnight, which is the 13th in New York.
+ *
+ * The keyboard model is the WAI-ARIA grid pattern, and it is what makes the
+ * control usable at all without a pointer: arrows move a day, PageUp/PageDown
+ * move a month, Home and End jump to the ends of the week. Only one cell is
+ * ever tabbable — the focused day — so Tab leaves the grid instead of walking
+ * through thirty-one buttons.
+ */
+import { component, html, signal } from "@c9up/aurora";
+import { buttonVariants } from "../atoms/Button.js";
+import { cn } from "../lib/cn.js";
+import { ChevronLeftIcon, ChevronRightIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { read } from "../lib/props.js";
+// ─── date helpers ────────────────────────────────────────────────────
+/** Local midnight of the given day — the canonical form for a calendar date. */
+export function startOfDay(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+export function isSameDay(a, b) {
+    return (a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate());
+}
+export function addDays(date, days) {
+    // Day-of-month arithmetic through the Date constructor, which normalises
+    // overflow — the 32nd of March becomes the 1st of April, leap years and
+    // month lengths included. Adding milliseconds would not: a day is not
+    // always 86 400 000 ms across a daylight-saving boundary.
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
+}
+export function addMonths(date, months) {
+    const target = new Date(date.getFullYear(), date.getMonth() + months, 1);
+    // Clamp the day: 31 January plus one month is 28 February, not 3 March.
+    const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+    return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), lastDay));
+}
+/**
+ * The six-week grid covering a month.
+ *
+ * Always six weeks, always 42 cells, even when five would do. A grid that
+ * changes height between months makes the whole popover jump as you page
+ * through it.
+ */
+export function monthGrid(month, weekStartsOn) {
+    const first = new Date(month.getFullYear(), month.getMonth(), 1);
+    const lead = (first.getDay() - weekStartsOn + 7) % 7;
+    const start = addDays(first, -lead);
+    return Array.from({ length: 42 }, (_unused, index) => addDays(start, index));
+}
+function hasWeekInfo(value) {
+    return "getWeekInfo" in value && typeof value.getWeekInfo === "function";
+}
+/** The locale's first day of the week, or Monday where it cannot be read. */
+function localeWeekStart(locale) {
+    const resolved = new Intl.Locale(locale ?? navigator.language);
+    if (!hasWeekInfo(resolved))
+        return 1;
+    // `firstDay` is 1–7 with 7 for Sunday; the Date API uses 0–6 with 0 Sunday.
+    return resolved.getWeekInfo().firstDay % 7;
+}
+/**
+ * Place a day relative to a span.
+ *
+ * `end` is passed in rather than read off the range because it may be the
+ * *preview* end — wherever the pointer is, before the second click. Keeping
+ * that decision at the call site is what lets this stay a pure function over
+ * three dates, which is the part worth testing exhaustively.
+ */
+export function rangePosition(date, range, end) {
+    if (range === undefined)
+        return "none";
+    if (end === undefined) {
+        return isSameDay(date, range.from) ? "single" : "none";
+    }
+    // Ordered, because the preview end can sit before the fixed start while the
+    // pointer sweeps backwards.
+    const [lo, hi] = range.from <= end ? [range.from, end] : [end, range.from];
+    // A one-day span is both ends at once, and squaring either side of it would
+    // leave a lone cell with a flat edge against nothing.
+    if (isSameDay(lo, hi))
+        return isSameDay(date, lo) ? "single" : "none";
+    if (isSameDay(date, lo))
+        return "start";
+    if (isSameDay(date, hi))
+        return "end";
+    return date > lo && date < hi ? "middle" : "none";
+}
+/**
+ * The span after clicking `date`.
+ *
+ * A click before the fixed start restarts the span rather than producing an
+ * inverted one. Silently swapping the ends would be the other option, and it
+ * is worse: the user who clicked the 3rd after the 10th almost always meant to
+ * start again, not to select the week between them.
+ */
+export function nextRange(current, date) {
+    if (current === undefined ||
+        current.to !== undefined ||
+        date < current.from) {
+        return { from: date };
+    }
+    return { from: current.from, to: date };
+}
+// ─── component ───────────────────────────────────────────────────────
+export const Calendar = component((props) => {
+    const gridId = uid("calendar-grid");
+    const labelId = uid("calendar-label");
+    const locale = props.locale;
+    const weekStartsOn = props.weekStartsOn ?? safeWeekStart(locale);
+    const isRange = props.mode === "range";
+    const today = startOfDay(new Date());
+    const initial = props.defaultValue ??
+        props.defaultRange?.from ??
+        props.defaultMonth ??
+        today;
+    const month = signal(new Date(initial.getFullYear(), initial.getMonth(), 1));
+    /** The day the keyboard is on. Only this cell is tabbable. */
+    const cursor = signal(startOfDay(initial));
+    const selected = () => read(props.value) ?? props.defaultValue;
+    /** The span being built, when the caller does not control it. */
+    const draft = signal(props.defaultRange);
+    /** The day under the pointer, for the preview half of an open range. */
+    const hovered = signal(undefined);
+    const activeRange = () => read(props.range) ?? draft();
+    /**
+     * The far end of the span as currently drawn.
+     *
+     * While only one end is fixed, that is wherever the pointer is — which is
+     * what makes the range visibly follow the cursor before the second click.
+     * Keyboard users get no preview, and that is fine: for them the span
+     * appears on Enter, and a preview tied to the roving cursor would announce
+     * a selection that has not happened.
+     */
+    function rangeEnd() {
+        const current = activeRange();
+        if (current === undefined)
+            return undefined;
+        return current.to ?? hovered();
+    }
+    function rangePositionOf(date) {
+        const current = activeRange();
+        if (current === undefined)
+            return "none";
+        const end = rangeEnd();
+        if (end === undefined) {
+            return isSameDay(date, current.from) ? "single" : "none";
+        }
+        // Ordered, because the preview end can sit before the fixed start while
+        // the pointer sweeps backwards.
+        const [lo, hi] = current.from <= end ? [current.from, end] : [end, current.from];
+        // A one-day span is both ends at once, and squaring either side of it
+        // would leave a lone cell with a flat edge against nothing.
+        if (isSameDay(lo, hi))
+            return isSameDay(date, lo) ? "single" : "none";
+        if (isSameDay(date, lo))
+            return "start";
+        if (isSameDay(date, hi))
+            return "end";
+        return date > lo && date < hi ? "middle" : "none";
+    }
+    const monthLabel = new Intl.DateTimeFormat(locale, {
+        month: "long",
+        year: "numeric",
+    });
+    const weekdayLabel = new Intl.DateTimeFormat(locale, { weekday: "short" });
+    const fullDate = new Intl.DateTimeFormat(locale, { dateStyle: "full" });
+    function isDisabled(date) {
+        if (props.min !== undefined && date < startOfDay(props.min))
+            return true;
+        if (props.max !== undefined && date > startOfDay(props.max))
+            return true;
+        return props.disabled?.(date) === true;
+    }
+    /**
+     * Show the month containing `date`, if it is not already showing.
+     *
+     * The guard is load-bearing. `month` is a signal the whole grid is derived
+     * from, so writing a fresh `Date` for the month already on screen rebuilds
+     * all 42 cells — destroying the one the user just clicked, and with it the
+     * focus that was on it.
+     */
+    function showMonthOf(date) {
+        const current = month();
+        if (current.getFullYear() === date.getFullYear() &&
+            current.getMonth() === date.getMonth()) {
+            return;
+        }
+        month(new Date(date.getFullYear(), date.getMonth(), 1));
+    }
+    function choose(date) {
+        if (isDisabled(date))
+            return;
+        cursor(date);
+        showMonthOf(date);
+        if (isRange)
+            chooseInRange(date);
+        else
+            props.onValueChange?.(date);
+    }
+    function chooseInRange(date) {
+        const next = nextRange(activeRange(), date);
+        draft(next);
+        // Drop the preview: it belonged to the span that just closed, and leaving
+        // it would paint a band to wherever the pointer happens to rest.
+        hovered(undefined);
+        props.onRangeChange?.(next);
+    }
+    function moveCursor(next) {
+        cursor(next);
+        // Follow the cursor across a month boundary, otherwise arrowing off the
+        // end of the grid moves focus to a cell that is not on screen.
+        if (next.getMonth() !== month().getMonth() ||
+            next.getFullYear() !== month().getFullYear()) {
+            month(new Date(next.getFullYear(), next.getMonth(), 1));
+        }
+        focusCursor();
+    }
+    function focusCursor() {
+        // After the signal write, so the new cell exists and carries tabindex 0.
+        queueMicrotask(() => {
+            const grid = document.getElementById(gridId);
+            grid
+                ?.querySelector("[data-cursor]")
+                ?.focus({ preventScroll: true });
+        });
+    }
+    function onKeyDown(event) {
+        const from = cursor();
+        const moves = {
+            ArrowLeft: () => addDays(from, -1),
+            ArrowRight: () => addDays(from, 1),
+            ArrowUp: () => addDays(from, -7),
+            ArrowDown: () => addDays(from, 7),
+            PageUp: () => addMonths(from, -1),
+            PageDown: () => addMonths(from, 1),
+            Home: () => addDays(from, -((from.getDay() - weekStartsOn + 7) % 7)),
+            End: () => addDays(from, 6 - ((from.getDay() - weekStartsOn + 7) % 7)),
+        };
+        const move = moves[event.key];
+        if (move !== undefined) {
+            event.preventDefault();
+            moveCursor(move());
+            return;
+        }
+        if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            choose(from);
+        }
+    }
+    const weekdayNames = Array.from({ length: 7 }, (_unused, index) => weekdayLabel.format(new Date(2024, 0, 7 + ((weekStartsOn + index) % 7))));
+    return html `<div
+		data-slot="calendar"
+		class="${() => cn("bg-background w-fit rounded-md p-3", read(props.class))}"
+	>
+		<div class="flex items-center justify-between pb-4">
+			<button
+				type="button"
+				aria-label="Previous month"
+				class="${buttonVariants({ variant: "outline", size: "icon", class: "size-7" })}"
+				@click="${() => month(addMonths(month(), -1))}"
+			>${ChevronLeftIcon({ class: "size-4" })}</button>
+			<div id="${labelId}" aria-live="polite" class="text-sm font-medium">
+				${() => monthLabel.format(month())}
+			</div>
+			<button
+				type="button"
+				aria-label="Next month"
+				class="${buttonVariants({ variant: "outline", size: "icon", class: "size-7" })}"
+				@click="${() => month(addMonths(month(), 1))}"
+			>${ChevronRightIcon({ class: "size-4" })}</button>
+		</div>
+		<div
+			role="grid"
+			id="${gridId}"
+			aria-labelledby="${labelId}"
+			class="grid grid-cols-7 gap-1"
+			@keydown="${onKeyDown}"
+		>
+			${weekdayNames.map((name) => html `<div
+					role="columnheader"
+					aria-label="${name}"
+					class="text-muted-foreground flex size-8 items-center justify-center text-[0.8rem] font-normal"
+				>${name}</div>`)}
+			${() => monthGrid(month(), weekStartsOn).map(renderDay)}
+		</div>
+	</div>`;
+    function renderDay(date) {
+        const outside = date.getMonth() !== month().getMonth();
+        const position = () => isRange ? rangePositionOf(date) : "none";
+        const chosen = () => {
+            if (isRange)
+                return position() !== "none";
+            const current = selected();
+            return current !== undefined && isSameDay(current, date);
+        };
+        const onCursor = () => isSameDay(cursor(), date);
+        const disabled = isDisabled(date);
+        return html `<button
+			type="button"
+			role="gridcell"
+			data-slot="calendar-day"
+			data-cursor="${() => (onCursor() ? "" : undefined)}"
+			data-outside="${outside ? "" : undefined}"
+			data-today="${isSameDay(date, today) ? "" : undefined}"
+			data-range="${() => {
+            const at = position();
+            return at === "none" ? undefined : at;
+        }}"
+			aria-label="${fullDate.format(date)}"
+			aria-selected="${() => (chosen() ? "true" : "false")}"
+			aria-current="${isSameDay(date, today) ? "date" : undefined}"
+			tabindex="${() => (onCursor() ? 0 : -1)}"
+			?disabled="${disabled}"
+			class="${() => cn("flex size-8 items-center justify-center rounded-md p-0 text-sm font-normal transition-colors outline-none", "hover:bg-accent hover:text-accent-foreground focus-visible:ring-ring/50 focus-visible:ring-[3px]", "aria-selected:bg-primary aria-selected:text-primary-foreground aria-selected:hover:bg-primary", "data-[today]:bg-accent data-[today]:aria-selected:bg-primary", 
+        // The interior of a span is a flat band: square, and in accent
+        // rather than primary, so the two ends stay the emphasis.
+        "data-[range=middle]:bg-accent data-[range=middle]:text-accent-foreground data-[range=middle]:rounded-none", "data-[range=start]:rounded-r-none data-[range=end]:rounded-l-none", outside ? "text-muted-foreground opacity-50" : "", disabled ? "pointer-events-none opacity-30" : "")}"
+			@click="${() => choose(date)}"
+			@pointerenter="${() => {
+            if (isRange && !disabled)
+                hovered(date);
+        }}"
+		>${date.getDate()}</button>`;
+    }
+});
+/**
+ * `Intl.Locale.getWeekInfo` is not available everywhere yet, and neither is
+ * `navigator` on the server. Monday is the fallback — the ISO week start, and
+ * the right answer for most of the world.
+ */
+function safeWeekStart(locale) {
+    try {
+        if (typeof navigator === "undefined" && locale === undefined)
+            return 1;
+        return localeWeekStart(locale);
+    }
+    catch {
+        return 1;
+    }
+}

package/dist/organisms/Carousel.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Carousel — a horizontally scrolling strip of slides.
+ *
+ * shadcn wraps `embla-carousel`, which animates a transform with its own
+ * requestAnimationFrame loop and reimplements drag physics on top. nebula uses
+ * CSS scroll-snap and `scrollBy`.
+ *
+ * That is not only smaller, it is better behaved. Native scrolling brings
+ * touch momentum, trackpad gestures, the platform's own overscroll, and
+ * keyboard scrolling — all things a transform-based carousel has to rebuild
+ * and usually gets partly wrong. `scroll-behavior: smooth` handles the
+ * animation, and `prefers-reduced-motion` turns it off without a branch here.
+ *
+ * The strip is a `region` with `aria-roledescription="carousel"`, and slides
+ * are `group`s labelled "N of M". A screen reader user otherwise has no way to
+ * tell how much is off-screen — the visual affordance of a strip running off
+ * the edge carries none of that.
+ */
+import type { Child } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+export interface CarouselProps {
+    slides: readonly Child[];
+    /** Announced before the slides. */
+    label?: string;
+    orientation?: "horizontal" | "vertical";
+    class?: Reactive<string>;
+    slideClass?: Reactive<string>;
+}
+export declare const Carousel: (props?: CarouselProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/Carousel.js

@@ -0,0 +1,128 @@
+/**
+ * Carousel — a horizontally scrolling strip of slides.
+ *
+ * shadcn wraps `embla-carousel`, which animates a transform with its own
+ * requestAnimationFrame loop and reimplements drag physics on top. nebula uses
+ * CSS scroll-snap and `scrollBy`.
+ *
+ * That is not only smaller, it is better behaved. Native scrolling brings
+ * touch momentum, trackpad gestures, the platform's own overscroll, and
+ * keyboard scrolling — all things a transform-based carousel has to rebuild
+ * and usually gets partly wrong. `scroll-behavior: smooth` handles the
+ * animation, and `prefers-reduced-motion` turns it off without a branch here.
+ *
+ * The strip is a `region` with `aria-roledescription="carousel"`, and slides
+ * are `group`s labelled "N of M". A screen reader user otherwise has no way to
+ * tell how much is off-screen — the visual affordance of a strip running off
+ * the edge carries none of that.
+ */
+import { component, html, onMount, onUnmount, signal } from "@c9up/aurora";
+import { buttonVariants } from "../atoms/Button.js";
+import { cn } from "../lib/cn.js";
+import { ArrowLeftIcon, ArrowRightIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { read } from "../lib/props.js";
+export const Carousel = component((props) => {
+    const trackId = uid("carousel-track");
+    const horizontal = props.orientation !== "vertical";
+    const atStart = signal(true);
+    const atEnd = signal(false);
+    function track() {
+        return document.getElementById(trackId);
+    }
+    /**
+     * Recompute whether either end is reached.
+     *
+     * The one-pixel tolerance is load-bearing: with fractional device pixel
+     * ratios, `scrollLeft` at the far end lands a fraction short of
+     * `scrollWidth - clientWidth`, and an exact comparison leaves the "next"
+     * button enabled on a carousel that cannot scroll any further.
+     */
+    function syncEdges() {
+        const element = track();
+        if (element === null)
+            return;
+        const position = horizontal ? element.scrollLeft : element.scrollTop;
+        const total = horizontal ? element.scrollWidth : element.scrollHeight;
+        const visible = horizontal ? element.clientWidth : element.clientHeight;
+        atStart(position <= 1);
+        atEnd(position + visible >= total - 1);
+    }
+    function scrollByPage(direction) {
+        const element = track();
+        if (element === null)
+            return;
+        const distance = (horizontal ? element.clientWidth : element.clientHeight) * direction;
+        element.scrollBy(horizontal
+            ? { left: distance, behavior: "smooth" }
+            : { top: distance, behavior: "smooth" });
+    }
+    function onKeyDown(event) {
+        const back = horizontal ? "ArrowLeft" : "ArrowUp";
+        const forward = horizontal ? "ArrowRight" : "ArrowDown";
+        if (event.key === back) {
+            event.preventDefault();
+            scrollByPage(-1);
+        }
+        else if (event.key === forward) {
+            event.preventDefault();
+            scrollByPage(1);
+        }
+    }
+    onMount(() => {
+        syncEdges();
+        const element = track();
+        element?.addEventListener("scroll", syncEdges, { passive: true });
+        window.addEventListener("resize", syncEdges);
+    });
+    onUnmount(() => {
+        track()?.removeEventListener("scroll", syncEdges);
+        window.removeEventListener("resize", syncEdges);
+    });
+    const count = props.slides.length;
+    return html `<div
+		data-slot="carousel"
+		role="region"
+		aria-roledescription="carousel"
+		aria-label="${props.label ?? "Carousel"}"
+		class="${() => cn("relative", read(props.class))}"
+		@keydown="${onKeyDown}"
+	>
+		<div
+			data-slot="carousel-track"
+			id="${trackId}"
+			tabindex="0"
+			class="${cn("flex snap-mandatory gap-4 overflow-auto scroll-smooth outline-none motion-reduce:scroll-auto", horizontal
+        ? "snap-x flex-row [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+        : "snap-y max-h-96 flex-col [scrollbar-width:none] [&::-webkit-scrollbar]:hidden")}"
+		>
+			${props.slides.map((child, index) => html `<div
+					data-slot="carousel-slide"
+					role="group"
+					aria-roledescription="slide"
+					aria-label="${`${index + 1} of ${count}`}"
+					class="${() => cn("min-w-0 shrink-0 grow-0 basis-full snap-start", read(props.slideClass))}"
+				>${child}</div>`)}
+		</div>
+		<button
+			type="button"
+			data-slot="carousel-previous"
+			aria-label="Previous slide"
+			?disabled="${() => atStart()}"
+			class="${cn(buttonVariants({ variant: "outline", size: "icon" }), "absolute size-8 rounded-full", horizontal
+        ? "top-1/2 -left-12 -translate-y-1/2"
+        : "-top-12 left-1/2 -translate-x-1/2 rotate-90")}"
+			@click="${() => scrollByPage(-1)}"
+		>${ArrowLeftIcon({ class: "size-4" })}</button>
+		<button
+			type="button"
+			data-slot="carousel-next"
+			aria-label="Next slide"
+			?disabled="${() => atEnd()}"
+			class="${cn(buttonVariants({ variant: "outline", size: "icon" }), "absolute size-8 rounded-full", horizontal
+        ? "top-1/2 -right-12 -translate-y-1/2"
+        : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90")}"
+			@click="${() => scrollByPage(1)}"
+		>${ArrowRightIcon({ class: "size-4" })}</button>
+	</div>`;
+});

package/dist/organisms/Chart.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Chart — line, area and bar charts drawn as inline SVG.
+ *
+ * shadcn's Chart is a theming wrapper around Recharts. nebula cannot follow it
+ * there — Recharts is React — and a zero-dependency port of a full charting
+ * library is not a thing to promise. So the scope is stated plainly: three
+ * chart types over one categorical axis and one numeric axis, which is what
+ * the shadcn chart examples are and what dashboards overwhelmingly need.
+ *
+ * Anything beyond that — stacked bars with negative values, dual axes, brushes,
+ * candlesticks — is a charting library's job, and an app needing one should
+ * install one rather than have this component grow into a bad copy.
+ *
+ * The colours come from `--chart-1` … `--chart-5`, so a chart re-themes with
+ * the rest of the design system instead of carrying its own palette.
+ *
+ * An SVG chart is invisible to a screen reader whatever ARIA is put on it, so
+ * the same data is emitted as a real `<table>`, visually hidden. That is the
+ * only approach that actually works: the reader gets rows and values it can
+ * navigate, not a described picture.
+ */
+import { type Reactive } from "../lib/props.js";
+export interface ChartSeries {
+    key: string;
+    label: string;
+    /** Any CSS colour. Defaults to `--chart-1`…`--chart-5` by position. */
+    color?: string;
+}
+/** One row: a category plus one numeric value per series key. */
+export type ChartDatum = Record<string, string | number>;
+export interface ChartProps {
+    data: readonly ChartDatum[];
+    series: readonly ChartSeries[];
+    /** Key in each datum holding the category label. */
+    categoryKey: string;
+    type?: "line" | "area" | "bar";
+    height?: number;
+    /** Announced as the chart's name, and used as the data table's caption. */
+    label: string;
+    /** Draw horizontal gridlines. Default `true`. */
+    grid?: boolean;
+    class?: Reactive<string>;
+}
+/**
+ * The value range the Y axis covers.
+ *
+ * Anchored at zero whenever the data is non-negative. A bar chart whose axis
+ * starts at the minimum value exaggerates every difference — the classic
+ * misleading chart — and it is not a choice worth exposing as an option.
+ */
+export declare function valueRange(data: readonly ChartDatum[], series: readonly ChartSeries[]): {
+    min: number;
+    max: number;
+};
+export declare const Chart: (props?: ChartProps | undefined) => import("@c9up/aurora").TemplateResult;