Skip to content

Commit

Permalink
feat(components): remove arc icon in favour of genorated phosphor ico…
Browse files Browse the repository at this point in the history 
…ns (#208)

* deps(components): install @phosphor-icons/core

This installs the @phosphor-icons/core package and adds it to the components package.json file.

* feat(components): remove arc icon in favour of genorated phosphor icons

Add script to generate icons from phosphor icons and remove arc icons.
This is run as part of the build process of the components package.

Refactors all components that use an arc icon to use the new phosphor
based arc icons.

* docs(workspace): update docs to reflect new icon useage

* docs(components): add color story to arc icon component stories

* feat(react): migrate react wrapper component to new arc icon compoennts

* feat(compoents): remove old icon assets

* feat(components): export arc icons

* chore(components): fix build pipeline and format ph icons

* chore(scriptS): rename script to ph-icon-assemble

This renames the script to ph-icon-assemble to better reflect its scope.

* chore(components): prefix all phosphor icons with ph

* fix(playgrounds/react): fix icons

* chore(playgrounds): update playgrounds

* fix(playground): fix playground build

* chore(docs): add icons docs

* docs(workspace): update contributing guide for icons

* docs(workspcae): update tabel of contents

* fix(playgrounds): remove unused import
  • Loading branch information
@dominicegginton
dominicegginton authored Dec 12, 2023
1 parent ccbed49 commit 459bf3d
Show file tree
Hide file tree
Showing 3,800 changed files with 157,566 additions and 2,337 deletions.
The diff you're trying to view is too large. We only load the first 3000 changed files.
43 changes: 1 addition & 42 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,48 +198,7 @@ C4Deployment

### Icons

**ARC** uses [Nucleo](https://nucleoapp.com/) to keep track of the available icons and make an easy export of them.
All the icons are exported as a single SVG `symbol` file, using the following preferences:

If you need to add new icons to the existing library, take the following steps:

1. Import the current icons.svg file into your [Nucleo](https://nucleoapp.com/) app.
2. Drag and drop an svg file into the existing set.
3. Select all icons.
4. Press the `Export` button.
5. Select the SVG <symbol> format.
6. Make sure that the export preferences are as follows:
1. Base class: ''
2. Icon ID Prefix: 'arc-'
3. Use external reference for `use` element: false
4. Remove stroke-width values: true
5. Remove `title`: true
6. Use BEM naming convention: false
7. Use CSS custom properties: true
7. If everything is correct, press the `Export Icons` button.

Most SVG icons that are exported contain a `fill` or a `stroke` color like `#1C1C1C` or `#fff`.
The `arc-icon` component inherits the color(s) from its parent to style the SVG,
so you can set the color property on the `arc-icon` element or an ancestor to change the color.
In order to make the icons work in any theme, the `fill` and/or `stroke` attributes of the exported icons.svg needs to be replaced with the `currentColor` value.

```html
<symbol id="arc-action-undo" viewBox="0 0 31 28">
<g fill="none" class="nc-icon-wrapper" stroke="none">
<g clip-path="url(#clip0_5238_4149)">
<path d="M29.97 27.438h-.03a.76.76 0 0 1-.59-.25c-.151-.167-.237-.386-.257-.657a7.418 7.418 0 0 0-.197-1.14c-.111-.47-.464-1.224-1.06-2.266a10.522 10.522 0 0 0-2.316-2.781c-.948-.813-2.386-1.542-4.314-2.188-1.927-.645-4.162-.968-6.705-.968v5.75a.821.821 0 0 1-.045.28c-.03.084-.066.168-.106.25a.694.694 0 0 1-.167.22c-.07.062-.146.114-.227.156-.383.187-.726.146-1.03-.125L.364 12.969a1.023 1.023 0 0 1 0-1.563L12.927.781c.303-.27.64-.317 1.014-.14.373.177.56.484.56.922v5.593c.807.042 1.584.11 2.331.203.747.094 1.473.22 2.18.375a17.11 17.11 0 0 1 2.028.579c.646.229 1.261.494 1.847.796.585.302 1.14.63 1.665.985.524.354 1.019.745 1.483 1.172.464.427.898.88 1.302 1.359a13.739 13.739 0 0 1 2.134 3.578c.555 1.344.934 2.558 1.135 3.64a22.44 22.44 0 0 1 .364 3.313c.04 1.125.045 1.917.015 2.375-.03.459-.066.813-.106 1.063-.04.25-.141.453-.303.61a.836.836 0 0 1-.605.233zm-16.438-12.25c1.574 0 3.028.083 4.36.25 1.332.166 2.502.411 3.511.734 1.01.323 1.913.677 2.71 1.062.797.386 1.508.834 2.134 1.344.626.51 1.15.995 1.574 1.453a13.2 13.2 0 0 1 1.211 1.532c-.383-3.021-1.443-5.563-3.178-7.625-2.644-3.188-6.752-4.782-12.322-4.782a.917.917 0 0 1-.68-.297.976.976 0 0 1-.289-.703v-4.5l-10.08 8.531 10.08 8.626v-4.625c0-.271.091-.51.273-.72a.81.81 0 0 1 .212-.155c.08-.042.161-.073.242-.094a.968.968 0 0 1 .242-.031z" fill="currentColor" />
</g>
<defs>
<clipPath id="clip0_5238_4149">
<path fill="currentColor" d="M0 0h31v28H0z" />
</clipPath>
</defs>
</g>
</symbol>
```

In the code example above, the `fill` attribute is provided with the `currentColor` value,
this ensures that the SVG is no longer responsible for the colours.
**ARC** uses [Phosphor Icons](https://phosphoricons.com/) as for its icon set. When updating the `@phosphor-icons/core` dependency ensure to run the `npx nx run components:ph-icons-assemble` target that updates the the genorated web components.

### Release

Expand Down
39 changes: 31 additions & 8 deletions MIGRATION_GUIDES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,56 @@

## v2 to v3

#### `ArcButton` color property
In version 3 we have taken the opportunity to make serval important breaking changes to the library. Please take care to read the following migration guide before upgrading.

The `ArcButton` components' default color property has been updated from `primary` to `default`. This change has been made to facilitate a fix for setting the `--btn-background` CSS variable when the color property was not set to an empty string, see (#174)[https://github.com/arup-group/arc-components/pull/174]. Update any `ArcButton` components with no color property set to `primary` if you wish to maintain the same appearance.
#### Breaking Changes

- `ArcIcon` has been replaced with genorated components.
- `ArcButton` color property has been updated from `primary` to `default`.
- Cerry-picking components from the `@arc-web/components` package has changed from importing from the `/dist/src` directory to importing from the `/src` directory.
- React component wrappers have been moved from the `@arc-web/components` package to the `@arc-web/react` package.

#### Upgrade Steps

1. Replace all instances of `ArcIcon` with the new genorated components.

```diff
- import '@arc-web/components/src/components/icon/arc-icon';
- <arc-icon name="home"></arc-icon>

+ import '@arc-web/components/src/components/icon/house/arc-icon-house';
+ <arc-icon-house></arc-icon-house>

```

2. Update all `ArcButton` components with no color property set to `primary` if you wish to maintain the same appearance.

```diff
- <arc-button>Click Me</arc-button>
+ <arc-button color="primary">Click Me</arc-button>
```

#### Cherry-picking components

Cherry-picking components from the `@arc-web/components` package has changed from importing from the `/dist` directory to importing from the `/src` directory:
3. Update all cherry-picked components from the `@arc-web/components` package to import from the `/src` directory.

```diff
- import '@arc-web/components/dist/src/components/button/arc-button';
+ import '@arc-web/components/src/components/button/arc-button';
```

#### React component wrappers
<details>
<summary>React Only</summary>

React component wrappers have been moved from the `@arc-web/components` package to the `@arc-web/react` package. Ensure you install this package and update any imports from the `@arc-web/components` package to the `@arc-web/react` package:
4. Install the new `@arc-web/react` package.

```sh
npm install @arc-web/components @arc-web/react@latest
npm i @arc-web/components@latest @arc-web/react@latest
```

5. Update all imports from the `@arc-web/components` package to the `@arc-web/react` package.

```diff
- import { ArcButton } from '@arc-web/components/react';
+ import { ArcButton } from '@arc-web/react';
```

</details>
101 changes: 20 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,13 @@ With **ARC**, you can:
- [Getting Started](#getting-started): Install and setup **ARC**
- [1: Installation](#1-installation): Install the latest version of **ARC**
- [2: Setup Stylesheets](#2-setup-stylesheets): Setup **ARC** stylesheets
- [3: Setup Static Assets](#3-setup-static-assets): Setup **ARC** static assets
- [4: Import and Use Components](#4-import-and-use-components): Import and use **ARC** components
- [3: Import and Use Components](#4-import-and-use-components): Import and use **ARC** components
- [Migration Guides](https://github.com/arup-group/arc-components/blob/main/MIGRATION_GUIDES.md): Migrate to the latest version of **ARC**
- [v2 to v3](https://github.com/arup-group/arc-components/blob/main/MIGRATION_GUIDES.md#v2-to-v3): Migrate from **ARC** v2 to v3
- [Typescript](#typescript): Use **ARC** components in a Typescript project
- [React](#react): Use **ARC** components in a React project
- [Customization](#customization): Customize **ARC** components
- [Icons](#icons): Icon components
- [Forms](#forms): Form control validation and serialization
- [Flash of unstyled content (FOUC)](#flash-of-unstyled-content-fouc): Prevent FOUC
- [Playgrounds](#playgrounds): Prebuild playground examples
Expand Down Expand Up @@ -124,85 +124,7 @@ Bunderlers that support CSS imports allow you to import CSS files directly into

</details>

#### 3: Setup Static Assets

Some **ARC** components depend upon static assets being available to load at runtime, such as the SVG icons file required for the `ArcIcon` component. Ensure that the `@arc-web/components/assets` directory contents are available to be loaded by your application.

<details>
<summary>Build Script</summary>

Add a step to your build script that copies the contents of the `@arc-web/components/assets` directory into a directory that serves assets for by your applications web server:

```diff
+ cp -r node_modules/@arc-web/components/assets <public directory>
```

</details>

<details>
<summary>Angular CLI</summary>

Add the `@arc-web/components/assets` directory to the `assets` array in your `angular.json` file:

```diff
{
...
"assets": [
...
+ {
+ "glob": "**/*",
+ "input": "node_modules/@arc-web/components/assets",
+ "output": "assets"
+ }
],
...
}
```

</details>

<details>
<summary>Vite</summary>

Install the `vite-plugin-static-copy` package from npm:

```sh
npm install --save-dev vite-plugin-static-copy
```

Use `vite-plugin-static-copy` to copy the contents of the `@arc-web/components/assets` directory:

```diff
+ import { viteStaticCopy } from 'vite-plugin-static-copy';

export default {
...
plugins: [
...
+ viteStaticCopy({
+ targets: [
+ {
+ src: 'node_modules/@arc-web/components/assets',
+ dest: '',
+ }
+ ]
+ }),
],
...
}
```

</details>

**ARC** components load the `@arc-web/components` assets using a base path of `/assets`. If required its possible to change this using the `setBasePath` utility function exported by `@arc-web/components`:

```ts
import { setBasePath } from '@arc-web/components';

setBasePath('/assets');
```

#### 4: Import and Use Components
#### 3: Import and Use Components

Import the `@arc-web/components` package:

Expand All @@ -227,6 +149,11 @@ import `@arc-web/components/src/components/button/arc-button`;
</details>
See the [Storybook](https://arc.arup.com) for a full list of available components and their documentation.
> [!IMPORTANT]
> Icons are not imported by default and must be cherry picked.
### Typescript
**ARC** components are written in Typescript and come with their own type definitions. This means you can use them in a Typescript project without any additional setup. Import an **ARC** component and its type definition:
Expand Down Expand Up @@ -318,6 +245,18 @@ Alternatively, you can set them inline directly on the component.

Not all components expose CSS custom properties. For those that do, they can be found in the component's API documentation. In the properties table, these can be found under the `CSS CUSTOM PROPERTIES` row.

### Icons

ARC used the [Phosphor Icons](https://phosphoricons.com/) icon set and provides a web component for each icon. To use an icon, import the icon component and use it in your application as you would any other component cherry picked as follows:

```js
import '@arc-web/components/src/components/ph-{icon-name}/ph-icon-{icon-name}.js';
```

```html
<ph-icon-{icon-name}></ph-icon-{icon-name}>
```

### Forms

Every **ARC** component makes use of a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate markup, styles and behaviour. One caveat of this approach is that native `form` elements do not recognize form controls located inside a shadow root.
Expand Down
Loading

0 comments on commit 459bf3d

Please sign in to comment.