@justeattakeaway/pie-icons-webc 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +76 -94
  2. package/package.json +3 -29
package/README.md CHANGED
@@ -3,82 +3,88 @@
3
3
 
4
4
  Shared PIE Icon Components built using [Lit Web Components](https://lit.dev/docs/).
5
5
 
6
- This package provides the PIE iconset as importable Web Components, to ensure icons are used to PIE guidelines for sizing.
6
+ This package provides the PIE icon set as importable web components, to make sure that icons are used in accordance with PIE sizing guidelines.
7
7
 
8
- The base [pie-icons](https://www.npmjs.com/package/@justeattakeaway/pie-icons) package is used to provide the SVGs that are compiled into Lit web components that can be imported into any application.
8
+ This package takes the icon SVGs from the [pie-icons](https://www.npmjs.com/package/@justeattakeaway/pie-icons) package and compiles them into Lit web components which can be imported into any web application.
9
9
 
10
10
  ---
11
11
 
12
12
  [![npm version](https://img.shields.io/npm/v/@justeattakeaway/pie-icons-webc.svg)](https://img.shields.io/npm/v/@justeattakeaway/pie-icons-webc.svg)
13
13
 
14
14
  ---
15
- ## Usage
16
15
 
17
- ### Installation
16
+ ## Installation
18
17
 
19
- Add the module to your project
18
+ To add the module to your project:
20
19
 
21
20
  ```bash
22
21
  yarn add @justeattakeaway/pie-icons-webc
23
22
  ```
24
23
 
25
24
 
26
- ### Usage
25
+ ## Usage
27
26
 
28
- #### Vanilla Javascript
27
+ ### Vanilla JavaScript
29
28
 
30
- 1. Import a specific icon from its entry point (recommended)
31
- ```js
32
- // Importing a specific icon directly from its entry point (recommended for tree-shaking benefits)
33
- import { IconCalendarFilledLarge } from '@justeattakeaway/pie-icons-webc/IconCalendarFilledLarge';
29
+ #### Importing a single icon
34
30
 
35
- function renderIcon() {
36
- // Using the imported icon
37
- const iconElement = new IconCalendarFilledLarge();
38
- document.body.appendChild(iconElement);
39
- }
40
- ```
31
+ The recommended approach for registering a single icon is to import it from its individual entry point.
41
32
 
42
- 2. Import a specific icon from its entry point without a reference (recommended)
43
33
  ```js
44
- // Importing a specific icon without keeping a reference from its entry point
45
- import '@justeattakeaway/pie-icons-webc/IconCalendarFilledLarge';
34
+ // Recommended
35
+ import '@justeattakeaway/pie-icons-webc/dist/IconCalendarFilledLarge.js';
36
+ ```
46
37
 
47
- // Rest of code does not directly reference IconCalendarFilledLarge however the web component has been registered in the browser
38
+ The rest of the code does not directly reference an `IconCalendarFilledLarge` object, but the custom element has still been registered in the browser.
39
+ It can now be used inside your HTML template (as long as your JavaScript file is being loaded!).
48
40
 
49
- // In some HTML:
50
- // <div>
51
- // <icon-calendar-filled-large></icon-calendar-filled-large>
52
- // <div>
41
+ ```html
42
+ <div>
43
+ <icon-calendar-filled-large></icon-calendar-filled-large>
44
+ <div>
53
45
  ```
54
46
 
55
- 3. Importing all icons at once (not recommended)
47
+ Alternatively, you can import the class, which extends `HTMLElement` (via `LitElement`).
48
+
56
49
  ```js
57
- // Importing all icons from the library (not recommended)
58
- import * as icons from '@justeattakeaway/pie-icons-webc';
50
+ // Also recommended, if you need to use the imported object.
51
+ import { IconCalendarFilledLarge } from '@justeattakeaway/pie-icons-webc/dist/IconCalendarFilledLarge.js';
59
52
 
60
53
  function renderIcon() {
61
- // Using a specific icon
62
- const iconElement = new icons.IconCalendarFilledLarge();
54
+ // Using the imported class to create a new element
55
+ const iconElement = new IconCalendarFilledLarge();
63
56
  document.body.appendChild(iconElement);
64
57
  }
65
58
  ```
66
59
 
60
+ #### Importing multiple icons
67
61
 
68
- > [!WARNING]
69
- > While it is also possible to import individual components from the overall bundle, we don't recommend this because
70
- > it is likely that the import will be tree-shaken unless you are referencing the imported object in your code.
62
+ The recommended approach for importing multiple icons is to import them one-by-one to keep your application lightweight and performant.
71
63
 
72
64
  ```js
73
- // Not recommended - Webpack v4+ or Rollup should treeshake but be careful
74
- import { IconAppRestaurant } from '@justeattakeaway/pie-icons-webc';
75
- // Not recommended
76
- import { IconAppRestaurant } from '@justeattakeaway/pie-icons-webc';
65
+ import '@justeattakeaway/pie-icons-webc/dist/IconHeart.js';
66
+ import '@justeattakeaway/pie-icons-webc/dist/IconHeartFilled.js';
77
67
  ```
78
68
 
79
- #### Lit Components
69
+ ```html
70
+ <div>
71
+ <icon-heart></icon-heart>
72
+ <icon-heart-filled></icon-heart-filled>
73
+ </div>
74
+ ```
75
+
76
+ Whilst it *is* possible to import all of the icons at once, this is **not recommended** as it will bloat and slow down your application.
77
+
78
+ Similarly, it is also **not recommended** to import individual icons from the package's main entrypoint, because it is likely that all icons will still be registered as custom elements in the browser.
79
+
80
+ You may also encounter issues with tree-shaking if you import an object but don't use it.
81
+
82
+ ### Lit components
83
+
84
+ Importing and using an icon inside a Lit web component is very straightforward.
85
+
80
86
  ```js
81
- import '@justeattakeaway/pie-icons-webc/IconAppRestaurant';
87
+ import '@justeattakeaway/pie-icons-webc/dist/IconAppRestaurant.js';
82
88
 
83
89
  export class MyAmazingComponent extends LitElement {
84
90
  render () {
@@ -91,78 +97,57 @@ export class MyAmazingComponent extends LitElement {
91
97
  }
92
98
  ```
93
99
 
94
- #### React
100
+ ### React
95
101
 
96
- To import from the package root:
102
+ Each icon has a separate entrypoint for use in React applications. This uses our [`pie-wrapper-react`](https://github.com/justeattakeaway/pie/blob/main/packages/tools/pie-wrapper-react) package.
97
103
 
98
104
  ```tsx
99
- // Please note we include /dist/ in the path only for React exports. This is due to how we have setup React exports to work with frameworks such as NextJS.
100
- import { IconAlertTriangleLarge, IconCalendar } from "@justeattakeaway/pie-icons-webc/dist/react";
101
-
102
- // If your app can support the exports set in the package.json, you can also import like so (exclude 'dist'):
103
- import { IconAlertTriangleLarge, IconCalendar } from "@justeattakeaway/pie-icons-webc/react";
105
+ import { IconAlertTriangleLarge } from "@justeattakeaway/pie-icons-webc/dist/react/IconAlertTriangleLarge.js";
106
+ import { IconCalendar } from "@justeattakeaway/pie-icons-webc/dist/react/IconCalendar.js";
104
107
 
105
108
  export default function App() {
106
109
  return (
107
110
  <div className="App">
108
- <IconCalendar />
109
111
  <IconAlertTriangleLarge fill={PIE_ALIAS_COLOR_TOKEN} />
110
- </div>
111
- );
112
- }
113
- ```
114
- To import a single icon:
115
-
116
- ```tsx
117
- // Please note we include /dist/ in the path only for React exports. This is due to how we have setup React exports to work with frameworks such as NextJS
118
- import { IconCalendar } from "@justeattakeaway/pie-icons-webc/dist/react/IconCalendar";
119
-
120
- // If your app can support the exports set in the package.json, you can also import like so (exclude 'dist'):
121
- import { IconCalendar } from "@justeattakeaway/pie-icons-webc/react/IconCalendar";
122
-
123
- export default function App() {
124
- return (
125
- <div className="App">
126
112
  <IconCalendar />
127
113
  </div>
128
114
  );
129
115
  }
130
116
  ```
131
117
 
132
- #### Vue
118
+ ### Vue
133
119
 
134
- This package requires Node 18+, therefore, if you are using a lower version of Node please use our native Vue component package – [pie-icons-vue](https://www.npmjs.com/package/@justeattakeaway/pie-icons-vue).
120
+ Note that you don't need to register the icons as Vue components, because they aren't!
135
121
 
136
- To import from the package root:
137
-
138
- ```tsx
139
- import { IconAlertTriangleLarge, IconCalendar } from "@justeattakeaway/pie-icons-webc";
122
+ ```vue
123
+ <template>
124
+ <div>
125
+ <icon-alert-triangle-large></icon-alert-triangle-large>
126
+ <icon-calendar></icon-calendar>
127
+ </div>
128
+ </template>
140
129
 
141
- export default function App() {
142
- return (
143
- <div className="App">
144
- <icon-calendar></icon-calendar>
145
- <icon-alert-triangle-large></icon-alert-triangle-large>
146
- </div>
147
- );
148
- }
130
+ <script>
131
+ import '@justeattakeaway/pie-icons-webc/dist/IconAlertTriangleLarge.js';
132
+ import '@justeattakeaway/pie-icons-webc/dist/IconCalendar.js';
133
+ </script>
149
134
  ```
150
135
 
151
136
 
152
- ### Props
137
+ ## Props
153
138
 
154
139
  Icons accept any standard attribute, except for `width` and `height` since those are set implicitly by using the `size` prop.
155
140
 
156
141
 
157
- ##### `size`
142
+ ### `size`
158
143
 
159
144
  Icons are made available in different size variants:
160
145
  - regular
161
146
  - large, when its name has the `Large` suffix
162
147
 
163
- Regular icons default size is `xs` and can use one of the following pre-determined values for `size`: `xs`, `s`, `m`, `l`, `xl`, and `xxl`. You can learn more about regular icon sizes [here](https://www.pie.design/foundations/iconography/overview/#:~:text=Sizes%20for%20the%20Small%20icon%20set).
148
+ A regular icon's default size is `xs` and can use one of the following pre-defined values for `size`: `xs`, `s`, `m`, `l`, `xl`, and `xxl`. You can learn more about regular icon sizes [here](https://www.pie.design/foundations/iconography/overview/#:~:text=Sizes%20for%20the%20Small%20icon%20set).
164
149
 
165
- Large icons `size` default and minimum value is `32`. Values larger than the minimum must be multiples of `8`, otherwise will be automatically rounded. You can learn more about large icon sizes [here](https://www.pie.design/foundations/iconography/overview/#:~:text=Sizes%20for%20the%20Large%20icon%20set).
150
+ A large icon's default (and minimum) `size` is `32`. Values larger than the minimum **must** be multiples of `8`, otherwise the default size will be used. You can learn more about large icon sizes [here](https://www.pie.design/foundations/iconography/overview/#:~:text=Sizes%20for%20the%20Large%20icon%20set).
166
151
 
167
152
  Example:
168
153
 
@@ -171,32 +156,29 @@ Example:
171
156
  <icon-alert-triangle-large size="80"></icon-alert-triangle-large>
172
157
  ```
173
158
 
174
- ### Tree shaking
175
-
176
- By using ES imports like `import { IconCalendar } from '@justeattakeaway/pie-icons-webc'` with Webpack v4+ or Rollup, unused exports in this module will be automatically eliminated.
177
-
178
- If you can't use a tree-shaking compatible build tool, then you can use the per-file icons from the [`/icons`](https://unpkg.com/@justeattakeaway/pie-icons-vue/) directory, e.g. `import IconCalendar from '@justeattakeaway/pie-icons-webc/IconCalendar'`.
179
159
 
180
-
181
- ### Browser Support
160
+ ## Browser support
182
161
 
183
162
  The component extends [@justeattakeaway/browserslist-config-pie](https://github.com/justeattakeaway/pie/tree/main/packages/tools/browserslist-config-pie) package for the list of browsers to support.
184
163
 
185
164
 
186
165
  ## Contributing
187
166
 
188
- Before starting please read our [contributing guide](https://pie.design/engineers/contributing/)
167
+ Before starting, please read our [contributing guide](https://pie.design/engineers/contributing/).
189
168
 
190
169
  ### Adding new icons
191
170
 
192
171
  Icons should be added as SVGs to the main pie-icons package and published, before simply incrementing the dependency of `pie-icons` in the `pie-icons-webc` package, to generate the new set of Web Components.
193
172
 
194
- The PIE iconset is managed by our PIE design team and new icon requests should go through them to ensure that they are designed in-line with our standards and guildelines. Please reach out to PIE design system team using #help-designsystem slack channel.
173
+ The PIE icon set is managed by our PIE Design System team. New icon requests should go through them to ensure that they meet our standards and follow our guidelines. Please reach out on the (internal) `#help-designsystem` Slack channel.
174
+
175
+ ### Building the module
195
176
 
196
- ### Building the Module
177
+ Run `yarn build --filter=pie-icons-webc` from the root of the monorepo.
197
178
 
198
- Run `yarn build --filter=pie-icons-webc` from the project level or `yarn turbo run build --filter=pie-icons-webc` from the root level to compile the module.
179
+ ## Icon library
199
180
 
200
- ## Icon list
181
+ You can view the full icon library on our [documentation site](https://pie.design/foundations/iconography/library/).
201
182
 
202
- You can check the list of all the icons on our [documentation site](https://pie.design/foundations/iconography/library/).
183
+ ## Bundling
184
+ When we build the icons, we run a plugin for Rollup named `rollup-plugin-visualizer`. This generates a file named `stats.html` in the root of the package. This file can be viewed in the browser to visualise the bundled Javascript and better understand what contributes to the size of the final build output.
package/package.json CHANGED
@@ -1,38 +1,12 @@
1
1
  {
2
2
  "name": "@justeattakeaway/pie-icons-webc",
3
- "version": "0.20.0",
3
+ "version": "0.22.0",
4
4
  "type": "module",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.js",
7
7
  "files": [
8
8
  "dist"
9
9
  ],
10
- "exports": {
11
- ".": {
12
- "import": "./dist/index.js",
13
- "types": "./dist/index.d.ts"
14
- },
15
- "./*": {
16
- "import": "./dist/*.js",
17
- "types": "./dist/*.d.ts"
18
- },
19
- "./react": {
20
- "import": "./dist/react/index.js",
21
- "types": "./dist/react/index.d.ts"
22
- },
23
- "./react/*": {
24
- "import": "./dist/react/*.js",
25
- "types": "./dist/react/*.d.ts"
26
- },
27
- "./dist/react": {
28
- "import": "./dist/react/index.js",
29
- "types": "./dist/react/index.d.ts"
30
- },
31
- "./dist/react/*": {
32
- "import": "./dist/react/*.js",
33
- "types": "./dist/react/*.d.ts"
34
- }
35
- },
36
10
  "publishConfig": {
37
11
  "access": "public"
38
12
  },
@@ -74,12 +48,12 @@
74
48
  "extends @justeattakeaway/browserslist-config-pie"
75
49
  ],
76
50
  "dependencies": {
77
- "@justeattakeaway/pie-webc-core": "0.20.0"
51
+ "@justeattakeaway/pie-webc-core": "0.21.1"
78
52
  },
79
53
  "devDependencies": {
80
54
  "@babel/core": "7.23.9",
81
55
  "@babel/node": "7.20.7",
82
- "@justeattakeaway/pie-components-config": "0.14.0",
56
+ "@justeattakeaway/pie-components-config": "0.16.0",
83
57
  "@justeattakeaway/pie-icons": "4.14.0",
84
58
  "@justeattakeaway/pie-icons-configs": "4.5.1",
85
59
  "@rollup/plugin-typescript": "11.1.6",