@arbor-education/design-system.components 3.0.2 → 3.2.0

package/src/components/icon/Icon.test.tsx

@@ -1,14 +1,186 @@
-import { describe, expect, test } from 'vitest';
-import { render, screen } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
 import { Icon } from './Icon.js';
 import '@testing-library/jest-dom/vitest';
-import { allowedIcons, type IconName } from './allowedIcons.js';
+import {
+  allowedIcons,
+  customIcons,
+  iconAliases,
+  isIconName,
+  type IconName,
+} from './allowedIcons.js';
+import { lucideIconNames } from './LucideIcon.js';
+
+/**
+ * Every name the design system supported before the whole Lucide set was exposed. Kept as a literal
+ * list so that removing a name from `iconAliases`, or Lucide dropping one, fails here rather than
+ * in a consumer.
+ */
+const PREVIOUSLY_SUPPORTED_NAMES = [
+  '3-dot', 'archive', 'arrow-down', 'arrow-left', 'arrow-right-from-line', 'arrow-right',
+  'arrow-up-right', 'arrow-up', 'ask-arbor', 'book-open', 'camera', 'chart-column-increasing',
+  'chart-spline', 'check', 'check-solid', 'chevron-down', 'chevron-left', 'chevron-right',
+  'chevron-up', 'chevrons-left', 'chevrons-right', 'circle-alert', 'circle-check-big',
+  'circle-check', 'circle-help', 'circle-percent', 'circle-plus', 'circle-x', 'clipboard-list',
+  'clipboard', 'clock-3', 'cloud-upload', 'copy', 'corner-down-left', 'date', 'dot', 'download',
+  'ellipsis-vertical', 'ellipsis', 'expand', 'external-link', 'eye-off', 'eye', 'favourite-filled',
+  'favourite-outline', 'file', 'files', 'flag', 'funnel', 'google', 'grab', 'graduation-cap',
+  'grid-3x3', 'group', 'guardians', 'history', 'house', 'info', 'iteration-ccw', 'layout-list',
+  'lightbulb', 'link', 'list-filter-plus', 'list', 'list-tree', 'loader', 'lock-open', 'lock',
+  'log-out', 'mail', 'menu', 'message-square-more', 'mic', 'minus', 'monitor', 'paint-bucket',
+  'paperclip', 'party-popper', 'pencil', 'percent', 'phone', 'pin', 'plus', 'projector', 'redo',
+  'save', 'search', 'send', 'settings', 'share', 'sheet', 'shrink', 'sliders-horizontal',
+  'smartphone', 'sorting', 'sparkles', 'staff', 'switch-camera', 'table', 'trash', 'trending-down',
+  'trending-up', 'triangle-alert', 'undo', 'upload', 'user', 'x', 'x-solid', 'zap',
+] as const satisfies readonly IconName[];
+
+/**
+ * A spread of plain Lucide names rather than all ~1,900 — enough to cover the naming shapes that
+ * kebab-casing tends to break on (leading single letters, digits, repeated digits, letter pairs)
+ * plus Lucide's own deprecated aliases.
+ */
+const SAMPLED_LUCIDE_NAMES = [
+  'ban', 'shopping-cart', 'a-arrow-down', 'a-large-small', 'align-center', 'arrow-down-a-z',
+  'arrow-down-0-1', 'axis-3d', 'bluetooth-connected', 'building-2', 'circle-slash-2', 'clock-12',
+  'columns-3', 'file-json-2', 'git-pull-request-arrow', 'square-dashed-mouse-pointer', 'test-tube',
+  'volume-2', 'wifi-off', 'zoom-out',
+  // Lucide's deprecated aliases still resolve, so they are supported too
+  'sort-desc', 'area-chart',
+] as const satisfies readonly IconName[];
+
+/**
+ * Waits for the loaded glyph rather than the placeholder. Both carry `role="img"`, so they are told
+ * apart by their contents: the placeholder is an empty SVG until the icon's chunk resolves.
+ */
+const findLoadedIcon = async () => waitFor(() => {
+  const icon = screen.getByRole('img', { hidden: true });
+  expect(icon.childElementCount).toBeGreaterThan(0);
+  return icon;
+});
+
+const renderedIcon = async (name: IconName) => {
+  const { unmount } = render(<Icon name={name} />);
+  const icon = await findLoadedIcon();
+  const classes = icon.getAttribute('class') ?? '';
+  unmount();
+  return { tagName: icon.tagName.toLowerCase(), classes };
+};
 
 describe('Icon', () => {
-  Object.keys(allowedIcons).forEach((icon) => {
-    test(`Icon ${icon} renders`, () => {
-      render(<Icon name={icon as IconName} />);
+  describe('name allow-list', () => {
+    test('every previously supported name is still accepted', () => {
+      const rejected = PREVIOUSLY_SUPPORTED_NAMES.filter(name => !isIconName(name));
+      expect(rejected).toEqual([]);
+    });
+
+    test('the whole Lucide set is accepted', () => {
+      const rejected = lucideIconNames.filter(name => !isIconName(name));
+      expect(rejected).toEqual([]);
+      expect(lucideIconNames.length).toBeGreaterThan(1500);
+    });
+
+    test('every alias target is a real Lucide icon', () => {
+      const lucideNames = new Set<string>(lucideIconNames);
+      const unresolved = Object.entries(iconAliases)
+        .filter(([, target]) => !lucideNames.has(target));
+      expect(unresolved).toEqual([]);
+    });
+
+    test('isIconName rejects names that are not icons', () => {
+      expect(isIconName('behaviour')).toBe(false);
+      expect(isIconName('not-an-icon')).toBe(false);
+      expect(isIconName('')).toBe(false);
+      expect(isIconName('toString')).toBe(false);
+    });
+
+    test('allowedIcons supports hasOwnProperty membership checks', () => {
+      // arbor-fe-library validates backend-supplied names this way, so the shape has to hold.
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'ban')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'shopping-cart')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, '3-dot')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'ask-arbor')).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(allowedIcons, 'not-an-icon')).toBe(false);
+    });
+  });
+
+  describe('rendering', () => {
+    test.each(Object.keys(iconAliases) as Array<keyof typeof iconAliases>)(
+      'alias %s renders its target glyph',
+      async (name) => {
+        const { tagName, classes } = await renderedIcon(name);
+        expect(tagName).toBe('svg');
+        // Lucide tags each glyph with its own name, which proves the alias resolved correctly.
+        expect(classes.split(' ')).toContain(`lucide-${iconAliases[name]}`);
+        expect(classes.split(' ')).toContain(`ds-icon-${name}`);
+      },
+    );
+
+    test.each(Object.keys(customIcons) as Array<keyof typeof customIcons>)(
+      'custom icon %s renders',
+      async (name) => {
+        const { tagName, classes } = await renderedIcon(name);
+        expect(tagName).toBe('svg');
+        expect(classes.split(' ')).toContain(`ds-icon-${name}`);
+      },
+    );
+
+    test.each(SAMPLED_LUCIDE_NAMES)('lucide icon %s renders', async (name) => {
+      const { tagName, classes } = await renderedIcon(name);
+      expect(tagName).toBe('svg');
+      expect(classes.split(' ')).toContain(`ds-icon-${name}`);
+    });
+
+    test('an Arbor alias wins over the Lucide icon it shadows', async () => {
+      const { classes } = await renderedIcon('trash');
+      expect(classes.split(' ')).toContain('lucide-trash-2');
+      expect(classes.split(' ')).not.toContain('lucide-trash');
+    });
+
+    test('favourite-filled fills the star with the icon colour', async () => {
+      render(<Icon name="favourite-filled" color="rebeccapurple" />);
+      const icon = await findLoadedIcon();
+      expect(icon).toHaveAttribute('fill', 'rebeccapurple');
+      expect(icon.getAttribute('class')).toContain('lucide-star');
+    });
+
+    test('a placeholder of the right size holds the icon\'s place while it loads', () => {
+      // `not-yet-loaded` is only true on the very first render of an icon in this file's module
+      // registry, so pick one no other test touches.
+      render(<Icon name="microscope" size={24} className="custom-class" />);
+      const placeholder = screen.getByRole('img', { hidden: true });
+      expect(placeholder).toHaveAttribute('width', '24');
+      expect(placeholder).toHaveAttribute('height', '24');
+      expect(placeholder).toHaveClass('custom-class', 'ds-icon', 'ds-icon-microscope');
+      expect(placeholder).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    test('a loaded icon renders synchronously on later mounts', async () => {
+      const { unmount } = render(<Icon name="rocket" />);
+      await findLoadedIcon();
+      unmount();
+
+      render(<Icon name="rocket" />);
+      // No `await` — the module-level cache means no second placeholder frame.
+      expect(screen.getByRole('img', { hidden: true }).getAttribute('class'))
+        .toContain('lucide-rocket');
+    });
+
+    test.each([12, 16, 24] as const)('renders at size %i', async (size) => {
+      render(<Icon name="ban" size={size} />);
+      const icon = await findLoadedIcon();
+      expect(icon).toHaveAttribute('width', String(size));
+      expect(icon).toHaveAttribute('height', String(size));
+    });
+
+    test('an unrecognised name renders the placeholder and reports the problem', () => {
+      const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+      // Consumers passing backend data can defeat the type, so this must not throw.
+      render(<Icon name={'definitely-not-an-icon' as IconName} />);
       expect(screen.getByRole('img', { hidden: true })).toBeInTheDocument();
+      expect(consoleError).toHaveBeenCalledWith(
+        '[design-system] "definitely-not-an-icon" is not a known icon name.',
+      );
+      consoleError.mockRestore();
     });
   });
 

package/src/components/icon/Icon.tsx

@@ -1,5 +1,6 @@
 import classNames from 'classnames';
-import { allowedIcons, type IconName } from './allowedIcons.js';
+import { customIcons, iconAliases, type IconName } from './allowedIcons.js';
+import { LucideIcon, type LucideIconName } from './LucideIcon.js';
 import type { CustomIconProps, IconSize } from './types.js';
 
 type IconProps = {
@@ -10,14 +11,35 @@ type IconProps = {
   className?: string;
 };
 
+const isCustomIconName = (name: IconName): name is keyof typeof customIcons =>
+  Object.prototype.hasOwnProperty.call(customIcons, name);
+
+const isAliasedIconName = (name: IconName): name is keyof typeof iconAliases =>
+  Object.prototype.hasOwnProperty.call(iconAliases, name);
+
+const resolveLucideName = (name: Exclude<IconName, keyof typeof customIcons>): LucideIconName =>
+  isAliasedIconName(name) ? iconAliases[name] : name;
+
+/**
+ * Arbor's custom icons and aliases are resolved before the Lucide set, so an Arbor name always wins
+ * over the Lucide icon it shadows.
+ */
+const IconGlyph = (props: CustomIconProps & { name: IconName }) => {
+  const { name, ...glyphProps } = props;
+  if (isCustomIconName(name)) {
+    const CustomIcon = customIcons[name];
+    return <CustomIcon {...glyphProps} />;
+  }
+  return <LucideIcon name={resolveLucideName(name)} {...glyphProps} />;
+};
+
 export const Icon = (props: IconProps) => {
   const { size = 16, color = 'currentColor', name, screenReaderText, className } = props;
-  const Component = allowedIcons[name];
   const classes = classNames(className, `ds-icon ds-icon-${name}`);
   return (
     <>
       {/* why aria-hidden? https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/ */}
-      <Component size={size} color={color} className={classes} role="img" aria-hidden />
+      <IconGlyph name={name} size={size} color={color} className={classes} role="img" aria-hidden />
       {!!screenReaderText && (
         <span className="sr-only">{screenReaderText}</span>
       )}

package/src/components/icon/LucideIcon.tsx

@@ -0,0 +1,94 @@
+import { useEffect, useReducer } from 'react';
+import { dynamicIconImports, iconNames } from 'lucide-react/dynamic.mjs';
+import type { DynamicIconModule, IconName } from 'lucide-react/dynamic';
+import type { CustomIconProps } from './types.js';
+
+/** Every icon name published by `lucide-react`, kebab-cased. */
+export type LucideIconName = IconName;
+
+/** Every `lucide-react` icon name, for building galleries and validating input. */
+export const lucideIconNames: readonly LucideIconName[] = iconNames;
+
+type IconLoader = () => Promise<DynamicIconModule>;
+type LucideIconComponent = DynamicIconModule['default'];
+
+const iconLoaders: Readonly<Record<LucideIconName, IconLoader>> = dynamicIconImports;
+
+/**
+ * Icons resolve through `lucide-react`'s per-icon dynamic imports so that consumers only ship the
+ * icons they actually render, rather than all ~1,900 of them. Both caches are module-scoped: the
+ * first render of a given icon anywhere in the app pays the import, and every render after that —
+ * including new instances in other trees — resolves synchronously from `loadedIcons`.
+ */
+const loadedIcons = new Map<LucideIconName, LucideIconComponent>();
+const inFlightLoads = new Map<LucideIconName, Promise<void>>();
+
+const loadIcon = (name: LucideIconName): Promise<void> => {
+  const inFlight = inFlightLoads.get(name);
+  if (inFlight) {
+    return inFlight;
+  }
+  // Annotated rather than inferred: names reaching `Icon` from a backend are not always valid.
+  const loader: IconLoader | undefined = iconLoaders[name];
+  if (!loader) {
+    console.error(`[design-system] "${name}" is not a known icon name.`);
+    // Cached so an unknown name is only reported once, however many times it is rendered.
+    const noSuchIcon = Promise.resolve();
+    inFlightLoads.set(name, noSuchIcon);
+    return noSuchIcon;
+  }
+  const load = loader()
+    .then((iconModule) => {
+      loadedIcons.set(name, iconModule.default);
+    })
+    .catch((error: unknown) => {
+      // Drop the rejected promise so a later render can retry (e.g. after a transient chunk 404).
+      inFlightLoads.delete(name);
+      console.error(`[design-system] Could not load the "${name}" icon.`, error);
+    });
+  inFlightLoads.set(name, load);
+  return load;
+};
+
+const useLucideIcon = (name: LucideIconName): LucideIconComponent | undefined => {
+  const [, rerender] = useReducer((renderCount: number) => renderCount + 1, 0);
+
+  useEffect(() => {
+    if (loadedIcons.has(name)) {
+      return;
+    }
+    let isMounted = true;
+    void loadIcon(name).then(() => {
+      if (isMounted) {
+        rerender();
+      }
+    });
+    return () => {
+      isMounted = false;
+    };
+  }, [name]);
+
+  return loadedIcons.get(name);
+};
+
+export type LucideIconProps = CustomIconProps & {
+  name: LucideIconName;
+  fill?: string;
+};
+
+/**
+ * Renders a single `lucide-react` icon, loading it on demand. Until the icon resolves an empty SVG
+ * of the same size is rendered in its place, so the surrounding layout does not shift and the
+ * element keeps its accessible role throughout.
+ */
+export const LucideIcon = (props: LucideIconProps) => {
+  const { name, ...iconProps } = props;
+  const Component = useLucideIcon(name);
+
+  if (!Component) {
+    const { size, ...placeholderProps } = iconProps;
+    return <svg width={size} height={size} viewBox="0 0 24 24" {...placeholderProps} />;
+  }
+
+  return <Component {...iconProps} />;
+};

package/src/components/icon/allowedIcons.tsx

@@ -1,217 +1,77 @@
-import {
-  Archive,
-  ArrowDown,
-  ArrowDownUp,
-  ArrowLeft,
-  ArrowRight,
-  ArrowRightFromLine,
-  ArrowUp,
-  ArrowUpRight,
-  BookOpen,
-  CalendarFold,
-  Camera,
-  ChartColumnIncreasing,
-  ChartSpline,
-  Check,
-  ChevronDown,
-  ChevronLeft,
-  ChevronRight,
-  ChevronsLeft,
-  ChevronsRight,
-  ChevronUp,
-  CircleAlert,
-  CircleCheck,
-  CircleCheckBig,
-  CirclePercent,
-  CirclePlus,
-  CircleQuestionMark,
-  CircleX,
-  Clipboard,
-  ClipboardList,
-  Clock3,
-  CloudUpload,
-  Copy,
-  CornerDownLeft,
-  Dot,
-  Download,
-  Ellipsis,
-  EllipsisVertical,
-  Expand,
-  ExternalLink,
-  Eye,
-  EyeOff,
-  File,
-  Files,
-  Flag,
-  Funnel,
-  GraduationCap,
-  Grid3x3,
-  GripVertical,
-  History,
-  House,
-  Info,
-  IterationCcw,
-  LayoutList,
-  Lightbulb,
-  Link,
-  List,
-  ListFilterPlus,
-  ListTree,
-  LoaderCircle,
-  Lock,
-  LockOpen,
-  LogOut, type LucideProps,
-  Mail,
-  Menu,
-  MessageSquareMore,
-  Mic,
-  Minimize2,
-  Minus,
-  Monitor,
-  PaintBucket,
-  Paperclip,
-  PartyPopper,
-  Pencil,
-  Percent,
-  Phone,
-  Pin,
-  Plus,
-  Projector,
-  Redo2,
-  Save,
-  Search,
-  Send,
-  Settings,
-  Share,
-  Sheet,
-  SlidersHorizontal,
-  Smartphone,
-  Sparkles,
-  Star, SwitchCamera, Table, Trash2, TrendingDown, TrendingUp, TriangleAlert, Undo2, Upload, User,
-  Users,
-  UsersRound, X, Zap,
-} from 'lucide-react';
+import type { ReactNode } from 'react';
+import { LucideIcon, lucideIconNames, type LucideIconName } from './LucideIcon.js';
 import { AskArbor } from './customIcons/AskArbor.js';
 import { CheckSolid } from './customIcons/CheckSolid.js';
 import { Google } from './customIcons/Google.js';
 import { XSolid } from './customIcons/XSolid.js';
 import type { CustomIconProps } from './types.js';
 
-export const allowedIcons = {
-  // lucide icons
-  '3-dot': EllipsisVertical,
-  'archive': Archive,
-  'arrow-down': ArrowDown,
-  'arrow-left': ArrowLeft,
-  'arrow-right-from-line': ArrowRightFromLine,
-  'arrow-right': ArrowRight,
-  'arrow-up-right': ArrowUpRight,
-  'arrow-up': ArrowUp,
-  'book-open': BookOpen,
-  'camera': Camera,
-  'chart-column-increasing': ChartColumnIncreasing,
-  'chart-spline': ChartSpline,
-  'check': Check,
-  'chevron-down': ChevronDown,
-  'chevron-left': ChevronLeft,
-  'chevron-right': ChevronRight,
-  'chevron-up': ChevronUp,
-  'chevrons-left': ChevronsLeft,
-  'chevrons-right': ChevronsRight,
-  'circle-alert': CircleAlert,
-  'circle-check-big': CircleCheckBig,
-  'circle-check': CircleCheck,
-  'circle-help': CircleQuestionMark,
-  'circle-percent': CirclePercent,
-  'circle-plus': CirclePlus,
-  'circle-x': CircleX,
-  'clipboard-list': ClipboardList,
-  'clipboard': Clipboard,
-  'clock-3': Clock3,
-  'cloud-upload': CloudUpload,
-  'copy': Copy,
-  'corner-down-left': CornerDownLeft,
-  'date': CalendarFold,
-  'dot': Dot,
-  'download': Download,
-  'ellipsis-vertical': EllipsisVertical,
-  'ellipsis': Ellipsis,
-  'expand': Expand,
-  'external-link': ExternalLink,
-  'eye-off': EyeOff,
-  'eye': Eye,
-  'favourite-outline': Star,
-  'file': File,
-  'files': Files,
-  'flag': Flag,
-  'funnel': Funnel,
-  'grab': GripVertical,
-  'graduation-cap': GraduationCap,
-  'grid-3x3': Grid3x3,
-  'group': UsersRound,
-  'guardians': Users,
-  'history': History,
-  'house': House,
-  'info': Info,
-  'iteration-ccw': IterationCcw,
-  'layout-list': LayoutList,
-  'lightbulb': Lightbulb,
-  'link': Link,
-  'list-filter-plus': ListFilterPlus,
-  'list': List,
-  'list-tree': ListTree,
-  'loader': LoaderCircle,
-  'lock-open': LockOpen,
-  'lock': Lock,
-  'log-out': LogOut,
-  'mail': Mail,
-  'menu': Menu,
-  'message-square-more': MessageSquareMore,
-  'mic': Mic,
-  'minus': Minus,
-  'monitor': Monitor,
-  'paint-bucket': PaintBucket,
-  'paperclip': Paperclip,
-  'party-popper': PartyPopper,
-  'pencil': Pencil,
-  'percent': Percent,
-  'phone': Phone,
-  'pin': Pin,
-  'plus': Plus,
-  'projector': Projector,
-  'redo': Redo2,
-  'save': Save,
-  'search': Search,
-  'send': Send,
-  'settings': Settings,
-  'share': Share,
-  'sheet': Sheet,
-  'shrink': Minimize2,
-  'sliders-horizontal': SlidersHorizontal,
-  'smartphone': Smartphone,
-  'sorting': ArrowDownUp,
-  'sparkles': Sparkles,
-  'staff': GraduationCap,
-  'switch-camera': SwitchCamera,
-  'table': Table,
-  'trash': Trash2,
-  'trending-down': TrendingDown,
-  'trending-up': TrendingUp,
-  'triangle-alert': TriangleAlert,
-  'undo': Undo2,
-  'upload': Upload,
-  'user': User,
-  'x': X,
-  'zap': Zap,
-  // custom icons
+/**
+ * Arbor names that point at a differently-named Lucide icon. These take precedence over the Lucide
+ * name they shadow, so `trash` stays the lidded can (`trash-2`) rather than Lucide's plain `trash`.
+ * Seven of these — `grab`, `group`, `loader`, `redo`, `shrink`, `trash` and `undo` — shadow a real
+ * Lucide icon with a different glyph, which is deliberate: renaming them would break every existing
+ * consumer. Reach for the target name directly if you want Lucide's version.
+ *
+ * The `satisfies` clause makes every target a compile-time-checked Lucide icon name.
+ */
+export const iconAliases = {
+  '3-dot': 'ellipsis-vertical',
+  'circle-help': 'circle-question-mark',
+  'date': 'calendar-fold',
+  'favourite-outline': 'star',
+  'grab': 'grip-vertical',
+  'group': 'users-round',
+  'guardians': 'users',
+  'loader': 'loader-circle',
+  'redo': 'redo-2',
+  'shrink': 'minimize-2',
+  'sorting': 'arrow-down-up',
+  'staff': 'graduation-cap',
+  'trash': 'trash-2',
+  'undo': 'undo-2',
+} as const satisfies Readonly<Record<string, LucideIconName>>;
+
+/**
+ * Icons that are not plain Lucide glyphs: Arbor-specific artwork, and the solid variants built for
+ * particular semantic emphasis states.
+ */
+export const customIcons = {
   'ask-arbor': AskArbor,
   'google': Google,
-  // solid icons
-  'check-solid': (props: CustomIconProps) => <CheckSolid {...props} />,
-  'favourite-filled': (props: LucideProps) => (
-    <Star {...props} fill={props.color} />
+  'check-solid': CheckSolid,
+  'favourite-filled': (props: CustomIconProps) => (
+    <LucideIcon name="star" {...props} fill={props.color} />
   ),
-  'x-solid': (props: CustomIconProps) => <XSolid {...props} />,
-} as const;
+  'x-solid': XSolid,
+} as const satisfies Readonly<Record<string, (props: CustomIconProps) => ReactNode>>;
+
+export type IconName
+  = | LucideIconName
+    | keyof typeof iconAliases
+    | keyof typeof customIcons;
+
+// `Object.keys` widens to `string[]`, so the key unions are reasserted here.
+const aliasNames = Object.keys(iconAliases) as ReadonlyArray<keyof typeof iconAliases>;
+const customIconNames = Object.keys(customIcons) as ReadonlyArray<keyof typeof customIcons>;
+
+/** Every name `Icon` accepts: the whole Lucide set, plus Arbor's aliases and custom icons. */
+export const iconNames: readonly IconName[] = [
+  ...lucideIconNames,
+  ...aliasNames,
+  ...customIconNames,
+];
+
+/**
+ * The `Icon` name allow-list, as a plain object so that membership can be tested with
+ * `hasOwnProperty`. Prefer {@link isIconName}; the values carry no meaning and exist only to make
+ * this a record. Icon components are no longer held here — they are loaded on demand, so nothing
+ * outside a render has a component to hand out.
+ */
+export const allowedIcons = Object.freeze(
+  Object.fromEntries(iconNames.map(name => [name, true])),
+) as Readonly<Record<IconName, true>>;
 
-export type IconName = keyof typeof allowedIcons;
+/** Narrows an arbitrary string to an `IconName`, for validating names that come from a backend. */
+export const isIconName = (name: string): name is IconName =>
+  Object.prototype.hasOwnProperty.call(allowedIcons, name);

package/src/components/icon/lucideDynamic.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `lucide-react` ships its dynamic-import entry point as `dynamic.mjs` and declares no `exports`
+ * map, so the extensionless `lucide-react/dynamic` specifier only resolves in bundlers that list
+ * `.mjs` in `resolve.extensions`. `arbor-fe-library`'s webpack config does not, so we import the
+ * file by its exact name instead. TypeScript then looks for a sibling `dynamic.d.mts`, which the
+ * package does not publish — this declaration points it at the types that do ship.
+ *
+ * Type-only imports still use `lucide-react/dynamic`, which resolves under both `bundler` and
+ * classic `node` module resolution and is erased before any bundler sees it.
+ */
+declare module 'lucide-react/dynamic.mjs' {
+  export * from 'lucide-react/dynamic';
+}

package/src/components/icon/types.ts

@@ -2,8 +2,9 @@ export const iconSizes = [12, 16, 24] as const;
 export type IconSize = typeof iconSizes[number];
 
 export type CustomIconProps = {
-  size: IconSize;
-  color?: string;
-  role?: string;
-  className?: string;
+  'size': IconSize;
+  'color'?: string;
+  'role'?: string;
+  'className'?: string;
+  'aria-hidden'?: boolean;
 };

package/src/components/tabs/Tabs.stories.tsx

@@ -107,7 +107,7 @@ const DEVELOPER_NOTES = [
   '| `active` | `boolean` | `false` | Marks this tab as selected — sets `aria-selected` and active styles |',
   '| `tabElement` | `"button" \\| "link"` | `"button"` | Inner element type. `"button"` for JS-controlled tabs; `"link"` for anchor/router navigation |',
   '| `tabElementProps` | `ButtonHTMLAttributes` or `AnchorHTMLAttributes` | — | Props forwarded to the inner `<button>` or `<a>`. Use `onClick` for state control; `href` for links |',
-  '| `iconName` | `keyof allowedIcons` | — | Optional icon rendered before the label text (16 px) |',
+  '| `iconName` | `IconName` | — | Optional icon rendered before the label text (16 px) |',
   '| `children` | `ReactNode` | — | Tab label text |',
   '| `className` | `string` | — | Extra CSS class on the `<li>` wrapper |',
   '',