@kolkrabbi/kol-shell 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "description": "KOL application shell — fixed 48px NavRail + AppShell layout root, PageShell/PageHeader scaffolds, ContentFilters catalog organism, GridCard, SettingsScaffold, WalkthroughPanel, ShortcutsOverlay. App chrome (kol-framework owns site chrome). Nav items, content, shortcuts and settings are consumer-injected. Sits above @kolkrabbi/kol-{theme,component,framework}.",
   "license": "MIT",

package/src/ContentFilters.jsx

@@ -1,4 +1,4 @@
-import { useState, useMemo, useRef, useEffect } from 'react'
+import { Fragment, useState, useMemo, useRef, useEffect } from 'react'
 import { Divider } from '@kolkrabbi/kol-component'
 import { Icon } from '@kolkrabbi/kol-icons'
 import TabStrip from './TabStrip.jsx'
@@ -27,6 +27,22 @@ import TabStrip from './TabStrip.jsx'
  * @param {Array} props.mutuallyExclusiveFilters - filter keys that self-clear
  * @param {Array} props.customFilterKeys - keys renderItem handles, not this organism
  * @param {ElementType} props.iconComponent - icon seam (defaults to DS Icon; needs `filter` + `search`)
+ * @param {Function} props.renderFilterValue - `(value, isActive, toggle) => node`, one filter value
+ * @param {string} props.labelClassName - REPLACES the group label's class (never stacks)
+ *
+ * **The two rendering seams (0.2.0).** How a filter value and a group label look
+ * is the consumer's call, not this organism's. Three publishes in one day went
+ * into re-ruling that here — outlined pills vs bare strip items vs chips — none
+ * of which is a design-system question: it is what a given app's filter bar
+ * should look like. `renderFilterValue` and `labelClassName` end that class of
+ * change without a publish.
+ *
+ * `labelClassName` REPLACES rather than stacks, per the 2026-07-30 law: two
+ * equal-specificity type classes on one element are decided by sheet order, so
+ * a stacked seam produces different renders in different consumers with no
+ * version difference. Same contract as ListingCard's `titleClassName`.
+ *
+ * Defaults reproduce 0.1.3 exactly — a bump moves nothing.
  */
 const ContentFilters = ({
   items,
@@ -47,6 +63,8 @@ const ContentFilters = ({
   headerActions,
   showCountOnlyWhenFiltering = false,
   iconComponent,
+  renderFilterValue,
+  labelClassName,
 }) => {
   const [activeFilters, setActiveFilters] = useState(new Set())
   const [isExpanded, setIsExpanded] = useState(false)
@@ -132,9 +150,10 @@ const ContentFilters = ({
     })
   }, [items, activeFilters, customFilterKeys, searchText, searchKeys])
 
-  // Filter values wear the LIST/GRID strip idiom, not Tag chips — user ruling
-  // 2026-08-15 ("TAGS should be same style as LIST and GRID"). Label and values
-  // sit on ONE line so the group shares the row with the layout strip.
+  // A group is a COLUMN: label on top, values beneath it (user ruling
+  // 2026-08-15). How a value and a label RENDER is the consumer's — three
+  // publishes in one day went into re-deciding that here, which is the defect
+  // the seams below end. Defaults are 0.1.3 exactly, so nothing moves on bump.
   const renderFilterGroup = (group) => {
     const prefix = `${group.key}:`
     const selected = new Set(
@@ -144,16 +163,31 @@ const ContentFilters = ({
     )
 
     return (
-      <div key={group.key} className="flex items-center gap-4">
-        <h4 className="kol-helper-12 text-fg-48">{group.label}</h4>
-        <TabStrip
-          options={group.values.map((v) => ({ value: v, label: v }))}
-          value={selected}
-          onChange={(v) => toggleFilter(group.key, v)}
-          size={12}
-          tracked
-          className="gap-4"
-        />
+      <div key={group.key} className="flex flex-col gap-3">
+        <h4
+          className={labelClassName || 'kol-helper-12 text-fg-32'}
+          style={labelClassName ? undefined : { letterSpacing: 1 }}
+        >
+          {group.label}
+        </h4>
+        {renderFilterValue ? (
+          <div className="flex flex-wrap items-center gap-4">
+            {group.values.map((v) => (
+              <Fragment key={v}>
+                {renderFilterValue(v, selected.has(v), () => toggleFilter(group.key, v))}
+              </Fragment>
+            ))}
+          </div>
+        ) : (
+          <TabStrip
+            options={group.values.map((v) => ({ value: v, label: v }))}
+            value={selected}
+            onChange={(v) => toggleFilter(group.key, v)}
+            size={12}
+            tracked
+            className="gap-4 flex-wrap"
+          />
+        )}
       </div>
     )
   }
@@ -238,19 +272,25 @@ const ContentFilters = ({
 
       <Divider className="mb-4" />
 
-      {/* ONE row BELOW the divider: filter groups on the LEFT (only while the
-          filter toggle is open), layout strip on the RIGHT and ALWAYS visible.
-          0.1.1 read "at the divider level" as the header row above it — the
-          filer's verdict corrected that; the strip never belongs in the header
+      {/* BELOW the divider: filter groups as left-aligned COLUMNS (only while
+          the filter toggle is open), layout strip RIGHT and ALWAYS visible.
+          `items-start` is load-bearing — it pins the strip to the label row, so
+          the strip and the group labels read as one line and the values hang
+          beneath. 0.1.1 read "at the divider level" as the header row above the
+          divider; the strip never belongs in the header
           (ShellHeaderFilterRefinements, 2026-08-15). */}
       {(layoutOptions || isExpanded) && (
-        <div className="flex items-center justify-between gap-16 mb-4">
-          <div className="flex items-center gap-16">
+        <div className="flex items-start justify-between gap-16 mb-4">
+          <div className="flex items-start gap-16">
             {isExpanded && filterGroups.map((group) => renderFilterGroup(group))}
             {isExpanded && activeFilters.size > 0 && (
+              // Strip rest recipe, not its own ink — this button shares the line
+              // with the labels and values, and that line carries exactly TWO
+              // ink states (user ruling 2026-08-15: "we are not maintaining 3
+              // opacity states for one line in a component").
               <button
                 onClick={clearAllFilters}
-                className="kol-helper-12 transition-colors underline text-fg-48"
+                className="kol-helper-12 transition-colors underline text-fg-32 hover:text-fg-48"
               >
                 Clear all ({activeFilters.size})
               </button>