@misoto22/design 0.6.1 → 0.8.0

package/dist/lib/overlay-container.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/overlay-container.tsx"],"sourcesContent":["'use client'\n\nimport { createContext, useContext } from 'react'\nimport type { ReactNode } from 'react'\n\nconst OverlayContainerContext = createContext<HTMLElement | null>(null)\n\nexport interface OverlayContainerProps {\n  /** The element overlays should render into. `null` restores the default. */\n  container: HTMLElement | null\n  children: ReactNode\n}\n\n/**\n * Redirects every overlay in the subtree — popover, select, menu, tooltip — into\n * a given element instead of `document.body`.\n *\n * Two problems, one cause. An overlay portalled to the body is positioned\n * against the VIEWPORT, so inside a bounded frame (a documentation example, a\n * device preview, a canvas) it flips and shifts against edges the reader cannot\n * see, and lands outside the box it belongs to. It also leaves the subtree, so\n * `dir=\"rtl\"` and `data-density` set on that frame stop reaching it.\n *\n * Naming the container fixes both: the panel renders inside the frame,\n * inherits what the frame declares, and collides with the frame's edges.\n *\n * The container must be positioned (`relative` is enough) for the panel to be\n * placed against it rather than against the nearest positioned ancestor.\n *\n * @example\n * const [frame, setFrame] = useState<HTMLElement | null>(null)\n * <div ref={setFrame} className=\"relative\" data-density=\"compact\">\n *   <OverlayContainer container={frame}>{children}</OverlayContainer>\n * </div>\n */\nexport function OverlayContainer({ container, children }: OverlayContainerProps) {\n  return <OverlayContainerContext value={container}>{children}</OverlayContainerContext>\n}\n\n/**\n * The element overlays in this subtree should render into, or `null` for the\n * document body. Every portal in the library reads this.\n */\nexport function useOverlayContainer(): HTMLElement | null {\n  return useContext(OverlayContainerContext)\n}\n"],"mappings":";AAoCS;AAlCT,SAAS,eAAe,kBAAkB;AAG1C,MAAM,0BAA0B,cAAkC,IAAI;AA8B/D,SAAS,iBAAiB,EAAE,WAAW,SAAS,GAA0B;AAC/E,SAAO,oBAAC,2BAAwB,OAAO,WAAY,UAAS;AAC9D;AAMO,SAAS,sBAA0C;AACxD,SAAO,WAAW,uBAAuB;AAC3C;","names":[]}
+{"version":3,"sources":["../../src/lib/overlay-container.tsx"],"sourcesContent":["'use client'\n\nimport { createContext, useContext } from 'react'\nimport type { ReactNode } from 'react'\n\nconst OverlayContainerContext = createContext<HTMLElement | null>(null)\n\nexport interface OverlayContainerProps {\n  /** The element overlays should render into. `null` restores the default. */\n  container: HTMLElement | null\n  children: ReactNode\n}\n\n/**\n * Redirects every overlay in the subtree — popover, select, menu, tooltip,\n * dialog, sheet — into a given element instead of `document.body`.\n *\n * Two problems, one cause. An overlay portalled to the body is positioned\n * against the VIEWPORT, so inside a bounded frame (a documentation example, a\n * device preview, a canvas) it flips and shifts against edges the reader cannot\n * see, and lands outside the box it belongs to. It also leaves the subtree, so\n * `dir=\"rtl\"` and `data-density` set on that frame stop reaching it.\n *\n * Naming the container fixes both: the panel renders inside the frame,\n * inherits what the frame declares, and collides with the frame's edges.\n *\n * The container must be positioned (`relative` is enough) for the panel to be\n * placed against it rather than against the nearest positioned ancestor. The\n * modal surfaces need it for a second reason: they place themselves with\n * `position: fixed`, which resolves against the VIEWPORT whatever element they\n * are portalled into, so a named container switches them to `absolute` — and\n * an unpositioned container would then hand them the wrong box.\n *\n * @example\n * const [frame, setFrame] = useState<HTMLElement | null>(null)\n * <div ref={setFrame} className=\"relative\" data-density=\"compact\">\n *   <OverlayContainer container={frame}>{children}</OverlayContainer>\n * </div>\n */\nexport function OverlayContainer({ container, children }: OverlayContainerProps) {\n  return <OverlayContainerContext value={container}>{children}</OverlayContainerContext>\n}\n\n/**\n * The element overlays in this subtree should render into, or `null` for the\n * document body.\n *\n * Every portal in the library reads this. That sentence was false for a\n * release: `Dialog` and `Sheet` rendered the Radix portal with no container and\n * never called this hook, and their props derive from `Content`, which has no\n * `container` — so a caller could not pass one either, and every modal example\n * on the documentation site escaped the preview card it was drawn in.\n */\nexport function useOverlayContainer(): HTMLElement | null {\n  return useContext(OverlayContainerContext)\n}\n"],"mappings":";AAwCS;AAtCT,SAAS,eAAe,kBAAkB;AAG1C,MAAM,0BAA0B,cAAkC,IAAI;AAkC/D,SAAS,iBAAiB,EAAE,WAAW,SAAS,GAA0B;AAC/E,SAAO,oBAAC,2BAAwB,OAAO,WAAY,UAAS;AAC9D;AAYO,SAAS,sBAA0C;AACxD,SAAO,WAAW,uBAAuB;AAC3C;","names":[]}

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/design/charts` and `@misoto22/design/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/design/charts` and `@misoto22/design/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/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/design] ${code}`,
+      `  ${problem}`,
+      `  field: ${field}`,
+      `  fix:   ${fix}`,
+      `  docs:  npx misoto22-design 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

package/dist/lib/warn.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/warn.ts"],"sourcesContent":["/**\n * Development warnings, written for the reader most likely to hit them.\n *\n * The skill in this package documents a handful of ways to misuse a component\n * that fail SILENTLY — a `Field` whose child is a wrapper wires no label, an\n * icon-only `Button` with no accessible name renders perfectly and is invisible\n * to a screen reader. Documentation is the wrong place for those on its own: it\n * only helps a reader who went looking, and the whole problem is that nothing\n * told them to look.\n *\n * So the component says it, at the moment it happens. The shape follows what an\n * agent needs to repair its own call without asking anyone: a stable `code` it\n * can branch on, the `field` that caused it, an imperative one-line `fix`, and\n * where to get the rest. A message that only says \"invalid props\" makes an\n * agent guess, and it guesses by trying things.\n *\n * Three constraints this has to keep:\n *\n * - **Dev only.** Every call site is behind `process.env.NODE_ENV`, which the\n *   consumer's bundler replaces and then drops. Nothing here reaches a\n *   production bundle.\n * - **Once per problem.** React renders twice in StrictMode and again on every\n *   state change; a warning printed each time is noise that trains people to\n *   ignore it.\n * - **Never throws.** A warning that breaks the render is worse than the bug it\n *   describes, and this runs during render.\n */\n\n/**\n * `process.env.NODE_ENV`, without pulling Node's types into a browser library.\n *\n * Declared module-locally rather than in a `.d.ts`: an ambient `process` there\n * would travel into the emitted declarations and collide with a consumer's own\n * Node types. The `typeof` guard is what makes it safe in a bundle that never\n * defines it.\n */\ndeclare const process: { env?: { NODE_ENV?: string } } | undefined\n\n/**\n * True outside a production build, and false when nothing said either way.\n *\n * Every bundler replaces `process.env.NODE_ENV` with a literal, which folds\n * this to `false` and lets the guarded calls below be dropped entirely. Off is\n * the right default for the case where nothing replaced it: a warning that\n * reaches a user's console is worse than one an author never sees.\n */\nexport const DEV =\n  typeof process !== 'undefined' && process?.env?.NODE_ENV !== 'production'\n\n/** Warnings already printed, keyed by code + detail, so a re-render is quiet. */\nconst seen = new Set<string>()\n\ninterface Warning {\n  /** Stable identifier. Never reused for a different cause. */\n  code: string\n  /** What went wrong, in one declarative sentence. */\n  problem: string\n  /** The prop or child that caused it. */\n  field: string\n  /** Imperative, and self-sufficient — assume nobody opens the docs. */\n  fix: string\n  /** The component to ask about. */\n  component: string\n}\n\n/**\n * Print one warning, once.\n *\n * Guarded at the call site too, so a production bundle drops the whole\n * expression rather than the branch inside it.\n */\nexport function warn({ code, problem, field, fix, component }: Warning): void {\n  if (!DEV) return\n\n  const key = `${code}:${field}`\n  if (seen.has(key)) return\n  seen.add(key)\n\n  console.warn(\n    [\n      `[@misoto22/design] ${code}`,\n      `  ${problem}`,\n      `  field: ${field}`,\n      `  fix:   ${fix}`,\n      `  docs:  npx misoto22-design docs ${component}`,\n    ].join('\\n'),\n  )\n}\n\n/** Test seam: the dedupe is global state, and a suite needs it reset. */\nexport function resetWarnings(): void {\n  seen.clear()\n}\n\n/**\n * Warn when a prop that is required for accessibility holds nothing usable.\n *\n * `Table.caption`, `Progress.label` and their siblings are required in the type\n * precisely because forgetting them ships a control nobody can use without\n * sight — and an empty string satisfies the type while satisfying nothing else.\n * That is exactly the shape a model produces when it knows a prop is mandatory\n * and has nothing to put in it.\n *\n * Not applied to `Avatar.alt`. An empty `alt` is the correct, deliberate markup\n * for a decorative image, so warning on it would be a false positive on a\n * pattern the platform endorses.\n */\nexport function warnBlankName(\n  component: string,\n  field: string,\n  value: unknown,\n  announces: string,\n): void {\n  if (!DEV) return\n  if (typeof value !== 'string' || value.trim() !== '') return\n\n  warn({\n    code: 'REQUIRED_NAME_BLANK',\n    problem: `${component}.${field} is an empty string, so ${announces}. The type is satisfied; nothing else is.`,\n    field: `${component}.${field}`,\n    fix: `Give ${field} the words a person would need to understand this without seeing it.`,\n    component,\n  })\n}\n"],"mappings":"AA8CO,MAAM,MACX,OAAO,YAAY,eAAe,SAAS,KAAK,aAAa;AAG/D,MAAM,OAAO,oBAAI,IAAY;AAqBtB,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,KAAK,UAAU,GAAkB;AAC5E,MAAI,CAAC,IAAK;AAEV,QAAM,MAAM,GAAG,IAAI,IAAI,KAAK;AAC5B,MAAI,KAAK,IAAI,GAAG,EAAG;AACnB,OAAK,IAAI,GAAG;AAEZ,UAAQ;AAAA,IACN;AAAA,MACE,sBAAsB,IAAI;AAAA,MAC1B,KAAK,OAAO;AAAA,MACZ,YAAY,KAAK;AAAA,MACjB,YAAY,GAAG;AAAA,MACf,qCAAqC,SAAS;AAAA,IAChD,EAAE,KAAK,IAAI;AAAA,EACb;AACF;AAGO,SAAS,gBAAsB;AACpC,OAAK,MAAM;AACb;AAeO,SAAS,cACd,WACA,OACA,OACA,WACM;AACN,MAAI,CAAC,IAAK;AACV,MAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,GAAI;AAEtD,OAAK;AAAA,IACH,MAAM;AAAA,IACN,SAAS,GAAG,SAAS,IAAI,KAAK,2BAA2B,SAAS;AAAA,IAClE,OAAO,GAAG,SAAS,IAAI,KAAK;AAAA,IAC5B,KAAK,QAAQ,KAAK;AAAA,IAClB;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/semantic.css

@@ -105,14 +105,21 @@
      Law 2 — a box-shadow is never blurred. The system has no elevation ramp;
      depth is a hard offset in ink, applied per component. These three resolve
      to nothing on purpose, so a component ported from a shadowed system stays
-     flat instead of drawing a blur the White Reset does not have. Reach for
-     --lift instead, which is the offset idiom expressed once. */
+     flat instead of drawing a blur the White Reset does not have. --lift below
+     is the sanctioned offset idiom for anything that must read as raised. */
   --shadow-color: transparent;
   --shadow-sm: none;
   --shadow: none;
   --shadow-lg: none;
-  /* The one depth cue the system does have: a hard 3px ink offset, no blur.
-     Used by a plate that must read as sitting above the page. */
+  /* The one depth cue the system does have: a hard 3px ink offset, no blur,
+     in the accent rather than a grey because --shadow-offset points at --clay.
+
+     PUBLISHED, NOT CONSUMED. No component in this package sets either one —
+     there is not a single shadow-(--lift) in src/. What the library actually
+     separates with is a hairline, a change of ground, and the reversal that
+     Card variant="plate" reaches for. These two exist so a consumer building a
+     raised plate of their own has the system's answer instead of inventing a
+     blur; do not read them as describing what the library does. */
   --lift: 3px 3px 0 0 var(--shadow-offset);
   --lift-sm: 2px 2px 0 0 var(--shadow-offset);
 
@@ -126,10 +133,48 @@
   --overlay: var(--scrim);
   --disabled-opacity: 0.5;
 
-  /* ─── Stacking ─── five component-facing names onto the seven ranks. ───── */
-  --z-dropdown: var(--z-drawer);
+  /* ─── Stacking ─── two component-facing names onto the seven ranks. ──────
+     The other five ranks are read by their own names; only these two had a
+     component-facing spelling that outlived the rank it pointed at.
+     --z-dropdown pointed at --z-drawer, 100, which put every anchored panel
+     under the modal at 210 that opened it. */
+  --z-dropdown: var(--z-anchored);
   --z-overlay: var(--z-scrim);
 
+  /* ─── Diagrams ───────────────────────────────────────────────────────────
+     The figures in `@misoto22/design/diagrams`, which draw in SVG and
+     therefore cannot read a custom property from a presentation attribute —
+     every one of these reaches a mark through a style rule.
+
+     Named separately from the page's own rules rather than pointed straight at
+     --rule-2 because a figure is a PICTURE inside a document: its hairline has
+     to hold up against a 1200-wide raster export and a greyscale print, where
+     the page's own hairline is chosen to disappear. Keeping the two apart is
+     what lets a figure be tuned without touching a table.
+
+     Nothing here is a hue. The seven kinds of node are separated by drawn
+     sigils, and the only colour a figure spends is --success / --danger on a
+     terminal lifecycle state — the same two the rest of the system reserves
+     for state and refuses to spend on brand. */
+  --diagram-surface: var(--paper);
+  --diagram-node: var(--paper);
+  --diagram-node-2: var(--paper-2);
+  --diagram-band: var(--stone);
+  --diagram-chip: var(--paper-2);
+  --diagram-rule: var(--rule-2);
+  --diagram-rule-hard: var(--ink-3-aa);
+  --diagram-line: var(--ink-2);
+  --diagram-line-strong: var(--ink);
+  --diagram-line-soft: var(--ink-3-aa);
+  --diagram-sigil: var(--ink-3-aa);
+  --diagram-ink: var(--ink);
+  --diagram-ink-2: var(--ink-2);
+  --diagram-ink-3: var(--ink-3-aa);
+  /* The reversed plate, and its type. A figure gets ONE of these — the node the
+     diagram is about — for the same reason a page gets one Card variant="plate". */
+  --diagram-plate: var(--accent);
+  --diagram-plate-ink: var(--accent-foreground);
+
   /* ─── Layout ───────────────────────────────────────────────────────────── */
   --page-pad: var(--pad);
   --w-page: var(--maxw);