@kolkrabbi/kol-component 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "@floating-ui/react": "^0.27.19",
     "embla-carousel-react": "^8.6.0",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-icons": "^0.16.0"
+    "@kolkrabbi/kol-icons": "^0.17.0"
   },
   "peerDependencies": {
     "framer-motion": "^12.0.0",

package/src/atoms/AudioPlayer.jsx

@@ -0,0 +1,51 @@
+/**
+ * AudioPlayer — 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/index.js

@@ -33,6 +33,10 @@ export { default as ExitPreview } from './utilities/ExitPreview.jsx'
 export { default as Figure } from './atoms/Figure.jsx'
 export { default as FullscreenOverlay } from './utilities/FullscreenOverlay.jsx'
 export { default as HlsVideo } from './atoms/HlsVideo.jsx'
+/* AudioPlayer — HlsVideo's opposite number: same tier and shape, inverted
+ * intent (built to be operated, not decorative). See its header before editing
+ * either one. */
+export { default as AudioPlayer } from './atoms/AudioPlayer.jsx'
 export { default as Input } from './atoms/Input.jsx'
 export { default as Label } from './atoms/Label.jsx'
 export { default as LabeledControl } from './molecules/LabeledControl.jsx'

package/src/organisms/ContentFilters.jsx

@@ -24,6 +24,7 @@ import IconFrame from '../atoms/IconFrame.jsx'
  * @param {Function} props.onFilterChange — optional callback when filters change
  * @param {Array} props.mutuallyExclusiveFilters — filter keys that should be mutually exclusive
  * @param {Array} props.customFilterKeys — filter keys handled by renderItem, not by ContentFilters
+ * @param {ElementType} props.iconComponent — icon seam (defaults to DS Icon; needs `filter` + `search`)
  */
 const ContentFilters = ({
   items,
@@ -44,8 +45,12 @@ const ContentFilters = ({
   searchKeys = ['label', 'name', 'title', 'type'],
   headerActions,
   showCountOnlyWhenFiltering = false,
+  iconComponent,
   className = '',
 }) => {
+  /* Icon seam — consumers on a local icon shelf pass their own component
+   * rather than being forced onto the DS set. Needs `filter` + `search`. */
+  const IconSeam = iconComponent || Icon
   const [activeFilters, setActiveFilters] = useState(new Set())
   const [isExpanded, setIsExpanded] = useState(false)
   const [internalViewMode, setInternalViewMode] = useState(defaultViewMode)
@@ -115,21 +120,38 @@ const ContentFilters = ({
     })
   }, [items, activeFilters, customFilterKeys, searchText, searchKeys])
 
+  /* THE FILTER VALUE IS A TAG — the atom's whole reason to exist ("a Tag with
+   * no handler is a Pill wearing the wrong name"). Three defects lived here
+   * until 2026-08-15, all of them working around the atom instead of using it:
+   *
+   *   variant="default"  — not a declared variant; `VARIANTS[v] ?? primary`
+   *                        silently rendered the FILLED chip. The outlined
+   *                        chip these want is `secondary`.
+   *   className border-* — hand-rolled active state beside the atom's own
+   *                        `active` prop, which is what drives `.is-active`.
+   *   <div onClick>      — the handler on a wrapper, so Tag rendered a <span>
+   *                        and the interactive chip was not interactive.
+   *
+   * Casing is the atom's too: `.kol-tag` carries `text-transform: uppercase`
+   * as the component tier's ONE documented exception to the no-casing law,
+   * because a filter value is data with no authoring site. Consumers must not
+   * uppercase these themselves. */
   const renderFilterGroup = (group) => (
-    <div key={group.key}>
+    <div key={group.key} className="flex flex-col gap-3">
       <h4 className="kol-helper-12 text-fg-48">{group.label}</h4>
-      <div className="flex flex-wrap gap-2 pt-3">
-        {group.values.map((value) => {
-          const filterKey = `${group.key}:${value}`
-          const isActive = activeFilters.has(filterKey)
-          return (
-            <div key={value} onClick={() => toggleFilter(group.key, value)}>
-              <Tag size="sm" variant="default" hash={false} className={isActive ? 'border-fg-32' : 'border-fg-08'}>
-                {value}
-              </Tag>
-            </div>
-          )
-        })}
+      <div className="flex flex-wrap gap-2">
+        {group.values.map((value) => (
+          <Tag
+            key={value}
+            size="sm"
+            variant="secondary"
+            hash={false}
+            active={activeFilters.has(`${group.key}:${value}`)}
+            onClick={() => toggleFilter(group.key, value)}
+          >
+            {value}
+          </Tag>
+        ))}
       </div>
     </div>
   )
@@ -158,7 +180,7 @@ const ContentFilters = ({
               aria-label="Toggle filters"
               style={{ background: 'transparent', border: 'none', cursor: 'pointer', color: 'inherit' }}
             >
-              <Icon name="filter" size={20} />
+              <IconSeam name="filter" size={20} />
             </button>
             <div
               className="flex items-center justify-center rounded-sm cursor-pointer hover:bg-fg-04 transition-colors"
@@ -186,7 +208,7 @@ const ContentFilters = ({
                   position: searchOpen ? 'absolute' : 'relative',
                 }}
               >
-                <Icon name="search" size={20} />
+                <IconSeam name="search" size={20} />
               </span>
               {searchOpen && (
                 <input
@@ -237,37 +259,47 @@ const ContentFilters = ({
 
       <Divider className="mb-4" />
 
-      {isExpanded && (
-        <div className="flex items-start gap-16 pb-4">
-          {filterGroups.map((group) => renderFilterGroup(group))}
-          {activeFilters.size > 0 && (
-            <button
-              type="button"
-              onClick={clearAllFilters}
-              className="kol-helper-12 transition-colors underline text-fg-48"
-              style={{ marginLeft: 'auto', background: 'transparent', border: 'none', cursor: 'pointer' }}
-            >
-              Clear all ({activeFilters.size})
-            </button>
+      {/* ONE ROW BELOW THE DIVIDER (user ruling 2026-08-15, four rounds of QA
+        * against a fork of this file). Filter groups are left-aligned COLUMNS —
+        * label above values — and appear only while the filter toggle is open.
+        * The layout strip is right-aligned and ALWAYS visible.
+        *
+        * `items-start` is load-bearing: it pins the strip to the label row so
+        * the values hang beneath it. The strip previously rendered in its own
+        * row AFTER this block, which is why expanding a filter group pushed it
+        * down the page — the defect that started the whole ticket. */}
+      {(layoutOptions || isExpanded) && (
+        <div className="flex items-start justify-between gap-16 pb-4">
+          <div className="flex items-start gap-16">
+            {isExpanded && filterGroups.map((group) => renderFilterGroup(group))}
+            {isExpanded && activeFilters.size > 0 && (
+              <button
+                type="button"
+                onClick={clearAllFilters}
+                className="kol-helper-12 transition-colors underline text-fg-48"
+                style={{ background: 'transparent', border: 'none', cursor: 'pointer' }}
+              >
+                Clear all ({activeFilters.size})
+              </button>
+            )}
+          </div>
+          {layoutOptions && (
+            <div className="flex items-center gap-4 flex-shrink-0">
+              {layoutOptions.map((opt) => (
+                <span
+                  key={opt.value}
+                  onClick={() => setLayout(opt.value)}
+                  className={`kol-helper-12 cursor-pointer select-none ${layout === opt.value ? 'text-fg-96' : 'text-fg-32 hover:text-fg-48'}`}
+                  style={{ letterSpacing: 1 }}
+                >
+                  {opt.label}
+                </span>
+              ))}
+            </div>
           )}
         </div>
       )}
 
-      {layoutOptions && (
-        <div className="flex items-center justify-end gap-4 mt-4">
-          {layoutOptions.map((opt) => (
-            <span
-              key={opt.value}
-              onClick={() => setLayout(opt.value)}
-              className={`kol-helper-12 cursor-pointer select-none ${layout === opt.value ? 'text-fg-96' : 'text-fg-32 hover:text-fg-48'}`}
-              style={{ letterSpacing: 1 }}
-            >
-              {opt.label}
-            </span>
-          ))}
-        </div>
-      )}
-
       <div className="mt-8" style={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0 }}>
         {renderItem(filteredItems, viewMode, layout)}
       </div>