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

package/src/components/toc.tsx

@@ -0,0 +1,122 @@
+"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 * as React from "react";
+
+/**
+ * "On this page": a page's section links, usually in SiteAside.
+ *
+ * ```tsx
+ * const active = useTocActive(sections.map((s) => s.id));
+ * <Toc>
+ *   <TocTitle>On this page</TocTitle>
+ *   <TocList>
+ *     {sections.map((s) => <TocItem key={s.id} href={`#${s.id}`} active={s.id === active}>{s.title}</TocItem>)}
+ *   </TocList>
+ * </Toc>
+ * ```
+ */
+function Toc({className, render, ...props}: useRender.ComponentProps<"nav">) {
+    return useRender({
+        defaultTagName: "nav",
+        props: mergeProps<"nav">(
+            {"aria-label": "On this page", className: cn("flex flex-col gap-2", className)},
+            props,
+        ),
+        render,
+        state: {slot: "toc"},
+    });
+}
+
+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)},
+            props,
+        ),
+        render,
+        state: {slot: "toc-title"},
+    });
+}
+
+function TocList({className, render, ...props}: useRender.ComponentProps<"ul">) {
+    return useRender({
+        defaultTagName: "ul",
+        props: mergeProps<"ul">({className: cn("flex flex-col border-l border-border text-sm", className)}, props),
+        render,
+        state: {slot: "toc-list"},
+    });
+}
+
+interface TocItemProps extends useRender.ComponentProps<"a"> {
+    /** The section in view: accent indicator on the rail + foreground text. */
+    active?: boolean;
+    /** Heading depth below the top level (indent). */
+    depth?: 0 | 1 | 2;
+}
+
+function TocItem({className, render, active = false, depth = 0, ...props}: TocItemProps) {
+    const link = useRender({
+        defaultTagName: "a",
+        props: mergeProps<"a">(
+            {
+                "aria-current": active ? "location" : undefined,
+                className: cn(
+                    "relative block py-1 pr-2 text-muted-foreground transition-colors hover:text-foreground after:pointer-events-none after:absolute after:inset-y-0 after:-left-[1.5px] after:w-0.5 after:bg-primary-text after:opacity-0",
+                    focusRing,
+                    {0: "pl-3", 1: "pl-6", 2: "pl-9"}[depth],
+                    "aria-[current=location]:after:opacity-100 aria-[current=location]:font-medium aria-[current=location]:text-foreground",
+                    className,
+                ),
+            },
+            props,
+        ),
+        render,
+        state: {slot: "toc-item"},
+    });
+    return <li data-slot="toc-list-item">{link}</li>;
+}
+
+/**
+ * Scroll-spy: the id of the section currently being read (the last one whose top passed the header),
+ * for TocItem `active`. SSR-safe; returns the first id until mounted.
+ */
+function useTocActive(ids: readonly string[], {offset = 96}: {offset?: number} = {}): string | undefined {
+    const [active, setActive] = React.useState<string | undefined>(ids[0]);
+    const key = ids.join("|");
+    React.useEffect(() => {
+        const elements = key
+            .split("|")
+            .map((id) => document.getElementById(id))
+            .filter((el): el is HTMLElement => !!el);
+        if (!elements.length) {
+            return;
+        }
+        let frame = 0;
+        const update = () => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(() => {
+                const atBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
+                const passed = elements.filter((el) => el.getBoundingClientRect().top <= offset);
+                const current = atBottom ? elements[elements.length - 1] : (passed[passed.length - 1] ?? elements[0]);
+                setActive(current?.id);
+            });
+        };
+        update();
+        window.addEventListener("scroll", update, {passive: true});
+        window.addEventListener("resize", update);
+        return () => {
+            cancelAnimationFrame(frame);
+            window.removeEventListener("scroll", update);
+            window.removeEventListener("resize", update);
+        };
+    }, [key, offset]);
+    return active;
+}
+
+export {Toc, TocItem, TocList, TocTitle, useTocActive};
+export type {TocItemProps};

package/src/components/toggle-group.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import {Toggle as TogglePrimitive} from "@base-ui/react/toggle";
+import {ToggleGroup as ToggleGroupPrimitive} from "@base-ui/react/toggle-group";
+import {toggleVariants} from "@repraze/kernelkit/components/toggle";
+import {type VariantProps} from "class-variance-authority";
+import {cn} from "cn";
+import * as React from "react";
+
+type ToggleGroupContextValue = VariantProps<typeof toggleVariants> & {
+    spacing?: number;
+    orientation?: "horizontal" | "vertical";
+};
+
+const ToggleGroupContext = React.createContext<ToggleGroupContextValue>({
+    size: "default",
+    variant: "default",
+    spacing: 2,
+    orientation: "horizontal",
+});
+
+type ToggleGroupProps = ToggleGroupPrimitive.Props & ToggleGroupContextValue;
+
+/**
+ * `spacing={0}` joins the items into one segmented control: outer corners follow the group radius,
+ * outline items overlap their borders so the pressed item's border stays whole.
+ */
+function ToggleGroup({
+    className,
+    variant,
+    size,
+    spacing = 2,
+    orientation = "horizontal",
+    children,
+    ...props
+}: ToggleGroupProps) {
+    return (
+        <ToggleGroupPrimitive
+            data-slot="toggle-group"
+            data-variant={variant ?? "default"}
+            data-size={size ?? "default"}
+            data-spacing={spacing}
+            data-orientation={orientation}
+            orientation={orientation}
+            style={{"--gap": spacing} as React.CSSProperties}
+            className={cn(
+                "group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-lg data-[size=sm]:rounded-md data-[size=xs]:rounded-md data-vertical:flex-col data-vertical:items-stretch",
+                className,
+            )}
+            {...props}
+        >
+            <ToggleGroupContext.Provider value={{variant, size, spacing, orientation}}>
+                {children}
+            </ToggleGroupContext.Provider>
+        </ToggleGroupPrimitive>
+    );
+}
+
+function ToggleGroupItem({
+    className,
+    children,
+    variant = "default",
+    size = "default",
+    ...props
+}: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
+    const context = React.useContext(ToggleGroupContext);
+    const itemVariant = context.variant || variant;
+    const itemSize = context.size || size;
+
+    return (
+        <TogglePrimitive
+            data-slot="toggle-group-item"
+            data-variant={itemVariant}
+            data-size={itemSize}
+            data-spacing={context.spacing}
+            className={cn(
+                toggleVariants({variant: itemVariant, size: itemSize}),
+                "focus-visible:z-10",
+                // joined: square inner corners, group-radius outer corners
+                "data-[spacing=0]:rounded-none",
+                "group-data-horizontal/toggle-group:data-[spacing=0]:first:rounded-l-[inherit] group-data-horizontal/toggle-group:data-[spacing=0]:last:rounded-r-[inherit]",
+                "group-data-vertical/toggle-group:data-[spacing=0]:first:rounded-t-[inherit] group-data-vertical/toggle-group:data-[spacing=0]:last:rounded-b-[inherit]",
+                // joined outline: overlap borders instead of dropping one, so a pressed border is never cut
+                "data-[variant=outline]:data-pressed:z-[5] group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:not-first:-ml-px group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:not-first:-mt-px",
+                className,
+            )}
+            {...props}
+        >
+            {children}
+        </TogglePrimitive>
+    );
+}
+
+export {ToggleGroup, ToggleGroupItem};
+export type {ToggleGroupProps};

package/src/components/toggle.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import {Toggle as TogglePrimitive} from "@base-ui/react/toggle";
+import {focusRing, invalidRing} from "@repraze/kernelkit/lib/recipes";
+import {cva, type VariantProps} from "class-variance-authority";
+import {cn} from "cn";
+
+/**
+ * Padding is chosen so an icon-only toggle is square at its height (§4); text-only toggles (no svg)
+ * get the regular control padding back.
+ */
+const toggleVariants = cva(
+    [
+        "group/toggle inline-flex shrink-0 items-center justify-center gap-1.5 rounded-lg border border-transparent text-sm font-medium whitespace-nowrap select-none",
+        "transition-[color,background-color,border-color,box-shadow] duration-100 motion-reduce:transition-none",
+        "hover:bg-hover hover:text-foreground disabled:pointer-events-none disabled:opacity-50",
+        focusRing,
+        invalidRing,
+        // on: accent tint fill + accent text (§6: a fill, never shade alone)
+        "data-pressed:bg-accent data-pressed:text-accent-foreground data-pressed:hover:bg-[color-mix(in_oklch,var(--accent),var(--foreground)_8%)]",
+        "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+    ],
+    {
+        variants: {
+            variant: {
+                default: "bg-transparent",
+                outline: "border-input bg-transparent data-pressed:border-primary-text",
+            },
+            size: {
+                xs: "h-6 min-w-6 gap-1 rounded-md px-1 text-xs not-has-[svg]:px-2 has-data-[icon=inline-end]:pl-2 has-data-[icon=inline-start]:pr-2 [&_svg:not([class*='size-'])]:size-3",
+                sm: "h-7 min-w-7 gap-1 rounded-md px-1.5 text-[0.8rem] not-has-[svg]:px-2.5 has-data-[icon=inline-end]:pl-2.5 has-data-[icon=inline-start]:pr-2.5 [&_svg:not([class*='size-'])]:size-3.5",
+                default:
+                    "h-8 min-w-8 px-2 not-has-[svg]:px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-end]:pl-2.5 has-data-[icon=inline-start]:pr-2.5 has-data-[icon=inline-start]:pl-2",
+                lg: "h-9 min-w-9 gap-2 px-2.5 not-has-[svg]:px-3 has-data-[icon=inline-end]:pl-3 has-data-[icon=inline-start]:pr-3",
+            },
+        },
+        defaultVariants: {
+            variant: "default",
+            size: "default",
+        },
+    },
+);
+
+type ToggleProps = TogglePrimitive.Props & VariantProps<typeof toggleVariants>;
+
+function Toggle({className, variant = "default", size = "default", ...props}: ToggleProps) {
+    return (
+        <TogglePrimitive
+            data-slot="toggle"
+            data-variant={variant}
+            data-size={size}
+            className={cn(toggleVariants({variant, size}), className)}
+            {...props}
+        />
+    );
+}
+
+export {Toggle, toggleVariants};
+export type {ToggleProps};

package/src/components/toolbar.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import {Toolbar as ToolbarPrimitive} from "@base-ui/react/toolbar";
+import {buttonVariants} from "@repraze/kernelkit/components/button";
+import {fieldSurface, focusRing} from "@repraze/kernelkit/lib/recipes";
+import {cn} from "cn";
+
+/**
+ * A bordered bar of controls with roving arrow-key focus (Base UI Toolbar). Items are ghost `icon-sm`
+ * buttons by default; pass `render={<Button …/>}` (or a Toggle, a Select trigger, a Menu trigger) to change one.
+ */
+function Toolbar({className, orientation = "horizontal", ...props}: ToolbarPrimitive.Root.Props) {
+    return (
+        <ToolbarPrimitive.Root
+            data-slot="toolbar"
+            orientation={orientation}
+            className={cn(
+                "flex w-fit items-center gap-px rounded-lg border border-border bg-background p-px data-vertical:flex-col",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function ToolbarButton({className, render, ...props}: ToolbarPrimitive.Button.Props) {
+    return (
+        <ToolbarPrimitive.Button
+            data-slot="toolbar-button"
+            // With a custom `render` (a kernelkit Button, Toggle…) that element brings its own look.
+            className={cn(
+                render === undefined && buttonVariants({variant: "ghost", size: "icon-sm"}),
+                // Disabled items stay focusable (aria-disabled, not `disabled`): dim them from the data attr.
+                "data-disabled:pointer-events-none data-disabled:opacity-50",
+                className,
+            )}
+            render={render}
+            {...props}
+        />
+    );
+}
+
+function ToolbarLink({className, ...props}: ToolbarPrimitive.Link.Props) {
+    return (
+        <ToolbarPrimitive.Link
+            data-slot="toolbar-link"
+            className={cn(
+                "inline-flex h-7 items-center gap-1 rounded-md px-2 text-[0.8rem] text-muted-foreground underline-offset-4 transition-colors hover:text-foreground hover:underline [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-3.5",
+                focusRing,
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+/** Compact text field that fits the toolbar row (`h-7`). */
+function ToolbarInput({className, ...props}: ToolbarPrimitive.Input.Props) {
+    return (
+        <ToolbarPrimitive.Input
+            data-slot="toolbar-input"
+            className={cn(
+                fieldSurface,
+                focusRing,
+                "h-7 w-40 min-w-0 rounded-md px-2 text-base md:text-[0.8rem]",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function ToolbarGroup({className, ...props}: ToolbarPrimitive.Group.Props) {
+    return (
+        <ToolbarPrimitive.Group
+            data-slot="toolbar-group"
+            className={cn("flex items-center gap-px data-vertical:flex-col", className)}
+            {...props}
+        />
+    );
+}
+
+function ToolbarSeparator({className, ...props}: ToolbarPrimitive.Separator.Props) {
+    return (
+        <ToolbarPrimitive.Separator
+            data-slot="toolbar-separator"
+            className={cn(
+                // Perpendicular to the toolbar: a horizontal toolbar gets data-orientation="vertical" separators.
+                "shrink-0 bg-border data-vertical:mx-1 data-vertical:h-4 data-vertical:w-px data-horizontal:my-1 data-horizontal:h-px data-horizontal:w-4",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+export {Toolbar, ToolbarButton, ToolbarGroup, ToolbarInput, ToolbarLink, ToolbarSeparator};

package/src/components/tooltip.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import {Tooltip as TooltipPrimitive} from "@base-ui/react/tooltip";
+import {popupMotion} from "@repraze/kernelkit/lib/recipes";
+import {usePortalContainer} from "@repraze/kernelkit/provider";
+import {cn} from "cn";
+
+function TooltipProvider({delay = 0, ...props}: TooltipPrimitive.Provider.Props) {
+    return <TooltipPrimitive.Provider data-slot="tooltip-provider" delay={delay} {...props} />;
+}
+
+function Tooltip({...props}: TooltipPrimitive.Root.Props) {
+    return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+function TooltipTrigger({...props}: TooltipPrimitive.Trigger.Props) {
+    return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+    className,
+    side = "top",
+    sideOffset = 6,
+    align = "center",
+    alignOffset = 0,
+    children,
+    ...props
+}: TooltipPrimitive.Popup.Props &
+    Pick<TooltipPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">) {
+    return (
+        <TooltipPrimitive.Portal container={usePortalContainer()}>
+            <TooltipPrimitive.Positioner
+                align={align}
+                alignOffset={alignOffset}
+                side={side}
+                sideOffset={sideOffset}
+                className="isolate z-50"
+            >
+                <TooltipPrimitive.Popup
+                    data-slot="tooltip-content"
+                    className={cn(
+                        // Inverted chip: max contrast against any surface, so it reads in high contrast too.
+                        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",
+                        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.Popup>
+            </TooltipPrimitive.Positioner>
+        </TooltipPrimitive.Portal>
+    );
+}
+
+export {Tooltip, TooltipContent, TooltipProvider, TooltipTrigger};

package/src/components/trace.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import {Collapsible, CollapsibleContent, CollapsibleTrigger} from "@repraze/kernelkit/components/collapsible";
+import {cn} from "cn";
+import {ChevronRightIcon} from "lucide-react";
+import * as React from "react";
+
+function Trace({className, ...props}: React.ComponentProps<"div">) {
+    return (
+        <div
+            data-slot="trace"
+            className={cn(
+                "flex w-full min-w-0 flex-col gap-2 *:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:rounded-md *:has-[>[data-slot=trace-line]]:text-left *:has-[>[data-slot=trace-line]]:outline-none *:has-[>[data-slot=trace-line]]:focus-visible:ring-3 *:has-[>[data-slot=trace-line]]:focus-visible:ring-ring/50 *:has-[>[data-slot=trace-line]]:-mx-1 *:has-[>[data-slot=trace-line]]:px-1",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function TraceLine({
+    className,
+    status,
+    ...props
+}: React.ComponentProps<"span"> & {
+    /** `running` shimmers the title, `error` turns the line danger, `pending` dims it. Omit when done. */
+    status?: "running" | "error" | "pending";
+}) {
+    return (
+        <span
+            data-slot="trace-line"
+            data-status={status}
+            className={cn(
+                "flex w-fit max-w-full min-w-0 items-center gap-2 text-sm text-muted-foreground transition-colors duration-100 in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-foreground data-[status=error]:text-danger data-[status=error]:in-[a:hover,button:hover]:text-danger data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:shimmer",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function TraceIcon({className, ...props}: React.ComponentProps<"span">) {
+    return (
+        <span
+            data-slot="trace-icon"
+            aria-hidden="true"
+            className={cn(
+                "flex size-4 shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [[data-slot=trace-title]~&]:-ml-1",
+                className,
+            )}
+            {...props}
+        />
+    );
+}
+
+function TraceTitle({className, ...props}: React.ComponentProps<"span">) {
+    return (
+        <span
+            data-slot="trace-title"
+            className={cn("min-w-0 truncate motion-reduce:shimmer-none", className)}
+            {...props}
+        />
+    );
+}
+
+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)}
+            {...props}
+        />
+    );
+}
+
+function TraceCollapsible({
+    className,
+    ...props
+}: Omit<React.ComponentProps<typeof Collapsible>, "open"> &
+    (
+        | {open?: undefined}
+        | {
+              open: boolean;
+              onOpenChange: NonNullable<React.ComponentProps<typeof Collapsible>["onOpenChange"]>;
+          }
+    )) {
+    return (
+        <Collapsible
+            data-slot="trace-collapsible"
+            className={cn("flex w-full min-w-0 flex-col", className)}
+            {...props}
+        />
+    );
+}
+
+function TraceCollapsibleTrigger({className, children, ...props}: React.ComponentProps<typeof CollapsibleTrigger>) {
+    return (
+        <CollapsibleTrigger
+            data-slot="trace-collapsible-trigger"
+            className={cn(
+                "group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center gap-1 rounded-md text-left text-muted-foreground transition-colors duration-100 outline-none hover:text-foreground hover:underline underline-offset-4 focus-visible:ring-3 focus-visible:ring-ring/50 -mx-1 px-1 aria-expanded:text-foreground has-[[data-status=error]]:text-danger",
+                className,
+            )}
+            {...props}
+        >
+            {children}
+            <TraceIcon className="transition-transform group-aria-expanded/trace-collapsible-trigger:rotate-90">
+                <ChevronRightIcon />
+            </TraceIcon>
+        </CollapsibleTrigger>
+    );
+}
+
+function TraceCollapsibleContent({className, children, ...props}: React.ComponentProps<typeof CollapsibleContent>) {
+    return (
+        <CollapsibleContent
+            data-slot="trace-collapsible-content"
+            className="h-(--collapsible-panel-height) min-w-0 overflow-hidden transition-[height] duration-150 data-ending-style:h-0 data-starting-style:h-0 motion-reduce:transition-none"
+            {...props}
+        >
+            <div
+                data-slot="trace-collapsible-content-inner"
+                className={cn(
+                    "mt-2 mb-1 ml-[calc(--spacing(2)-1px)] min-w-0 border-l border-border pr-1 pl-4 text-sm leading-relaxed wrap-break-word text-muted-foreground",
+                    className,
+                )}
+            >
+                {children}
+            </div>
+        </CollapsibleContent>
+    );
+}
+
+export {
+    Trace,
+    TraceCollapsible,
+    TraceCollapsibleContent,
+    TraceCollapsibleTrigger,
+    TraceDescription,
+    TraceIcon,
+    TraceLine,
+    TraceTitle,
+};