@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/input/gesture/zones/zone/motion-pointers.ts

@@ -0,0 +1,74 @@
+import { type MotionValue, motionValue } from 'motion/react';
+import type {
+  Pointer as CorePointer,
+  Pointers as CorePointers,
+} from '@kestack/use-gesture';
+import type { Target } from '../touch-input/index.ts';
+
+type Sample = CorePointer<Target>['start'];
+
+/**
+ * One finger of a Gesture, from landing until the Gesture ends. `target` is
+ * the element it landed on. `x` and `y` are where it is now, in viewport px;
+ * `dx` and `dy` how far it is from where it landed. They follow it while it
+ * is down and keep where it lifted after. `end` is set once it lifts.
+ */
+export type Pointer = {
+  readonly id: number;
+  readonly target: Target;
+  readonly start: Sample;
+  readonly x: MotionValue<number>;
+  readonly y: MotionValue<number>;
+  readonly dx: MotionValue<number>;
+  readonly dy: MotionValue<number>;
+  readonly end?: Sample;
+};
+
+/** Every finger of a Gesture, by id, in the order they landed. */
+export type Pointers = ReadonlyMap<number, Pointer>;
+
+/**
+ * The core's Pointers as motion values, for one Gesture Provider: each
+ * finger keeps its own motion values for its Gesture, set as the core's
+ * Pointer changes, so movement never re-renders React. The map changes only
+ * as a finger lands or lifts, as the core's does on those.
+ */
+export const createMotionPointers = () => {
+  let source: CorePointers<Target> | undefined;
+  let mirrored: Pointers = new Map();
+
+  return (next: CorePointers<Target>): Pointers => {
+    if (next === source) return mirrored;
+    source = next;
+    let changed = next.size !== mirrored.size;
+    const pointers = new Map<number, Pointer>();
+    for (const [id, pointer] of next) {
+      let own = mirrored.get(id);
+      // The same finger keeps its `start` for the whole Gesture.
+      if (own === undefined || own.start !== pointer.start) {
+        own = {
+          id,
+          target: pointer.target,
+          start: pointer.start,
+          x: motionValue(pointer.x),
+          y: motionValue(pointer.y),
+          dx: motionValue(pointer.dx),
+          dy: motionValue(pointer.dy),
+        };
+        changed = true;
+      } else {
+        own.x.set(pointer.x);
+        own.y.set(pointer.y);
+        own.dx.set(pointer.dx);
+        own.dy.set(pointer.dy);
+      }
+      if (pointer.end !== undefined && own.end === undefined) {
+        own = { ...own, end: pointer.end };
+        changed = true;
+      }
+      pointers.set(id, own);
+    }
+    if (changed) mirrored = pointers;
+    return mirrored;
+  };
+};

package/src/input/gesture/zones/zone/zone.tsx

@@ -0,0 +1,291 @@
+import { type MotionValue, useMotionValue } from 'motion/react';
+import {
+  type ComponentProps,
+  type CSSProperties,
+  createContext,
+  type ReactNode,
+  type Ref,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+import {
+  createGestureProvider,
+  type Direction,
+  type Directions,
+  type GestureEnd,
+  type GestureProvider as CoreProvider,
+} from '@kestack/use-gesture';
+import {
+  createTouchInput,
+  DOM_ZONES,
+  type Target,
+} from '../touch-input/index.ts';
+import {
+  createMotionPointers,
+  type Pointer,
+  type Pointers,
+} from './motion-pointers.ts';
+
+export type { Direction, Directions, GestureEnd } from '@kestack/use-gesture';
+export type { Pointer, Pointers } from './motion-pointers.ts';
+
+type Tracker = CoreProvider<Element, Target>;
+
+type Provided = {
+  readonly tracker: Tracker;
+  /** The core's Pointers as this provider's motion values. */
+  readonly motion: ReturnType<typeof createMotionPointers>;
+  readonly bindZone: (element: Element) => () => void;
+};
+
+const ProviderContext = createContext<Provided | undefined>(undefined);
+
+type Zone = {
+  readonly tracker: Tracker;
+  readonly motion: Provided['motion'];
+  readonly element: Element | null;
+};
+
+const ZoneContext = createContext<Zone | undefined>(undefined);
+
+const assignRef = <T,>(ref: Ref<T> | undefined, value: T | null) => {
+  if (typeof ref === 'function') ref(value);
+  else if (ref !== null && ref !== undefined) ref.current = value;
+};
+
+/**
+ * Tracks every Gesture in the Gesture Zones inside it: the one place its
+ * fingers are followed. Put one at the app's root; separate sections may
+ * each have their own, and each then runs its own Gesture. One inside
+ * another does nothing: its zones join the outer one, so nested screens
+ * share one Gesture.
+ */
+export function GestureProvider(props: { readonly children?: ReactNode }) {
+  const outer = useContext(ProviderContext);
+  return outer === undefined ? (
+    <Provider>{props.children}</Provider>
+  ) : (
+    props.children
+  );
+}
+
+function Provider(props: { readonly children?: ReactNode }) {
+  const [provided] = useState(() => {
+    const tracker = createGestureProvider(DOM_ZONES);
+    const input =
+      typeof window === 'undefined'
+        ? undefined
+        : createTouchInput(window, tracker.sink);
+    return {
+      tracker,
+      motion: createMotionPointers(),
+      input,
+      bindZone: (element: Element) => input?.bindZone(element) ?? (() => {}),
+    };
+  });
+
+  useEffect(() => {
+    provided.input?.start();
+    return () => provided.input?.stop();
+  }, [provided]);
+
+  return <ProviderContext value={provided}>{props.children}</ProviderContext>;
+}
+
+export type GestureZoneProps = ComponentProps<'div'> & {
+  /**
+   * Whether Gestures that start in it stay in it, rather than also reaching
+   * the zones around it. It never keeps a touch from the browser. False by
+   * default. Read as a Gesture starts.
+   */
+  readonly trapped?: boolean;
+};
+
+// Touch defaults for the zone's own element, as inline style so they need no
+// stylesheet; `style` on the zone overrides any of them.
+const ZONE_STYLE: CSSProperties = {
+  userSelect: 'none',
+  WebkitUserSelect: 'none',
+  WebkitTouchCallout: 'none',
+};
+
+/**
+ * An area where the app can own touch, read with `useGesture` by any
+ * component inside it, shown or hidden. A Gesture starting in it is heard
+ * here and by each zone around it up to the first trapped one; sibling
+ * zones never hear each other. At the first movement one of them takes it,
+ * if a listener wants it; otherwise the browser scrolls. Zones nest, and
+ * must be inside a GestureProvider.
+ */
+export function GestureZone({
+  ref,
+  style,
+  children,
+  trapped = false,
+  ...props
+}: GestureZoneProps) {
+  const provided = useContext(ProviderContext);
+  if (provided === undefined) {
+    throw new Error('GestureZone must be used inside a GestureProvider');
+  }
+  const { tracker, motion, bindZone } = provided;
+  const [element, setElement] = useState<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (element === null) return;
+    const removeZone = tracker.addZone(element);
+    const unbind = bindZone(element);
+    return () => {
+      unbind();
+      removeZone();
+    };
+  }, [tracker, bindZone, element]);
+
+  const attach = useCallback(
+    (next: HTMLDivElement | null) => {
+      setElement(next);
+      assignRef(ref, next);
+    },
+    [ref],
+  );
+
+  return (
+    <ZoneContext value={{ tracker, motion, element }}>
+      <div
+        ref={attach}
+        data-slot="gesture-zone"
+        data-trapped={trapped ? '' : undefined}
+        style={{ ...ZONE_STYLE, ...style }}
+        {...props}
+      >
+        {children}
+      </div>
+    </ZoneContext>
+  );
+}
+
+// The nearest Gesture Zone; hooks throw a clear error outside one.
+const useZone = (user: string): Zone => {
+  const zone = useContext(ZoneContext);
+  if (zone === undefined) {
+    throw new Error(`${user} must be used inside a GestureZone`);
+  }
+  return zone;
+};
+
+// The latest options, read by the zone mid-Gesture without re-registering.
+const useLatest = <T,>(value: T) => {
+  const ref = useRef(value);
+  useLayoutEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+};
+
+const NONE: Pointers = new Map();
+
+export type GestureOptions = {
+  /** Whether it takes the next Gesture: true by default. Read as its first finger lands. */
+  readonly enabled?: boolean;
+  /** The first finger landed. */
+  readonly onStart?: (pointers: Pointers) => void;
+  /** A finger landed or lifted; `pointer` is that finger. */
+  readonly onPointer?: (pointer: Pointer, pointers: Pointers) => void;
+  /**
+   * The last finger lifted: every finger of the Gesture, lifted ones
+   * included. Also when the browser or another zone took it, `interrupted`.
+   */
+  readonly onEnd?: (pointers: Pointers, end: GestureEnd) => void;
+  /**
+   * The Directions it takes touches in: `['left', 'right']`, or `'all'`. An
+   * element under the finger that can still scroll that way keeps it
+   * instead. Read at the touch's first movement. Without `directions` or
+   * `captures` it only watches, and never keeps a touch from the browser,
+   * apart from the edge it `guardsEdge`.
+   */
+  readonly directions?: Directions;
+  /** The Gesture first moved in `direction`: read once, for every listener. */
+  readonly onDirection?: (direction: Direction) => void;
+  /**
+   * Whether it captures a touch whose first finger landed at `point`, in
+   * viewport px, whichever way it moves, even over an element that could
+   * scroll it. Read at the touch's first movement; taps are never affected.
+   */
+  readonly captures?: (point: {
+    readonly x: number;
+    readonly y: number;
+  }) => boolean;
+  /**
+   * A side edge it keeps from the browser's edge swipe (back and forward on
+   * iOS) while it is enabled, even when it would not take a touch there. It
+   * neither captures nor wants anything, so it never changes who takes a
+   * Gesture. Read as a touch lands.
+   */
+  readonly guardsEdge?: 'left' | 'right';
+};
+
+export type GestureState = {
+  /**
+   * Every finger of the Gesture under way, by id, lifted ones included;
+   * empty between Gestures. It changes as a finger lands or lifts; each
+   * finger's own motion values follow it as it moves.
+   */
+  readonly pointers: MotionValue<Pointers>;
+  /** True from the first finger landing until the last one lifts. */
+  readonly active: boolean;
+};
+
+/**
+ * Reads every Gesture its nearest Gesture Zone hears: each that starts in
+ * it, or in a zone inside it that is not trapped, until another zone takes
+ * it, unless it only watches. It reports each finger
+ * that lands between the first landing and the last lifting, with where,
+ * when and on what it landed and motion values that follow it. It never
+ * classifies anything; what a Gesture means is up to the caller.
+ */
+export function useGesture(options: GestureOptions = {}): GestureState {
+  const { tracker, motion, element } = useZone('useGesture');
+  const latest = useLatest(options);
+  const pointers = useMotionValue(NONE);
+  const [active, setActive] = useState(false);
+
+  useEffect(() => {
+    if (element === null) return;
+    return tracker.addGesture(element, {
+      enabled: () => latest.current.enabled !== false,
+      start: (core) => {
+        const next = motion(core);
+        pointers.set(next);
+        setActive(true);
+        latest.current.onStart?.(next);
+      },
+      pointer: (pointer, core) => {
+        const next = motion(core);
+        const own = next.get(pointer.id);
+        pointers.set(next);
+        if (own !== undefined) latest.current.onPointer?.(own, next);
+      },
+      move: (_pointer, core) => {
+        motion(core);
+      },
+      captures: (point) => latest.current.captures?.(point) === true,
+      directions: () => latest.current.directions,
+      guardsEdge: () => latest.current.guardsEdge,
+      acts: () =>
+        latest.current.captures !== undefined ||
+        latest.current.directions !== undefined,
+      direction: (direction) => latest.current.onDirection?.(direction),
+      end: (last, end) => {
+        latest.current.onEnd?.(motion(last), end);
+        pointers.set(NONE);
+        setActive(false);
+      },
+    });
+  }, [tracker, motion, element, latest, pointers]);
+
+  return { pointers, active };
+}

package/src/input/index.ts

@@ -0,0 +1,4 @@
+// How a person drives the app: what the device can be driven by, and touch
+// gestures, with every finger as Motion values in nested Gesture Zones.
+export { DEVICE_SCRIPT, type Device, useDevice } from './device/index.ts';
+export * from './gesture/index.ts';

package/src/pwa/browser/dom-events.ts

@@ -0,0 +1,17 @@
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+
+/** Adds `listener` for the life of the current scope. */
+export const listen = (
+  target: EventTarget,
+  type: string,
+  listener: (event: Event) => void,
+): Effect.Effect<void, never, Scope.Scope> =>
+  Effect.acquireRelease(
+    Effect.sync(() => target.addEventListener(type, listener)),
+    () => Effect.sync(() => target.removeEventListener(type, listener)),
+  );
+
+/** False during SSR and in workers. */
+export const isBrowser = (): boolean =>
+  typeof window !== 'undefined' && typeof document !== 'undefined';

package/src/pwa/browser/subscription-ref.ts

@@ -0,0 +1,29 @@
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Stream from 'effect/Stream';
+import * as SubscriptionRef from 'effect/SubscriptionRef';
+import { useCallback, useSyncExternalStore } from 'react';
+
+/** The ref's current value, re-rendering on change; `fallback` during SSR, hydration and before the ref exists. */
+export const useSubscriptionRef = <A>(
+  ref: SubscriptionRef.SubscriptionRef<A> | undefined,
+  fallback: A,
+): A => {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (ref === undefined) return () => {};
+      const fiber = Effect.runFork(
+        Stream.runForEach(SubscriptionRef.changes(ref), () =>
+          Effect.sync(onChange),
+        ),
+      );
+      return () => void Effect.runFork(Fiber.interrupt(fiber));
+    },
+    [ref],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => (ref === undefined ? fallback : SubscriptionRef.getUnsafe(ref)),
+    () => fallback,
+  );
+};

package/src/pwa/client/client.ts

@@ -0,0 +1,43 @@
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type { ClientBuildInfo } from '../shared/config/index.js';
+import { register } from './registration.js';
+import { clearRuntimeCaches } from './runtime-cache.js';
+import { makeStatus, type StatusService } from './status/index.js';
+
+export { PwaStatus } from './status/index.js';
+
+/**
+ * The PWA as the page sees it: one `status` stream, and the two things the
+ * page can do about updates. Never reloads unasked; `applyUpdate` activates
+ * the waiting build and every open page reloads into it.
+ */
+export class Pwa extends Context.Service<
+  Pwa,
+  StatusService & {
+    /** Deletes every Runtime Cache (use on sign-out); the Precache stays. */
+    readonly clearRuntimeCache: Effect.Effect<void>;
+  }
+>()('@kestack/web-platform/pwa/Pwa') {
+  /**
+   * Registers the worker and watches it. Browser only: build it after
+   * hydration, never during SSR (there it is `Unsupported`).
+   */
+  static layer(info: ClientBuildInfo): Layer.Layer<Pwa> {
+    return Layer.effect(
+      this,
+      Effect.gen(function* () {
+        const registration = yield* register(info);
+        const status = yield* makeStatus(info.update, registration);
+        return { ...status, clearRuntimeCache: clearRuntimeCaches };
+      }),
+    );
+  }
+}
+
+/**
+ * Deletes every Runtime Cache straight from CacheStorage, which the page
+ * shares with the worker, so it needs no registration or `Pwa` service.
+ */
+export const clearRuntimeCache: Effect.Effect<void> = clearRuntimeCaches;

package/src/pwa/client/commands/commands.ts

@@ -0,0 +1,28 @@
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import {
+  type CommandReply,
+  type CommandType,
+  makeCommand,
+  matchCommandReply,
+} from '../../shared/commands/index.js';
+
+/** A worker that does not know `type` never replies, so every request times out. */
+const REPLY_TIMEOUT = '3 seconds';
+
+/** Sends one command to `worker`; none on timeout or an unreadable reply. */
+export const sendCommand = (
+  worker: ServiceWorker,
+  type: CommandType,
+): Effect.Effect<Option.Option<CommandReply>> =>
+  Effect.callback<Option.Option<CommandReply>>((resume) => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = (event: MessageEvent) =>
+      resume(Effect.succeed(matchCommandReply(event.data)));
+    try {
+      worker.postMessage(makeCommand(type), [channel.port2]);
+    } catch {
+      resume(Effect.succeed(Option.none()));
+    }
+    return Effect.sync(() => channel.port1.close());
+  }).pipe(Effect.timeoutOption(REPLY_TIMEOUT), Effect.map(Option.flatten));

package/src/pwa/client/commands/index.ts

@@ -0,0 +1 @@
+export { sendCommand } from './commands.js';

package/src/pwa/client/index.ts

@@ -0,0 +1 @@
+export { clearRuntimeCache, Pwa, PwaStatus } from './client.js';

package/src/pwa/client/registration.ts

@@ -0,0 +1,63 @@
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { isToolkitCacheName } from '../shared/build/index.js';
+import type { ClientBuildInfo } from '../shared/config/index.js';
+import { isBrowser } from '../browser/dom-events.js';
+
+const hasServiceWorkerApi = (): boolean =>
+  isBrowser() && 'serviceWorker' in navigator;
+
+/**
+ * Registers `swUrl`. `updateViaCache: 'none'` makes every update check hit
+ * the network. None when unsupported or refused, and when disabled (Kill
+ * Switch, dev without `dev: true`): then any registration of `swUrl` left
+ * from an earlier build or dev session is removed, with the toolkit's caches.
+ */
+export const register = (
+  config: ClientBuildInfo,
+): Effect.Effect<Option.Option<ServiceWorkerRegistration>> => {
+  if (!hasServiceWorkerApi()) return Effect.succeed(Option.none());
+  if (!config.enabled) return Effect.as(unregister(config), Option.none());
+  return Effect.tryPromise(() =>
+    navigator.serviceWorker.register(config.swUrl, {
+      scope: config.scope,
+      updateViaCache: 'none',
+    }),
+  ).pipe(
+    Effect.map(Option.some),
+    Effect.tapError((error) =>
+      Effect.logWarning(
+        'pwa-toolkit: service worker registration failed',
+        error,
+      ),
+    ),
+    Effect.orElseSucceed(Option.none),
+  );
+};
+
+const scriptPath = (registration: ServiceWorkerRegistration) => {
+  const worker =
+    registration.active ?? registration.waiting ?? registration.installing;
+  return worker === null ? null : new URL(worker.scriptURL).pathname;
+};
+
+const unregister = (config: ClientBuildInfo): Effect.Effect<void> =>
+  Effect.tryPromise(async () => {
+    const stale = (await navigator.serviceWorker.getRegistrations()).filter(
+      (registration) => scriptPath(registration) === config.swUrl,
+    );
+    if (stale.length === 0) return;
+    await Promise.all(stale.map((registration) => registration.unregister()));
+    if (typeof caches === 'undefined') return;
+    const names = await caches.keys();
+    await Promise.all(
+      names.filter(isToolkitCacheName).map((name) => caches.delete(name)),
+    );
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.logWarning(
+        'pwa-toolkit: removing the old service worker failed',
+        error,
+      ),
+    ),
+  );

package/src/pwa/client/runtime-cache.ts

@@ -0,0 +1,24 @@
+import * as Effect from 'effect/Effect';
+import { isRuntimeCacheName } from '../shared/build/index.js';
+
+/**
+ * Deletes every Runtime Cache straight from CacheStorage, which the page
+ * shares with the worker, so it works with no registration at all.
+ */
+export const clearRuntimeCaches: Effect.Effect<void> = Effect.suspend(() =>
+  typeof caches === 'undefined'
+    ? Effect.void
+    : Effect.tryPromise(async () => {
+        const names = await caches.keys();
+        await Promise.all(
+          names.filter(isRuntimeCacheName).map((name) => caches.delete(name)),
+        );
+      }).pipe(
+        Effect.catch((error) =>
+          Effect.logWarning(
+            'pwa-toolkit: clearing Runtime Caches failed',
+            error,
+          ),
+        ),
+      ),
+);

package/src/pwa/client/status/index.ts

@@ -0,0 +1 @@
+export { makeStatus, PwaStatus, type StatusService } from './status.js';