@iress-oss/ids-components 6.0.0-alpha.20 → 6.0.0-alpha.21

package/dist/components/Icon/Icon.js

@@ -1,43 +1,81 @@
-import { jsx as p } from "react/jsx-runtime";
-import { s as e } from "../../factory-CsinCTPr.js";
-import { c as n } from "../../cx-DN21T1EH.js";
+import { jsx as c } from "react/jsx-runtime";
+import { s as d } from "../../factory-CsinCTPr.js";
+import { s as v } from "../../is-valid-prop-DweT-eOL.js";
+import { c as L } from "../../css-DNdLYQld.js";
+import { c as p } from "../../cx-DN21T1EH.js";
 import { icon as I } from "./Icon.styles.js";
-import { GlobalCSSClass as x } from "../../enums.js";
-const d = ({
-  className: s,
-  fixedWidth: r,
-  flip: a,
-  name: i,
-  rotate: m,
-  screenreaderText: o,
-  set: f = "fal",
-  spin: l,
+import { GlobalCSSClass as u } from "../../enums.js";
+import { useContext as M, useEffect as N } from "react";
+import { IconContext as S } from "./IconProvider.js";
+import { idsLogger as _ } from "../../helpers/utility/idsLogger.js";
+import { FA_TO_MATERIAL_MAP as $ } from "./helpers/iconMapping.js";
+const E = ({
+  className: r,
+  flip: m,
+  name: s,
+  rotate: l,
+  screenreaderText: a,
+  spin: n,
+  type: f,
   ...t
 }) => {
-  const c = I({
-    flip: a,
-    rotate: m,
-    spin: l
+  const i = M(S), e = f ?? i?.type ?? "material";
+  f == "fontawesome" && _(
+    `[IressIcon] Font Awesome is deprecated and will be removed in a future version. Please migrate to Material Symbols. Icon name: "${s}"`
+  );
+  let o;
+  if (e === "material" && (o = $[s] ?? s), N(() => {
+    e === "material" && i && o && i.registerIcon(o);
+  }, [e, i, o]), e === "material" && o) {
+    const x = i ? i.isIconLoaded(o) : !0, C = I.raw({
+      flip: m,
+      rotate: l,
+      spin: n,
+      filled: t.filled,
+      type: e,
+      loading: !x
+    }), [w, A] = v(t);
+    return /* @__PURE__ */ c(
+      d.span,
+      {
+        role: "img",
+        className: p(
+          L(C, w),
+          u.Icon,
+          "material-symbols-rounded",
+          r
+        ),
+        "aria-hidden": !a && "true",
+        "aria-label": a,
+        ...A,
+        children: o
+      }
+    );
+  }
+  const g = "fa-", y = t.set ?? "fal", b = t.fixedWidth ?? !1, h = I({
+    flip: m,
+    rotate: l,
+    spin: n
   });
-  return /* @__PURE__ */ p(
-    e.span,
+  return /* @__PURE__ */ c(
+    d.span,
     {
       role: "img",
-      className: n(
-        c,
-        x.Icon,
-        f,
-        `fa-${i}`,
-        r && "fa-fw",
-        s
+      className: p(
+        h,
+        u.Icon,
+        y,
+        `${g}${s}`,
+        b && "fa-fw",
+        r
       ),
-      "aria-hidden": !o && "true",
-      "aria-label": o,
+      "aria-hidden": !a && "true",
+      "aria-label": a,
       ...t
     }
   );
 };
-d.displayName = "IressIcon";
+E.displayName = "IressIcon";
 export {
-  d as IressIcon
+  E as IressIcon
 };

package/dist/components/Icon/Icon.styles.d.ts

@@ -1,4 +1,20 @@
 export declare const icon: import('../../styled-system/types').RecipeRuntimeFn<{
+    type: {
+        fontawesome: {};
+        material: {
+            fontFamily: "Material Symbols Rounded";
+            textStyle: "inherit";
+            verticalAlign: "middle";
+            fontVariationSettings: "'FILL' 0, 'wght' 300, 'GRAD' 0, 'opsz' 36";
+            scale: "[1.5]";
+            fontFeatureSettings: "liga";
+        };
+    };
+    filled: {
+        true: {
+            fontVariationSettings: "'FILL' 1, 'wght' 300, 'GRAD' 0, 'opsz' 36";
+        };
+    };
     flip: {
         horizontal: {
             transform: "scaleX(-1)";
@@ -10,6 +26,13 @@ export declare const icon: import('../../styled-system/types').RecipeRuntimeFn<{
             transform: "scale(-1)";
         };
     };
+    loading: {
+        true: {
+            visibility: "hidden";
+            width: "[1em]";
+            height: "[1em]";
+        };
+    };
     rotate: {
         90: {
             transform: "rotate(90deg)";

package/dist/components/Icon/Icon.styles.js

@@ -1,6 +1,24 @@
-import { c as a } from "../../cva-DtPMccE9.js";
-const n = a({
+import { c as i } from "../../cva-DtPMccE9.js";
+import { MATERIAL_SYMBOLS as t } from "./Icon.constants.js";
+const o = i({
+  base: {},
   variants: {
+    type: {
+      fontawesome: {},
+      material: {
+        fontFamily: "Material Symbols Rounded",
+        textStyle: "inherit",
+        verticalAlign: "middle",
+        fontVariationSettings: `'FILL' 0, 'wght' ${t.weight}, 'GRAD' ${t.grade}, 'opsz' ${t.opticalSize}`,
+        scale: "[1.5]",
+        fontFeatureSettings: "liga"
+      }
+    },
+    filled: {
+      true: {
+        fontVariationSettings: `'FILL' 1, 'wght' ${t.weight}, 'GRAD' ${t.grade}, 'opsz' ${t.opticalSize}`
+      }
+    },
     flip: {
       horizontal: {
         transform: "scaleX(-1)"
@@ -12,6 +30,13 @@ const n = a({
         transform: "scale(-1)"
       }
     },
+    loading: {
+      true: {
+        visibility: "hidden",
+        width: "[1em]",
+        height: "[1em]"
+      }
+    },
     rotate: {
       90: {
         transform: "rotate(90deg)"
@@ -37,8 +62,17 @@ const n = a({
         animationStyle: "icon-spin-3"
       }
     }
-  }
+  },
+  compoundVariants: [
+    {
+      type: "material",
+      filled: !0,
+      css: {
+        fontVariationSettings: `'FILL' 1, 'wght' ${t.weight}, 'GRAD' ${t.grade}, 'opsz' ${t.opticalSize}`
+      }
+    }
+  ]
 });
 export {
-  n as icon
+  o as icon
 };

package/dist/components/Icon/IconProvider.d.ts

@@ -0,0 +1,100 @@
+import { PropsWithChildren } from 'react';
+import { MaterialSymbol } from 'material-symbols';
+import { ShadowContainer } from '../../types';
+import { IressTestProps } from '../../interfaces';
+export type IconType = 'fontawesome' | 'material';
+export interface IconContextValue<P extends IconType = IconType> {
+    /**
+     * Check if an icon is already loaded (for Material Symbols only)
+     * @param name - The name of the Material Symbol icon
+     * @returns True if the icon is loaded, false otherwise
+     */
+    isIconLoaded: (name: MaterialSymbol) => boolean;
+    /**
+     * Register an icon as used (for Material Symbols only)
+     * @param name - The name of the Material Symbol icon
+     * @returns void
+     */
+    registerIcon: (name: MaterialSymbol) => void;
+    /**
+     * The icon provider type being used
+     * @default 'material'
+     */
+    type: P;
+}
+export declare const IconContext: import('react').Context<IconContextValue<IconType> | null>;
+export interface IressIconProviderProps<P extends IconType = 'material'> extends PropsWithChildren, IressTestProps {
+    /**
+     * Optional container to inject the font styles into.
+     * Can be a ShadowRoot, HTMLElement, or a ref to either.
+     * Note: Font is always injected into document head as well.
+     */
+    container?: ShadowContainer;
+    /**
+     * Disable automatic font subsetting via Google Fonts CDN
+     * When false, only icons actually used in the component tree are loaded
+     * When true, the full Material Symbols font is loaded
+     * @default false
+     */
+    noSubsetting?: P extends 'material' ? boolean : never;
+    /**
+     * The icon provider to use for all child icons
+     * @default 'material'
+     */
+    type?: P;
+}
+/**
+ * This provider tracks Material Symbols usage across your app and dynamically
+ * loads only the icons you use via Google Fonts CDN, dramatically reducing
+ * font payload size.
+ *
+ * Loads Material Symbols Rounded with fixed parameters:
+ * - Weight: 300
+ * - FILL: 0 (default state) to 1 (active state)
+ * - Grade: 24
+ * - Optical Size: 24dp
+ *
+ * @example
+ * ```tsx
+ * import { IconProvider } from '@iress-oss/ids-components';
+ *
+ * function App() {
+ *   return (
+ *     <IconProvider>
+ *       <YourApp />
+ *     </IconProvider>
+ *   );
+ * }
+ * ```
+ *
+ * **Bundle Size Optimization:**
+ * - Full font: ~1.4MB
+ * - 18 icons (typical usage): ~15-20KB (85% savings)
+ * - Auto-optimizes based on actual usage
+ *
+ * **Trade-offs:**
+ * - ✅ Automatic optimization (no consumer config needed)
+ * - ✅ Works for any number of icons (1 to 1000+)
+ * - ✅ Google CDN handles caching
+ * - ⚠️ Requires internet connection
+ * - ⚠️ Brief icon loading delay
+ *
+ * **When to Use:**
+ * - You want automatic bundle size optimization
+ * - Network connectivity is expected
+ * - Icon loading delay is acceptable (typically <500ms on fast connections)
+ *
+ * **When NOT to Use:**
+ * - Using more than ~50 icons (consider full font instead)
+ * - Offline apps (use full bundled font instead)
+ * - SSR with critical icons (icons may flash during hydration)
+ * - Need deterministic font versions (Google controls CDN updates)
+ *
+ * ---
+ *
+ * It also provides Font Awesome fonts when using that icon set.
+ */
+export declare const IressIconProvider: {
+    <P extends IconType = "material">({ children, container, "data-testid": dataTestId, type, noSubsetting, }: IressIconProviderProps<P>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/Icon/IconProvider.js

@@ -0,0 +1,66 @@
+import { jsxs as h, jsx as l } from "react/jsx-runtime";
+import { createContext as w, useState as y, useCallback as S } from "react";
+import { FontLoader as m } from "./components/FontLoader.js";
+import { useDynamicFontSubsetting as g } from "./hooks/useDynamicFontSubsetting.js";
+import { MATERIAL_SYMBOLS as e } from "./Icon.constants.js";
+const L = w(null), $ = ({
+  children: c,
+  container: i,
+  "data-testid": n,
+  type: t = "material",
+  noSubsetting: a = !1
+}) => {
+  const [d, f] = y(/* @__PURE__ */ new Set()), u = S(
+    (o) => {
+      a || f((s) => {
+        if (!s.has(o)) {
+          const r = new Set(s);
+          return r.add(o), r;
+        }
+        return s;
+      });
+    },
+    [a]
+  ), { isIconLoaded: I } = g({
+    icons: d,
+    buildUrl: (o) => {
+      let s = a ? "" : `&icon_names=${encodeURIComponent(o.join(","))}`;
+      return `https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@${e.opticalSize},${e.weight},0..1,${e.grade}${s}`;
+    },
+    dataAttribute: "material-icons-subset",
+    fontFamily: "Material Symbols Rounded",
+    disabled: t !== "material",
+    noSubsetting: a
+  }), p = {
+    type: t,
+    registerIcon: u,
+    isIconLoaded: (o) => t !== "material" ? !0 : I(o)
+  };
+  return /* @__PURE__ */ h(L.Provider, { value: p, children: [
+    c,
+    t === "material" && i && /* @__PURE__ */ l(
+      m,
+      {
+        url: `https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@${e.opticalSize},${e.weight},0..1,${e.grade}`,
+        container: i,
+        onlyShadow: !0,
+        keyPrefix: "material-symbols-fonts",
+        "data-testid": n
+      }
+    ),
+    t === "fontawesome" && /* @__PURE__ */ l(
+      m,
+      {
+        url: "https://cdn.iress.com/icons/5.15.4/css/combined.min.css",
+        container: i,
+        keyPrefix: "font-awesome-fonts",
+        "data-testid": n
+      }
+    )
+  ] });
+};
+$.displayName = "IressIconProvider";
+export {
+  L as IconContext,
+  $ as IressIconProvider
+};

package/dist/components/Icon/components/FontLoader.d.ts

@@ -0,0 +1,31 @@
+import { ShadowContainer } from '../../../types';
+import { IressTestProps } from '../../../interfaces';
+export interface FontLoaderProps extends IressTestProps {
+    /**
+     * Optional container to inject the font styles into.
+     * Can be a ShadowRoot, HTMLElement, or a ref to either.
+     * Note: Font is always injected into document head as well.
+     */
+    container?: ShadowContainer;
+    /**
+     * Unique key prefix for the portal keys
+     */
+    keyPrefix: string;
+    /**
+     * Only load into the shadow container, not the head
+     * Used when the font is already loaded in the head in a different method (eg. subsetting)
+     */
+    onlyShadow?: boolean;
+    /**
+     * The URL of the font stylesheet to load
+     */
+    url: string;
+}
+/**
+ * Shared component for injecting font stylesheets into document head and optional shadow container.
+ * This component uses React's createPortal to ensure the font styles are added where required.
+ *
+ * Uses <style> tags with @import to support CSS layers, which has lower priority
+ * than Panda CSS utilities. This allows Panda CSS styling props to override the default font styles.
+ */
+export declare const FontLoader: ({ container, keyPrefix, onlyShadow, url, }: FontLoaderProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/Icon/components/FontLoader.js

@@ -0,0 +1,29 @@
+import { jsxs as a, Fragment as u, jsx as d } from "react/jsx-runtime";
+import { createPortal as o } from "react-dom";
+const i = ({
+  container: e,
+  keyPrefix: l,
+  onlyShadow: s,
+  url: r
+}) => {
+  if (typeof document > "u")
+    return null;
+  let t = null;
+  e && ("current" in e ? t = e.current : t = e);
+  const n = `@import url("${r}") layer(reset);`;
+  return /* @__PURE__ */ a(u, { children: [
+    !s && o(
+      /* @__PURE__ */ d("style", { "data-url": r, children: n }),
+      document.head,
+      `${l}-head`
+    ),
+    t && o(
+      /* @__PURE__ */ d("style", { "data-url": r, children: n }),
+      t,
+      `${l}-shadow`
+    )
+  ] });
+};
+export {
+  i as FontLoader
+};

package/dist/components/Icon/helpers/getMaterialSymbolsList.d.ts

@@ -0,0 +1,12 @@
+import { MaterialSymbol } from 'material-symbols';
+/**
+ * Extracts all Material Symbol names from the type definition.
+ * This is done lazily to avoid processing 3800+ icon names until needed.
+ *
+ * @returns Promise resolving to array of all Material Symbol names
+ */
+export declare const getMaterialSymbolsList: () => Promise<MaterialSymbol[]>;
+/**
+ * Get the Material Symbols list with caching
+ */
+export declare const getMaterialSymbolsListCached: () => Promise<MaterialSymbol[]>;

package/dist/components/Icon/helpers/getMaterialSymbolsList.js

@@ -0,0 +1,12 @@
+const a = async () => {
+  const { default: o } = await import("../../../index.d-CZvOUeIl.js"), l = o, s = /type MaterialSymbols = (\[)([\s\S]*?)(\]);/.exec(l);
+  if (!s)
+    throw new Error("Could not parse Material Symbols type definition");
+  return s[2].split(",").map((t) => t.trim()).filter((t) => t.startsWith('"')).map((t) => t.replace(/(^")|("$)/g, ""));
+};
+let e = null;
+const m = () => (e ??= a(), e);
+export {
+  a as getMaterialSymbolsList,
+  m as getMaterialSymbolsListCached
+};

package/dist/components/Icon/helpers/iconMapping.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Maps Font Awesome icon names to Material Symbols names
+ *
+ * This mapping is based on actual consumer usage patterns and provides
+ * semantic equivalents for common icons used in the design system.
+ *
+ * Naming convention differences:
+ * - Font Awesome: kebab-case (e.g., 'arrow-left', 'smile-wink')
+ * - Material Symbols: snake_case (e.g., 'arrow_back', 'sentiment_satisfied')
+ */
+export declare const FA_TO_MATERIAL_MAP: {
+    check: "check";
+    times: "close";
+    'times-circle': "cancel";
+    spinner: "progress_activity";
+    'lock-alt': "lock";
+    lock: "lock";
+    'chevron-down': "keyboard_arrow_down";
+    'chevron-up': "keyboard_arrow_up";
+    'chevron-left': "keyboard_arrow_left";
+    'chevron-right': "keyboard_arrow_right";
+    'chevron-double-down': "keyboard_double_arrow_down";
+    'chevron-double-up': "keyboard_double_arrow_up";
+    'chevron-circle-down': "expand_circle_down";
+    'arrow-left': "arrow_back";
+    'arrow-right': "arrow_forward";
+    'arrow-up': "arrow_upward";
+    'arrow-down': "arrow_downward";
+    'user-circle': "account_circle";
+    'power-off': "power_settings_new";
+    'ellipsis-v': "more_vert";
+    'ellipsis-h': "more_horiz";
+    bars: "menu";
+    search: "search";
+    cog: "settings";
+    'file-image': "image";
+    'file-pdf': "picture_as_pdf";
+    'file-spreadsheet': "table_chart";
+    'file-word': "description";
+    file: "drive_folder_upload";
+    folder: "folder";
+    'folder-open': "folder_open";
+    home: "home";
+    trash: "delete";
+    edit: "edit";
+    pencil: "edit";
+    plus: "add";
+    minus: "remove";
+    info: "info";
+    'info-circle': "info";
+    question: "help";
+    'question-circle': "help";
+    'exclamation-triangle': "warning";
+    star: "star";
+    heart: "favorite";
+    calendar: "calendar_today";
+    clock: "schedule";
+    bell: "notifications";
+    envelope: "mail";
+    download: "download";
+    upload: "upload";
+    print: "print";
+    share: "share";
+    link: "link";
+    'external-link': "open_in_new";
+    ban: "block";
+    'info-square': "info";
+    'align-left': "format_align_left";
+    'align-center': "format_align_center";
+    'align-right': "format_align_right";
+    'align-justify': "format_align_justify";
+    eye: "visibility";
+    'spinner-third': "progress_activity";
+    'file-alt': "draft";
+    user: "account_circle";
+    'plus-circle': "add_circle";
+};
+export type FontAwesomeIconWithMaterialEquivalent = keyof typeof FA_TO_MATERIAL_MAP;

package/dist/components/Icon/helpers/iconMapping.js

@@ -0,0 +1,75 @@
+const e = {
+  // Status & Feedback
+  check: "check",
+  times: "close",
+  "times-circle": "cancel",
+  spinner: "progress_activity",
+  "lock-alt": "lock",
+  lock: "lock",
+  // Navigation & Arrows
+  "chevron-down": "keyboard_arrow_down",
+  "chevron-up": "keyboard_arrow_up",
+  "chevron-left": "keyboard_arrow_left",
+  "chevron-right": "keyboard_arrow_right",
+  "chevron-double-down": "keyboard_double_arrow_down",
+  "chevron-double-up": "keyboard_double_arrow_up",
+  "chevron-circle-down": "expand_circle_down",
+  "arrow-left": "arrow_back",
+  "arrow-right": "arrow_forward",
+  "arrow-up": "arrow_upward",
+  "arrow-down": "arrow_downward",
+  // UI Controls & Actions
+  "user-circle": "account_circle",
+  "power-off": "power_settings_new",
+  "ellipsis-v": "more_vert",
+  "ellipsis-h": "more_horiz",
+  bars: "menu",
+  search: "search",
+  cog: "settings",
+  // File Types
+  "file-image": "image",
+  "file-pdf": "picture_as_pdf",
+  "file-spreadsheet": "table_chart",
+  "file-word": "description",
+  file: "drive_folder_upload",
+  folder: "folder",
+  "folder-open": "folder_open",
+  // Common Icons
+  home: "home",
+  trash: "delete",
+  edit: "edit",
+  pencil: "edit",
+  plus: "add",
+  minus: "remove",
+  info: "info",
+  "info-circle": "info",
+  question: "help",
+  "question-circle": "help",
+  "exclamation-triangle": "warning",
+  star: "star",
+  heart: "favorite",
+  calendar: "calendar_today",
+  clock: "schedule",
+  bell: "notifications",
+  envelope: "mail",
+  download: "download",
+  upload: "upload",
+  print: "print",
+  share: "share",
+  link: "link",
+  "external-link": "open_in_new",
+  ban: "block",
+  "info-square": "info",
+  "align-left": "format_align_left",
+  "align-center": "format_align_center",
+  "align-right": "format_align_right",
+  "align-justify": "format_align_justify",
+  eye: "visibility",
+  "spinner-third": "progress_activity",
+  "file-alt": "draft",
+  user: "account_circle",
+  "plus-circle": "add_circle"
+};
+export {
+  e as FA_TO_MATERIAL_MAP
+};

package/dist/components/Icon/hooks/useDynamicFontSubsetting.d.ts

@@ -0,0 +1,45 @@
+export interface UseDynamicFontSubsettingOptions {
+    /**
+     * Set of icon names to load
+     */
+    icons: Set<string>;
+    /**
+     * Function to build the font URL from an array of icon names
+     */
+    buildUrl: (icons: string[]) => string;
+    /**
+     * Data attribute to identify the link element in the DOM. Must be kebab-case.
+     */
+    dataAttribute: string;
+    /**
+     * Font family name for the Font Loading API
+     */
+    fontFamily: string;
+    /**
+     * Whether the hook is disabled (loads nothing if true)
+     */
+    disabled?: boolean;
+    /**
+     * Whether font subsetting is disabled (full font loaded at once)
+     * When true, all icons are considered loaded after first font load
+     */
+    noSubsetting?: boolean;
+}
+/**
+ * Hook to dynamically load fonts with text subsetting from a CDN.
+ * Only loads the specific glyphs that are actually used, dramatically reducing payload size.
+ *
+ * @example Material Symbols: 1407KB → 15-20KB (98.5% reduction)
+ */
+export declare const useDynamicFontSubsetting: ({ icons, buildUrl, dataAttribute, fontFamily, disabled, noSubsetting, }: UseDynamicFontSubsettingOptions) => {
+    /**
+     * Set of icons that have been loaded and are ready to use
+     */
+    loadedIcons: Set<string>;
+    /**
+     * Check if a specific icon has been loaded
+     * In noSubsetting mode, returns true if fullyLoaded
+     * In subsetting mode, only returns true for individually loaded icons
+     */
+    isIconLoaded: (name: string) => boolean;
+};