@nowline/layout 0.0.0-dev.20260601071750.g04bdff9

package/src/inline-date-pin-geometry.ts

@@ -0,0 +1,196 @@
+// Inline-date pin glyph placement.
+//
+// `after:DATE` paints a calendar glyph in the entity's top-LEFT decoration
+// slot; `before:DATE` paints it in the top-RIGHT slot. The two helpers
+// below produce `Point` coordinates for the glyph's top-left corner, plus
+// a `spilled` flag indicating whether the bar was too narrow to host the
+// glyph inside (item case only — containers always have room).
+//
+// Slot interleaving rules (per specs/rendering.md "Inline-date glyph"):
+//
+//   Item top-LEFT: glyph sits at the bar's leftmost slot when no link icon
+//   is present, otherwise one decoration step right of the link icon's
+//   right edge.
+//
+//   Item top-RIGHT: glyph sits at the bar's rightmost slot when no status
+//   dot or footnotes are present, one step LEFT of the status dot when no
+//   footnotes, and one step LEFT of the LEFTMOST footnote indicator when
+//   footnotes are present (so the inline-date glyph inserts at the LEFT
+//   end of the existing badge cluster rather than reordering it).
+//
+//   Container (group, parallel): glyph sits at the bounding box's top
+//   corners with the standard inset. Containers don't carry status dots
+//   or footnote indicators in their own decoration row, so no
+//   interleaving math is needed.
+
+import {
+    INLINE_DATE_GLYPH_GAP_PX,
+    INLINE_DATE_GLYPH_INSET_LEFT_PX,
+    INLINE_DATE_GLYPH_INSET_RIGHT_PX,
+    INLINE_DATE_GLYPH_INSET_TOP_PX,
+    INLINE_DATE_GLYPH_TILE_SIZE_PX,
+    ITEM_CAPTION_SPILL_GAP_PX,
+    ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX,
+    ITEM_FOOTNOTE_INDICATOR_STEP_PX,
+    ITEM_LINK_ICON_INSET_PX,
+    ITEM_LINK_ICON_TILE_SIZE_PX,
+    ITEM_STATUS_DOT_INSET_RIGHT_PX,
+    ITEM_STATUS_DOT_RADIUS_PX,
+    MIN_BAR_WIDTH_FOR_INLINE_DATE_PX,
+} from './item-bar-geometry.js';
+import type { BoundingBox, InlineDatePin, Point } from './types.js';
+
+export interface ItemInlineDatePinInputs {
+    box: BoundingBox;
+    /** ISO date string from `after:DATE`, or undefined when no inline `after`. */
+    afterDate: string | undefined;
+    /** ISO date string from `before:DATE`, or undefined when no inline `before`. */
+    beforeDate: string | undefined;
+    hasLinkIcon: boolean;
+    /** Number of footnote indicators rendered in the bar's top-RIGHT cluster. */
+    footnoteCount: number;
+}
+
+/**
+ * Compute inline-date pin glyph placements for an item bar. Returns an
+ * empty array when neither `afterDate` nor `beforeDate` is set.
+ *
+ * Item bars participate in the narrow-bar spill family — when the bar is
+ * narrower than `MIN_BAR_WIDTH_FOR_INLINE_DATE_PX`, the `before:` glyph
+ * spills RIGHT of the bar (joining the status-dot / footnote spill
+ * column) and the `after:` glyph spills LEFT of the bar's leading edge
+ * so the side semantics stay readable.
+ */
+export function computeItemInlineDatePins(opts: ItemInlineDatePinInputs): InlineDatePin[] {
+    const { box, afterDate, beforeDate, hasLinkIcon, footnoteCount } = opts;
+    if (!afterDate && !beforeDate) return [];
+
+    const pins: InlineDatePin[] = [];
+    const tileSize = INLINE_DATE_GLYPH_TILE_SIZE_PX;
+    const topY = box.y + INLINE_DATE_GLYPH_INSET_TOP_PX;
+    const spilled = box.width < MIN_BAR_WIDTH_FOR_INLINE_DATE_PX;
+
+    if (afterDate) {
+        const insideLeftX = hasLinkIcon
+            ? box.x +
+              ITEM_LINK_ICON_INSET_PX +
+              ITEM_LINK_ICON_TILE_SIZE_PX +
+              INLINE_DATE_GLYPH_GAP_PX
+            : box.x + INLINE_DATE_GLYPH_INSET_LEFT_PX;
+        const glyphLeft: Point = spilled
+            ? {
+                  x: box.x - ITEM_CAPTION_SPILL_GAP_PX - tileSize,
+                  y: topY,
+              }
+            : { x: insideLeftX, y: topY };
+        pins.push({
+            side: 'after',
+            isoDate: afterDate,
+            glyphTopLeft: glyphLeft,
+            glyphSize: tileSize,
+            spilled,
+        });
+    }
+
+    if (beforeDate) {
+        // Walk LEFT from the rightmost top-decoration slot:
+        //   - rightmost footnote anchors at (box.right - INSET_RIGHT_PX)
+        //   - leftmost footnote sits one step further left per extra digit
+        //   - status dot left edge sits at (box.right - INSET_RIGHT - DOT_RADIUS)
+        //   - inline-date glyph sits one INLINE_DATE_GLYPH_GAP_PX further left
+        const rightEdge = box.x + box.width;
+        let anchorRightX: number;
+        if (footnoteCount > 0) {
+            const leftmostFootnoteCenter =
+                rightEdge -
+                ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX -
+                (footnoteCount - 1) * ITEM_FOOTNOTE_INDICATOR_STEP_PX;
+            anchorRightX = leftmostFootnoteCenter - INLINE_DATE_GLYPH_GAP_PX;
+        } else {
+            const dotLeftEdge =
+                rightEdge - ITEM_STATUS_DOT_INSET_RIGHT_PX - ITEM_STATUS_DOT_RADIUS_PX;
+            anchorRightX = dotLeftEdge - INLINE_DATE_GLYPH_GAP_PX;
+        }
+        const insideRightX = anchorRightX - tileSize;
+        const glyphLeft: Point = spilled
+            ? {
+                  x: rightEdge + ITEM_CAPTION_SPILL_GAP_PX,
+                  y: topY,
+              }
+            : { x: insideRightX, y: topY };
+        pins.push({
+            side: 'before',
+            isoDate: beforeDate,
+            glyphTopLeft: glyphLeft,
+            glyphSize: tileSize,
+            spilled,
+        });
+    }
+
+    return pins;
+}
+
+export interface ContainerInlineDatePinInputs {
+    /** Bounding box that anchors the glyph corners. For styled groups and
+     *  bracketed parallels this is the visible box; for unstyled groups
+     *  and bare parallels it is the logical bounding box (leftmost child
+     *  start, rightmost child end, top of the highest child row). */
+    box: BoundingBox;
+    afterDate: string | undefined;
+    beforeDate: string | undefined;
+}
+
+/**
+ * Compute inline-date pin glyph placements for a container (group or
+ * parallel). The glyphs sit flush to the box's top-LEFT (`after`) and
+ * top-RIGHT (`before`) corners with the standard inset; containers
+ * never spill (they always have room for a 12 px tile in their own
+ * top-decoration row).
+ */
+export function computeContainerInlineDatePins(
+    opts: ContainerInlineDatePinInputs,
+): InlineDatePin[] {
+    const { box, afterDate, beforeDate } = opts;
+    if (!afterDate && !beforeDate) return [];
+
+    const pins: InlineDatePin[] = [];
+    const tileSize = INLINE_DATE_GLYPH_TILE_SIZE_PX;
+    const topY = box.y + INLINE_DATE_GLYPH_INSET_TOP_PX;
+
+    if (afterDate) {
+        pins.push({
+            side: 'after',
+            isoDate: afterDate,
+            glyphTopLeft: { x: box.x + INLINE_DATE_GLYPH_INSET_LEFT_PX, y: topY },
+            glyphSize: tileSize,
+            spilled: false,
+        });
+    }
+
+    if (beforeDate) {
+        pins.push({
+            side: 'before',
+            isoDate: beforeDate,
+            glyphTopLeft: {
+                x: box.x + box.width - INLINE_DATE_GLYPH_INSET_RIGHT_PX - tileSize,
+                y: topY,
+            },
+            glyphSize: tileSize,
+            spilled: false,
+        });
+    }
+
+    return pins;
+}
+
+/**
+ * Returns the first ISO date literal in `values`, or undefined when none
+ * is present. The validator enforces "at most one inline date per
+ * direction" so this lookup is unambiguous.
+ */
+export function pickInlineDate(values: readonly string[]): string | undefined {
+    for (const v of values) {
+        if (/^\d{4}-\d{2}-\d{2}$/.test(v)) return v;
+    }
+    return undefined;
+}

package/src/item-bar-geometry.ts

@@ -0,0 +1,271 @@
+// Item-bar internal geometry — the "rails" inside an item rectangle:
+// caption text (title + meta), label chips along the bottom, status
+// dot at the upper-right, footnote indicators just left of the dot,
+// and the link icon tile at the bottom-right.
+//
+// These metrics are shared between layout (label-chip placement,
+// future content-aware width estimation) and renderer (text baselines
+// + glyph positions). Keeping them in one module means a single edit
+// re-skins every item bar consistently — the alternative is hunting
+// matching `+ 12`s across two packages.
+//
+// Coordinate convention: every offset is **relative to the item's
+// `box`** (`box.x` for X, `box.y` for Y), with `box.height` /
+// `box.width` used as the "right edge" / "bottom edge" anchor where
+// noted.
+
+// ---- Caption (title + meta text) ---------------------------------
+
+/** Horizontal inset (px) for the caption's left edge inside the bar. */
+export const ITEM_CAPTION_INSET_X_PX = 12;
+
+/**
+ * When the bar's title would overflow to the right, layout sets
+ * `textSpills` and the caption renders to the RIGHT of the bar; this
+ * is the gap (px) between the bar's right edge and the spilled
+ * caption.
+ */
+export const ITEM_CAPTION_SPILL_GAP_PX = 6;
+
+/** Baseline Y of the title text relative to the bar's top. */
+export const ITEM_CAPTION_TITLE_BASELINE_OFFSET_PX = 20;
+
+/** Baseline Y of the meta text (second line) relative to the bar's top. */
+export const ITEM_CAPTION_META_BASELINE_OFFSET_PX = 38;
+
+/** Font size (px) of the title text. */
+export const ITEM_CAPTION_TITLE_FONT_SIZE_PX = 13;
+
+/** Font size (px) of the meta text. */
+export const ITEM_CAPTION_META_FONT_SIZE_PX = 11;
+
+// ---- Status dot (upper-right glyph) ------------------------------
+
+/** Distance (px) from the bar's right edge to the dot's center. */
+export const ITEM_STATUS_DOT_INSET_RIGHT_PX = 12;
+
+/** Distance (px) from the bar's top edge to the dot's center. */
+export const ITEM_STATUS_DOT_INSET_TOP_PX = 12;
+
+/** Radius (px) of the status dot. */
+export const ITEM_STATUS_DOT_RADIUS_PX = 5;
+
+// ---- Footnote indicators (numbers next to status dot) ------------
+
+/**
+ * X offset (px from bar's right edge) where the rightmost footnote
+ * digit's anchor sits. Tuned to leave room for the status dot.
+ */
+export const ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX = 22;
+
+/** Baseline Y (px from bar's top) for footnote indicator digits. */
+export const ITEM_FOOTNOTE_INDICATOR_BASELINE_OFFSET_PX = 14;
+
+/**
+ * Horizontal step (px) between consecutive footnote indicators when
+ * an item carries more than one footnote — they walk LEFT from the
+ * status dot.
+ */
+export const ITEM_FOOTNOTE_INDICATOR_STEP_PX = 8;
+
+// ---- Link icon tile (bottom-right) -------------------------------
+
+/** Side length (px) of the square link-icon tile. */
+export const ITEM_LINK_ICON_TILE_SIZE_PX = 14;
+
+/** Distance (px) from the bar's right/bottom edges to the tile's edge. */
+export const ITEM_LINK_ICON_INSET_PX = 6;
+
+// ---- Narrow-bar decoration spill --------------------------------
+
+/**
+ * Horizontal gap (px) between consecutive decorations (status dot,
+ * link icon, footnote, title) when they spill into the column to
+ * the right of a bar that's too narrow to host them inside.
+ */
+export const ITEM_DECORATION_SPILL_GAP_PX = 4;
+
+/**
+ * Minimum bar width (px) needed to host the status dot inside the
+ * bar with its full inset. Below this, the dot would have to
+ * extend past the bar's left edge, so the dot spills into the
+ * caption column to the right of the bar instead.
+ */
+export const MIN_BAR_WIDTH_FOR_DOT_PX = ITEM_STATUS_DOT_INSET_RIGHT_PX + ITEM_STATUS_DOT_RADIUS_PX;
+
+/**
+ * Minimum bar width (px) needed to host the link-icon tile AND the
+ * status dot inside the bar with at least
+ * `ITEM_DECORATION_SPILL_GAP_PX` of breathing room between them.
+ * Below this, the link icon would visually collide with (or push
+ * into) the dot's column, so the icon spills out and renders ahead
+ * of the (also-spilled) title.
+ */
+export const MIN_BAR_WIDTH_FOR_LINK_AND_DOT_PX =
+    ITEM_LINK_ICON_INSET_PX +
+    ITEM_LINK_ICON_TILE_SIZE_PX +
+    ITEM_DECORATION_SPILL_GAP_PX +
+    ITEM_STATUS_DOT_INSET_RIGHT_PX +
+    ITEM_STATUS_DOT_RADIUS_PX;
+
+/**
+ * Minimum bar width (px) needed to host the footnote indicator at
+ * its inset-right position without overshooting the bar's left
+ * edge or colliding with a leading link icon. Approximate width
+ * for one digit is 8px (font-size 10, bold).
+ */
+export const MIN_BAR_WIDTH_FOR_FOOTNOTE_PX = ITEM_FOOTNOTE_INDICATOR_INSET_RIGHT_PX + 1;
+
+// ---- Inline-date glyph (after:DATE / before:DATE corner badge) ---
+//
+// Renders the renderer's built-in `calendar` SVG at top-LEFT (`after`)
+// or top-RIGHT (`before`) of the entity bar. Sized as a sibling of
+// the status dot and footnote indicators (smaller than the link tile)
+// so the top-decoration row stays visually unified. See
+// specs/rendering.md "Inline-date glyph".
+
+/** Side length (px) of the inline-date calendar glyph tile. */
+export const INLINE_DATE_GLYPH_TILE_SIZE_PX = 12;
+
+/** Distance (px) from the bar's left edge to the glyph's left edge
+ *  when the glyph sits at the leftmost top-decoration slot (no link
+ *  icon present). */
+export const INLINE_DATE_GLYPH_INSET_LEFT_PX = 6;
+
+/** Distance (px) from the bar's right edge to the glyph's right edge
+ *  when the glyph sits at the rightmost top-decoration slot (no
+ *  status dot or footnote present). */
+export const INLINE_DATE_GLYPH_INSET_RIGHT_PX = 6;
+
+/** Distance (px) from the bar's top edge to the glyph's top edge. */
+export const INLINE_DATE_GLYPH_INSET_TOP_PX = 5;
+
+/** Horizontal gap (px) between the inline-date glyph and an adjacent
+ *  decoration (link icon on the left, status dot / footnote indicator
+ *  on the right). Matches the existing decoration spill gap so the
+ *  top-decoration row reads as one rhythm. */
+export const INLINE_DATE_GLYPH_GAP_PX = ITEM_DECORATION_SPILL_GAP_PX;
+
+/**
+ * Minimum bar width (px) needed to host the inline-date glyph inside
+ * the bar. Below this, the glyph spills:
+ *   - `before:` glyph spills RIGHT into the column the status dot
+ *     uses (same family of decorations, same step pitch).
+ *   - `after:` glyph spills LEFT of the bar's leading edge so the
+ *     side semantics (after vs before) stay readable in the spill.
+ *
+ * The threshold reserves room for the glyph itself plus a small
+ * clearance from the link-icon column (when present) so the two
+ * glyphs don't overlap inside narrow bars.
+ */
+export const MIN_BAR_WIDTH_FOR_INLINE_DATE_PX =
+    INLINE_DATE_GLYPH_INSET_LEFT_PX +
+    INLINE_DATE_GLYPH_TILE_SIZE_PX +
+    INLINE_DATE_GLYPH_GAP_PX +
+    INLINE_DATE_GLYPH_TILE_SIZE_PX +
+    INLINE_DATE_GLYPH_INSET_RIGHT_PX;
+
+// ---- Label chips (along the bar's bottom) ------------------------
+
+/** Height (px) of a label chip rectangle. */
+export const LABEL_CHIP_HEIGHT_PX = 13;
+
+/**
+ * Vertical gap (px) between the top of the bottom progress strip and
+ * the BOTTOM of a label chip. Keeps chips from touching the strip and
+ * gives a clear visual rail.
+ */
+export const LABEL_CHIP_GAP_ABOVE_PROGRESS_STRIP_PX = 3;
+
+/** Horizontal gap (px) between consecutive chips in a row. */
+export const LABEL_CHIP_GAP_BETWEEN_PX = 4;
+
+/**
+ * Vertical gap (px) between two stacked chip rows when chips spill
+ * outside the bar and form a multi-row column to the right.
+ */
+export const LABEL_CHIP_ROW_GAP_PX = 4;
+
+/**
+ * Vertical row pitch (px) for a stacked chip column — chip height +
+ * inter-row gap.
+ */
+export const LABEL_CHIP_ROW_STEP_PX = LABEL_CHIP_HEIGHT_PX + LABEL_CHIP_ROW_GAP_PX;
+
+/**
+ * Slack budget (fraction) applied ONCE per item when chips spill
+ * outside the bar. If a chip would overflow its row by less than
+ * `SPILL_ROW_SLACK_FRACTION × chip.width`, the row is allowed to
+ * stretch by the overflow amount and keep the chip on it instead of
+ * wrapping. This rescues "lonely chip" cases where one chip just
+ * barely overshoots; once the slack is consumed, no further row
+ * expansions happen for that item.
+ */
+export const SPILL_ROW_SLACK_FRACTION = 0.25;
+
+export interface ChipRowSample<T> {
+    id: T;
+    width: number;
+}
+
+export interface SpillChipPack<T> {
+    /** Rows ordered top-to-bottom — `rows[0]` sits at the chip
+     *  column's top y, `rows[1]` one `LABEL_CHIP_ROW_STEP_PX` below,
+     *  and so on. */
+    rows: ChipRowSample<T>[][];
+    /** True when the slack rule was used to keep an extra chip on
+     *  row 0 (or whichever row was being filled when the overflow
+     *  happened). At most one expansion per item. */
+    expanded: boolean;
+}
+
+/**
+ * Pack `chips` into rows for the SPILL column to the right of an
+ * item bar. Each row is capped at `barVisualWidth` (with gaps
+ * between chips). When a chip would overflow:
+ *
+ * - If the row is empty, place the chip anyway (a chip wider than
+ *   the cap occupies its own row).
+ * - Else if the slack rule applies (`overflow ≤ 0.25 × chip.width`)
+ *   AND the slack hasn't already been used for this item, expand
+ *   the current row by `overflow` and keep the chip on it.
+ * - Else wrap the chip to a fresh row.
+ */
+export function packSpillChips<T>(
+    chips: ChipRowSample<T>[],
+    barVisualWidth: number,
+): SpillChipPack<T> {
+    if (chips.length === 0) return { rows: [[]], expanded: false };
+    const rows: ChipRowSample<T>[][] = [[]];
+    let used = 0;
+    let rowCap = barVisualWidth;
+    let expanded = false;
+    for (const chip of chips) {
+        const row = rows[rows.length - 1];
+        const needed = (row.length === 0 ? 0 : LABEL_CHIP_GAP_BETWEEN_PX) + chip.width;
+        const wouldBe = used + needed;
+        if (wouldBe <= rowCap) {
+            row.push(chip);
+            used = wouldBe;
+            continue;
+        }
+        if (row.length === 0) {
+            row.push(chip);
+            used = chip.width;
+            continue;
+        }
+        const overflow = wouldBe - rowCap;
+        const slack = chip.width * SPILL_ROW_SLACK_FRACTION;
+        if (!expanded && overflow <= slack) {
+            row.push(chip);
+            used = wouldBe;
+            rowCap = wouldBe;
+            expanded = true;
+            continue;
+        }
+        rows.push([chip]);
+        used = chip.width;
+        rowCap = barVisualWidth;
+    }
+    return { rows, expanded };
+}