Merge pull request #192 from RtlZeroMemory/feat/measure-element-truncate-start

feat(core): add measureElement and textOverflow start

Author: RtlZeroMemory

CLAUDE.md

@@ -107,7 +107,7 @@ Current layout behavior to preserve when editing or generating docs:
 - Intrinsic sizing protocol (`measureMinContent` / `measureMaxContent`) is active for leaf and container measurement.
 - Stack constraints support `flex`, `flexShrink`, `flexBasis`, and per-child `alignSelf`.
 - Stack wrap and non-wrap paths use bounded cross-axis feedback (max 2 measure passes per child when needed).
-- Text supports `wrap` with grapheme-safe hard breaks and newline-aware paragraph splits.
+- Text supports `wrap` with grapheme-safe hard breaks and newline-aware paragraph splits. `textOverflow` supports `"clip"`, `"ellipsis"`, `"middle"`, and `"start"` (keeps tail with leading ellipsis).
 - Box has `gap` on its synthetic inner column and runs absolute children in a second out-of-flow pass.
 - Stack/box absolute positioning supports `position: "absolute"` + `top/right/bottom/left`.
 - Grid supports explicit placement and spans (`gridColumn`, `gridRow`, `colSpan`, `rowSpan`) with occupancy-aware auto placement.
@@ -308,6 +308,10 @@ each(items, (item) => ui.text(item.name), { key: (item) => item.id });
 
 This allows centralized logging/middleware via app-level event listeners in addition to per-widget callbacks.
 
+## Layout Measurement
+
+`app.measureElement(id)` returns the computed layout `Rect` (`{ x, y, w, h }`) for any widget by its string `id`, or `null` if the widget is not in the current tree. The rect reflects the most recent layout pass. Types `Rect`, `Size`, and `Axis` are exported from `@rezi-ui/core`.
+
 ## Drawlist Codegen Protocol (MUST for ZRDL command changes)
 
 When changing drawlist command layout/opcodes/field offsets for v3/v4/v5:

docs/migration/ink-to-rezi.md

@@ -100,17 +100,27 @@ ui.table({
 
 ### 4) Text styling and truncation
 
-`ui.text` handles style + deterministic cell-aware truncation.
+`ui.text` handles style + deterministic cell-aware truncation. Four overflow modes are available: `"clip"` (default), `"ellipsis"`, `"middle"`, and `"start"`.
 
 ```typescript
 import { rgb } from "@rezi-ui/core";
 
 ui.column({ gap: 1 }, [
   ui.text("Build failed", { style: { fg: rgb(255, 110, 110), bold: true } }),
   ui.text(state.path, { textOverflow: "middle", maxWidth: 40 }),
+  ui.text(state.longPath, { textOverflow: "start" }), // keeps tail, e.g. "…src/index.ts"
 ]);
 ```
 
+### 4b) Layout measurement
+
+Ink's `measureElement` ref has a direct equivalent: `app.measureElement(id)` returns the computed `Rect` (`{ x, y, w, h }`) for any widget by its `id`, or `null` if not found.
+
+```typescript
+const rect = app.measureElement("sidebar");
+if (rect) console.log(`sidebar is ${rect.w}x${rect.h} at (${rect.x},${rect.y})`);
+```
+
 ### 5) Forms
 
 Use controlled `input` widgets and validate in update handlers, not during render.

docs/widgets/text.md

@@ -22,7 +22,7 @@ ui.text("Caption", { variant: "caption", textOverflow: "ellipsis" }); // pass Te
 | `key` | `string` | - | Reconciliation key for lists |
 | `style` | `TextStyle` | - | Style applied to this text |
 | `variant` | `"body" \| "heading" \| "caption" \| "code" \| "label"` | `"body"` | Predefined styling intent |
-| `textOverflow` | `"clip" \| "ellipsis" \| "middle"` | `"clip"` | How to handle overflow |
+| `textOverflow` | `"clip" \| "ellipsis" \| "middle" \| "start"` | `"clip"` | How to handle overflow |
 | `maxWidth` | `number` | - | Maximum width (cells) for overflow handling |
 | `wrap` | `boolean` | `false` | Wrap text into multiple lines using cell-width-aware line breaking |
 
@@ -59,7 +59,20 @@ ui.box({ width: 24, border: "single", p: 1 }, [
 ]);
 ```
 
-### 4) Wrapped multiline text
+### 4) Start truncation
+
+Keeps the tail of the string, prepending an ellipsis. Useful for file paths where the significant part is at the end.
+
+```typescript
+import { ui } from "@rezi-ui/core";
+
+ui.box({ width: 30, border: "single", p: 1 }, [
+  ui.text("/home/user/documents/project/src/index.ts", { textOverflow: "start" }),
+]);
+// renders: "…uments/project/src/index.ts"
+```
+
+### 5) Wrapped multiline text
 
 ```typescript
 import { ui } from "@rezi-ui/core";

packages/core/src/app/createApp.ts

@@ -2040,6 +2040,11 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
       return terminalProfile;
     },
 
+    measureElement(id: string): Rect | null {
+      if (mode !== "widget") return null;
+      return widgetRenderer.getRectByIdIndex().get(id) ?? null;
+    },
+
     ...(routerIntegration ? { router: routerIntegration.router } : {}),
   };
 

packages/core/src/app/inspectorOverlayHelper.ts

@@ -300,6 +300,9 @@ export function createAppWithInspectorOverlay<S>(
     getTerminalProfile() {
       return app.getTerminalProfile();
     },
+    measureElement(id: string) {
+      return app.measureElement(id);
+    },
     ...(app.router ? { router: app.router } : {}),
     inspectorOverlay: controller,
   };

packages/core/src/app/types.ts

@@ -62,5 +62,7 @@ export interface App<S> {
   getBindings(mode?: string): readonly RegisteredBinding[];
   readonly pendingChord: string | null;
   getTerminalProfile(): TerminalProfile;
+  /** Return the computed layout rect for a widget by its `id`, or `null` if not found. */
+  measureElement(id: string): Rect | null;
   readonly router?: RouterApi;
 }

packages/core/src/index.ts

@@ -65,6 +65,7 @@ export {
   measureTextCells,
   truncateWithEllipsis,
   truncateMiddle,
+  truncateStart,
   clearTextMeasureCache,
   getTextMeasureCacheSize,
   setTextMeasureEmojiPolicy,
@@ -503,6 +504,12 @@ export {
 } from "./widgets/virtualList.js";
 export { rgb, type Rgb, type TextStyle } from "./widgets/style.js";
 
+// =============================================================================
+// Layout Types
+// =============================================================================
+
+export type { Rect, Size, Axis } from "./layout/types.js";
+
 // =============================================================================
 // Spacing Scale
 // =============================================================================

packages/core/src/layout/__tests__/textMeasure.truncate.unicode.test.ts

@@ -1,5 +1,10 @@
 import { assert, describe, test } from "@rezi-ui/testkit";
-import { measureTextCells, truncateMiddle, truncateWithEllipsis } from "../textMeasure.js";
+import {
+  measureTextCells,
+  truncateMiddle,
+  truncateStart,
+  truncateWithEllipsis,
+} from "../textMeasure.js";
 
 function hasUnpairedSurrogate(text: string): boolean {
   for (let i = 0; i < text.length; i++) {
@@ -51,4 +56,62 @@ describe("unicode-safe truncation", () => {
     assert.equal(hasUnpairedSurrogate(result), false);
     assert.ok(measureTextCells(result) <= 4);
   });
+
+  test("truncateStart does not split surrogate pairs", () => {
+    const result = truncateStart("A😀B", 3);
+    assert.equal(result, "…B");
+    assert.equal(hasUnpairedSurrogate(result), false);
+    assert.ok(measureTextCells(result) <= 3);
+  });
+
+  test("truncateStart does not split ZWJ emoji clusters", () => {
+    const family = "👨‍👩‍👧‍👦";
+    const result = truncateStart(`Z${family}`, 2);
+    assert.equal(hasUnpairedSurrogate(result), false);
+    assert.ok(measureTextCells(result) <= 2);
+  });
+});
+
+describe("truncateStart", () => {
+  test("returns full text when it fits", () => {
+    assert.equal(truncateStart("abcd", 4), "abcd");
+    assert.equal(truncateStart("abcd", 10), "abcd");
+  });
+
+  test("empty string returns empty", () => {
+    assert.equal(truncateStart("", 5), "");
+  });
+
+  test("width=0 returns empty", () => {
+    assert.equal(truncateStart("abcdef", 0), "");
+  });
+
+  test("width=1 returns only ellipsis", () => {
+    assert.equal(truncateStart("abcdef", 1), "…");
+  });
+
+  test("width=2 keeps one trailing char", () => {
+    assert.equal(truncateStart("abcdef", 2), "…f");
+  });
+
+  test("width=3 keeps two trailing chars", () => {
+    assert.equal(truncateStart("abcdef", 3), "…ef");
+  });
+
+  test("width=5 keeps four trailing chars", () => {
+    assert.equal(truncateStart("abcdef", 5), "…cdef");
+  });
+
+  test("CJK wide chars counted as 2 cells", () => {
+    // "你好世界" = 4 chars, 8 cells
+    const result = truncateStart("你好世界", 5);
+    assert.equal(result, "…世界");
+    assert.ok(measureTextCells(result) <= 5);
+  });
+
+  test("mixed ASCII and CJK", () => {
+    const result = truncateStart("ab你好cd", 5);
+    assert.equal(result, "…好cd");
+    assert.ok(measureTextCells(result) <= 5);
+  });
 });

packages/core/src/layout/textMeasure.ts

@@ -618,6 +618,39 @@ export function truncateWithEllipsis(text: string, maxWidth: number): string {
  * // "/home/user/…/src/index.ts"
  * ```
  */
+/**
+ * Truncate text from the start, preserving the end.
+ * Useful for file paths and URLs where the tail is most important.
+ *
+ * @param text - The text to truncate
+ * @param maxWidth - Maximum width in terminal cells
+ * @returns Truncated text with ellipsis at start, or original if it fits
+ *
+ * @example
+ * ```typescript
+ * truncateStart("/home/user/documents/project/src/index.ts", 20)
+ * // "…ject/src/index.ts"
+ * ```
+ */
+export function truncateStart(text: string, maxWidth: number): string {
+  const fullWidth = measureTextCells(text);
+  if (fullWidth <= maxWidth) return text;
+  if (maxWidth <= 0) return "";
+  if (maxWidth === 1) return "…";
+
+  // Reserve 1 cell for ellipsis
+  const targetWidth = maxWidth - 1;
+  if (targetWidth <= 0) return "…";
+
+  const { starts, prefixWidths } = collectGraphemeSlices(text);
+  const clusterCount = starts.length;
+  const endClusters = maxSuffixClustersWithinWidth(prefixWidths, targetWidth);
+  if (endClusters === 0) return "…";
+  const endStartCluster = clusterCount - endClusters;
+  const endStart = starts[endStartCluster] ?? text.length;
+  return `…${text.slice(endStart)}`;
+}
+
 export function truncateMiddle(text: string, maxWidth: number): string {
   const fullWidth = measureTextCells(text);
   if (fullWidth <= maxWidth) return text;

packages/core/src/renderer/__tests__/renderer.text.test.ts

@@ -620,6 +620,58 @@ describe("renderer text - truncation boundaries", () => {
     assert.equal(expectSingleDrawText(frame).text, "ab…");
   });
 
+  test("start truncation width=5 keeps tail", () => {
+    const frame = parseFrame(
+      renderBytes(textVNode("abcdef", { textOverflow: "start", maxWidth: 5 }), {
+        cols: 20,
+        rows: 1,
+      }),
+    );
+    assert.equal(expectSingleDrawText(frame).text, "…cdef");
+  });
+
+  test("start truncation width=3 keeps two trailing chars", () => {
+    const frame = parseFrame(
+      renderBytes(textVNode("abcdef", { textOverflow: "start", maxWidth: 3 }), {
+        cols: 20,
+        rows: 1,
+      }),
+    );
+    assert.equal(expectSingleDrawText(frame).text, "…ef");
+  });
+
+  test("start truncation width=1 is only ellipsis", () => {
+    const frame = parseFrame(
+      renderBytes(textVNode("abcdef", { textOverflow: "start", maxWidth: 1 }), {
+        cols: 20,
+        rows: 1,
+      }),
+    );
+    assert.equal(expectSingleDrawText(frame).text, "…");
+  });
+
+  test("start truncation width=0 produces no text command", () => {
+    const frame = parseFrame(
+      renderBytes(textVNode("abcdef", { textOverflow: "start", maxWidth: 0 }), {
+        cols: 20,
+        rows: 1,
+      }),
+    );
+    assert.equal(frame.drawTexts.length, 0);
+    assert.equal(frame.drawTextRuns.length, 0);
+    assert.equal(frame.strings.length, 0);
+  });
+
+  test("start truncation exact boundary keeps full text", () => {
+    const frame = parseFrame(
+      renderBytes(textVNode("abcd", { textOverflow: "start", maxWidth: 4 }), {
+        cols: 20,
+        rows: 1,
+      }),
+    );
+    assert.equal(expectSingleDrawText(frame).text, "abcd");
+  });
+
   test("text longer than viewport width uses clip and keeps full source string", () => {
     const source = "0123456789";
     const frame = parseFrame(renderBytes(textVNode(source), { cols: 5, rows: 1 }));