@misoto22/folio 0.0.0 → 0.17.0

package/dist/lib/svg-export.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Taking an `<svg>` off the page as a file.
+ *
+ * Shared by two entries that both draw in SVG and both need to hand a reader a
+ * picture of it: `@misoto22/folio/charts` and `@misoto22/folio/diagrams`.
+ * Everything here is engine-agnostic — nothing knows what a series or a node
+ * is — so the parts that DO know (which `<svg>` inside a wrapper is the plot,
+ * what the file should be called, what sits behind it) stay with the caller.
+ *
+ * Nothing touches the DOM at module scope. Every browser API — `document`,
+ * `canvas`, `URL.createObjectURL` — is reached for inside a function body, so
+ * this module imports cleanly into a server component and only fails when a
+ * consumer actually asks for a file on a server, which is a call that cannot
+ * succeed anywhere.
+ */
+/**
+ * Copies the resolved paint of every node in `live` onto the matching node in
+ * `clone`.
+ *
+ * ## The problem this function exists to solve
+ *
+ * Serialising an `<svg>` and handing it to an `<img>` puts it in a document of
+ * its own. That document has none of the page's stylesheets, so every
+ * `var(--ink)`, `var(--rule-2)` and `var(--diagram-node)` in the markup
+ * resolves to nothing — and a paint that resolves to nothing is not a fallback
+ * colour, it is an invisible mark. Serialise naively and you get an empty
+ * rectangle.
+ *
+ * ## The solution
+ *
+ * Walk the live tree and the clone in step, and on every node write
+ * `getComputedStyle`'s answer into an inline `style`. Computed values have
+ * already had `var()` substituted by the engine, so `fill: var(--ink)` arrives
+ * as `fill: rgb(16, 16, 16)` — and, because the walk reads the LIVE element, it
+ * reads it under whichever theme is currently applied. Light and dark come out
+ * right for free, with no theme argument anywhere in this file.
+ *
+ * `<stop>` and `<marker>` children are walked too, which is the half that is
+ * easy to miss: a gradient's stops and an arrowhead's fill carry custom
+ * properties of their own, and a `<defs>` that lost its paint takes every line
+ * ending with it.
+ */
+declare function inlinePaint(live: Element, clone: Element): void;
+/**
+ * A custom property, resolved against the live element.
+ *
+ * `var()` inside a custom property is substituted at computed-value time, so
+ * `--diagram-surface: var(--paper)` reads back as a colour. The guard is for
+ * the case where it did not — an unregistered name, or a value the engine left
+ * as a token stream — because writing `var(--paper)` into a serialised SVG
+ * paints nothing at all.
+ */
+declare function readToken(element: Element, name: string, fallback: string): string;
+interface SerializeOptions {
+    /** Space around the artwork, in user units. Defaults to 16. */
+    padding?: number;
+    /** Painted behind the artwork. Omit for a transparent ground. */
+    background?: string;
+    /** A band above the artwork carrying this text. */
+    title?: string;
+    /** Paint for the title. Defaults to `#101010`. */
+    titleColor?: string;
+    /** Family for the title. Defaults to `sans-serif`. */
+    titleFont?: string;
+    /**
+     * Forces the output box, letterboxing the artwork inside it.
+     *
+     * This is what a share card is: a fixed 1200×630 frame that the diagram is
+     * fitted into, rather than a frame the diagram sizes. Omit it and the output
+     * is the artwork plus its padding.
+     */
+    frame?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * One standalone `<svg>` document: the element's own artwork, repainted with
+ * resolved colours, on an optional plate, under an optional title.
+ *
+ * Returns markup rather than a blob because the SVG export wants the string
+ * and every raster export wants it as a data source — one serialisation, four
+ * file formats.
+ *
+ * ## What this cannot capture, honestly
+ *
+ * - **Anything drawn in HTML.** A toolbar, a tooltip, an inspector panel are
+ *   DOM, not SVG. The file is the artwork.
+ * - **Web fonts.** The isolated document cannot fetch the page's `@font-face`
+ *   sources, so text is rasterised in whatever the resolved family stack finds
+ *   locally. Type metrics will differ from the screen.
+ * - **Cross-origin images.** An `<image>` from another origin taints the canvas
+ *   and `toBlob` throws; there is no way around it from script.
+ */
+declare function serializeSvg(svg: SVGSVGElement, options?: SerializeOptions): string;
+/** The raster formats a browser canvas can encode. */
+type RasterFormat = 'png' | 'jpeg' | 'webp';
+interface RasterOptions {
+    /** Multiplier on the on-screen size. 2 is a retina-sharp export. */
+    scale?: number;
+    /** Encoder quality for `jpeg` and `webp`, 0–1. Ignored by `png`. */
+    quality?: number;
+    /**
+     * Painted behind the image, for a format with no alpha channel.
+     *
+     * JPEG has no transparency, so a diagram serialised without a plate lands on
+     * black. Passing the page's own surface here is what makes the file look
+     * like the screen rather than like a negative.
+     */
+    background?: string;
+}
+/**
+ * SVG markup, rasterised through a canvas.
+ *
+ * This is the browser's own SVG rasteriser re-drawing the markup, not a
+ * screenshot: antialiasing, `backdrop-filter` and any effect a page stylesheet
+ * applied from outside the `<svg>` are not in it.
+ */
+declare function rasterize(markup: string, format: RasterFormat, options?: RasterOptions): Promise<Blob>;
+/**
+ * Hands a blob to the browser as a download.
+ *
+ * Throws rather than no-oping without a `document`: a download is something a
+ * person just asked for, and a silent return would look to them like a click
+ * that did nothing.
+ */
+declare function downloadBlob(blob: Blob, filename: string): void;
+/**
+ * A title as a filename.
+ *
+ * Lowercase, ASCII-safe and hyphenated, because a downloaded file crosses into
+ * shells, zip archives and Windows paths where a title's spaces and slashes are
+ * someone else's problem. A title with no ASCII in it at all — a Chinese one,
+ * say — slugs to nothing, so the caller's fallback is what names the file.
+ */
+declare function exportFilename(title: string, extension: string, fallback?: string): string;
+
+export { type RasterFormat, type RasterOptions, type SerializeOptions, downloadBlob, exportFilename, inlinePaint, rasterize, readToken, serializeSvg };

package/dist/lib/svg-export.js

@@ -0,0 +1,198 @@
+const SVG_NS = "http://www.w3.org/2000/svg";
+const PAINTED_PROPERTIES = [
+  "display",
+  "visibility",
+  "opacity",
+  "color",
+  "fill",
+  "fill-opacity",
+  "fill-rule",
+  "stroke",
+  "stroke-opacity",
+  "stroke-width",
+  "stroke-linecap",
+  "stroke-linejoin",
+  "stroke-dasharray",
+  "stroke-dashoffset",
+  "stop-color",
+  "stop-opacity",
+  "flood-color",
+  "flood-opacity",
+  "marker-start",
+  "marker-mid",
+  "marker-end",
+  "mask",
+  "filter",
+  "clip-path",
+  "clip-rule",
+  "paint-order",
+  "mix-blend-mode",
+  "shape-rendering",
+  "text-anchor",
+  "dominant-baseline",
+  "font-family",
+  "font-size",
+  "font-style",
+  "font-weight",
+  "letter-spacing",
+  "text-transform"
+];
+function inlinePaint(live, clone) {
+  const computed = getComputedStyle(live);
+  let css = "";
+  for (const property of PAINTED_PROPERTIES) {
+    const value = computed.getPropertyValue(property);
+    if (value) css += `${property}:${value};`;
+  }
+  if (css) clone.setAttribute("style", css);
+  const children = live.children;
+  const clones = clone.children;
+  for (let index = 0; index < children.length; index += 1) {
+    const liveChild = children[index];
+    const cloneChild = clones[index];
+    if (liveChild && cloneChild) inlinePaint(liveChild, cloneChild);
+  }
+}
+function readToken(element, name, fallback) {
+  const value = getComputedStyle(element).getPropertyValue(name).trim();
+  return value && !value.includes("var(") ? value : fallback;
+}
+function serializeSvg(svg, options = {}) {
+  const { padding = 16, background, title, titleColor = "#101010", titleFont = "sans-serif" } = options;
+  const box = svg.getBoundingClientRect();
+  const width = Math.ceil(box.width) || Number(svg.getAttribute("width")) || 0;
+  const height = Math.ceil(box.height) || Number(svg.getAttribute("height")) || 0;
+  if (width === 0 || height === 0) {
+    throw new Error("serializeSvg: the artwork has no measured size yet \u2014 export it after it renders");
+  }
+  const clone = svg.cloneNode(true);
+  inlinePaint(svg, clone);
+  clone.setAttribute("width", String(width));
+  clone.setAttribute("height", String(height));
+  const titleBand = title ? 34 : 0;
+  const contentWidth = width + padding * 2;
+  const contentHeight = height + padding * 2 + titleBand;
+  const totalWidth = options.frame?.width ?? contentWidth;
+  const totalHeight = options.frame?.height ?? contentHeight;
+  const scale = options.frame ? Math.min(totalWidth / contentWidth, totalHeight / contentHeight, 1) : 1;
+  const offsetX = (totalWidth - contentWidth * scale) / 2;
+  const offsetY = (totalHeight - contentHeight * scale) / 2;
+  const page = document.createElementNS(SVG_NS, "svg");
+  page.setAttribute("xmlns", SVG_NS);
+  page.setAttribute("xmlns:xlink", "http://www.w3.org/1999/xlink");
+  page.setAttribute("width", String(totalWidth));
+  page.setAttribute("height", String(totalHeight));
+  page.setAttribute("viewBox", `0 0 ${totalWidth} ${totalHeight}`);
+  if (background) {
+    const plate = document.createElementNS(SVG_NS, "rect");
+    plate.setAttribute("width", String(totalWidth));
+    plate.setAttribute("height", String(totalHeight));
+    plate.setAttribute("fill", background);
+    page.append(plate);
+  }
+  const stage = document.createElementNS(SVG_NS, "g");
+  stage.setAttribute("transform", `translate(${offsetX}, ${offsetY}) scale(${scale})`);
+  page.append(stage);
+  if (title) {
+    const caption = document.createElementNS(SVG_NS, "text");
+    caption.setAttribute("x", String(padding));
+    caption.setAttribute("y", String(padding + 15));
+    caption.setAttribute("fill", titleColor);
+    caption.setAttribute("font-size", "15");
+    caption.setAttribute("font-weight", "500");
+    caption.setAttribute("font-family", titleFont);
+    caption.textContent = title;
+    stage.append(caption);
+  }
+  const group = document.createElementNS(SVG_NS, "g");
+  group.setAttribute("transform", `translate(${padding}, ${padding + titleBand})`);
+  group.append(clone);
+  stage.append(group);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+${new XMLSerializer().serializeToString(page)}`;
+}
+const MIME = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  webp: "image/webp"
+};
+async function rasterize(markup, format, options = {}) {
+  const { scale = 2, quality = 0.92, background } = options;
+  const url = URL.createObjectURL(new Blob([markup], { type: "image/svg+xml;charset=utf-8" }));
+  try {
+    const image = await loadImage(url);
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.ceil(image.width * scale));
+    canvas.height = Math.max(1, Math.ceil(image.height * scale));
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("rasterize: this browser gave back no 2D canvas context");
+    if (background) {
+      context.fillStyle = background;
+      context.fillRect(0, 0, canvas.width, canvas.height);
+    }
+    context.drawImage(image, 0, 0, canvas.width, canvas.height);
+    return await canvasToBlob(canvas, MIME[format], quality);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+function loadImage(url) {
+  return new Promise((resolve, reject) => {
+    const image = new Image();
+    image.addEventListener("load", () => resolve(image));
+    image.addEventListener(
+      "error",
+      () => reject(new Error("rasterize: the browser refused to decode the serialised artwork"))
+    );
+    image.src = url;
+  });
+}
+function canvasToBlob(canvas, mime, quality) {
+  return new Promise((resolve, reject) => {
+    try {
+      canvas.toBlob(
+        (blob) => {
+          if (blob) resolve(blob);
+          else reject(new Error(`rasterize: the canvas produced no ${mime} data`));
+        },
+        mime,
+        quality
+      );
+    } catch (cause) {
+      reject(
+        new Error(
+          "rasterize: the canvas is tainted, which means the artwork contains a cross-origin image",
+          { cause }
+        )
+      );
+    }
+  });
+}
+function downloadBlob(blob, filename) {
+  if (typeof document === "undefined") {
+    throw new Error("downloadBlob: needs a browser document \u2014 call it from an event handler");
+  }
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.rel = "noopener";
+  anchor.style.display = "none";
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+function exportFilename(title, extension, fallback = "figure") {
+  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return `${slug || fallback}.${extension}`;
+}
+export {
+  downloadBlob,
+  exportFilename,
+  inlinePaint,
+  rasterize,
+  readToken,
+  serializeSvg
+};
+//# sourceMappingURL=svg-export.js.map

package/dist/lib/svg-export.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/svg-export.ts"],"sourcesContent":["/**\n * Taking an `<svg>` off the page as a file.\n *\n * Shared by two entries that both draw in SVG and both need to hand a reader a\n * picture of it: `@misoto22/folio/charts` and `@misoto22/folio/diagrams`.\n * Everything here is engine-agnostic — nothing knows what a series or a node\n * is — so the parts that DO know (which `<svg>` inside a wrapper is the plot,\n * what the file should be called, what sits behind it) stay with the caller.\n *\n * Nothing touches the DOM at module scope. Every browser API — `document`,\n * `canvas`, `URL.createObjectURL` — is reached for inside a function body, so\n * this module imports cleanly into a server component and only fails when a\n * consumer actually asks for a file on a server, which is a call that cannot\n * succeed anywhere.\n */\n\nconst SVG_NS = 'http://www.w3.org/2000/svg'\n\n/**\n * The properties copied from the live DOM onto the serialised clone.\n *\n * Paint, geometry-adjacent paint, and type. Layout is deliberately absent: an\n * SVG's geometry is in its attributes, which the clone already carries, and\n * copying computed `width`/`height`/`transform` onto every node would fight\n * them.\n */\nconst PAINTED_PROPERTIES = [\n  'display',\n  'visibility',\n  'opacity',\n  'color',\n  'fill',\n  'fill-opacity',\n  'fill-rule',\n  'stroke',\n  'stroke-opacity',\n  'stroke-width',\n  'stroke-linecap',\n  'stroke-linejoin',\n  'stroke-dasharray',\n  'stroke-dashoffset',\n  'stop-color',\n  'stop-opacity',\n  'flood-color',\n  'flood-opacity',\n  'marker-start',\n  'marker-mid',\n  'marker-end',\n  'mask',\n  'filter',\n  'clip-path',\n  'clip-rule',\n  'paint-order',\n  'mix-blend-mode',\n  'shape-rendering',\n  'text-anchor',\n  'dominant-baseline',\n  'font-family',\n  'font-size',\n  'font-style',\n  'font-weight',\n  'letter-spacing',\n  'text-transform',\n] as const\n\n/**\n * Copies the resolved paint of every node in `live` onto the matching node in\n * `clone`.\n *\n * ## The problem this function exists to solve\n *\n * Serialising an `<svg>` and handing it to an `<img>` puts it in a document of\n * its own. That document has none of the page's stylesheets, so every\n * `var(--ink)`, `var(--rule-2)` and `var(--diagram-node)` in the markup\n * resolves to nothing — and a paint that resolves to nothing is not a fallback\n * colour, it is an invisible mark. Serialise naively and you get an empty\n * rectangle.\n *\n * ## The solution\n *\n * Walk the live tree and the clone in step, and on every node write\n * `getComputedStyle`'s answer into an inline `style`. Computed values have\n * already had `var()` substituted by the engine, so `fill: var(--ink)` arrives\n * as `fill: rgb(16, 16, 16)` — and, because the walk reads the LIVE element, it\n * reads it under whichever theme is currently applied. Light and dark come out\n * right for free, with no theme argument anywhere in this file.\n *\n * `<stop>` and `<marker>` children are walked too, which is the half that is\n * easy to miss: a gradient's stops and an arrowhead's fill carry custom\n * properties of their own, and a `<defs>` that lost its paint takes every line\n * ending with it.\n */\nexport function inlinePaint(live: Element, clone: Element): void {\n  const computed = getComputedStyle(live)\n  let css = ''\n  for (const property of PAINTED_PROPERTIES) {\n    const value = computed.getPropertyValue(property)\n    if (value) css += `${property}:${value};`\n  }\n  if (css) clone.setAttribute('style', css)\n\n  // The clone is a faithful deep copy, so child lists line up by index.\n  const children = live.children\n  const clones = clone.children\n  for (let index = 0; index < children.length; index += 1) {\n    const liveChild = children[index]\n    const cloneChild = clones[index]\n    if (liveChild && cloneChild) inlinePaint(liveChild, cloneChild)\n  }\n}\n\n/**\n * A custom property, resolved against the live element.\n *\n * `var()` inside a custom property is substituted at computed-value time, so\n * `--diagram-surface: var(--paper)` reads back as a colour. The guard is for\n * the case where it did not — an unregistered name, or a value the engine left\n * as a token stream — because writing `var(--paper)` into a serialised SVG\n * paints nothing at all.\n */\nexport function readToken(element: Element, name: string, fallback: string): string {\n  const value = getComputedStyle(element).getPropertyValue(name).trim()\n  return value && !value.includes('var(') ? value : fallback\n}\n\nexport interface SerializeOptions {\n  /** Space around the artwork, in user units. Defaults to 16. */\n  padding?: number\n  /** Painted behind the artwork. Omit for a transparent ground. */\n  background?: string\n  /** A band above the artwork carrying this text. */\n  title?: string\n  /** Paint for the title. Defaults to `#101010`. */\n  titleColor?: string\n  /** Family for the title. Defaults to `sans-serif`. */\n  titleFont?: string\n  /**\n   * Forces the output box, letterboxing the artwork inside it.\n   *\n   * This is what a share card is: a fixed 1200×630 frame that the diagram is\n   * fitted into, rather than a frame the diagram sizes. Omit it and the output\n   * is the artwork plus its padding.\n   */\n  frame?: { width: number; height: number }\n}\n\n/**\n * One standalone `<svg>` document: the element's own artwork, repainted with\n * resolved colours, on an optional plate, under an optional title.\n *\n * Returns markup rather than a blob because the SVG export wants the string\n * and every raster export wants it as a data source — one serialisation, four\n * file formats.\n *\n * ## What this cannot capture, honestly\n *\n * - **Anything drawn in HTML.** A toolbar, a tooltip, an inspector panel are\n *   DOM, not SVG. The file is the artwork.\n * - **Web fonts.** The isolated document cannot fetch the page's `@font-face`\n *   sources, so text is rasterised in whatever the resolved family stack finds\n *   locally. Type metrics will differ from the screen.\n * - **Cross-origin images.** An `<image>` from another origin taints the canvas\n *   and `toBlob` throws; there is no way around it from script.\n */\nexport function serializeSvg(svg: SVGSVGElement, options: SerializeOptions = {}): string {\n  const { padding = 16, background, title, titleColor = '#101010', titleFont = 'sans-serif' } = options\n\n  const box = svg.getBoundingClientRect()\n  const width = Math.ceil(box.width) || Number(svg.getAttribute('width')) || 0\n  const height = Math.ceil(box.height) || Number(svg.getAttribute('height')) || 0\n  if (width === 0 || height === 0) {\n    // Artwork that has not been measured yet has no size to export. Silently\n    // producing a 0×0 file would look to a reader like a broken download\n    // rather than a call made one frame too early.\n    throw new Error('serializeSvg: the artwork has no measured size yet — export it after it renders')\n  }\n\n  const clone = svg.cloneNode(true) as SVGSVGElement\n  inlinePaint(svg, clone)\n  clone.setAttribute('width', String(width))\n  clone.setAttribute('height', String(height))\n\n  const titleBand = title ? 34 : 0\n  const contentWidth = width + padding * 2\n  const contentHeight = height + padding * 2 + titleBand\n\n  // A frame letterboxes rather than stretches: a share card that squashed a\n  // wide diagram to 1200×630 would be a picture of a different diagram.\n  const totalWidth = options.frame?.width ?? contentWidth\n  const totalHeight = options.frame?.height ?? contentHeight\n  const scale = options.frame\n    ? Math.min(totalWidth / contentWidth, totalHeight / contentHeight, 1)\n    : 1\n  const offsetX = (totalWidth - contentWidth * scale) / 2\n  const offsetY = (totalHeight - contentHeight * scale) / 2\n\n  const page = document.createElementNS(SVG_NS, 'svg')\n  page.setAttribute('xmlns', SVG_NS)\n  page.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink')\n  page.setAttribute('width', String(totalWidth))\n  page.setAttribute('height', String(totalHeight))\n  page.setAttribute('viewBox', `0 0 ${totalWidth} ${totalHeight}`)\n\n  if (background) {\n    const plate = document.createElementNS(SVG_NS, 'rect')\n    plate.setAttribute('width', String(totalWidth))\n    plate.setAttribute('height', String(totalHeight))\n    plate.setAttribute('fill', background)\n    page.append(plate)\n  }\n\n  const stage = document.createElementNS(SVG_NS, 'g')\n  stage.setAttribute('transform', `translate(${offsetX}, ${offsetY}) scale(${scale})`)\n  page.append(stage)\n\n  if (title) {\n    const caption = document.createElementNS(SVG_NS, 'text')\n    caption.setAttribute('x', String(padding))\n    caption.setAttribute('y', String(padding + 15))\n    caption.setAttribute('fill', titleColor)\n    caption.setAttribute('font-size', '15')\n    caption.setAttribute('font-weight', '500')\n    caption.setAttribute('font-family', titleFont)\n    caption.textContent = title\n    stage.append(caption)\n  }\n\n  const group = document.createElementNS(SVG_NS, 'g')\n  group.setAttribute('transform', `translate(${padding}, ${padding + titleBand})`)\n  group.append(clone)\n  stage.append(group)\n\n  return `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n${new XMLSerializer().serializeToString(page)}`\n}\n\n/** The raster formats a browser canvas can encode. */\nexport type RasterFormat = 'png' | 'jpeg' | 'webp'\n\nconst MIME: Record<RasterFormat, string> = {\n  png: 'image/png',\n  jpeg: 'image/jpeg',\n  webp: 'image/webp',\n}\n\nexport interface RasterOptions {\n  /** Multiplier on the on-screen size. 2 is a retina-sharp export. */\n  scale?: number\n  /** Encoder quality for `jpeg` and `webp`, 0–1. Ignored by `png`. */\n  quality?: number\n  /**\n   * Painted behind the image, for a format with no alpha channel.\n   *\n   * JPEG has no transparency, so a diagram serialised without a plate lands on\n   * black. Passing the page's own surface here is what makes the file look\n   * like the screen rather than like a negative.\n   */\n  background?: string\n}\n\n/**\n * SVG markup, rasterised through a canvas.\n *\n * This is the browser's own SVG rasteriser re-drawing the markup, not a\n * screenshot: antialiasing, `backdrop-filter` and any effect a page stylesheet\n * applied from outside the `<svg>` are not in it.\n */\nexport async function rasterize(\n  markup: string,\n  format: RasterFormat,\n  options: RasterOptions = {},\n): Promise<Blob> {\n  const { scale = 2, quality = 0.92, background } = options\n\n  const url = URL.createObjectURL(new Blob([markup], { type: 'image/svg+xml;charset=utf-8' }))\n  try {\n    const image = await loadImage(url)\n    const canvas = document.createElement('canvas')\n    canvas.width = Math.max(1, Math.ceil(image.width * scale))\n    canvas.height = Math.max(1, Math.ceil(image.height * scale))\n\n    const context = canvas.getContext('2d')\n    if (!context) throw new Error('rasterize: this browser gave back no 2D canvas context')\n\n    if (background) {\n      context.fillStyle = background\n      context.fillRect(0, 0, canvas.width, canvas.height)\n    }\n    context.drawImage(image, 0, 0, canvas.width, canvas.height)\n\n    return await canvasToBlob(canvas, MIME[format], quality)\n  } finally {\n    URL.revokeObjectURL(url)\n  }\n}\n\nfunction loadImage(url: string): Promise<HTMLImageElement> {\n  return new Promise((resolve, reject) => {\n    const image = new Image()\n    image.addEventListener('load', () => resolve(image))\n    image.addEventListener('error', () =>\n      reject(new Error('rasterize: the browser refused to decode the serialised artwork')),\n    )\n    image.src = url\n  })\n}\n\nfunction canvasToBlob(canvas: HTMLCanvasElement, mime: string, quality: number): Promise<Blob> {\n  return new Promise((resolve, reject) => {\n    try {\n      canvas.toBlob(\n        (blob) => {\n          if (blob) resolve(blob)\n          else reject(new Error(`rasterize: the canvas produced no ${mime} data`))\n        },\n        mime,\n        quality,\n      )\n    } catch (cause) {\n      // A cross-origin image anywhere in the artwork taints the canvas and this\n      // throws SecurityError. Nothing in script can untaint it, so the honest\n      // move is to say which failure it was.\n      reject(\n        new Error(\n          'rasterize: the canvas is tainted, which means the artwork contains a cross-origin image',\n          { cause },\n        ),\n      )\n    }\n  })\n}\n\n/**\n * Hands a blob to the browser as a download.\n *\n * Throws rather than no-oping without a `document`: a download is something a\n * person just asked for, and a silent return would look to them like a click\n * that did nothing.\n */\nexport function downloadBlob(blob: Blob, filename: string): void {\n  if (typeof document === 'undefined') {\n    throw new Error('downloadBlob: needs a browser document — call it from an event handler')\n  }\n\n  const url = URL.createObjectURL(blob)\n  const anchor = document.createElement('a')\n  anchor.href = url\n  anchor.download = filename\n  anchor.rel = 'noopener'\n  anchor.style.display = 'none'\n  document.body.append(anchor)\n  anchor.click()\n  anchor.remove()\n\n  // Revoking in the same tick cancels the download in Safari; one turn of the\n  // event loop is enough for the navigation to have started.\n  setTimeout(() => URL.revokeObjectURL(url), 0)\n}\n\n/**\n * A title as a filename.\n *\n * Lowercase, ASCII-safe and hyphenated, because a downloaded file crosses into\n * shells, zip archives and Windows paths where a title's spaces and slashes are\n * someone else's problem. A title with no ASCII in it at all — a Chinese one,\n * say — slugs to nothing, so the caller's fallback is what names the file.\n */\nexport function exportFilename(title: string, extension: string, fallback = 'figure'): string {\n  const slug = title\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '')\n  return `${slug || fallback}.${extension}`\n}\n"],"mappings":"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","names":[]}

package/dist/lib/useClipboardCopy.d.ts

@@ -0,0 +1,30 @@
+/** How long a copy control confirms before it returns to its resting label. */
+declare const COPIED_RESET_MS = 1600;
+interface ClipboardCopy {
+    /** True from an accepted write until the confirmation window closes. */
+    copied: boolean;
+    /**
+     * Writes the text and resolves `true` only once the browser accepted it.
+     *
+     * A function is read at activation rather than at render, for a host that
+     * owns the rendered code; if it throws, that counts as a failed copy.
+     */
+    copy: (source: string | (() => string)) => Promise<boolean>;
+}
+/**
+ * The copy state every copy control in the package shares: CodeBlock's strip
+ * button and the website ClipboardButton.
+ *
+ * Internal on purpose. It is not a public export, because the public contract
+ * is the controls that use it, not a clipboard helper.
+ *
+ * A rejected write is handled, not swallowed: clipboard access is denied in an
+ * insecure context and inside some embeds, and the only honest reaction the
+ * control has is to stop claiming success. So a failure clears any confirmation
+ * still showing from an earlier copy, resolves `false` for the caller, and says
+ * why in development. The snippet stays selectable by hand, so there is nothing
+ * further to recover, and an unhandled rejection would take the page with it.
+ */
+declare function useClipboardCopy(component: string): ClipboardCopy;
+
+export { COPIED_RESET_MS, type ClipboardCopy, useClipboardCopy };

package/dist/lib/useClipboardCopy.js

@@ -0,0 +1,37 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { warn } from "./warn.js";
+const COPIED_RESET_MS = 1600;
+function useClipboardCopy(component) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef(void 0);
+  useEffect(() => () => clearTimeout(timer.current), []);
+  const copy = useCallback(
+    async (source) => {
+      clearTimeout(timer.current);
+      try {
+        await navigator.clipboard.writeText(typeof source === "function" ? source() : source);
+      } catch (error) {
+        setCopied(false);
+        warn({
+          code: "CLIPBOARD_WRITE_REJECTED",
+          problem: `The browser refused the clipboard write (${error instanceof Error ? error.message : String(error)}), so ${component} kept its copy label instead of confirming.`,
+          field: `${component}.copy`,
+          fix: "Serve the page from a secure context (HTTPS or localhost) and allow clipboard-write in any embedding iframe.",
+          component
+        });
+        return false;
+      }
+      setCopied(true);
+      timer.current = setTimeout(() => setCopied(false), COPIED_RESET_MS);
+      return true;
+    },
+    [component]
+  );
+  return { copied, copy };
+}
+export {
+  COPIED_RESET_MS,
+  useClipboardCopy
+};
+//# sourceMappingURL=useClipboardCopy.js.map

package/dist/lib/useClipboardCopy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/useClipboardCopy.ts"],"sourcesContent":["'use client'\n\nimport { useCallback, useEffect, useRef, useState } from 'react'\nimport { warn } from './warn'\n\n/** How long a copy control confirms before it returns to its resting label. */\nexport const COPIED_RESET_MS = 1600\n\nexport interface ClipboardCopy {\n  /** True from an accepted write until the confirmation window closes. */\n  copied: boolean\n  /**\n   * Writes the text and resolves `true` only once the browser accepted it.\n   *\n   * A function is read at activation rather than at render, for a host that\n   * owns the rendered code; if it throws, that counts as a failed copy.\n   */\n  copy: (source: string | (() => string)) => Promise<boolean>\n}\n\n/**\n * The copy state every copy control in the package shares: CodeBlock's strip\n * button and the website ClipboardButton.\n *\n * Internal on purpose. It is not a public export, because the public contract\n * is the controls that use it, not a clipboard helper.\n *\n * A rejected write is handled, not swallowed: clipboard access is denied in an\n * insecure context and inside some embeds, and the only honest reaction the\n * control has is to stop claiming success. So a failure clears any confirmation\n * still showing from an earlier copy, resolves `false` for the caller, and says\n * why in development. The snippet stays selectable by hand, so there is nothing\n * further to recover, and an unhandled rejection would take the page with it.\n */\nexport function useClipboardCopy(component: string): ClipboardCopy {\n  const [copied, setCopied] = useState(false)\n  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)\n\n  useEffect(() => () => clearTimeout(timer.current), [])\n\n  const copy = useCallback(\n    async (source: string | (() => string)) => {\n      clearTimeout(timer.current)\n      try {\n        await navigator.clipboard.writeText(typeof source === 'function' ? source() : source)\n      } catch (error) {\n        setCopied(false)\n        warn({\n          code: 'CLIPBOARD_WRITE_REJECTED',\n          problem: `The browser refused the clipboard write (${error instanceof Error ? error.message : String(error)}), so ${component} kept its copy label instead of confirming.`,\n          field: `${component}.copy`,\n          fix: 'Serve the page from a secure context (HTTPS or localhost) and allow clipboard-write in any embedding iframe.',\n          component,\n        })\n        return false\n      }\n      setCopied(true)\n      // Restarted on every accepted write, so a second copy gets its own full\n      // confirmation window rather than the remainder of the first.\n      timer.current = setTimeout(() => setCopied(false), COPIED_RESET_MS)\n      return true\n    },\n    [component],\n  )\n\n  return { copied, copy }\n}\n"],"mappings":";AAEA,SAAS,aAAa,WAAW,QAAQ,gBAAgB;AACzD,SAAS,YAAY;AAGd,MAAM,kBAAkB;AA4BxB,SAAS,iBAAiB,WAAkC;AACjE,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAS,KAAK;AAC1C,QAAM,QAAQ,OAAkD,MAAS;AAEzE,YAAU,MAAM,MAAM,aAAa,MAAM,OAAO,GAAG,CAAC,CAAC;AAErD,QAAM,OAAO;AAAA,IACX,OAAO,WAAoC;AACzC,mBAAa,MAAM,OAAO;AAC1B,UAAI;AACF,cAAM,UAAU,UAAU,UAAU,OAAO,WAAW,aAAa,OAAO,IAAI,MAAM;AAAA,MACtF,SAAS,OAAO;AACd,kBAAU,KAAK;AACf,aAAK;AAAA,UACH,MAAM;AAAA,UACN,SAAS,4CAA4C,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC,SAAS,SAAS;AAAA,UAC7H,OAAO,GAAG,SAAS;AAAA,UACnB,KAAK;AAAA,UACL;AAAA,QACF,CAAC;AACD,eAAO;AAAA,MACT;AACA,gBAAU,IAAI;AAGd,YAAM,UAAU,WAAW,MAAM,UAAU,KAAK,GAAG,eAAe;AAClE,aAAO;AAAA,IACT;AAAA,IACA,CAAC,SAAS;AAAA,EACZ;AAEA,SAAO,EAAE,QAAQ,KAAK;AACxB;","names":[]}

package/dist/lib/useSelectionIndicator.d.ts

@@ -0,0 +1,29 @@
+interface IndicatorStyle {
+    /** Distance from the container's inline start, in pixels. */
+    offset: number;
+    width: number;
+    height: number;
+    top: number;
+    /** False until the first measurement, so the pill does not fly in from 0. */
+    ready: boolean;
+}
+/**
+ * Measures the selected child so a single pill can slide between options
+ * instead of one filled background switching off while another switches on.
+ *
+ * Why measure rather than animate each option's own background: a colour that
+ * cross-fades reads as two things changing, and a shape that travels reads as
+ * one thing moving — which is what actually happened. It is also the only way
+ * to get the movement onto the compositor, since `background-color` cannot be
+ * transformed.
+ *
+ * `useLayoutEffect` and not `useEffect`: the measurement has to land in the
+ * same frame as the render that caused it, or the pill visibly starts from its
+ * old place on first paint.
+ *
+ * Re-measures on resize and whenever `key` changes — `key` being whatever makes
+ * the selection different, usually the selected value.
+ */
+declare function useSelectionIndicator<T extends HTMLElement>(key: string | null): [React.RefObject<T | null>, IndicatorStyle];
+
+export { type IndicatorStyle, useSelectionIndicator };

package/dist/lib/useSelectionIndicator.js

@@ -0,0 +1,49 @@
+"use client";
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+function useSelectionIndicator(key) {
+  const containerRef = useRef(null);
+  const [style, setStyle] = useState({
+    offset: 0,
+    width: 0,
+    height: 0,
+    top: 0,
+    ready: false
+  });
+  const measure = useCallback(() => {
+    const container = containerRef.current;
+    const selected = container?.querySelector('[data-indicator-active="true"]');
+    if (!container || !selected) {
+      setStyle((previous) => ({ ...previous, ready: false }));
+      return;
+    }
+    let offset = 0;
+    let top = 0;
+    for (let node = selected; node && node !== container; node = node.offsetParent) {
+      offset += node.offsetLeft;
+      top += node.offsetTop;
+    }
+    setStyle({
+      // Physical `left`, not `inline-start`: the pill is positioned with
+      // `transform`, which is physical, and the measurement has to match. It
+      // comes out right in both directions because both sides of the
+      // subtraction flip together.
+      offset,
+      width: selected.offsetWidth,
+      height: selected.offsetHeight,
+      top,
+      ready: true
+    });
+  }, []);
+  useLayoutEffect(() => {
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    if (containerRef.current) observer.observe(containerRef.current);
+    return () => observer.disconnect();
+  }, [key, measure]);
+  return [containerRef, style];
+}
+export {
+  useSelectionIndicator
+};
+//# sourceMappingURL=useSelectionIndicator.js.map

package/dist/lib/useSelectionIndicator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/useSelectionIndicator.ts"],"sourcesContent":["'use client'\n\nimport { useCallback, useLayoutEffect, useRef, useState } from 'react'\n\nexport interface IndicatorStyle {\n  /** Distance from the container's inline start, in pixels. */\n  offset: number\n  width: number\n  height: number\n  top: number\n  /** False until the first measurement, so the pill does not fly in from 0. */\n  ready: boolean\n}\n\n/**\n * Measures the selected child so a single pill can slide between options\n * instead of one filled background switching off while another switches on.\n *\n * Why measure rather than animate each option's own background: a colour that\n * cross-fades reads as two things changing, and a shape that travels reads as\n * one thing moving — which is what actually happened. It is also the only way\n * to get the movement onto the compositor, since `background-color` cannot be\n * transformed.\n *\n * `useLayoutEffect` and not `useEffect`: the measurement has to land in the\n * same frame as the render that caused it, or the pill visibly starts from its\n * old place on first paint.\n *\n * Re-measures on resize and whenever `key` changes — `key` being whatever makes\n * the selection different, usually the selected value.\n */\nexport function useSelectionIndicator<T extends HTMLElement>(\n  key: string | null,\n): [React.RefObject<T | null>, IndicatorStyle] {\n  const containerRef = useRef<T>(null)\n  const [style, setStyle] = useState<IndicatorStyle>({\n    offset: 0,\n    width: 0,\n    height: 0,\n    top: 0,\n    ready: false,\n  })\n\n  const measure = useCallback(() => {\n    const container = containerRef.current\n    const selected = container?.querySelector<HTMLElement>('[data-indicator-active=\"true\"]')\n    if (!container || !selected) {\n      setStyle((previous) => ({ ...previous, ready: false }))\n      return\n    }\n    // `offsetLeft` and friends, not `getBoundingClientRect`.\n    //\n    // The rect is in VISUAL pixels: inside a zoomed or scaled ancestor — a\n    // thumbnail, a device preview — it comes back multiplied, while the\n    // `transform` this feeds is interpreted in the element's own coordinate\n    // space. The pill then landed short of its segment by exactly the scale\n    // factor. The offset properties are layout values and are unaffected.\n    //\n    // Offsets are relative to `offsetParent`, which is usually the strip itself\n    // but need not be, so they are accumulated up to the container rather than\n    // read once.\n    let offset = 0\n    let top = 0\n    for (\n      let node: HTMLElement | null = selected;\n      node && node !== container;\n      node = node.offsetParent as HTMLElement | null\n    ) {\n      offset += node.offsetLeft\n      top += node.offsetTop\n    }\n\n    setStyle({\n      // Physical `left`, not `inline-start`: the pill is positioned with\n      // `transform`, which is physical, and the measurement has to match. It\n      // comes out right in both directions because both sides of the\n      // subtraction flip together.\n      offset,\n      width: selected.offsetWidth,\n      height: selected.offsetHeight,\n      top,\n      ready: true,\n    })\n  }, [])\n\n  useLayoutEffect(() => {\n    measure()\n    if (typeof ResizeObserver === 'undefined') return\n    const observer = new ResizeObserver(measure)\n    if (containerRef.current) observer.observe(containerRef.current)\n    return () => observer.disconnect()\n  }, [key, measure])\n\n  return [containerRef, style]\n}\n"],"mappings":";AAEA,SAAS,aAAa,iBAAiB,QAAQ,gBAAgB;AA6BxD,SAAS,sBACd,KAC6C;AAC7C,QAAM,eAAe,OAAU,IAAI;AACnC,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAyB;AAAA,IACjD,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,KAAK;AAAA,IACL,OAAO;AAAA,EACT,CAAC;AAED,QAAM,UAAU,YAAY,MAAM;AAChC,UAAM,YAAY,aAAa;AAC/B,UAAM,WAAW,WAAW,cAA2B,gCAAgC;AACvF,QAAI,CAAC,aAAa,CAAC,UAAU;AAC3B,eAAS,CAAC,cAAc,EAAE,GAAG,UAAU,OAAO,MAAM,EAAE;AACtD;AAAA,IACF;AAYA,QAAI,SAAS;AACb,QAAI,MAAM;AACV,aACM,OAA2B,UAC/B,QAAQ,SAAS,WACjB,OAAO,KAAK,cACZ;AACA,gBAAU,KAAK;AACf,aAAO,KAAK;AAAA,IACd;AAEA,aAAS;AAAA;AAAA;AAAA;AAAA;AAAA,MAKP;AAAA,MACA,OAAO,SAAS;AAAA,MAChB,QAAQ,SAAS;AAAA,MACjB;AAAA,MACA,OAAO;AAAA,IACT,CAAC;AAAA,EACH,GAAG,CAAC,CAAC;AAEL,kBAAgB,MAAM;AACpB,YAAQ;AACR,QAAI,OAAO,mBAAmB,YAAa;AAC3C,UAAM,WAAW,IAAI,eAAe,OAAO;AAC3C,QAAI,aAAa,QAAS,UAAS,QAAQ,aAAa,OAAO;AAC/D,WAAO,MAAM,SAAS,WAAW;AAAA,EACnC,GAAG,CAAC,KAAK,OAAO,CAAC;AAEjB,SAAO,CAAC,cAAc,KAAK;AAC7B;","names":[]}

package/dist/lib/warn.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Development warnings, written for the reader most likely to hit them.
+ *
+ * The skill in this package documents a handful of ways to misuse a component
+ * that fail SILENTLY — a `Field` whose child is a wrapper wires no label, an
+ * icon-only `Button` with no accessible name renders perfectly and is invisible
+ * to a screen reader. Documentation is the wrong place for those on its own: it
+ * only helps a reader who went looking, and the whole problem is that nothing
+ * told them to look.
+ *
+ * So the component says it, at the moment it happens. The shape follows what an
+ * agent needs to repair its own call without asking anyone: a stable `code` it
+ * can branch on, the `field` that caused it, an imperative one-line `fix`, and
+ * where to get the rest. A message that only says "invalid props" makes an
+ * agent guess, and it guesses by trying things.
+ *
+ * Three constraints this has to keep:
+ *
+ * - **Dev only.** Every call site is behind `process.env.NODE_ENV`, which the
+ *   consumer's bundler replaces and then drops. Nothing here reaches a
+ *   production bundle.
+ * - **Once per problem.** React renders twice in StrictMode and again on every
+ *   state change; a warning printed each time is noise that trains people to
+ *   ignore it.
+ * - **Never throws.** A warning that breaks the render is worse than the bug it
+ *   describes, and this runs during render.
+ */
+/**
+ * True outside a production build, and false when nothing said either way.
+ *
+ * Every bundler replaces `process.env.NODE_ENV` with a literal, which folds
+ * this to `false` and lets the guarded calls below be dropped entirely. Off is
+ * the right default for the case where nothing replaced it: a warning that
+ * reaches a user's console is worse than one an author never sees.
+ */
+declare const DEV: boolean;
+interface Warning {
+    /** Stable identifier. Never reused for a different cause. */
+    code: string;
+    /** What went wrong, in one declarative sentence. */
+    problem: string;
+    /** The prop or child that caused it. */
+    field: string;
+    /** Imperative, and self-sufficient — assume nobody opens the docs. */
+    fix: string;
+    /** The component to ask about. */
+    component: string;
+}
+/**
+ * Print one warning, once.
+ *
+ * Guarded at the call site too, so a production bundle drops the whole
+ * expression rather than the branch inside it.
+ */
+declare function warn({ code, problem, field, fix, component }: Warning): void;
+/** Test seam: the dedupe is global state, and a suite needs it reset. */
+declare function resetWarnings(): void;
+/**
+ * Warn when a prop that is required for accessibility holds nothing usable.
+ *
+ * `Table.caption`, `Progress.label` and their siblings are required in the type
+ * precisely because forgetting them ships a control nobody can use without
+ * sight — and an empty string satisfies the type while satisfying nothing else.
+ * That is exactly the shape a model produces when it knows a prop is mandatory
+ * and has nothing to put in it.
+ *
+ * Not applied to `Avatar.alt`. An empty `alt` is the correct, deliberate markup
+ * for a decorative image, so warning on it would be a false positive on a
+ * pattern the platform endorses.
+ */
+declare function warnBlankName(component: string, field: string, value: unknown, announces: string): void;
+
+export { DEV, resetWarnings, warn, warnBlankName };

package/dist/lib/warn.js

@@ -0,0 +1,38 @@
+const DEV = typeof process !== "undefined" && process?.env?.NODE_ENV !== "production";
+const seen = /* @__PURE__ */ new Set();
+function warn({ code, problem, field, fix, component }) {
+  if (!DEV) return;
+  const key = `${code}:${field}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  console.warn(
+    [
+      `[@misoto22/folio] ${code}`,
+      `  ${problem}`,
+      `  field: ${field}`,
+      `  fix:   ${fix}`,
+      `  docs:  npx @misoto22/folio docs ${component}`
+    ].join("\n")
+  );
+}
+function resetWarnings() {
+  seen.clear();
+}
+function warnBlankName(component, field, value, announces) {
+  if (!DEV) return;
+  if (typeof value !== "string" || value.trim() !== "") return;
+  warn({
+    code: "REQUIRED_NAME_BLANK",
+    problem: `${component}.${field} is an empty string, so ${announces}. The type is satisfied; nothing else is.`,
+    field: `${component}.${field}`,
+    fix: `Give ${field} the words a person would need to understand this without seeing it.`,
+    component
+  });
+}
+export {
+  DEV,
+  resetWarnings,
+  warn,
+  warnBlankName
+};
+//# sourceMappingURL=warn.js.map