@frontera-sdk/core 1.47.1 → 1.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/core",
-  "version": "1.47.1",
+  "version": "1.48.0",
   "description": "Frontera app runtime: the platform bridge client, app bootstrap and typed platform client.",
   "keywords": [
     "frontera",

package/src/create-frontera-app.tsx

@@ -108,19 +108,240 @@ class AppErrorBoundary extends Component<BoundaryProps, { error: Error | null }>
   }
 }
 
-function diagnostic(title: string, detail: string): ReactNode {
+/**
+ * The keyframes the boot screen needs.
+ *
+ * Inlined as a <style> element rather than a CSS import because this package
+ * is consumed as source by app bundlers that are not all configured to handle
+ * a stylesheet import, and a boot screen must never be the thing that breaks
+ * the build it is meant to report on.
+ */
+const BOOT_KEYFRAMES =
+  '@keyframes frontera-boot-cube{0%,70%,100%{transform:scale3d(.5,.5,1)}35%{transform:scale3d(0,0,1)}}' +
+  '@keyframes frontera-boot-shimmer{0%{background-position:100% 0}100%{background-position:-100% 0}}' +
+  '@media(prefers-reduced-motion:reduce){' +
+  '[data-frontera-boot-cube]{animation-duration:3.9s!important}' +
+  '[data-frontera-boot-shimmer]{animation:none!important}}'
+
+/**
+ * Per-cube animation delays, in grid order.
+ *
+ * Copied from the platform's `.spinner-cube:nth-child(n)` rules rather than
+ * re-derived, so the two read as the same object in motion. The pattern is a
+ * diagonal wave: equal delays run bottom-left to top-right.
+ */
+const BOOT_CUBE_DELAYS = [0.2, 0.3, 0.4, 0.1, 0.2, 0.3, 0, 0.1, 0.2]
+
+/**
+ * Colours for the boot screen.
+ *
+ * Tokens, with literals only for the app that defines none of them.
+ *
+ * This paints in whatever scheme the document is already in, which before the
+ * handshake means the app's own `:root` — light, unless the app itself has put
+ * `.dark` on the document. Nothing here sets the scheme: `applyHostTheme` runs
+ * at handshake, by which point this screen is gone, and a guess made earlier
+ * would be a write that outlives the screen and fights the app for control of
+ * its own theme.
+ *
+ * There is deliberately no `foreground` entry. In the platform theme
+ * `--foreground` holds a bare HSL triplet (`47 13% 14%`) rather than a colour —
+ * it is wrapped as `hsl(var(--foreground))` at the point of use — and Tailwind's
+ * `@theme inline` does not emit a `--color-foreground` custom property to reach
+ * for instead. Naming either one here produces an invalid declaration that the
+ * browser drops. Text therefore INHERITS, which lands on the app's own body
+ * colour: already correct, in either scheme, with nothing to keep in sync.
+ */
+const BOOT_PALETTE = {
+  // `--surface`, not `--background`: this screen sits where the app's own
+  // surface will be, so booting on the surface colour means the handover to
+  // the real UI is not also a change of backdrop. It needs no `--color-*`
+  // form — unlike the two below it, `--surface` is already a colour.
+  background: 'var(--surface, #fafafa)',
+  muted: 'var(--muted-foreground, #6b7280)',
+  border: 'var(--border, #e5e7eb)',
+  surface: 'var(--surface-raised, var(--surface, #fafafa))',
+  destructive: 'var(--destructive, #dc2626)',
+}
+
+/**
+ * The spinner shown while the session is being established.
+ *
+ * The platform's own `GridSpinner` — a 3×3 of pulsing cubes — rebuilt here in
+ * inline styles, because this package has neither Tailwind nor the stylesheet
+ * that rule lives in. Matching it matters more than the few lines it costs: an
+ * app booting inside the platform should not announce itself with a spinner
+ * shape that appears nowhere else in the product.
+ *
+ * Not a top bar: `AppFrame` already shows `LoadingBar` outside the iframe for
+ * exactly this wait, and a second bar inside the frame would draw the same
+ * progress twice.
+ *
+ * Sized in `em` like the original, so the cubes track the font size rather
+ * than needing a second number kept in sync.
+ */
+function bootSpinner(): ReactNode {
+  return (
+    <div
+      aria-hidden="true"
+      style={{
+        display: 'inline-grid',
+        gridTemplateColumns: 'repeat(3, 1fr)',
+        gap: '0.08em',
+        width: '1em',
+        height: '1em',
+        fontSize: 28,
+        color: BOOT_PALETTE.muted,
+        // Tops the container's 10 up to the 16 this sits above.
+        marginBottom: 6,
+      }}
+    >
+      {BOOT_CUBE_DELAYS.map((delay, index) => (
+        <span
+          key={index}
+          data-frontera-boot-cube=""
+          style={{
+            backgroundColor: 'currentColor',
+            transform: 'scale3d(0.5, 0.5, 1)',
+            animation: `frontera-boot-cube 1.3s ${delay}s infinite ease-in-out`,
+          }}
+        />
+      ))}
+    </div>
+  )
+}
+
+/**
+ * The screens shown before an app can render: connecting, and the two ways
+ * starting can fail.
+ *
+ * Colours come from `BOOT_PALETTE` rather than being written inline, because
+ * this paints BEFORE `applyHostTheme` has run and the values have to hold up
+ * without it.
+ */
+function diagnostic(title: string, detail: string, variant: 'loading' | 'error' = 'error'): ReactNode {
+  const loading = variant === 'loading'
   return (
     <div
-      role="alert"
+      // A loading screen is a status, not an alert: `alert` is assertive and
+      // interrupts the screen-reader user on every single app boot.
+      role={loading ? 'status' : 'alert'}
+      aria-live={loading ? 'polite' : undefined}
       style={{
+        boxSizing: 'border-box',
+        minHeight: '100dvh',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 32,
         fontFamily: 'var(--font-sans, system-ui, sans-serif)',
-        color: 'var(--foreground, #111)',
-        padding: 24,
+        background: BOOT_PALETTE.background,
         lineHeight: 1.5,
       }}
     >
-      <strong>{title}</strong>
-      <div style={{ marginTop: 4, opacity: 0.75, fontSize: 14 }}>{detail}</div>
+      <style>{BOOT_KEYFRAMES}</style>
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          // The two gaps differ: 10 between the lines of text, 16 from the
+          // indicator down to them. `gap` sets the smaller one for every pair
+          // and the indicator adds the remainder below itself, so the two
+          // numbers stay readable instead of being one compromise value.
+          gap: 10,
+          textAlign: 'center',
+          maxWidth: 380,
+        }}
+      >
+        {loading ? (
+          bootSpinner()
+        ) : (
+          <svg
+            aria-hidden="true"
+            viewBox="0 0 24 24"
+            width={30}
+            height={30}
+            fill="none"
+            stroke={BOOT_PALETTE.destructive}
+            strokeWidth={2}
+            strokeLinecap="round"
+          >
+            <circle cx="12" cy="12" r="9" />
+            <path d="M12 8v5" />
+            <path d="M12 16.5h.01" />
+          </svg>
+        )}
+        <div
+          data-frontera-boot-shimmer={loading ? '' : undefined}
+          style={{
+            // No font-size: `<strong>` inherited the body size on main, and
+            // matching it keeps this screen the size it has always been.
+            fontWeight: 'bold' as const,
+            // A highlight sweeping across the glyphs themselves, clipped to the
+            // text. Only while connecting: an error is not in progress, and
+            // animating it would suggest the app is still trying.
+            //
+            // The gradient rests on `currentColor`, which is the heading's own
+            // full-contrast colour — on main this was plain `--foreground`, and
+            // a muted base would leave it at the same weight as the line
+            // beneath it for most of the sweep.
+            //
+            // `currentColor` rather than the token, because a token can fail:
+            // in the platform theme `--foreground` holds a bare HSL triplet, so
+            // naming it inside `linear-gradient()` makes the whole declaration
+            // invalid. The browser then drops the gradient but KEEPS
+            // `-webkit-text-fill-color: transparent` — and the heading vanishes
+            // entirely. `currentColor` is always a valid colour, so the worst
+            // case is a shimmer that does not shimmer, never invisible text.
+            //
+            // The travelling stop is `muted-foreground`, NOT `primary`: primary
+            // is near-black in the default light theme, which is also what the
+            // heading already is, so that sweep was three identical stops and
+            // no visible motion. Muted is the one token guaranteed to differ
+            // from body text in both schemes — that is what it is for.
+            ...(loading
+              ? {
+                  backgroundImage: `linear-gradient(90deg, currentColor 30%, ${BOOT_PALETTE.muted} 50%, currentColor 70%)`,
+                  backgroundSize: '200% 100%',
+                  WebkitBackgroundClip: 'text',
+                  backgroundClip: 'text',
+                  fontSize: 18,
+                  // Transparent text is invisible if `background-clip: text` is
+                  // not honoured, so the fill is set the same way and the
+                  // colour underneath stays the readable one.
+                  WebkitTextFillColor: 'transparent',
+                  animation: 'frontera-boot-shimmer 2s linear infinite',
+                }
+              : {}),
+          }}
+        >
+          {title}
+        </div>
+        <div
+          style={{
+            fontSize: 14,
+            color: BOOT_PALETTE.muted,
+            // An error detail is a raw message or stack fragment: monospaced,
+            // left-aligned and boxed so a long one stays readable instead of
+            // becoming a centred wall of text.
+            ...(loading
+              ? {}
+              : {
+                  fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+                  textAlign: 'left' as const,
+                  background: BOOT_PALETTE.surface,
+                  border: `1px solid ${BOOT_PALETTE.border}`,
+                  borderRadius: 'calc(var(--radius, 8px) - 2px)',
+                  padding: '10px 12px',
+                  maxWidth: '100%',
+                  overflowWrap: 'anywhere' as const,
+                }),
+          }}
+        >
+          {detail}
+        </div>
+      </div>
     </div>
   )
 }
@@ -209,7 +430,7 @@ export interface FronteraAppProviderProps {
 export function FronteraAppProvider({
   children,
   providers = [],
-  loading = diagnostic('Connecting to Frontera', 'Establishing an authenticated App session.'),
+  loading = diagnostic('Connecting to Frontera', 'Establishing an authenticated App session.', 'loading'),
   errorFallback,
   queryClient: providedQueryClient,
   timeoutMs,