@flipdish/ui-library 0.31.3 → 0.31.5

package/dist/utilities/localStorageUtils/index.js

@@ -12,12 +12,15 @@ import { LOCAL_STORAGE_KEYS } from './localStorageUtils.constants.js';
  * — check there for the full list before adding a new one.
  */
 /**
- * Build a typed, failure-safe accessor for a single `localStorage` key.
+ * Builds a typed, failure-safe accessor for a single `localStorage` key.
  *
- * @example
- * const draft = createLocalStorageItem<Draft>('fd-draft');
- * draft.set({ title: 'Hi' });
- * const value = draft.get(); // Draft | null
+ *   const draft = createLocalStorageItem<Draft>('fd-draft'); draft.set({ title: 'Hi' }); draft.get(); // Draft | null
+ *
+ * @param key The storage key; register it in `LOCAL_STORAGE_KEYS` first.
+ * @param options Custom `serialize`/`deserialize` and a `validate` guard; see
+ *   `LocalStorageItemOptions`.
+ * @returns `get`, `set` and `clear` that never throw; `get()` returns `null` when storage is
+ *   unavailable, while `set()` and `clear()` return `void` and ignore failures.
  */
 const createLocalStorageItem = (key, options = {}) => createWebStorageItem(() => window.localStorage, key, options);
 /**

package/dist/utilities/localStorageUtils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/utilities/localStorageUtils/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;;;;;;;;;AASG;AA2BH;;;;;;;AAOG;AACI,MAAM,sBAAsB,GAAG,CAAI,GAAW,EAAE,OAAA,GAAsC,EAAE,KAC7F,oBAAoB,CAAC,MAAM,MAAM,CAAC,YAAY,EAAE,GAAG,EAAE,OAAO;AAE9D;;;AAGG;MACU,uBAAuB,GAAG,sBAAsB,CAAU,kBAAkB,CAAC,gBAAgB,EAAE;AAC1G,IAAA,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,CAAC,GAAG,KAAK,kBAAkB,CAAC,GAAG,EAAE,iCAAiC,CAAC;AAChF,IAAA,QAAQ,EAAE,SAAS;AACpB,CAAA;AAED;MACa,gBAAgB,GAAG,sBAAsB,CAAS,kBAAkB,CAAC,SAAS,EAAE;AAC3F,IAAA,SAAS,EAAE,MAAM;AACjB,IAAA,WAAW,EAAE,CAAC,GAAG,KAAK,GAAG;AACzB,IAAA,QAAQ,EAAE,QAAQ;AACnB,CAAA;;"}
+{"version":3,"file":"index.js","sources":["../../../src/utilities/localStorageUtils/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;;;;;;;;;AASG;AA2BH;;;;;;;;;;AAUG;AACI,MAAM,sBAAsB,GAAG,CAAI,GAAW,EAAE,OAAA,GAAsC,EAAE,KAC7F,oBAAoB,CAAC,MAAM,MAAM,CAAC,YAAY,EAAE,GAAG,EAAE,OAAO;AAE9D;;;AAGG;MACU,uBAAuB,GAAG,sBAAsB,CAAU,kBAAkB,CAAC,gBAAgB,EAAE;AAC1G,IAAA,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,CAAC,GAAG,KAAK,kBAAkB,CAAC,GAAG,EAAE,iCAAiC,CAAC;AAChF,IAAA,QAAQ,EAAE,SAAS;AACpB,CAAA;AAED;MACa,gBAAgB,GAAG,sBAAsB,CAAS,kBAAkB,CAAC,SAAS,EAAE;AAC3F,IAAA,SAAS,EAAE,MAAM;AACjB,IAAA,WAAW,EAAE,CAAC,GAAG,KAAK,GAAG;AACzB,IAAA,QAAQ,EAAE,QAAQ;AACnB,CAAA;;"}

package/dist/utilities/renderUtils/index.cjs

@@ -4,10 +4,11 @@ var React = require('react');
 var importWithRetry_utils = require('./importWithRetry.utils.cjs');
 
 /**
- * Retrieves an environment variable.
+ * Reads an environment variable from `process.env` first (tests, SSR), then Vite's
+ * `import.meta.env`.
  *
- * @param key The key of the environment variable to retrieve.
- * @returns The value of the environment variable.
+ * @param key The variable name, such as `VITE_APPID_OVERRIDE`.
+ * @returns Its value, or an empty string when neither source defines it.
  */
 const getEnvironmentVariable = (key) => {
     // Prefer Node env in tests/SSR
@@ -23,10 +24,10 @@ const getEnvironmentVariable = (key) => {
     return viteEnv?.[key] ?? '';
 };
 /**
- * Retrieves a micro-frontend attribute.
+ * Reads an attribute from the `#flipdish-micro-frontend` container Portal mounts the app into.
  *
- * @param key The key of the attribute to retrieve.
- * @returns The value of the attribute.
+ * @param key The attribute name, such as `data-app-id`.
+ * @returns Its value, or an empty string when there is no document or no such attribute.
  */
 const getMicroFrontendAttribute = (key) => {
     if (typeof document === 'undefined') {
@@ -36,49 +37,42 @@ const getMicroFrontendAttribute = (key) => {
     return microFrontendDiv?.getAttribute(key) || '';
 };
 /**
- * Retrieves the AppId.
+ * Reads the app id: the `VITE_APPID_OVERRIDE` environment variable first, then the container's
+ * `data-app-id` attribute (`data-appid` for portal-library 5.1.0 and below). Read once at call
+ * time; a component will not re-render when the value changes.
  *
- * Attempts to get the value from the environment variable `VITE_APPID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-app-id`.
- * Fallbacks to `data-appid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
- *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The app id, or an empty string when neither source provides one.
  */
 const getAppId = () => {
     return getEnvironmentVariable('VITE_APPID_OVERRIDE') || getMicroFrontendAttribute('data-app-id') || getMicroFrontendAttribute('data-appid');
 };
 /**
- * Retrieves the OrgId.
- *
- * Attempts to get the value from the environment variable `VITE_ORGID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-org-id`.
- * Fallbacks to `data-orgid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
+ * Reads the org id: the `VITE_ORGID_OVERRIDE` environment variable first, then the container's
+ * `data-org-id` attribute (`data-orgid` for portal-library 5.1.0 and below). Read once at call
+ * time; a component will not re-render when the value changes.
  *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The org id, or an empty string when neither source provides one.
  */
 const getOrgId = () => {
     return getEnvironmentVariable('VITE_ORGID_OVERRIDE') || getMicroFrontendAttribute('data-org-id') || getMicroFrontendAttribute('data-orgid');
 };
 /**
- * Retrieves the BrandId.
+ * Reads the brand id: the `VITE_BRANDID_OVERRIDE` environment variable first, then the
+ * container's `data-brand-id` attribute (`data-brandid` for portal-library 5.1.0 and below).
+ * Read once at call time; a component will not re-render when the value changes.
  *
- * Attempts to get the value from the environment variable `VITE_BRANDID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-brand-id`.
- * Fallbacks to `data-brandid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
- *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The brand id, or an empty string when neither source provides one.
  */
 const getBrandId = () => {
     return getEnvironmentVariable('VITE_BRANDID_OVERRIDE') || getMicroFrontendAttribute('data-brand-id') || getMicroFrontendAttribute('data-brandid');
 };
 /**
- * Retrieves the isFlipdishStaff attribute.
- *
- * Attempts to get the value from the environment variable `VITE_ISFLIPDISHSTAFFOVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-is-flipdish-staff`.
- * Fallbacks to `data-isflipdishstaff` for backwards compatibility @flipdish/portal-library@5.1.0 and below
+ * Reads the Flipdish-staff flag: the `VITE_ISFLIPDISHSTAFFOVERRIDE` environment variable
+ * first, then the container's `data-is-flipdish-staff` attribute (`data-isflipdishstaff` for
+ * portal-library 5.1.0 and below). Read once at call time; a component will not re-render when
+ * the value changes.
  *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns `true` when the value reads as true, otherwise `false`.
  */
 const getIsFlipdishStaff = () => {
     const stringValue = getEnvironmentVariable('VITE_ISFLIPDISHSTAFFOVERRIDE') ||
@@ -86,6 +80,13 @@ const getIsFlipdishStaff = () => {
         getMicroFrontendAttribute('data-isflipdishstaff');
     return stringValue?.toString() === 'true';
 };
+/**
+ * `React.lazy` that reloads the page once when a dynamic import fails, on the assumption that
+ * a deploy replaced the chunk; a second failure after the reload is thrown as a real error.
+ *
+ * @param componentImport The `() => import('./Page')` factory you would pass to `React.lazy`.
+ * @returns A lazy component to render inside `Suspense`.
+ */
 // biome-ignore lint/suspicious/noExplicitAny: dynamic import factory shape isn't expressible without `any`; preserved from portal-library implementation
 const lazyWithRetry = (componentImport) => React.lazy(() => importWithRetry_utils.importWithRetry(componentImport));
 

package/dist/utilities/renderUtils/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../../../src/utilities/renderUtils/index.ts"],"sourcesContent":[null],"names":["lazy","importWithRetry"],"mappings":";;;;;AAIA;;;;;AAKG;AACI,MAAM,sBAAsB,GAAG,CAAC,GAAW,KAAY;;AAE5D,IAAA,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE;AACzF,QAAA,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAW;IACnC;;;;;;AAMA,IAAA,MAAM,OAAO,GAAI,SAA6E;AAC9F,IAAA,OAAO,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE;AAC7B;AAEA;;;;;AAKG;AACI,MAAM,yBAAyB,GAAG,CAAC,GAAW,KAAY;AAC/D,IAAA,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE;AACnC,QAAA,OAAO,EAAE;IACX;IACA,MAAM,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,yBAAyB,CAAC;IAC3E,OAAO,gBAAgB,EAAE,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE;AAClD;AAEA;;;;;;;;AAQG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;;;AAQG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;;;AAQG;AACI,MAAM,UAAU,GAAG,MAAa;AACrC,IAAA,OAAO,sBAAsB,CAAC,uBAAuB,CAAC,IAAI,yBAAyB,CAAC,eAAe,CAAC,IAAI,yBAAyB,CAAC,cAAc,CAAC;AACnJ;AAEA;;;;;;;;AAQG;AACI,MAAM,kBAAkB,GAAG,MAAc;AAC9C,IAAA,MAAM,WAAW,GACf,sBAAsB,CAAC,8BAA8B,CAAC;QACtD,yBAAyB,CAAC,wBAAwB,CAAC;QACnD,yBAAyB,CAAC,sBAAsB,CAAC;AACnD,IAAA,OAAO,WAAW,EAAE,QAAQ,EAAE,KAAK,MAAM;AAC3C;AAEA;AACO,MAAM,aAAa,GAAG,CAAC,eAA0B,KAAKA,UAAI,CAAC,MAAMC,qCAAe,CAAC,eAAe,CAAC;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":["../../../src/utilities/renderUtils/index.ts"],"sourcesContent":[null],"names":["lazy","importWithRetry"],"mappings":";;;;;AAIA;;;;;;AAMG;AACI,MAAM,sBAAsB,GAAG,CAAC,GAAW,KAAY;;AAE5D,IAAA,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE;AACzF,QAAA,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAW;IACnC;;;;;;AAMA,IAAA,MAAM,OAAO,GAAI,SAA6E;AAC9F,IAAA,OAAO,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE;AAC7B;AAEA;;;;;AAKG;AACI,MAAM,yBAAyB,GAAG,CAAC,GAAW,KAAY;AAC/D,IAAA,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE;AACnC,QAAA,OAAO,EAAE;IACX;IACA,MAAM,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,yBAAyB,CAAC;IAC3E,OAAO,gBAAgB,EAAE,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE;AAClD;AAEA;;;;;;AAMG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;AAMG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;AAMG;AACI,MAAM,UAAU,GAAG,MAAa;AACrC,IAAA,OAAO,sBAAsB,CAAC,uBAAuB,CAAC,IAAI,yBAAyB,CAAC,eAAe,CAAC,IAAI,yBAAyB,CAAC,cAAc,CAAC;AACnJ;AAEA;;;;;;;AAOG;AACI,MAAM,kBAAkB,GAAG,MAAc;AAC9C,IAAA,MAAM,WAAW,GACf,sBAAsB,CAAC,8BAA8B,CAAC;QACtD,yBAAyB,CAAC,wBAAwB,CAAC;QACnD,yBAAyB,CAAC,sBAAsB,CAAC;AACnD,IAAA,OAAO,WAAW,EAAE,QAAQ,EAAE,KAAK,MAAM;AAC3C;AAEA;;;;;;AAMG;AACH;AACO,MAAM,aAAa,GAAG,CAAC,eAA0B,KAAKA,UAAI,CAAC,MAAMC,qCAAe,CAAC,eAAe,CAAC;;;;;;;;"}

package/dist/utilities/renderUtils/index.d.ts

@@ -1,56 +1,57 @@
 /**
- * Retrieves an environment variable.
+ * Reads an environment variable from `process.env` first (tests, SSR), then Vite's
+ * `import.meta.env`.
  *
- * @param key The key of the environment variable to retrieve.
- * @returns The value of the environment variable.
+ * @param key The variable name, such as `VITE_APPID_OVERRIDE`.
+ * @returns Its value, or an empty string when neither source defines it.
  */
 export declare const getEnvironmentVariable: (key: string) => string;
 /**
- * Retrieves a micro-frontend attribute.
+ * Reads an attribute from the `#flipdish-micro-frontend` container Portal mounts the app into.
  *
- * @param key The key of the attribute to retrieve.
- * @returns The value of the attribute.
+ * @param key The attribute name, such as `data-app-id`.
+ * @returns Its value, or an empty string when there is no document or no such attribute.
  */
 export declare const getMicroFrontendAttribute: (key: string) => string;
 /**
- * Retrieves the AppId.
+ * Reads the app id: the `VITE_APPID_OVERRIDE` environment variable first, then the container's
+ * `data-app-id` attribute (`data-appid` for portal-library 5.1.0 and below). Read once at call
+ * time; a component will not re-render when the value changes.
  *
- * Attempts to get the value from the environment variable `VITE_APPID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-app-id`.
- * Fallbacks to `data-appid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
- *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The app id, or an empty string when neither source provides one.
  */
 export declare const getAppId: () => string;
 /**
- * Retrieves the OrgId.
- *
- * Attempts to get the value from the environment variable `VITE_ORGID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-org-id`.
- * Fallbacks to `data-orgid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
+ * Reads the org id: the `VITE_ORGID_OVERRIDE` environment variable first, then the container's
+ * `data-org-id` attribute (`data-orgid` for portal-library 5.1.0 and below). Read once at call
+ * time; a component will not re-render when the value changes.
  *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The org id, or an empty string when neither source provides one.
  */
 export declare const getOrgId: () => string;
 /**
- * Retrieves the BrandId.
+ * Reads the brand id: the `VITE_BRANDID_OVERRIDE` environment variable first, then the
+ * container's `data-brand-id` attribute (`data-brandid` for portal-library 5.1.0 and below).
+ * Read once at call time; a component will not re-render when the value changes.
  *
- * Attempts to get the value from the environment variable `VITE_BRANDID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-brand-id`.
- * Fallbacks to `data-brandid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
- *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The brand id, or an empty string when neither source provides one.
  */
 export declare const getBrandId: () => string;
 /**
- * Retrieves the isFlipdishStaff attribute.
- *
- * Attempts to get the value from the environment variable `VITE_ISFLIPDISHSTAFFOVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-is-flipdish-staff`.
- * Fallbacks to `data-isflipdishstaff` for backwards compatibility @flipdish/portal-library@5.1.0 and below
+ * Reads the Flipdish-staff flag: the `VITE_ISFLIPDISHSTAFFOVERRIDE` environment variable
+ * first, then the container's `data-is-flipdish-staff` attribute (`data-isflipdishstaff` for
+ * portal-library 5.1.0 and below). Read once at call time; a component will not re-render when
+ * the value changes.
  *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns `true` when the value reads as true, otherwise `false`.
  */
 export declare const getIsFlipdishStaff: () => boolean;
+/**
+ * `React.lazy` that reloads the page once when a dynamic import fails, on the assumption that
+ * a deploy replaced the chunk; a second failure after the reload is thrown as a real error.
+ *
+ * @param componentImport The `() => import('./Page')` factory you would pass to `React.lazy`.
+ * @returns A lazy component to render inside `Suspense`.
+ */
 export declare const lazyWithRetry: (componentImport: () => any) => import("react").LazyExoticComponent<import("react").ComponentType<any>>;
 //# sourceMappingURL=index.d.ts.map

package/dist/utilities/renderUtils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utilities/renderUtils/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GAAI,KAAK,MAAM,KAAG,MAYpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,KAAK,MAAM,KAAG,MAMvD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,QAAO,MAE3B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,QAAO,MAE3B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,QAAO,MAE7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,QAAO,OAMrC,CAAC;AAGF,eAAO,MAAM,aAAa,GAAI,iBAAiB,MAAM,GAAG,4EAAiD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utilities/renderUtils/index.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,KAAK,MAAM,KAAG,MAYpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,KAAK,MAAM,KAAG,MAMvD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,QAAO,MAE3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,QAAO,MAE3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAO,MAE7B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAAO,OAMrC,CAAC;AAEF;;;;;;GAMG;AAEH,eAAO,MAAM,aAAa,GAAI,iBAAiB,MAAM,GAAG,4EAAiD,CAAC"}

package/dist/utilities/renderUtils/index.js

@@ -2,10 +2,11 @@ import { lazy } from 'react';
 import { importWithRetry } from './importWithRetry.utils.js';
 
 /**
- * Retrieves an environment variable.
+ * Reads an environment variable from `process.env` first (tests, SSR), then Vite's
+ * `import.meta.env`.
  *
- * @param key The key of the environment variable to retrieve.
- * @returns The value of the environment variable.
+ * @param key The variable name, such as `VITE_APPID_OVERRIDE`.
+ * @returns Its value, or an empty string when neither source defines it.
  */
 const getEnvironmentVariable = (key) => {
     // Prefer Node env in tests/SSR
@@ -21,10 +22,10 @@ const getEnvironmentVariable = (key) => {
     return viteEnv?.[key] ?? '';
 };
 /**
- * Retrieves a micro-frontend attribute.
+ * Reads an attribute from the `#flipdish-micro-frontend` container Portal mounts the app into.
  *
- * @param key The key of the attribute to retrieve.
- * @returns The value of the attribute.
+ * @param key The attribute name, such as `data-app-id`.
+ * @returns Its value, or an empty string when there is no document or no such attribute.
  */
 const getMicroFrontendAttribute = (key) => {
     if (typeof document === 'undefined') {
@@ -34,49 +35,42 @@ const getMicroFrontendAttribute = (key) => {
     return microFrontendDiv?.getAttribute(key) || '';
 };
 /**
- * Retrieves the AppId.
+ * Reads the app id: the `VITE_APPID_OVERRIDE` environment variable first, then the container's
+ * `data-app-id` attribute (`data-appid` for portal-library 5.1.0 and below). Read once at call
+ * time; a component will not re-render when the value changes.
  *
- * Attempts to get the value from the environment variable `VITE_APPID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-app-id`.
- * Fallbacks to `data-appid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
- *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The app id, or an empty string when neither source provides one.
  */
 const getAppId = () => {
     return getEnvironmentVariable('VITE_APPID_OVERRIDE') || getMicroFrontendAttribute('data-app-id') || getMicroFrontendAttribute('data-appid');
 };
 /**
- * Retrieves the OrgId.
- *
- * Attempts to get the value from the environment variable `VITE_ORGID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-org-id`.
- * Fallbacks to `data-orgid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
+ * Reads the org id: the `VITE_ORGID_OVERRIDE` environment variable first, then the container's
+ * `data-org-id` attribute (`data-orgid` for portal-library 5.1.0 and below). Read once at call
+ * time; a component will not re-render when the value changes.
  *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The org id, or an empty string when neither source provides one.
  */
 const getOrgId = () => {
     return getEnvironmentVariable('VITE_ORGID_OVERRIDE') || getMicroFrontendAttribute('data-org-id') || getMicroFrontendAttribute('data-orgid');
 };
 /**
- * Retrieves the BrandId.
+ * Reads the brand id: the `VITE_BRANDID_OVERRIDE` environment variable first, then the
+ * container's `data-brand-id` attribute (`data-brandid` for portal-library 5.1.0 and below).
+ * Read once at call time; a component will not re-render when the value changes.
  *
- * Attempts to get the value from the environment variable `VITE_BRANDID_OVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-brand-id`.
- * Fallbacks to `data-brandid` for backwards compatibility @flipdish/portal-library@5.1.0 and below
- *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns The brand id, or an empty string when neither source provides one.
  */
 const getBrandId = () => {
     return getEnvironmentVariable('VITE_BRANDID_OVERRIDE') || getMicroFrontendAttribute('data-brand-id') || getMicroFrontendAttribute('data-brandid');
 };
 /**
- * Retrieves the isFlipdishStaff attribute.
- *
- * Attempts to get the value from the environment variable `VITE_ISFLIPDISHSTAFFOVERRIDE`.
- * If the environment variable is not set, it falls back to retrieving from a micro frontend attribute `data-is-flipdish-staff`.
- * Fallbacks to `data-isflipdishstaff` for backwards compatibility @flipdish/portal-library@5.1.0 and below
+ * Reads the Flipdish-staff flag: the `VITE_ISFLIPDISHSTAFFOVERRIDE` environment variable
+ * first, then the container's `data-is-flipdish-staff` attribute (`data-isflipdishstaff` for
+ * portal-library 5.1.0 and below). Read once at call time; a component will not re-render when
+ * the value changes.
  *
- * @warning Your component will not re-render if the value changes. Use 'useMicroFrontendAttributes' custom hook instead if you care about reactivity.
+ * @returns `true` when the value reads as true, otherwise `false`.
  */
 const getIsFlipdishStaff = () => {
     const stringValue = getEnvironmentVariable('VITE_ISFLIPDISHSTAFFOVERRIDE') ||
@@ -84,6 +78,13 @@ const getIsFlipdishStaff = () => {
         getMicroFrontendAttribute('data-isflipdishstaff');
     return stringValue?.toString() === 'true';
 };
+/**
+ * `React.lazy` that reloads the page once when a dynamic import fails, on the assumption that
+ * a deploy replaced the chunk; a second failure after the reload is thrown as a real error.
+ *
+ * @param componentImport The `() => import('./Page')` factory you would pass to `React.lazy`.
+ * @returns A lazy component to render inside `Suspense`.
+ */
 // biome-ignore lint/suspicious/noExplicitAny: dynamic import factory shape isn't expressible without `any`; preserved from portal-library implementation
 const lazyWithRetry = (componentImport) => lazy(() => importWithRetry(componentImport));
 

package/dist/utilities/renderUtils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/utilities/renderUtils/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;AAKG;AACI,MAAM,sBAAsB,GAAG,CAAC,GAAW,KAAY;;AAE5D,IAAA,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE;AACzF,QAAA,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAW;IACnC;;;;;;AAMA,IAAA,MAAM,OAAO,GAAI,MAAM,CAAC,IAAkE,CAAC,GAAG;AAC9F,IAAA,OAAO,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE;AAC7B;AAEA;;;;;AAKG;AACI,MAAM,yBAAyB,GAAG,CAAC,GAAW,KAAY;AAC/D,IAAA,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE;AACnC,QAAA,OAAO,EAAE;IACX;IACA,MAAM,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,yBAAyB,CAAC;IAC3E,OAAO,gBAAgB,EAAE,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE;AAClD;AAEA;;;;;;;;AAQG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;;;AAQG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;;;AAQG;AACI,MAAM,UAAU,GAAG,MAAa;AACrC,IAAA,OAAO,sBAAsB,CAAC,uBAAuB,CAAC,IAAI,yBAAyB,CAAC,eAAe,CAAC,IAAI,yBAAyB,CAAC,cAAc,CAAC;AACnJ;AAEA;;;;;;;;AAQG;AACI,MAAM,kBAAkB,GAAG,MAAc;AAC9C,IAAA,MAAM,WAAW,GACf,sBAAsB,CAAC,8BAA8B,CAAC;QACtD,yBAAyB,CAAC,wBAAwB,CAAC;QACnD,yBAAyB,CAAC,sBAAsB,CAAC;AACnD,IAAA,OAAO,WAAW,EAAE,QAAQ,EAAE,KAAK,MAAM;AAC3C;AAEA;AACO,MAAM,aAAa,GAAG,CAAC,eAA0B,KAAK,IAAI,CAAC,MAAM,eAAe,CAAC,eAAe,CAAC;;"}
+{"version":3,"file":"index.js","sources":["../../../src/utilities/renderUtils/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;AAMG;AACI,MAAM,sBAAsB,GAAG,CAAC,GAAW,KAAY;;AAE5D,IAAA,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE;AACzF,QAAA,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAW;IACnC;;;;;;AAMA,IAAA,MAAM,OAAO,GAAI,MAAM,CAAC,IAAkE,CAAC,GAAG;AAC9F,IAAA,OAAO,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE;AAC7B;AAEA;;;;;AAKG;AACI,MAAM,yBAAyB,GAAG,CAAC,GAAW,KAAY;AAC/D,IAAA,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE;AACnC,QAAA,OAAO,EAAE;IACX;IACA,MAAM,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,yBAAyB,CAAC;IAC3E,OAAO,gBAAgB,EAAE,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE;AAClD;AAEA;;;;;;AAMG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;AAMG;AACI,MAAM,QAAQ,GAAG,MAAa;AACnC,IAAA,OAAO,sBAAsB,CAAC,qBAAqB,CAAC,IAAI,yBAAyB,CAAC,aAAa,CAAC,IAAI,yBAAyB,CAAC,YAAY,CAAC;AAC7I;AAEA;;;;;;AAMG;AACI,MAAM,UAAU,GAAG,MAAa;AACrC,IAAA,OAAO,sBAAsB,CAAC,uBAAuB,CAAC,IAAI,yBAAyB,CAAC,eAAe,CAAC,IAAI,yBAAyB,CAAC,cAAc,CAAC;AACnJ;AAEA;;;;;;;AAOG;AACI,MAAM,kBAAkB,GAAG,MAAc;AAC9C,IAAA,MAAM,WAAW,GACf,sBAAsB,CAAC,8BAA8B,CAAC;QACtD,yBAAyB,CAAC,wBAAwB,CAAC;QACnD,yBAAyB,CAAC,sBAAsB,CAAC;AACnD,IAAA,OAAO,WAAW,EAAE,QAAQ,EAAE,KAAK,MAAM;AAC3C;AAEA;;;;;;AAMG;AACH;AACO,MAAM,aAAa,GAAG,CAAC,eAA0B,KAAK,IAAI,CAAC,MAAM,eAAe,CAAC,eAAe,CAAC;;"}

package/dist/utilities/sessionStorageUtils/index.cjs

@@ -14,12 +14,15 @@ var sessionStorageUtils_constants = require('./sessionStorageUtils.constants.cjs
  * — check there for the full list before adding a new one.
  */
 /**
- * Build a typed, failure-safe accessor for a single `sessionStorage` key.
+ * Builds a typed, failure-safe accessor for a single `sessionStorage` key.
  *
- * @example
- * const draft = createSessionStorageItem<Draft>('fd-draft');
- * draft.set({ title: 'Hi' });
- * const value = draft.get(); // Draft | null
+ *   const draft = createSessionStorageItem<Draft>('fd-draft'); draft.set({ title: 'Hi' }); draft.get(); // Draft | null
+ *
+ * @param key The storage key; register it in `SESSION_STORAGE_KEYS` first.
+ * @param options Custom `serialize`/`deserialize` and a `validate` guard; see
+ *   `SessionStorageItemOptions`.
+ * @returns `get`, `set` and `clear` that never throw; `get()` returns `null` when storage is
+ *   unavailable, while `set()` and `clear()` return `void` and ignore failures.
  */
 const createSessionStorageItem = (key, options = {}) => webStorage_utils.createWebStorageItem(() => window.sessionStorage, key, options);
 /**

package/dist/utilities/sessionStorageUtils/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../../../src/utilities/sessionStorageUtils/index.ts"],"sourcesContent":[null],"names":["createWebStorageItem","SESSION_STORAGE_KEYS","parseBooleanString","isBoolean"],"mappings":";;;;;AAAA;;;;;;;;;AASG;AA2BH;;;;;;;AAOG;AACI,MAAM,wBAAwB,GAAG,CAAI,GAAW,EAAE,OAAA,GAAwC,EAAE,KACjGA,qCAAoB,CAAC,MAAM,MAAM,CAAC,cAAc,EAAE,GAAG,EAAE,OAAO;AAEhE;;;AAGG;MACU,yBAAyB,GAAG,wBAAwB,CAAUC,kDAAoB,CAAC,yBAAyB,EAAE;AACzH,IAAA,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,CAAC,GAAG,KAAKC,mCAAkB,CAAC,GAAG,EAAE,oCAAoC,CAAC;AACnF,IAAA,QAAQ,EAAEC,0BAAS;AACpB,CAAA;;;;"}
+{"version":3,"file":"index.cjs","sources":["../../../src/utilities/sessionStorageUtils/index.ts"],"sourcesContent":[null],"names":["createWebStorageItem","SESSION_STORAGE_KEYS","parseBooleanString","isBoolean"],"mappings":";;;;;AAAA;;;;;;;;;AASG;AA2BH;;;;;;;;;;AAUG;AACI,MAAM,wBAAwB,GAAG,CAAI,GAAW,EAAE,OAAA,GAAwC,EAAE,KACjGA,qCAAoB,CAAC,MAAM,MAAM,CAAC,cAAc,EAAE,GAAG,EAAE,OAAO;AAEhE;;;AAGG;MACU,yBAAyB,GAAG,wBAAwB,CAAUC,kDAAoB,CAAC,yBAAyB,EAAE;AACzH,IAAA,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,CAAC,GAAG,KAAKC,mCAAkB,CAAC,GAAG,EAAE,oCAAoC,CAAC;AACnF,IAAA,QAAQ,EAAEC,0BAAS;AACpB,CAAA;;;;"}

package/dist/utilities/sessionStorageUtils/index.d.ts

@@ -27,12 +27,15 @@ export interface SessionStorageItemOptions<T> {
     validate?: (value: unknown) => value is T;
 }
 /**
- * Build a typed, failure-safe accessor for a single `sessionStorage` key.
+ * Builds a typed, failure-safe accessor for a single `sessionStorage` key.
  *
- * @example
- * const draft = createSessionStorageItem<Draft>('fd-draft');
- * draft.set({ title: 'Hi' });
- * const value = draft.get(); // Draft | null
+ *   const draft = createSessionStorageItem<Draft>('fd-draft'); draft.set({ title: 'Hi' }); draft.get(); // Draft | null
+ *
+ * @param key The storage key; register it in `SESSION_STORAGE_KEYS` first.
+ * @param options Custom `serialize`/`deserialize` and a `validate` guard; see
+ *   `SessionStorageItemOptions`.
+ * @returns `get`, `set` and `clear` that never throw; `get()` returns `null` when storage is
+ *   unavailable, while `set()` and `clear()` return `void` and ignore failures.
  */
 export declare const createSessionStorageItem: <T>(key: string, options?: SessionStorageItemOptions<T>) => SessionStorageItem<T>;
 /**

package/dist/utilities/sessionStorageUtils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utilities/sessionStorageUtils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAIhC,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,gFAAgF;IAChF,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAChB,wEAAwE;IACxE,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,mDAAmD;IACnD,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EAAE,KAAK,MAAM,EAAE,UAAS,yBAAyB,CAAC,CAAC,CAAM,KAAG,kBAAkB,CAAC,CAAC,CACzD,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,6BAIpC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utilities/sessionStorageUtils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAIhC,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,gFAAgF;IAChF,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAChB,wEAAwE;IACxE,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,mDAAmD;IACnD,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EAAE,KAAK,MAAM,EAAE,UAAS,yBAAyB,CAAC,CAAC,CAAM,KAAG,kBAAkB,CAAC,CAAC,CACzD,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,6BAIpC,CAAC"}

package/dist/utilities/sessionStorageUtils/index.js

@@ -12,12 +12,15 @@ import { SESSION_STORAGE_KEYS } from './sessionStorageUtils.constants.js';
  * — check there for the full list before adding a new one.
  */
 /**
- * Build a typed, failure-safe accessor for a single `sessionStorage` key.
+ * Builds a typed, failure-safe accessor for a single `sessionStorage` key.
  *
- * @example
- * const draft = createSessionStorageItem<Draft>('fd-draft');
- * draft.set({ title: 'Hi' });
- * const value = draft.get(); // Draft | null
+ *   const draft = createSessionStorageItem<Draft>('fd-draft'); draft.set({ title: 'Hi' }); draft.get(); // Draft | null
+ *
+ * @param key The storage key; register it in `SESSION_STORAGE_KEYS` first.
+ * @param options Custom `serialize`/`deserialize` and a `validate` guard; see
+ *   `SessionStorageItemOptions`.
+ * @returns `get`, `set` and `clear` that never throw; `get()` returns `null` when storage is
+ *   unavailable, while `set()` and `clear()` return `void` and ignore failures.
  */
 const createSessionStorageItem = (key, options = {}) => createWebStorageItem(() => window.sessionStorage, key, options);
 /**

package/dist/utilities/sessionStorageUtils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/utilities/sessionStorageUtils/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;;;;;;;;;AASG;AA2BH;;;;;;;AAOG;AACI,MAAM,wBAAwB,GAAG,CAAI,GAAW,EAAE,OAAA,GAAwC,EAAE,KACjG,oBAAoB,CAAC,MAAM,MAAM,CAAC,cAAc,EAAE,GAAG,EAAE,OAAO;AAEhE;;;AAGG;MACU,yBAAyB,GAAG,wBAAwB,CAAU,oBAAoB,CAAC,yBAAyB,EAAE;AACzH,IAAA,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,CAAC,GAAG,KAAK,kBAAkB,CAAC,GAAG,EAAE,oCAAoC,CAAC;AACnF,IAAA,QAAQ,EAAE,SAAS;AACpB,CAAA;;"}
+{"version":3,"file":"index.js","sources":["../../../src/utilities/sessionStorageUtils/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;;;;;;;;;AASG;AA2BH;;;;;;;;;;AAUG;AACI,MAAM,wBAAwB,GAAG,CAAI,GAAW,EAAE,OAAA,GAAwC,EAAE,KACjG,oBAAoB,CAAC,MAAM,MAAM,CAAC,cAAc,EAAE,GAAG,EAAE,OAAO;AAEhE;;;AAGG;MACU,yBAAyB,GAAG,wBAAwB,CAAU,oBAAoB,CAAC,yBAAyB,EAAE;AACzH,IAAA,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,CAAC,GAAG,KAAK,kBAAkB,CAAC,GAAG,EAAE,oCAAoC,CAAC;AACnF,IAAA,QAAQ,EAAE,SAAS;AACpB,CAAA;;"}

package/dist/utilities/testIdUtils/index.cjs

@@ -22,34 +22,68 @@ var React = require('react');
 const TEST_ID_PREFIX = 'fd';
 /** Separator placed between hierarchy levels (within a segment, use single `-`). */
 const TEST_ID_SEPARATOR = '--';
-/** Convert an arbitrary string into a kebab-case, testid-safe segment. */
+/**
+ * Converts an arbitrary string into a kebab-case, testid-safe segment.
+ *
+ * @param value A label or id, in any case or punctuation.
+ * @returns Lower-case text with runs of non-alphanumerics collapsed to single hyphens.
+ */
 const slugifyTestId = (value) => value
     .toLowerCase()
     .trim()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
-/** Build a root-level testid, e.g. `rootTestId('sidebar-navigation')` -> `fd-sidebar-navigation`. */
+/**
+ * Builds a root-level testid, e.g. `rootTestId('sidebar-navigation')` ->
+ * `fd-sidebar-navigation`.
+ *
+ * @param kebabName The component's kebab-case name.
+ * @returns The name prefixed with `fd-`.
+ */
 const rootTestId = (kebabName) => `${TEST_ID_PREFIX}-${kebabName}`;
-/** Append a child segment to a parent testid, e.g. `joinTestId('fd-x', 'nav-item-orders')` -> `fd-x--nav-item-orders`. */
+/**
+ * Appends a child segment to a parent testid, e.g. `joinTestId('fd-x', 'nav-item-orders')` ->
+ * `fd-x--nav-item-orders`.
+ *
+ * @param prefix The ancestor's resolved testid.
+ * @param segment The child's own segment, already slugified.
+ * @returns The two joined with `--`.
+ */
 const joinTestId = (prefix, segment) => `${prefix}${TEST_ID_SEPARATOR}${segment}`;
-/** Return the override when provided, otherwise the fallback (explicit-child case). */
+/**
+ * Returns the override when provided, otherwise the fallback (explicit-child case).
+ *
+ * @param override A consumer-provided `data-testid`, if any.
+ * @param fallback The derived default to use without one.
+ * @returns Whichever applies.
+ */
 const resolveTestId = (override, fallback) => override ?? fallback;
 /**
- * Spread helper for the resolved testid. Returns `{ 'data-testid': value }` when
- * a value is present, otherwise an empty object. Centralising this keeps the
- * emitted attribute name in one place (a React Native sibling can map it to
- * `testID` in a follow-up without touching call sites).
+ * Spread helper for a resolved test id: `{ 'data-testid': value }` when present, else an empty
+ * object. Centralising it keeps the attribute name in one place so a React Native sibling can
+ * map it to `testID`.
+ *
+ * @param testId The resolved id, or `undefined` to emit nothing.
+ * @returns Props to spread onto the rendered element.
  */
 const testIdProps = (testId) => (testId ? { 'data-testid': testId } : {});
 /** Context carrying the current resolved testid, used as the prefix for descendant components. */
 const TestIdContext = React.createContext(undefined);
 /** Provides a resolved testid as the prefix for descendant library components. */
 const TestIdProvider = TestIdContext.Provider;
-/** Read the testid prefix contributed by an ancestor component (`undefined` at the root). */
+/**
+ * Reads the testid prefix contributed by an ancestor component.
+ *
+ * @returns The ancestor's resolved testid, or `undefined` at the root.
+ */
 const useTestIdPrefix = () => React.useContext(TestIdContext);
 /**
- * Resolve a component's testid: an explicit override wins; otherwise derive
+ * Resolves a component's testid: an explicit override wins; otherwise derive
  * `<ancestorPrefix>--<segment>` when nested, or `fd-<rootName>` at the root.
+ *
+ * @param options The consumer `testId` override, the component's `segment`, and its
+ *   `rootName`.
+ * @returns The id to render as `data-testid`.
  */
 const useResolvedTestId = ({ testId, segment, rootName }) => {
     const prefix = useTestIdPrefix();

package/dist/utilities/testIdUtils/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../../../src/utilities/testIdUtils/index.ts"],"sourcesContent":[null],"names":["createContext","useContext"],"mappings":";;;;AAIA;;;;;;;;;;;;;;;AAeG;AAEH;AACO,MAAM,cAAc,GAAG;AAE9B;AACO,MAAM,iBAAiB,GAAG;AAEjC;MACa,aAAa,GAAG,CAAC,KAAa,KACzC;AACG,KAAA,WAAW;AACX,KAAA,IAAI;AACJ,KAAA,OAAO,CAAC,aAAa,EAAE,GAAG;AAC1B,KAAA,OAAO,CAAC,UAAU,EAAE,EAAE;AAE3B;AACO,MAAM,UAAU,GAAG,CAAC,SAAiB,KAAa,CAAA,EAAG,cAAc,CAAA,CAAA,EAAI,SAAS;AAEvF;AACO,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,OAAe,KAAa,GAAG,MAAM,CAAA,EAAG,iBAAiB,CAAA,EAAG,OAAO;AAE9G;AACO,MAAM,aAAa,GAAG,CAAC,QAA4B,EAAE,QAAgB,KAAa,QAAQ,IAAI;AAErG;;;;;AAKG;AACI,MAAM,WAAW,GAAG,CAAC,MAA0B,MAAkC,MAAM,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE;AAE/H;MACa,aAAa,GAAGA,mBAAa,CAAqB,SAAS;AAExE;AACO,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C;AACO,MAAM,eAAe,GAAG,MAA0BC,gBAAU,CAAC,aAAa;AAWjF;;;AAGG;AACI,MAAM,iBAAiB,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAA4B,KAAY;AACnG,IAAA,MAAM,MAAM,GAAG,eAAe,EAAE;IAChC,OAAO,MAAM,KAAK,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;AAChF;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":["../../../src/utilities/testIdUtils/index.ts"],"sourcesContent":[null],"names":["createContext","useContext"],"mappings":";;;;AAIA;;;;;;;;;;;;;;;AAeG;AAEH;AACO,MAAM,cAAc,GAAG;AAE9B;AACO,MAAM,iBAAiB,GAAG;AAEjC;;;;;AAKG;MACU,aAAa,GAAG,CAAC,KAAa,KACzC;AACG,KAAA,WAAW;AACX,KAAA,IAAI;AACJ,KAAA,OAAO,CAAC,aAAa,EAAE,GAAG;AAC1B,KAAA,OAAO,CAAC,UAAU,EAAE,EAAE;AAE3B;;;;;;AAMG;AACI,MAAM,UAAU,GAAG,CAAC,SAAiB,KAAa,CAAA,EAAG,cAAc,CAAA,CAAA,EAAI,SAAS;AAEvF;;;;;;;AAOG;AACI,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,OAAe,KAAa,GAAG,MAAM,CAAA,EAAG,iBAAiB,CAAA,EAAG,OAAO;AAE9G;;;;;;AAMG;AACI,MAAM,aAAa,GAAG,CAAC,QAA4B,EAAE,QAAgB,KAAa,QAAQ,IAAI;AAErG;;;;;;;AAOG;AACI,MAAM,WAAW,GAAG,CAAC,MAA0B,MAAkC,MAAM,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE;AAE/H;MACa,aAAa,GAAGA,mBAAa,CAAqB,SAAS;AAExE;AACO,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C;;;;AAIG;AACI,MAAM,eAAe,GAAG,MAA0BC,gBAAU,CAAC,aAAa;AAWjF;;;;;;;AAOG;AACI,MAAM,iBAAiB,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAA4B,KAAY;AACnG,IAAA,MAAM,MAAM,GAAG,eAAe,EAAE;IAChC,OAAO,MAAM,KAAK,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;AAChF;;;;;;;;;;;;"}