Skip to content

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

TypeScript
5.3 KB
Raw Blame
// 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.',
      },
    ],
  },
};