@repraze/kernelkit 0.0.0-stage → 0.1.0-alpha.1

package/src/components/site-footer.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import {mergeProps} from "@base-ui/react/merge-props";
+import {useRender} from "@base-ui/react/use-render";
+import {focusRing} from "@repraze/kernelkit/lib/recipes";
+import {cn} from "cn";
+import type * as React from "react";
+
+/**
+ * The suite's site footer: a top border and one mono row at the site width, credits on the left and
+ * links on the right.
+ *
+ * ```tsx
+ * <SiteFooter>
+ *   <span>MIT · built from one palette</span>
+ *   <SiteFooterLinks>
+ *     <SiteFooterLink href="https://github.com/…">GitHub</SiteFooterLink>
+ *   </SiteFooterLinks>
+ * </SiteFooter>
+ * ```
+ */
+function SiteFooter({className, children, ...props}: React.ComponentProps<"footer">) {
+    return (
+        <footer data-slot="site-footer" className={cn("border-t border-border", className)} {...props}>
+            <div className="mx-auto flex w-full max-w-(--kk-site-width) flex-col gap-3 px-4 py-6 font-mono text-xs text-muted-foreground sm:flex-row sm:items-center sm:justify-between md:px-6">
+                {children}
+            </div>
+        </footer>
+    );
+}
+
+/** The footer's links (wrap on phones). */
+function SiteFooterLinks({className, render, ...props}: useRender.ComponentProps<"nav">) {
+    return useRender({
+        defaultTagName: "nav",
+        props: mergeProps<"nav">({className: cn("flex flex-wrap items-center gap-x-4 gap-y-1", className)}, props),
+        render,
+        state: {slot: "site-footer-links"},
+    });
+}
+
+/** A footer link: muted, foreground on hover. */
+function SiteFooterLink({className, render, ...props}: useRender.ComponentProps<"a">) {
+    return useRender({
+        defaultTagName: "a",
+        props: mergeProps<"a">(
+            {className: cn("rounded-sm transition-colors hover:text-foreground", focusRing, className)},
+            props,
+        ),
+        render,
+        state: {slot: "site-footer-link"},
+    });
+}
+
+export {SiteFooter, SiteFooterLink, SiteFooterLinks};

package/src/components/site-header.tsx

@@ -0,0 +1,169 @@
+"use client";
+
+import {mergeProps} from "@base-ui/react/merge-props";
+import {useRender} from "@base-ui/react/use-render";
+import {Button} from "@repraze/kernelkit/components/button";
+import {Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger} from "@repraze/kernelkit/components/sheet";
+import {focusRing} from "@repraze/kernelkit/lib/recipes";
+import {cn} from "cn";
+import {MenuIcon} from "lucide-react";
+import type * as React from "react";
+
+/**
+ * The suite's site header: sticky, blurred, one row of `--kk-header-height` inside a `--kk-site-width`
+ * container. Brand, then mono nav links (current page underlined in the accent), then actions.
+ *
+ * ```tsx
+ * <SiteHeader>
+ *   <SiteHeaderContent>
+ *     <SiteHeaderMenu title="termicolor">…mobile nav…</SiteHeaderMenu>
+ *     <SiteHeaderBrand render={<Link to="/" />}>…</SiteHeaderBrand>
+ *     <SiteNav><SiteNavLink render={<Link to="/ports" />}>Ports</SiteNavLink></SiteNav>
+ *     <SiteHeaderActions>…search, theme, github…</SiteHeaderActions>
+ *   </SiteHeaderContent>
+ * </SiteHeader>
+ * ```
+ */
+function SiteHeader({className, render, ...props}: useRender.ComponentProps<"header">) {
+    return useRender({
+        defaultTagName: "header",
+        props: mergeProps<"header">(
+            {
+                className: cn(
+                    "sticky top-0 z-40 w-full border-b border-border bg-background/85 text-foreground backdrop-blur supports-backdrop-filter:bg-background/70",
+                    className,
+                ),
+            },
+            props,
+        ),
+        render,
+        state: {slot: "site-header"},
+    });
+}
+
+/** The header row: centered at the site width, the same gutters as SiteContainer. */
+function SiteHeaderContent({className, render, ...props}: useRender.ComponentProps<"div">) {
+    return useRender({
+        defaultTagName: "div",
+        props: mergeProps<"div">(
+            {
+                className: cn(
+                    "mx-auto flex h-14 w-full max-w-(--kk-site-width) items-center gap-4 px-4 md:gap-6 md:px-6",
+                    className,
+                ),
+            },
+            props,
+        ),
+        render,
+        state: {slot: "site-header-content"},
+    });
+}
+
+/** Logo + name, links home. Pass the router link with `render`. */
+function SiteHeaderBrand({className, render, ...props}: useRender.ComponentProps<"a">) {
+    return useRender({
+        defaultTagName: "a",
+        props: mergeProps<"a">(
+            {
+                className: cn(
+                    "flex shrink-0 items-center gap-2 rounded-md font-mono text-sm font-semibold tracking-tight",
+                    focusRing,
+                    "[&_svg]:shrink-0",
+                    className,
+                ),
+            },
+            props,
+        ),
+        render,
+        state: {slot: "site-header-brand"},
+    });
+}
+
+/** Primary navigation (desktop). On phones the links move into SiteHeaderMenu. */
+function SiteNav({className, render, ...props}: useRender.ComponentProps<"nav">) {
+    return useRender({
+        defaultTagName: "nav",
+        props: mergeProps<"nav">(
+            {"aria-label": "Main", className: cn("hidden items-center gap-1 md:flex", className)},
+            props,
+        ),
+        render,
+        state: {slot: "site-nav"},
+    });
+}
+
+/**
+ * A nav link, styled like the suite's other navigation (GUIDELINES §7c): muted at rest, a hover wash,
+ * and when current (`aria-current="page"`, `data-status="active"` from TanStack Router, or `data-active`)
+ * foreground text plus a 2px accent indicator. In SiteNav the indicator sits on the header's bottom
+ * border (like line Tabs); elsewhere (the phone menu) the link is a sidebar row with a tint and the
+ * indicator on its left edge.
+ */
+function SiteNavLink({className, render, ...props}: useRender.ComponentProps<"a">) {
+    return useRender({
+        defaultTagName: "a",
+        props: mergeProps<"a">(
+            {
+                className: cn(
+                    "relative flex h-8 items-center rounded-md px-2.5 font-mono text-sm text-muted-foreground transition-colors hover:bg-hover hover:text-foreground motion-reduce:transition-none",
+                    focusRing,
+                    // indicator: vertical by default, on the header border inside SiteNav
+                    "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",
+                    "in-data-[slot=site-nav]:after:top-auto in-data-[slot=site-nav]:after:right-2.5 in-data-[slot=site-nav]:after:-bottom-[calc(0.75rem+1px)] in-data-[slot=site-nav]:after:left-2.5 in-data-[slot=site-nav]:after:h-0.5 in-data-[slot=site-nav]:after:w-auto",
+                    "aria-[current=page]:text-foreground aria-[current=page]:after:opacity-100 data-[status=active]:text-foreground data-[status=active]:after:opacity-100 data-active:text-foreground data-active:after:opacity-100",
+                    // outside the header row: the sidebar's current-row tint
+                    "not-in-data-[slot=site-nav]:aria-[current=page]:bg-primary-tint not-in-data-[slot=site-nav]:data-[status=active]:bg-primary-tint not-in-data-[slot=site-nav]:data-active:bg-primary-tint",
+                    className,
+                ),
+            },
+            props,
+        ),
+        render,
+        state: {slot: "site-nav-link"},
+    });
+}
+
+/** Right side of the header row: search, theme, repository links. */
+function SiteHeaderActions({className, render, ...props}: useRender.ComponentProps<"div">) {
+    return useRender({
+        defaultTagName: "div",
+        props: mergeProps<"div">({className: cn("ml-auto flex items-center gap-1", className)}, props),
+        render,
+        state: {slot: "site-header-actions"},
+    });
+}
+
+interface SiteHeaderMenuProps extends Omit<React.ComponentProps<typeof Sheet>, "children"> {
+    children?: React.ReactNode;
+    /** Sheet title (also the accessible name). */
+    title?: React.ReactNode;
+    className?: string;
+}
+
+/**
+ * Phone navigation: a menu button (hidden from `md`) opening a left sheet with the nav and the page's
+ * sidebar. Control `open` to close it on navigation.
+ */
+function SiteHeaderMenu({title = "Menu", children, className, ...props}: SiteHeaderMenuProps) {
+    return (
+        <Sheet {...props}>
+            <SheetTrigger
+                render={<Button variant="ghost" size="icon-sm" className="-ml-1.5 md:hidden" aria-label="Menu" />}
+            >
+                <MenuIcon />
+            </SheetTrigger>
+            <SheetContent
+                side="left"
+                data-slot="site-header-menu"
+                className={cn("w-72 gap-0 overflow-y-auto overscroll-contain p-0", className)}
+            >
+                <SheetHeader className="border-b border-border">
+                    <SheetTitle className="flex items-center gap-2">{title}</SheetTitle>
+                </SheetHeader>
+                <div className="flex flex-col gap-4 p-2">{children}</div>
+            </SheetContent>
+        </Sheet>
+    );
+}
+
+export {SiteHeader, SiteHeaderActions, SiteHeaderBrand, SiteHeaderContent, SiteHeaderMenu, SiteNav, SiteNavLink};

package/src/components/site-layout.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import {mergeProps} from "@base-ui/react/merge-props";
+import {useRender} from "@base-ui/react/use-render";
+import {ScrollArea} from "@repraze/kernelkit/components/scroll-area";
+import {cn} from "cn";
+import * as React from "react";
+
+/**
+ * The suite's page layout, under SiteHeader:
+ *
+ * ```tsx
+ * <SiteLayout>
+ *   <SiteSidebar aria-label="Docs">…SidebarGroup / SidebarMenu…</SiteSidebar>
+ *   <SiteMain>…PageHeader, content, Pager…</SiteMain>
+ *   <SiteAside><Toc>…</Toc></SiteAside>
+ * </SiteLayout>
+ * ```
+ *
+ * Sidebars are sticky below the header and scroll on their own with edge fades. Content pages without
+ * a sidebar use SiteContainer.
+ */
+
+/** Centered at `--kk-site-width` with the header's gutters. */
+function SiteContainer({className, render, ...props}: useRender.ComponentProps<"div">) {
+    return useRender({
+        defaultTagName: "div",
+        props: mergeProps<"div">(
+            {className: cn("mx-auto w-full max-w-(--kk-site-width) px-4 md:px-6", className)},
+            props,
+        ),
+        render,
+        state: {slot: "site-container"},
+    });
+}
+
+/** Sidebar + main (+ aside) row inside the site container. */
+function SiteLayout({className, render, ...props}: useRender.ComponentProps<"div">) {
+    return useRender({
+        defaultTagName: "div",
+        props: mergeProps<"div">(
+            {
+                className: cn(
+                    "mx-auto flex w-full max-w-(--kk-site-width) flex-1 gap-8 px-4 md:px-6 lg:gap-10",
+                    className,
+                ),
+            },
+            props,
+        ),
+        render,
+        state: {slot: "site-layout"},
+    });
+}
+
+/** Sticky columns fill the viewport below the header; their content has the page's vertical padding. */
+const stickyColumn = "sticky top-(--kk-header-height) h-[calc(100svh-var(--kk-header-height))]";
+/** Vertical rhythm of every column (the layout itself has none, so the sidebar border runs edge to edge). */
+const columnPadding = "py-8 lg:py-10";
+
+interface SiteSidebarProps extends React.ComponentProps<"aside"> {
+    /** Classes for the scrolling viewport (padding, etc.). */
+    viewportClassName?: string;
+}
+
+/** Items a nav marks current: SidebarMenuButton isActive, router links, aria-current. */
+const CURRENT = '[data-active]:not([data-active="false"]), [aria-current="page"], [data-status="active"]';
+
+/** Center the current item in the sidebar's own viewport (never scrolls the page). */
+function useKeepCurrentInView(viewport: React.RefObject<HTMLDivElement | null>) {
+    React.useEffect(() => {
+        const el = viewport.current;
+        if (!el) {
+            return;
+        }
+        const reveal = () => {
+            const item = el.querySelector<HTMLElement>(CURRENT);
+            if (!item) {
+                return;
+            }
+            const offset = item.getBoundingClientRect().top - el.getBoundingClientRect().top;
+            if (offset < 0 || offset > el.clientHeight - item.offsetHeight) {
+                el.scrollTop += offset - el.clientHeight / 2;
+            }
+        };
+        reveal();
+        // navigation flips data-active / aria-current on the links: follow it
+        const observer = new MutationObserver(reveal);
+        observer.observe(el, {
+            subtree: true,
+            attributes: true,
+            attributeFilter: ["data-active", "aria-current", "data-status"],
+        });
+        return () => observer.disconnect();
+    }, [viewport]);
+}
+
+/**
+ * Left navigation column (from `md`): sticky, scrolls on its own, fades at its edges, and keeps the
+ * current item in view. Its right border runs the layout's full height, header to footer.
+ */
+function SiteSidebar({className, viewportClassName, children, ...props}: SiteSidebarProps) {
+    const viewport = React.useRef<HTMLDivElement>(null);
+    useKeepCurrentInView(viewport);
+    return (
+        <aside
+            data-slot="site-sidebar"
+            className={cn("hidden w-60 shrink-0 border-r border-border md:block", className)}
+            {...props}
+        >
+            {/* sticky on a wrapper: Base UI's ScrollArea root sets position inline */}
+            <div className={stickyColumn}>
+                <ScrollArea
+                    fade
+                    className="h-full"
+                    viewportRef={viewport}
+                    viewportClassName={cn(columnPadding, "pr-3", viewportClassName)}
+                >
+                    {children}
+                </ScrollArea>
+            </div>
+        </aside>
+    );
+}
+
+/** The page column. */
+function SiteMain({className, render, ...props}: useRender.ComponentProps<"main">) {
+    return useRender({
+        defaultTagName: "main",
+        props: mergeProps<"main">(
+            {className: cn("flex min-w-0 flex-1 flex-col gap-10", columnPadding, className)},
+            props,
+        ),
+        render,
+        state: {slot: "site-main"},
+    });
+}
+
+/** Right column (from `xl`): table of contents, page meta. Sticky like the sidebar. */
+function SiteAside({className, children, ...props}: React.ComponentProps<"aside">) {
+    return (
+        <aside data-slot="site-aside" className={cn("hidden w-48 shrink-0 xl:block", className)} {...props}>
+            <div className={cn(stickyColumn, columnPadding, "overflow-y-auto")}>{children}</div>
+        </aside>
+    );
+}
+
+export {SiteAside, SiteContainer, SiteLayout, SiteMain, SiteSidebar};

package/src/components/skeleton.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import {mergeProps} from "@base-ui/react/merge-props";
+import {useRender} from "@base-ui/react/use-render";
+import {cn} from "cn";
+
+/** Placeholder block while content loads. Size it with `h-*`/`w-*`; `rounded-pill` for avatars and pills. */
+const skeletonClass = "animate-pulse rounded-md bg-foreground/10 motion-reduce:animate-none hc:bg-border";
+
+function Skeleton({className, render, ...props}: useRender.ComponentProps<"div">) {
+    return useRender({
+        defaultTagName: "div",
+        props: mergeProps<"div">({"aria-hidden": true, className: cn(skeletonClass, className)}, props),
+        render,
+        state: {slot: "skeleton"},
+    });
+}
+
+export {Skeleton, skeletonClass};

package/src/components/slider.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import {Slider as SliderPrimitive} from "@base-ui/react/slider";
+import {cn} from "cn";
+
+function Slider({className, defaultValue, value, min = 0, max = 100, ...props}: SliderPrimitive.Root.Props) {
+    const _values = Array.isArray(value) ? value : Array.isArray(defaultValue) ? defaultValue : [min, max];
+    const thumbs = value !== undefined || defaultValue !== undefined ? _values.length : 1;
+
+    return (
+        <SliderPrimitive.Root
+            className={cn("group/slider data-horizontal:w-full data-vertical:h-full", className)}
+            data-slot="slider"
+            defaultValue={defaultValue}
+            value={value}
+            min={min}
+            max={max}
+            thumbAlignment="edge"
+            {...props}
+        >
+            <SliderPrimitive.Control
+                data-slot="slider-control"
+                className="relative flex w-full touch-none items-center select-none data-disabled:cursor-not-allowed data-disabled:opacity-50 data-horizontal:h-4 data-vertical:h-full data-vertical:min-h-40 data-vertical:w-4 data-vertical:flex-col data-vertical:justify-center"
+            >
+                <SliderPrimitive.Track
+                    data-slot="slider-track"
+                    className="relative grow overflow-hidden rounded-pill bg-input select-none data-horizontal:h-1.5 data-horizontal:w-full data-vertical:h-full data-vertical:w-1.5"
+                >
+                    <SliderPrimitive.Indicator
+                        data-slot="slider-range"
+                        className="bg-primary select-none group-data-invalid/slider:bg-danger data-horizontal:h-full data-vertical:w-full"
+                    />
+                </SliderPrimitive.Track>
+                {Array.from({length: thumbs}, (_, index) => (
+                    <SliderPrimitive.Thumb
+                        data-slot="slider-thumb"
+                        key={index}
+                        className="relative block size-4 shrink-0 cursor-grab rounded-pill border-2 border-primary-text bg-background shadow-sm shadow-(color:--shadow-color) ring-ring/50 transition-[color,box-shadow,border-color] duration-100 select-none after:absolute after:-inset-1 hover:ring-3 has-focus-visible:ring-3 has-focus-visible:outline-hidden active:cursor-grabbing active:ring-3 group-data-invalid/slider:border-danger group-data-invalid/slider:ring-danger/20 data-disabled:pointer-events-none motion-reduce:transition-none"
+                    />
+                ))}
+            </SliderPrimitive.Control>
+        </SliderPrimitive.Root>
+    );
+}
+
+export {Slider};

package/src/components/spinner.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import {cva, type VariantProps} from "class-variance-authority";
+import {cn} from "cn";
+import {Loader2Icon} from "lucide-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",
+            },
+        },
+        defaultVariants: {size: "default"},
+    },
+);
+
+interface SpinnerProps extends React.ComponentProps<"svg">, VariantProps<typeof spinnerVariants> {}
+
+/** Indeterminate loading indicator. Inherits `currentColor`; announces itself as a status. */
+function Spinner({className, size, ...props}: SpinnerProps) {
+    return (
+        <Loader2Icon
+            data-slot="spinner"
+            data-size={size ?? "default"}
+            role="status"
+            aria-label="Loading"
+            className={cn(spinnerVariants({size}), className)}
+            {...props}
+        />
+    );
+}
+
+export {Spinner, spinnerVariants};
+export type {SpinnerProps};

package/src/components/stat.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+import {mergeProps} from "@base-ui/react/merge-props";
+import {useRender} from "@base-ui/react/use-render";
+import {cva} from "class-variance-authority";
+import {cn} from "cn";
+import {ArrowDownRightIcon, ArrowUpRightIcon, MinusIcon} from "lucide-react";
+import type * as React from "react";
+
+/** A metric: label, big mono value, delta and an optional sparkline. Sits alone or inside a Card. */
+const statVariants = cva("group/stat grid min-w-0 grid-cols-[1fr_auto] content-start gap-x-3", {
+    variants: {
+        size: {
+            sm: "gap-y-0.5",
+            default: "gap-y-1",
+            lg: "gap-y-1.5",
+        },
+    },
+    defaultVariants: {size: "default"},
+});
+
+function Stat({
+    className,
+    size = "default",
+    render,
+    ...props
+}: useRender.ComponentProps<"div"> & {size?: "sm" | "default" | "lg"}) {
+    return useRender({
+        defaultTagName: "div",
+        props: mergeProps<"div">({className: cn(statVariants({size}), className)}, props),
+        render,
+        state: {slot: "stat", size},
+    });
+}
+
+function StatLabel({className, ...props}: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="stat-label"
+            className={cn(
+                "col-span-full flex min-w-0 items-center gap-1.5 truncate text-xs font-medium text-muted-foreground [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function StatValue({className, ...props}: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="stat-value"
+            className={cn(
+                "col-start-1 flex items-baseline gap-1 font-mono text-2xl leading-tight font-medium tracking-tight text-foreground tabular-nums",
+                "group-data-[size=sm]/stat:text-xl group-data-[size=lg]/stat:text-3xl",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+/** Unit or suffix after the value (`ms`, `%`, `req/s`). */
+function StatUnit({className, ...props}: React.ComponentProps<"span">) {
+    return (
+        <span
+            data-slot="stat-unit"
+            className={cn("text-sm font-normal tracking-normal text-muted-foreground", className)}
+            {...props}
+        />
+    );
+}
+
+type StatTrend = "up" | "down" | "flat";
+
+const statDeltaVariants = cva(
+    "col-start-1 inline-flex w-fit items-center gap-1 font-mono text-xs font-medium tabular-nums [&_svg]:size-3.5 [&_svg]:shrink-0",
+    {
+        variants: {
+            intent: {
+                positive: "text-success",
+                negative: "text-danger",
+                neutral: "text-muted-foreground",
+            },
+        },
+        defaultVariants: {intent: "neutral"},
+    },
+);
+
+const trendIcon = {up: ArrowUpRightIcon, down: ArrowDownRightIcon, flat: MinusIcon} as const;
+
+/**
+ * Change versus a previous period. `trend` picks the arrow; up is good (success) and down is bad (danger)
+ * unless `invert` is set (latency, error rate, cost). The arrow keeps the meaning readable without color.
+ */
+function StatDelta({
+    className,
+    trend = "flat",
+    invert = false,
+    children,
+    ...props
+}: React.ComponentProps<"div"> & {trend?: StatTrend; invert?: boolean}) {
+    const good = trend === "flat" ? null : (trend === "up") !== invert;
+    const intent = good === null ? "neutral" : good ? "positive" : "negative";
+    const Icon = trendIcon[trend];
+    return (
+        <div
+            data-slot="stat-delta"
+            data-trend={trend}
+            data-intent={intent}
+            className={cn(statDeltaVariants({intent}), className)}
+            {...props}
+        >
+            <Icon aria-hidden="true" />
+            {children}
+        </div>
+    );
+}
+
+function StatDescription({className, ...props}: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="stat-description"
+            className={cn("col-start-1 text-xs text-muted-foreground", className)}
+            {...props}
+        />
+    );
+}
+
+/** Right-hand slot beside the value and delta rows: a sparkline, an icon tile or a badge. */
+function StatSparkline({className, ...props}: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="stat-sparkline"
+            className={cn(
+                "col-start-2 row-span-2 row-start-2 flex h-full min-h-8 w-24 items-end self-end text-primary-text",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+export {
+    Stat,
+    StatDelta,
+    statDeltaVariants,
+    StatDescription,
+    StatLabel,
+    StatSparkline,
+    StatUnit,
+    StatValue,
+    statVariants,
+};
+export type {StatTrend};