@kolkrabbi/kol-component 0.92.0 → 0.93.0

package/package.json

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

@@ -0,0 +1,79 @@
+import { useEffect, useRef, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
+
+/* Promoted verbatim from showcase/src/sets/content-card-comparison.jsx
+ * (ContentFiltersCollection, kol-r2b2 2026-08-27) — the card's `size` slot:
+ * the size at rest, a download link on hover. `href` is the download. */
+/* The size string IS the download affordance: "2.4 MB" at rest, a download
+ * icon + "Download" on hover, no container of any kind.
+ *
+ * Both states sit in ONE grid cell so the meta row never reflows. The icon is
+ * CLIPPED at zero width at rest and opens to its box on hover, sliding left to
+ * right — so it reads as coming out from behind the word rather than fading in
+ * beside it. ONE duration and curve for every part and both directions — 500ms
+ * on the house curve `--kol-ease-house`, plus a 200ms delay on the icon so the
+ * word starts before the glyph. That delay is on the `group-hover:` variant,
+ * NOT the base — ENTRY only. With it on the base the exit inherited it too, so
+ * the glyph finished retracting at t=700 while the fade ended at t=500: it went
+ * invisible at full extension and never appeared to slide back.
+ *
+ * The glyph is NOT on `.kol-inline-control` — that chrome is for a control you
+ * click, and this one is inside the link rather than being it.
+ *
+ * Both hover parts ink on the OPACITY scale (`text-oq-80`), not an `fg-*` role:
+ * a stroke glyph on a flat fg colour reads wrong against the plate, and oq is
+ * what the rest of the chrome uses.
+ *
+ * ONE type class throughout — kol-mono-12. helper-12 is line-height 1 against
+ * mono's 16px, so swapping classes moved the line. Only the ink changes.
+ */
+export default function SizeOrDownload({
+  children,
+  href,
+  icon = 'download',
+  confirmIcon = 'check',
+  label = 'Download',
+  confirmLabel = 'Downloaded',
+}) {
+  /* The confirm is LOCAL, not ActionButton's — this affordance is the link
+   * itself, not an icon control sitting inside one. */
+  const [done, setDone] = useState(false)
+  const timer = useRef(null)
+  useEffect(() => () => clearTimeout(timer.current), [])
+
+  const click = (event) => {
+    /* a real `href` downloads; without one the click is the confirm alone */
+    if (!href) event.preventDefault()
+    clearTimeout(timer.current)
+    setDone(true)
+    timer.current = setTimeout(() => setDone(false), 2000)
+  }
+
+  return (
+    <a
+      href={href ?? '#'}
+      onClick={click}
+      aria-label={done ? confirmLabel : label}
+      className="group/size -mx-1 inline-grid items-end justify-items-start rounded-[var(--kol-radius-sm)] px-1 transition-colors duration-500 ease-[var(--kol-ease-house)] hover:bg-oq-04 active:bg-oq-08"
+    >
+      <span
+        className="kol-mono-12 text-oq-80 group-hover/size:opacity-0"
+        style={{ gridArea: '1 / 1', transition: 'opacity 500ms var(--kol-ease-house)' }}
+      >
+        {children}
+      </span>
+
+      <span
+        className="inline-flex items-center opacity-0 group-hover/size:opacity-100"
+        style={{ gridArea: '1 / 1', transition: 'opacity 500ms var(--kol-ease-house)' }}
+      >
+        <span className="inline-flex w-0 overflow-hidden transition-[width] duration-500 ease-[var(--kol-ease-house)] group-hover/size:w-[20px] group-hover/size:delay-200">
+          <span className="inline-flex h-4 w-4 -translate-x-2 items-center justify-center text-oq-80 transition-transform duration-500 ease-[var(--kol-ease-house)] group-hover/size:translate-x-0 group-hover/size:delay-200">
+            <Icon name={done ? confirmIcon : icon} size={16} />
+          </span>
+        </span>
+        <span className="kol-mono-12 text-oq-80">{label}</span>
+      </span>
+    </a>
+  )
+}

package/src/atoms/SortHeader.jsx

@@ -0,0 +1,30 @@
+import { Icon } from '@kolkrabbi/kol-icons'
+
+/**
+ * SortHeader — one sortable field: label + direction arrow. Strip chrome, verbatim
+ * from kol-r2b2's FileList (ContentFiltersCollection, 2026-08-27): `kol-helper-12`,
+ * uppercase label, `letterSpacing: 1`, `select-none`; active `text-oq-96`, rest
+ * `text-oq-48 hover:text-oq-64`. The arrow renders ONLY on the active field —
+ * arrow-down = ascending (1→N, A→Z, oldest→newest), arrow-up = descending.
+ *
+ * @param {ReactNode} label     the field's label (rendered uppercase)
+ * @param {boolean}   active    this field is the current sort
+ * @param {'asc'|'desc'} dir    direction, read only when active
+ * @param {Function}  onClick   () => void
+ * @param {string}    className extra classes on the button
+ */
+export default function SortHeader({ label, active = false, dir = 'asc', onClick, className = '', ...props }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      className={`kol-helper-12 flex items-center gap-1 select-none transition-colors ${active ? 'text-oq-96' : 'text-oq-48 hover:text-oq-64'} ${className}`.replace(/\s+/g, ' ').trim()}
+      style={{ letterSpacing: 1 }}
+      {...props}
+    >
+      {typeof label === 'string' ? label.toUpperCase() : label}
+      {active && <Icon name={dir === 'asc' ? 'arrow-down' : 'arrow-up'} size={10} />}
+    </button>
+  )
+}

package/src/atoms/ToggleCheckbox.jsx

@@ -1,9 +1,14 @@
 import React from 'react'
 
+/* `variant="media"` (ContentFiltersCollection, kol-r2b2 2026-08-27): inside a
+ * media frame the unchecked hairline vanished over a photo; this variant's
+ * UNCHECKED box carries the media control's solid plate (`--kol-oq-12`) so it
+ * reads over any image. Checked stays the white plate + black check. */
 const ToggleCheckbox = ({
   label,
   checked = false,
   onChange,
+  variant = 'default',
   className = '',
   hint,
   ...props
@@ -15,7 +20,7 @@ const ToggleCheckbox = ({
 
   return (
     <label
-      className={`toggle-checkbox ${checked ? 'is-active' : ''} ${className}`.trim()}
+      className={`toggle-checkbox ${variant === 'media' ? 'toggle-checkbox--media' : ''} ${checked ? 'is-active' : ''} ${className}`.replace(/\s+/g, ' ').trim()}
       {...props}
     >
       <input

package/src/index.js

@@ -23,6 +23,9 @@ export { default as Avatar } from './atoms/Avatar.jsx'
 export { default as Badge } from './atoms/Badge.jsx'
 export { default as Button } from './atoms/Button.jsx'
 export { default as ActionButton } from './atoms/ActionButton.jsx'
+export { default as SizeOrDownload } from './atoms/SizeOrDownload.jsx'
+export { default as SortHeader } from './atoms/SortHeader.jsx'
+export { default as SortControls } from './molecules/SortControls.jsx'
 export { default as CopyButton } from './molecules/CopyButton.jsx'
 export { default as CurveOverlay } from './atoms/CurveOverlay.jsx'
 export { default as Divider } from './atoms/Divider.jsx'

package/src/molecules/ContentCard.jsx

@@ -101,6 +101,7 @@ export default function ContentCard({
   ring,
   zoom,
   control,
+  controlStart,
   actions,
   expanded = false,
   expandedContent,
@@ -199,6 +200,12 @@ export default function ContentCard({
    * what MediaCard hardcodes as a download link plus a select checkbox, and
    * the reason its media library could not migrate onto ContentCard. */
   const controlNode = control ? <div className="kol-frame-control">{control}</div> : null
+  /* The frame's OTHER corner — top-left — for a second control (kol-r2b2
+   * 2026-08-27: the select indicator beside the download chip). Port note:
+   * becomes `.kol-frame-control--start` in kol-theme; inline until then. */
+  const controlStartNode = controlStart
+    ? <div className="kol-frame-control kol-frame-control--top-left">{controlStart}</div>
+    : null
 
 
   const body =
@@ -208,6 +215,7 @@ export default function ContentCard({
         <div className="relative">
           <ContentMedia ratio={r} {...mediaProps}>{media}</ContentMedia>
           {controlNode}
+          {controlStartNode}
         </div>
         {textNode}
       </>
@@ -216,6 +224,7 @@ export default function ContentCard({
         <div className="flex-1 min-w-0 min-h-0 relative overflow-hidden" style={expanded ? { flex: '0 0 50%' } : undefined}>
           <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
           {controlNode}
+          {controlStartNode}
         </div>
         {expanded ? (
           <div
@@ -231,6 +240,7 @@ export default function ContentCard({
         <div className="relative h-full">
           <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
           {controlNode}
+          {controlStartNode}
         </div>
         {/* the plate is INVERSE and hidden until hover — `kol-card-drawer` owns
           * the reveal so the transition sits with the rest of the chrome */}
@@ -242,6 +252,7 @@ export default function ContentCard({
         <div className="absolute" style={{ inset: 0 }}>
           <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
           {controlNode}
+          {controlStartNode}
         </div>
         {textNode}
       </>

package/src/molecules/ContentText.jsx

@@ -189,9 +189,15 @@ export default function ContentText({
    * so a card that wants the whole excerpt simply does not pass it. */
   const extra = (slot) => (slot === 'body' && clamp ? ` line-clamp-${clamp}` : '')
 
+  /* the title dim is BEHAVIOUR, not voice: a `titleClass` override replaces the
+   * ramp string whole (that is the seam's contract), and the hook was riding in
+   * that string — so Stack's uppercase display title lost its hover the moment
+   * it overrode the class (user 2026-08-27: "I had put A HOVER OPACITY drop,
+   * WHERE IS IT"). The hook is re-attached after the override. */
+  const hook = (slot) => (overrides[slot] && /\bkol-content-title-dim\b/.test(ramp[slot] ?? '') ? ' kol-content-title-dim' : '')
   const line = (slot) =>
     values[slot] == null ? null : (
-      <div key={slot} className={`${overrides[slot] ?? ramp[slot] ?? ''}${extra(slot)}`.trim()}>{values[slot]}</div>
+      <div key={slot} className={`${overrides[slot] ?? ramp[slot] ?? ''}${extra(slot)}${hook(slot)}`.trim()}>{values[slot]}</div>
     )
 
   /* RECURSIVE (2026-08-15) — an entry inside a line/between/group may itself be

package/src/molecules/SortControls.jsx

@@ -0,0 +1,31 @@
+import SortHeader from '../atoms/SortHeader.jsx'
+
+/**
+ * SortControls — the sortable-header group (ContentFiltersCollection, kol-r2b2
+ * 2026-08-27): `flex items-center gap-4` of SortHeaders. Click an inactive field
+ * → it becomes the sort, ASCENDING; click the active field → the direction
+ * flips. `onSort(field)` fires once per click — the consumer writes ONE state
+ * (two setter calls spreading the same stale state clobbered each other in the
+ * original; the fixed reference is in the ticket).
+ *
+ * @param {{value: string, label: ReactNode}[]} options  the fields
+ * @param {string}   sortBy    the active field's value
+ * @param {'asc'|'desc'} sortDir
+ * @param {Function} onSort    (field) => void
+ * @param {string}   className extra classes on the group
+ */
+export default function SortControls({ options = [], sortBy, sortDir = 'asc', onSort = () => {}, className = '' }) {
+  return (
+    <div className={`flex items-center gap-4 ${className}`.trim()}>
+      {options.map((opt) => (
+        <SortHeader
+          key={opt.value}
+          label={opt.label}
+          active={sortBy === opt.value}
+          dir={sortDir}
+          onClick={() => onSort(opt.value)}
+        />
+      ))}
+    </div>
+  )
+}

package/src/organisms/ContentFilters.jsx

@@ -25,6 +25,13 @@ import IconFrame from '../atoms/IconFrame.jsx'
  * @param {string} props.layout — controlled LIST/GRID value (kol-r2b2 2026-08-27: a consumer that persists
  *   layout per bucket needs the strip's value back; `defaultLayout` alone kept it internal)
  * @param {Function} props.onLayoutChange — (layout) => void, fires on every strip click
+ * @param {ReactNode} props.leadingActions — the LEFT half of the below-divider row, beside the
+ *   LIST/GRID strip (kol-r2b2 2026-08-27: the selection bar lives there, not on a row of its own)
+ * @param {ReactNode} props.belowActions — the RIGHT half of the below-divider row, beside the count
+ *   (kol-r2b2 2026-08-27: the sort group, once SELECT/FLAT moved up into the header strip)
+ * @param {ReactNode} props.trailingActions — the header's RIGHT slot, where the view strip sits
+ *   (kol-r2b2 2026-08-27: a consumer's own controls — sort, flat, select — belong there;
+ *   `headerActions` is the left group beside search and was never that)
  * @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
@@ -80,6 +87,9 @@ const ContentFilters = ({
   customFilterKeys = [],
   searchKeys = ['label', 'name', 'title', 'type'],
   headerActions,
+  trailingActions,
+  leadingActions,
+  belowActions,
   showCountOnlyWhenFiltering = false,
   iconComponent,
   className = '',
@@ -218,8 +228,10 @@ const ContentFilters = ({
       {layoutOptions.map((opt) => (
         <span
           key={opt.value}
-          onClick={() => setLayout(opt.value)}
-          className={`${layoutClassName} cursor-pointer select-none ${layout === opt.value ? stripActiveClassName : stripRestClassName}`}
+          onClick={opt.onClick ?? (() => setLayout(opt.value))}
+          aria-pressed={opt.active !== undefined ? !!opt.active : undefined}
+          title={opt.title}
+          className={`${layoutClassName} cursor-pointer select-none ${(opt.active ?? layout === opt.value) ? stripActiveClassName : stripRestClassName}`}
           style={{ letterSpacing: 1 }}
         >
           {opt.label}
@@ -359,7 +371,11 @@ const ContentFilters = ({
           )}
         </div>
 
-        <div className="flex items-center gap-8">
+        <div className="flex items-center gap-6">
+          {trailingActions}
+          {/* The divider between a consumer's trailing controls and the strip is
+            * the organism's, as it is on the left between title and icons. */}
+          {trailingActions && layoutPlacement === 'header' && layoutStrip && <Divider variant="vertical" />}
           {layoutPlacement === 'header' && layoutStrip}
           {/* RECENT / SAVED is the SAME STRIP as LIST / GRID, not a ViewToggle.
             * Read off kol-monitor's original (_tmp/2026-08-15-shell-adoption/
@@ -404,9 +420,10 @@ const ContentFilters = ({
         * while the groups and the count appear only with the panel open. Gating
         * the whole row on `isExpanded` hid the strip until you opened filters,
         * which is not a state anyone would guess at. */}
-      {(isExpanded || (layoutPlacement === 'below' && layoutStrip)) && (
+      {(isExpanded || (layoutPlacement === 'below' && layoutStrip) || leadingActions || belowActions) && (
         <div className="flex items-start justify-between gap-16">
           <div className="flex min-w-0 flex-1 items-start gap-16">
+            {leadingActions}
             {isExpanded && filterGroups.map((group) => renderFilterGroup(group))}
             {isExpanded && activeFilters.size > 0 && (
               <button
@@ -437,6 +454,7 @@ const ContentFilters = ({
               </span>
             )}
             {layoutPlacement === 'below' && layoutStrip}
+            {belowActions}
           </div>
         </div>
       )}