@lovett/ui 0.0.11 → 0.2.0

package/src/display-popover.tsx

@@ -0,0 +1,487 @@
+/**
+ * DisplayPopover + its row primitives — the "how should this view look" panel.
+ *
+ * `docs/design-briefs/tasks-board-header-primitives.md` §4: the source app's
+ * display popover is copy-pasted JSX, and the ONE abstraction in the whole
+ * repo is an eight-line `OptionRow` that its two call sites already disagree
+ * about (`text-sm`/`h-8` in one, `text-xs`/`h-7` in the other). So the
+ * boundary is drawn here rather than ported:
+ *
+ *   OptionRow            label on the left, control on the right
+ *   SelectRow            OptionRow + <Select>
+ *   ToggleRow            OptionRow + <Checkbox>, owning the id/htmlFor pair
+ *   ChipToggleGroup      the display-property chips
+ *   SectionHeading       plain + muted
+ *   PopoverFooterActions the reset row
+ *   DisplayPopover       the shell: fixed width, no padding of its own,
+ *                        self-padding sections separated by a hairline
+ *
+ * Two things the source gets wrong and this cannot:
+ *
+ *   1. `ToggleRow` MINTS the id and wires `htmlFor` itself, so a caller
+ *      cannot ship a checkbox whose label does not click it. Theirs is
+ *      hand-written at three call sites.
+ *   2. `PopoverFooterActions` renders its primary action ONLY when one is
+ *      supplied. Theirs has a "Set default for everyone" `<button>` with no
+ *      `onClick` in three files — a dead control that cannot happen here
+ *      because the absent prop renders nothing.
+ *
+ * Chips carry `type="button"` and `aria-pressed`; theirs carry neither, so
+ * inside a form they submit it and to a screen reader they are unlabelled
+ * toggles. A pressed chip steps up to an OPAQUE surface with an accent border
+ * rather than being marked by a translucent tint (CLAUDE.md §2: "if the state
+ * is conveyed only by alpha, it is wrong").
+ *
+ * Focus: `Popover` is non-modal — it focuses in and hands focus back, but Tab
+ * walks out of it. A display panel is a self-contained set of controls, so the
+ * shell wraps Tab inside itself with `handleTabTrap`. Escape and focus-return
+ * come from `Popover` unchanged.
+ */
+
+import {
+  useId,
+  useRef,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+} from 'react'
+import { Check } from 'lucide-react'
+import { cn } from './lib/utils'
+import { handleTabTrap } from './lib/focus'
+import { Popover } from './popover'
+import { Checkbox } from './checkbox'
+import { Select, type SelectOption } from './select'
+
+/* ------------------------------------------------------------------ */
+/* SectionHeading                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface SectionHeadingProps {
+  children: ReactNode
+  /** The quieter treatment, for a secondary block inside the same panel. */
+  muted?: boolean
+  className?: string
+}
+
+/** Small caps get positive tracking (interface standards §"Type"). */
+export function SectionHeading({ children, muted, className }: SectionHeadingProps) {
+  return (
+    <div
+      className={cn(
+        'text-[10.5px] font-semibold uppercase tracking-[0.06em]',
+        className,
+      )}
+      style={{ color: `rgb(var(--text-${muted ? 'muted' : 'tertiary'}))` }}
+    >
+      {children}
+    </div>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* OptionRow                                                           */
+/* ------------------------------------------------------------------ */
+
+export interface OptionRowProps {
+  /** A Lucide icon, sized by the caller. Optional — most rows have none. */
+  icon?: ReactNode
+  label: ReactNode
+  /** Secondary line under the label. */
+  hint?: ReactNode
+  /** Nest this row under the one above it. */
+  indent?: boolean
+  disabled?: boolean
+  /** The control. Sits at the inline end of the row. */
+  children?: ReactNode
+  /**
+   * Renders the label as a `<label>` for this control id. `ToggleRow` sets
+   * it; a caller building a bespoke row can too.
+   */
+  htmlFor?: string
+  className?: string
+}
+
+/**
+ * The label/control row. `min-h` rather than a fixed height, so a row whose
+ * label wraps grows instead of clipping (interface standards §3, "no fixed
+ * widths on any text container").
+ */
+export function OptionRow({
+  icon,
+  label,
+  hint,
+  indent,
+  disabled,
+  children,
+  htmlFor,
+  className,
+}: OptionRowProps) {
+  const text = (
+    <>
+      <span className="text-[12.5px] font-medium leading-tight">{label}</span>
+      {hint ? (
+        <span
+          className="text-[11.5px] leading-tight"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          {hint}
+        </span>
+      ) : null}
+    </>
+  )
+
+  return (
+    <div
+      data-slot="option-row"
+      data-disabled={disabled ? 'true' : undefined}
+      className={cn(
+        'flex min-h-[var(--ctrl-sm)] items-center justify-between gap-3',
+        'rounded-[var(--radius-sm)]',
+        indent && 'ps-5',
+        disabled && 'opacity-50',
+        className,
+      )}
+      style={{ color: 'rgb(var(--foreground))' }}
+    >
+      {htmlFor ? (
+        <label
+          htmlFor={htmlFor}
+          className="flex flex-1 cursor-pointer select-none items-center gap-2 py-1"
+        >
+          {icon ? <span className="flex shrink-0 items-center">{icon}</span> : null}
+          <span className="flex flex-col gap-0.5">{text}</span>
+        </label>
+      ) : (
+        <span className="flex flex-1 items-center gap-2 py-1">
+          {icon ? <span className="flex shrink-0 items-center">{icon}</span> : null}
+          <span className="flex flex-col gap-0.5">{text}</span>
+        </span>
+      )}
+      {children ? <span className="flex shrink-0 items-center">{children}</span> : null}
+    </div>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* SelectRow                                                           */
+/* ------------------------------------------------------------------ */
+
+export interface SelectRowProps<T extends string = string>
+  extends Omit<OptionRowProps, 'children' | 'htmlFor'> {
+  value: T
+  onValueChange: (next: T) => void
+  options: ReadonlyArray<SelectOption<T>>
+  /** Accessible name for the control. Defaults to the row's label if it is a string. */
+  controlLabel?: string
+  /** Width of the select. Defaults to a slot wide enough for the longest option. */
+  selectClassName?: string
+}
+
+export function SelectRow<T extends string = string>({
+  value,
+  onValueChange,
+  options,
+  controlLabel,
+  selectClassName,
+  label,
+  ...row
+}: SelectRowProps<T>) {
+  const name =
+    controlLabel ?? (typeof label === 'string' ? label : undefined) ?? 'Option'
+  return (
+    <OptionRow label={label} {...row}>
+      <Select
+        size="sm"
+        aria-label={name}
+        value={value}
+        onValueChange={onValueChange}
+        options={options}
+        disabled={row.disabled ?? false}
+        // A reserved slot, so swapping "Due date" for "Manual" cannot resize
+        // the row (interface standards §"Layout stability").
+        className={cn('min-w-[9.5rem]', selectClassName)}
+      />
+    </OptionRow>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* ToggleRow                                                           */
+/* ------------------------------------------------------------------ */
+
+export interface ToggleRowProps extends Omit<OptionRowProps, 'children' | 'htmlFor'> {
+  checked: boolean
+  onCheckedChange: (next: boolean) => void
+  /** Override the minted id. Rarely needed. */
+  id?: string
+}
+
+/**
+ * The id/htmlFor pairing lives HERE, not at the call site — a caller cannot
+ * forget it, which is the single most common way a settings checkbox ships
+ * with a label that does not click it.
+ */
+export function ToggleRow({
+  checked,
+  onCheckedChange,
+  id,
+  ...row
+}: ToggleRowProps) {
+  const generated = useId()
+  const controlId = id ?? `toggle-row-${generated.replace(/:/g, '')}`
+  return (
+    <OptionRow
+      {...row}
+      htmlFor={controlId}
+      className={cn(
+        // The checkbox itself is 16px; the row is the hit area, and the ring
+        // has to be visible on the row because the input is opacity-0.
+        //
+        // `:has(:focus-visible)`, not `:focus-within`. `focus-within` fires on
+        // ANY focus, including the focus a plain mouse click puts on the
+        // checkbox — so clicking a toggle painted a keyboard focus ring on the
+        // row and left it there. `:focus-visible` is the browser's own
+        // "this focus came from the keyboard" heuristic, and `:has()` lifts it
+        // from the invisible input to the row that can actually show it.
+        // Forced-colors gets the same treatment as a system outline in
+        // styles.css, since this ring is a box-shadow.
+        'has-[:focus-visible]:[box-shadow:var(--ring-focus)]',
+        row.className,
+      )}
+    >
+      <Checkbox
+        id={controlId}
+        checked={checked}
+        onCheckedChange={onCheckedChange}
+        disabled={row.disabled ?? false}
+      />
+    </OptionRow>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* ChipToggleGroup                                                     */
+/* ------------------------------------------------------------------ */
+
+export interface ChipToggleItem {
+  readonly key: string
+  readonly label: string
+  readonly icon?: ReactNode
+}
+
+export interface ChipToggleGroupProps {
+  items: readonly ChipToggleItem[]
+  /** key -> pressed. A key missing from the record reads as unpressed. */
+  value: Readonly<Record<string, boolean>>
+  onToggle: (key: string, next: boolean) => void
+  /** Names the group for assistive tech. */
+  'aria-label': string
+  className?: string
+}
+
+/**
+ * A row of on/off chips. Every chip is `type="button"` with `aria-pressed`,
+ * which the source's is not — inside a form theirs submits it, and a screen
+ * reader is told nothing about which are on.
+ */
+export function ChipToggleGroup({
+  items,
+  value,
+  onToggle,
+  'aria-label': ariaLabel,
+  className,
+}: ChipToggleGroupProps) {
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      className={cn('flex flex-wrap gap-1.5', className)}
+    >
+      {items.map((item) => {
+        const pressed = value[item.key] ?? false
+        return (
+          <button
+            key={item.key}
+            type="button"
+            aria-pressed={pressed}
+            onClick={() => onToggle(item.key, !pressed)}
+            className={cn(
+              'inline-flex min-h-6 items-center gap-1.5 px-2 py-1',
+              'rounded-[var(--radius-sm)] text-[11.5px] font-medium',
+              'transition-[background-color,border-color,color,box-shadow]',
+              'duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+              'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+            )}
+            style={{
+              // A pressed chip STEPS UP to an OPAQUE surface, out of the
+              // recessed track: never an alpha tint alone (CLAUDE.md §2, "if
+              // the state is conveyed only by alpha, it is wrong").
+              //
+              // The step-up is neutral — border weight, text weight and
+              // shadow — and deliberately NOT the accent. This is a
+              // multi-toggle whose DEFAULT is every chip on, so an accent
+              // border here paints five accents into a view that already
+              // spends its one on the active view tab. The accent earns its
+              // impact from scarcity; depth does this job without it.
+              background: pressed
+                ? 'rgb(var(--surface-card))'
+                : 'rgb(var(--surface-frame))',
+              border: `1px solid rgb(var(${pressed ? '--border-strong' : '--border'}))`,
+              color: `rgb(var(${pressed ? '--foreground' : '--text-muted'}))`,
+              boxShadow: pressed ? 'var(--shadow-sm)' : 'none',
+            }}
+          >
+            {/* A SHAPE cue, not only a surface one. In dark mode
+                `--surface-card` and `--surface-frame` sit close enough that
+                the step-up alone is not a reliable on/off read, and a state
+                carried by colour alone fails the accessibility floor either
+                way. The slot is always rendered so toggling cannot resize the
+                chip and reflow the row. */}
+            <Check
+              aria-hidden="true"
+              className={cn('h-3 w-3 shrink-0', !pressed && 'invisible')}
+              strokeWidth={2.5}
+            />
+            {item.icon ? (
+              <span className="flex shrink-0 items-center">{item.icon}</span>
+            ) : null}
+            {item.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* PopoverFooterActions                                                */
+/* ------------------------------------------------------------------ */
+
+export interface PopoverFooterAction {
+  label: string
+  onClick: () => void
+  disabled?: boolean
+}
+
+export interface PopoverFooterActionsProps {
+  onReset: () => void
+  resetLabel?: string
+  /** Absent renders NOTHING — the reason a dead primary cannot ship here. */
+  primaryAction?: PopoverFooterAction
+  /** Disables the reset when the panel is already at its defaults. */
+  resetDisabled?: boolean
+}
+
+export function PopoverFooterActions({
+  onReset,
+  resetLabel = 'Reset to defaults',
+  primaryAction,
+  resetDisabled,
+}: PopoverFooterActionsProps) {
+  return (
+    <div className="flex items-center justify-between gap-2">
+      <button
+        type="button"
+        onClick={onReset}
+        disabled={resetDisabled ?? false}
+        className={cn(
+          'inline-flex min-h-6 items-center rounded-[var(--radius-sm)] px-1.5',
+          'text-[11.5px] font-medium underline-offset-2 hover:underline',
+          'disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:no-underline',
+          'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+        )}
+        style={{ color: 'rgb(var(--text-secondary))' }}
+      >
+        {resetLabel}
+      </button>
+      {primaryAction ? (
+        <button
+          type="button"
+          onClick={primaryAction.onClick}
+          disabled={primaryAction.disabled ?? false}
+          className="btn btn-secondary size-sm"
+        >
+          {primaryAction.label}
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* DisplayPopover                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface DisplayPopoverProps {
+  /** The trigger element. Rendered through `Popover.Trigger asChild`. */
+  trigger: ReactNode
+  /** Accessible name for the panel. */
+  label: string
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** `DisplayPopover.Section` children. */
+  children: ReactNode
+  /** Panel width. Default `w-80`. */
+  className?: string
+}
+
+function DisplayPopoverRoot({
+  trigger,
+  label,
+  open,
+  onOpenChange,
+  children,
+  className,
+}: DisplayPopoverProps) {
+  const contentRef = useRef<HTMLDivElement | null>(null)
+
+  return (
+    <Popover
+      {...(open === undefined ? {} : { open })}
+      {...(onOpenChange ? { onOpenChange } : {})}
+    >
+      <Popover.Trigger asChild>{trigger}</Popover.Trigger>
+      <Popover.Content
+        ref={contentRef}
+        aria-label={label}
+        align="end"
+        // Padding is stripped here and paid by each section, so the hairline
+        // between sections reaches both edges of the panel.
+        className={cn('w-80 p-0', className)}
+        onKeyDown={(event: ReactKeyboardEvent<HTMLDivElement>) =>
+          handleTabTrap(event, contentRef.current)
+        }
+      >
+        {children}
+      </Popover.Content>
+    </Popover>
+  )
+}
+
+export interface DisplayPopoverSectionProps {
+  children: ReactNode
+  className?: string
+}
+
+/**
+ * A self-padding block. Every section but the first draws a hairline above
+ * it — the divider is the LAST resort elsewhere, but here it is the panel's
+ * only structure and the sections are genuinely different subjects.
+ */
+function DisplayPopoverSection({ children, className }: DisplayPopoverSectionProps) {
+  return (
+    <div
+      className={cn(
+        'flex flex-col gap-1.5 p-3',
+        '[&:not(:first-child)]:border-t [&:not(:first-child)]:border-solid',
+        className,
+      )}
+      style={{ borderColor: 'rgb(var(--border))' }}
+    >
+      {children}
+    </div>
+  )
+}
+
+export const DisplayPopover = Object.assign(DisplayPopoverRoot, {
+  Section: DisplayPopoverSection,
+})