@royaloperahouse/chord 1.14.0 → 2.0.0-spike-chord-webpack-5

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/README.md CHANGED
@@ -1,67 +1,277 @@
1
- # Royal Opera House - chord
1
+ # Royal Opera House Chord - Front End Design System
2
2
 
3
- Welcome to the Royal Opera House library components `@royaloperahouse/chord`.
3
+ Welcome to the Royal Opera House Front End Design System, `@royaloperahouse/chord`
4
4
 
5
5
  This package is a library of UI components intended to be used in the ROH website.
6
6
 
7
+ It uses React, TypeScript, TSDX and Storybook.
7
8
 
8
- ## Install
9
+ The NPM packages are published at [https://www.npmjs.com/package/@royaloperahouse/chord](https://www.npmjs.com/package/@royaloperahouse/chord)
10
+
11
+ The Storybook for the latest version of the library is hosted at [chord.roh.org.uk](chord.roh.org.uk)
12
+
13
+
14
+ ## Prerequisites
15
+ ---
16
+
17
+ * Make sure the required package dependencies are installed using `yarn install`
18
+
19
+ * If this is the first time you are working on Chord, make sure to run `yarn build` to build all the modules.
20
+
21
+ * **To deploy the storybook publicly** you will need credentials for the **parent** 'Royal Opera House' AWS account in your `~/.aws/credentials` file.
22
+ * The deploy script expects these to be called `[parent]`.
23
+
24
+ * You can find these values at:
25
+
26
+ *AWS 'Your Applications' page -> 'Royal Opera House' -> 'Developer Access' -> 'Command line or programmatic access'*
27
+
28
+ * **To deploy a preview** for demo / QA you will need the `CHROMATIC_PROJECT_TOKEN` -- find this in 1Password
29
+
30
+
31
+ * **To publish the NPM package** you will need the ROH `NPM_TOKEN` -- find this in 1Password
32
+
33
+
34
+ ## Versioning
35
+ ---
36
+
37
+ We use [Semantic Versioning](https://semver.org/) for Chord.
38
+
39
+ Given a version number MAJOR.MINOR.PATCH, increment the:
40
+
41
+ * MAJOR version when you make incompatible library changes
42
+ * MINOR version when you add functionality in a backwards compatible manner
43
+ * PATCH version when you make backwards compatible bug fixes
44
+
45
+ When you create a new release always update the `CHANGELOG` and `package.json`
46
+
47
+ Increment your version from the latest stable version on `chord-releases`
48
+
49
+
50
+ ## Deploying the Storybook
51
+ ---
52
+
53
+ ### **1. To build and deploy locally**
54
+
55
+ You can quickly build and serve the contents of `/storybook-static` from your local machine, for development and manual testing. To do this run:
56
+
57
+ ```bash
58
+ yarn storybook
59
+ ```
60
+
61
+ By default the storybook will be accessible at
62
+ [http://localhost:6006/]()
63
+
64
+ The server will hot-reload on most changes.
65
+
66
+ ### **2. To deploy a preview version remotely**
67
+
68
+ You can deploy a release candidate, or work-in-progress to [Chromatic](https://www.chromatic.com/) for showcase or QA.
69
+
70
+ **NOTE:** you will need the `CHROMATIC_PROJECT_TOKEN` as described in *Prerequisites* above.
71
+
72
+ Either set the token as a shell variable or use a `.env` file in the chord root directory containing the token, as so:
73
+
74
+ ```
75
+ CHROMATIC_PROJECT_TOKEN=tokengoeshere
76
+ ```
77
+
78
+ Run:
79
+
80
+ ```
81
+ yarn deploy-storybook-dev
82
+ ```
83
+
84
+ to build and deploy the storybook from your repo to Chromatic.
85
+
86
+ You will find the address of your deployed storybook in the console output, looking something like this:
87
+
88
+ `→ View your Storybook at https://randomHexString-randomAlphabeticalString.chromatic.com`
89
+
90
+ ### **3. To deploy a release version**
91
+
92
+ You can deploy the contents of `./storybook-static` to S3 as a static site, which is permanently accessible at [chord.roh.org.uk](chord.roh.org.uk)
93
+
94
+ **NOTE:** To do this you will need the correct `AWS` credentials set up, as described in *Prerequisites* above.
95
+
96
+ First build the storybook using:
97
+
98
+ ```
99
+ yarn build-storybook
100
+ ```
101
+
102
+ then run:
103
+
104
+ ```bash
105
+ yarn deploy-storybook
106
+ ```
107
+
108
+ > **IMPORTANT:** This URL is intended to showcase the latest stable version of Chord, it should be kept up to date with the main `chord-releases` branch and should **only** be used for release versions. If you want to deploy a development version follow the steps above under *To deploy a preview version remotely*.
109
+
110
+
111
+ ## Releasing a New Package Version
112
+ ---
113
+
114
+ This is the procedure for releasing a new Chord NPM package.
115
+
116
+ There are two types of package:
117
+
118
+ A **snapshot** can be published to use a development version of the Chord library in our frontend staging environments, to perform integrated, manual testing.
119
+
120
+ A **stable** package is published for use in production.
121
+
122
+ **NOTE:** You will need the `NPM_TOKEN`, as described in 'Prerequisites' above.
123
+
124
+ ### **1. To release a snapshot version**
125
+
126
+ > **IMPORTANT:** Make sure you always publish your **snapshots** from `chord-development` after merging in your feature branch.
127
+
128
+ For snapshots, `RELEASE_VERSION` should be the same as the latest **stable** version of the Chord Library, as found in `chord-releases`, followed by an **unused** lowercase letter.
129
+
130
+ For example, if the latest stable release was 1.42.0, and the last snapshot published to NPM was 1.42.0-w, you would use RELEASE_VERSION `1.42.0-x`
131
+
132
+ To publish a snapshot use:
9
133
 
10
134
  ```bash
11
- npm i --save @royaloperahouse/chord
135
+ NPM_ROH_TOKEN={NPM_TOKEN} RELEASE_VERSION={RELEASE_VERSION} yarn publish-snapshot
12
136
  ```
137
+
138
+ The version published to NPM will be named, e.g. `1.42.0-a-chord-development`, use this to install the snapshot package in the frontend repos.
139
+
140
+ ### **2. To release a stable version**
141
+
142
+ > **IMPORTANT:** Make sure you always publish your **stable** packages from `chord-releases` after merging in your feature branch.
143
+
144
+ For stable releases, increment your version from the latest **stable** version found on `chord-releases`, following the rules described in *Versioning* above, and use this as `RELEASE_VERSION`. (Make sure it matches the version in your `package.json` and `CHANGELOG.md`!)
145
+
146
+ To publish a stable package use:
147
+
13
148
  ```bash
14
- yarn add @royaloperahouse/chord
149
+ NPM_ROH_TOKEN={NPM_TOKEN} RELEASE_VERSION={RELEASE_VERSION} yarn publish-release
15
150
  ```
16
151
 
17
- ## Usage
18
152
 
19
- ```javascript
20
- import {
21
- Footer, GlobalStyles, ThemeProvider, ThemeType,
22
- } from '@royaloperahouse/chord';
153
+ ## Using the Package
154
+ ---
155
+
156
+ The package is deployed to NPM, and can be installed using yarn or npm:
23
157
 
158
+ ```bash
159
+ npm i --save @royaloperahouse/chord
24
160
  ```
25
- ## Sample
161
+ ```bash
162
+ yarn add @royaloperahouse/chord
163
+ ```
164
+
26
165
 
27
- ```javascript
166
+ ## Testing
167
+ ---
28
168
 
29
- import {
30
- Footer, GlobalStyles, ThemeProvider, ThemeType,
31
- } from '@royaloperahouse/chord';
169
+ To **Lint** the package use:
32
170
 
171
+ ```bash
172
+ yarn lint
173
+ # Use the --fix option to perform automatic fixes
174
+ ```
33
175
 
34
- const App = ({ children }: InnerProps): React.ReactElement => (
35
- <ErrorBoundary>
36
- <ThemeProvider theme={ThemeType.Core}>
37
- <GlobalStyles />
38
- <Wrapper>
39
- <Header />
40
- <GlobalStyle />
41
- <HealthBanner />
42
- <ErrorBoundary>
43
- <Content>
44
- {children}
45
- </Content>
46
- </ErrorBoundary>
47
- <LiveChat />
48
- </Wrapper>
49
- <Footer data={footerData} />
50
- </ThemeProvider>
51
- </ErrorBoundary>
52
- );
176
+ To run the **unit tests** (using Jest) use:
53
177
 
178
+ ```bash
179
+ yarn test
180
+
181
+ # Use the -u option to update snapshots if needed
182
+ # Run `yarn test:watch` to re-run tests on changes
54
183
  ```
55
184
 
56
- ## Components
185
+ To **run and and store the unit tests** for display in storybook use:
186
+
187
+ ```bash
188
+ yarn test-storybook
189
+ # Use the -u option to update snapshots if needed
190
+ ```
191
+
192
+
193
+ ## Development Process
194
+ ---
195
+
196
+ ### **1. Branching Model**
197
+ * The Chord project lives in the `roh-components` *monorepo*
198
+ * When working on Chord, treat the `roh-components/packages/chord` directory as your root
199
+ * The Chord **development** branch is currently `chord-development`
200
+ * The Chord **main** branch is currently `chord-releases`
201
+ * All work should be done on a correctly named **feature branch** of the format: `issueType/ticketNumber-short-description-of-feature`, e.g. `feature/RD-1234-update-chord-documentation`
202
+ * Always create your feature branch FROM, and submit pull requests TO, the **main** branch
203
+ * For **QA / UAT** of a Chord component in isolation: following review you should deploy a preview version to Chromatic straight from your **feature branch** _without_ merging to development
204
+ * For releasing an **NPM snapshot**: merge your feature branch into the **development** branch and publish the NPM snapshot from there
205
+
206
+ ### **2. Detailed Workflow**
207
+
208
+ #### **Before review:**
209
+
210
+ * Git pull the latest version of `chord-releases`
211
+ * Checkout a new, correctly-named feature branch from `chord releases`
212
+ * Do your work on this feature branch
213
+ * Run: `yarn lint`
214
+ * Run: `yarn test`
215
+ * Commit your changes
216
+ * Create a pull request from your feature branch to `chord-releases`
217
+ * Add the appropriate reviewers
218
+
219
+ #### **Before QA / UAT:**
220
+
221
+ After your PR is approved, you have two options:
222
+
223
+ **i.** For QA of a component in isolation:
57
224
 
58
- Accordion, Accordions, AltHeader, AnchorTabBar, AnnouncementBanner, BodyText, Card, Cards, Carousel, CinemaBadge, ContactCard, ControlledDropdown, devices, Editorial, Footer, GlobalStyles, Grid, GridItem, Header, HighlightsCarousel, HighlightsCarouselCinema, HighlightsCarouselCore, HighlightsCarouselStream, Icon, ImageWithCaption, Navigation, Overline, PageHeadingCinema, PageHeadingCore, PageHeadingImpact, PageHeadingStream, PeopleListing, PrimaryButton, PromoWithTags, PromoWithTitle, RotatorButtons, SecondaryButton, SecondaryLogo, SectionSplitter, SectionTitle, Sponsorship, StickyBar, StreamBadge, Subtitle, Tab, TabLink, Tabs, TertiaryButton, TextLink, TextOnly, Tickbox, TitleWithCTA, ThemeProvider, TypeTags, Quote
225
+ * Follow the steps above in *Deploying the Storybook -> 2. Deploying a preview version remotely*
226
+ * Share the generated Chromatic URL with the appropriate people for QA / UAT
227
+
228
+ **ii.** For integrated testing of a component in the frontend staging environments:
229
+
230
+ * Check out the `chord-development` branch
231
+ * Merge your work in to `chord-development`
232
+ * Follow the steps above under *Publishing a New Package Version -> 1. To release a snapshot version*
233
+ * Git push the updated `chord-development` branch to remote
234
+ * Finally, in the frontend repo:
235
+
236
+ 1. Update the `package.json` to reference the new snapshot version
237
+ 2. Run: `yarn install`
238
+ 3. Deploy the frontend to a staging environment
239
+
240
+ #### **When ready for production:**
241
+
242
+ * Return to your chord **feature branch**
243
+ * Update the chord version in `package.json`, incrementing from the last **stable** release, found in `chord-releases`, and following the rules described in the *Versioning* section
244
+ * Update `CHANGELOG.md`, adding the new version number and a short description of your changes
245
+ * Run: `yarn lint`
246
+ * Run: `yarn test`
247
+ * Run: `yarn test-storybook -u`
248
+ * Run: `yarn build-storybook`
249
+ * Git commit, push, and update your PR for final approval
250
+ * Merge your approved PR to `chord-releases`
251
+ * Follow the steps in *Publishing a New Package Version -> 2. To release a stable version* to publish the NPM package
252
+ * Finally, follow the steps in *Deploying The Storybook -> 3. To deploy a release version*, to update the public Chord Storybook page
253
+
254
+ Once you have successfully published a new release version, you can open a ticket to update to this version in any of the frontend repos.
255
+
256
+
257
+ ## Notes
258
+ ---
259
+ ### The `storybook-static` folder
260
+
261
+ This folder contains all the HTML / JS required to deploy the Storybook as a static site. It's autogenerated whenever the Storybook is built and therefore will show up a lot of merge conflicts when you merge other branches into your feature branch. It is best to leave generating the storybook until the later part of your workflow, but in case you run into conflicts earlier, it's ok to just delete the folder and regenerate using:
262
+
263
+ ```bash
264
+ yarn build-storybook
265
+ ```
59
266
 
60
- ## Types
267
+ For the same reason changes to this folder will cause a lot of big diffs, when looking at a PR, but can mostly be skimmed over unless something looks unusual.
61
268
 
62
- AspectRatio, CarouselType, Colors, FooterData, INavigationProps, INavTopProps, TickboxMode, ThemeType
269
+ ---
270
+ ### Examples
63
271
 
272
+ There is an example implementation in the example folder. Alternatively there are also integration examples in storybook. Make sure to keep these updated so as to showcase the current components available.
64
273
 
65
- ## Documentation
274
+ ---
275
+ ### Bundle analysis
66
276
 
67
- See Storybook as a reference
277
+ Calculate the real cost of your library using [size-limit](https://github.com/ai/size-limit) with `yarn size` and visualize it with `yarn analyze`.
@@ -8,7 +8,7 @@ var React = require('react');
8
8
  var React__default = _interopDefault(React);
9
9
  var styled = require('styled-components');
10
10
  var styled__default = _interopDefault(styled);
11
- var swiperReact_js = require('swiper/react/swiper-react.js');
11
+ var react = require('swiper/react');
12
12
  require('swiper/swiper-bundle.css');
13
13
  var reactRouterDom = require('react-router-dom');
14
14
 
@@ -2760,7 +2760,7 @@ var SectionSplitter = function SectionSplitter(_ref) {
2760
2760
  };
2761
2761
 
2762
2762
  var _templateObject$f;
2763
- var ImageAspectRatioWrapper = /*#__PURE__*/styled__default.div(_templateObject$f || (_templateObject$f = /*#__PURE__*/_taggedTemplateLiteralLoose(["\n aspect-ratio: ", ";\n\n @supports not (aspect-ratio: ", ") {\n position: relative;\n width: 100%;\n padding-top: ", "%;\n }\n\n img {\n display: block;\n width: 100%;\n height: 100%;\n object-fit: cover;\n\n @supports not (aspect-ratio: ", ") {\n position: absolute;\n top: 0;\n left: 0;\n }\n }\n"])), function (_ref) {
2763
+ var ImageAspectRatioWrapper = /*#__PURE__*/styled__default.div(_templateObject$f || (_templateObject$f = /*#__PURE__*/_taggedTemplateLiteralLoose(["\n aspect-ratio: ", ";\n\n @supports not (\n aspect-ratio: ", "\n ) {\n position: relative;\n width: 100%;\n padding-top: ", "%;\n }\n\n img {\n display: block;\n width: 100%;\n height: 100%;\n object-fit: cover;\n\n @supports not (\n aspect-ratio: ", "\n ) {\n position: absolute;\n top: 0;\n left: 0;\n }\n }\n"])), function (_ref) {
2764
2764
  var _ref$aspectRatio = _ref.aspectRatio,
2765
2765
  aspectRatio = _ref$aspectRatio === void 0 ? exports.AspectRatio['1:1'] : _ref$aspectRatio;
2766
2766
  return aspectRatio;
@@ -4614,7 +4614,7 @@ var Carousel = function Carousel(_ref) {
4614
4614
  columnSpanDesktop: 16,
4615
4615
  columnStartDevice: 1,
4616
4616
  columnSpanDevice: 14
4617
- }, /*#__PURE__*/React__default.createElement(swiperReact_js.Swiper, {
4617
+ }, /*#__PURE__*/React__default.createElement(react.Swiper, {
4618
4618
  slidesPerView: "auto",
4619
4619
  slidesOffsetBefore: slidesOffsetBefore,
4620
4620
  loop: loop,
@@ -4622,7 +4622,7 @@ var Carousel = function Carousel(_ref) {
4622
4622
  onSwiper: onSwiper,
4623
4623
  "data-testid": "carousel-swiper"
4624
4624
  }, React__default.Children.map(children, function (child) {
4625
- return /*#__PURE__*/React__default.createElement(swiperReact_js.SwiperSlide, null, child);
4625
+ return /*#__PURE__*/React__default.createElement(react.SwiperSlide, null, child);
4626
4626
  })))));
4627
4627
  };
4628
4628
 
@@ -4873,13 +4873,13 @@ var HighlightsCarousel = function HighlightsCarousel(_ref) {
4873
4873
  }, /*#__PURE__*/React__default.createElement(RotatorButtons, {
4874
4874
  onClickNext: onNext,
4875
4875
  onClickPrev: onPrev
4876
- })), /*#__PURE__*/React__default.createElement(swiperReact_js.Swiper, {
4876
+ })), /*#__PURE__*/React__default.createElement(react.Swiper, {
4877
4877
  slidesPerView: "auto",
4878
4878
  loop: hasMultipleImages,
4879
4879
  loopedSlides: images.length,
4880
4880
  onSwiper: onSwiper
4881
4881
  }, images.map(function (image) {
4882
- return /*#__PURE__*/React__default.createElement(swiperReact_js.SwiperSlide, {
4882
+ return /*#__PURE__*/React__default.createElement(react.SwiperSlide, {
4883
4883
  key: image.key
4884
4884
  }, /*#__PURE__*/React__default.createElement(ImageAspectRatioWrapper, {
4885
4885
  aspectRatio: exports.AspectRatio['4:3']
@@ -6057,13 +6057,13 @@ var PageHeadingHighlight = function PageHeadingHighlight(_ref) {
6057
6057
  }, /*#__PURE__*/React__default.createElement(RotatorButtons, {
6058
6058
  onClickNext: onNext,
6059
6059
  onClickPrev: onPrev
6060
- })), /*#__PURE__*/React__default.createElement(swiperReact_js.Swiper, {
6060
+ })), /*#__PURE__*/React__default.createElement(react.Swiper, {
6061
6061
  slidesPerView: "auto",
6062
6062
  loop: hasMultipleImages,
6063
6063
  loopedSlides: headerImages.length,
6064
6064
  onSwiper: onSwiper
6065
6065
  }, headerImages.map(function (image, index) {
6066
- return /*#__PURE__*/React__default.createElement(swiperReact_js.SwiperSlide, {
6066
+ return /*#__PURE__*/React__default.createElement(react.SwiperSlide, {
6067
6067
  key: "carousel-image-" + index
6068
6068
  }, /*#__PURE__*/React__default.createElement(ImageAspectRatioWrapper, {
6069
6069
  aspectRatio: exports.AspectRatio['4:3']
@@ -6205,8 +6205,7 @@ var Pagination = function Pagination(_ref) {
6205
6205
  // Array of page numbers starting at 1
6206
6206
  var pageNumbers = Array.from(Array(pageCount).keys());
6207
6207
  var reducedPageNumbers = reducePages(pageNumbers, currentPage);
6208
- return /*#__PURE__*/React__default.createElement(PageNumberWrapper, null, // {/* Left arrow only appears after page 1 */
6209
- currentPage > 0 && /*#__PURE__*/React__default.createElement("li", {
6208
+ return /*#__PURE__*/React__default.createElement(PageNumberWrapper, null, currentPage > 0 && /*#__PURE__*/React__default.createElement("li", {
6210
6209
  key: "previous-page",
6211
6210
  "data-testid": "left-arrow"
6212
6211
  }, /*#__PURE__*/React__default.createElement(NextPage, {