@lotics/ui 18.2.0 → 19.0.1

package/src/task_metrics.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { TASK_ROW_BAND, TASK_ROW_GAP, TASK_TITLE_LINE, taskGutter, taskTitleSlack } from "./task_metrics";
+
+describe("task row geometry", () => {
+  it("puts the control's centre and the title's first text line on the SAME y, at every density", () => {
+    for (const band of Object.values(TASK_ROW_BAND)) {
+      // The control centres in the band; the title's first line centres at its slack + half a
+      // line. A density whose band breaks this equality sags the control off its own title.
+      expect(taskTitleSlack(band) + TASK_TITLE_LINE / 2).toBe(band / 2);
+    }
+  });
+
+  it("pins the first line on any band the family builds, not only the density table's", () => {
+    // A sub-field's line is the TALLER of the row band and the control it holds (a 40px inline
+    // editor does not fit a `dense` 32 row), so the law has to hold on bands the density table
+    // never names.
+    for (let band = TASK_TITLE_LINE; band <= 64; band += 2) {
+      expect(taskTitleSlack(band) + TASK_TITLE_LINE / 2).toBe(band / 2);
+    }
+  });
+
+  it("lands every density on whole pixels", () => {
+    for (const band of Object.values(TASK_ROW_BAND)) {
+      expect(Number.isInteger(taskTitleSlack(band))).toBe(true);
+    }
+  });
+
+  it("never pulls a title above its row when the band is shorter than a line of text", () => {
+    expect(taskTitleSlack(TASK_TITLE_LINE - 8)).toBe(0);
+  });
+});
+
+describe("task row gutters", () => {
+  it("gives a pinned control its own width plus the gap that separates it from the content", () => {
+    // ONE rule for BOTH edges: the leading ring's column and the trailing ⋯'s column are the same
+    // arithmetic, which is what lets a row reserve them as plain padding and leave a content box
+    // every line — title, caption, sub-row, detail, nested list — can span exactly.
+    for (const width of [20, 24, 28, 40]) {
+      expect(taskGutter(width)).toBe(width + TASK_ROW_GAP);
+    }
+  });
+
+  it("charges NOTHING for a gutter a list declines", () => {
+    // A list whose rows carry no ⋯ passes `actionWidth={0}` and its content must run to the
+    // container's edge. Leaving the gap behind would bill it 12px for a column it never uses.
+    expect(taskGutter(0)).toBe(0);
+  });
+});

package/src/task_metrics.ts

@@ -0,0 +1,55 @@
+/**
+ * The task row's geometry — the two laws a style object cannot state on its own.
+ *
+ * VERTICALLY, a row's FIRST LINE is a BAND: the leading control centres in that band, and the
+ * title's first text line centres in it too. Both centres are `band / 2`, which is what keeps a
+ * column of controls straight however tall the rows grow underneath them.
+ *
+ * HORIZONTALLY, a row is a GUTTER, one content box, and a GUTTER: each pinned control's column
+ * is its own width plus the row gap, and the same `taskGutter` sizes both edges — so the ⋯ on
+ * the right is the mirror of the ring on the left, not a second rule that happens to look alike.
+ *
+ * RN-free on purpose (Vitest cannot parse `react-native`): `task.tsx` renders these numbers,
+ * `task_metrics.test.ts` asserts the laws they exist to hold.
+ */
+
+/**
+ * The band per density — `comfortable` is a finger's tap target, `dense` trades it for rows on
+ * screen. It is also the row's MINIMUM height: with nothing hanging beneath it, the first line
+ * IS the row.
+ */
+export const TASK_ROW_BAND = { comfortable: 44, dense: 32 } as const;
+
+/** The kit's `Text size="sm"` line box — one line of a task title, wrapped or not. */
+export const TASK_TITLE_LINE = 20;
+
+/** The horizontal rhythm between a row's slots — and the air between a pinned control and the
+ *  content beside it, which is what makes it half of a gutter. */
+export const TASK_ROW_GAP = 12;
+
+/**
+ * ONE gutter — the column a PINNED control owns on either edge of a row: its own width plus the
+ * gap that separates it from the content. The item reserves it as padding, the control sits in
+ * it, and what is left between the two gutters is the row's content box: every line the item
+ * renders (title, caption, sub-row, detail, a nested list) spans exactly that box, so the right
+ * edge is straight even down a list where only SOME rows carry a ⋯.
+ *
+ * Zero width is zero gutter, gap included — a list whose rows carry no menu pays nothing for a
+ * column it never uses, and a reserved-but-empty 12px is still paying.
+ */
+export function taskGutter(controlWidth: number): number {
+  return controlWidth === 0 ? 0 : controlWidth + TASK_ROW_GAP;
+}
+
+/**
+ * The slack a PLAIN-TEXT title carries above AND below its text so its FIRST line centres on
+ * the band. Symmetric padding, not `minHeight` + centring, is what holds that first line in
+ * place when the title wraps: centring a BLOCK of two lines drops the first one half a line
+ * above the control, which is the misalignment this geometry exists to prevent.
+ *
+ * Clamped at 0 — a band shorter than a line of text starts the text at the row's top rather
+ * than pulling it above the row.
+ */
+export function taskTitleSlack(band: number): number {
+  return Math.max(0, (band - TASK_TITLE_LINE) / 2);
+}