Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(useLinkify): add hook docs and a comment-thread example block (#9969)

Sleep8hc5cc8f4c4344
diff --git a/.changeset/hook-doc-use-linkify.md b/.changeset/hook-doc-use-linkify.md
new file mode 100644
index 0000000000..467c97095f
--- /dev/null
+++ b/.changeset/hook-doc-use-linkify.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[docs] Hook docs for `useLinkify`, so `astryx hook useLinkify` and `astryx search` return it, and a `useLinkify — Links in a Comment Thread` example block: plain-text comments where the URL and email become Links and a custom `#123` issue-reference pattern shows the patterns option, while a comment without matches stays plain.
+
+@LetMeSleep8h
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 40989e4d0b..d89a915d33 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -818,6 +818,7 @@
"/templates/useInteractiveRoleHookUsage/",
"/templates/useKeyboardHintHookUsage/",
"/templates/useLinkComponentHookUsage/",
+ "/templates/useLinkifyHookUsage/",
"/templates/useListFocusHookUsage/",
"/templates/useLocaleHookUsage/",
"/templates/useMergedRefsHookUsage/",
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index f780c10a63..fe8df1773c 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3836,6 +3836,11 @@
"path": "examples/use-link-component/article-cards",
"aliases": []
},
+ {
+ "name": "example-use-linkify-links-in-a-comment-thread",
+ "path": "examples/use-linkify/links-in-a-comment-thread",
+ "aliases": []
+ },
{
"name": "example-use-list-focus-recent-files",
"path": "examples/use-list-focus/recent-files",
@@ -4206,6 +4211,11 @@
"path": "hooks/use-link-component",
"aliases": []
},
+ {
+ "name": "hook-use-linkify",
+ "path": "hooks/use-linkify",
+ "aliases": []
+ },
{
"name": "hook-use-list-focus",
"path": "hooks/use-list-focus",
diff --git a/packages/cli/api/component/__fixtures__/resolutions/modules.txt b/packages/cli/api/component/__fixtures__/resolutions/modules.txt
index 79773ba1be..ac56858871 100644
--- a/packages/cli/api/component/__fixtures__/resolutions/modules.txt
+++ b/packages/cli/api/component/__fixtures__/resolutions/modules.txt
@@ -271,7 +271,7 @@ useIsomorphicLayoutEffect useIsomorphicLayoutEffect hooks/useAnimatedLayout.doc.
useLayerDismissal useLayerDismissal Layer/Layer.doc.mjs Layer/useLayerDismissal.ts
useLightbox useLightbox Lightbox/useLightbox.doc.mjs Lightbox/useLightbox.tsx
useLinkComponent useLinkComponent Link/useLinkComponent.doc.mjs Link/useLinkComponent.ts
-useLinkify useLinkify Link/Link.doc.mjs Link/useLinkify.tsx
+useLinkify useLinkify Link/useLinkify.doc.mjs Link/useLinkify.tsx
useListFormatter useListFormatter i18n/InternationalizationProvider.doc.mjs i18n/useListFormatter.ts
useMenuDrillIn useMenuDrillIn DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/useMenuDrillIn.tsx
useMenuHover useMenuHover hooks/useAnimatedLayout.doc.mjs hooks/useMenuHover.ts
diff --git a/packages/cli/api/template/use-linkify-hook-usage.test.tsx b/packages/cli/api/template/use-linkify-hook-usage.test.tsx
new file mode 100644
index 0000000000..9322ba2cb0
--- /dev/null
+++ b/packages/cli/api/template/use-linkify-hook-usage.test.tsx
@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @vitest-environment jsdom
+
+/**
+ * The useLinkify example turns plain-text comments into mixed text and links:
+ * the URL and the email each become a Link, the #123/#456 references become
+ * tracker links via the custom pattern, and the comment without matches
+ * renders no link at all.
+ */
+
+import {act} from 'react';
+import {createRoot, type Root} from 'react-dom/client';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import UseLinkifyHookUsage from '../../assets/templates/blocks/components/Link/useLinkifyHookUsage';
+
+(globalThis as {IS_REACT_ACT_ENVIRONMENT?: boolean}).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+let root: Root | null = null;
+let container: HTMLElement;
+
+beforeEach(() => {
+ vi.stubGlobal(
+ 'matchMedia',
+ (query: string) =>
+ ({
+ matches: false,
+ media: query,
+ onchange: null,
+ addListener: () => {},
+ removeListener: () => {},
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ dispatchEvent: () => false,
+ }) as unknown as MediaQueryList,
+ );
+ container = document.createElement('div');
+ document.body.appendChild(container);
+});
+
+afterEach(() => {
+ act(() => root?.unmount());
+ root = null;
+ container.remove();
+ vi.unstubAllGlobals();
+});
+
+describe('useLinkifyHookUsage example', () => {
+ it('links URLs, emails and issue references in plain comments', () => {
+ root = createRoot(container);
+ act(() => root!.render(<UseLinkifyHookUsage />));
+
+ const links = Array.from(
+ container.querySelectorAll('a'),
+ ) as Array<HTMLAnchorElement>;
+ const hrefs = links.map(link => link.getAttribute('href') ?? '');
+
+ // Built-in URL detection, external.
+ expect(hrefs).toContain('https://example.com/spec');
+ // Built-in email detection, mailto.
+ expect(hrefs).toContain('mailto:[email protected]');
+ // Custom issue pattern: capture group mapped onto the tracker scheme.
+ expect(hrefs).toContain('https://example.com/issues/123');
+ expect(hrefs).toContain('https://example.com/issues/456');
+
+ // Exactly the four detected links, nothing more: the plain comment adds none.
+ expect(links).toHaveLength(4);
+ });
+});
diff --git a/packages/cli/assets/templates/blocks/components/Link/useLinkifyHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Link/useLinkifyHookUsage.doc.mjs
new file mode 100644
index 0000000000..7d022804c4
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Link/useLinkifyHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useLinkify',
+ name: 'useLinkify — Links in a Comment Thread',
+ displayName: 'useLinkify — Links in a Comment Thread',
+ description:
+ 'Plain-text comments where useLinkify turns the URL and the email address into Links, and a custom pattern turns issue references like #123 into tracker links — the patterns option in action. The comment without matches stays plain text.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Link', 'Layout', 'Text'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Link/useLinkifyHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Link/useLinkifyHookUsage.tsx
new file mode 100644
index 0000000000..dfb9278d60
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Link/useLinkifyHookUsage.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useLinkify, type LinkifyPattern} from '@astryxdesign/core/Link';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+const COMMENTS = [
+ 'See https://example.com/spec or email [email protected].',
+ 'Fixed by #123, tracking the regression in #456.',
+ 'No links here, just a plain note.',
+];
+
+// Issue references like #123 link into the tracker; the capture group maps
+// onto its URL scheme, showing the patterns option.
+const ISSUE_PATTERN: LinkifyPattern = {
+ pattern: /#(\d+)/g,
+ href: match => `https://example.com/issues/${match[1]}`,
+};
+
+function Comment({children}: {children: string}) {
+ const nodes = useLinkify(children, {patterns: [ISSUE_PATTERN]});
+ return (
+ <Text type="body" color="secondary">
+ {nodes}
+ </Text>
+ );
+}
+
+export default function UseLinkifyHookUsage() {
+ return (
+ <VStack gap={3} style={{width: '100%', maxWidth: 360}}>
+ {COMMENTS.map(comment => (
+ <Comment key={comment}>{comment}</Comment>
+ ))}
+ </VStack>
+ );
+}
diff --git a/packages/core/src/Link/useLinkify.doc.mjs b/packages/core/src/Link/useLinkify.doc.mjs
new file mode 100644
index 0000000000..d14261b196
--- /dev/null
+++ b/packages/core/src/Link/useLinkify.doc.mjs
@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+ name: 'useLinkify',
+ displayName: 'useLinkify',
+ keywords: [
+ 'linkify',
+ 'link',
+ 'autolink',
+ 'url',
+ 'email',
+ 'mailto',
+ 'plain text',
+ 'custom pattern',
+ 'issue reference',
+ 'LinkProvider',
+ 'routing',
+ ],
+ params: [
+ {
+ name: 'text',
+ type: 'string',
+ description:
+ 'The plain text to scan. Empty text returns a single-element array of itself.',
+ required: true,
+ },
+ {
+ name: 'options',
+ type: 'UseLinkifyOptions',
+ description: 'Configuration object.',
+ required: false,
+ },
+ {
+ name: 'options.patterns',
+ type: 'LinkifyPattern[]',
+ description:
+ 'Custom patterns to detect, in addition to (or, with hasBuiltins false, replacing) the built-in URL and email detection. Each pattern is a global-flag regex plus an href builder (capture groups available) and an optional label builder and isExternal flag. When matches overlap, the earliest one wins; at the same start, custom patterns win over the built-in ones.',
+ required: false,
+ },
+ {
+ name: 'options.hasBuiltins',
+ type: 'boolean',
+ description:
+ 'Include the built-in http(s) URL and email detection. Default true; set false when patterns should fully define what links.',
+ default: 'true',
+ required: false,
+ },
+ ],
+ returns: [
+ {
+ name: '(return value)',
+ type: 'ReactNode[]',
+ description:
+ 'The text as a mix of plain strings and Link elements, one per match, ready to render inside a text container. Matched URLs open externally (isExternal), emails link as mailto:, and every link renders through Link — so a LinkProvider routes clicks client-side the same as a hand-written Link.',
+ },
+ ],
+ usage: {
+ description:
+ 'Finds URLs, email addresses and custom patterns in plain text and returns React nodes with a Link for each match; the links respect LinkProvider for client-side routing. Use it wherever user- or tool-authored plain text should grow safe, styled links without pre-parsing it into markup: activity feeds, comment threads, description fields. Custom patterns turn project-specific references (issue numbers like #123, ticket IDs) into links by supplying a regex plus an href builder — e.g. an issue tracker pattern that maps captures onto its URL scheme. When matches overlap, the earliest one wins, and at the same start a custom pattern wins over the built-in ones, so a custom #123 pattern coexists with URL detection in the same string.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Render the returned nodes directly inside a text container (<p>{nodes}</p>); the hook already interleaves the unmatched plain text.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Wrap the app (or the region) in LinkProvider so detected links route client-side instead of full-page navigating.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Give a custom pattern the global flag (g). Without it the scan never advances, and when the text contains a match the render never finishes.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Pre-parse the text into your own markup before linkifying — the hook exists so the plain string can be rendered as-is with links composed in.',
+ },
+ ],
+ },
+ relatedComponents: ['Link', 'LinkProvider'],
+ importPath: '@astryxdesign/core',
+ category: 'link',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+ description:
+ 'Finds URLs, emails and custom patterns in plain text; returns ReactNode[] interleaving plain strings and Link elements that respect LinkProvider routing. Built-in URL/email detection, custom global-regex patterns with href/label builders, overlaps resolved earliest-match-first (custom wins at the same start).',
+ paramDescriptions: {
+ text: 'plain text to scan; empty returns [text].',
+ options: 'config object.',
+ 'options.patterns':
+ 'custom LinkifyPatterns added before the builtins; each is a /g regex + href builder (+ optional label, isExternal).',
+ 'options.hasBuiltins':
+ 'include built-in URL/email detection (default true).',
+ },
+ returnDescriptions: {
+ '(return value)':
+ 'mixed plain strings and Link elements, ready inside a text container; URLs external, emails mailto:, all via Link/LinkProvider.',
+ },
+ usage: {
+ description:
+ 'Grow safe styled links in plain authored text (feeds, comments, descriptions) without pre-parsing. Custom patterns map project references (#123, ticket IDs) onto a URL scheme via capture groups. Overlaps: earliest match wins; custom wins at the same start.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Render the nodes as-is; plain text is already interleaved.',
+ },
+ {
+ guidance: true,
+ description: 'LinkProvider around the region for client-side routing.',
+ },
+ {guidance: true, description: 'Custom patterns need the g flag.'},
+ {
+ guidance: false,
+ description: 'Pre-parse text into markup before linkifying.',
+ },
+ ],
+ },
+};