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

package/src/hooks/use-time-format.ts

@@ -0,0 +1,72 @@
+"use client";
+
+import {useLocale} from "@repraze/kernelkit/components/locale";
+import * as React from "react";
+
+/** `"auto"` follows the locale: 12 in en-US, 24 in fr-FR, en-GB or ja-JP. */
+type HourCyclePreference = 12 | 24 | "auto";
+
+interface TimeFormat {
+    locale: string;
+    hourCycle: 12 | 24;
+    /** Localized day periods: "AM" / "PM" in en-US, "a.m." / "p.m." in en-CA, "오전" / "오후" in ko. */
+    am: string;
+    pm: string;
+    /** The day period comes before the hour (ko, zh). */
+    periodFirst: boolean;
+    /** "09:30" (24h) or "9:30 AM" / "오전 9:30" (12h), in the locale's own pattern. */
+    format: (minutes: number) => string;
+    /** A two-digit segment in the locale's digits: "05", "٠٥" in ar-EG. */
+    digits: (n: number) => string;
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/**
+ * Hour cycle, day-period labels and a formatter, from `Intl` for the resolved locale (see `useLocale`:
+ * prop › LocaleProvider › browser, hydration-safe). An explicit 12 / 24 overrides the locale's cycle.
+ */
+function useTimeFormat(preference: HourCyclePreference = "auto", explicitLocale?: string): TimeFormat {
+    const locale = useLocale(explicitLocale);
+    return React.useMemo(() => {
+        let hourCycle: 12 | 24 = preference === "auto" ? 24 : preference;
+        let am = "AM";
+        let pm = "PM";
+        let periodFirst = false;
+        let formatter: Intl.DateTimeFormat | null = null;
+        let numbers: Intl.NumberFormat | null = null;
+        try {
+            numbers = new Intl.NumberFormat(locale, {minimumIntegerDigits: 2, useGrouping: false});
+            if (preference === "auto") {
+                const hc = new Intl.DateTimeFormat(locale, {hour: "numeric"}).resolvedOptions().hourCycle;
+                hourCycle = hc === "h11" || hc === "h12" ? 12 : 24;
+            }
+            const f = new Intl.DateTimeFormat(locale, {hour: "numeric", hourCycle: "h12"});
+            const parts = (h: number) => f.formatToParts(new Date(2000, 0, 1, h));
+            am = parts(9).find((p) => p.type === "dayPeriod")?.value ?? am;
+            pm = parts(21).find((p) => p.type === "dayPeriod")?.value ?? pm;
+            const types = parts(9).map((p) => p.type);
+            periodFirst = types.includes("dayPeriod") && types.indexOf("dayPeriod") < types.indexOf("hour");
+            formatter = new Intl.DateTimeFormat(locale, {
+                hour: hourCycle === 24 ? "2-digit" : "numeric",
+                minute: "2-digit",
+                hourCycle: hourCycle === 24 ? "h23" : "h12",
+            });
+        } catch {
+            formatter = null;
+        }
+        const format = (minutes: number) => {
+            const h = Math.floor(minutes / 60);
+            const m = minutes % 60;
+            if (formatter) {
+                return formatter.format(new Date(2000, 0, 1, h, m));
+            }
+            return hourCycle === 24 ? `${pad(h)}:${pad(m)}` : `${h % 12 || 12}:${pad(m)} ${h < 12 ? am : pm}`;
+        };
+        const digits = (n: number) => (numbers ? numbers.format(n) : pad(n));
+        return {locale, hourCycle, am, pm, periodFirst, format, digits};
+    }, [preference, locale]);
+}
+
+export {useTimeFormat};
+export type {HourCyclePreference, TimeFormat};

package/src/lib/color.ts

@@ -6,9 +6,13 @@
  * - `--c-tint` opaque wash behind foreground text
  * - `--c-fill` / `--c-fill-fg` vivid solid surface and its text (TermiColor "fills are the brand":
  *   in light mode the text tier is darkened for contrast, the fill tier stays vivid)
+ * - `--c-soft-text` text on a wash of its own color (soft variants, soft status surfaces): `--c` mixed 25%
+ *   toward the foreground with its chroma restored, which keeps hue and saturation and passes WCAG AA
+ *   4.5:1 for every color, in light, dark and both hc modes, on background, card and popover (plain `--c`
+ *   on its own wash fell to ~3.6)
  *
  * Spread `colorVariants` into a cva `variants.color` map, then write variants against the vars
- * (`bg-(--c) text-(--c-fg)`, `bg-(--c)/12 text-(--c)`, …).
+ * (`bg-(--c) text-(--c-fg)`, `bg-(--c)/12 text-(--c-soft-text)`, …).
  */
 
 export const STATUS_COLORS = ["danger", "warning", "success", "info"] as const;
@@ -17,8 +21,17 @@ export const COLORS = ["neutral", "primary", ...STATUS_COLORS, ...HUES] as const
 
 export type Color = (typeof COLORS)[number];
 
+/**
+ * Derived from `--c` on the same element, so it is set alongside every color (a :root rule would see no `--c`).
+ * The mix toward the (neutral) foreground sets the lightness for contrast but also scales chroma by 0.75, so
+ * where relative color syntax is supported the chroma is multiplied back by 1/0.75: same lightness and hue,
+ * the original saturation (≥ 5.08:1 everywhere, vs ≥ 5.68 for the plain mix kept as the fallback).
+ */
+const SOFT_TEXT =
+    "[--c-soft-text:color-mix(in_oklab,var(--c)_75%,var(--foreground))] supports-[color:oklch(from_red_l_c_h)]:[--c-soft-text:oklch(from_color-mix(in_oklab,var(--c)_75%,var(--foreground))_l_calc(c*1.333)_h)]";
+
 // Literal strings on purpose: Tailwind only generates classes it can read in the source.
-export const colorVariants: Record<Color, string> = {
+const baseColorVariants: Record<Color, string> = {
     neutral:
         "[--c:var(--foreground)] [--c-fg:var(--background)] [--c-tint:var(--secondary)] [--c-fill:var(--foreground)] [--c-fill-fg:var(--background)]",
     primary:
@@ -39,6 +52,10 @@ export const colorVariants: Record<Color, string> = {
     pink: "[--c:var(--tc-pink)] [--c-fg:var(--tc-pink-on)] [--c-tint:var(--tc-pink-tint)] [--c-fill:var(--tc-pink-fill)] [--c-fill-fg:var(--tc-pink-on-fill)]",
 };
 
+export const colorVariants = Object.fromEntries(
+    Object.entries(baseColorVariants).map(([color, vars]) => [color, `${vars} ${SOFT_TEXT}`]),
+) as Record<Color, string>;
+
 /** Every color except neutral: the ones whose outline/ghost variants are tinted. */
 export const TINTED_COLORS = COLORS.filter((c) => c !== "neutral");
 

package/src/lib/recipes.ts

@@ -40,9 +40,13 @@ export const listLabel = "px-2 py-1.5 text-xs font-medium text-muted-foreground"
 /** Separator inside a popup or list. */
 export const listSeparator = "-mx-1 my-1 h-px bg-border";
 
-/** Modal backdrop for dialog, alert dialog, sheet, drawer. */
+/**
+ * Modal backdrop for dialog, alert dialog, sheet, drawer. A transition on Base UI's starting/ending styles,
+ * not a keyframe: the backdrop stays mounted until the slower panel finishes, and a finished keyframe
+ * (no fill) snapped it back to full dim and blur for that wait, a flash on close.
+ */
 export const backdrop =
-    "fixed inset-0 isolate z-50 bg-black/40 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0"; // lint-design-ignore: scrim is not a role
+    "fixed inset-0 isolate z-50 bg-black/40 transition-opacity duration-150 ease-out motion-reduce:transition-none supports-backdrop-filter:backdrop-blur-xs data-starting-style:opacity-0 data-ending-style:opacity-0"; // lint-design-ignore: scrim is not a role
 
 /** Title in cards, dialogs, sheets, popovers, empty states, alerts (§5). */
 export const heading = "font-heading font-medium tracking-tight";
@@ -55,14 +59,16 @@ export const selectedRow = "bg-accent text-accent-foreground shadow-[inset_2px_0
 
 /**
  * Status surface shared by Alert and Callout (§2): one `soft` / `outline` axis, same values in both.
- * Expects a color variant (`--c`, `--c-tint`) on the same element. Neutral swaps the hue border for the
+ * Expects a color variant (`--c`, `--c-tint`) on the same element. Text, icons and links on it use
+ * `--c-text`, which each variant sets to the color that passes 4.5:1 on that surface. Neutral swaps the hue border for the
  * plain border on a card surface (`statusSurfaceNeutral`).
  */
 export const statusSurface = {
-    // status tint behind foreground text; the hue lives in the border, icon and accents (TermiColor rule)
-    soft: "border-(--c)/30 bg-(--c-tint) hc:border-(--c)",
+    // status tint behind foreground text; the hue lives in the border, icon and accents (TermiColor rule).
+    // `--c-text` is the hue for text, icons and links on it: on the tint it is the soft text (4.5:1)
+    soft: "border-(--c)/30 bg-(--c-tint) hc:border-(--c) [--c-text:var(--c-soft-text)]",
     // no wash: card surface with a hue border, for dense layouts
-    outline: "border-(--c)/50 bg-card hc:border-(--c)",
+    outline: "border-(--c)/50 bg-card hc:border-(--c) [--c-text:var(--c)]",
 } as const;
 
-export const statusSurfaceNeutral = "border-border bg-card hc:border-border";
+export const statusSurfaceNeutral = "border-border bg-card hc:border-border [--c-text:var(--c)]";

package/src/site/suite-header.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import {Button} from "@repraze/kernelkit/components/button";
+import {type SearchHandler, SearchRelay, SearchTrigger} from "@repraze/kernelkit/components/search-trigger";
 import {Separator} from "@repraze/kernelkit/components/separator";
 import {
     SiteHeader,
@@ -13,7 +14,7 @@ import {
 } from "@repraze/kernelkit/components/site-header";
 import {ThemeMenu} from "@repraze/kernelkit/components/theme-menu";
 import type * as React from "react";
-import {useEffect, useState} from "react";
+import {useEffect, useRef, useState} from "react";
 
 import {GithubIcon} from "./github-icon";
 
@@ -36,7 +37,10 @@ export interface SuiteHeaderProps {
     nav: SuiteNavItem[];
     /** Accessible name of the nav (default "Main"). */
     navLabel?: string;
-    /** The search (DocsSearch, or the site's own), before the separator. */
+    /**
+     * The search (DocsSearch, or the site's own built on SearchTrigger), before the separator. Below `md`
+     * it moves to the top of the phone menu: a full-width trigger there opens the same dialog.
+     */
     search?: React.ReactNode;
     /** Replaces the default `<ThemeMenu />`. */
     themeMenu?: React.ReactNode;
@@ -66,6 +70,7 @@ export function SuiteHeader({
 }: SuiteHeaderProps) {
     const [menuOpen, setMenuOpen] = useState(false);
     useEffect(() => setMenuOpen(false), [locationKey]);
+    const openSearch = useRef<SearchHandler | null>(null);
 
     const navLinks = nav.map((item) => (
         <SiteNavLink
@@ -82,6 +87,18 @@ export function SuiteHeader({
         <SiteHeader>
             <SiteHeaderContent>
                 <SiteHeaderMenu title={brand} open={menuOpen} onOpenChange={setMenuOpen}>
+                    {search ? (
+                        <div className="px-2 pt-2">
+                            <SearchTrigger
+                                expanded
+                                aria-label="Search"
+                                onClick={(event) => {
+                                    setMenuOpen(false);
+                                    openSearch.current?.(event);
+                                }}
+                            />
+                        </div>
+                    ) : null}
                     <nav aria-label={navLabel} className="flex flex-col gap-1 px-2 pt-2">
                         {navLinks}
                     </nav>
@@ -92,10 +109,14 @@ export function SuiteHeader({
                 </SiteHeaderBrand>
                 <SiteNav aria-label={navLabel}>{navLinks}</SiteNav>
                 <SiteHeaderActions>
-                    {search}
+                    {search ? (
+                        <SearchRelay handler={openSearch}>
+                            <div className="hidden md:contents">{search}</div>
+                        </SearchRelay>
+                    ) : null}
                     <Separator
                         orientation="vertical"
-                        className="mx-1 hidden data-vertical:h-5 data-vertical:self-center sm:block"
+                        className="mx-1 hidden data-vertical:h-5 data-vertical:self-center md:block"
                     />
                     {themeMenu ?? <ThemeMenu />}
                     {repository ? (

package/src/styles/kernelkit.css

@@ -187,6 +187,62 @@
             translate: 250% 0;
         }
     }
+    /* Spinner variants (spinner.tsx) and segmented Progress: cells light up and fade, a glyph strip steps (braille), a cursor
+       blinks, equalizer bars bounce, a scan line sweeps. Delays are set per cell. */
+    --animate-loader-cell: kk-loader-cell 1.2s ease-in-out infinite;
+    @keyframes kk-loader-cell {
+        0%,
+        100% {
+            opacity: 0.2;
+        }
+        30% {
+            opacity: 1;
+        }
+        60% {
+            opacity: 0.2;
+        }
+    }
+    --animate-loader-braille: kk-loader-braille 0.8s steps(10) infinite;
+    @keyframes kk-loader-braille {
+        to {
+            translate: 0 -100%;
+        }
+    }
+    --animate-loader-blink: kk-loader-blink 1s step-end infinite;
+    @keyframes kk-loader-blink {
+        50% {
+            opacity: 0;
+        }
+    }
+    --animate-loader-bars: kk-loader-bars 0.9s ease-in-out infinite;
+    @keyframes kk-loader-bars {
+        0%,
+        100% {
+            scale: 1 0.3;
+        }
+        50% {
+            scale: 1 1;
+        }
+    }
+    --animate-loader-scan: kk-loader-scan 1.4s linear infinite;
+    @keyframes kk-loader-scan {
+        from {
+            translate: -100% 0;
+        }
+        to {
+            translate: 100% 0;
+        }
+    }
+    /* Shimmer: a highlight band sweeping across clipped text. */
+    --animate-shimmer: kk-shimmer 2s linear infinite;
+    @keyframes kk-shimmer {
+        from {
+            background-position: 100% 0;
+        }
+        to {
+            background-position: 0% 0;
+        }
+    }
     /* Boxes under 20px (checkbox, kbd keys, tiny chips): capped so they never turn into circles at xl. */
     --radius-box: min(calc(var(--kk-radius) * 0.5), 0.25rem);