@lovett/ui 0.0.11 → 0.2.0

package/src/detail/field-list.tsx

@@ -0,0 +1,196 @@
+/**
+ * FieldList — the chrome above the field rows, and the filter they read.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md` §4: "Above the list: Manage
+ * fields, a field search, and All / Filled / Empty chips that filter the
+ * visible rows."
+ *
+ * ## How a row disappears, and why it is `hidden` rather than unmounted
+ *
+ * Filtering by returning `null` from a filtered-out row would throw away that
+ * row's editor state — type half a due date, type a letter in the search box,
+ * lose it. §1's "switching modes must not lose an in-progress edit" is about
+ * modes, but the same loss through the search box would be no less of a bug.
+ * So a filtered-out row stays MOUNTED and carries the `hidden` attribute,
+ * which the package's reset renders as `display: none !important` and which
+ * removes it from the accessibility tree and the tab ring. Clear the search
+ * and the half-typed editor is still there.
+ *
+ * ## The value column
+ *
+ * Every row's value starts on the same line because the label column is one
+ * shared custom property, declared here and read by every row
+ * (`--field-label-inline-size`). A row cannot set its own and drift.
+ *
+ * ## The empty state
+ *
+ * Driven by CSS (`.ds-field-list-empty` in styles.css) rather than by counting
+ * matched rows in React. Counting would need every row to REGISTER with this
+ * component in an effect, which is a render-loop hazard for a purely cosmetic
+ * line — and the browser can already answer "are any of my rows visible?" with
+ * `:has()`.
+ */
+
+import {
+  createContext,
+  useContext,
+  useId,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react'
+import { Search, Settings2 } from 'lucide-react'
+import { Button } from '../button'
+import { Input } from '../input'
+import { cn } from '../lib/utils'
+import { SegmentedChoice } from './segmented-choice'
+import { FIELD_FILTERS, FIELD_FILTER_LABELS, type FieldFilter } from './types'
+
+interface FieldListContextValue {
+  readonly query: string
+  readonly filter: FieldFilter
+}
+
+const FieldListCtx = createContext<FieldListContextValue | null>(null)
+
+/**
+ * Whether a row with this label and fill state passes the list's current
+ * search and chip. Outside a `<FieldList>` every row is visible — a row is
+ * usable on its own.
+ */
+export function useFieldRowVisible(label: string, filled: boolean): boolean {
+  const ctx = useContext(FieldListCtx)
+  if (ctx === null) return true
+  if (ctx.filter === 'filled' && !filled) return false
+  if (ctx.filter === 'empty' && filled) return false
+  const query = ctx.query.trim().toLowerCase()
+  if (query.length === 0) return true
+  return label.toLowerCase().includes(query)
+}
+
+/** React accepts custom properties in `style`; the DOM typings do not. */
+type StyleWithVars = CSSProperties & Record<`--${string}`, string>
+
+export interface FieldListProps {
+  children: ReactNode
+  /** Omit and no Manage fields control is drawn. */
+  onManageFields?: (() => void) | undefined
+  manageFieldsLabel?: string | undefined
+  /** Controlled search. Omit for internal state. */
+  query?: string | undefined
+  onQueryChange?: ((next: string) => void) | undefined
+  searchPlaceholder?: string | undefined
+  /** Controlled chip. Omit for internal state. */
+  filter?: FieldFilter | undefined
+  onFilterChange?: ((next: FieldFilter) => void) | undefined
+  /**
+   * Width of the shared label column, px. The DEFAULT lives in styles.css
+   * (`.ds-field-list`); this only overrides it.
+   */
+  labelWidth?: number | undefined
+  /** Shown when the search and chip leave nothing visible. */
+  emptyState?: ReactNode | undefined
+  className?: string | undefined
+}
+
+export function FieldList({
+  children,
+  onManageFields,
+  manageFieldsLabel = 'Manage fields',
+  query,
+  onQueryChange,
+  searchPlaceholder = 'Search fields',
+  filter,
+  onFilterChange,
+  labelWidth,
+  emptyState = 'No fields match that search.',
+  className,
+}: FieldListProps) {
+  const searchId = useId()
+  const [internalQuery, setInternalQuery] = useState('')
+  const [internalFilter, setInternalFilter] = useState<FieldFilter>('all')
+  const activeQuery = query ?? internalQuery
+  const activeFilter = filter ?? internalFilter
+
+  const style: StyleWithVars | undefined =
+    labelWidth === undefined
+      ? undefined
+      : { '--field-label-inline-size': `${labelWidth}px` }
+
+  return (
+    <FieldListCtx.Provider value={{ query: activeQuery, filter: activeFilter }}>
+      <div
+        data-slot="field-list"
+        className={cn('ds-field-list flex min-h-0 flex-1 flex-col', className)}
+        {...(style === undefined ? {} : { style })}
+      >
+        <div
+          className="flex shrink-0 flex-wrap items-center border-b"
+          style={{
+            gap: 'var(--space-2)',
+            paddingInline: 'var(--space-4)',
+            paddingBlock: 'var(--space-2)',
+            borderColor: 'rgb(var(--border))',
+          }}
+        >
+          <label htmlFor={searchId} className="sr-only">
+            {searchPlaceholder}
+          </label>
+          <Input
+            id={searchId}
+            inputSize="sm"
+            type="search"
+            value={activeQuery}
+            placeholder={searchPlaceholder}
+            onChange={(event) => {
+              const next = event.target.value
+              if (query === undefined) setInternalQuery(next)
+              onQueryChange?.(next)
+            }}
+            leadingAffix={<Search size={14} strokeWidth={1.5} aria-hidden="true" />}
+            shellClassName="min-w-[10rem] flex-1"
+          />
+
+          <SegmentedChoice
+            ariaLabel="Filter fields"
+            value={activeFilter}
+            onChange={(next) => {
+              if (filter === undefined) setInternalFilter(next)
+              onFilterChange?.(next)
+            }}
+            items={FIELD_FILTERS.map((id) => ({ id, label: FIELD_FILTER_LABELS[id] }))}
+          />
+
+          {onManageFields === undefined ? null : (
+            <Button
+              variant="secondary"
+              size="sm"
+              onClick={onManageFields}
+              leadingIcon={<Settings2 size={14} strokeWidth={1.5} aria-hidden="true" />}
+            >
+              {manageFieldsLabel}
+            </Button>
+          )}
+        </div>
+
+        <div
+          data-slot="field-list-body"
+          className="flex min-h-0 flex-1 flex-col overflow-y-auto"
+          style={{
+            gap: 'var(--space-1)',
+            paddingInline: 'var(--space-4)',
+            paddingBlock: 'var(--space-3)',
+          }}
+        >
+          {children}
+          <p
+            className="ds-field-list-empty text-[12.5px] leading-[1.5]"
+            style={{ margin: 0, color: 'rgb(var(--text-tertiary))' }}
+          >
+            {emptyState}
+          </p>
+        </div>
+      </div>
+    </FieldListCtx.Provider>
+  )
+}