@bwp-web/components 1.0.9 → 1.1.0

package/README.md

@@ -49,6 +49,7 @@ For `BiampTable` only:
 | `SegmentedButton`       | Individual toggle button for use inside `SegmentedButtonGroup`                   |
 | `BiampTable`            | Composable data table with sorting, selection, pagination, and more              |
 | `UserInitialsIcon`      | Avatar-style icon showing a user's initials with a deterministic color           |
+| `DynamicSvgIcon`        | Renders a remotely-fetched SVG with a skeleton loader and required fallback      |
 
 ## Usage
 
@@ -247,6 +248,35 @@ import { UserInitialsIcon } from '@bwp-web/components';
 | `sx`     | `SxProps`  | —       | MUI `sx` style overrides                                    |
 | `...`    | `BoxProps` | —       | All other MUI `Box` props are forwarded to the root element |
 
+### DynamicSvgIcon
+
+Fetches an SVG from a URL and renders it as a MUI `SvgIcon`. Shows a `Skeleton` placeholder while loading and a required fallback on error. The `width` and `height` props are enforced across all three states so the layout never shifts.
+
+```tsx
+import { DynamicSvgIcon } from '@bwp-web/components';
+import BrokenImageIcon from '@mui/icons-material/BrokenImage';
+
+<DynamicSvgIcon
+  url="https://example.com/icon.svg"
+  width={32}
+  height={32}
+  fallback={<BrokenImageIcon />}
+/>;
+```
+
+#### DynamicSvgIcon Props
+
+| Prop                | Type                                       | Default      | Description                                       |
+| ------------------- | ------------------------------------------ | ------------ | ------------------------------------------------- |
+| `url`               | `string`                                   | —            | URL of the SVG to fetch                           |
+| `fallback`          | `React.ReactNode`                          | **required** | Element shown when loading fails                  |
+| `width`             | `number`                                   | `24`         | Width in pixels for icon, skeleton, and fallback  |
+| `height`            | `number`                                   | `24`         | Height in pixels for icon, skeleton, and fallback |
+| `skeletonVariant`   | `'circular' \| 'rectangular' \| 'rounded'` | `'circular'` | Skeleton shape during loading                     |
+| `skeletonAnimation` | `'pulse' \| 'wave' \| false`               | `'pulse'`    | Skeleton animation type                           |
+| `onLoad`            | `() => void`                               | —            | Called when the SVG loads successfully            |
+| `onError`           | `(error: string) => void`                  | —            | Called when loading fails                         |
+
 ### BiampTable
 
 A composable data table built on TanStack React Table v8 with support for sorting, row selection, pagination, column visibility, global search, column filters, and CSV export.
@@ -267,3 +297,4 @@ Detailed per-component docs are available in the repository's [`/docs`](../../do
 | [biamp-global-search.md](../../docs/biamp-global-search.md) | `BiampGlobalSearch` — options, filtering, async loading, navigation                 |
 | [biamp-table.md](../../docs/biamp-table.md)                 | `BiampTable` — columns, sorting, selection, pagination, filters, export             |
 | [user-initials-icon.md](../../docs/user-initials-icon.md)   | `UserInitialsIcon` — props, color seeding, sizing, edge cases                       |
+| [dynamic-svg-icon.md](../../docs/dynamic-svg-icon.md)       | `DynamicSvgIcon` — props, hook API, caching, skeleton, fallback                     |

package/dist/DynamicSvgIcon/DynamicSvgIcon.d.ts

@@ -0,0 +1,80 @@
+import type { SvgIconProps } from '@mui/material';
+/** Clear the internal SVG fetch cache. Useful for testing or forcing a refetch. */
+export declare function clearDynamicSvgIconCache(): void;
+export interface UseDynamicSvgIconOptions {
+    /** Called when the SVG loads successfully */
+    onLoad?: () => void;
+    /** Called when loading fails */
+    onError?: (error: string) => void;
+}
+export interface UseDynamicSvgIconResult {
+    /** Whether the SVG is currently being fetched */
+    loading: boolean;
+    /** Error message if fetching failed, null otherwise */
+    error: string | null;
+    /** The inner SVG content (paths, groups, etc.) */
+    svgContent: string | null;
+    /** The viewBox extracted from the source SVG */
+    svgViewBox: string | null;
+}
+/**
+ * Hook that fetches an SVG from a URL and returns the parsed content.
+ * The SVG is rendered as-is — colors and viewBox are preserved from the source.
+ * Results are cached in-memory so subsequent renders with the same URL are instant.
+ *
+ * @param url - URL of the SVG to fetch (supports any URL that `fetch` can handle, including data URLs)
+ * @param options - Optional callbacks for load/error events
+ * @returns Object with `loading`, `error`, `svgContent`, and `svgViewBox` fields
+ *
+ * @example
+ * ```tsx
+ * const { loading, error, svgContent, svgViewBox } = useDynamicSvgIcon(
+ *   'https://example.com/icon.svg',
+ *   { onError: (msg) => console.warn(msg) },
+ * );
+ * ```
+ */
+export declare function useDynamicSvgIcon(url: string, options?: UseDynamicSvgIconOptions): UseDynamicSvgIconResult;
+export interface DynamicSvgIconProps extends Omit<SvgIconProps, 'children' | 'onLoad' | 'onError' | 'width' | 'height'> {
+    /** URL of the SVG to load */
+    url: string;
+    /** Fallback element shown when loading fails */
+    fallback: React.ReactNode;
+    /** Width in pixels — applied to icon, skeleton, and fallback (default: 24) */
+    width?: number;
+    /** Height in pixels — applied to icon, skeleton, and fallback (default: 24) */
+    height?: number;
+    /** Skeleton shape shown during loading (default: 'circular') */
+    skeletonVariant?: 'circular' | 'rectangular' | 'rounded';
+    /** Skeleton animation type (default: 'pulse') */
+    skeletonAnimation?: 'pulse' | 'wave' | false;
+    /** Called when the SVG loads successfully */
+    onLoad?: () => void;
+    /** Called when loading fails */
+    onError?: (error: string) => void;
+}
+/**
+ * Renders an SVG icon fetched from a URL with a MUI Skeleton placeholder during
+ * loading and a required fallback on error. The `width` and `height` props
+ * control the dimensions of all three states (skeleton, icon, fallback).
+ *
+ * The SVG is rendered as-is — fill, stroke, and viewBox are preserved from the
+ * source. Paths without an explicit fill will inherit `currentColor` from MUI
+ * SvgIcon's CSS, so they respond to the parent's text color.
+ *
+ * Fetched SVGs are cached in-memory; the same URL will only be fetched once
+ * per page session. Use {@link clearDynamicSvgIconCache} to force a refetch.
+ *
+ * @example
+ * ```tsx
+ * <DynamicSvgIcon
+ *   url="https://example.com/icon.svg"
+ *   width={32}
+ *   height={32}
+ *   fallback={<BrokenImageIcon />}
+ *   onError={(msg) => console.warn(msg)}
+ * />
+ * ```
+ */
+export declare function DynamicSvgIcon({ url, fallback, width, height, skeletonVariant, skeletonAnimation, onLoad, onError, sx, ...svgIconProps }: DynamicSvgIconProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DynamicSvgIcon.d.ts.map

package/dist/DynamicSvgIcon/DynamicSvgIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicSvgIcon.d.ts","sourceRoot":"","sources":["../../src/DynamicSvgIcon/DynamicSvgIcon.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAUlD,mFAAmF;AACnF,wBAAgB,wBAAwB,SAEvC;AAED,MAAM,WAAW,wBAAwB;IACvC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kDAAkD;IAClD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gDAAgD;IAChD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,wBAA6B,GACrC,uBAAuB,CAwFzB;AAID,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAC/C,YAAY,EACZ,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CACvD;IACC,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,eAAe,CAAC,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC;IACzD,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IAC7C,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,GAAG,EACH,QAAQ,EACR,KAAoB,EACpB,MAAqB,EACrB,eAA4B,EAC5B,iBAA2B,EAC3B,MAAM,EACN,OAAO,EACP,EAAE,EACF,GAAG,YAAY,EAChB,EAAE,mBAAmB,2CAqDrB"}

package/dist/DynamicSvgIcon/index.d.ts

@@ -0,0 +1,3 @@
+export { DynamicSvgIcon, useDynamicSvgIcon, clearDynamicSvgIconCache, } from './DynamicSvgIcon';
+export type { DynamicSvgIconProps, UseDynamicSvgIconOptions, UseDynamicSvgIconResult, } from './DynamicSvgIcon';
+//# sourceMappingURL=index.d.ts.map

package/dist/DynamicSvgIcon/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/DynamicSvgIcon/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC"}

package/dist/index.cjs

@@ -438,10 +438,12 @@ __export(index_exports, {
   BiampTableToolbarSearch: () => BiampTableToolbarSearch,
   BiampTableTruncatedCell: () => BiampTableTruncatedCell,
   BiampWrapper: () => BiampWrapper,
+  DynamicSvgIcon: () => DynamicSvgIcon,
   SegmentedButton: () => SegmentedButton,
   SegmentedButtonGroup: () => SegmentedButtonGroup,
   UserInitialsIcon: () => UserInitialsIcon,
   buildCsvString: () => buildCsvString,
+  clearDynamicSvgIconCache: () => clearDynamicSvgIconCache,
   exportToCsv: () => exportToCsv,
   getColumnVisibilityDirtyCount: () => getColumnVisibilityDirtyCount,
   getDefaultColumnVisibility: () => getDefaultColumnVisibility,
@@ -454,7 +456,8 @@ __export(index_exports, {
   sortingToOrder: () => sortingToOrder,
   toVisibilityState: () => toVisibilityState,
   useBiampServerSideTable: () => useBiampServerSideTable,
-  useDebouncedCallback: () => useDebouncedCallback
+  useDebouncedCallback: () => useDebouncedCallback,
+  useDynamicSvgIcon: () => useDynamicSvgIcon
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -2759,6 +2762,150 @@ var getInitials = (name) => {
   const initials = words.filter(Boolean).slice(0, 2).map((word) => word[0].toUpperCase()).join("");
   return initials;
 };
+
+// src/DynamicSvgIcon/DynamicSvgIcon.tsx
+var import_material23 = require("@mui/material");
+var import_react12 = require("react");
+var import_jsx_runtime26 = require("react/jsx-runtime");
+var svgCache = /* @__PURE__ */ new Map();
+function clearDynamicSvgIconCache() {
+  svgCache.clear();
+}
+function useDynamicSvgIcon(url, options = {}) {
+  const { onLoad, onError } = options;
+  const [svgContent, setSvgContent] = (0, import_react12.useState)(() => {
+    const cached = svgCache.get(url);
+    return cached ? cached.innerContent : null;
+  });
+  const [svgViewBox, setSvgViewBox] = (0, import_react12.useState)(() => {
+    const cached = svgCache.get(url);
+    return cached?.viewBox ?? null;
+  });
+  const [loading, setLoading] = (0, import_react12.useState)(() => !svgCache.has(url));
+  const [error, setError] = (0, import_react12.useState)(null);
+  (0, import_react12.useEffect)(() => {
+    if (!url) {
+      setLoading(false);
+      setError("No URL provided");
+      setSvgContent(null);
+      setSvgViewBox(null);
+      return;
+    }
+    let cancelled = false;
+    const cached = svgCache.get(url);
+    if (cached) {
+      setSvgContent(cached.innerContent);
+      setSvgViewBox(cached.viewBox);
+      setLoading(false);
+      setError(null);
+      onLoad?.();
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    setSvgContent(null);
+    setSvgViewBox(null);
+    (async () => {
+      try {
+        const response = await fetch(url);
+        if (!response.ok) {
+          throw new Error(
+            `Failed to fetch SVG: ${response.status} ${response.statusText}`
+          );
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        const text = await response.text();
+        if (!text.includes("<svg") && !contentType.includes("svg")) {
+          throw new Error("Response is not an SVG");
+        }
+        const viewBoxMatch = text.match(/viewBox="([^"]*)"/);
+        const viewBox = viewBoxMatch ? viewBoxMatch[1] : null;
+        const svgMatch = text.match(/<svg[^>]*>([\s\S]*?)<\/svg>/);
+        const innerContent = svgMatch ? svgMatch[1] : text;
+        svgCache.set(url, { innerContent, viewBox });
+        if (!cancelled) {
+          setSvgContent(innerContent);
+          setSvgViewBox(viewBox);
+          setLoading(false);
+          onLoad?.();
+        }
+      } catch (err) {
+        if (!cancelled) {
+          const message = err instanceof Error ? err.message : "Failed to load SVG";
+          setError(message);
+          setLoading(false);
+          onError?.(message);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [url]);
+  return { loading, error, svgContent, svgViewBox };
+}
+var DEFAULT_SIZE2 = 24;
+function DynamicSvgIcon({
+  url,
+  fallback,
+  width = DEFAULT_SIZE2,
+  height = DEFAULT_SIZE2,
+  skeletonVariant = "circular",
+  skeletonAnimation = "pulse",
+  onLoad,
+  onError,
+  sx,
+  ...svgIconProps
+}) {
+  const { loading, error, svgContent, svgViewBox } = useDynamicSvgIcon(url, {
+    onLoad,
+    onError
+  });
+  if (loading) {
+    return /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(
+      import_material23.Skeleton,
+      {
+        variant: skeletonVariant,
+        animation: skeletonAnimation,
+        sx: { width, height }
+      }
+    );
+  }
+  if (error || !svgContent) {
+    return /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(
+      import_material23.Box,
+      {
+        sx: {
+          width,
+          height,
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          overflow: "hidden",
+          flexShrink: 0,
+          "& > svg, & > .MuiSvgIcon-root": {
+            width: "100%",
+            height: "100%"
+          }
+        },
+        children: fallback
+      }
+    );
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime26.jsx)(
+    import_material23.SvgIcon,
+    {
+      ...svgIconProps,
+      ...svgViewBox && { viewBox: svgViewBox },
+      sx: {
+        ...typeof sx === "object" && sx !== null && !Array.isArray(sx) ? sx : void 0,
+        width,
+        height
+      },
+      children: /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("g", { dangerouslySetInnerHTML: { __html: svgContent } })
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BIAMP_TABLE_DEBOUNCE_DELAY,
@@ -2799,10 +2946,12 @@ var getInitials = (name) => {
   BiampTableToolbarSearch,
   BiampTableTruncatedCell,
   BiampWrapper,
+  DynamicSvgIcon,
   SegmentedButton,
   SegmentedButtonGroup,
   UserInitialsIcon,
   buildCsvString,
+  clearDynamicSvgIconCache,
   exportToCsv,
   getColumnVisibilityDirtyCount,
   getDefaultColumnVisibility,
@@ -2815,6 +2964,7 @@ var getInitials = (name) => {
   sortingToOrder,
   toVisibilityState,
   useBiampServerSideTable,
-  useDebouncedCallback
+  useDebouncedCallback,
+  useDynamicSvgIcon
 });
 //# sourceMappingURL=index.cjs.map