@kolkrabbi/kol-component 0.105.0 → 0.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.105.0",
+  "version": "0.107.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     "react-syntax-highlighter": "^16.1.1"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-icons": ">=0.18.0",
+    "@kolkrabbi/kol-icons": ">=0.22.0",
     "framer-motion": "^12.0.0",
     "gsap": "^3.13.0",
     "hls.js": "^1.6.0",
@@ -30,7 +30,7 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.20.0"
+    "@kolkrabbi/kol-icons": "^0.22.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -142,6 +142,9 @@ export { default as SectionNewsletter } from './organisms/SectionNewsletter.jsx'
 export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
 export { default as ColumnBrowser } from './organisms/ColumnBrowser.jsx'
 export { default as KindPreview } from './molecules/KindPreview.jsx'
+export { default as AudioPreview, AudioTile, VideoTile, formatLength } from './molecules/AudioPreview.jsx'
+export { default as VideoSheet } from './molecules/VideoSheet.jsx'
+export { readCover } from './utilities/id3.js'
 export { kindOf, extOf, isSystemFile, KINDS, KIND_LABEL } from './utilities/mediaKinds.js'
 export { default as markdownToHtml, inlineToHtml } from './utilities/markdownToHtml.js'
 export { default as RecordManager } from './organisms/RecordManager.jsx'

package/src/molecules/AudioPreview.jsx

@@ -0,0 +1,138 @@
+/* eslint-disable react-hooks/refs -- floating-ui's `refs.setReference` is a callback ref, not a ref read; the DS Tooltip wires it the same way */
+import { useEffect, useRef, useState } from 'react';
+import IconFrame from '../atoms/IconFrame.jsx';
+import Slider from './Slider.jsx';
+import { usePopover, PopoverPanel } from '../utilities/Popover.jsx';
+import { readCover } from '../utilities/id3.js';
+
+/* taxonomy-ok: molecule — nests IconFrame (atom) + Slider / PopoverPanel (relative). */
+
+/**
+ * AudioPreview · AudioTile · VideoTile — kol-r2b2's players, promoted verbatim
+ * (ColumnBrowserMediaFacts 2026-08-27; the tiles re-ruled the same day,
+ * PlayDiscAndVideoBar): players composed from DS parts (IconFrame · Slider ·
+ * Popover) — the DS AudioPlayer is a native <audio controls>, whose one-row
+ * layout can't be reshaped. Finder model (user ruling 2026-08-27): the COLUMN
+ * gets a square tile over full-bleed artwork with ONE control — the Finder
+ * play/pause disc (`.kol-play-disc`: round, hidden at rest, shown on hover of
+ * `.kol-media-tile`) — `AudioTile` (artwork = the file's embedded ID3 cover,
+ * `readCover`) / `VideoTile` (artwork = the poster; the media element is hidden
+ * — the tile never shows a decoded video frame). Timeline + volume belong to
+ * the OVERLAY / Quick Look — `AudioPreview` (play/pause · Slider seek with an
+ * m:ss readout · volume behind `slider-01`, a vertical `slider-black` range in
+ * a PopoverPanel, placement top; no title line — the name sits in the facts)
+ * and `VideoSheet` (the QuickTime bar).
+ *
+ * @param {string}   src         the media URL
+ * @param {string}   poster      VideoTile — the poster URL
+ * @param {Function} onDuration  AudioPreview — (seconds) => void once metadata lands
+ * @param {string}   className   AudioPreview — wrapper classes (the width is the consumer's)
+ */
+export const formatLength = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`;
+const fmt = formatLength;
+
+function useCover(src) {
+  const [cover, setCover] = useState(null);
+  useEffect(() => {
+    let live = true;
+    readCover(src).then((url) => { if (live) setCover(url); });
+    return () => { live = false; };
+  }, [src]);
+  return cover;
+}
+
+/* One disc for both tiles — the ruled Finder play/pause. The theme's
+ * `.kol-play-disc` paints it after the IconFrame variants, so nothing is restated here. */
+function PlayDisc({ playing, onClick }) {
+  return (
+    <IconFrame name={playing ? 'pause' : 'play'} variant="secondary" size="lg" radius="full" onClick={onClick} aria-label={playing ? 'Pause' : 'Play'} className="relative kol-play-disc" />
+  );
+}
+
+export function AudioTile({ src }) {
+  const ref = useRef(null);
+  const [playing, setPlaying] = useState(false);
+  const cover = useCover(src);
+  return (
+    <div className="kol-media-tile relative w-full aspect-square rounded overflow-hidden flex items-center justify-center">
+      <audio ref={ref} src={src} preload="metadata" onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onEnded={() => setPlaying(false)} />
+      {cover && <img src={cover} alt="" className="absolute inset-0 w-full h-full object-cover" />}
+      <PlayDisc playing={playing} onClick={() => (playing ? ref.current.pause() : ref.current.play())} />
+    </div>
+  );
+}
+
+export function VideoTile({ src, poster }) {
+  const ref = useRef(null);
+  const [playing, setPlaying] = useState(false);
+  return (
+    <div className="kol-media-tile relative w-full aspect-square rounded overflow-hidden flex items-center justify-center">
+      {/* Same as audio: the media element is hidden, the artwork (the poster) is the tile. */}
+      <video ref={ref} src={src} playsInline preload="metadata" className={poster ? 'hidden' : 'absolute inset-0 w-full h-full object-cover'} onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onEnded={() => setPlaying(false)} />
+      {poster && <img src={poster} alt="" className="absolute inset-0 w-full h-full object-cover" />}
+      <PlayDisc playing={playing} onClick={() => (playing ? ref.current.pause() : ref.current.play())} />
+    </div>
+  );
+}
+
+function useAudio(onDuration) {
+  const ref = useRef(null);
+  const [playing, setPlaying] = useState(false);
+  const [time, setTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const toggle = () => (playing ? ref.current.pause() : ref.current.play());
+  const element = (src) => (
+    <audio
+      ref={ref}
+      src={src}
+      preload="metadata"
+      onPlay={() => setPlaying(true)}
+      onPause={() => setPlaying(false)}
+      onEnded={() => setPlaying(false)}
+      onTimeUpdate={(e) => setTime(e.target.currentTime)}
+      onLoadedMetadata={(e) => { setDuration(e.target.duration); onDuration?.(e.target.duration); }}
+    />
+  );
+  return { ref, playing, time, duration, toggle, element, setTime };
+}
+
+export default function AudioPreview({ src, className = '', onDuration }) {
+  const { ref, playing, time, duration, toggle, element, setTime } = useAudio(onDuration);
+  const [volume, setVolume] = useState(100);
+  const [open, setOpen] = useState(false);
+  const pop = usePopover({ open, onOpenChange: setOpen, placement: 'top' });
+
+  return (
+    <div className={`flex items-center gap-2 ${className}`}>
+      {element(src)}
+      <IconFrame name={playing ? 'pause' : 'play'} variant="ghost" size="sm" onClick={toggle} />
+      <Slider
+        className="flex-1"
+        min={0}
+        max={duration || 0}
+        step={0.1}
+        value={time}
+        onChange={(v) => { ref.current.currentTime = v; setTime(v); }}
+        formatValue={fmt}
+        displayWidth={5}
+      />
+      <span ref={pop.refs.setReference} {...pop.getReferenceProps()} className="inline-flex">
+        <IconFrame name="slider-01" variant={open ? 'secondary' : 'ghost'} size="sm" onClick={() => {}} />
+      </span>
+      <PopoverPanel popover={pop} className="p-2">
+        {/* DS track class on a native range, turned upright: the one thing the DS Slider can't do. */}
+        <div className="w-6 h-24 flex items-center justify-center">
+          <input
+            type="range"
+            min={0}
+            max={100}
+            value={volume}
+            onChange={(e) => { const v = Number(e.target.value); ref.current.volume = v / 100; setVolume(v); }}
+            className="slider-black cursor-pointer w-24 -rotate-90"
+            aria-label="Volume"
+          />
+        </div>
+      </PopoverPanel>
+    </div>
+  );
+}

package/src/molecules/KindPreview.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import AudioPlayer from '../atoms/AudioPlayer.jsx'
+import { AudioTile, VideoTile } from './AudioPreview.jsx'
 import HlsVideo from '../atoms/HlsVideo.jsx'
 import CodeBlock from './CodeBlock.jsx'
 import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
@@ -13,7 +13,10 @@ import markdownToHtml from '../utilities/markdownToHtml.js'
  * promoted 2026-08-27 (SettingsPanelChromeAndColumnPreview). Before it, anything
  * that was not an image or a video showed a grey box with the word "text".
  * HLS → `HlsVideo` (inert — the DS's background-video atom, preview only),
- * audio → `AudioPlayer`, markdown → rendered prose in `.kol-prose`
+ * video → `VideoTile` and audio → `AudioTile` (ColumnBrowserMediaFacts
+ * 2026-08-27 — the square column tile with one play/pause control; no Figure, no
+ * border — `VideoBlock`'s Figure border is why kol-r2b2 bypassed it; the overlay
+ * player is `AudioPreview`), markdown → rendered prose in `.kol-prose`
  * (markdownToHtml, KindPreviewMarkdown 2026-08-27), json / yaml / text / code →
  * `CodeBlock` (language by kind or extension), the rest
  * → `AssetPlaceholder`. Images are the caller's (ColumnBrowser keeps its own
@@ -71,13 +74,8 @@ export default function KindPreview({ o, urlOf = (x) => x.url, poster, kindOf =
       </div>
     )
   }
-  if (kind === 'audio') {
-    return (
-      <div className="flex justify-center p-8">
-        <AudioPlayer src={url} label={name} className="items-center w-[420px] max-w-full" />
-      </div>
-    )
-  }
+  if (kind === 'video') return <VideoTile src={url} poster={poster} />
+  if (kind === 'audio') return <AudioTile src={url} />
   if (isText) {
     if (loading) return <span className="kol-mono-12 text-meta">Loading…</span>
     if (error) return <span className="kol-mono-12 text-ui-error">Couldn’t load: {error}</span>

package/src/molecules/VideoSheet.jsx

@@ -0,0 +1,87 @@
+/* eslint-disable react-hooks/refs -- floating-ui's `refs.setReference` is a callback ref, as in the DS Tooltip */
+import { useRef, useState } from 'react';
+import IconFrame from '../atoms/IconFrame.jsx';
+import Slider from './Slider.jsx';
+import { usePopover, PopoverPanel } from '../utilities/Popover.jsx';
+import { formatLength } from './AudioPreview.jsx';
+
+/* taxonomy-ok: molecule — nests IconFrame (atom) + Slider / PopoverPanel (relative). */
+
+/**
+ * VideoSheet — the overlay for video: the QuickTime bar (ruled in kol-r2b2
+ * 2026-08-27, PlayDiscAndVideoBar; promoted verbatim). No native controls; a
+ * frosted strip over the video's bottom edge, inset 16px, radius 4px (never
+ * more), `bg-fg-absolute-64` (absolute black — it sits on video, not on the
+ * theme) + `backdrop-blur-md`, `h-14 px-4 gap-3`: skip-back 15 · play/pause ·
+ * skip-forward 15 · elapsed · the DS Slider as the scrubber with the REMAINING
+ * time as its readout · volume behind `slider-01` (the vertical `slider-black`
+ * range in a PopoverPanel, as AudioPreview). Click on the video toggles play;
+ * `autoPlay`. Aria-labels only, no `title` tooltips.
+ *
+ * @param {string}   src     the video URL
+ * @param {string}   poster  the poster URL
+ * @param {Function} onMeta  ({ w, h, len }) => void once metadata lands — the overlay's facts
+ */
+export default function VideoSheet({ src, poster, onMeta }) {
+  const ref = useRef(null);
+  const [playing, setPlaying] = useState(false);
+  const [time, setTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [volume, setVolume] = useState(100);
+  const [open, setOpen] = useState(false);
+  const pop = usePopover({ open, onOpenChange: setOpen, placement: 'top' });
+  const toggle = () => (playing ? ref.current.pause() : ref.current.play());
+  const seek = (t) => { const v = Math.max(0, Math.min(duration || 0, t)); ref.current.currentTime = v; setTime(v); };
+  return (
+    <div className="relative max-w-full">
+      <video
+        ref={ref}
+        src={src}
+        poster={poster}
+        autoPlay
+        playsInline
+        preload="metadata"
+        className="max-w-full max-h-[78vh] rounded"
+        onClick={toggle}
+        onPlay={() => setPlaying(true)}
+        onPause={() => setPlaying(false)}
+        onEnded={() => setPlaying(false)}
+        onTimeUpdate={(e) => setTime(e.target.currentTime)}
+        onLoadedMetadata={(e) => { setDuration(e.target.duration); onMeta?.({ w: e.target.videoWidth, h: e.target.videoHeight, len: e.target.duration }); }}
+      />
+      <div className="absolute left-4 right-4 bottom-4 h-14 px-4 rounded flex items-center gap-3 bg-fg-absolute-64 backdrop-blur-md">
+        <IconFrame name="skip-back-15" variant="ghost" size="sm" onClick={() => seek(time - 15)} aria-label="Back 15 seconds" />
+        <IconFrame name={playing ? 'pause' : 'play'} variant="ghost" size="sm" onClick={toggle} aria-label={playing ? 'Pause' : 'Play'} />
+        <IconFrame name="skip-forward-15" variant="ghost" size="sm" onClick={() => seek(time + 15)} aria-label="Forward 15 seconds" />
+        <span className="kol-mono-14 text-fg-64 tabular-nums">{formatLength(time)}</span>
+        {/* DS Slider: the track is the scrubber, its readout is the remaining time. */}
+        <Slider
+          className="flex-1 min-w-0"
+          min={0}
+          max={duration || 0}
+          step={0.1}
+          value={time}
+          onChange={seek}
+          formatValue={(v) => formatLength(Math.max(0, (duration || 0) - v))}
+          displayWidth={5}
+        />
+        <span ref={pop.refs.setReference} {...pop.getReferenceProps()} className="inline-flex">
+          <IconFrame name="slider-01" variant={open ? 'secondary' : 'ghost'} size="sm" onClick={() => {}} aria-label="Volume" />
+        </span>
+        <PopoverPanel popover={pop} className="p-2">
+          <div className="w-6 h-24 flex items-center justify-center">
+            <input
+              type="range"
+              min={0}
+              max={100}
+              value={volume}
+              onChange={(e) => { const v = Number(e.target.value); ref.current.volume = v / 100; setVolume(v); }}
+              className="slider-black cursor-pointer w-24 -rotate-90"
+              aria-label="Volume"
+            />
+          </div>
+        </PopoverPanel>
+      </div>
+    </div>
+  );
+}

package/src/organisms/ColumnBrowser.jsx

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
 import KindPreview from '../molecules/KindPreview.jsx'
+import { formatLength } from '../molecules/AudioPreview.jsx'
 import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/mediaKinds.js'
 
 /**
@@ -43,7 +44,7 @@ import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/me
  * @param {Object}   kindLabel    kind → label shown when there is no visual preview
  * @param {Function} formatSize   (bytes) => string
  * @param {Function} partition    (objects, level) => { folders: string[], files: object[] }
- * @param {Function} renderPreview  (file) => ReactNode — replaces the preview column's media frame (the facts stay); without it images render the organism's <img>, everything else the DS KindPreview
+ * @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 {string}   className    extra classes on the browser
  */
 
@@ -96,14 +97,21 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
 }
 
 function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
-  // Pixel size comes from the loaded image itself — the bucket stores none.
+  // 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
+  // 2026-08-27 — "missing pixel dimensions and length in info").
   const [dims, setDims] = useState(null)
+  const kind = kindOf(o)
   const src = isImage(o) ? urlOf?.(o) : null
+  const sized = src || kind === 'video'
+  const timed = kind === 'video' || kind === 'audio'
   const facts = [
-    ['Kind', kindLabel[kindOf(o)] || 'file'],
+    ['Kind', kindLabel[kind] || 'file'],
     ['Type', o.contentType || '—'],
     ['Size', formatSize(o.size)],
-    ...(src ? [['Dimensions', dims ? `${dims.w} × ${dims.h} px` : '…']] : []),
+    ...(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) : '—'],
   ]
   return (
@@ -111,7 +119,9 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
       {/* the media frame: an image is the organism's own <img> (it reads the
         * dimensions); anything else is `renderPreview(o)` or the DS KindPreview
         * (video · audio · code · text — SettingsPanelChromeAndColumnPreview,
-        * 2026-08-27). Dimensions also come off any <img> a custom node loads. */}
+        * 2026-08-27). Dimensions and Length also come off any <img> / <video> /
+        * <audio> a custom node loads — captured on the frame, so consumer
+        * `renderPreview` nodes count. */}
       {src && !renderPreview ? (
         <div className="w-full aspect-square bg-fg-04 rounded flex items-center justify-center overflow-hidden">
           <img
@@ -126,6 +136,11 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
         <div
           className="kol-column-browser-media w-full min-h-[160px] max-h-[60vh] overflow-auto rounded bg-fg-04 flex items-center justify-center"
           onLoadCapture={(e) => { if (e.target?.tagName === 'IMG') setDims({ w: e.target.naturalWidth, h: e.target.naturalHeight }) }}
+          onLoadedMetadataCapture={(e) => {
+            const t = e.target
+            if (t?.tagName === 'VIDEO') setDims({ w: t.videoWidth, h: t.videoHeight, len: t.duration })
+            else if (t?.tagName === 'AUDIO') setDims({ len: t.duration })
+          }}
         >
           {renderPreview ? renderPreview(o) : <KindPreview o={o} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} />}
         </div>

package/src/utilities/id3.js

@@ -0,0 +1,65 @@
+// Embedded cover art: the ID3v2.3 / 2.4 `APIC` frame at the head of an MP3, read with one ranged fetch
+// (`Range` with a single byte range is CORS-safelisted — no preflight; R2 and the B2 proxy honour it).
+// ponytail: no ID3v2.2 (`PIC`), no unsynchronisation — add when a file in the buckets needs either.
+const CHUNK = 1 << 20
+const covers = new Map(); // url → Promise<string|null> object URL. ponytail: never revoked — a few hundred KB per file viewed.
+
+const syncsafe = (b, i) => ((b[i] & 0x7f) << 21) | ((b[i + 1] & 0x7f) << 14) | ((b[i + 2] & 0x7f) << 7) | (b[i + 3] & 0x7f)
+const be32 = (b, i) => ((b[i] << 24) | (b[i + 1] << 16) | (b[i + 2] << 8) | b[i + 3]) >>> 0
+const latin1 = (b) => String.fromCharCode(...b)
+
+async function range(url, from, to) {
+  const r = await fetch(url, { headers: { Range: `bytes=${from}-${to}` } })
+  if (!r.ok) throw new Error(String(r.status))
+  return new Uint8Array(await r.arrayBuffer())
+}
+
+function concat(a, b) { const out = new Uint8Array(a.length + b.length); out.set(a); out.set(b, a.length); return out; }
+
+function apic(tag, version) {
+  let i = 0
+  let first = null; // Finder shows the FRONT cover (type 3) when a file carries several pictures
+  while (i + 10 <= tag.length) {
+    const id = latin1(tag.subarray(i, i + 4))
+    if (!/^[A-Z0-9]{4}$/.test(id)) break; // padding
+    const size = version === 4 ? syncsafe(tag, i + 4) : be32(tag, i + 4)
+    if (id === 'APIC') {
+      const body = tag.subarray(i + 10, i + 10 + size)
+      const enc = body[0]
+      let p = 1
+      while (p < body.length && body[p] !== 0) p++
+      const mime = latin1(body.subarray(1, p))
+      const type = body[p + 1]
+      p += 2; // mime terminator + picture type
+      if (enc === 1 || enc === 2) { while (p + 1 < body.length && !(body[p] === 0 && body[p + 1] === 0)) p += 2; p += 2; } // UTF-16 description
+      else { while (p < body.length && body[p] !== 0) p++; p++; }
+      const blob = new Blob([body.subarray(p)], { type: mime || 'image/jpeg' })
+      if (type === 3) return blob
+      first ??= blob
+    }
+    i += 10 + size
+  }
+  return first
+}
+
+export function readCover(url) {
+  if (!covers.has(url)) {
+    covers.set(url, (async () => {
+      try {
+        let bytes = await range(url, 0, CHUNK - 1)
+        if (latin1(bytes.subarray(0, 3)) !== 'ID3' || bytes[3] < 3) return null
+        const version = bytes[3]
+        const flags = bytes[5]
+        const size = syncsafe(bytes, 6)
+        if (bytes.length < 10 + size) bytes = concat(bytes, await range(url, bytes.length, 10 + size - 1))
+        let tag = bytes.subarray(10, 10 + size)
+        if (flags & 0x40) tag = tag.subarray(version === 4 ? syncsafe(tag, 0) : be32(tag, 0) + 4); // extended header
+        const blob = apic(tag, version)
+        return blob ? URL.createObjectURL(blob) : null
+      } catch {
+        return null
+      }
+    })())
+  }
+  return covers.get(url)
+}