@kolkrabbi/kol-component 0.207.0 → 0.208.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.207.0",
+  "version": "0.208.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.26.0"
+    "@kolkrabbi/kol-icons": "^0.27.0"
   },
   "files": [
     "src",

package/src/hooks/svgExport.js

@@ -0,0 +1,146 @@
+/**
+ * svgExport — turn a finished SVG string into pixels, and embed the fonts it
+ * needs so the export reads like the screen.
+ *
+ * Packaged 2026-09-04 (`export-and-history-want-packaging`, kol-fxr for
+ * kol-client-olina, who had copied ~180 lines of it). **The BUILDER is
+ * deliberately not here.** Assembling an SVG welds to an app's own layer
+ * schema — slides in one editor, compose layers in another — so it was never
+ * the reusable half. This takes a finished string and gives back a Blob.
+ */
+
+/**
+ * Rasterize an SVG string to a PNG Blob at `scale`× the SVG's own dimensions.
+ * Triggers no download.
+ *
+ * @param {string} svgString - A complete, self-contained SVG document
+ * @param {number} [scale=1] - The @Nx multiplier
+ * @param {number} [fallbackSize=1080] - Used when the SVG declares no intrinsic size
+ * @returns {Promise<Blob>} the PNG
+ */
+export function svgToPngBlob(svgString, scale = 1, fallbackSize = 1080) {
+  return new Promise((resolve, reject) => {
+    const blob = new Blob([svgString], { type: 'image/svg+xml' })
+    const url = URL.createObjectURL(blob)
+    const img = new Image()
+    img.onload = () => {
+      const canvas = document.createElement('canvas')
+      canvas.width = (img.width || fallbackSize) * scale
+      canvas.height = (img.height || fallbackSize) * scale
+      const ctx = canvas.getContext('2d')
+      ctx.drawImage(img, 0, 0, canvas.width, canvas.height)
+      URL.revokeObjectURL(url)
+      canvas.toBlob((pngBlob) => {
+        if (pngBlob) resolve(pngBlob)
+        else reject(new Error('PNG encode failed'))
+      }, 'image/png')
+    }
+    img.onerror = () => { URL.revokeObjectURL(url); reject(new Error('SVG rasterize failed')) }
+    img.src = url
+  })
+}
+
+const b64 = (buf) => {
+  const bytes = new Uint8Array(buf)
+  let bin = ''
+  const CH = 0x8000
+  for (let i = 0; i < bytes.length; i += CH) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + CH))
+  return btoa(bin)
+}
+
+const FORMAT = { woff2: 'woff2', woff: 'woff', ttf: 'truetype', otf: 'opentype' }
+const formatFor = (url) => FORMAT[(url.split('?')[0].split('.').pop() || '').toLowerCase()] ?? 'truetype'
+
+/**
+ * Inline every font a stylesheet references, by REWRITING its `@font-face`
+ * blocks and swapping only the `src`.
+ *
+ * ⚠ **NEVER SYNTHESIZE A FACE.** This is the bug the seam exists to stop
+ * (kol-client-olina, 2026-09-04): they harvested bare `url(...)` matches out
+ * of Google's CSS and emitted their own `@font-face` without `unicode-range`.
+ * Google splits ONE family into latin / latin-ext / cyrillic / greek subsets
+ * that are distinguished by that range and nothing else — so the first subset
+ * fetched got embedded, matched no glyph, and every family exported in a system
+ * fallback while the screen looked perfect. Rewriting the whole block keeps
+ * `unicode-range`, the weight and stretch ranges, and anything else the
+ * foundry declared.
+ *
+ * A face that fails to fetch is REPORTED, not swallowed: a silent `catch {}`
+ * is how the same export goes out in fallback with nothing to look at.
+ *
+ * @param {string} cssText - The stylesheet whose `@font-face` blocks to inline
+ * @param {Function} [fetchFont] - `(url) => Promise<ArrayBuffer>`; defaults to `fetch`
+ * @returns {Promise<{css: string, failed: Array<{url: string, error: Error}>}>} the rewritten CSS and every face that could not be embedded
+ */
+export async function inlineFontFaces(cssText, fetchFont) {
+  const load = fetchFont ?? (async (url) => {
+    const r = await fetch(url)
+    if (!r.ok) throw new Error(`font fetch failed: ${r.status} ${url}`)
+    return r.arrayBuffer()
+  })
+
+  const failed = []
+  const blocks = [...cssText.matchAll(/@font-face\s*{[^}]*}/g)].map((m) => m[0])
+  const urls = new Map()
+  for (const block of blocks) {
+    for (const m of block.matchAll(/url\(\s*['"]?([^'")]+)['"]?\s*\)/g)) {
+      if (!m[1].startsWith('data:')) urls.set(m[1], null)
+    }
+  }
+
+  await Promise.all([...urls.keys()].map(async (url) => {
+    try {
+      urls.set(url, `data:font/${formatFor(url)};base64,${b64(await load(url))}`)
+    } catch (error) {
+      failed.push({ url, error })
+    }
+  }))
+
+  /* Only the `src` is touched — every other descriptor in the block, and
+   * `unicode-range` above all, survives exactly as authored. */
+  const css = cssText.replace(/url\(\s*['"]?([^'")]+)['"]?\s*\)(\s*format\(\s*['"]?[^'")]+['"]?\s*\))?/g,
+    (whole, url) => {
+      const data = urls.get(url)
+      return data ? `url(${data}) format('${formatFor(url)}')` : whole
+    })
+
+  return { css, failed }
+}
+
+/**
+ * Build one `@font-face` block for a SELF-HOSTED, full-range file — the only
+ * case where synthesizing is safe, because there are no subsets to confuse.
+ * Anything served as subsets (Google's families, any foundry CSS) must go
+ * through `inlineFontFaces` instead.
+ *
+ * @param {{family: string, url: string, weight?: string, stretch?: string}} face
+ * @param {Function} [fetchFont] - `(url) => Promise<ArrayBuffer>`
+ * @returns {Promise<string>} the `@font-face` block, fonts inlined
+ */
+export async function embedFontFace({ family, url, weight = '1 1000', stretch = '1% 1000%' }, fetchFont) {
+  const load = fetchFont ?? (async (u) => {
+    const r = await fetch(u)
+    if (!r.ok) throw new Error(`font fetch failed: ${r.status} ${u}`)
+    return r.arrayBuffer()
+  })
+  const data = `data:font/${formatFor(url)};base64,${b64(await load(url))}`
+  return `@font-face{font-family:'${family}';src:url(${data}) format('${formatFor(url)}');font-weight:${weight};font-stretch:${stretch};}`
+}
+
+/**
+ * Download a Blob under a filename. The one place a DOM anchor is minted for
+ * a save, so a consumer's export path does not hand-roll it.
+ *
+ * @param {Blob} blob
+ * @param {string} filename
+ */
+export function downloadBlob(blob, filename) {
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+  URL.revokeObjectURL(url)
+}

package/src/hooks/useHistory.js

@@ -0,0 +1,121 @@
+import { useCallback, useRef, useState } from 'react'
+
+/**
+ * useHistory — undo/redo over a value the CONSUMER owns, with transactions.
+ *
+ * Packaged 2026-09-04 (`export-and-history-want-packaging`, kol-fxr for
+ * kol-client-olina, who had copied it on our advice and came back asking for
+ * it by name). **Generic over the value, deliberately**: one editor's snapshot
+ * is `{ slides, active, selectedIds }`, another's is compose state. The
+ * consumer's words, and they are right — *if it knows about layers it stops
+ * being reusable*. Nothing here inspects what it stores.
+ *
+ * TWO THINGS MAKE IT WORTH PACKAGING, and both are behaviour rather than code:
+ *
+ * 1. **Selection rides INSIDE the snapshot.** Undo restores what was selected,
+ *    not only what was drawn — so put the selection in the value. An undo that
+ *    redraws the old shape but leaves a stale selection is the version everyone
+ *    writes first and nobody wants.
+ * 2. **A drag is ONE entry.** `begin()` before a gesture and `end()` after it:
+ *    every `set` between them updates the live value without pushing, and `end`
+ *    pushes once. Without it a pointer-move drag floods the stack.
+ *
+ * ⚠ **NEVER PUSH INSIDE A `setState` UPDATER.** React StrictMode invokes
+ * updaters twice, so every entry doubles — silently, in dev only, and it looks
+ * like undo "skipping". The next value is computed against a ref here, outside
+ * the updater, which is what makes that impossible rather than merely avoided.
+ *
+ *   const { value, set, begin, end, undo, redo, reset, canUndo, canRedo } = useHistory(initial)
+ *   onPointerDown={begin} onPointerMove={(e) => set(next(e))} onPointerUp={end}
+ *
+ * @param {*} initialValue - The first snapshot; any shape
+ * @param {number} [limit=100] - Entries kept before the oldest is dropped
+ * @returns {{value: *, set: Function, begin: Function, end: Function, undo: Function, redo: Function, reset: Function, canUndo: boolean, canRedo: boolean}}
+ */
+export default function useHistory(initialValue, limit = 100) {
+  const [value, setValue] = useState(initialValue)
+  /* The ref is the truth the history reads. State drives the render; this
+   * drives the stack, so a push never depends on an updater running once. */
+  const valueRef = useRef(initialValue)
+  const past = useRef([])
+  const future = useRef([])
+  const txn = useRef(null)   /* the value as it was when begin() was called */
+  const [, bump] = useState(0)
+  const rerender = () => bump((n) => n + 1)
+
+  const commit = useCallback((next) => {
+    valueRef.current = next
+    setValue(next)
+  }, [])
+
+  /* `set` takes a value or a producer. The producer is called HERE, against
+   * the ref, never inside setState — see the StrictMode note above. */
+  const set = useCallback((nextOrFn) => {
+    const prev = valueRef.current
+    const next = typeof nextOrFn === 'function' ? nextOrFn(prev) : nextOrFn
+    if (Object.is(next, prev)) return
+    if (txn.current === null) {
+      past.current = [...past.current, prev].slice(-limit)
+      future.current = []
+    }
+    commit(next)
+    rerender()
+  }, [commit, limit])
+
+  /* Open a transaction: `set` keeps updating the live value, and the entry
+   * that lands on `end` is the value as it was when this was called. */
+  const begin = useCallback(() => {
+    if (txn.current === null) txn.current = { from: valueRef.current }
+  }, [])
+
+  const end = useCallback(() => {
+    const open = txn.current
+    txn.current = null
+    if (!open) return
+    if (Object.is(open.from, valueRef.current)) return  /* a gesture that moved nothing is not an entry */
+    past.current = [...past.current, open.from].slice(-limit)
+    future.current = []
+    rerender()
+  }, [limit])
+
+  const undo = useCallback(() => {
+    if (!past.current.length) return
+    const prev = past.current[past.current.length - 1]
+    past.current = past.current.slice(0, -1)
+    future.current = [valueRef.current, ...future.current]
+    commit(prev)
+    rerender()
+  }, [commit])
+
+  const redo = useCallback(() => {
+    if (!future.current.length) return
+    const next = future.current[0]
+    future.current = future.current.slice(1)
+    past.current = [...past.current, valueRef.current].slice(-limit)
+    commit(next)
+    rerender()
+  }, [commit, limit])
+
+  /* Drop the whole stack and start again (a fresh document, a loaded file).
+   * Not an undoable step — there is nothing behind it. Omit `next` to return
+   * to the value the hook was initialised with. */
+  const reset = useCallback((next) => {
+    past.current = []
+    future.current = []
+    txn.current = null
+    commit(next === undefined ? initialValue : next)
+    rerender()
+  }, [commit, initialValue])
+
+  return {
+    value,
+    set,
+    begin,
+    end,
+    undo,
+    redo,
+    reset,
+    canUndo: past.current.length > 0,
+    canRedo: future.current.length > 0,
+  }
+}

package/src/index.js

@@ -222,6 +222,11 @@ export { useEyedropper, pickFromCanvasElement } from './hooks/useEyedropper.js'
  * STRUCTURAL responsive fork, where the markup itself changes and a stylesheet
  * cannot express it (ColumnBrowserStackMode, 2026-09-03). Sizes stay Tailwind's. */
 export { default as useMediaQuery } from './hooks/useMediaQuery.js'
+/* The two seams kol-client-olina asked for by name after copying both
+ * (export-and-history-want-packaging, 2026-09-04). The SVG BUILDER is
+ * deliberately absent — it welds to an app's own layer schema. */
+export { svgToPngBlob, inlineFontFaces, embedFontFace, downloadBlob } from './hooks/svgExport.js'
+export { default as useHistory } from './hooks/useHistory.js'
 /* The rail gesture's other half. It lived in kol-framework until 2026-09-03 and
  * moved here for the same reason `useGrabEdge` did: kol-component's own
  * `EditorShell` needs resizable rails and cannot import framework. framework