cursedbelt 5.78.0 → 5.79.0

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

@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { useState } from 'react';
+import { SelectField } from './SelectField.js';
+
+afterEach(cleanup);
+
+/** Radix's trigger carries `dir` (from its DirectionProvider); the light one draws none. */
+const isRadix = (trigger: HTMLElement) => trigger.hasAttribute('dir');
+
+const OPTIONS = [
+  { value: 'title', label: 'Title' },
+  { value: 'artist', label: 'Artist' },
+];
+
+/** A copy of `SelectField.tsx` with its OWN module state — nothing has loaded its Radix chunk yet,
+ *  so its first commit is the light trigger even though the test preload warmed the shared one. */
+async function coldSelectField(): Promise<typeof SelectField> {
+  const mod = (await import(`./SelectField.tsx?cold=${Math.random()}`)) as {
+    SelectField: typeof SelectField;
+  };
+  return mod.SelectField;
+}
+
+function Picker({ Field, onPick }: { Field: typeof SelectField; onPick?: (v: string) => void }) {
+  const [value, setValue] = useState('artist');
+  return (
+    <Field
+      aria-label='Sort by'
+      value={value}
+      onValueChange={(v) => {
+        setValue(v);
+        onPick?.(v);
+      }}
+      options={OPTIONS}
+    />
+  );
+}
+
+/**
+ * A BYTE contract as much as a behavioural one: a SelectField on an app's entry chunk hoisted
+ * Radix Select there (+29.20 kB gzip in music, forge task 3096), so the Radix select is its own
+ * chunk and this file is a trigger.
+ */
+describe('SelectField (lazy)', () => {
+  test('the wrapper imports no Radix, and loads the implementation dynamically', () => {
+    const src = readFileSync(join(import.meta.dir, 'SelectField.tsx'), 'utf8');
+    expect(src).not.toMatch(/from\s*['"]@radix-ui\//);
+    expect(src).not.toMatch(/from\s*['"]\.\/SelectFieldImpl(\.js)?['"]/);
+    expect(src).toContain("import('./SelectFieldImpl.js')");
+  });
+
+  test('the light trigger is the same box as the real one: role, label, classes, placeholder', async () => {
+    const Cold = await coldSelectField();
+    const light = render(<Cold aria-label='Sort by' value='artist' options={OPTIONS} className='w-40' />);
+    const lightTrigger = light.getByRole('combobox', { name: 'Sort by' });
+    expect(isRadix(lightTrigger)).toBe(false);
+    const lightBox = { text: lightTrigger.textContent, cls: lightTrigger.className };
+    light.unmount();
+
+    const real = render(<SelectField aria-label='Sort by' value='artist' options={OPTIONS} className='w-40' />);
+    const realTrigger = real.getByRole('combobox', { name: 'Sort by' });
+    expect(isRadix(realTrigger)).toBe(true);
+    expect(lightBox).toEqual({ text: realTrigger.textContent, cls: realTrigger.className });
+    expect(lightBox.text).toBe('Artist');
+    real.unmount();
+
+    const empty = render(<Cold aria-label='Sort by' placeholder='Pick one' options={OPTIONS} />);
+    const emptyTrigger = empty.getByRole('combobox', { name: 'Sort by' });
+    expect(emptyTrigger.textContent).toBe('Pick one');
+    expect(emptyTrigger.hasAttribute('data-placeholder')).toBe(true);
+  });
+
+  test('Enter on the light trigger is not lost: the real select mounts open and the pick lands', async () => {
+    const Cold = await coldSelectField();
+    const picks: string[] = [];
+    render(<Picker Field={Cold} onPick={(v) => picks.push(v)} />);
+    const trigger = screen.getByRole('combobox', { name: 'Sort by' });
+    expect(isRadix(trigger)).toBe(false);
+    fireEvent.keyDown(trigger, { key: 'Enter' });
+    fireEvent.click(await screen.findByRole('option', { name: 'Title' }));
+    expect(picks).toEqual(['title']);
+    await waitFor(() => expect(screen.getByRole('combobox', { name: 'Sort by' }).textContent).toBe('Title'));
+  });
+
+  test('a mouse press on the light trigger opens the list', async () => {
+    const Cold = await coldSelectField();
+    render(<Picker Field={Cold} />);
+    fireEvent.pointerDown(screen.getByRole('combobox', { name: 'Sort by' }), {
+      pointerType: 'mouse',
+      button: 0,
+    });
+    expect(await screen.findByRole('listbox')).toBeTruthy();
+  });
+
+  test('focus held on the light trigger moves to the real one when it lands', async () => {
+    const Cold = await coldSelectField();
+    render(<Picker Field={Cold} />);
+    const light = screen.getByRole('combobox', { name: 'Sort by' });
+    expect(isRadix(light)).toBe(false);
+    light.focus();
+    await waitFor(() =>
+      expect(isRadix(screen.getByRole('combobox', { name: 'Sort by' }))).toBe(true),
+    );
+    expect(document.activeElement).toBe(screen.getByRole('combobox', { name: 'Sort by' }));
+  });
+
+  test('once warm, the first commit is the real select — the keyboard path tests rely on', () => {
+    render(<Picker Field={SelectField} />);
+    const trigger = screen.getByRole('combobox', { name: 'Sort by' });
+    expect(isRadix(trigger)).toBe(true);
+    fireEvent.keyDown(trigger, { key: 'Enter' });
+    expect(screen.getByRole('option', { name: 'Title' })).toBeTruthy();
+  });
+});

package/src/react/components/SelectField.tsx

@@ -1,64 +1,40 @@
-import * as RSelect from '@radix-ui/react-select';
-import { Check, ChevronDown, ChevronUp } from 'lucide-react';
-import type { ReactNode } from 'react';
-import { cn } from '../lib/cn.js';
-import { useFloatingContainer } from '../lib/floatingContainer.js';
-import { type ControlSize, choiceFieldWidth, declareFieldWidth, fieldControlClass } from '../lib/field.js';
+import { ChevronDown } from 'lucide-react';
+import { type ComponentType, useEffect, useRef, useState } from 'react';
+import { cn, RAW_BUTTON } from '../lib/cn.js';
+import { choiceFieldWidth, declareFieldWidth } from '../lib/field.js';
 import {
-  FLOATING_ANIMATION,
-  FLOATING_COLLISION_PADDING,
-  FLOATING_CONTENT_BASE,
-  FLOATING_ITEM_BASE,
-} from '../lib/floatingStyles.js';
+  SELECT_OPEN_KEYS,
+  SELECT_VALUE_CLASS,
+  type SelectFieldImplProps,
+  type SelectFieldProps,
+  selectGroupsOf,
+  selectShowsPlaceholder,
+  selectTriggerClass,
+} from '../lib/selectField.js';
 
-export interface SelectOption {
-  value: string;
-  label: ReactNode;
-  description?: ReactNode;
-  disabled?: boolean;
-}
+export type { SelectFieldProps, SelectGroup, SelectOption } from '../lib/selectField.js';
 
-export interface SelectGroup {
-  label?: string;
-  options: SelectOption[];
-}
+type SelectFieldImplComponent = ComponentType<SelectFieldImplProps>;
+
+let loadedImpl: SelectFieldImplComponent | null = null;
+let pendingImpl: Promise<SelectFieldImplComponent> | null = null;
 
-export interface SelectFieldProps {
-  value?: string;
-  onValueChange?: (value: string) => void;
-  options?: SelectOption[];
-  groups?: SelectGroup[];
-  placeholder?: string;
-  disabled?: boolean;
-  /** Use the full field style (16px, rounded-md, border, focus ring). Default true. */
-  fieldStyle?: boolean;
-  /** Trigger height on the shared control-height scale (`--control-h-*`, task
-   *  cbux-41). Default `md`. No-op when `fieldStyle={false}`. */
-  size?: ControlSize;
-  /** Forwarded to the trigger so a visible `<label htmlFor>` can target it. */
-  id?: string;
-  name?: string;
-  required?: boolean;
-  className?: string;
-  'aria-label'?: string;
-  'aria-labelledby'?: string;
-  /**
-   * What to say when there is nothing to choose — *"No lists yet"*.
-   *
-   * 🔴 Required in practice for any control whose options come from DATA rather than
-   * from a constant: an empty popup is a dead end that reads as a broken control, and
-   * the `choice-needs-empty-state` guardrail reports one. Rendered as plain text, not
-   * as an item, so it can never be picked or keyboard-focused.
-   */
-  emptyLabel?: ReactNode;
-  /** The second line — what belongs in this list, or how to get one. */
-  emptyHint?: ReactNode;
-  /** Set by {@link Field} for inline validation — paints the field-token invalid
-   *  border (via `aria-invalid`) and links the description/error to the trigger. */
-  'aria-invalid'?: boolean | 'true' | 'false';
-  'aria-describedby'?: string;
+/** Fetch the Radix implementation once per page. Exported for tests and for a consumer that wants
+ *  to warm it explicitly. */
+export function preloadSelectField(): Promise<SelectFieldImplComponent> {
+  if (!pendingImpl) {
+    pendingImpl = import('./SelectFieldImpl.js').then((m) => {
+      loadedImpl = m.default;
+      return m.default;
+    });
+  }
+  return pendingImpl;
 }
 
+// Start the fetch when this module is evaluated, so the implementation is normally there before
+// the first field mounts and no trigger is ever swapped (Tooltip.tsx has the history).
+if (typeof window !== 'undefined') void preloadSelectField();
+
 /**
  * Portal-based select control on Radix Select. Replaces the native `<select>`
  * wrapper. Fully styleable, keyboard-navigable, a11y-correct, and never clipped by
@@ -71,122 +47,111 @@ export interface SelectFieldProps {
  * is true (the default for form fields), giving it the same control-height token +
  * rounded-md as Input at the same `size`. Pass `fieldStyle={false}` + a `className`
  * for a bespoke trigger.
+ *
+ * ── Why this file is a trigger and not the select ───────────────────────────
+ * 🔴 Radix Select (with its popper, focus scope and remove-scroll) is ~29 kB gzip, and a
+ * static import puts it in whatever chunk renders a field. In a lazy page that is a few kB;
+ * in an app's ENTRY it hoisted the Radix code a dozen lazy chunks had shared: music's library
+ * Sort by took `index-*.js` from 203 to 232 kB gzip and was reverted (forge task 3096). So the
+ * Radix select is `SelectFieldImpl`, a dynamic `import()`, and this file draws the same trigger
+ * box — same classes, `role="combobox"`, the chosen option's label, the chevron — until it
+ * lands. A press, Enter, Space or an arrow that beats the fetch is not lost: the real select
+ * mounts open; focus held on the light trigger moves to the real one.
  */
-export function SelectField({
-  value,
-  onValueChange,
-  options = [],
-  groups = [],
-  placeholder = 'Select…',
-  disabled,
-  fieldStyle = true,
-  size = 'md',
-  id,
-  name,
-  required,
-  className,
-  emptyLabel,
-  emptyHint,
-  'aria-label': ariaLabel,
-  'aria-labelledby': ariaLabelledBy,
-  'aria-invalid': ariaInvalid,
-  'aria-describedby': ariaDescribedBy,
-}: SelectFieldProps) {
-  const allGroups: SelectGroup[] =
-    groups.length > 0 ? groups : options.length > 0 ? [{ options }] : [];
-  const empty = allGroups.every((group) => group.options.length === 0);
-  const container = useFloatingContainer();
+export function SelectField(props: SelectFieldProps) {
+  // `() => loadedImpl`: a component IS a function, and `useState(fn)` would call it.
+  const [Impl, setImpl] = useState<SelectFieldImplComponent | null>(() => loadedImpl);
+  const openRef = useRef(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const pointerTypeRef = useRef('mouse');
+
+  useEffect(() => {
+    if (Impl) return;
+    let alive = true;
+    void preloadSelectField().then((c) => {
+      if (alive) setImpl(() => c);
+    });
+    return () => {
+      alive = false;
+    };
+  }, [Impl]);
+
+  if (Impl) {
+    const focused = triggerRef.current !== null && triggerRef.current === document.activeElement;
+    return <Impl {...props} initialOpen={openRef.current} initialFocus={focused} />;
+  }
+
+  const {
+    value,
+    placeholder = 'Select…',
+    disabled,
+    fieldStyle,
+    size,
+    className,
+    id,
+    required,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-invalid': ariaInvalid,
+    'aria-describedby': ariaDescribedBy,
+  } = props;
+  const showPlaceholder = selectShowsPlaceholder(value);
+  const chosen = showPlaceholder
+    ? undefined
+    : selectGroupsOf(props)
+        .flatMap((group) => group.options)
+        .find((opt) => opt.value === value);
+
+  const open = () => {
+    openRef.current = true;
+    // Already fetched by another field: swap now rather than on the effect's next tick.
+    if (loadedImpl) setImpl(() => loadedImpl);
+  };
 
   return (
-    <RSelect.Root
-      value={value}
-      onValueChange={onValueChange}
+    <button
+      // guardrails-ignore no-raw-action-button: task 3096 — SelectField's light trigger until
+      // its Radix select loads, the same box SelectFieldImpl's trigger draws.
+      ref={triggerRef}
+      type='button'
+      role='combobox'
+      id={id}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-invalid={ariaInvalid}
+      aria-describedby={ariaDescribedBy}
+      aria-expanded={false}
+      aria-required={required}
+      aria-autocomplete='none'
+      data-state='closed'
       disabled={disabled}
-      name={name}
-      required={required}
+      data-disabled={disabled ? '' : undefined}
+      data-placeholder={showPlaceholder ? '' : undefined}
+      className={cn(RAW_BUTTON, selectTriggerClass({ fieldStyle, size, className }))}
+      // Radix's own split: a mouse opens on press, touch and pen on the click (so a scroll that
+      // starts on the field is not a pick).
+      onPointerDown={(e) => {
+        pointerTypeRef.current = e.pointerType;
+        if (e.pointerType === 'mouse' && e.button === 0 && !e.ctrlKey) {
+          e.preventDefault();
+          open();
+        }
+      }}
+      onClick={() => {
+        if (pointerTypeRef.current !== 'mouse') open();
+      }}
+      onKeyDown={(e) => {
+        if (SELECT_OPEN_KEYS.includes(e.key)) {
+          e.preventDefault();
+          open();
+        }
+      }}
     >
-      <RSelect.Trigger
-        id={id}
-        aria-label={ariaLabel}
-        aria-labelledby={ariaLabelledBy}
-        aria-invalid={ariaInvalid}
-        aria-describedby={ariaDescribedBy}
-        className={cn(
-          fieldStyle && fieldControlClass(size),
-          'flex items-center justify-between gap-2 data-[placeholder]:text-muted-foreground',
-          className,
-        )}
-      >
-        {/* One line, ellipsized, left-aligned: a long value (a deep path) used to wrap to three
-            centred lines and spill out of a 36px trigger at 390px (Radix Themes' Select
-            truncates the same way, forge task 2594). Radix's Value drops `className`, so the
-            truncation lives on a wrapper. */}
-        <span className='block min-w-0 flex-1 truncate text-left'>
-          <RSelect.Value placeholder={placeholder} />
-        </span>
-        <RSelect.Icon asChild>
-          <ChevronDown className='size-4 shrink-0 opacity-50' />
-        </RSelect.Icon>
-      </RSelect.Trigger>
-      <RSelect.Portal container={container}>
-        <RSelect.Content
-          position='popper'
-          sideOffset={4}
-          collisionPadding={FLOATING_COLLISION_PADDING}
-          className={cn(
-            FLOATING_COLLISION_PADDING,
-  FLOATING_CONTENT_BASE,
-            FLOATING_ANIMATION,
-            'max-h-[var(--radix-select-content-available-height)] min-w-[var(--radix-select-trigger-width)] p-1',
-          )}
-        >
-          <RSelect.ScrollUpButton className='flex cursor-default items-center justify-center py-1'>
-            <ChevronUp className='size-4' />
-          </RSelect.ScrollUpButton>
-          <RSelect.Viewport>
-            {empty && (
-              // Not a `RSelect.Item`: an empty state is a statement, not a choice, and
-              // Radix would make it focusable and type-ahead-matchable.
-              <div className='flex flex-col gap-0.5 px-2 py-2.5 text-left'>
-                <span className='text-sm font-medium'>
-                  {emptyLabel ?? 'Nothing to choose from yet'}
-                </span>
-                {emptyHint && <span className='text-xs text-muted-foreground'>{emptyHint}</span>}
-              </div>
-            )}
-            {allGroups.map((group, gi) => (
-              <RSelect.Group key={group.label ?? gi}>
-                {group.label && (
-                  <RSelect.Label className='px-2 py-1.5 text-xs font-semibold text-muted-foreground'>
-                    {group.label}
-                  </RSelect.Label>
-                )}
-                {group.options.map((opt) => (
-                  <RSelect.Item
-                    key={opt.value}
-                    value={opt.value}
-                    disabled={opt.disabled}
-                    className={cn(FLOATING_ITEM_BASE, 'pr-8')}
-                  >
-                    <RSelect.ItemIndicator className='absolute right-2 flex size-4 items-center justify-center'>
-                      <Check className='size-3' />
-                    </RSelect.ItemIndicator>
-                    <RSelect.ItemText>{opt.label}</RSelect.ItemText>
-                    {opt.description && (
-                      <span className='text-xs text-muted-foreground'>{opt.description}</span>
-                    )}
-                  </RSelect.Item>
-                ))}
-                {gi < allGroups.length - 1 && <RSelect.Separator className='my-1 h-px bg-border' />}
-              </RSelect.Group>
-            ))}
-          </RSelect.Viewport>
-          <RSelect.ScrollDownButton className='flex cursor-default items-center justify-center py-1'>
-            <ChevronDown className='size-4' />
-          </RSelect.ScrollDownButton>
-        </RSelect.Content>
-      </RSelect.Portal>
-    </RSelect.Root>
+      <span className={SELECT_VALUE_CLASS}>
+        {showPlaceholder ? placeholder : chosen?.label}
+      </span>
+      <ChevronDown aria-hidden className='size-4 shrink-0 opacity-50' />
+    </button>
   );
 }
 

package/src/react/components/SelectFieldImpl.tsx

@@ -0,0 +1,140 @@
+import * as RSelect from '@radix-ui/react-select';
+import { Check, ChevronDown, ChevronUp } from 'lucide-react';
+import { useEffect, useRef } from 'react';
+import { cn, RAW_BUTTON } from '../lib/cn.js';
+import { useFloatingContainer } from '../lib/floatingContainer.js';
+import {
+  FLOATING_ANIMATION,
+  FLOATING_COLLISION_PADDING,
+  FLOATING_CONTENT_BASE,
+  FLOATING_ITEM_BASE,
+} from '../lib/floatingStyles.js';
+import {
+  SELECT_VALUE_CLASS,
+  type SelectFieldImplProps,
+  selectGroupsOf,
+  selectTriggerClass,
+} from '../lib/selectField.js';
+
+/**
+ * The Radix Select behind {@link SelectField} — loaded as its own chunk by `SelectField.tsx`, which
+ * says why. Not exported from the package: render `SelectField`.
+ */
+export default function SelectFieldImpl({
+  value,
+  onValueChange,
+  options = [],
+  groups = [],
+  placeholder = 'Select…',
+  disabled,
+  fieldStyle = true,
+  size = 'md',
+  id,
+  name,
+  required,
+  className,
+  emptyLabel,
+  emptyHint,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-invalid': ariaInvalid,
+  'aria-describedby': ariaDescribedBy,
+  initialOpen = false,
+  initialFocus = false,
+}: SelectFieldImplProps) {
+  const allGroups = selectGroupsOf({ options, groups });
+  const empty = allGroups.every((group) => group.options.length === 0);
+  const container = useFloatingContainer();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  // The light trigger this replaced had the keyboard focus: keep it here, or it drops to <body>.
+  // An `initialOpen` select moves focus into its list itself, and hands it back on close.
+  useEffect(() => {
+    if (initialFocus && !initialOpen) triggerRef.current?.focus();
+  }, [initialFocus, initialOpen]);
+
+  return (
+    <RSelect.Root
+      value={value}
+      onValueChange={onValueChange}
+      disabled={disabled}
+      name={name}
+      required={required}
+      defaultOpen={initialOpen}
+    >
+      <RSelect.Trigger
+        ref={triggerRef}
+        id={id}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-invalid={ariaInvalid}
+        aria-describedby={ariaDescribedBy}
+        className={cn(RAW_BUTTON, selectTriggerClass({ fieldStyle, size, className }))}
+      >
+        <span className={SELECT_VALUE_CLASS}>
+          <RSelect.Value placeholder={placeholder} />
+        </span>
+        <RSelect.Icon asChild>
+          <ChevronDown className='size-4 shrink-0 opacity-50' />
+        </RSelect.Icon>
+      </RSelect.Trigger>
+      <RSelect.Portal container={container}>
+        <RSelect.Content
+          position='popper'
+          sideOffset={4}
+          collisionPadding={FLOATING_COLLISION_PADDING}
+          className={cn(
+            FLOATING_CONTENT_BASE,
+            FLOATING_ANIMATION,
+            'max-h-[var(--radix-select-content-available-height)] min-w-[var(--radix-select-trigger-width)] p-1',
+          )}
+        >
+          <RSelect.ScrollUpButton className='flex cursor-default items-center justify-center py-1'>
+            <ChevronUp className='size-4' />
+          </RSelect.ScrollUpButton>
+          <RSelect.Viewport>
+            {empty && (
+              // Not a `RSelect.Item`: an empty state is a statement, not a choice, and
+              // Radix would make it focusable and type-ahead-matchable.
+              <div className='flex flex-col gap-0.5 px-2 py-2.5 text-left'>
+                <span className='text-sm font-medium'>
+                  {emptyLabel ?? 'Nothing to choose from yet'}
+                </span>
+                {emptyHint && <span className='text-xs text-muted-foreground'>{emptyHint}</span>}
+              </div>
+            )}
+            {allGroups.map((group, gi) => (
+              <RSelect.Group key={group.label ?? gi}>
+                {group.label && (
+                  <RSelect.Label className='px-2 py-1.5 text-xs font-semibold text-muted-foreground'>
+                    {group.label}
+                  </RSelect.Label>
+                )}
+                {group.options.map((opt) => (
+                  <RSelect.Item
+                    key={opt.value}
+                    value={opt.value}
+                    disabled={opt.disabled}
+                    className={cn(FLOATING_ITEM_BASE, 'pr-8')}
+                  >
+                    <RSelect.ItemIndicator className='absolute right-2 flex size-4 items-center justify-center'>
+                      <Check className='size-3' />
+                    </RSelect.ItemIndicator>
+                    <RSelect.ItemText>{opt.label}</RSelect.ItemText>
+                    {opt.description && (
+                      <span className='text-xs text-muted-foreground'>{opt.description}</span>
+                    )}
+                  </RSelect.Item>
+                ))}
+                {gi < allGroups.length - 1 && <RSelect.Separator className='my-1 h-px bg-border' />}
+              </RSelect.Group>
+            ))}
+          </RSelect.Viewport>
+          <RSelect.ScrollDownButton className='flex cursor-default items-center justify-center py-1'>
+            <ChevronDown className='size-4' />
+          </RSelect.ScrollDownButton>
+        </RSelect.Content>
+      </RSelect.Portal>
+    </RSelect.Root>
+  );
+}

package/src/react/components/filterChip.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+import { cn, RAW_BUTTON } from '../lib/cn.js';
+import { PRESS } from '../lib/press.js';
+
+/*
+ * The pill `ChipFilterStrip` draws, and `KanbanBoard`'s column tray on a phone. Its own module,
+ * off every barrel and subpath: it is a part, not a component an app reaches for.
+ */
+
+export interface ChipProps {
+  active: boolean;
+  onClick: () => void;
+  children: ReactNode;
+}
+
+export function Chip({ active, onClick, children }: ChipProps) {
+  return (
+    <button
+      // guardrails-ignore no-raw-action-button: presentational filter-chip toggle —
+      // reflects local filter state (aria-pressed), no destructive/mutating intent.
+      type='button'
+      onClick={onClick}
+      aria-pressed={active}
+      className={cn(
+        RAW_BUTTON,
+        // 44 px min tap target height via py + min-h (STANDARDS §4a). px-4 keeps every
+        // pill's internal padding identical regardless of label length.
+        'inline-flex min-h-11 shrink-0 cursor-pointer items-center rounded-full px-4 text-sm font-medium',
+        PRESS,
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        // Soft active state — an accent tint + accent text (the standardized active
+        // treatment shared with nav items and the `accent` Badge tone), not a stark
+        // solid accent block. `text-accent-strong` (not plain `text-accent`) — the
+        // /15 tint only clears 4.43:1 with the base accent hue, under AA (cbux-101).
+        active
+          ? 'bg-accent/15 text-accent-strong ring-1 ring-inset ring-accent/30'
+          : 'bg-muted text-muted-foreground hover:bg-muted/80 hover:text-foreground',
+      )}
+    >
+      {children}
+    </button>
+  );
+}