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.mdnew file mode 100644index 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.++@LetMeSleep8hdiff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.jsonindex 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.jsonindex 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.txtindex 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.tsuseLightbox useLightbox Lightbox/useLightbox.doc.mjs Lightbox/useLightbox.tsxuseLinkComponent 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.tsxuseListFormatter useListFormatter i18n/InternationalizationProvider.doc.mjs i18n/useListFormatter.tsuseMenuDrillIn useMenuDrillIn DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/useMenuDrillIn.tsxuseMenuHover useMenuHover hooks/useAnimatedLayout.doc.mjs hooks/useMenuHover.tsdiff --git a/packages/cli/api/template/use-linkify-hook-usage.test.tsx b/packages/cli/api/template/use-linkify-hook-usage.test.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.',+ },+ ],+ },+};