@lovett/ui 0.0.11 → 0.2.0

package/src/detail/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @lovett/ui — the item-detail surface.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md`. A frame with three modes, a
+ * slotted header, the ellipsis menu, the Notion-style field rows, and the
+ * activity pane. Entity-agnostic by construction: nothing here fetches, and
+ * nothing here knows what a task is. The lens supplies the data and the
+ * behaviour; this package supplies the surface.
+ *
+ * `MonthCalendar` is deliberately NOT exported — it is the date row's editor,
+ * not a general calendar, and promoting it would freeze a shape that has had
+ * exactly one consumer.
+ */
+
+export { DetailSurface, type DetailSurfaceProps } from './detail-surface'
+export { DetailHeader, type DetailHeaderProps } from './detail-header'
+export {
+  DetailMenu,
+  type DetailMenuProps,
+  type DetailMenuAction,
+  type DetailMenuItem,
+} from './detail-menu'
+export { DetailDivider, type DetailDividerProps } from './detail-divider'
+
+export { FieldList, useFieldRowVisible, type FieldListProps } from './field-list'
+export {
+  FieldRow,
+  FieldValueButton,
+  type FieldRowProps,
+  type FieldValueButtonProps,
+  type FieldRowTextProps,
+  type FieldRowDateProps,
+  type FieldRowSelectProps,
+  type FieldRowPeopleProps,
+  type FieldRowTagsProps,
+} from './field-row'
+
+export { ActivityPane, type ActivityPaneProps, type ActivityTab } from './activity-pane'
+
+/** Date values are `YYYY-MM-DD` / `YYYY-MM-DDTHH:mm`, parsed as LOCAL. */
+export { formatDateDisplay, parseDateValue, type DateParts } from './calendar'
+
+export {
+  DETAIL_COLLAPSE_VALUES,
+  DETAIL_MODES,
+  DETAIL_MODE_LABELS,
+  DETAIL_PANEL_DEFAULT_SIZE,
+  FIELD_FILTERS,
+  FIELD_FILTER_LABELS,
+  detailPaneSide,
+  type ActivityEntry,
+  type DetailCollapse,
+  type DetailMode,
+  type DetailPaneSide,
+  type FieldFilter,
+  type FieldOption,
+  type FieldPerson,
+} from './types'

package/src/detail/segmented-choice.tsx

@@ -0,0 +1,94 @@
+/**
+ * SegmentedChoice — a one-of-N choice, internal to the detail surface.
+ *
+ * NOT `SegmentedPill`, and the reason is a11y rather than taste: that
+ * primitive renders `role="tablist"` with `role="tab"` segments, which is
+ * correct for a view switcher wired to tab panels and wrong for the two
+ * choices here — the mode row in the ellipsis menu, and the All / Filled /
+ * Empty filter chips. Neither controls a tab panel, and a screen reader that
+ * announces "tab 2 of 3" for a filter is being told something untrue.
+ * `role="group"` + `aria-pressed` says what these actually are.
+ *
+ * The selected state is the one CLAUDE.md §2 mandates: an opaque step UP
+ * (`--surface-card` on a `--surface-inset` track) with an accent border and
+ * `--shadow-sm`. Never an alpha tint on a translucent track — two alpha
+ * layers composite to a raised element that renders DARKER than the well it
+ * sits in.
+ *
+ * Not exported from the package barrel; it is a shape, not a contract.
+ */
+
+import type { ReactNode } from 'react'
+import { cn } from '../lib/utils'
+
+export interface SegmentedChoiceItem<Id extends string> {
+  readonly id: Id
+  /** Visible text, or the accessible name when `icon` carries the meaning. */
+  readonly label: string
+  readonly icon?: ReactNode | undefined
+  /** Render the icon alone and keep `label` as the accessible name. */
+  readonly iconOnly?: boolean | undefined
+}
+
+export interface SegmentedChoiceProps<Id extends string> {
+  items: readonly SegmentedChoiceItem<Id>[]
+  value: Id
+  onChange: (next: Id) => void
+  /** Names the group. Required — a bare row of buttons has no name. */
+  ariaLabel: string
+  /** Stretch the segments to fill the track. Default false. */
+  stretch?: boolean | undefined
+  className?: string | undefined
+}
+
+export function SegmentedChoice<Id extends string>({
+  items,
+  value,
+  onChange,
+  ariaLabel,
+  stretch = false,
+  className,
+}: SegmentedChoiceProps<Id>) {
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      data-slot="segmented-choice"
+      className={cn('inline-flex items-center gap-[var(--space-1)] border p-[var(--space-1)]', className)}
+      style={{
+        borderRadius: 'var(--radius-md)',
+        borderColor: 'rgb(var(--border))',
+        background: 'rgb(var(--surface-inset))',
+      }}
+    >
+      {items.map((item) => {
+        const active = item.id === value
+        return (
+          <button
+            key={item.id}
+            type="button"
+            data-choice={item.id}
+            aria-pressed={active}
+            {...(item.iconOnly ? { 'aria-label': item.label } : {})}
+            onClick={() => onChange(item.id)}
+            className={cn(
+              'inline-flex h-[26px] items-center justify-center gap-[var(--space-1)]',
+              'px-[var(--space-2)] text-[12px] font-semibold',
+              stretch && 'flex-1',
+              'transition-[background-color,color,border-color,box-shadow] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+              'motion-reduce:transition-none',
+              'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+              active
+                ? 'border border-[rgb(var(--accent))] bg-[rgb(var(--surface-card))] text-[rgb(var(--accent-ink))] [box-shadow:var(--shadow-sm)]'
+                : 'border border-transparent text-[rgb(var(--text-tertiary))] hover:text-[rgb(var(--foreground))]',
+            )}
+            style={{ borderRadius: 'var(--radius-sm)' }}
+          >
+            {item.icon}
+            {item.iconOnly ? null : item.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}

package/src/detail/types.ts

@@ -0,0 +1,129 @@
+/**
+ * Item detail — the shared vocabulary.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md` §1. Three modes, and the
+ * orientation of the activity pane FOLLOWS the mode rather than being a second
+ * setting that can disagree with it: side-by-side in the two centred modes,
+ * stacked in the side panel. `detailPaneSide()` is the only place that mapping
+ * exists, so a host cannot ship a `full` detail with a bottom pane.
+ *
+ * Nothing in this module renders. It is the type surface the lens imports.
+ */
+
+import type { ReactNode } from 'react'
+
+/** §1 — `full` is the default; the host persists the choice. */
+export type DetailMode = 'full' | 'modal' | 'panel'
+
+/** Menu order: the three mode icons read left to right in this order. */
+export const DETAIL_MODES: readonly DetailMode[] = ['full', 'modal', 'panel']
+
+/**
+ * Sentence case, and each names what happens rather than what it is
+ * (interface standards §7). These are accessible names for icon-only
+ * controls, so they have to survive being read on their own.
+ */
+export const DETAIL_MODE_LABELS: Readonly<Record<DetailMode, string>> = {
+  full: 'Open full screen',
+  modal: 'Open centred',
+  panel: 'Open in side panel',
+}
+
+/**
+ * `panel` mode's default width, px — what the mode's `max-inline-size` was
+ * before its leading edge became draggable, so a host with nothing stored
+ * opens exactly where it always did, and `Home` / double-click on the edge
+ * come back to it.
+ *
+ * Exported because the HOST persists the width. A store that hard-codes its
+ * own copy of the default is one release away from disagreeing with the
+ * surface it is driving.
+ */
+export const DETAIL_PANEL_DEFAULT_SIZE = 560
+
+/** Where the activity pane sits relative to the fields. */
+export type DetailPaneSide = 'side' | 'bottom'
+
+/**
+ * §1 — "Orientation follows the mode." `full` and `modal` put activity to the
+ * inline end with a vertical divider; `panel` puts it below with a horizontal
+ * one.
+ */
+export function detailPaneSide(mode: DetailMode): DetailPaneSide {
+  return mode === 'panel' ? 'bottom' : 'side'
+}
+
+/**
+ * Which pane of the split is collapsed, if either.
+ *
+ * A THIRD state rather than two booleans: "both collapsed" is not a layout,
+ * and a pair of flags is one bad write away from expressing it. `fields` and
+ * `aside` name the pane that is HIDDEN, not the one that is showing, because
+ * that is what the restore affordance has to say out loud.
+ *
+ * It is per-ORIENTATION for the same reason the pane's size is: a host that
+ * collapsed the activity pane beside the fields has said nothing about
+ * whether it wants it collapsed below them.
+ */
+export type DetailCollapse = 'none' | 'fields' | 'aside'
+
+/** For a host persisting the choice — the allow-list its store validates against. */
+export const DETAIL_COLLAPSE_VALUES: readonly DetailCollapse[] = [
+  'none',
+  'fields',
+  'aside',
+]
+
+/** The chips above the field list. */
+export type FieldFilter = 'all' | 'filled' | 'empty'
+
+export const FIELD_FILTERS: readonly FieldFilter[] = ['all', 'filled', 'empty']
+
+export const FIELD_FILTER_LABELS: Readonly<Record<FieldFilter, string>> = {
+  all: 'All',
+  filled: 'Filled',
+  empty: 'Empty',
+}
+
+/** One choice in a `FieldRow.Select`. */
+export interface FieldOption<T extends string = string> {
+  readonly value: T
+  readonly label: string
+  /** A Lucide icon or a colour dot. Rendered before the label in both states. */
+  readonly icon?: ReactNode | undefined
+  readonly disabled?: boolean | undefined
+}
+
+/** One person in a `FieldRow.People`. Shaped like the thread's author (D5). */
+export interface FieldPerson {
+  readonly id: string
+  /** Nullable by standing policy — never fabricate a display name. */
+  readonly name: string | null
+  readonly avatarUrl?: string | null | undefined
+  /** Identity colour as DATA. Omitted falls back to Avatar's hash. */
+  readonly tint?: string | null | undefined
+  /** A secondary line in the picker — an email, a role. */
+  readonly hint?: string | undefined
+}
+
+/**
+ * One row of the item's history (§5).
+ *
+ * The pane never derives these from the item on the client — §6 is explicit
+ * that the feed is written server-side in the same transaction as the change,
+ * "which is how the reference's activity tab stays truthful". This type is the
+ * shape that feed arrives in, and `summary` exists for the entries the
+ * standard `‹field› from ‹a› to ‹b›` sentence cannot say.
+ */
+export interface ActivityEntry {
+  readonly id: string
+  /** Epoch milliseconds, like the thread (D16). */
+  readonly at: number
+  readonly actor?: FieldPerson | null | undefined
+  /** User-facing field name — "Status", never `column_id` (§7 copy). */
+  readonly field?: string | undefined
+  readonly from?: string | null | undefined
+  readonly to?: string | null | undefined
+  /** Overrides the derived sentence entirely. */
+  readonly summary?: ReactNode | undefined
+}