Skip to content

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

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

/**
 * @file globalIconRegistry.tsx
 * @input Theme icon entries (a DefinedTheme or a registered theme name), the
 *   process-wide registry, and built-in defaults
 * @output Exports registerIcons, getIconRegistry, getIcon, getExtendedIcon,
 *   resetIcons, resolveIcon and resolveComponentIcon (internal), IconName,
 *   IconRegistry, IconEntry, IconRequest
 * @position Global and theme-scoped icon registry and component icon slot
 *   resolution; works in server and client environments
 *
 * This module has NO 'use client' directive — it's importable from RSC.
 * Components resolve semantic icons through getIcon() or the client useIcon() hook.
 *
 * An entry is a React node or a pure synchronous function of an
 * {@link IconRequest}. Resolution picks one source — theme entry, then
 * process-wide registration, then built-in default; a nullish static entry
 * falls through — and a selected function's result is final. `Icon` passes
 * its resolved size and a variant the entry can receive (listed by the active
 * theme and, for a theme entry, by the theme that defined it), otherwise
 * `undefined`; the public reads below pass `{size: 'md'}`.
 *
 * `resolveComponentIcon` is the only caller of a theme's `componentIcons`
 * slot functions. It turns a slot, its state, and the component's own
 * fallback into the request the component renders through `Icon`.
 */

import type {ReactNode} from 'react';
import {defaultIcons} from './defaultIcons';
import type {IconSize} from './IconSize.stylex';
import type {
  ComponentIconRequest,
  ComponentIconSlotMap,
  ComponentIconSlotName,
  IconVariant,
} from './index';
import type {DefinedTheme} from '../theme/defineTheme';
import {getRegisteredTheme} from '../theme/themeRegistry';
import {warnOnce} from '../utils/devWarning';

// =============================================================================
// Types
// =============================================================================

/**
 * Semantic icon names used internally by Astryx components.
 *
 * These represent the functional purpose of each icon, not a specific
 * visual representation. Themes provide the actual icon components.
 */
// SYNC: packages/cli/assets/docs/icons.doc.mjs — update USAGE_HINTS when adding names
export type IconName =
  | 'close'
  | 'chevronDown'
  | 'chevronLeft'
  | 'chevronRight'
  | 'chevronsLeft'
  | 'chevronsRight'
  | 'check'
  | 'success'
  | 'error'
  | 'warning'
  | 'info'
  | 'calendar'
  | 'clock'
  | 'externalLink'
  | 'menu'
  | 'moreHorizontal'
  | 'search'
  | 'upload'
  | 'arrowUp'
  | 'arrowDown'
  | 'arrowsUpDown'
  | 'funnel'
  | 'eyeSlash'
  | 'viewColumns'
  | 'copy'
  | 'checkDouble'
  | 'wrench'
  | 'stop'
  | 'microphone';

/**
 * A namespaced extension key, `'<namespace>:<name>'`.
 *
 * This is the tier for a glyph that belongs to one component or library rather
 * than to the system: `'richtext:bold'`, `'numberInput:stepperDown'`. A theme
 * overrides it by key through `registerIcons` or `defineTheme({icons})`,
 * exactly as it overrides a built-in name, and the core {@link IconName} union
 * stays reserved for glyphs the whole system shares.
 *
 * Accepted anywhere a built-in name is, including `<Icon icon>` — which is
 * what lets a namespaced glyph keep `size`, `color` and `xstyle`.
 */
export type NamespacedIconName = `${string}:${string}`;

/**
 * A semantic icon name — either one of the built-in {@link IconName}s or an
 * arbitrary string key contributed by a library/app.
 *
 * The `(string & {})` intersection keeps the built-in names available for
 * autocomplete while still allowing any string, so downstream libraries can
 * register and resolve their own keys (e.g. `'richtext:bold'`) without having
 * to widen the core `IconName` union.
 */
export type ExtendedIconName = IconName | (string & {});

/**
 * A complete icon registry: every semantic name mapped to a React node.
 */
export type IconRegistry = Record<IconName, ReactNode>;

/**
 * What `Icon` asks a function icon entry for: the final Icon size, resolved
 * explicit `size` → owning component's default → `'md'`, and a variant name
 * or `undefined`.
 *
 * Inside `defineTheme`, `Variant` is the theme's listed `iconVariants`; a
 * process-wide registration receives {@link IconVariant}.
 */
export type IconRequest<Variant extends string = IconVariant> = Readonly<{
  size: IconSize;
  variant?: Variant;
}>;

/**
 * A theme or process-wide icon entry: a React node, or a pure synchronous
 * function of the {@link IconRequest} that returns one.
 *
 * A function computes its result from the request only — no hooks, DOM or
 * SVG measurement, browser globals, network access, mutable module state, or
 * side effects. Once selected, its result is final: returning `null` or
 * `undefined` renders no glyph instead of falling through to another source.
 *
 * @example
 * ```
 * defineTheme({
 *   name: 'brand',
 *   icons: {
 *     info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} />,
 *   },
 * });
 * ```
 */
export type IconEntry<Variant extends string = IconVariant> =
  ReactNode | ((request: IconRequest<Variant>) => ReactNode);

/**
 * How resolution holds any entry: an entry typed for some variant names
 * accepts a request with none of them.
 */
type StoredIconEntry = IconEntry<never>;

export type IconRegistrySource = DefinedTheme | string | null | undefined;

/** The request every public, one-argument read uses. */
const PUBLIC_READ_REQUEST: IconRequest<never> = {size: 'md'};

// =============================================================================
// Global Registry
// =============================================================================

let globalRegistry: Record<string, StoredIconEntry> = {};

/**
 * A key is namespaced when it carries a `<namespace>:` prefix — the runtime
 * form of {@link NamespacedIconName}, which is how the typed
 * {@link getIconRegistry} snapshot tells a built-in name from a component- or
 * library-owned one.
 */
function isNamespacedKey(name: string): boolean {
  return name.includes(':');
}

function getTheme(source: IconRegistrySource): DefinedTheme | null {
  return typeof source === 'string'
    ? getRegisteredTheme(source)
    : (source ?? null);
}

/**
 * The theme's icon entries, functions included. A theme from `defineTheme`
 * keeps them in `__icons` when any entry is a function (its public `icons`
 * is the node view); otherwise `icons` already holds them.
 */
function getThemeIconEntries(
  theme: DefinedTheme | null,
): Readonly<Record<string, StoredIconEntry>> | null {
  if (theme == null) {
    return null;
  }
  return theme.__icons ?? theme.icons ?? null;
}

/**
 * The selected entry, with every variant list a requested variant must be in
 * for the entry to receive it. No lists: the entry receives no variant.
 */
interface IconSelection {
  entry: StoredIconEntry;
  variantLists: ReadonlyArray<ReadonlyArray<string> | undefined>;
}

/**
 * Pick the one source that answers `name`: the theme entry, then the
 * process-wide registration, then the built-in default, then `fallback`. A
 * nullish static entry falls through; a function is returned as-is, because
 * its result is final.
 *
 * A theme entry may receive a variant listed by the active theme and by the
 * theme that defined the entry (an inherited entry keeps its defining
 * theme's list). A process-wide registration may receive a variant the
 * active theme lists.
 */
function selectIconEntry(
  name: string,
  source: IconRegistrySource,
  fallback?: ReactNode,
): IconSelection {
  const theme = getTheme(source);
  const activeVariants = theme?.iconVariants;
  const themeEntry = getThemeIconEntries(theme)?.[name];
  if (theme != null && themeEntry != null) {
    const definingVariants =
      theme.__iconEntryVariants != null &&
      Object.hasOwn(theme.__iconEntryVariants, name)
        ? theme.__iconEntryVariants[name]
        : activeVariants;
    return {
      entry: themeEntry,
      variantLists: [activeVariants, definingVariants],
    };
  }
  const globalEntry = globalRegistry[name];
  if (globalEntry != null) {
    return {entry: globalEntry, variantLists: [activeVariants]};
  }
  return {entry: defaultIcons[name as IconName] ?? fallback, variantLists: []};
}

/**
 * Read a selected entry for a request: call a function, return a node as-is.
 * The function receives the requested variant only when every list of the
 * selection contains it; otherwise it receives `undefined`.
 */
function readIconEntry(
  {entry, variantLists}: IconSelection,
  {size, variant}: IconRequest<string>,
): ReactNode {
  if (typeof entry !== 'function') {
    return entry;
  }
  const receivable =
    variant !== undefined &&
    variantLists.length > 0 &&
    variantLists.every(list => list?.includes(variant) === true);
  // A receivable variant is one the entry's theme lists, which is the type
  // the entry was written against.
  return entry((receivable ? {size, variant} : {size}) as IconRequest<never>);
}

/**
 * Resolve a key for an Icon request. `Icon` is the caller: it passes the size
 * it resolved and the variant it was asked for. Public reads use
 * {@link getIcon} instead.
 * @internal
 */
export function resolveIcon(
  name: ExtendedIconName,
  source: IconRegistrySource,
  request: IconRequest<string>,
): ReactNode {
  return readIconEntry(selectIconEntry(name, source), request);
}

/**
 * Register icons at the module level. Works in both server and client
 * environments. Call once at app initialization (e.g. root layout).
 *
 * Icons registered here are available to all components — including
 * server-rendered ones that can't access React Context.
 *
 * @example
 * ```
 * import { registerIcons } from '@astryxdesign/core';
 * import { brandIcons } from './brand-icons';
 * registerIcons(brandIcons);
 * ```
 *
 * Libraries may also register their own extension keys (any string), so a
 * theme can override them the same way it overrides built-in icons. A library
 * that ships its own icons registers them by key, then resolves with
 * `getIcon('richtext:bold')`.
 * @example
 * ```
 * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
 * ```
 *
 * An entry may also be a pure synchronous function of `{size, variant}`
 * ({@link IconEntry}); `Icon` passes it the size it renders at.
 * @example
 * ```
 * registerIcons({ info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} /> });
 * ```
 */
export function registerIcons(
  icons: Partial<Record<ExtendedIconName, IconEntry>>,
): void {
  warnOnce(
    'icon-registry:global-register-icons',
    'Icon',
    '`registerIcons()` applies icon overrides globally. Prefer `defineTheme({ icons })` for theme-scoped icon overrides.',
  );
  globalRegistry = {...globalRegistry, ...icons};
}

/**
 * Get a snapshot of the full icon registry, with registered icons overriding
 * built-in defaults.
 *
 * Works in both server and client environments. Useful for tooling that needs
 * to derive valid semantic icon-name options from the same registry Icon
 * resolves against.
 *
 * Every value is a React node: a function entry is read at `{size: 'md'}`,
 * exactly as {@link getIcon} reads it.
 */
export function getIconRegistry(
  source?: IconRegistrySource,
): Readonly<Record<IconName, ReactNode>> {
  const registry: Record<string, ReactNode> = {};

  // Only surface built-in IconName keys here — namespaced keys, whether
  // contributed by a library or shipped as a component's own default, are
  // resolved via getIcon/getExtendedIcon and intentionally kept out of the
  // typed IconRegistry snapshot.
  const names = new Set(Object.keys(defaultIcons));
  for (const name of Object.keys(getThemeIconEntries(getTheme(source)) ?? {})) {
    names.add(name);
  }
  for (const name of names) {
    if (isNamespacedKey(name)) {
      continue;
    }
    registry[name] = readIconEntry(
      selectIconEntry(name, source),
      PUBLIC_READ_REQUEST,
    );
  }

  return registry as Record<IconName, ReactNode>;
}

/**
 * Get an icon by name from the global registry, falling back to defaults.
 *
 * Works in both server and client environments.
 * Falls back to built-in default icons when no override is registered.
 *
 * Accepts extension keys (any string) in addition to the built-in
 * {@link IconName}s — useful for library-contributed icons. For a
 * caller-supplied fallback when a key isn't registered, use
 * {@link getExtendedIcon}.
 *
 * Returns a React node: a function entry is read at `{size: 'md'}`. Render
 * `<Icon icon={name} />` to request another size.
 */
export function getIcon(
  name: ExtendedIconName,
  source?: IconRegistrySource,
): ReactNode {
  return readIconEntry(selectIconEntry(name, source), PUBLIC_READ_REQUEST);
}

/**
 * Resolve an extension icon by an arbitrary string key, falling back to a
 * caller-supplied default when nothing is registered.
 *
 * This is the seam libraries use to make their own icons themeable: ship the
 * inline SVG as `fallback`, resolve through this function, and a theme can
 * override the key via {@link registerIcons} without the library having to
 * widen the core {@link IconName} union.
 *
 * The `fallback` is the library default, overridable by a theme registering the
 * same key (for example `'richtext:bold'`). A function entry is read at
 * `{size: 'md'}`, and its result is final: a nullish result does not fall
 * back.
 * @example
 * ```
 * getExtendedIcon('richtext:bold', <BoldGlyph />)
 * ```
 */
export function getExtendedIcon(
  name: ExtendedIconName,
  fallback?: ReactNode,
  source?: IconRegistrySource,
): ReactNode {
  return readIconEntry(
    selectIconEntry(name, source, fallback),
    PUBLIC_READ_REQUEST,
  );
}

// =============================================================================
// Component icon slots
// =============================================================================

/**
 * A theme's stored value for a slot, function included. A function was typed
 * for its slot's state; resolution passes it the state of that slot only.
 */
export type StoredComponentIconValue =
  | IconName
  | null
  | ComponentIconRequest<string>
  | ((state: never) => ComponentIconRequest<string> | null | undefined);

/** The state a slot's component passes: `undefined` for a stateless slot. */
export type ComponentIconSlotState<Slot extends ComponentIconSlotName> =
  ComponentIconSlotMap[Slot] extends true
    ? undefined
    : Readonly<ComponentIconSlotMap[Slot]>;

/**
 * What a component renders for a slot when the theme maps nothing: its own
 * icon name (or `null` for none), and optionally its own variant and size.
 */
export type ComponentIconFallback =
  | IconName
  | null
  | Readonly<{icon: IconName | null; variant?: IconVariant; size?: IconSize}>;

/** A slot resolved to what the component renders through `Icon`. */
export type ResolvedComponentIcon = Readonly<{
  icon: IconName | null;
  variant?: string;
  size?: IconSize;
}>;

const ICON_SIZES: ReadonlySet<unknown> = new Set(['xsm', 'sm', 'md', 'lg']);

function isIconName(value: unknown): value is IconName {
  return (
    typeof value === 'string' &&
    !isNamespacedKey(value) &&
    Object.hasOwn(defaultIcons, value)
  );
}

/**
 * The theme's slot values, functions included. A theme from `defineTheme`
 * keeps them in `__componentIcons` when any value is a function (its public
 * `componentIcons` is the static view); otherwise `componentIcons` holds them.
 */
function getThemeComponentIcons(
  theme: DefinedTheme | null,
): Readonly<Record<string, StoredComponentIconValue | undefined>> | null {
  if (theme == null) {
    return null;
  }
  return theme.__componentIcons ?? theme.componentIcons ?? null;
}

function warnMalformedRequest(slot: string, problem: string): void {
  warnOnce(
    `component-icons:${slot}:${problem}`,
    'Icon',
    `componentIcons["${slot}"] ${problem}. The component keeps its own value for that field.`,
  );
}

/**
 * Apply a theme's request to the component's fallback, field by field. A
 * missing field keeps the fallback. An unknown icon, a variant the active
 * theme does not list, or an unsupported size is ignored with one
 * development-only warning.
 */
function applyComponentIconRequest(
  slot: string,
  fallback: ResolvedComponentIcon,
  request: unknown,
  theme: DefinedTheme | null,
): ResolvedComponentIcon {
  if (request === undefined) {
    return fallback;
  }
  if (request === null) {
    return {...fallback, icon: null};
  }
  if (typeof request !== 'object' || Array.isArray(request)) {
    warnMalformedRequest(
      slot,
      `returned ${JSON.stringify(request)}, which is not a request`,
    );
    return fallback;
  }
  const {icon, variant, size} = request as Record<string, unknown>;
  let resolved = fallback;
  if (icon === null || isIconName(icon)) {
    resolved = {...resolved, icon};
  } else if (icon !== undefined) {
    warnMalformedRequest(
      slot,
      `requests the unknown icon ${JSON.stringify(icon)}`,
    );
  }
  if (typeof variant === 'string' && theme?.iconVariants?.includes(variant)) {
    resolved = {...resolved, variant};
  } else if (variant !== undefined) {
    warnMalformedRequest(
      slot,
      `requests the variant ${JSON.stringify(variant)}, which the theme does not list`,
    );
  }
  if (ICON_SIZES.has(size)) {
    resolved = {...resolved, size: size as IconSize};
  } else if (size !== undefined) {
    warnMalformedRequest(
      slot,
      `requests the unsupported size ${JSON.stringify(size)}`,
    );
  }
  return resolved;
}

/**
 * Resolve a component's icon slot. The component passes its slot state and
 * its own fallback; the active theme's `componentIcons[slot]` adjusts that
 * fallback. A shared icon name replaces the fallback icon, `null` hides the
 * icon, a request applies field by field, and a slot function receives the
 * state and returns a request whose result is final: `null` hides the icon,
 * `undefined` changes nothing.
 *
 * This is the only caller of a theme's slot functions. Caller-supplied icon
 * content wins before resolution, so a component does not resolve the slot
 * when its caller passed content.
 * @internal
 */
export function resolveComponentIcon<Slot extends ComponentIconSlotName>(
  slot: Slot,
  state: ComponentIconSlotState<Slot>,
  fallback: ComponentIconFallback,
  source: IconRegistrySource,
): ResolvedComponentIcon {
  const own: ResolvedComponentIcon =
    fallback === null || typeof fallback === 'string'
      ? {icon: fallback}
      : fallback;
  const theme = getTheme(source);
  const value = getThemeComponentIcons(theme)?.[slot];
  if (value === undefined) {
    return own;
  }
  if (typeof value === 'function') {
    const result: unknown = (value as (state: unknown) => unknown)(state);
    if (typeof result === 'string') {
      warnMalformedRequest(
        slot,
        `returned ${JSON.stringify(result)}, which is not a request`,
      );
      return own;
    }
    return applyComponentIconRequest(slot, own, result, theme);
  }
  if (typeof value === 'string') {
    return applyComponentIconRequest(slot, own, {icon: value}, theme);
  }
  return applyComponentIconRequest(slot, own, value, theme);
}

/**
 * Reset the global registry. For testing only.
 * @internal
 */
export function resetIcons(): void {
  globalRegistry = {};
}