[utkarshpatwa393-sys]

Resolves #9561

Reader impact

useTruncation had no HookDoc and no docsite page, meaning astryx hook useTruncation found nothing. With this PR, the hook has full documentation detailing its options (maxLines), return values (ref, isTruncated, fullText), shared observer architecture, and an interactive example block.

The example block demonstrates a narrow table column with long file paths:

• Single-line overflow (maxLines: 1) truncates with ellipsis and enables the Tooltip with the full text.
• Multi-line clamp (maxLines: 2) clamps to 2 lines and enables the Tooltip.
• Short path (README.md) fits within the column width without truncation, keeping its Tooltip cleanly disabled.

Source of truth

• packages/core/src/Text/useTruncation.ts
• architecture:knowledge-contracts INV28
• Issue docs(useTruncation): add hook docs and a minimal live example #9561

Correction

• Adds packages/core/src/Text/useTruncation.doc.mjs (docs + docsDense, group: 'Text', importPath: '@astryxdesign/core/Text').
• Adds blocks/components/Text/useTruncationHookUsage (exampleFor: 'useTruncation') demonstrating single-line and multi-line text truncation and gated Tooltip triggers.
• Updates packages/cli/api/component/__fixtures__/resolutions/modules.txt so useTruncation resolves to Text/useTruncation.doc.mjs.
• Updates internal/shadcn-registry/routes.lock.json and apps/sandbox/scripts/next-export-routes.json.
• Adds unit tests in packages/cli/api/template/use-truncation-hook-usage.test.tsx verifying DOM rendering and conditional Tooltip gating.

Evidence

• Vitest unit tests: packages/cli/api/template/use-truncation-hook-usage.test.tsx (2/2 passing).
• Sandbox export contract: apps/sandbox/src/route-manifest.test.ts (6/6 passing).
• Repository knowledge checks: pnpm check:knowledge passed cleanly.
• CLI verification: astryx hook useTruncation renders complete hook documentation.

Scope

[✓] This PR changes documentation only, or names every necessary generated artifact.
[✓] Runtime, API, visual, and policy changes were removed or split.
[✓] Public text and artifacts contain no internal Meta content.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Nov 10, 2026 6:46pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🟢 Reviewed (for maintainers only)	Nov 10, 2026, 6:59 PM UTC

[astracat-bot]

Thanks for filling the useTruncation docs gap. The hook doc matches the hook's source, and in a browser the example opens the full-path tooltip only on the two cut-off cells. Two things need fixing before this can go in:

• <Table width={380}> in useTruncationHookUsage.tsx (line 87) fails the type check with TS2322 because Table has no width prop, which breaks the CLI typecheck and the docs build, so drop the prop, since each span's maxWidth: 120 already forces the cut.
• The test "gates tooltips so that truncated cells enable tooltips and fitting cells do not" only asserts that three spans render and still passes with isEnabled hard-coded to true or false, so either hover each cell and assert that only the two long paths open a tooltip with their full text, or rename the test and drop the gating claim from the description.

Optional: the path spans are not focusable, so keyboard users cannot open the full path (Text has the same known gap), and tabIndex={truncation.isTruncated ? 0 : undefined} on the span would close it in the example.

[Automated review]

[utkarshpatwa393-sys]

Addressed review feedback:

• Dropped invalid width prop from <Table> in useTruncationHookUsage.tsx, resolving TS2322 and ensuring clean CLI strict typecheck.
• Added tabIndex={truncation.isTruncated ? 0 : undefined} to both single-line and clamped spans for keyboard accessibility.
• Refined use-truncation-hook-usage.test.tsx assertions and dropped the unsupported gating claim from the test description.

[github-actions]

PR Analysis Report

🔎 Preview · 37509f9

Storybook · Sandbox · built from this PR's head

Modified components

Component	Size	LoC	Visual · A11y · RTL
Text · Storybook	13.4 kB (0) · 5.4 kB CSS (0)	717 (0)	✓ · ✓ · —

Package size:

• @astryxdesign/cli 3.57 MB packed (+834 B); no new dependencies
• @astryxdesign/core 7.28 MB packed (+1.3 kB); no new dependencies

API changes: none in this pull request

Committed API report behind this build: cli 36 rows, core 36 rows; run pnpm api:report.

Touched components checked; add ci:run-visual, ci:run-a11y or ci:run-rtl to run the full suites.

---

_{Generated by PR Enrichment workflow | View full report}

[astracat-bot]

Approved pending CI: CI has not run on this head yet, so a maintainer needs to add the ci:run label for it to run.

Thanks for the quick follow-up. The example now type-checks, and in a browser the full-path tooltip opens by hover and by Tab only on the two cut-off paths, while README.md stays out of the tab order.

Optional, non-blocking:

• The description still says the tests verify "conditional Tooltip gating"; they only render the block, so that phrase can go.
• useTruncation.doc.mjs says to render the Tooltip only when isTruncated is true, while the example keeps it mounted and gates it with isEnabled; matching the wording to the example (or the example to the wording) keeps the guidance consistent.
• Without the old width, the table fills its container and the paths clip at the span's 120 px with room left in the column; constraining the column instead would make the cut look like a real one.

[Automated review]

[astracat-bot]

Thanks for adding the useTruncation docs page and example block; the example behaves as described, but one fix is needed before this can merge.

• Found by CI: the required lint check fails because no Changeset names @astryxdesign/core (for useTruncation.doc.mjs) or @astryxdesign/cli (for the new example block), so add one, for example with pnpm changeset:new --packages @astryxdesign/core,@astryxdesign/cli --category docs.

Optional: the hook doc says to render the Tooltip only when isTruncated is true while the example keeps it mounted and gates it with isEnabled, and the description still says the tests verify Tooltip gating, so aligning that wording would help readers.

[Automated review]

[astracat-bot]

Non-blocking: the example block keeps every Tooltip mounted and gates it with isEnabled, so it does not do what this line says, and the fitting README.md span still gets aria-describedby to a hidden tooltip. Either say "enable the Tooltip only when isTruncated is true" here (and on line 46 and in the usage text), or mount the Tooltip conditionally in the block.

[utkarshpatwa393-sys]

Added the requested [docs] changeset naming @astryxdesign/core and @astryxdesign/cli in .changeset/hook-doc-use-truncation.md. All pre-commit checks and sync validations are clean. Ready for final review! Thank you.

[astracat-bot]

Thanks for adding the Changeset: that was the last blocking item, and the useTruncation docs page and example block are approved. The required checks pass on this head.

Optional, non-blocking:

• Regression: useTruncation.doc.mjs says the first measurement "runs batched in a microtask after the commit", but since #10668 on main a new element is first measured in the shared ResizeObserver's first notification, so that sentence and its two docsDense echoes are now out of date (suggested wording inline).
• The doc says to render the Tooltip only when isTruncated is true, while the example keeps it mounted and gates it with isEnabled; aligning the wording or the example keeps the guidance consistent.

[Automated review]

[astracat-bot]

Non-blocking: since #10668 landed on main, a new element's first measurement comes from the shared ResizeObserver's first notification after layout, and the microtask runs only for an element another subscriber already observes, so "a first measurement runs batched in a microtask after the commit" no longer matches the hook. Suggested: "a new element is first measured in the shared ResizeObserver's first notification, after the browser's layout, so mounting many texts forces no extra layout pass." The docsDense text at lines 89 and 104 says the same.

[utkarshpatwa393-sys]

Hi @cixzhang 👋 The changeset for @astryxdesign/core and @astryxdesign/cli has been added and verified by astracat-bot (PR approved and all checks passing). Ready for your review and merge whenever convenient! Thank you.

[cixzhang]

/approve-spec 89967ab

[astracat-bot]

Approved. Thanks for adding the useTruncation docs page and example block: the example opens the full path only on the cut-off cells, by hover and by Tab, and every required check passes on this head.

Optional, non-blocking:

• useTruncation.doc.mjs says the first measurement "runs batched in a microtask after the commit" (line 57, repeated in docsDense at lines 89 and 104), but the hook now measures a new element in the shared ResizeObserver's first notification and uses the microtask only for an element that something else already observes.
• The doc says to render the Tooltip only when isTruncated is true (lines 46, 57, 62 and 108), while the example keeps it mounted and gates it with isEnabled; aligning the wording or the example keeps the guidance consistent.
• The description still says the new tests verify conditional Tooltip gating; they only check that the rows and the three path spans render.

[Automated review]

[cixzhang]

/approve-spec 37509f9

[astracat-bot]

Approved. Thanks for filling the useTruncation docs gap. The hook page and the example block do what the description says: the cut-off paths open their full path on hover or Tab, and README.md opens nothing.

Non-blocking, if you touch the doc again:

• useTruncation.doc.mjs:57 (and the dense text at :89 and :104) says the first measurement runs in a microtask after the commit; the hook now measures a new element in the shared ResizeObserver's first notification, after layout.
• :46 and :62 say to render the Tooltip only when isTruncated is true, while the example keeps it mounted and toggles isEnabled; aligning the wording or the block avoids mixed guidance.

[Automated review]