@charcuterie/ui 4.5.1 → 4.7.0

package/dist/LaneTimeline/LaneTimelineLane.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUniqueId } from "@charcuterie/logic";
+import { CATEGORICAL_INDEX_COUNT, CATEGORICAL_SEQUENCE, } from "@charcuterie/tokens";
+import { Badge } from "../Badge/Badge.js";
+import { CATEGORICAL_SOLID_FILL_CLASS } from "../categoricalStyles.js";
+import { TextLink } from "../TextLink/TextLink.js";
+import { toClassName } from "../toClassName.js";
+import { LaneTimelineBar } from "./LaneTimelineBar.js";
+import { describeTimelineSpan, toPackedLane, } from "./laneTimelineGeometry.js";
+/**
+ * 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, }) => {
+    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}`;
+    const header = (_jsxs("header", { className: "flex min-w-0 items-center gap-2", children: [_jsx("span", { "aria-hidden": "true", className: toClassName("h-4 w-1 shrink-0 rounded-full", CATEGORICAL_SOLID_FILL_CLASS[categorical]) }), _jsx(Heading, { className: "min-w-0 truncate font-semibold text-content-primary text-sm", id: headingId, title: lane.label, children: lane.href ? (_jsx(TextLink, { appearance: "standalone", className: "font-semibold text-inherit", href: lane.href, children: lane.label })) : (lane.label) }), _jsx(Badge, { appearance: "soft", intent: "neutral", size: "sm", children: String(packed.inRangeCount) })] }));
+    if (shape === "list") {
+        const items = packed.rows
+            .flat()
+            .sort((first, second) => first.placement.columnStart -
+            second.placement.columnStart);
+        return (_jsxs("div", { "aria-labelledby": headingId, className: "flex flex-col gap-1.5 border-border-subtle border-t py-2", role: "group", children: [header, items.length === 0 ? (_jsx("p", { className: "text-content-muted text-xs", children: "Nothing in this range." })) : (_jsx("ul", { className: "flex flex-col gap-1", children: items.map(({ item, placement }) => (_jsx("li", { className: "min-w-0", children: _jsx(LaneTimelineBar, { laneCategorical: categorical, description: describeTimelineSpan({
+                                locale,
+                                placement,
+                                span: item,
+                            }), hasEarlierStart: placement.hasEarlierStart, hasLaterEnd: placement.hasLaterEnd, item: item, shape: "row" }) }, item.key))) }))] }));
+    }
+    return (_jsxs("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", children: [header, _jsxs("div", { className: "relative min-h-6", children: [_jsx("div", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 grid", style: { gridTemplateColumns: columnTemplate }, children: Array.from({ length: axis.columnCount }, (_unused, index) => axis.startDay + index).map((dayNumber) => (_jsx("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") }, dayNumber))) }), _jsx("ul", { className: "relative grid gap-1", style: { gridTemplateColumns: columnTemplate }, children: packed.rows.flatMap((row, rowIndex) => row.map(({ item, placement }) => (_jsx("li", { className: "min-w-0", 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,
+                            }, children: _jsx(LaneTimelineBar, { laneCategorical: categorical, description: describeTimelineSpan({
+                                    locale,
+                                    placement,
+                                    span: item,
+                                }), hasEarlierStart: placement.hasEarlierStart, hasLaterEnd: placement.hasLaterEnd, item: item, shape: "bar" }) }, item.key)))) }), packed.hiddenCount > 0 ? (_jsx("p", { className: "pt-1 text-content-muted text-xs", children: `+ ${packed.hiddenCount} more overlapping in ${lane.label}` })) : null] })] }));
+};
+//# sourceMappingURL=LaneTimelineLane.js.map

package/dist/LaneTimeline/LaneTimelineLane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LaneTimelineLane.js","sourceRoot":"","sources":["../../src/LaneTimeline/LaneTimelineLane.tsx"],"names":[],"mappings":"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"}

package/dist/LaneTimeline/laneTimelineGeometry.d.ts

@@ -0,0 +1,268 @@
+/**
+ * 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";
+/**
+ * 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>[][];
+};
+/**
+ * `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 declare const toTimelineAxis: (range: TimelineSpan) => null | TimelineAxis;
+/**
+ * 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 declare const toBarPlacement: ({ axis, span, }: {
+    axis: TimelineAxis;
+    span: TimelineSpan;
+}) => null | BarPlacement;
+/**
+ * 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 declare 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>;
+/**
+ * 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 declare 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;
+export declare const chooseAxisTickStep: ({ columnCount, inlineSize, minTickInlineSize, }: {
+    columnCount: number;
+    inlineSize: number;
+    /** Room one tick label needs, in CSS pixels. */
+    minTickInlineSize: number;
+}) => number;
+/**
+ * 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 declare const describeTimelineSpan: ({ locale, placement, span, }: {
+    locale?: string;
+    placement: BarPlacement;
+    span: TimelineSpan;
+}) => string;
+/**
+ * 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 declare const formatAxisDate: ({ date, locale, }: {
+    date: PlainDate;
+    locale?: string;
+}) => string;
+//# sourceMappingURL=laneTimelineGeometry.d.ts.map

package/dist/LaneTimeline/laneTimelineGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"laneTimelineGeometry.d.ts","sourceRoot":"","sources":["../../src/LaneTimeline/laneTimelineGeometry.ts"],"names":[],"mappings":"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"}

package/dist/LaneTimeline/laneTimelineGeometry.js

@@ -0,0 +1,277 @@
+/**
+ * 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 { formatPlainDate, getDayNumber, parseIsoDate, } from "../DatePicker/plainDate.js";
+const toDayNumber = (isoDate) => {
+    const date = 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) => {
+    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, }) => {
+    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 = ({ axis, items, maxRowCount, }) => {
+    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 = [];
+    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, }) => !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];
+export const chooseAxisTickStep = ({ columnCount, inlineSize, minTickInlineSize, }) => {
+    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, }) => {
+    const start = parseIsoDate(span.start);
+    if (!start) {
+        return "";
+    }
+    const format = (date) => 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, }) => formatPlainDate(date, {
+    day: "numeric",
+    locale,
+    month: "short",
+    weekday: "short",
+});
+//# sourceMappingURL=laneTimelineGeometry.js.map