@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/recipes/kabuki-devtools/timeline/timeline.tsx

@@ -0,0 +1,206 @@
+import { useEffect, useRef } from 'react';
+import { ChevronLeft, ChevronRight, GitBranch } from 'lucide-react';
+import { cn } from '../../../components/lib/utils.ts';
+import { ink } from '../ink/index.ts';
+
+/*
+ * The Timeline: the bar under the Map for picking the Step shown.
+ *
+ * 1. Step    one step back or on.
+ * 2. Track   one tick per Step on the Branch in view, init first; the one
+ *            shown stands taller, and stays scrolled into view.
+ * 3. Read    the Step shown: its place and its Message, once there is room.
+ * 4. Branch  bring another Branch into view, when there is more than one.
+ * 5. Live    back to the Head, or the sign that it is there.
+ */
+
+export interface TimelineStep {
+  readonly id: string;
+  readonly label: string;
+}
+
+export interface TimelineBranch {
+  readonly id: string;
+  readonly label: string;
+}
+
+export function Timeline({
+  steps,
+  shown,
+  live,
+  onShow,
+  onLive,
+  branches = [],
+  branch,
+  onBranch,
+}: {
+  /** Every Step on the Branch in view, init first. */
+  readonly steps: ReadonlyArray<TimelineStep>;
+  /** The place of the Step shown. */
+  readonly shown: number;
+  /** Showing the Head of the running app. */
+  readonly live: boolean;
+  readonly onShow: (index: number) => void;
+  readonly onLive: () => void;
+  readonly branches?: ReadonlyArray<TimelineBranch>;
+  /** The Branch in view. */
+  readonly branch?: string;
+  readonly onBranch?: (id: string) => void;
+}) {
+  const track = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    track.current
+      ?.querySelector<HTMLElement>('[aria-current="step"]')
+      ?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+  }, [shown]);
+
+  const step = steps[shown];
+  const last = steps.length - 1;
+
+  return (
+    <div className="bg-background/90 flex h-14 shrink-0 items-center gap-2 border-t px-2 backdrop-blur-sm @md:gap-3 @md:px-3">
+      {/* 1. Step */}
+      <div className="flex">
+        <Press
+          label="Step back"
+          disabled={shown <= 0}
+          onClick={() => onShow(shown - 1)}
+        >
+          <ChevronLeft />
+        </Press>
+        <Press
+          label="Step on"
+          disabled={shown >= last}
+          onClick={() => onShow(shown + 1)}
+        >
+          <ChevronRight />
+        </Press>
+      </div>
+
+      {/* 2. Track */}
+      <div
+        ref={track}
+        role="list"
+        aria-label="Steps"
+        className="flex h-full min-w-0 flex-1 items-center gap-[3px] overflow-x-auto px-1 [scrollbar-width:none]"
+      >
+        {steps.map((each, index) => (
+          <button
+            key={each.id}
+            type="button"
+            role="listitem"
+            title={`${index === 0 ? 'init' : `${index}. ${each.label}`}`}
+            aria-label={index === 0 ? 'init' : `Step ${index}, ${each.label}`}
+            aria-current={index === shown ? 'step' : undefined}
+            onClick={() => onShow(index)}
+            className="group grid h-8 w-2.5 shrink-0 place-items-center outline-none"
+          >
+            <span
+              className={cn(
+                'w-[3px] rounded-full transition-[height,background-color] duration-150',
+                index === shown
+                  ? 'h-6'
+                  : 'group-hover:bg-foreground/50 h-3 group-focus-visible:h-5',
+              )}
+              style={{
+                backgroundColor:
+                  index === shown
+                    ? ink('message')
+                    : index < shown
+                      ? ink('line-lit')
+                      : ink('line'),
+              }}
+            />
+          </button>
+        ))}
+      </div>
+
+      {/* 3. Read */}
+      {step && (
+        <div className="hidden min-w-0 flex-col items-end leading-tight @md:flex">
+          <span className="truncate text-xs font-medium">
+            {shown === 0 ? 'init' : step.label}
+          </span>
+          <span className="text-muted-foreground text-[10.5px] tabular-nums">
+            {shown} of {last}
+          </span>
+        </div>
+      )}
+
+      {/* 4. Branch */}
+      {branches.length > 1 && onBranch && (
+        <label className="text-muted-foreground hover:text-foreground relative flex h-9 items-center gap-1.5 rounded-md border px-2 text-xs transition-colors duration-150 focus-within:ring-2">
+          <GitBranch className="size-3.5" />
+          <span className="sr-only">Branch in view</span>
+          <select
+            value={branch}
+            onChange={(event) => onBranch(event.target.value)}
+            className="bg-transparent outline-none"
+          >
+            {branches.map((each) => (
+              <option key={each.id} value={each.id}>
+                {each.label}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+
+      {/* 5. Live */}
+      <button
+        type="button"
+        onClick={onLive}
+        disabled={live}
+        className={cn(
+          'flex h-9 items-center gap-2 rounded-md border px-3 text-xs font-medium transition-[background-color,color,scale] duration-150 outline-none focus-visible:ring-2 active:scale-[0.97]',
+          live
+            ? 'text-foreground cursor-default'
+            : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+        )}
+      >
+        <span className="relative grid size-2 place-items-center">
+          {live && (
+            <span
+              className="absolute inset-0 animate-ping rounded-full opacity-60 motion-reduce:hidden"
+              style={{ backgroundColor: ink('active') }}
+            />
+          )}
+          <span
+            className="size-2 rounded-full border"
+            style={
+              live
+                ? { backgroundColor: ink('active'), borderColor: ink('active') }
+                : { borderColor: 'currentColor' }
+            }
+          />
+        </span>
+        {live ? 'Live' : 'Go live'}
+      </button>
+    </div>
+  );
+}
+
+function Press({
+  label,
+  disabled,
+  onClick,
+  children,
+}: {
+  readonly label: string;
+  readonly disabled: boolean;
+  readonly onClick: () => void;
+  readonly children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      disabled={disabled}
+      onClick={onClick}
+      className="text-muted-foreground hover:text-foreground hover:bg-muted grid size-9 place-items-center rounded-md transition-colors duration-150 outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-40 [&_svg]:size-4"
+    >
+      {children}
+    </button>
+  );
+}

package/src/recipes/key-bindings/index.ts

@@ -0,0 +1 @@
+export * from './key-bindings.tsx';

package/src/recipes/key-bindings/key-bindings.tsx

@@ -0,0 +1,80 @@
+import { Kbd, KbdGroup } from '#components/ui/kbd';
+import { cn } from '#lib/utils';
+import type { Binding, Shortcut } from '@kestack/use-keys';
+
+/** Whether this is an Apple device, where `mod` is Cmd. */
+const mac = () =>
+  typeof navigator !== 'undefined' &&
+  /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+
+/**
+ * One recorded key, as a Shortcut: Cmd on a Mac or Ctrl elsewhere becomes
+ * `mod`, so the key works on both.
+ */
+export const recorded = (name: string, held: ReadonlySet<string>): Shortcut => {
+  const apple = mac();
+  return {
+    type: 'shortcut',
+    key: name as Shortcut['key'],
+    mod: held.has(apple ? 'Meta' : 'Control'),
+    ctrl: apple && held.has('Control'),
+    alt: held.has('Alt'),
+    // A symbol is the character typed, so Shift is part of it.
+    shift: held.has('Shift') && /^[a-z]$|^[A-Z]/.test(name),
+    meta: !apple && held.has('Meta'),
+  };
+};
+
+const KEY_NAMES: Readonly<Record<string, string>> = {
+  ArrowUp: '↑',
+  ArrowDown: '↓',
+  ArrowLeft: '←',
+  ArrowRight: '→',
+  Enter: '↵',
+  Escape: 'Esc',
+  Space: 'Space',
+};
+
+// A Shortcut as its keys read on this platform: ⌘K on a Mac, Ctrl K elsewhere.
+const labels = (step: Shortcut) => {
+  const apple = mac();
+  return [
+    step.mod !== false && (apple ? '⌘' : 'Ctrl'),
+    step.ctrl !== false && (apple ? '⌃' : 'Ctrl'),
+    step.alt !== false && (apple ? '⌥' : 'Alt'),
+    step.shift !== false && '⇧',
+    step.meta !== false && (apple ? '⌘' : 'Win'),
+    KEY_NAMES[step.key] ?? step.key.toUpperCase(),
+  ].filter((label) => label !== false);
+};
+
+/**
+ * A Binding's keys, step by step: `G` `G`, or `⌘` `K`. A hint shows only
+ * where there is a keyboard and Keys are on; `always` shows it anyway, as
+ * Settings lists every key.
+ */
+export function BindingKeys(props: {
+  readonly binding: Binding;
+  readonly always?: boolean;
+  readonly className?: string;
+}) {
+  const steps =
+    props.binding.type === 'shortcut' ? [props.binding] : props.binding.steps;
+  return (
+    <KbdGroup
+      className={cn(
+        'gap-0.5',
+        props.always !== true && 'hidden keys:inline-flex',
+        props.className,
+      )}
+    >
+      {steps.map((step, i) => (
+        <KbdGroup key={i} className="gap-0.5">
+          {labels(step).map((label) => (
+            <Kbd key={label}>{label}</Kbd>
+          ))}
+        </KbdGroup>
+      ))}
+    </KbdGroup>
+  );
+}

package/src/recipes/local-sign-in/index.ts

@@ -0,0 +1,5 @@
+export {
+  LocalSignIn,
+  type LocalSignInChoice,
+  type LocalSignInProps,
+} from './local-sign-in';

package/src/recipes/local-sign-in/local-sign-in.tsx

@@ -0,0 +1,148 @@
+import { useId, useState, type FormEvent } from 'react';
+
+import { Avatar, AvatarFallback } from '#components/ui/avatar';
+import { Button } from '#components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '#components/ui/dialog';
+import { Input } from '#components/ui/input';
+import { Label } from '#components/ui/label';
+import { cn } from '#lib/utils';
+
+import { MaskedEmail } from '../parts/email-privacy';
+
+/** Who to sign in as, when sign-in is local. */
+export interface LocalSignInChoice {
+  email: string;
+  name?: string;
+}
+
+export interface LocalSignInProps {
+  open: boolean;
+  presets: ReadonlyArray<LocalSignInChoice>;
+  onChoose: (choice: LocalSignInChoice) => void;
+  /** Called when the User closes the dialog without choosing. */
+  onCancel: () => void;
+}
+
+const initials = (choice: LocalSignInChoice) =>
+  (choice.name || choice.email)
+    .split(/[\s@]+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part.charAt(0).toUpperCase())
+    .join('');
+
+function PresetButton({
+  choice,
+  onChoose,
+}: {
+  choice: LocalSignInChoice;
+  onChoose: (choice: LocalSignInChoice) => void;
+}) {
+  return (
+    <Button
+      variant="ghost"
+      className="h-auto w-full justify-start gap-3 px-2 py-2 text-left font-normal"
+      onClick={() => onChoose(choice)}
+    >
+      <Avatar className="size-7 text-[0.6rem]">
+        <AvatarFallback>{initials(choice)}</AvatarFallback>
+      </Avatar>
+      <span className="flex min-w-0 flex-1 flex-col">
+        {choice.name ? (
+          <span className="truncate text-sm">{choice.name}</span>
+        ) : null}
+        <span
+          className={cn(
+            'truncate',
+            choice.name ? 'text-xs text-muted-foreground' : 'text-sm',
+          )}
+        >
+          <MaskedEmail email={choice.email} />
+        </span>
+      </span>
+    </Button>
+  );
+}
+
+/** Stands in for a real sign-in when an app runs on its own: the
+ * User picks a preset or types who they want to be. */
+export function LocalSignIn({
+  open,
+  presets,
+  onChoose,
+  onCancel,
+}: LocalSignInProps) {
+  const id = useId();
+  const [email, setEmail] = useState('');
+  const [name, setName] = useState('');
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault();
+    const trimmed = email.trim();
+    if (!trimmed) return;
+    onChoose(
+      name.trim() ? { email: trimmed, name: name.trim() } : { email: trimmed },
+    );
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={(next) => !next && onCancel()}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Who should sign in?</DialogTitle>
+          <DialogDescription>
+            Nothing here leaves this device. Pick anyone to continue as.
+          </DialogDescription>
+        </DialogHeader>
+        {presets.length > 0 ? (
+          <div className="-mx-2 flex flex-col gap-1">
+            {presets.map((choice) => (
+              <PresetButton
+                key={choice.email}
+                choice={choice}
+                onChoose={onChoose}
+              />
+            ))}
+          </div>
+        ) : null}
+        <form onSubmit={submit} className="flex flex-col gap-4">
+          <div className="flex flex-col gap-2">
+            <Label htmlFor={`${id}-email`}>Email</Label>
+            <Input
+              id={`${id}-email`}
+              type="email"
+              required
+              value={email}
+              onChange={(event) => setEmail(event.target.value)}
+              autoComplete="off"
+              spellCheck={false}
+              data-1p-ignore
+              placeholder="someone@example.com"
+            />
+          </div>
+          <div className="flex flex-col gap-2">
+            <Label htmlFor={`${id}-name`}>
+              Name <span className="text-muted-foreground">(optional)</span>
+            </Label>
+            <Input
+              id={`${id}-name`}
+              value={name}
+              onChange={(event) => setName(event.target.value)}
+              autoComplete="off"
+              data-1p-ignore
+            />
+          </div>
+          <Button type="submit" disabled={email.trim() === ''}>
+            Sign in
+          </Button>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/recipes/parts/email-privacy/email-privacy.tsx

@@ -0,0 +1,52 @@
+import { Eye, EyeOff } from 'lucide-react';
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+import { Button } from '#components/ui/button';
+import { cn } from '#lib/utils';
+
+interface EmailPrivacy {
+  masked: boolean;
+  toggle: () => void;
+}
+
+export const useEmailPrivacy = create<EmailPrivacy>()(
+  persist(
+    (set) => ({
+      masked: false,
+      toggle: () => set((state) => ({ masked: !state.masked })),
+    }),
+    { name: 'auth:mask-email' },
+  ),
+);
+
+export function MaskedEmail({ email }: { email: string }) {
+  const masked = useEmailPrivacy((state) => state.masked);
+  return (
+    <span
+      aria-label={masked ? 'Email address hidden' : undefined}
+      className={cn(
+        'inline-block max-w-full truncate align-bottom',
+        masked && 'select-none blur-xs',
+      )}
+    >
+      {email}
+    </span>
+  );
+}
+
+export function EmailToggle() {
+  const { masked, toggle } = useEmailPrivacy();
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      aria-label={masked ? 'Show email address' : 'Hide email address'}
+      aria-pressed={masked}
+      className="relative text-muted-foreground before:absolute before:-inset-1 hover:text-foreground"
+      onClick={toggle}
+    >
+      {masked ? <EyeOff /> : <Eye />}
+    </Button>
+  );
+}

package/src/recipes/parts/email-privacy/index.ts

@@ -0,0 +1 @@
+export { EmailToggle, MaskedEmail, useEmailPrivacy } from './email-privacy';

package/src/recipes/swipe-row/index.ts

@@ -0,0 +1 @@
+export { SwipeRow } from './swipe-row.tsx';

package/src/recipes/swipe-row/swipe-row.tsx

@@ -0,0 +1,97 @@
+import { Trash2 } from '#lib/lucide';
+import { cn } from '#lib/utils';
+import { GestureZone, useSwipe } from '../../input/index.ts';
+import {
+  animate,
+  motion,
+  useMotionValue,
+  useMotionValueEvent,
+  useTransform,
+} from 'motion/react';
+import { type ReactNode, useRef, useState } from 'react';
+import { play } from '../../feedback/index.ts';
+
+// How far, in px, the row goes left before letting go deletes it.
+const DELETE_AT = 112;
+
+const SPRING = { type: 'spring', duration: 0.35, bounce: 0.15 } as const;
+
+/**
+ * A row that one finger swipes left to delete. As it goes, Delete shows
+ * behind it; past DELETE_AT it arms, with a click and a buzz, and letting
+ * go then slides it away and deletes it. Coming back short, or letting go
+ * before, springs it home. A mouse never swipes it: keys delete instead.
+ * `sounds` is whether it clicks as it arms and goes; on unless switched off.
+ */
+export function SwipeRow(props: {
+  readonly onDelete: () => void;
+  readonly sounds?: boolean;
+  readonly children: ReactNode;
+}) {
+  // The row is a Gesture Zone of its own, so its Swipe hears only it.
+  return (
+    <GestureZone className="relative overflow-hidden rounded-lg">
+      <Swiped {...props} />
+    </GestureZone>
+  );
+}
+
+function Swiped(props: {
+  readonly onDelete: () => void;
+  readonly sounds?: boolean;
+  readonly children: ReactNode;
+}) {
+  const sounds = props.sounds ?? true;
+  const row = useRef<HTMLDivElement>(null);
+  const x = useMotionValue(0);
+  const [armed, setArmed] = useState(false);
+  const shown = useTransform(x, [0, -24], [0, 1]);
+  const latest = useRef({ props, sounds });
+  latest.current = { props, sounds };
+
+  const home = () => void animate(x, 0, SPRING);
+  const swipe = useSwipe({
+    direction: 'left',
+    commit: { distance: DELETE_AT },
+    onCommit: () => {
+      const width = row.current?.offsetWidth ?? 400;
+      if (latest.current.sounds) play('success');
+      void animate(x, -width, { duration: 0.18, ease: [0.4, 0, 1, 1] }).then(
+        () => latest.current.props.onDelete(),
+      );
+    },
+    onCancel: home,
+  });
+
+  useMotionValueEvent(swipe.offset, 'change', (offset) => x.set(-offset));
+  useMotionValueEvent(swipe.willCommit, 'change', (will) => {
+    setArmed(will);
+    if (!will) return;
+    if (latest.current.sounds) play('arm');
+    navigator.vibrate?.(8);
+  });
+
+  return (
+    <>
+      <motion.div
+        aria-hidden="true"
+        style={{ opacity: shown }}
+        className={cn(
+          'absolute inset-0 flex items-center justify-end gap-2 rounded-lg pr-5 text-sm font-medium text-destructive transition-colors duration-150',
+          armed ? 'bg-destructive/20' : 'bg-destructive/10',
+        )}
+      >
+        <motion.span
+          animate={{ scale: armed ? 1.15 : 1 }}
+          transition={{ type: 'spring', duration: 0.3, bounce: 0.45 }}
+          className="flex items-center gap-1.5"
+        >
+          <Trash2 className="size-4" aria-hidden="true" /> Delete
+        </motion.span>
+      </motion.div>
+      <motion.div ref={row} style={{ x }} className="relative bg-background">
+        {props.children}
+      </motion.div>
+    </>
+  );
+}

package/src/recipes/thumb-picker/choice.ts

@@ -0,0 +1,14 @@
+import type { ComponentType } from 'react';
+
+/**
+ * One thing to choose: its name, its icon, what choosing it does, and the
+ * choices inside it. A choice with none to do is only a way in to its own.
+ * How a swipe walks a tree of them is use-gesture's Tree Walk.
+ */
+export type Choice = {
+  readonly id: string;
+  readonly label: string;
+  readonly icon?: ComponentType<{ readonly className?: string }>;
+  readonly onSelect?: () => void;
+  readonly children?: ReadonlyArray<Choice>;
+};

package/src/recipes/thumb-picker/index.ts

@@ -0,0 +1 @@
+export { type Choice, ThumbPicker } from './thumb-picker.tsx';

package/src/recipes/thumb-picker/list.tsx

@@ -0,0 +1,73 @@
+import { ChevronRight } from '#lib/lucide';
+import { cn } from '#lib/utils';
+import { TreeWalk } from '@kestack/use-gesture';
+import { motion, type Transition } from 'motion/react';
+import type { Choice } from './choice.ts';
+
+/**
+ * Every choice of one list in order, the marked one under a highlight that
+ * springs from row to row, a dot beside where the swipe began, and a
+ * chevron on each choice with choices inside it, nudged toward them when
+ * marked.
+ */
+export function List(props: {
+  readonly id: string;
+  readonly choices: ReadonlyArray<Choice>;
+  readonly marked: number;
+  readonly here: number | undefined;
+  readonly move: Transition;
+}) {
+  return (
+    <ul className="grid min-w-44 p-1">
+      {props.choices.map((choice, index) => {
+        const marked = index === props.marked;
+        return (
+          <li
+            key={choice.id}
+            aria-current={marked || undefined}
+            className="relative flex items-center gap-2.5 px-2.5 py-1.5"
+          >
+            {marked && (
+              <motion.span
+                layoutId={`thumb-picker-mark-${props.id}`}
+                transition={props.move}
+                className="absolute inset-0 rounded-[10px] bg-accent"
+              />
+            )}
+            {choice.icon && (
+              <choice.icon
+                className={cn(
+                  'relative size-4',
+                  !marked && 'text-muted-foreground',
+                )}
+              />
+            )}
+            <span
+              className={cn(
+                'relative flex-1 truncate',
+                marked && 'font-medium',
+              )}
+            >
+              {choice.label}
+            </span>
+            {index === props.here && (
+              <span
+                aria-label="Where you are"
+                className="relative size-1.5 rounded-full bg-muted-foreground"
+              />
+            )}
+            {TreeWalk.opens(choice) && (
+              <ChevronRight
+                aria-label="Has more inside"
+                className={cn(
+                  'relative -mr-1 size-3.5 text-muted-foreground transition-transform duration-150',
+                  marked && 'translate-x-0.5 text-foreground',
+                )}
+              />
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}