@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/app/web-host.ts

@@ -0,0 +1,104 @@
+import {
+  type Backend,
+  backendNamed,
+  type Host,
+  keptBroadcasters,
+  type TableSource,
+  type TabMessage,
+} from './host/index.ts';
+import { cookie } from '@kestack/auth-toolkit/client/web';
+import { sharedBroadcaster } from '@kestack/std-toolkit/core';
+import { IDB, type IDBTable } from '@kestack/std-toolkit/db/idb';
+import { Sync } from '@kestack/std-toolkit/sync/idb';
+
+// `?backend=device` or `?backend=cloud` (or their former names, `local` and
+// `remote`) chooses the Backend, as Settings would, and leaves the address.
+const launchBackend = (): Backend | null => {
+  const url = new URL(window.location.href);
+  const asked = backendNamed(url.searchParams.get('backend'));
+  if (asked === null) return null;
+  url.searchParams.delete('backend');
+  window.history.replaceState(window.history.state, '', url.href);
+  return asked;
+};
+
+const onOnlineChange = (changed: () => void) => {
+  window.addEventListener('online', changed);
+  window.addEventListener('offline', changed);
+  return () => {
+    window.removeEventListener('online', changed);
+    window.removeEventListener('offline', changed);
+  };
+};
+
+const onForeground = (shown: () => void) => {
+  const changed = () => {
+    if (document.visibilityState === 'visible') shown();
+  };
+  document.addEventListener('visibilitychange', changed);
+  return () => document.removeEventListener('visibilitychange', changed);
+};
+
+/**
+ * The browser as an app's Host: each table in the IndexedDB database it
+ * names, heard by every tab, Std Sync in IndexedDB shared by every tab, the cloud APIs at this
+ * origin, sign-in through the sign-in service at `authUrl` and its cookies
+ * when the app has auth, and the window's network, visibility and other
+ * tabs under `name`. Made in the browser only.
+ */
+export const webHost = (options: {
+  readonly name: string;
+  readonly authUrl?: string | undefined;
+}): Host => {
+  // Each table opens once per tab, in the database it is kept in.
+  const tables = new Map<string, unknown>();
+  const table = <Name extends string>(
+    source: TableSource<Name>,
+    database: string,
+  ) => {
+    const key = `${database}/${source.logicalName}`;
+    const opened =
+      (tables.get(key) as IDBTable<Name> | undefined) ??
+      IDB.make(source, { database: IDB.database({ databaseName: database }) });
+    tables.set(key, opened);
+    return opened.layer;
+  };
+  const channel = new BroadcastChannel(`${options.name}:gate`);
+  const { authUrl } = options;
+  return {
+    storage: {
+      table,
+      // Every tab writes to the same IndexedDB database, so each hears the
+      // others' writes.
+      broadcaster: keptBroadcasters(sharedBroadcaster),
+      sync: {
+        ...Sync.idb(),
+        list: () => Sync.idb.list(),
+        remove: (name) => Sync.idb.remove(name),
+      },
+    },
+    cloud: {
+      url: window.location.origin,
+      ...(authUrl !== undefined && {
+        signIn: cookie({ authWorkerUrl: authUrl }),
+        manageAccounts: async () => {
+          window.open(authUrl, '_blank', 'noopener');
+        },
+      }),
+    },
+    lifecycle: {
+      online: () => navigator.onLine,
+      onOnlineChange,
+      onForeground,
+      launchBackend,
+    },
+    tabs: {
+      announce: (message) => channel.postMessage(message),
+      listen: (heard) => {
+        const listener = (event: MessageEvent<TabMessage>) => heard(event.data);
+        channel.addEventListener('message', listener);
+        return () => channel.removeEventListener('message', listener);
+      },
+    },
+  };
+};

package/src/client/index.ts

@@ -0,0 +1,9 @@
+// The opinionated way in on TanStack Start: the root document. The Theme
+// read on the server is ./client/server's.
+export {
+  type HeadTag,
+  type RootHead,
+  type RootPlugin,
+  webRoot,
+  type WebRootOptions,
+} from './root/index.ts';

package/src/client/root/index.ts

@@ -0,0 +1,7 @@
+export {
+  type HeadTag,
+  type RootHead,
+  type RootPlugin,
+  webRoot,
+  type WebRootOptions,
+} from './root.tsx';

package/src/client/root/root.tsx

@@ -0,0 +1,149 @@
+import {
+  HeadContent,
+  Link,
+  Outlet,
+  Scripts,
+  useLoaderData,
+} from '@tanstack/react-router';
+import { Fragment, type ComponentType, type ReactNode } from 'react';
+import { buttonVariants } from '#components/ui/button';
+import { DEVICE_SCRIPT } from '../../input/index.ts';
+import type { createTheme } from '../../theme/index.ts';
+
+type Theme = 'light' | 'dark';
+
+/** A tag in the document's head, as TanStack Router takes it. */
+export type HeadTag = Readonly<Record<string, string>>;
+
+/** The head tags something adds to every page. */
+export interface RootHead {
+  readonly meta?: ReadonlyArray<HeadTag>;
+  readonly links?: ReadonlyArray<HeadTag>;
+}
+
+/**
+ * Something the root document takes in without knowing it: its head tags,
+ * and a provider around every page. The PWA plugs in this way, so an app
+ * that leaves it out ships none of it.
+ */
+export interface RootPlugin {
+  readonly head?: () => RootHead;
+  readonly Provider?: ComponentType<{ readonly children: ReactNode }>;
+}
+
+export interface WebRootOptions {
+  /** The title of every page. */
+  readonly title: string;
+  /** The app's stylesheet, as `import css from './styles.css?url'` gives it. */
+  readonly stylesheet: string;
+  /** The app's Theme, from `createTheme`. */
+  readonly theme: ReturnType<typeof createTheme>;
+  /** Default: `/favicon.svg`. */
+  readonly icon?: string;
+  readonly plugins?: ReadonlyArray<RootPlugin>;
+  /**
+   * The Theme the server renders the page in, as a server function of the
+   * app's reading the cookie (`getTheme`). Without it the page renders
+   * dark, and the Theme's script sets the right one before the first paint.
+   */
+  readonly loadTheme?: () => Promise<Theme>;
+  /** What a page that does not exist shows; a plain 404 unless given. */
+  readonly notFound?: () => ReactNode;
+}
+
+const VIEWPORT =
+  'width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content';
+
+// The browser already shows the Theme its script set.
+const shownTheme = (): Theme =>
+  document.documentElement.dataset['theme'] === 'light' ? 'light' : 'dark';
+
+function NotFound() {
+  return (
+    <main className="mx-auto flex min-h-dvh max-w-md flex-col items-start justify-center gap-4 px-6">
+      <p className="text-sm text-muted-foreground">404</p>
+      <h1 className="text-2xl font-semibold tracking-tight">
+        Nothing lives here
+      </h1>
+      <Link to="/" className={buttonVariants({ className: 'min-h-11' })}>
+        Home
+      </Link>
+    </main>
+  );
+}
+
+/**
+ * The root route of a web app on TanStack Start: the document, in the
+ * Theme its cookie names before the first paint, the device marked before
+ * it too, the head every page shares, and the plugins' providers around
+ * every page. Pass it to `createRootRoute`.
+ */
+export const webRoot = (options: WebRootOptions) => {
+  const plugins = options.plugins ?? [];
+  const { theme } = options;
+
+  function RootDocument(props: { readonly children: ReactNode }) {
+    const initial =
+      (useLoaderData({ strict: false }) as Theme | undefined) ?? 'dark';
+    return (
+      <html
+        lang="en"
+        className={initial === 'dark' ? 'dark' : undefined}
+        data-theme={initial}
+        style={{ colorScheme: initial }}
+        suppressHydrationWarning
+      >
+        <head>
+          <HeadContent />
+          <theme.Script initialTheme={initial} />
+          {/* Before the first paint: what this device is driven by. */}
+          <script dangerouslySetInnerHTML={{ __html: DEVICE_SCRIPT }} />
+        </head>
+        <body>
+          {props.children}
+          <Scripts />
+        </body>
+      </html>
+    );
+  }
+
+  function Root() {
+    return plugins.reduceRight<ReactNode>(
+      (children, { Provider }) =>
+        Provider === undefined ? children : <Provider>{children}</Provider>,
+      <Fragment>
+        <Outlet />
+      </Fragment>,
+    );
+  }
+
+  return {
+    loader: async (): Promise<Theme> =>
+      typeof document !== 'undefined'
+        ? shownTheme()
+        : ((await options.loadTheme?.()) ?? 'dark'),
+    head: () => {
+      const added = plugins.map((plugin) => plugin.head?.() ?? {});
+      return {
+        meta: [
+          { charSet: 'utf-8' },
+          { name: 'viewport', content: VIEWPORT },
+          { title: options.title },
+          ...added.flatMap((head) => head.meta ?? []),
+        ],
+        links: [
+          { rel: 'stylesheet', href: options.stylesheet },
+          {
+            rel: 'icon',
+            type: 'image/svg+xml',
+            href: options.icon ?? '/favicon.svg',
+          },
+          ...added.flatMap((head) => head.links ?? []),
+        ],
+      };
+    },
+    shellComponent: RootDocument,
+    component: Root,
+    notFoundComponent: options.notFound ?? NotFound,
+  };
+};

package/src/client/server.ts

@@ -0,0 +1,3 @@
+// Server only: the Theme read from the request's cookie, for an app's own
+// server function (webRoot's `loadTheme`).
+export { getTheme } from './theme/index.ts';

package/src/client/theme/index.ts

@@ -0,0 +1 @@
+export { getTheme } from './tanstack-start.ts';

package/src/client/theme/tanstack-start.ts

@@ -0,0 +1,5 @@
+import { getCookie } from '@tanstack/react-start/server';
+import { THEME_COOKIE, themeFromCookies } from '../../theme/index.ts';
+
+export const getTheme = () =>
+  themeFromCookies(`${THEME_COOKIE}=${getCookie(THEME_COOKIE) ?? ''}`);

package/src/components/hooks/use-element-width.ts

@@ -0,0 +1,24 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Track an element's content width via {@link ResizeObserver}. Used to learn
+ * the pixel width of the bar column so a span bar that has been clamped to its
+ * pixel minimum can be visually distinguished (dimmed) from a true-width bar.
+ */
+export function useElementWidth<T extends HTMLElement>() {
+  const ref = useRef<T | null>(null);
+  const [width, setWidth] = useState(0);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    setWidth(el.getBoundingClientRect().width);
+    const observer = new ResizeObserver((entries) => {
+      setWidth(entries[0]?.contentRect.width ?? 0);
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  return [ref, width] as const;
+}

package/src/components/hooks/use-mobile.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+const MOBILE_BREAKPOINT = 768;
+/** The screens `useIsMobile` calls a phone's. */
+export const MOBILE_QUERY = `(max-width: ${MOBILE_BREAKPOINT - 1}px)`;
+
+const subscribe = (onChange: () => void) => {
+  const mql = window.matchMedia(MOBILE_QUERY);
+  mql.addEventListener('change', onChange);
+  return () => mql.removeEventListener('change', onChange);
+};
+
+// The server renders wide; hydration uses that too, then React re-renders
+// with the real width, so server and client markup always match.
+export function useIsMobile() {
+  return React.useSyncExternalStore(
+    subscribe,
+    () => window.matchMedia(MOBILE_QUERY).matches,
+    () => false,
+  );
+}

package/src/components/hooks/use-scroll.ts

@@ -0,0 +1,292 @@
+import { useRef, useState, useCallback, useEffect } from 'react';
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * How close to the bottom (px) the user must be for auto-scroll to
+ * re-engage.  Generous enough that momentum-deceleration, content
+ * streaming between frames, and sub-pixel rounding can't prevent it.
+ */
+const REENGAGE_THRESHOLD = 80;
+
+function getEl(el?: HTMLElement | null): HTMLElement {
+  return (
+    el ??
+    (document.scrollingElement as HTMLElement | null) ??
+    document.documentElement
+  );
+}
+
+function getRootEl(): HTMLElement {
+  return (
+    (document.scrollingElement as HTMLElement | null) ??
+    document.documentElement
+  );
+}
+
+function getScrollTop(el?: HTMLElement | null): number {
+  return el ? el.scrollTop : window.scrollY;
+}
+
+function maxScroll(el?: HTMLElement | null): number {
+  if (!el) {
+    const rootEl = getRootEl();
+    return rootEl.scrollHeight - rootEl.clientHeight;
+  }
+  return el.scrollHeight - el.clientHeight;
+}
+
+function nearBottom(el?: HTMLElement | null): boolean {
+  return maxScroll(el) - getScrollTop(el) <= REENGAGE_THRESHOLD;
+}
+
+/**
+ * Returns `true` on touch devices when an input-like element is focused.
+ * Used to skip auto-scroll during virtual-keyboard resize events that
+ * change the viewport but not the content.
+ */
+function hasVirtualKeyboardInput(): boolean {
+  if (!window.matchMedia('(pointer: coarse)').matches) return false;
+  const el = document.activeElement;
+  if (!el || el === document.body) return false;
+  const tag = el.tagName;
+  return (
+    tag === 'INPUT' ||
+    tag === 'TEXTAREA' ||
+    el.closest('[contenteditable]') != null
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// useScroll
+//
+// sticky=true  → pinned to bottom; content growth auto-tracked
+// sticky=false → user is in control
+//
+// Four mechanisms:
+//   1. Content tracking : ResizeObserver → snap when sticky,
+//                         re-engage + snap when user is near bottom
+//   2. Smooth scroll    : rAF + easeOutCubic (button click / API)
+//   3. Re-engage        : scroll-down near bottom, wheel-down near bottom
+//   4. Disengage        : wheel-up, touchmove
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useScroll(element?: HTMLElement | null) {
+  const isRoot = element == null;
+  const stickyRef = useRef(true);
+  const [isAutoScrolling, setIsAutoScrolling] = useState(true);
+  const rafIdRef = useRef<number | null>(null);
+
+  // ── Internal helpers ──────────────────────────────────────────────────
+
+  const cancelRaf = useCallback(() => {
+    if (rafIdRef.current !== null) {
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = null;
+    }
+  }, []);
+
+  const engage = useCallback(() => {
+    stickyRef.current = true;
+    setIsAutoScrolling(true);
+  }, []);
+
+  const disengage = useCallback(() => {
+    stickyRef.current = false;
+    setIsAutoScrolling(false);
+    cancelRaf();
+  }, [cancelRaf]);
+
+  // ── rAF smooth scroll ────────────────────────────────────────────────
+
+  const animateScrollTo = useCallback(
+    (target: number) => {
+      cancelRaf();
+      const el = getEl(element);
+      const start = isRoot ? getRootEl().scrollTop : el.scrollTop;
+      const distance = target - start;
+      if (Math.abs(distance) < 1) return;
+
+      const duration = Math.min(300, Math.max(150, Math.abs(distance) * 0.5));
+      const startTime = performance.now();
+
+      const step = (now: number) => {
+        const t = Math.min((now - startTime) / duration, 1);
+        const eased = 1 - Math.pow(1 - t, 3); // easeOutCubic
+        const next = start + distance * eased;
+        if (isRoot) {
+          getRootEl().scrollTop = next;
+        } else {
+          el.scrollTop = next;
+        }
+        if (t < 1) {
+          rafIdRef.current = requestAnimationFrame(step);
+        } else {
+          rafIdRef.current = null;
+        }
+      };
+
+      rafIdRef.current = requestAnimationFrame(step);
+    },
+    [element, cancelRaf],
+  );
+
+  // ── ResizeObserver ────────────────────────────────────────────────────
+  // When sticky → snap to bottom on any content growth.
+  // When NOT sticky but user is near bottom → re-engage and snap.
+  // This handles the streaming case where the user has parked near the
+  // bottom but no more scroll events fire (scrollTop didn't change).
+
+  useEffect(() => {
+    const el = getEl(element);
+    const scrollEl = isRoot ? undefined : el;
+    const observeTarget = isRoot ? document.body : el;
+
+    const snapToBottom = () => {
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = null;
+      }
+      if (isRoot) {
+        getRootEl().scrollTop = maxScroll();
+      } else {
+        el.scrollTop = maxScroll(el);
+      }
+    };
+
+    // Initial snap
+    if (stickyRef.current) snapToBottom();
+
+    const observer = new ResizeObserver(() => {
+      // On touch devices, skip all resize-driven snapping while an input
+      // is focused.  Virtual keyboard open/close AND input-field growth
+      // (typing more lines) both fire this observer and cause jarring
+      // jumps on mobile.
+      if (hasVirtualKeyboardInput()) return;
+
+      if (stickyRef.current) {
+        snapToBottom();
+      } else if (nearBottom(scrollEl)) {
+        engage();
+        snapToBottom();
+      }
+    });
+
+    observer.observe(observeTarget);
+    return () => observer.disconnect();
+  }, [element, engage]);
+
+  // ── Scroll / wheel / touch — engage & disengage ──────────────────────
+  //
+  // Re-engage (any one is sufficient):
+  //   • scroll event while scrolling DOWN and within REENGAGE_THRESHOLD
+  //   • wheel event with deltaY > 0  and within REENGAGE_THRESHOLD
+  //     (catches the edge where scrollTop === maxScroll → no scroll fires)
+  //
+  // Disengage:
+  //   • wheel event with deltaY < 0  (user scrolling up)
+  //   • touchmove event              (mobile drag)
+
+  useEffect(() => {
+    const scrollEl = isRoot ? undefined : getEl(element);
+    const target = isRoot ? window : getEl(element);
+    let lastScrollTop = getScrollTop(scrollEl);
+
+    // ── scroll: fires when scrollTop actually changes ──
+    const handleScroll = () => {
+      const current = getScrollTop(scrollEl);
+      const goingDown = current >= lastScrollTop;
+      lastScrollTop = current;
+
+      if (stickyRef.current) return;
+      if (goingDown && nearBottom(scrollEl)) {
+        engage();
+      }
+    };
+
+    // ── wheel: fires even at edges where scrollTop can't move ──
+    const handleWheel = (e: Event) => {
+      const { deltaY } = e as WheelEvent;
+
+      // Scrolling up → disengage (always, regardless of position).
+      if (deltaY < 0 && stickyRef.current && maxScroll(scrollEl) > 0) {
+        disengage();
+        return;
+      }
+
+      // Scrolling down while disengaged → re-engage if near bottom.
+      if (deltaY > 0 && !stickyRef.current && nearBottom(scrollEl)) {
+        engage();
+      }
+    };
+
+    // ── touch: any drag disengages (mobile) ──
+    const handleTouchMove = () => {
+      if (stickyRef.current) disengage();
+    };
+
+    target.addEventListener('scroll', handleScroll, { passive: true });
+    target.addEventListener('wheel', handleWheel, { passive: true });
+    target.addEventListener('touchmove', handleTouchMove, { passive: true });
+    return () => {
+      target.removeEventListener('scroll', handleScroll);
+      target.removeEventListener('wheel', handleWheel);
+      target.removeEventListener('touchmove', handleTouchMove);
+    };
+  }, [element, engage, disengage, isRoot]);
+
+  // ── Public API ────────────────────────────────────────────────────────
+
+  const scrollDownBy = useCallback(
+    (px: number) => {
+      const el = getEl(element);
+      animateScrollTo(getScrollTop(isRoot ? undefined : el) + px);
+    },
+    [element, animateScrollTo, isRoot],
+  );
+
+  const scrollUpBy = useCallback(
+    (px: number) => {
+      const el = getEl(element);
+      animateScrollTo(getScrollTop(isRoot ? undefined : el) - px);
+    },
+    [element, animateScrollTo, isRoot],
+  );
+
+  const scrollToTop = useCallback(() => {
+    animateScrollTo(0);
+  }, [animateScrollTo]);
+
+  const scrollToEnd = useCallback(() => {
+    animateScrollTo(maxScroll(isRoot ? undefined : getEl(element)));
+  }, [element, animateScrollTo, isRoot]);
+
+  /** Engage sticky mode and smooth-scroll to bottom. */
+  const alwaysScrollToBottom = useCallback(() => {
+    if (stickyRef.current) return;
+    engage();
+    animateScrollTo(maxScroll(isRoot ? undefined : getEl(element)));
+  }, [element, engage, animateScrollTo, isRoot]);
+
+  /** Disengage sticky mode. */
+  const stopAlwaysScrollToBottom = useCallback(() => {
+    disengage();
+  }, [disengage]);
+
+  // ── Cleanup ───────────────────────────────────────────────────────────
+  useEffect(() => {
+    return () => {
+      if (rafIdRef.current !== null) cancelAnimationFrame(rafIdRef.current);
+    };
+  }, []);
+
+  return {
+    scrollDownBy,
+    scrollUpBy,
+    scrollToTop,
+    scrollToEnd,
+    alwaysScrollToBottom,
+    stopAlwaysScrollToBottom,
+    isAutoScrolling,
+  };
+}

package/src/components/lib/lucide.ts

@@ -0,0 +1 @@
+export * from 'lucide-react';

package/src/components/lib/motion.ts

@@ -0,0 +1 @@
+export * from 'motion/react';

package/src/components/lib/scrollStyles.ts

@@ -0,0 +1,44 @@
+import { cn } from '#lib/utils';
+
+const baseStyles = cn(
+  'pointer-fine:[&::-webkit-scrollbar-track]:bg-transparent',
+  'pointer-fine:[&::-webkit-scrollbar-thumb]:bg-foreground/20',
+  'pointer-fine:[&::-webkit-scrollbar-thumb]:rounded-full',
+  'pointer-fine:[&::-webkit-scrollbar-thumb]:border-2',
+  'pointer-fine:[&::-webkit-scrollbar-thumb]:border-transparent',
+  'pointer-fine:[&::-webkit-scrollbar-thumb:hover]:bg-foreground/30',
+  'pointer-fine:[&::-webkit-scrollbar-corner]:bg-transparent',
+);
+/**
+ * Returns custom scrollbar styling classes for webkit browsers.
+ * Uses pointer-fine media query to only apply on devices with precise pointing (desktop).
+ *
+ * @returns String of Tailwind classes for custom scrollbars
+ */
+export const scrollbarStyles = cn(
+  baseStyles,
+  'pointer-fine:[&::-webkit-scrollbar]:h-2',
+  'pointer-fine:[&::-webkit-scrollbar]:w-2',
+);
+
+export const scrollBar = (
+  variant: 'default' | 'small' | 'none',
+  { direction = 'both' }: { direction: 'both' | 'vertical' | 'horizontal' } = {
+    direction: 'both',
+  },
+) =>
+  cn(baseStyles, {
+    [cn(
+      (direction === 'vertical' || direction === 'both') &&
+        'pointer-fine:[&::-webkit-scrollbar]:h-0.5',
+      (direction === 'horizontal' || direction === 'both') &&
+        'pointer-fine:[&::-webkit-scrollbar]:w-0.5',
+    )]: variant === 'small',
+    'pointer-fine:[&::-webkit-scrollbar]:hidden': variant === 'none',
+    [cn(
+      (direction === 'vertical' || direction === 'both') &&
+        'pointer-fine:[&::-webkit-scrollbar]:h-2',
+      (direction === 'horizontal' || direction === 'both') &&
+        'pointer-fine:[&::-webkit-scrollbar]:w-2',
+    )]: variant === 'default',
+  });