@gusnips/vite 0.8.32 → 0.8.34

package/src/icons.test.ts

@@ -0,0 +1,135 @@
+import { mkdtemp, readFile, readdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { webManifest, writeIconSet } from "./icons.ts";
+
+/**
+ * The callbacks are the product's (resvg, sharp, an ICO packer), so the tests stub them with
+ * deterministic bytes and assert the driving: each size rendered once, files named and placed,
+ * the ICO packed from the right renders in order.
+ */
+const SVG = `<svg xmlns="http://www.w3.org/2000/svg"><rect width="100" height="100"/></svg>`;
+const render = (svg: string, size: number): Uint8Array =>
+  new TextEncoder().encode(`${svg.length}:${size}`);
+const packIco = (pngs: readonly Uint8Array[]): Uint8Array =>
+  new TextEncoder().encode(`ico[${pngs.map((png) => new TextDecoder().decode(png)).join(",")}]`);
+
+async function dir(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "frontkit-icons-"));
+}
+
+describe("writeIconSet", () => {
+  it("writes one PNG per size, the touch icon, and a packed favicon.ico", async () => {
+    const outDir = await dir();
+    const files = await writeIconSet({
+      outDir,
+      svg: SVG,
+      pngSizes: [192, 512],
+      icoSizes: [16, 32],
+      render,
+      packIco,
+    });
+    expect(files).toEqual(["icon-192.png", "icon-512.png", "apple-touch-icon.png", "favicon.ico"]);
+    expect(await readdir(outDir)).toEqual([...files].sort());
+    expect(await readFile(join(outDir, "icon-192.png"), "utf8")).toBe(`${SVG.length}:192`);
+    expect(await readFile(join(outDir, "apple-touch-icon.png"), "utf8")).toBe(`${SVG.length}:180`);
+    expect(await readFile(join(outDir, "favicon.ico"), "utf8")).toBe(
+      `ico[${SVG.length}:16,${SVG.length}:32]`,
+    );
+  });
+
+  // The touch icon at a size the set already renders costs no extra raster: same bytes, one
+  // render. A renderer that bills per call makes the difference visible.
+  it("renders each size once even when the touch icon shares it", async () => {
+    const seen: number[] = [];
+    await writeIconSet({
+      outDir: await dir(),
+      svg: SVG,
+      pngSizes: [180, 512],
+      icoSizes: [180],
+      render: (svg, size) => {
+        seen.push(size);
+        return render(svg, size);
+      },
+      packIco,
+    });
+    expect(seen).toEqual([180, 512]);
+  });
+
+  // A renderer that throws leaves no half-written set behind: every size renders first.
+  it("writes nothing when a render fails, and reports without writing on check", async () => {
+    const failing = async (_svg: string, size: number): Promise<Uint8Array> => {
+      if (size === 512) throw new Error("rasterizer down");
+      return render(_svg, size);
+    };
+    const outDir = await dir();
+    await expect(
+      writeIconSet({
+        outDir,
+        svg: SVG,
+        pngSizes: [192, 512],
+        icoSizes: [16],
+        render: failing,
+        packIco,
+      }),
+    ).rejects.toThrow("rasterizer down");
+    expect(await readdir(outDir)).toEqual([]);
+
+    const checkDir = await dir();
+    const files = await writeIconSet({
+      outDir: checkDir,
+      svg: SVG,
+      pngSizes: [192],
+      icoSizes: [16],
+      check: true,
+      render,
+      packIco,
+    });
+    expect(files).toEqual(["icon-192.png", "apple-touch-icon.png", "favicon.ico"]);
+    expect(await readdir(checkDir)).toEqual([]);
+  });
+});
+
+describe("webManifest", () => {
+  it("writes keys in install order with the travelled defaults", () => {
+    expect(
+      webManifest({
+        name: "Acme",
+        icons: [{ src: "/icon-192.png", sizes: "192x192", type: "image/png" }],
+      }),
+    ).toBe(
+      `{\n  "name": "Acme",\n  "start_url": ".",\n  "display": "standalone",\n` +
+        `  "icons": [\n    {\n      "src": "/icon-192.png",\n      "sizes": "192x192",\n` +
+        `      "type": "image/png"\n    }\n  ]\n}\n`,
+    );
+  });
+
+  it("keeps the optional fields and a maskable purpose", () => {
+    const txt = webManifest({
+      name: "Acme",
+      shortName: "Acme",
+      description: "Do things.",
+      scope: "/app/",
+      backgroundColor: "#ffffff",
+      themeColor: "#7c3aed",
+      icons: [{ src: "/icon-512.png", sizes: "512x512", type: "image/png", purpose: "maskable" }],
+    });
+    const parsed = JSON.parse(txt) as Record<string, unknown>;
+    expect(parsed["short_name"]).toBe("Acme");
+    expect(parsed["scope"]).toBe("/app/");
+    expect(parsed["background_color"]).toBe("#ffffff");
+    expect(parsed["theme_color"]).toBe("#7c3aed");
+    expect(parsed["icons"]).toEqual([
+      { src: "/icon-512.png", sizes: "512x512", type: "image/png", purpose: "maskable" },
+    ]);
+  });
+
+  // A manifest with no name installs as nothing, and one with no icons fails installability
+  // with no error anywhere. Both fail here instead.
+  it("refuses an empty name and an empty icon list", () => {
+    const icon = { src: "/icon-192.png", sizes: "192x192", type: "image/png" };
+    expect(() => webManifest({ name: "  ", icons: [icon] })).toThrow(/name/);
+    expect(() => webManifest({ name: "Acme", icons: [] })).toThrow(/icons/);
+  });
+});

package/src/icons.ts

@@ -0,0 +1,140 @@
+/**
+ * PWA icons and the manifest that names them, driven the way `writeOgCards` is.
+ *
+ * The artwork is the product's — one SVG master — and so are the two operations this package
+ * cannot do without dragging image tooling into every adopter: rasterizing (resvg, sharp,
+ * satori, …) and ICO packing. Both arrive as callbacks, so this file stays dependency-free and
+ * a repo that only wants a sitemap installs neither. What ships is the part every copy got
+ * subtly wrong: which sizes exist, what they are named, and the manifest agreeing with the
+ * files on disk.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** One SVG master at one pixel size. The renderer is the caller's; this only drives it. */
+export type RenderIcon = (svg: string, size: number) => Uint8Array | Promise<Uint8Array>;
+
+/** Several same-size PNGs into one multi-image `favicon.ico`. */
+export type PackIco = (pngs: readonly Uint8Array[]) => Uint8Array | Promise<Uint8Array>;
+
+export interface WriteIconSetOptions {
+  /** Where the files land — `public/` in every donor, so they are served as static files. */
+  outDir: string;
+  /** The one master artwork. A single path with no variants is what keeps every size in step. */
+  svg: string;
+  /** PNG sizes to write, e.g. `[180, 192, 512]`. Each is rendered once even when named twice. */
+  pngSizes: readonly number[];
+  /** The file name for one PNG size. Default `` `icon-${size}.png` ``. */
+  file?: (size: number) => string;
+  /**
+   * The size written as `apple-touch-icon.png`. Default 180 — what the reader's home screen
+   * asks for. Reuses the PNG render when it is already in `pngSizes`, so the common case costs
+   * no extra raster.
+   */
+  appleTouchSize?: number;
+  /** Sizes re-rendered and packed into `favicon.ico`, e.g. `[16, 32, 48]`. */
+  icoSizes: readonly number[];
+  /** Lay every icon out and report, without writing anything. */
+  check?: boolean;
+  render: RenderIcon;
+  packIco: PackIco;
+}
+
+/**
+ * Render one icon set and write it, plus the multi-size `favicon.ico`.
+ *
+ * Every size is rendered BEFORE anything is written, so a renderer that throws leaves no
+ * half-written set behind — the same order `writeOgCards` keeps for the same reason.
+ */
+export async function writeIconSet({
+  outDir,
+  svg,
+  pngSizes,
+  file = (size) => `icon-${size}.png`,
+  appleTouchSize = 180,
+  icoSizes,
+  check = false,
+  render,
+  packIco,
+}: WriteIconSetOptions): Promise<string[]> {
+  const sizes = [...new Set([...pngSizes, appleTouchSize, ...icoSizes])].sort((a, b) => a - b);
+  const rendered = new Map<number, Uint8Array>();
+  for (const size of sizes) rendered.set(size, await render(svg, size));
+
+  const written: Array<{ file: string; png: Uint8Array }> = [];
+  for (const size of pngSizes)
+    written.push({ file: file(size), png: rendered.get(size) ?? new Uint8Array() });
+  written.push({
+    file: "apple-touch-icon.png",
+    png: rendered.get(appleTouchSize) ?? new Uint8Array(),
+  });
+  written.push({
+    file: "favicon.ico",
+    png: await packIco(icoSizes.map((size) => rendered.get(size) ?? new Uint8Array())),
+  });
+
+  if (check) return written.map((entry) => entry.file);
+
+  await mkdir(outDir, { recursive: true });
+  for (const entry of written) await writeFile(join(outDir, entry.file), entry.png);
+  return written.map((entry) => entry.file);
+}
+
+/** One icon as the manifest names it. `src` is the path `writeIconSet` wrote, from the root. */
+export interface ManifestIcon {
+  src: string;
+  /** `"192x192"`, `"48x48"`, or several space-separated when one file serves several. */
+  sizes: string;
+  type: string;
+  purpose?: string;
+}
+
+export interface WebManifestOptions {
+  name: string;
+  shortName?: string;
+  description?: string;
+  /** Default `"."`: the manifest travels with the app, so a relative start stays correct. */
+  startUrl?: string;
+  scope?: string;
+  /** Default `"standalone"`: a PWA that opens in a tab is a bookmark, not an app. */
+  display?: string;
+  backgroundColor?: string;
+  themeColor?: string;
+  /** At least one — a manifest with no icons fails installability with no error anywhere. */
+  icons: readonly ManifestIcon[];
+}
+
+/**
+ * `site.webmanifest`, as text with a trailing newline. Keys in install order, so two runs over
+ * the same options write the same bytes.
+ */
+export function webManifest({
+  name,
+  shortName,
+  description,
+  startUrl = ".",
+  scope,
+  display = "standalone",
+  backgroundColor,
+  themeColor,
+  icons,
+}: WebManifestOptions): string {
+  if (name.trim() === "") throw new Error("manifest: `name` is empty");
+  if (icons.length === 0)
+    throw new Error("manifest: `icons` is empty — name what writeIconSet wrote");
+  const manifest: Record<string, unknown> = { name };
+  if (shortName !== undefined) manifest["short_name"] = shortName;
+  if (description !== undefined) manifest["description"] = description;
+  manifest["start_url"] = startUrl;
+  if (scope !== undefined) manifest["scope"] = scope;
+  manifest["display"] = display;
+  if (backgroundColor !== undefined) manifest["background_color"] = backgroundColor;
+  if (themeColor !== undefined) manifest["theme_color"] = themeColor;
+  manifest["icons"] = icons.map((icon) => ({
+    src: icon.src,
+    sizes: icon.sizes,
+    type: icon.type,
+    ...(icon.purpose !== undefined && { purpose: icon.purpose }),
+  }));
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/src/index.ts

@@ -9,12 +9,13 @@
  * Four repos wrote it independently and each learned something the others had not. What is
  * here is the merge; every non-obvious rule carries the reason it exists.
  *
- * Three things live behind their own subpath, because each drags a dependency this barrel would
+ * Five things live behind their own subpath, because each drags a dependency this barrel would
  * otherwise force on everyone: the vite config preset at `@gusnips/vite/preset` (the React and
- * Tailwind plugins), `renderTree` at `@gusnips/vite/render`, and the theme pre-paint plugin at
- * `@gusnips/vite/theme` (both React itself). Nothing here
- * imports React or vite, so a prerender script, an OG generator and a repo that only wants a
- * sitemap all install exactly what they use.
+ * Tailwind plugins), `renderTree` at `@gusnips/vite/render`, the theme pre-paint plugin at
+ * `@gusnips/vite/theme` (both React itself), the catalog check at `@gusnips/vite/i18n`, and the
+ * contrast gate at `@gusnips/vite/contrast` (tailwindcss) — the last two run in CI and never in
+ * a build. Nothing here imports React, vite or tailwindcss, so a prerender script, an OG
+ * generator and a repo that only wants a sitemap all install exactly what they use.
  */
 export { resolveKey } from "./catalog.ts";
 // `headExtra` takes raw markup, so the moment an adopter builds a tag out of its own copy it
@@ -26,8 +27,10 @@ export {
   assertRendered,
   bakeHead,
   EMPTY_ROOT,
+  faqJsonLd,
   ogLocale,
   type Alternate,
+  type FaqEntry,
   type HeadTags,
   type RenderedChecks,
 } from "./head.ts";
@@ -40,6 +43,15 @@ export {
   type OgCard,
   type WriteOgCardsOptions,
 } from "./node.ts";
+export {
+  webManifest,
+  writeIconSet,
+  type ManifestIcon,
+  type PackIco,
+  type RenderIcon,
+  type WebManifestOptions,
+  type WriteIconSetOptions,
+} from "./icons.ts";
 export {
   describeOverflow,
   fitText,
@@ -63,6 +75,7 @@ export {
   siteOrigin,
   sitemapFor,
   sitemapXml,
+  templateOrigin,
   type PublicPage,
   type RobotsOptions,
   type SitemapEntry,

package/src/sitemap.test.ts

@@ -7,6 +7,7 @@ import {
   siteOrigin,
   sitemapFor,
   sitemapXml,
+  templateOrigin,
 } from "./sitemap.ts";
 
 describe("pageFile", () => {
@@ -122,3 +123,26 @@ describe("robotsTxt", () => {
     expect(txt.startsWith("User-agent: *\nAllow: /\n")).toBe(true);
   });
 });
+
+describe("templateOrigin", () => {
+  // One file is the answer for the head Vite ships and for every file written after it: read
+  // the domain out of the template's own canonical instead of resolving a second source.
+  it("reads the origin out of the template's canonical", () => {
+    const template = `<html><head><link rel="canonical" href="https://acme.com/" /></head></html>`;
+    expect(templateOrigin(template)).toBe("https://acme.com");
+  });
+
+  it("reads the reversed attribute order too", () => {
+    const template = `<html><head><link href="https://acme.com/docs" rel="canonical" /></head></html>`;
+    expect(templateOrigin(template)).toBe("https://acme.com");
+  });
+
+  // Demanded, like the tag is in `bakeHead`: a template without one would hand every page
+  // somebody else's origin, quietly.
+  it("refuses a template with no canonical, and a relative one", () => {
+    expect(() => templateOrigin("<html><head></head></html>")).toThrow(/canonical/);
+    expect(() =>
+      templateOrigin(`<html><head><link rel="canonical" href="/pricing" /></head></html>`),
+    ).toThrow(/absolute origin/);
+  });
+});

package/src/sitemap.ts

@@ -54,6 +54,25 @@ export function siteOrigin(url: string): string {
   return url.replace(/\/+$/, "");
 }
 
+/**
+ * The origin the template already declares, read out of its canonical.
+ *
+ * One file is the answer for the head Vite ships and for every file written after it, so there
+ * is no second place for a domain to drift to — no env var the script has to resolve beside
+ * it. Demanded rather than defaulted, for the reason `bakeHead` demands the tag: a template
+ * without one would hand every page somebody else's origin, quietly.
+ */
+export function templateOrigin(template: string): string {
+  const href =
+    /<link[^>]*rel="canonical"[^>]*href="([^"]*)"/.exec(template)?.[1] ??
+    /<link[^>]*href="([^"]*)"[^>]*rel="canonical"/.exec(template)?.[1];
+  if (href === undefined)
+    throw new Error('prerender: <link rel="canonical"> not found in index.html');
+  // A canonical names a PAGE, not the origin — drop the path. `siteOrigin` first, for its
+  // scheme demand: `VITE_SITE_URL=acme.com` looks right in a `.env` and is a relative URL.
+  return new URL(siteOrigin(href)).origin;
+}
+
 /**
  * The three things about a public page that do not translate: where it is, how often it
  * changes, and how it ranks against its siblings.