@kolkrabbi/kol-component 0.97.2 → 0.98.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.97.2",
+  "version": "0.98.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/atoms/Tag.jsx

@@ -53,7 +53,8 @@ export default function Tag({
   icon,
   onRemove,
   onClick,
-  className = ''
+  className = '',
+  ...props
 }) {
   const isInteractive = !!(onClick || onRemove)
   const Element = isInteractive ? 'button' : 'span'
@@ -92,6 +93,7 @@ export default function Tag({
 
   return (
     <Element
+      {...props}
       type={isInteractive ? 'button' : undefined}
       className={classes}
       onClick={onClick}

package/src/index.js

@@ -141,6 +141,8 @@ export { default as SettingsPanel, SettingsRow, SettingsSwitch, SettingsChoice,
 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 { kindOf, extOf, isSystemFile, KINDS, KIND_LABEL } from './utilities/mediaKinds.js'
 export { default as RecordManager } from './organisms/RecordManager.jsx'
 export { default as SpectrumGrid } from './organisms/SpectrumGrid.jsx'
 export { default as Table } from './organisms/Table.jsx'

package/src/molecules/KindPreview.jsx

@@ -0,0 +1,93 @@
+import { useEffect, useState } from 'react'
+import AudioPlayer from '../atoms/AudioPlayer.jsx'
+import HlsVideo from '../atoms/HlsVideo.jsx'
+import CodeBlock from './CodeBlock.jsx'
+import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
+import { kindOf as defaultKindOf, extOf as defaultExtOf, KIND_LABEL } from '../utilities/mediaKinds.js'
+
+/* taxonomy-ok: molecule — nests the DS media atoms + CodeBlock (relative). */
+
+/**
+ * KindPreview — a preview for any kind of file: kol-r2b2's `KindPreview.jsx`,
+ * 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`, text / code → `CodeBlock` (language by extension;
+ * markdown as code — the DS has no markdown renderer in this tier), the rest
+ * → `AssetPlaceholder`. Images are the caller's (ColumnBrowser keeps its own
+ * `<img>` so it can read the dimensions). Text fetches cap at `textLimit`.
+ *
+ * @param {object}   o          the object — `{ key, contentType?, displayKey?, segmentCount? }`
+ * @param {Function} urlOf      (o) => string — the object's public URL (default: `o.url`)
+ * @param {string}   poster     a poster URL for HLS (the sibling image)
+ * @param {Function} kindOf · extOf   classification seams (defaults: the DS mediaKinds)
+ * @param {Object}   kindLabel  kind → label
+ * @param {number}   textLimit  bytes of text fetched for a preview (default 200 KB)
+ */
+const TEXT_LIMIT = 200 * 1024
+const LANG = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+  ts: 'typescript', tsx: 'typescript', json: 'json', yaml: 'yaml', yml: 'yaml',
+  css: 'css', html: 'html', sh: 'bash', py: 'python', md: 'markdown',
+  csv: 'text', tsv: 'text', pgn: 'text', txt: 'text', xml: 'xml',
+}
+
+function useTextContent(url, enabled, limit) {
+  const [result, setResult] = useState({ url: null, text: '', error: null, truncated: false })
+  useEffect(() => {
+    if (!enabled || !url) return undefined
+    let cancelled = false
+    const controller = new AbortController()
+    fetch(url, { signal: controller.signal })
+      .then(async (res) => {
+        if (!res.ok) throw new Error(`${res.status}`)
+        const size = Number(res.headers.get('content-length') || 0)
+        const body = await res.text()
+        if (cancelled) return
+        const truncated = body.length > limit || size > limit
+        setResult({ url, text: truncated ? body.slice(0, limit) : body, error: null, truncated })
+      })
+      .catch((e) => { if (!cancelled && e.name !== 'AbortError') setResult({ url, text: '', error: e.message, truncated: false }) })
+    return () => { cancelled = true; controller.abort() }
+  }, [url, enabled, limit])
+  return { ...result, loading: enabled && result.url !== url }
+}
+
+export default function KindPreview({ o, urlOf = (x) => x.url, poster, kindOf = defaultKindOf, extOf = defaultExtOf, kindLabel = KIND_LABEL, textLimit = TEXT_LIMIT }) {
+  const kind = kindOf(o)
+  const url = urlOf(o)
+  const ext = extOf(o.key)
+  const name = o.displayKey ?? o.key
+  const isText = kind === 'text' || kind === 'code'
+  const { loading, text, error, truncated } = useTextContent(url, isText, textLimit)
+
+  if (kind === 'playlist') {
+    return (
+      <div className="flex flex-col items-center gap-2">
+        <HlsVideo src={url} poster={poster} className="max-w-full max-h-[70vh] rounded" />
+        <span className="kol-mono-12 text-meta">HLS stream · playback is preview-only, no controls</span>
+      </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 (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>
+    return (
+      <div className="max-w-[80ch] max-h-[78vh] overflow-y-auto">
+        <CodeBlock code={text} language={LANG[ext] || 'text'} filename={name} />
+        {truncated && <p className="kol-mono-12 text-meta">truncated at {textLimit / 1024} KB</p>}
+      </div>
+    )
+  }
+  if (kind === 'segments') {
+    return <AssetPlaceholder category="HLS" name={`${o.segmentCount} segments`} note="STREAM CHUNKS" className="w-[420px] max-w-full" />
+  }
+  return <AssetPlaceholder category={kindLabel[kind] || 'file'} name={name} note={ext ? ext.toUpperCase() : 'FILE'} className="w-[420px] max-w-full" />
+}

package/src/molecules/ShellDrawer.jsx

@@ -151,7 +151,7 @@ export default function ShellDrawer({
         tabIndex={-1}
         className={`fixed inset-y-0 z-[200] flex max-w-full flex-col bg-surface-primary px-4 py-4 outline-none md:px-5 lg:px-6 ${backdrop ? 'shadow-2xl' : ''} ${
           side === 'right' ? 'right-0 border-l' : 'left-0 border-r'
-        } border-fg-08 ${width == null ? 'w-full' : ''} ${motionPanel} ${className}`}
+        } border-oq-08 ${width == null ? 'w-full' : ''} ${motionPanel} ${className}`}
         style={width != null ? { width: typeof width === 'number' ? `${width}px` : width } : undefined}
       >
         {/* closeSide="start": the reference sets the × glyph ~9px deeper than

package/src/organisms/ColumnBrowser.jsx

@@ -1,5 +1,7 @@
 import { useEffect, useRef, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
+import KindPreview from '../molecules/KindPreview.jsx'
+import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/mediaKinds.js'
 
 /**
  * ColumnBrowser — Finder-style Miller columns over a flat key space (kol-r2b2's
@@ -41,17 +43,13 @@ import { Icon } from '@kolkrabbi/kol-icons'
  * @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 {string}   className    extra classes on the browser
  */
 
-const defaultKindOf = (o) => {
-  const ct = o.contentType || ''
-  if (ct.startsWith('image/')) return 'image'
-  if (ct.startsWith('video/')) return 'video'
-  if (ct.startsWith('audio/')) return 'audio'
-  return 'file'
-}
-const DEFAULT_KIND_LABEL = { image: 'image', video: 'video', audio: 'audio', file: 'file' }
+/* the DS kinds (mediaKinds — kol-r2b2's classification, promoted 2026-08-27) */
+const defaultKindOf = dsKindOf
+const DEFAULT_KIND_LABEL = DS_KIND_LABEL
 const defaultFormatSize = (bytes) => {
   if (bytes == null) return '—'
   if (bytes < 1024) return `${bytes} B`
@@ -74,7 +72,7 @@ const defaultPartition = (objects, prefix) => {
 const isImage = (o) => (o.contentType || '').startsWith('image/')
 
 /* kol-icons has no `audio` glyph yet — audio rows wear `file` until it does */
-const COL_ICON = { image: 'image', video: 'video', audio: 'file' }
+const COL_ICON = { image: 'image', video: 'video', audio: 'file', playlist: 'video' }
 
 function Row({ icon, label, active, cursor = false, trailing, onClick, muted = false }) {
   return (
@@ -97,7 +95,7 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
   )
 }
 
-function Preview({ o, urlOf, kindOf, kindLabel, formatSize }) {
+function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
   // Pixel size comes from the loaded image itself — the bucket stores none.
   const [dims, setDims] = useState(null)
   const src = isImage(o) ? urlOf?.(o) : null
@@ -110,8 +108,12 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize }) {
   ]
   return (
     <div className="kol-column-browser-preview w-[320px] shrink-0 overflow-y-auto p-4 flex flex-col gap-4">
-      <div className="w-full aspect-square bg-fg-04 rounded flex items-center justify-center overflow-hidden">
-        {src ? (
+      {/* 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. */}
+      {src && !renderPreview ? (
+        <div className="w-full aspect-square bg-fg-04 rounded flex items-center justify-center overflow-hidden">
           <img
             src={src}
             alt=""
@@ -119,10 +121,15 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize }) {
             loading="lazy"
             onLoad={(e) => setDims({ w: e.target.naturalWidth, h: e.target.naturalHeight })}
           />
-        ) : (
-          <span className="kol-mono-12 text-fg-48">{kindLabel[kindOf(o)] || 'file'}</span>
-        )}
-      </div>
+        </div>
+      ) : (
+        <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 }) }}
+        >
+          {renderPreview ? renderPreview(o) : <KindPreview o={o} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} />}
+        </div>
+      )}
       <p className="kol-mono-12 text-fg-default break-all">{o.displayKey ?? o.key}</p>
       <dl className="flex flex-col gap-1">
         {facts.map(([k, v]) => (
@@ -148,6 +155,7 @@ export default function ColumnBrowser({
   kindLabel = DEFAULT_KIND_LABEL,
   formatSize = defaultFormatSize,
   partition = defaultPartition,
+  renderPreview,
   className = '',
 }) {
   const [picked, setPicked] = useState(null)
@@ -156,14 +164,6 @@ export default function ColumnBrowser({
    * outside prefix change fires null */
   const pick = (o) => { setPicked(o); onPick?.(o) }
   useEffect(() => { if (picked) pick(null) }, [prefix]) // eslint-disable-line react-hooks/exhaustive-deps
-  // Keyboard cursor: which column, which row. Clicks keep it in sync.
-  const [cursor, setCursor] = useState({ col: 0, idx: 0 })
-  /* the cursor is NOT drawn until the keyboard is used (ColumnBrowserCursorStart,
-   * kol-r2b2 2026-08-27): at rest it sat on row 0 beside the open folder and
-   * read as a second selection. Arrows arm it; a click seeds it. */
-  const [cursorActive, setCursorActive] = useState(false)
-  const rootRef = useRef(null)
-
   const levelsOf = (pfx) => {
     const out = ['']
     if (pfx) {
@@ -176,6 +176,27 @@ export default function ColumnBrowser({
     const { folders, files } = partition(objects.filter((o) => o.key.startsWith(level)), level)
     return [...folders.map((f) => ({ type: 'folder', name: f })), ...files.map((o) => ({ type: 'file', o }))]
   }
+  // Keyboard cursor: which column, which row. Clicks keep it in sync.
+  /* SEEDED on the open folder of the deepest column that has one (Finder's
+   * start — ColumnBrowserCursorSeed, kol-r2b2 2026-08-27): with a deep `prefix`
+   * the first ↓ used to act in column 0. Re-seeded when `prefix` changes; the
+   * internal moves land on the same spot, so nothing jumps. */
+  const seedCursor = (pfx) => {
+    const lv = levelsOf(pfx)
+    if (lv.length < 2) return { col: 0, idx: 0 }
+    const col = lv.length - 2
+    const opened = lv[col + 1].slice(lv[col].length)
+    const idx = itemsAt(lv[col]).findIndex((it) => it.type === 'folder' && it.name === opened)
+    return { col, idx: Math.max(0, idx) }
+  }
+  const [cursor, setCursor] = useState(() => seedCursor(prefix))
+  useEffect(() => { setCursor(seedCursor(prefix)) }, [prefix, objects.length]) // eslint-disable-line react-hooks/exhaustive-deps
+  /* the cursor is NOT drawn until the keyboard is used (ColumnBrowserCursorStart,
+   * kol-r2b2 2026-08-27): at rest it sat on row 0 beside the open folder and
+   * read as a second selection. Arrows arm it; a click seeds it. */
+  const [cursorActive, setCursorActive] = useState(false)
+  const rootRef = useRef(null)
+
   const land = (level, item) => {
     if (!item) return
     if (item.type === 'folder') { pick(null); onPrefix(level + item.name) }
@@ -198,6 +219,9 @@ export default function ColumnBrowser({
     const items = itemsAt(lv[col])
     if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
       const idx = Math.max(0, Math.min(items.length - 1, cursor.idx + (e.key === 'ArrowDown' ? 1 : -1)))
+      /* an arrow that did not move the cursor does nothing — re-landing on an
+       * open folder re-fired onPrefix (ColumnBrowserCursorSeed) */
+      if (idx === cursor.idx && col === cursor.col) return
       setCursor({ col, idx })
       land(lv[col], items[idx])
     } else if (e.key === 'ArrowRight') {
@@ -294,7 +318,7 @@ export default function ColumnBrowser({
           </ul>
         )
       })}
-      {shown && <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} />}
+      {shown && <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} renderPreview={renderPreview} />}
     </div>
   )
 }

package/src/organisms/SettingsPanel.jsx

@@ -1,4 +1,5 @@
 import Button from '../atoms/Button.jsx'
+import Tag from '../atoms/Tag.jsx'
 import SegmentedToggle from '../atoms/SegmentedToggle.jsx'
 import ToggleSwitch from '../atoms/ToggleSwitch.jsx'
 import ShellDrawer from '../molecules/ShellDrawer.jsx'
@@ -54,13 +55,17 @@ export default function SettingsPanel({
 }) {
   const header = (
     <div className="flex min-w-0 flex-col">
-      {title && <span className="kol-mono-12 text-emphasis">{title}</span>}
-      {subtitle && <span className="kol-mono-10 text-meta">{subtitle}</span>}
+      {/* THE APP REGISTER (SettingsPanelChromeAndColumnPreview, kol-r2b2 2026-08-27 —
+        * user: "all wrong font styles"): the collection beside the panel is the
+        * reference — helper-14 uppercase titles, the eyebrow for section labels,
+        * mono-12 rows and hints. No mono-10 anywhere. */}
+      {title && <span className="kol-helper-14 uppercase text-emphasis">{title}</span>}
+      {subtitle && <span className="kol-mono-12 text-meta">{subtitle}</span>}
     </div>
   )
   const body = (
     <>
-      {intro && <p className="kol-mono-10 text-meta">{intro}</p>}
+      {intro && <p className="kol-mono-12 text-meta">{intro}</p>}
       <div className="flex flex-col gap-5">{children}</div>
       {footer && <div className="mt-2">{footer}</div>}
     </>
@@ -102,8 +107,8 @@ export function SettingsRow({ label, hint, children }) {
   return (
     <div className="grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-6 py-1">
       <div className="flex min-w-0 flex-col">
-        <span className="kol-mono-12 text-body">{label}</span>
-        {hint && <span className="kol-mono-10 text-meta">{hint}</span>}
+        <span className="kol-mono-12 text-emphasis">{label}</span>
+        {hint && <span className="kol-mono-12 text-meta">{hint}</span>}
       </div>
       <div className="shrink-0">{children}</div>
     </div>
@@ -132,10 +137,10 @@ export function SettingsChoice({ options = [], value, onChange, ariaLabel }) {
   return <SegmentedToggle size="sm" value={value} onChange={onChange} options={opts} ariaLabel={ariaLabel} />
 }
 
-/* The toggle-chip pattern — `.kol-control` sm, filled when on, meta ink when
- * off (ViewToggle's text variant wears the same string; MediaLibrary's kind
- * chips too). ponytail: a `ControlChip` atom is the upgrade if a third
- * consumer types this. */
+/* The chips are the DS `Tag` ("the tag ticket" — SettingsPanelChromeAndColumnPreview,
+ * user 2026-08-27: same chrome as Tag everywhere else, not a third look): `md`
+ * (helper-12), `inverse` when on, `secondary` when off, as a button. The old
+ * `.kol-control` string stays exported for consumers that typed it. */
 export const CHIP_CLS = 'kol-control kol-control-sm kol-mono-12'
 export const chipCls = (on) => `${CHIP_CLS} ${on ? 'kol-control--filled' : 'text-meta hover:text-emphasis'}`
 
@@ -151,16 +156,18 @@ export function SettingsChipRow({ options = [], selected = [], onToggle }) {
   return (
     <div className="flex flex-wrap gap-1">
       {options.map((o) => (
-        <button
+        <Tag
           key={String(o.value)}
-          type="button"
+          size="md"
+          hash={false}
+          variant={on.has(o.value) ? 'inverse' : 'secondary'}
+          active={on.has(o.value)}
           aria-pressed={on.has(o.value)}
           onClick={() => onToggle?.(o.value)}
-          className={chipCls(on.has(o.value))}
         >
           {o.label ?? String(o.value)}
           {o.count > 0 && <span className="text-meta"> {o.count}</span>}
-        </button>
+        </Tag>
       ))}
     </div>
   )
@@ -170,7 +177,7 @@ export function SettingsChipRow({ options = [], selected = [], onToggle }) {
 export function SettingsFooter({ customised = false, onReset, resetLabel = 'Reset to defaults' }) {
   return (
     <div className="flex items-center justify-between">
-      <span className="kol-mono-10 text-meta">{customised ? 'customised' : 'defaults'}</span>
+      <span className="kol-mono-12 text-meta">{customised ? 'customised' : 'defaults'}</span>
       {onReset && <Button variant="ghost" size="sm" onClick={onReset}>{resetLabel}</Button>}
     </div>
   )

package/src/utilities/mediaKinds.js

@@ -0,0 +1,48 @@
+/* Media classification — kol-r2b2's `lib/media.js` kinds, promoted 2026-08-27
+ * (SettingsPanelChromeAndColumnPreview) so ColumnBrowser and KindPreview
+ * classify the same way the app does. contentType is unreliable for text /
+ * code (B2 hands back application/octet-stream), so the extension decides. */
+
+const EXT_KINDS = {
+  json: 'text', yaml: 'text', yml: 'text', txt: 'text', md: 'text', csv: 'text',
+  tsv: 'text', pgn: 'text', xml: 'text', svg: 'image',
+  js: 'code', mjs: 'code', cjs: 'code', ts: 'code', jsx: 'code', tsx: 'code',
+  css: 'code', html: 'code', sh: 'code', py: 'code',
+  m3u8: 'playlist',
+  woff: 'font', woff2: 'font', ttf: 'font', otf: 'font',
+  zip: 'archive', gz: 'archive', tar: 'archive', rar: 'archive', '7z': 'archive',
+}
+
+export function extOf(key = '') {
+  const base = key.slice(key.lastIndexOf('/') + 1)
+  const dot = base.lastIndexOf('.')
+  return dot === -1 ? '' : base.slice(dot + 1).toLowerCase()
+}
+
+const SYSTEM_NAMES = new Set(['.ds_store', 'thumbs.db', 'desktop.ini', '.bzempty'])
+export function isSystemFile(key = '') {
+  return SYSTEM_NAMES.has(key.slice(key.lastIndexOf('/') + 1).toLowerCase())
+}
+
+export function kindOf(o) {
+  if (o.forcedKind) return o.forcedKind
+  if (isSystemFile(o.key)) return 'system'
+  const ct = o.contentType || ''
+  if (ct.startsWith('image/')) return 'image'
+  if (ct.startsWith('video/')) return 'video'
+  if (ct.startsWith('audio/')) return 'audio'
+  const ext = extOf(o.key)
+  if (EXT_KINDS[ext]) return EXT_KINDS[ext]
+  if (ct.startsWith('text/')) return 'text'
+  if (ct.startsWith('font/')) return 'font'
+  if (ct === 'application/json') return 'text'
+  return 'other'
+}
+
+export const KINDS = ['image', 'video', 'audio', 'text', 'code', 'playlist', 'font', 'archive', 'other']
+
+export const KIND_LABEL = {
+  image: 'image', video: 'video', audio: 'audio', text: 'text', code: 'code',
+  playlist: 'HLS', font: 'font', archive: 'archive', segments: 'HLS segments',
+  system: 'system', other: 'file',
+}