@lovett/ui 0.0.11 → 0.2.0

package/src/detail/detail-header.tsx

@@ -0,0 +1,287 @@
+/**
+ * DetailHeader — the item's name, its state, and every way out.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md` §2, left to right: mark
+ * complete · title · "Updated ‹relative›" · prev / next · reminder · favourite
+ * · ellipsis · close.
+ *
+ * IT RENDERS SLOTS; THE LENS SUPPLIES BEHAVIOUR. Nothing here writes to a
+ * server, moves an item between columns or knows what a board is. The two
+ * controls §7 says cannot be honest yet — the reminder, and anything else the
+ * host has no backing system for — are `ReactNode` slots that render NOTHING
+ * when the host passes nothing. That is how an un-backed control stays off the
+ * screen instead of shipping dead: the header cannot draw a button the lens
+ * did not hand it.
+ *
+ * The same rule shapes the rest. `onCompleteChange` absent → no completion
+ * toggle. `onFavouriteChange` absent → no star. `onTitleChange` absent → the
+ * title is a heading, not a field. Prev / next render as a pair once EITHER
+ * handler is present, and the one without a handler is disabled — that is the
+ * "disabled at the ends" state, and it comes from the host passing `undefined`
+ * rather than from this component knowing anything about board order.
+ *
+ * Every control is an icon PLUS an accessible name (§8). The three that are
+ * icon-only carry it as `aria-label`; mark-complete carries it as visible text
+ * because its label is also the state readout ("the label reflects state").
+ */
+
+import { useId, useRef, type ReactNode } from 'react'
+import {
+  Check,
+  ChevronDown,
+  ChevronUp,
+  Circle,
+  Star,
+  X,
+} from 'lucide-react'
+import { Button } from '../button'
+import { cn } from '../lib/utils'
+import { RelativeTime } from '../thread/relative-time'
+import { useNowTick } from '../thread/use-now'
+
+export interface DetailHeaderProps {
+  /** The item's name. */
+  title: string
+  /** Omit and the title renders as a heading rather than a field. */
+  onTitleChange?: ((next: string) => void) | undefined
+  /** Enter and blur both land here. Escape reverts without calling it. */
+  onTitleCommit?: (() => void) | undefined
+  /** Accessible name for the title field. Default "Item title". */
+  titleLabel?: string | undefined
+  titleMaxLength?: number | undefined
+
+  /** Completion. Omit `onCompleteChange` and no toggle renders. */
+  complete?: boolean | undefined
+  onCompleteChange?: ((next: boolean) => void) | undefined
+  /** Default "Mark complete" / "Completed" — sentence case, names the state. */
+  completeLabel?: string | undefined
+  completedLabel?: string | undefined
+
+  /** Epoch milliseconds. Omit and no "Updated" reads out. */
+  updatedAt?: number | undefined
+  /** Frozen clock for tests. Omit and the shared 60s ticker drives it. */
+  now?: number | undefined
+  locale?: string | undefined
+
+  /** Prev / next through the board's visible items. Omit BOTH for no pair. */
+  onPrev?: (() => void) | undefined
+  onNext?: (() => void) | undefined
+  prevLabel?: string | undefined
+  nextLabel?: string | undefined
+
+  /**
+   * §7 — reminders have no notification system behind them in this workspace,
+   * and a reminder that silently never fires is worse than no reminder. So
+   * there is no built-in control: a host that HAS a backing system passes one
+   * here, and a host that does not passes nothing and nothing is drawn.
+   */
+  reminder?: ReactNode | undefined
+
+  /** Favourite. Omit `onFavouriteChange` and no star renders. */
+  favourite?: boolean | undefined
+  onFavouriteChange?: ((next: boolean) => void) | undefined
+  favouriteLabel?: string | undefined
+  favouritedLabel?: string | undefined
+
+  /** The ellipsis — a `<DetailMenu>`. Nothing renders when omitted. */
+  menu?: ReactNode | undefined
+
+  onClose: () => void
+  closeLabel?: string | undefined
+  className?: string | undefined
+}
+
+export function DetailHeader({
+  title,
+  onTitleChange,
+  onTitleCommit,
+  titleLabel = 'Item title',
+  titleMaxLength = 200,
+  complete,
+  onCompleteChange,
+  completeLabel = 'Mark complete',
+  completedLabel = 'Completed',
+  updatedAt,
+  now,
+  locale,
+  onPrev,
+  onNext,
+  prevLabel = 'Previous item',
+  nextLabel = 'Next item',
+  reminder,
+  favourite,
+  onFavouriteChange,
+  favouriteLabel = 'Add to favourites',
+  favouritedLabel = 'Remove from favourites',
+  menu,
+  onClose,
+  closeLabel = 'Close item',
+  className,
+}: DetailHeaderProps) {
+  const fieldId = useId()
+  // The shared 60s ticker, or a frozen clock. `useNowTick(false)` subscribes
+  // to nothing and starts no timer, so a test that passes `now` is
+  // deterministic without fake-timer plumbing.
+  const ticked = useNowTick(now === undefined)
+  const clock = now ?? ticked
+  // Enter commits and then leaves the field, which fires a blur that would
+  // commit a second time. One gesture, one write.
+  const committedRef = useRef(false)
+  const isComplete = complete === true
+  const isFavourite = favourite === true
+  const showSteps = onPrev !== undefined || onNext !== undefined
+
+  return (
+    <header
+      data-slot="detail-header"
+      className={cn('flex shrink-0 items-center border-b', className)}
+      style={{
+        gap: 'var(--space-2)',
+        paddingInline: 'var(--space-4)',
+        // A step under the horizontal, per the optical rule (§8).
+        paddingBlock: 'var(--space-3)',
+        borderColor: 'rgb(var(--border))',
+      }}
+    >
+      {onCompleteChange === undefined ? null : (
+        <Button
+          variant="secondary"
+          size="sm"
+          aria-pressed={isComplete}
+          onClick={() => onCompleteChange(!isComplete)}
+          className="shrink-0"
+          leadingIcon={
+            isComplete ? (
+              <Check
+                size={14}
+                strokeWidth={2}
+                aria-hidden="true"
+                style={{ color: 'rgb(var(--success))' }}
+              />
+            ) : (
+              <Circle size={14} strokeWidth={1.5} aria-hidden="true" />
+            )
+          }
+        >
+          {isComplete ? completedLabel : completeLabel}
+        </Button>
+      )}
+
+      <div className="flex min-w-0 flex-1 items-center">
+        {onTitleChange === undefined ? (
+          <h2
+            className="min-w-0 truncate text-[17px] font-semibold leading-[1.3] tracking-[-0.01em]"
+            style={{ color: 'rgb(var(--foreground))', margin: 0 }}
+          >
+            {title}
+          </h2>
+        ) : (
+          <>
+            <label htmlFor={`${fieldId}-title`} className="sr-only">
+              {titleLabel}
+            </label>
+            <input
+              id={`${fieldId}-title`}
+              value={title}
+              maxLength={titleMaxLength}
+              onChange={(event) => onTitleChange(event.target.value)}
+              onBlur={() => {
+                if (committedRef.current) {
+                  committedRef.current = false
+                  return
+                }
+                onTitleCommit?.()
+              }}
+              onKeyDown={(event) => {
+                if (event.key !== 'Enter') return
+                event.preventDefault()
+                committedRef.current = true
+                onTitleCommit?.()
+                event.currentTarget.blur()
+              }}
+              // Reads as a heading until you reach for it. The transparent 1px
+              // border is always there, so revealing the field on hover cannot
+              // move the title by a pixel.
+              className="w-full truncate rounded-[var(--radius-sm)] border border-solid border-transparent bg-transparent text-[17px] font-semibold leading-[1.3] tracking-[-0.01em] hover:border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]"
+              style={{
+                color: 'rgb(var(--foreground))',
+                paddingInline: 'var(--space-2)',
+                paddingBlock: 'var(--space-1)',
+                marginInlineStart: 'calc(var(--space-2) * -1)',
+              }}
+            />
+          </>
+        )}
+      </div>
+
+      {updatedAt === undefined ? null : (
+        <span
+          data-slot="detail-updated"
+          className="shrink-0 whitespace-nowrap text-[11.5px] tabular-nums"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          Updated <RelativeTime value={updatedAt} now={clock} locale={locale} />
+        </span>
+      )}
+
+      {!showSteps ? null : (
+        <span className="flex shrink-0 items-center" style={{ gap: 'var(--space-1)' }}>
+          <Button
+            variant="icon"
+            size="sm"
+            aria-label={prevLabel}
+            disabled={onPrev === undefined}
+            onClick={onPrev}
+          >
+            <ChevronUp size={15} strokeWidth={2} aria-hidden="true" />
+          </Button>
+          <Button
+            variant="icon"
+            size="sm"
+            aria-label={nextLabel}
+            disabled={onNext === undefined}
+            onClick={onNext}
+          >
+            <ChevronDown size={15} strokeWidth={2} aria-hidden="true" />
+          </Button>
+        </span>
+      )}
+
+      {reminder === undefined ? null : (
+        <span data-slot="detail-reminder" className="flex shrink-0 items-center">
+          {reminder}
+        </span>
+      )}
+
+      {onFavouriteChange === undefined ? null : (
+        <Button
+          variant="icon"
+          size="sm"
+          aria-label={isFavourite ? favouritedLabel : favouriteLabel}
+          aria-pressed={isFavourite}
+          onClick={() => onFavouriteChange(!isFavourite)}
+        >
+          {/* Not colour alone: the star FILLS when active, and the control is
+              `aria-pressed` (interface standards §"Color & emphasis"). */}
+          <Star
+            size={15}
+            strokeWidth={isFavourite ? 2 : 1.5}
+            aria-hidden="true"
+            fill={isFavourite ? 'currentColor' : 'none'}
+            style={isFavourite ? { color: 'rgb(var(--accent-ink))' } : undefined}
+          />
+        </Button>
+      )}
+
+      {menu === undefined ? null : (
+        <span data-slot="detail-menu-slot" className="flex shrink-0 items-center">
+          {menu}
+        </span>
+      )}
+
+      <Button variant="icon" size="sm" aria-label={closeLabel} onClick={onClose}>
+        <X size={15} strokeWidth={2} aria-hidden="true" />
+      </Button>
+    </header>
+  )
+}

package/src/detail/detail-menu.tsx

@@ -0,0 +1,254 @@
+/**
+ * DetailMenu — the ellipsis.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md` §3, top to bottom: the three
+ * mode icons in a row · Move · Copy · Copy URL · Repeat · Print · Archive ·
+ * Delete (destructive, confirmed) · the record id with a copy affordance.
+ *
+ * THE HOST SUPPLIES THE ITEMS, AND AN ITEM IT DOES NOT SUPPLY IS NOT DRAWN.
+ * That is the whole point of the `actions` record rather than a fixed list of
+ * callbacks: §7 names three things — reminders, repeat, attachments — that
+ * have no backing system yet, and the owner's standing rule is that a rendered
+ * control does what it says. A menu built from a fixed list can only express
+ * "missing" as a disabled row, which is a dead control with an excuse. Here,
+ * `repeat` absent means there is no Repeat line at all, and the day the
+ * scheduling engine lands the lens adds one key to one object.
+ *
+ * ORDER IS FIXED HERE, not by the caller's key order, so two lenses cannot
+ * ship the same menu in two different sequences.
+ *
+ * The mode row is a real selected state: an opaque step UP (`--surface-card`
+ * on a `--surface-inset` track, accent border, `--shadow-sm`), never an alpha
+ * tint on a translucent track — CLAUDE.md §2's hard rule, and the same shape
+ * the thread's sort pills use.
+ */
+
+import { useEffect, useState, type ReactNode } from 'react'
+import {
+  Archive,
+  Copy,
+  CornerUpRight,
+  Link2,
+  Maximize2,
+  MoreHorizontal,
+  PanelRight,
+  Printer,
+  Repeat2,
+  SquareDashed,
+  Trash2,
+} from 'lucide-react'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '../dropdown-menu'
+import { Kbd } from '../kbd'
+import { cn } from '../lib/utils'
+import { copyText } from '../lib/clipboard'
+import { SegmentedChoice } from './segmented-choice'
+import { DETAIL_MODES, DETAIL_MODE_LABELS, type DetailMode } from './types'
+
+export type DetailMenuAction =
+  | 'move'
+  | 'copy'
+  | 'copyUrl'
+  | 'repeat'
+  | 'print'
+  | 'archive'
+  | 'delete'
+
+export interface DetailMenuItem {
+  onSelect: () => void
+  /** Overrides the default label. Sentence case. */
+  label?: string | undefined
+  /** Keyboard hint glyph. Defaults to the reference's (M · C · L · R · P). */
+  hint?: string | undefined
+  disabled?: boolean | undefined
+}
+
+/** Fixed order and default copy. Two lenses cannot ship two sequences. */
+const ACTION_ORDER: readonly DetailMenuAction[] = [
+  'move',
+  'copy',
+  'copyUrl',
+  'repeat',
+  'print',
+  'archive',
+  'delete',
+]
+
+const ACTION_LABEL: Readonly<Record<DetailMenuAction, string>> = {
+  move: 'Move',
+  copy: 'Copy',
+  copyUrl: 'Copy URL',
+  repeat: 'Repeat',
+  print: 'Print',
+  archive: 'Archive',
+  delete: 'Delete',
+}
+
+const ACTION_HINT: Readonly<Partial<Record<DetailMenuAction, string>>> = {
+  move: 'M',
+  copy: 'C',
+  copyUrl: 'L',
+  repeat: 'R',
+  print: 'P',
+}
+
+const ACTION_ICON: Readonly<Record<DetailMenuAction, ReactNode>> = {
+  move: <CornerUpRight size={15} strokeWidth={1.5} aria-hidden="true" />,
+  copy: <Copy size={15} strokeWidth={1.5} aria-hidden="true" />,
+  copyUrl: <Link2 size={15} strokeWidth={1.5} aria-hidden="true" />,
+  repeat: <Repeat2 size={15} strokeWidth={1.5} aria-hidden="true" />,
+  print: <Printer size={15} strokeWidth={1.5} aria-hidden="true" />,
+  archive: <Archive size={15} strokeWidth={1.5} aria-hidden="true" />,
+  delete: <Trash2 size={15} strokeWidth={1.5} aria-hidden="true" />,
+}
+
+const MODE_ICON: Readonly<Record<DetailMode, ReactNode>> = {
+  full: <Maximize2 size={15} strokeWidth={1.5} aria-hidden="true" />,
+  modal: <SquareDashed size={15} strokeWidth={1.5} aria-hidden="true" />,
+  panel: <PanelRight size={15} strokeWidth={1.5} aria-hidden="true" />,
+}
+
+export interface DetailMenuProps {
+  mode: DetailMode
+  onModeChange: (next: DetailMode) => void
+  /** Only the actions present here are rendered, in the order §3 sets. */
+  actions?: Partial<Record<DetailMenuAction, DetailMenuItem>> | undefined
+  /** The record id, muted, at the foot. Omit for no id row. */
+  recordId?: string | undefined
+  /** Defaults to writing the id to the clipboard with a confirmation toast. */
+  onCopyRecordId?: ((recordId: string) => void) | undefined
+  /** Controlled open state. Omit for internal. */
+  open?: boolean | undefined
+  onOpenChange?: ((next: boolean) => void) | undefined
+  /** Accessible name for the ellipsis. Default "More actions". */
+  triggerLabel?: string | undefined
+  /** Names the mode group. Default "Open items in". */
+  modeGroupLabel?: string | undefined
+  className?: string | undefined
+}
+
+export function DetailMenu({
+  mode,
+  onModeChange,
+  actions,
+  recordId,
+  onCopyRecordId,
+  open,
+  onOpenChange,
+  triggerLabel = 'More actions',
+  modeGroupLabel = 'Open items in',
+  className,
+}: DetailMenuProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(false)
+  const isOpen = open ?? uncontrolledOpen
+  // Two-step delete. The confirm lives here rather than in the host so every
+  // lens gets the same guard; it resets whenever the menu closes, so a menu
+  // reopened later never starts one keystroke from destroying a record.
+  const [confirmingDelete, setConfirmingDelete] = useState(false)
+  useEffect(() => {
+    if (!isOpen) setConfirmingDelete(false)
+  }, [isOpen])
+
+  const present = ACTION_ORDER.filter((action) => actions?.[action] !== undefined)
+
+  return (
+    <DropdownMenu
+      open={isOpen}
+      onOpenChange={(next) => {
+        setUncontrolledOpen(next)
+        onOpenChange?.(next)
+      }}
+    >
+      <DropdownMenuTrigger
+        unstyled
+        aria-label={triggerLabel}
+        className={cn('btn btn-icon size-sm', className)}
+      >
+        <MoreHorizontal size={15} strokeWidth={2} aria-hidden="true" />
+      </DropdownMenuTrigger>
+
+      <DropdownMenuContent align="end" className="min-w-[15rem]">
+        {/* 1. The three modes. */}
+        <SegmentedChoice
+          ariaLabel={modeGroupLabel}
+          stretch
+          className="w-full"
+          value={mode}
+          onChange={onModeChange}
+          items={DETAIL_MODES.map((candidate) => ({
+            id: candidate,
+            label: DETAIL_MODE_LABELS[candidate],
+            icon: MODE_ICON[candidate],
+            iconOnly: true,
+          }))}
+        />
+
+        {present.length === 0 ? null : <DropdownMenuSeparator />}
+
+        {/* 2-8. Only what the host supplied, in §3's order. */}
+        {present.map((action) => {
+          const item = actions?.[action]
+          if (item === undefined) return null
+          const destructive = action === 'delete'
+          const confirming = destructive && confirmingDelete
+          const label = confirming
+            ? 'Confirm delete'
+            : (item.label ?? ACTION_LABEL[action])
+          const hint = item.hint ?? ACTION_HINT[action]
+          return (
+            <DropdownMenuItem
+              key={action}
+              data-action={action}
+              variant={destructive ? 'destructive' : 'default'}
+              disabled={item.disabled ?? false}
+              onClick={(event) => {
+                if (destructive && !confirmingDelete) {
+                  // Keep the menu open for the second press: the primitive
+                  // closes on click unless the handler prevents it.
+                  event.preventDefault()
+                  setConfirmingDelete(true)
+                  return
+                }
+                item.onSelect()
+              }}
+            >
+              {ACTION_ICON[action]}
+              <span className="flex-1">{label}</span>
+              {hint === undefined || confirming ? null : (
+                <Kbd size="sm">{hint}</Kbd>
+              )}
+            </DropdownMenuItem>
+          )
+        })}
+
+        {/* 9. The record id. Muted, and copyable. */}
+        {recordId === undefined ? null : (
+          <>
+            <DropdownMenuSeparator />
+            {/* A `menuitem`, not a bare button: everything inside a
+                `role="menu"` has to be one, and copying the id IS an action.
+                Muted and tabular so it reads as a record stamp rather than as
+                a seventh command. */}
+            <DropdownMenuItem
+              data-slot="detail-record-id"
+              aria-label={`Copy record id ${recordId}`}
+              onClick={() => {
+                if (onCopyRecordId) onCopyRecordId(recordId)
+                else void copyText(recordId, 'record id')
+              }}
+              className="text-[11.5px] font-normal tabular-nums text-[rgb(var(--text-tertiary))]"
+            >
+              <span className="min-w-0 flex-1 truncate">{recordId}</span>
+              <Copy size={13} strokeWidth={1.5} aria-hidden="true" />
+            </DropdownMenuItem>
+          </>
+        )}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}