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

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

@@ -55,14 +55,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/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);