@dxos/app-framework 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/vite-plugin/boot-loader/BootLoader.stories.tsx

@@ -0,0 +1,263 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useRef, useState } from 'react';
+
+import { Composer } from '@dxos/brand';
+import { Toolbar } from '@dxos/react-ui';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { Placeholder } from '../../ui';
+import bootLoaderCss from './boot-loader.css?raw';
+import bootLoaderScript from './boot-loader.js?raw';
+
+/**
+ * Storybook host that runs the **real** inline driver script (`boot-loader.js`)
+ * against the same DOM structure {@link bootLoaderPlugin} injects in production
+ * via `transformIndexHtml`. The component injects `<style>` + the loader DOM,
+ * evaluates the driver, and exposes `window.__bootLoader` for the stories to
+ * call — no React reimplementation of the state machine.
+ *
+ * On unmount, the host calls `__bootLoader.dismiss()` (which clears the creep
+ * timer and removes the `#boot-loader` node) and clears the global so a fresh
+ * mount re-runs the driver from scratch.
+ */
+type BootLoaderHostProps = {
+  initialStatus?: string;
+  markSvg?: string;
+};
+
+// `__bootLoader` is declared globally by `../../ui/components/Placeholder/Placeholder.tsx`
+// so consumers don't have to redeclare it. The story imports `Placeholder` for the
+// handoff scenarios, which pulls the declaration into scope.
+
+const BootLoaderHost = ({ initialStatus = 'Loading…', markSvg }: BootLoaderHostProps) => {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+    // Mirror the HTML structure produced by `bootLoaderPlugin.transformIndexHtml`.
+    const initialLine = initialStatus ? `<div class="boot-loader-status-line">${escapeHtml(initialStatus)}</div>` : '';
+    const markHtml = markSvg ? `<div id="boot-loader-mark">${markSvg}</div>` : '';
+    container.innerHTML = `
+      <div id="boot-loader" role="status" aria-live="polite" aria-label="Initializing">
+        <div id="boot-loader-disc">
+          <div id="boot-loader-bar"></div>
+          <div id="boot-loader-dot"></div>
+          ${markHtml}
+        </div>
+        <div id="boot-loader-status">${initialLine}</div>
+      </div>
+    `;
+    // Evaluate the driver IIFE — it auto-promotes idle → state 1 (slow creep)
+    // and exposes `window.__bootLoader.{status, progress, dismiss}` globally.
+    const driverEl = document.createElement('script');
+    driverEl.textContent = bootLoaderScript;
+    container.appendChild(driverEl);
+
+    return () => {
+      try {
+        window.__bootLoader?.dismiss();
+      } catch {
+        // Driver removes its own DOM — swallow errors from idempotent retries.
+      }
+      delete window.__bootLoader;
+      container.innerHTML = '';
+    };
+  }, [initialStatus, markSvg]);
+
+  return (
+    <>
+      <style>{bootLoaderCss}</style>
+      <div ref={containerRef} />
+    </>
+  );
+};
+
+const escapeHtml = (text: string): string =>
+  text.replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]!);
+
+// Inlined snapshot of `packages/ui/brand/assets/icons/composer-icon.svg` —
+// keeps storybook self-contained (production pipes the same file in from
+// vite.config.ts via the plugin's `markSvg` option) while previewing the
+// real brand palette the loader will render in production.
+const PLACEHOLDER_MARK = `
+  <svg viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g transform="matrix(0.969697,0,0,1,-570.182,0)">
+      <rect x="588" y="0" width="264" height="256" style="fill:none;"/>
+      <g transform="matrix(0.917198,0,0,1,-223.93,-876)">
+        <path d="M1065.83,1064L1029.14,1064C991.913,1064 961.684,1037.12 961.684,1004C961.684,971.197 991.282,944.542 1028.02,944.008L1028.02,944L1047.85,944L1039.21,968L1029.14,968C1006.79,968 988.669,984.118 988.669,1004C988.669,1023.87 1006.81,1040 1029.14,1040C1029.38,1040 1029.62,1040 1029.85,1040L1029.85,1040L1074.47,1040L1065.83,1064ZM1083.11,1040L1083.11,1040L1083.11,1064L1083.11,1064L1083.11,1040Z" style="fill:rgb(1,122,183);"/>
+      </g>
+      <path d="M761.579,164L720,164C699.51,164 682.875,147.869 682.875,128C682.875,108.452 698.942,92.543 718.969,92.014L718.969,92L729.238,92L721.317,116L720,116C713.165,116 707.625,121.373 707.625,128C707.625,134.623 713.17,140 720,140C720.072,140 720.144,139.999 720.216,139.998L720.216,140L769.5,140L761.579,164Z" style="fill:rgb(6,197,253);"/>
+      <path d="M745.738,212L720.025,212L720,212C672.202,212 633.389,174.377 633.375,128.024C633.361,81.958 671.591,44.542 718.969,44.006L718.969,44L719.975,44L745.079,44L737.159,68L719.982,68C685.809,68.01 658.115,94.88 658.125,128.017C658.135,161.126 685.858,188 720,188L720.018,188C720.378,188 720.738,187.997 721.098,187.991L721.098,188L753.659,188L745.738,212Z" style="fill:rgb(10,75,105);"/>
+      <g transform="matrix(1.03125,0,0,1,588,0)">
+        <path d="M128,236C68.393,236 20,187.607 20,128C20,68.353 68.353,20 128,20L160,20L152.319,44L128,44C81.608,44 44,81.608 44,128C44,174.361 81.639,212 128,212C127.756,212.004 127.878,212.004 128,212.003C128.122,212.002 128.244,212 128,212L152.958,212L145.277,236L128,236ZM128,236C128.628,236 127.372,236.011 128,236Z" style="fill:rgb(5,40,61);"/>
+      </g>
+    </g>
+  </svg>
+`;
+
+/**
+ * Approximate plugin count used by the simulation. Hardcoded here to keep the
+ * storybook self-contained — the production count comes from
+ * `composer-app/src/plugin-defs.tsx`'s dynamic-import list.
+ */
+const STORY_PLUGIN_COUNT = 80;
+
+/** Tick interval for the determinate-progress simulation, in ms. */
+const STORY_TICK_MS = 50;
+
+/**
+ * Story controls — emits real `__bootLoader.status(...)` and `progress(...)`
+ * calls into the running driver script, which then drives the visible DOM.
+ * No React state shadow of the loader's progress; the driver is the source
+ * of truth.
+ */
+type SimRunningState = 'idle' | 'creep' | 'progress' | 'done';
+
+const useBootLoaderDriver = ({ withHandoff = false }: { withHandoff?: boolean } = {}) => {
+  const [running, setRunning] = useState<SimRunningState>('creep');
+  const [stage, setStage] = useState(0);
+
+  // `creep` state — driver auto-creeps; the story emits a sequence of
+  // status messages so the appended-log behaviour is observable.
+  useEffect(() => {
+    if (running !== 'creep') {
+      return;
+    }
+    const phases = ['Loading framework…', 'Reading configuration…', 'Starting services…'];
+    let index = 0;
+    const handle = setInterval(() => {
+      window.__bootLoader?.status({ humanized: phases[index] });
+      index += 1;
+      if (index >= phases.length) {
+        clearInterval(handle);
+      }
+    }, 600);
+    return () => clearInterval(handle);
+  }, [running]);
+
+  // `progress` state — random-walk through the plugin count, calling the
+  // real `__bootLoader.progress(...)` so the driver's no-regress + creep
+  // logic runs as it does in production.
+  useEffect(() => {
+    if (running !== 'progress') {
+      return;
+    }
+    let loaded = 0;
+    const handle = setInterval(() => {
+      loaded += Math.abs(Math.random()) * 1.5;
+      const fraction = Math.min(1, loaded / STORY_PLUGIN_COUNT);
+      window.__bootLoader?.progress(fraction);
+      // Range-bearing payload — replaces the current line in place
+      // instead of appending one entry per plugin tick.
+      window.__bootLoader?.status({
+        humanized: 'Loading plugins',
+        range: { index: Math.round(loaded), total: STORY_PLUGIN_COUNT },
+      });
+      if (loaded >= STORY_PLUGIN_COUNT) {
+        clearInterval(handle);
+        window.__bootLoader?.status({ humanized: 'Starting Composer…' });
+        setRunning('done');
+      }
+    }, STORY_TICK_MS);
+    return () => clearInterval(handle);
+  }, [running]);
+
+  // Handoff phase — fade the placeholder in/out once the driver hits 100%.
+  useEffect(() => {
+    if (!withHandoff || running !== 'done') {
+      return;
+    }
+    const handles: ReturnType<typeof setTimeout>[] = [];
+    handles.push(setTimeout(() => setStage(1), 200));
+    handles.push(setTimeout(() => setStage(2), 2_000));
+    return () => handles.forEach(clearTimeout);
+  }, [running, withHandoff]);
+
+  const advance = () => {
+    if (running === 'creep') {
+      setRunning('progress');
+    } else {
+      setRunning('creep');
+      setStage(0);
+    }
+  };
+
+  return { running, stage, advance };
+};
+
+const SimToolbar = ({ running, advance }: { running: SimRunningState; advance: () => void }) => {
+  const button =
+    running === 'creep'
+      ? { icon: 'ph--play--regular', label: 'Start progress' }
+      : { icon: 'ph--arrow-counter-clockwise--regular', label: 'Reset' };
+  return (
+    <Toolbar.Root classNames='relative z-20'>
+      <Toolbar.IconButton icon={button.icon} label={button.label} iconOnly onClick={advance} />
+      <Toolbar.Text>{running}</Toolbar.Text>
+    </Toolbar.Root>
+  );
+};
+
+const DefaultStory = () => {
+  const { running, advance } = useBootLoaderDriver();
+  return (
+    <>
+      <SimToolbar running={running} advance={advance} />
+      <BootLoaderHost markSvg={PLACEHOLDER_MARK} />
+    </>
+  );
+};
+
+const meta: Meta<typeof BootLoaderHost> = {
+  title: 'sdk/app-framework/vite-plugin/BootLoader',
+  component: BootLoaderHost,
+  render: DefaultStory,
+  decorators: [withTheme({})],
+  parameters: {
+    layout: 'fullscreen',
+  },
+  argTypes: {
+    initialStatus: { control: 'text' },
+    markSvg: { control: 'text' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof BootLoaderHost>;
+
+export const Default: Story = {};
+
+/**
+ * Renders the React `Placeholder` from `@dxos/app-framework/ui` on its own —
+ * useful for eyeballing the handoff target the boot loader dismisses to.
+ */
+export const PlaceholderHandoff: Story = {
+  name: 'Placeholder',
+  render: () => <Placeholder stage={1} logo={(logoProps) => <Composer {...logoProps} />} />,
+};
+
+/**
+ * End-to-end handoff sim: the driver ticks 0 → 100% then the host calls
+ * `dismiss()` and the underlying `Placeholder` fades the mark in / out,
+ * mirroring the production sequence.
+ */
+export const Handoff: Story = {
+  render: () => {
+    const { running, stage, advance } = useBootLoaderDriver({ withHandoff: true });
+    return (
+      <>
+        <SimToolbar running={running} advance={advance} />
+        <Placeholder stage={stage} logo={(logoProps) => <Composer {...logoProps} />} />
+        {stage < 1 && <BootLoaderHost markSvg={PLACEHOLDER_MARK} />}
+      </>
+    );
+  },
+};

package/src/vite-plugin/boot-loader/boot-loader.css

@@ -0,0 +1,294 @@
+/*
+ * Boot loader stylesheet — injected into the host's `<head>` by `bootLoaderPlugin`.
+ * The keyframe animation runs on the browser's compositor thread, so the bar
+ * keeps moving even while the JS main thread is busy parsing modules.
+ */
+
+/*
+ * Defaults match `@dxos/ui-theme`'s `--color-base-surface`, which resolves to
+ * Tailwind's `neutral-50` / `neutral-950` in light / dark mode respectively
+ * (see `packages/ui/ui-theme/src/css/theme/semantic.css`). Hosts can override
+ * with the `--boot-loader-bg-*` / `--boot-loader-fg-*` custom properties on
+ * `:root` if they need a different palette. Keeping the boot loader's
+ * background identical to the app's `body` eliminates the flash on handoff
+ * to React's `<Placeholder>`.
+ */
+#boot-loader {
+  /*
+   * Tunable sizes — change these in one place and every derived calc()
+   * (mark size, dot orbit radius, status offset, …) follows.
+   */
+  /*
+   * Caps the disc / mark at the design pixel sizes on roomy viewports while
+   * shrinking proportionally on narrow ones (`vmin` follows the smaller of
+   * width / height) so neither the ring nor the mark crops on phones.
+   */
+  --boot-loader-disc-size: min(384px, 80vmin);
+  /*
+   * Match the React `Placeholder`'s logo box (`h-[300px] w-[300px]` at the
+   * `stage >= 1` keyframe) so the brand mark doesn't visibly jump size when
+   * the loader hands off — the responsive cap keeps the same 300/384 ratio
+   * (≈78%) at any viewport width.
+   */
+  --boot-loader-mark-size: min(300px, 62.5vmin);
+  --boot-loader-dot-size: 6px;
+  --boot-loader-line-thickness: 1px;
+  --boot-loader-line-feather: 2px;
+  --boot-loader-status-gap: 24px;
+
+  position: fixed;
+  inset: 0;
+  z-index: 10;
+  background: var(--boot-loader-bg-light, #fafafa);
+  color: var(--boot-loader-fg-light, #0a0a0a);
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+  font-size: 13px;
+}
+
+@media (prefers-color-scheme: dark) {
+  #boot-loader {
+    background: var(--boot-loader-bg-dark, #0a0a0a);
+    color: var(--boot-loader-fg-dark, #fafafa);
+  }
+}
+
+/*
+ * Register the progress var as a typed custom property so the browser can
+ * interpolate it. Both the conic-gradient arc and the orbiting dot derive
+ * their angle from `--boot-loader-bar-progress`, so animating the var (rather
+ * than the resulting `background` / `transform`) keeps them in lockstep —
+ * `transition: background` on a conic-gradient doesn't interpolate smoothly
+ * in all engines, which previously caused the head of the arc to flicker
+ * against the dot during each progress step.
+ */
+@property --boot-loader-bar-progress {
+  syntax: '<number>';
+  inherits: true;
+  initial-value: 0;
+}
+
+/*
+ * Stack the ring and the brand mark in the same square so the mark sits
+ * centered inside the circle. Grid stacking keeps the mark outside the ring's
+ * mask (the mask would otherwise clip the SVG to the 1px-thick arc shape).
+ */
+#boot-loader-disc {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  display: grid;
+  place-items: center;
+  width: var(--boot-loader-disc-size);
+  height: var(--boot-loader-disc-size);
+  transform: translate(-50%, -50%);
+  transition: --boot-loader-bar-progress 240ms ease-out;
+}
+
+#boot-loader-disc > * {
+  grid-column: 1;
+  grid-row: 1;
+}
+
+/*
+ * Default to grayscale so the mark reads as a quiet monochrome silhouette
+ * before any host-driven progress lands; the brand palette swaps in once
+ * the driver flips `data-host-driven` on the disc (state-2 entry — the
+ * first `__bootLoader.progress()` call). Hover keeps a parallel reveal
+ * affordance for inspection in the storybook. The 600ms ease lets the
+ * grayscale → color transition play through the activation phase rather
+ * than snapping.
+ */
+#boot-loader-mark {
+  width: var(--boot-loader-mark-size);
+  height: var(--boot-loader-mark-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  filter: grayscale(100%);
+  transition: filter 1000ms ease-out;
+}
+
+/*
+ * `grayscale(0%)` (identity) rather than `none` — `filter: none` changes
+ * the filter function list and most engines treat that as a discrete
+ * transition (snap, not ease). Keeping `grayscale(...)` on both sides of
+ * the rule lets the browser interpolate the percentage smoothly.
+ */
+#boot-loader-disc[data-host-driven] #boot-loader-mark,
+#boot-loader-mark:hover {
+  filter: grayscale(0%);
+}
+
+#boot-loader-mark svg {
+  width: 100%;
+  height: 100%;
+  /*
+   * The host SVG carries its own brand-palette fills, so we don't apply a
+   * `color` cascade here. SVGs that intentionally use `fill="currentColor"`
+   * still pick up the loader's text colour via `#boot-loader`'s `color`.
+   */
+}
+
+/*
+ * Circular determinate progress — a 1px-thick ring carved out of a filled
+ * disc by a radial-gradient mask. The mask applies to the element and its
+ * descendants so the `::before` progress arc is clipped to the ring shape
+ * too. There is no indeterminate state: the ring sits empty (0%) until the
+ * host calls `__bootLoader.progress(fraction)`, then the arc grows in place.
+ * The fill repaints on the compositor thread so progress remains visually
+ * smooth even while the JS main thread is busy parsing modules.
+ */
+#boot-loader-bar {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  background: rgba(127, 127, 127, 0.18);
+  opacity: 0.2;
+  /*
+   * Feather the inner edge so the thin line gets soft anti-aliased edges
+   * instead of a hard pixel cutoff (which can look stair-stepped on
+   * non-retina screens). The outer edge is clipped by `border-radius: 50%`,
+   * so only the inner side of the ring needs the gradient feather. The
+   * solid line lives in the outermost `--boot-loader-line-thickness` of the
+   * disc; the feather extends `--boot-loader-line-feather` further inward.
+   */
+  mask: radial-gradient(
+    circle closest-side,
+    transparent calc(100% - var(--boot-loader-line-thickness) - var(--boot-loader-line-feather)),
+    #000 calc(100% - var(--boot-loader-line-thickness))
+  );
+  -webkit-mask: radial-gradient(
+    circle closest-side,
+    transparent calc(100% - var(--boot-loader-line-thickness) - var(--boot-loader-line-feather)),
+    #000 calc(100% - var(--boot-loader-line-thickness))
+  );
+}
+
+/*
+ * The host writes 0–100 into `--boot-loader-bar-progress` via
+ * `__bootLoader.progress(fraction)`. The `transition: background` smooths
+ * the transitions between counter ticks so the arc grows continuously
+ * rather than snapping. `conic-gradient` is clockwise-only, so the arc is
+ * mirrored horizontally with `scaleX(-1)` to grow anticlockwise from
+ * 12 o'clock.
+ */
+#boot-loader-bar::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  background: conic-gradient(currentcolor calc(var(--boot-loader-bar-progress, 0) * 1%), transparent 0);
+  transform: scaleX(-1);
+  opacity: 0.9;
+}
+
+/*
+ * A small dot at the leading edge of the arc. Lives as a sibling of the
+ * masked ring (inside `#boot-loader-disc`) so the radial-gradient mask
+ * doesn't clip it. The `rotate(...) translateY(-50%)` recipe orbits the
+ * dot around the disc centre: at progress 0 it sits at 12 o'clock; the
+ * negative rotation grows it anticlockwise to match the arc.
+ */
+#boot-loader-dot {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: var(--boot-loader-dot-size);
+  height: var(--boot-loader-dot-size);
+  margin: calc(var(--boot-loader-dot-size) / -2) 0 0 calc(var(--boot-loader-dot-size) / -2);
+  border-radius: 50%;
+  background: currentcolor;
+  opacity: 0;
+  /*
+   * Orbit radius = `disc/2 - line/2` so the dot's centre lands on the solid
+   * line's centre rather than on the disc's outer edge (the line lives in
+   * the outermost `--boot-loader-line-thickness` of the disc).
+   */
+  transform: rotate(calc(var(--boot-loader-bar-progress, 0) * -3.6deg))
+    translateY(calc(var(--boot-loader-disc-size) / -2 + var(--boot-loader-line-thickness) / 2));
+  transition: opacity 200ms ease-out;
+}
+
+/*
+ * The driver sets `data-progress-active` on `#boot-loader-disc` while
+ * progress is strictly between 0 and 1, hiding the dot at the empty (0%)
+ * and full (100%) ring states where it would either sit on a bare ring or
+ * coincide with the start of the arc.
+ */
+#boot-loader-disc[data-progress-active] #boot-loader-dot {
+  opacity: 0.9;
+}
+
+#boot-loader-status {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  /* Sit just below the centered disc — half the disc plus the configured gap. */
+  transform: translate(-50%, calc(var(--boot-loader-disc-size) / 2 + var(--boot-loader-status-gap)));
+  /*
+   * Slightly de-emphasised vs body text so the brand mark + ring stay the
+   * dominant focus, but high enough to remain legible on both light and dark
+   * backgrounds without a custom palette.
+   */
+  opacity: 0.5;
+  /*
+   * Single-line viewport over a vertically-stacked track of every status
+   * the driver has emitted. The track translates upward by one line-height
+   * per `status()` call (see `--boot-loader-line` below), animated via
+   * CSS `transition` on `transform` so the new line slides in from below
+   * while the previous line slides out — independent of any
+   * `scroll-behavior` smooth-scroll support, which Playwright/headless
+   * Chrome strips even from spec-compliant `scrollTo({ behavior: 'smooth' })`
+   * calls.
+   */
+  height: 1.5em;
+  line-height: 1.5;
+  letter-spacing: 0.01em;
+  /* 
+   * Fixed-width digits so the `(i/n)` counter on range-bearing status
+   * updates ("Loading plugins (12/80)") doesn't jitter as the index
+   * ticks through different glyph widths. 
+   */
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+  overflow: hidden;
+}
+
+/*
+ * Track of every appended `.boot-loader-status-line`. The driver writes
+ * `--boot-loader-line` (0 = first line visible, 1 = second, …) on this
+ * element and the `transform` interpolates because `--boot-loader-line` is
+ * registered as a typed `<number>` custom property below.
+ */
+#boot-loader-status-track {
+  display: flex;
+  flex-direction: column;
+  /*
+   * The driver writes `transform: translateY(<index>em)` directly per
+   * `status()` call (see `boot-loader.js`). The transition animates the
+   * change so the new line slides in from below while the previous one
+   * slides out at the top.
+   */
+  transform: translateY(0);
+  transition: transform 500ms ease-out;
+}
+
+/* Honour reduced-motion preferences explicitly — `transition` doesn't auto-respect it. */
+@media (prefers-reduced-motion: reduce) {
+  #boot-loader-status-track {
+    transition: none;
+  }
+}
+
+.boot-loader-status-line {
+  flex: 0 0 auto;
+  height: 1.5em;
+  white-space: nowrap;
+}