@kolkrabbi/kol-component 0.106.0 → 0.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.106.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

@@ -143,6 +143,8 @@ 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

@@ -1,22 +1,27 @@
 /* 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 { useRef, useState } from 'react';
+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 `AudioPreview.jsx`, promoted
- * verbatim 2026-08-27 (ColumnBrowserMediaFacts): 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 with one play/pause control and nothing else —
- * `AudioTile` / `VideoTile` (KindPreview's audio and video branches); 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).
+ * 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
@@ -26,6 +31,50 @@ import { usePopover, PopoverPanel } from '../utilities/Popover.jsx';
 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);
@@ -47,40 +96,6 @@ function useAudio(onDuration) {
   return { ref, playing, time, duration, toggle, element, setTime };
 }
 
-export function AudioTile({ src }) {
-  const { playing, toggle, element } = useAudio();
-  return (
-    <div className="w-full aspect-square flex items-center justify-center">
-      {element(src)}
-      <IconFrame name={playing ? 'pause' : 'play'} variant="secondary" size="lg" onClick={toggle} />
-    </div>
-  );
-}
-
-// Video tile: covers the square, one play/pause control — native controls stay in the overlay.
-export function VideoTile({ src, poster }) {
-  const ref = useRef(null);
-  const [playing, setPlaying] = useState(false);
-  return (
-    <div className="relative w-full aspect-square rounded overflow-hidden">
-      <video
-        ref={ref}
-        src={src}
-        poster={poster}
-        playsInline
-        preload="metadata"
-        className="w-full h-full object-cover"
-        onPlay={() => setPlaying(true)}
-        onPause={() => setPlaying(false)}
-        onEnded={() => setPlaying(false)}
-      />
-      <div className="absolute inset-0 flex items-center justify-center">
-        <IconFrame name={playing ? 'pause' : 'play'} variant="secondary" size="lg" onClick={() => (playing ? ref.current.pause() : ref.current.play())} />
-      </div>
-    </div>
-  );
-}
-
 export default function AudioPreview({ src, className = '', onDuration }) {
   const { ref, playing, time, duration, toggle, element, setTime } = useAudio(onDuration);
   const [volume, setVolume] = useState(100);

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/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)
+}