@kolkrabbi/kol-component 0.92.1 → 0.93.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.92.1",
+  "version": "0.93.1",
   "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/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,10 @@ 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)
@@ -84,6 +88,8 @@ const ContentFilters = ({
   searchKeys = ['label', 'name', 'title', 'type'],
   headerActions,
   trailingActions,
+  leadingActions,
+  belowActions,
   showCountOnlyWhenFiltering = false,
   iconComponent,
   className = '',
@@ -291,7 +297,12 @@ const ContentFilters = ({
             * states"); the span here was the same defect that promoted it. */}
           <h2 className="flex items-center gap-2">
             {titleIcon && <IconFrame name={titleIcon} variant="secondary" size="md" />}
-            <span className={titleClassName} style={titleUppercase ? { textTransform: 'uppercase', letterSpacing: 1 } : undefined}>{title}</span>
+            {/* `pr-4` by rule (ContentFiltersTitleGap, kol-website 2026-08-27): the
+              * divider sat 24px from the title's text edge but 32 from the
+              * icon glyphs (the frames carry 8px of air a side) and read pushed
+              * toward the title; 16px on the title side balances it. The seam
+              * `titleClassName` stays what it was. */}
+            <span className={`${titleClassName} pr-4`} style={titleUppercase ? { textTransform: 'uppercase', letterSpacing: 1 } : undefined}>{title}</span>
           </h2>
           <Divider variant="vertical" />
           <div className="flex items-center gap-1">
@@ -365,8 +376,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/
@@ -411,9 +425,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
@@ -444,6 +459,7 @@ const ContentFilters = ({
               </span>
             )}
             {layoutPlacement === 'below' && layoutStrip}
+            {belowActions}
           </div>
         </div>
       )}