@kestack/web-platform 0.0.0-stage → 0.0.0

package/src/server/stage/stage.ts

@@ -0,0 +1,43 @@
+/**
+ * A deploy's stage, as alchemy names it: `prod`, a pull request's `prN`, or
+ * anyone's own stage on their machine. Only `prod` and `prN` reach the
+ * world.
+ */
+const isProdStage = (stage: string): boolean => stage === 'prod';
+const isPrStage = (stage: string): boolean => /^pr\d+$/.test(stage);
+
+export const isDeployedStage = (stage: string): boolean =>
+  isProdStage(stage) || isPrStage(stage);
+
+/** Refuses a deployed stage unless the deploy says so on purpose, as CI and
+ * a deploy script do with ALLOW_DEPLOY=true. */
+export const assertStageIsSafe = (stage: string): void => {
+  if (isDeployedStage(stage) && process.env['ALLOW_DEPLOY'] !== 'true') {
+    throw new Error(
+      `Refusing to target deployed stage "${stage}" without ALLOW_DEPLOY=true.`,
+    );
+  }
+};
+
+/** Where a stage is served: `domain` for prod, `prN-domain` for a pull
+ * request, and nowhere public for anyone's own stage. */
+export const domainFor = (stage: string, domain: string): string | undefined =>
+  isProdStage(stage)
+    ? domain
+    : isDeployedStage(stage)
+      ? `${stage}-${domain}`
+      : undefined;
+
+/** A local stage's dev server, on the PORT `portless run` hands it. */
+export const devConfigFor = (
+  isLocal: boolean,
+): { port: number } | undefined => {
+  if (!isLocal) return undefined;
+  const port = Number(process.env['PORT']);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(
+      'PORT must be assigned by portless. Start the app with `pnpm dev`.',
+    );
+  }
+  return { port };
+};

package/src/server/worker/index.ts

@@ -0,0 +1 @@
+export { type Handle, webServer } from './worker.ts';

package/src/server/worker/worker.ts

@@ -0,0 +1,26 @@
+import handler from '@tanstack/react-start/server-entry';
+
+/** Answers a request with the platform's own context, such as a Worker's
+ * `env`. */
+export type Handle<Env> = (request: Request, env: Env) => Promise<Response>;
+
+/**
+ * A web app's server: what `route` answers, and everything else the app's
+ * pages, from TanStack Start. `rpc` answers `/rpc` alone. A plain fetch
+ * handler, so it is a Cloudflare Worker's default export as it is, and runs
+ * anywhere else that calls `fetch(request, env)`.
+ */
+export const webServer = <Env>(options: {
+  readonly rpc?: Handle<Env>;
+  /** Answers a request it knows, or null to leave it to the pages. */
+  readonly route?: (request: Request, env: Env) => Promise<Response> | null;
+}) => ({
+  fetch: (request: Request, env: Env): Promise<Response> => {
+    const routed = options.route?.(request, env) ?? null;
+    if (routed !== null) return routed;
+    const path = new URL(request.url).pathname;
+    return options.rpc !== undefined && (path === '/rpc' || path === '/rpc/')
+      ? options.rpc(request, env)
+      : Promise.resolve(handler.fetch(request));
+  },
+});

package/src/theme/cookie.ts

@@ -0,0 +1,22 @@
+import { DEFAULT_THEME, isTheme, THEME_COOKIE, type Theme } from './model.ts';
+
+export const themeFromCookies = (cookies: string | null | undefined): Theme => {
+  for (const part of (cookies ?? '').split(';')) {
+    const [name, ...rest] = part.trim().split('=');
+    if (name !== THEME_COOKIE) continue;
+    const value = decodeURIComponent(rest.join('='));
+    return isTheme(value) ? value : DEFAULT_THEME;
+  }
+  return DEFAULT_THEME;
+};
+
+export const writeThemeCookie = (theme: Theme, cookieDomain?: string): void => {
+  const domain = cookieDomain?.replace(/^\./, '').trim();
+  const shared =
+    domain &&
+    (location.hostname === domain || location.hostname.endsWith(`.${domain}`))
+      ? `; Domain=${domain}`
+      : '';
+  const secure = location.protocol === 'https:' ? '; Secure' : '';
+  document.cookie = `${THEME_COOKIE}=${theme}; Path=/; Max-Age=31536000; SameSite=Lax${shared}${secure}`;
+};

package/src/theme/css/font-inter.css

@@ -0,0 +1,2 @@
+@import '@fontsource-variable/inter';
+@import '@fontsource-variable/jetbrains-mono';

package/src/theme/css/global.css

@@ -0,0 +1,62 @@
+/* This file is meant to be imported as is in frontend projects!. */
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+
+@custom-variant dark (&:where(.dark, .dark *, [data-theme='dark'], [data-theme='dark'] *));
+
+/*
+ * What the device can be driven by, from `<html>` (marked before the first
+ * paint by the root document; see input's DEVICE_SCRIPT).
+ */
+@custom-variant keyboard (&:where([data-keyboard] *));
+@custom-variant touch (&:where([data-touch] *));
+
+/* The one focus ring: drawn inside, so no scrolling parent clips it. */
+@utility focus-ring {
+  outline: none;
+  &:focus-visible {
+    box-shadow: inset 0 0 0 2px var(--color-ring);
+  }
+}
+
+@import './sources.css';
+@import './typography.css';
+@import './theme.css';
+@import './shiki.css';
+
+@layer base {
+  html {
+    scrollbar-gutter: auto;
+    scrollbar-color: color-mix(
+        in oklab,
+        var(--muted-foreground) 45%,
+        transparent
+      )
+      transparent;
+    scrollbar-width: thin;
+  }
+  html::-webkit-scrollbar {
+    width: 10px;
+  }
+  html::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  html::-webkit-scrollbar-thumb {
+    border: 3px solid transparent;
+    border-radius: 999px;
+    background-color: color-mix(
+      in oklab,
+      var(--muted-foreground) 45%,
+      transparent
+    );
+    background-clip: content-box;
+  }
+  html::-webkit-scrollbar-thumb:hover {
+    background-color: color-mix(
+      in oklab,
+      var(--muted-foreground) 70%,
+      transparent
+    );
+  }
+}

package/src/theme/css/shiki.css

@@ -0,0 +1,71 @@
+/**
+ * Dual-theme Shiki support. CodeBlock tokenizes once with both light and dark
+ * themes: each token span carries its light colour inline plus a `--shiki-dark`
+ * custom property. Under the app's dark theme we swap the span colour to that
+ * dark value. Scoped to `.shiki-token` so the surrounding gutter and layout
+ * spans (which carry no `--shiki-dark`) keep their own colours.
+ */
+.dark .shiki .shiki-token,
+[data-theme='dark'] .shiki .shiki-token {
+  color: var(--shiki-dark) !important;
+}
+
+/**
+ * Diff line decoration for SourceViewer. Written as plain CSS rather than
+ * Tailwind arbitrary variants because these classes are added by a Shiki
+ * transformer into markup Tailwind never scans.
+ */
+.source-line-add {
+  background-color: rgb(34 197 94 / 0.14);
+  border-inline-start-color: rgb(34 197 94) !important;
+}
+
+.source-line-remove {
+  background-color: rgb(244 63 94 / 0.14);
+  border-inline-start-color: rgb(244 63 94) !important;
+}
+
+.source-line-empty {
+  background-color: color-mix(
+    in oklab,
+    var(--muted-foreground) 7%,
+    transparent
+  );
+}
+
+.source-line-meta {
+  background-color: var(--muted);
+  color: var(--muted-foreground);
+}
+
+.source-line-add::after,
+.source-line-remove::after {
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: 2.85rem;
+  width: 0.65rem;
+  text-align: center;
+  font-size: 11px;
+  font-weight: 700;
+  line-height: inherit;
+}
+
+.source-line-add::after {
+  content: '+';
+  color: rgb(22 163 74);
+}
+
+.source-line-remove::after {
+  content: '\2212';
+  color: rgb(225 29 72);
+}
+
+.dark .source-line-add::after,
+[data-theme='dark'] .source-line-add::after {
+  color: rgb(74 222 128);
+}
+
+.dark .source-line-remove::after,
+[data-theme='dark'] .source-line-remove::after {
+  color: rgb(251 113 133);
+}

package/src/theme/css/sources.css

@@ -0,0 +1,6 @@
+/* Paths resolve inside the installed package, including in node_modules. */
+@source "../../components";
+@source "../../form";
+@source "../../recipes";
+@source "../../client";
+@source "../../pwa";

package/src/theme/css/theme.css

@@ -0,0 +1,170 @@
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-dialog: var(--dialog);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-edge: var(--edge);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-chart-6: var(--chart-6);
+  --color-chart-7: var(--chart-7);
+  --color-chart-8: var(--chart-8);
+  --color-chart-9: var(--chart-9);
+  --color-positive: var(--positive);
+  --color-positive-foreground: var(--positive-foreground);
+  --font-sans: 'Inter Variable', ui-sans-serif, system-ui, sans-serif;
+  --font-mono:
+    'JetBrains Mono Variable', ui-monospace, 'SF Mono', 'Menlo', monospace;
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-active: var(--sidebar-active);
+  --color-sidebar-active-foreground: var(--sidebar-active-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+[data-theme='light'],
+:root {
+  color-scheme: light;
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --dialog: var(--popover);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  /* The hairline around raised surfaces; in light, the foreground at 10%. */
+  --edge: color-mix(in oklab, var(--foreground) 10%, transparent);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --chart-6: oklch(0.586 0.2 277.117);
+  --chart-7: oklch(0.723 0.15 50.08);
+  --chart-8: oklch(0.52 0.13 200.723);
+  --chart-9: oklch(0.645 0.2 330.44);
+  --positive: oklch(0.55 0.18 145);
+  --positive-foreground: oklch(0.985 0 0);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-active: oklch(0.94 0.03 264);
+  --sidebar-active-foreground: oklch(0.4 0.16 264);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+[data-theme='dark'],
+.dark {
+  color-scheme: dark;
+  /* Dark surfaces rise by getting lighter, as light ones do by casting a
+     shadow: page, then card and sidebar, then popovers, menus and sheets. */
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.195 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.235 0 0);
+  /* A dialog sits on a dimmed page: darker than a menu, so its text stands
+     out more. */
+  --dialog: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 15%);
+  /* Shadows barely show on a dark page, so edges carry the shape. */
+  --edge: oklch(1 0 0 / 16%);
+  --input: oklch(1 0 0 / 20%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --chart-6: oklch(0.637 0.2 277.117);
+  --chart-7: oklch(0.773 0.15 50.08);
+  --chart-8: oklch(0.57 0.13 200.723);
+  --chart-9: oklch(0.695 0.2 330.44);
+  --positive: oklch(0.65 0.17 145);
+  --positive-foreground: oklch(0.985 0 0);
+  --sidebar: oklch(0.195 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-active: oklch(0.25 0.045 264);
+  --sidebar-active-foreground: oklch(0.78 0.12 264);
+  --sidebar-border: oklch(1 0 0 / 15%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply font-sans bg-background text-foreground overflow-y-scroll;
+  }
+  /* An App Shell with a sidebar fills the screen and scrolls inside, so the page
+     keeps no empty scrollbar track at its edge. */
+  body:has([data-slot='app-shell']) {
+    @apply overflow-hidden;
+  }
+  html {
+    @apply font-sans;
+  }
+}

package/src/theme/css/typography.css

@@ -0,0 +1 @@
+@plugin "@tailwindcss/typography";

package/src/theme/document.ts

@@ -0,0 +1,37 @@
+import { THEME_COLORS, type Theme } from './model.ts';
+
+const freezeTransitions = (): (() => void) => {
+  const style = document.createElement('style');
+  style.textContent = '*,*::before,*::after{transition:none!important}';
+  document.head.appendChild(style);
+  return () =>
+    requestAnimationFrame(() => requestAnimationFrame(() => style.remove()));
+};
+
+export const applyThemeToDocument = (theme: Theme, freeze = false): void => {
+  const unfreeze = freeze ? freezeTransitions() : undefined;
+  const root = document.documentElement;
+  root.classList.toggle('dark', theme === 'dark');
+  root.dataset.theme = theme;
+  root.style.colorScheme = theme;
+  root.style.backgroundColor = THEME_COLORS[theme];
+  if (document.body !== null) {
+    document.body.style.backgroundColor = THEME_COLORS[theme];
+  }
+
+  const metas = [
+    ...document.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]'),
+  ];
+  if (metas.length === 0) {
+    metas.push(
+      document.head.appendChild(
+        Object.assign(document.createElement('meta'), { name: 'theme-color' }),
+      ),
+    );
+  }
+  for (const meta of metas) meta.content = THEME_COLORS[theme];
+  unfreeze?.();
+};
+
+export const bootstrapSource = (initialTheme: Theme): string =>
+  `(function(){try{var n='kui-theme',m=document.cookie.match(new RegExp('(?:^|; )'+n+'=([^;]*)')),t=m?decodeURIComponent(m[1]):'${initialTheme}';if(t!=='light'&&t!=='dark')t='dark';var c=t==='dark'?'${THEME_COLORS.dark}':'${THEME_COLORS.light}',r=document.documentElement;r.classList.toggle('dark',t==='dark');r.setAttribute('data-theme',t);r.style.colorScheme=t;r.style.backgroundColor=c;document.querySelectorAll('meta[name="theme-color"]').forEach(function(e){e.setAttribute('content',c)})}catch(e){}})()`;

package/src/theme/index.ts

@@ -0,0 +1,3 @@
+export { createTheme } from './theme.ts';
+export { themeFromCookies } from './cookie.ts';
+export { THEME_COOKIE } from './model.ts';

package/src/theme/model.ts

@@ -0,0 +1,12 @@
+export type Theme = 'light' | 'dark';
+
+export const THEME_COOKIE = 'kui-theme';
+export const DEFAULT_THEME: Theme = 'dark';
+export const THEME_CHANGED = 'kui-theme-change';
+export const THEME_COLORS: Record<Theme, string> = {
+  light: '#ffffff',
+  dark: '#0a0a0a',
+};
+
+export const isTheme = (value: unknown): value is Theme =>
+  value === 'light' || value === 'dark';

package/src/theme/status-bar.ts

@@ -0,0 +1,28 @@
+import { createElement, Fragment } from 'react';
+import { THEME_COLORS } from './model.ts';
+
+// An installed iOS web app ignores a theme-color change made in place: it
+// tints the status bar from the opaque element at the top edge. This strip is
+// that element, above every layer, so a see-through scrim or drawer over the
+// top of the app can never change the status bar's color.
+const css = `[data-slot="status-bar"]{position:fixed;inset:0 0 auto;z-index:2147483647;pointer-events:none;height:env(safe-area-inset-top);background-color:light-dark(${THEME_COLORS.light},${THEME_COLORS.dark})}@media (display-mode:standalone){[data-slot="status-bar"]{height:max(12px,env(safe-area-inset-top))}}`;
+
+/**
+ * `color` paints it in place of the Theme's background, for an app whose top
+ * edge changes, such as a page that moves aside for a sidebar. Any CSS color.
+ */
+export function StatusBar(props: { readonly color?: string }) {
+  return createElement(
+    Fragment,
+    null,
+    createElement('style', null, css),
+    createElement('div', {
+      'aria-hidden': true,
+      'data-slot': 'status-bar',
+      style:
+        props.color === undefined
+          ? undefined
+          : { backgroundColor: props.color },
+    }),
+  );
+}

package/src/theme/store.ts

@@ -0,0 +1,66 @@
+import { useSyncExternalStore } from 'react';
+import { themeFromCookies, writeThemeCookie } from './cookie.ts';
+import { applyThemeToDocument } from './document.ts';
+import {
+  DEFAULT_THEME,
+  THEME_CHANGED,
+  THEME_COOKIE,
+  type Theme,
+} from './model.ts';
+
+let current: Theme = DEFAULT_THEME;
+let listening = false;
+const listeners = new Set<() => void>();
+
+const readBrowserTheme = (): Theme => themeFromCookies(document.cookie);
+
+const publish = (theme: Theme, freeze = false): void => {
+  current = theme;
+  applyThemeToDocument(theme, freeze);
+  for (const listener of listeners) listener();
+};
+
+const refresh = (): void => {
+  const theme = readBrowserTheme();
+  if (theme !== current) publish(theme);
+};
+
+const beginListening = (): void => {
+  if (listening || typeof window === 'undefined') return;
+  listening = true;
+  current = readBrowserTheme();
+  applyThemeToDocument(current);
+  window.addEventListener(THEME_CHANGED, refresh);
+  window.addEventListener('focus', refresh);
+  document.addEventListener('visibilitychange', refresh);
+
+  const cookies = window.cookieStore;
+  cookies?.addEventListener('change', (event) => {
+    if (
+      [...event.changed, ...event.deleted].some(
+        (cookie) => cookie.name === THEME_COOKIE,
+      )
+    ) {
+      refresh();
+    }
+  });
+};
+
+const subscribe = (listener: () => void): (() => void) => {
+  beginListening();
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+};
+
+export const useThemeValue = (): Theme =>
+  useSyncExternalStore(
+    subscribe,
+    () => current,
+    () => DEFAULT_THEME,
+  );
+
+export const setThemeValue = (theme: Theme, cookieDomain?: string): void => {
+  writeThemeCookie(theme, cookieDomain);
+  publish(theme, true);
+  window.dispatchEvent(new Event(THEME_CHANGED));
+};

package/src/theme/theme.ts

@@ -0,0 +1,45 @@
+import { createElement, Fragment } from 'react';
+import { bootstrapSource } from './document.ts';
+import { THEME_COLORS, type Theme } from './model.ts';
+import { StatusBar } from './status-bar.ts';
+import { setThemeValue, useThemeValue } from './store.ts';
+
+export function createTheme(
+  options: { readonly cookieDomain?: string | undefined } = {},
+) {
+  const setTheme = (theme: Theme) => setThemeValue(theme, options.cookieDomain);
+
+  function useTheme() {
+    const theme = useThemeValue();
+    return {
+      theme,
+      setTheme,
+      toggleTheme: () => setTheme(theme === 'dark' ? 'light' : 'dark'),
+    };
+  }
+
+  function Script(props: { readonly initialTheme?: Theme }) {
+    const initialTheme = props.initialTheme ?? 'dark';
+    return createElement(
+      Fragment,
+      null,
+      createElement('meta', {
+        name: 'theme-color',
+        content: THEME_COLORS[initialTheme],
+      }),
+      createElement('script', {
+        dangerouslySetInnerHTML: { __html: bootstrapSource(initialTheme) },
+      }),
+    );
+  }
+
+  return {
+    useTheme,
+    Script,
+    StatusBar,
+    manifest: (theme: Theme) => ({
+      theme_color: THEME_COLORS[theme],
+      background_color: THEME_COLORS[theme],
+    }),
+  };
+}