@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 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
- # Temporary Holding Version
1
+ # @abgov-uiam/shell
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.