@jskit-ai/agent-docs 0.1.276 → 0.1.278

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.
Files changed (15) hide show
  1. package/guide/agent/app-setup/material-3-migration.md +32 -2
  2. package/guide/agent/framework/material-3.md +22 -2
  3. package/package.json +1 -1
  4. package/patterns/minimal-foundation/example/package.json +2 -2
  5. package/patterns/shell-foundation/example/package.json +3 -3
  6. package/reference/autogen/PATTERN_INDEX.md +15 -15
  7. package/reference/autogen/packages/material-web.md +1 -1
  8. package/reference/autogen/packages/shell-web.md +30 -1
  9. package/reference/autogen/tooling/jskit-catalog.md +7 -1
  10. package/skills/jskit/references/material-3.md +22 -2
  11. package/skills/jskit/references/pattern-index.md +15 -15
  12. package/skills/jskit/references/patterns/app/minimal-foundation/example/package.json +2 -2
  13. package/skills/jskit/references/patterns/app/shell-foundation/example/package.json +3 -3
  14. package/skills/jskit/references/patterns/auth/oidc-sign-in/example/package.json +2 -2
  15. package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json +2 -2
package/guide/agent/app-setup/material-3-migration.md CHANGED
@@ -52,8 +52,9 @@ export const theme = {
52
52
  - A colour the app really owns (a partner brand, a status of its own) goes in
53
53
  `colors` by camelCase name, such as `partner: "#0A7D3E"`. It becomes
54
54
  `partner`, `on-partner`, `partner-container` and `on-partner-container`,
55
- harmonized to the seed, in both schemes. `success`, `warning` and `info` are
56
- already there.
55
+ harmonized to the seed, in both schemes; `{ value: "#F5C518", blend: false }`
56
+ keeps a brand colour's own hue. `success`, `warning` and `info` are already
57
+ there.
57
58
  - Delete `defaultTheme: "light"`. The app now follows the device's light or
58
59
  dark setting.
59
60
 
@@ -114,6 +115,9 @@ arrow. The shell's Up arrow returns to the page the person came from, or else
114
115
  to the parent, so:
115
116
 
116
117
  - delete "Back to X" buttons, `router.back()` and `history.back()` calls;
118
+ - rename a back button for a step or panel inside a page to what it does
119
+ ("Previous step") or where it goes ("Dashboard"), without the back arrow.
120
+ An embedded frame's own Back and Forward, such as a preview browser's, stay;
117
121
  - delete redirects from a settings or section landing page to its first child.
118
122
  A settings page is a list-detail page (`ShellListDetail`): on wide windows the
119
123
  list stays beside the open section, and on narrow ones the list is the
@@ -135,6 +139,32 @@ the content into the app bar:
135
139
  At most one action is `primary`; on compact windows the others show as icon
136
140
  buttons named by their label.
137
141
 
142
+ A layout that draws its own top app bar instead of `ShellLayout` keeps it and
143
+ builds the page's part from the shell's pieces, so Up, the title and the
144
+ actions behave as in `ShellLayout`:
145
+
146
+ ```vue
147
+ <script setup>
148
+ import { ShellPageActionsTarget, ShellPageTitle, ShellUpButton, useShellAppBar } from "@jskit-ai/shell-web/client";
149
+
150
+ useShellAppBar();
151
+ </script>
152
+
153
+ <template>
154
+ <v-app-bar>
155
+ <ShellUpButton />
156
+ <ShellPageTitle title="Workspace" />
157
+ <ShellPageActionsTarget />
158
+ <!-- the app's own controls -->
159
+ </v-app-bar>
160
+ <v-main><slot /></v-main>
161
+ </template>
162
+ ```
163
+
164
+ Delete the bar's own back button and the pages' own `h1`s: `ShellPageTitle` is
165
+ the page's one `h1`, and `jskit check` now counts the layout as a shell layout,
166
+ so its inner pages need parents.
167
+
138
168
  ## 7. CRUD screens
139
169
 
140
170
  The CRUD screens apply all of this themselves. An app that customized them
package/guide/agent/framework/material-3.md CHANGED
@@ -112,7 +112,7 @@ Exactly this, and nothing more:
112
112
  | `nav/history` | `history.back()`, `history.go()`, `history.pushState()`/`replaceState()`, `router.back()`, `router.go()` |
113
113
  | `nav/window-location` | `window.location` assignments, `.href =`, `location.assign()`, `location.replace()` |
114
114
  | `nav/raw-link` | a hand-built in-app path in `to`, `href`, `router.push()`, `router.replace()` or a `to:`/`href:` object key outside a placement |
115
- | `nav/back-control` | any back control but the shell's Up: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
115
+ | `nav/back-control` | any back control but the shell's Up that navigates the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
116
116
  | `nav/missing-parent` | an inner page of a shell surface without a declared parent |
117
117
  | `nav/top-level-parent` | a main-navigation destination that declares a parent |
118
118
  | `nav/allow` | any `m3-check: allow nav/...` comment: nothing excuses a navigation rule |
@@ -145,6 +145,15 @@ Exactly this, and nothing more:
145
145
  `finish(recordUrl)`; the record shows, and Up goes where the record's Up went
146
146
  before. Wrong: `router.push(recordUrl)` after Save, so Up or Back reopens the
147
147
  form.
148
+ - **Steps and drill-downs inside a page are named actions.** A wizard step or
149
+ a panel the page opens in place is not a page, so it has no Up. Right:
150
+ "Previous step", or the destination's name ("Dashboard"), with no back
151
+ arrow. Wrong: "Back" or a back arrow. `nav/back-control` flags only controls
152
+ that navigate the app: a link into it, or a handler that reaches the router,
153
+ JSKIT paths, `up()`, `finish()` or the browser's history or location. Prose
154
+ ("back from version 2"), a variable named `back` and an embedded frame's own
155
+ Back and Forward (`frame.contentWindow.history.back()`, as in a preview
156
+ browser) are not back controls.
148
157
 
149
158
  ## Foundation
150
159
 
@@ -196,6 +205,15 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
196
205
  standalone heading. A section inside a page uses a title role.
197
206
  - **Up** sits in the bar on every inner page (see Navigation and Up). On phones
198
207
  it replaces the menu icon.
208
+ - **A layout that draws its own top app bar** (a workspace bar with the
209
+ app's own controls, instead of `ShellLayout`) builds it from `ShellLayout`'s
210
+ own pieces, from `@jskit-ai/shell-web/client`. It calls `useShellAppBar()`
211
+ once, so its pages enter the trail and their `ShellPageActions` show in its
212
+ bar, and renders `ShellUpButton` first, then `ShellPageTitle` (the page's one
213
+ `h1`: `useShellPageTitle()`, else the route's `jskit.title`, else its `title`
214
+ prop) and `ShellPageActionsTarget`. `jskit check` counts it as a shell
215
+ layout, so its inner pages need parents; an Up the app draws itself is a
216
+ `nav/back-control` finding.
199
217
  - **Actions:** a screen's actions go in the bar inside `ShellPageActions`
200
218
  (`@jskit-ai/shell-web/client/components/ShellPageActions`), each a
201
219
  `ShellPageAction` with `icon`, `label` (also its accessible name and compact
@@ -322,7 +340,9 @@ Take the approved route first; none needs an exception:
322
340
 
323
341
  - **Brand or partner colours** are theme custom colours, used by name:
324
342
  `colors: { partner: "#0A7D3E" }` in `src/theme/index.js`, then
325
- `<v-chip color="partner">`.
343
+ `<v-chip color="partner">`. A hex string is harmonized toward the seed; a
344
+ colour that must keep its hue is `{ value: "#F5C518", blend: false }`
345
+ (Material Theme Builder's Blend switched off), with the same four roles.
326
346
  - **Chart and data colours** come from the theme: `const theme = useTheme()`,
327
347
  then `["primary", "tertiary"].map((role) => theme.current.value.colors[role])`.
328
348
  - **A third-party widget** lives in one wrapper component, such as
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jskit-ai/agent-docs",
3
- "version": "0.1.276",
3
+ "version": "0.1.278",
4
4
  "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
5
5
  "type": "module",
6
6
  "files": [
package/patterns/minimal-foundation/example/package.json CHANGED
@@ -35,7 +35,7 @@
35
35
  "@local/main": "0.1.0",
36
36
  "@fastify/static": "^10.1.3",
37
37
  "@jskit-ai/kernel": "0.2.10",
38
- "@jskit-ai/material-web": "0.1.0",
38
+ "@jskit-ai/material-web": "0.1.1",
39
39
  "@tanstack/vue-query": "^5.101.0",
40
40
  "fastify": "^5.12.7",
41
41
  "pino": "^10.3.1",
@@ -50,7 +50,7 @@
50
50
  },
51
51
  "devDependencies": {
52
52
  "@jskit-ai/config-eslint": "0.1.245",
53
- "@jskit-ai/jskit-catalog": "0.2.28",
53
+ "@jskit-ai/jskit-catalog": "0.2.30",
54
54
  "@playwright/test": "1.61.1",
55
55
  "@vitejs/plugin-vue": "^6.0.7",
56
56
  "eslint": "^10.8.0",
package/patterns/shell-foundation/example/package.json CHANGED
@@ -35,7 +35,7 @@
35
35
  "@local/main": "0.1.0",
36
36
  "@fastify/static": "^10.1.3",
37
37
  "@jskit-ai/kernel": "0.2.10",
38
- "@jskit-ai/material-web": "0.1.0",
38
+ "@jskit-ai/material-web": "0.1.1",
39
39
  "@tanstack/vue-query": "^5.101.0",
40
40
  "fastify": "^5.12.7",
41
41
  "pino": "^10.3.1",
@@ -45,13 +45,13 @@
45
45
  "vue-router": "^5.3.1",
46
46
  "vuetify": "^4.3.0",
47
47
  "@jskit-ai/http-runtime": "0.2.10",
48
- "@jskit-ai/shell-web": "0.2.11",
48
+ "@jskit-ai/shell-web": "0.2.12",
49
49
  "@fastify/fast-json-stringify-compiler": "^5.1.0",
50
50
  "@vue/devtools-api": "^8.2.1"
51
51
  },
52
52
  "devDependencies": {
53
53
  "@jskit-ai/config-eslint": "0.1.245",
54
- "@jskit-ai/jskit-catalog": "0.2.28",
54
+ "@jskit-ai/jskit-catalog": "0.2.30",
55
55
  "@playwright/test": "1.61.1",
56
56
  "@vitejs/plugin-vue": "^6.0.7",
57
57
  "eslint": "^10.8.0",
package/reference/autogen/PATTERN_INDEX.md CHANGED
@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
15
15
 
16
16
  - Id: `app/minimal-foundation`
17
17
  - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
18
- - Owner: `@jskit-ai/agent-docs@0.1.276`
18
+ - Owner: `@jskit-ai/agent-docs@0.1.278`
19
19
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/minimal-foundation/PATTERN.md)
20
20
  - Examples: [example/](../../skills/jskit/references/patterns/app/minimal-foundation/example/)
21
21
  - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
26
26
 
27
27
  - Id: `app/shell-foundation`
28
28
  - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
29
- - Owner: `@jskit-ai/agent-docs@0.1.276`
29
+ - Owner: `@jskit-ai/agent-docs@0.1.278`
30
30
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/shell-foundation/PATTERN.md)
31
31
  - Examples: [example/](../../skills/jskit/references/patterns/app/shell-foundation/example/)
32
32
  - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
37
37
 
38
38
  - Id: `assistant/assistant-surface`
39
39
  - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
40
- - Owner: `@jskit-ai/assistant-runtime@0.2.24`
40
+ - Owner: `@jskit-ai/assistant-runtime@0.2.25`
41
41
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/assistant/assistant-surface/PATTERN.md)
42
42
  - Examples: [example/](../../skills/jskit/references/patterns/assistant/assistant-surface/example/)
43
43
  - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -59,7 +59,7 @@ Compose JSKIT authentication routes, views, profile controls, and public surface
59
59
 
60
60
  - Id: `auth/auth-surface`
61
61
  - Keywords: `account`, `auth`, `login`, `logout`, `password`, `placement`, `profile`, `reset`, `surface`
62
- - Owner: `@jskit-ai/auth-web@0.2.13`
62
+ - Owner: `@jskit-ai/auth-web@0.2.14`
63
63
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/auth/auth-surface/PATTERN.md)
64
64
  - Examples: [example/](../../skills/jskit/references/patterns/auth/auth-surface/example/)
65
65
  - Requires: `@jskit-ai/auth-core`, `@jskit-ai/auth-web`, `@jskit-ai/shell-web`
@@ -70,7 +70,7 @@ Let people sign in with the accounts they already have in an accounts hub or ano
70
70
 
71
71
  - Id: `auth/oidc-sign-in`
72
72
  - Keywords: `accounts hub`, `auth`, `authentication`, `back-channel logout`, `dynamic client registration`, `issuer`, `master login`, `oidc`, `openid connect`, `single sign-on`, `sso`
73
- - Owner: `@jskit-ai/auth-provider-oidc-core@0.2.15`
73
+ - Owner: `@jskit-ai/auth-provider-oidc-core@0.2.16`
74
74
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/auth/oidc-sign-in/PATTERN.md)
75
75
  - Examples: [example/](../../skills/jskit/references/patterns/auth/oidc-sign-in/example/)
76
76
  - Requires: `@jskit-ai/auth-provider-oidc-core`, `@jskit-ai/auth-web`
@@ -246,7 +246,7 @@ Add a protected administration surface, settings shell, and semantic navigation
246
246
 
247
247
  - Id: `console/console-surface`
248
248
  - Keywords: `admin`, `console`, `navigation`, `owner`, `placement`, `settings`, `surface`
249
- - Owner: `@jskit-ai/console-web@0.1.235`
249
+ - Owner: `@jskit-ai/console-web@0.1.236`
250
250
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/console/console-surface/PATTERN.md)
251
251
  - Examples: [example/](../../skills/jskit/references/patterns/console/console-surface/example/)
252
252
  - Requires: `@jskit-ai/console-core`, `@jskit-ai/console-web`, `@jskit-ai/shell-web`
@@ -257,7 +257,7 @@ Build a routed CRUD user interface as thin application pages over JSKIT's shared
257
257
 
258
258
  - Id: `crud/crud-screen-set`
259
259
  - Keywords: `actions`, `add`, `crud`, `delete`, `edit`, `filters`, `list`, `material`, `routes`, `view`, `vue`
260
- - Owner: `@jskit-ai/http-web@0.2.16`
260
+ - Owner: `@jskit-ai/http-web@0.2.17`
261
261
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/crud/crud-screen-set/PATTERN.md)
262
262
  - Examples: [example/](../../skills/jskit/references/patterns/crud/crud-screen-set/example/)
263
263
  - Requires: `@jskit-ai/http-web`, `@jskit-ai/resource-crud-core`
@@ -312,7 +312,7 @@ Wrap a JSKIT web application in a Capacitor Android shell using native Capacitor
312
312
 
313
313
  - Id: `mobile/android-application`
314
314
  - Keywords: `android`, `capacitor`, `device`, `mobile`, `native`, `shell`, `webview`
315
- - Owner: `@jskit-ai/mobile-capacitor@0.2.11`
315
+ - Owner: `@jskit-ai/mobile-capacitor@0.2.12`
316
316
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/mobile/android-application/PATTERN.md)
317
317
  - Examples: [example/](../../skills/jskit/references/patterns/mobile/android-application/example/)
318
318
  - Requires: `@capacitor/android`, `@capacitor/app`, `@capacitor/cli`, `@jskit-ai/mobile-capacitor`
@@ -323,7 +323,7 @@ Add JSKIT realtime events with an optional Redis backplane and an explicit shell
323
323
 
324
324
  - Id: `realtime/realtime-application`
325
325
  - Keywords: `realtime`, `redis`, `socket.io`, `sockets`, `status`, `websocket`
326
- - Owner: `@jskit-ai/realtime@0.2.14`
326
+ - Owner: `@jskit-ai/realtime@0.2.15`
327
327
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/realtime/realtime-application/PATTERN.md)
328
328
  - Examples: [example/](../../skills/jskit/references/patterns/realtime/realtime-application/example/)
329
329
  - Requires: `@jskit-ai/realtime`, `@jskit-ai/shell-web`
@@ -334,7 +334,7 @@ Compose application-owned Google Publisher Tag delivery with the generic rewarde
334
334
 
335
335
  - Id: `rewards/google-rewarded`
336
336
  - Keywords: `ads`, `google`, `publisher tag`, `rewarded`, `unlock`
337
- - Owner: `@jskit-ai/rewarded-web@0.2.13`
337
+ - Owner: `@jskit-ai/rewarded-web@0.2.14`
338
338
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/rewards/google-rewarded/PATTERN.md)
339
339
  - Examples: [example/](../../skills/jskit/references/patterns/rewards/google-rewarded/example/)
340
340
  - Requires: `@jskit-ai/rewarded-web`
@@ -345,7 +345,7 @@ Define a server feature through explicit capabilities and first-class actions, a
345
345
 
346
346
  - Id: `server/feature-package`
347
347
  - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
348
- - Owner: `@jskit-ai/agent-docs@0.1.276`
348
+ - Owner: `@jskit-ai/agent-docs@0.1.278`
349
349
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/server/feature-package/PATTERN.md)
350
350
  - Examples: [example/](../../skills/jskit/references/patterns/server/feature-package/example/)
351
351
  - Requires: `@jskit-ai/kernel`
@@ -356,7 +356,7 @@ Compose the JSKIT responsive shell, semantic placements, settings navigation, an
356
356
 
357
357
  - Id: `shell/application-shell`
358
358
  - Keywords: `adaptive`, `app`, `layout`, `navigation`, `placement`, `responsive`, `settings`, `shell`
359
- - Owner: `@jskit-ai/shell-web@0.2.11`
359
+ - Owner: `@jskit-ai/shell-web@0.2.12`
360
360
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/shell/application-shell/PATTERN.md)
361
361
  - Examples: [example/](../../skills/jskit/references/patterns/shell/application-shell/example/)
362
362
  - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -367,7 +367,7 @@ Add product routes and shell extensions through file routing, semantic placement
367
367
 
368
368
  - Id: `ui/page-and-placement`
369
369
  - Keywords: `component`, `navigation`, `outlet`, `page`, `placement`, `routes`, `section`, `shell`, `subpages`, `vue`
370
- - Owner: `@jskit-ai/shell-web@0.2.11`
370
+ - Owner: `@jskit-ai/shell-web@0.2.12`
371
371
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/ui/page-and-placement/PATTERN.md)
372
372
  - Examples: [example/](../../skills/jskit/references/patterns/ui/page-and-placement/example/)
373
373
  - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -378,7 +378,7 @@ Compose an account settings route and profile, preference, notification, and sig
378
378
 
379
379
  - Id: `users/account-settings`
380
380
  - Keywords: `account`, `link provider`, `notifications`, `oauth`, `preferences`, `profile`, `settings`, `sign-in methods`, `user`, `vue`
381
- - Owner: `@jskit-ai/users-web@0.2.18`
381
+ - Owner: `@jskit-ai/users-web@0.2.19`
382
382
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/users/account-settings/PATTERN.md)
383
383
  - Examples: [example/](../../skills/jskit/references/patterns/users/account-settings/example/)
384
384
  - Requires: `@jskit-ai/shell-web`, `@jskit-ai/users-core`, `@jskit-ai/users-web`
@@ -411,7 +411,7 @@ Compose workspace selection, invitation, member administration, settings, and re
411
411
 
412
412
  - Id: `workspaces/workspace-surfaces`
413
413
  - Keywords: `admin`, `invite`, `member`, `navigation`, `settings`, `surface`, `switcher`, `workspace`
414
- - Owner: `@jskit-ai/workspaces-web@0.2.18`
414
+ - Owner: `@jskit-ai/workspaces-web@0.2.19`
415
415
  - Read: [PATTERN.md](../../skills/jskit/references/patterns/workspaces/workspace-surfaces/PATTERN.md)
416
416
  - Examples: [example/](../../skills/jskit/references/patterns/workspaces/workspace-surfaces/example/)
417
417
  - Requires: `@jskit-ai/shell-web`, `@jskit-ai/workspaces-core`, `@jskit-ai/workspaces-web`
package/reference/autogen/packages/material-web.md CHANGED
@@ -21,7 +21,7 @@ Local functions
21
21
  - `kebabCase(name)`
22
22
  - `channels(argb)`
23
23
  - `customColorRoleNames(name)`
24
- - `addCustomColorRoles(roles, seedArgb, dark, name, argb)`
24
+ - `addCustomColorRoles(roles, seedArgb, dark, name, argb, blend = true)`
25
25
  - `schemeColors(scheme, seedArgb, dark, appColors)`
26
26
  - `vuetifyTheme(seedArgb, dark, appColors)`
27
27
  - `normalizeAppColors(colors, schemeRoles)`
package/reference/autogen/packages/shell-web.md CHANGED
@@ -82,7 +82,6 @@ Exports
82
82
  - None
83
83
  Local functions
84
84
  - `updateScrolled()`
85
- - `goUp()`
86
85
 
87
86
  ### `src/client/components/ShellListDetail.vue`
88
87
  Exports
@@ -123,6 +122,14 @@ Local functions
123
122
  Exports
124
123
  - None
125
124
 
125
+ ### `src/client/components/ShellPageActionsTarget.vue`
126
+ Exports
127
+ - None
128
+
129
+ ### `src/client/components/ShellPageTitle.vue`
130
+ Exports
131
+ - None
132
+
126
133
  ### `src/client/components/ShellRouteTransition.vue`
127
134
  Exports
128
135
  - None
@@ -135,12 +142,22 @@ Exports
135
142
  Exports
136
143
  - None
137
144
 
145
+ ### `src/client/components/ShellUpButton.vue`
146
+ Exports
147
+ - None
148
+ Local functions
149
+ - `goUp()`
150
+
138
151
  ### `src/client/composables/shellLayoutDrawerPreference.js`
139
152
  Exports
140
153
  - `SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY`
141
154
  - `readDrawerDefaultOpenPreference({ storage = pageStorage() } = {})`
142
155
  - `writeDrawerDefaultOpenPreference(open, { storage = pageStorage() } = {})`
143
156
 
157
+ ### `src/client/composables/useShellAppBar.js`
158
+ Exports
159
+ - `useShellAppBar()`
160
+
144
161
  ### `src/client/composables/useShellDrawer.js`
145
162
  Exports
146
163
  - `useShellDrawer({ props, modalLayout, viewportWidth, navigationToggle, layoutState })`
@@ -278,6 +295,10 @@ Exports
278
295
  - `ShellPageActions`
279
296
  - `ShellPageAction`
280
297
  - `ShellListDetail`
298
+ - `ShellUpButton`
299
+ - `ShellPageTitle`
300
+ - `ShellPageActionsTarget`
301
+ - `useShellAppBar`
281
302
  - `useShellLayoutState`
282
303
  - `useShellPageTitle`
283
304
  - `useShellWindowSizeClass`
@@ -640,6 +661,10 @@ Local functions
640
661
  - `createSurfacePlacements(surface)`
641
662
  - `refuseBlockedRecord(to)`
642
663
 
664
+ ### `fixtures/adaptive-shell/src/OwnBarLayout.vue`
665
+ Exports
666
+ - None
667
+
643
668
  ### `fixtures/adaptive-shell/src/RecordListPage.vue`
644
669
  Exports
645
670
  - None
@@ -660,6 +685,10 @@ Exports
660
685
  Exports
661
686
  - None
662
687
 
688
+ ### `fixtures/adaptive-shell/src/StudioPage.vue`
689
+ Exports
690
+ - None
691
+
663
692
  ### `fixtures/adaptive-shell/src/theme/index.js`
664
693
  Exports
665
694
  - `theme`
package/reference/autogen/tooling/jskit-catalog.md CHANGED
@@ -124,7 +124,7 @@ Local functions
124
124
  ### `scripts/navigation.mjs`
125
125
  Exports
126
126
  - `NAVIGATION_RULES`
127
- - `checkBackControl(tag, report)`
127
+ - `checkBackControl(tag, report, script = "")`
128
128
  - `checkLinkAttribute(tag, entry, report)`
129
129
  - `checkNavigationCode(code, offset, report)`
130
130
  - `checkPageParents({ root, appFiles, pageFiles, report })`
@@ -134,6 +134,10 @@ Exports
134
134
  Local functions
135
135
  - `compact(text)`
136
136
  - `isPlacementLink(code, offset)`
137
+ - `definitionOf(script, name)`
138
+ - `statementFrom(text, start)`
139
+ - `navigatesApp(code, script, seen = new Set())`
140
+ - `navigatesFromControl(tag, script)`
137
141
  - `attribute(tag, name)`
138
142
  - `visibleText(inner)`
139
143
  - `isBackTag(tag)`
@@ -149,6 +153,8 @@ Local functions
149
153
  - `surfaceOf(route, surfaces)`
150
154
  - `routeDeclarations(source)`
151
155
  - `readPage(file, source)`
156
+ - `createShellBarReader(appFiles, read)`
157
+ - `localComponent(file, specifier, known)`
152
158
  - `pageKey(file)`
153
159
 
154
160
  ### `scripts/pattern-assets.mjs`
package/skills/jskit/references/material-3.md CHANGED
@@ -107,7 +107,7 @@ Exactly this, and nothing more:
107
107
  | `nav/history` | `history.back()`, `history.go()`, `history.pushState()`/`replaceState()`, `router.back()`, `router.go()` |
108
108
  | `nav/window-location` | `window.location` assignments, `.href =`, `location.assign()`, `location.replace()` |
109
109
  | `nav/raw-link` | a hand-built in-app path in `to`, `href`, `router.push()`, `router.replace()` or a `to:`/`href:` object key outside a placement |
110
- | `nav/back-control` | any back control but the shell's Up: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
110
+ | `nav/back-control` | any back control but the shell's Up that navigates the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
111
111
  | `nav/missing-parent` | an inner page of a shell surface without a declared parent |
112
112
  | `nav/top-level-parent` | a main-navigation destination that declares a parent |
113
113
  | `nav/allow` | any `m3-check: allow nav/...` comment: nothing excuses a navigation rule |
@@ -140,6 +140,15 @@ Exactly this, and nothing more:
140
140
  `finish(recordUrl)`; the record shows, and Up goes where the record's Up went
141
141
  before. Wrong: `router.push(recordUrl)` after Save, so Up or Back reopens the
142
142
  form.
143
+ - **Steps and drill-downs inside a page are named actions.** A wizard step or
144
+ a panel the page opens in place is not a page, so it has no Up. Right:
145
+ "Previous step", or the destination's name ("Dashboard"), with no back
146
+ arrow. Wrong: "Back" or a back arrow. `nav/back-control` flags only controls
147
+ that navigate the app: a link into it, or a handler that reaches the router,
148
+ JSKIT paths, `up()`, `finish()` or the browser's history or location. Prose
149
+ ("back from version 2"), a variable named `back` and an embedded frame's own
150
+ Back and Forward (`frame.contentWindow.history.back()`, as in a preview
151
+ browser) are not back controls.
143
152
 
144
153
  ## Foundation
145
154
 
@@ -191,6 +200,15 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
191
200
  standalone heading. A section inside a page uses a title role.
192
201
  - **Up** sits in the bar on every inner page (see Navigation and Up). On phones
193
202
  it replaces the menu icon.
203
+ - **A layout that draws its own top app bar** (a workspace bar with the
204
+ app's own controls, instead of `ShellLayout`) builds it from `ShellLayout`'s
205
+ own pieces, from `@jskit-ai/shell-web/client`. It calls `useShellAppBar()`
206
+ once, so its pages enter the trail and their `ShellPageActions` show in its
207
+ bar, and renders `ShellUpButton` first, then `ShellPageTitle` (the page's one
208
+ `h1`: `useShellPageTitle()`, else the route's `jskit.title`, else its `title`
209
+ prop) and `ShellPageActionsTarget`. `jskit check` counts it as a shell
210
+ layout, so its inner pages need parents; an Up the app draws itself is a
211
+ `nav/back-control` finding.
194
212
  - **Actions:** a screen's actions go in the bar inside `ShellPageActions`
195
213
  (`@jskit-ai/shell-web/client/components/ShellPageActions`), each a
196
214
  `ShellPageAction` with `icon`, `label` (also its accessible name and compact
@@ -317,7 +335,9 @@ Take the approved route first; none needs an exception:
317
335
 
318
336
  - **Brand or partner colours** are theme custom colours, used by name:
319
337
  `colors: { partner: "#0A7D3E" }` in `src/theme/index.js`, then
320
- `<v-chip color="partner">`.
338
+ `<v-chip color="partner">`. A hex string is harmonized toward the seed; a
339
+ colour that must keep its hue is `{ value: "#F5C518", blend: false }`
340
+ (Material Theme Builder's Blend switched off), with the same four roles.
321
341
  - **Chart and data colours** come from the theme: `const theme = useTheme()`,
322
342
  then `["primary", "tertiary"].map((role) => theme.current.value.colors[role])`.
323
343
  - **A third-party widget** lives in one wrapper component, such as
package/skills/jskit/references/pattern-index.md CHANGED
@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
15
15
 
16
16
  - Id: `app/minimal-foundation`
17
17
  - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
18
- - Owner: `@jskit-ai/agent-docs@0.1.276`
18
+ - Owner: `@jskit-ai/agent-docs@0.1.278`
19
19
  - Read: [PATTERN.md](patterns/app/minimal-foundation/PATTERN.md)
20
20
  - Examples: [example/](patterns/app/minimal-foundation/example/)
21
21
  - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
26
26
 
27
27
  - Id: `app/shell-foundation`
28
28
  - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
29
- - Owner: `@jskit-ai/agent-docs@0.1.276`
29
+ - Owner: `@jskit-ai/agent-docs@0.1.278`
30
30
  - Read: [PATTERN.md](patterns/app/shell-foundation/PATTERN.md)
31
31
  - Examples: [example/](patterns/app/shell-foundation/example/)
32
32
  - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
37
37
 
38
38
  - Id: `assistant/assistant-surface`
39
39
  - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
40
- - Owner: `@jskit-ai/assistant-runtime@0.2.24`
40
+ - Owner: `@jskit-ai/assistant-runtime@0.2.25`
41
41
  - Read: [PATTERN.md](patterns/assistant/assistant-surface/PATTERN.md)
42
42
  - Examples: [example/](patterns/assistant/assistant-surface/example/)
43
43
  - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -59,7 +59,7 @@ Compose JSKIT authentication routes, views, profile controls, and public surface
59
59
 
60
60
  - Id: `auth/auth-surface`
61
61
  - Keywords: `account`, `auth`, `login`, `logout`, `password`, `placement`, `profile`, `reset`, `surface`
62
- - Owner: `@jskit-ai/auth-web@0.2.13`
62
+ - Owner: `@jskit-ai/auth-web@0.2.14`
63
63
  - Read: [PATTERN.md](patterns/auth/auth-surface/PATTERN.md)
64
64
  - Examples: [example/](patterns/auth/auth-surface/example/)
65
65
  - Requires: `@jskit-ai/auth-core`, `@jskit-ai/auth-web`, `@jskit-ai/shell-web`
@@ -70,7 +70,7 @@ Let people sign in with the accounts they already have in an accounts hub or ano
70
70
 
71
71
  - Id: `auth/oidc-sign-in`
72
72
  - Keywords: `accounts hub`, `auth`, `authentication`, `back-channel logout`, `dynamic client registration`, `issuer`, `master login`, `oidc`, `openid connect`, `single sign-on`, `sso`
73
- - Owner: `@jskit-ai/auth-provider-oidc-core@0.2.15`
73
+ - Owner: `@jskit-ai/auth-provider-oidc-core@0.2.16`
74
74
  - Read: [PATTERN.md](patterns/auth/oidc-sign-in/PATTERN.md)
75
75
  - Examples: [example/](patterns/auth/oidc-sign-in/example/)
76
76
  - Requires: `@jskit-ai/auth-provider-oidc-core`, `@jskit-ai/auth-web`
@@ -246,7 +246,7 @@ Add a protected administration surface, settings shell, and semantic navigation
246
246
 
247
247
  - Id: `console/console-surface`
248
248
  - Keywords: `admin`, `console`, `navigation`, `owner`, `placement`, `settings`, `surface`
249
- - Owner: `@jskit-ai/console-web@0.1.235`
249
+ - Owner: `@jskit-ai/console-web@0.1.236`
250
250
  - Read: [PATTERN.md](patterns/console/console-surface/PATTERN.md)
251
251
  - Examples: [example/](patterns/console/console-surface/example/)
252
252
  - Requires: `@jskit-ai/console-core`, `@jskit-ai/console-web`, `@jskit-ai/shell-web`
@@ -257,7 +257,7 @@ Build a routed CRUD user interface as thin application pages over JSKIT's shared
257
257
 
258
258
  - Id: `crud/crud-screen-set`
259
259
  - Keywords: `actions`, `add`, `crud`, `delete`, `edit`, `filters`, `list`, `material`, `routes`, `view`, `vue`
260
- - Owner: `@jskit-ai/http-web@0.2.16`
260
+ - Owner: `@jskit-ai/http-web@0.2.17`
261
261
  - Read: [PATTERN.md](patterns/crud/crud-screen-set/PATTERN.md)
262
262
  - Examples: [example/](patterns/crud/crud-screen-set/example/)
263
263
  - Requires: `@jskit-ai/http-web`, `@jskit-ai/resource-crud-core`
@@ -312,7 +312,7 @@ Wrap a JSKIT web application in a Capacitor Android shell using native Capacitor
312
312
 
313
313
  - Id: `mobile/android-application`
314
314
  - Keywords: `android`, `capacitor`, `device`, `mobile`, `native`, `shell`, `webview`
315
- - Owner: `@jskit-ai/mobile-capacitor@0.2.11`
315
+ - Owner: `@jskit-ai/mobile-capacitor@0.2.12`
316
316
  - Read: [PATTERN.md](patterns/mobile/android-application/PATTERN.md)
317
317
  - Examples: [example/](patterns/mobile/android-application/example/)
318
318
  - Requires: `@capacitor/android`, `@capacitor/app`, `@capacitor/cli`, `@jskit-ai/mobile-capacitor`
@@ -323,7 +323,7 @@ Add JSKIT realtime events with an optional Redis backplane and an explicit shell
323
323
 
324
324
  - Id: `realtime/realtime-application`
325
325
  - Keywords: `realtime`, `redis`, `socket.io`, `sockets`, `status`, `websocket`
326
- - Owner: `@jskit-ai/realtime@0.2.14`
326
+ - Owner: `@jskit-ai/realtime@0.2.15`
327
327
  - Read: [PATTERN.md](patterns/realtime/realtime-application/PATTERN.md)
328
328
  - Examples: [example/](patterns/realtime/realtime-application/example/)
329
329
  - Requires: `@jskit-ai/realtime`, `@jskit-ai/shell-web`
@@ -334,7 +334,7 @@ Compose application-owned Google Publisher Tag delivery with the generic rewarde
334
334
 
335
335
  - Id: `rewards/google-rewarded`
336
336
  - Keywords: `ads`, `google`, `publisher tag`, `rewarded`, `unlock`
337
- - Owner: `@jskit-ai/rewarded-web@0.2.13`
337
+ - Owner: `@jskit-ai/rewarded-web@0.2.14`
338
338
  - Read: [PATTERN.md](patterns/rewards/google-rewarded/PATTERN.md)
339
339
  - Examples: [example/](patterns/rewards/google-rewarded/example/)
340
340
  - Requires: `@jskit-ai/rewarded-web`
@@ -345,7 +345,7 @@ Define a server feature through explicit capabilities and first-class actions, a
345
345
 
346
346
  - Id: `server/feature-package`
347
347
  - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
348
- - Owner: `@jskit-ai/agent-docs@0.1.276`
348
+ - Owner: `@jskit-ai/agent-docs@0.1.278`
349
349
  - Read: [PATTERN.md](patterns/server/feature-package/PATTERN.md)
350
350
  - Examples: [example/](patterns/server/feature-package/example/)
351
351
  - Requires: `@jskit-ai/kernel`
@@ -356,7 +356,7 @@ Compose the JSKIT responsive shell, semantic placements, settings navigation, an
356
356
 
357
357
  - Id: `shell/application-shell`
358
358
  - Keywords: `adaptive`, `app`, `layout`, `navigation`, `placement`, `responsive`, `settings`, `shell`
359
- - Owner: `@jskit-ai/shell-web@0.2.11`
359
+ - Owner: `@jskit-ai/shell-web@0.2.12`
360
360
  - Read: [PATTERN.md](patterns/shell/application-shell/PATTERN.md)
361
361
  - Examples: [example/](patterns/shell/application-shell/example/)
362
362
  - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -367,7 +367,7 @@ Add product routes and shell extensions through file routing, semantic placement
367
367
 
368
368
  - Id: `ui/page-and-placement`
369
369
  - Keywords: `component`, `navigation`, `outlet`, `page`, `placement`, `routes`, `section`, `shell`, `subpages`, `vue`
370
- - Owner: `@jskit-ai/shell-web@0.2.11`
370
+ - Owner: `@jskit-ai/shell-web@0.2.12`
371
371
  - Read: [PATTERN.md](patterns/ui/page-and-placement/PATTERN.md)
372
372
  - Examples: [example/](patterns/ui/page-and-placement/example/)
373
373
  - Requires: `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -378,7 +378,7 @@ Compose an account settings route and profile, preference, notification, and sig
378
378
 
379
379
  - Id: `users/account-settings`
380
380
  - Keywords: `account`, `link provider`, `notifications`, `oauth`, `preferences`, `profile`, `settings`, `sign-in methods`, `user`, `vue`
381
- - Owner: `@jskit-ai/users-web@0.2.18`
381
+ - Owner: `@jskit-ai/users-web@0.2.19`
382
382
  - Read: [PATTERN.md](patterns/users/account-settings/PATTERN.md)
383
383
  - Examples: [example/](patterns/users/account-settings/example/)
384
384
  - Requires: `@jskit-ai/shell-web`, `@jskit-ai/users-core`, `@jskit-ai/users-web`
@@ -411,7 +411,7 @@ Compose workspace selection, invitation, member administration, settings, and re
411
411
 
412
412
  - Id: `workspaces/workspace-surfaces`
413
413
  - Keywords: `admin`, `invite`, `member`, `navigation`, `settings`, `surface`, `switcher`, `workspace`
414
- - Owner: `@jskit-ai/workspaces-web@0.2.18`
414
+ - Owner: `@jskit-ai/workspaces-web@0.2.19`
415
415
  - Read: [PATTERN.md](patterns/workspaces/workspace-surfaces/PATTERN.md)
416
416
  - Examples: [example/](patterns/workspaces/workspace-surfaces/example/)
417
417
  - Requires: `@jskit-ai/shell-web`, `@jskit-ai/workspaces-core`, `@jskit-ai/workspaces-web`
package/skills/jskit/references/patterns/app/minimal-foundation/example/package.json CHANGED
@@ -35,7 +35,7 @@
35
35
  "@local/main": "0.1.0",
36
36
  "@fastify/static": "^10.1.3",
37
37
  "@jskit-ai/kernel": "0.2.10",
38
- "@jskit-ai/material-web": "0.1.0",
38
+ "@jskit-ai/material-web": "0.1.1",
39
39
  "@tanstack/vue-query": "^5.101.0",
40
40
  "fastify": "^5.12.7",
41
41
  "pino": "^10.3.1",
@@ -50,7 +50,7 @@
50
50
  },
51
51
  "devDependencies": {
52
52
  "@jskit-ai/config-eslint": "0.1.245",
53
- "@jskit-ai/jskit-catalog": "0.2.28",
53
+ "@jskit-ai/jskit-catalog": "0.2.30",
54
54
  "@playwright/test": "1.61.1",
55
55
  "@vitejs/plugin-vue": "^6.0.7",
56
56
  "eslint": "^10.8.0",
package/skills/jskit/references/patterns/app/shell-foundation/example/package.json CHANGED
@@ -35,7 +35,7 @@
35
35
  "@local/main": "0.1.0",
36
36
  "@fastify/static": "^10.1.3",
37
37
  "@jskit-ai/kernel": "0.2.10",
38
- "@jskit-ai/material-web": "0.1.0",
38
+ "@jskit-ai/material-web": "0.1.1",
39
39
  "@tanstack/vue-query": "^5.101.0",
40
40
  "fastify": "^5.12.7",
41
41
  "pino": "^10.3.1",
@@ -45,13 +45,13 @@
45
45
  "vue-router": "^5.3.1",
46
46
  "vuetify": "^4.3.0",
47
47
  "@jskit-ai/http-runtime": "0.2.10",
48
- "@jskit-ai/shell-web": "0.2.11",
48
+ "@jskit-ai/shell-web": "0.2.12",
49
49
  "@fastify/fast-json-stringify-compiler": "^5.1.0",
50
50
  "@vue/devtools-api": "^8.2.1"
51
51
  },
52
52
  "devDependencies": {
53
53
  "@jskit-ai/config-eslint": "0.1.245",
54
- "@jskit-ai/jskit-catalog": "0.2.28",
54
+ "@jskit-ai/jskit-catalog": "0.2.30",
55
55
  "@playwright/test": "1.61.1",
56
56
  "@vitejs/plugin-vue": "^6.0.7",
57
57
  "eslint": "^10.8.0",
package/skills/jskit/references/patterns/auth/oidc-sign-in/example/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "private": true,
3
3
  "type": "module",
4
4
  "dependencies": {
5
- "@jskit-ai/auth-provider-oidc-core": "0.2.15",
6
- "@jskit-ai/auth-web": "0.2.13"
5
+ "@jskit-ai/auth-provider-oidc-core": "0.2.16",
6
+ "@jskit-ai/auth-web": "0.2.14"
7
7
  }
8
8
  }
package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "private": true,
3
3
  "type": "module",
4
4
  "dependencies": {
5
- "@jskit-ai/realtime": "0.2.14",
6
- "@jskit-ai/shell-web": "0.2.11"
5
+ "@jskit-ai/realtime": "0.2.15",
6
+ "@jskit-ai/shell-web": "0.2.12"
7
7
  }
8
8
  }