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

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 |',
   '',

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

@@ -9,7 +9,7 @@ import {
 } from '@storybook/addon-docs/blocks';
 import { TabsItem } from './TabsItem.js';
 import { Tabs } from './Tabs.js';
-import { allowedIcons } from 'Components/icon/allowedIcons';
+import type { IconName } from 'Components/icon/allowedIcons';
 
 // ---------------------------------------------------------------------------
 // Docs page
@@ -93,10 +93,14 @@ const meta = {
     },
     iconName: {
       control: 'select',
-      options: Object.keys(allowedIcons),
-      description: 'Optional icon rendered before the label text at 16 px.',
+      // Any Icon name works; these are the ones that read well in a tab.
+      options: [
+        'house', 'user', 'guardians', 'staff', 'date', 'sheet', 'table', 'settings',
+        'chart-column-increasing', 'clipboard-list', 'mail', 'archive',
+      ] satisfies IconName[],
+      description: 'Optional icon rendered before the label text at 16 px. Accepts any `IconName`.',
       table: {
-        type: { summary: 'keyof allowedIcons' },
+        type: { summary: 'IconName' },
         defaultValue: { summary: 'undefined' },
       },
     },

package/src/components/tabs/TabsItem.tsx

@@ -1,11 +1,11 @@
 import classNames from 'classnames';
-import type { allowedIcons } from 'Components/icon/allowedIcons';
+import type { IconName } from 'Components/icon/allowedIcons';
 import { Icon } from 'Components/icon/Icon';
 import type { AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes } from 'react';
 
 type TabsItemProps = {
   active?: boolean;
-  iconName?: keyof typeof allowedIcons;
+  iconName?: IconName;
 } & (
   | { tabElement?: 'button'; tabElementProps?: ButtonHTMLAttributes<HTMLButtonElement> }
   | { tabElement?: 'link'; tabElementProps?: AnchorHTMLAttributes<HTMLAnchorElement> }