cursedbelt 3.0.2 → 4.1.0

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

@@ -0,0 +1,172 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { ListToolbar } from './ListToolbar';
+
+afterEach(cleanup);
+
+const CHIPS = [
+  { value: 'waiting', label: 'Waiting', count: 2 },
+  { value: 'taken', label: 'Taken' },
+];
+
+describe('ListToolbar', () => {
+  test('renders the search box, named by searchLabel', () => {
+    const { getByRole } = render(
+      <ListToolbar
+        search='draft'
+        onSearchChange={() => {}}
+        searchPlaceholder='anything in a draft'
+        searchLabel='Search the drafts'
+      />,
+    );
+    const box = getByRole('searchbox', { name: 'Search the drafts' });
+    expect((box as HTMLInputElement).value).toBe('draft');
+    expect(box.getAttribute('placeholder')).toBe('anything in a draft');
+  });
+
+  test('the accessible name falls back to the placeholder, then to "Search"', () => {
+    const { getByRole } = render(
+      <ListToolbar search='' onSearchChange={() => {}} searchPlaceholder='file name or repo' />,
+    );
+    expect(getByRole('searchbox', { name: 'file name or repo' })).toBeDefined();
+    cleanup();
+
+    const bare = render(<ListToolbar search='' onSearchChange={() => {}} />);
+    expect(bare.getByRole('searchbox', { name: 'Search' })).toBeDefined();
+  });
+
+  test('typing fires onSearchChange with the new text', () => {
+    let seen = '';
+    const { getByRole } = render(
+      <ListToolbar
+        search=''
+        onSearchChange={(v) => {
+          seen = v;
+        }}
+      />,
+    );
+    fireEvent.change(getByRole('searchbox'), { target: { value: 'queue' } });
+    expect(seen).toBe('queue');
+  });
+
+  test('no search box without BOTH value and handler — a box nobody listens to is worse than none', () => {
+    const { queryByRole } = render(<ListToolbar search='orphan' />);
+    expect(queryByRole('searchbox')).toBeNull();
+    cleanup();
+
+    const noValue = render(<ListToolbar onSearchChange={() => {}} />);
+    expect(noValue.queryByRole('searchbox')).toBeNull();
+  });
+
+  test('renders one chip per option plus the "All" pill, and reports a click', () => {
+    let picked: string | string[] | null = null;
+    const read = (): string | string[] | null => picked;
+    const { getByRole, getAllByRole } = render(
+      <ListToolbar
+        chips={CHIPS}
+        chipValue={null}
+        onChipChange={(v) => {
+          picked = v;
+        }}
+      />,
+    );
+    expect(getAllByRole('button')).toHaveLength(3); // All + 2
+    expect(getByRole('button', { name: 'All' }).getAttribute('aria-pressed')).toBe('true');
+    fireEvent.click(getByRole('button', { name: /Waiting/ }));
+    expect(read()).toBe('waiting');
+  });
+
+  test('chipValue defaults to the "All" state', () => {
+    const { getByRole } = render(<ListToolbar chips={CHIPS} onChipChange={() => {}} />);
+    expect(getByRole('button', { name: 'All' }).getAttribute('aria-pressed')).toBe('true');
+  });
+
+  test('multiChips accumulates instead of replacing', () => {
+    let picked: string | string[] | null = null;
+    const read = (): string | string[] | null => picked;
+    const { getByRole } = render(
+      <ListToolbar
+        chips={CHIPS}
+        chipValue={['waiting']}
+        multiChips
+        onChipChange={(v) => {
+          picked = v;
+        }}
+      />,
+    );
+    fireEvent.click(getByRole('button', { name: /Taken/ }));
+    expect(read()).toEqual(['waiting', 'taken']);
+  });
+
+  test('chipsAllLabel renames the clear-all pill', () => {
+    const { getByRole } = render(
+      <ListToolbar chips={CHIPS} onChipChange={() => {}} chipsAllLabel='Everything' />,
+    );
+    expect(getByRole('button', { name: 'Everything' })).toBeDefined();
+  });
+
+  test('an EMPTY chip list renders nothing — not a lone "All" pill filtering nothing', () => {
+    const { queryByRole } = render(<ListToolbar chips={[]} onChipChange={() => {}} />);
+    expect(queryByRole('button', { name: 'All' })).toBeNull();
+    expect(queryByRole('group', { name: 'Filter options' })).toBeNull();
+  });
+
+  test('sort, view and actions land in one right-hand cluster, in that order', () => {
+    const { container, getByTestId } = render(
+      <ListToolbar
+        search=''
+        onSearchChange={() => {}}
+        sort={<span data-testid='sort'>sort</span>}
+        view={<span data-testid='view'>view</span>}
+        actions={<span data-testid='actions'>actions</span>}
+      />,
+    );
+    const cluster = getByTestId('sort').parentElement;
+    expect(cluster).not.toBeNull();
+    // One cluster, not three loose children: all three share the same parent…
+    expect(getByTestId('view').parentElement).toBe(cluster as HTMLElement);
+    expect(getByTestId('actions').parentElement).toBe(cluster as HTMLElement);
+    expect([...(cluster as HTMLElement).children].map((c) => c.textContent)).toEqual([
+      'sort',
+      'view',
+      'actions',
+    ]);
+    // …and that cluster is pushed right, per DESIGN.md §2.
+    expect((cluster as HTMLElement).className).toContain('ml-auto');
+    expect((cluster as HTMLElement).parentElement).toBe(container.firstChild as HTMLElement);
+  });
+
+  test('no right-hand cluster when there is nothing to put in it', () => {
+    const { container } = render(<ListToolbar search='' onSearchChange={() => {}} />);
+    expect((container.firstChild as HTMLElement).querySelector('.ml-auto')).toBeNull();
+  });
+
+  test('extra filters sit on the left, outside the right-hand cluster', () => {
+    const { getByTestId, container } = render(
+      <ListToolbar
+        filters={<span data-testid='extra'>extra</span>}
+        view={<span data-testid='view'>view</span>}
+      />,
+    );
+    expect(getByTestId('extra').parentElement).toBe(container.firstChild as HTMLElement);
+    expect(getByTestId('view').parentElement).not.toBe(container.firstChild as HTMLElement);
+  });
+
+  test('ONE wrapping line (DESIGN.md §2 + §5), never a second row', () => {
+    const { container } = render(
+      <ListToolbar search='' onSearchChange={() => {}} chips={CHIPS} onChipChange={() => {}} />,
+    );
+    const row = container.firstChild as HTMLElement;
+    // A single flex container: `flex-wrap` is what keeps 44px targets at 390px without
+    // a second layout, so it is asserted rather than left to a reviewer's eye.
+    expect(row.className).toContain('flex');
+    expect(row.className).toContain('flex-wrap');
+    expect(container.childElementCount).toBe(1);
+  });
+
+  test('className is merged onto the row, not dropped', () => {
+    const { container } = render(<ListToolbar className='mb-4' view={<span>v</span>} />);
+    expect((container.firstChild as HTMLElement).className).toContain('mb-4');
+    expect((container.firstChild as HTMLElement).className).toContain('flex-wrap');
+  });
+});

package/src/react/components/ListToolbar.tsx

@@ -0,0 +1,151 @@
+import type { ReactNode } from 'react';
+import { cn } from '../lib/cn';
+import { ChipFilterStrip, type ChipOption } from './ChipFilterStrip';
+import { Input } from './Input';
+
+export interface ListToolbarProps {
+  /**
+   * The search text. The box renders only when BOTH this and `onSearchChange`
+   * are given — a search input nobody is listening to is worse than none.
+   */
+  search?: string;
+  onSearchChange?: (value: string) => void;
+  /** What the reader can type, in the reader's terms — `'file name, repo or title'`. */
+  searchPlaceholder?: string;
+  /**
+   * The box's accessible name. Say WHAT is being searched (*"Search the queue"*),
+   * because a page with two lists gives a screen reader two boxes called "Search".
+   * Falls back to the placeholder, then to `'Search'`.
+   */
+  searchLabel?: string;
+  /**
+   * The filter chips — one dimension of the list, as data. An EMPTY array renders
+   * nothing at all: {@link ChipFilterStrip} always draws its "All" pill, and a lone
+   * "All" chip filtering nothing is noise on the line (`ConsoleView` filters its
+   * bucket chips down to the buckets that have rows, and can reach zero).
+   */
+  chips?: readonly ChipOption[];
+  /** Selected chip(s). `null` / `[]` is the "All" state. Default `null`. */
+  chipValue?: string | string[] | null;
+  onChipChange?: (value: string | string[] | null) => void;
+  /** Let more than one chip be active at once. Default `false`. */
+  multiChips?: boolean;
+  /** Label for the chips' clear-all pill. Default `'All'`. */
+  chipsAllLabel?: string;
+  /** Any further FILTER controls — they sit left, after the chips. */
+  filters?: ReactNode;
+  /** The sort control (a `NativeSelect`, a `ChoiceMenu`, …). Right-hand cluster. */
+  sort?: ReactNode;
+  /** The density/view-mode control — normally a `TableViewToggle`. Right-hand cluster. */
+  view?: ReactNode;
+  /** The far right: the one thing this page DOES. */
+  actions?: ReactNode;
+  className?: string;
+}
+
+/**
+ * The toolbar above a list: ONE line, filters left, view controls and actions right.
+ *
+ * DESIGN.md §2, quoted because this component is nothing but that paragraph:
+ * *"Never scatter operational controls or filter tabs across multi-row lines. Merge
+ * navigation filters, search boxes, query parameters, execution buttons, and
+ * destructive triggers into a single cohesive layout line. Position filters to the
+ * left/center and main execution actions to the far right."*
+ *
+ * ── Why this is in the design system, not in the app ───────────────────────
+ * `apps/station` composed exactly this shape inline on BOTH of its lists — the queue
+ * (`ConsoleView`) and the intake (`IdeasView`) — about thirty identical lines each,
+ * differing only in their options. The retired `cursed-satellites` station had already
+ * met that fork and said so in `BoardChrome.tsx`'s header: two boards with the same
+ * INTERACTION built twice give you *"two toolbars that drift apart on the first change
+ * to either"*. Task `183` was right to forbid a station-local component and `184` is
+ * the consequence: the shape belongs to every app's list, so it lives here.
+ *
+ * ── Layout only. It has no memory ─────────────────────────────────────────
+ * 🔴 Search text, the chosen chips, the sort key and the view mode are all the
+ * caller's state, and one of them is already solved elsewhere: `useTableViewMode`
+ * persists rows ⇄ cards per account, server-side. A toolbar that grew its own
+ * storage would either fight that hook or quietly become a second, local, worse copy
+ * of it. `sort`/`view`/`actions` are SLOTS for the same reason — this one must work
+ * for `MasterDetail` pages and card grids, which is why it is not {@link TableToolbar}
+ * (that one reads everything off a TanStack `table` and cannot exist without one).
+ *
+ * ── `flex-wrap`, and no `role='toolbar'` ──────────────────────────────────
+ * Wrapping, not a grid and not a breakpoint swap: the console runs at 1440 on a desk
+ * and 390 on a phone, and wrapping is the one behaviour that keeps DESIGN.md §5's 44px
+ * targets at both widths without a second layout. `ml-auto` on the right-hand cluster
+ * keeps the controls right when everything fits on one line and lets them ride down as
+ * a group when it does not.
+ *
+ * No `role='toolbar'`: that role promises arrow-key roving focus between its controls,
+ * which would take the arrow keys away from the text box and the native `<select>`
+ * that live on this line. Tab order is the correct affordance here.
+ *
+ * @example
+ * <ListToolbar
+ *   search={search}
+ *   onSearchChange={setSearch}
+ *   searchPlaceholder='file name, repo or title'
+ *   searchLabel='Search the queue'
+ *   chips={buckets}
+ *   chipValue={filter}
+ *   onChipChange={(v) => setFilter(typeof v === 'string' ? v : null)}
+ *   sort={<NativeSelect size='sm' aria-label='Sort the queue' … />}
+ *   view={<TableViewToggle value={view.mode} onChange={view.setMode} />}
+ * />
+ */
+export function ListToolbar({
+  search,
+  onSearchChange,
+  searchPlaceholder,
+  searchLabel,
+  chips,
+  chipValue = null,
+  onChipChange,
+  multiChips = false,
+  chipsAllLabel,
+  filters,
+  sort,
+  view,
+  actions,
+  className,
+}: ListToolbarProps) {
+  const showSearch = search !== undefined && onSearchChange !== undefined;
+  const showChips = chips !== undefined && chips.length > 0 && onChipChange !== undefined;
+  const showRight = Boolean(sort) || Boolean(view) || Boolean(actions);
+
+  return (
+    <div className={cn('flex flex-wrap items-center gap-x-3 gap-y-2', className)}>
+      {showSearch ? (
+        <Input
+          type='search'
+          value={search}
+          onChange={(e) => onSearchChange(e.currentTarget.value)}
+          placeholder={searchPlaceholder}
+          aria-label={searchLabel ?? searchPlaceholder ?? 'Search'}
+          // Full width on a phone (the chips then wrap beneath it, still tappable);
+          // a fixed, modest column from `sm:` so the chips share the line rather than
+          // being pushed off it by a box that grows with the container.
+          className='w-full min-w-40 sm:w-56'
+        />
+      ) : null}
+      {showChips ? (
+        <ChipFilterStrip
+          options={[...chips]}
+          value={chipValue}
+          onChange={onChipChange}
+          multi={multiChips}
+          {...(chipsAllLabel === undefined ? {} : { allLabel: chipsAllLabel })}
+        />
+      ) : null}
+      {filters}
+      {showRight ? (
+        <span className='ml-auto flex flex-wrap items-center gap-2'>
+          {sort}
+          {view}
+          {actions}
+        </span>
+      ) : null}
+    </div>
+  );
+}