@unimelb/pattern-lib-vue 16.0.0 → 16.1.0-dev
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.
- package/.out/vue.js +1 -1
- package/README.md +8 -263
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -9,10 +9,6 @@ The contents of this repository have been produced by The University of Melbourn
|
|
|
9
9
|
- [Development Preview](https://dev--pattern-lib-unimelb.netlify.app/) (Netlify deploy from `dev` branch)
|
|
10
10
|
- [Production](https://pattern-lib-unimelb.netlify.app/) (Netlify deploy from `master` branch)
|
|
11
11
|
|
|
12
|
-
## External usage
|
|
13
|
-
|
|
14
|
-
- [How to use the library](docs/how-to-use.md) - how this library externally
|
|
15
|
-
|
|
16
12
|
## Getting started
|
|
17
13
|
|
|
18
14
|
The design system requires:
|
|
@@ -33,276 +29,25 @@ cp .env.example .env
|
|
|
33
29
|
# 4. Copy the git pre-push hook
|
|
34
30
|
cp pre-push.sh .git/hooks/pre-push
|
|
35
31
|
|
|
36
|
-
#
|
|
32
|
+
# 5. Install dependencies. Make sure yarn is installed: https://yarnpkg.com/lang/en/docs/install
|
|
37
33
|
yarn
|
|
38
34
|
|
|
39
|
-
#
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
## Development
|
|
43
|
-
|
|
44
|
-
- [Contributing Guidelines](CONTRIBUTING.md)
|
|
45
|
-
|
|
46
|
-
Storybook is the main development environment.
|
|
47
|
-
|
|
48
|
-
- `yarn dev` - [http://localhost:7002/](http://localhost:7002/)
|
|
49
|
-
- `yarn build` to build the documentation site to `/.out/docs`. Environment variable `LOAD_EXTERNAL_ASSETS` controls whether the documentation site is to load the library assets locally (`false`) or from the CDN (`true`).
|
|
50
|
-
|
|
51
|
-
### Generator
|
|
52
|
-
|
|
53
|
-
This project includes generators to speed up common development tasks. Commands include:
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
# Generate a new component
|
|
57
|
-
yarn generate component
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
You will then be asked for the name of the component, this will be used to create a new folder with a minimal component layout and story
|
|
61
|
-
|
|
62
|
-
> **Note**: Always remember to add the new component to the file `index.js` inside of the folders `target/lib` and `target/vue`, that way the component will be exportable to `Matrix CMS` via `CDN` and `Vue` via `NPM`.
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
# Generate a new view component
|
|
66
|
-
yarn generate story
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
You will need to select the component from the list of folders, then confirm the selection by selecting `choose this directory`. You will then be asked to give the story a name.
|
|
70
|
-
|
|
71
|
-
> **Note**: This requires some special comments are added in the `stories/index.js` file. If it doesn't work make sure the comments are the same as in the template directory.
|
|
72
|
-
|
|
73
|
-
### Using a component in CMS
|
|
74
|
-
|
|
75
|
-
In Storybook: When adding the "how to use a component" documentation, add a description that clearly shows that ( in the CMS environment) a component must be used in the way of closing the tag explicitly, as shown in the following example:
|
|
76
|
-
|
|
77
|
-
## Do not:
|
|
78
|
-
|
|
79
|
-
(In the CMS, self closing tags won't load the component:)
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
# self close the components
|
|
83
|
-
<my-new-component/>
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
## Do
|
|
87
|
-
|
|
88
|
-
(To be compatible with CMS, call the component this way:)
|
|
89
|
-
|
|
90
|
-
```bash
|
|
91
|
-
# explicitly closing
|
|
92
|
-
<my-new-component></my-new-component>
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
> **Note**: Matrix CMS can only use the components in that way and must be in the `target/lib` folder as well. You can self-close a component when importing it in a parent component in the pattern-lib context. The rule described above applies just when the component is called in the CMS context. ie. footer component, which is used like this in CMS: `<page-footer-alt></page-footer-alt>` instead of `<page-footer-alt />`.
|
|
96
|
-
|
|
97
|
-
### Targets
|
|
98
|
-
|
|
99
|
-
#### UI library - `targets/lib`
|
|
100
|
-
|
|
101
|
-
The main UI library for use in the CMS. The target provides a local development environment for testing purposes.
|
|
102
|
-
|
|
103
|
-
- `yarn start:lib` - [http://localhost:7003/](http://localhost:7003/).
|
|
104
|
-
- `yarn build:lib` to compile the library to `.out/lib/<version>`, including `ui.css`, `ui.js`, `sprite.svg`, and SVG assets in `components/shared`. You can then use `http-server` or another static file server to serve the output directory.
|
|
105
|
-
|
|
106
|
-
The following environment variables are available to configure the behaviour of `yarn build:lib`:
|
|
107
|
-
|
|
108
|
-
- `LOAD_EXTERNAL_ASSETS` controls whether the library is to load its assets locally (`false`) or from the CDN (`true`).
|
|
109
|
-
- `LIB_EMIT_HTML` controls whether to emit the demo HTML file - set it to `true` to emit the file.
|
|
110
|
-
- `LIB_LOAD_VERSION` controls which version of the library to load in the demo:
|
|
111
|
-
- leave it blank to load the local bundles (e.g. to test a new feature),
|
|
112
|
-
- set it to `auto` to load the latest version from the CDN (i.e. the version specified in `package.json`),
|
|
113
|
-
- set it to a specific version number to load that version from the CDN - e.g. `0.0.12` (no `v` prefix).
|
|
114
|
-
|
|
115
|
-
#### Vue library - `targets/vue`
|
|
116
|
-
|
|
117
|
-
The library with all the Vue components for use in single-page apps and other Vue-based projects.
|
|
118
|
-
|
|
119
|
-
- `yarn build:vue` to compile the library to `.out/vue.js`.
|
|
120
|
-
|
|
121
|
-
### Linting
|
|
122
|
-
|
|
123
|
-
CSS files are linted on the fly with stylelint. The configuration file, `.stylelintrc`, extends two shared configuration: [`stylelint-config-standard`](https://github.com/stylelint/stylelint-config-standard) and [`stylelint-config-property-sort-order-smacss`](https://github.com/cahamilton/css-property-sort-order-smacss/blob/master/index.js).
|
|
124
|
-
|
|
125
|
-
JS files and single-file Vue components are linted on the fly with ESLint. The configuration file, `.eslintrc`, extends two shared configurations: [`eslint-config-airbnb`](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb) and [`plugin:vue/recommended`](https://github.com/vuejs/eslint-plugin-vue)
|
|
126
|
-
|
|
127
|
-
For your own sanity, make sure to install your code editor's ESLint and stylelint extensions. The following commands are available for on-demand linting and fixing:
|
|
128
|
-
|
|
129
|
-
- `yarn lint`
|
|
130
|
-
- `yarn lint:css`
|
|
131
|
-
- `yarn lint:js`
|
|
132
|
-
|
|
133
|
-
## Release process
|
|
134
|
-
|
|
135
|
-
**At the start of a new release sprint:**
|
|
136
|
-
|
|
137
|
-
- Create a milestone called `next-release`.
|
|
138
|
-
|
|
139
|
-
**Throughout the release sprint:**
|
|
140
|
-
|
|
141
|
-
- Assign the appropriate `pr-` label to every new PR: `pr-major` if it contains a breaking change, `pr-minor` if it adds a new feature, `pr-patch` in all other cases.
|
|
142
|
-
- Assign issues and PRs to `next-release` as they are resolved/merged.
|
|
143
|
-
- Assign additional labels to issues when relevant (e.g. `deprecated`, `documentation`, etc.)
|
|
144
|
-
|
|
145
|
-
**At the end of the release sprint:**
|
|
146
|
-
|
|
147
|
-
> [!NOTE]
|
|
148
|
-
> **Note on versioning**: the version number follows the [semver](http://semver.org/) convention `MAJOR.MINOR.PATCH`, where: `MAJOR` corresponds to a breaking change (e.g. a change in a component's markup), `MINOR` to a new feature (e.g. a new component, a new feature for an existing component, etc.), and `PATCH` to a bug fix or under-the-hood change (e.g. code clean-up, performance improvement, etc.)
|
|
149
|
-
|
|
150
|
-
1. Look at all the PRs that were assigned to `next-release` throughout the sprint and identify the highest-level of change (major, minor or patch). Deduce the next release's version number and rename the milestone accordingly.
|
|
151
|
-
1. Create a new release notes draft based on the following template: `.github/RELEASE_NOTES_TEMPLATE.md`.
|
|
152
|
-
1. Write the release notes by going through all the issues and PRs assigned to the milestone.
|
|
153
|
-
1. Deploy to production:
|
|
154
|
-
1. Bump the `version` number in `package.json` (cf. note below).
|
|
155
|
-
1. Commit the version change to the `dev` branch.
|
|
156
|
-
1. Create a pull request to merge the `dev` branch into `master` - e.g. "Deploy v1.0.1".
|
|
157
|
-
1. Wait for the mandatory checks to pass then select `Create a merge commit`
|
|
158
|
-
1. Once the library and documentation sites are deployed, publish the release notes and close the milestone.
|
|
159
|
-
1. Share the release on the `design-systems` slack channel using the following template:
|
|
160
|
-
|
|
161
|
-
```
|
|
162
|
-
@channel new `gen2` version `vx.x.x` is out: https://github.com/unimelb/pattern-lib/releases/tag/vx.x.x
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
> [!TIP]
|
|
166
|
-
> Github Actions then automatically builds the library and syncs the output files to S3. If the version you're deploying had been previously deployed, you'll need to invalidate the files on the CDN (AWS Cloudfront) or wait a day or so for this to happen automatically. Once the library is deployed, follow the release process below.
|
|
167
|
-
|
|
168
|
-
### Semi-automatic deployment to dev
|
|
169
|
-
|
|
170
|
-
Pre-release builds can be created like this (using the git pre-push hook behind the scenes):
|
|
171
|
-
|
|
172
|
-
> [!NOTE]
|
|
173
|
-
> **Note on pre-release versions**: These are legitimate [semver](http://semver.org/) versions. They have the format MAJOR.MINOR.PATCH-beta.NUMBER. **Only** these pre-release versions will be published on `dev`.
|
|
174
|
-
|
|
175
|
-
1. Check out a clean `dev` branch
|
|
176
|
-
1. in bash `git push` - this will increment the pre-release version number and make a commit to your local repository
|
|
177
|
-
1. in bash `git push` again
|
|
178
|
-
- You will be prompted that this will trigger a build. Answer `y`
|
|
179
|
-
- This will push (only) your version number change commit to the remote `dev` repo
|
|
180
|
-
1. After the normal checks a build with the new version will be triggered by Github Actions
|
|
181
|
-
|
|
182
|
-
## Testing
|
|
183
|
-
|
|
184
|
-
### Component unit testing
|
|
185
|
-
To run the component units tests use `yarn test`. This runs the jest unit and accessibility tests.
|
|
186
|
-
|
|
187
|
-
### User agent
|
|
188
|
-
The end-to-end testing requires user agent to be set to load assets ie. images and videos hosted by CMS during testing. Update the local `.env` file and set the variable `MATRIX_USER_AGENT`.
|
|
189
|
-
|
|
190
|
-
> [!TIP]
|
|
191
|
-
> Refer to the GitHub repo setting environments for the latest value.
|
|
192
|
-
|
|
193
|
-
### Storybook end-to-end testing
|
|
194
|
-
To run the Storybook stories visual snapshots and story tests use `yarn test:e2e`.
|
|
195
|
-
|
|
196
|
-
To view the e2e test report use `yarn test:report`.
|
|
197
|
-
|
|
198
|
-
**Note:** the visual snapshot testing runs on Playwright and requires Docker to be up and running.
|
|
199
|
-
|
|
200
|
-
#### Visual snapshot testing
|
|
201
|
-
|
|
202
|
-
You can run the Storybook stories visual snapshot tests exclusively using `yarn test:snapshots`. This compares your changes against the baseline visual snapshot. To see the failed snapshot tests run `yarn test:report`.
|
|
203
|
-
|
|
204
|
-
If you wish to update the snapshots with your changes run `yarn test:update:snapshots`.
|
|
205
|
-
|
|
206
|
-
> [!IMPORTANT]
|
|
207
|
-
> Whenever a new story is created or the story name is updated, it is important to update the corresponding `*.spec.js` file for the story.
|
|
208
|
-
|
|
209
|
-
#### Example
|
|
210
|
-
The story `components/grid/stories/index.stories.js` corresponds to `e2e/tests/components/grid.spec.js`.
|
|
211
|
-
```
|
|
212
|
-
const component = 'Grid';
|
|
213
|
-
const stories = [
|
|
214
|
-
'Default',
|
|
215
|
-
'Desk',
|
|
216
|
-
'Desk Combination',
|
|
217
|
-
'Tab',
|
|
218
|
-
'Tab Combination',
|
|
219
|
-
'Wide',
|
|
220
|
-
'Wide Combination',
|
|
221
|
-
'Center Grid',
|
|
222
|
-
];
|
|
223
|
-
|
|
224
|
-
testVisualStory(component, stories);
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
`testVisualStory` will run the snapshot tests on the following viewports:
|
|
228
|
-
- 1280 x 3600 - desktop
|
|
229
|
-
- 480 x 3600 - mobile
|
|
230
|
-
|
|
231
|
-
### Testing Pull-requests
|
|
232
|
-
|
|
233
|
-
You can test `pull-requests` on live sites by using `?preview=test-xxx` where `xxx` is the pull-request `number`.
|
|
234
|
-
|
|
235
|
-
For example: https://study.unimelb.edu.au/?preview=test-2203 will load https://github.com/unimelb/pattern-lib/pull/2203
|
|
236
|
-
|
|
237
|
-
### How could you test before going live?
|
|
238
|
-
|
|
239
|
-
> Code changes to the remote `dev` branch triggers a `Github Actions` deploy into the AWS S3 Bucket in a folder called `latest` where the `CMS` team can appoint to `latest` and test it out before go to `production`.
|
|
240
|
-
|
|
241
|
-
> Each `pull request` that is opened, also is automatically generated a comment with a preview link to test it.
|
|
242
|
-
|
|
243
|
-
> **Note**: Always check `Github Actions` in your `pull request` checks to insure it is building properly, before merge into `dev`.
|
|
244
|
-
|
|
245
|
-
Supported browsers:
|
|
246
|
-
|
|
247
|
-
- last two versions of Chrome, Firefox and Edge
|
|
248
|
-
- IE 11
|
|
249
|
-
- Safari 8+
|
|
250
|
-
- iOS 8.4+
|
|
251
|
-
- Android 4.4+
|
|
252
|
-
- Firefox ESR (v52.x)
|
|
253
|
-
|
|
254
|
-
Recommended mobile devices for testing:
|
|
255
|
-
|
|
256
|
-
- iPhone 4S
|
|
257
|
-
- iPhone 6
|
|
258
|
-
- iPad 2
|
|
259
|
-
- Galaxy s5
|
|
260
|
-
|
|
261
|
-
### Visual Regression Tests
|
|
262
|
-
|
|
263
|
-
> [!IMPORTANT]
|
|
264
|
-
> These tests should be run **exclusively** on your **local** machine to detect visual regressions **before merging** your pull-request.
|
|
265
|
-
|
|
266
|
-
You can test your changes against live `production` sites to ensure nothing breaks.
|
|
267
|
-
|
|
268
|
-
- uses `TEST_PREVIEW_ID` located in `.env` - refer to `env.example`
|
|
269
|
-
- the list of production sites are located in `/e2e/tests/regression/pages.json`
|
|
270
|
-
|
|
271
|
-
#### Running regression tests
|
|
272
|
-
|
|
273
|
-
1. update your regression snapshots
|
|
274
|
-
|
|
275
|
-
> [!TIP]
|
|
276
|
-
> Make sure to comment out `TEST_PREVIEW_ID` to use the `dev` branch as the `base` snapshots. Alternatively, you can use any `pull-request` id.
|
|
277
|
-
|
|
278
|
-
```
|
|
279
|
-
yarn test:update:regression
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
2. set the `TEST_PREVIEW_ID` to your desired `pull-request` id
|
|
283
|
-
3. run the regression tests to compare your `pull-request` againts the base snapshots
|
|
284
|
-
|
|
285
|
-
```bash
|
|
286
|
-
yarn test:regression
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
4. view the report
|
|
290
|
-
|
|
291
|
-
```bash
|
|
292
|
-
yarn test:report
|
|
35
|
+
# 6. Start the Storybook development environment.
|
|
36
|
+
yarn dev
|
|
293
37
|
```
|
|
294
38
|
|
|
295
39
|
## Developer documentation
|
|
296
40
|
|
|
41
|
+
- [How to use the library](docs/how-to-use.md) - how this library externally
|
|
297
42
|
- [Documenting stories](docs/docs.md) - how to customise the content of the README panel for each story
|
|
298
43
|
- [Icons](docs/icons.md) - how to add new icons, and how to use icons in CSS and Vue components
|
|
299
|
-
- [Contributing](
|
|
44
|
+
- [Contributing](docs/contributing.md) - how to get involved and contribute code
|
|
45
|
+
- [Testing](docs/testing.md) - how to test your changes to the design system
|
|
46
|
+
- [Deployment](docs/deployment.md) - for developers, how to deploy new versions of the design system
|
|
300
47
|
|
|
301
48
|
## Example websites
|
|
302
49
|
|
|
303
50
|
- The following UoM websites are using these components on the new Squiz CMS (Gen 2). Documentation on how to use these components in Edit+ [Gen 2 documentation](https://matrix-cms.unimelb.edu.au/web/mce)
|
|
304
|
-
|
|
305
|
-
- [University Home Page](https://unimelb.edu.au)
|
|
51
|
+
- [Study](https://study.unimelb.edu.au)
|
|
306
52
|
- [About Us](https://about.unimelb.edu.au)
|
|
307
53
|
- [Brand Hub](https://brandhub.unimelb.edu.au)
|
|
308
|
-
- [MSpace](https://mspace.unimelb.edu.au)
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@unimelb/pattern-lib-vue",
|
|
3
3
|
"description": "A complete design system for the University of Melbourne.",
|
|
4
|
-
"version": "16.
|
|
4
|
+
"version": "16.1.0-dev",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
|
-
"url": "https://github.com/unimelb/pattern-lib.git"
|
|
7
|
+
"url": "git+https://github.com/unimelb/pattern-lib.git"
|
|
8
8
|
},
|
|
9
9
|
"author": "The University of Melbourne",
|
|
10
10
|
"license": "UNLICENSED",
|
|
@@ -134,7 +134,7 @@
|
|
|
134
134
|
"jest-axe": "3.1.1",
|
|
135
135
|
"jest-environment-jsdom": "29.7.0",
|
|
136
136
|
"jest-transform-stub": "2.0.0",
|
|
137
|
-
"lint-staged": "
|
|
137
|
+
"lint-staged": "^16.2.7",
|
|
138
138
|
"marked": "14.1.2",
|
|
139
139
|
"mini-css-extract-plugin": "2.9.0",
|
|
140
140
|
"npm-run-all": "4.1.5",
|
|
@@ -159,7 +159,7 @@
|
|
|
159
159
|
"rimraf": "3.0.2",
|
|
160
160
|
"serve": "11.3.0",
|
|
161
161
|
"start-server-and-test": "1.10.11",
|
|
162
|
-
"storybook": "8.
|
|
162
|
+
"storybook": "8.6.15",
|
|
163
163
|
"strip-html-comments": "1.0.0",
|
|
164
164
|
"style-loader": "0.21.0",
|
|
165
165
|
"stylelint": "14.16.1",
|