@kolkrabbi/kol-workshop 0.5.1 → 0.11.0

package/src/shell/ShellSidebar.jsx

@@ -1,6 +1,8 @@
 import { useState, useEffect } from 'react'
-import { NavLink, Link, useLocation } from 'react-router-dom'
-import { Icon, Tooltip } from '@kolkrabbi/kol-component'
+import { useLocation } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-component'
+import RailSection from './RailSection.jsx'
+import RailRow from './RailRow.jsx'
 
 const getSectionRootPath = (route, basePath) => {
   if (route.path !== undefined && route.path !== null) {
@@ -63,115 +65,58 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
     setCollapsedSections((prev) => ({ ...prev, [route.id]: !prev[route.id] }))
   }
 
+  /* No count at L1 — the eyebrow names a body of material and the tally lives
+   * on the groups inside it (user ruling 2026-08-01). RailSection refuses one
+   * at this rung, so there is nothing to compute here. */
   return (
     <div className="space-y-4">
-      {/* kol-helper-10 types the wrapper box itself (was an untyped 16px box) */}
-      <div className="shell-sidebar-toggle shell-sidebar-label kol-doc-eyebrow" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
-        {labelTo ? (
-          <Link to={labelTo} className="shell-sidebar-label kol-doc-eyebrow" onClick={(e) => {
-            if (navCollapsed && handleToggle) handleToggle()
-            if (onNavigate) onNavigate(e)
-          }}>
-            {label}
-          </Link>
-        ) : (
-          /* Same voice as the labelTo branch. This read `kol-helper-10
-           * text-meta`, so the one rail mounted without a labelTo (the vault's
-           * "Documentation") rendered its label at a different size and colour
-           * from its two siblings — a type fork caused purely by which props
-           * the consumer happened to pass. */
-          <button type="button" className="shell-sidebar-label kol-doc-eyebrow" onClick={handleToggle}>{label}</button>
-        )}
-        <Tooltip label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}>
-          <button
-            type="button"
-            onClick={handleToggle}
-            aria-label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}
-            aria-expanded={!navCollapsed}
-            className="flex items-center justify-center"
-            style={{ height: '16.5px', marginBottom: '8px' }}
-          >
-            <Icon
-              name="chevron-down"
-              size={10}
-              className={`stroke-[2.5] transition-transform ${navCollapsed ? '' : 'rotate-180'}`}
-            />
-          </button>
-        </Tooltip>
-      </div>
+      <RailSection
+        level={1}
+        label={label}
+        to={labelTo}
+        collapsed={navCollapsed}
+        onToggle={handleToggle}
+        onNavigate={onNavigate}
+      >
+        <div className="space-y-4">
+          {routes.map((route) => {
+            /* A group with no children is not a group — it is a link. It used
+             * to render as a header anyway: a chevron that rotated over an
+             * empty body, no count, and no navigation, so clicking "Icons" or
+             * "Components" in the tree did nothing at all while looking like
+             * it should. `collapsible` is what that distinction is now. */
+            const hasChildren = route.children?.length > 0
 
-      {!navCollapsed && <div className="space-y-4">
-        {routes.map((route) => {
-          const isExpanded = !collapsedSections[route.id]
-
-          /* A group with no children is not a group — it is a link. It used to
-           * render as a header anyway: a chevron that rotated over an empty
-           * body, no count, and no navigation, so clicking "Icons" or
-           * "Components" in the tree did nothing at all while looking like it
-           * should. Now the chevron and the toggle only appear when there is
-           * something to expand, and a childless row goes where it says. */
-          const hasChildren = route.children?.length > 0
-          const headerClass = 'shell-nav-group-header w-full text-left kol-mono-14 text-body'
-
-          return (
-            <div key={route.id} className="shell-nav-group">
-              {hasChildren ? (
-                <button
-                  type="button"
-                  className={headerClass}
-                  onClick={() => handleSectionClick(route)}
-                  aria-expanded={isExpanded}
+            return (
+              <div key={route.id} className="shell-nav-group">
+                <RailSection
+                  level={2}
+                  label={route.label}
+                  count={hasChildren ? route.children.length : undefined}
+                  to={hasChildren ? undefined : getSectionRootPath(route, basePath)}
+                  collapsible={hasChildren}
+                  collapsed={!!collapsedSections[route.id]}
+                  onToggle={() => handleSectionClick(route)}
+                  onNavigate={onNavigate}
+                  icon={Icon}
                 >
-                  <span className="flex items-center gap-2">
-                    <Icon
-                      name="chevron-right"
-                      size={12}
-                      className={`transition-transform ${isExpanded ? 'rotate-90' : ''}`}
-                    />
-                    {route.label}
-                  </span>
-                  <span className="kol-mono-14 text-subtle">({route.children.length})</span>
-                </button>
-              ) : (
-                <Link
-                  to={getSectionRootPath(route, basePath)}
-                  className={headerClass}
-                  onClick={onNavigate}
-                >
-                  {/* aligned with the expandable rows' label column — the
-                    * chevron's width, kept as space so the two kinds of row
-                    * share a left edge */}
-                  <span className="flex items-center gap-2">
-                    <span aria-hidden="true" style={{ width: 12 }} />
-                    {route.label}
-                  </span>
-                </Link>
-              )}
-
-              {isExpanded && route.children?.length > 0 && (
-                <div className="shell-nav-items">
-                  {route.children.map((child) => {
-                    const childPath = getChildPath(child, basePath)
-                    return (
-                      <NavLink
+                  <div className="shell-nav-items">
+                    {(route.children ?? []).map((child) => (
+                      <RailRow
                         key={child.id}
-                        to={childPath}
-                        end
-                        className={({ isActive }) =>
-                          `shell-nav-item kol-mono-14 ${isActive ? 'text-emphasis' : 'text-body'}`
-                        }
-                        onClick={onNavigate}
+                        to={getChildPath(child, basePath)}
+                        onNavigate={onNavigate}
                       >
-                        <span className="shell-nav-item-title">{child.label}</span>
-                      </NavLink>
-                    )
-                  })}
-                </div>
-              )}
-            </div>
-          )
-        })}
-      </div>}
+                        {child.label}
+                      </RailRow>
+                    ))}
+                  </div>
+                </RailSection>
+              </div>
+            )
+          })}
+        </div>
+      </RailSection>
     </div>
   )
 }

package/src/shell/index.js

@@ -9,3 +9,10 @@
 export { default as ShellLayout } from './ShellLayout.jsx'
 export { ShellTocContext, ShellFullHeightContext, ShellTocCollapsedContext } from './ShellLayout.jsx'
 export { default as ShellSidebar } from './ShellSidebar.jsx'
+/* RailSection — THE rail ladder. Every rail header at every rung comes from
+ * here, in both rails; see the file header for why a class alone was not
+ * enough. `pnpm validate:rails` R4 asserts it. */
+export { default as RailSection } from './RailSection.jsx'
+/* RailRow — THE L3 rail row. The look lives in `.shell-nav-item`; this owns the
+ * markup so nine hand-written utility stacks cannot come back. R4 asserts it. */
+export { default as RailRow } from './RailRow.jsx'

package/src/tags/TagModeContext.jsx

@@ -22,14 +22,43 @@ export const TagModeProvider = ({
   docHref = defaultDocHref,
   tagHref = defaultTagHref
 }) => {
-  const [state, setState] = useState({ isOpen: false, activeTags: [] })
+  /* `view` lives in the CONTEXT, not in the overlay (2026-08-01). The overlay
+   * held its own `viewMode` state, so the graph could only be reached by
+   * finding an unlabelled glyph inside the already-open overlay — a caller
+   * could open tag mode but not say which mode. The rail's "Graph view" row
+   * needs exactly that. */
+  const [state, setState] = useState({ isOpen: false, activeTags: [], view: 'list', text: '', expanded: false })
+
+  /* ONE QUERY (user ruling 2026-08-01: "a system that accepts both tags and
+   * keywords"). `text` + `activeTags` are two facets of the SAME query, not
+   * two searches — ShellLayout used to hold `searchQuery` in its own local
+   * state while tags lived here, which is the whole reason the app had two
+   * surfaces. `expanded` is the palette's second state: Enter commits the
+   * query and opens the results body, Escape collapses it. */
+  const openTagMode = useCallback((tag = null, { view = 'list', expanded = false } = {}) => {
+    setState((prev) => ({
+      isOpen: true,
+      activeTags: tag ? [tag] : prev.activeTags,
+      view,
+      text: '',
+      expanded: expanded || !!tag,
+    }))
+  }, [])
+
+  const setText = useCallback((text) => {
+    setState((prev) => ({ ...prev, isOpen: true, text }))
+  }, [])
+
+  const setExpanded = useCallback((expanded) => {
+    setState((prev) => ({ ...prev, expanded }))
+  }, [])
 
-  const openTagMode = useCallback((tag = null) => {
-    setState({ isOpen: true, activeTags: tag ? [tag] : [] })
+  const setView = useCallback((view) => {
+    setState((prev) => ({ ...prev, view }))
   }, [])
 
   const closeTagMode = useCallback(() => {
-    setState({ isOpen: false, activeTags: [] })
+    setState({ isOpen: false, activeTags: [], view: 'list', text: '', expanded: false })
   }, [])
 
   const toggleTag = useCallback((tag) => {
@@ -63,7 +92,7 @@ export const TagModeProvider = ({
   // Close on any route change
   const location = useLocation()
   useEffect(() => {
-    if (state.isOpen) setState({ isOpen: false, activeTags: [] })
+    if (state.isOpen) setState({ isOpen: false, activeTags: [], view: 'list', text: '', expanded: false })
   }, [location.pathname])
 
   useEffect(() => {
@@ -79,9 +108,19 @@ export const TagModeProvider = ({
   }, [state.isOpen, closeTagMode])
 
   const value = useMemo(() => ({
+    /* Lets a consumer tell a real provider from the inert fallback, so
+     * ShellLayout can own its own palette state when mounted without one
+     * instead of silently no-op'ing every keystroke. */
+    isProvided: true,
     isOpen: state.isOpen,
     activeTags: state.activeTags,
     activeTag,
+    view: state.view,
+    setView,
+    text: state.text,
+    setText,
+    expanded: state.expanded,
+    setExpanded,
     openTagMode,
     closeTagMode,
     toggleTag,
@@ -91,7 +130,7 @@ export const TagModeProvider = ({
     inventory,
     docHref,
     tagHref
-  }), [state.isOpen, state.activeTags, activeTag, openTagMode, closeTagMode, toggleTag, removeTag, clearTags, setActiveTag, inventory, docHref, tagHref])
+  }), [state.isOpen, state.activeTags, state.view, state.text, state.expanded, setView, setText, setExpanded, activeTag, openTagMode, closeTagMode, toggleTag, removeTag, clearTags, setActiveTag, inventory, docHref, tagHref])
 
   return (
     <TagModeContext.Provider value={value}>
@@ -106,9 +145,16 @@ export const TagModeProvider = ({
  */
 const noop = () => {}
 const DEFAULT_TAG_MODE = {
+  isProvided: false,
   isOpen: false,
   activeTags: [],
   activeTag: null,
+  view: 'list',
+  setView: noop,
+  text: '',
+  setText: noop,
+  expanded: false,
+  setExpanded: noop,
   openTagMode: noop,
   closeTagMode: noop,
   toggleTag: noop,

package/src/tags/TagModeOverlay.jsx

@@ -1,26 +1,36 @@
-import { useMemo, useState } from 'react'
+import { useMemo } from 'react'
 import { Link } from 'react-router-dom'
-import { Input, Tag, Button, Tooltip } from '@kolkrabbi/kol-component'
+import { Button, Tooltip } from '@kolkrabbi/kol-component'
+import TagPath from './TagPath.jsx'
 import { useTagMode } from './TagModeContext.jsx'
 import TagGraph from './TagGraph.jsx'
-import { extractDocNumber, cleanTitle, getTagColor } from '../engine/index.js'
+import RailRow from '../shell/RailRow.jsx'
+import { extractDocNumber, cleanTitle } from '../engine/index.js'
 import { buildTagCounts } from '../engine/tags.js'
 
+/**
+ * TagModeOverlay - the tag BROWSER: the list and the graph. It does not search.
+ *
+ * ONE SEARCH (user ruling 2026-08-01: "search SHOULD be ONE system not 2").
+ * This component owned a second one - a raw `Input` plus
+ * `tag.toLowerCase().includes(q)` in a useMemo - over a corpus the shell's own
+ * index already covered. Two matchers, two behaviours, and this one never
+ * called the engine's `matchSearchItems` at all. Deleted rather than aligned:
+ * tags are rows in the shell search index now, so the one modal finds them
+ * like it finds everything else.
+ *
+ * `view` comes from the CONTEXT, not local state - the rail's "Graph view" row
+ * has to say which mode it wants before this component exists.
+ */
 const TagModeOverlay = () => {
-  const { activeTags, activeTag, toggleTag, removeTag, clearTags, closeTagMode, inventory, docHref, tagHref } = useTagMode()
-  const [viewMode, setViewMode] = useState('list')
-  const [search, setSearch] = useState('')
+  const { activeTags, activeTag, toggleTag, clearTags, closeTagMode, inventory, docHref, tagHref, view, setView } = useTagMode()
 
   const allTagsWithCount = useMemo(() => buildTagCounts(inventory), [inventory])
 
-  const visibleTags = useMemo(() => {
-    let tags = allTagsWithCount.filter(({ tag }) => !activeTags.includes(tag))
-    if (search.trim()) {
-      const q = search.toLowerCase()
-      tags = tags.filter(({ tag }) => tag.toLowerCase().includes(q))
-    }
-    return tags
-  }, [allTagsWithCount, search, activeTags])
+  const visibleTags = useMemo(
+    () => allTagsWithCount.filter(({ tag }) => !activeTags.includes(tag)),
+    [allTagsWithCount, activeTags]
+  )
 
   const filteredDocs = useMemo(() => {
     if (activeTags.length === 0) return []
@@ -33,102 +43,49 @@ const TagModeOverlay = () => {
   const hasFilters = activeTags.length > 0
 
   return (
-    <article className="docs-article">
-      {/* was max-w-[864px] — an improvised value in the ~900–1200 band the
-        * panel token exists to settle (kol-theme "Content widths"). */}
-      <div className="mx-auto max-w-[var(--kol-content-panel)]">
-        <div className="flex items-center justify-start gap-1 mb-3">
-          {hasFilters && (
-            <Tooltip label={viewMode === 'graph' ? 'List view' : 'Graph view'}>
-              <Button
-                variant="outline"
-                quiet
-                size="sm"
-                iconOnly={viewMode === 'graph' ? 'view-list' : 'polygon'}
-                onClick={() => setViewMode(viewMode === 'graph' ? 'list' : 'graph')}
-                aria-label={viewMode === 'graph' ? 'List view' : 'Graph view'}
-              />
-            </Tooltip>
-          )}
-          <Tooltip label="Close tag mode">
-            <Button
-              variant="outline"
-              quiet
-              size="sm"
-              iconOnly="x"
-              onClick={closeTagMode}
-              aria-label="Close tag mode"
-            />
-          </Tooltip>
-        </div>
-
-        <div className="dash-card flex flex-col gap-8 -mt-4">
-          <div className="flex items-center gap-2" style={{ width: '100%', alignSelf: 'stretch' }}>
-            <Input
-              type="text"
-              aria-label="Search tags"
-              placeholder="Search tags…"
-              value={search}
-              onChange={(e) => setSearch(e.target.value)}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter' && visibleTags.length > 0) {
-                  toggleTag(visibleTags[0].tag)
-                  setSearch('')
-                }
-              }}
-              size="md"
-              iconLeft="search"
-              className="w-full"
-              autoFocus
-            />
-            {search && (
-              <Tooltip label="Clear search">
-                <Button
-                  variant="outline"
-                  quiet
-                  size="sm"
-                  iconOnly="x"
-                  onClick={() => setSearch('')}
-                  aria-label="Clear search"
-                />
-              </Tooltip>
-            )}
-          </div>
-
-          <div className="flex flex-col gap-4 px-10">
+    /* NOT AN OVERLAY ANY MORE (user ruling 2026-08-01). This is the EXPANDED
+     * BODY of ShellSearchOverlay, rendered inside its panel — so it owns no
+     * scrim, no panel chrome and no close button. It was a sibling overlay
+     * with its own everything, which is what "two systems" meant. */
+    /* PLAIN BODY (user 2026-08-01). `.docs-article` is the PROSE wrapper — it
+     * centred every row and imposed a reading measure on a filter list, which
+     * is why "everything is center aligned". A results body is chrome, not
+     * prose. The node/graph button is gone too: the rail's Quick actions owns
+     * that entry, and a bare unlabelled hex floating at the corner was "not
+     * the place for it". */
+    <div className="flex flex-col gap-4 py-4">
+      <div className="flex flex-col gap-4">
+          {/* THE SEARCH BOX IS GONE (user ruling 2026-08-01). It was a raw
+            * `Input` driving `tag.toLowerCase().includes(q)` - a second search
+            * system over a corpus the shell index already holds. Tags are rows
+            * in that index now, so the ONE modal searches them. This overlay
+            * browses: the full list, and the graph. */}
+        <div className="flex flex-col gap-4">
             {hasFilters && (
               <>
                 <div className="flex items-center justify-between">
-                  <Button
-                    variant="outline"
-                    quiet
-                    size="sm"
-                    onClick={clearTags}
-                  >
-                    clear filters
+                  {/* PRIMARY (user 2026-08-01). `outline quiet` is the
+                    * recessive rung — this is the one action in the body. */}
+                  <Button variant="primary" size="sm" onClick={clearTags}>
+                    Clear filters
                   </Button>
-                  <div className="flex flex-wrap items-center gap-1.5">
-                    {activeTags.map((tag) => (
-                      <Tag
-                        key={tag}
-                        variant="solid"
-                        color={getTagColor(tag)}
-                        size="md"
-                        onRemove={() => removeTag(tag)}
-                      >
-                        {tag}
-                      </Tag>
-                    ))}
-                  </div>
+                  {/* NO CHIPS HERE (2026-08-01). The palette renders the
+                    * active tags in its input row — this block repeated them
+                    * inside the body, so one filter showed as two chips. The
+                    * query's facets belong to the query's input. */}
                 </div>
                 <div className="border-t border-fg-08 my-4" />
               </>
             )}
 
-            {hasFilters && viewMode === 'graph' ? (
+            {/* `hasFilters` dropped from this condition too — with no tag
+              * active the graph renders the WHOLE map, which is the view worth
+              * opening cold. Gated, the button could be clicked and nothing
+              * changed. */}
+            {view === 'graph' ? (
               <div>
                 <TagGraph
-                  docs={filteredDocs}
+                  docs={hasFilters ? filteredDocs : inventory}
                   allDocs={inventory}
                   activeTag={activeTag}
                   onTagClick={(tag) => toggleTag(tag)}
@@ -138,24 +95,28 @@ const TagModeOverlay = () => {
             ) : (
               <>
                 <div className="flex flex-col">
+                  {/* RAIL ROWS (user 2026-08-01: "reference the sidebars,
+                    * dont introduce a different text treatment here"). These
+                    * wore `.tag-list-item` / `.tag-list-count`, which have NO
+                    * CSS RULE ANYWHERE — that is the whole reason they centred
+                    * and carried no type. RailRow already is this row. */}
                   {visibleTags.map(({ tag, count }) => (
-                    <button
+                    <RailRow
                       key={tag}
-                      type="button"
-                      className={`tag-list-item${activeTags.includes(tag) ? ' active' : ''}`}
                       onClick={() => toggleTag(tag)}
+                      active={activeTags.includes(tag)}
+                      trailing={count}
                     >
-                      <span>{tag}</span>
-                      <span className="tag-list-count">{count}</span>
-                    </button>
+                      <TagPath tag={tag} />
+                    </RailRow>
                   ))}
                   {visibleTags.length === 0 && (
-                    <p className="text-fg-48 kol-mono-12 py-4">No tags matching "{search}"</p>
+                    <p className="text-fg-48 kol-mono-12 py-4">No tags</p>
                   )}
                 </div>
 
                 {hasFilters && filteredDocs.length > 0 && (
-                  <div className="flex flex-col pt-4 border-t border-fg-08">
+                  <div className="shell-nav-items pt-4 border-t border-fg-08">
                     {filteredDocs.map((d) => (
                       /* `d.href` wins over `docHref(d.id)` so ONE tag system can
                        * span content types that live in different URL spaces —
@@ -163,24 +124,22 @@ const TagModeOverlay = () => {
                        * at /components/:slug. Without it the inventory could
                        * only ever hold one kind of thing, which is why the
                        * graph saw the vault's 46 docs and nothing else. */
-                      <Link
+                      <RailRow
                         key={d.id}
                         to={d.href ?? docHref(d.id)}
-                        className="tag-list-item"
-                        onClick={closeTagMode}
+                        trailing={extractDocNumber(d.id)}
+                        onNavigate={closeTagMode}
                       >
-                        <span>{cleanTitle(d.title, d.id)}</span>
-                        <span className="tag-list-count">{extractDocNumber(d.id)}</span>
-                      </Link>
+                        {cleanTitle(d.title, d.id)}
+                      </RailRow>
                     ))}
                   </div>
                 )}
               </>
             )}
           </div>
-        </div>
       </div>
-    </article>
+    </div>
   )
 }
 

package/src/tags/TagPath.jsx

@@ -0,0 +1,24 @@
+/**
+ * TagPath — a tag is a PATH, not a string.
+ *
+ * User ruling 2026-08-01: "nested tags… its a feature not a shape."
+ * `domain/components/atoms` printed flat, so the namespace read as noise
+ * inside the name. The namespace dims and the LEAF carries — the same
+ * hierarchy the taxonomy already declares (ten top-level namespaces,
+ * `engine/doc-helpers.js` NAMESPACE_COLORS).
+ *
+ * Extracted out of TagModeOverlay 2026-08-01 when the frontmatter panel
+ * became the second surface that needed it — every place a tag renders reads
+ * from here rather than growing a second spelling.
+ */
+export default function TagPath({ tag }) {
+  const parts = String(tag).replace(/^#/, '').split('/')
+  const leaf = parts.pop()
+  if (!parts.length) return leaf
+  return (
+    <>
+      <span className="text-fg-32">{parts.join('/')}/</span>
+      {leaf}
+    </>
+  )
+}

package/src/tags/index.js

@@ -9,3 +9,4 @@ export { TagModeProvider, useTagMode } from './TagModeContext.jsx'
 export { default as TagModeGate } from './TagModeGate.jsx'
 export { default as TagModeOverlay } from './TagModeOverlay.jsx'
 export { default as TagGraph } from './TagGraph.jsx'
+export { default as TagPath } from './TagPath.jsx'