@lovett/ui 0.0.11 → 0.2.0

package/src/task-card.tsx

@@ -0,0 +1,610 @@
+/**
+ * TaskCard — the board card.
+ *
+ * `docs/design-briefs/tasks-board-design-language.md` §2 + §3, as corrected by
+ * `tasks-board-interface-standards.md` §1 (radius), §2 (surface) and §3
+ * (grouping). ADR-146 D13.
+ *
+ * "Dynamic and more informative" concretely means: **every row is optional
+ * except the title.** The card grows to fit what the item actually has and
+ * reserves nothing for what it does not. It is therefore not a template with
+ * placeholders — an item with no note, no media and no dates renders as three
+ * short lines, and one with everything renders tall.
+ *
+ * ## The five groups (interface-standards §3)
+ *
+ * Grouped with SPACE, not lines — `--space-1` within a group, `--space-3`
+ * between groups, and no dividers inside a card:
+ *
+ *   1. tags + overflow menu
+ *   2. eyebrow · title · note
+ *   3. media
+ *   4. embedded panel, then the ledger
+ *   5. date chip · avatars · counts
+ *
+ * ## The radius chain
+ *
+ * Column `--radius-2xl` (24) − `--space-2` (8) = card `--radius-lg` (16);
+ * card 16 − media inset `--space-2` (8) = media `--radius-sm` (8). Text rows
+ * pad `--space-3` and are outside the chain because text has no corner. Chips
+ * sit flat on the card, so they are `--radius-sm` and outside it too.
+ *
+ * ## Why the card is not a `<button>`, and why it is not a drag handle either
+ *
+ * It holds a menu, a vote control and clickable ledger segments; a button
+ * cannot legally contain those. The TITLE is the actionable element instead,
+ * so the card is fully keyboard-operable without nesting interactive content,
+ * and the article carries a POINTER click on top of it — one target for the
+ * mouse, one real control for the keyboard, one `onOpen`.
+ *
+ * The same reasoning is why the card is not the drag handle. The article gets
+ * `setNodeRef` and `style` — it is what dnd-kit measures and transforms — and
+ * NOTHING else. The activators (`onPointerDown`, `onKeyDown`) and the aria
+ * wiring both ride the visible grip. Spreading the listeners on the article
+ * made every pointer-down anywhere on the card the start of a drag, which is
+ * why the card read `cursor: grab` and could not be clicked.
+ *
+ * The hue comes from an ancestor's `.hue hue-<key>` pair (see `hue.ts`).
+ */
+
+import { useState, type ComponentPropsWithoutRef } from 'react'
+import type {
+  CSSProperties,
+  HTMLAttributes,
+  MouseEvent as ReactMouseEvent,
+  ReactNode,
+} from 'react'
+import { Flag, GripVertical, ImageOff } from 'lucide-react'
+import { cn } from './lib/utils'
+import { hueClass, hueForKey } from './hue'
+
+type CardHeadingLevel = 2 | 3 | 4 | 5
+
+function CardTitleHeading({
+  level,
+  ...rest
+}: { level: CardHeadingLevel } & ComponentPropsWithoutRef<'h4'>) {
+  const Tag = `h${level}` as const
+  return <Tag {...rest} />
+}
+
+export interface TaskCardMedia {
+  /** Resolved by the caller — the primitive never builds a URL. */
+  src: string
+  alt: string
+}
+
+export interface TaskCardCount {
+  /** A Lucide icon at `strokeWidth={1.5}` — it sits beside 400-weight text. */
+  icon: ReactNode
+  value: number
+  /** Sentence-case, for the accessible name: "comments", "attachments". */
+  label: string
+}
+
+export interface TaskCardAvatar {
+  id: string
+  name: string
+}
+
+export interface TaskCardDate {
+  /** Operator language — "Due", "Target launch", "Launched". Never a schema word. */
+  label: string
+  value: string
+  /** A terminal column reads in `--success-ink` rather than the neutral. */
+  terminal?: boolean
+}
+
+export interface TaskCardDragProps {
+  /** The measured/transformed node. Carries no handlers — see the file header. */
+  setNodeRef?: ((node: HTMLElement | null) => void) | undefined
+  /**
+   * The drag activator, pointer AND keyboard, plus dnd-kit's aria wiring.
+   * Rendered as a visible grip — in group 1 when that row exists for its own
+   * reasons, otherwise floated into the title row — so a drag starts from one
+   * named, focusable control and the card itself stays clickable.
+   */
+  activatorProps?: HTMLAttributes<HTMLElement> | undefined
+  /** dnd-kit's handle ref, so a finished keyboard drag restores focus to the grip. */
+  activatorRef?: ((node: HTMLElement | null) => void) | undefined
+  style?: CSSProperties | undefined
+  isDragging?: boolean | undefined
+}
+
+export interface TaskCardProps {
+  /**
+   * Document-outline level for the card title. Default 4.
+   * Should sit one below the column heading so the outline has no skip.
+   */
+  headingLevel?: CardHeadingLevel
+  title: string
+  eyebrow?: string
+  note?: string
+  tags?: readonly string[]
+  /** Tags shown before a `+N` chip takes over. */
+  maxTags?: number
+  /**
+   * Consumer-rendered chips alongside the tags — Community's LensChip, a
+   * priority pill. Group 1 is "what this card is labelled", and a caller with
+   * its own chip vocabulary should not have to fork the card to use it.
+   */
+  chips?: ReactNode
+  media?: readonly TaskCardMedia[]
+  /** Declared up front so the card cannot reflow as an image loads. */
+  mediaAspectRatio?: string
+  /** An embedded sub-panel — option tiles, a mini widget. */
+  panel?: ReactNode
+  /** Typically a <ProgressLedger>. Any node; the card owns only its slot. */
+  ledger?: ReactNode
+  date?: TaskCardDate
+  avatars?: readonly TaskCardAvatar[]
+  maxAvatars?: number
+  counts?: readonly TaskCardCount[]
+  /**
+   * Rendered after the counts at the end of the footer. This is the seam that
+   * makes the board primitive generic over its CARD BODY rather than over its
+   * data (ADR-146 D2) — Community passes its vote control here, beside the
+   * comment count, and neither consumer forks the card.
+   */
+  footerEnd?: ReactNode
+  /** Overflow menu trigger. Supply an `aria-label`; the card cannot know it. */
+  menu?: ReactNode
+  /**
+   * Opens the item. Makes the title an actionable button AND the whole card a
+   * pointer target. Omit for a static card — a card with no `onOpen` gets no
+   * pointer cursor and no hover lift, so it never claims an affordance it
+   * cannot honour.
+   */
+  onOpen?: () => void
+  /** Archived / shipped treatment — dimmed, never hidden. */
+  dimmed?: boolean
+  drag?: TaskCardDragProps
+  /** Rendering inside a DragOverlay: no hover lift, a heavier shadow. */
+  isOverlay?: boolean
+  className?: string
+}
+
+export function TaskCard({
+  headingLevel = 4,
+  title,
+  eyebrow,
+  note,
+  tags,
+  maxTags = 3,
+  chips,
+  media,
+  mediaAspectRatio = '16 / 10',
+  panel,
+  ledger,
+  date,
+  avatars,
+  maxAvatars = 4,
+  counts,
+  footerEnd,
+  menu,
+  onOpen,
+  dimmed = false,
+  drag,
+  isOverlay = false,
+  className,
+}: TaskCardProps) {
+  const shownTags = tags?.slice(0, maxTags) ?? []
+  const hiddenTags = (tags?.length ?? 0) - shownTags.length
+  const hasFooter = Boolean(date || avatars?.length || counts?.length || footerEnd)
+  const grip = drag?.activatorProps
+  // Group 1 is "what this card is LABELLED". A grip is not a label, so a card
+  // with no tags, no chips and no menu does not get a group for it — the grip
+  // floats into the title row instead. Rendering an otherwise-empty 24px row
+  // on every card was pure overhead on the Tasks board, where no card has any
+  // of the three.
+  const hasTopRow = shownTags.length > 0 || Boolean(chips) || Boolean(menu)
+  const gripInTitleRow = Boolean(grip) && !hasTopRow
+  const interactive = Boolean(onOpen) && !isOverlay
+
+  /**
+   * The card's POINTER target.
+   *
+   * The keyboard path is the title `<button>` below — one real control, with
+   * the title as its accessible name — so this handler deliberately adds no
+   * `tabIndex` and no `role` to the article. A `role="button"` here would take
+   * presentational children and erase the grip, the overflow menu and the
+   * footer's own controls from assistive tech.
+   *
+   * Clicks that started on a control inside the card belong to that control:
+   * the grip, the menu, a ledger segment, a vote button, a link — and the
+   * title button, which calls `onOpen` itself and must not call it twice.
+   */
+  const handleCardClick = (event: ReactMouseEvent<HTMLElement>) => {
+    if (!onOpen) return
+    const origin = event.target
+    if (
+      origin instanceof Element &&
+      origin.closest('button, a, input, select, textarea, [role="button"], [role="menuitem"]')
+    ) {
+      return
+    }
+    onOpen()
+  }
+
+  return (
+    <article
+      ref={drag?.setNodeRef}
+      data-interactive={interactive ? 'true' : undefined}
+      data-overlay={isOverlay ? 'true' : undefined}
+      {...(interactive ? { onClick: handleCardClick } : {})}
+      className={cn('ds-board-card flex flex-col', className)}
+      style={{
+        background: 'rgb(var(--surface-card))',
+        // Structure, not depth: near-invisible, but in dark mode it is the
+        // only thing separating the card from the column behind it.
+        border: '1px solid rgb(var(--border))',
+        borderRadius: 'var(--radius-lg)',
+        // The SHADOW is not here. It was, and an inline box-shadow outranks
+        // every stylesheet rule, so `.ds-board-card:hover`'s --shadow-sm ->
+        // --shadow-md step had never once applied: the 1px lift was the whole
+        // of the hover feedback and the focus step could not work at all. The
+        // resting and overlay shadows now live in styles.css beside the states
+        // that step them.
+        paddingBlock: 'var(--space-3)',
+        gap: 'var(--space-3)',
+        opacity: dimmed ? 0.6 : 1,
+        ...drag?.style,
+      }}
+    >
+      {/* GROUP 1 — drag grip, tags, overflow menu. */}
+      {hasTopRow ? (
+        <div
+          className="flex items-center flex-wrap"
+          style={{ gap: 'var(--space-1)', paddingInline: 'var(--space-3)' }}
+        >
+          {grip ? (
+            <CardGrip grip={grip} gripRef={drag?.activatorRef} title={title} />
+          ) : null}
+          {shownTags.map((tag) => (
+            <TagChip key={tag}>#{tag.toLowerCase()}</TagChip>
+          ))}
+          {hiddenTags > 0 ? <TagChip>+{hiddenTags}</TagChip> : null}
+          {chips}
+          {menu ? <span className="ms-auto shrink-0">{menu}</span> : null}
+        </div>
+      ) : null}
+
+      {/* GROUP 2 — eyebrow, title, note. When group 1 has nothing of its own
+          to hold, the drag grip rides here rather than owning a row. */}
+      <div
+        className="flex items-start"
+        style={{ gap: 'var(--space-1)', paddingInline: 'var(--space-3)' }}
+      >
+        {gripInTitleRow && grip ? (
+          <CardGrip grip={grip} gripRef={drag?.activatorRef} title={title} inTitleRow />
+        ) : null}
+        <div className="flex flex-col min-w-0 flex-1" style={{ gap: 'var(--space-1)' }}>
+          {eyebrow ? (
+            <span
+              className="text-[11px] leading-[1.3]"
+              style={{ color: 'rgb(var(--text-tertiary))' }}
+            >
+              {eyebrow}
+            </span>
+          ) : null}
+          {/* `h4`, one level under the column's `h3` — the card is nested inside
+              the column, and the heading tree should say so. When the card is
+              openable the button lives INSIDE the heading rather than replacing
+              it, so the title is still reachable by heading navigation. */}
+          {/* No line clamp. A clamped title with no tooltip and no drawer is a
+              title the reader cannot finish — and the card is variable-height by
+              design, so it has somewhere to put the second and third line. */}
+          <CardTitleHeading
+            level={headingLevel}
+            className="ds-board-card-title text-[15px] font-semibold leading-[1.3]"
+            style={{ margin: 0, color: 'rgb(var(--foreground))' }}
+          >
+            {onOpen ? (
+              <button
+                type="button"
+                onClick={onOpen}
+                className="text-start rounded-[var(--radius-sm)] focus-visible:[box-shadow:var(--ring-focus)] focus-visible:outline-none"
+                style={{
+                  background: 'transparent',
+                  border: 'none',
+                  padding: 0,
+                  font: 'inherit',
+                  color: 'inherit',
+                }}
+              >
+                {title}
+              </button>
+            ) : (
+              title
+            )}
+          </CardTitleHeading>
+          {note ? (
+            <p
+              className="text-[12.5px] leading-[1.45] line-clamp-2"
+              style={{ margin: 0, color: 'rgb(var(--text-tertiary))' }}
+            >
+              {note}
+            </p>
+          ) : null}
+        </div>
+      </div>
+
+      {/* GROUP 3 — media. */}
+      {media && media[0] ? (
+        <div style={{ paddingInline: 'var(--space-2)' }}>
+          <CardMedia
+            media={media[0]}
+            extra={media.length - 1}
+            aspectRatio={mediaAspectRatio}
+          />
+        </div>
+      ) : null}
+
+      {/* GROUP 4 — embedded panel, then the ledger. */}
+      {panel ? <div style={{ paddingInline: 'var(--space-2)' }}>{panel}</div> : null}
+      {ledger ? <div style={{ paddingInline: 'var(--space-3)' }}>{ledger}</div> : null}
+
+      {/* GROUP 5 — date chip, avatars, counts. Wraps rather than clips. */}
+      {hasFooter ? (
+        <div
+          className="ds-board-card-footer flex items-center flex-wrap"
+          style={{ gap: 'var(--space-2)', paddingInline: 'var(--space-3)' }}
+        >
+          {date ? <DateChip date={date} /> : null}
+          {avatars && avatars.length > 0 ? (
+            <AvatarStack avatars={avatars} max={maxAvatars} />
+          ) : null}
+          <span className="ms-auto flex items-center" style={{ gap: 'var(--space-2)' }}>
+            {counts?.map((count) => <CountChip key={count.label} count={count} />)}
+            {footerEnd}
+          </span>
+        </div>
+      ) : null}
+    </article>
+  )
+}
+
+/**
+ * THE drag activator — pointer and keyboard both — rendered as a visible grip.
+ *
+ * `grip` carries dnd-kit's listeners AND its attributes, so this is the one
+ * element a drag can start from and the one element assistive tech is told
+ * about. `aria-label` comes after the spread deliberately: dnd-kit's
+ * `aria-roledescription` describes the gesture, the label names the card.
+ *
+ * Lives in group 1 when that row exists for its own reasons, and floats into
+ * the title row when it does not — so it never conjures a row of its own.
+ */
+function CardGrip({
+  grip,
+  gripRef,
+  title,
+  inTitleRow = false,
+}: {
+  grip: HTMLAttributes<HTMLElement>
+  gripRef?: ((node: HTMLElement | null) => void) | undefined
+  title: string
+  inTitleRow?: boolean
+}) {
+  return (
+    <button
+      type="button"
+      ref={gripRef}
+      {...grip}
+      aria-label={`Reorder ${title}`}
+      className="ds-board-card-grip inline-grid place-items-center shrink-0 cursor-grab active:cursor-grabbing focus-visible:[box-shadow:var(--ring-focus)] focus-visible:outline-none"
+      style={{
+        inlineSize: '24px',
+        blockSize: '24px',
+        marginInlineStart: 'calc(var(--space-1) * -1)',
+        // Optical, not mathematical: a 24px box beside a 19.5px first line
+        // sits low unless it is nudged up by the difference's half.
+        ...(inTitleRow ? { marginBlockStart: '-2px' } : {}),
+        borderRadius: 'var(--radius-sm)',
+        background: 'transparent',
+        border: 'none',
+        color: 'rgb(var(--text-muted))',
+        touchAction: 'none',
+      }}
+    >
+      <GripVertical size={14} strokeWidth={1.5} aria-hidden="true" />
+    </button>
+  )
+}
+
+/** Lens-local label. Inset well on the card, never a filled accent pill. */
+function TagChip({ children }: { children: ReactNode }) {
+  return (
+    <span
+      className="inline-flex items-center text-[11px] font-medium leading-none"
+      style={{
+        paddingInline: 'var(--space-2)',
+        paddingBlock: '4px',
+        borderRadius: 'var(--radius-sm)',
+        background: 'rgb(var(--surface-inset))',
+        color: 'rgb(var(--muted-foreground))',
+      }}
+    >
+      {children}
+    </span>
+  )
+}
+
+function DateChip({ date }: { date: TaskCardDate }) {
+  return (
+    <span
+      className="inline-flex items-center text-[11.5px] font-medium leading-none tabular-nums"
+      style={{
+        gap: '5px',
+        paddingInline: 'var(--space-2)',
+        paddingBlock: '5px',
+        borderRadius: 'var(--radius-sm)',
+        border: '1px solid rgb(var(--border))',
+        color: date.terminal ? 'rgb(var(--success-ink))' : 'rgb(var(--text-tertiary))',
+      }}
+    >
+      {/* strokeWidth 1.5 — this sits beside 400-weight meta text. */}
+      <FlagGlyph />
+      <span className="sr-only">{date.label}: </span>
+      {date.value}
+    </span>
+  )
+}
+
+/**
+ * The flag is imported rather than inlined so the icon rule holds even inside
+ * `packages/ui`, where an inline `<svg>` would be legal.
+ */
+function FlagGlyph() {
+  return <Flag size={12} strokeWidth={1.5} aria-hidden="true" />
+}
+
+function CountChip({ count }: { count: TaskCardCount }) {
+  return (
+    <span
+      className="inline-flex items-center text-[11.5px] leading-none"
+      style={{
+        gap: '5px',
+        // 24px minimum hit-area height even though it is not a control, so a
+        // count sitting beside the overflow menu does not shrink the row.
+        minHeight: '24px',
+        paddingInline: 'var(--space-2)',
+        borderRadius: 'var(--radius-sm)',
+        // Bordered, not filled — a count is metadata, not an action.
+        border: '1px solid rgb(var(--border))',
+        color: 'rgb(var(--text-tertiary))',
+      }}
+    >
+      {count.icon}
+      {/* min-width slot + tabular-nums: a new comment must not resize the card. */}
+      <span className="tabular-nums" style={{ minInlineSize: '2ch', textAlign: 'end' }}>
+        {count.value}
+      </span>
+      <span className="sr-only">{count.label}</span>
+    </span>
+  )
+}
+
+function AvatarStack({
+  avatars,
+  max,
+}: {
+  avatars: readonly TaskCardAvatar[]
+  max: number
+}) {
+  const shown = avatars.slice(0, max)
+  const extra = avatars.length - shown.length
+  return (
+    <span className="inline-flex items-center" style={{ gap: '2px' }}>
+      {shown.map((person) => (
+        <span
+          key={person.id}
+          // Its own hue, so two people on a card are distinguishable. Stable
+          // per name, because an avatar that changes colour reads as someone
+          // else. Opaque by construction — it is a tint-ladder rung.
+          className={cn(hueClass(hueForKey(person.id || person.name)), 'inline-grid place-items-center text-[9.5px] font-bold')}
+          style={{
+            width: '22px',
+            height: '22px',
+            borderRadius: 'var(--radius-full)',
+            background: 'var(--tint-group)',
+            border: '1px solid var(--tint-edge)',
+            // The INK rung, not the raw hue: `--h` on `--tint-group` measures
+            // 2.77:1 (slate) / 3.13:1 (blue) in LIGHT mode at 9.5px/700.
+            // `--tint-ink` mixes toward --foreground, so it darkens in light
+            // and lightens in dark instead of being tuned for one theme.
+            color: 'var(--tint-ink)',
+          }}
+          title={person.name}
+        >
+          {initials(person.name)}
+          <span className="sr-only">{person.name}</span>
+        </span>
+      ))}
+      {extra > 0 ? (
+        <span
+          className="inline-grid place-items-center text-[10px] font-semibold tabular-nums"
+          style={{
+            width: '22px',
+            height: '22px',
+            borderRadius: 'var(--radius-full)',
+            background: 'rgb(var(--surface-inset))',
+            color: 'rgb(var(--text-tertiary))',
+          }}
+        >
+          +{extra}
+        </span>
+      ) : null}
+    </span>
+  )
+}
+
+function CardMedia({
+  media,
+  extra,
+  aspectRatio,
+}: {
+  media: TaskCardMedia
+  extra: number
+  aspectRatio: string
+}) {
+  const [failed, setFailed] = useState(false)
+  return (
+    <div
+      className="relative w-full overflow-hidden"
+      style={{
+        aspectRatio,
+        borderRadius: 'var(--radius-sm)',
+        // Placeholder behind the image, so the box is never empty or collapsed.
+        background: 'rgb(var(--surface-inset))',
+        // Pure-neutral hairline: a tinted border picks up the surface under it
+        // and reads as dirt on the image edge (interface-standards §2).
+        border: '1px solid rgb(var(--border))',
+      }}
+    >
+      {failed ? (
+        <span
+          className="absolute inset-0 grid place-items-center"
+          style={{ color: 'rgb(var(--text-muted))' }}
+        >
+          <ImageOff size={18} strokeWidth={1.5} aria-hidden="true" />
+          <span className="sr-only">Image unavailable: {media.alt}</span>
+        </span>
+      ) : (
+        <img
+          src={media.src}
+          alt={media.alt}
+          loading="lazy"
+          decoding="async"
+          onError={() => setFailed(true)}
+          className="absolute inset-0 h-full w-full"
+          style={{ objectFit: 'cover' }}
+        />
+      )}
+      {extra > 0 ? (
+        <span
+          className="absolute text-[11px] font-semibold tabular-nums"
+          style={{
+            insetBlockEnd: 'var(--space-2)',
+            insetInlineEnd: 'var(--space-2)',
+            paddingInline: '7px',
+            paddingBlock: '3px',
+            borderRadius: 'var(--radius-sm)',
+            background: 'rgb(var(--media-scrim-label))',
+            color: 'rgb(var(--media-on-scrim))',
+          }}
+        >
+          +{extra}
+        </span>
+      ) : null}
+    </div>
+  )
+}
+
+function initials(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return '?'
+  const first = parts[0]?.[0] ?? ''
+  const last = parts.length > 1 ? (parts[parts.length - 1]?.[0] ?? '') : ''
+  return (first + last).toUpperCase()
+}