@kolkrabbi/kol-component 0.322.0 → 0.324.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.322.0",
+  "version": "0.324.0",
   "description": "The core component library",
   "license": "MIT",
   "type": "module",
@@ -26,8 +26,8 @@
     "embla-carousel-react": "^8.6.0",
     "pdfjs-dist": "^6.3.289",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-growth": "^0.4.0",
     "@kolkrabbi/kol-search": "^0.3.0",
+    "@kolkrabbi/kol-growth": "^0.4.0",
     "@kolkrabbi/kol-markdown": "^0.2.0"
   },
   "peerDependencies": {
@@ -39,7 +39,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.54.0"
+    "@kolkrabbi/kol-icons": "^0.56.0"
   },
   "files": [
     "src",

package/src/atoms/Button.jsx

@@ -12,7 +12,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *
  * @param {Object} props
  * @param {ReactNode} props.children - Button content
- * @param {'accent'|'danger'|'nav'|'tab'|'tab-filled'} props.variant - The intent; the GROUND is `tone`. `tab` is the tab chip (2026-10-02): quiet text at rest, a soft filled chip while `pressed`. `tab-filled` (2026-10-29) shows its chip at rest (oq-04), brighter on hover (oq-08) and brightest selected (oq-16). `float` (FloatingStyleAndSignInDemos; round 3's values, W16 2026-10-31) is the shape only: a capsule whose height and type step together — sm · md · lg 28 · 36 · 44 with 12 · 13 · 14 type and an 18 glyph, on `pointer: coarse` 36 · 44 · 52, 15 · 16 type and a 20 glyph; icon-only is the square; the ground stays the `tone`'s, the surface is the float it sits on. A composed float component (AppFloatNav, AccountForm's box) passes it, a consumer never sets it by hand. `primary · secondary · outline · ghost · grey · control` are deprecated aliases of tones (2026-10-01, on the retirement ledger): pass `tone` — `secondary` is `tone="inverted"`, `control` is `tone="ghost"`, the rest keep their name. Visual variant. UNSET (the default) inherits the tone of the nearest `kol-tone-*` wrapper, else renders primary; the five ground variants are aliases of `tone`. `danger` is the destructive treatment (--ui-error fill); `nav` is the chrome rung — transparent, oq-64 ink, one step brighter than `ghost`; `control` is an alias for `ghost` (legacy call-sites).
+ * @param {'accent'|'danger'|'nav'|'tab'|'tab-filled'|'bare'} props.variant - `bare` is a pressable surface with no button chrome (a tile, a bar row — the caller draws it). The intent; the GROUND is `tone`. `tab` is the tab chip (2026-10-02): quiet text at rest, a soft filled chip while `pressed`. `tab-filled` (2026-10-29) shows its chip at rest (oq-04), brighter on hover (oq-08) and brightest selected (oq-16). `float` (FloatingStyleAndSignInDemos; round 3's values, W16 2026-10-31) is the shape only: a capsule whose height and type step together — sm · md · lg 28 · 36 · 44 with 12 · 13 · 14 type and an 18 glyph, on `pointer: coarse` 36 · 44 · 52, 15 · 16 type and a 20 glyph; icon-only is the square; the ground stays the `tone`'s, the surface is the float it sits on. A composed float component (AppFloatNav, AccountForm's box) passes it, a consumer never sets it by hand. `primary · secondary · outline · ghost · grey · control` are deprecated aliases of tones (2026-10-01, on the retirement ledger): pass `tone` — `secondary` is `tone="inverted"`, `control` is `tone="ghost"`, the rest keep their name. Visual variant. UNSET (the default) inherits the tone of the nearest `kol-tone-*` wrapper, else renders primary; the five ground variants are aliases of `tone`. `danger` is the destructive treatment (--ui-error fill); `nav` is the chrome rung — transparent, oq-64 ink, one step brighter than `ghost`; `control` is an alias for `ghost` (legacy call-sites).
  * @param {'xs'|'sm'|'md'|'lg'} props.size - Button size (default: 'md'); xs is the panel rung (ControlsXsRung, 2026-09-01) — kol-mono-8 in a 22px shell (20 icon-only), opt-in by prop
  * @param {string} props.iconLeft - Icon name to display on the left
  * @param {string} props.iconRight - Icon name to display on the right
@@ -65,6 +65,12 @@ const Button = ({
   tone = 'default',
   ...props
 }) => {
+  /* `variant="bare"` (MetricRebuild, 2026-10-31): a pressable SURFACE — a stat tile, a bar row, a column head — that
+   * draws itself. No kol-btn chrome (ground, size, type, radius); the button keeps its type, the KOL focus ring
+   * (`kol-menu-btn`, as MenuItem's rows) and `disabled`. For a control that looks like a button, use any other variant. */
+  if (variant === 'bare') {
+    return <button type={type} onClick={onClick} disabled={disabled} className={`kol-menu-btn ${className}`.trim()} style={style} {...props}>{children}</button>
+  }
   // Two ladders, split on whether a label sits beside the glyph. An icon-only
   // button is a solo glyph in a pinned square, so it takes SOLO (16/20/24) —
   // it took the text-adjacent ladder until component 0.20.0, which put a 14px

package/src/index.js

@@ -127,7 +127,8 @@ export { default as ContentCard } from './molecules/ContentCard.jsx'
 export { default as ContentRow } from './molecules/ContentRow.jsx'
 export { default as ContentItem } from './molecules/ContentItem.jsx'
 export { default as ContentCollection } from './organisms/ContentCollection.jsx'
-export { MenuItem, MenuDropdownItem, MenuDropdownDivider, MenuDropdownNest } from './molecules/MenuItem.jsx'
+export { MenuItem, MenuRow, MenuDivider, MenuFlyout, MenuDropdownItem, MenuDropdownDivider, MenuDropdownNest } from './molecules/MenuItem.jsx'
+export { Menu, MenuTrigger, MenuPanel, MenuLabel, MenuFilter, MenuDatePicker, MenuMore } from './molecules/Menu.jsx'
 export { MenuPopover } from './molecules/MenuPopover.jsx'
 export { ModalProvider, useModal, Dialog } from './molecules/Modal.jsx'
 export { default as Combobox } from './molecules/Combobox.jsx'

package/src/molecules/Dropdown.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { toneClass, TONE_VARS } from '../utilities/tone.js'
 import { Icon } from '@kolkrabbi/kol-icons'
-import { MenuDropdownItem, MenuDropdownDivider } from './MenuItem.jsx'
+import { MenuRow, MenuDivider } from './MenuItem.jsx'
 import { PopoverPanel, usePopover } from '../utilities/Popover.jsx'
 import { glyphSize, indicatorSize } from '../hooks/glyphLadders.js'
 
@@ -32,6 +32,8 @@ import { glyphSize, indicatorSize } from '../hooks/glyphLadders.js'
  * explicit `size` prop (user law 2026-07-28 — desktop is sm, always, and
  * smaller viewports never resolve larger than desktop). The old auto-ramp
  * (lg ≥1024 / md ≥768 / sm below) is gone.
+ *
+ * An action menu (rows as data under a trigger) is `Menu` (the Menu* family, 2026-10-31), not this.
  */
 
 /* xs (ControlsXsRung, 2026-09-01): the panel rung, opt-in by prop — the default stays sm (2026-07-28 law) */
@@ -297,11 +299,11 @@ const Dropdown = ({
 
         <div ref={listRef} className="kol-dd-list" role="listbox" style={scale !== 1 ? { zoom: scale } : undefined}>
           {options.map((option, i) => {
-            if (option?.divider) return <MenuDropdownDivider key={`divider-${i}`} />
+            if (option?.divider) return <MenuDivider key={`divider-${i}`} />
             if (option?.heading) return <div key={`heading-${i}`} className={`${resolvedSize === 'xs' ? 'kol-mono-8' : 'kol-helper-12'} ${ROW_H[resolvedSize] ?? ROW_H.sm} ${ROW_PAD[resolvedSize] ?? ROW_PAD.sm} flex shrink-0 items-center text-meta`}>{option.heading}</div>
             const isActive = option.value === currentOption?.value
             return (
-              <MenuDropdownItem
+              <MenuRow
                 key={option.value}
                 /* NO HOVER STATE ANYWHERE ON A DROPDOWN (user 2026-08-28,
                  * "delete any hover state on dropdowns"): the trigger was
@@ -336,7 +338,7 @@ const Dropdown = ({
                   </span>
                 )}
                 {option.label}
-              </MenuDropdownItem>
+              </MenuRow>
             )
           })}
         </div>

package/src/molecules/Menu.jsx

@@ -0,0 +1,198 @@
+import { useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
+import Button from '../atoms/Button.jsx'
+import Kbd from '../atoms/Kbd.jsx'
+import SearchInput from './SearchInput.jsx'
+import { MenuRow, MenuDivider, MenuFlyout } from './MenuItem.jsx'
+import { PopoverPanel, usePopover, Tooltip } from '../utilities/Popover.jsx'
+
+/**
+ * The Menu* family (metric Round 4, 2026-10-31) — one family, one prefix.
+ *
+ *   MenuTrigger  the chip: `Button variant="tab" size="sm"`, `pressed` while open; `iconOnly` is the ⋮
+ *   MenuPanel    the faint raised panel (kol-theme `.kol-menu-panel`)
+ *   MenuRow · MenuDivider · MenuLabel · MenuFlyout — the parts (MenuRow / MenuFlyout / MenuDivider live in MenuItem.jsx)
+ *   Menu         the base: `trigger` (render prop `({ open, props })`) + `items` (rows as data)
+ *   MenuFilter · MenuDatePicker · MenuMore — ready-made menus, data and callbacks only
+ *
+ *   <Menu align="end" minWidth={224} trigger={({ open, props }) => <MenuTrigger open={open} icon="filter-lines" {...props}>Filter</MenuTrigger>} items={[
+ *     { heading: 'Graph interval' },                                   // a MenuLabel row
+ *     { label: 'Days', current: true, checked: true, onClick },
+ *     { divider: true },
+ *     { label: 'Segment', icon: 'star', disabled: true, tooltip: 'No segments saved' },
+ *     { label: 'Browser', icon: 'layout', items: [{ label: 'Browser', onClick }] },   // a flyout
+ *     { label: 'Last 7 days', kbd: 'W', onClick },
+ *     { label: 'Export stats', trailing: 'download', onClick },
+ *   ]} />
+ *
+ *   row keys: `icon` (kol-icons name or node) · `trailing` (+ `trailingSize`) · `current` fills the row · `checked` ✓
+ *   (before the `kbd` cap) · `kbd` · `disabled` + `tooltip` (why) · `items` (a flyout of the same rows).
+ *   `search` ({ placeholder, empty }) puts a search field above the rows and filters them by label.
+ *   `children` sit above the rows.
+ */
+
+/* the ⋮ — kol-icons `more-vertical` (user 2026-10-31: *"just make a vertical version"* — was `more` turned 90°) */
+const MORE = <Icon name="more-vertical" size={16} />
+
+export function MenuTrigger({ open = false, iconOnly, icon, iconComponent, children, ...rest }) {
+  if (iconOnly) {
+    return <Button variant="tab" size="sm" pressed={open} iconOnly={iconOnly === true ? 'more-vertical' : iconOnly} iconComponent={iconOnly === true ? MORE : iconComponent} {...rest} className={`kol-menu-trigger ${rest.className ?? ''}`.trim()} />
+  }
+  /* a labelled trigger has NO hover wash — its ground shows only while its menu is open (user 2026-10-31, on Plausible:
+   * *"its not supposed to be solid, only bg on hover … no hover just click … only [...] has hover"*); the ⋮ keeps it */
+  return <Button variant="tab" size="sm" pressed={open} iconLeft={icon} iconComponent={iconComponent} {...rest} className={`kol-menu-trigger kol-menu-trigger--quiet ${rest.className ?? ''}`.trim()}>{children}</Button>
+}
+
+export const MenuPanel = ({ className = '', children, ...rest }) => (
+  <div className={`kol-menu-panel ${className}`.trim()} {...rest}>{children}</div>
+)
+
+export const MenuLabel = ({ children }) => <div className="kol-menu-label kol-helper-12">{children}</div>
+
+const glyph = (icon, size) => (typeof icon === 'string' ? <Icon name={icon} size={size} /> : icon)
+const Check = () => <Icon name="check" size={14} className="text-oq-88" />
+
+function trailingOf(it) {
+  if (it.kbd != null) {
+    return (
+      <span className="inline-flex items-center gap-2">
+        {it.checked && <Check />}
+        <Kbd size="md" className="kol-menu-kbd">{it.kbd}</Kbd>
+      </span>
+    )
+  }
+  if (it.checked) return <Check />
+  return it.trailing ? <span className="text-oq-88 inline-flex">{glyph(it.trailing, it.trailingSize ?? 14)}</span> : undefined
+}
+
+function Rows({ items }) {
+  return items.map((it, i) => {
+    if (it.divider) return <MenuDivider key={`d${i}`} className="kol-menu-rule" />
+    if (it.heading) return <MenuLabel key={`h${i}`}>{it.heading}</MenuLabel>
+    const icon = it.icon && <span className="text-oq-88 inline-flex">{glyph(it.icon, 16)}</span>
+    const cls = `kol-menu-row kol-helper-12${it.current ? ' kol-menu-row--current' : ''}`
+    const row = it.items?.length && !it.disabled ? (
+      <MenuFlyout flyout iconLeft={icon} label={it.label} rowClass={cls} panelClassName="kol-menu-panel min-w-[200px]" panelStyle={{ marginLeft: 4 }}>
+        <Rows items={it.items} />
+      </MenuFlyout>
+    ) : (
+      <MenuRow disabled={it.disabled} rowClass={cls} onClick={it.onClick} iconLeft={icon} shortcut={trailingOf(it)}>
+        {it.label}
+      </MenuRow>
+    )
+    const key = it.key ?? `r${i}`
+    return it.tooltip
+      ? <Tooltip key={key} label={it.tooltip} placement="left" triggerClassName="block w-full">{row}</Tooltip>
+      : <div key={key}>{row}</div>
+  })
+}
+
+export function Menu({ items = [], trigger, align = 'start', minWidth, offset = 4, defaultOpen = false, stayOpen = false, search, className = '', children }) {
+  const [open, setOpen] = useState(defaultOpen)
+  const [q, setQ] = useState('')
+  const popover = usePopover({
+    open,
+    onOpenChange: setOpen,
+    placement: align === 'end' ? 'bottom-end' : 'bottom-start',
+    offset,
+    role: 'menu',
+    dismiss: stayOpen ? { outsidePress: false } : true,
+  })
+  let rows = items
+  if (search) {
+    const s = q.toLowerCase()
+    rows = items.filter((it) => it.label == null || String(it.label).toLowerCase().includes(s))
+    if (!rows.some((it) => it.label != null)) rows = [...rows, { key: 'empty', label: search.empty || 'Nothing matches', disabled: true }]
+  }
+  /* the wrapper takes the ref (a Button need not forward one); the trigger takes the handlers and the aria —
+   * `aria-pressed` cleared, an open menu is `aria-expanded`, its fill is the trigger's `pressed` */
+  return (
+    <>
+      <span ref={popover.refs.setReference} className={`inline-flex align-middle ${className}`.trim()}>
+        {trigger({ open, props: { ...popover.getReferenceProps(), 'aria-pressed': undefined } })}
+      </span>
+      <PopoverPanel popover={popover} panel={false} focus={false} className="kol-menu-panel w-max" style={minWidth ? { minWidth } : undefined}>
+        {/* a row's click closes the menu (it bubbles from `[data-menu-item]`); a flyout row only toggles */}
+        <div onClick={(e) => { if (e.target.closest('[data-menu-item]')) setOpen(false) }}>
+          {search && <div className="pb-1"><SearchInput variant="outline" size="sm" value={q} onChange={(e) => setQ(e.target?.value ?? e)} onClear={() => setQ('')} placeholder={search.placeholder || 'Search'} /></div>}
+          {children}
+          <Rows items={rows} />
+        </div>
+      </PopoverPanel>
+    </>
+  )
+}
+
+/* ── the ready-made menus ── */
+
+/**
+ * MenuFilter — category rows (`groups`: `{ key, label, icon, fields: [{ key, label }], more, disabled: 'why' }` or
+ * `{ divider: true }`). A group with one field is a plain row that opens it; a `more` group with 2+ fields opens a flyout
+ * of them; a `more` group with none is disabled with ›; a disabled group shows its reason. `onPick({ group, field? })`.
+ * `active` (`[{ key, label, group, field? }]`) — metric Round 6 (user: *"dont put this tag there, it breaks the layout"*):
+ * the active filters live INSIDE the menu, an "Active" section on top (a row's click is `onPick` to edit it, its × is
+ * `onRemove(f)`, "Clear all" at 2+ is `onClear`), and the trigger holds its pressed ground while any is set. No count.
+ */
+export function MenuFilter({ groups = [], onPick, active = [], onRemove, onClear, label = 'Filter', icon = 'filter-lines', align = 'end', minWidth = 224 }) {
+  const items = groups.map((g) => {
+    if (g.divider) return g
+    const one = g.fields?.length === 1 && !g.disabled
+    return {
+      key: g.key, label: g.label, icon: g.icon, disabled: !!g.disabled, tooltip: g.disabled || undefined,
+      trailing: g.more && g.disabled ? 'chevron-right' : undefined, trailingSize: 12,
+      items: g.more && !g.disabled && !one ? g.fields.map((f) => ({ key: f.key, label: f.label, onClick: () => onPick?.({ group: g.key, field: f.key }) })) : undefined,
+      onClick: () => onPick?.({ group: g.key }),
+    }
+  })
+  const rowCls = 'kol-menu-row kol-helper-12'
+  return (
+    <Menu align={align} minWidth={minWidth} offset={8} items={items}
+      trigger={({ open, props }) => <MenuTrigger open={open || active.length > 0} icon={icon} {...props}>{label}</MenuTrigger>}>
+      {active.length > 0 && (
+        <>
+          <MenuLabel>Active</MenuLabel>
+          {active.map((f) => (
+            <div key={f.key} className="flex items-center">
+              <div className="flex-1 min-w-0">
+                <MenuRow rowClass={rowCls} onClick={() => onPick?.({ group: f.group, field: f.field })}>{f.label}</MenuRow>
+              </div>
+              <Button tone="ghost" size="xs" iconOnly="x" aria-label={`Remove filter: ${f.label}`} onClick={() => onRemove?.(f)} />
+            </div>
+          ))}
+          {active.length > 1 && onClear && <MenuRow rowClass={rowCls} onClick={onClear}>Clear all</MenuRow>}
+          <MenuDivider className="kol-menu-rule" />
+        </>
+      )}
+    </Menu>
+  )
+}
+
+/**
+ * MenuDatePicker — range `groups` (`[[{ key, label, kbd }]]`, a rule between groups), `value` the current key (filled,
+ * ✓), `onChange(key)` (a custom-range key is the caller's to open its dialog). `compare` (`{ label, kbd, onClick }`)
+ * adds the compare row under a rule. The trigger shows `label` beside the calendar glyph (`icon` / `iconComponent`).
+ * metric Round 6 (user: *"relation ship between tab and dropdown is much better at reference"* — plausible.io): the
+ * trigger holds a value, so it wears its chip at rest — the tab's pressed oq-08, the panel's own ground, one family —
+ * and the panel opens right-aligned 8px under it (plausible.io measured: 8px, right edges flush).
+ */
+export function MenuDatePicker({ groups = [], value, onChange, label, icon = 'calendar', iconComponent, compare, align = 'end', minWidth = 224 }) {
+  const items = [
+    ...groups.flatMap((g, i) => [
+      ...(i > 0 ? [{ divider: true }] : []),
+      ...g.map((r) => ({ key: r.key, label: r.label, current: r.key === value, checked: r.key === value, kbd: r.kbd, onClick: () => onChange?.(r.key) })),
+    ]),
+    ...(compare ? [{ divider: true }, { key: 'compare', label: compare.label, kbd: compare.kbd, onClick: compare.onClick }] : []),
+  ]
+  return (
+    <Menu align={align} minWidth={minWidth} offset={8} items={items}
+      trigger={({ open, props }) => <MenuTrigger open={open} icon={icon} iconComponent={iconComponent} {...props}>{label}</MenuTrigger>} />
+  )
+}
+
+/** MenuMore — the ⋮ chip and its rows (`items`, as `Menu`'s); `label` names it for a screen reader. */
+export function MenuMore({ label, items = [], align = 'end', minWidth = 224, defaultOpen, stayOpen }) {
+  return (
+    <Menu align={align} minWidth={minWidth} offset={8} items={items} defaultOpen={defaultOpen} stayOpen={stayOpen}
+      trigger={({ open, props }) => <MenuTrigger open={open} iconOnly aria-label={label} {...props} />} />
+  )
+}

package/src/molecules/MenuItem.jsx

@@ -99,7 +99,7 @@ export function MenuItem({
 }
 
 /**
- * MenuDropdownItem — action row inside a MenuItem's dropdown panel.
+ * MenuRow — action row inside a menu panel (`Menu`, `MenuItem`). Was `MenuDropdownItem` (alias kept, 2026-10-31).
  *
  * `height` (default none — the `h-8` rung) — an inline row height, for a panel
  * in a chrome whose own rows are shorter (DropdownGhostWidthAndListHeight,
@@ -134,7 +134,7 @@ const ROW_BY_SIZE = { xs: 'kol-mono-8 px-2 h-5', sm: 'kol-helper-12 px-2 h-8', m
 /* `flex`, not `inline-flex` (MenuDropdownItemBlockRow, kol-fxr 2026-10-13): as bare children of a
  * content-sized (`w-max`) panel, inline rows measured as ONE line — five starters ≈ 795px. A block
  * row still fills a fixed panel through `w-full` and lets a content-sized one hug its longest label. */
-export function MenuDropdownItem({ onClick, onPointerEnter, onPointerLeave, disabled, prefix, iconLeft, shortcut, hover = true, height, size = 'sm', rowClass, children }) {
+export function MenuRow({ onClick, onPointerEnter, onPointerLeave, disabled, prefix, iconLeft, shortcut, hover = true, height, size = 'sm', rowClass, children }) {
   return (
     <button
       type="button"
@@ -161,12 +161,13 @@ export function MenuDropdownItem({ onClick, onPointerEnter, onPointerLeave, disa
 
 /* `className` — the rule's colour and spacing, whole (MetricDashboardUpstream, kol-website 2026-10-31): on a filled
  * panel the default `border-oq-08` vanishes. */
-export function MenuDropdownDivider({ className = 'border-oq-08 my-1' }) {
+/* MenuDivider — a rule between a menu's groups. Was `MenuDropdownDivider` (alias kept, 2026-10-31). */
+export function MenuDivider({ className = 'border-oq-08 my-1' }) {
   return <div className={`border-t ${className}`} />
 }
 
 /**
- * MenuDropdownNest — A dropdown row that opens a submenu. a row inside a dropdown panel that holds a submenu.
+ * MenuFlyout — a menu row that holds a submenu. Was `MenuDropdownNest` (alias kept, 2026-10-31).
  *
  * Default — ACCORDION: click the row to expand/collapse its children inline
  * (below the row, in the same panel); the trailing chevron rotates 90°.
@@ -193,7 +194,7 @@ export function MenuDropdownDivider({ className = 'border-oq-08 my-1' }) {
  * Either way, a leaf MenuDropdownItem inside still closes the whole menu via the
  * standard data-menu-item bubble; the nest row itself only toggles.
  */
-export function MenuDropdownNest({ prefix, iconLeft, label, disabled, flyout = false, scroll = false, rowClass, panelClassName, panelStyle, children }) {
+export function MenuFlyout({ prefix, iconLeft, label, disabled, flyout = false, scroll = false, rowClass, panelClassName, panelStyle, children }) {
   if (flyout) return <MenuFlyoutNest prefix={prefix} iconLeft={iconLeft} label={label} disabled={disabled} scroll={scroll} rowClass={rowClass} panelClassName={panelClassName} panelStyle={panelStyle}>{children}</MenuFlyoutNest>
   return <MenuAccordionNest prefix={prefix} iconLeft={iconLeft} label={label} disabled={disabled}>{children}</MenuAccordionNest>
 }
@@ -296,3 +297,10 @@ function MenuFlyoutNest({ prefix, iconLeft, label, disabled, scroll, rowClass, p
     </div>
   )
 }
+
+/** @deprecated 2026-10-31 → MenuRow (the Menu* family, metric Round 4) */
+export const MenuDropdownItem = MenuRow
+/** @deprecated 2026-10-31 → MenuDivider */
+export const MenuDropdownDivider = MenuDivider
+/** @deprecated 2026-10-31 → MenuFlyout */
+export const MenuDropdownNest = MenuFlyout

package/src/molecules/Modal.jsx

@@ -64,7 +64,16 @@ import ToggleCheckbox from '../atoms/ToggleCheckbox.jsx'
 
 const ModalCtx = (globalThis[Symbol.for('@kolkrabbi/kol-component/ModalCtx')] ??= createContext(null))
 
-export function ModalProvider({ children }) {
+/* THE MODAL VARIANTS (user 2026-10-31: *"do we not use variants for different styles?"*). `lift` — the overlay panel
+ * every KOL overlay wears (oq-04, no border, the scrim is the edge); `bordered` — the page surface behind an fg-08
+ * hairline. Each modal keeps its own default (prompts bordered, Dialog lift) until he picks one. */
+const MODAL_VARIANTS = {
+  lift: { className: 'kol-overlay-panel', style: {} },
+  bordered: { className: 'border border-fg-08', style: { background: 'var(--kol-surface-primary)', color: 'var(--kol-surface-on-primary)' } },
+}
+const modalVariant = (v, fallback) => MODAL_VARIANTS[v] ?? MODAL_VARIANTS[fallback]
+
+export function ModalProvider({ children, variant = 'bordered' }) {
   const [state, setState] = useState(null)
 
   const closeWith = useCallback((value) => {
@@ -74,34 +83,35 @@ export function ModalProvider({ children }) {
     })
   }, [])
 
-  const prompt = useCallback((title, defaultValue = '', { okLabel, cancelLabel, type = 'text', placeholder } = {}) =>
-    new Promise((resolve) => setState({ kind: 'prompt', title, defaultValue, okLabel, cancelLabel, type, placeholder, resolve })),
+  const prompt = useCallback((title, defaultValue = '', { okLabel, cancelLabel, type = 'text', placeholder, variant } = {}) =>
+    new Promise((resolve) => setState({ kind: 'prompt', title, defaultValue, okLabel, cancelLabel, type, placeholder, variant, resolve })),
   [])
 
-  const confirm = useCallback((title, { okLabel, cancelLabel, options } = {}) =>
-    new Promise((resolve) => setState({ kind: 'confirm', title, okLabel, cancelLabel, options: options?.length ? options : null, resolve })),
+  const confirm = useCallback((title, { okLabel, cancelLabel, options, variant } = {}) =>
+    new Promise((resolve) => setState({ kind: 'confirm', title, okLabel, cancelLabel, options: options?.length ? options : null, variant, resolve })),
   [])
 
-  const alert = useCallback((title, { okLabel } = {}) =>
-    new Promise((resolve) => setState({ kind: 'alert', title, okLabel, resolve })),
+  const alert = useCallback((title, { okLabel, variant } = {}) =>
+    new Promise((resolve) => setState({ kind: 'alert', title, okLabel, variant, resolve })),
   [])
 
-  const form = useCallback((title, fields = [], { okLabel, cancelLabel } = {}) =>
-    new Promise((resolve) => setState({ kind: 'form', title, fields, okLabel, cancelLabel, resolve })),
+  const form = useCallback((title, fields = [], { okLabel, cancelLabel, variant } = {}) =>
+    new Promise((resolve) => setState({ kind: 'form', title, fields, okLabel, cancelLabel, variant, resolve })),
   [])
 
   return (
     <ModalCtx.Provider value={{ prompt, confirm, alert, form }}>
       {children}
       {state && typeof document !== 'undefined' && createPortal(
-        <ModalView state={state} closeWith={closeWith} />,
+        <ModalView state={state} closeWith={closeWith} variant={state.variant ?? variant} />,
         document.body,
       )}
     </ModalCtx.Provider>
   )
 }
 
-function ModalView({ state, closeWith }) {
+function ModalView({ state, closeWith, variant }) {
+  const look = modalVariant(variant, 'bordered')
   const [val, setVal] = useState(state.defaultValue ?? '')
   const [values, setValues] = useState(() => Object.fromEntries((state.options ?? []).map((o) => [o.id, !!o.defaultValue])))
   const [fieldVals, setFieldVals] = useState(() => Object.fromEntries((state.fields ?? []).map((f) => [f.id, f.defaultValue ?? ''])))
@@ -184,10 +194,9 @@ function ModalView({ state, closeWith }) {
         aria-modal="true"
         aria-labelledby="kol-modal-title"
         onMouseDown={(e) => e.stopPropagation()}
-        className="kol-modal flex flex-col gap-4 p-5 rounded border border-fg-08"
+        className={`kol-modal flex flex-col gap-4 p-5 rounded ${look.className}`}
         style={{
-          background: 'var(--kol-surface-primary)',
-          color: 'var(--kol-surface-on-primary)',
+          ...look.style,
           minWidth: 320,
           maxWidth: '90vw',
         }}
@@ -288,7 +297,8 @@ export function useModal() {
  *
  *   <Dialog open={open} onClose={() => setOpen(false)} title="Filter by page" width={560}>…</Dialog>
  */
-export function Dialog({ open, onClose, title, width = 560, children }) {
+export function Dialog({ open, onClose, title, width = 560, variant = 'lift', children }) {
+  const look = modalVariant(variant, 'lift')
   useEffect(() => {
     if (!open) return undefined
     const onKey = (e) => { if (e.key === 'Escape' && !document.querySelector('.kol-popover-float')) onClose() }
@@ -308,8 +318,11 @@ export function Dialog({ open, onClose, title, width = 560, children }) {
         aria-label={title}
         data-dialog
         onMouseDown={(e) => e.stopPropagation()}
-        className="kol-modal flex flex-col rounded border border-fg-08 max-h-[85vh]"
-        style={{ background: 'var(--kol-surface-primary)', color: 'var(--kol-surface-on-primary)', width: `min(${width}px, calc(100vw - 32px))` }}
+        /* THE OVERLAY PANEL (MetricRebuild, 2026-10-31 — user: the filter dialog read as "a borderless box floating
+         * mid-page"): it painted the page's own surface behind an fg-08 hairline, so on a dark page it was the page.
+         * `.kol-overlay-panel` is the lift every KOL overlay wears (oq-04, no border — the scrim is the edge). */
+        className={`kol-modal flex flex-col rounded max-h-[85vh] ${look.className}`}
+        style={{ ...look.style, width: `min(${width}px, calc(100vw - 32px))` }}
       >
         {children}
       </div>

package/src/molecules/SectionText.jsx

@@ -37,13 +37,15 @@
  *                                 stamps `reveal` on each part; nothing animates in the DS)
  * @param {object}    slotStyle    inline style per slot — `{ headline: { '--reveal-delay': '0.1s' } }`
  * @param {string}    className    extra classes on the block
- * @param {'page'|'app'|'section'|'content'} [level]  THE HEADER LEVELS (2026-10-22, user: *"rename PageHeader to
+ * @param {'page'|'app'|'section'|'content'|'document'} [variant]  THE HEADER VARIANTS (was `level` until 2026-10-31 — user: `variant`
+ *                    is the only word for a variant; `level` stays a deprecated alias on the retirement ledger) (2026-10-22, user: *"rename PageHeader to
  *                    something that describes section text elements"* — PageHeader is now an alias of this). A
  *                    level fills the role defaults; any explicit prop still wins. page = h1 display-01 over
  *                    `.kol-header-lede` — the hero; app = h1 display-01 at 46/60 over `.kol-header-lede-app`;
  *                    section = h2 display-03 over `.kol-header-lede-section`; content = h3 heading-04 under a
  *                    `kol-eyebrow`, over body-01 fg-64 at 64ch — a section of a page's CONTENT (a dev tab's
- *                    sections, DevSectionHeader, kol-fxr). A level sets actions inline, and the bottom rhythm
+ *                    sections, DevSectionHeader, kol-fxr); document = h1 36/1.2 bold display face over a 15/1.6 body-face lede
+ *                    to 724px — a document's own page (DocumentIndex). A level sets actions inline, and the bottom rhythm
  *                    to `--kol-page-header-mb` (40px; content 16px). Unset = the section family as before.
  * @param {ReactNode} media        a mark above the eyebrow (a logo, an SVG) — with a `level` only
  */
@@ -60,7 +62,7 @@ export const HEADLINE_ROLE = {
   'heading-05': 'kol-sans-heading-05',
 }
 
-/* ONE HEADER, FOUR LEVELS (Round 11 + PageHeaderAppLevel, carried from PageHeader whole). `title` is the
+/* ONE HEADER, FIVE LEVELS (Round 11 + PageHeaderAppLevel, carried from PageHeader whole). `title` is the
  * headline's type, `lede` the body's; the rest default the block for that level. */
 export const SECTION_TEXT_LEVELS = {
   page: { title: 'kol-sans-display-01', lede: 'kol-header-lede' },
@@ -69,6 +71,9 @@ export const SECTION_TEXT_LEVELS = {
   /* content (DevSectionHeader, kol-fxr 2026-10-22 — the user's approved look: *"maybe title and description is
    * one step bigger?"*; never `kol-helper-*` for a paragraph) */
   content: { title: 'kol-sans-heading-04', lede: 'kol-sans-body-01 text-fg-64', eyebrow: 'kol-eyebrow text-fg-48', as: 'h3', gap: 'gap-2', mb: '16px', measure: '64ch' },
+  /* document (DocumentIndexFigma, kol-atlas 2026-10-31) — the Research page header, the workspace sheet's: 36/1.2 bold
+   * display face at −0.005em, 12 under it; the lede 15/1.6 in the body face to a 724 edge */
+  document: { title: 'font-[family-name:var(--kol-font-family-sans)] text-[36px] font-bold leading-[1.2] tracking-[-0.005em]', lede: 'm-0 font-[family-name:var(--kol-font-family-sans-neutral)] text-[15px] leading-[1.6] text-fg-96', measure: '724px' },
 }
 
 export default function SectionText({
@@ -115,11 +120,14 @@ export default function SectionText({
      (PageHeader's `--kol-page-header-mb`). `slotStyle` reaches the slots; this
      was the one box it could not reach. */
   style,
+  variant: variantProp,
+  /* deprecated alias of `variant` (2026-10-31) */
   level,
   media,
 }) {
   /* a LEVEL fills the header defaults; an explicit prop always wins */
-  const L = level ? SECTION_TEXT_LEVELS[level] ?? SECTION_TEXT_LEVELS.page : null
+  const variant = variantProp ?? level
+  const L = variant ? SECTION_TEXT_LEVELS[variant] ?? SECTION_TEXT_LEVELS.page : null
   const Headline = headlineAs ?? L?.as ?? (L ? 'h1' : 'h2')
   if (L) {
     headlineClass = `text-fg-96 ${headlineClass ?? L.title}`

package/src/molecules/TabsRow.jsx

@@ -242,8 +242,11 @@ function StackedTabs({ tabs, value, onChange, placement, shape = 'bar', collapse
           onClick={() => onChange?.(t.id)}
           aria-current={active ? 'page' : undefined}
           aria-label={t.label}
-          className={`flex flex-col items-center justify-center rounded-full cursor-pointer flex-none${labels ? ' gap-0.5' : ''}`}
-          style={{ width: slotW, height: slotH, padding: 0, border: 'none', background: active ? 'var(--kol-oq-16)' : 'transparent', color: ink(active) }}
+          /* a DOCK slot lights on hover like a menu row — the nav row's oq-04 ground and on-primary ink (HomeDockRound4,
+           * kol-fxr 2026-10-31; was forced from AppFloatNav with `!` over the inline ground). The rest ground and ink ride
+           * variables so the hover class can win without `!`. */
+          className={`flex flex-col items-center justify-center rounded-full cursor-pointer flex-none bg-[var(--slot-bg)] text-[var(--slot-ink)]${dock && !active ? ' hover:bg-[var(--kol-oq-04)] hover:text-[var(--kol-surface-on-primary)]' : ''}${labels ? ' gap-0.5' : ''}`}
+          style={{ width: slotW, height: slotH, padding: 0, border: 'none', '--slot-bg': active ? 'var(--kol-oq-16)' : 'transparent', '--slot-ink': ink(active) }}
         >
           {t.icon && <Icon name={t.icon} size={labels ? 24 : 28} />}
           {labels && <span className="truncate max-w-full px-1.5" style={{ fontFamily: 'var(--kol-font-family-mono)', fontSize: 11, lineHeight: 1.2, fontWeight: 600 }}>{t.label}</span>}

package/src/organisms/SettingsPanel.jsx

@@ -143,10 +143,13 @@ export default function SettingsPanel({
  * row living in a column narrower than the 160px label default
  * (SettingsShortcutsComboOverflow, kol-monitor 2026-09-01). `text` is a row whose value is text — the same label,
  * on the baseline, as tall as its text (LabeledControl's `text`; SettingsRowMonoBaseline, kol-monitor 2026-10-18).
+ * `stack` puts the label ABOVE the value, both at the row's start — a dated entry read as a bulletin (metric's
+ * Deploys tab, Round 3 2026-10-31: *"date above the text"*); `labelWidth` and `align` do nothing there.
  */
-export function SettingsRow({ label, hint, align = 'end', labelWidth = 160, text = false, children }) {
+export function SettingsRow({ label, hint, align = 'end', labelWidth = 160, text = false, stack = false, children }) {
+  if (stack) align = 'fill'
   return (
-    <LabeledControl inline text={text} label={typeof label === 'string' ? label.toUpperCase() : label} labelWidth={labelWidth}>
+    <LabeledControl inline={!stack} text={text} label={typeof label === 'string' ? label.toUpperCase() : label} labelWidth={labelWidth}>
       {hint
         ? <Tooltip label={hint} triggerClassName={`flex min-h-6 items-center w-full ${align === 'fill' ? '' : 'justify-end'}`.trim()}>{children}</Tooltip>
         /* `flex`, not `inline-flex`: an inline box rode the label's text baseline and sat 5px low (2026-10-31) */

package/src/organisms/SettingsSections.jsx

@@ -67,7 +67,7 @@ const rowAlign = (row, fallback) => row.align ?? (row.type === 'choice' || row.t
  * first included: the rule is `.kol-section--divided + .kol-section--divided`,
  * so the first draws nothing and skipping it just costs the next its line.
  *
- * @param {Array<{label?: string, note?: string|string[], rows?: Array<{label: ReactNode, type?: 'choice'|'switch'|'slider', options?: Array, value?: ReactNode, on?: boolean, onChange?: Function, min?: number, max?: number, step?: number, formatValue?: Function, defaultValue?: number, displayWidth?: number, render?: Function, hint?: string, align?: string, labelWidth?: number|'auto', text?: boolean, id?: string}>, rowGap?: number}>} sections - The settings body, in order (`hint` → SettingsRow's hint; `note` a sentence or two under the eyebrow; a string `value` is drawn in the DS's mono-12 and sits on the baseline; `type: 'choice'` / `'switch'` / `'slider'` rows are drawn here — a slider is the DS Slider across the value column, fluid track + the Input readout at `displayWidth` chars (3, `preset="rail"`), its label column 80 unless set; `min` · `max` · `step` · `value` · `onChange`)
+ * @param {Array<{label?: string, note?: string|string[], rows?: Array<{label: ReactNode, type?: 'choice'|'switch'|'slider', options?: Array, value?: ReactNode, on?: boolean, onChange?: Function, min?: number, max?: number, step?: number, formatValue?: Function, defaultValue?: number, displayWidth?: number, render?: Function, hint?: string, align?: string, labelWidth?: number|'auto', text?: boolean, stack?: boolean, id?: string}>, rowGap?: number}>} sections - The settings body, in order (`hint` → SettingsRow's hint; `stack` → SettingsRow's stack, the label over the value; `note` a sentence or two under the eyebrow; a string `value` is drawn in the DS's mono-12 and sits on the baseline; `type: 'choice'` / `'switch'` / `'slider'` rows are drawn here — a slider is the DS Slider across the value column, fluid track + the Input readout at `displayWidth` chars (3, `preset="rail"`), its label column 80 unless set; `min` · `max` · `step` · `value` · `onChange`)
  * @param {boolean} [divided=false] - Hairline above each section
  * @param {number|'auto'} [labelWidth] - Default label column for every row — `'auto'` makes the label yield and the control hug, which is what a narrow column or a nowrap value needs
  * @param {string} [align] - Default row alignment passed to `SettingsRow`
@@ -87,6 +87,7 @@ export default function SettingsSections({ sections = [], divided = false, label
               align={rowAlign(row, align)}
               labelWidth={row.labelWidth ?? labelWidth ?? (row.type === 'slider' ? 80 : undefined)}
               text={row.text ?? (!row.render && !row.type && isText(row.value))}
+              stack={row.stack}
             >
               {control(row)}
             </SettingsRow>