@vc-shell/vc-app-skill 2.10.4-pr406.8ba2b2d → 2.11.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vc-shell/vc-app-skill",
3
- "version": "2.10.4-pr406.8ba2b2d",
3
+ "version": "2.11.0",
4
4
  "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
5
5
  "bin": "./bin/install.cjs",
6
6
  "files": [
package/runtime/VERSION CHANGED
@@ -1 +1 @@
1
- 2.10.4
1
+ 2.11.0
@@ -1 +1 @@
1
- Synced from framework at commit ec5bc413b on 2026-11-02T13:24:47.833Z
1
+ Synced from framework at commit 1bfeef1d5 on 2026-11-05T09:48:16.625Z
@@ -20,6 +20,8 @@ Headless widgets are defined as plain configuration objects with reactive refs f
20
20
 
21
21
  - **`useBladeWidgets`**: Register sidebar widgets (counters, action buttons) for a blade without creating Vue components. Refresh widget data after blade operations (save, delete).
22
22
  - **`useWidgetTrigger`**: Inside an external widget component (registered via `registerExternalWidget`) to register `onRefresh` / `onClick` callbacks. The blade can then call `refresh(widgetId)` or `refreshAll()` to trigger them.
23
+ - **Badge color** for a status (quality, completeness): see [Badge color](#badge-color).
24
+ - **Alerts** for things the user should look at (a declined payment, unread messages): see [Alerts](#alerts).
23
25
  - When NOT to use `useBladeWidgets`: for widgets that need their own template or complex UI (use `registerExternalWidget` + `useWidgetTrigger` instead).
24
26
 
25
27
  ## Basic Usage
@@ -72,56 +74,166 @@ async function onSave() {
72
74
 
73
75
  Inline `useBladeWidgets([...])` is fine for one-off widgets, but extracting becomes essential when widget data comes from API calls (which need their own composables anyway).
74
76
 
75
- ## API
77
+ ## Badge color
76
78
 
77
- ### Parameters
79
+ `badgeVariant` colors the badge to report a status that needs no action, such as a quality score. Unset keeps the default `"primary"`.
78
80
 
79
- | Parameter | Type | Required | Description |
80
- | --------- | ----------------------------- | -------- | ---------------------------- |
81
- | `widgets` | `HeadlessWidgetDeclaration[]` | Yes | Array of widget declarations |
81
+ | `WidgetBadgeVariant` | Typical meaning |
82
+ | -------------------- | ---------------------------- |
83
+ | `"primary"` | Default, a plain counter |
84
+ | `"success"` | Good state |
85
+ | `"warning"` | Medium state, worth a glance |
86
+ | `"danger"` | Bad state |
87
+ | `"info"` | Neutral information |
88
+ | `"secondary"` | No data, inactive |
82
89
 
83
- ### HeadlessWidgetDeclaration
90
+ Badge color is a status. For something the user should look at, use [alerts](#alerts) instead. A widget can use both: a yellow badge for medium quality and a red dot for a new problem.
91
+
92
+ ### Headless widget
93
+
94
+ ```ts
95
+ const score = ref<number>();
96
+
97
+ useBladeWidgets([
98
+ {
99
+ id: "QualityWidget",
100
+ icon: "lucide-gauge",
101
+ title: "PRODUCTS.WIDGETS.QUALITY",
102
+ badge: score,
103
+ badgeVariant: computed(() => (score.value === undefined ? undefined : score.value >= 80 ? "success" : score.value >= 50 ? "warning" : "danger")),
104
+ },
105
+ ]);
106
+ ```
84
107
 
85
- | Field | Type | Required | Description |
86
- | ----------------- | -------------------------------------------------------- | -------- | ----------------------------------------- |
87
- | `id` | `string` | Yes | Unique widget identifier |
88
- | `icon` | `string` | Yes | Icon name (e.g., `"lucide-tag"`) |
89
- | `title` | `string` | Yes | i18n key or display title |
90
- | `badge` | `Ref<number \| string> \| ComputedRef<number \| string>` | No | Badge counter value |
91
- | `loading` | `Ref<boolean> \| ComputedRef<boolean>` | No | Show loading indicator |
92
- | `disabled` | `Ref<boolean> \| boolean` | No | Disable the widget |
93
- | `isVisible` | `ComputedRef<boolean> \| Ref<boolean> \| boolean` | No | Toggle visibility |
94
- | `onClick` | `() => void` | No | Action when widget is clicked |
95
- | `onRefresh` | `() => void \| Promise<void>` | No | Called by `refresh(id)` or `refreshAll()` |
96
- | `alerts` | `Ref<IWidgetAlert[]> \| ComputedRef<IWidgetAlert[]>` | No | Live alerts shown in the widget popup |
97
- | `alertsComponent` | `Component` | No | Popup content instead of the default rows |
108
+ ### External widget
98
109
 
99
- ### Alerts
110
+ An external widget renders `VcWidget` itself, so it passes `badge-variant` as a prop. The registration does not change.
111
+
112
+ ```vue
113
+ <!-- QualityWidget.vue -->
114
+ <script setup lang="ts">
115
+ import { computed, ref } from "vue";
116
+ import { VcWidget, injectBladeContext, useWidgetTrigger } from "@vc-shell/framework";
100
117
 
101
- A widget with a non-empty `alerts` list shows a dot on its icon, colored by the highest severity. Hovering the widget (desktop) opens a popup with the alerts; clicking the widget still opens the blade. On touch screens the first tap on a widget with alerts opens the popup, which then has an Open button; a second tap on the widget also opens the blade. Widgets without alerts show no popup.
118
+ const ctx = injectBladeContext();
119
+ const productId = computed(() => (ctx.value.item as { id?: string })?.id ?? "");
120
+ const score = ref<number>();
121
+ const variant = computed(() => (score.value === undefined ? undefined : score.value >= 80 ? "success" : score.value >= 50 ? "warning" : "danger"));
102
122
 
103
- ```typescript
104
- const alerts = computed<IWidgetAlert[]>(() => (outOfStock.value ? [{ id: "stock", severity: "warning", text: t("OFFERS.OUT_OF_STOCK") }] : []));
123
+ async function load() {
124
+ score.value = await qualityApi.getScore(productId.value);
125
+ }
105
126
 
106
- useBladeWidgets([{ id: "OffersWidget", icon: "lucide-tag", title: "OFFERS.TITLE", alerts }]);
127
+ useWidgetTrigger({ onRefresh: load });
128
+ load();
129
+ </script>
130
+
131
+ <template>
132
+ <VcWidget
133
+ icon="lucide-gauge"
134
+ :title="$t('QUALITY.WIDGET.TITLE')"
135
+ :value="score"
136
+ :badge-variant="variant"
137
+ />
138
+ </template>
107
139
  ```
108
140
 
109
- | `IWidgetAlert` field | Type | Required | Description |
110
- | -------------------- | ---------------------------------------------- | -------- | --------------------------------- |
111
- | `id` | `string` | Yes | Unique within the widget |
112
- | `severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | Drives the dot color and row icon |
113
- | `text` | `string` | Yes | Already translated |
114
- | `meta` | `string` | No | Secondary line (time, reason) |
115
- | `onOpen` | `() => void` | No | Called on row click |
116
- | `action` | `{ label: string; run: () => void }` | No | Inline action button |
141
+ ```ts
142
+ registerExternalWidget({ id: "QualityWidget", component: QualityWidget, targetBlades: ["ProductDetails"] });
143
+ ```
117
144
 
118
- Alerts are data: compute them from what the widget has loaded, and they stay exactly as long as the problem does. When a push means the data changed, refetch it; the alerts follow, together with the badge. A component widget passes the same `alerts` through `useWidgetTrigger`.
145
+ ## Alerts
119
146
 
120
- ```typescript
147
+ Alerts tell the user that something in the widget's data needs a look: a declined payment, an address to confirm, unread messages.
148
+
149
+ ::storybook id="navigation-vcblade--widgets-with-alerts" height="520"
150
+
151
+ What the user sees:
152
+
153
+ - A dot on the widget icon, colored by the highest severity in the list.
154
+ - Desktop: hovering the widget opens a popup with the alerts. A click on the widget still opens its blade.
155
+ - Touch: the first tap opens the popup with an Open button; a second tap opens the blade.
156
+ - In the overflow menu, widgets with alerts are listed first.
157
+ - An empty list means no dot and no popup.
158
+
159
+ | `severity` | Dot color | Use for |
160
+ | ------------ | --------- | ------------------------------ |
161
+ | `"info"` | Blue | Something new, no problem |
162
+ | `"warning"` | Yellow | Needs attention soon |
163
+ | `"error"` | Red | Something failed |
164
+ | `"critical"` | Red | Blocks work; ranks above error |
165
+
166
+ ### IWidgetAlert
167
+
168
+ | Field | Type | Required | Description |
169
+ | ---------- | ----------------------------------------------------- | -------- | ----------------------------------- |
170
+ | `id` | `string` | Yes | Unique within the widget |
171
+ | `severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | Drives the dot color and row marker |
172
+ | `text` | `string` | Yes | Already translated |
173
+ | `meta` | `string` | No | Secondary line (time, reason) |
174
+ | `onOpen` | `() => void` | No | Called on row click |
175
+ | `action` | `{ label: string; run: () => void \| Promise<void> }` | No | Inline action button on the row |
176
+
177
+ ### Alerts are data
178
+
179
+ Compute alerts from what the widget has loaded. They stay exactly as long as the problem does: fix the data and the alert is gone. There is no "mark as seen" and no API to push an alert. When something changes on the server, refetch the data and the alerts follow, together with the badge.
180
+
181
+ ### Headless widget
182
+
183
+ ```ts
184
+ const { t } = useI18n();
185
+ const order = ref<Order>();
186
+
187
+ const alerts = computed<IWidgetAlert[]>(() => {
188
+ const list: IWidgetAlert[] = [];
189
+ if (order.value?.paymentStatus === "Declined") {
190
+ list.push({
191
+ id: "payment",
192
+ severity: "error",
193
+ text: t("ORDERS.ALERTS.PAYMENT_DECLINED"),
194
+ meta: formatRelative(order.value.modifiedDate),
195
+ onOpen: () => openBlade({ name: "OrderPayments", param: order.value!.id }),
196
+ });
197
+ }
198
+ if (order.value && !order.value.shippingAddress?.isConfirmed) {
199
+ list.push({
200
+ id: "address",
201
+ severity: "warning",
202
+ text: t("ORDERS.ALERTS.ADDRESS_UNCONFIRMED"),
203
+ action: { label: t("ORDERS.ALERTS.CONFIRM"), run: () => confirmAddress(order.value!.id) },
204
+ });
205
+ }
206
+ return list;
207
+ });
208
+
209
+ useBladeWidgets([
210
+ {
211
+ id: "PaymentsWidget",
212
+ icon: "lucide-credit-card",
213
+ title: "ORDERS.WIDGETS.PAYMENTS",
214
+ alerts,
215
+ onClick: () => openBlade({ name: "OrderPayments", param: order.value?.id }),
216
+ },
217
+ ]);
218
+ ```
219
+
220
+ ### External widget
221
+
222
+ An external widget passes the same `alerts` through `useWidgetTrigger`. This one counts unread messages and refetches on a push for its entity:
223
+
224
+ ```vue
225
+ <!-- MessagesWidget.vue -->
226
+ <script setup lang="ts">
227
+ import { computed, ref } from "vue";
228
+ import { VcWidget, injectBladeContext, useBladeNotifications, useWidgetTrigger, type IWidgetAlert } from "@vc-shell/framework";
229
+
230
+ const ctx = injectBladeContext();
231
+ const entityId = computed(() => (ctx.value.item as { id?: string })?.id ?? "");
121
232
  const unread = ref<Message[]>([]);
122
- const load = async () => {
123
- unread.value = await api.searchUnread({ entityId: entityId.value });
124
- };
233
+
234
+ async function load() {
235
+ unread.value = await messagesApi.searchUnread({ entityId: entityId.value });
236
+ }
125
237
 
126
238
  // A push for this entity: refetch, and the badge and alerts update together
127
239
  useBladeNotifications<MessagePush>({
@@ -130,8 +242,30 @@ useBladeNotifications<MessagePush>({
130
242
  onMessage: load,
131
243
  });
132
244
 
133
- const alerts = computed<IWidgetAlert[]>(() => unread.value.map((m) => ({ id: m.id!, severity: "info", text: m.content ?? "", onOpen: openMessenger })));
245
+ const alerts = computed<IWidgetAlert[]>(() =>
246
+ unread.value.map(
247
+ (m): IWidgetAlert => ({
248
+ id: m.id!,
249
+ severity: "info",
250
+ text: m.content ?? "",
251
+ meta: m.senderName,
252
+ onOpen: openMessenger,
253
+ }),
254
+ ),
255
+ );
256
+
134
257
  useWidgetTrigger({ onRefresh: load, alerts });
258
+ load();
259
+ </script>
260
+
261
+ <template>
262
+ <VcWidget
263
+ icon="lucide-message-square"
264
+ :title="$t('MESSAGES.WIDGET.TITLE')"
265
+ :value="unread.length"
266
+ @click="openMessenger"
267
+ />
268
+ </template>
135
269
  ```
136
270
 
137
271
  Widget alerts are independent from the notification bell: the bell lists notifications, the widget lists what is unresolved in its data.
@@ -140,6 +274,8 @@ Widget alerts are independent from the notification bell: the bell lists notific
140
274
 
141
275
  The popup shows one row per alert by default. To draw it yourself (message previews, an offer card), pass `alertsComponent`. The alerts still decide the dot and whether the popup opens; the component decides what it shows. It receives `IWidgetAlertsComponentProps`: the `alerts` and a `close()` to call after it opens a blade.
142
276
 
277
+ ::storybook id="navigation-vcblade--widgets-custom-alerts-content" height="520"
278
+
143
279
  ```vue
144
280
  <!-- MessagesPreview.vue -->
145
281
  <script setup lang="ts">
@@ -160,12 +296,39 @@ defineProps<IWidgetAlertsComponentProps>();
160
296
  </template>
161
297
  ```
162
298
 
163
- ```typescript
299
+ ```ts
164
300
  useWidgetTrigger({ onRefresh: load, alerts, alertsComponent: MessagesPreview });
301
+ // or, for a headless widget:
302
+ useBladeWidgets([{ id: "MessagesWidget", icon: "lucide-message-square", title: "MESSAGES.TITLE", alerts, alertsComponent: MessagesPreview }]);
165
303
  ```
166
304
 
167
305
  Keyboard opening moves focus to the first button, link or input in the component, so put the main action first or make it a real `<button>`.
168
306
 
307
+ ## API
308
+
309
+ ### Parameters
310
+
311
+ | Parameter | Type | Required | Description |
312
+ | --------- | ----------------------------- | -------- | ---------------------------- |
313
+ | `widgets` | `HeadlessWidgetDeclaration[]` | Yes | Array of widget declarations |
314
+
315
+ ### HeadlessWidgetDeclaration
316
+
317
+ | Field | Type | Required | Description |
318
+ | ----------------- | ------------------------------------------------------------ | -------- | ----------------------------------------- |
319
+ | `id` | `string` | Yes | Unique widget identifier |
320
+ | `icon` | `string` | Yes | Icon name (e.g., `"lucide-tag"`) |
321
+ | `title` | `string` | Yes | i18n key or display title |
322
+ | `badge` | `Ref<number \| string> \| ComputedRef<number \| string>` | No | Badge counter value |
323
+ | `badgeVariant` | `WidgetBadgeVariant \| Ref<WidgetBadgeVariant \| undefined>` | No | Badge color; unset keeps `"primary"` |
324
+ | `loading` | `Ref<boolean> \| ComputedRef<boolean>` | No | Show loading indicator |
325
+ | `disabled` | `Ref<boolean> \| boolean` | No | Disable the widget |
326
+ | `isVisible` | `ComputedRef<boolean> \| Ref<boolean> \| boolean` | No | Toggle visibility |
327
+ | `onClick` | `() => void` | No | Action when widget is clicked |
328
+ | `onRefresh` | `() => void \| Promise<void>` | No | Called by `refresh(id)` or `refreshAll()` |
329
+ | `alerts` | `Ref<IWidgetAlert[]> \| ComputedRef<IWidgetAlert[]>` | No | Live alerts, see [Alerts](#alerts) |
330
+ | `alertsComponent` | `Component` | No | Popup content instead of the default rows |
331
+
169
332
  ### Returns
170
333
 
171
334
  | Property | Type | Description |
@@ -196,7 +359,7 @@ useWidgetTrigger({ onRefresh: loadData });
196
359
  | `onClick` | `() => void` | No | Handler called when widget is clicked in dropdown |
197
360
  | `onRefresh` | `() => void \| Promise<void>` | No | Handler called to refresh widget data |
198
361
  | `disabled` | `Ref<boolean> \| boolean` | No | Disabled state |
199
- | `alerts` | `Ref<IWidgetAlert[]>` | No | Live alerts shown in the widget popup (see above) |
362
+ | `alerts` | `Ref<IWidgetAlert[]>` | No | Live alerts, see [Alerts](#alerts) |
200
363
  | `alertsComponent` | `Component` | No | Popup content instead of the default rows (see above) |
201
364
 
202
365
  ### How It Works
@@ -0,0 +1,219 @@
1
+ ---
2
+ title: useKeyboardShortcuts
3
+ category: composables
4
+ group: utilities
5
+ ---
6
+
7
+ !!! tip "Long page"
8
+ Use the section headings to jump directly to what you need: [Primary pattern: declare a shortcut on a toolbar item](#primary-pattern-declare-a-shortcut-on-a-toolbar-item), [Quick Start](#quick-start), [Built-in blade shortcuts](#built-in-blade-shortcuts), or [API Reference](#api-reference).
9
+
10
+ # useKeyboardShortcuts
11
+
12
+ `useKeyboardShortcuts` is the framework's keyboard-shortcut toolkit: the `hotkey` fluent builder for describing a combination, and OS-aware formatting for the tooltip and `aria-keyshortcuts` that a toolbar button shows automatically once it declares one. There is no manual `keydown` wiring in module code -- a shortcut is a plain field on a toolbar item, and the blade navigation layer dispatches it globally.
13
+
14
+ ## Primary pattern: declare a shortcut on a toolbar item
15
+
16
+ Add `shortcut: hotkey.mod.s` to any `IBladeToolbar` entry. `hotkey.mod.s` resolves to `{ key: "s", mod: true }` -- `mod` is the platform's primary modifier (Cmd on macOS, Ctrl elsewhere), so one definition covers both operating systems.
17
+
18
+ ```vue title="orders-details.vue"
19
+ <script setup lang="ts">
20
+ import { ref } from "vue";
21
+ import { hotkey, VcBlade, type IBladeToolbar } from "@vc-shell/framework";
22
+
23
+ const bladeToolbar = ref<IBladeToolbar[]>([
24
+ {
25
+ id: "save",
26
+ title: "Save",
27
+ icon: "lucide-save",
28
+ shortcut: hotkey.mod.s,
29
+ clickHandler: () => save(),
30
+ },
31
+ ]);
32
+ </script>
33
+
34
+ <template>
35
+ <VcBlade :toolbar-items="bladeToolbar" />
36
+ </template>
37
+ ```
38
+
39
+ That single field is the whole integration. The rendered "Save" button now shows a `⌘S` / `Ctrl+S` tooltip, sets `aria-keyshortcuts="Meta+S"`, and the blade navigation layer fires `clickHandler` when the user presses the combination while the blade is active -- no listener, no cleanup.
40
+
41
+ ## When to reach for it
42
+
43
+ - **Declaring a shortcut on a toolbar item.** The common case: add `shortcut: hotkey.mod.s` next to `clickHandler` on an `IBladeToolbar` entry (array pattern or `useToolbar().registerToolbarItem`, see [useToolbar](../useToolbar/)).
44
+ - **Formatting a shortcut for custom UI.** Call `useKeyboardShortcuts()` and use `formatShortcut(def)` when you need the OS-aware label somewhere other than the built-in toolbar tooltip (a help panel, a command palette row).
45
+ - **Detecting the platform.** `isMac` is exposed for any OS-conditional copy or icon choice tied to a shortcut.
46
+ - **Not for building your own key listener.** There is no public "register a global shortcut" API outside toolbar items -- see [Common mistakes](#common-mistakes).
47
+
48
+ ## Quick Start
49
+
50
+ ### Import vs `useKeyboardShortcuts()` destructure
51
+
52
+ `hotkey` is a context-free singleton -- import it directly wherever you only need to build a definition:
53
+
54
+ ```typescript
55
+ import { hotkey } from "@vc-shell/framework";
56
+
57
+ const saveShortcut = hotkey.mod.s; // { key: "s", mod: true }
58
+ ```
59
+
60
+ Reach for the composable form only when you also need `formatShortcut` or `isMac` (both are bound together so `formatShortcut` doesn't need an `isMac` argument at the call site):
61
+
62
+ ```typescript
63
+ import { useKeyboardShortcuts } from "@vc-shell/framework";
64
+
65
+ const { hotkey, formatShortcut, isMac } = useKeyboardShortcuts();
66
+
67
+ const saveShortcut = hotkey.mod.s;
68
+ const { parts, aria } = formatShortcut(saveShortcut);
69
+ // isMac ? parts = ["⌘", "S"] : parts = ["Ctrl", "S"]
70
+ // aria = "Meta+S" on macOS, "Control+S" elsewhere
71
+ ```
72
+
73
+ Both forms return the same `hotkey` singleton -- the composable exists for convenience when a component already needs `isMac`/`formatShortcut`, not because `hotkey` itself carries state.
74
+
75
+ ## Built-in blade shortcuts
76
+
77
+ Two shortcuts are wired up by the framework at the blade navigation root -- no client code required, and no toolbar item needed to get them:
78
+
79
+ | Shortcut | Effect | Gate |
80
+ | ------------ | ----------------------- | --------------------------------------------------------------------------- |
81
+ | `Esc` | Closes the active blade | Only if the blade is closable (has a `parentId`; workspace roots ignore it) |
82
+ | `Cmd/Ctrl+\` | Toggles expand/maximize | Only on desktop and only if the blade is closable |
83
+
84
+ Both are evaluated against the currently active blade, and both are skipped while the corresponding condition doesn't hold -- `Esc` on a non-closable workspace root does nothing, and `Cmd/Ctrl+\` does nothing on mobile viewports even on a closable blade.
85
+
86
+ **An explicit toolbar shortcut always wins.** The dispatcher checks the active blade's toolbar items before either built-in, so a toolbar item declared with `shortcut: hotkey.escape` (for example, a "Cancel" button) intercepts `Esc` and the built-in close never runs.
87
+
88
+ ## OS adaptation
89
+
90
+ `formatShortcut(def)` returns two independent representations from one `ShortcutDefinition`, so you never branch on OS yourself:
91
+
92
+ - `parts` -- an array of OS-native keycap labels for display. macOS renders modifier glyphs in Apple's canonical order (`⌃ ⌥ ⇧ ⌘`) with no separator; Windows/Linux render words (`Ctrl`, `Alt`, `Shift`) with a `+` between chips.
93
+ - `aria` -- a single canonical string in W3C `aria-keyshortcuts` format (`"Control+Shift+S"`), OS-independent by design -- this is what assistive tech reads, not what's painted on screen.
94
+
95
+ ```typescript
96
+ import { useKeyboardShortcuts } from "@vc-shell/framework";
97
+
98
+ const { hotkey, formatShortcut, isMac } = useKeyboardShortcuts();
99
+ const { parts } = formatShortcut(hotkey.mod.s);
100
+
101
+ // isMac === true → parts = ["⌘", "S"] → tooltip renders "⌘S" (no separator)
102
+ // isMac === false → parts = ["Ctrl", "S"] → tooltip renders "Ctrl+S" (with separator)
103
+ ```
104
+
105
+ The toolbar button itself (`ToolbarBaseButton`) already does this for you: it calls `formatShortcut` internally and renders the result through the internal `ShortcutTooltip` (`ShortcutKbd` chips inside a `VcTooltip`). The blade and AI panel header controls use the same component. `isMac` also determines `matchesEvent`'s runtime resolution of `mod` -- the same flag drives both what the user sees and what actually fires.
106
+
107
+ ## Accessibility
108
+
109
+ - **`aria-keyshortcuts`.** Set automatically on the button element whenever `shortcut` is present, using the canonical `aria` string from `formatShortcut` (for example `aria-keyshortcuts="Meta+S"`). No shortcut, no attribute -- it's never rendered empty.
110
+ - **Tooltip discovery.** A sighted user discovers the shortcut through the `<kbd>` chips shown on hover/focus of the toolbar button, after a 500ms delay (`ShortcutTooltip`). This is the only visual affordance; there is no separate "shortcuts list" surface in v1.
111
+ - **No button, no discovery.** Both `aria-keyshortcuts` and the tooltip are properties of the rendered toolbar button -- they exist only because `shortcut` lives on an `IBladeToolbar` item that renders as a button. There is currently no way to advertise a shortcut that isn't attached to a visible button (see [Common mistakes](#common-mistakes)).
112
+ - **Accessible name still comes from the title.** `shortcut` does not change how the button's accessible name is computed -- it still comes from the visible `title` text. Keep `title` non-empty; `shortcut` is additive, not a substitute for a labeled button.
113
+ - **Suppressed behind a modal.** Blade shortcuts (toolbar and built-in) do not fire while a modal (`aria-modal="true"`) is open, so a shortcut never acts on a blade hidden behind it.
114
+
115
+ ## Common mistakes
116
+
117
+ ### Expecting a bare key to fire while an input is focused
118
+
119
+ ```typescript
120
+ // Wrong -- assumes "e" fires globally
121
+ registerToolbarItem({ id: "edit", title: "Edit", shortcut: { key: "e" }, clickHandler: () => edit() });
122
+ ```
123
+
124
+ A shortcut with no modifier is suppressed while focus is inside a text input, textarea, select, or a `contenteditable` element -- otherwise typing the letter "e" into a form field would trigger the button. This guard only applies to bare keys; add a modifier (`hotkey.mod.e`) if the shortcut must also fire while a field is focused.
125
+
126
+ ```typescript
127
+ // Correct -- a modified combination is not suppressed by input focus
128
+ registerToolbarItem({ id: "edit", title: "Edit", shortcut: hotkey.mod.e, clickHandler: () => edit() });
129
+ ```
130
+
131
+ ### Two toolbar items sharing the same combination
132
+
133
+ ```typescript
134
+ // Wrong -- both items declare mod+s on the same blade
135
+ const bladeToolbar = ref<IBladeToolbar[]>([
136
+ { id: "save", title: "Save", shortcut: hotkey.mod.s, clickHandler: () => save() },
137
+ { id: "save-as", title: "Save As", shortcut: hotkey.mod.s, clickHandler: () => saveAs() },
138
+ ]);
139
+ ```
140
+
141
+ The dispatcher walks a blade's toolbar items in declaration order and fires the _first_ item whose shortcut matches, then stops -- `save-as` never receives `Cmd/Ctrl+S` as long as `save` is registered ahead of it. In development, the dispatcher emits a deduplicated `console.warn` on keydown for this case (first item wins, second is named in the warning), for a toolbar item with an unrecognized `shortcut.key`, and for a toolbar item that overrides a built-in (`Esc`, `Cmd/Ctrl+\`). Production stays silent -- these are warnings, not thrown errors -- so still treat shortcut collisions within a blade's toolbar as a review-time concern: keep combinations unique per blade.
142
+
143
+ ```typescript
144
+ // Correct -- distinct combinations
145
+ const bladeToolbar = ref<IBladeToolbar[]>([
146
+ { id: "save", title: "Save", shortcut: hotkey.mod.s, clickHandler: () => save() },
147
+ { id: "save-as", title: "Save As", shortcut: hotkey.mod.shift.s, clickHandler: () => saveAs() },
148
+ ]);
149
+ ```
150
+
151
+ ### Expecting a button-less shortcut
152
+
153
+ ```typescript
154
+ // Wrong -- there is no API to register a shortcut without a toolbar item
155
+ onMounted(() => {
156
+ window.addEventListener("keydown", (e) => {
157
+ if (e.metaKey && e.key === "s") save();
158
+ });
159
+ });
160
+ ```
161
+
162
+ Rolling your own `keydown` listener bypasses `isTextInputFocused` suppression, the active-blade scoping, and the tooltip/`aria-keyshortcuts` discovery that toolbar shortcuts get for free -- and it risks double-firing alongside the framework dispatcher. In v1, every shortcut must be attached to a visible `IBladeToolbar` item; there is no headless/button-less registration path. If the action genuinely has no natural button, add one (it can be low-priority/overflowed) rather than reaching for a manual listener.
163
+
164
+ ## API Reference
165
+
166
+ ### `hotkey`
167
+
168
+ A fluent builder, importable directly or via the composable. Modifier and key names are finite string unions, so a typo (`hotkey.mdo.s`) is a compile error, not a silent no-op.
169
+
170
+ ```typescript
171
+ hotkey.mod.s; // { key: "s", mod: true }
172
+ hotkey.mod.shift.s; // { key: "s", mod: true, shift: true }
173
+ hotkey.ctrl.alt.delete; // { key: "delete", ctrl: true, alt: true }
174
+ hotkey.escape; // { key: "escape" }
175
+ ```
176
+
177
+ Chainable modifiers: `mod`, `ctrl`, `meta`, `alt`, `shift` (any order, any combination). Terminal keys: letters `a`-`z`, digits `0`-`9`, `enter`, `escape`, `tab`, `space`, `delete`, `backspace`, `arrowup`/`arrowdown`/`arrowleft`/`arrowright`, `f1`-`f12`, `backslash`, `period`, `comma`, `slash`.
178
+
179
+ ### `useKeyboardShortcuts()`
180
+
181
+ Context-free -- no inject/lifecycle, usable in or out of a component `setup()`.
182
+
183
+ #### Returns: `UseKeyboardShortcutsReturn`
184
+
185
+ | Property | Type | Description |
186
+ | ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
187
+ | `hotkey` | `HotkeyBuilder` | The same singleton as the named `hotkey` import |
188
+ | `formatShortcut` | `(def: ShortcutDefinition) => { parts: string[]; aria: string }` | `isMac`-bound: formats a definition into display chips and an aria string |
189
+ | `isMac` | `boolean` | `true` when the user agent reports macOS/iOS |
190
+
191
+ ### `formatShortcut(def, isMac)`
192
+
193
+ The standalone function (also exported directly) if you need to format for an explicit `isMac` value instead of the detected one:
194
+
195
+ ```typescript
196
+ import { formatShortcut } from "@vc-shell/framework";
197
+
198
+ formatShortcut({ key: "s", mod: true }, true); // { parts: ["⌘", "S"], aria: "Meta+S" }
199
+ formatShortcut({ key: "s", mod: true }, false); // { parts: ["Ctrl", "S"], aria: "Control+S" }
200
+ ```
201
+
202
+ ### `ShortcutDefinition`
203
+
204
+ | Property | Type | Required | Description |
205
+ | -------- | --------- | -------- | ----------------------------------------------------------------------------------- |
206
+ | `key` | `string` | Yes | Single key: `"s"`, `"1"`, `"enter"`, `"escape"`, `"f2"`, `"arrowup"`, `"backslash"` |
207
+ | `mod` | `boolean` | No | Platform primary modifier -- Cmd on macOS, Ctrl elsewhere |
208
+ | `ctrl` | `boolean` | No | Literal Ctrl, regardless of platform |
209
+ | `meta` | `boolean` | No | Literal Cmd/Win key, regardless of platform |
210
+ | `alt` | `boolean` | No | Alt/Option |
211
+ | `shift` | `boolean` | No | Shift |
212
+
213
+ Building definitions by hand (`{ key: "s", mod: true }`) works identically to `hotkey.mod.s` -- the builder is sugar over this shape, useful when a definition needs to be constructed dynamically.
214
+
215
+ ## Related
216
+
217
+ - [useToolbar](../useToolbar/) -- registers the toolbar items that carry `shortcut`; see its `IBladeToolbar`/`IToolbarItem` reference for the full item shape
218
+ - [Blade Navigation Composables](../../blade-navigation/) -- the blade stack that scopes shortcut dispatch to the active blade and hosts the two built-in shortcuts
219
+ - `IBladeToolbar` in [Core types](../../types/) -- the `shortcut?: ShortcutDefinition` field lives here
@@ -0,0 +1,151 @@
1
+ ---
2
+ title: useLatestRequest
3
+ category: composables
4
+ group: utilities
5
+ ---
6
+
7
+ # useLatestRequest
8
+
9
+ Latest-wins sequencing for overlapping async work: lets a caller drop a response
10
+ that a newer request already superseded.
11
+
12
+ `useAsync` covers loading state, error state and error notifications, but it has
13
+ no notion of a superseded call — a slow earlier response can overwrite a newer
14
+ one. This composable fills that gap.
15
+
16
+ ## When to Use
17
+
18
+ - A search field that fires a request per keystroke, where the slowest response must not win
19
+ - A master/detail pair, where clicking row A then row B must not leave A's details on screen
20
+ - Any load that can still be in flight when its blade closes
21
+ - When NOT to use: for a single request with no concurrent sibling — plain `useAsync` is enough
22
+
23
+ !!! note "Discards, does not cancel"
24
+ The superseded request still completes; its result is thrown away. The generated
25
+ API clients build their own `RequestInit` and accept no `AbortSignal`, so there
26
+ is nothing to cancel through. Aborting would additionally save the round trip and
27
+ belongs with a client that takes a signal.
28
+
29
+ ## Quick Start
30
+
31
+ ```typescript
32
+ import { useLatestRequest } from "@vc-shell/framework";
33
+
34
+ const search = useLatestRequest();
35
+ const items = ref([]);
36
+
37
+ async function load(criteria) {
38
+ const result = await search.latest(client.search(criteria));
39
+ if (!result) return; // a newer search already won
40
+ items.value = result;
41
+ }
42
+ ```
43
+
44
+ `latest()` owns the bookkeeping: it marks the request as the newest, releases it
45
+ when it settles — including on a throw — and hands back `undefined` if a newer
46
+ request started meanwhile. There is no `finally` to forget.
47
+
48
+ !!! note "When `undefined` is ambiguous"
49
+ `undefined` means superseded. A request whose own successful result can be
50
+ `undefined` cannot distinguish the two, and should use `begin()` below.
51
+
52
+ ## API Reference
53
+
54
+ ### Returns
55
+
56
+ | Member | Type | Description |
57
+ | ------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
58
+ | `latest` | `<T>(request: Promise<T>) => Promise<T \| undefined>` | Runs a request, resolving to `undefined` if a newer one superseded it |
59
+ | `begin` | `() => LatestRequest` | Starts a request and supersedes any earlier one. The manual form behind `latest` |
60
+ | `invalidate` | `() => void` | Supersedes the in-flight request without starting a new one |
61
+ | `dispose` | `() => void` | Permanently supersedes everything. Runs automatically when the owning scope stops |
62
+ | `pending` | `Readonly<Ref<boolean>>` | `true` while the newest request is still running |
63
+
64
+ ### `LatestRequest`
65
+
66
+ Returned by `begin()`, for the cases `latest()` cannot serve: the request and the
67
+ check living in different functions, or a result that is legitimately `undefined`.
68
+
69
+ | Member | Type | Description |
70
+ | ----------- | --------------- | ---------------------------------------------------------------------------------- |
71
+ | `isCurrent` | `() => boolean` | `false` once a newer request started, or after `invalidate()` / `dispose()` |
72
+ | `complete` | `() => void` | Marks this request finished. Idempotent; only the current request clears `pending` |
73
+
74
+ ## Features
75
+
76
+ ### `pending` tracks the newest request only
77
+
78
+ A superseded request finishing does **not** clear `pending` — the newer one is
79
+ still running, and clearing there would hide the spinner while the screen is
80
+ still waiting for data.
81
+
82
+ ### Automatic disposal
83
+
84
+ When called inside a component or effect scope, the tracker disposes itself when
85
+ that scope stops, so a response landing after its blade closed can never write
86
+ into a dead scope. Call `dispose()` by hand only outside a scope.
87
+
88
+ ## Recipes
89
+
90
+ ### Driving a spinner
91
+
92
+ ```typescript
93
+ const details = useLatestRequest();
94
+ // `pending` is a ref, so watch it, render it, or hand it to useLoading.
95
+ const loading = details.pending;
96
+ ```
97
+
98
+ ### Dropping a request on selection change
99
+
100
+ ```typescript
101
+ watch(selectedId, () => {
102
+ // Nothing new starts yet; whatever is in flight stops being current.
103
+ details.invalidate();
104
+ });
105
+ ```
106
+
107
+ ## Common Mistakes
108
+
109
+ **Wrong: checking before the await**
110
+
111
+ ```typescript
112
+ const request = search.begin();
113
+ if (!request.isCurrent()) return; // always true here — nothing has superseded it yet
114
+ const result = await client.search(criteria);
115
+ items.value = result; // still overwrites newer data
116
+ ```
117
+
118
+ **Right: checking after**
119
+
120
+ ```typescript
121
+ const request = search.begin();
122
+ const result = await client.search(criteria);
123
+ if (!request.isCurrent()) return;
124
+ items.value = result;
125
+ ```
126
+
127
+ **Wrong: completing only on success**
128
+
129
+ ```typescript
130
+ const request = search.begin();
131
+ const result = await client.search(criteria); // throws → pending stays true forever
132
+ request.complete();
133
+ ```
134
+
135
+ **Right: completing in `finally`**
136
+
137
+ ```typescript
138
+ const request = search.begin();
139
+ try {
140
+ const result = await client.search(criteria);
141
+ if (!request.isCurrent()) return;
142
+ items.value = result;
143
+ } finally {
144
+ request.complete();
145
+ }
146
+ ```
147
+
148
+ ## Related
149
+
150
+ - [useAsync](./useAsync.md) — loading state, error state and error notifications for a single call
151
+ - [useLoading](./useLoading.md) — aggregates several loading flags
@@ -0,0 +1,48 @@
1
+ ---
2
+ title: Focus targets
3
+ category: composables
4
+ group: utilities
5
+ internal: true
6
+ ---
7
+
8
+ # Focus targets
9
+
10
+ Where focus goes after a context change, and which code puts it there. A transition that leaves focus on `<body>` makes the next Tab restart at the top of the document, which fails WCAG 2.4.3 Focus Order — so every transition below has a named target, and none of them may end on `<body>`.
11
+
12
+ Two kinds of move appear in the table, and the difference decides what you should expect to see:
13
+
14
+ - **Repair** — `focusIfLoose(getTarget)` moves focus only when nothing meaningful holds it. If the user clicked a row, or the view autofocused a field, focus stays where it is. A repair that declines is correct behaviour, not a miss.
15
+ - **Handoff** — a deliberate `focus()` call, used when the element the user was on stops existing. It moves focus even though something held it, because that something is about to be unmounted.
16
+
17
+ ## Targets per transition
18
+
19
+ | Transition | Target | Kind | Implemented in |
20
+ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
21
+ | Sign-in, and any route change | the shell workspace (`.vc-app__workspace`, `tabindex="-1"`) | repair | `vc-app.vue` — `watch(route.fullPath)`, plus a `watch(workspaceRef)` because sign-in is not a route change this component can observe |
22
+ | Sign-out | the unauthenticated layout root | repair | `vc-auth-layout.vue` — `onMounted` |
23
+ | Blade open | the blade root | repair | `vc-blade.vue` — `onMounted` |
24
+ | Maximize / Restore — header button | the replacement control (`Restore` after maximize, `Maximize` after restore) | handoff | `shared/header-controls/header-controls.vue` (blade header and AI panel header) — `watch(maximized)`, `flush: "pre"` |
25
+ | Maximize / Restore — `mod+\` shortcut | same as the header button | handoff | same watch. The shortcut dispatches outside the click handlers, so the handoff hangs off the state change rather than either entry point (VCST-5812) |
26
+ | Maximize while focus is outside the blade (sidebar, app bar, global search) | the blade root | repair | `vc-blade.vue` — `watch(renderingState.maximized)`. Maximizing inerts those regions, and an inert node loses focus a tick later, so `focusIsLoose` treats an element inside `[inert]` as loose (VCST-5859) |
27
+ | Save, and any load that raises `loading` | the blade root | repair | `vc-blade.vue` — `watch(props.loading)`. The toolbar re-renders and the control the user activated can stop existing; before this, only a blade that happened to remount recovered, through the mount repair (VCST-5670) |
28
+ | First load, before content has ever rendered | the blade root | park | `vc-blade.vue` — `watch(showSkeleton)`, which parks focus that was inside the blade before the skeleton replaces its controls |
29
+ | Popup close | the opener, or the workspace when the opener is gone | repair | `usePopup` for imperative popups; `vc-popup.vue` on `@after-leave` for `v-model` ones, because Headless UI restores focus only when it owns the unmount (VCST-5676). Both call `focusIfLoose(() => opener ?? focusFallbackTarget())`, and the second to run declines |
30
+
31
+ A blade mounting inside the workspace requests focus after the workspace does, so the more specific context wins. That ordering is deliberate.
32
+
33
+ ## Asserting it
34
+
35
+ Focus transitions are invisible to axe, so the story-level a11y gate proves nothing here. Perform the action, then read `document.activeElement`:
36
+
37
+ ```js
38
+ document.activeElement.tagName; // must never be "BODY"
39
+ ```
40
+
41
+ Pressing Tab once and checking that focus continues is a weaker check and on some paths no check at all: when the nav precedes `main` in DOM order, a genuine continuation and a restart from the document's first stop land on the same control. The absent `[active]` node is the evidence, not the next stop.
42
+
43
+ Chrome keeps the sequential-focus navigation starting point at a removed node, so Tab can still reach the right control even after focus was lost. That is engine-specific and does nothing for a screen reader — `document.activeElement` is still `BODY` and the focus ring is gone.
44
+
45
+ ## Related
46
+
47
+ - `focusIfLoose`, `focusFallbackTarget` — `framework/core/utilities/focus.ts`
48
+ - VCST-5670 — the ticket this table was written for
@@ -42,15 +42,16 @@ function openNotifications() {
42
42
 
43
43
  ## Key Props
44
44
 
45
- | Prop | Type | Default | Description |
46
- | ------------ | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47
- | `icon` | `string` | -- | Icon name (Lucide format, e.g., `"lucide-save"`) |
48
- | `title` | `string` | -- | Label text below (or beside) the icon |
49
- | `value` | `string \| number` | -- | Badge count displayed on the icon; numbers above 99 show as "99+" |
50
- | `disabled` | `boolean` | `false` | Prevents clicks and applies muted styling |
51
- | `isExpanded` | `boolean` | `false` | Expanded visual state |
52
- | `horizontal` | `boolean` | `false` | Arranges icon and title side by side instead of stacked |
53
- | `widgetId` | `string` | -- | Sets the `data-widget-id` attribute on the root element. The root also binds `data-widget-name` from `title`; both are used for widget identification/targeting. |
45
+ | Prop | Type | Default | Description |
46
+ | -------------- | -------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47
+ | `icon` | `string` | -- | Icon name (Lucide format, e.g., `"lucide-save"`) |
48
+ | `title` | `string` | -- | Label text below (or beside) the icon |
49
+ | `value` | `string \| number` | -- | Badge count displayed on the icon; numbers above 99 show as "99+" |
50
+ | `badgeVariant` | `"primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info"` | `"primary"` | Badge color for a status the widget reports |
51
+ | `disabled` | `boolean` | `false` | Prevents clicks and applies muted styling |
52
+ | `isExpanded` | `boolean` | `false` | Expanded visual state |
53
+ | `horizontal` | `boolean` | `false` | Arranges icon and title side by side instead of stacked |
54
+ | `widgetId` | `string` | -- | Sets the `data-widget-id` attribute on the root element. The root also binds `data-widget-name` from `title`; both are used for widget identification/targeting. |
54
55
 
55
56
  ## Events
56
57
 
@@ -96,6 +97,14 @@ Badge values above 99 are automatically displayed as "99+".
96
97
  <!-- Badge shows "99+" -->
97
98
  ```
98
99
 
100
+ ### Badge Color for a Status
101
+
102
+ Use `badgeVariant` when the badge reports a state that needs no action, such as a quality score. For things the user should look at, use alerts (the dot) instead. See [useBladeWidgets](../../../../core/composables/useBladeWidgets/index.docs.md#badge-color) for headless and external widget examples.
103
+
104
+ ```vue
105
+ <VcWidget icon="lucide-gauge" title="Quality" :value="64" badge-variant="warning" />
106
+ ```
107
+
99
108
  ## CSS Custom Properties
100
109
 
101
110
  | Variable | Default | Description |
@@ -113,6 +122,10 @@ Badge values above 99 are automatically displayed as "99+".
113
122
 
114
123
  ## Alert dot and badge highlight
115
124
 
125
+ ::storybook id="data-display-vcwidget--with-alert-dot" height="200"
126
+
127
+ How to give a widget alerts: [useBladeWidgets → Alerts](../../../../core/composables/useBladeWidgets/index.docs.md#alerts).
128
+
116
129
  Inside a blade widget strip, `VcWidget` reads per-widget render state provided by the blade (it renders exactly as before elsewhere):
117
130
 
118
131
  - **Alert dot**: a small dot on the icon (`.vc-widget__alert-dot--danger|--warning|--info`), coloured from the highest alert severity. The dot itself is `aria-hidden`; the widget gets `aria-haspopup="dialog"`, `aria-expanded` for the alert popup, and an `aria-describedby` text such as "2 need attention".