@lovett/ui 0.0.11 → 0.2.0

package/src/detail/calendar.tsx

@@ -0,0 +1,355 @@
+/**
+ * MonthCalendar — the date editor's month grid, and the date-value helpers.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md` §4: "a calendar popover for
+ * dates (with an `Include time` toggle and a confirm)". This file is the grid;
+ * `FieldRow.Date` owns the toggle, the time field and the confirm.
+ *
+ * ## Values are strings, and they are LOCAL
+ *
+ * `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` when a time is included — the same shape
+ * a `<input type="date">` and the wire both use. Every conversion here goes
+ * through the numeric parts, never `new Date('2026-09-06')`: that literal
+ * parses as UTC midnight, which renders as the fifth of September for
+ * everybody west of Greenwich. A date field that shows the wrong day in half
+ * the world is the classic version of this bug and it is entirely avoidable.
+ *
+ * ## The clock
+ *
+ * "Today" comes from the thread's shared ticker rather than `Date.now()` in a
+ * render path, so a test freezes it by passing `now` and no timer runs.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { Button } from '../button'
+import { cn } from '../lib/utils'
+import { useNowTick } from '../thread/use-now'
+
+export interface DateParts {
+  readonly year: number
+  /** 0-11, like `Date`. */
+  readonly month: number
+  readonly day: number
+  /** `HH:mm`, or null when the value is a plain date. */
+  readonly time: string | null
+}
+
+const VALUE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?/
+
+/** Defensive parse: an unreadable value is "no value", never a throw. */
+export function parseDateValue(value: string | null | undefined): DateParts | null {
+  if (typeof value !== 'string') return null
+  const match = VALUE_PATTERN.exec(value.trim())
+  if (match === null) return null
+  const [, y, m, d, hh, mm] = match
+  if (y === undefined || m === undefined || d === undefined) return null
+  const year = Number(y)
+  const month = Number(m) - 1
+  const day = Number(d)
+  if (month < 0 || month > 11 || day < 1 || day > 31) return null
+  const time = hh !== undefined && mm !== undefined ? `${hh}:${mm}` : null
+  return { year, month, day, time }
+}
+
+function pad(n: number): string {
+  return n < 10 ? `0${n}` : String(n)
+}
+
+export function formatDateValue(parts: DateParts): string {
+  const date = `${parts.year}-${pad(parts.month + 1)}-${pad(parts.day)}`
+  return parts.time === null ? date : `${date}T${parts.time}`
+}
+
+/** Local midday, so a DST shift cannot roll the day over. */
+function toDate(parts: DateParts): Date {
+  return new Date(parts.year, parts.month, parts.day, 12, 0, 0, 0)
+}
+
+/** The value as a person reads it. Falls back to the raw string if unparseable. */
+export function formatDateDisplay(
+  value: string | null | undefined,
+  locale?: string | undefined,
+): string {
+  const parts = parseDateValue(value)
+  if (parts === null) return typeof value === 'string' ? value : ''
+  const day = new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  }).format(toDate(parts))
+  if (parts.time === null) return day
+  const [hh = '0', mm = '0'] = parts.time.split(':')
+  const withTime = new Date(parts.year, parts.month, parts.day, Number(hh), Number(mm))
+  const time = new Intl.DateTimeFormat(locale, {
+    hour: 'numeric',
+    minute: '2-digit',
+  }).format(withTime)
+  return `${day}, ${time}`
+}
+
+function daysInMonth(year: number, month: number): number {
+  return new Date(year, month + 1, 0).getDate()
+}
+
+function sameDay(a: DateParts | null, year: number, month: number, day: number): boolean {
+  return a !== null && a.year === year && a.month === month && a.day === day
+}
+
+export interface MonthCalendarProps {
+  /** The selected day, or null. */
+  selected: DateParts | null
+  onSelect: (next: { year: number; month: number; day: number }) => void
+  locale?: string | undefined
+  /** 0 = Sunday. Default 0. */
+  weekStartsOn?: number | undefined
+  /** Frozen clock, epoch ms. Omit and the shared ticker supplies "today". */
+  now?: number | undefined
+  className?: string | undefined
+}
+
+export function MonthCalendar({
+  selected,
+  onSelect,
+  locale,
+  weekStartsOn = 0,
+  now,
+  className,
+}: MonthCalendarProps) {
+  const ticked = useNowTick(now === undefined)
+  const clock = now ?? ticked
+  const today = useMemo(() => new Date(clock), [clock])
+
+  const [view, setView] = useState<{ year: number; month: number }>(() =>
+    selected === null
+      ? { year: today.getFullYear(), month: today.getMonth() }
+      : { year: selected.year, month: selected.month },
+  )
+  // The roving tab stop. One button in the grid is tabbable; the arrows move
+  // which one, so the grid is one stop rather than 35.
+  const [focusedDay, setFocusedDay] = useState<number>(selected?.day ?? today.getDate())
+  const moveFocusRef = useRef(false)
+  const gridRef = useRef<HTMLDivElement | null>(null)
+
+  // Follow the selection when it changes from outside (a different item).
+  //
+  // Keyed on the three NUMBERS, never on `selected` itself. The parent builds
+  // that object by parsing a string on every render, so a fresh identity
+  // arrives each time — an effect depending on it would set state, re-render,
+  // receive another fresh object and run again. That is the render loop the
+  // repo has already been bitten by once (`useResumableDraft`, ADR-116 Phase
+  // B), and it presents as an out-of-memory test rather than as a loop.
+  const selectedYear = selected === null ? null : selected.year
+  const selectedMonth = selected === null ? null : selected.month
+  const selectedDay = selected === null ? null : selected.day
+  useEffect(() => {
+    if (selectedYear === null || selectedMonth === null || selectedDay === null) return
+    setView((current) =>
+      current.year === selectedYear && current.month === selectedMonth
+        ? current
+        : { year: selectedYear, month: selectedMonth },
+    )
+    setFocusedDay(selectedDay)
+  }, [selectedYear, selectedMonth, selectedDay])
+
+  useEffect(() => {
+    if (!moveFocusRef.current) return
+    moveFocusRef.current = false
+    const node = gridRef.current?.querySelector<HTMLElement>('[data-day][tabindex="0"]')
+    node?.focus()
+  }, [focusedDay, view])
+
+  const total = daysInMonth(view.year, view.month)
+  const firstWeekday = new Date(view.year, view.month, 1).getDay()
+  const lead = (firstWeekday - weekStartsOn + 7) % 7
+
+  const weekdayLabels = useMemo(() => {
+    const formatter = new Intl.DateTimeFormat(locale, { weekday: 'short' })
+    // 2024-01-07 was a Sunday; offsetting from it gives every weekday name
+    // without touching the current date.
+    return Array.from({ length: 7 }, (_, index) =>
+      formatter.format(new Date(2024, 0, 7 + ((index + weekStartsOn) % 7))),
+    )
+  }, [locale, weekStartsOn])
+
+  const monthLabel = useMemo(
+    () =>
+      new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(
+        new Date(view.year, view.month, 1),
+      ),
+    [locale, view.year, view.month],
+  )
+
+  const dayLabel = useMemo(
+    () => new Intl.DateTimeFormat(locale, { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' }),
+    [locale],
+  )
+
+  const shift = (delta: number) => {
+    const next = new Date(view.year, view.month, focusedDay + delta)
+    moveFocusRef.current = true
+    setView({ year: next.getFullYear(), month: next.getMonth() })
+    setFocusedDay(next.getDate())
+  }
+
+  const shiftMonth = (delta: number) => {
+    const next = new Date(view.year, view.month + delta, 1)
+    const year = next.getFullYear()
+    const month = next.getMonth()
+    setView({ year, month })
+    setFocusedDay((current) => Math.min(current, daysInMonth(year, month)))
+  }
+
+  const cells: (number | null)[] = [
+    ...Array.from({ length: lead }, () => null),
+    ...Array.from({ length: total }, (_, index) => index + 1),
+  ]
+  while (cells.length % 7 !== 0) cells.push(null)
+  const rows: (number | null)[][] = []
+  for (let index = 0; index < cells.length; index += 7) {
+    rows.push(cells.slice(index, index + 7))
+  }
+
+  return (
+    <div data-slot="month-calendar" className={cn('flex flex-col', className)} style={{ gap: 'var(--space-2)' }}>
+      <div className="flex items-center justify-between" style={{ gap: 'var(--space-2)' }}>
+        <Button
+          variant="icon"
+          size="sm"
+          aria-label="Previous month"
+          onClick={() => shiftMonth(-1)}
+        >
+          <ChevronLeft size={15} strokeWidth={2} aria-hidden="true" />
+        </Button>
+        <span
+          aria-live="polite"
+          className="text-[12.5px] font-semibold"
+          style={{ color: 'rgb(var(--foreground))' }}
+        >
+          {monthLabel}
+        </span>
+        <Button variant="icon" size="sm" aria-label="Next month" onClick={() => shiftMonth(1)}>
+          <ChevronRight size={15} strokeWidth={2} aria-hidden="true" />
+        </Button>
+      </div>
+
+      <div
+        ref={gridRef}
+        role="grid"
+        aria-label={monthLabel}
+        onKeyDown={(event) => {
+          const moves: Readonly<Record<string, number>> = {
+            ArrowLeft: -1,
+            ArrowRight: 1,
+            ArrowUp: -7,
+            ArrowDown: 7,
+            PageUp: -total,
+            PageDown: total,
+          }
+          const delta = moves[event.key]
+          if (delta !== undefined) {
+            event.preventDefault()
+            shift(delta)
+            return
+          }
+          if (event.key === 'Home') {
+            event.preventDefault()
+            shift(-((focusedDay - 1) % 7))
+          } else if (event.key === 'End') {
+            event.preventDefault()
+            shift(6 - ((focusedDay - 1) % 7))
+          }
+        }}
+      >
+        <div role="row" className="grid grid-cols-7" style={{ gap: 'var(--space-1)' }}>
+          {weekdayLabels.map((label) => (
+            <span
+              key={label}
+              role="columnheader"
+              className="flex h-6 items-center justify-center text-[10.5px] font-semibold uppercase tracking-[0.06em]"
+              style={{ color: 'rgb(var(--text-tertiary))' }}
+            >
+              {label.slice(0, 2)}
+            </span>
+          ))}
+        </div>
+        {rows.map((row, rowIndex) => (
+          <div
+            key={`row-${String(rowIndex)}`}
+            role="row"
+            className="grid grid-cols-7"
+            style={{ gap: 'var(--space-1)' }}
+          >
+            {row.map((day, cellIndex) => {
+              if (day === null) {
+                return (
+                  <span
+                    key={`blank-${String(rowIndex)}-${String(cellIndex)}`}
+                    role="gridcell"
+                    aria-hidden="true"
+                    className="h-7"
+                  />
+                )
+              }
+              const isSelected = sameDay(selected, view.year, view.month, day)
+              const isToday =
+                today.getFullYear() === view.year &&
+                today.getMonth() === view.month &&
+                today.getDate() === day
+              return (
+                // The CELL is the gridcell; the button inside keeps its native
+                // role. `role="gridcell"` was on the <button>, which overwrote
+                // it — a grid full of cells that a screen reader could not
+                // announce as buttons, and buttons it could not announce as
+                // cells. `aria-selected` belongs on the cell too (it is a
+                // gridcell state; a plain button does not support it).
+                <div
+                  key={day}
+                  role="gridcell"
+                  aria-selected={isSelected}
+                >
+                  <button
+                    type="button"
+                    data-day={day}
+                    aria-label={dayLabel.format(new Date(view.year, view.month, day, 12))}
+                    // The cell that IS today, announced as such rather than left
+                    // to the underline and the extra font weight.
+                    {...(isToday ? { 'aria-current': 'date' as const } : {})}
+                    tabIndex={day === focusedDay ? 0 : -1}
+                    onClick={() => {
+                      setFocusedDay(day)
+                      onSelect({ year: view.year, month: view.month, day })
+                    }}
+                    className={cn(
+                      // `w-full`: the button used to BE the grid item and
+                      // stretched to the column; now the cell wrapper does, so
+                      // the button has to fill it or the hit area shrinks to the
+                      // width of the digits.
+                      'flex h-7 w-full items-center justify-center text-[12px] tabular-nums',
+                      'transition-[background-color,color,border-color] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+                      'motion-reduce:transition-none',
+                      'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                      isSelected
+                        ? 'border border-[rgb(var(--accent))] bg-[rgb(var(--surface-card))] font-semibold text-[rgb(var(--accent-ink))] [box-shadow:var(--shadow-sm)]'
+                        : 'border border-transparent text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))]',
+                    )}
+                    style={{
+                      borderRadius: 'var(--radius-xs)',
+                      // Today is marked by weight as well as colour, so it is
+                      // legible without perceiving hue.
+                      fontWeight: isToday && !isSelected ? 700 : undefined,
+                      textDecoration: isToday ? 'underline' : undefined,
+                      textUnderlineOffset: isToday ? '3px' : undefined,
+                    }}
+                  >
+                    {day}
+                  </button>
+                </div>
+              )
+            })}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/detail/detail-divider.tsx

@@ -0,0 +1,261 @@
+/**
+ * DetailDivider — the seam between the fields and the activity pane.
+ *
+ * §8: "The divider is a real `separator` with keyboard resize." That is
+ * already `ResizableHandle` (WAI-ARIA splitter: `role="separator"`,
+ * `aria-valuenow/min/max`, arrows, PageUp/PageDown, Home), so this file adds
+ * no second implementation of any of it. What it adds is the three things the
+ * handle deliberately does not own:
+ *
+ *   1. AN IN-FLOW STRIP. `ResizableHandle` is `position: absolute` — it
+ *      decorates an edge of an already-positioned pane. The detail's split is
+ *      a flex row (or column) where the divider is a sibling BETWEEN two
+ *      panes, so it needs a box of its own to sit in.
+ *   2. THE VISIBLE LINE. The handle paints only on hover and drag; at rest it
+ *      is transparent. A split with no line at rest is the "flat / floating"
+ *      defect (CLAUDE.md §2) — grey structure inside an opaque surface is
+ *      required, not a candidate for cleanup. So the strip carries a 1px
+ *      `--border` hairline down its centre.
+ *   3. THE COLLAPSE CAPSULE, and the double-click that goes with it. Modelled
+ *      on `lenses/social/components/ResizableSplit.tsx`, which is the shape
+ *      the owner already tuned: a hover-revealed capsule centred on the seam
+ *      with one button per direction, and the seam's double-click toggling
+ *      collapse rather than resetting the size.
+ *
+ * ORIENTATION, and why the mapping is inverted. `value` is the size of the
+ * pane AFTER the divider (the activity pane). `ResizableHandle` inverts the
+ * drag delta for its `left` and `top` sides, which is exactly the sign we
+ * need: dragging the seam toward the inline start grows the pane that sits
+ * after it. So `side` → `left` and `bottom` → `top`, and dragging always
+ * grows the thing you are dragging away from.
+ *
+ * ## Why double-click is intercepted in the CAPTURE phase
+ *
+ * `ResizableHandle` binds double-click to "reset to `defaultValue`", and the
+ * handle covers the whole strip, so a listener on the strip would fire in
+ * ADDITION to it — one gesture doing two things. Taking the event in the
+ * capture phase and stopping it there is the only way to REPLACE the handle's
+ * behaviour without forking the handle, and the reset is not lost: it is what
+ * `Home` does, which is where the WAI-ARIA splitter pattern puts it anyway.
+ *
+ * ## Where the collapse's FOCUS move lives (it is not here)
+ *
+ * Pressing a capsule button collapses a pane, which sets `hidden` on this
+ * whole strip — so the button unmounts under the operator's finger and focus
+ * falls to `<body>`. The fix is to park focus on the `RestoreRail` the
+ * collapse leaves behind, and that CANNOT be done from this file: the rail is
+ * rendered by `DetailSurface` and mounts in the same commit this strip
+ * disappears in, so there is no node here to move focus to.
+ *
+ * So the divider stays presentational — it calls the callbacks it is given
+ * and knows nothing about what they do. `DetailSurface`'s `collapseTo` owns
+ * the state change AND the focus that follows it, in a `useLayoutEffect`
+ * after the commit. If you are here because focus is being dropped on
+ * collapse, read `collapseTo` in `detail-surface.tsx`.
+ */
+
+import type { ReactNode } from 'react'
+import { ChevronsDown, ChevronsLeft, ChevronsRight, ChevronsUp } from 'lucide-react'
+import { ResizableHandle } from '../resizable'
+import { cn } from '../lib/utils'
+import type { DetailPaneSide } from './types'
+
+export interface DetailDividerProps {
+  /**
+   * Where the resizable pane sits: `side` (a vertical seam, activity at the
+   * inline end) or `bottom` (a horizontal seam, activity below). Comes from
+   * `detailPaneSide(mode)` — never chosen independently.
+   */
+  orientation: DetailPaneSide
+  /** Size of the pane after the seam, in px. */
+  value: number
+  onChange: (next: number) => void
+  /** Fires once on release / keypress. Persist from here, not `onChange`. */
+  onCommit?: ((next: number) => void) | undefined
+  min: number
+  max: number
+  /** Home target, and what the capsule restores to. Defaults to the midpoint. */
+  defaultValue?: number | undefined
+  /** Keyboard nudge, px. Default 16. */
+  step?: number | undefined
+  /** Required. Names what is being resized, not "divider". */
+  'aria-label': string
+  disabled?: boolean | undefined
+  /**
+   * Takes the strip out of the layout AND the tab ring. Set while a pane is
+   * collapsed: there is nothing left to resize, and a separator reporting a
+   * range it cannot move through is worse than no separator.
+   */
+  hidden?: boolean | undefined
+  /** Collapses the pane BEFORE the seam. Omitted, no button is drawn. */
+  onCollapseFields?: (() => void) | undefined
+  /** Collapses the pane AFTER the seam. Omitted, no button is drawn. */
+  onCollapseAside?: (() => void) | undefined
+  /** Double-click on the seam. Omitted, double-click does nothing. */
+  onToggleCollapse?: (() => void) | undefined
+  className?: string | undefined
+}
+
+export function DetailDivider({
+  orientation,
+  value,
+  onChange,
+  onCommit,
+  min,
+  max,
+  defaultValue,
+  step,
+  'aria-label': ariaLabel,
+  disabled,
+  hidden,
+  onCollapseFields,
+  onCollapseAside,
+  onToggleCollapse,
+  className,
+}: DetailDividerProps) {
+  const vertical = orientation === 'side'
+  const CollapseFieldsIcon = vertical ? ChevronsLeft : ChevronsUp
+  const CollapseAsideIcon = vertical ? ChevronsRight : ChevronsDown
+  const hasCapsule = onCollapseFields !== undefined || onCollapseAside !== undefined
+
+  return (
+    <div
+      data-slot="detail-divider"
+      data-orientation={vertical ? 'vertical' : 'horizontal'}
+      hidden={hidden === true}
+      onDoubleClickCapture={
+        onToggleCollapse === undefined
+          ? undefined
+          : (event) => {
+              // Capture, and stopped here: see the header note. Without this
+              // the handle's own reset runs on the same gesture.
+              event.stopPropagation()
+              onToggleCollapse()
+            }
+      }
+      className={cn(
+        'relative shrink-0',
+        vertical ? 'w-1 self-stretch' : 'h-1 w-full',
+        className,
+      )}
+    >
+      {/* The hairline. Centred in the 4px strip so the handle's hover fill
+          reads as thickening the existing line rather than introducing one. */}
+      <span
+        aria-hidden="true"
+        className="pointer-events-none absolute"
+        style={{
+          background: 'rgb(var(--border))',
+          ...(vertical
+            ? { insetBlock: 0, insetInlineStart: 'calc(50% - 0.5px)', inlineSize: '1px' }
+            : { insetInline: 0, insetBlockStart: 'calc(50% - 0.5px)', blockSize: '1px' }),
+        }}
+      />
+      <ResizableHandle
+        side={vertical ? 'left' : 'top'}
+        value={value}
+        onChange={onChange}
+        min={min}
+        max={max}
+        step={step ?? 16}
+        aria-label={ariaLabel}
+        disabled={disabled ?? false}
+        {...(onCommit === undefined ? {} : { onCommit })}
+        {...(defaultValue === undefined ? {} : { defaultValue })}
+      />
+
+      {/* The capsule. Revealed by `:hover` / `:focus-within` on the strip
+          (styles.css) rather than by state, so a keyboard user reaches the
+          buttons by Tab and the reveal follows the focus ring. It is
+          ABSOLUTE, so revealing it shifts nothing. */}
+      {hasCapsule ? (
+        <div
+          data-slot="detail-collapse-capsule"
+          className={cn(
+            'absolute z-[1] flex items-center',
+            vertical ? 'flex-col' : 'flex-row',
+          )}
+          style={{
+            // A QUARTER along the seam, not half. Centred, the capsule covers
+            // the seam's midpoint — which is exactly where a pointer goes to
+            // grab it — and the buttons swallow the press, so the divider
+            // stops being draggable at its most obvious grab point. The
+            // reference splitter gets away with centring because its channel
+            // is 28px wide and the capsule leaves a grip between the buttons;
+            // this seam is 4px, so the control moves instead.
+            insetBlockStart: vertical ? '25%' : '50%',
+            insetInlineStart: vertical ? '50%' : '25%',
+            transform: 'translate(-50%, -50%)',
+            gap: '1px',
+            // An OPAQUE raised chrome. `--surface-overlay` here would read as
+            // a grey ghost over whichever pane it overlaps (CLAUDE.md §2);
+            // `--muted` is the public opaque neutral until `--surface-raised`
+            // lands (ADR-063).
+            background: 'rgb(var(--muted))',
+            border: '1px solid rgb(var(--border))',
+            borderRadius: 'var(--radius-full)',
+            padding: 'var(--space-1)',
+            boxShadow: 'var(--shadow-md)',
+          }}
+        >
+          {onCollapseFields === undefined ? null : (
+            <CapsuleButton
+              label="Collapse the fields pane"
+              onClick={onCollapseFields}
+            >
+              <CollapseFieldsIcon size={14} strokeWidth={1.5} aria-hidden="true" />
+            </CapsuleButton>
+          )}
+          {onCollapseAside === undefined ? null : (
+            <CapsuleButton label="Collapse the activity pane" onClick={onCollapseAside}>
+              <CollapseAsideIcon size={14} strokeWidth={1.5} aria-hidden="true" />
+            </CapsuleButton>
+          )}
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+/**
+ * One button in the capsule.
+ *
+ * `onPointerDown` is stopped: the handle underneath starts a drag on
+ * pointerdown, so without this every collapse click would also nudge the seam
+ * by however far the pointer moved between press and release.
+ */
+function CapsuleButton({
+  label,
+  onClick,
+  children,
+}: {
+  label: string
+  onClick: () => void
+  children: ReactNode
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      data-slot="detail-collapse-button"
+      onClick={onClick}
+      onPointerDown={(event) => event.stopPropagation()}
+      onDoubleClick={(event) => event.stopPropagation()}
+      className={cn(
+        'inline-flex items-center justify-center rounded-[var(--radius-full)]',
+        'transition-colors duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+        'motion-reduce:transition-none',
+        'hover:bg-[rgb(var(--surface-hover))] hover:text-[rgb(var(--foreground))]',
+        'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+      )}
+      style={{
+        inlineSize: 'var(--space-6)',
+        blockSize: 'var(--space-6)',
+        color: 'rgb(var(--text-secondary))',
+      }}
+    >
+      {children}
+    </button>
+  )
+}