@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/recipes/frame/sidebar/nav.tsx

@@ -0,0 +1,46 @@
+import type { ComponentType, ReactElement } from 'react';
+import {
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from './blocks.tsx';
+
+/** A place to go: its name, icon, whether it's here, and the link to it. */
+export interface NavItem {
+  readonly title: string;
+  readonly icon?: ComponentType<{ readonly 'aria-hidden'?: boolean }>;
+  readonly active?: boolean;
+  /** The link, such as a router's `<Link to=… />`; its children are filled in. */
+  readonly render: ReactElement;
+}
+
+/** The sidebar's places, in groups, each with an optional label. */
+export type Nav = ReadonlyArray<{
+  readonly label?: string;
+  readonly items: ReadonlyArray<NavItem>;
+}>;
+
+export function NavList(props: { readonly nav: Nav }) {
+  return props.nav.map((group, index) => (
+    <SidebarGroup key={group.label ?? index}>
+      {group.label === undefined ? null : (
+        <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
+      )}
+      <SidebarGroupContent>
+        <SidebarMenu>
+          {group.items.map((item) => (
+            <SidebarMenuItem key={item.title}>
+              <SidebarMenuButton isActive={item.active} render={item.render}>
+                {item.icon === undefined ? null : <item.icon aria-hidden />}
+                <span>{item.title}</span>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroupContent>
+    </SidebarGroup>
+  ));
+}

package/src/recipes/frame/sidebar/resize-handle.tsx

@@ -0,0 +1,94 @@
+import { useRef, useState } from 'react';
+import { useFrame } from '../frame/index.ts';
+
+const MIN = 224;
+const MAX = 480;
+const STEP = 16;
+
+const clamp = (width: number) => Math.min(MAX, Math.max(MIN, width));
+
+// While dragging, the whole page keeps the resize cursor and no text selects.
+const holdCursor = (held: boolean) => {
+  document.body.style.cursor = held ? 'col-resize' : '';
+  document.body.style.userSelect = held ? 'none' : '';
+};
+
+/**
+ * The sidebar's right edge on a wide screen: drag it, or use the arrow keys,
+ * to resize the sidebar between 224 and 480 px; click it, or press Enter, to
+ * shut or open it.
+ */
+export function ResizeHandle(props: {
+  readonly width: number;
+  readonly onWidthChange: (width: number) => void;
+}) {
+  const { open, toggle } = useFrame();
+  const drag = useRef<{ x: number; width: number } | null>(null);
+  const moved = useRef(false);
+  const [resizing, setResizing] = useState(false);
+
+  const stop = () => {
+    drag.current = null;
+    setResizing(false);
+    holdCursor(false);
+  };
+
+  return (
+    <button
+      type="button"
+      role="separator"
+      aria-label="Resize the sidebar"
+      aria-orientation="vertical"
+      aria-valuemin={MIN}
+      aria-valuemax={MAX}
+      aria-valuenow={props.width}
+      aria-valuetext={`${props.width} pixels wide`}
+      title="Drag to resize the sidebar"
+      data-resizing={resizing}
+      className="absolute inset-y-0 right-0 z-20 hidden w-2 cursor-col-resize touch-none after:absolute after:inset-y-0 after:right-0 after:w-0.5 after:transition-[background-color] after:duration-150 hover:after:bg-primary/40 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring data-[resizing=true]:after:bg-primary/60 md:block"
+      onPointerDown={(event) => {
+        if (!open || event.button !== 0) return;
+        event.currentTarget.setPointerCapture(event.pointerId);
+        drag.current = { x: event.clientX, width: props.width };
+        moved.current = false;
+      }}
+      onPointerMove={(event) => {
+        if (drag.current === null) return;
+        const delta = event.clientX - drag.current.x;
+        if (!moved.current && Math.abs(delta) > 2) {
+          moved.current = true;
+          setResizing(true);
+          holdCursor(true);
+        }
+        if (moved.current)
+          props.onWidthChange(clamp(drag.current.width + delta));
+      }}
+      onPointerUp={(event) => {
+        if (drag.current === null) return;
+        event.currentTarget.releasePointerCapture(event.pointerId);
+        stop();
+      }}
+      onPointerCancel={() => {
+        moved.current = false;
+        stop();
+      }}
+      onClick={() => {
+        if (moved.current) {
+          moved.current = false;
+          return;
+        }
+        toggle();
+      }}
+      onKeyDown={(event) => {
+        if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+          event.preventDefault();
+          const direction = event.key === 'ArrowLeft' ? -1 : 1;
+          props.onWidthChange(clamp(props.width + direction * STEP));
+        } else if (event.key === 'Home' || event.key === 'End') {
+          event.preventDefault();
+          props.onWidthChange(event.key === 'Home' ? MIN : MAX);
+        }
+      }}
+    />
+  );
+}

package/src/recipes/frame/sidebar/sidebar.tsx

@@ -0,0 +1,44 @@
+import type { ReactNode } from 'react';
+import { type Nav, NavList } from './nav.tsx';
+import { ResizeHandle } from './resize-handle.tsx';
+
+/** What an app puts in its sidebar. */
+export interface SidebarConfig {
+  /** Top: the app, and a way back. */
+  readonly header?: ReactNode;
+  /** Middle: where you can go, as a list of groups… */
+  readonly nav?: Nav;
+  /** …or anything the list can't describe, built from the Sidebar pieces. */
+  readonly content?: ReactNode;
+  /** Bottom: who you are. */
+  readonly footer?: ReactNode;
+  /** Its width on a wide screen, in px: 256 unless set. */
+  readonly width?: number;
+  /** Lets people resize it by its edge on a wide screen. */
+  readonly onWidthChange?: (width: number) => void;
+}
+
+/** The sidebar, top to bottom: header, places, footer, and its edge. */
+export function SidebarContents(props: { readonly config: SidebarConfig }) {
+  const { config } = props;
+  return (
+    <>
+      {config.header === undefined ? null : (
+        <div className="flex flex-col gap-2 p-2">{config.header}</div>
+      )}
+      <div className="no-scrollbar flex min-h-0 flex-1 flex-col gap-2 overflow-auto">
+        {config.content ??
+          (config.nav === undefined ? null : <NavList nav={config.nav} />)}
+      </div>
+      {config.footer === undefined ? null : (
+        <div className="flex flex-col gap-2 p-2">{config.footer}</div>
+      )}
+      {config.onWidthChange === undefined ? null : (
+        <ResizeHandle
+          width={config.width ?? 256}
+          onWidthChange={config.onWidthChange}
+        />
+      )}
+    </>
+  );
+}

package/src/recipes/frame/sidebar/width.ts

@@ -0,0 +1,23 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * The sidebar's width on a wide screen, kept in `localStorage` under `key`
+ * so it stays as the person left it. Give both to `AppShell`'s sidebar
+ * (`width`, `onWidthChange`) to let them resize it by its edge.
+ */
+export const useSidebarWidth = (key: string, initial = 256) => {
+  const [width, setWidth] = useState(initial);
+  // Read after mount: the server renders the default.
+  useEffect(() => {
+    const stored = Number(localStorage.getItem(key));
+    if (Number.isFinite(stored) && stored > 0) setWidth(stored);
+  }, [key]);
+  const change = useCallback(
+    (next: number) => {
+      setWidth(next);
+      localStorage.setItem(key, String(next));
+    },
+    [key],
+  );
+  return [width, change] as const;
+};

package/src/recipes/gate-screens/gate-screens.tsx

@@ -0,0 +1,213 @@
+import { CircleAlert, LoaderCircle } from 'lucide-react';
+import { type ReactNode, useEffect, useState } from 'react';
+
+import { Button } from '#components/ui/button';
+import { GoogleButton } from '#components/ui/google-button';
+
+/** What stands in for an app while no Account is open, one per state. */
+export type GateScreen =
+  | { kind: 'checking' }
+  | { kind: 'signingOut' }
+  | { kind: 'opening'; name: string }
+  | { kind: 'signedOut'; unreachable: boolean }
+  | { kind: 'unopenable'; name: string };
+
+export interface GateScreensProps {
+  /** The app's name, as every screen titles it. */
+  title: string;
+  /** One line on what the app is for. */
+  description?: string;
+  /** The app's mark, above its name. */
+  mark?: ReactNode;
+  /** Whatever colors the status bar, such as the Theme's strip. */
+  statusBar?: ReactNode;
+  /** For the Google button. */
+  theme: 'light' | 'dark';
+  screen: GateScreen;
+  /** The Backend running, and whether the app has a device Backend to
+   * offer. */
+  backend: 'cloud' | 'device' | null;
+  hasDevice: boolean;
+  /** Why the last sign-in came back with nobody, shown once. */
+  loginError?: string | null;
+  onLoginErrorShown?: () => void;
+  onSignIn: () => Promise<void> | void;
+  onCheckAgain: () => void;
+  onRetry: () => void;
+  onSignOut: () => void;
+  onBackend: (backend: 'cloud' | 'device') => void;
+}
+
+/**
+ * Every screen an app shows before an Account is open: checking who is
+ * signed in, opening an Account, signing out, signed out (Google on the
+ * cloud Backend, a name on the device Backend, and the way to the other),
+ * and an Account that would not open. One card for all of them, so nothing
+ * jumps between them. An Account Lost is the Account Lost recipe.
+ */
+export function GateScreens(props: GateScreensProps) {
+  const { screen, title } = props;
+  switch (screen.kind) {
+    case 'checking':
+    case 'signingOut':
+    case 'opening':
+      return (
+        <Card {...props}>
+          <p
+            role="status"
+            className="flex h-10 items-center gap-2 text-sm text-muted-foreground"
+          >
+            <LoaderCircle
+              className="size-4 motion-safe:animate-spin"
+              aria-hidden="true"
+            />
+            {screen.kind === 'signingOut'
+              ? 'Signing out…'
+              : screen.kind === 'checking'
+                ? 'Checking who is signed in…'
+                : `Opening ${screen.name}’s ${title}…`}
+          </p>
+        </Card>
+      );
+    case 'unopenable':
+      return (
+        <Card {...props}>
+          <div className="space-y-3">
+            <p role="alert" className="text-sm text-destructive">
+              Couldn’t open {screen.name}’s {title} on this device.
+            </p>
+            <div className="flex gap-2">
+              <Button onClick={props.onRetry}>Try again</Button>
+              <Button variant="outline" onClick={props.onSignOut}>
+                Sign out {screen.name}
+              </Button>
+            </div>
+          </div>
+        </Card>
+      );
+    case 'signedOut':
+      return <SignedOut {...props} unreachable={screen.unreachable} />;
+  }
+}
+
+function SignedOut(props: GateScreensProps & { unreachable: boolean }) {
+  if (props.backend === 'device') {
+    return (
+      <Card {...props}>
+        <div className="space-y-3">
+          <Button onClick={() => void props.onSignIn()}>Sign in</Button>
+          <OtherBackend {...props} to="cloud" />
+        </div>
+      </Card>
+    );
+  }
+  if (props.unreachable) {
+    return (
+      <Card {...props}>
+        <div className="space-y-3">
+          <p role="alert" className="text-sm text-destructive">
+            Couldn’t reach the sign-in service.
+          </p>
+          <Button variant="outline" onClick={props.onCheckAgain}>
+            Try again
+          </Button>
+          {props.hasDevice && <OtherBackend {...props} to="device" />}
+        </div>
+      </Card>
+    );
+  }
+  return (
+    <Card {...props}>
+      <div className="space-y-3">
+        <GoogleSignIn {...props} />
+        {props.hasDevice && <OtherBackend {...props} to="device" />}
+      </div>
+    </Card>
+  );
+}
+
+// The way from one Backend to the other.
+function OtherBackend(props: GateScreensProps & { to: 'device' | 'cloud' }) {
+  return (
+    <p className="text-sm text-muted-foreground">
+      {props.to === 'device'
+        ? `Or try ${props.title} on this device, without an account.`
+        : 'Or sign in with Google, to keep everything on every device.'}{' '}
+      <Button
+        variant="link"
+        className="h-auto p-0"
+        onClick={() => props.onBackend(props.to)}
+      >
+        {props.to === 'device' ? 'Use this device' : 'Use Google'}
+      </Button>
+    </p>
+  );
+}
+
+function GoogleSignIn(props: GateScreensProps) {
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string>();
+  const { loginError, onLoginErrorShown } = props;
+  // The error a sign-in came back with, shown once.
+  useEffect(() => {
+    if (loginError == null) return;
+    setError(loginError);
+    onLoginErrorShown?.();
+  }, [loginError, onLoginErrorShown]);
+  const start = async () => {
+    setPending(true);
+    setError(undefined);
+    try {
+      await props.onSignIn();
+    } catch {
+      setError('The sign-in service didn’t answer. Try again.');
+    } finally {
+      setPending(false);
+    }
+  };
+  return (
+    <div className="space-y-3">
+      <div className="w-fit">
+        <GoogleButton
+          theme={props.theme}
+          disabled={pending}
+          aria-busy={pending || undefined}
+          onClick={() => void start()}
+        />
+      </div>
+      {error && (
+        <p
+          role="alert"
+          className="flex items-start gap-1.5 text-sm text-destructive"
+        >
+          <CircleAlert className="mt-0.5 size-4 shrink-0" aria-hidden="true" />
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+function Card(props: GateScreensProps & { children: ReactNode }) {
+  return (
+    <main className="grid min-h-dvh place-items-center px-6 py-12">
+      {props.statusBar}
+      <section className="w-full max-w-sm space-y-8">
+        <div className="space-y-4">
+          {props.mark}
+          <div className="space-y-2">
+            <h1 className="text-3xl font-semibold tracking-tight">
+              {props.title}
+            </h1>
+            {props.description && (
+              <p className="text-pretty text-muted-foreground">
+                {props.description}
+              </p>
+            )}
+          </div>
+        </div>
+        <div className="min-h-10">{props.children}</div>
+      </section>
+    </main>
+  );
+}

package/src/recipes/gate-screens/index.ts

@@ -0,0 +1,5 @@
+export {
+  type GateScreen,
+  GateScreens,
+  type GateScreensProps,
+} from './gate-screens';

package/src/recipes/kabuki-devtools/index.ts

@@ -0,0 +1 @@
+export { KabukiDevtools, Inspector } from './kabuki-devtools.tsx';

package/src/recipes/kabuki-devtools/ink/index.ts

@@ -0,0 +1,2 @@
+export { INK, TONE_NAMES, ink } from './ink.ts';
+export type { Tone } from './ink.ts';

package/src/recipes/kabuki-devtools/ink/ink.ts

@@ -0,0 +1,53 @@
+import type { CSSProperties } from 'react';
+
+/*
+ * The Inspector's colours: one name per thing the Map shows, each a CSS
+ * custom property set once on the Inspector and read everywhere below it.
+ *
+ * Built on the Theme: lit is the foreground, dim and lines are the
+ * foreground thinned, active is the Theme's positive and failed its
+ * destructive. The three it lacks, running, message and command, are written
+ * here in OKLCH as `light-dark()` pairs, so they follow the Theme's
+ * `color-scheme` with no class of their own: darker and more vivid on a
+ * light ground, lighter and calmer on a dark one.
+ */
+
+/** Everything the Map colours, by what it means. */
+const TONES = {
+  /** What runs, or the State an Instance is in. */
+  lit: 'var(--foreground)',
+  /** What only could run. */
+  dim: 'color-mix(in oklch, var(--foreground) 32%, transparent)',
+  /** A Link to something dim. */
+  line: 'color-mix(in oklch, var(--foreground) 14%, transparent)',
+  /** A Link to something lit. */
+  'line-lit': 'color-mix(in oklch, var(--foreground) 42%, transparent)',
+  /** The State an Instance is in. */
+  active: 'var(--positive)',
+  'active-soft': 'light-dark(oklch(0.95 0.045 145), oklch(0.32 0.07 145))',
+  /** A Worker at work. */
+  running: 'light-dark(oklch(0.58 0.12 205), oklch(0.78 0.11 205))',
+  /** A Worker that failed. */
+  failed: 'var(--destructive)',
+  /** The Step's Message: its Send and its Request. */
+  message: 'light-dark(oklch(0.55 0.2 262), oklch(0.74 0.14 262))',
+  'message-soft': 'light-dark(oklch(0.95 0.03 262), oklch(0.3 0.07 262))',
+  /** A Command the Step's Update asked for. */
+  command: 'light-dark(oklch(0.62 0.15 60), oklch(0.8 0.13 70))',
+  'command-soft': 'light-dark(oklch(0.96 0.04 70), oklch(0.32 0.06 65))',
+  /** Its dot grid. */
+  grain: 'color-mix(in oklch, var(--foreground) 9%, transparent)',
+} as const;
+
+export type Tone = keyof typeof TONES;
+
+/** The custom properties to set on the Inspector, once. */
+export const INK = Object.fromEntries(
+  Object.entries(TONES).map(([tone, value]) => [`--kabuki-${tone}`, value]),
+) as CSSProperties;
+
+/** A tone, as a CSS value to use anywhere below the Inspector. */
+export const ink = (tone: Tone) => `var(--kabuki-${tone})`;
+
+/** Every tone, for a swatch. */
+export const TONE_NAMES = Object.keys(TONES) as ReadonlyArray<Tone>;