@charcuterie/ui 4.6.0 → 4.7.0

package/src/LaneTimeline/laneTimelineGeometry.ts

@@ -0,0 +1,476 @@
+/**
+ * Where a bar sits on the axis, and how many bars a lane stacks —
+ * the whole of the arithmetic, with no React and no DOM in it.
+ *
+ * It is its own module for the reason `boardMove.ts` is: every
+ * defect a timeline actually ships is an off-by-one, and an
+ * off-by-one is invisible in a screenshot. A bar one column to the
+ * left of where it belongs looks exactly like a bar. So the
+ * arithmetic is unit-tested against fixtures in Node, and the
+ * component below it only paints what comes out.
+ *
+ * ### Every position is a DAY NUMBER, never a `Date`
+ *
+ * Reached through `plainDate.ts` rather than reimplemented, because
+ * that file already argues the case at length and re-arguing it in a
+ * second place is how two answers appear. A timeline is the exact
+ * shape that bug hides in: "the roofers are here Monday to Friday"
+ * is true in every zone, and a `new Date("2026-04-06")` read at
+ * 23:30 west of Greenwich puts the bar on Sunday. The whole file is
+ * integer maths on days since 1970-01-01.
+ *
+ * ### The END IS INCLUSIVE, everywhere in here
+ *
+ * See `LaneTimelineItem.end` for the argument. The one thing to
+ * carry into this file: `columnSpan` is `end - start + 1`, so a
+ * single-day item is a span of **1**, not 0.
+ */
+
+import type { PlainDate } from "../DatePicker/plainDate.ts"
+import {
+  formatPlainDate,
+  getDayNumber,
+  parseIsoDate,
+} from "../DatePicker/plainDate.ts"
+
+/**
+ * A closed interval of calendar days, `YYYY-MM-DD` at both ends.
+ * Both the visible range and an item's own extent are this shape,
+ * deliberately — the component asks the same question of both.
+ */
+export type TimelineSpan = {
+  /** The last day covered. **Inclusive.** */
+  end: string
+  /** The first day covered. */
+  start: string
+}
+
+/**
+ * The visible range, parsed once and reused for every item.
+ *
+ * Parsed once because a household week with eight lanes and two
+ * hundred items would otherwise re-parse the same two strings four
+ * hundred times — but mostly because a range that cannot be parsed
+ * has to fail in **one** place, rather than resolving to a
+ * different silent fallback inside each item's placement.
+ */
+export type TimelineAxis = {
+  /** Day columns in the visible range. Never below 1. */
+  columnCount: number
+  endDay: number
+  startDay: number
+}
+
+export type BarPlacement = {
+  /** 1-based CSS grid column the bar starts in. */
+  columnStart: number
+  /**
+   * Day columns the bar covers **after clipping**, never below 1.
+   *
+   * A CSS `grid-column: 4 / span 0` is not an error and not a
+   * zero-width box — the browser treats a span of 0 as 1 in some
+   * engines and as invalid-and-ignored in others, so the bar lands
+   * either in the right place or at the end of the row with nothing
+   * to say which. The clamp lives here so no caller has to know
+   * that.
+   */
+  columnSpan: number
+  /**
+   * The days the item covers in **total**, clipping ignored — so a
+   * two-week thing clipped to the visible Tuesday still says
+   * fourteen days out loud. The number a person is owed is the
+   * item's own length, not the part of it that fits on screen.
+   */
+  dayCount: number
+  /** The item begins before the first visible day. */
+  hasEarlierStart: boolean
+  /** The item is still running after the last visible day. */
+  hasLaterEnd: boolean
+}
+
+export type PlacedTimelineItem<Item> = {
+  item: Item
+  placement: BarPlacement
+}
+
+export type PackedLane<Item> = {
+  /**
+   * Items that were placed and then did not fit inside
+   * `maxRowCount` stacked rows. Counted rather than drawn, and the
+   * lane says the number out loud — the same honest-overflow rule
+   * `Board`'s `+ n more` follows, for the same reason: a lane that
+   * silently drops the ninth overlapping thing is a lane that lies
+   * about how loaded it is, which is the one question this
+   * component exists to answer.
+   */
+  hiddenCount: number
+  /**
+   * Items with any part of themselves inside the visible range,
+   * drawn or not.
+   *
+   * The number the lane's badge shows, and it is **not**
+   * `items.length`: a consumer hands over a month and looks at a
+   * week, so counting the whole array would put "31" beside a lane
+   * carrying two things. It is not `rows` flattened either — that
+   * would drop the overflow and make a lane look lighter the more
+   * loaded it got, which inverts the one question this component
+   * answers.
+   */
+  inRangeCount: number
+  rows: PlacedTimelineItem<Item>[][]
+}
+
+const toDayNumber = (isoDate: string): null | number => {
+  const date: null | PlainDate = parseIsoDate(isoDate)
+
+  return date && getDayNumber(date)
+}
+
+/**
+ * `null` when either end is not an ISO calendar date.
+ *
+ * Not a thrown error and not a guessed range. A component that
+ * invents a range paints a confident picture of days nobody asked
+ * for, and the caller finds out when somebody notices the dates are
+ * wrong — which on a timeline is never, because there is nothing to
+ * compare them against.
+ *
+ * An **inverted** range (`end` before `start`) is a different case
+ * and is repaired rather than refused: it collapses to the single
+ * day at `start`. A caller flipping two variables gets one column
+ * and an obviously wrong picture, which is recoverable, instead of
+ * an empty component, which reads as "there is nothing on".
+ */
+export const toTimelineAxis = (
+  range: TimelineSpan,
+): null | TimelineAxis => {
+  const startDay = toDayNumber(range.start)
+
+  const rawEndDay = toDayNumber(range.end)
+
+  if (startDay === null || rawEndDay === null) {
+    return null
+  }
+
+  const endDay = Math.max(startDay, rawEndDay)
+
+  return {
+    columnCount: endDay - startDay + 1,
+    endDay,
+    startDay,
+  }
+}
+
+/**
+ * Where one item's bar goes, or `null` for "it is not in this
+ * picture at all".
+ *
+ * `null` is the right answer for an item outside the range, and it
+ * matters that it is distinguishable from a zero-width one: an item
+ * in another month must not be drawn, while an item whose own dates
+ * are degenerate must be. The four cases a naive implementation
+ * gets wrong, and what happens to each here:
+ *
+ *  - **Zero width** — `end` earlier than `start`. The span folds to
+ *    the single day at `start` and is drawn. It is not dropped,
+ *    because a dropped row is a data fault nobody can see; and it
+ *    is not drawn backwards, because there is no such shape.
+ *  - **A single day** — `start` equal to `end`. One column, with
+ *    the same bar treatment as any other. Not a dot: a dot is a
+ *    different mark, and the eye then has two vocabularies to learn
+ *    on one axis.
+ *  - **Starts before the range.** Clipped to column 1, with
+ *    `hasEarlierStart` set so the bar can drop its leading radius
+ *    and say "starts before this range" in its name. The naive
+ *    version computes a negative column, and CSS grid reads a
+ *    negative `grid-column-start` as counting back from the **end**
+ *    of the row — so the bar appears, in entirely the wrong place,
+ *    with nothing failing.
+ *  - **Ends after the range.** Clipped to the last column, with
+ *    `hasLaterEnd` set. `dayCount` still reports the item's true
+ *    length.
+ */
+export const toBarPlacement = ({
+  axis,
+  span,
+}: {
+  axis: TimelineAxis
+  span: TimelineSpan
+}): null | BarPlacement => {
+  const startDay = toDayNumber(span.start)
+
+  if (startDay === null) {
+    return null
+  }
+
+  const parsedEndDay = toDayNumber(span.end)
+
+  // An unparseable or inverted end is the zero-width case, and both
+  // resolve the same way: the item covers its start day and nothing
+  // else.
+  const endDay = Math.max(
+    startDay,
+    parsedEndDay ?? startDay,
+  )
+
+  if (endDay < axis.startDay || startDay > axis.endDay) {
+    return null
+  }
+
+  const visibleStartDay = Math.max(startDay, axis.startDay)
+
+  const visibleEndDay = Math.min(endDay, axis.endDay)
+
+  return {
+    columnStart: visibleStartDay - axis.startDay + 1,
+    columnSpan: visibleEndDay - visibleStartDay + 1,
+    dayCount: endDay - startDay + 1,
+    hasEarlierStart: startDay < axis.startDay,
+    hasLaterEnd: endDay > axis.endDay,
+  }
+}
+
+/**
+ * Stack a lane's items into as few rows as they fit in.
+ *
+ * Greedy first-fit over items sorted by start column, which is the
+ * standard interval-partitioning answer and is **optimal** for row
+ * count — the number of rows it produces equals the largest number
+ * of items overlapping on any one day, which is the smallest number
+ * any packing could use. Worth saying because the obvious
+ * alternative, one row per item, is what makes a hand-rolled
+ * timeline four screens tall.
+ *
+ * The lane getting taller is not a side effect, it is the point. A
+ * lane carrying three things at once is literally three times the
+ * height of one carrying them in sequence, so the asymmetry reads
+ * from across the room before anybody counts anything.
+ *
+ * Ties are broken by the **longer** item first and then by `key`,
+ * so the packing is stable: the same data renders the same rows on
+ * every machine and in every reorder of the input array. Without
+ * the `key` tie-break two items starting on the same day swap rows
+ * whenever the consumer's sort is unstable, which reads as the
+ * timeline flickering for no reason.
+ */
+export const toPackedLane = <
+  Item extends TimelineSpan & { key: string },
+>({
+  axis,
+  items,
+  maxRowCount,
+}: {
+  axis: TimelineAxis
+  items: readonly Item[]
+  /**
+   * How tall one lane may get. Past this, items are counted rather
+   * than drawn.
+   */
+  maxRowCount: number
+}): PackedLane<Item> => {
+  const placed = items.flatMap((item) => {
+    const placement = toBarPlacement({
+      axis,
+      span: item,
+    })
+
+    return placement ? [{ item, placement }] : []
+  })
+
+  const sorted = [...placed].sort(
+    (first, second) =>
+      first.placement.columnStart -
+        second.placement.columnStart ||
+      second.placement.columnSpan -
+        first.placement.columnSpan ||
+      (first.item.key < second.item.key ? -1 : 1),
+  )
+
+  const rows: PlacedTimelineItem<Item>[][] = []
+
+  let hiddenCount = 0
+
+  for (const entry of sorted) {
+    const row = rows.find((candidate) => {
+      const last = candidate.at(-1)
+
+      return (
+        !last ||
+        last.placement.columnStart +
+          last.placement.columnSpan <=
+          entry.placement.columnStart
+      )
+    })
+
+    if (row) {
+      row.push(entry)
+    } else if (rows.length < maxRowCount) {
+      rows.push([entry])
+    } else {
+      hiddenCount += 1
+    }
+  }
+
+  return {
+    hiddenCount,
+    inRangeCount: placed.length,
+    rows,
+  }
+}
+
+/**
+ * Is the axis wide enough to be worth drawing?
+ *
+ * The question a media query cannot ask, and the reason this
+ * component measures. The answer depends on **two** numbers and a
+ * breakpoint only knows one: 30 columns in 900px is a readable
+ * month, and 365 columns in the same 900px is 2.5px a day — a grey
+ * smear with bars in it. `Nav` folds its bar on measured width for
+ * the same reason, and `useToolbarOverflow` writes the general
+ * version of the argument down: a hardcoded `480px` is wrong the
+ * moment anything about the content changes.
+ *
+ * ⚠️ **`isMeasured` is a separate flag and not `inlineSize > 0`.**
+ * Before the layout effect runs there is no width, and the honest
+ * answer is the axis — it is what the component is for, and
+ * defaulting the other way would ship the fallback list to every
+ * non-browser render with nothing to say why. But **zero is also a
+ * real measurement**: the track sits in a `minmax(0, 1fr)` column
+ * beside a fixed label rail, so a container narrower than the rail
+ * resolves the track to exactly 0px. Reading that as "not measured
+ * yet" is how the first draft drew a thirty-column axis into 150
+ * pixels and reported it as fine.
+ */
+export const getIsAxisReadable = ({
+  columnCount,
+  inlineSize,
+  isMeasured,
+  minColumnInlineSize,
+}: {
+  columnCount: number
+  /** The measured inline size of the track, in CSS pixels. */
+  inlineSize: number
+  isMeasured: boolean
+  minColumnInlineSize: number
+}): boolean =>
+  !isMeasured ||
+  columnCount <= 0 ||
+  inlineSize / columnCount >= minColumnInlineSize
+
+/**
+ * Label every day, every week, or every four weeks.
+ *
+ * Thinning the ticks rather than shrinking the type, because type
+ * that shrinks to fit is type somebody cannot read and because the
+ * density axis already owns font size. The steps are 1, 7 and 28 —
+ * all whole weeks past the first, so a labelled column is the same
+ * weekday every time and the axis stays scannable. A step of 2 or 3
+ * was rejected for exactly that: labels landing on Tuesday, then
+ * Thursday, then Saturday give the eye nothing to lock onto.
+ */
+const TICK_STEPS = [1, 7, 28] as const
+
+export const chooseAxisTickStep = ({
+  columnCount,
+  inlineSize,
+  minTickInlineSize,
+}: {
+  columnCount: number
+  inlineSize: number
+  /** Room one tick label needs, in CSS pixels. */
+  minTickInlineSize: number
+}): number => {
+  if (inlineSize <= 0 || columnCount <= 0) {
+    return 1
+  }
+
+  const columnInlineSize = inlineSize / columnCount
+
+  return (
+    TICK_STEPS.find(
+      (step) =>
+        columnInlineSize * step >= minTickInlineSize,
+    ) ?? TICK_STEPS[TICK_STEPS.length - 1]
+  )
+}
+
+/**
+ * What a bar says when it cannot be seen.
+ *
+ * This is the load-bearing accessibility decision in the component,
+ * not a nicety. A bar carries its meaning in **position and
+ * length**, and neither of those reaches a screen reader, a
+ * high-contrast rendering, or anybody who cannot tell two hues
+ * apart. A one-day bar is also about 20px wide, so its own title
+ * does not fit inside it for a sighted reader either — the same
+ * sentence solves both.
+ *
+ * The dates are the item's **own**, never the clipped ones. A thing
+ * that runs from March into May reads as March to May even when the
+ * visible range is one week of April, because "when is this on" has
+ * one true answer and the viewport is not part of it.
+ *
+ * English, like `Board`'s move announcements. The library has no
+ * translation seam yet, and inventing one here would be a bigger
+ * decision than this component.
+ */
+export const describeTimelineSpan = ({
+  locale,
+  placement,
+  span,
+}: {
+  locale?: string
+  placement: BarPlacement
+  span: TimelineSpan
+}): string => {
+  const start = parseIsoDate(span.start)
+
+  if (!start) {
+    return ""
+  }
+
+  const format = (date: PlainDate) =>
+    formatAxisDate({ date, locale })
+
+  const end = parseIsoDate(span.end)
+
+  const sentence =
+    placement.dayCount <= 1 || !end
+      ? format(start)
+      : `${format(start)} to ${format(end)}, ${placement.dayCount} days`
+
+  return [
+    sentence,
+    placement.hasEarlierStart
+      ? "starts before this range"
+      : "",
+    placement.hasLaterEnd
+      ? "continues past this range"
+      : "",
+  ]
+    .filter(Boolean)
+    .join(", ")
+}
+
+/**
+ * One date, spelled the way both the axis and the spoken sentence
+ * want it: weekday, day, month.
+ *
+ * The weekday is in there because a timeline is read in weeks. "Is
+ * that the weekend?" is the most common question anybody asks of
+ * one, and answering it from a bare day number means counting
+ * columns.
+ */
+export const formatAxisDate = ({
+  date,
+  locale,
+}: {
+  date: PlainDate
+  locale?: string
+}): string =>
+  formatPlainDate(date, {
+    day: "numeric",
+    locale,
+    month: "short",
+    weekday: "short",
+  })

package/src/LaneTimeline/useTrackMeasurements.ts

@@ -0,0 +1,165 @@
+import type { RefObject } from "react"
+import {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react"
+
+/**
+ * The track's width, and the font size it is drawn in.
+ *
+ * ## Measured, because no breakpoint can answer this
+ *
+ * `Nav` folds its bar on a measured width and
+ * `useToolbarOverflow.ts` writes down the general form of the
+ * argument: mux-magic collapses at a hardcoded `480px`, plex-channels
+ * at `760px`, and neither number has a reason. A timeline has the
+ * same problem one level worse, because the question is not "how
+ * wide is the box" but **"how wide is one day"** — and that is the
+ * width divided by a number that lives in the data. Thirty columns
+ * in 900px is a readable month; three hundred and sixty five columns
+ * in the same 900px is a grey smear. A media query sees the first
+ * number and a container query sees the first number, so neither can
+ * decide this.
+ *
+ * ## Why the font size comes back too
+ *
+ * The minimum readable column is a multiple of the **type**, not a
+ * count of pixels. Every length in this token set moves with the
+ * density axis — `--font-size-md` is one thing on a desktop and
+ * another on the kiosk — so a column floor pinned at 20px is
+ * generous at one density and clips a two-digit date at the next.
+ * `Avatar` makes the same argument about a chip that stays 20px
+ * while the prose around it scales, and it is the same mistake.
+ *
+ * ⚠️ **The measured element must not be sized by its own contents.**
+ * The timeline reads its own box to decide what to draw in it, so a
+ * shrink-wrapping parent makes the answer its own input: fewer
+ * columns, narrower box, fewer columns. `LaneTimeline`'s root
+ * declares `container-type: inline-size`, which forbids exactly that
+ * — the same reason `Main` declares one — so the loop cannot form
+ * even when a caller drops the component into a `inline-flex` cell.
+ *
+ * ## The first paint
+ *
+ * `useLayoutEffect`, so the measurement lands **before the browser
+ * paints** and a timeline that has to fall back to the Narrow View
+ * never flashes an unreadable axis first. Same reasoning as
+ * `useToolbarOverflow`; the failure it prevents was visible on a
+ * kiosk Pi, where a slow first frame is on screen long enough to
+ * read.
+ *
+ * ## ⚠️ `trackRef` goes on a PROBE, never on the real track
+ *
+ * The one-way trap, and it is not hypothetical — the first draft
+ * had it. Attach this to the axis track itself and the Narrow View
+ * unmounts the element being measured, so the width never updates
+ * again and the timeline can never come back when the window
+ * widens. Hiding the track with `display: none` instead is worse: a
+ * hidden box measures 0, 0 reads as *unmeasured*, unmeasured shows
+ * the axis, the axis hides the fallback, and the component
+ * oscillates every frame.
+ *
+ * So the ref belongs to a zero-height `aria-hidden` cell that sits
+ * in the **same grid track** the axis would occupy and is rendered
+ * in both layouts. It answers the question actually being asked —
+ * *how wide would a day column be if I drew one* — in the layout
+ * where no day column exists.
+ */
+export const useTrackMeasurements = (): {
+  fontSize: number
+  inlineSize: number
+  isMeasured: boolean
+  trackRef: RefObject<HTMLDivElement | null>
+} => {
+  const trackRef = useRef<HTMLDivElement>(null)
+
+  const [measurements, setMeasurements] = useState({
+    fontSize: 0,
+    inlineSize: 0,
+    /**
+     * Its own flag rather than `inlineSize > 0`, and the reason is
+     * written out on `getIsAxisReadable`: **zero is a real width
+     * here.** The track is a `minmax(0, 1fr)` column beside a fixed
+     * label rail, so any container narrower than the rail resolves
+     * it to exactly 0px — and reading that as "not measured yet"
+     * puts a thirty-column axis into a phone and calls it readable.
+     */
+    isMeasured: false,
+  })
+
+  const measure = useCallback(() => {
+    const track = trackRef.current
+
+    if (!track) {
+      return
+    }
+
+    const style = getComputedStyle(track)
+
+    const next = {
+      fontSize: Number.parseFloat(style.fontSize) || 0,
+      inlineSize: track.clientWidth,
+      isMeasured: true,
+    }
+
+    setMeasurements((current) =>
+      current.fontSize === next.fontSize &&
+      current.inlineSize === next.inlineSize &&
+      current.isMeasured
+        ? current
+        : next,
+    )
+  }, [])
+
+  useLayoutEffect(measure)
+
+  useLayoutEffect(() => {
+    const track = trackRef.current
+
+    if (!track) {
+      return
+    }
+
+    /**
+     * Only when the **box** changed.
+     *
+     * A `ResizeObserver` delivers a record on observe and again for
+     * every reflow inside the frame it fired in, and measuring from
+     * each one is what raises chromium's "ResizeObserver loop
+     * completed with undelivered notifications". The same guard
+     * `useToolbarOverflow` carries, for the same reason: this
+     * callback's own `setState` can reflow the element it is
+     * watching.
+     */
+    let lastInlineSize = -1
+
+    const observer = new ResizeObserver(([entry]) => {
+      const inlineSize =
+        entry?.contentRect.width ??
+        track.getBoundingClientRect().width
+
+      if (inlineSize === lastInlineSize) {
+        return
+      }
+
+      lastInlineSize = inlineSize
+
+      measure()
+    })
+
+    observer.observe(track)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [measure])
+
+  return {
+    fontSize: measurements.fontSize,
+    inlineSize: measurements.inlineSize,
+    isMeasured: measurements.isMeasured,
+    trackRef,
+  }
+}

package/src/index.ts

@@ -237,6 +237,19 @@ export {
   INTENT_HOVER_CLASS,
   INTENT_SOLID_FILL_CLASS,
 } from "./intentStyles.ts"
+export type { LaneTimelineProps } from "./LaneTimeline/LaneTimeline.tsx"
+export { LaneTimeline } from "./LaneTimeline/LaneTimeline.tsx"
+export type { TimelineItem } from "./LaneTimeline/LaneTimelineBar.tsx"
+export type { TimelineLane } from "./LaneTimeline/LaneTimelineLane.tsx"
+export type {
+  BarPlacement,
+  TimelineAxis,
+  TimelineSpan,
+} from "./LaneTimeline/laneTimelineGeometry.ts"
+export {
+  toBarPlacement,
+  toTimelineAxis,
+} from "./LaneTimeline/laneTimelineGeometry.ts"
 export type { LightboxProps } from "./Lightbox/Lightbox.tsx"
 export { Lightbox } from "./Lightbox/Lightbox.tsx"
 export type {

package/src/sourceRules.test.ts

@@ -233,6 +233,13 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
     // owner is in whenever he browses zoomed in.
     "DatePicker",
     "EmptyState",
+    // `LaneTimeline` declares one and **never queries it**, which is
+    // the `Main` case rather than a mistake: it wants the
+    // `contain: inline-size` that rides along, because the component
+    // measures its own box to decide whether to draw a date axis at
+    // all. Without the containment a shrink-wrapping parent makes
+    // that answer its own input.
+    "LaneTimeline",
     "Main",
     "MarkdownEditor",
     "MediaTile",
@@ -591,7 +598,21 @@ test("the barrel is the only place components are re-exported", async () => {
   // from `ActionTiles`' "what do you want to do" and would have
   // meant one component whose icon is sometimes a 20px glyph beside
   // a title and sometimes a 144px circle above it.
-  expect(componentNames.length).toBe(65)
+  //
+  // `LaneTimeline` — one horizontal lane per group across a date
+  // axis, with a multi-day thing drawn as a bar — is +1 -> 66. It is
+  // the first component that folds on a **measurement of its own
+  // box** rather than on a container query, and the reason is in the
+  // arithmetic: the question is not how wide the box is but how wide
+  // one day is, which is the width divided by a number that lives in
+  // the data. `laneTimelineGeometry.ts`, `LaneTimelineBar.tsx`,
+  // `LaneTimelineLane.tsx` and `useTrackMeasurements.ts` are its
+  // members and stay out of this count by the `<Name>/<Name>.tsx`
+  // rule. The geometry module is still exported from the barrel — a
+  // consumer deciding whether an item is on screen must ask the
+  // question the same way the bars are placed, or the two answers
+  // drift by a day and nothing says so.
+  expect(componentNames.length).toBe(66)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)