cursedbelt 5.52.2 → 5.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.52.2",
+	"version": "5.54.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -384,6 +384,12 @@
 			"source": "./src/react/pdf-viewer/index.ts",
 			"import": "./dist/react/pdf-viewer/index.js"
 		},
+		"./react/place-bar": {
+			"types": "./dist/react/place-bar/index.d.ts",
+			"bun": "./src/react/place-bar/index.ts",
+			"source": "./src/react/place-bar/index.ts",
+			"import": "./dist/react/place-bar/index.js"
+		},
 		"./react/popover": {
 			"types": "./dist/react/components/Popover.d.ts",
 			"bun": "./src/react/components/Popover.tsx",
@@ -420,6 +426,12 @@
 			"source": "./src/react/components/SecretInput.tsx",
 			"import": "./dist/react/components/SecretInput.js"
 		},
+		"./react/native-select": {
+			"types": "./dist/react/components/NativeSelect.d.ts",
+			"bun": "./src/react/components/NativeSelect.tsx",
+			"source": "./src/react/components/NativeSelect.tsx",
+			"import": "./dist/react/components/NativeSelect.js"
+		},
 		"./react/select-field": {
 			"types": "./dist/react/components/SelectField.d.ts",
 			"bun": "./src/react/components/SelectField.tsx",
@@ -492,6 +504,12 @@
 			"source": "./src/react/components/MultiSelectField.tsx",
 			"import": "./dist/react/components/MultiSelectField.js"
 		},
+		"./react/section-nav": {
+			"types": "./dist/react/components/SectionNav.d.ts",
+			"bun": "./src/react/components/SectionNav.tsx",
+			"source": "./src/react/components/SectionNav.tsx",
+			"import": "./dist/react/components/SectionNav.js"
+		},
 		"./react/segmented-control": {
 			"types": "./dist/react/components/SegmentedControl.d.ts",
 			"bun": "./src/react/components/SegmentedControl.tsx",
@@ -594,6 +612,7 @@
 		"./styles-areas/overlays.css": "./src/styles-areas/overlays.css",
 		"./styles-areas/palette.css": "./src/styles-areas/palette.css",
 		"./styles-areas/pdf-viewer.css": "./src/styles-areas/pdf-viewer.css",
+		"./styles-areas/place-bar.css": "./src/styles-areas/place-bar.css",
 		"./styles-areas/problem-detail.css": "./src/styles-areas/problem-detail.css",
 		"./styles-areas/rich-text.css": "./src/styles-areas/rich-text.css",
 		"./styles-areas/sharing.css": "./src/styles-areas/sharing.css",
@@ -890,7 +909,7 @@
 		"clsx": "^2.1.1",
 		"cmdk": "^1.1.1",
 		"cursedbelt-core": "^2.10.0",
-		"cwip": "^4.6.0",
+		"cwip": "^4.12.0",
 		"lucide-react": "^1.21.0",
 		"react-hook-form": "^7.80.0",
 		"react-resizable-panels": "^4.12.0",

package/scripts/styleAreas.ts

@@ -174,6 +174,7 @@ export const AREAS: readonly Area[] = [
 			'components/InfoHint.tsx',
 			'components/InfoHintImpl.tsx',
 			'components/Input.tsx',
+			'components/ListPanel.tsx',
 			'components/Menu.tsx',
 			'components/Modal.tsx',
 			'components/OnlineDot.tsx',
@@ -266,6 +267,8 @@ export const AREAS: readonly Area[] = [
 			'components/RenderField.tsx',
 			'components/SearchInput.tsx',
 			'components/SecretInput.tsx',
+			// A settings page's section column / phone strip (forge task 2752).
+			'components/SectionNav.tsx',
 			'components/SliderField.tsx',
 			'components/StarRating.tsx',
 			'components/SwatchPicker.tsx',
@@ -341,6 +344,11 @@ export const AREAS: readonly Area[] = [
 	},
 	{ name: 'palette', why: 'the ⌘K command palette and its hotkey/source hooks', roots: ['palette'] },
 	{ name: 'pdf-viewer', why: 'the lazy PDF viewer (an optional peer already)', roots: ['pdf-viewer'] },
+	{
+		name: 'place-bar',
+		why: 'the `cursedbelt/react/place-bar` phone bottom bar, for an app that mounts it without the AppShell (desk)',
+		roots: ['place-bar'],
+	},
 	{ name: 'problem-detail', why: 'the RFC-7807 problem renderer', roots: ['problem-detail'] },
 	{ name: 'rich-text', why: 'the TipTap editor and its toolbar', roots: ['rich-text'] },
 	{ name: 'sharing', why: 'the share sheet and its permission rows', roots: ['sharing', 'components/sharing'] },

package/src/react/activity-bar/ActivityBar.spec.tsx

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { cleanup, fireEvent, render, screen } from '@testing-library/react';
-import { ActivityBar, type ActivityBarItem } from './ActivityBar.js';
+import { ActivityBar, type ActivityBarItem, EXPAND_HOVER_MS, EXPAND_PRESS_MS } from './ActivityBar.js';
 
 /**
  * What is worth pinning here.
@@ -125,3 +125,108 @@ describe("a consumer's own widget", () => {
     expect(screen.queryByLabelText('Account')).toBeNull();
   });
 });
+
+describe('the rail shows its words on demand (NAV-2, forge task 2748)', () => {
+  /*
+   * What is pinned is the STATE machine — `data-expanded` and which way in set it — because
+   * the width and the visible label are CSS, which happy-dom does not compute. The browser
+   * spec in desk (`test/browser/rail-words.test.ts`) measures the overlay itself.
+   */
+  const rail = () => screen.getByRole('group');
+  const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+  const pointer = (pointerType: string, x = 10, y = 10) => ({ pointerType, clientX: x, clientY: y, bubbles: true });
+
+  test('every control carries its word, hidden until the rail expands', () => {
+    render(<ActivityBar top={[item()]} />);
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+    expect(rail().querySelector('.cbab-label')?.textContent).toBe('Files');
+  });
+
+  test('a mouse resting on the rail expands it, and leaving folds it', async () => {
+    render(<ActivityBar top={[item()]} />);
+    fireEvent.pointerOver(rail(), pointer('mouse'));
+    await wait(EXPAND_HOVER_MS + 50);
+    expect(rail().getAttribute('data-expanded')).toBe('hover');
+    fireEvent.pointerOut(rail(), pointer('mouse'));
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+  });
+
+  test('a mouse that only crosses the rail does not expand it', async () => {
+    render(<ActivityBar top={[item()]} />);
+    fireEvent.pointerOver(rail(), pointer('mouse'));
+    fireEvent.pointerOut(rail(), pointer('mouse'));
+    await wait(EXPAND_HOVER_MS + 50);
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+  });
+
+  test('a touch-and-hold expands it, and the hold does not press the button', async () => {
+    let pressed = 0;
+    render(<ActivityBar top={[item({ onSelect: () => pressed++ })]} />);
+    const button = screen.getByLabelText('Files');
+    fireEvent.pointerDown(button, pointer('touch'));
+    await wait(EXPAND_PRESS_MS + 50);
+    expect(rail().getAttribute('data-expanded')).toBe('press');
+    fireEvent.pointerUp(button, pointer('touch'));
+    fireEvent.click(button);
+    expect(pressed).toBe(0);
+    // A tap now — the labels on screen — is the button's own, and folds the rail.
+    fireEvent.pointerDown(button, pointer('touch'));
+    fireEvent.pointerUp(button, pointer('touch'));
+    fireEvent.click(button);
+    expect(pressed).toBe(1);
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+  });
+
+  test('a touch that drifts is a scroll, not a hold', async () => {
+    render(<ActivityBar top={[item()]} />);
+    const button = screen.getByLabelText('Files');
+    fireEvent.pointerDown(button, pointer('touch', 10, 10));
+    fireEvent.pointerMove(button, pointer('touch', 10, 40));
+    await wait(EXPAND_PRESS_MS + 50);
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+  });
+
+  test('a touch outside folds a held-open rail', async () => {
+    render(
+      <>
+        <ActivityBar top={[item()]} />
+        <p>page</p>
+      </>,
+    );
+    fireEvent.pointerDown(screen.getByLabelText('Files'), pointer('touch'));
+    await wait(EXPAND_PRESS_MS + 50);
+    fireEvent.pointerUp(screen.getByLabelText('Files'), pointer('touch'));
+    expect(rail().getAttribute('data-expanded')).toBe('press');
+    fireEvent.pointerDown(screen.getByText('page'), pointer('touch'));
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+  });
+
+  test('Escape folds it', async () => {
+    render(<ActivityBar top={[item()]} />);
+    fireEvent.pointerOver(rail(), pointer('mouse'));
+    await wait(EXPAND_HOVER_MS + 50);
+    fireEvent.keyDown(screen.getByLabelText('Files'), { key: 'Escape' });
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+  });
+
+  test('expandable={false} keeps the icon-only column', async () => {
+    render(<ActivityBar top={[item()]} expandable={false} />);
+    fireEvent.pointerOver(rail(), pointer('mouse'));
+    await wait(EXPAND_HOVER_MS + 50);
+    expect(rail().getAttribute('data-expanded')).toBeNull();
+  });
+
+  test('a count rides the expanded row, and zero draws nothing', () => {
+    render(<ActivityBar top={[item({ count: 1200 }), item({ id: 'trash', label: 'Trash', count: 0 })]} />);
+    const counts = rail().querySelectorAll('.cbab-count');
+    expect(counts).toHaveLength(1);
+    expect(counts[0]?.textContent).toBe((1200).toLocaleString());
+  });
+
+  test('onSelect is handed the pressed button, so a menu can anchor to it', () => {
+    const triggers: HTMLButtonElement[] = [];
+    render(<ActivityBar top={[item({ onSelect: (node) => triggers.push(node) })]} />);
+    fireEvent.click(screen.getByLabelText('Files'));
+    expect(triggers).toEqual([screen.getByLabelText('Files') as HTMLButtonElement]);
+  });
+});

package/src/react/activity-bar/ActivityBar.tsx

@@ -49,6 +49,20 @@
  * {@link ActivityBarItem.render} takes the consumer's own popover, and
  * {@link ActivityBarItem.hasMenu}/{@link ActivityBarItem.menuOpen} say so to a screen reader.
  *
+ * ── 🔴 It shows its WORDS on demand (NAV-2, forge task 2748) ───────────────────────────
+ * An icon-only rail is a row of riddles: `DESIGN.md`'s NAV-2 wants every navigation surface
+ * to be able to say what each glyph is without a hover on each one. So the column stays 48px
+ * and EXPANDS, as an overlay over whatever is beside it (nothing reflows), into icon + label
+ * rows — the hover-expand rail Gmail and the Azure portal draw, and the labelled activity
+ * bar VS Code's own users keep asking for. Three ways in, one for each kind of hand:
+ *  · a mouse resting on the rail for {@link EXPAND_HOVER_MS} (the delay is what lets a pointer
+ *    cross the rail on its way to the sidebar without the rail flaring at it);
+ *  · keyboard focus arriving in it (`:focus-visible`), so tabbing reads the words too;
+ *  · a touch-and-hold of {@link EXPAND_PRESS_MS} on any control — the hold is swallowed, so
+ *    reading the labels never also presses the button under the thumb.
+ * It folds again when the mouse leaves, focus leaves, a touch lands outside it, Escape is
+ * pressed, or a control is chosen. {@link ActivityBarProps.expandable} `false` opts out.
+ *
  * ── Plain CSS, deliberately ─────────────────────────────────────────────────────────────
  * `activityBar.css` under the `cbab-` prefix, the same convention (and the same reason) as
  * `fileTree.css` and `denseGallery.css`: this mounts inside apps whose Tailwind build cannot
@@ -56,7 +70,18 @@
  * ships a NARROWED `@source` list and has already shipped one unstyled control from exactly
  * that gap.
  */
-import type { JSX, ReactNode } from 'react';
+import {
+  type FocusEvent,
+  type JSX,
+  type KeyboardEvent,
+  type MouseEvent,
+  type PointerEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
 import { Tooltip } from '../components/Tooltip.js';
 import './activityBar.css';
 
@@ -87,7 +112,12 @@ export interface ActivityBarItem {
   icon?: ReactNode;
   /** Drawn as the view you are in — a hairline, not a box. See the file header. */
   active?: boolean;
-  onSelect?: () => void;
+  /**
+   * The press. It is handed the button that was pressed, so a control that opens a popover can
+   * anchor it — and name it as the trigger, so a second press closes rather than re-opens —
+   * without needing a {@link render} slot of its own.
+   */
+  onSelect?: (trigger: HTMLButtonElement) => void;
   /**
    * Why this cannot act right now. Present ⇒ the control is DISABLED and says why on hover,
    * never hidden — `DESIGN.md`'s standing rule, and the reason an owner UI is one UI.
@@ -102,6 +132,13 @@ export interface ActivityBarItem {
    * says *look here*; what the number is belongs to whatever the button opens.
    */
   badge?: boolean;
+  /**
+   * How many — drawn at the END of the expanded row only (Gmail's expanded rail: "Inbox 3"),
+   * where there is room for a number at full size. Collapsed, the 20px glyph has none, which
+   * is why {@link badge} stays a dot; put the number in {@link title} as well so a hover
+   * reads it there. Zero or absent draws nothing.
+   */
+  count?: number;
   /**
    * Render this instead of a button. For a widget the consumer already owns — an account
    * menu, a fleet launcher — that has to keep its own behaviour and its own popover.
@@ -125,9 +162,24 @@ export interface ActivityBarProps {
   /** Names the whole column for a screen reader. */
   ariaLabel?: string;
   className?: string;
+  /**
+   * Expand into icon + label rows on a hover, keyboard focus or touch-and-hold — see the file
+   * header. Default `true`: NAV-2 is the design law, not a preference. `false` keeps the
+   * icon-only column (a rail whose every control is already named beside it).
+   */
+  expandable?: boolean;
 }
 
-function ActivityButton({ item }: { item: ActivityBarItem }): JSX.Element {
+/** How long a mouse rests on the rail before it opens its words. */
+export const EXPAND_HOVER_MS = 350;
+/** How long a touch holds before the rail opens its words — Android's long-press. */
+export const EXPAND_PRESS_MS = 450;
+/** A hold that drifts further than this is a scroll or a drag, not a press. */
+const PRESS_SLOP_PX = 10;
+
+type ExpandedBy = 'hover' | 'focus' | 'press' | null;
+
+function ActivityButton({ item, onChosen }: { item: ActivityBarItem; onChosen: () => void }): JSX.Element {
   const disabled = item.unavailableReason !== undefined;
   const button = (
     <button
@@ -138,7 +190,14 @@ function ActivityButton({ item }: { item: ActivityBarItem }): JSX.Element {
       type='button'
       className='cbab-btn'
       data-active={item.active || undefined}
-      onClick={disabled ? undefined : item.onSelect}
+      onClick={
+        disabled
+          ? undefined
+          : (event: MouseEvent<HTMLButtonElement>) => {
+              item.onSelect?.(event.currentTarget);
+              onChosen();
+            }
+      }
       /*
        * 🔴 `aria-disabled`, not `disabled`. A disabled button is not focusable and does not
        * fire the pointer events a tooltip listens for, so the REASON — the only thing that
@@ -152,8 +211,18 @@ function ActivityButton({ item }: { item: ActivityBarItem }): JSX.Element {
     >
       <span className='cbab-glyph' aria-hidden='true'>
         {item.icon}
+        {item.badge ? <span className='cbab-badge' /> : null}
       </span>
-      {item.badge ? <span className='cbab-badge' aria-hidden='true' /> : null}
+      {/* The word. Hidden by the stylesheet until the rail expands; `aria-hidden` because
+          `aria-label` already names the button, and a name read twice is noise. */}
+      <span className='cbab-label' aria-hidden='true'>
+        {item.label}
+      </span>
+      {item.count ? (
+        <span className='cbab-count' aria-hidden='true'>
+          {item.count.toLocaleString()}
+        </span>
+      ) : null}
     </button>
   );
   return (
@@ -163,16 +232,21 @@ function ActivityButton({ item }: { item: ActivityBarItem }): JSX.Element {
   );
 }
 
-function Group({ items }: { items: readonly ActivityBarItem[] }): JSX.Element | null {
+function Group({ items, onChosen }: { items: readonly ActivityBarItem[]; onChosen: () => void }): JSX.Element | null {
   if (items.length === 0) return null;
   return (
     <div className='cbab-group'>
       {items.map((item) =>
         item.render === undefined ? (
-          <ActivityButton item={item} key={item.id} />
+          <ActivityButton item={item} key={item.id} onChosen={onChosen} />
         ) : (
-          <div className='cbab-slot' key={item.id}>
-            {item.render}
+          /* A borrowed widget keeps its own behaviour, so expanded it gets its word BESIDE it
+             rather than inside it — the slot is still the 40px square it always was. */
+          <div className='cbab-slotrow' key={item.id}>
+            <div className='cbab-slot'>{item.render}</div>
+            <span className='cbab-label' aria-hidden='true'>
+              {item.label}
+            </span>
           </div>
         ),
       )}
@@ -180,12 +254,132 @@ function Group({ items }: { items: readonly ActivityBarItem[] }): JSX.Element |
   );
 }
 
+/** `:focus-visible` — a keyboard arrival, not a click. Old engines without it count as one. */
+function focusVisible(node: Element): boolean {
+  try {
+    return node.matches(':focus-visible');
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * The expand machinery, apart from the markup so the rules read in one place. Each way in
+ * remembers WHICH way it came, because each way out only undoes its own: a mouse leaving must
+ * not fold a rail the keyboard opened, and a focus leaving must not fold one the hand holds.
+ */
+function useExpand(enabled: boolean) {
+  const [by, setBy] = useState<ExpandedBy>(null);
+  const root = useRef<HTMLFieldSetElement>(null);
+  const hoverTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const press = useRef<{ x: number; y: number; timer?: ReturnType<typeof setTimeout>; held: boolean }>({
+    x: 0,
+    y: 0,
+    held: false,
+  });
+
+  const clearHover = () => {
+    if (hoverTimer.current !== undefined) clearTimeout(hoverTimer.current);
+    hoverTimer.current = undefined;
+  };
+  const clearPress = () => {
+    if (press.current.timer !== undefined) clearTimeout(press.current.timer);
+    press.current.timer = undefined;
+  };
+  // Refs only, so it is stable across renders — it is handed to every control as `onChosen`.
+  const collapse = useCallback(() => {
+    clearTimeout(hoverTimer.current);
+    hoverTimer.current = undefined;
+    clearTimeout(press.current.timer);
+    press.current.timer = undefined;
+    setBy(null);
+  }, []);
+
+  // Timers die with the rail; a late one would set state on nothing.
+  useEffect(
+    () => () => {
+      clearTimeout(hoverTimer.current);
+      clearTimeout(press.current.timer);
+    },
+    [],
+  );
+
+  // Opened by a hold, it folds on a touch anywhere else — there is no "pointer leaves" on glass.
+  useEffect(() => {
+    if (by !== 'press') return;
+    const outside = (event: globalThis.PointerEvent) => {
+      if (!root.current?.contains(event.target as Node)) setBy(null);
+    };
+    document.addEventListener('pointerdown', outside, true);
+    return () => document.removeEventListener('pointerdown', outside, true);
+  }, [by]);
+
+  if (!enabled) return { root, by: null, handlers: {}, collapse };
+
+  const handlers = {
+    onPointerEnter(event: PointerEvent<HTMLFieldSetElement>) {
+      if (event.pointerType !== 'mouse' || by !== null) return;
+      clearHover();
+      hoverTimer.current = setTimeout(() => setBy((current) => current ?? 'hover'), EXPAND_HOVER_MS);
+    },
+    onPointerLeave(event: PointerEvent<HTMLFieldSetElement>) {
+      if (event.pointerType !== 'mouse') return;
+      clearHover();
+      setBy((current) => (current === 'hover' ? null : current));
+    },
+    onPointerDown(event: PointerEvent<HTMLFieldSetElement>) {
+      if (event.pointerType === 'mouse') return;
+      clearPress();
+      press.current = { x: event.clientX, y: event.clientY, held: false };
+      press.current.timer = setTimeout(() => {
+        press.current.held = true;
+        press.current.timer = undefined;
+        setBy('press');
+      }, EXPAND_PRESS_MS);
+    },
+    onPointerMove(event: PointerEvent<HTMLFieldSetElement>) {
+      if (press.current.timer === undefined) return;
+      if (Math.hypot(event.clientX - press.current.x, event.clientY - press.current.y) > PRESS_SLOP_PX) clearPress();
+    },
+    onPointerUp: clearPress,
+    onPointerCancel: clearPress,
+    /* 🔴 The hold is SWALLOWED: the click a lifted thumb fires would otherwise press the very
+       control whose label it was reading. Capture phase, so the button never sees it. */
+    onClickCapture(event: MouseEvent<HTMLFieldSetElement>) {
+      if (!press.current.held) return;
+      press.current.held = false;
+      event.preventDefault();
+      event.stopPropagation();
+    },
+    // iOS/Android raise their own long-press menu on the same gesture.
+    onContextMenu(event: MouseEvent<HTMLFieldSetElement>) {
+      if (press.current.held || press.current.timer !== undefined) event.preventDefault();
+    },
+    onFocus(event: FocusEvent<HTMLFieldSetElement>) {
+      if (focusVisible(event.target)) setBy((current) => current ?? 'focus');
+    },
+    onBlur(event: FocusEvent<HTMLFieldSetElement>) {
+      if (root.current?.contains(event.relatedTarget as Node | null)) return;
+      setBy((current) => (current === 'focus' ? null : current));
+    },
+    onKeyDown(event: KeyboardEvent<HTMLFieldSetElement>) {
+      if (event.key === 'Escape' && by !== null) {
+        event.stopPropagation();
+        collapse();
+      }
+    },
+  };
+  return { root, by, handlers, collapse };
+}
+
 export function ActivityBar({
   top,
   bottom = [],
   ariaLabel = 'Views and settings',
   className,
+  expandable = true,
 }: ActivityBarProps): JSX.Element {
+  const { root, by, handlers, collapse } = useExpand(expandable);
   return (
     /*
      * A `<fieldset>`, matching `DenseGalleryShell`'s `cbgd-order` next to it — a group of
@@ -193,13 +387,24 @@ export function ActivityBar({
      * pretending to be. Not `role="toolbar"`: that promises arrow-key navigation between the
      * buttons, and seven separate tab stops is both honest and better here.
      */
-    <fieldset className={className ? `cbab ${className}` : 'cbab'} aria-label={ariaLabel}>
-      <Group items={top} />
-      {/* Pushes the application group to the floor. A flex spacer rather than
-          `justify-content: space-between`, so a rail with an EMPTY bottom group still
-          starts its top group at the top instead of centring it. */}
-      <div className='cbab-spacer' />
-      <Group items={bottom} />
+    <fieldset
+      ref={root}
+      className={className ? `cbab ${className}` : 'cbab'}
+      aria-label={ariaLabel}
+      data-expandable={expandable || undefined}
+      data-expanded={by ?? undefined}
+      {...handlers}
+    >
+      {/* The panel is what widens; the fieldset keeps its 48px track, so expanding is an
+          overlay and nothing beside the rail moves. */}
+      <div className='cbab-panel'>
+        <Group items={top} onChosen={collapse} />
+        {/* Pushes the application group to the floor. A flex spacer rather than
+            `justify-content: space-between`, so a rail with an EMPTY bottom group still
+            starts its top group at the top instead of centring it. */}
+        <div className='cbab-spacer' />
+        <Group items={bottom} onChosen={collapse} />
+      </div>
     </fieldset>
   );
 }