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

package/src/components/theme-menu.tsx

@@ -0,0 +1,243 @@
+"use client";
+
+import {Button} from "@repraze/kernelkit/components/button";
+import {Label} from "@repraze/kernelkit/components/label";
+import {
+    Popover,
+    PopoverContent,
+    PopoverHeader,
+    PopoverTitle,
+    PopoverTrigger,
+} from "@repraze/kernelkit/components/popover";
+import {Switch} from "@repraze/kernelkit/components/switch";
+import {ToggleGroup, ToggleGroupItem} from "@repraze/kernelkit/components/toggle-group";
+import {Tooltip, TooltipContent, TooltipTrigger} from "@repraze/kernelkit/components/tooltip";
+import {type Accent, ACCENTS, type Mode, RADII, type Radius, useTheme} from "@repraze/kernelkit/provider";
+import {cn} from "cn";
+import {CheckIcon, type LucideIcon, MonitorIcon, MoonIcon, RotateCcwIcon, SunIcon} from "lucide-react";
+import * as React from "react";
+
+/** Mode choices in display order, with the icon the trigger shows for each. */
+const THEME_MODES: readonly {value: Mode; label: string; icon: LucideIcon}[] = [
+    {value: "light", label: "Light", icon: SunIcon},
+    {value: "dark", label: "Dark", icon: MoonIcon},
+    {value: "system", label: "System", icon: MonitorIcon},
+];
+
+const modeOption = (mode: Mode) => THEME_MODES.find((m) => m.value === mode) ?? THEME_MODES[2]!;
+
+/** The icon for the chosen mode (not the resolved one): sun, moon, or monitor for "system". */
+function ThemeModeIcon({mode, ...props}: {mode?: Mode} & React.ComponentProps<LucideIcon>) {
+    const theme = useTheme();
+    const Icon = modeOption(mode ?? theme.mode).icon;
+    return <Icon data-slot="theme-mode-icon" {...props} />;
+}
+
+/** Light / dark / system as a segmented control. */
+function ThemeModePicker({className}: {className?: string}) {
+    const theme = useTheme();
+    return (
+        <ToggleGroup
+            data-slot="theme-mode-picker"
+            aria-label="Mode"
+            variant="outline"
+            size="sm"
+            value={[theme.mode]}
+            onValueChange={(v) => v[0] && theme.setMode(v[0] as Mode)}
+            className={cn("w-full", className)}
+        >
+            {THEME_MODES.map(({value, label, icon: Icon}) => (
+                <ToggleGroupItem key={value} value={value} className="flex-1">
+                    <Icon /> {label}
+                </ToggleGroupItem>
+            ))}
+        </ToggleGroup>
+    );
+}
+
+/** Swatch per accent: the vivid fill tier, with that accent's own on-fill color for the check mark. */
+const swatch = (accent: Accent) => ({
+    background: `var(--tc-accent-${accent}-accent-fill)`,
+    color: `var(--tc-accent-${accent}-on-accent-fill)`,
+});
+
+/** The eight TermiColor accents as swatches; sets the theme's accent. */
+function ThemeAccentPicker({className}: {className?: string}) {
+    const theme = useTheme();
+    return (
+        <div
+            data-slot="theme-accent-picker"
+            role="group"
+            aria-label="Accent"
+            className={cn("grid grid-cols-8 gap-1.5", className)}
+        >
+            {ACCENTS.map((accent) => {
+                const on = theme.accent === accent;
+                return (
+                    <Tooltip key={accent}>
+                        <TooltipTrigger
+                            render={
+                                <button
+                                    type="button"
+                                    aria-label={accent}
+                                    aria-pressed={on}
+                                    onClick={() => theme.setAccent(accent)}
+                                    style={swatch(accent)}
+                                    className={cn(
+                                        "flex aspect-square items-center justify-center rounded-md outline-none",
+                                        "ring-offset-2 ring-offset-transparent transition-shadow duration-100 motion-reduce:transition-none",
+                                        "hover:ring-2 hover:ring-input focus-visible:ring-2 focus-visible:ring-ring",
+                                        on && "ring-2 ring-foreground hover:ring-foreground",
+                                    )}
+                                />
+                            }
+                        >
+                            {on ? <CheckIcon className="size-3.5" strokeWidth={3} /> : null}
+                        </TooltipTrigger>
+                        <TooltipContent className="capitalize">{accent}</TooltipContent>
+                    </Tooltip>
+                );
+            })}
+        </div>
+    );
+}
+
+/** The radius scale as a segmented control; sets the theme's radius. */
+function ThemeRadiusPicker({className}: {className?: string}) {
+    const theme = useTheme();
+    return (
+        <ToggleGroup
+            data-slot="theme-radius-picker"
+            aria-label="Radius"
+            variant="outline"
+            size="sm"
+            value={[theme.radius]}
+            onValueChange={(v) => v[0] && theme.setRadius(v[0] as Radius)}
+            className={cn("w-full", className)}
+        >
+            {RADII.map((radius) => (
+                <ToggleGroupItem key={radius} value={radius} className="flex-1 font-alt">
+                    {radius}
+                </ToggleGroupItem>
+            ))}
+        </ToggleGroup>
+    );
+}
+
+/** High contrast on/off, with its label. */
+function ThemeContrastSwitch({className}: {className?: string}) {
+    const theme = useTheme();
+    const id = React.useId();
+    return (
+        <div data-slot="theme-contrast-switch" className={cn("flex items-center justify-between gap-2", className)}>
+            <Label htmlFor={id}>High contrast</Label>
+            <Switch
+                id={id}
+                checked={theme.contrast === "high"}
+                onCheckedChange={(on) => theme.setContrast(on ? "high" : "normal")}
+            />
+        </div>
+    );
+}
+
+/** A labelled block inside the menu. */
+function ThemeMenuSection({
+    label,
+    children,
+    className,
+}: {
+    label: string;
+    children: React.ReactNode;
+    className?: string;
+}) {
+    return (
+        <div data-slot="theme-menu-section" className={cn("flex flex-col gap-2", className)}>
+            <span className="text-xs font-medium text-muted-foreground">{label}</span>
+            {children}
+        </div>
+    );
+}
+
+interface ThemeMenuProps extends Omit<React.ComponentProps<typeof Button>, "children" | "title"> {
+    /** Popover title. */
+    title?: React.ReactNode;
+    /** Extra controls, after the built-in ones and before Reset. */
+    children?: React.ReactNode;
+    /** Popover alignment against the trigger. */
+    align?: "start" | "center" | "end";
+    contentClassName?: string;
+}
+
+/**
+ * The suite's theme control (GUIDELINES §7b): one ghost icon button in `SiteHeaderActions` showing the
+ * chosen mode (sun, moon, monitor), opening a popover with mode, accent, high contrast, radius and a
+ * Reset to the provider's defaults. Reads and writes `useTheme()`, so it needs a `ThemeProvider`.
+ * Trigger props (`aria-label`, `className`, `data-*`) pass through to the button.
+ */
+function ThemeMenu({title = "Theme", children, align = "end", contentClassName, className, ...props}: ThemeMenuProps) {
+    const theme = useTheme();
+    const {defaults} = theme;
+    const isDefault =
+        theme.mode === defaults.mode &&
+        theme.accent === defaults.accent &&
+        theme.contrast === defaults.contrast &&
+        theme.radius === defaults.radius;
+    return (
+        <Popover>
+            <PopoverTrigger
+                render={
+                    <Button
+                        variant="ghost"
+                        size="icon"
+                        aria-label={`Theme: ${modeOption(theme.mode).label}`}
+                        data-slot="theme-menu-trigger"
+                        data-mode={theme.mode}
+                        className={className}
+                        {...props}
+                    />
+                }
+            >
+                <ThemeModeIcon />
+            </PopoverTrigger>
+            <PopoverContent data-slot="theme-menu-content" align={align} className={cn("w-72 gap-4", contentClassName)}>
+                <PopoverHeader>
+                    <PopoverTitle>{title}</PopoverTitle>
+                </PopoverHeader>
+                <ThemeMenuSection label="Mode">
+                    <ThemeModePicker />
+                </ThemeMenuSection>
+                <ThemeMenuSection label="Accent">
+                    <ThemeAccentPicker />
+                </ThemeMenuSection>
+                <ThemeContrastSwitch />
+                <ThemeMenuSection label="Radius">
+                    <ThemeRadiusPicker />
+                </ThemeMenuSection>
+                {children}
+                <div className="-mx-3 -mb-3 border-t border-border p-3">
+                    <Button
+                        variant="outline"
+                        size="sm"
+                        data-slot="theme-menu-reset"
+                        className="w-full"
+                        disabled={isDefault}
+                        onClick={theme.resetTheme}
+                    >
+                        <RotateCcwIcon data-icon="inline-start" /> Reset to defaults
+                    </Button>
+                </div>
+            </PopoverContent>
+        </Popover>
+    );
+}
+
+export {
+    ThemeAccentPicker,
+    ThemeContrastSwitch,
+    ThemeMenu,
+    ThemeMenuSection,
+    ThemeModeIcon,
+    ThemeModePicker,
+    ThemeRadiusPicker,
+};
+export type {ThemeMenuProps};

package/src/components/toc.tsx

@@ -35,7 +35,7 @@ function TocTitle({className, render, ...props}: useRender.ComponentProps<"p">)
     return useRender({
         defaultTagName: "p",
         props: mergeProps<"p">(
-            {className: cn("font-mono text-xs font-medium text-muted-foreground uppercase", className)},
+            {className: cn("font-alt text-xs font-medium text-muted-foreground uppercase", className)},
             props,
         ),
         render,

package/src/components/tooltip.tsx

@@ -39,15 +39,27 @@ function TooltipContent({
                 <TooltipPrimitive.Popup
                     data-slot="tooltip-content"
                     className={cn(
-                        // Inverted chip: max contrast against any surface, so it reads in high contrast too.
+                        // Popover-coloured chip: the popup surface and border, small mono text.
                         popupMotion,
-                        "z-50 inline-flex min-h-6 w-fit max-w-xs items-center gap-1.5 rounded-md bg-foreground px-2 py-1 text-xs text-background shadow-md shadow-(color:--shadow-color) has-data-[slot=kbd]:pr-1 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:h-4 **:data-[slot=kbd]:min-w-4 **:data-[slot=kbd]:rounded-xs",
+                        "z-50 inline-flex min-h-6 w-fit max-w-xs items-center gap-1.5 rounded-md border border-border bg-popover px-2 py-1 font-alt text-xs text-popover-foreground shadow-md shadow-(color:--shadow-color) has-data-[slot=kbd]:pr-1 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:h-4 **:data-[slot=kbd]:min-w-4 **:data-[slot=kbd]:rounded-xs",
                         className,
                     )}
                     {...props}
                 >
                     {children}
-                    <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-xs bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
+                    <TooltipPrimitive.Arrow
+                        className={cn(
+                            // A rotated square in the popup colours; the border sits on the two edges that face out,
+                            // centred on the popup's border line so the outline runs on without a seam.
+                            "z-50 size-2.5 rotate-45 rounded-xs border-border bg-popover",
+                            "data-[side=top]:-bottom-1.25 data-[side=top]:border-r data-[side=top]:border-b",
+                            "data-[side=bottom]:-top-1.25 data-[side=bottom]:border-t data-[side=bottom]:border-l",
+                            "data-[side=left]:top-1/2! data-[side=left]:-right-1.25 data-[side=left]:-translate-y-1/2 data-[side=left]:border-t data-[side=left]:border-r",
+                            "data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1.25 data-[side=inline-start]:-translate-y-1/2 data-[side=inline-start]:border-t data-[side=inline-start]:border-r",
+                            "data-[side=right]:top-1/2! data-[side=right]:-left-1.25 data-[side=right]:-translate-y-1/2 data-[side=right]:border-b data-[side=right]:border-l",
+                            "data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1.25 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-end]:border-b data-[side=inline-end]:border-l",
+                        )}
+                    />
                 </TooltipPrimitive.Popup>
             </TooltipPrimitive.Positioner>
         </TooltipPrimitive.Portal>

package/src/components/trace.tsx

@@ -67,7 +67,7 @@ function TraceDescription({className, ...props}: React.ComponentProps<"span">) {
     return (
         <span
             data-slot="trace-description"
-            className={cn("shrink-0 font-mono text-xs text-muted-foreground tabular-nums", className)}
+            className={cn("shrink-0 font-alt text-xs text-muted-foreground tabular-nums", className)}
             {...props}
         />
     );

package/src/lib/recipes.ts

@@ -23,9 +23,16 @@ export const popupSurface =
 export const popupMotion =
     "origin-(--transform-origin) duration-100 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 motion-reduce:animate-none";
 
+/**
+ * The sidebar's current-row indicator (§7c): a 2px accent pill inset on the row's left edge, hidden until
+ * the row's state shows it (`data-highlighted:after:opacity-100`, `data-active:after:opacity-100`...).
+ * The row keeps its own rounding on every corner.
+ */
+export const rowIndicator =
+    "after:pointer-events-none after:absolute after:top-1.5 after:bottom-1.5 after:left-0 after:w-0.5 after:rounded-pill after:bg-primary-text after:opacity-0";
+
 /** Row inside a popup or list: menu item, select item, command item (§4, §6). */
-export const listItem =
-    "relative flex min-h-8 cursor-default items-center gap-2 rounded-md px-2 py-1.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-muted-foreground data-highlighted:[&_svg:not([class*='text-'])]:text-accent-foreground";
+export const listItem = `${rowIndicator} data-highlighted:after:opacity-100 relative flex min-h-8 cursor-default items-center gap-2 rounded-md px-2 py-1.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-muted-foreground data-highlighted:[&_svg:not([class*='text-'])]:text-accent-foreground`;
 
 /** Group label inside a popup or list. */
 export const listLabel = "px-2 py-1.5 text-xs font-medium text-muted-foreground";
@@ -45,3 +52,17 @@ export const placeholderFill = "bg-foreground/10 hc:bg-border";
 
 /** Selected row (table, data table, code line, list): accent tint + 2px inset primary indicator (§6). */
 export const selectedRow = "bg-accent text-accent-foreground shadow-[inset_2px_0_0_var(--primary-text)]";
+
+/**
+ * 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
+ * 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)",
+    // no wash: card surface with a hue border, for dense layouts
+    outline: "border-(--c)/50 bg-card hc:border-(--c)",
+} as const;
+
+export const statusSurfaceNeutral = "border-border bg-card hc:border-border";

package/src/provider/theme-provider.tsx

@@ -32,6 +32,10 @@ export interface ThemeContextValue extends ThemeState {
     setContrast: (contrast: ThemeState["contrast"]) => void;
     setAccent: (accent: ThemeState["accent"]) => void;
     setRadius: (radius: ThemeState["radius"]) => void;
+    /** The values `resetTheme` restores: the provider's `defaultTheme` over the kit defaults. */
+    defaults: ThemeState;
+    /** Forget the stored choice and go back to `defaults`. */
+    resetTheme: () => void;
 }
 
 const ThemeContext = createContext<ThemeContextValue | null>(null);
@@ -139,6 +143,17 @@ export function ThemeProvider({
         [storageKey, fallback],
     );
 
+    const resetTheme = useCallback(() => {
+        if (storageKey) {
+            try {
+                window.localStorage.removeItem(storageKey);
+            } catch {
+                // storage blocked: the in-memory reset still applies
+            }
+        }
+        setStored(fallback);
+    }, [storageKey, fallback]);
+
     const value = useMemo<ThemeContextValue>(
         () => ({
             ...theme,
@@ -148,8 +163,10 @@ export function ThemeProvider({
             setContrast: (contrast) => setTheme({contrast}),
             setAccent: (accent) => setTheme({accent}),
             setRadius: (radius) => setTheme({radius}),
+            defaults: fallback,
+            resetTheme,
         }),
-        [theme, resolvedMode, setTheme],
+        [theme, resolvedMode, setTheme, fallback, resetTheme],
     );
 
     return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;

package/src/styles/kernelkit.css

@@ -133,6 +133,9 @@
     --kk-font-mono: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
     /* Titles: card, dialog, sheet, empty, alert. Mono by default (the TermiColor look). */
     --kk-font-heading: var(--kk-font-mono);
+    /* Labels and readouts: badges, tooltips, breadcrumbs, kbd, shortcuts, eyebrows, nav, values. Mono by
+       default (the TermiColor look); point it at any face. Code always stays on --kk-font-mono. */
+    --kk-font-alt: var(--kk-font-mono);
     /* Site shell (site-header, site-layout): content width, and the sticky header's height that
        sidebars and anchors offset by. A site with a banner above the header row adds it here. */
     --kk-site-width: 80rem;
@@ -159,6 +162,7 @@
     --font-sans: var(--kk-font-sans);
     --font-mono: var(--kk-font-mono);
     --font-heading: var(--kk-font-heading);
+    --font-alt: var(--kk-font-alt);
 
     --radius-xs: calc(var(--kk-radius) * 0.25);
     --radius-sm: calc(var(--kk-radius) * 0.5);