@tamagui/static 2.7.7 → 3.0.0-beta.643.1

package/src/zero/islands.ts

@@ -0,0 +1,262 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+import type { ZeroIsland } from './options'
+
+/**
+ * Island generation.
+ *
+ * An island is a full-runtime entry graph built in a separate bundler
+ * invocation. The zero graph never imports it; it imports a generated loader
+ * that owns the deterministic server placeholder, the shared React handoff, and
+ * the async fetch of the separately built island bundle.
+ */
+
+export const ISLAND_RUNTIME_KEY = '__tamagui_island_runtime__'
+export const ISLAND_REGISTRY_KEY = '__tamagui_islands__'
+
+/** Block 3's normalized internal representation, produced at compile time. */
+export interface IslandThemeBridgeLayer {
+  inlineValues: {
+    values: Record<string, string | number>
+    themes?: Record<string, Record<string, string | number>>
+  }
+  inlineClassName: string
+}
+
+export interface IslandThemeBridge {
+  id: string
+  name: string
+  layers: IslandThemeBridgeLayer[]
+}
+
+export interface IslandGenerationInput {
+  island: ZeroIsland
+  /** Names the integration in the loader's recovery diagnostic. */
+  integration: string
+  /** Absolute path of the app's tamagui config module. */
+  configPath: string
+  /** URL the loader fetches the built island bundle from. */
+  scriptUrl: string
+  /** URL of the one generated CSS artifact both entries load. */
+  cssHref: string
+}
+
+function writeIfChanged(file: string, content: string) {
+  mkdirSync(path.dirname(file), { recursive: true })
+  let existing: string | null = null
+  try {
+    existing = readFileSync(file, 'utf8')
+  } catch {
+    existing = null
+  }
+  if (existing !== content) writeFileSync(file, content)
+}
+
+function importPath(from: string, to: string) {
+  const relative = path.relative(path.dirname(from), to).replace(/\\/g, '/')
+  return relative.startsWith('.') ? relative : `./${relative}`
+}
+
+export function generateIslandLoaderSource(input: IslandGenerationInput): string {
+  return `// generated by @tamagui/static zero-runtime. do not edit.
+import * as React from 'react'
+import * as ReactDOM from 'react-dom'
+import * as JSXRuntime from 'react/jsx-runtime'
+
+const ISLAND_ID = ${JSON.stringify(input.island.id)}
+const ISLAND_SRC = ${JSON.stringify(input.scriptUrl)}
+const CSS_HREF = ${JSON.stringify(input.cssHref)}
+const INTEGRATION = ${JSON.stringify(input.integration)}
+
+function sharedRuntime() {
+  const scope = globalThis
+  if (!scope[${JSON.stringify(ISLAND_RUNTIME_KEY)}]) {
+    scope[${JSON.stringify(ISLAND_RUNTIME_KEY)}] = {
+      react: React,
+      reactDom: ReactDOM,
+      jsxRuntime: JSXRuntime,
+    }
+  }
+  if (!scope[${JSON.stringify(ISLAND_REGISTRY_KEY)}]) {
+    scope[${JSON.stringify(ISLAND_REGISTRY_KEY)}] = {}
+  }
+  return scope
+}
+
+// The one accepted runtime recovery in zero-runtime mode, and it is loud on
+// purpose. "Unimported" is not decidable at build time for a published zero
+// artifact on Next or Metro, so the loader still guarantees the island has its
+// styles; on a correct build this never runs.
+function ensureZeroStylesheet() {
+  const links = document.querySelectorAll('link[rel="stylesheet"]')
+  for (let index = 0; index < links.length; index++) {
+    const href = links[index].getAttribute('href') || ''
+    if (href === CSS_HREF || href.split('?')[0].endsWith(CSS_HREF)) return
+  }
+  console.error(
+    '[tamagui zero-runtime] the page did not link the generated CSS artifact ' +
+      CSS_HREF +
+      ', so island "' +
+      ISLAND_ID +
+      '" (' +
+      INTEGRATION +
+      ') is loading it at runtime. On a correct build this never happens: the ' +
+      'artifact is generated by the build and must be linked by the document ' +
+      'that mounts the island. Fix the document, not this recovery.'
+  )
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = CSS_HREF
+  link.setAttribute('data-tamagui-zero-css', '1')
+  document.head.appendChild(link)
+}
+
+let pending = null
+
+function loadIsland() {
+  const scope = sharedRuntime()
+  const registered = scope[${JSON.stringify(ISLAND_REGISTRY_KEY)}][ISLAND_ID]
+  if (registered) return Promise.resolve(registered)
+  if (!pending) {
+    pending = new Promise((resolve, reject) => {
+      ensureZeroStylesheet()
+      const script = document.createElement('script')
+      script.src = ISLAND_SRC
+      script.async = true
+      script.onload = () => {
+        const mod = scope[${JSON.stringify(ISLAND_REGISTRY_KEY)}][ISLAND_ID]
+        if (mod) resolve(mod)
+        else reject(new Error('tamagui island ' + ISLAND_ID + ' did not register'))
+      }
+      script.onerror = () => reject(new Error('tamagui island ' + ISLAND_ID + ' failed to load ' + ISLAND_SRC))
+      document.head.appendChild(script)
+    })
+  }
+  return pending
+}
+
+export default function TamaguiIsland(props) {
+  const bridgeId = props['data-tamagui-bridge'] || 'root'
+  const [Loaded, setLoaded] = React.useState(null)
+
+  React.useEffect(() => {
+    let cancelled = false
+    loadIsland().then((mod) => {
+      if (!cancelled) setLoaded(() => mod.Island)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  if (!Loaded) {
+    return React.createElement('div', {
+      'data-tamagui-island': ISLAND_ID,
+      'data-tamagui-bridge': bridgeId,
+    })
+  }
+
+  const forwarded = {}
+  for (const key in props) forwarded[key] = props[key]
+  forwarded['data-tamagui-island'] = ISLAND_ID
+  return React.createElement(Loaded, forwarded)
+}
+`
+}
+
+export function generateIslandEntrySource(input: IslandGenerationInput): string {
+  const entry = input.island.entry
+  return `// generated by @tamagui/static zero-runtime. do not edit.
+import * as React from 'react'
+import { TamaguiProvider, Theme } from 'tamagui'
+import config from ${JSON.stringify(importPath(entry, input.configPath))}
+import IslandRoot from ${JSON.stringify(importPath(entry, input.island.module))}
+
+export function Island(props) {
+  const bridge = props.__tamaguiBridge
+  const inner = {}
+  for (const key in props) {
+    if (key !== '__tamaguiBridge') inner[key] = props[key]
+  }
+  let node = React.createElement(IslandRoot, inner)
+  const layers = (bridge && bridge.layers) || []
+  for (let index = layers.length - 1; index >= 0; index--) {
+    node = React.createElement(
+      Theme,
+      {
+        inlineValues: layers[index].inlineValues,
+        inlineClassName: layers[index].inlineClassName,
+        forceClassName: true,
+      },
+      node
+    )
+  }
+  // isSubtreeRoot: the island shares a document with a zero page that already
+  // has its own compiled theme spans, so its provider must not write a theme
+  // class onto html or body and must carry its own theme on its own node.
+  return React.createElement(
+    TamaguiProvider,
+    {
+      config,
+      defaultTheme: (bridge && bridge.name) || 'light',
+      disableInjectCSS: true,
+      isSubtreeRoot: true,
+    },
+    node
+  )
+}
+
+const scope = globalThis
+if (!scope[${JSON.stringify(ISLAND_REGISTRY_KEY)}]) scope[${JSON.stringify(ISLAND_REGISTRY_KEY)}] = {}
+scope[${JSON.stringify(ISLAND_REGISTRY_KEY)}][${JSON.stringify(input.island.id)}] = { Island }
+`
+}
+
+export function writeIslandModules(input: IslandGenerationInput): void {
+  writeIfChanged(input.island.loader, generateIslandLoaderSource(input))
+  writeIfChanged(input.island.entry, generateIslandEntrySource(input))
+}
+
+/**
+ * The island child build externalizes React to the handoff the generated loader
+ * publishes, so one React instance serves both graphs.
+ *
+ * Property paths are the source of truth: webpack needs the segments (a dotted
+ * string becomes one literal property name), rollup needs the joined expression.
+ */
+export const ISLAND_EXTERNAL_GLOBAL_PATHS: Record<string, string[]> = {
+  react: [ISLAND_RUNTIME_KEY, 'react'],
+  'react-dom': [ISLAND_RUNTIME_KEY, 'reactDom'],
+  'react/jsx-runtime': [ISLAND_RUNTIME_KEY, 'jsxRuntime'],
+}
+
+export const ISLAND_EXTERNAL_GLOBALS: Record<string, string> = Object.fromEntries(
+  Object.entries(ISLAND_EXTERNAL_GLOBAL_PATHS).map(([name, segments]) => [
+    name,
+    `globalThis.${segments.join('.')}`,
+  ])
+)
+
+/**
+ * Merges one module's bridge descriptors into the build-wide manifest.
+ *
+ * A module is transformed once per compilation (webpack builds a server and a
+ * client pass over the same source), so a bridge id must replace its previous
+ * record rather than append a duplicate.
+ */
+export function mergeIslandBridges(
+  target: Map<string, IslandThemeBridge[]>,
+  incoming: Map<string, IslandThemeBridge[]>
+): void {
+  for (const [islandId, bridges] of incoming) {
+    const list = target.get(islandId) ?? []
+    for (const bridge of bridges) {
+      const index = list.findIndex((existing) => existing.id === bridge.id)
+      if (index >= 0) list[index] = bridge
+      else list.push(bridge)
+    }
+    list.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0))
+    target.set(islandId, list)
+  }
+}

package/src/zero/options.ts

@@ -0,0 +1,239 @@
+import { zeroConfigDriverMessage } from '@tamagui/compiler-core'
+import type { TamaguiInternalConfig } from '@tamagui/web'
+import glob from 'fast-glob'
+import path from 'node:path'
+
+import type { TamaguiOptions } from '../types'
+
+/**
+ * `TAMAGUI_RUNTIME` has exactly two integration-owned literal values. The public
+ * `experimental.zeroRuntime` option is the author input; this literal is
+ * generated output, so an ambient shell value never reaches a build.
+ */
+export type TamaguiRuntimeLiteral = 'full' | 'zero'
+
+export type ZeroRuntimeMode = 'off' | 'report' | 'enforce'
+
+export interface ZeroIsland {
+  /** Stable, deterministic id derived from the island module's root-relative path. */
+  id: string
+  /** Absolute path of the island root module. */
+  module: string
+  /** Absolute path of the generated loader the zero graph imports. */
+  loader: string
+  /** Absolute path of the generated full-runtime entry. */
+  entry: string
+}
+
+export interface ZeroRuntimeResolved {
+  mode: ZeroRuntimeMode
+  /** The project being built. The graph gate excludes its own package. */
+  root: string
+  islandGlobs: string[]
+  islands: ZeroIsland[]
+  /** Absolute directory holding generated loaders, entries, and receipts. */
+  outDir: string
+  /** Absolute path of the single generated CSS artifact. */
+  cssPath: string
+}
+
+// under the project's existing generated-output directory, which the repository
+// already excludes from git and from the formatter
+export const ZERO_OUT_DIRNAME = '.tamagui/zero'
+
+/**
+ * Island id is the module's basename, which is also the generated loader's
+ * filename. Two declared islands may not share a basename.
+ */
+export function islandIdFor(moduleId: string): string {
+  return path.basename(moduleId).replace(/\.[jt]sx?$/, '')
+}
+
+type ZeroRuntimeInput = Pick<TamaguiOptions, 'experimental' | 'outputCSS' | 'platform'>
+
+export async function resolveZeroRuntime(
+  options: ZeroRuntimeInput,
+  root: string
+): Promise<ZeroRuntimeResolved> {
+  const early = resolveZeroRuntimeEarly(options, root)
+  if (early.done) return early.resolved
+  return finishZeroRuntime(
+    options,
+    root,
+    early.islandGlobs,
+    early.islandGlobs.length
+      ? await glob(early.islandGlobs, { cwd: root, absolute: true, dot: false })
+      : []
+  )
+}
+
+/** The webpack adapter configures itself synchronously, before any hook runs. */
+export function resolveZeroRuntimeSync(
+  options: ZeroRuntimeInput,
+  root: string
+): ZeroRuntimeResolved {
+  const early = resolveZeroRuntimeEarly(options, root)
+  if (early.done) return early.resolved
+  return finishZeroRuntime(
+    options,
+    root,
+    early.islandGlobs,
+    early.islandGlobs.length
+      ? glob.sync(early.islandGlobs, { cwd: root, absolute: true, dot: false })
+      : []
+  )
+}
+
+function resolveZeroRuntimeEarly(
+  options: ZeroRuntimeInput,
+  root: string
+):
+  | { done: true; resolved: ZeroRuntimeResolved }
+  | { done: false; islandGlobs: string[] } {
+  const requested = options.experimental?.zeroRuntime
+  const outDir = path.join(root, ZERO_OUT_DIRNAME)
+  const off: ZeroRuntimeResolved = {
+    mode: 'off',
+    root,
+    islandGlobs: [],
+    islands: [],
+    outDir,
+    cssPath: '',
+  }
+  if (!requested) return { done: true, resolved: off }
+
+  if (options.platform === 'native' && requested === 'report') {
+    return { done: true, resolved: { ...off, mode: 'report' } }
+  }
+
+  if (options.platform === 'native') {
+    throw new Error(
+      `[tamagui zero-runtime] experimental.zeroRuntime is web only. A native build always receives TAMAGUI_RUNTIME="full".`
+    )
+  }
+
+  // `report` keeps the full runtime, so it owns no generated artifact and needs
+  // no outputCSS. It still runs every per-module analysis.
+  if (requested !== 'report' && !options.outputCSS) {
+    throw new Error(
+      `[tamagui zero-runtime] experimental.zeroRuntime requires outputCSS. The bundler owns one generated CSS artifact and derives TAMAGUI_DID_OUTPUT_CSS from it.`
+    )
+  }
+
+  if (requested !== 'report' && process.env.TAMAGUI_DOES_SSR_CSS === 'mutates-themes') {
+    throw new Error(
+      `[tamagui zero-runtime] Rule 4: TAMAGUI_DOES_SSR_CSS="mutates-themes" declares runtime theme mutation. Zero-runtime themes are build-time data. Remove runtime mutation or move that surface to a full-runtime island.`
+    )
+  }
+
+  return {
+    done: false,
+    islandGlobs: requested === true || requested === 'report' ? [] : requested.islands,
+  }
+}
+
+function finishZeroRuntime(
+  options: ZeroRuntimeInput,
+  root: string,
+  islandGlobs: string[],
+  matches: string[]
+): ZeroRuntimeResolved {
+  const outDir = path.join(root, ZERO_OUT_DIRNAME)
+  // resolveZeroRuntimeEarly already rejected a missing outputCSS in enforce mode
+  const outputCSS = (options.outputCSS ?? '') as string
+  const islands = [...new Set(matches.map((match) => path.normalize(match)))]
+    .sort()
+    .map((module): ZeroIsland => {
+      const id = islandIdFor(module)
+      return {
+        id,
+        module,
+        loader: path.join(outDir, `${id}.loader.js`),
+        entry: path.join(outDir, `${id}.entry.js`),
+      }
+    })
+
+  const seen = new Set<string>()
+  for (const island of islands) {
+    if (seen.has(island.id)) {
+      throw new Error(
+        `[tamagui zero-runtime] two declared islands share the basename "${island.id}". Island ids are their module basename because that is also the generated loader's filename.`
+      )
+    }
+    seen.add(island.id)
+  }
+
+  if (islandGlobs.length && islands.length === 0) {
+    throw new Error(
+      `[tamagui zero-runtime] experimental.zeroRuntime.islands matched no module for ${JSON.stringify(
+        islandGlobs
+      )}`
+    )
+  }
+
+  return {
+    mode: options.experimental?.zeroRuntime === 'report' ? 'report' : 'enforce',
+    root,
+    islandGlobs,
+    islands,
+    outDir,
+    cssPath: !outputCSS
+      ? ''
+      : path.isAbsolute(outputCSS)
+        ? outputCSS
+        : path.resolve(root, outputCSS),
+  }
+}
+
+/**
+ * Rule 5 at config level. A non-CSS driver in the zero entry's own config means
+ * every animated component in that graph needs a component animation runtime,
+ * which is exactly what the mode removes.
+ */
+export function assertZeroConfigDrivers(config: TamaguiInternalConfig): void {
+  // `animationDrivers` is set only for a multi-driver config; a single-driver
+  // config resolves to `animations`, and reading only the map would make this
+  // check silently unable to fail for the ordinary shape
+  const drivers: [string, { outputStyle?: unknown } | undefined][] = (
+    config.animationDrivers
+      ? Object.entries(config.animationDrivers)
+      : [['default', config.animations]]
+  ) as [string, { outputStyle?: unknown } | undefined][]
+  for (const [name, driver] of drivers) {
+    if (!driver || driver.outputStyle === 'css') continue
+    throw new Error(zeroConfigDriverMessage(name, driver.outputStyle))
+  }
+}
+
+export type ZeroIntegration = 'vite' | 'next-webpack' | 'metro-web'
+
+/**
+ * Base and island support are enabled per integration after that integration
+ * passes its own receipts. One lagging integration never blocks another.
+ */
+export const ZERO_INTEGRATION_SUPPORT: Record<
+  ZeroIntegration,
+  { base: boolean; islands: boolean }
+> = {
+  vite: { base: true, islands: true },
+  'next-webpack': { base: true, islands: true },
+  'metro-web': { base: true, islands: true },
+}
+
+export function assertZeroIntegrationSupport(
+  integration: ZeroIntegration,
+  resolved: ZeroRuntimeResolved
+): void {
+  if (resolved.mode !== 'enforce') return
+  const support = ZERO_INTEGRATION_SUPPORT[integration]
+  if (!support.base) {
+    throw new Error(
+      `[tamagui zero-runtime] ${integration} has not qualified for zero-runtime output in this version. Use zeroRuntime: "report" or choose a qualified integration.`
+    )
+  }
+  if (resolved.islands.length && !support.islands) {
+    throw new Error(
+      `[tamagui zero-runtime] ${integration} does not support experimental.zeroRuntime islands in this version. Use zeroRuntime: true without islands or choose an integration with island support.`
+    )
+  }
+}

package/src/zero/ownership.ts

@@ -0,0 +1,113 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+import type { TamaguiOptions } from '../types'
+import { resolveZeroRuntimeSync } from './options'
+
+/**
+ * Artifact ownership, shared by every integration and by both CSS tiers.
+ *
+ * A build may claim `TAMAGUI_DID_OUTPUT_CSS='1'` only after the artifact that
+ * replaces the stripped JavaScript rules is proven to exist, to match the CSS
+ * this build's config generates, and to be loaded by the entry graph. Those are
+ * three separate failures with three separate causes, so they are three
+ * separate diagnostics.
+ */
+
+export type GlobalCSSFailureKind = 'missing' | 'stale' | 'unimported'
+
+export interface GlobalCSSFailure {
+  kind: GlobalCSSFailureKind
+  cssPath: string
+  message: string
+}
+
+export const hashCSS = (css: string) =>
+  createHash('sha256').update(css).digest('hex').slice(0, 16)
+
+const normalize = (value: string) => value.split(/[?#]/, 1)[0]!.replace(/\\/g, '/')
+
+/**
+ * `TAMAGUI_DOES_SSR_CSS='mutates-themes'` declares that themes are mutated at
+ * runtime, which is the one declaration that keeps the runtime theme generator
+ * alive. It therefore blocks the compiled-global-CSS claim outright.
+ */
+export const declaresRuntimeThemeMutation = () =>
+  process.env.TAMAGUI_DOES_SSR_CSS === 'mutates-themes'
+
+export interface GlobalCSSOwnership {
+  /** Absolute path of the artifact this build owns. */
+  cssPath: string
+}
+
+/**
+ * The compiled-global-CSS tier for one web build, or null when the build is not
+ * in that tier.
+ *
+ * Zero mode owns its own combined artifact and derives the flag through
+ * `ZeroCSSArtifact`, so it is deliberately excluded here: one tier, one owner.
+ */
+export function resolveGlobalCSSOwnership(
+  options: Pick<TamaguiOptions, 'experimental' | 'outputCSS' | 'platform' | 'disable'>,
+  root: string
+): GlobalCSSOwnership | null {
+  if (options.disable) return null
+  if (options.platform === 'native') return null
+  if (!options.outputCSS) return null
+  if (declaresRuntimeThemeMutation()) return null
+  if (resolveZeroRuntimeSync(options, root).mode === 'enforce') return null
+  return {
+    cssPath: path.isAbsolute(options.outputCSS)
+      ? options.outputCSS
+      : path.resolve(root, options.outputCSS),
+  }
+}
+
+/**
+ * The three ways the stripping fact and its replacement asset can diverge.
+ *
+ * `loadedModuleIds` is the set of module ids the entry graph actually shipped.
+ * An integration that publishes the artifact as a static file rather than as a
+ * graph module passes the published copy's path instead, which is the same
+ * question asked of a different transport.
+ */
+export function checkGlobalCSSArtifact(input: {
+  cssPath: string
+  expectedCSS: string
+  loadedModuleIds: Iterable<string>
+  /** How the entry is expected to reach the artifact, printed on failure. */
+  importHint: string
+}): GlobalCSSFailure | null {
+  const { cssPath, expectedCSS } = input
+  let onDisk: string
+  try {
+    onDisk = readFileSync(cssPath, 'utf8')
+  } catch {
+    return {
+      kind: 'missing',
+      cssPath,
+      message: `[tamagui] the generated CSS artifact ${cssPath} does not exist, so this build cannot claim TAMAGUI_DID_OUTPUT_CSS. The design-system, :root, font and theme rules would be stripped from JavaScript and put nowhere.`,
+    }
+  }
+  if (onDisk !== expectedCSS) {
+    return {
+      kind: 'stale',
+      cssPath,
+      message: `[tamagui] the generated CSS artifact ${cssPath} is stale: it hashes ${hashCSS(
+        onDisk
+      )} but this build's config generates ${hashCSS(
+        expectedCSS
+      )}. Deriving TAMAGUI_DID_OUTPUT_CSS from it would ship rules that do not match the build.`,
+    }
+  }
+  const wanted = normalize(cssPath)
+  for (const id of input.loadedModuleIds) {
+    if (normalize(id) === wanted) return null
+  }
+  return {
+    kind: 'unimported',
+    cssPath,
+    message: `[tamagui] the generated CSS artifact ${cssPath} exists but the entry graph never loads it. ${input.importHint}`,
+  }
+}