@charcuterie/ui 4.6.0 → 4.7.0

package/src/LaneTimeline/LaneTimelineBar.tsx

@@ -0,0 +1,237 @@
+import type { CategoricalIndex } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+
+import {
+  CATEGORICAL_APPEARANCE_CLASS,
+  CATEGORICAL_HOVER_CLASS,
+} from "../categoricalStyles.ts"
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { UnstyledLink } from "../RouterLink/UnstyledLink.tsx"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+import type { TimelineSpan } from "./laneTimelineGeometry.ts"
+
+/**
+ * Who owns the item's activation — nobody, a router, or a handler.
+ *
+ * A union rather than two loose optionals, the same call
+ * `BoardItemTitleLink` makes and for the same reason: `href` renders
+ * an `<a>` and `onSelect` renders a `<button>`, so a bar carrying
+ * both is one of them with the other silently dropped. On screen the
+ * two are identical.
+ */
+type TimelineItemAction =
+  | {
+      /**
+       * Where the bar navigates. Routed through
+       * `RouterLinkProvider` like every other `href` in this
+       * library.
+       */
+      href?: string
+      onSelect?: never
+    }
+  | {
+      href?: never
+      /** For a timeline that opens a panel rather than a route. */
+      onSelect?: () => void
+    }
+
+export type TimelineItem = TimelineSpan & {
+  /**
+   * The bar's colour, when somebody has chosen one. Omitted, it is
+   * the **lane's**, because on this component colour means *which
+   * lane* — an item that picked its own hue out of the ten would
+   * read as belonging somewhere else. Pass this only when the item
+   * genuinely carries its own identity, and then put that identity
+   * in words too.
+   */
+  categorical?: CategoricalIndex
+  key: string
+  /**
+   * The words. A **string**, not a `ReactNode`, for the reason
+   * `BoardLane.label` is one: the same value goes into the bar's
+   * accessible name, the `title` a hovering reader gets, and the
+   * Narrow View's row — none of which can hold a node.
+   */
+  title: string
+} & TimelineItemAction
+
+export type LaneTimelineBarProps = {
+  className?: string
+  item: TimelineItem
+  /** The lane's hue, used when the item picked none. */
+  laneCategorical: CategoricalIndex
+  /** What the bar says out loud: title, then the span in words. */
+  description: string
+  /** Square the leading edge — the item began before this range. */
+  hasEarlierStart: boolean
+  /** Square the trailing edge — it runs past this range. */
+  hasLaterEnd: boolean
+  /**
+   * `bar` is the block on the axis. `row` is the Narrow View's
+   * full-width line, where the same item has room for two lines of
+   * text and no position to carry meaning.
+   */
+  shape: "bar" | "row"
+}
+
+/**
+ * One item, in either of the two shapes this component draws it in.
+ *
+ * ### The name is the whole of the accessibility argument
+ *
+ * A bar means something by **where it sits and how long it is**, and
+ * neither of those reaches a screen reader. Nor does the hue: ten
+ * categorical colours carry *which lane*, and colour alone failing
+ * WCAG 1.4.1 is the least of it — the lane is already a named group,
+ * so the colour is reinforcement rather than information.
+ *
+ * What is genuinely only in the geometry is the **span**, so every
+ * bar carries it as text: `description` is appended to the title in
+ * a `VisuallyHidden` and repeated in the `title` attribute. That
+ * second one is not an accessibility feature, it is for the sighted
+ * reader: a one-day bar is about twenty pixels wide and cannot show
+ * its own name at all.
+ *
+ * A native `title` rather than `Tooltip`, deliberately. A household
+ * week is two hundred bars, and two hundred floating-ui instances to
+ * describe boxes that are already described is a cost with nothing
+ * on the other side of it.
+ *
+ * ### The clipped edge is square, and it is also in words
+ *
+ * An item running out of the visible range loses the radius on that
+ * edge, which is the convention every Gantt chart uses. It is **not**
+ * the only signal:
+ * `description` already says "starts before this range", because a
+ * missing corner is not something anybody perceives without the
+ * unclipped bar beside it to compare against.
+ */
+export const LaneTimelineBar = ({
+  className,
+  description,
+  hasEarlierStart,
+  hasLaterEnd,
+  item,
+  laneCategorical,
+  shape,
+}: LaneTimelineBarProps): ReactNode => {
+  const categorical = item.categorical ?? laneCategorical
+
+  const isInteractive = Boolean(item.href ?? item.onSelect)
+
+  const content = (
+    <>
+      {/*
+       * `truncate` and a `min-w-0`, per the flex-overflow rule: the
+       * title is the flex row's text child and a single unbreakable
+       * word would otherwise become the bar's floor and push the
+       * bar past its own grid column. The whole string is in the
+       * `title` attribute and in the hidden sentence, so nothing is
+       * lost to the ellipsis.
+       */}
+      <span
+        className={toClassName(
+          "min-w-0 flex-1",
+          shape === "bar"
+            ? "truncate"
+            : "wrap-anywhere text-sm",
+        )}
+      >
+        {item.title}
+      </span>
+
+      {/*
+       * Three cases, and which one applies is the reason this is not
+       * one line.
+       *
+       * The Narrow View has room to print the span, so it prints it
+       * — a reader who can see the row should not need a hover to
+       * learn when a thing is on.
+       *
+       * A bar that is a control takes its span through `aria-label`
+       * instead, because a name assembled from two elements is
+       * assembled by the **browser**: chromium joins the two text
+       * runs with a space and firefox with nothing, so
+       * `getByRole("button", { name })` matches on one engine and
+       * not the other. One attribute makes the name exact, and the
+       * visible title still opens it, which is what WCAG 2.5.3 asks.
+       *
+       * A bar that is not a control has no name to write, so the
+       * sentence goes in the content where a screen reader will
+       * still read it.
+       */}
+      {shape === "row" ? (
+        <span className="text-content-muted text-xs">
+          {description}
+        </span>
+      ) : isInteractive ? null : (
+        <VisuallyHidden>{description}</VisuallyHidden>
+      )}
+    </>
+  )
+
+  /**
+   * Only the bar shape gets one, and it carries the **title** as
+   * well as the span. The Narrow View prints both already, and a
+   * tooltip repeating text that is on screen is noise a pointer
+   * user cannot dismiss.
+   */
+  const sentence = `${item.title}, ${description}`
+
+  const hoverText = shape === "bar" ? sentence : undefined
+
+  const shellClassName = toClassName(
+    "w-full min-w-0 border px-1.5 text-xs leading-tight",
+    shape === "bar"
+      ? "flex min-h-5 items-center rounded-sm"
+      : "flex flex-col gap-0.5 rounded-md py-1",
+    CATEGORICAL_APPEARANCE_CLASS[categorical].soft,
+    // A square edge where the item leaves the range. `rounded-*-none`
+    // rather than a different component, so a clipped bar and a whole
+    // one are the same box with one corner rule changed.
+    hasEarlierStart && shape === "bar" && "rounded-s-none",
+    hasLaterEnd && shape === "bar" && "rounded-e-none",
+    isInteractive && "cursor-pointer",
+    isInteractive &&
+      CATEGORICAL_HOVER_CLASS[categorical].soft,
+    isInteractive && FOCUS_RING_CLASS,
+    className,
+  )
+
+  if (item.href) {
+    return (
+      <UnstyledLink
+        aria-label={sentence}
+        className={shellClassName}
+        href={item.href}
+        title={hoverText}
+      >
+        {content}
+      </UnstyledLink>
+    )
+  }
+
+  if (item.onSelect) {
+    return (
+      <button
+        aria-label={sentence}
+        className={toClassName(
+          shellClassName,
+          "text-start",
+        )}
+        onClick={item.onSelect}
+        title={hoverText}
+        type="button"
+      >
+        {content}
+      </button>
+    )
+  }
+
+  return (
+    <span className={shellClassName} title={hoverText}>
+      {content}
+    </span>
+  )
+}

package/src/LaneTimeline/LaneTimelineLane.tsx

@@ -0,0 +1,332 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { CategoricalIndex } from "@charcuterie/tokens"
+import {
+  CATEGORICAL_INDEX_COUNT,
+  CATEGORICAL_SEQUENCE,
+} from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+
+import { Badge } from "../Badge/Badge.tsx"
+import { CATEGORICAL_SOLID_FILL_CLASS } from "../categoricalStyles.ts"
+import { TextLink } from "../TextLink/TextLink.tsx"
+import { toClassName } from "../toClassName.ts"
+import type { TimelineItem } from "./LaneTimelineBar.tsx"
+import { LaneTimelineBar } from "./LaneTimelineBar.tsx"
+import type { TimelineAxis } from "./laneTimelineGeometry.ts"
+import {
+  describeTimelineSpan,
+  toPackedLane,
+} from "./laneTimelineGeometry.ts"
+
+export type TimelineLane = {
+  /**
+   * Which of the ten hues this lane wears, overriding the one its
+   * **position** would have given it.
+   *
+   * Reach for it when a lane's colour means something outside this
+   * set — a person who is the same colour on every screen of the
+   * app, a pair that must not drift apart when a third lane is
+   * inserted between them. An overridden lane keeps its hue and the
+   * rest go on walking `CATEGORICAL_SEQUENCE` from their own
+   * positions, so naming one does not force naming all of them.
+   */
+  categorical?: CategoricalIndex
+  /**
+   * Where the lane's heading navigates — the "show me only this
+   * lane" route. A link **inside** the heading, never a heading
+   * replaced by a link, exactly as `BoardLane.href` is: the heading
+   * keeps its level, its id, and its job of naming the group.
+   */
+  href?: string
+  items: readonly TimelineItem[]
+  key: string
+  /**
+   * The lane's name. A **string**: it names the group, and a group
+   * with a `ReactNode` name is a group with no name.
+   */
+  label: string
+}
+
+export type LaneTimelineLaneProps = {
+  axis: TimelineAxis
+  /** The CSS track list, built once by the parent and shared. */
+  columnTemplate: string
+  headingLevel: 2 | 3 | 4 | 5
+  lane: TimelineLane
+  locale?: string
+  maxRowCount: number
+  /** Where this lane sits in the set, for its default hue. */
+  position: number
+  /**
+   * `axis` is the bars across the date axis. `list` is the Narrow
+   * View, where there is no axis and each item is a line of text.
+   */
+  shape: "axis" | "list"
+  /** Draw a separator every this many columns. */
+  tickStep: number
+}
+
+/**
+ * One lane: its name, how much it is carrying, and either a track of
+ * bars or a list of lines.
+ *
+ * ### A lane is a `group`, not a landmark
+ *
+ * The same call `BoardLaneList` makes, and it was a real axe failure
+ * there before it changed. A named `<section>` is a `region`, so a
+ * timeline of eight lanes would put eight landmarks on a page that
+ * has one job, and two timelines on one page would put two landmarks
+ * with the same name in the document — which is `landmark-unique`.
+ * It is a `<div role="group">` rather than a `<section role="group">`
+ * because axe matches `section[aria-labelledby]` on the **element**
+ * and audits it as a landmark even after the role is overridden.
+ *
+ * ### The count is what the lane carries IN THIS RANGE
+ *
+ * Not `items.length`. A consumer hands over a month and shows a
+ * week; counting the array would print "31" beside a lane with two
+ * bars on it. `inRangeCount` includes anything the row limit hid, so
+ * a lane cannot look lighter by being more loaded.
+ *
+ * ### A lane gets TALLER when it is busy, and that is the design
+ *
+ * Overlapping items stack into rows (`toPackedLane`), so a lane
+ * carrying three things at once is three bars tall while one
+ * carrying them in sequence is one. Load asymmetry then reads as
+ * height from across the room, before anybody counts anything —
+ * which is the whole reason this component exists rather than a
+ * month grid, where every cell is the same size no matter what is
+ * in it.
+ */
+export const LaneTimelineLane = ({
+  axis,
+  columnTemplate,
+  headingLevel,
+  lane,
+  locale,
+  maxRowCount,
+  position,
+  shape,
+  tickStep,
+}: LaneTimelineLaneProps): ReactNode => {
+  const headingId = useUniqueId()
+
+  /*
+   * Position, not `getCategoricalIndex(lane.key)`, and `ActionTiles`
+   * made the same call for the same reason. That helper hashes, so a
+   * row keeps its colour across a list nobody controls the order of
+   * — right for Docket's labels, wrong here: a hash of two lane keys
+   * can collide, and two lanes in one hue defeats the only thing the
+   * colour is for. Measured on this component's own fixtures, where
+   * `wren` and `juno` both hashed to Pink and the screenshot showed
+   * one person's week twice.
+   *
+   * `CATEGORICAL_SEQUENCE` rather than the ring: the ring is
+   * hue-ordered for the swatch picker's sake, so walking it in order
+   * hands a two-lane set the two hardest colours in the family to
+   * tell apart.
+   */
+  const categorical =
+    lane.categorical ??
+    CATEGORICAL_SEQUENCE[position % CATEGORICAL_INDEX_COUNT]
+
+  const packed = toPackedLane({
+    axis,
+    items: lane.items,
+    /*
+     * The Narrow View has no row limit, because there are no rows:
+     * it is a vertical list, so the thing the limit protects
+     * against — a lane growing past the height of the screen while
+     * every other lane stays one bar tall — cannot happen. Hiding
+     * items there would lose them for the reader who has the least
+     * room to spare.
+     */
+    maxRowCount:
+      shape === "list" ? lane.items.length : maxRowCount,
+  })
+
+  const Heading = `h${headingLevel}` as const
+
+  const header = (
+    <header className="flex min-w-0 items-center gap-2">
+      {/*
+       * The lane's hue, beside its name, so the reader learns which
+       * colour is which lane once instead of per bar. Decoration
+       * only — the heading is the thing that says whose lane it is,
+       * which is what keeps the colour from being the sole carrier
+       * of anything.
+       */}
+      <span
+        aria-hidden="true"
+        className={toClassName(
+          "h-4 w-1 shrink-0 rounded-full",
+          CATEGORICAL_SOLID_FILL_CLASS[categorical],
+        )}
+      />
+
+      <Heading
+        className="min-w-0 truncate font-semibold text-content-primary text-sm"
+        id={headingId}
+        title={lane.label}
+      >
+        {lane.href ? (
+          <TextLink
+            appearance="standalone"
+            className="font-semibold text-inherit"
+            href={lane.href}
+          >
+            {lane.label}
+          </TextLink>
+        ) : (
+          lane.label
+        )}
+      </Heading>
+
+      <Badge appearance="soft" intent="neutral" size="sm">
+        {String(packed.inRangeCount)}
+      </Badge>
+    </header>
+  )
+
+  if (shape === "list") {
+    const items = packed.rows
+      .flat()
+      .sort(
+        (first, second) =>
+          first.placement.columnStart -
+          second.placement.columnStart,
+      )
+
+    return (
+      // biome-ignore lint/a11y/useSemanticElements: the semantic element for `group` is `<fieldset>`, which drags `<legend>`, a border and form-reset behaviour onto a lane of dates. Same call `BoardLaneList`, `Menu`'s group and `AccordionSection` already made.
+      <div
+        aria-labelledby={headingId}
+        className="flex flex-col gap-1.5 border-border-subtle border-t py-2"
+        role="group"
+      >
+        {header}
+
+        {items.length === 0 ? (
+          <p className="text-content-muted text-xs">
+            Nothing in this range.
+          </p>
+        ) : (
+          <ul className="flex flex-col gap-1">
+            {items.map(({ item, placement }) => (
+              <li className="min-w-0" key={item.key}>
+                <LaneTimelineBar
+                  laneCategorical={categorical}
+                  description={describeTimelineSpan({
+                    locale,
+                    placement,
+                    span: item,
+                  })}
+                  hasEarlierStart={
+                    placement.hasEarlierStart
+                  }
+                  hasLaterEnd={placement.hasLaterEnd}
+                  item={item}
+                  shape="row"
+                />
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: see the Narrow View branch above — `<fieldset>` is the only semantic element for `group`, and it is a form-control grouping.
+    <div
+      aria-labelledby={headingId}
+      className="grid grid-cols-[12rem_minmax(0,1fr)] items-start gap-x-3 border-border-subtle border-t py-1.5"
+      role="group"
+    >
+      {header}
+
+      <div className="relative min-h-6">
+        {/*
+         * The separators, drawn behind the bars rather than between
+         * them. A real element between two columns takes up space,
+         * which moves the columns it was measuring itself against —
+         * the same feedback loop `BoardLaneList`'s drop indicator
+         * avoids by being absolute.
+         */}
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 grid"
+          style={{ gridTemplateColumns: columnTemplate }}
+        >
+          {/*
+           * Keyed by the DAY, not by the loop index — the day number
+           * is what the cell is, and a key that is an index is a key
+           * that moves when the range does.
+           */}
+          {Array.from(
+            { length: axis.columnCount },
+            (_unused, index) => axis.startDay + index,
+          ).map((dayNumber) => (
+            <span
+              className={toClassName(
+                // Never on the leading edge: a line down the start of
+                // the track reads as a frame the track does not have.
+                dayNumber > axis.startDay &&
+                  (dayNumber - axis.startDay) % tickStep ===
+                    0 &&
+                  "border-border-subtle border-s",
+              )}
+              key={dayNumber}
+            />
+          ))}
+        </div>
+
+        <ul
+          className="relative grid gap-1"
+          style={{ gridTemplateColumns: columnTemplate }}
+        >
+          {packed.rows.flatMap((row, rowIndex) =>
+            row.map(({ item, placement }) => (
+              <li
+                className="min-w-0"
+                key={item.key}
+                style={{
+                  /*
+                   * `span`, never a start/end pair. An end line is
+                   * one past the last column the bar covers, so
+                   * writing it is the single easiest place to lose
+                   * a day — and it is invisible, because a bar one
+                   * day short still looks like a bar.
+                   */
+                  gridColumn: `${placement.columnStart} / span ${placement.columnSpan}`,
+                  gridRow: rowIndex + 1,
+                }}
+              >
+                <LaneTimelineBar
+                  laneCategorical={categorical}
+                  description={describeTimelineSpan({
+                    locale,
+                    placement,
+                    span: item,
+                  })}
+                  hasEarlierStart={
+                    placement.hasEarlierStart
+                  }
+                  hasLaterEnd={placement.hasLaterEnd}
+                  item={item}
+                  shape="bar"
+                />
+              </li>
+            )),
+          )}
+        </ul>
+
+        {packed.hiddenCount > 0 ? (
+          <p className="pt-1 text-content-muted text-xs">
+            {`+ ${packed.hiddenCount} more overlapping in ${lane.label}`}
+          </p>
+        ) : null}
+      </div>
+    </div>
+  )
+}