basalt-ui 1.20.0 → 1.21.0

package/src/vite.test.ts

@@ -17,13 +17,20 @@ function resolveConfig(plugin: Plugin, base: string): void {
   configResolved({ base } as unknown as ResolvedConfig)
 }
 
+type HtmlTransformResult = { html: string; tags: HtmlTagDescriptor[] }
+
+/** Invokes the plugin's `transformIndexHtml` hook (object form, `order: 'pre'`). */
+function transform(plugin: Plugin, html: string): HtmlTransformResult {
+  const hook = plugin.transformIndexHtml as unknown as {
+    order: 'pre'
+    handler: (html: string) => HtmlTransformResult
+  }
+  return hook.handler(html)
+}
+
 /** Invokes the plugin's `transformIndexHtml` hook and returns the emitted tags. */
 function transformHtml(plugin: Plugin, html: string): HtmlTagDescriptor[] {
-  const transformIndexHtml = plugin.transformIndexHtml as unknown as (html: string) => {
-    html: string
-    tags: HtmlTagDescriptor[]
-  }
-  return transformIndexHtml(html).tags
+  return transform(plugin, html).tags
 }
 
 type FakeReq = { url: string }
@@ -63,6 +70,7 @@ describe('basaltAppPlugin — base handling', () => {
     const tags = transformHtml(plugin, HTML_NO_VIEWPORT)
 
     expect(tags).toEqual([
+      { tag: 'meta', attrs: { charset: 'UTF-8' } },
       {
         tag: 'meta',
         attrs: {
@@ -78,7 +86,11 @@ describe('basaltAppPlugin — base handling', () => {
         tag: 'meta',
         attrs: { name: 'theme-color', media: '(prefers-color-scheme: dark)', content: '#111111' },
       },
-      { tag: 'style', children: 'html{background-color:#111111;color-scheme:dark}' },
+      {
+        tag: 'style',
+        children:
+          'html:not([data-mantine-color-scheme]){background-color:#111111;color-scheme:dark}',
+      },
       { tag: 'link', attrs: { rel: 'shortcut icon', href: '/favicon.ico' } },
       { tag: 'link', attrs: { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' } },
       { tag: 'link', attrs: { rel: 'icon', sizes: '96x96', href: '/favicon-96x96.png' } },
@@ -190,3 +202,110 @@ describe('basaltAppPlugin — base handling', () => {
     )
   })
 })
+
+describe('basaltAppPlugin — the anti-FOUC boot rule (V1)', () => {
+  const bootStyleOf = (options: Partial<BasaltAppOptions>): string => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR, ...options })
+    resolveConfig(plugin, '/')
+    const style = transformHtml(plugin, HTML_NO_VIEWPORT).find((tag) => tag.tag === 'style')
+    return String(style?.children ?? '')
+  }
+
+  test('every mode scopes the rule so Mantine can take it back', () => {
+    // The whole defect: an UNLAYERED `html{color-scheme:dark}` outranks Mantine's own layered
+    // `:root{color-scheme:var(--mantine-color-scheme)}`, so light mode kept dark native controls
+    // forever. Scoping to the absence of the attribute Mantine writes is what expires it.
+    for (const colorScheme of ['dark', 'light', 'auto', false] as const) {
+      const css = bootStyleOf({ colorScheme })
+      expect(css).toContain('html:not([data-mantine-color-scheme])')
+      expect(css).not.toMatch(/(^|[};])html\{/)
+    }
+  })
+
+  test('default is dark — byte-identical to 1.20.0 apart from the scope', () => {
+    expect(bootStyleOf({})).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#111111;color-scheme:dark}',
+    )
+  })
+
+  test('light paints the light surface and declares color-scheme: light', () => {
+    expect(bootStyleOf({ colorScheme: 'light' })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#ffffff;color-scheme:light}',
+    )
+  })
+
+  test('auto declares `light dark` and follows prefers-color-scheme for the paint', () => {
+    expect(bootStyleOf({ colorScheme: 'auto' })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#ffffff;color-scheme:light dark}' +
+        '@media(prefers-color-scheme:dark){html:not([data-mantine-color-scheme])' +
+        '{background-color:#111111}}',
+    )
+  })
+
+  test('an explicit backgroundColor wins over the auto media pair', () => {
+    expect(bootStyleOf({ colorScheme: 'auto', backgroundColor: '#abcdef' })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#abcdef;color-scheme:light dark}',
+    )
+  })
+
+  test('colorScheme: false is the full opt-out — paint, no color-scheme at all', () => {
+    expect(bootStyleOf({ colorScheme: false })).toBe(
+      'html:not([data-mantine-color-scheme]){background-color:#111111}',
+    )
+  })
+
+  test('the manifest theme_color follows the boot scheme', () => {
+    const read = (options: Partial<BasaltAppOptions>): Record<string, unknown> => {
+      const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR, ...options })
+      const body = runMiddleware(getDevMiddleware(plugin, '/'), '/site.webmanifest')
+      return JSON.parse(body ?? '{}') as Record<string, unknown>
+    }
+    expect(read({})['theme_color']).toBe('#111111')
+    expect(read({ colorScheme: 'auto' })['theme_color']).toBe('#111111')
+    expect(read({ colorScheme: 'light' })['theme_color']).toBe('#ffffff')
+    expect(read({ colorScheme: 'light' })['background_color']).toBe('#ffffff')
+  })
+})
+
+describe('basaltAppPlugin — the encoding declaration (V2)', () => {
+  const SHELL =
+    '<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n' +
+    '    <title>App</title>\n  </head>\n  <body></body>\n</html>'
+
+  test("the consumer's charset is hoisted out of the html and re-emitted first", () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    resolveConfig(plugin, '/')
+    const result = transform(plugin, SHELL)
+
+    expect(result.html).not.toContain('charset')
+    expect(result.tags[0]).toEqual({ tag: 'meta', attrs: { charset: 'utf-8' } })
+    // The hoist takes the whole line — no orphaned indentation left behind.
+    expect(result.html).toContain('<head>\n    <title>App</title>')
+  })
+
+  test('a shell that declares no encoding gets one', () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    resolveConfig(plugin, '/')
+    expect(transform(plugin, HTML_NO_VIEWPORT).tags[0]).toEqual({
+      tag: 'meta',
+      attrs: { charset: 'UTF-8' },
+    })
+  })
+
+  test('the legacy http-equiv form is left completely alone', () => {
+    const html =
+      '<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8">' +
+      '</head><body></body></html>'
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    resolveConfig(plugin, '/')
+    const result = transform(plugin, html)
+
+    expect(result.html).toBe(html)
+    expect(result.tags.some((tag) => tag.attrs?.['charset'] !== undefined)).toBe(false)
+  })
+
+  test("the hook runs `pre` so no other plugin's tags can land ahead of the charset", () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    expect((plugin.transformIndexHtml as { order?: string }).order).toBe('pre')
+  })
+})

package/src/vite.ts

@@ -211,7 +211,21 @@ export type BasaltAppOptions = {
    * plugin exists. Pass an explicit `{ light, dark }` pair of already-flat CSS colors to override.
    */
   themeColor?: 'auto' | { light: string; dark: string }
-  /** Manifest `background_color` + anti-FOUC paint color. Default: the resolved dark theme color. */
+  /**
+   * Which scheme the anti-FOUC `<style>` paints before the app boots. Default `'dark'` —
+   * `BasaltProvider`'s own default. `'light'` paints the light surface, `'auto'` declares
+   * `color-scheme: light dark` and picks the background off `prefers-color-scheme`, and `false`
+   * paints the background but declares no `color-scheme` at all (leave native controls to Mantine).
+   *
+   * Set this to whatever the app passes as `defaultColorScheme` — a mismatch is a visible flash of
+   * the wrong surface, not a correctness bug: the boot rule stops applying the moment Mantine
+   * writes `data-mantine-color-scheme` on `<html>` (see `BOOT_SCOPE`).
+   */
+  colorScheme?: 'dark' | 'light' | 'auto' | false
+  /**
+   * Manifest `background_color` + anti-FOUC paint color. Default: the theme color matching
+   * `colorScheme` (the dark one for `'dark'` / `'auto'` / `false`, the light one for `'light'`).
+   */
   backgroundColor?: string
   /** Manifest `display` mode. Default: `'standalone'`. */
   display?: 'standalone' | 'minimal-ui' | 'fullscreen' | 'browser'
@@ -319,6 +333,91 @@ const VIEWPORT_TAG: HtmlTagDescriptor = {
   attrs: { name: 'viewport', content: 'width=device-width, initial-scale=1.0, viewport-fit=cover' },
 }
 
+// ── The anti-FOUC boot rule ───────────────────────────────────────────────────────────────────
+
+/**
+ * The selector every anti-FOUC declaration is scoped to.
+ *
+ * The rule paints the page before any stylesheet lands, so it is UNLAYERED by construction — and an
+ * unlayered declaration outranks every layered one regardless of specificity. Through 1.20.0 that
+ * meant a flat `html{color-scheme:dark}` permanently beat Mantine's own
+ * `@layer mantine{:root{color-scheme:var(--mantine-color-scheme)}}`: a light-scheme consumer got
+ * dark scrollbars, dark `<select>` popups and dark date pickers forever, with no opt-out (found
+ * independently by two consumers).
+ *
+ * `MantineProvider` writes `data-mantine-color-scheme` onto `<html>` as soon as it mounts, so
+ * scoping the boot rule to its ABSENCE makes it expire exactly when the real theme exists — which
+ * is the anti-FOUC contract stated honestly. A cascade layer would also work in principle and is
+ * deliberately NOT used: a layer's position is fixed by where its name is first encountered, and in
+ * dev Mantine's CSS is injected by JS after this `<style>` is already in the document, so the layer
+ * order would depend on bundler mode. Selector scoping depends on nothing.
+ */
+const BOOT_SCOPE = 'html:not([data-mantine-color-scheme])'
+
+/** The `color-scheme` value each boot mode declares. `false` declares none. */
+const BOOT_COLOR_SCHEME = { dark: 'dark', light: 'light', auto: 'light dark' } as const
+
+/**
+ * Builds the anti-FOUC stylesheet: paint the surface (and, unless opted out, tell the UA which
+ * native-control palette to use) for the frames between first paint and Mantine's stylesheet.
+ *
+ * `'auto'` with no explicit `backgroundColor` emits a `prefers-color-scheme` pair so the pre-boot
+ * paint follows the OS the same way `color-scheme: light dark` does; an explicit `backgroundColor`
+ * is used verbatim for both, since the consumer has named one color on purpose.
+ */
+function buildBootStyle(input: {
+  colorScheme: 'dark' | 'light' | 'auto' | false
+  themeColor: { light: string; dark: string }
+  backgroundColor: string
+  explicitBackground: boolean
+}): string {
+  const { colorScheme, themeColor, backgroundColor, explicitBackground } = input
+
+  if (colorScheme === false) return `${BOOT_SCOPE}{background-color:${backgroundColor}}`
+
+  const scheme = BOOT_COLOR_SCHEME[colorScheme]
+  if (colorScheme !== 'auto' || explicitBackground) {
+    return `${BOOT_SCOPE}{background-color:${backgroundColor};color-scheme:${scheme}}`
+  }
+  return (
+    `${BOOT_SCOPE}{background-color:${themeColor.light};color-scheme:${scheme}}` +
+    `@media(prefers-color-scheme:dark){${BOOT_SCOPE}{background-color:${themeColor.dark}}}`
+  )
+}
+
+// ── The encoding declaration ──────────────────────────────────────────────────────────────────
+
+/** `<meta charset="…">`, with the value in group 1/2/3 depending on the quoting style. */
+const CHARSET_META_RE =
+  /[ \t]*<meta\s+charset\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>=]+))\s*\/?>[ \t]*\r?\n?/i
+/** The legacy `<meta http-equiv="Content-Type" charset=…>` form — left verbatim, never rewritten. */
+const HTTP_EQUIV_CHARSET_RE = /<meta\s[^>]*http-equiv\s*=\s*["']?content-type["']?[^>]*>/i
+const DEFAULT_CHARSET = 'UTF-8'
+
+/**
+ * Hoists the shell's encoding declaration ahead of everything this plugin injects.
+ *
+ * Every tag here defaults to `injectTo: 'head-prepend'`, which lands it immediately after `<head>`
+ * and therefore AHEAD of the consumer's own `<meta charset>`. On a realistic shell that pushed the
+ * declaration to byte 1653 — past the 1024-byte window the HTML spec gives it — and there is no
+ * consumer-side fix, because the plugin owns the injection point. So the plugin owns the hoist too:
+ * the consumer's tag is removed from the html and re-emitted as this plugin's FIRST head-prepend
+ * tag. A shell that declares no encoding at all gets `UTF-8`.
+ *
+ * The legacy `http-equiv` form is detected and left completely alone — rewriting a consumer's
+ * markup into a different (if equivalent) tag is not this plugin's business.
+ */
+function hoistCharset(html: string): { html: string; tag: HtmlTagDescriptor | undefined } {
+  if (HTTP_EQUIV_CHARSET_RE.test(html)) return { html, tag: undefined }
+
+  const match = CHARSET_META_RE.exec(html)
+  const charset = match?.[1] ?? match?.[2] ?? match?.[3] ?? DEFAULT_CHARSET
+  return {
+    html: match ? html.replace(CHARSET_META_RE, '') : html,
+    tag: { tag: 'meta', attrs: { charset } },
+  }
+}
+
 function buildSeoTags(input: {
   name: string
   description: string | undefined
@@ -374,7 +473,7 @@ function buildStaticTags(input: {
   options: BasaltAppOptions
   shortName: string
   themeColor: { light: string; dark: string }
-  backgroundColor: string
+  bootStyle: string
   iconsEnabled: boolean
   iconsDir: string | undefined
   darkreader: 'lock' | false
@@ -386,7 +485,7 @@ function buildStaticTags(input: {
     options,
     shortName,
     themeColor,
-    backgroundColor,
+    bootStyle,
     iconsEnabled,
     iconsDir,
     darkreader,
@@ -416,13 +515,11 @@ function buildStaticTags(input: {
     },
   )
 
-  // Anti-FOUC — BasaltProvider defaults to dark, so this paints the dark surface before any
-  // stylesheet loads. injectTo defaults to 'head-prepend', so this (and every tag below) lands
-  // immediately after <head>, ahead of the consumer's own <link rel="stylesheet"> tags.
-  tags.push({
-    tag: 'style',
-    children: `html{background-color:${backgroundColor};color-scheme:dark}`,
-  })
+  // Anti-FOUC — paints the boot surface before any stylesheet loads. injectTo defaults to
+  // 'head-prepend', so this (and every tag below) lands immediately after <head> and the hoisted
+  // <meta charset>, ahead of the consumer's own <link rel="stylesheet"> tags. Scoped to
+  // BOOT_SCOPE so it expires the moment Mantine resolves the real scheme — see buildBootStyle.
+  tags.push({ tag: 'style', children: bootStyle })
 
   if (iconsEnabled) {
     tags.push(
@@ -489,7 +586,7 @@ function buildManifestJson(input: {
   scope: string
   id: string
   display: NonNullable<BasaltAppOptions['display']>
-  themeColor: { light: string; dark: string }
+  schemeColor: string
   backgroundColor: string
   iconsDir: string | undefined
   base: string
@@ -501,7 +598,7 @@ function buildManifestJson(input: {
     scope,
     id,
     display,
-    themeColor,
+    schemeColor,
     backgroundColor,
     iconsDir,
     base,
@@ -514,7 +611,9 @@ function buildManifestJson(input: {
     start_url: startUrl,
     scope,
     display,
-    theme_color: themeColor.dark,
+    // A manifest carries ONE theme color, so it follows the boot scheme rather than the dual
+    // `<meta name="theme-color">` pair. Unchanged for the default (`'dark'`) and for `'auto'`.
+    theme_color: schemeColor,
     background_color: backgroundColor,
     icons: [
       {
@@ -542,7 +641,17 @@ function createMainPlugin(options: BasaltAppOptions): Plugin {
   const manifestEnabled = options.manifest !== false
 
   const themeColor = resolveThemeColors(options.themeColor)
-  const backgroundColor = options.backgroundColor ?? themeColor.dark
+  // The boot scheme picks which half of the pair is "the" single color (manifest theme_color, the
+  // default paint). `'auto'` and `false` keep the historical dark default.
+  const colorScheme = options.colorScheme ?? 'dark'
+  const schemeColor = colorScheme === 'light' ? themeColor.light : themeColor.dark
+  const backgroundColor = options.backgroundColor ?? schemeColor
+  const bootStyle = buildBootStyle({
+    colorScheme,
+    themeColor,
+    backgroundColor,
+    explicitBackground: options.backgroundColor !== undefined,
+  })
 
   // Icon hrefs, the manifest link, and the manifest's start_url/scope/icon src all depend on
   // Vite's resolved `base`, which is only known once `configResolved` fires — so manifestJson and
@@ -569,7 +678,7 @@ function createMainPlugin(options: BasaltAppOptions): Plugin {
         scope,
         id,
         display,
-        themeColor,
+        schemeColor,
         backgroundColor,
         iconsDir,
         base,
@@ -579,7 +688,7 @@ function createMainPlugin(options: BasaltAppOptions): Plugin {
         options,
         shortName,
         themeColor,
-        backgroundColor,
+        bootStyle,
         iconsEnabled,
         iconsDir,
         darkreader,
@@ -588,9 +697,20 @@ function createMainPlugin(options: BasaltAppOptions): Plugin {
         manifestHref,
       })
     },
-    transformIndexHtml(html) {
-      const tags = hasViewportMeta(html) ? staticTags : [VIEWPORT_TAG, ...staticTags]
-      return { html, tags }
+    transformIndexHtml: {
+      // `pre` so this plugin's tags are the FIRST head-prepend contributions Vite collects — that
+      // ordering is what puts the hoisted <meta charset> at the very top of <head> rather than
+      // behind another plugin's tags. Vite injects all collected tags after every hook has run.
+      order: 'pre',
+      handler(html) {
+        const hoisted = hoistCharset(html)
+        const tags = [
+          ...(hoisted.tag ? [hoisted.tag] : []),
+          ...(hasViewportMeta(html) ? [] : [VIEWPORT_TAG]),
+          ...staticTags,
+        ]
+        return { html: hoisted.html, tags }
+      },
     },
     generateBundle() {
       if (!manifestEnabled) return
@@ -666,13 +786,21 @@ function createServiceWorkerPlugin(
  * manifest `theme_color` both need a FLAT color, so the flattening step is the contract this
  * plugin owes its output regardless of which shape the palette hands it.
  *
+ * Two behaviours worth knowing before adopting it, both of which the plugin owns because the
+ * consumer cannot reach them:
+ *  • It HOISTS the shell's `<meta charset>` ahead of everything it injects, so the encoding
+ *    declaration stays inside the spec's first 1024 bytes (see `hoistCharset`).
+ *  • The anti-FOUC `<style>` expires the moment Mantine resolves the real scheme, and `colorScheme`
+ *    selects which surface it paints until then (see `BOOT_SCOPE` / `buildBootStyle`).
+ *
  * @example
  * // vite.config.ts
  * import { basaltAppPlugin, basaltViteConfig } from 'basalt-ui/vite'
  *
  * export default {
  *   ...basaltViteConfig({ port: 5173 }),
- *   plugins: [react(), ...basaltAppPlugin({ name: 'Argo' })],
+ *   // colorScheme mirrors <BasaltProvider defaultColorScheme> — omit it for the dark default.
+ *   plugins: [react(), ...basaltAppPlugin({ name: 'Argo', colorScheme: 'auto' })],
  * }
  */
 export function basaltAppPlugin(options: BasaltAppOptions): PluginOption[] {