@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/form/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Metadata about a form field's current state
+ */
+export interface FieldMeta {
+  isTouched: boolean;
+  isBlurred: boolean;
+  isDirty: boolean;
+  isValidating: boolean;
+  isInvalid: boolean;
+  errors: string[];
+}
+
+/**
+ * Common props shared across all form field components
+ */
+export interface BaseFieldProps {
+  label?: string;
+  description?: string;
+  required?: boolean;
+  disabled?: boolean;
+  placeholder?: string;
+  className?: string;
+  showAllErrors?: boolean;
+}
+
+/**
+ * Field state interface matching TanStack Form's field.state.meta
+ */
+interface FieldStateMeta {
+  isTouched: boolean;
+  isBlurred: boolean;
+  isDirty: boolean;
+  isValidating: boolean;
+  errors: unknown[];
+}
+
+/**
+ * Minimal field interface for extracting metadata
+ */
+interface FieldLike {
+  state: {
+    meta: FieldStateMeta;
+  };
+}
+
+/**
+ * Extract field metadata from a FieldApi instance
+ */
+export function toFieldErrors(
+  errors: string[],
+  showAll: boolean,
+): Array<{ message: string }> {
+  return (showAll ? errors : errors.slice(0, 1)).map((message) => ({
+    message,
+  }));
+}
+
+export function getFieldMeta(field: FieldLike): FieldMeta {
+  const { state } = field;
+  const errors = state.meta.errors
+    .map((e: unknown) =>
+      typeof e === 'string'
+        ? e
+        : ((e as { message?: string } | null)?.message ?? String(e)),
+    )
+    .filter(Boolean) as string[];
+
+  return {
+    isTouched: state.meta.isTouched,
+    isBlurred: state.meta.isBlurred,
+    isDirty: state.meta.isDirty,
+    isValidating: state.meta.isValidating,
+    isInvalid: errors.length > 0,
+    errors,
+  };
+}

package/src/input/device/device.ts

@@ -0,0 +1,83 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * What this device can be driven by. A device may have both: a laptop with
+ * a touch screen, an iPad with a keyboard.
+ */
+export type Device = {
+  /** A keyboard, or a mouse that hovers, which nearly always has one. */
+  readonly keyboard: boolean;
+  /** A touch screen. */
+  readonly touch: boolean;
+};
+
+const FINE = '(hover: hover) and (pointer: fine)';
+const COARSE = '(any-pointer: coarse)';
+
+/**
+ * Marks `<html>` with `data-keyboard` and `data-touch` before the first
+ * paint, so CSS shows the right hints without a flash. Inline it in the
+ * document's head.
+ */
+export const DEVICE_SCRIPT = `(()=>{const h=document.documentElement;if(matchMedia('${FINE}').matches)h.dataset.keyboard='';if(matchMedia('${COARSE}').matches)h.dataset.touch=''})()`;
+
+const SERVER: Device = { keyboard: false, touch: false };
+
+let device: Device | undefined;
+const listeners = new Set<() => void>();
+
+const read = (): Device => {
+  const html = document.documentElement;
+  return {
+    keyboard: 'keyboard' in html.dataset || matchMedia(FINE).matches,
+    touch: matchMedia(COARSE).matches,
+  };
+};
+
+const write = (next: Device) => {
+  const html = document.documentElement;
+  html.toggleAttribute('data-keyboard', next.keyboard);
+  html.toggleAttribute('data-touch', next.touch);
+  if (device?.keyboard === next.keyboard && device.touch === next.touch) return;
+  device = next;
+  for (const listener of listeners) listener();
+};
+
+const editable = (target: EventTarget | null) =>
+  target instanceof HTMLElement &&
+  (target.isContentEditable ||
+    /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName));
+
+// A key pressed outside a text field is a real keyboard: an on-screen one
+// only types into fields. Once seen, it stays for the visit.
+const onKey = (event: KeyboardEvent) => {
+  if (device?.keyboard || editable(event.target)) return;
+  write({ ...read(), keyboard: true });
+};
+
+const onMedia = () => write(read());
+
+const subscribe = (listener: () => void) => {
+  if (listeners.size === 0) {
+    write(read());
+    window.addEventListener('keydown', onKey, true);
+    matchMedia(FINE).addEventListener('change', onMedia);
+    matchMedia(COARSE).addEventListener('change', onMedia);
+  }
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size > 0) return;
+    window.removeEventListener('keydown', onKey, true);
+    matchMedia(FINE).removeEventListener('change', onMedia);
+    matchMedia(COARSE).removeEventListener('change', onMedia);
+  };
+};
+
+/** What this device can be driven by, live. */
+export const useDevice = () =>
+  useSyncExternalStore(
+    subscribe,
+    () => (device ??= read()),
+    () => SERVER,
+  );

package/src/input/device/index.ts

@@ -0,0 +1 @@
+export { DEVICE_SCRIPT, type Device, useDevice } from './device.ts';

package/src/input/gesture/index.ts

@@ -0,0 +1,26 @@
+// The web: the browser as the touch source, Gesture Zones as DOM elements,
+// and every finger as Motion values, over the platform-free core.
+export { GestureProvider, GestureZone, useGesture } from './zones/index.ts';
+export type {
+  Directions,
+  GestureEnd,
+  GestureOptions,
+  GestureState,
+  GestureZoneProps,
+  Pointer,
+  Pointers,
+} from './zones/index.ts';
+export { useSwipe } from './recognizers/index.ts';
+export type {
+  CommitRule,
+  Direction,
+  Edge,
+  Fingers,
+  Swipe,
+  SwipeCancel,
+  SwipeOptions,
+  SwipeRelease,
+  SwipeState,
+} from './recognizers/index.ts';
+export { usePullToRefresh, useSidebar } from './patterns/index.ts';
+export type { PullState } from './patterns/index.ts';

package/src/input/gesture/patterns/index.ts

@@ -0,0 +1,3 @@
+export { usePullToRefresh } from './pull-to-refresh/index.ts';
+export type { PullState } from './pull-to-refresh/index.ts';
+export { useSidebar } from './sidebar/index.ts';

package/src/input/gesture/patterns/pull-to-refresh/index.ts

@@ -0,0 +1,6 @@
+export { usePullToRefresh } from './use-pull-to-refresh.ts';
+export type {
+  PullState,
+  PullToRefresh,
+  PullToRefreshOptions,
+} from './use-pull-to-refresh.ts';

package/src/input/gesture/patterns/pull-to-refresh/use-pull-to-refresh.ts

@@ -0,0 +1,101 @@
+import {
+  type AnimationPlaybackControls,
+  animate,
+  type MotionValue,
+  useMotionValue,
+  useTransform,
+} from 'motion/react';
+import { useEffect, useRef, useState } from 'react';
+import { useSwipe } from '../../recognizers/index.ts';
+
+export type PullToRefreshOptions = {
+  /** Runs once a pull is released armed; the indicator holds until it settles. */
+  readonly onRefresh: () => Promise<unknown> | void;
+  /** How far, in px, the indicator travels to be armed: 72 by default. */
+  readonly distance?: number;
+  /** Whether a Swipe down pulls: true by default. */
+  readonly enabled?: boolean;
+};
+
+/**
+ * `pulling` while fingers pull short of `distance`, `armed` past it, and
+ * `refreshing` from an armed release until `onRefresh` settles.
+ */
+export type PullState = 'idle' | 'pulling' | 'armed' | 'refreshing';
+
+export type PullToRefresh = {
+  /** The indicator's offset in px, with resistance: it reaches `distance` at twice that pull. */
+  readonly y: MotionValue<number>;
+  /** 0 to 1 toward armed. */
+  readonly progress: MotionValue<number>;
+  readonly state: PullState;
+};
+
+const SPRING = { type: 'spring', stiffness: 400, damping: 40 } as const;
+
+/** Px of indicator for `offset` px of pull: slows as it goes, `limit` at most. */
+export const resist = (offset: number, limit: number) =>
+  (limit * offset) / (offset + limit);
+
+/**
+ * Pull to refresh: a Swipe down that the indicator follows with resistance,
+ * refreshing when released past `distance`. It starts only where the list is
+ * already at its top, since a list that can still scroll keeps the touch.
+ */
+export function usePullToRefresh(options: PullToRefreshOptions): PullToRefresh {
+  const { distance = 72, enabled = true } = options;
+  const limit = distance * 2;
+  const y = useMotionValue(0);
+  const progress = useTransform(y, [0, distance], [0, 1]);
+  const [state, setState] = useState<PullState>('idle');
+  const pulling = useRef(false);
+  const animation = useRef<AnimationPlaybackControls | undefined>(undefined);
+
+  const to = (value: number) => {
+    animation.current?.stop();
+    animation.current = animate(y, value, SPRING);
+  };
+
+  const back = () => {
+    pulling.current = false;
+    to(0);
+    setState('idle');
+  };
+
+  const swipe = useSwipe({
+    enabled: enabled && state !== 'refreshing',
+    direction: 'down',
+    commit: { distance: limit },
+    onStart: () => {
+      animation.current?.stop();
+      pulling.current = true;
+      setState('pulling');
+    },
+    onCommit: () => {
+      pulling.current = false;
+      to(distance);
+      setState('refreshing');
+      void Promise.resolve().then(options.onRefresh).finally(back);
+    },
+    onCancel: () => {
+      if (pulling.current) back();
+    },
+  });
+
+  useEffect(() => {
+    const offOffset = swipe.offset.on('change', (offset) => {
+      if (pulling.current) y.set(resist(offset, limit));
+    });
+    const offArmed = swipe.willCommit.on('change', (armed) => {
+      if (pulling.current) setState(armed ? 'armed' : 'pulling');
+    });
+    return () => {
+      offOffset();
+      offArmed();
+    };
+  });
+
+  useEffect(() => () => animation.current?.stop(), []);
+
+  return { y, progress, state };
+}

package/src/input/gesture/patterns/sidebar/index.ts

@@ -0,0 +1,2 @@
+export { useSidebar } from './use-sidebar.ts';
+export type { Sidebar, SidebarOptions } from './use-sidebar.ts';

package/src/input/gesture/patterns/sidebar/use-sidebar.ts

@@ -0,0 +1,201 @@
+import {
+  type AnimationPlaybackControls,
+  animate,
+  type MotionValue,
+  useMotionValue,
+  useTransform,
+} from 'motion/react';
+import { useEffect, useRef, useState } from 'react';
+import { useGesture } from '../../zones/index.ts';
+import { type SwipeRelease, useSwipe } from '../../recognizers/index.ts';
+
+export type SidebarOptions = {
+  /** The screen edge it lives on. */
+  readonly side: 'left' | 'right';
+  /** Its width in px: how far it travels. */
+  readonly width: number;
+  /** Whether it is open, when the app controls it. */
+  readonly open?: boolean;
+  /** Whether it starts open, when it controls itself. */
+  readonly defaultOpen?: boolean;
+  readonly onOpenChange?: (open: boolean) => void;
+  /**
+   * Opt in to opening only from a strip along `side`, this many px wide.
+   * Without it, a Swipe that starts anywhere opens it. Either way a
+   * one-finger touch that starts in the strip, EDGE_STRIP px wide without
+   * `edge`, is always the sidebar's, even over a list that scrolls or a zone
+   * inside that wants its Direction.
+   */
+  readonly edge?: number;
+  /** Whether Swipes open and close it: true by default. */
+  readonly enabled?: boolean;
+};
+
+export type Sidebar = {
+  /** Its translateX in px: `-width` or `width` closed, 0 open, never past either. */
+  readonly x: MotionValue<number>;
+  /** 0 closed to 1 open, for a scrim. */
+  readonly progress: MotionValue<number>;
+  readonly open: boolean;
+  readonly setOpen: (open: boolean) => void;
+  /** Whether fingers are moving it now. */
+  readonly dragging: boolean;
+};
+
+// Drawer-fast, no bounce; shutting is quicker than opening, as the eye has
+// already moved on. A Swipe's velocity still carries into either.
+const OPEN_SPRING = {
+  type: 'spring',
+  visualDuration: 0.13,
+  bounce: 0,
+} as const;
+const CLOSE_SPRING = {
+  type: 'spring',
+  visualDuration: 0.1,
+  bounce: 0,
+} as const;
+
+/** How wide the edge strip that is always the sidebar's is, in px, without `edge`. */
+const EDGE_STRIP = 24;
+
+/**
+ * A sidebar that follows a Swipe toward open, from anywhere or only from its
+ * `edge`, and a Swipe back from anywhere to close, then settles open or
+ * closed by where the fingers' momentum would carry it, past half its width.
+ */
+export function useSidebar(options: SidebarOptions): Sidebar {
+  const { side, width, edge, enabled = true } = options;
+  const [own, setOwn] = useState(options.defaultOpen ?? false);
+  const open = options.open ?? own;
+  // Which way opening moves x, and x when closed.
+  const sign = side === 'left' ? 1 : -1;
+  const closed = -sign * width;
+  const at = (amount: number) =>
+    closed + sign * Math.min(Math.max(amount, 0), width);
+
+  // Where the springs put it, which may overshoot; `x` stops dead at both ends.
+  const position = useMotionValue(at(open ? width : 0));
+  const x = useMotionValue(position.get());
+  useEffect(
+    () =>
+      position.on('change', (v) =>
+        x.set(Math.min(Math.max(v, Math.min(closed, 0)), Math.max(closed, 0))),
+      ),
+    [position, x, closed],
+  );
+  const progress = useTransform(x, [closed, 0], [0, 1]);
+  const moving = useRef<'open' | 'close' | undefined>(undefined);
+  // How open it was, in px, when fingers took it.
+  const base = useRef(0);
+  const animation = useRef<AnimationPlaybackControls | undefined>(undefined);
+  // Where it is headed, so settling after a Swipe is not redone as `open` catches up.
+  const target = useRef(open);
+
+  const settle = (next: boolean, velocity = 0) => {
+    moving.current = undefined;
+    target.current = next;
+    animation.current?.stop();
+    if (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) {
+      position.jump(at(next ? width : 0));
+      return;
+    }
+    animation.current = animate(position, at(next ? width : 0), {
+      ...(next ? OPEN_SPRING : CLOSE_SPRING),
+      velocity,
+    });
+  };
+
+  const change = (next: boolean) => {
+    if (next === open) return;
+    if (options.open === undefined) setOwn(next);
+    options.onOpenChange?.(next);
+  };
+
+  const setOpen = (next: boolean) => {
+    settle(next);
+    change(next);
+  };
+
+  useEffect(() => {
+    if (target.current !== open) settle(open);
+  });
+
+  // Fingers take it from wherever it is, even mid-spring.
+  const grab = (way: 'open' | 'close') => () => {
+    animation.current?.stop();
+    base.current = sign * (x.get() - closed);
+    moving.current = way;
+  };
+
+  // Opening Swipes measure toward open, closing ones toward closed.
+  const release = (way: 'open' | 'close') => (at?: SwipeRelease) => {
+    if (moving.current !== way) return;
+    if (at === undefined) return settle(open);
+    const headed =
+      way === 'open'
+        ? base.current + at.projected
+        : base.current - at.projected;
+    const opens = headed >= width / 2;
+    settle(opens, (way === 'open' ? sign : -sign) * at.velocity);
+    change(opens);
+  };
+
+  const opening = useSwipe({
+    enabled: enabled && !open,
+    direction: side === 'left' ? 'right' : 'left',
+    ...(edge === undefined ? {} : { from: { edge: side, within: edge } }),
+    onStart: grab('open'),
+    onCommit: release('open'),
+    onCancel: (_reason, at) => release('open')(at),
+  });
+  const closing = useSwipe({
+    enabled: enabled && open,
+    direction: side === 'left' ? 'left' : 'right',
+    onStart: grab('close'),
+    onCommit: release('close'),
+    onCancel: (_reason, at) => release('close')(at),
+  });
+
+  // Its side's edge is its own, open or closed: a swipe there while open does
+  // nothing, which beats the browser going back a page. And a one-finger
+  // touch landing in its strip is its zone's, even where a zone inside wants
+  // its Direction, so a swipe from the edge always moves it. A touch with
+  // more fingers is left to the zones, for gestures such as a resting thumb.
+  const fingers = useRef(0);
+  const strip = edge ?? EDGE_STRIP;
+  useGesture({
+    enabled,
+    guardsEdge: side,
+    onPointer: (_pointer, pointers) => {
+      fingers.current = [...pointers.values()].filter(
+        (finger) => finger.end === undefined,
+      ).length;
+    },
+    captures: (point) =>
+      fingers.current === 1 &&
+      (side === 'left' ? point.x <= strip : point.x >= innerWidth - strip),
+  });
+
+  useEffect(() => {
+    const offOpen = opening.offset.on('change', (offset) => {
+      if (moving.current === 'open') position.set(at(base.current + offset));
+    });
+    const offClose = closing.offset.on('change', (offset) => {
+      if (moving.current === 'close') position.set(at(base.current - offset));
+    });
+    return () => {
+      offOpen();
+      offClose();
+    };
+  });
+
+  useEffect(() => () => animation.current?.stop(), []);
+
+  return {
+    x,
+    progress,
+    open,
+    setOpen,
+    dragging: opening.state === 'tracking' || closing.state === 'tracking',
+  };
+}

package/src/input/gesture/recognizers/index.ts

@@ -0,0 +1,12 @@
+export { useSwipe } from './swipe/index.ts';
+export type {
+  CommitRule,
+  Direction,
+  Edge,
+  Fingers,
+  Swipe,
+  SwipeCancel,
+  SwipeOptions,
+  SwipeRelease,
+  SwipeState,
+} from './swipe/index.ts';

package/src/input/gesture/recognizers/swipe/index.ts

@@ -0,0 +1,12 @@
+export { useSwipe } from './use-swipe.ts';
+export type {
+  CommitRule,
+  Direction,
+  Edge,
+  Fingers,
+  Swipe,
+  SwipeCancel,
+  SwipeOptions,
+  SwipeRelease,
+  SwipeState,
+} from './use-swipe.ts';