Skip to content

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

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

/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
export const docs = {
  name: 'useIcon',
  displayName: 'useIcon',
  group: 'Icon',
  keywords: [
    'icon',
    'semantic icon',
    'theme icons',
    'icon registry',
    'getIcon',
    'registerIcons',
    'success',
    'warning',
    'error',
  ],
  params: [
    {
      name: 'name',
      type: 'IconName | NamespacedIconName',
      description:
        "Semantic icon name, such as 'success', 'warning' or 'close', or a namespaced extension key such as 'richtext:bold'. Both resolve through the same registry.",
      required: true,
    },
  ],
  returns: [
    {
      name: 'icon',
      type: 'ReactNode',
      description:
        "The icon for that name from the nearest Theme's icons (or, outside any Theme, from the registered theme the document root names), else from registerIcons() overrides, else the built-in default. A function entry is read at {size: 'md'}.",
    },
  ],
  usage: {
    description:
      "Resolves a semantic icon name to a React node through the nearest Theme, so a custom component draws the same success, warning or error icon that Astryx components draw and follows a theme that overrides it. Resolution reads the nearest Theme's icons (outside any Theme, the registered theme the document root names), then registerIcons() overrides, then the built-in default. The node is returned as is, with no size or color wrapper: the built-in icons are 1em squares in currentColor, so they follow the surrounding text. A function entry is read at {size: 'md'}. Render <Icon icon={name} /> instead when the icon needs another size, a color or a label.",
    bestPractices: [
      {
        guidance: true,
        description:
          'Use it in a custom component that places a semantic icon itself, so a Theme that overrides the icon changes the component too.',
      },
      {
        guidance: true,
        description:
          'Render <Icon icon={name} /> when the icon needs a size other than md, a color, or an accessible label.',
      },
      {
        guidance: false,
        description:
          'Import a specific icon library glyph for a semantic purpose that a theme should control, such as a success or error state.',
      },
    ],
  },
  relatedComponents: ['Icon', 'Theme'],
  relatedHooks: ['useTheme'],
  importPath: '@astryxdesign/core/Icon',
  category: 'utilities',
};

/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
export const docsDense = {
  description:
    "Resolves a semantic icon name to a React node via the nearest Theme, so custom components draw the same icons as Astryx components and follow theme overrides. Fallback: nearest Theme icons (outside any Theme, the root's registered theme), registerIcons() overrides, built-in default. Node returned as is (built-ins are 1em, currentColor). Function entries read at {size: 'md'}. Use <Icon icon={name} /> for another size, a color or a label.",
  paramDescriptions: {
    name: "semantic icon name ('success', 'close') or namespaced key ('richtext:bold'); same registry.",
  },
  returnDescriptions: {
    icon: "icon node from nearest Theme (outside any Theme, the root's registered theme), else registerIcons() overrides, else built-in default; function entries read at {size: 'md'}.",
  },
  usage: {
    description:
      "Semantic icon name to React node via nearest Theme; custom components follow theme icon overrides. Fallback: nearest Theme (or root's registered theme), registerIcons(), built-in. No size/color wrapper; function entries read at {size: 'md'}. Use <Icon icon={name} /> for other sizes, color or a label.",
    bestPractices: [
      {
        guidance: true,
        description:
          'Use in custom components that place a semantic icon, so Theme overrides reach them.',
      },
      {
        guidance: true,
        description:
          'Render <Icon icon={name} /> for a non-md size, a color, or an accessible label.',
      },
      {
        guidance: false,
        description:
          'Import a library glyph for a semantic purpose a theme should control (success, error).',
      },
    ],
  },
};