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

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-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};