@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.
@@ -0,0 +1,130 @@
1
+ /**
2
+ * The `@abgov-uiam/shell` prop contract.
3
+ *
4
+ * `UserMenu`, `TopMenu` and `UserMenuItem` mirror the UIAM data API's `UserMenu` response
5
+ * (`uiam-data-api/UiamDataApi/Features/Users/Queries/ViewModels/UserMenu.cs`) exactly as the API
6
+ * serializes it: camelCase keys, and `null` for values that are not set. The `data` of
7
+ * `POST account/user-menu` can be passed straight in as `ShellProps.menu`.
8
+ *
9
+ * Fields marked "IAM-11267" are additive and optional. They are what the data API needs to add to
10
+ * describe the account app's side menu (organizations, cross-app links, section headings), so
11
+ * responses from today's API still match the contract.
12
+ */
13
+ import type { MouseEvent, ReactNode } from 'react';
14
+ /** The data API derives the type from `href`: links have one, groups don't. */
15
+ export type UserMenuItemType = 'group' | 'link';
16
+ /** One side menu entry (`UserMenuItem` in the data API). */
17
+ export interface UserMenuItem {
18
+ /** `link` for a navigation link, `group` for a collapsible section of `items`. */
19
+ type: UserMenuItemType;
20
+ /** The visible label. */
21
+ heading: string;
22
+ /** Where a link goes: an absolute URL or a path. `null` for groups. */
23
+ href?: string | null;
24
+ /** A Design System icon name, such as `person` or `briefcase`. */
25
+ icon?: string | null;
26
+ /** A group's entries, in display order: links, and nested groups such as one per organization. */
27
+ items?: readonly UserMenuItem[] | null;
28
+ /**
29
+ * IAM-11267: the link belongs to another app (such as the wallet or the privacy portal), so it is
30
+ * always a full page load, never `renderLink`.
31
+ */
32
+ external?: boolean | null;
33
+ /** IAM-11267: the link is a heading for the entries that follow, such as "Business overview". */
34
+ isSectionHeader?: boolean | null;
35
+ /** IAM-11267: a stable key and test id, for entries whose heading isn't unique (such as an organization code). */
36
+ itemKey?: string | null;
37
+ /**
38
+ * IAM-11267: for a group, the path or URL its pages sit under, such as an organization's
39
+ * `https://account.alberta.ca/ui/account/business/ORG01`. Pages at or below it count as the group's, even
40
+ * when none of its links is the current page, so a long list shows the group rather than hiding it.
41
+ */
42
+ activePathPrefix?: string | null;
43
+ }
44
+ /** Data for the header's user menu (`TopMenu` in the data API). */
45
+ export interface TopMenu {
46
+ /** Name of the organization the user signed in as. */
47
+ staffAccountOrgName?: string | null;
48
+ /** IAM-11267: where the organization name links to. Without it the name is plain text. */
49
+ staffAccountOrgHref?: string | null;
50
+ /**
51
+ * Where an organization admin reviews pending staff account requests. `null` for everyone else. The data API
52
+ * links to the organization directory: same origin, but another app, which `toRouterPath` leaves as a full page load.
53
+ */
54
+ staffAccountApprovalHref?: string | null;
55
+ /** How many staff account requests are pending. `0` when there are none, or the user isn't an admin. */
56
+ staffAccountApprovalCount: number;
57
+ }
58
+ /** The data API's `UserMenu` response. */
59
+ export interface UserMenu {
60
+ /** Header data. `null` unless the user signed in as a staff account. */
61
+ top?: TopMenu | null;
62
+ /** The side menu, in display order. */
63
+ left: readonly UserMenuItem[];
64
+ }
65
+ /**
66
+ * Who is signed in. Not part of the data API response: the account app derives it from `accountBasic`
67
+ * (`getDisplayNameFromAccount` and `Email`).
68
+ */
69
+ export interface ShellUser {
70
+ /** Display name. Shortened to 18 characters on the header's user menu button. */
71
+ name: string;
72
+ /** Email address. Shown in lowercase. */
73
+ email?: string | null;
74
+ }
75
+ /** A plain link, used for the user menu's extra links and the footer. */
76
+ export interface ShellLink {
77
+ /** The visible label. */
78
+ label: string;
79
+ /** An absolute URL or a path. */
80
+ href: string;
81
+ /** Always a full page load, never `renderLink`. */
82
+ external?: boolean;
83
+ /** `data-testid` for the rendered link. */
84
+ testId?: string;
85
+ }
86
+ /**
87
+ * What `renderLink` receives: everything a single `<a>` needs. Spread it onto your router's link, for
88
+ * example `({ href, ...rest }) => <Link to={toRouterPath(href, basename)} {...rest} />`.
89
+ */
90
+ export interface ShellLinkRenderProps {
91
+ href: string;
92
+ children: ReactNode;
93
+ className?: string;
94
+ 'aria-current'?: 'page';
95
+ 'aria-label'?: string;
96
+ 'data-testid'?: string;
97
+ onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
98
+ }
99
+ /**
100
+ * Renders a same-origin, non-external link, usually for client-side navigation. It must return a single
101
+ * `<a>` element: the Design System menus only style and track links that are direct `<a>` children.
102
+ */
103
+ export type RenderShellLink = (props: ShellLinkRenderProps) => ReactNode;
104
+ /** Everything `AppLayout` renders around the page: its header, side menu and footer. */
105
+ export interface ShellProps {
106
+ /** Service name shown in the header, such as "Alberta.ca Account". */
107
+ appName: string;
108
+ /** Full URL the Alberta.ca logo links to. */
109
+ appUrl: string;
110
+ /** Who is signed in. Leave it out on signed-out pages: the header then has no user menu. */
111
+ user?: ShellUser | null;
112
+ /** The data API's `UserMenu` response. */
113
+ menu?: UserMenu | null;
114
+ /**
115
+ * The current page's path, used to mark the active side menu link. It may include the app's base path or not:
116
+ * `/personal` and `/ui/account/personal` both match `https://account.alberta.ca/ui/account/personal`, and both
117
+ * match a path-only href or `activePathPrefix` such as `/personal` too.
118
+ */
119
+ currentPath?: string;
120
+ /** Extra links in the user menu, after the user details (for example "My account" in the sign-in app). */
121
+ userLinks?: readonly ShellLink[];
122
+ /** Footer links. Defaults to the Alberta.ca Account footer (`DEFAULT_FOOTER_LINKS`). */
123
+ footerLinks?: readonly ShellLink[];
124
+ /** Renders same-origin, non-external links, such as with React Router's `<Link>`. Defaults to a plain `<a>`. */
125
+ renderLink?: RenderShellLink;
126
+ /** Called when the user chooses "Sign out". Without it, no sign-out link is shown. */
127
+ onSignOut?: () => void;
128
+ /** Maximum content width of the header and footer. @default '100%' */
129
+ maxContentWidth?: string;
130
+ }
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Path helpers for the side menu. The active-link rules are ported from
3
+ * `packages/shared/src/util/pathUtils.ts` (the shell can't import `@abgov-uiam/shared`), so the shell
4
+ * marks the same link active as the legacy side menu.
5
+ */
6
+ /** Removes trailing slashes and ensures a leading slash. A loop rather than a regex, so untrusted input can't backtrack. */
7
+ export declare const normalizePath: (path: string) => string;
8
+ /** The normalized pathname of an absolute URL or a path. */
9
+ export declare const getPathFromHref: (href: string) => string;
10
+ /**
11
+ * Whether `href` is the current page. Either side may include the app's base path:
12
+ * `/personal` matches `https://host/ui/account/personal`, and `/ui/account/personal` matches `/personal`.
13
+ */
14
+ export declare const isExactPathMatch: (currentPath: string, href: string) => boolean;
15
+ /**
16
+ * Whether the current page is `href` or a page below it, such as `/business/ACME/staff/5` for
17
+ * `/business/ACME/staff`. Either side may include the app's base path.
18
+ */
19
+ export declare const isPathWithin: (currentPath: string, href: string) => boolean;
20
+ /** A path within the current site: starts with a single `/` and has no scheme. */
21
+ export declare const isInternalRoute: (href: string) => boolean;
22
+ /** A path, or an absolute URL on the current page's origin. Absolute URLs are never same-origin outside a browser. */
23
+ export declare const isSameOrigin: (href: string) => boolean;
24
+ /**
25
+ * The href for a full page load. A bare path becomes `origin + path`, so a `<base>` element can't
26
+ * resolve it relative to the current app.
27
+ */
28
+ export declare const toAbsoluteHref: (href: string) => string;
29
+ /**
30
+ * Where a router link should go for an href, for `renderLink`. Paths are returned as-is. An absolute URL on
31
+ * the current origin inside `basePath` (the router's basename, such as `/ui/account`) becomes the path below
32
+ * it, keeping its query and hash. Anything else, such as another app on the same origin, is returned
33
+ * unchanged: React Router's `<Link>` loads an absolute URL outside its basename as a full page.
34
+ *
35
+ * @example toRouterPath('https://account.alberta.ca/ui/account/personal?tab=1', '/ui/account') // '/personal?tab=1'
36
+ * @example toRouterPath('https://account.alberta.ca/app/directory/x', '/ui/account') // unchanged
37
+ */
38
+ export declare const toRouterPath: (href: string, basePath?: string) => string;
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Whether a CSS media query matches, kept in sync with the viewport. Always `false` where
3
+ * `window.matchMedia` doesn't exist (server rendering, jsdom).
4
+ */
5
+ export declare const useMediaQuery: (query: string) => boolean;
package/package.json CHANGED
@@ -1,6 +1,82 @@
1
1
  {
2
2
  "name": "@abgov-uiam/shell",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Alberta.ca Account header, side menu and footer for Design System 2.0, as stateless, props-driven React components fed by the UIAM data API.",
5
+ "keywords": [
6
+ "alberta",
7
+ "alberta.ca account",
8
+ "design system",
9
+ "react"
10
+ ],
11
+ "author": "Government of Alberta",
12
+ "license": "MIT",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/GovAlta-EMU/alberta-ca-account.git",
16
+ "directory": "packages/shell"
17
+ },
18
+ "homepage": "https://github.com/GovAlta-EMU/alberta-ca-account/tree/main/packages/shell#readme",
19
+ "bugs": {
20
+ "url": "https://github.com/GovAlta-EMU/alberta-ca-account/issues"
21
+ },
22
+ "main": "dist/index.cjs.js",
23
+ "module": "dist/index.esm.js",
24
+ "types": "dist/types/index.d.ts",
25
+ "files": [
26
+ "dist",
27
+ "CHANGELOG.md"
28
+ ],
29
+ "sideEffects": [
30
+ "**/*.css"
31
+ ],
32
+ "exports": {
33
+ ".": {
34
+ "types": "./dist/types/index.d.ts",
35
+ "import": "./dist/index.esm.js",
36
+ "require": "./dist/index.cjs.js"
37
+ },
38
+ "./styles/*": "./dist/styles/*",
39
+ "./package.json": "./package.json"
40
+ },
41
+ "scripts": {
42
+ "build": "npm run typecheck && rollup -c",
43
+ "dev": "vite --config playground/vite.config.mts",
44
+ "typecheck": "tsc --noEmit -p tsconfig.json",
45
+ "test": "vitest run",
46
+ "test:watch": "vitest",
47
+ "coverage": "vitest run --coverage",
48
+ "prepack": "npm run build",
49
+ "prettier": "prettier --write src",
50
+ "prettier-check": "prettier --check src"
51
+ },
52
+ "publishConfig": {
53
+ "access": "public",
54
+ "registry": "https://registry.npmjs.org/"
55
+ },
56
+ "peerDependencies": {
57
+ "@abgov/react-components": "^8.0.0",
58
+ "react": "^18.0.0 || ^19.0.0",
59
+ "react-dom": "^18.0.0 || ^19.0.0"
60
+ },
61
+ "devDependencies": {
62
+ "@abgov/react-components": "8.0.0",
63
+ "@abgov/ui-components-common": "3.0.0",
64
+ "@abgov/web-components": "3.0.0",
65
+ "@rollup/plugin-typescript": "^12.3.1",
66
+ "@testing-library/dom": "^10.4.2",
67
+ "@testing-library/jest-dom": "^7.0.1",
68
+ "@testing-library/react": "^16.3.3",
69
+ "@types/react": "^19.3.0",
70
+ "@types/react-dom": "^19.3.0",
71
+ "@vitejs/plugin-react": "^6.3.0",
72
+ "@vitest/coverage-v8": "^5.1.0",
73
+ "ionicons": "^8.1.0",
74
+ "jsdom": "^31.0.0",
75
+ "prettier": "^3.9.10",
76
+ "rollup": "^4.62.2",
77
+ "tslib": "^2.9.1",
78
+ "typescript": "^6.0.3",
79
+ "vite": "^8.3.7",
80
+ "vitest": "^5.0.5"
81
+ }
82
+ }