@lovett/ui 0.0.11 → 0.2.0

package/src/filter-menu.tsx

@@ -0,0 +1,649 @@
+/**
+ * FilterMenu + FilterChipBar — the UI layer over `filter-core`.
+ *
+ * `docs/design-briefs/tasks-board-action-bar.md` §5 and
+ * `tasks-board-header-primitives.md` §5. The source's filter ENGINE is worth
+ * having and its seven UI files are not; the engine is already ported
+ * (`src/filter-core/**`, pure TypeScript, 148 tests) and this is the UI on our
+ * own primitives. It inherits none of the three bugs the brief names:
+ *
+ *   - facet counts are recomputed from the rows passed in on every render
+ *     (theirs froze at mount behind an empty dep array), and they are counted
+ *     against `facetedRowsFor`, so picking one option does not zero the rest;
+ *   - there is no `useMemo` after an early return, because there is no early
+ *     return: the popover content only mounts when open;
+ *   - the operator promotion rule is never re-derived here — every write goes
+ *     through `toggleOptionValue` / `toggleMultiOptionValue` in the core.
+ *
+ * TWO STEPS. Step one is a search box over the filterable FIELDS, each row an
+ * icon, a name and a chevron saying it leads somewhere. Step two is a
+ * MULTI-SELECT: checkboxes, several values at once, each value's count as
+ * SUPERSCRIPT after its label (`Backlog⁵⁰`) rather than as a trailing chip.
+ *
+ * The field list shows ONLY `option` / `multiOption` columns: text, number and
+ * raw date columns need editors this component does not have, and offering a
+ * field that opens onto nothing is the dead-control failure the port exists to
+ * avoid. A caller may pass columns of any type — `filterRows` still honours
+ * them, they simply are not offered here. (A date dimension is best declared
+ * as an option column of derived buckets, which is what the Tasks board does
+ * with `Due`.)
+ *
+ * `FilterChipBar` is the other half of the loop: a bar that appears BELOW the
+ * action bar once anything is applied, each filter a three-part chip
+ * (field · verb · value) with its own remove control, and a single `Clear` at
+ * the trailing edge. Nothing writes a private parallel filter state — a facet
+ * click, a chip edit and a quick scope all go through `onFiltersChange`.
+ */
+
+import {
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+} from 'react'
+import { ArrowLeft, Check, ChevronRight, ListFilter, Search, X } from 'lucide-react'
+import { cn } from './lib/utils'
+import { handleTabTrap } from './lib/focus'
+import { Button } from './button'
+import { Input } from './input'
+import { Popover } from './popover'
+import {
+  facetedCounts,
+  facetedRowsFor,
+  getFilter,
+  isColumnOfType,
+  removeFilter,
+  toggleMultiOptionValue,
+  toggleOptionValue,
+  type AnyColumnConfig,
+  type ColumnOption,
+  type FilterModel,
+  type FiltersState,
+} from './filter-core'
+
+/**
+ * Resolves an option's icon. Caller-supplied, because `filter-core` stays
+ * React-free and this package will not pull in Lucide's dynamic icon map for
+ * a handful of names.
+ */
+export type FilterOptionIconRenderer = (
+  option: ColumnOption,
+  columnId: string,
+) => ReactNode
+
+/** Resolves a FIELD's icon, for the step-one list. Same reasoning. */
+export type FilterFieldIconRenderer = (columnId: string) => ReactNode
+
+interface EditableColumn<TData> {
+  readonly config: AnyColumnConfig<TData>
+  readonly options: readonly ColumnOption[]
+}
+
+/** The columns this UI can actually edit, with their option lists. */
+function editableColumns<TData>(
+  columns: ReadonlyArray<AnyColumnConfig<TData>>,
+): ReadonlyArray<EditableColumn<TData>> {
+  const out: EditableColumn<TData>[] = []
+  for (const config of columns) {
+    if (config.type !== 'option' && config.type !== 'multiOption') continue
+    out.push({ config, options: config.options ?? [] })
+  }
+  return out
+}
+
+/**
+ * The string values of an option-ish filter.
+ *
+ * Narrowed on the discriminant rather than cast: `FilterModel` is a union and
+ * a `date` filter's `values` really are `Date[]`, so `as readonly string[]`
+ * would be a lie the compiler happens to accept. A filter on a non-option
+ * column contributes no option values, which is exactly right here.
+ */
+function optionValuesOf(filter: FilterModel | undefined): readonly string[] {
+  if (!filter) return []
+  return filter.type === 'option' || filter.type === 'multiOption'
+    ? filter.values
+    : []
+}
+
+/* ------------------------------------------------------------------ */
+/* Step two — the multi-select value list                              */
+/* ------------------------------------------------------------------ */
+
+interface FilterValueListProps<TData> {
+  rows: readonly TData[]
+  columns: ReadonlyArray<AnyColumnConfig<TData>>
+  filters: FiltersState
+  column: AnyColumnConfig<TData>
+  options: readonly ColumnOption[]
+  onFiltersChange: (next: FiltersState) => void
+  renderOptionIcon?: FilterOptionIconRenderer
+}
+
+function FilterValueList<TData>({
+  rows,
+  columns,
+  filters,
+  column,
+  options,
+  onFiltersChange,
+  renderOptionIcon,
+}: FilterValueListProps<TData>) {
+  const [query, setQuery] = useState('')
+
+  // Counted against everything surviving the OTHER columns' filters, so
+  // selecting one option leaves the rest of this list countable.
+  const counts = useMemo(
+    () => facetedCounts(facetedRowsFor(rows, columns, filters, column.id), column),
+    [rows, columns, filters, column],
+  )
+
+  const active = getFilter(filters, column.id)
+  const selected = new Set(optionValuesOf(active))
+
+  const needle = query.trim().toLowerCase()
+  const shown = needle
+    ? options.filter((option) => option.label.toLowerCase().includes(needle))
+    : options
+
+  const toggle = (value: string) => {
+    if (isColumnOfType(column, 'option')) {
+      onFiltersChange(toggleOptionValue(filters, column, value))
+      return
+    }
+    if (isColumnOfType(column, 'multiOption')) {
+      onFiltersChange(toggleMultiOptionValue(filters, column, value))
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <FilterSearchField
+        value={query}
+        onChange={setQuery}
+        label={`Search ${column.displayName.toLowerCase()} values`}
+        placeholder="Search…"
+      />
+      {shown.length === 0 ? (
+        <p
+          className="px-2 py-3 text-center text-[12px]"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          No matches.
+        </p>
+      ) : (
+        <div role="group" aria-label={column.displayName} className="flex flex-col">
+          {shown.map((option) => {
+            const isOn = selected.has(option.value)
+            const count = counts.get(option.value) ?? 0
+            return (
+              <button
+                key={option.value}
+                type="button"
+                role="checkbox"
+                aria-checked={isOn}
+                // Named explicitly: the accessible name computed from the
+                // children runs the label into the superscript ("To do2"),
+                // which is what a screen reader would read out.
+                aria-label={`${option.label}, ${count} matching`}
+                onClick={() => toggle(option.value)}
+                className={cn(
+                  // Optical spacing: vertical padding under the horizontal,
+                  // because the line box already carries space the glyphs do
+                  // not fill (action-bar brief §6.5).
+                  'flex min-h-7 items-center gap-2 rounded-[var(--radius-sm)] px-2 py-1',
+                  'text-start text-[12.5px]',
+                  'transition-[background-color] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+                  'hover:bg-[rgb(var(--surface-hover))]',
+                  'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                )}
+              >
+                <span
+                  aria-hidden="true"
+                  className="flex h-4 w-4 shrink-0 items-center justify-center rounded-[var(--radius-xs)]"
+                  style={{
+                    border: `1.5px solid rgb(var(${isOn ? '--accent' : '--border-strong'}))`,
+                    background: isOn ? 'rgb(var(--accent))' : 'transparent',
+                    color: 'white',
+                  }}
+                >
+                  {isOn ? <Check className="h-3 w-3" strokeWidth={3} /> : null}
+                </span>
+                {renderOptionIcon ? (
+                  <span className="flex shrink-0 items-center">
+                    {renderOptionIcon(option, column.id)}
+                  </span>
+                ) : null}
+                <span className="min-w-0 flex-1 truncate">
+                  {option.label}
+                  {/* Superscript, not a trailing chip: the count belongs to
+                      the label. Hung on the far edge it reads as a second
+                      column of unrelated numbers. */}
+                  <sup
+                    aria-hidden="true"
+                    className="ms-0.5 text-[9.5px] font-medium tabular-nums"
+                    style={{ color: 'rgb(var(--text-tertiary))' }}
+                  >
+                    {count}
+                  </sup>
+                </span>
+              </button>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* The search field, shared by both steps                              */
+/* ------------------------------------------------------------------ */
+
+function FilterSearchField({
+  value,
+  onChange,
+  label,
+  placeholder,
+  autoFocus,
+}: {
+  value: string
+  onChange: (next: string) => void
+  label: string
+  placeholder: string
+  autoFocus?: boolean
+}) {
+  return (
+    <Input
+      inputSize="sm"
+      type="text"
+      value={value}
+      aria-label={label}
+      placeholder={placeholder}
+      leadingAffix={<Search className="h-3.5 w-3.5" />}
+      {...(autoFocus ? { 'data-autofocus': 'true' } : {})}
+      onChange={(event) => onChange(event.target.value)}
+    />
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* FilterMenu                                                          */
+/* ------------------------------------------------------------------ */
+
+export interface FilterMenuProps<TData> {
+  /**
+   * The UNFILTERED rows in scope. Facet counts are computed from these, minus
+   * the filters on the other columns — pass the filtered set and every count
+   * collapses to what is already on screen.
+   */
+  rows: readonly TData[]
+  columns: ReadonlyArray<AnyColumnConfig<TData>>
+  filters: FiltersState
+  onFiltersChange: (next: FiltersState) => void
+  /** Trigger label. Default "Filter". Always rendered beside the icon. */
+  label?: string
+  renderOptionIcon?: FilterOptionIconRenderer
+  renderFieldIcon?: FilterFieldIconRenderer
+  className?: string
+}
+
+export function FilterMenu<TData>({
+  rows,
+  columns,
+  filters,
+  onFiltersChange,
+  label = 'Filter',
+  renderOptionIcon,
+  renderFieldIcon,
+  className,
+}: FilterMenuProps<TData>) {
+  const [open, setOpen] = useState(false)
+  const [columnId, setColumnId] = useState<string | null>(null)
+  const [query, setQuery] = useState('')
+  const contentRef = useRef<HTMLDivElement | null>(null)
+
+  const editable = useMemo(() => editableColumns(columns), [columns])
+  const active = editable.find((entry) => entry.config.id === columnId) ?? null
+
+  const needle = query.trim().toLowerCase()
+  const shownFields = needle
+    ? editable.filter((entry) =>
+        entry.config.displayName.toLowerCase().includes(needle),
+      )
+    : editable
+
+  const close = (next: boolean) => {
+    setOpen(next)
+    if (!next) {
+      // Reopening always lands on the field list — a popover that reopens
+      // three levels deep into where you were last is disorienting.
+      setColumnId(null)
+      setQuery('')
+    }
+  }
+
+  return (
+    <Popover open={open} onOpenChange={close}>
+      <Popover.Trigger asChild>
+        {/* Icon AND text, never one of the two (action-bar brief §2). */}
+        <Button
+          variant="secondary"
+          size="sm"
+          className={className ?? ''}
+          leadingIcon={
+            <ListFilter className="h-3.5 w-3.5" strokeWidth={1.5} aria-hidden="true" />
+          }
+        >
+          {label}
+        </Button>
+      </Popover.Trigger>
+      <Popover.Content
+        ref={contentRef}
+        aria-label={active ? `Filter by ${active.config.displayName}` : 'Add a filter'}
+        align="end"
+        className="w-64 p-3"
+        onKeyDown={(event: ReactKeyboardEvent<HTMLDivElement>) =>
+          handleTabTrap(event, contentRef.current)
+        }
+      >
+        {active ? (
+          <div className="flex flex-col gap-1.5">
+            <div className="flex items-center gap-1.5">
+              <Button
+                variant="icon"
+                size="sm"
+                aria-label="Back to fields"
+                onClick={() => {
+                  setColumnId(null)
+                  setQuery('')
+                }}
+              >
+                <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" />
+              </Button>
+              <span className="text-[12.5px] font-semibold">
+                {active.config.displayName}
+              </span>
+            </div>
+            <FilterValueList
+              rows={rows}
+              columns={columns}
+              filters={filters}
+              column={active.config}
+              options={active.options}
+              onFiltersChange={onFiltersChange}
+              {...(renderOptionIcon ? { renderOptionIcon } : {})}
+            />
+          </div>
+        ) : (
+          <div className="flex flex-col gap-1.5">
+            <FilterSearchField
+              value={query}
+              onChange={setQuery}
+              label="Search filter fields"
+              placeholder="Filter by…"
+              autoFocus
+            />
+            {shownFields.length === 0 ? (
+              <p
+                className="px-2 py-3 text-center text-[12px]"
+                style={{ color: 'rgb(var(--text-tertiary))' }}
+              >
+                No fields match.
+              </p>
+            ) : (
+              <div role="group" aria-label="Filter fields" className="flex flex-col">
+                {shownFields.map((entry) => {
+                  const count = getFilter(filters, entry.config.id)?.values.length ?? 0
+                  return (
+                    <button
+                      key={entry.config.id}
+                      type="button"
+                      aria-label={
+                        count > 0
+                          ? `${entry.config.displayName}, ${count} selected`
+                          : entry.config.displayName
+                      }
+                      onClick={() => {
+                        setColumnId(entry.config.id)
+                        setQuery('')
+                      }}
+                      className={cn(
+                        'flex min-h-7 items-center gap-2 rounded-[var(--radius-sm)] px-2 py-1',
+                        'text-start text-[12.5px]',
+                        'transition-[background-color] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+                        'hover:bg-[rgb(var(--surface-hover))]',
+                        'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                      )}
+                    >
+                      {renderFieldIcon ? (
+                        <span
+                          className="flex shrink-0 items-center"
+                          style={{ color: 'rgb(var(--text-tertiary))' }}
+                        >
+                          {renderFieldIcon(entry.config.id)}
+                        </span>
+                      ) : null}
+                      <span className="flex-1 truncate">{entry.config.displayName}</span>
+                      {count > 0 ? (
+                        <span
+                          className="shrink-0 text-[11.5px] tabular-nums"
+                          style={{ color: 'rgb(var(--accent-ink))' }}
+                        >
+                          {count}
+                        </span>
+                      ) : null}
+                      {/* The affordance that says this row leads somewhere. */}
+                      <ChevronRight
+                        className="h-3.5 w-3.5 shrink-0"
+                        strokeWidth={1.5}
+                        aria-hidden="true"
+                        style={{ color: 'rgb(var(--text-muted))' }}
+                      />
+                    </button>
+                  )
+                })}
+              </div>
+            )}
+          </div>
+        )}
+      </Popover.Content>
+    </Popover>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* FilterChipBar                                                       */
+/* ------------------------------------------------------------------ */
+
+/** "Building", "Building, Review", "Building, Review +2". */
+function summarize(options: readonly ColumnOption[], values: readonly string[]): string {
+  const labels = values.map(
+    (value) => options.find((option) => option.value === value)?.label ?? value,
+  )
+  if (labels.length <= 2) return labels.join(', ')
+  return `${labels.slice(0, 2).join(', ')} +${labels.length - 2}`
+}
+
+export interface FilterChipBarProps<TData> {
+  rows: readonly TData[]
+  columns: ReadonlyArray<AnyColumnConfig<TData>>
+  filters: FiltersState
+  onFiltersChange: (next: FiltersState) => void
+  renderOptionIcon?: FilterOptionIconRenderer
+  className?: string
+}
+
+/**
+ * The applied filters, as a bar under the action bar.
+ *
+ *   ⚑ | Column  is  Building  ✕ | ................ [Clear]
+ *
+ * Renders NOTHING when nothing is applied — no reserved strip, no empty frame
+ * — so an unfiltered board is the action bar and the columns, nothing else.
+ */
+export function FilterChipBar<TData>({
+  rows,
+  columns,
+  filters,
+  onFiltersChange,
+  renderOptionIcon,
+  className,
+}: FilterChipBarProps<TData>) {
+  const editable = useMemo(() => editableColumns(columns), [columns])
+  if (filters.length === 0) return null
+
+  return (
+    <div
+      role="group"
+      aria-label="Active filters"
+      className={cn(
+        'flex flex-wrap items-center gap-2 rounded-[var(--radius-lg)] px-3 py-2',
+        className,
+      )}
+      style={{
+        background: 'rgb(var(--surface-frame))',
+        border: '1px solid rgb(var(--border))',
+      }}
+    >
+      <ListFilter
+        className="h-3.5 w-3.5 shrink-0"
+        strokeWidth={1.5}
+        aria-hidden="true"
+        style={{ color: 'rgb(var(--text-tertiary))' }}
+      />
+      {filters.map((filter) => {
+        const entry = editable.find((candidate) => candidate.config.id === filter.columnId)
+        // A filter on a column this UI cannot edit is still real and still
+        // removable — it just does not open a value list.
+        const displayName =
+          entry?.config.displayName ??
+          columns.find((column) => column.id === filter.columnId)?.displayName ??
+          filter.columnId
+        const summary = summarize(entry?.options ?? [], optionValuesOf(filter))
+        return (
+          <FilterChip
+            key={filter.columnId}
+            displayName={displayName}
+            operator={filter.operator}
+            summary={summary}
+            onRemove={() => onFiltersChange(removeFilter(filters, filter.columnId))}
+            {...(entry
+              ? {
+                  edit: (
+                    <FilterValueList
+                      rows={rows}
+                      columns={columns}
+                      filters={filters}
+                      column={entry.config}
+                      options={entry.options}
+                      onFiltersChange={onFiltersChange}
+                      {...(renderOptionIcon ? { renderOptionIcon } : {})}
+                    />
+                  ),
+                }
+              : {})}
+          />
+        )
+      })}
+      <div className="flex-1" />
+      <Button variant="secondary" size="sm" onClick={() => onFiltersChange([])}>
+        Clear
+      </Button>
+    </div>
+  )
+}
+
+function FilterChip({
+  displayName,
+  operator,
+  summary,
+  onRemove,
+  edit,
+}: {
+  displayName: string
+  operator: string
+  summary: string
+  onRemove: () => void
+  edit?: ReactNode
+}) {
+  const contentRef = useRef<HTMLDivElement | null>(null)
+  const chipLabel = `${displayName} ${operator} ${summary}`
+
+  const body = (
+    <span className="flex items-center gap-1.5 text-[11.5px]">
+      <span className="font-semibold" style={{ color: 'rgb(var(--foreground))' }}>
+        {displayName}
+      </span>
+      {/* The verb reads in the mono face and the muted ink: it is the joint
+          between the two halves, not a third thing to read. */}
+      <span
+        className="text-[10.5px]"
+        style={{ color: 'rgb(var(--text-muted))', fontFamily: 'var(--font-mono)' }}
+      >
+        {operator}
+      </span>
+      <span className="font-medium" style={{ color: 'rgb(var(--accent-ink))' }}>
+        {summary}
+      </span>
+    </span>
+  )
+
+  return (
+    <span
+      // CONCENTRIC WITHIN 8px (action-bar brief §6.1). The chip is
+      // --radius-sm (8) and pads its trailing control by 2px, so the remove
+      // control is exactly 8 − 2 = 6 = --radius-xs. Both are real tokens and
+      // the derivation is exact, not approximate.
+      className="inline-flex min-h-7 items-center gap-1.5 rounded-[var(--radius-sm)] py-0.5 pe-0.5 ps-2"
+      style={{
+        background: 'rgb(var(--surface-card))',
+        border: '1px solid rgb(var(--border))',
+        boxShadow: 'var(--shadow-sm)',
+      }}
+    >
+      {edit ? (
+        <Popover>
+          <Popover.Trigger asChild>
+            <button
+              type="button"
+              aria-label={`Edit filter: ${chipLabel}`}
+              className="rounded-[var(--radius-xs)] focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]"
+            >
+              {body}
+            </button>
+          </Popover.Trigger>
+          <Popover.Content
+            ref={contentRef}
+            aria-label={`Filter by ${displayName}`}
+            align="start"
+            className="w-60 p-3"
+            onKeyDown={(event: ReactKeyboardEvent<HTMLDivElement>) =>
+              handleTabTrap(event, contentRef.current)
+            }
+          >
+            {edit}
+          </Popover.Content>
+        </Popover>
+      ) : (
+        <span>{body}</span>
+      )}
+      {/* 24×24 hit area (interface standards §6), inside a 28px chip. */}
+      <button
+        type="button"
+        aria-label={`Remove filter: ${chipLabel}`}
+        onClick={onRemove}
+        className={cn(
+          'flex h-6 w-6 shrink-0 items-center justify-center rounded-[var(--radius-xs)]',
+          'transition-[background-color] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+          'hover:bg-[rgb(var(--surface-hover))]',
+          'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+        )}
+        style={{ color: 'rgb(var(--text-tertiary))' }}
+      >
+        <X className="h-3 w-3" strokeWidth={2} aria-hidden="true" />
+      </button>
+    </span>
+  )
+}

package/src/floating-drawer.tsx

@@ -49,6 +49,13 @@ export interface FloatingDrawerProps {
   onResize?: (next: number) => void
   /** Header title — short, e.g. the record's name or the drawer's purpose. */
   title?: ReactNode
+  /**
+   * Accessible name for the dialog, for a drawer whose `title` is JSX or
+   * absent. The panel derives `aria-label` from `title` only when it is a
+   * plain string, so a caller that owns its own header (or passes a node)
+   * otherwise ships a dialog with NO name at all.
+   */
+  ariaLabel?: string
   /** Optional element rendered to the right of the title, before close. */
   titleSlot?: ReactNode
   /** Optional footer — action buttons. */
@@ -110,6 +117,7 @@ export function FloatingDrawer({
   resizable = false,
   onResize,
   title,
+  ariaLabel,
   titleSlot,
   footer,
   children,
@@ -241,7 +249,17 @@ export function FloatingDrawer({
       <aside
         role="dialog"
         aria-modal={modal ? 'true' : undefined}
-        aria-label={typeof title === 'string' ? title : undefined}
+        aria-label={typeof title === 'string' ? title : ariaLabel}
+        /**
+         * A CLOSED drawer is still mounted — that is how it animates out, and
+         * consumers that keep it mounted rely on it. But an off-screen panel
+         * left in the accessibility tree is a nameless dialog a screen-reader
+         * user can land in, and its controls stay in the tab order, which is a
+         * keyboard hole nobody sees. `inert` removes both, and reverts the
+         * moment it opens.
+         */
+        aria-hidden={isOpen ? undefined : 'true'}
+        inert={!isOpen}
         className={cn(
           panelZ,
           'flex flex-col overflow-hidden',