Skip to content

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

TypeScript
4.2 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
export const docs = {
  name: 'useInteractiveRole',
  displayName: 'useInteractiveRole',
  keywords: [
    'role',
    'polymorphic',
    'link',
    'button',
    'inert',
    'href',
    'onClick',
    'element type',
    'as',
    'trigger',
    'semantics',
    'accessibility',
    'a11y',
  ],
  params: [
    {
      name: 'options',
      type: 'UseInteractiveRoleOptions',
      description: 'The interactivity inputs the component received.',
      required: true,
    },
    {
      name: 'options.href',
      type: 'string',
      description:
        'URL for navigation. Highest priority: with an href the component is a link.',
    },
    {
      name: 'options.onClick',
      type: '((...args: never[]) => unknown) | null',
      description:
        'Click handler. Resolves to a button, ahead of any context-provided role.',
    },
    {
      name: 'options.isDisabled',
      type: 'boolean',
      description:
        'When true, href is ignored for role resolution (a disabled link is an anti-pattern), so the role comes from onClick, then context, then inert.',
      default: 'false',
    },
  ],
  returns: [
    {
      name: 'role',
      type: "'link' | 'button' | 'inert'",
      description:
        'The element the component should render: an anchor, a button, or a non-interactive span/div.',
    },
  ],
  usage: {
    description:
      'Resolves what a polymorphic component should render as, in one place: href wins, then onClick, then an interactive trigger context supplied by a parent (Popover, DropdownMenu and friends), then inert. Use it in any component that is sometimes a link, sometimes a button, and sometimes plain content; Token, Thumbnail, Item and ClickableCard all do. Because context is part of the resolution, a component built on it becomes a valid trigger for new surfaces without changing.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Switch on the returned role to pick the element, and render an anchor only for "link" so keyboard and middle-click behavior come from the platform.',
      },
      {
        guidance: true,
        description:
          'Pass isDisabled through rather than dropping the href yourself; the hook already keeps disabled links out of the tab order.',
      },
      {
        guidance: false,
        description:
          'Add another ad-hoc href/onClick precedence check in a component; new trigger contexts are added here so every consumer inherits them.',
      },
    ],
  },
  relatedComponents: ['Token', 'Thumbnail', 'Item', 'ClickableCard'],
  relatedHooks: ['useClickableContainer'],
  importPath: '@astryxdesign/core/hooks',
  category: 'interaction',
};

/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
export const docsDense = {
  description:
    'Resolves what a polymorphic component renders as: href -> link, onClick -> button, interactive trigger context -> its role, else inert. Single place the precedence lives.',
  paramDescriptions: {
    options: 'interactivity inputs the component received.',
    'options.href': 'navigation URL; highest priority.',
    'options.onClick': 'click handler; button, ahead of context role.',
    'options.isDisabled':
      'true = href ignored for resolution (disabled link is anti-pattern); falls to onClick / context / inert.',
  },
  returnDescriptions: {
    role: "element to render: 'link' (anchor), 'button', or 'inert' (span/div).",
  },
  usage: {
    description:
      'For components that are sometimes link, sometimes button, sometimes plain content (Token, Thumbnail, Item, ClickableCard). Context-aware, so consumers become valid triggers for new surfaces w/o changing.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Switch on returned role; render a real anchor for "link" so platform keyboard / middle-click behavior applies.',
      },
      {
        guidance: true,
        description:
          'Pass isDisabled through instead of dropping href yourself.',
      },
      {
        guidance: false,
        description:
          'Re-implement href/onClick precedence per component; new trigger contexts are added here.',
      },
    ],
  },
};