@nationalarchives/frontend 0.1.3-prerelease → 0.1.5-prerelease
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 +0 -167
- package/nationalarchives/_base.scss +1 -4
- package/nationalarchives/all.css +1 -1
- package/nationalarchives/all.css.map +1 -1
- package/nationalarchives/all.scss +0 -5
- package/nationalarchives/components/_all.scss +4 -4
- package/nationalarchives/components/grid/_index.scss +1 -1
- package/nationalarchives/components/sensitive-image/_index.scss +1 -1
- package/nationalarchives/stories/development/about.mdx +62 -0
- package/nationalarchives/stories/development/dependencies.mdx +9 -0
- package/nationalarchives/stories/development/publishing.mdx +16 -0
- package/nationalarchives/stories/development/relationships.md +91 -0
- package/nationalarchives/stories/development/structure.mdx +2 -2
- package/nationalarchives/tools/_all.scss +1 -0
- package/nationalarchives/utilities/_all.scss +0 -1
- package/package.json +2 -2
- /package/nationalarchives/{utilities → tools}/_grid.scss +0 -0
package/README.md
CHANGED
|
@@ -22,170 +22,3 @@ npm install
|
|
|
22
22
|
# Start Storybook
|
|
23
23
|
npm start
|
|
24
24
|
```
|
|
25
|
-
|
|
26
|
-
### Updating
|
|
27
|
-
|
|
28
|
-
```sh
|
|
29
|
-
# Upgrade all Storybook packages
|
|
30
|
-
npx sb upgrade
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
### Release
|
|
34
|
-
|
|
35
|
-
```sh
|
|
36
|
-
# Update version in package.json
|
|
37
|
-
npm install
|
|
38
|
-
# Commit and push to main
|
|
39
|
-
git tag v0.1.0
|
|
40
|
-
git push origin --tags
|
|
41
|
-
# Create a new release on GitHub: https://github.com/nationalarchives/tna-frontend/releases/new
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## Needs
|
|
45
|
-
|
|
46
|
-
TNA needs a frontend toolkit that is:
|
|
47
|
-
|
|
48
|
-
- standardised - a single source of truth for all TNA that follows all our coding standards (currently non-existent)
|
|
49
|
-
- version controlled - as well as [semantically versioned](https://semver.org/) with a [changelog](https://keepachangelog.com/en/1.0.0/)
|
|
50
|
-
- open - all source code should be [open and available to anyone](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open)
|
|
51
|
-
- accessible - all components meet WCAG 2.1 AA standards
|
|
52
|
-
- progressively enhanced - all components should still be operable without JavaScript, CSS or both
|
|
53
|
-
- importable into projects (via a service such as [NPM](https://www.npmjs.com/search?q=nationalarchives)) - to make dependency management as simple as possible
|
|
54
|
-
- agnostic - the implementation for the markup of the components can be replicated in any required technology (because we have Python, PHP and Java applications throughout the organisation)
|
|
55
|
-
- testable - both from an internal perspective as well as providing scenarios and expected results for language implimentations to be able to validate against
|
|
56
|
-
- lean - minimal reliance on other languages and dependencies to ensure good extendability and speed of development and deployment
|
|
57
|
-
- automatically published - leveraging CI/CD, creating a new release version should be as simple as possible
|
|
58
|
-
|
|
59
|
-
It would also be nice to have a toolkit that is:
|
|
60
|
-
|
|
61
|
-
- extendable - rather than providing a static snapshot of the toolkit, we should always be able to extend it for any given application
|
|
62
|
-
- documentable - not just from a technical perspective but also from a user-centred design perspective with best practices of when and how to use each component (this might be a separate project where we can [share information such as user research](https://www.gov.uk/service-manual/service-standard/point-13-use-common-standards-components-patterns))
|
|
63
|
-
- prototype-able - by using Nunjucks, we could easily create a toolkit that integrated with the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk/docs/) which means we could very easily create high fidelity prototypes to test with, ultimately helping with user research
|
|
64
|
-
|
|
65
|
-
## Current solutions
|
|
66
|
-
|
|
67
|
-
There is already a solution in [nationalarchives/tdr-components](https://github.com/nationalarchives/tdr-components) which is specific to TDR and extends the GOV.UK components and styles. We need to create a more generic set of components that are suitable for every TNA service, while still extending the GOV.UK components and styles but with a more TNA-branded look and feel.
|
|
68
|
-
|
|
69
|
-
We also have [nationalarchives/tna-frontend-design-toolkit](https://github.com/nationalarchives/tna-frontend-design-toolkit) which aims to provide similar functionality but isn't as featureful as we need and isn't published to NPM which means it has to be [copied into the projects that require it](https://github.com/nationalarchives/ds-wagtail/tree/develop/sass/tna-toolkit).
|
|
70
|
-
|
|
71
|
-
## Proposed solution
|
|
72
|
-
|
|
73
|
-
This repository should hold all the JavaScript and SCSS source files required for all the frontend styles along with tests and expected markup.
|
|
74
|
-
|
|
75
|
-
### Output
|
|
76
|
-
|
|
77
|
-
The source files will be compiled down to a NodeJS package and deployed to [NPM](https://www.npmjs.com/). The package will contain:
|
|
78
|
-
|
|
79
|
-
- All the JavaScript and SCSS source files which can be imported into a projects source code and compiled by the project (which will allow for tree shaking and application-specific modifications)
|
|
80
|
-
- An AMD/UMD/IIFE (TBD) ES5 JavaScript file which can be included with a normal `<script>` element
|
|
81
|
-
- A single CSS file containing all the styles which can be included with a normal `<style>` element
|
|
82
|
-
- The Nunjucks templates for each component that might be required in other projects such as prototyping tools (other implementations can be made such as [Jinja templates](https://github.com/nationalarchives/tna-frontend-jinja))
|
|
83
|
-
|
|
84
|
-
### Component resources
|
|
85
|
-
|
|
86
|
-
Each component in this repository should contain:
|
|
87
|
-
|
|
88
|
-
- Nunjucks template - only used to display the component within the examples page and aid development
|
|
89
|
-
- SCSS - which could either be imported as a standalone styles declaration or as part of the compiled output
|
|
90
|
-
- JavaScript (ESNext) - if there is any progressive enhancement required on the component
|
|
91
|
-
- Options/properties - a list of the configurable properties of the component and their types
|
|
92
|
-
- Test scenarios - a variety of configurations and their expected outputs that can be used by either this repository or other implementations of the components (e.g. Jinja)
|
|
93
|
-
|
|
94
|
-
### Technologies
|
|
95
|
-
|
|
96
|
-
- SCSS (used by GDS, is the de facto standard CSS preprocessor, already using in ETNA)
|
|
97
|
-
- Webpack - compilation of JavaScript and CSS (used by numerous TNA projects already)
|
|
98
|
-
- Babel - will allow us to use ESNext or possibly even TypeScript (although this could go against the lean requirement)
|
|
99
|
-
- Storybook - allow viewing and testing of components (we have already used this elsewhere in TNA)
|
|
100
|
-
|
|
101
|
-
### Relationship to other resources
|
|
102
|
-
|
|
103
|
-
#### System context
|
|
104
|
-
|
|
105
|
-
```mermaid
|
|
106
|
-
C4Context
|
|
107
|
-
Person(dev, "Developer", "TNA developer")
|
|
108
|
-
System_Ext(github, "GitHub", "Repositories for source files")
|
|
109
|
-
System_Ext(npm, "NPMJS", "Hosts NodeJS packages")
|
|
110
|
-
System_Ext(pypi, "PyPi", "Hosts Python packages")
|
|
111
|
-
Container(app, "Application", "Example application")
|
|
112
|
-
System_Ext(pypi, "PyPi", "Hosts Python packages")
|
|
113
|
-
|
|
114
|
-
Rel(dev, github, "commits to", "git")
|
|
115
|
-
UpdateRelStyle(dev, github, $offsetX="-30", $offsetY="-30")
|
|
116
|
-
Rel(github, npm, "publishes to", "npm")
|
|
117
|
-
Rel(github, pypi, "publishes to", "pip")
|
|
118
|
-
Rel(app, npm, "consumes", "npm")
|
|
119
|
-
Rel(app, pypi, "consumes", "pip")
|
|
120
|
-
|
|
121
|
-
UpdateLayoutConfig($c4ShapeInRow="2")
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
#### Component diagram
|
|
125
|
-
|
|
126
|
-
```mermaid
|
|
127
|
-
C4Context
|
|
128
|
-
Person(dev, "Developer", "TNA developer")
|
|
129
|
-
|
|
130
|
-
%% Boundary(developer_machine, "Developer machine", "boundary") {
|
|
131
|
-
%% System(docker, "Docker")
|
|
132
|
-
%% }
|
|
133
|
-
|
|
134
|
-
Boundary(github, "GitHub", "boundary") {
|
|
135
|
-
Boundary(github_jinja, "Jinja templates", "repository") {
|
|
136
|
-
Container(github_jinja_source, "Jinja templates")
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
Boundary(github_frontend, "Frontend styles", "repository") {
|
|
140
|
-
Container(github_frontend_source, "Frontend styles", "git repository")
|
|
141
|
-
}
|
|
142
|
-
|
|
143
|
-
Boundary(github_application, "Application", "repository") {
|
|
144
|
-
Container(github_application_source, "Application source code")
|
|
145
|
-
Component(github_application_image, "Application docker image", "GitHub image registry")
|
|
146
|
-
}
|
|
147
|
-
}
|
|
148
|
-
|
|
149
|
-
Boundary(npm, "NPMJS", "boundary") {
|
|
150
|
-
Component(npm_package, "Frontend styles")
|
|
151
|
-
}
|
|
152
|
-
|
|
153
|
-
Enterprise_Boundary(aws, "TNA AWS", "boundary") {
|
|
154
|
-
Container(app, "Application")
|
|
155
|
-
}
|
|
156
|
-
|
|
157
|
-
Boundary(pypi, "PyPi", "boundary") {
|
|
158
|
-
Component(pypi_package, "Jinja templates")
|
|
159
|
-
}
|
|
160
|
-
|
|
161
|
-
Rel(dev, github_frontend_source, "commits to")
|
|
162
|
-
UpdateRelStyle(dev, github_frontend_source, $offsetX="-80", $offsetY="-80")
|
|
163
|
-
Rel(github_frontend_source, npm_package, "publishes", "GitHub action")
|
|
164
|
-
UpdateRelStyle(github_frontend_source, npm_package, $offsetX="-40", $offsetY="-40")
|
|
165
|
-
|
|
166
|
-
Rel(dev, github_jinja_source, "commits to")
|
|
167
|
-
UpdateRelStyle(dev, github_jinja_source, $offsetX="-15", $offsetY="-80")
|
|
168
|
-
Rel(github_jinja_source, github_frontend_source, "consumes")
|
|
169
|
-
UpdateRelStyle(github_jinja_source, github_frontend_source, $offsetX="-40", $offsetY="-15")
|
|
170
|
-
Rel(github_jinja_source, pypi_package, "publishes", "GitHub action")
|
|
171
|
-
UpdateRelStyle(github_jinja_source, pypi_package, $offsetX="-110", $offsetY="-310")
|
|
172
|
-
|
|
173
|
-
Rel(dev, github_application_source, "commits to")
|
|
174
|
-
UpdateRelStyle(dev, github_application_source, $offsetX="-105", $offsetY="-250")
|
|
175
|
-
Rel(github_application_source, github_application_image, "creates", "GitHub action")
|
|
176
|
-
UpdateRelStyle(github_application_source, github_application_image, $offsetX="-90", $offsetY="-20")
|
|
177
|
-
|
|
178
|
-
Rel(github_application_image, npm_package, "consumes", "GitHub action")
|
|
179
|
-
UpdateRelStyle(github_application_image, npm_package, $offsetX="-50", $offsetY="-10")
|
|
180
|
-
Rel(github_application_image, pypi_package, "consumes", "GitHub action")
|
|
181
|
-
UpdateRelStyle(github_application_image, pypi_package, $offsetX="-120", $offsetY="-10")
|
|
182
|
-
|
|
183
|
-
%% Rel(dev, docker, "uses")
|
|
184
|
-
%% Rel(docker, npm_package, "consumes")
|
|
185
|
-
%% Rel(docker, pypi_package, "consumes")
|
|
186
|
-
|
|
187
|
-
Rel(app, github_application_image, "consumes")
|
|
188
|
-
UpdateRelStyle(app, github_application_image, $offsetX="-70", $offsetY="-10")
|
|
189
|
-
|
|
190
|
-
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")
|
|
191
|
-
```
|
package/nationalarchives/all.css
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
@import"https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;700&family=Roboto+Mono:wght@500;700&display=swap";.tna-template{min-width:320px;width:100%;height:100%;overflow-x:hidden;overflow-y:auto;-webkit-overflow-scrolling:touch}@media(prefers-reduced-motion){.tna-template *{animation:none !important;transition:none !important}}.tna-template__body{margin:0;padding:0;background-color:#fff;overflow:auto}img,svg,video,canvas{max-width:100%;display:block}video,canvas{width:100%}.tna-template{font-family:"Open Sans",sans-serif;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;-webkit-text-size-adjust:none;direction:ltr}.tna-template__body{font-size:1rem;line-height:1.6}.tna-heading--xl{font-size:4rem}.tna-heading--l{font-size:2rem}.tna-heading--m{font-size:1.3rem}.tna-heading--s{font-size:1.125rem}.tna-hgroup--xl .tna-hgroup__title{font-size:4rem}.tna-hgroup--l .tna-hgroup__title{font-size:2rem}.tna-hgroup--m .tna-hgroup__title{font-size:1.3rem}.tna-hgroup--s .tna-hgroup__title{font-size:1.125rem}.tna-hgroup__supertitle{text-transform:uppercase}.tna-container{max-width:75.25rem;width:100%;margin-right:auto;margin-left:auto;padding-right:1rem;padding-left:1rem;box-sizing:border-box;display:-ms-flexbox;display:flex;flex-wrap:wrap;justify-content:stretch;align-items:stretch}.tna-container.tna-container--max{max-width:none}.tna-container.tna-container--no-padding{max-width:71.25rem;padding-right:0;padding-left:0}.tna-container.tna-container--no-padding .tna-column{padding-right:0;padding-left:0}.tna-column{padding-right:1rem;padding-left:1rem;box-sizing:border-box}.tna-column.tna-column--full{width:100%}.tna-column--flex-1{flex:1 0}.tna-column--flex-2{flex:2 0}.tna-column--flex-3{flex:3 0}.tna-column--width-1-12{width:8.3333333333%}.tna-column--width-1-6{width:16.6666666667%}.tna-column--width-1-4{width:25%}.tna-column--width-1-3{width:33.3333333333%}.tna-column--width-5-12{width:41.6666666667%}.tna-column--width-1-2{width:50%}.tna-column--width-7-12{width:58.3333333333%}.tna-column--width-2-3{width:66.6666666667%}.tna-column--width-3-4{width:75%}.tna-column--width-5-6{width:83.3333333333%}.tna-column--width-11-12{width:91.6666666667%}@media(min-width: 769px)and (max-width: 1024px){.tna-column--width-full-medium{width:100%}.tna-column--flex-1-medium{flex:1 0}.tna-column--flex-2-medium{flex:2 0}.tna-column--flex-3-medium{flex:3 0}.tna-column--width-1-6-medium{width:16.6666666667%}.tna-column--width-1-3-medium{width:33.3333333333%}.tna-column--width-1-2-medium{width:50%}.tna-column--width-2-3-medium{width:66.6666666667%}.tna-column--width-5-6-medium{width:83.3333333333%}}@media(max-width: 768px){.tna-container{padding-right:1.125rem;padding-left:1.125rem}.tna-column{padding-right:.375rem;padding-left:.375rem}}@media(min-width: 481px)and (max-width: 768px){.tna-column--width-full-small{width:100%}.tna-column--flex-1-small{flex:1 0}.tna-column--flex-2-small{flex:2 0}.tna-column--flex-3-small{flex:3 0}.tna-column--width-1-4-small{width:25%}.tna-column--width-1-2-small{width:50%}.tna-column--width-3-4-small{width:75%}}@media(max-width: 480px){.tna-column--width-full-tiny{width:100%}.tna-column--flex-1-tiny{width:auto;flex:1 0}.tna-column--flex-2-tiny{width:auto;flex:2 0}.tna-column--flex-3-tiny{width:auto;flex:3 0}.tna-column--width-1-2-tiny{width:50%}}.tna-
|
|
1
|
+
@import"https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;700&family=Roboto+Mono:wght@500;700&display=swap";.tna-template{min-width:320px;width:100%;height:100%;overflow-x:hidden;overflow-y:auto;-webkit-overflow-scrolling:touch}@media(prefers-reduced-motion){.tna-template *{animation:none !important;transition:none !important}}.tna-template__body{margin:0;padding:0;background-color:#fff;overflow:auto}img,svg,video,canvas{max-width:100%;display:block}video,canvas{width:100%}.tna-template{font-family:"Open Sans",sans-serif;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;-webkit-text-size-adjust:none;direction:ltr}.tna-template__body{font-size:1rem;line-height:1.6}.tna-heading--xl{font-size:4rem}.tna-heading--l{font-size:2rem}.tna-heading--m{font-size:1.3rem}.tna-heading--s{font-size:1.125rem}.tna-hgroup--xl .tna-hgroup__title{font-size:4rem}.tna-hgroup--l .tna-hgroup__title{font-size:2rem}.tna-hgroup--m .tna-hgroup__title{font-size:1.3rem}.tna-hgroup--s .tna-hgroup__title{font-size:1.125rem}.tna-hgroup__supertitle{text-transform:uppercase}.tna-button{padding:.25rem 1rem;display:inline-block;color:#fff;text-decoration:none;background-color:#000}.tna-button:hover{background-color:#069}.tna-button--secondary{color:#000;background-color:#ff0}.tna-button--secondary:hover{color:#fff}.tna-card{display:-ms-flexbox;display:flex;-ms-box-orient:vertical;-ms-flex-direction:column;flex-direction:column}.tna-card__heading{order:2}.tna-card__image{order:1}.tna-card__body{order:3}.tna-card__actions{order:4}.tna-footer{padding-top:3rem;padding-bottom:3rem;color:#fff;background-color:#26262a}.tna-footer__link{color:inherit}.tna-footer__link:hover{color:#f0a}.tna-footer__navigation{padding-bottom:3rem}.tna-footer__navigation-group-items{padding-left:0;list-style:none}.tna-footer__social{padding-bottom:4rem}.tna-footer__social-item{text-align:center}.tna-footer__licence-logo{display:block}.tna-footer__govuk-link{display:inline-block;color:inherit;fill:#fff}.tna-footer__govuk-link:hover{color:#f0a;fill:#f0a}.tna-footer__govuk-logotype-crown{margin:0 auto;display:block;fill:inherit}.tna-container{max-width:75.25rem;width:100%;margin-right:auto;margin-left:auto;padding-right:1rem;padding-left:1rem;box-sizing:border-box;display:-ms-flexbox;display:flex;flex-wrap:wrap;justify-content:stretch;align-items:stretch}.tna-container.tna-container--max{max-width:none}.tna-container.tna-container--no-padding{max-width:71.25rem;padding-right:0;padding-left:0}.tna-container.tna-container--no-padding .tna-column{padding-right:0;padding-left:0}.tna-column{padding-right:1rem;padding-left:1rem;box-sizing:border-box}.tna-column.tna-column--full{width:100%}.tna-column--flex-1{flex:1 0}.tna-column--flex-2{flex:2 0}.tna-column--flex-3{flex:3 0}.tna-column--width-1-12{width:8.3333333333%}.tna-column--width-1-6{width:16.6666666667%}.tna-column--width-1-4{width:25%}.tna-column--width-1-3{width:33.3333333333%}.tna-column--width-5-12{width:41.6666666667%}.tna-column--width-1-2{width:50%}.tna-column--width-7-12{width:58.3333333333%}.tna-column--width-2-3{width:66.6666666667%}.tna-column--width-3-4{width:75%}.tna-column--width-5-6{width:83.3333333333%}.tna-column--width-11-12{width:91.6666666667%}@media(min-width: 769px)and (max-width: 1024px){.tna-column--width-full-medium{width:100%}.tna-column--flex-1-medium{flex:1 0}.tna-column--flex-2-medium{flex:2 0}.tna-column--flex-3-medium{flex:3 0}.tna-column--width-1-6-medium{width:16.6666666667%}.tna-column--width-1-3-medium{width:33.3333333333%}.tna-column--width-1-2-medium{width:50%}.tna-column--width-2-3-medium{width:66.6666666667%}.tna-column--width-5-6-medium{width:83.3333333333%}}@media(max-width: 768px){.tna-container{padding-right:1.125rem;padding-left:1.125rem}.tna-column{padding-right:.375rem;padding-left:.375rem}}@media(min-width: 481px)and (max-width: 768px){.tna-column--width-full-small{width:100%}.tna-column--flex-1-small{flex:1 0}.tna-column--flex-2-small{flex:2 0}.tna-column--flex-3-small{flex:3 0}.tna-column--width-1-4-small{width:25%}.tna-column--width-1-2-small{width:50%}.tna-column--width-3-4-small{width:75%}}@media(max-width: 480px){.tna-column--width-full-tiny{width:100%}.tna-column--flex-1-tiny{width:auto;flex:1 0}.tna-column--flex-2-tiny{width:auto;flex:2 0}.tna-column--flex-3-tiny{width:auto;flex:3 0}.tna-column--width-1-2-tiny{width:50%}}.tna-sensitive-image__details{position:relative}.tna-sensitive-image__details::after{width:100%;padding-bottom:calc(100%*var(--sensitive-image-height)/var(--sensitive-image-width));display:block;position:relative;z-index:-1;background-image:var(--sensitive-image);background-clip:padding-box;background-size:contain;filter:blur(20px) saturate(0);content:""}.tna-sensitive-image__show{display:flex;align-items:center;justify-content:center;position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;font-size:0;cursor:pointer}.tna-sensitive-image__show::after{padding:.5rem 2rem;font-size:1rem;background-color:#ff0;content:attr(data-action)}.tna-sensitive-image__show:hover::after{color:#fff;background-color:#000}.tna-sensitive-image__image{width:100%}.tna-sensitive-image__details[open]::after,.tna-sensitive-image__details[open] .tna-sensitive-image__show{display:none}/*# sourceMappingURL=all.css.map */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sourceRoot":"","sources":["../../src/nationalarchives/utilities/_typography.scss","../../src/nationalarchives/utilities/_global.scss","../../src/nationalarchives/components/grid/_index.scss","../../src/nationalarchives/variables/_grid.scss","../../src/nationalarchives/
|
|
1
|
+
{"version":3,"sourceRoot":"","sources":["../../src/nationalarchives/utilities/_typography.scss","../../src/nationalarchives/utilities/_global.scss","../../src/nationalarchives/components/button/_index.scss","../../src/nationalarchives/components/card/_index.scss","../../src/nationalarchives/components/footer/_index.scss","../../src/nationalarchives/components/grid/_index.scss","../../src/nationalarchives/variables/_grid.scss","../../src/nationalarchives/tools/_grid.scss","../../src/nationalarchives/components/sensitive-image/_index.scss"],"names":[],"mappings":"AACQ,sHCDR,cACE,gBACA,WACA,YAEA,kBACA,gBACA,iCAEA,+BACE,gBACE,0BACA,4BAKN,oBACE,SACA,UAEA,sBAEA,cAGF,qBAIE,eAEA,cAGF,aAEE,WDlCF,cACE,mCACA,eACA,kCACA,mCACA,kCACA,8BACA,cAGF,oBACE,eACA,gBAMF,iBACE,eAGF,gBACE,eAGF,gBACE,iBAGF,gBACE,mBAUA,mCACE,eAQF,kCACE,eAQF,kCACE,iBAQF,kCACE,mBAIJ,wBACE,yBE5EA,YACE,oBAEA,qBAEA,WACA,qBAEA,sBAEA,kBACE,sBAIJ,uBACE,WAEA,sBAEA,6BACE,WCrBJ,UACE,oBACA,aACA,wBACA,0BACA,sBAGF,mBACE,QAYF,iBACE,QAGF,gBACE,QAGF,mBACE,QC3BF,YACE,iBACA,oBAEA,WAEA,yBAGF,kBACE,cAEA,wBACE,WAIJ,wBACE,oBASF,oCACE,eAEA,gBASF,oBACE,oBAGF,yBACE,kBAMF,0BACE,cAGF,wBACE,qBAEA,cACA,UAEA,8BACE,WACA,UAIJ,kCACE,cACA,cAEA,aCpEF,eACE,UCPsB,SDQtB,WACA,kBACA,iBACA,mBACA,kBAEA,sBAEA,oBACA,aACA,eACA,wBACA,oBAEA,kCACE,eAGF,yCACE,mBACA,gBACA,eAEA,qDACE,gBACA,eAKN,YACE,mBACA,kBAEA,sBAEA,6BACE,WAUF,oBACE,SADF,oBACE,SADF,oBACE,SE9CE,wBACE,oBADF,uBACE,qBADF,uBACE,UADF,uBACE,qBADF,wBACE,qBADF,uBACE,UADF,wBACE,qBADF,uBACE,qBADF,uBACE,UADF,uBACE,qBADF,yBACE,qBFyDR,gDEzBA,+BACE,WAIA,2BACE,SADF,2BACE,SADF,2BACE,SAvCE,8BACE,qBADF,8BACE,qBADF,8BACE,UADF,8BACE,qBADF,8BACE,sBF6DR,yBETA,eACE,uBACA,sBAGF,YACE,sBACA,sBFMF,+CEeA,8BACE,WAIA,0BACE,SADF,0BACE,SADF,0BACE,SAvFE,6BACE,UADF,6BACE,UADF,6BACE,WFqER,yBE+BA,6BACE,WAIA,yBACE,WAEA,SAHF,yBACE,WAEA,SAHF,yBACE,WAEA,SA7GE,4BACE,WCFR,8BACE,kBAIA,qCACE,WACA,qFAIA,cAEA,kBACA,WAEA,wCACA,4BACA,wBAEA,8BAEA,WAIJ,2BACE,aACA,mBACA,uBAEA,kBACA,MACA,QACA,SACA,OACA,UAEA,YAEA,eAEA,kCACE,mBAEA,eAEA,sBAEA,0BAIA,wCACE,WAEA,sBAQN,4BACE,WAIA,0GAEE","file":"all.css"}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { Meta } from "@storybook/blocks";
|
|
2
|
+
|
|
3
|
+
<Meta title="Development/About" />
|
|
4
|
+
|
|
5
|
+
# Project history
|
|
6
|
+
|
|
7
|
+
## Needs
|
|
8
|
+
|
|
9
|
+
TNA needed a frontend toolkit that was:
|
|
10
|
+
|
|
11
|
+
- standardised - a single source of truth for all TNA that follows all our coding standards (currently non-existent)
|
|
12
|
+
- version controlled - as well as [semantically versioned](https://semver.org/) with a [changelog](https://keepachangelog.com/en/1.0.0/)
|
|
13
|
+
- open - all source code should be [open and available to anyone](https://www.gov.uk/service-manual/service-standard/point-12-make-new-source-code-open)
|
|
14
|
+
- accessible - all components meet WCAG 2.1 AA standards
|
|
15
|
+
- progressively enhanced - all components should still be operable without JavaScript, CSS or both
|
|
16
|
+
- importable into projects (via a service such as [NPM](https://www.npmjs.com/search?q=nationalarchives)) - to make dependency management as simple as possible
|
|
17
|
+
- agnostic - the implementation for the markup of the components can be replicated in any required technology (because we have Python, PHP and Java applications throughout the organisation)
|
|
18
|
+
- testable - both from an internal perspective as well as providing scenarios and expected results for language implimentations to be able to validate against
|
|
19
|
+
- lean - minimal reliance on other languages and dependencies to ensure good extendability and speed of development and deployment
|
|
20
|
+
- automatically published - leveraging CI/CD, creating a new release version should be as simple as possible
|
|
21
|
+
|
|
22
|
+
It would have also been nice to have a toolkit that was:
|
|
23
|
+
|
|
24
|
+
- extendable - rather than providing a static snapshot of the toolkit, we should always be able to extend it for any given application
|
|
25
|
+
- documentable - not just from a technical perspective but also from a user-centred design perspective with best practices of when and how to use each component (this might be a separate project where we can [share information such as user research](https://www.gov.uk/service-manual/service-standard/point-13-use-common-standards-components-patterns))
|
|
26
|
+
- prototype-able - by using Nunjucks, we could easily create a toolkit that integrated with the [GOV.UK Prototype Kit](https://prototype-kit.service.gov.uk/docs/) which means we could very easily create high fidelity prototypes to test with, ultimately helping with user research
|
|
27
|
+
|
|
28
|
+
## Current solutions
|
|
29
|
+
|
|
30
|
+
There was already a solution in [nationalarchives/tdr-components](https://github.com/nationalarchives/tdr-components) which is specific to TDR and extends the GOV.UK components and styles. We needed to create a more generic set of components that were suitable for every TNA service, ~~while still extending the GOV.UK components and styles~~ *[Edit: this was not implemented]* but with a more TNA-branded look and feel.
|
|
31
|
+
|
|
32
|
+
We also had [nationalarchives/tna-frontend-design-toolkit](https://github.com/nationalarchives/tna-frontend-design-toolkit) which aimed to provide similar functionality but wasn't as featureful as we needed and wasn't published to NPM which means it has to be [copied into the projects that require it](https://github.com/nationalarchives/ds-wagtail/tree/develop/sass/tna-toolkit).
|
|
33
|
+
|
|
34
|
+
## Proposed solution
|
|
35
|
+
|
|
36
|
+
This repository should hold all the JavaScript and SCSS source files required for all the frontend styles along with tests and expected markup.
|
|
37
|
+
|
|
38
|
+
### Output
|
|
39
|
+
|
|
40
|
+
The source files will be compiled down to a NodeJS package and deployed to [NPM](https://www.npmjs.com/). The package will contain:
|
|
41
|
+
|
|
42
|
+
- All the JavaScript and SCSS source files which can be imported into a projects source code and compiled by the project (which will allow for tree shaking and application-specific modifications)
|
|
43
|
+
- An AMD/UMD/IIFE (TBD) ES5 JavaScript file which can be included with a normal `<script>` element
|
|
44
|
+
- A single CSS file containing all the styles which can be included with a normal `<style>` element
|
|
45
|
+
- The Nunjucks templates for each component that might be required in other projects such as prototyping tools (other implementations can be made such as [Jinja templates](https://github.com/nationalarchives/tna-frontend-jinja))
|
|
46
|
+
|
|
47
|
+
### Component resources
|
|
48
|
+
|
|
49
|
+
Each component in this repository should contain:
|
|
50
|
+
|
|
51
|
+
- Nunjucks template - only used to display the component within the examples page and aid development
|
|
52
|
+
- SCSS - which could either be imported as a standalone styles declaration or as part of the compiled output
|
|
53
|
+
- JavaScript (ESNext) - if there is any progressive enhancement required on the component
|
|
54
|
+
- Options/properties - a list of the configurable properties of the component and their types
|
|
55
|
+
- Test scenarios - a variety of configurations and their expected outputs that can be used by either this repository or other implementations of the components (e.g. Jinja)
|
|
56
|
+
|
|
57
|
+
### Technologies
|
|
58
|
+
|
|
59
|
+
- SCSS (used by GDS, is the de facto standard CSS preprocessor, already using in ETNA)
|
|
60
|
+
- Webpack - compilation of JavaScript and CSS (used by numerous TNA projects already)
|
|
61
|
+
- Babel - will allow us to use ESNext or possibly even TypeScript (although this could go against the lean requirement)
|
|
62
|
+
- Storybook - allow viewing and testing of components (we have already used this elsewhere in TNA)
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { Meta } from "@storybook/blocks";
|
|
2
|
+
|
|
3
|
+
<Meta title="Development/Publishing" />
|
|
4
|
+
|
|
5
|
+
# Publishing a new version
|
|
6
|
+
|
|
7
|
+
1. Update `version` in `package.json` using [SemVer](https://semver.org/)
|
|
8
|
+
1. Update the CHANGELOG
|
|
9
|
+
1. Run `nvm use` to ensure the correct Node version is used
|
|
10
|
+
1. Run `npm install` to update the `package-lock.json`
|
|
11
|
+
1. Merge all changes to `main` via a pull request
|
|
12
|
+
1. Tag the version with `git tag v1.0.0` (ensure leading `v` and change version number as necessary)
|
|
13
|
+
1. Push the new tag with `git push origin --tags`
|
|
14
|
+
1. Create a [new release on GitHub](https://github.com/nationalarchives/tna-frontend/releases/new) using the tag you just created
|
|
15
|
+
|
|
16
|
+
Once a release is created, the [publish pipeline](https://github.com/nationalarchives/tna-frontend/blob/main/.github/workflows/npm-publish.yml) will be triggered.
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Relationship to other resources
|
|
2
|
+
|
|
3
|
+
## System context
|
|
4
|
+
|
|
5
|
+
```mermaid
|
|
6
|
+
C4Context
|
|
7
|
+
Person(dev, "Developer", "TNA developer")
|
|
8
|
+
System_Ext(github, "GitHub", "Repositories for source files")
|
|
9
|
+
System_Ext(npm, "NPMJS", "Hosts NodeJS packages")
|
|
10
|
+
System_Ext(pypi, "PyPi", "Hosts Python packages")
|
|
11
|
+
Container(app, "Application", "Example application")
|
|
12
|
+
System_Ext(pypi, "PyPi", "Hosts Python packages")
|
|
13
|
+
|
|
14
|
+
Rel(dev, github, "commits to", "git")
|
|
15
|
+
UpdateRelStyle(dev, github, $offsetX="-30", $offsetY="-30")
|
|
16
|
+
Rel(github, npm, "publishes to", "npm")
|
|
17
|
+
Rel(github, pypi, "publishes to", "pip")
|
|
18
|
+
Rel(app, npm, "consumes", "npm")
|
|
19
|
+
Rel(app, pypi, "consumes", "pip")
|
|
20
|
+
|
|
21
|
+
UpdateLayoutConfig($c4ShapeInRow="2")
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Component diagram
|
|
25
|
+
|
|
26
|
+
```mermaid
|
|
27
|
+
C4Context
|
|
28
|
+
Person(dev, "Developer", "TNA developer")
|
|
29
|
+
|
|
30
|
+
%% Boundary(developer_machine, "Developer machine", "boundary") {
|
|
31
|
+
%% System(docker, "Docker")
|
|
32
|
+
%% }
|
|
33
|
+
|
|
34
|
+
Boundary(github, "GitHub", "boundary") {
|
|
35
|
+
Boundary(github_jinja, "Jinja templates", "repository") {
|
|
36
|
+
Container(github_jinja_source, "Jinja templates")
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
Boundary(github_frontend, "Frontend styles", "repository") {
|
|
40
|
+
Container(github_frontend_source, "Frontend styles", "git repository")
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
Boundary(github_application, "Application", "repository") {
|
|
44
|
+
Container(github_application_source, "Application source code")
|
|
45
|
+
Component(github_application_image, "Application docker image", "GitHub image registry")
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
Boundary(npm, "NPMJS", "boundary") {
|
|
50
|
+
Component(npm_package, "Frontend styles")
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
Enterprise_Boundary(aws, "TNA AWS", "boundary") {
|
|
54
|
+
Container(app, "Application")
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
Boundary(pypi, "PyPi", "boundary") {
|
|
58
|
+
Component(pypi_package, "Jinja templates")
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
Rel(dev, github_frontend_source, "commits to")
|
|
62
|
+
UpdateRelStyle(dev, github_frontend_source, $offsetX="-80", $offsetY="-80")
|
|
63
|
+
Rel(github_frontend_source, npm_package, "publishes", "GitHub action")
|
|
64
|
+
UpdateRelStyle(github_frontend_source, npm_package, $offsetX="-40", $offsetY="-40")
|
|
65
|
+
|
|
66
|
+
Rel(dev, github_jinja_source, "commits to")
|
|
67
|
+
UpdateRelStyle(dev, github_jinja_source, $offsetX="-15", $offsetY="-80")
|
|
68
|
+
Rel(github_jinja_source, github_frontend_source, "consumes")
|
|
69
|
+
UpdateRelStyle(github_jinja_source, github_frontend_source, $offsetX="-40", $offsetY="-15")
|
|
70
|
+
Rel(github_jinja_source, pypi_package, "publishes", "GitHub action")
|
|
71
|
+
UpdateRelStyle(github_jinja_source, pypi_package, $offsetX="-110", $offsetY="-310")
|
|
72
|
+
|
|
73
|
+
Rel(dev, github_application_source, "commits to")
|
|
74
|
+
UpdateRelStyle(dev, github_application_source, $offsetX="-105", $offsetY="-250")
|
|
75
|
+
Rel(github_application_source, github_application_image, "creates", "GitHub action")
|
|
76
|
+
UpdateRelStyle(github_application_source, github_application_image, $offsetX="-90", $offsetY="-20")
|
|
77
|
+
|
|
78
|
+
Rel(github_application_image, npm_package, "consumes", "GitHub action")
|
|
79
|
+
UpdateRelStyle(github_application_image, npm_package, $offsetX="-50", $offsetY="-10")
|
|
80
|
+
Rel(github_application_image, pypi_package, "consumes", "GitHub action")
|
|
81
|
+
UpdateRelStyle(github_application_image, pypi_package, $offsetX="-120", $offsetY="-10")
|
|
82
|
+
|
|
83
|
+
%% Rel(dev, docker, "uses")
|
|
84
|
+
%% Rel(docker, npm_package, "consumes")
|
|
85
|
+
%% Rel(docker, pypi_package, "consumes")
|
|
86
|
+
|
|
87
|
+
Rel(app, github_application_image, "consumes")
|
|
88
|
+
UpdateRelStyle(app, github_application_image, $offsetX="-70", $offsetY="-10")
|
|
89
|
+
|
|
90
|
+
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")
|
|
91
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nationalarchives/frontend",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5-prerelease",
|
|
4
4
|
"description": "The National Archives frontend styles",
|
|
5
5
|
"scripts": {
|
|
6
6
|
"start": "storybook dev -p 6006",
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"lint": "prettier --check '{src,.storybook,tasks}/**/*.{js,mjs,scss,json}'",
|
|
9
9
|
"test": "node tasks/test-fixtures.js",
|
|
10
10
|
"prettier": "prettier --write '{src,.storybook,tasks}/**/*.{js,mjs,scss,json}'",
|
|
11
|
-
"package:sass": "sass --style=compressed --quiet-deps
|
|
11
|
+
"package:sass": "sass --style=compressed --quiet-deps src/nationalarchives/all.scss package/nationalarchives/all.css",
|
|
12
12
|
"package:scripts": "webpack"
|
|
13
13
|
},
|
|
14
14
|
"repository": {
|
|
File without changes
|