diff --git a/.changeset/dirty-bears-win.md b/.changeset/dirty-bears-win.md new file mode 100644 index 0000000000..fe7f079524 --- /dev/null +++ b/.changeset/dirty-bears-win.md @@ -0,0 +1,34 @@ +--- +"@patternfly/elements": major +--- +``: removed the `getIconUrl` static method, and replaced it with the +`resolve` static method + +The steps for overriding icon loading behaviour have changed. Before, you had to +return a string from the `getIconUrl` method, or the second argument to +`addIconSet`. Now, both of those functions must return a Node, or any lit-html +renderable value, or a Promise thereof. + +BEFORE: + +```js +PfIcon.addIconSet('local', (set, icon) => + new URL(`/assets/icons/${set}-${icon}.js`)); + +// or +PfIcon.getIconUrl = (set, icon) => + new URL(`/assets/icons/${set}-${icon}.js`)) +``` + +AFTER +```js +PfIcon.addIconSet('local', (set, icon) => + import(`/assets/icons/${set}-${icon}.js`)) + .then(mod => mod.default); + +// or +PfIcon.resolve = (set, icon) => + import(`/assets/icons/${set}-${icon}.js`)) + .then(mod => mod.default); +``` + diff --git a/.changeset/fresh-shrimps-work.md b/.changeset/fresh-shrimps-work.md new file mode 100644 index 0000000000..0e550d4716 --- /dev/null +++ b/.changeset/fresh-shrimps-work.md @@ -0,0 +1,4 @@ +--- +"@patternfly/elements": major +--- +``: removed the `defaultIconSet` static field. diff --git a/elements/package.json b/elements/package.json index d2ef0d5d74..516c6b50fa 100644 --- a/elements/package.json +++ b/elements/package.json @@ -130,7 +130,7 @@ ], "dependencies": { "@lit/context": "^1.1.0", - "@patternfly/icons": "^1.0.2", + "@patternfly/icons": "^1.0.3", "@patternfly/pfe-core": "^3.0.0", "lit": "^3.1.2", "tslib": "^2.6.2" diff --git a/elements/pf-icon/README.md b/elements/pf-icon/README.md index 280462273e..f739929014 100644 --- a/elements/pf-icon/README.md +++ b/elements/pf-icon/README.md @@ -49,6 +49,7 @@ Icon comes with three built-in icon sets: 1. `fas`: Font Awesome Free Solid icons (the default set) 1. `far`: Font Awesome Free Regular icons +1. `fab`: Font Awesome Free Bold icons 1. `patternfly`: PatternFly icons Use the `set` attribute to pick an alternative icon set. @@ -61,19 +62,31 @@ Use the `set` attribute to pick an alternative icon set. It is possible to add custom icon sets or override the default sets. Icon sets are defined in detail in [the docs][icon-sets]. -### Bundling +### Bundling and custom loading behaviour -When bundling PfIcon with other modules, the default icon imports will be -relative to the bundle, not the source file, so be sure to either register all -the icon sets you'll need, or override the default getter. +When bundling `` with other modules (e.g. using webpack, rollup, +esbuild, vite, or similar tools), icon imports will be code-split into chunks, +as they are imported from the `@patternfly/icons` package. Ensure that your +bundler is configured to permit dynamic imports, or mark the `@patternfly/icons` +package as "external" and apply an [import map][importmap] to your page instead. +If you would like to +customize the loading behaviour, override the `PfIcon.resolve()` static method. +This methods takes two arguments: the icon set (a string) and the icon name +(a string), and returns a promise of the icon contents, which is a DOM node, or +[anything else that lit-html can render][renderable]. ```js -// Workaround for bundled pf-icon: make icon imports absolute, instead of -relative to the bundle import { PfIcon } from '/pfe.min.js'; -PfIcon.getIconUrl = (set, icon) => - new URL(`/assets/icons/${set}/${icon}.js`, import.meta.url); - // default: new URL(`./icons/${set}/${icon}.js`, import.meta.url); +PfIcon.resolve = async function(set, icon) { + try { + const { default: content } = await import(`/assets/icons/${set}/${icon}.js`); + if (content instanceof Node) { + return content.cloneNode(true); + } + } catch (e) { + return ''; + } +} ``` ## Loading @@ -84,3 +97,5 @@ see the [docs][docs] for more info. [docs]: https://patternflyelements.org/components/icon/ [icon-sets]: https://patternflyelements.org/components/icon/#icon-sets +[renderable]: https://lit.dev/docs/components/rendering/#renderable-values +[importmap]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap diff --git a/elements/pf-icon/demo/custom-icon-sets.html b/elements/pf-icon/demo/custom-icon-sets.html index ef9ba98e14..9e62817bd6 100644 --- a/elements/pf-icon/demo/custom-icon-sets.html +++ b/elements/pf-icon/demo/custom-icon-sets.html @@ -15,8 +15,9 @@

Custom Icon Sets

``` ```js import { PfIcon } from '@patternfly/elements/pf-icon/pf-icon.js'; - PfIcon.addIconSet('rh', (set, icon) => - new URL(`./icons/${set}/${icon}.js`, import.meta.url)); + PfIcon.addIconSet('rh', async (set, icon) => + import(`./icons/${set}/${icon}.js`) + .then(mod => mod.default)); ``` @@ -25,8 +26,9 @@

Custom Icon Sets