@kolkrabbi/kol-foundry 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-foundry",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "private": false,
   "description": "KOL foundry component set — the type-specimen apparatus: typeface hero, variable-font axis playground, parsed-metric glyph inspector, character-set browser, font-preview, and the typeface-catalog grid. Every component renders, inspects, or manipulates a live font. Typeface data is consumer-injected. Sits above @kolkrabbi/kol-{theme,icons,component}.",
   "license": "MIT",
@@ -11,9 +11,9 @@
     ".": "./src/index.js"
   },
   "dependencies": {
-    "@kolkrabbi/kol-component": "0.8.0",
-    "@kolkrabbi/kol-theme": "0.7.3",
-    "@kolkrabbi/kol-icons": "0.5.0"
+    "@kolkrabbi/kol-component": "0.10.0",
+    "@kolkrabbi/kol-theme": "0.7.5",
+    "@kolkrabbi/kol-icons": "0.6.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/FontPreviewSection.jsx

@@ -59,22 +59,20 @@ function FontPreviewItem({
             options={weightOptions}
             value={selectedWeight}
             onChange={setSelectedWeight}
-            variant="minimal"
           />
         </div>
         <div className="flex-1 flex justify-start items-start gap-8">
-          <Slider label="Size" min={12} max={200} value={size} onChange={setSize} variant="minimal" className="flex-1" />
+          <Slider label="Size" min={12} max={200} value={size} onChange={setSize} className="flex-1" />
           <Slider
             label="Leading"
             min={0}
             max={50}
             value={leading}
             onChange={setLeading}
-            variant="minimal"
             className="hidden md:flex flex-1"
             formatValue={(val) => 90 + val}
           />
-          <Slider label="Spacing" min={-50} max={50} value={spacing} onChange={setSpacing} variant="minimal" className="hidden md:flex flex-1" />
+          <Slider label="Spacing" min={-50} max={50} value={spacing} onChange={setSpacing} className="hidden md:flex flex-1" />
         </div>
       </div>
 

package/src/TypeSpecimenLive.jsx

@@ -0,0 +1,130 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+
+/* taxonomy-ok: organism — self-measuring live specimen; owns getComputedStyle
+ * I/O over rendered font samples. */
+
+/**
+ * TypeSpecimenLive — a self-measuring type specimen. One row per type class,
+ * each rendering a live sample and reading its OWN `getComputedStyle` to print
+ * the resolved typeface / weight / size / leading / tracking beside it. Because
+ * the labels are measured off the real rendered element, they can never drift
+ * from the CSS: retune a token and the specimen follows.
+ *
+ * Ported from the kol portfolio-kit's `TypeSpecimen` page and generalised for
+ * the design system — the kit's hardcoded row list is now the consumer-injected
+ * `specs` prop, and the PP-Right-Grotesk / JetBrains-Mono weight-name maps are
+ * overridable props (defaulted to the kit's fonts). Casing is untouched: class
+ * names and samples render verbatim.
+ *
+ * WHY IT EXISTS: `TypeSpecCard` is a STATIC data sheet — the consumer types the
+ * metric tuples in by hand next to a sample. This component is its live cousin:
+ * it MEASURES the sample, so there's nothing to type and nothing to keep in
+ * sync. Richer, and honest by construction.
+ *
+ * @param {Object} props
+ * @param {Array<{className:string, sample:React.ReactNode, label?:string}>} props.specs
+ *   The rows. `className` is the type class to render + measure; `sample` is the
+ *   live copy; `label` overrides the printed class name (defaults to className).
+ * @param {string} [props.title] Optional header title (rendered verbatim).
+ * @param {string} [props.description] Optional header description (verbatim).
+ * @param {string} [props.sampleClassName] Extra class(es) on every sample element
+ *   (default `text-emphasis` for a legible default color; pass '' to opt out).
+ * @param {Object<number,string>} [props.sansWeightNames] weight→name for
+ *   proportional faces (default PP Right Grotesk ramp).
+ * @param {Object<number,string>} [props.monoWeightNames] weight→name for mono
+ *   faces (default JetBrains Mono ramp).
+ * @param {{mono:string, sans:string}} [props.typefaceNames] Friendly typeface
+ *   labels chosen by the mono/proportional split (default RG / JetBrains).
+ * @param {string} [props.className] Class(es) on the root <div>.
+ */
+
+const DEFAULT_SANS_WEIGHTS = { 100: 'Fine', 300: 'Light', 400: 'Regular', 500: 'Medium', 600: 'Dark', 700: 'Bold', 900: 'Black' }
+const DEFAULT_MONO_WEIGHTS = { 400: 'Regular', 500: 'Medium', 600: 'SemiBold', 700: 'Bold' }
+const DEFAULT_TYPEFACE_NAMES = { mono: 'JetBrains Mono', sans: 'Right Grotesk' }
+
+/**
+ * Read a computed-style object into a printable metric record. Exported so
+ * consumers can reuse the exact same derivation in tests or custom rows.
+ */
+export function readMeta(cs, {
+  sansWeightNames = DEFAULT_SANS_WEIGHTS,
+  monoWeightNames = DEFAULT_MONO_WEIGHTS,
+  typefaceNames = DEFAULT_TYPEFACE_NAMES,
+} = {}) {
+  const fam = cs.fontFamily.split(',')[0].replace(/["']/g, '').trim()
+  const mono = /mono/i.test(fam)
+  const typeface = mono ? typefaceNames.mono : typefaceNames.sans
+  const width = /Narrow/.test(fam) ? 'Narrow' : /Compact/.test(fam) ? 'Compact' : mono ? 'Monospace' : 'Regular'
+  const w = parseInt(cs.fontWeight, 10)
+  const wname = (mono ? monoWeightNames : sansWeightNames)[w]
+  const size = parseFloat(cs.fontSize)
+  const lh = parseFloat(cs.lineHeight)
+  const leading = Number.isNaN(lh) ? cs.lineHeight : `${+lh.toFixed(1)}px (${(lh / size).toFixed(2)}×)`
+  const ls = parseFloat(cs.letterSpacing)
+  const tracking = !ls ? '0' : `${cs.letterSpacing} (${(ls / size).toFixed(3)}em)`
+  return { fam, typeface, width, weight: `${w}${wname ? ` ${wname}` : ''}`, size: `${+size.toFixed(1)}px`, leading, tracking }
+}
+
+function SpecimenRow({ className, sample, label, sampleClassName, metaConfig }) {
+  const ref = useRef(null)
+  const [m, setM] = useState(null)
+
+  useLayoutEffect(() => {
+    const measure = () => { if (ref.current) setM(readMeta(getComputedStyle(ref.current), metaConfig)) }
+    measure()
+    // Re-measure once webfonts land — line-height can resolve as `normal`
+    // (font-dependent) before the face loads, which would print a stale leading.
+    let cancelled = false
+    if (typeof document !== 'undefined' && document.fonts?.ready) {
+      document.fonts.ready.then(() => { if (!cancelled) measure() })
+    }
+    return () => { cancelled = true }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [className])
+
+  return (
+    <div className="flex flex-col gap-2 py-4 border-b border-fg-08">
+      <div ref={ref} className={sampleClassName ? `${className} ${sampleClassName}` : className}>{sample}</div>
+      {m && (
+        <div className="kol-mono-10 text-meta flex flex-col gap-0.5">
+          <span className="text-body">{label ?? className}</span>
+          <span>{m.typeface} · {m.fam} · {m.width} · {m.weight}</span>
+          <span>{m.size} · leading {m.leading} · tracking {m.tracking}</span>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default function TypeSpecimenLive({
+  specs = [],
+  title,
+  description,
+  sampleClassName = 'text-emphasis',
+  sansWeightNames = DEFAULT_SANS_WEIGHTS,
+  monoWeightNames = DEFAULT_MONO_WEIGHTS,
+  typefaceNames = DEFAULT_TYPEFACE_NAMES,
+  className = '',
+}) {
+  const metaConfig = { sansWeightNames, monoWeightNames, typefaceNames }
+  return (
+    <div className={`kol-type-specimen-live flex flex-col ${className}`}>
+      {(title || description) && (
+        <header className="mb-4">
+          {title && <h2 className="kol-sans-heading-04 text-emphasis mb-3">{title}</h2>}
+          {description && <p className="kol-sans-body-03 text-meta">{description}</p>}
+        </header>
+      )}
+      {specs.map((s, i) => (
+        <SpecimenRow
+          key={s.className ? `${s.className}-${i}` : i}
+          className={s.className}
+          sample={s.sample}
+          label={s.label}
+          sampleClassName={sampleClassName}
+          metaConfig={metaConfig}
+        />
+      ))}
+    </div>
+  )
+}

package/src/TypefaceVariablePreview.jsx

@@ -111,7 +111,6 @@ const TypefaceVariablePreview = ({
             max={200}
             value={size}
             onChange={setSize}
-            variant="minimal"
             className="flex-1"
           />
           <Slider
@@ -120,7 +119,6 @@ const TypefaceVariablePreview = ({
             max={50}
             value={leading}
             onChange={setLeading}
-            variant="minimal"
             className="flex-1"
             formatValue={(val) => 90 + val}
           />
@@ -130,7 +128,6 @@ const TypefaceVariablePreview = ({
             max={50}
             value={spacing}
             onChange={setSpacing}
-            variant="minimal"
             className="flex-1"
           />
         </div>

package/src/VariableFontSection.jsx

@@ -144,7 +144,6 @@ const VariableFontSection = ({
                 max={maxWeight}
                 value={Math.round(weight)}
                 onChange={handleSliderChange}
-                variant="minimal"
                 className="w-full"
               />
             </div>

package/src/index.js

@@ -25,6 +25,10 @@ export { default as TypefaceVariablePreview } from './TypefaceVariablePreview.js
 // type-specimen kit — prop-driven specimen blocks (moved from @kolkrabbi/kol-component 2026-07-09)
 export { default as TypeSample } from './TypeSample.jsx'
 export { default as TypeSpecCard } from './TypeSpecCard.jsx'
+export { default as TypeSpecimenLive, readMeta } from './TypeSpecimenLive.jsx'
+
+// font-metric hook — opentype.js parsing (optional peer, degrades gracefully)
+export { default as useFontMetrics, extractFaceMetrics, buildOutlinePaths, glyphMetricsOf } from './useFontMetrics.js'
 
 // live-font effects — variable-font axes, animated
 export { default as TextPressure } from './TextPressure.jsx'

package/src/useFontMetrics.js

@@ -0,0 +1,251 @@
+import { useEffect, useMemo, useState } from 'react'
+
+/**
+ * useFontMetrics — parse a real font with opentype.js and expose its metrics +
+ * text→outline geometry. The parsing engine ported from the kol type-editor's
+ * `fontLoader.js` (async fetch + parse + promise cache) and `textOutline.js`
+ * (tracking-aware advance measurement, greedy soft-wrap, CSS half-leading
+ * baseline math). Generalised off the editor's `layer` object into plain args
+ * and stripped of the editor's case-folding — casing is a content concern, so
+ * text is measured and outlined verbatim.
+ *
+ * WHY IT EXISTS: `GlyphMetricsGrid` already injects a FontFace and parses face-
+ * level metrics (ascender/descender/cap/x-height) inline. This hook is the
+ * reusable, parse-only layer beneath that — and it adds what the grid can't
+ * currently show: per-glyph advance/bounding-box readouts and true glyph
+ * OUTLINE path data (`<path d>`) for any string, at any size/tracking, wrapped
+ * to a box. A consumer can feed those straight into an SVG specimen.
+ *
+ * GRACEFUL DEGRADATION: opentype.js is an OPTIONAL peer, loaded via dynamic
+ * import. Absent it, the hook resolves to `status: 'unavailable'` with a null
+ * font — every derived helper returns an empty/zero result instead of throwing,
+ * exactly like the grid's overlay simply not drawing.
+ *
+ * @param {string} [fontUrl] Same-origin URL of a `.ttf`/`.otf` to fetch + parse.
+ * @param {Object} [options]
+ * @param {ArrayBuffer} [options.buffer] Pre-fetched font bytes — skips the fetch
+ *   (use when a caller already holds the buffer, e.g. an upload). Takes priority
+ *   over `fontUrl`; the two share the same parse/metric path.
+ * @param {string} [options.cacheKey] Override the cache key when passing a raw
+ *   buffer (defaults to a per-buffer identity key, so repeat buffers re-parse).
+ * @returns {{
+ *   status: 'idle'|'loading'|'ready'|'unavailable'|'error',
+ *   opentypeAvailable: boolean,
+ *   font: object|null,
+ *   metrics: {unitsPerEm:number,ascender:number,descender:number,capHeight:number,xHeight:number}|null,
+ *   error: Error|null,
+ *   getAdvanceWidth: (text:string, size:number, opts?:{tracking?:number}) => number,
+ *   getGlyphMetrics: (char:string, size?:number) => object|null,
+ *   getOutlinePaths: (text:string, opts?:object) => string[],
+ * }}
+ */
+
+/* ── opentype loader — cached dynamic import; null once we know it's absent ──
+ * Mirrors GlyphMetricsGrid's inline dynamic import so the two agree on how the
+ * optional peer is resolved (mod.parse ?? mod.default.parse ?? mod.default). */
+let opentypePromise = null
+function loadOpentype() {
+  if (opentypePromise) return opentypePromise
+  opentypePromise = import('opentype.js')
+    .then((mod) => ({ parse: mod.parse || mod.default?.parse || mod.default }))
+    .catch(() => null)
+  return opentypePromise
+}
+
+/* Resolved { font, metrics } promises, keyed like fontLoader's cache so repeat
+ * calls for the same cut never re-fetch or re-parse. A rejected/absent parse is
+ * evicted so a later attempt can retry. */
+const cache = new Map()
+
+/* Face-level metric extraction with the SAME fallback chains GlyphMetricsGrid
+ * uses (os2 ?? hhea ?? literal) so an incomplete font degrades instead of
+ * throwing. */
+function extractFaceMetrics(font) {
+  const os2 = font.tables?.os2
+  const hhea = font.tables?.hhea
+  return {
+    unitsPerEm: font.unitsPerEm || 1000,
+    ascender: os2?.sTypoAscender ?? hhea?.ascender ?? 800,
+    descender: os2?.sTypoDescender ?? hhea?.descender ?? -200,
+    capHeight: os2?.sCapHeight ?? 700,
+    xHeight: os2?.sxHeight ?? 500,
+  }
+}
+
+async function loadFontMetrics(key, source) {
+  if (cache.has(key)) return cache.get(key)
+  const promise = (async () => {
+    const ot = await loadOpentype()
+    if (!ot?.parse) return { font: null, metrics: null, reason: 'unavailable' }
+    const buffer =
+      source.buffer ??
+      (await fetch(source.url).then((r) => {
+        if (!r.ok) throw new Error(`Font fetch failed: ${source.url}`)
+        return r.arrayBuffer()
+      }))
+    const font = ot.parse(buffer)
+    return { font, metrics: extractFaceMetrics(font), reason: 'ready' }
+  })()
+  cache.set(key, promise)
+  promise.catch(() => cache.delete(key))
+  return promise
+}
+
+/* opentype render options for an em tracking value. Non-zero tracking clears
+ * ligature features — matching CSS ("UAs should not apply optional ligatures
+ * when letter-spacing is non-zero"); kerning stays on via the defaults. */
+const renderOpts = (track) =>
+  !track ? {} : { letterSpacing: track, features: [] }
+
+/* Greedy soft-wrap of one hard line to maxW, measured with the same advance/
+ * kerning/letter-spacing engine that draws the glyphs. Whitespace never forces
+ * a break (trailing space hangs); a word wider than the box splits at char
+ * level (overflow-wrap: break-word). Ported verbatim from textOutline.js. */
+function wrapLine(font, text, size, opts, maxW) {
+  if (!text.trim() || maxW <= 0) return [text]
+  const measure = (s) => font.getAdvanceWidth(s.replace(/\s+$/, ''), size, opts)
+  const tokens = text.split(/(\s+)/).filter(Boolean)
+  const lines = []
+  let cur = ''
+  for (const tok of tokens) {
+    if (/^\s+$/.test(tok)) { cur += tok; continue }
+    if (cur.trim() && measure(cur + tok) > maxW) { lines.push(cur); cur = tok }
+    else cur += tok
+    while (measure(cur) > maxW && cur.trim().length > 1) {
+      let n = cur.length - 1
+      while (n > 1 && measure(cur.slice(0, n)) > maxW) n -= 1
+      lines.push(cur.slice(0, n))
+      cur = cur.slice(n)
+    }
+  }
+  lines.push(cur)
+  return lines
+}
+
+/**
+ * Glyph outlines as layer-local `<path d>` strings, one per rendered line.
+ * Ported from textOutline.js `textOutlinePaths` — baselines via the CSS half-
+ * leading model over hhea ascent/descent (what Chrome/mac uses for the line-box
+ * content area). Text is outlined verbatim (no case-folding). When `boxWidth`
+ * is 0 the text is treated as a single unwrapped line; when `boxHeight` is 0 the
+ * block is top-anchored (top = 0) rather than vertically centered.
+ */
+function buildOutlinePaths(font, metrics, text, opts = {}) {
+  const {
+    size = 96,
+    tracking = 0,
+    lineHeight = 1.05,
+    align = 'left',
+    boxWidth = 0,
+    boxHeight = 0,
+    decimals = 2,
+  } = opts
+  const display = String(text ?? '')
+  if (!display.trim()) return []
+
+  const ropts = renderOpts(tracking)
+  const lines = display
+    .split('\n')
+    .flatMap((ln) => (boxWidth > 0 ? wrapLine(font, ln, size, ropts, boxWidth) : [ln]))
+
+  const scale = size / metrics.unitsPerEm
+  const ascent = metrics.ascender * scale
+  const descent = -metrics.descender * scale        /* hhea descender is negative */
+  const lineH = lineHeight * size
+  const blockH = Math.max(lines.length * lineH, size)  /* min-height: 1em */
+  const top = boxHeight > 0 ? (boxHeight - blockH) / 2 : 0
+
+  const paths = []
+  lines.forEach((line, i) => {
+    const t = line.replace(/\s+$/, '')             /* trailing spaces hang */
+    if (!t) return                                 /* blank line still holds its slot */
+    const lineW = font.getAdvanceWidth(t, size, ropts)
+    const lx =
+      align === 'left' ? 0 : align === 'right' ? boxWidth - lineW : (boxWidth - lineW) / 2
+    const baseY = top + i * lineH + (lineH - (ascent + descent)) / 2 + ascent
+    const d = font.getPath(t, lx, baseY, size, ropts).toPathData(decimals)
+    if (d) paths.push(d)
+  })
+  return paths
+}
+
+/* Per-glyph readout for the first char of `char`, in font units and (if a size
+ * is given) scaled px. Upgrades GlyphMetricsGrid: it can now print each cell's
+ * real advance + bounding box, not just the face-level lines. */
+function glyphMetricsOf(font, char, size) {
+  const ch = String(char ?? '').charAt(0)
+  if (!ch) return null
+  const glyph = font.charToGlyph(ch)
+  if (!glyph) return null
+  const bbox = glyph.getBoundingBox?.() ?? { x1: 0, y1: 0, x2: 0, y2: 0 }
+  const advanceUnits = glyph.advanceWidth ?? 0
+  const base = {
+    name: glyph.name,
+    unicode: glyph.unicode,
+    index: glyph.index,
+    advanceWidth: advanceUnits,
+    boundingBox: bbox,
+    leftSideBearing: glyph.leftSideBearing ?? bbox.x1,
+  }
+  if (!size) return base
+  const scale = size / (font.unitsPerEm || 1000)
+  return {
+    ...base,
+    advanceWidthPx: advanceUnits * scale,
+    widthPx: (bbox.x2 - bbox.x1) * scale,
+    heightPx: (bbox.y2 - bbox.y1) * scale,
+  }
+}
+
+export default function useFontMetrics(fontUrl, options = {}) {
+  const { buffer, cacheKey } = options
+  const key = buffer ? cacheKey ?? `buffer:${cacheKey ?? Math.random()}` : fontUrl
+
+  const [state, setState] = useState({
+    status: 'idle',
+    font: null,
+    metrics: null,
+    error: null,
+  })
+
+  useEffect(() => {
+    if (!buffer && !fontUrl) {
+      setState({ status: 'idle', font: null, metrics: null, error: null })
+      return
+    }
+    let cancelled = false
+    setState((s) => ({ ...s, status: 'loading', error: null }))
+    loadFontMetrics(key, buffer ? { buffer } : { url: fontUrl })
+      .then(({ font, metrics, reason }) => {
+        if (cancelled) return
+        if (!font) { setState({ status: 'unavailable', font: null, metrics: null, error: null }); return }
+        setState({ status: reason === 'ready' ? 'ready' : 'unavailable', font, metrics, error: null })
+      })
+      .catch((error) => {
+        if (!cancelled) setState({ status: 'error', font: null, metrics: null, error })
+      })
+    return () => { cancelled = true }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key])
+
+  const { font, metrics } = state
+
+  // Stable helper identities per parsed font — safe to pass to children/memos.
+  const helpers = useMemo(() => ({
+    getAdvanceWidth: (text, size, opts = {}) =>
+      font ? font.getAdvanceWidth(String(text ?? ''), size, renderOpts(opts.tracking)) : 0,
+    getGlyphMetrics: (char, size) => (font ? glyphMetricsOf(font, char, size) : null),
+    getOutlinePaths: (text, opts) => (font && metrics ? buildOutlinePaths(font, metrics, text, opts) : []),
+  }), [font, metrics])
+
+  return {
+    status: state.status,
+    opentypeAvailable: state.status !== 'unavailable',
+    font,
+    metrics,
+    error: state.error,
+    ...helpers,
+  }
+}
+
+export { extractFaceMetrics, buildOutlinePaths, glyphMetricsOf }