cursedbelt 5.59.0 → 5.63.0

package/src/react/components/TreeView.spec.tsx

@@ -332,3 +332,160 @@ describe('TreeView — aria attributes', () => {
     expect(getByText('Alpha 1')).toBeTruthy();
   });
 });
+
+// --- Row slots, opening and sections (forge task 2839) ---------------------------
+//
+// What desk's Components tree drew by hand beside this one: a trailing count and kind word, a
+// second "why it matched" line, double-click/Enter to open an editor, and "Lists" / "Components"
+// headings between its roots.
+
+describe('TreeView — meta, description and row attributes', () => {
+  const RICH: TreeNode[] = [
+    {
+      id: 'base',
+      label: 'Generic item',
+      meta: 'base template',
+      rowProps: { 'data-kind': 'type', className: 'app-row' },
+      children: [{ id: 'svc', label: 'Service X', description: 'Notes: …the api pod…', rowProps: { 'data-kind': 'component' } }],
+    },
+  ];
+
+  test('meta trails the label inside the row, and the description is a second line under it', () => {
+    const { getByText } = render(<TreeView nodes={RICH} defaultExpanded={['base']} />);
+    const meta = getByText('base template');
+    expect(meta.getAttribute('data-slot')).toBe('tree-meta');
+    // The label comes first in the row; the meta after it.
+    const row = meta.parentElement as HTMLElement;
+    expect(row.firstChild?.textContent).not.toBe('base template');
+    expect(row.lastElementChild).toBe(meta);
+    const why = getByText('Notes: …the api pod…');
+    expect(why.getAttribute('data-slot')).toBe('tree-description');
+    expect(why.previousElementSibling?.textContent).toBe('Service X');
+  });
+
+  test('🔴 rowProps land on the ROW, so a hook never matches the ancestors that wrap a nested row', () => {
+    const { getByText, container } = render(<TreeView nodes={RICH} defaultExpanded={['base']} />);
+    expect(container.querySelectorAll('[data-kind="type"]')).toHaveLength(1);
+    expect(container.querySelector('[data-kind="type"]')?.getAttribute('role')).toBeNull();
+    expect(container.querySelector('[data-kind="type"]')?.textContent).not.toContain('Service X');
+    expect(getByText('Service X').closest('[data-kind]')?.getAttribute('data-kind')).toBe('component');
+    expect(container.querySelector('.app-row')?.textContent).toContain('Generic item');
+  });
+});
+
+describe('TreeView — onOpen', () => {
+  test('a double-click opens that row, and only that row — not the parent that wraps it', () => {
+    const onOpen = mock((_id: string) => {});
+    const { getByText } = render(<TreeView nodes={NODES} defaultExpanded={['a']} onOpen={onOpen} />);
+    fireEvent.doubleClick(getByText('Alpha 1'));
+    expect(onOpen.mock.calls).toEqual([['a1']]);
+  });
+
+  test('Enter selects and opens; Space only selects', () => {
+    const onOpen = mock((_id: string) => {});
+    const onSelectionChange = mock((_ids: string[]) => {});
+    const { getByText } = render(<TreeView nodes={NODES} onOpen={onOpen} onSelectionChange={onSelectionChange} />);
+    const beta = getByText('Beta').closest('[role="treeitem"]') as HTMLElement;
+    fireEvent.keyDown(beta, { key: ' ' });
+    expect(onSelectionChange.mock.calls).toEqual([[['b']]]);
+    expect(onOpen).not.toHaveBeenCalled();
+    fireEvent.keyDown(beta, { key: 'Enter' });
+    expect(onSelectionChange.mock.calls.at(-1)).toEqual([['b']]);
+    expect(onOpen.mock.calls).toEqual([['b']]);
+  });
+
+  test('a disabled row does not open', () => {
+    const onOpen = mock((_id: string) => {});
+    const { getByText } = render(<TreeView nodes={NODES} onOpen={onOpen} />);
+    fireEvent.doubleClick(getByText('Gamma'));
+    expect(onOpen).not.toHaveBeenCalled();
+  });
+});
+
+describe('TreeView — sections', () => {
+  const SECTIONS = [
+    { id: 'lists', label: 'Lists', nodes: [{ id: 'todo', label: 'To-do list' }] },
+    { id: 'components', label: 'Components', nodes: [{ id: 'base', label: 'Generic item' }, { id: 'tool', label: 'Tool' }] },
+  ];
+
+  test('each section is a group named by its heading, and the heading is not a row', () => {
+    const { getByRole, getAllByRole } = render(<TreeView sections={SECTIONS} aria-label='Library' />);
+    expect(getByRole('group', { name: 'Lists' })).toBeTruthy();
+    expect(getByRole('group', { name: 'Components' })).toBeTruthy();
+    expect(getAllByRole('treeitem').map((item) => item.textContent)).toEqual(['To-do list', 'Generic item', 'Tool']);
+  });
+
+  test('🔴 one tab stop across every section, not one per section', () => {
+    const { getAllByRole } = render(<TreeView sections={SECTIONS} />);
+    const stops = getAllByRole('treeitem').filter((item) => item.tabIndex === 0);
+    expect(stops.map((item) => item.textContent)).toEqual(['To-do list']);
+  });
+
+  test('ArrowDown steps from the last row of one section to the first of the next, over the heading', () => {
+    const { getByText } = render(<TreeView sections={SECTIONS} />);
+    const todo = getByText('To-do list').closest('[role="treeitem"]') as HTMLElement;
+    todo.focus();
+    fireEvent.keyDown(todo, { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(getByText('Generic item').closest('[role="treeitem"]'));
+  });
+
+  test('a section with no label draws no heading', () => {
+    const { container } = render(<TreeView sections={[{ id: 'only', nodes: [{ id: 'x', label: 'X' }] }]} />);
+    expect(container.querySelector('[data-slot="tree-section"]')).toBeNull();
+  });
+});
+
+describe('TreeView — the tab stop', () => {
+  test('rests on the selected row until a row is focused', () => {
+    const { getAllByRole } = render(<TreeView nodes={NODES} selected={['b']} />);
+    expect(getAllByRole('treeitem').filter((item) => item.tabIndex === 0).map((item) => item.textContent)).toEqual(['Beta']);
+  });
+
+  test('🔴 survives the focused row being filtered away', () => {
+    const { getAllByRole, rerender } = render(<TreeView nodes={NODES} />);
+    const beta = getAllByRole('treeitem')[1] as HTMLElement;
+    fireEvent.focus(beta);
+    rerender(<TreeView nodes={NODES.filter((node) => node.id !== 'b')} />);
+    expect(getAllByRole('treeitem').filter((item) => item.tabIndex === 0)).toHaveLength(1);
+  });
+});
+
+describe('TreeView — the focus ring', () => {
+  // The DOM under test answers :focus-visible as the engine does; each case pins the answer so
+  // the spec holds whichever way this DOM would have decided.
+  const answering = (visible: boolean) => {
+    const proto = HTMLElement.prototype as unknown as { matches(selector: string): boolean };
+    const real = proto.matches;
+    proto.matches = function (this: HTMLElement, selector: string) {
+      return selector === ':focus-visible' ? visible : real.call(this, selector);
+    };
+    return () => {
+      proto.matches = real;
+    };
+  };
+  const rowOf = (el: HTMLElement) => el.closest('[role="treeitem"]')?.firstElementChild as HTMLElement;
+
+  test('🔴 a click selects the row and draws no ring (forge task 2839)', () => {
+    const restore = answering(false);
+    try {
+      const { getByText } = render(<TreeView nodes={NODES} />);
+      fireEvent.focus(getByText('Beta').closest('[role="treeitem"]') as HTMLElement);
+      fireEvent.click(getByText('Beta'));
+      expect(rowOf(getByText('Beta')).className).not.toContain('ring-2');
+    } finally {
+      restore();
+    }
+  });
+
+  test('keyboard focus draws it, on the focused row only — not on the parent that wraps it', () => {
+    const restore = answering(true);
+    try {
+      const { getByText } = render(<TreeView nodes={NODES} defaultExpanded={['a']} />);
+      fireEvent.focus(getByText('Alpha 1').closest('[role="treeitem"]') as HTMLElement);
+      expect(rowOf(getByText('Alpha 1')).className).toContain('ring-2');
+      expect(rowOf(getByText('Alpha')).className).not.toContain('ring-2');
+    } finally {
+      restore();
+    }
+  });
+});

package/src/react/components/TreeView.tsx

@@ -1,11 +1,13 @@
 import { ChevronRight, Loader2 } from 'lucide-react';
 import {
   createContext,
+  type HTMLAttributes,
   type KeyboardEvent,
   type ReactNode,
   useCallback,
   useContext,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
@@ -29,12 +31,39 @@ export interface TreeNode {
   /** True when children exist but haven't been fetched yet (triggers `onLoadChildren`). */
   hasChildren?: boolean;
   disabled?: boolean;
+  /**
+   * Trailing content after the label: a count, a status dot, a word or two of kind. Drawn muted
+   * and never truncated, so it says the same thing at any width; the label gives way first.
+   */
+  meta?: ReactNode;
+  /** A second, muted line under the label: why a search kept this row, a path, a summary. */
+  description?: ReactNode;
+  /**
+   * Attributes for the visible ROW — not the treeitem, which also wraps the node's children, so
+   * a hook on it would match every ancestor of the row you meant. A `data-*` an app's test or
+   * stylesheet keys on, a className.
+   */
+  rowProps?: HTMLAttributes<HTMLDivElement> & { [key: `data-${string}`]: string | undefined };
+}
+
+/** A run of root nodes under a heading ("Lists", "Components"). Arrow keys pass over the heading. */
+export interface TreeSection {
+  id: string;
+  /** The heading. Omitted, the section draws no heading (a single section, or the first). */
+  label?: ReactNode;
+  nodes: TreeNode[];
 }
 
 export type TreeSelectionMode = 'none' | 'single' | 'multi';
 
 export interface TreeViewProps {
-  nodes: TreeNode[];
+  /** The root nodes. Give `sections` instead to draw the roots in headed groups. */
+  nodes?: TreeNode[];
+  /**
+   * The roots in headed groups. One tree, one tab stop and one keyboard path across all of them
+   * — the arrows step from the last row of one section to the first of the next.
+   */
+  sections?: TreeSection[];
   /** Selection behavior (default `'single'`). */
   selectionMode?: TreeSelectionMode;
   /** Controlled selected ids. */
@@ -47,11 +76,18 @@ export interface TreeViewProps {
   onExpandedChange?: (ids: string[]) => void;
   /** Called to lazily load children for a node (they are cached after the first load). */
   onLoadChildren?: (id: string) => Promise<TreeNode[]>;
+  /**
+   * Open a node — a double-click, or Enter (which selects it first). Separate from selection:
+   * selecting shows a thing, opening acts on it (an editor, a document), as Finder and VS Code's
+   * explorer split the two. Space only selects.
+   */
+  onOpen?: (id: string) => void;
   /** Enable drag-to-reorder within each level (default `false`). */
   draggable?: boolean;
   /**
    * Called when nodes at a level are reordered.
-   * `parentId` is the parent node's id, or `null` for the root level.
+   * `parentId` is the parent node's id, or `null` for the root level — with `sections`, the
+   * section's id, since a row is dragged only within its own section.
    */
   onReorder?: (parentId: string | null, nodes: TreeNode[]) => void;
   className?: string;
@@ -67,6 +103,10 @@ interface TreeCtx {
   loading: Set<string>;
   childrenMap: Map<string, TreeNode[]>;
   focusedId: string | null;
+  /** Whether the focused row shows its ring: only when the browser calls that focus :focus-visible. */
+  ringVisible: boolean;
+  /** The one row with tabIndex 0: the focused row while it is visible, else the first selected, else the first. */
+  tabStop: string | null;
   selectionMode: TreeSelectionMode;
   draggable: boolean;
   /** Flat ordered list of currently-visible node ids (for keyboard navigation). */
@@ -78,8 +118,10 @@ interface TreeCtx {
   setExpanded: (id: string, open: boolean) => void;
   setSelected: (id: string, mod: { ctrl: boolean; shift: boolean }) => void;
   setFocused: (id: string | null) => void;
+  setRingVisible: (visible: boolean) => void;
   triggerLoad: (id: string) => void;
   handleReorder: (parentId: string | null, nodes: TreeNode[]) => void;
+  open: ((id: string) => void) | undefined;
 }
 
 const TreeContext = createContext<TreeCtx>(null!);
@@ -121,14 +163,26 @@ function buildParentMap(
   return map;
 }
 
+/** `:focus-visible`, where the engine knows it; a DOM without it keeps the ring (the old behaviour). */
+function isFocusVisible(el: HTMLElement): boolean {
+  try {
+    return el.matches(':focus-visible');
+  } catch {
+    return true;
+  }
+}
+
 function isExpandable(node: TreeNode, childrenMap: Map<string, TreeNode[]>): boolean {
   return Boolean(node.hasChildren || node.children?.length || childrenMap.has(node.id));
 }
 
 // --- Main component -------------------------------------------------------------
 
+const NO_NODES: TreeNode[] = [];
+
 export function TreeView({
-  nodes,
+  nodes: rootNodes,
+  sections,
   selectionMode = 'single',
   selected: controlledSelected,
   defaultSelected,
@@ -137,12 +191,20 @@ export function TreeView({
   defaultExpanded,
   onExpandedChange,
   onLoadChildren,
+  onOpen,
   draggable = false,
   onReorder,
   className,
   'aria-label': ariaLabel,
   'aria-labelledby': ariaLabelledBy,
 }: TreeViewProps) {
+  // Every root, in order, whichever way they were given: keyboard paths and parents cross sections.
+  const nodes = useMemo(
+    () => (sections ? sections.flatMap((section) => section.nodes) : (rootNodes ?? NO_NODES)),
+    [sections, rootNodes],
+  );
+  const headingId = useId();
+
   // Expanded state (controlled or internal)
   const expandedIsControlled = controlledExpanded !== undefined;
   const [expandedInternal, setExpandedInternal] = useState<Set<string>>(
@@ -173,6 +235,7 @@ export function TreeView({
   selectedRef.current = selected;
 
   const [focusedId, setFocused] = useState<string | null>(null);
+  const [ringVisible, setRingVisible] = useState(false);
   const [loading, setLoading] = useState<Set<string>>(new Set());
   const [childrenMap, setChildrenMap] = useState<Map<string, TreeNode[]>>(new Map());
 
@@ -193,6 +256,13 @@ export function TreeView({
 
   const parentMap = useMemo(() => buildParentMap(nodes, childrenMap), [nodes, childrenMap]);
 
+  // 🔴 Computed from what is VISIBLE, not "the first root": with sections every section's first
+  // row was a tab stop, and a focused row that a filter then hid left the tree with none at all.
+  const tabStop =
+    focusedId !== null && visibleIds.includes(focusedId)
+      ? focusedId
+      : (visibleIds.find((id) => selected.has(id)) ?? visibleIds[0] ?? null);
+
   const triggerLoad = useCallback(
     (id: string) => {
       if (!onLoadChildren || loadingRef.current.has(id) || childrenMapRef.current.has(id)) return;
@@ -265,6 +335,8 @@ export function TreeView({
       loading,
       childrenMap,
       focusedId,
+      ringVisible,
+      tabStop,
       selectionMode,
       draggable,
       visibleIds,
@@ -273,8 +345,10 @@ export function TreeView({
       setExpanded,
       setSelected,
       setFocused,
+      setRingVisible,
       triggerLoad,
       handleReorder,
+      open: onOpen,
     }),
     [
       expanded,
@@ -282,6 +356,8 @@ export function TreeView({
       loading,
       childrenMap,
       focusedId,
+      ringVisible,
+      tabStop,
       selectionMode,
       draggable,
       visibleIds,
@@ -291,6 +367,7 @@ export function TreeView({
       setSelected,
       triggerLoad,
       handleReorder,
+      onOpen,
     ],
   );
 
@@ -303,7 +380,31 @@ export function TreeView({
         aria-multiselectable={selectionMode === 'multi' || undefined}
         className={cn('select-none', className)}
       >
-        <TreeLevel nodes={nodes} parentId={null} level={1} />
+        {sections ? (
+          sections.map((section) => (
+            // biome-ignore lint/a11y/useSemanticElements: an ARIA tree's grouping is role="group"; a <fieldset> is a form control group.
+            <div
+              key={section.id}
+              role='group'
+              aria-labelledby={section.label != null ? `${headingId}-${section.id}` : undefined}
+            >
+              {section.label != null && (
+                // aria-hidden: the group is named BY it, so it is not read a second time as a row.
+                <div
+                  id={`${headingId}-${section.id}`}
+                  aria-hidden='true'
+                  data-slot='tree-section'
+                  className='px-2 pt-3 pb-1 text-xs font-medium text-muted-foreground first:pt-1'
+                >
+                  {section.label}
+                </div>
+              )}
+              <TreeLevel nodes={section.nodes} parentId={null} reorderId={section.id} level={1} />
+            </div>
+          ))
+        ) : (
+          <TreeLevel nodes={nodes} parentId={null} reorderId={null} level={1} />
+        )}
       </div>
     </TreeContext.Provider>
   );
@@ -314,10 +415,13 @@ export function TreeView({
 function TreeLevel({
   nodes,
   parentId,
+  reorderId,
   level,
 }: {
   nodes: TreeNode[];
   parentId: string | null;
+  /** What `onReorder` is told the level is: the parent's id, or a section's at the root. */
+  reorderId: string | null;
   level: number;
 }) {
   const { draggable, handleReorder } = useContext(TreeContext);
@@ -325,7 +429,7 @@ function TreeLevel({
   const { DragContext, Sortable, items } = useDragReorder({
     items: nodes,
     getKey: (n) => n.id,
-    onReorder: (next) => handleReorder(parentId, next),
+    onReorder: (next) => handleReorder(reorderId, next),
     disabled: !draggable,
     handle: true,
   });
@@ -375,6 +479,8 @@ function TreeItem({
     loading,
     childrenMap,
     focusedId,
+    ringVisible,
+    tabStop,
     selectionMode,
     draggable,
     visibleIds,
@@ -383,7 +489,9 @@ function TreeItem({
     setExpanded,
     setSelected,
     setFocused,
+    setRingVisible,
     triggerLoad,
+    open,
   } = useContext(TreeContext);
 
   const isExpanded = expanded.has(node.id);
@@ -413,9 +521,7 @@ function TreeItem({
     }
   }, [isFocused]);
 
-  // First item at the root gets tabIndex=0 before any interaction.
-  const isDefaultFocusable = focusedId === null && posInSet === 1 && level === 1;
-  const tabIndex = isFocused || isDefaultFocusable ? 0 : -1;
+  const tabIndex = tabStop === node.id ? 0 : -1;
 
   const handleExpand = useCallback(
     (e: React.MouseEvent) => {
@@ -527,6 +633,7 @@ function TreeItem({
             ctrl: selectionMode === 'multi',
             shift: false,
           });
+          if (e.key === 'Enter') open?.(node.id);
           break;
         }
       }
@@ -545,9 +652,19 @@ function TreeItem({
       setExpanded,
       setSelected,
       triggerLoad,
+      open,
     ],
   );
 
+  const handleDoubleClick = useCallback(
+    (e: React.MouseEvent) => {
+      // Stopped for the same reason as a click: an ancestor's treeitem would open too.
+      e.stopPropagation();
+      if (!node.disabled) open?.(node.id);
+    },
+    [node, open],
+  );
+
   return (
     <div
       ref={mergeRef}
@@ -560,10 +677,17 @@ function TreeItem({
       aria-disabled={node.disabled || undefined}
       tabIndex={tabIndex}
       onClick={handleClick}
+      onDoubleClick={open ? handleDoubleClick : undefined}
       onKeyDown={handleKeyDown}
       // Only the row itself: focus bubbles too, and a nested row's focus named its parent focused.
       onFocus={(e) => {
-        if (e.target === e.currentTarget) setFocused(node.id);
+        if (e.target !== e.currentTarget) return;
+        setFocused(node.id);
+        // 🔴 The ring is for the KEYBOARD. Drawn on every focus, a click left a 2px ring around
+        // the row it selected (desk's Components tree, forge task 2839). The browser already
+        // decides which focus is visible — Tab and the arrows' programmatic focus are, a click
+        // is not — so ask it, rather than a CSS variant that put +453 B in every consumer.
+        setRingVisible(isFocusVisible(e.currentTarget));
       }}
       style={dragApi.style}
       // A disabled row reads in muted ink, not at half opacity: opacity-50 dragged its text
@@ -572,6 +696,7 @@ function TreeItem({
     >
       {/* Row */}
       <div
+        {...node.rowProps}
         className={cn(
           // 32px rows for a mouse, as VS Code's explorer and Finder's list run; a touch screen
           // still gets the 44px target (LAY-13). Every row was 44px everywhere (forge task 2594).
@@ -581,9 +706,11 @@ function TreeItem({
           // text-accent-strong (cbux-101) — plain text-accent only clears 4.43:1 on this tint.
           isSelected && 'bg-accent/10 text-accent-strong font-medium',
           dragApi.isDragging && 'opacity-50',
-          isFocused && 'ring-2 ring-inset ring-ring',
+          isFocused && ringVisible && 'ring-2 ring-inset ring-ring',
+          node.description != null && 'py-1',
+          node.rowProps?.className,
         )}
-        style={{ paddingLeft: `calc(${(level - 1) * INDENT_PX}px + 0.25rem)` }}
+        style={{ ...node.rowProps?.style, paddingLeft: `calc(${(level - 1) * INDENT_PX}px + 0.25rem)` }}
       >
         {/* Drag handle — visible on hover, always present when drag enabled */}
         {draggable && (
@@ -622,15 +749,35 @@ function TreeItem({
           </span>
         )}
 
-        {/* Label */}
-        <span className='min-w-0 flex-1 truncate'>{node.label}</span>
+        {/* Label, and the line under it */}
+        {node.description != null ? (
+          <span className='flex min-w-0 flex-1 flex-col'>
+            <span data-slot='tree-label' className='truncate'>
+              {node.label}
+            </span>
+            <span data-slot='tree-description' className='truncate text-xs font-normal text-muted-foreground'>
+              {node.description}
+            </span>
+          </span>
+        ) : (
+          <span data-slot='tree-label' className='min-w-0 flex-1 truncate'>
+            {node.label}
+          </span>
+        )}
+
+        {/* Trailing meta — after the label, which gives way first */}
+        {node.meta != null && (
+          <span data-slot='tree-meta' className='flex shrink-0 items-center gap-1.5 text-xs font-normal text-muted-foreground'>
+            {node.meta}
+          </span>
+        )}
       </div>
 
       {/* Children (only rendered when expanded and children are available) */}
       {expandable && isExpanded && children.length > 0 && (
         // biome-ignore lint/a11y/useSemanticElements: ARIA tree spec requires role="group" on the children container; <fieldset> is semantically wrong here.
         <div role='group'>
-          <TreeLevel nodes={children} parentId={node.id} level={level + 1} />
+          <TreeLevel nodes={children} parentId={node.id} reorderId={node.id} level={level + 1} />
         </div>
       )}
     </div>

package/src/react/components/editorPage.css

@@ -124,13 +124,7 @@
 		box-sizing: border-box;
 		min-width: 0;
 		min-height: 0;
-		/* guardrails-ignore no-raw-overflow: task 2827 — each side scrolls on its own in a Tailwind-free host, where ScrollArea cannot draw; the keyboard inset below is ScrollArea's. */
-		overflow: auto;
-		overscroll-behavior: contain;
-		/* ScrollArea's keyboard clearance (a no-op 0px on desktop): a focused field is never
-		   parked under a phone's keyboard, and the last one can be scrolled above it. */
-		scroll-padding-bottom: calc(var(--keyboard-inset, 0px) + 1rem);
-		padding-bottom: var(--keyboard-inset, 0px);
+		/* Each side scrolls on its own: `.cbfk-scroll` (scrollRegion.css) on the element. */
 	}
 
 	.cbfk-page-form {

package/src/react/components/formKit.css

@@ -470,11 +470,8 @@
 	.cbfk-split-body {
 		max-height: 45dvh;
 		margin-top: 0.5rem;
-		/* A card taller than 45dvh scrolls inside the pinned bar rather than covering the form.
-		   guardrails-ignore no-raw-overflow: plain CSS for a no-Tailwind host — ScrollArea is a
-		   React component and this is one capped box inside a sticky bar, with no keyboard to clear. */
-		overflow: auto;
-		overscroll-behavior: contain;
+		/* A card taller than 45dvh scrolls inside the pinned bar (`.cbfk-scroll`, scrollRegion.css)
+		   rather than covering the form. */
 	}
 
 	.cbfk-split[data-preview-open="false"] .cbfk-split-body {
@@ -533,7 +530,9 @@
 			grid-column: 1 / -1;
 		}
 
-		.cbfk-split-body,
+		/* `.cbfk-split` in front so this out-ranks `.cbfk-scroll` (scrollRegion.css), which loads
+		   after this sheet: wide, the preview is not a scroller. */
+		.cbfk-split .cbfk-split-body,
 		.cbfk-split[data-preview-open="false"] .cbfk-split-body {
 			display: block;
 			max-height: none;

package/src/react/components/formKit.spec.tsx

@@ -135,4 +135,13 @@ describe('KeyBadge / SettingsStrip / FormPreviewLayout', () => {
     expect(getByRole('region', { name: 'Preview' })).not.toBeNull();
     expect(container.querySelector('.cbfk-split-below ol')).not.toBeNull();
   });
+
+  test('FormPreviewLayout: the pinned preview scrolls through the form kit’s scroller (forge task 2827)', () => {
+    const { container } = render(
+      <FormPreviewLayout preview={<p>card</p>} previewLabel='Preview' previewSummary={<span>DY</span>}>
+        <Input aria-label='Name' />
+      </FormPreviewLayout>,
+    );
+    expect(container.querySelector('.cbfk-split-body')?.classList.contains('cbfk-scroll')).toBe(true);
+  });
 });

package/src/react/components/scrollRegion.css

@@ -0,0 +1,31 @@
+/*
+ * The form kit's scroll region — `.cbfk-scroll`. Its own file, imported only by the pieces that
+ * scroll (`EditorPage`, `FormPreviewLayout`), because `formKit.css` lands in every view that
+ * draws one KeyBadge (see formKitStylesheets.spec.ts): in formKit.css it cost station's
+ * DuplicatesView and music's TubeView +0.06 kB gzip each for a box neither draws.
+ *
+ * Inside `@layer base`, for formKit.css's reason: a Tailwind app's utilities must still win.
+ */
+
+@layer base {
+	/* `ScrollArea`, drawn from plain CSS for a host with no Tailwind (forge task 2827). A form-kit
+	   box that scrolls takes this class and `useCaretInView`'s `onFocusCapture`, and never writes
+	   `overflow` itself — `no-raw-overflow` accepts this one rule, and only while it carries the
+	   keyboard clearance below. `--keyboard-inset` is `0px` on a desktop, so it is a no-op there.
+	   - `scroll-padding-bottom` keeps the browser's own "scroll the focused field into view" from
+	     parking a field under a phone's keyboard;
+	   - the `::after` spacer lifts the last row above the keyboard. It is ScrollArea's trailing
+	     spacer: ADDED to the box's own padding, so a box's `padding` shorthand cannot undo it;
+	   - `overscroll-behavior: contain` keeps pull-to-refresh from bleeding through. */
+	.cbfk-scroll {
+		overflow: auto;
+		overscroll-behavior: contain;
+		scroll-padding-bottom: calc(var(--keyboard-inset, 0px) + 1rem);
+	}
+
+	.cbfk-scroll::after {
+		content: "";
+		display: block;
+		height: var(--keyboard-inset, 0px);
+	}
+}

package/src/react/index.ts

@@ -170,6 +170,7 @@ export { CodeArea, type CodeAreaProps } from './components/CodeArea.js';
 export { CodeFieldInput, type CodeFieldInputProps } from './components/CodeFieldInput.js';
 export { Collapsible, type CollapsibleProps } from './components/Collapsible.js';
 export { ColorField, type ColorFieldProps } from './components/ColorField.js';
+export { ColorSwatches, type ColorSwatchesProps } from './components/ColorSwatches.js';
 export {
   ComboboxField,
   type ComboboxFieldMultiProps,
@@ -679,6 +680,7 @@ export {
 } from './components/Tooltip.js';
 export {
   type TreeNode,
+  type TreeSection,
   type TreeSelectionMode,
   TreeView,
   type TreeViewProps,

package/src/react/master-detail/MasterDetail.spec.tsx

@@ -59,3 +59,24 @@ describe('MasterDetail — DESIGN.md §2 empty states', () => {
     expect(getByText('Nothing matches.')).toBeTruthy();
   });
 });
+
+describe('MasterDetail — a row keeps its title before its subtitle', () => {
+  test('the subtitle shrinks first, and the title can still truncate once it is gone', () => {
+    // 🔴 Seen on station's queue at 390 (forge task 2849): title and file name shrank equally,
+    // so every title read "A session t…" beside its whole file name. happy-dom draws no layout,
+    // so this pins the two classes that decide the split.
+    const { getByText } = render(
+      <MasterDetail
+        items={[{ id: 'q', title: 'A session task', subtitle: '102-a-session-task.md' }]}
+        selectedId={null}
+        onSelect={() => {}}
+        detail={<p>detail</p>}
+      />,
+    );
+    const subtitle = getByText('102-a-session-task.md');
+    expect(subtitle.getAttribute('data-slot')).toBe('master-detail-subtitle');
+    expect(subtitle.className).toContain('shrink-[1000]');
+    expect(subtitle.className).toContain('min-w-0');
+    expect(getByText('A session task').className).toContain('min-w-0');
+  });
+});