@kolkrabbi/kol-component 0.236.0 → 0.238.0

package/src/utilities/armLongPress.js

@@ -0,0 +1,18 @@
+// armLongPress — the touch hold a value control reports (Slider/Knob `variant="panel"`; kol-monitor 2026-09-01,
+// moved here from kol-hardware 2026-10-01 with the controls that arm it).
+
+const HOLD_MS = 500
+const SLOP_PX = 6
+
+/* Arm a long-press on a touch pointerdown. Returns `{ move, cancel }`: feed
+ * pointermoves to `move` (past SLOP it disarms — that is a drag, not a hold),
+ * call `cancel` on pointerup. `fire` runs once when the hold lands. A mouse
+ * never arms — desktop keeps drag + ⌥-click and nothing else. */
+export function armLongPress(e, fire) {
+  if (e.pointerType !== 'touch') return { move: () => {}, cancel: () => {} }
+  const x = e.clientX, y = e.clientY
+  let t = setTimeout(() => { t = null; fire() }, HOLD_MS)
+  const cancel = () => { if (t) { clearTimeout(t); t = null } }
+  const move = (ev) => { if (t && Math.hypot(ev.clientX - x, ev.clientY - y) > SLOP_PX) cancel() }
+  return { move, cancel }
+}

package/src/utilities/mediaSearch.js

@@ -2,7 +2,7 @@
  * mediaSearch — the media library's search, on the KOL engine (`@kolkrabbi/kol-search`).
  *
  * Four places in the media pages each ran their own `key.toLowerCase().includes(q)` — the browse
- * filter, the ⌘K palette, the smart-folder text match, the picker's filter (apps review,
+ * filter, the ⌘K search modal, the smart-folder text match, the picker's filter (apps review,
  * 2026-09-29). One helper now, so the media search speaks the same language as every other KOL
  * search: several words must ALL match, `-word` must not, `"a phrase"`, `tag:x` / `#x`,
  * `kind:image` / `is:video`, `after:2026-09-01`. A plain substring still finds what it found.
@@ -24,7 +24,7 @@ const toItem = (o, nameOf) => ({
   o,
 })
 
-/** ranked hits, best first — the palette's order. `nameOf(o)` overrides the title (a display key). */
+/** ranked hits, best first — the search modal's order. `nameOf(o)` overrides the title (a display key). */
 export function rankMedia(objects, query, { nameOf, limit } = {}) {
   const q = String(query ?? '').trim()
   if (!q) return limit ? objects.slice(0, limit) : objects

package/src/utilities/tone.js

@@ -26,6 +26,12 @@ export const TONES = ['primary', 'secondary', 'inverted', 'outline', 'ghost', 'g
 export const toneClass = (tone) =>
   tone === 'inverse' ? 'kol-tone-sunken' : TONES.includes(tone) ? `kol-tone-${tone}` : ''
 
+/* THE SIX VARIANTS THAT WERE TONES (user ruling 2026-10-01). Button's `variant` named five grounds
+ * and a legacy alias of one; each is a tone under a second name — the theme's variant classes are
+ * aliases of the tone bundles. `variant` keeps `accent · danger · nav`; these six are deprecated
+ * aliases on the retirement ledger. `secondary` is the misleading one: it paints `inverted`. */
+export const VARIANT_TONE = { primary: 'primary', secondary: 'inverted', outline: 'outline', ghost: 'ghost', grey: 'grey', control: 'ghost' }
+
 /* the properties a bundle sets — Dropdown copies them from its trigger onto
  * the PORTALLED panel, which the cascade cannot reach */
 export const TONE_VARS = [

package/src/atoms/AudioPlayer.jsx

@@ -1,51 +0,0 @@
-/**
- * AudioPlayer — A native audio player with a label. the interactive audio atom: one native <audio> with the UA's
- * own control strip, and an optional label line above it.
- *
- * WHY IT EXISTS. Audio was the one media kind the design system had nothing for,
- * so every consumer hand-rolled a bare `<audio controls>` and inherited whatever
- * the browser painted. The MediaLibrary widening (kol-component 0.39.0) made
- * audio objects arrive — 116 sound files in `kol-vault-media` alone — and left
- * minting this as the open taxonomy call; this is that call made: an ATOM,
- * beside HlsVideo.
- *
- * THE CONTRAST WITH HlsVideo, which is the thing to read before touching either.
- * Same tier, same shape — one native media element, all layout via `className`,
- * no composition — and **inverted intent**. HlsVideo is deliberately inert:
- * `pointer-events: none`, `controls={false}`, plus the hardening set (no PiP, no
- * download, no fullscreen, no remote playback, no context menu). It is
- * decorative. This atom exists **to be operated**, so none of that hardening
- * crosses over, and `controls` is not a prop — an audio player without controls
- * is not a variant, it is a different component.
- *
- * The native strip is UA-painted and not themeable past `color-scheme`. Do not
- * reach for pseudo-element hacks; a branded transport would be a separate
- * `AudioTransport` molecule built on this atom.
- *
- * Layout is the call site's: the padding, the centring and the width that lived
- * in the consumer source are all call-site concerns and none of them are baked
- * in here.
- *
- * @param {string} src        audio URL; renders nothing when absent (the guard
- *                            style the other media atoms use)
- * @param {string} [label]    line above the player; the element is omitted entirely
- *                            when absent. Authored casing — no text-transform
- * @param {'none'|'metadata'|'auto'} [preload='metadata']  native preload hint
- * @param {string} [className] all layout/sizing (consumer-supplied)
- */
-export default function AudioPlayer({
-  src,
-  label,
-  preload = 'metadata',
-  className = '',
-  ...props
-}) {
-  if (!src) return null
-
-  return (
-    <figure className={`kol-audio-player flex flex-col gap-3 ${className}`.trim()}>
-      {label && <figcaption className="kol-mono-12 text-fg-48">{label}</figcaption>}
-      <audio src={src} preload={preload} controls className="w-full" {...props} />
-    </figure>
-  )
-}

package/src/molecules/AudioPreview.jsx

@@ -1,140 +0,0 @@
-/* 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)
- * @param {ReactNode} fallback   AudioTile — shown when the file carries no cover art (2026-09-23:
- *                               it was an empty square, so a WAV read as a missing file)
- */
-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, fallback = null }) {
-  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" /> : fallback && <div className="absolute inset-0 flex items-center justify-center">{fallback}</div>}
-      <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/AudioSheet.jsx

@@ -1,48 +0,0 @@
-import { useEffect, useState } from 'react'
-import usePlayback from '../hooks/usePlayback.js'
-import PlaybackBar, { clock } from './PlaybackBar.jsx'
-import QuickLookFrame from './QuickLookFrame.jsx'
-import FileIcon from '../atoms/FileIcon.jsx'
-import { readCover } from '../utilities/id3.js'
-
-/* taxonomy-ok: molecule — nests PlaybackBar + QuickLookFrame (relative) + FileIcon (atom). */
-
-function useCover(src) {
-  const [cover, setCover] = useState(null)
-  useEffect(() => {
-    let live = true
-    readCover(src).then((url) => { if (live) setCover(url) }).catch(() => {})
-    return () => { live = false }
-  }, [src])
-  return cover
-}
-
-/**
- * AudioSheet — Audio in the preview window. audio in the Quick Look window, Finder's layout (user 2026-09-23, the reference
- * shot): the artwork square left, `Time: mm:ss` beside it, the QuickTime bar docked in the
- * window's footer. Artwork = the file's embedded ID3 `APIC` cover (`readCover`); no cover →
- * `FileIcon`, the same page the tile shows. The `cover` / `sheet` variants are gone — there is
- * one window now, and it is the sheet.
- *
- * @param {string}   src         the audio URL
- * @param {string}   ext         the extension, for the no-cover icon
- * @param {Function} onDuration  (seconds) => void once metadata lands
- * @param {Object}   frame       the window's header — `QuickLookFrame`'s title · meta · actions · onClose
- */
-export default function AudioSheet({ src, ext, onDuration, frame }) {
-  const { ref, handlers, bar } = usePlayback((el) => onDuration?.(el.duration))
-  const cover = useCover(src)
-  return (
-    <QuickLookFrame {...frame} footer={<PlaybackBar {...bar} docked />}>
-      <audio ref={ref} src={src} preload="metadata" {...handlers} />
-      <div className="kol-quicklook-audio">
-        <div className="kol-quicklook-art">
-          {cover
-            ? <img src={cover} alt="" className="w-full h-full object-cover" />
-            : <FileIcon ext={ext} glyph="music-note" className="w-[52%]" />}
-        </div>
-        <span className="kol-mono-16 text-meta">Time: <b className="text-strong">{clock(bar.duration)}</b></span>
-      </div>
-    </QuickLookFrame>
-  )
-}

package/src/molecules/VideoSheet.jsx

@@ -1,25 +0,0 @@
-import usePlayback from '../hooks/usePlayback.js'
-import PlaybackBar from './PlaybackBar.jsx'
-import QuickLookFrame from './QuickLookFrame.jsx'
-
-/* taxonomy-ok: molecule — nests PlaybackBar + QuickLookFrame (relative). */
-
-/**
- * VideoSheet — A video in the preview window. video in the Quick Look window: the frame at the video's own aspect ratio, the
- * QuickTime bar docked in the window's footer (2026-09-23 — it floated over the picture, which
- * made video the one kind whose controls sat on the media). No native controls; click on the
- * video toggles play; no autoplay (user 2026-09-23 — Quick Look opens paused), `playsInline`, `preload="metadata"`.
- *
- * @param {string}   src     the video URL
- * @param {string}   poster  the poster URL
- * @param {Function} onMeta  ({ w, h, len }) => void once metadata lands — the window's facts
- * @param {Object}   frame   the window's header — `QuickLookFrame`'s title · meta · actions · onClose
- */
-export default function VideoSheet({ src, poster, onMeta, frame }) {
-  const { ref, handlers, bar } = usePlayback((el) => onMeta?.({ w: el.videoWidth, h: el.videoHeight, len: el.duration }))
-  return (
-    <QuickLookFrame {...frame} footer={<PlaybackBar {...bar} docked />}>
-      <video ref={ref} src={src} poster={poster} playsInline preload="metadata" className="kol-quicklook-media" onClick={bar.onToggle} {...handlers} />
-    </QuickLookFrame>
-  )
-}