[MannXo]

Reader impact

useLinkComponent has no HookDoc, so it has no docsite page and astryx hook useLinkComponent finds nothing. After this change it has a page with its parameter, its return value and the as > LinkProvider > anchor order, and an example. Custom Article cards render their title link with the component the hook resolves. Inside a LinkProvider wired to a client-side router the title navigates without a page load and updates the router location, as="a" gives a native anchor even inside that provider, and a card outside the provider falls back to the next provider up or a native anchor. astryx template useLinkComponentHookUsage <path> copies it.

Source of truth

• packages/core/src/Link/useLinkComponent.ts (resolution order, the useMemo per resolved component, the destination check and the to={href} handoff).
• The Link href rule in Link.doc.mjs and the component prop in LinkProvider.doc.mjs, which the new doc refers to rather than restates.
• architecture:knowledge-contracts INV28.

Correction

• Adds packages/core/src/Link/useLinkComponent.doc.mjs (docs + docsDense, group: 'Link', importPath: '@astryxdesign/core/Link'), in the shape useLightbox.doc.mjs uses.
• Adds blocks/components/Link/useLinkComponentHookUsage (exampleFor: 'useLinkComponent'). ArticleCard calls useLinkComponent(linkAs) and renders its title with the result. The example wraps two cards in <LinkProvider component={RouterLink}>, where RouterLink stands in for a router's link: it reads to, prevents the default navigation and sets the router location through a context. The second card passes linkAs="a". A third card sits outside that provider.
• Updates the recorded module resolution for useLinkComponent in packages/cli/api/component/__fixtures__/resolutions/modules.txt (it now opens Link/useLinkComponent.doc.mjs instead of falling back to Link/Link.doc.mjs), as test: main is green again: Tokenizer's sheet-row test passes presentation, and the recorded module resolutions follow core #9851 did for useLightbox.

Evidence

• Real Chromium (Playwright against the docsite dev server, /components/useLinkComponent, 1280x900).

  Click	Router location	Page URL	Same document
  (start)	/	/components/useLinkComponent
  Getting started (provider)	/articles/getting-started	unchanged	yes
  Style guide (PDF) (as="a")	unchanged	#style-guide
  Release notes (outside)	unchanged	#release-notes

  The docsite wraps every page in its own LinkProvider for Next.js Link, so on the docsite the third card resolves to that provider rather than to a bare anchor. Its caption says "the app's LinkProvider, or a native anchor" for that reason. The test below renders the block with no provider above it, where the third card is a native anchor.

• Test (packages/cli/api/template/use-link-component-hook-usage.test.tsx, 3 cases). It clicks each title and asserts whether the default navigation was prevented and where the router location went. With the useLinkComponent call replaced by linkAs ?? 'a', the provider case fails.

Scope

• This PR changes documentation only, or names every necessary generated artifact. The generated artifacts are the block's route and the hook's route in internal/shadcn-registry/routes.lock.json, the block's sandbox route in apps/sandbox/scripts/next-export-routes.json, and the recorded resolution above.
• Runtime, API, visual, and policy changes were removed or split.
• Public text and artifacts contain no internal Meta context.

Testing

• vitest run --project node packages/cli/foundation/discovery packages/cli/api/template packages/cli/assets/templates internal/shadcn-registry apps/sandbox/src/route-manifest.test.ts packages/cli/api/build/tree.test.mjs packages/cli/test/experimental-isolation.test.mjs packages/cli/api/component/resolution-compat.test.mjs packages/cli/api/docs packages/cli/api/hook: 1474 passed, 0 failed.
• vitest run --project ui packages/core/src/docPropLiterals.test.ts packages/core/src/docPropReferences.test.ts: 22 passed.
• apps/docsite: pnpm generate, then vitest run src/__tests__/data-extraction.test.ts src/__tests__/example-coverage.test.ts: 136 passed, 0 failed. The route lock check is clean after UPDATE_SHADCN_ROUTE_LOCK=1 added the two routes.
• pnpm lint:strict: clean (0 errors).
• pnpm -F @astryxdesign/cli typecheck: clean.
• node scripts/release/changeset-coverage.mjs pr --base upstream/main --head HEAD --released v0.7.7: passes. Changeset names @astryxdesign/core and @astryxdesign/cli, patch, [docs].
• .github/scripts/check-public-text.mjs over this commit, title and description: no findings.
• Not run: the full pnpm test suite.

Notes for reviewers

The titles render as the resolved component with no Link styling, since the hook hands back the raw component (as a router's link would be). Wrapping them in Link as={LinkComponent} would style them, but then Link would resolve the component itself and the hook would not be what drives the example.

Fixes #9486

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Nov 4, 2026 7:56am UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🟢 Reviewed (for maintainers only)	Nov 5, 2026, 3:30 PM UTC

[github-actions]

PR Analysis Report

🔎 Preview · e951eb7

Storybook · Sandbox · built from this PR's head

Modified components

Component	Size	LoC	Visual · A11y · RTL
LinkProvider	3.5 kB (0) · 20 B CSS (0)	—	✓ · ✓ · ✗
Link	42.3 kB (0) · 6.9 kB CSS (0)	—	✓ · ✓ · —

Package size:

• @astryxdesign/cli 3.34 MB packed (+956 B); no new dependencies
• @astryxdesign/core 6.31 MB packed (+830 B); no new dependencies

API changes: none in this pull request

Committed API report behind this build: cli 8 rows, theme-butter 1 row, theme-chocolate 1 row, theme-gothic 1 row, theme-matcha 1 row, theme-neutral 1 row, theme-stone 1 row, theme-y2k 1 row; 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. A maintainer needs to add the ci:run label so the required checks run.

The new useLinkComponent hook doc and the Article Cards example meet the hook-example rule: the provider card navigates through the router only because the card calls the hook (with the call replaced by linkAs ?? 'a', that case breaks), and the doc's resolution order, to={href} handoff and destination check match the LinkProvider contract and the hook's source. No changes requested.

[Automated review]