@abgov-uiam/shell 0.0.0-stage → 0.1.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.
- package/CHANGELOG.md +18 -0
- package/LICENSE +21 -0
- package/README.md +356 -2
- package/dist/index.cjs.js +337 -0
- package/dist/index.esm.js +333 -0
- package/dist/styles/shell.css +124 -0
- package/dist/types/components/AppLayout.d.ts +18 -0
- package/dist/types/components/Footer.d.ts +6 -0
- package/dist/types/components/Header.d.ts +15 -0
- package/dist/types/components/ShellAnchor.d.ts +11 -0
- package/dist/types/components/SideMenu.d.ts +17 -0
- package/dist/types/components/UserDetails.d.ts +14 -0
- package/dist/types/index.d.ts +5 -0
- package/dist/types/types.d.ts +130 -0
- package/dist/types/utils/paths.d.ts +38 -0
- package/dist/types/utils/useMediaQuery.d.ts +5 -0
- package/package.json +80 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@abgov-uiam/shell` are documented here. The package follows
|
|
4
|
+
[semantic versioning](https://semver.org/). To release, bump `version` in `package.json` and add an entry here in the
|
|
5
|
+
same pull request (see the README's "Versioning and publishing").
|
|
6
|
+
|
|
7
|
+
## 0.1.0
|
|
8
|
+
|
|
9
|
+
First release (IAM-11266). Published as `@abgov-uiam/shell` (IAM-11711), staged to npm by GitHub Actions
|
|
10
|
+
through trusted publishing.
|
|
11
|
+
|
|
12
|
+
- `AppLayout`: the Alberta.ca Account page layout on Design System 2.0 (`@abgov/react-components` 8), a stateless,
|
|
13
|
+
props-driven component that draws the header, side menu and footer around the page. The header, side menu and
|
|
14
|
+
footer aren't exported on their own, and only the page prints.
|
|
15
|
+
- `ShellProps` contract mirroring the data API's `UserMenu` response (`top` and `left`), with the optional
|
|
16
|
+
IAM-11267 fields (`external`, `isSectionHeader`, `itemKey`, `activePathPrefix`, `staffAccountOrgHref`).
|
|
17
|
+
- `DEFAULT_FOOTER_LINKS` and the `toRouterPath` helper.
|
|
18
|
+
- Stylesheet at `@abgov-uiam/shell/styles/shell.css`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 GovAlta-EMU
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,357 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @abgov-uiam/shell
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Alberta.ca Account page layout, built on the Government of Alberta Design System 2.0 as a stateless,
|
|
4
|
+
props-driven React component: `AppLayout` draws the header, side menu and footer around your page. Alberta.ca Account,
|
|
5
|
+
sign-in and partner apps render the same shell from one source: the UIAM data API's `UserMenu` response.
|
|
6
|
+
|
|
7
|
+
- [Install](#install)
|
|
8
|
+
- [Usage](#usage)
|
|
9
|
+
- [AppLayout](#applayout)
|
|
10
|
+
- [toRouterPath](#torouterpathhref-basepath)
|
|
11
|
+
- [The props contract](#the-props-contract)
|
|
12
|
+
- [Contract fixtures](#contract-fixtures)
|
|
13
|
+
- [Versioning and publishing](#versioning-and-publishing)
|
|
14
|
+
- [Development](#development)
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @abgov-uiam/shell
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### Peer dependencies
|
|
23
|
+
|
|
24
|
+
| Package | Version |
|
|
25
|
+
| ------------------------- | ---------------------------- |
|
|
26
|
+
| `react`, `react-dom` | `^18.0.0 \|\| ^19.0.0` |
|
|
27
|
+
| `@abgov/react-components` | `^8.0.0` (Design System 2.0) |
|
|
28
|
+
|
|
29
|
+
The shell renders Design System 2.0 components, so your app must be set up for Design System 2.0 as in the
|
|
30
|
+
[developer setup guide](https://design.alberta.ca/get-started/developers/setup/): `@abgov/web-components` 3.x
|
|
31
|
+
registered once, its stylesheet loaded, and the Ionicons script in `index.html`. Then load the shell's stylesheet
|
|
32
|
+
after the Design System's:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import '@abgov/web-components';
|
|
36
|
+
import '@abgov-uiam/shell/styles/shell.css';
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
> Design System 1.0 and 2.0 can't share a page: both register the same `goa-*` elements. Only use the shell in pages
|
|
40
|
+
> that load Design System 2.0. In this repository that means the DS 2.0 build only (`VITE_DS_VERSION=2`, see
|
|
41
|
+
> `docs/design-system-2-exit.md`): there, `config/design-system-variant.ts` swaps each app's
|
|
42
|
+
> `src/components/Menu/AppLayout.tsx` for its `ShellAppLayout.tsx`, which renders this package.
|
|
43
|
+
|
|
44
|
+
## Usage
|
|
45
|
+
|
|
46
|
+
Fetch the menu yourself (`POST account/user-menu` on the data API), then render your pages inside `AppLayout`. The
|
|
47
|
+
shell does no fetching, routing or state management of its own.
|
|
48
|
+
|
|
49
|
+
```tsx
|
|
50
|
+
import { AppLayout, toRouterPath, type UserMenu } from '@abgov-uiam/shell';
|
|
51
|
+
import { Link, useLocation } from 'react-router';
|
|
52
|
+
|
|
53
|
+
const BASENAME = '/ui/account';
|
|
54
|
+
|
|
55
|
+
export const Layout = ({ userMenu, children }: { userMenu: UserMenu; children: React.ReactNode }) => {
|
|
56
|
+
const { pathname } = useLocation();
|
|
57
|
+
|
|
58
|
+
return (
|
|
59
|
+
<AppLayout
|
|
60
|
+
appName="Alberta.ca Account"
|
|
61
|
+
appUrl="https://account.alberta.ca/ui/account"
|
|
62
|
+
user={{ name: 'Jane Doe', email: 'jane.doe@example.com' }}
|
|
63
|
+
menu={userMenu}
|
|
64
|
+
currentPath={pathname}
|
|
65
|
+
renderLink={({ href, ...rest }) => <Link to={toRouterPath(href, BASENAME)} {...rest} />}
|
|
66
|
+
onSignOut={() => signOut()}>
|
|
67
|
+
<div className="page">{children}</div>
|
|
68
|
+
</AppLayout>
|
|
69
|
+
);
|
|
70
|
+
};
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`AppLayout` adds no padding around the page, so give your page container its own margins and maximum width.
|
|
74
|
+
|
|
75
|
+
`user` and `menu` can arrive after the first render, for example once your app has fetched the account: render
|
|
76
|
+
`AppLayout` straight away and pass them in when you have them.
|
|
77
|
+
|
|
78
|
+
## AppLayout
|
|
79
|
+
|
|
80
|
+
A Design System one-column layout with:
|
|
81
|
+
|
|
82
|
+
- **the header** in the header slot, after `banner` when there is one;
|
|
83
|
+
- **the side menu** beside the page on wide viewports, when `menu.left` has entries. On narrow viewports (up to
|
|
84
|
+
`mobileBreakpoint`) it moves into the header's drawer and the page takes the full width. The page keeps its place
|
|
85
|
+
either way, so crossing the breakpoint never remounts it;
|
|
86
|
+
- **the page** (`children`), inside the layout's own main landmark, so don't wrap it in another `<main>`;
|
|
87
|
+
- **the footer** in the footer slot.
|
|
88
|
+
|
|
89
|
+
It takes [`ShellProps`](#shellprops), plus:
|
|
90
|
+
|
|
91
|
+
| Prop | Type | Default | Description |
|
|
92
|
+
| ------------------ | ----------- | ------- | --------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `children` | `ReactNode` | | The page. |
|
|
94
|
+
| `banner` | `ReactNode` | | Shown above the app header, such as the Design System microsite header of an alpha or beta service. |
|
|
95
|
+
| `mobileBreakpoint` | `number` | `1024` | The widest viewport, in pixels, that gets the mobile layout. |
|
|
96
|
+
|
|
97
|
+
### Header
|
|
98
|
+
|
|
99
|
+
The Design System app header.
|
|
100
|
+
|
|
101
|
+
- **Wide viewports:** the user menu (name shortened to 18 characters; user details, organization, `userLinks` and
|
|
102
|
+
"Sign out") and, for organization admins with pending staff account requests, a notification link with the count.
|
|
103
|
+
- **Narrow viewports:** a "Menu" button that opens a drawer with the user details, the staff account requests link,
|
|
104
|
+
`userLinks`, the side menu and "Sign out".
|
|
105
|
+
|
|
106
|
+
Internal UI state: whether the drawer is open, and the viewport width (`matchMedia`). The drawer closes when
|
|
107
|
+
`currentPath` changes, when a link in it is chosen, and when the viewport grows past the breakpoint. The Design System
|
|
108
|
+
header only reads what's in its utilities area (the user menu, the notification or the Menu button) when it first
|
|
109
|
+
appears on the page, so the shell creates it afresh whenever that changes.
|
|
110
|
+
|
|
111
|
+
### Side menu
|
|
112
|
+
|
|
113
|
+
The Design System side menu, from `menu.left`. Links render as `<a>` (or through `renderLink`), groups as side menu
|
|
114
|
+
groups, and nested groups (such as one per organization) as nested side menu groups. A group lists ten nested
|
|
115
|
+
groups, then a "Show N more" button.
|
|
116
|
+
|
|
117
|
+
The link matching `currentPath` gets `aria-current="page"` and the `current` class. Matching follows the legacy side
|
|
118
|
+
menu: either side may include the app's base path, so `currentPath` can be a router path (`/personal`) or the full
|
|
119
|
+
pathname (`/ui/account/personal`), and hrefs and `activePathPrefix` can be absolute URLs or paths.
|
|
120
|
+
|
|
121
|
+
Internal UI state: which groups are open, and whether a long list shows all its nested groups. Design System side
|
|
122
|
+
menu groups open and close themselves, and open on their own when they hold the current page's link. When the page
|
|
123
|
+
changes to one inside a nested group that the list hides (one of its links or a page below one, or a page at or below
|
|
124
|
+
its `activePathPrefix`), the list shows all its nested groups. "Show less" collapses it again until the next page
|
|
125
|
+
change.
|
|
126
|
+
|
|
127
|
+
### Footer
|
|
128
|
+
|
|
129
|
+
The Design System app footer, with `footerLinks` (default `DEFAULT_FOOTER_LINKS`, the Alberta.ca Account footer) in
|
|
130
|
+
its meta section. To add a link to the defaults, pass `[...DEFAULT_FOOTER_LINKS, link]`.
|
|
131
|
+
|
|
132
|
+
### Styling
|
|
133
|
+
|
|
134
|
+
Load `@abgov-uiam/shell/styles/shell.css` once, after the Design System's stylesheet. For your own page styles:
|
|
135
|
+
|
|
136
|
+
- the layout's root has the class `uiam-shell-layout`, plus `uiam-shell-layout--side-menu` while the side menu is
|
|
137
|
+
beside the page;
|
|
138
|
+
- `--uiam-shell-side-menu-width` (set on `.uiam-shell-layout`, `18rem` by default) is the side menu column's width,
|
|
139
|
+
for example to size full-bleed content.
|
|
140
|
+
|
|
141
|
+
When printing, only the page prints. The stylesheet hides the header (with the banner and the mobile drawer), the
|
|
142
|
+
side menu column and the footer: `uiam-shell-layout-header`, `uiam-shell-layout-side-menu` and
|
|
143
|
+
`uiam-shell-layout-footer`. To print one of them anyway, set its `display` in an `@media print` rule of your own,
|
|
144
|
+
loaded after the shell's stylesheet.
|
|
145
|
+
|
|
146
|
+
## `toRouterPath(href, basePath?)`
|
|
147
|
+
|
|
148
|
+
Turns an href into a destination for your router's link, for `renderLink`:
|
|
149
|
+
|
|
150
|
+
- a path is returned as-is;
|
|
151
|
+
- an absolute URL on the page's origin inside `basePath` (your router's basename) becomes the path below it, keeping
|
|
152
|
+
its query and hash;
|
|
153
|
+
- anything else is returned unchanged. That includes other apps on the same origin, such as the organization directory
|
|
154
|
+
the data API links staff account requests to. React Router's `<Link>` loads an absolute URL outside its basename as
|
|
155
|
+
a full page.
|
|
156
|
+
|
|
157
|
+
## The props contract
|
|
158
|
+
|
|
159
|
+
`ShellProps` and its sub-types are exported for TypeScript users.
|
|
160
|
+
|
|
161
|
+
### `ShellProps`
|
|
162
|
+
|
|
163
|
+
| Prop | Type | Description |
|
|
164
|
+
| ----------------- | ------------------- | -------------------------------------------------------------------------------- |
|
|
165
|
+
| `appName` | `string` | Service name in the header. |
|
|
166
|
+
| `appUrl` | `string` | Full URL the Alberta.ca logo links to. |
|
|
167
|
+
| `user` | `ShellUser \| null` | `{ name, email }` of who is signed in. Leave it out on signed-out pages. |
|
|
168
|
+
| `menu` | `UserMenu \| null` | The data API's `UserMenu` response. |
|
|
169
|
+
| `currentPath` | `string` | The current page's path, for the active side menu link. Default `'/'`. |
|
|
170
|
+
| `userLinks` | `ShellLink[]` | Extra user menu links, such as "My account" in the sign-in app. |
|
|
171
|
+
| `footerLinks` | `ShellLink[]` | Footer links. Default `DEFAULT_FOOTER_LINKS`. |
|
|
172
|
+
| `renderLink` | `RenderShellLink` | Renders same-origin, non-external links (client-side navigation). Default `<a>`. |
|
|
173
|
+
| `onSignOut` | `() => void` | Called on "Sign out". Without it there is no sign-out link. |
|
|
174
|
+
| `maxContentWidth` | `string` | Maximum content width of the header and footer. Default `'100%'`. |
|
|
175
|
+
|
|
176
|
+
`user` isn't part of the data API response: the account app derives it from `accountBasic`.
|
|
177
|
+
|
|
178
|
+
### `UserMenu`, `TopMenu` and `UserMenuItem`
|
|
179
|
+
|
|
180
|
+
These mirror the data API's `UserMenu` (`uiam-data-api/.../ViewModels/UserMenu.cs`) exactly as the API serializes it:
|
|
181
|
+
camelCase keys, with `null` for values that aren't set. Pass the response's `data` straight in.
|
|
182
|
+
|
|
183
|
+
| Type | Field | Type | Notes |
|
|
184
|
+
| -------------- | --------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
185
|
+
| `UserMenu` | `top` | `TopMenu \| null` | `null` unless signed in as a staff account. |
|
|
186
|
+
| | `left` | `UserMenuItem[]` | The side menu, in order. |
|
|
187
|
+
| `TopMenu` | `staffAccountOrgName` | `string \| null` | Organization the user signed in as. |
|
|
188
|
+
| | `staffAccountOrgHref` | `string \| null` | IAM-11267. Links the organization name. |
|
|
189
|
+
| | `staffAccountApprovalHref` | `string \| null` | Where admins review staff account requests. |
|
|
190
|
+
| | `staffAccountApprovalCount` | `number` | Pending requests. The notification shows when it is above 0 and there's an href. |
|
|
191
|
+
| `UserMenuItem` | `type` | `'group' \| 'link'` | Links have an `href`, groups have `items`. |
|
|
192
|
+
| | `heading` | `string` | The label. |
|
|
193
|
+
| | `href` | `string \| null` | Absolute URL or path. |
|
|
194
|
+
| | `icon` | `string \| null` | Design System icon name. |
|
|
195
|
+
| | `items` | `UserMenuItem[] \| null` | A group's entries: links and nested groups. |
|
|
196
|
+
| | `external` | `boolean \| null` | IAM-11267. Another app's link: always a full page load. |
|
|
197
|
+
| | `isSectionHeader` | `boolean \| null` | IAM-11267. A heading link, such as "Business overview". |
|
|
198
|
+
| | `itemKey` | `string \| null` | IAM-11267. Stable key and group test id. |
|
|
199
|
+
| | `activePathPrefix` | `string \| null` | IAM-11267. Where a group's pages sit, such as an organization's `/business/ORG01`. Pages at or below it count as the group's. |
|
|
200
|
+
|
|
201
|
+
Fields marked IAM-11267 are optional additions the data API needs to describe the account app's menu. Responses
|
|
202
|
+
without them still match the contract.
|
|
203
|
+
|
|
204
|
+
Organizations are nested groups inside the Business group, each with its `activePathPrefix`, so a page under an
|
|
205
|
+
organization that the group doesn't link to (its overview, or verification pages) still counts as the organization's.
|
|
206
|
+
With one organization, the account app lists the organization's name as a section heading link followed by its links
|
|
207
|
+
instead:
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
{
|
|
211
|
+
"type": "group",
|
|
212
|
+
"heading": "Business",
|
|
213
|
+
"icon": "briefcase",
|
|
214
|
+
"itemKey": "business-section",
|
|
215
|
+
"items": [
|
|
216
|
+
{
|
|
217
|
+
"type": "link",
|
|
218
|
+
"heading": "Business overview",
|
|
219
|
+
"href": "https://account.alberta.ca/ui/account/business",
|
|
220
|
+
"isSectionHeader": true
|
|
221
|
+
},
|
|
222
|
+
{
|
|
223
|
+
"type": "group",
|
|
224
|
+
"heading": "Northwind Traders",
|
|
225
|
+
"itemKey": "ORG01",
|
|
226
|
+
"activePathPrefix": "https://account.alberta.ca/ui/account/business/ORG01",
|
|
227
|
+
"items": [
|
|
228
|
+
{
|
|
229
|
+
"type": "link",
|
|
230
|
+
"heading": "Organization details",
|
|
231
|
+
"href": "https://account.alberta.ca/ui/account/business/ORG01/details"
|
|
232
|
+
},
|
|
233
|
+
{
|
|
234
|
+
"type": "link",
|
|
235
|
+
"heading": "Staff list",
|
|
236
|
+
"href": "https://account.alberta.ca/ui/account/business/ORG01/staff"
|
|
237
|
+
}
|
|
238
|
+
]
|
|
239
|
+
}
|
|
240
|
+
]
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Links
|
|
245
|
+
|
|
246
|
+
| Link | Renders as |
|
|
247
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
248
|
+
| `external: true` | A plain `<a>` (full page load). A bare path gets the page's origin, so a `<base>` element can't redirect it. |
|
|
249
|
+
| Same origin (a path, or the page's origin) | `renderLink(props)` when given, otherwise a plain `<a>`. |
|
|
250
|
+
| Another origin | A plain `<a>`. |
|
|
251
|
+
|
|
252
|
+
`renderLink` receives `ShellLinkRenderProps` (`href`, `children`, `className`, `aria-current`, `aria-label`,
|
|
253
|
+
`data-testid`, `onClick`) and must return a single `<a>` element, such as React Router's `<Link>`: the Design System
|
|
254
|
+
menus only style and track links that are their direct `<a>` children. Same-origin links include other apps on the
|
|
255
|
+
origin, so map `href` with `toRouterPath` (as in the usage example) rather than stripping the origin yourself.
|
|
256
|
+
|
|
257
|
+
### Test ids
|
|
258
|
+
|
|
259
|
+
The shell keeps the legacy test ids where there is an equivalent: side menu links (`personalinformationlink`,
|
|
260
|
+
`stafflistlink`, …), groups (`itemKey`, or the heading), `uiam-desktop-headermenu`, `uiam-desktop-signout-link`,
|
|
261
|
+
`uiam-mobile-signout-link`, `collapsible-entity-list-toggle` and the `footer-*` links. New ones: `uiam-shell-layout`,
|
|
262
|
+
`uiam-shell-content` (around the page), `uiam-shell-header`, `uiam-shell-user-details`, `uiam-shell-user-org`,
|
|
263
|
+
`uiam-shell-notification`, `uiam-shell-staff-requests`, `uiam-shell-menu-button`, `uiam-shell-drawer`,
|
|
264
|
+
`uiam-shell-drawer-side-menu`, `uiam-shell-side-menu` and `uiam-shell-footer`.
|
|
265
|
+
|
|
266
|
+
### Rendering is pure
|
|
267
|
+
|
|
268
|
+
The same props always render the same output. Rendering makes no network requests, and the package has no
|
|
269
|
+
dependency on `@abgov-uiam/shared`, a router or Redux (`src/package-boundary.test.ts` enforces this).
|
|
270
|
+
|
|
271
|
+
## Contract fixtures
|
|
272
|
+
|
|
273
|
+
`src/__fixtures__` holds one `ShellProps` per account type: personal, business (one organization), multi-organization
|
|
274
|
+
admin, admin, and shell account. Each is declared with `satisfies ShellProps`, and `npm run typecheck`, part of
|
|
275
|
+
`npm run build`, compiles them, so a fixture that doesn't match the contract fails the build in CI.
|
|
276
|
+
`src/contract.typetest.ts` checks the opposite: shapes the contract must reject.
|
|
277
|
+
|
|
278
|
+
`src/fixtures.test.tsx` renders each fixture and checks it against the legacy account app's side menu, active item
|
|
279
|
+
and header organization block.
|
|
280
|
+
|
|
281
|
+
To add a data API response as a fixture, paste its JSON `data` into a `.ts` fixture as `menu`, keeping
|
|
282
|
+
`satisfies ShellProps`. JSON imports can't be checked directly, because TypeScript widens their `"type"` values to
|
|
283
|
+
`string`.
|
|
284
|
+
|
|
285
|
+
## Versioning and publishing
|
|
286
|
+
|
|
287
|
+
The package follows [semantic versioning](https://semver.org/):
|
|
288
|
+
|
|
289
|
+
- **Patch:** fixes that don't change the props or the intended look.
|
|
290
|
+
- **Minor:** new optional props or contract fields, and design changes.
|
|
291
|
+
- **Major:** removed or changed props or contract fields, or a new Design System major version.
|
|
292
|
+
|
|
293
|
+
Until 1.0.0 (after designer sign-off and adoption in the account and sign-in apps, IAM-11268), minor versions may
|
|
294
|
+
include breaking changes.
|
|
295
|
+
|
|
296
|
+
To release, bump `version` in `packages/shell/package.json` and add an entry to `CHANGELOG.md` in the same pull
|
|
297
|
+
request. Pull requests that touch the package build it, run its tests and dry-run `npm pack`. When the pull request
|
|
298
|
+
merges to `main`, `.github/workflows/publish-shell.yml` stages `@abgov-uiam/shell@<version>` on npm if that
|
|
299
|
+
version isn't there yet. A maintainer then approves the staged version with 2FA, either in the "Staged Packages" tab
|
|
300
|
+
on npmjs.com or with `npm stage approve <id>`; only then does it go live. Only `main` stages: running the workflow by
|
|
301
|
+
hand on another branch does nothing, because a version published to npm can't be replaced. Prerelease versions such
|
|
302
|
+
as `0.2.0-beta.1` are published under the `next` dist-tag.
|
|
303
|
+
|
|
304
|
+
The workflow uses npm trusted publishing (OIDC), so there is no npm token or repository secret. It needs a trusted
|
|
305
|
+
publisher configured for this package on npmjs.com (organization `GovAlta-EMU`, repository `alberta-ca-account`,
|
|
306
|
+
workflow `publish-shell.yml`). The first version of a package can't be staged and is published by hand.
|
|
307
|
+
|
|
308
|
+
## Development
|
|
309
|
+
|
|
310
|
+
From the repository root:
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
npm run build:shell # type-check (fixtures included), then bundle to dist/
|
|
314
|
+
npm run test -w @abgov-uiam/shell # unit, fixture and package boundary tests
|
|
315
|
+
npm run typecheck -w @abgov-uiam/shell # type-check only
|
|
316
|
+
npm run dev:shell # the playground, at http://localhost:5180
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
The package builds and tests against Design System 2.0 from its own devDependencies, pinned to the versions behind
|
|
320
|
+
the repository's `-v2` aliases (`@abgov/react-components` 8.0.0, `@abgov/web-components` and
|
|
321
|
+
`@abgov/ui-components-common` 3.0.0). The Design System 1.0 packages the apps still use stay at the repository root;
|
|
322
|
+
`src/package-boundary.test.ts` fails if the shell ever resolves those instead. Bump these pins together with the
|
|
323
|
+
aliases.
|
|
324
|
+
|
|
325
|
+
To see the shell in the apps, run their Design System 2.0 dev servers: `npm run dev:account:ds2` or
|
|
326
|
+
`npm run dev:signin:ds2`.
|
|
327
|
+
|
|
328
|
+
### Playground
|
|
329
|
+
|
|
330
|
+
`npm run dev:shell` serves [playground/](playground/), a Design System 2.0 page that renders `AppLayout` from source
|
|
331
|
+
with the contract fixtures. Use it to try changes and for the design review:
|
|
332
|
+
|
|
333
|
+
- **Account:** switch between the personal, business, multi-organization admin, admin, shell account and signed-out
|
|
334
|
+
fixtures.
|
|
335
|
+
- **Navigation:** links within the account app navigate inside the playground, so the URL, the active link and the
|
|
336
|
+
Design System's own highlighting change as they would in the app. Links that would load another page (other apps,
|
|
337
|
+
alberta.ca) are listed under Events instead of followed, as is "Sign out".
|
|
338
|
+
- **Current page:** type a path, such as `/business/ORG11/staff/5` with the multi-organization fixture, to see how the
|
|
339
|
+
side menu handles it.
|
|
340
|
+
- **Mobile:** at 1024px wide or less the header switches to its mobile layout. Narrow the window, or use your
|
|
341
|
+
browser's device toolbar, then choose Menu.
|
|
342
|
+
|
|
343
|
+
Source edits reload in place. The playground isn't part of the published package.
|
|
344
|
+
|
|
345
|
+
### In another app
|
|
346
|
+
|
|
347
|
+
To try the built package in another Design System 2.0 app before it's published, pack it and install the tarball.
|
|
348
|
+
`npm pack` builds the package first (its `prepack` script).
|
|
349
|
+
|
|
350
|
+
```bash
|
|
351
|
+
npm pack -w @abgov-uiam/shell --pack-destination <folder outside the repository>
|
|
352
|
+
# then, in the other app:
|
|
353
|
+
npm install <folder>/abgov-uiam-shell-<version>.tgz
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
Prefer this to `npm link`: a linked package resolves React and the Design System from this repository, so the app
|
|
357
|
+
would end up with two copies of each.
|