basalt-ui 1.21.0 → 1.23.0

package/src/vite.test.ts

@@ -201,6 +201,118 @@ describe('basaltAppPlugin — base handling', () => {
       false,
     )
   })
+
+  // The head half of `icons: false` shipped; the manifest half did not. `{ manifest: true, icons:
+  // false }` emitted a site.webmanifest naming two PNGs the app never ships — an installable app
+  // with two 404s, which is why rb went hybrid rather than use the plugin's manifest at all.
+  test('icons: false reaches the MANIFEST, not just the head links', () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR, icons: false })
+    const middleware = getDevMiddleware(plugin, '/myapp/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/myapp/site.webmanifest') ?? '{}')
+
+    expect(manifest.icons).toBeUndefined()
+    expect(JSON.stringify(manifest)).not.toContain('.png')
+    // …and the rest of the manifest is unaffected.
+    expect(manifest.start_url).toBe('/myapp/')
+    expect(manifest.name).toBe('Test App')
+  })
+
+  test('the default (icons on) still carries both manifest icon entries', () => {
+    const plugin = getPlugin({ name: 'Test App', themeColor: THEME_COLOR })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons).toHaveLength(2)
+  })
+
+  test('icons.dir still redirects the manifest icon srcs', () => {
+    const plugin = getPlugin({
+      name: 'Test App',
+      themeColor: THEME_COLOR,
+      icons: { dir: '/brand' },
+    })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons[0].src).toBe('/brand/web-app-manifest-192x192.png')
+  })
+
+  // ── the consumer-named array form ─────────────────────────────────────────
+  //
+  // `{ dir }` can move basalt's six filenames but not rename one, so an app whose only icon is
+  // `favicon.svg` could pick between a manifest naming two PNGs it does not ship and a manifest
+  // with no icons at all. Both are wrong for an installable app, and the second is why rb still
+  // kept a hand-written manifest one release after `icons: false` was fixed.
+
+  // rb's REAL icon set, copied from apps/web/public/manifest.webmanifest — the manifest this
+  // option exists to let the plugin generate.
+  const RB_ICONS = [
+    { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+  ] as const
+
+  test("generates rb's hand-written manifest icons member verbatim", () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: RB_ICONS })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+
+    expect(manifest.icons).toEqual([
+      { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' },
+    ])
+    expect(JSON.stringify(manifest)).not.toContain('.png')
+    expect(manifest.name).toBe('rb')
+    expect(manifest.display).toBe('standalone')
+  })
+
+  test('a named icon reaches the head only when it asks for a rel', () => {
+    const iconLinks = (icons: NonNullable<BasaltAppOptions['icons']>): HtmlTagDescriptor[] => {
+      const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons })
+      resolveConfig(plugin, '/')
+      return transformHtml(plugin, HTML_NO_VIEWPORT).filter(
+        (tag) => tag.tag === 'link' && String(tag.attrs?.['rel']).includes('icon'),
+      )
+    }
+
+    // rb's index.html already links favicon.svg — the manifest gets fixed, the head is left alone.
+    expect(iconLinks(RB_ICONS)).toHaveLength(0)
+
+    const withRel = iconLinks([{ src: 'favicon.svg', type: 'image/svg+xml', rel: 'icon' }])
+    expect(withRel).toHaveLength(1)
+    expect(withRel[0]?.attrs).toEqual({
+      rel: 'icon',
+      type: 'image/svg+xml',
+      href: '/favicon.svg',
+    })
+  })
+
+  test('a named icon src is base-prefixed, with or without its leading slash', () => {
+    const plugin = getPlugin({
+      name: 'rb',
+      themeColor: THEME_COLOR,
+      icons: [
+        { src: 'favicon.svg', sizes: 'any' },
+        { src: '/icon-512.png', sizes: '512x512' },
+      ],
+    })
+    const middleware = getDevMiddleware(plugin, '/myapp/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/myapp/site.webmanifest') ?? '{}')
+
+    expect(manifest.icons.map((icon: { src: string }) => icon.src)).toEqual([
+      '/myapp/favicon.svg',
+      '/myapp/icon-512.png',
+    ])
+  })
+
+  test('an empty array reads as icons: false — no member, not an empty one', () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: [] })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons).toBeUndefined()
+  })
+
+  test('the array form omits keys the consumer did not write', () => {
+    const plugin = getPlugin({ name: 'rb', themeColor: THEME_COLOR, icons: [{ src: '/a.svg' }] })
+    const middleware = getDevMiddleware(plugin, '/')
+    const manifest = JSON.parse(runMiddleware(middleware, '/site.webmanifest') ?? '{}')
+    expect(manifest.icons).toEqual([{ src: '/a.svg' }])
+  })
 })
 
 describe('basaltAppPlugin — the anti-FOUC boot rule (V1)', () => {

package/src/vite.ts

@@ -198,6 +198,30 @@ const ICON_FILES = {
   manifest512: 'web-app-manifest-512x512.png',
 } as const
 
+/**
+ * One icon a consumer names itself — a manifest `icons` member, plus optionally the head `<link>`
+ * that points at the same file.
+ *
+ * The field names are the manifest's own, verbatim, so what a consumer writes here is what ships in
+ * `site.webmanifest`. `src` is root-relative (`'/favicon.svg'` or `'favicon.svg'`, both resolve the
+ * same) and is prefixed with Vite's `base` exactly like basalt's built-in set.
+ */
+export type BasaltAppIcon = {
+  /** Root-relative path under `public/`. Prefixed with Vite's resolved `base`. */
+  src: string
+  /** Manifest `sizes`. `'any'` for a scalable SVG; `'192x192'` for a raster. */
+  sizes?: string
+  /** MIME type, e.g. `'image/svg+xml'`. */
+  type?: string
+  /** Manifest `purpose`, e.g. `'any maskable'`. */
+  purpose?: string
+  /**
+   * Emit a head `<link rel="…">` for this icon too. Omitted → manifest only, which is what an app
+   * that links its own favicon from `index.html` wants.
+   */
+  rel?: 'icon' | 'shortcut icon' | 'apple-touch-icon' | 'mask-icon'
+}
+
 export type BasaltAppOptions = {
   /** App display name — used verbatim as the manifest `name` and (unless overridden) OG title. */
   name: string
@@ -242,8 +266,27 @@ export type BasaltAppOptions = {
   scope?: string
   /** Manifest `id`. Default: the resolved `startUrl` (default- or explicitly-derived, per above). */
   id?: string
-  /** Icon links + manifest icon paths. `false` skips the head `<link>` icons entirely. */
-  icons?: false | { dir?: string }
+  /**
+   * Which icons the plugin knows about — three forms, one question each.
+   *
+   * - **omitted / `{ dir }`** — basalt's own six-filename set (the realfavicongenerator layout argo
+   *   ships), optionally under a subdirectory of `public/`. Unchanged default.
+   * - **`false`** — no head `<link>` icons and no manifest `icons` member, so a manifest is never
+   *   emitted pointing at files that 404.
+   * - **an array** — the icons this app ACTUALLY has, named by the consumer.
+   *
+   * The array is the form for every app that was not scaffolded from basalt's icon set, which is
+   * most of them. `{ dir }` can only move the six fixed filenames; it cannot rename one, so an app
+   * whose single icon is `favicon.svg` had no way to say so and had to keep a hand-written manifest
+   * beside the generated head — the last thing standing between rb and deleting a file carrying a
+   * permanent `theme-allow-file`. One SVG at `sizes: 'any'` is a complete, installable icon set.
+   *
+   * Every entry becomes a manifest icon; an entry becomes a head `<link>` only when it names a
+   * {@link BasaltAppIcon.rel}. That split is deliberate — an app that already links its favicon
+   * from its own `index.html` wants the manifest fixed without a duplicate tag, and an app that
+   * wants the plugin to own the head says so per icon. An empty array reads as `false`.
+   */
+  icons?: false | { dir?: string } | readonly BasaltAppIcon[]
   /** Emits `<meta name="darkreader-lock">` when `'lock'` (default). Pass `false` to omit it. */
   darkreader?: 'lock' | false
   /** Site-wide SEO metadata — only the keys provided are emitted, no per-page SEO. */
@@ -324,6 +367,39 @@ function withBase(base: string, path: string): string {
   return base + path.slice(1)
 }
 
+/**
+ * The three `icons` forms, collapsed to what the two emitters actually need.
+ *
+ * `'none'` and `'default'` are the pre-existing behaviour verbatim — `'default'` still walks
+ * {@link ICON_FILES}, so an app on basalt's own icon layout emits byte-identical head tags and a
+ * byte-identical manifest. `'explicit'` is the new form. An EMPTY array collapses to `'none'`
+ * rather than to an empty `icons: []` member: a manifest declaring zero icons is a claim, and the
+ * honest way to say "this app has no icons" already exists.
+ */
+type ResolvedIcons =
+  | { mode: 'none' }
+  | { mode: 'default'; dir: string | undefined }
+  | { mode: 'explicit'; icons: readonly BasaltAppIcon[] }
+
+/** `Array.isArray` widens to `any[]` and does not narrow a `readonly T[]` OUT of a union. */
+function isIconList(
+  icons: { dir?: string } | readonly BasaltAppIcon[],
+): icons is readonly BasaltAppIcon[] {
+  return Array.isArray(icons)
+}
+
+function resolveIcons(icons: BasaltAppOptions['icons']): ResolvedIcons {
+  if (icons === false) return { mode: 'none' }
+  if (icons === undefined) return { mode: 'default', dir: undefined }
+  if (!isIconList(icons)) return { mode: 'default', dir: icons.dir }
+  return icons.length === 0 ? { mode: 'none' } : { mode: 'explicit', icons }
+}
+
+/** Root-relative `src` (with or without its leading slash) → base-prefixed href. */
+function iconHref(base: string, src: string): string {
+  return withBase(base, src.startsWith('/') ? src : `/${src}`)
+}
+
 function hasViewportMeta(html: string): boolean {
   return /<meta\s+[^>]*name=["']viewport["']/i.test(html)
 }
@@ -474,8 +550,7 @@ function buildStaticTags(input: {
   shortName: string
   themeColor: { light: string; dark: string }
   bootStyle: string
-  iconsEnabled: boolean
-  iconsDir: string | undefined
+  icons: ResolvedIcons
   darkreader: 'lock' | false
   manifestEnabled: boolean
   base: string
@@ -486,8 +561,7 @@ function buildStaticTags(input: {
     shortName,
     themeColor,
     bootStyle,
-    iconsEnabled,
-    iconsDir,
+    icons,
     darkreader,
     manifestEnabled,
     base,
@@ -521,13 +595,13 @@ function buildStaticTags(input: {
   // BOOT_SCOPE so it expires the moment Mantine resolves the real scheme — see buildBootStyle.
   tags.push({ tag: 'style', children: bootStyle })
 
-  if (iconsEnabled) {
+  if (icons.mode === 'default') {
     tags.push(
       {
         tag: 'link',
         attrs: {
           rel: 'shortcut icon',
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.favicon)),
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.favicon)),
         },
       },
       {
@@ -535,7 +609,7 @@ function buildStaticTags(input: {
         attrs: {
           rel: 'icon',
           type: 'image/svg+xml',
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.svg)),
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.svg)),
         },
       },
       {
@@ -543,7 +617,7 @@ function buildStaticTags(input: {
         attrs: {
           rel: 'icon',
           sizes: '96x96',
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.png96)),
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.png96)),
         },
       },
       {
@@ -551,12 +625,29 @@ function buildStaticTags(input: {
         attrs: {
           rel: 'apple-touch-icon',
           sizes: '180x180',
-          href: withBase(base, withIconPath(iconsDir, ICON_FILES.appleTouch)),
+          href: withBase(base, withIconPath(icons.dir, ICON_FILES.appleTouch)),
         },
       },
     )
   }
 
+  // A consumer-named icon reaches the head only when it asks to, so the plugin can fix a manifest
+  // without duplicating a `<link>` the app's own index.html already writes.
+  if (icons.mode === 'explicit') {
+    for (const icon of icons.icons) {
+      if (icon.rel === undefined) continue
+      tags.push({
+        tag: 'link',
+        attrs: {
+          rel: icon.rel,
+          ...(icon.type === undefined ? {} : { type: icon.type }),
+          ...(icon.sizes === undefined ? {} : { sizes: icon.sizes }),
+          href: iconHref(base, icon.src),
+        },
+      })
+    }
+  }
+
   tags.push(
     { tag: 'meta', attrs: { name: 'apple-mobile-web-app-title', content: shortName } },
     { tag: 'meta', attrs: { name: 'apple-mobile-web-app-capable', content: 'yes' } },
@@ -579,6 +670,39 @@ function buildStaticTags(input: {
   return tags
 }
 
+/** The manifest's `icons` member, or nothing at all — never an empty array. */
+function manifestIcons(
+  icons: ResolvedIcons,
+  base: string,
+): { icons?: ReadonlyArray<Record<string, string>> } {
+  if (icons.mode === 'none') return {}
+  if (icons.mode === 'default') {
+    return {
+      icons: [
+        {
+          src: withBase(base, withIconPath(icons.dir, ICON_FILES.manifest192)),
+          sizes: '192x192',
+          type: 'image/png',
+        },
+        {
+          src: withBase(base, withIconPath(icons.dir, ICON_FILES.manifest512)),
+          sizes: '512x512',
+          type: 'image/png',
+          purpose: 'any maskable',
+        },
+      ],
+    }
+  }
+  return {
+    icons: icons.icons.map((icon) => ({
+      src: iconHref(base, icon.src),
+      ...(icon.sizes === undefined ? {} : { sizes: icon.sizes }),
+      ...(icon.type === undefined ? {} : { type: icon.type }),
+      ...(icon.purpose === undefined ? {} : { purpose: icon.purpose }),
+    })),
+  }
+}
+
 function buildManifestJson(input: {
   options: BasaltAppOptions
   shortName: string
@@ -588,7 +712,7 @@ function buildManifestJson(input: {
   display: NonNullable<BasaltAppOptions['display']>
   schemeColor: string
   backgroundColor: string
-  iconsDir: string | undefined
+  icons: ResolvedIcons
   base: string
 }): string {
   const {
@@ -600,7 +724,7 @@ function buildManifestJson(input: {
     display,
     schemeColor,
     backgroundColor,
-    iconsDir,
+    icons,
     base,
   } = input
   const manifest = {
@@ -615,19 +739,13 @@ function buildManifestJson(input: {
     // `<meta name="theme-color">` pair. Unchanged for the default (`'dark'`) and for `'auto'`.
     theme_color: schemeColor,
     background_color: backgroundColor,
-    icons: [
-      {
-        src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest192)),
-        sizes: '192x192',
-        type: 'image/png',
-      },
-      {
-        src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest512)),
-        sizes: '512x512',
-        type: 'image/png',
-        purpose: 'any maskable',
-      },
-    ],
+    // `icons: false` reaches HERE too, not just the head links. The array was unconditional, so
+    // `{ manifest: true, icons: false }` shipped a manifest pointing at two PNGs the app never
+    // ships — an installable app with broken icons, and the reason rb went hybrid (plugin for the
+    // head, a hand-written manifest for the rest). A manifest with NO icons member is valid.
+    // The `'explicit'` arm is the other half of that fix: honest about icons it cannot see was
+    // only worth having once a consumer could tell it which icons it DOES have.
+    ...manifestIcons(icons, base),
   }
   return JSON.stringify(manifest, null, 2)
 }
@@ -636,8 +754,7 @@ function createMainPlugin(options: BasaltAppOptions): Plugin {
   const shortName = options.shortName ?? options.name
   const display = options.display ?? 'standalone'
   const darkreader = options.darkreader ?? 'lock'
-  const iconsEnabled = options.icons !== false
-  const iconsDir = options.icons === false ? undefined : options.icons?.dir
+  const icons = resolveIcons(options.icons)
   const manifestEnabled = options.manifest !== false
 
   const themeColor = resolveThemeColors(options.themeColor)
@@ -680,7 +797,7 @@ function createMainPlugin(options: BasaltAppOptions): Plugin {
         display,
         schemeColor,
         backgroundColor,
-        iconsDir,
+        icons,
         base,
       })
 
@@ -689,8 +806,7 @@ function createMainPlugin(options: BasaltAppOptions): Plugin {
         shortName,
         themeColor,
         bootStyle,
-        iconsEnabled,
-        iconsDir,
+        icons,
         darkreader,
         manifestEnabled,
         base,