@kolkrabbi/kol-component 0.207.0 → 0.209.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.207.0",
-  "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
+  "version": "0.209.0",
+  "description": "KOL design-system components \u2014 atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
@@ -34,7 +34,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.26.0"
+    "@kolkrabbi/kol-icons": "workspace:^"
   },
   "files": [
     "src",
@@ -56,4 +56,4 @@
     "access": "public"
   },
   "sideEffects": false
-}
+}

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

package/src/organisms/ColumnBrowser.jsx

@@ -57,6 +57,7 @@ import { GRAB_COLUMN } from '../utilities/motion.js'
  * @param {Function} kindOf       (o) => 'image' | 'video' | 'audio' | string
  * @param {Object}   kindLabel    kind → label shown when there is no visual preview
  * @param {Function} formatSize   (bytes) => string
+ * @param {Function} formatDate   (isoString) => string — the row/preview date, ISO date-only by default
  * @param {Function} partition    (objects, level) => { folders: string[], files: object[] }
  * @param {Function} renderPreview  (file) => ReactNode — replaces the preview column's media frame (the facts stay — Dimensions and Length are read off whatever <img> / <video> / <audio> the node loads); without it images render the organism's <img>, everything else the DS KindPreview
  * @param {number}   height         controlled height in px (omit for uncontrolled)
@@ -97,6 +98,54 @@ const defaultFormatSize = (bytes) => {
   if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
   return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
 }
+
+/* THE STACK'S ROW ORDER — walked, not iterated, and lifted out of the component
+ * so it is reachable by a check (the defect below is invisible to every
+ * structural assertion: the rows are all present and each carries the right
+ * `depth`, they are merely in the wrong ORDER).
+ *
+ * The open folder's children have to land DIRECTLY under its own row. That
+ * adjacency IS inline expand, and inline expand is the whole ruling. A flat
+ * loop over `openPath` appends each level after the one before it, so an open
+ * folder's children surfaced below its last SIBLING and below that level's
+ * files (D1, kol-r2b2 2026-09-04) — which read as an indent bug rather than a
+ * sequence bug, and is how a comment claiming "the loop IS the path" survived.
+ *
+ * @param {object[]} objects   the flat key space
+ * @param {string[]} openPath  the open levels, shallowest first
+ * @param {Function} partition (objects, level) => { folders, files }
+ * @returns {object[]} rows — `folder` | `file` | `empty`, each with its `depth`
+ */
+export function stackRows(objects, openPath, partition) {
+  const rows = []
+  const walk = (depth) => {
+    const level = openPath[depth]
+    const { folders, files } = partition(objects.filter((o) => o.key.startsWith(level)), level)
+    const openFolder = openPath[depth + 1]?.slice(level.length) ?? null
+    folders.forEach((f) => {
+      const isOpen = f === openFolder
+      rows.push({ kind: 'folder', key: level + f, level, name: f, depth, open: isOpen })
+      if (isOpen) walk(depth + 1)
+    })
+    files.forEach((o) => rows.push({ kind: 'file', key: o.key, o, depth, level }))
+    if (!folders.length && !files.length) rows.push({ kind: 'empty', key: level + '·empty', depth })
+  }
+  walk(0)
+  return rows
+}
+
+/* A ROW SHOWS A DATE, NOT A TIMESTAMP. `2026-06-19T02:00:14.629Z` is storage
+ * answering "when" in its own voice, and it shipped into the stack meta line
+ * because the value arrives as a string and a string renders (D2, kol-r2b2
+ * 2026-09-04). A seam beside `formatSize` for the same reason that one is a
+ * seam: how a date reads is the consumer's call, not the DS's. The default is
+ * ISO-8601 date-only — unambiguous everywhere, which no locale format is.
+ * Anything unparseable comes through verbatim rather than as `Invalid Date`. */
+const defaultFormatDate = (v) => {
+  if (!v) return ''
+  const d = new Date(v)
+  return Number.isNaN(d.getTime()) ? String(v) : d.toISOString().slice(0, 10)
+}
 /* kol-r2b2's partition: the next path segment is a folder, the rest are files */
 const defaultPartition = (objects, prefix) => {
   const folderSet = new Set()
@@ -227,7 +276,7 @@ function Row({
   )
 }
 
-function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, width }) {
+function Preview({ o, urlOf, kindOf, kindLabel, formatSize, formatDate, renderPreview, width }) {
   // Pixel size and length come from the loaded media itself — the bucket stores
   // none. `{ w, h }` off an <img> load, `{ w, h, len }` off a <video>'s and
   // `{ len }` off an <audio>'s loadedmetadata (ColumnBrowserMediaFacts, kol-r2b2
@@ -243,7 +292,7 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, width
     ['Size', formatSize(o.size)],
     ...(sized ? [['Dimensions', dims?.w ? `${dims.w} × ${dims.h} px` : '…']] : []),
     ...(timed ? [['Length', dims?.len != null ? formatLength(dims.len) : '…']] : []),
-    ['Date', o.uploaded ? new Date(o.uploaded).toISOString().slice(0, 10) : '—'],
+    ['Date', formatDate(o.uploaded) || '—'],
   ]
   return (
     <div className="kol-column-browser-preview shrink-0 overflow-y-auto p-4 flex flex-col gap-4" style={{ width }}>
@@ -343,6 +392,7 @@ export default function ColumnBrowser({
   kindOf = defaultKindOf,
   kindLabel = DEFAULT_KIND_LABEL,
   formatSize = defaultFormatSize,
+  formatDate = defaultFormatDate,
   partition = defaultPartition,
   renderPreview,
   height,
@@ -563,23 +613,9 @@ export default function ColumnBrowser({
 
     /* One flat row list, walked down the open path: each level's items, with
      * the open folder's children spliced in directly under it. */
-    const rows = []
-    openPath.forEach((level, depth) => {
-      const { folders, files } = partition(objects.filter((o) => o.key.startsWith(level)), level)
-      const openFolder = openPath[depth + 1]?.slice(level.length) ?? null
-      folders.forEach((f) => {
-        const isOpen = f === openFolder
-        rows.push({
-          kind: 'folder', key: level + f, level, name: f, depth, open: isOpen,
-        })
-        /* the open folder's own children are pushed by the next iteration —
-         * nothing recursive here, the loop IS the path */
-      })
-      files.forEach((o) => rows.push({ kind: 'file', key: o.key, o, depth, level }))
-      if (!folders.length && !files.length) rows.push({ kind: 'empty', key: level + '·empty', depth })
-    })
+    const rows = stackRows(objects, openPath, partition)
 
-    const metaOf = (o) => [o.size != null && formatSize(o.size), o.uploaded].filter(Boolean).join(' · ')
+    const metaOf = (o) => [o.size != null && formatSize(o.size), formatDate(o.uploaded)].filter(Boolean).join(' · ')
 
     return (
       <div
@@ -741,7 +777,7 @@ export default function ColumnBrowser({
       })}
       {shown && (
         <>
-          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} renderPreview={renderPreview} width={widthOf('preview')} />
+          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} formatDate={formatDate} renderPreview={renderPreview} width={widthOf('preview')} />
           <ResizeHandle axis="x" onDrag={resizeCol('preview')} onEnd={endDrag} />
         </>
       )}

package/src/organisms/MediaLibraryPages.jsx

@@ -314,6 +314,17 @@ const profileOf = (objects, rawFiles, systemCount) => ({
 export function MediaLibraryBrowse({
   client, title = 'MEDIA', bucket, onBucketChange, prefix: prefixProp, onPrefix, defaults, settings: settingsProp, onSettingsChange,
   folderTree, headerActions, refreshKey, onOpen, autoFocus = false, settingsFooter, className = '',
+  /* PASS-THROUGHS TO `ColumnBrowser`. A documented prop this page does not
+   * forward is a prop no consumer of the PAGE can reach, which makes the seam
+   * fictional — `thumbnailFor` and `folderMeta` shipped, were announced, and
+   * rendered as if they never existed because this signature ended before them
+   * (ColumnBrowserMobileViews items 10 + 13, kol-r2b2 2026-09-04). Second time
+   * this shape bit: `SettingsPanel` documented a `footer` slot this file
+   * hardcoded past. The rule the sweep leaves behind — WHEN A PROP IS ADDED TO
+   * `ColumnBrowser`, IT IS ADDED HERE IN THE SAME EDIT, unless the page holds a
+   * real opinion about it (it owns `height`, the widths and `partition`, so
+   * those are deliberately absent from this list). */
+  thumbnailFor, folderMeta, formatDate, stackView,
 }) {
   const [ownPrefix, setOwnPrefix] = useState('')
   const prefix = prefixProp ?? ownPrefix
@@ -483,6 +494,10 @@ export function MediaLibraryBrowse({
               kindOf={kindOf}
               kindLabel={KIND_LABEL}
               formatSize={formatSize}
+              formatDate={formatDate}
+              thumbnailFor={thumbnailFor}
+              folderMeta={folderMeta}
+              stackView={stackView}
               renderPreview={(o) => {
                 const real = { ...o, key: o.key.slice(VROOT.length) }
                 if (isImage(real.contentType)) return <ImageFrame src={mediaUrl(real.key)} />