@repraze/kernelkit 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/components/time-select.tsx

@@ -0,0 +1,291 @@
+"use client";
+
+import {
+    Combobox,
+    ComboboxContent,
+    ComboboxEmpty,
+    ComboboxInput,
+    ComboboxItem,
+    ComboboxList,
+} from "@repraze/kernelkit/components/combobox";
+import {type HourCyclePreference, useTimeFormat} from "@repraze/kernelkit/hooks/use-time-format";
+import {cva} from "class-variance-authority";
+import {cn} from "cn";
+import * as React from "react";
+
+/* ------------------------------------------------------------------------------------------------
+ * Time helpers (minutes since midnight)
+ * ----------------------------------------------------------------------------------------------*/
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+function toMinutes(value: string | null | undefined): number | null {
+    const m = value ? /^(\d{1,2}):(\d{2})/.exec(value) : null;
+    if (!m) {
+        return null;
+    }
+    const h = Number(m[1]);
+    const min = Number(m[2]);
+    return h > 23 || min > 59 ? null : h * 60 + min;
+}
+
+const toValue = (minutes: number) => `${pad(Math.floor(minutes / 60))}:${pad(minutes % 60)}`;
+
+function formatTime(minutes: number, cycle: 12 | 24) {
+    const h = Math.floor(minutes / 60);
+    const m = pad(minutes % 60);
+    return cycle === 24 ? `${pad(h)}:${m}` : `${h % 12 || 12}:${m} ${h < 12 ? "AM" : "PM"}`;
+}
+
+function formatDuration(minutes: number) {
+    if (minutes < 60) {
+        return `${minutes} min`;
+    }
+    const h = Math.floor(minutes / 60);
+    const m = minutes % 60;
+    return m ? `${h} h ${m} min` : `${h} h`;
+}
+
+/**
+ * Lenient match, like Google Calendar's time list: "9" → 09:xx and 9 PM, "930" / "9:3" → 09:30,
+ * "9p" → 21:xx, "21" → 21:xx. Returns the exact time when the query is a complete one ("10:10", "7:05pm").
+ */
+function matchTime(query: string, cycle: 12 | 24 = 24) {
+    const q = query
+        .toLowerCase()
+        .replace(/\s+/g, "")
+        .replace(/\.(?=\d)/, ":");
+    const meridiem = /(a|am|p|pm)$/.exec(q)?.[1]?.[0] as "a" | "p" | undefined;
+    const body = meridiem ? q.replace(/(a|am|p|pm)$/, "") : q;
+    if (!/^\d{0,2}(:\d{0,2})?$|^\d{3,4}$/.test(body) || (!body && !meridiem)) {
+        return {test: () => false, exact: null as number | null};
+    }
+    let hourText: string;
+    let minuteText: string;
+    if (body.includes(":")) {
+        [hourText = "", minuteText = ""] = body.split(":");
+    } else if (body.length > 2) {
+        hourText = body.slice(0, body.length - 2);
+        minuteText = body.slice(-2);
+    } else {
+        hourText = body;
+        minuteText = "";
+    }
+
+    const test = (minutes: number) => {
+        const h24 = Math.floor(minutes / 60);
+        const h12 = h24 % 12 || 12;
+        const pm = h24 >= 12;
+        if (meridiem && (meridiem === "p") !== pm) {
+            return false;
+        }
+        // 24h display: hours are read as 24h ("9" is 09:xx) unless a meridiem is typed
+        const hourOk =
+            !hourText ||
+            (meridiem || cycle === 12
+                ? Number(hourText) === h12 || (!meridiem && Number(hourText) === h24)
+                : Number(hourText) === h24);
+        return hourOk && pad(minutes % 60).startsWith(minuteText);
+    };
+
+    // a complete time typed off the grid ("10:10") is offered as its own option
+    let exact: number | null = null;
+    const h = Number(hourText);
+    if (hourText && minuteText.length === 2) {
+        const m = Number(minuteText);
+        const h24 = meridiem ? (h % 12) + (meridiem === "p" ? 12 : 0) : h;
+        if (m < 60 && h24 < 24 && (!meridiem || (h >= 1 && h <= 12))) {
+            exact = h24 * 60 + m;
+        }
+    }
+    return {test, exact};
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * TimeSelect
+ * ----------------------------------------------------------------------------------------------*/
+
+const timeSelectVariants = cva(
+    "w-36 font-normal *:data-[slot=input-group-control]:font-mono *:data-[slot=input-group-control]:tabular-nums",
+    {
+        variants: {
+            size: {
+                sm: "h-7 rounded-md text-[0.8rem]",
+                default: "h-8",
+                lg: "h-9",
+            },
+        },
+        defaultVariants: {size: "default"},
+    },
+);
+
+interface TimeSelectProps {
+    /** 24-hour `"HH:mm"`, or `null`. */
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null) => void;
+    /** Minutes between slots. */
+    step?: number;
+    /** First slot, `"HH:mm"`. */
+    min?: string;
+    /** Last slot, `"HH:mm"`. */
+    max?: string;
+    /** How times are shown; `"auto"` follows the user's locale. The value stays 24-hour. */
+    hourCycle?: HourCyclePreference;
+    /** BCP 47 locale for `"auto"` and the labels ("9:30 AM", "午前9:30"); defaults to the browser's. */
+    locale?: string;
+    /** A start time: slots begin there and show their duration, "(1 h 30 min)", like an end-time list. */
+    durationFrom?: string | null;
+    placeholder?: string;
+    size?: "sm" | "default" | "lg";
+    disabled?: boolean;
+    "aria-invalid"?: boolean;
+    "aria-label"?: string;
+    id?: string;
+    name?: string;
+    className?: string;
+}
+
+/**
+ * A time from a list of slots, Google Calendar style: open it and pick, or type a few characters
+ * ("9", "930", "9p") to filter. A complete time typed off the grid ("10:10") is offered too.
+ */
+function TimeSelect({
+    value,
+    defaultValue = null,
+    onValueChange,
+    step = 30,
+    min = "00:00",
+    max = "23:59",
+    hourCycle: hourCyclePreference = "auto",
+    locale,
+    durationFrom,
+    placeholder: placeholderProp,
+    size = "default",
+    disabled,
+    id,
+    name,
+    className,
+    ...aria
+}: TimeSelectProps) {
+    const controlled = value !== undefined;
+    const [inner, setInner] = React.useState<string | null>(defaultValue);
+    const current = controlled ? value : inner;
+    const currentMin = toMinutes(current);
+
+    const set = (next: string | null) => {
+        if (!controlled) {
+            setInner(next);
+        }
+        onValueChange?.(next);
+    };
+
+    const from = toMinutes(durationFrom);
+    const slots = React.useMemo(() => {
+        const lo = Math.max(toMinutes(min) ?? 0, from ?? 0);
+        const hi = toMinutes(max) ?? 23 * 60 + 59;
+        const s = Math.max(1, step);
+        const list: number[] = [];
+        // durationFrom: the grid starts at the start time; otherwise it is aligned on midnight
+        for (let t = from !== null ? lo : Math.ceil(lo / s) * s; t <= hi; t += s) {
+            list.push(t);
+        }
+        return list;
+    }, [min, max, step, from]);
+
+    const fmt = useTimeFormat(hourCyclePreference, locale);
+    const hourCycle = fmt.hourCycle;
+    const placeholder = placeholderProp ?? (hourCycle === 12 ? "--:-- --" : "--:--");
+    const label = fmt.format;
+
+    // filter only once the user types: opening on a picked time lists every slot, scrolled to it
+    const [input, setInput] = React.useState(currentMin === null ? "" : label(currentMin));
+    const [query, setQuery] = React.useState<string | null>(null);
+    // re-label when the value changes or the locale's format arrives after hydration
+    const seenKey = `${current}|${hourCycle}|${fmt.am}|${fmt.pm}`;
+    const [seen, setSeen] = React.useState(seenKey);
+    if (seenKey !== seen) {
+        setSeen(seenKey);
+        setInput(currentMin === null ? "" : label(currentMin));
+    }
+
+    const items = React.useMemo(() => {
+        const base =
+            currentMin !== null && !slots.includes(currentMin) ? [...slots, currentMin].sort((a, b) => a - b) : slots;
+        if (!query) {
+            return base;
+        }
+        const {test, exact} = matchTime(query, hourCycle);
+        // the typed text also matches the localized label ("p.m.", "午後")
+        const q = query.toLowerCase().replace(/\s+/g, "");
+        const hits = base.filter((t) => test(t) || label(t).toLowerCase().replace(/\s+/g, "").includes(q));
+        return exact !== null && !hits.includes(exact) ? [exact, ...hits] : hits;
+    }, [slots, currentMin, query, hourCycle, label]);
+
+    const listRef = React.useRef<HTMLDivElement>(null);
+
+    return (
+        <Combobox<number>
+            items={items}
+            filter={null}
+            // typing highlights the first match, so Enter takes it
+            autoHighlight
+            value={currentMin}
+            onValueChange={(next) => {
+                setQuery(null);
+                set(next === null ? null : toValue(next));
+            }}
+            inputValue={input}
+            onInputValueChange={(text, details) => {
+                setInput(text);
+                if (details.reason === "input-change") {
+                    setQuery(text.trim() || null);
+                }
+            }}
+            onOpenChange={(open) => {
+                if (open) {
+                    // the selected slot in view (Base UI highlights it; the list starts at the top)
+                    requestAnimationFrame(() =>
+                        listRef.current
+                            ?.querySelector<HTMLElement>("[data-selected]")
+                            ?.scrollIntoView({block: "center"}),
+                    );
+                } else {
+                    setQuery(null);
+                    setInput(currentMin === null ? "" : label(currentMin));
+                }
+            }}
+            itemToStringLabel={label}
+            disabled={disabled}
+            name={name}
+        >
+            <ComboboxInput
+                id={id}
+                placeholder={placeholder}
+                disabled={disabled}
+                inputMode="text"
+                autoComplete="off"
+                className={cn(timeSelectVariants({size}), className)}
+                {...aria}
+            />
+            <ComboboxContent data-slot="time-select-content">
+                <ComboboxEmpty>No matching time.</ComboboxEmpty>
+                <ComboboxList ref={listRef}>
+                    {(minutes: number) => (
+                        <ComboboxItem key={minutes} value={minutes} className="tabular-nums">
+                            <span className="font-mono">{label(minutes)}</span>
+                            {from !== null && minutes >= from && (
+                                <span className="ms-auto font-alt text-xs text-muted-foreground">
+                                    {formatDuration(minutes - from)}
+                                </span>
+                            )}
+                        </ComboboxItem>
+                    )}
+                </ComboboxList>
+            </ComboboxContent>
+        </Combobox>
+    );
+}
+
+export {formatDuration, formatTime, matchTime, TimeSelect, timeSelectVariants};
+export type {TimeSelectProps};

package/src/components/timeline.tsx

@@ -0,0 +1,190 @@
+"use client";
+
+import {type Color, colorVariants} from "@repraze/kernelkit/lib/color";
+import {cva} from "class-variance-authority";
+import {cn} from "cn";
+import * as React from "react";
+
+type TimelineSize = "sm" | "default";
+
+const TimelineContext = React.createContext<TimelineSize>("default");
+
+/**
+ * The marker column sets the rhythm: its box is as tall as the title's line (24px, 20px at `sm`), so a dot
+ * or icon centres on the first line of text whatever the item holds.
+ */
+const timelineVariants = cva("flex flex-col", {
+    variants: {
+        size: {
+            default: "text-sm",
+            sm: "text-xs",
+        },
+    },
+    defaultVariants: {size: "default"},
+});
+
+interface TimelineProps extends React.ComponentProps<"ol"> {
+    /** `sm` is the dense log: 20px rows, `text-xs`, tighter spacing. */
+    size?: TimelineSize;
+}
+
+/** A vertical list of events: a marker per item joined by a line, newest first or last as you order them. */
+function Timeline({size = "default", className, ...props}: TimelineProps) {
+    return (
+        <TimelineContext.Provider value={size}>
+            <ol data-slot="timeline" data-size={size} className={cn(timelineVariants({size}), className)} {...props} />
+        </TimelineContext.Provider>
+    );
+}
+
+/** One event: `TimelineMarker` then `TimelineContent` (put a `TimelineTime` first for a time column). */
+function TimelineItem({className, ...props}: React.ComponentProps<"li">) {
+    const size = React.useContext(TimelineContext);
+    return (
+        <li
+            data-slot="timeline-item"
+            data-size={size}
+            className={cn("group/timeline-item relative flex gap-3 data-[size=sm]:gap-2.5", className)}
+            {...props}
+        />
+    );
+}
+
+const timelineMarkerVariants = cva(
+    "relative z-10 inline-flex shrink-0 items-center justify-center rounded-pill [&_svg]:shrink-0",
+    {
+        variants: {
+            color: colorVariants,
+            kind: {
+                // a dot with a ring of the page colour, so it reads over the line
+                dot: "bg-(--c)",
+                icon: "border border-(--c)/40 bg-background text-(--c) hc:border-(--c)",
+            },
+            size: {
+                default: "",
+                sm: "",
+            },
+        },
+        compoundVariants: [
+            {kind: "dot", size: "default", class: "size-2.5"},
+            {kind: "dot", size: "sm", class: "size-2"},
+            {kind: "icon", size: "default", class: "size-6 [&_svg:not([class*='size-'])]:size-3.5"},
+            {kind: "icon", size: "sm", class: "size-5 [&_svg:not([class*='size-'])]:size-3"},
+            {kind: "dot", color: "neutral", class: "bg-muted-foreground"},
+            {kind: "icon", color: "neutral", class: "border-border text-muted-foreground hc:border-border"},
+        ],
+        defaultVariants: {color: "neutral", kind: "dot", size: "default"},
+    },
+);
+
+interface TimelineMarkerProps extends Omit<React.ComponentProps<"span">, "color"> {
+    /** Status or hue of the dot / icon ring. Defaults to neutral grey. */
+    color?: Color | null;
+}
+
+/**
+ * The item's dot, or an icon in a ring when it has children. Carries the line down to the next item;
+ * the last item has no tail.
+ */
+function TimelineMarker({color, className, children, ...props}: TimelineMarkerProps) {
+    const size = React.useContext(TimelineContext);
+    const resolved = color ?? "neutral";
+    const kind = children ? "icon" : "dot";
+    return (
+        <span
+            data-slot="timeline-marker"
+            data-size={size}
+            data-color={resolved}
+            className="flex w-6 shrink-0 flex-col items-center self-stretch data-[size=sm]:w-5"
+        >
+            <span className="flex h-6 items-center justify-center data-[size=sm]:h-5" data-size={size}>
+                <span
+                    data-slot="timeline-marker-indicator"
+                    className={cn(timelineMarkerVariants({color: resolved, kind, size}), className)}
+                    {...props}
+                >
+                    {children}
+                </span>
+            </span>
+            <span
+                data-slot="timeline-marker-tail"
+                aria-hidden="true"
+                className={cn(
+                    "w-px flex-1 bg-border group-last/timeline-item:hidden",
+                    // a dot sits inside its box with room around it; an icon fills the box, so leave a gap at both ends
+                    kind === "icon" && "my-1",
+                )}
+            />
+        </span>
+    );
+}
+
+/** Title, time and description of an item. Its bottom padding is the gap to the next item. */
+function TimelineContent({className, ...props}: React.ComponentProps<"div">) {
+    const size = React.useContext(TimelineContext);
+    return (
+        <div
+            data-slot="timeline-content"
+            data-size={size}
+            className={cn(
+                "flex min-w-0 flex-1 flex-col gap-0.5 pb-6 group-last/timeline-item:pb-0 data-[size=sm]:gap-0 data-[size=sm]:pb-2",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function TimelineTitle({className, ...props}: React.ComponentProps<"div">) {
+    const size = React.useContext(TimelineContext);
+    return (
+        <div
+            data-slot="timeline-title"
+            data-size={size}
+            className={cn(
+                "flex min-h-6 flex-wrap items-center gap-x-2 font-medium text-foreground data-[size=sm]:min-h-5 data-[size=sm]:font-normal",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+/** A timestamp: mono, muted. Inline after a title, or first in the item for a time column. */
+function TimelineTime({className, ...props}: React.ComponentProps<"time">) {
+    const size = React.useContext(TimelineContext);
+    return (
+        <time
+            data-slot="timeline-time"
+            data-size={size}
+            className={cn(
+                "inline-flex min-h-6 shrink-0 items-center font-alt text-xs font-normal text-muted-foreground tabular-nums data-[size=sm]:min-h-5",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function TimelineDescription({className, ...props}: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="timeline-description"
+            className={cn("text-sm text-muted-foreground in-data-[size=sm]:text-xs", className)}
+            {...props}
+        />
+    );
+}
+
+export {
+    Timeline,
+    TimelineContent,
+    TimelineDescription,
+    TimelineItem,
+    TimelineMarker,
+    timelineMarkerVariants,
+    TimelineTime,
+    TimelineTitle,
+    timelineVariants,
+};
+export type {TimelineMarkerProps, TimelineProps, TimelineSize};

package/src/components/toast.tsx

@@ -2,10 +2,11 @@
 
 import {Toast as ToastPrimitive} from "@base-ui/react/toast";
 import {Button} from "@repraze/kernelkit/components/button";
+import {Spinner} from "@repraze/kernelkit/components/spinner";
 import {focusRing, heading} from "@repraze/kernelkit/lib/recipes";
 import {usePortalContainer} from "@repraze/kernelkit/provider";
 import {cn} from "cn";
-import {CircleCheckIcon, InfoIcon, Loader2Icon, OctagonXIcon, TriangleAlertIcon, XIcon} from "lucide-react";
+import {CircleCheckIcon, InfoIcon, OctagonXIcon, TriangleAlertIcon, XIcon} from "lucide-react";
 import * as React from "react";
 
 const toast = ToastPrimitive.createToastManager();
@@ -136,9 +137,8 @@ const TOAST_ICONS: Record<string, React.ReactNode> = {
     warning: <TriangleAlertIcon className="text-warning" aria-hidden="true" />,
     error: <OctagonXIcon className="text-danger" aria-hidden="true" />,
     danger: <OctagonXIcon className="text-danger" aria-hidden="true" />,
-    loading: (
-        <Loader2Icon className="animate-spin text-muted-foreground motion-reduce:animate-none" aria-hidden="true" />
-    ),
+    // follows the app's SpinnerProvider like every other kit spinner
+    loading: <Spinner className="text-muted-foreground" role="presentation" aria-label={undefined} />,
 };
 
 function ToastIcon({type, className}: {type: string | undefined; className?: string}) {