@kolkrabbi/kol-component 0.216.0 → 0.218.0

package/src/organisms/SettingsPanel.jsx

@@ -6,6 +6,7 @@ import LabeledControl from '../molecules/LabeledControl.jsx'
 import ToggleSwitch from '../atoms/ToggleSwitch.jsx'
 import ShellDrawer from '../molecules/ShellDrawer.jsx'
 import FullscreenOverlay from '../utilities/FullscreenOverlay.jsx'
+import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
  * SettingsPanel — a settings surface for the thing you are looking at: you
@@ -110,7 +111,8 @@ export default function SettingsPanel({
  * uppercase label (`kol-helper-10` tracked, meta ink) in a 160px column, the
  * control fills the rest. A switch sits at the far right (`align="end"`, the
  * default); a dropdown fills the row (`align="fill"`). No hint sentences on the
- * page — `hint` rides the control's `title`. `labelWidth="auto"` passes through
+ * page — `hint` rides the control's DS `Tooltip` (a native `title` until
+ * 2026-09-22, kol-client-olina). `labelWidth="auto"` passes through
  * to LabeledControl: the label flexes and truncates, the control hugs — for a
  * row living in a column narrower than the 160px label default
  * (SettingsShortcutsComboOverflow, kol-monitor 2026-09-01).
@@ -118,24 +120,28 @@ export default function SettingsPanel({
 export function SettingsRow({ label, hint, align = 'end', labelWidth = 160, children }) {
   return (
     <LabeledControl inline label={typeof label === 'string' ? label.toUpperCase() : label} labelWidth={labelWidth}>
-      <span title={hint} className={`inline-flex w-full ${align === 'fill' ? '' : 'justify-end'}`.trim()}>{children}</span>
+      {hint
+        ? <Tooltip label={hint} triggerClassName={`inline-flex w-full ${align === 'fill' ? '' : 'justify-end'}`.trim()}>{children}</Tooltip>
+        : <span className={`inline-flex w-full ${align === 'fill' ? '' : 'justify-end'}`.trim()}>{children}</span>}
     </LabeledControl>
   )
 }
 
 /** SettingsSwitch — the row's on/off control: the DS ToggleSwitch, bare, sm.
- *  `disabledHint` rides `title` so a switch that cannot act says why. */
+ *  `disabledHint` rides a DS `Tooltip` so a switch that cannot act says why;
+ *  inside a row's `hint` it wins while hovered, as the native `title` did. */
 export function SettingsSwitch({ on = false, onChange, disabled = false, disabledHint, label, title }) {
-  return (
+  const tip = title ?? (disabled ? disabledHint : undefined)
+  const toggle = (
     <ToggleSwitch
       size="sm"
       checked={on}
       onChange={onChange}
       disabled={disabled}
-      title={title ?? (disabled ? disabledHint : undefined)}
       aria-label={label}
     />
   )
+  return tip ? <Tooltip label={tip}>{toggle}</Tooltip> : toggle
 }
 
 /** LabeledControlSection — a section of LabeledControls: the EYEBROW
@@ -253,7 +259,11 @@ export function SettingsFooter({ onReset, resetLabel = 'Reset to defaults', chil
       <Divider />
       <div className="flex justify-end items-center gap-2">
         {children}
-        {onReset && <IconFrame name="refresh" variant="primary" size="sm" onClick={onReset} title={resetLabel} aria-label={resetLabel} />}
+        {onReset && (
+          <Tooltip label={resetLabel}>
+            <IconFrame name="refresh" variant="primary" size="sm" onClick={onReset} aria-label={resetLabel} />
+          </Tooltip>
+        )}
       </div>
     </div>
   )

package/src/utilities/FullscreenOverlay.jsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef } from 'react'
+import { pushLayer, popLayer, isTopLayer } from './layerStack.js'
 import CloseButton from './CloseButton.jsx'
 
 /**
@@ -36,6 +37,11 @@ export default function FullscreenOverlay({
    * caller should have to know to put focus in it. A plain `<div ref>` always
    * works. */
   initialFocus,
+  /* A DIM BACKDROP INSTEAD OF THE SURFACE (user 2026-09-23, on Quick Look: *"its overlay, not a
+   * black background … just dim the background slightly"*). The flat surface is still the default
+   * — that is the 2026-08-27 ruling, made because a wash read as a halo around a lightboxed image
+   * — so this is opt-in per overlay rather than a reversal for every consumer of the component. */
+  scrim = false,
   children,
 }) {
   const sheetRef = useRef(null)
@@ -44,10 +50,17 @@ export default function FullscreenOverlay({
    * the same trap ShellDrawer carries; before this a Tab from the overlay
    * walked into the page underneath). Focus moves into the sheet on open and
    * back to the opener on close. */
+  /* `onClose` through a ref: an inline handler is a new function every render, and with it in the
+   * deps the effect re-ran on every render — re-pushing this layer to the TOP of the stack and
+   * re-stealing focus while a sheet above it was open. */
+  const onCloseRef = useRef(onClose)
+  onCloseRef.current = onClose
   useEffect(() => {
     if (!open) return
+    const layer = pushLayer()
     const onKey = (e) => {
-      if (e.key === 'Escape') { onClose?.(); return }
+      if (!isTopLayer(layer)) return
+      if (e.key === 'Escape') { onCloseRef.current?.(); return }
       if (e.key !== 'Tab') return
       const sheet = sheetRef.current
       if (!sheet) return
@@ -72,11 +85,12 @@ export default function FullscreenOverlay({
       : sheetRef.current
     target?.focus?.()
     return () => {
+      popLayer(layer)
       document.removeEventListener('keydown', onKey)
       document.body.style.overflow = prev
       if (prevFocus instanceof HTMLElement) prevFocus.focus()
     }
-  }, [open, onClose, initialFocus])
+  }, [open, initialFocus])
 
   if (!open) return null
 
@@ -90,7 +104,7 @@ export default function FullscreenOverlay({
   }
 
   return (
-    <div className="kol-overlay" role="dialog" aria-modal="true" onMouseDown={onBackdropClick}>
+    <div className={`kol-overlay${scrim ? ' kol-overlay-scrim' : ''}`} role="dialog" aria-modal="true" onMouseDown={onBackdropClick}>
       <div ref={sheetRef} tabIndex={-1} className="kol-overlay-sheet outline-none">
         {closeButton && (
           /* ONE close idiom (FullscreenOverlayCloseIdiom, kol-chess 2026-09-01,

package/src/utilities/Popover.jsx

@@ -1,4 +1,4 @@
-import { useState } from 'react'
+import { createContext, useContext, useState } from 'react'
 import { toneClass } from './tone.js'
 import {
   useFloating,
@@ -131,6 +131,11 @@ export function usePopover({
  *     <Button iconOnly="ptrn-checker" ... />
  *   </Tooltip>
  */
+/* A tooltip inside a tooltip's trigger (a disabled switch's reason inside its
+ * row's hint) hides the outer one while it is open, and hands it back on leave
+ * — the innermost wins, as the native `title` it replaced behaved. */
+const TooltipNest = createContext(null)
+
 export function Tooltip({
   label,
   shortcut,
@@ -140,9 +145,11 @@ export function Tooltip({
   triggerClassName = 'inline-flex',
 }) {
   const [open, setOpen] = useState(false)
+  const [covered, setCovered] = useState(false)
+  const parent = useContext(TooltipNest)
   const popover = usePopover({
-    open,
-    onOpenChange: setOpen,
+    open: open && !covered,
+    onOpenChange: (v) => { setOpen(v); parent?.(v) },
     placement,
     offset,
     role: 'tooltip',
@@ -158,7 +165,7 @@ export function Tooltip({
         {...popover.getReferenceProps()}
         className={triggerClassName}
       >
-        {children}
+        <TooltipNest.Provider value={setCovered}>{children}</TooltipNest.Provider>
       </span>
       <PopoverPanel
         popover={popover}

package/src/utilities/id3.js

@@ -43,6 +43,9 @@ function apic(tag, version) {
 }
 
 export function readCover(url) {
+  /* only a URL a browser can fetch — a placeholder scheme (a fixture, an unresolved key) is "no
+   * cover", not a console error */
+  if (!/^(https?:|data:|blob:|\/)/.test(String(url ?? ''))) return Promise.resolve(null)
   if (!covers.has(url)) {
     covers.set(url, (async () => {
       try {

package/src/utilities/layerStack.js

@@ -0,0 +1,18 @@
+/* THE LAYER STACK — which open overlay owns the keyboard (2026-09-23). Every overlay and drawer
+ * listened for Escape and Tab on `document`, so with a sheet open over a drawer one Escape closed
+ * BOTH, and two focus traps fought over Tab. Each layer pushes itself on open and pops on close;
+ * only the top one answers. Order is open order, which is stacking order. */
+const stack = []
+
+export function pushLayer() {
+  const id = {}
+  stack.push(id)
+  return id
+}
+
+export function popLayer(id) {
+  const i = stack.indexOf(id)
+  if (i !== -1) stack.splice(i, 1)
+}
+
+export const isTopLayer = (id) => stack[stack.length - 1] === id

package/src/utilities/mediaKinds.js

@@ -11,6 +11,9 @@ const EXT_KINDS = {
   js: 'code', mjs: 'code', cjs: 'code', ts: 'code', jsx: 'code', tsx: 'code',
   css: 'code', html: 'code', sh: 'code', py: 'code',
   m3u8: 'playlist',
+  /* A PDF IS ITS OWN KIND (user 2026-09-23: *"File I guess is pdf? weird name"*). It fell through
+   * to `other`, so the one document type with a real page-one preview was labelled "File". */
+  pdf: 'pdf',
   woff: 'font', woff2: 'font', ttf: 'font', otf: 'font',
   zip: 'archive', gz: 'archive', tar: 'archive', rar: 'archive', '7z': 'archive',
 }
@@ -42,12 +45,15 @@ export function kindOf(o) {
   return 'other'
 }
 
-export const KINDS = ['audio', 'video', 'image', 'markdown', 'json', 'yaml', 'text', 'code', 'playlist', 'font', 'archive', 'other']
+export const KINDS = ['audio', 'video', 'image', 'pdf', 'markdown', 'json', 'yaml', 'text', 'code', 'playlist', 'font', 'archive', 'other']
 
+/* A LABEL IS CAPITALISED, AN ACRONYM IS AN ACRONYM (user 2026-09-22). These read as values in a
+ * facts table ("Kind · Markdown") and beside them sit the MIME type and the filename, which are
+ * DATA and stay exactly as stored. The filter chips are unaffected — `.kol-tag` uppercases. */
 export const KIND_LABEL = {
-  image: 'image', video: 'video', audio: 'audio', markdown: 'markdown', json: 'JSON', yaml: 'YAML', text: 'text', code: 'code',
-  playlist: 'HLS', font: 'font', archive: 'archive', segments: 'HLS segments',
-  system: 'system', other: 'file',
+  image: 'Image', video: 'Video', audio: 'Audio', pdf: 'PDF', markdown: 'Markdown', json: 'JSON', yaml: 'YAML', text: 'Text', code: 'Code',
+  playlist: 'HLS', font: 'Font', archive: 'Archive', segments: 'HLS segments',
+  system: 'System', other: 'File',
 }
 
 /* The chips a bucket always shows (user ruling 2026-08-27): media, then the text