chore(icons): add deprecation notice and warning (#5009)

* chore(icons): add deprecation notice and warning * chore(icons): add test for deprecated usage * chore(icons): update deprecated notice doc Co-authored-by: Rúben Carvalho <[email protected]> --------- Co-authored-by: Rúben Carvalho <[email protected]>
adobe · Jan 14, 2025 · ce841fe · ce841fe
1 parent fcfab2d
commit ce841fe
Show file tree

Hide file tree

Showing 6 changed files with 102 additions and 16 deletions.
diff --git a/packages/icons/README.md b/packages/icons/README.md
@@ -23,3 +23,11 @@ When looking to leverage the `IconsMedium` or `IconsLarge` base classes as a typ
 ```
 import { IconsMedium, IconsLarge } from '@spectrum-web-components/icons';
 ```
+
+### Deprecated
+
+The `Icons` package has been deprecated as part of the removal of the `Iconset` package from the library and will be removed in an upcoming release. To optimize your build and ensure smaller bundles and higher performance for your users, consider using techniques that include only the icons actually used in your application. For Spectrum icons, you can use [UI Icons](../icons-ui/) or [Workflow Icons](../icons-workflow/).
+
+For non-Spectrum icons, you can still:
+1. Slot SVG or image content into an [`sp-icon` element](../icon/), or
+2. Sanitize the SVG and convert it to a template literal to use within the `render()` method of an extension of `IconBase` to create your own custom named icon element.```
diff --git a/packages/icons/package.json b/packages/icons/package.json
@@ -77,6 +77,7 @@
     },
     "types": "./src/index.d.ts",
     "customElements": "custom-elements.json",
+    "deprecationNotice": "@spectrum-web-components/icons is deprecated and will be removed in an upcoming release.",
     "sideEffects": [
         "./sp-*.js",
         "./**/*.dev.js"

diff --git a/packages/icons/src/IconsLarge.ts b/packages/icons/src/IconsLarge.ts
@@ -25,6 +25,18 @@ export class IconsLarge extends IconsetSVG {
         this.name = 'ui'; // default iconset name for these icons
     }
 
+    protected override firstUpdated(): void {
+        super.firstUpdated();
+        if (window.__swc.DEBUG) {
+            window.__swc.warn(
+                this,
+                'Icons package has been deprecated and will be removed from the project in an upcoming release. For default Spectrum Icons, learn more about leveraging UI Icons (https://opensource.adobe.com/spectrum-web-components/components/icons-ui/) or Workflow Icons (https://opensource.adobe.com/spectrum-web-components/components/icons-workflow/) as an alternative.',
+                'https://opensource.adobe.com/spectrum-web-components/components/icons/#deprecated',
+                { level: 'deprecation' }
+            );
+        }
+    }
+
     protected override renderDefaultContent(): TemplateResult {
         return iconsSVG;
     }

diff --git a/packages/icons/src/IconsMedium.ts b/packages/icons/src/IconsMedium.ts
@@ -25,6 +25,18 @@ export class IconsMedium extends IconsetSVG {
         this.name = 'ui'; // default iconset name for these icons
     }
 
+    protected override firstUpdated(): void {
+        super.firstUpdated();
+        if (window.__swc.DEBUG) {
+            window.__swc.warn(
+                this,
+                'Icons package has been deprecated and will be removed from the project in an upcoming release. For default Spectrum Icons, learn more about leveraging UI Icons (https://opensource.adobe.com/spectrum-web-components/components/icons-ui/) or Workflow Icons (https://opensource.adobe.com/spectrum-web-components/components/icons-workflow/) as an alternative.',
+                'https://opensource.adobe.com/spectrum-web-components/components/icons/#deprecated',
+                { level: 'deprecation' }
+            );
+        }
+    }
+
     protected override renderDefaultContent(): TemplateResult {
         return iconsSVG;
     }

diff --git a/packages/icons/test/icons.test.ts b/packages/icons/test/icons.test.ts
@@ -13,42 +13,95 @@ import '@spectrum-web-components/icons/sp-icons-medium.js';
 import { IconsLarge, IconsMedium } from '../';
 import IconsetSVG from '../src/icons-large.svg.js';
 import { elementUpdated, expect, fixture, html } from '@open-wc/testing';
+import { stub } from 'sinon';
 
 describe('icons', () => {
     it('large', async () => {
-        const el = await fixture<IconsLarge>(
-            html`
-                <sp-icons-large></sp-icons-large>
-            `
-        );
+        const el = await fixture<IconsLarge>(html`
+            <sp-icons-large></sp-icons-large>
+        `);
 
         await elementUpdated(el);
 
         expect(el).to.not.equal(undefined);
         expect(el.getIconList().length).to.be.above(0);
     });
     it('medium', async () => {
-        const el = await fixture<IconsMedium>(
-            html`
-                <sp-icons-medium></sp-icons-medium>
-            `
-        );
+        const el = await fixture<IconsMedium>(html`
+            <sp-icons-medium></sp-icons-medium>
+        `);
 
         await elementUpdated(el);
 
         expect(el).to.not.equal(undefined);
         expect(el.getIconList().length).to.be.above(0);
     });
     it('listens to slotchange events', async () => {
-        const el = await fixture<IconsMedium>(
-            html`
-                <sp-icons-medium>${IconsetSVG}</sp-icons-medium>
-            `
-        );
+        const el = await fixture<IconsMedium>(html`
+            <sp-icons-medium>${IconsetSVG}</sp-icons-medium>
+        `);
 
         await elementUpdated(el);
 
         expect(el).to.not.equal(undefined);
         expect(el.getIconList().length).to.equal(48);
     });
 });
+
+describe('dev mode', () => {
+    let consoleWarnStub!: ReturnType<typeof stub>;
+    before(() => {
+        window.__swc.verbose = true;
+        consoleWarnStub = stub(console, 'warn');
+    });
+    afterEach(() => {
+        consoleWarnStub.resetHistory();
+    });
+    after(() => {
+        window.__swc.verbose = false;
+        consoleWarnStub.restore();
+    });
+
+    it('warns in devMode for deprecated usage - medium', async () => {
+        const el = await fixture<IconsMedium>(html`
+            <sp-icons-medium>${IconsetSVG}</sp-icons-medium>
+        `);
+
+        await elementUpdated(el);
+        expect(consoleWarnStub.called).to.be.true;
+
+        const spyCall = consoleWarnStub.getCall(0);
+        expect(
+            (spyCall.args.at(0) as string).includes('deprecated'),
+            'confirm deprecated variant warning'
+        ).to.be.true;
+        expect(spyCall.args.at(-1), 'confirm `data` shape').to.deep.equal({
+            data: {
+                localName: 'sp-icons-medium',
+                type: 'api',
+                level: 'deprecation',
+            },
+        });
+    });
+    it('warns in devMode for deprecated usage - large', async () => {
+        const el = await fixture<IconsLarge>(html`
+            <sp-icons-large>${IconsetSVG}</sp-icons-large>
+        `);
+
+        await elementUpdated(el);
+        expect(consoleWarnStub.called).to.be.true;
+
+        const spyCall = consoleWarnStub.getCall(0);
+        expect(
+            (spyCall.args.at(0) as string).includes('deprecated'),
+            'confirm deprecated variant warning'
+        ).to.be.true;
+        expect(spyCall.args.at(-1), 'confirm `data` shape').to.deep.equal({
+            data: {
+                localName: 'sp-icons-large',
+                type: 'api',
+                level: 'deprecation',
+            },
+        });
+    });
+});
diff --git a/packages/iconset/package.json b/packages/iconset/package.json
@@ -64,7 +64,7 @@
     },
     "types": "./src/index.d.ts",
     "customElements": "custom-elements.json",
-    "deprecationNotice": "@spectrum-web-components/iconset is deprecated and will be removed in the SWC 1.0 release.",
+    "deprecationNotice": "@spectrum-web-components/iconset is deprecated and will be removed in an upcoming release.",
     "sideEffects": [
         "./src/index.js",
         "./stories/icons-demo.js",