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

package/src/components/description-list.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import {cva} from "class-variance-authority";
+import {cn} from "cn";
+import * as React from "react";
+
+type DescriptionListOrientation = "horizontal" | "vertical";
+
+const DescriptionListContext = React.createContext<{orientation: DescriptionListOrientation; divided: boolean}>({
+    orientation: "horizontal",
+    divided: false,
+});
+
+const descriptionListVariants = cva("text-sm", {
+    variants: {
+        orientation: {
+            // one shared term column: every item is a subgrid row, so terms line up across rows
+            horizontal: "grid grid-cols-[minmax(0,max-content)_minmax(0,1fr)] gap-x-6",
+            vertical: "flex flex-col",
+        },
+        divided: {
+            true: "",
+            false: "",
+        },
+    },
+    compoundVariants: [
+        {orientation: "horizontal", divided: false, class: "gap-y-2.5"},
+        {orientation: "vertical", divided: false, class: "gap-4"},
+    ],
+    defaultVariants: {orientation: "horizontal", divided: false},
+});
+
+interface DescriptionListProps extends React.ComponentProps<"dl"> {
+    /** `horizontal`: terms in a column beside their details. `vertical`: each term above its details. */
+    orientation?: DescriptionListOrientation;
+    /** Rule between items. */
+    divided?: boolean;
+}
+
+/** Key / value pairs: properties of a server, an order, a file. Terms in the label face, details in the body face. */
+function DescriptionList({orientation = "horizontal", divided = false, className, ...props}: DescriptionListProps) {
+    const ctx = React.useMemo(() => ({orientation, divided}), [orientation, divided]);
+    return (
+        <DescriptionListContext.Provider value={ctx}>
+            <dl
+                data-slot="description-list"
+                data-orientation={orientation}
+                data-divided={divided ? "" : undefined}
+                className={cn(descriptionListVariants({orientation, divided}), className)}
+                {...props}
+            />
+        </DescriptionListContext.Provider>
+    );
+}
+
+const descriptionItemVariants = cva("min-w-0", {
+    variants: {
+        orientation: {
+            horizontal: "col-span-2 grid grid-cols-subgrid items-baseline",
+            vertical: "flex flex-col gap-1",
+        },
+        divided: {
+            true: "border-b border-border py-2.5 first:pt-0 last:border-b-0 last:pb-0",
+            false: "",
+        },
+    },
+    defaultVariants: {orientation: "horizontal", divided: false},
+});
+
+/** One term with its details (a `<div>`, which `<dl>` allows around each group). */
+function DescriptionItem({className, ...props}: React.ComponentProps<"div">) {
+    const {orientation, divided} = React.useContext(DescriptionListContext);
+    return (
+        <div
+            data-slot="description-item"
+            data-orientation={orientation}
+            data-divided={divided ? "" : undefined}
+            className={cn(descriptionItemVariants({orientation, divided}), className)}
+            {...props}
+        />
+    );
+}
+
+function DescriptionTerm({className, ...props}: React.ComponentProps<"dt">) {
+    return (
+        <dt
+            data-slot="description-term"
+            className={cn("min-w-0 font-alt text-xs text-muted-foreground", className)}
+            {...props}
+        />
+    );
+}
+
+/** The value. Inline content (a status dot, a copy button) sits on one row with `flex items-center gap-2`. */
+function DescriptionDetails({className, ...props}: React.ComponentProps<"dd">) {
+    return <dd data-slot="description-details" className={cn("min-w-0 text-foreground", className)} {...props} />;
+}
+
+export {
+    DescriptionDetails,
+    DescriptionItem,
+    descriptionItemVariants,
+    DescriptionList,
+    descriptionListVariants,
+    DescriptionTerm,
+};
+export type {DescriptionListOrientation, DescriptionListProps};

package/src/components/locale.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Locale for the kit's dates and times (Calendar, DatePicker, TimeInput, TimeSelect), all formatted with
+ * `Intl`. Resolution: a component's own `locale` prop › the nearest `LocaleProvider` › the browser's
+ * language. Hydration-safe: the server render and the hydration pass use `FALLBACK_LOCALE` (the browser's
+ * language is unknown on the server), then the client re-renders with the browser's. To get it right from
+ * the first paint in SSR, pass the request's locale (Accept-Language, user setting) to `LocaleProvider`.
+ */
+const FALLBACK_LOCALE = "en-US";
+
+const LocaleContext = React.createContext<string | undefined>(undefined);
+
+function LocaleProvider({locale, children}: {locale?: string; children: React.ReactNode}) {
+    return <LocaleContext.Provider value={locale}>{children}</LocaleContext.Provider>;
+}
+
+function browserLocale(): string | null {
+    try {
+        const tag = navigator.languages?.[0] ?? navigator.language;
+        return tag && Intl.DateTimeFormat.supportedLocalesOf(tag).length ? tag : null;
+    } catch {
+        return null;
+    }
+}
+
+function subscribe(onChange: () => void) {
+    window.addEventListener("languagechange", onChange);
+    return () => window.removeEventListener("languagechange", onChange);
+}
+
+/** The locale to format with: `explicit` › LocaleProvider › browser (after hydration) › `FALLBACK_LOCALE`. */
+function useLocale(explicit?: string): string {
+    const provided = React.useContext(LocaleContext);
+    const browser = React.useSyncExternalStore(subscribe, browserLocale, () => null);
+    return explicit ?? provided ?? browser ?? FALLBACK_LOCALE;
+}
+
+// Regions whose week starts on Sunday or Saturday (CLDR), for engines without Intl.Locale#getWeekInfo.
+const SUNDAY = new Set(
+    "AG AS AU BD BR BS BT BW BZ CA CN CO DM DO ET GT GU HK HN ID IL IN JM JP KE KH KR LA MH MM MO MT MX MZ NI NP PA PE PH PK PR PT PY SA SG SV TH TT TW UM US VE VI WS YE ZA ZW".split(
+        " ",
+    ),
+);
+const SATURDAY = new Set("AE AF BH DJ DZ EG IQ IR JO KW LY OM QA SD SY".split(" "));
+
+/** First day of the week for a locale: 0 Sunday … 6 Saturday. */
+function weekStart(locale: string): 0 | 1 | 6 {
+    try {
+        const loc = new Intl.Locale(locale) as Intl.Locale & {
+            getWeekInfo?: () => {firstDay: number};
+            weekInfo?: {firstDay: number};
+        };
+        const info = loc.getWeekInfo?.() ?? loc.weekInfo;
+        if (info) {
+            return (info.firstDay % 7) as 0 | 1 | 6;
+        }
+        const region = loc.maximize().region ?? "";
+        return SUNDAY.has(region) ? 0 : SATURDAY.has(region) ? 6 : 1;
+    } catch {
+        return 0;
+    }
+}
+
+export {FALLBACK_LOCALE, LocaleProvider, useLocale, weekStart};

package/src/components/popover.tsx

@@ -20,9 +20,10 @@ function PopoverContent({
     alignOffset = 0,
     side = "bottom",
     sideOffset = 4,
+    anchor,
     ...props
 }: PopoverPrimitive.Popup.Props &
-    Pick<PopoverPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">) {
+    Pick<PopoverPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset" | "anchor">) {
     return (
         <PopoverPrimitive.Portal container={usePortalContainer()}>
             <PopoverPrimitive.Positioner
@@ -30,6 +31,7 @@ function PopoverContent({
                 alignOffset={alignOffset}
                 side={side}
                 sideOffset={sideOffset}
+                anchor={anchor}
                 className="isolate z-50"
             >
                 <PopoverPrimitive.Popup

package/src/components/progress.tsx

@@ -2,8 +2,10 @@
 
 import {Progress as ProgressPrimitive} from "@base-ui/react/progress";
 import {type Color, colorVariants} from "@repraze/kernelkit/lib/color";
+import {placeholderFill} from "@repraze/kernelkit/lib/recipes";
 import {cva} from "class-variance-authority";
 import {cn} from "cn";
+import type * as React from "react";
 
 /** Root of a progress or meter: label + value on one row, track below. Sets the color vars. */
 const progressVariants = cva("group/progress flex w-full flex-wrap items-center gap-x-3 gap-y-1.5", {
@@ -29,24 +31,44 @@ interface ProgressProps extends Omit<ProgressPrimitive.Root.Props, "color"> {
     color?: Color | null;
     /** Track height: sm `h-1`, default `h-1.5`, lg `h-2`. */
     size?: ProgressSize | null;
+    /** `bar`: one pill track. `segmented`: a row of cells, lit in order; a wave runs through them while indeterminate. */
+    variant?: "bar" | "segmented";
+    /** `segmented` only: number of cells. */
+    segments?: number;
 }
 
-function Progress({className, children, value, color, size, ...props}: ProgressProps) {
+function Progress({
+    className,
+    children,
+    value,
+    color,
+    size,
+    variant = "bar",
+    segments = 12,
+    max = 100,
+    ...props
+}: ProgressProps) {
     const resolvedColor = color ?? "primary";
     const resolvedSize = size ?? "default";
     return (
         <ProgressPrimitive.Root
             value={value}
+            max={max}
             data-slot="progress"
+            data-variant={variant}
             data-color={resolvedColor}
             data-size={resolvedSize}
             className={cn(progressVariants({color: resolvedColor, size: resolvedSize}), className)}
             {...props}
         >
             {children}
-            <ProgressTrack>
-                <ProgressIndicator />
-            </ProgressTrack>
+            {variant === "segmented" ? (
+                <ProgressSegments segments={segments} lit={value == null ? null : (value / max) * segments} />
+            ) : (
+                <ProgressTrack>
+                    <ProgressIndicator />
+                </ProgressTrack>
+            )}
         </ProgressPrimitive.Root>
     );
 }
@@ -72,6 +94,49 @@ function ProgressIndicator({className, ...props}: ProgressPrimitive.Indicator.Pr
     );
 }
 
+/** Negative delays so every cell is mid-cycle on the first frame (no dead start). */
+const cellDelay = (i: number, n: number) => ({animationDelay: `${-((n - i) * 1.2) / n}s`});
+
+/**
+ * The `segmented` track: cells in the fill tier, unlit ones on the placeholder fill (§4). `lit` is how many
+ * cells are on (fractional rounds), `null` runs the indeterminate wave. Reduced motion slows the wave down.
+ */
+function ProgressSegments({
+    segments,
+    lit,
+    className,
+    ...props
+}: React.ComponentProps<"div"> & {segments: number; lit: number | null}) {
+    const on = lit === null ? -1 : Math.round(Math.min(segments, Math.max(0, lit)));
+    return (
+        <div
+            data-slot="progress-segments"
+            aria-hidden
+            className={cn(
+                "flex h-1.5 w-full gap-0.5 group-data-[size=lg]/progress:h-2 group-data-[size=sm]/progress:h-1",
+                className,
+            )}
+            {...props}
+        >
+            {Array.from({length: segments}, (_, i) => (
+                <span
+                    key={i}
+                    data-lit={on < 0 || i < on ? "" : undefined}
+                    className={cn(
+                        "h-full flex-1 rounded-xs transition-colors duration-300 motion-reduce:transition-none",
+                        on < 0
+                            ? "animate-loader-cell bg-(--c-fill) motion-reduce:[animation-duration:3s]"
+                            : i < on
+                              ? "bg-(--c-fill)"
+                              : placeholderFill,
+                    )}
+                    style={on < 0 ? cellDelay(i, segments) : undefined}
+                />
+            ))}
+        </div>
+    );
+}
+
 function ProgressLabel({className, ...props}: ProgressPrimitive.Label.Props) {
     return (
         <ProgressPrimitive.Label
@@ -97,6 +162,7 @@ export {
     ProgressIndicator,
     progressIndicatorClass,
     ProgressLabel,
+    ProgressSegments,
     ProgressTrack,
     progressTrackClass,
     ProgressValue,

package/src/components/search-dialog.tsx

@@ -84,4 +84,17 @@ function SearchFooter({className, ...props}: React.ComponentProps<"div">) {
     );
 }
 
-export {SearchDialog, SearchFooter, SearchItem};
+/**
+ * The suite's search filter for `<Command filter={substringFilter}>`: a plain substring match (prefix
+ * matches rank first). cmdk's default fuzzy match finds "t…a…b" in nearly every title.
+ */
+function substringFilter(value: string, search: string, keywords?: string[]) {
+    const haystack = [value, ...(keywords ?? [])].join(" ").toLowerCase();
+    const needle = search.trim().toLowerCase();
+    if (haystack.startsWith(needle)) {
+        return 1;
+    }
+    return haystack.includes(needle) ? 0.5 : 0;
+}
+
+export {SearchDialog, SearchFooter, SearchItem, substringFilter};

package/src/components/search-trigger.tsx

@@ -51,7 +51,10 @@ interface SearchTriggerProps extends React.ComponentProps<typeof Button> {
     children?: React.ReactNode;
 }
 
-/** Header search button: icon, placeholder, OS-aware shortcut. Same 32px height as the header's icon buttons. Open your dialog in `onClick`. */
+/**
+ * Header search button: icon, placeholder, OS-aware shortcut. Same 32px height as the header's icon buttons. Open your dialog in `onClick`.
+ * The keycap gets the same inset on the right as top/bottom (32 - 20 = 6px each side, border included).
+ */
 function SearchTrigger({children = "Search…", className, ...props}: SearchTriggerProps) {
     const mod = useModKey();
     return (
@@ -59,7 +62,10 @@ function SearchTrigger({children = "Search…", className, ...props}: SearchTrig
             variant="outline"
             aria-label="Search"
             data-slot="search-trigger"
-            className={cn("w-8 justify-start px-0 text-muted-foreground sm:w-48 sm:px-2.5 md:w-56", className)}
+            className={cn(
+                "w-8 justify-start px-0 text-muted-foreground sm:w-48 sm:pr-1.25 sm:pl-2.5 md:w-56",
+                className,
+            )}
             {...props}
         >
             <SearchIcon data-icon="inline-start" className="mx-auto sm:mx-0" />

package/src/components/shimmer.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import {mergeProps} from "@base-ui/react/merge-props";
+import {useRender} from "@base-ui/react/use-render";
+import {cn} from "cn";
+
+interface ShimmerProps extends useRender.ComponentProps<"span"> {
+    /** Seconds per sweep. */
+    duration?: number;
+}
+
+/**
+ * Text with a highlight band sweeping across it ("Thinking…", "Indexing files…"). Muted text, foreground
+ * band. Reduced motion: plain muted text.
+ */
+function Shimmer({render, duration, className, style, ...props}: ShimmerProps) {
+    return useRender({
+        defaultTagName: "span",
+        props: mergeProps<"span">(
+            {
+                className: cn(
+                    "inline-block animate-shimmer bg-linear-to-r from-muted-foreground from-40% via-foreground via-50% to-muted-foreground to-60% bg-size-[250%_100%] bg-clip-text text-transparent",
+                    "motion-reduce:animate-none motion-reduce:bg-none motion-reduce:text-muted-foreground",
+                    className,
+                ),
+                style: duration ? {animationDuration: `${duration}s`, ...style} : style,
+            },
+            props,
+        ),
+        render,
+        state: {slot: "shimmer"},
+    });
+}
+
+export {Shimmer};
+export type {ShimmerProps};

package/src/components/spinner.tsx

@@ -1,42 +1,145 @@
 "use client";
 
+import {type Color, colorVariants} from "@repraze/kernelkit/lib/color";
+import {placeholderFill} from "@repraze/kernelkit/lib/recipes";
 import {cva, type VariantProps} from "class-variance-authority";
 import {cn} from "cn";
 import {Loader2Icon} from "lucide-react";
+import * as React from "react";
 
-/** Sizes follow the icon column of §4 so a spinner can replace an icon in place. */
-const spinnerVariants = cva(
-    // reduced motion: slow the spin down rather than freeze it, a frozen spinner reads as a glyph
-    "shrink-0 animate-spin text-current motion-reduce:[animation-duration:2.5s]",
-    {
-        variants: {
-            size: {
-                xs: "size-3",
-                sm: "size-3.5",
-                default: "size-4",
-                lg: "size-5",
-                xl: "size-6",
-            },
+/**
+ * Sizes follow the icon column of §4 so a spinner can replace an icon in place. Each size also sets the
+ * vars the techy variants draw with: `--ls` (box), `--lc`/`--lg` (dot cell and gap, whole pixels so cells
+ * stay crisp) and `--lb` (bar width).
+ */
+const spinnerVariants = cva("relative inline-flex shrink-0 items-center justify-center align-middle text-current", {
+    variants: {
+        variant: {
+            // reduced motion: slow the spin down rather than freeze it, a frozen spinner reads as a glyph
+            ring: "size-(--ls) animate-spin motion-reduce:[animation-duration:2.5s]",
+            dots: "size-(--ls)",
+            braille: "h-(--ls) w-(--ls) items-start overflow-hidden font-mono text-(length:--ls) leading-none",
+            // hc: the placeholder fill is the dark border colour there, so the box becomes an outline instead
+            scan: `size-(--ls) overflow-hidden rounded-box ${placeholderFill} hc:bg-transparent hc:shadow-[inset_0_0_0_1px_var(--border)]`,
+            blink: "h-(--ls) w-[calc(var(--ls)/2)]",
+            bars: "size-(--ls) justify-between",
+        },
+        size: {
+            xs: "[--lb:2px] [--lc:3px] [--lg:1px] [--ls:0.75rem]",
+            sm: "[--lb:2px] [--lc:4px] [--lg:1px] [--ls:0.875rem]",
+            default: "[--lb:3px] [--lc:4px] [--lg:2px] [--ls:1rem]",
+            lg: "[--lb:3px] [--lc:6px] [--lg:1px] [--ls:1.25rem]",
+            xl: "[--lb:4px] [--lc:6px] [--lg:3px] [--ls:1.5rem]",
         },
-        defaultVariants: {size: "default"},
     },
-);
+    defaultVariants: {variant: "ring", size: "default"},
+});
+
+type SpinnerVariant = NonNullable<VariantProps<typeof spinnerVariants>["variant"]>;
+
+/** Every animated part: slower, not frozen, under reduced motion. */
+const slow = "motion-reduce:[animation-duration:3s]";
 
-interface SpinnerProps extends React.ComponentProps<"svg">, VariantProps<typeof spinnerVariants> {}
+const BRAILLE = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
+
+/** Negative delays so every cell is mid-cycle on the first frame (no dead start). */
+const delay = (i: number, n: number, duration: number) => ({animationDelay: `${-((n - i) * duration) / n}s`});
+
+function SpinnerParts({variant}: {variant: SpinnerVariant}) {
+    switch (variant) {
+        case "ring":
+            return <Loader2Icon aria-hidden className="size-full" />;
+        case "dots":
+            return (
+                <span
+                    data-slot="spinner-grid"
+                    className="grid grid-cols-[repeat(3,var(--lc))] grid-rows-[repeat(3,var(--lc))] gap-(--lg)"
+                >
+                    {Array.from({length: 9}, (_, i) => (
+                        <span
+                            key={i}
+                            className={cn("animate-loader-cell rounded-pill bg-current", slow)}
+                            // diagonal wave from the top-left corner
+                            style={delay(4 - (Math.floor(i / 3) + (i % 3)), 5, 1.2)}
+                        />
+                    ))}
+                </span>
+            );
+        case "braille":
+            return (
+                <span aria-hidden className={cn("flex animate-loader-braille flex-col", slow)}>
+                    {[...BRAILLE].map((g) => (
+                        <span key={g} className="h-(--ls) leading-(--ls)">
+                            {g}
+                        </span>
+                    ))}
+                </span>
+            );
+        case "scan":
+            return (
+                <span
+                    className={cn(
+                        "absolute inset-0 animate-loader-scan border-e-2 border-current bg-linear-to-r from-transparent to-current/40",
+                        slow,
+                    )}
+                />
+            );
+        case "blink":
+            return <span className={cn("size-full animate-loader-blink bg-current", slow)} />;
+        case "bars":
+            return Array.from({length: 4}, (_, i) => (
+                <span
+                    key={i}
+                    className={cn("h-full w-(--lb) origin-bottom animate-loader-bars rounded-box bg-current", slow)}
+                    style={delay((i * 2 + Math.floor(i / 2)) % 4, 4, 0.9)}
+                />
+            ));
+    }
+}
+
+const SpinnerContext = React.createContext<SpinnerVariant>("ring");
+
+/**
+ * Sets the default `variant` of every Spinner below it, including the ones the kit renders itself
+ * (tree lazy rows, stepper, file upload, toasts): one switch for the whole app's loading look.
+ */
+function SpinnerProvider({variant, children}: {variant: SpinnerVariant; children: React.ReactNode}) {
+    return <SpinnerContext.Provider value={variant}>{children}</SpinnerContext.Provider>;
+}
+
+interface SpinnerProps
+    extends Omit<React.ComponentProps<"span">, "color" | "children">, VariantProps<typeof spinnerVariants> {
+    /** Color from the §2 axis; defaults to `currentColor`. */
+    color?: Color;
+}
 
-/** Indeterminate loading indicator. Inherits `currentColor`; announces itself as a status. */
-function Spinner({className, size, ...props}: SpinnerProps) {
+/**
+ * Indeterminate loading indicator at icon size: a spinning ring, or a techy variant (dot matrix, braille,
+ * scan line, block cursor, equalizer bars). Inherits `currentColor`; announces itself as a status. The
+ * default variant comes from the nearest `SpinnerProvider`.
+ */
+function Spinner({variant, size, color, className, ...props}: SpinnerProps) {
+    const fallback = React.useContext(SpinnerContext);
+    const resolved = variant ?? fallback;
     return (
-        <Loader2Icon
+        <span
             data-slot="spinner"
+            data-variant={resolved}
             data-size={size ?? "default"}
+            data-color={color}
             role="status"
             aria-label="Loading"
-            className={cn(spinnerVariants({size}), className)}
+            className={cn(
+                spinnerVariants({variant: resolved, size}),
+                color && cn(colorVariants[color], "text-(--c)"),
+                className,
+            )}
             {...props}
-        />
+        >
+            <SpinnerParts variant={resolved} />
+        </span>
     );
 }
 
-export {Spinner, spinnerVariants};
-export type {SpinnerProps};
+export {Spinner, SpinnerProvider, spinnerVariants};
+export type {SpinnerProps, SpinnerVariant};