@vc-shell/vc-app-skill 2.12.0-pr418.1fe890c → 2.13.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 +1 -1
- package/runtime/VERSION +1 -1
- package/runtime/knowledge/components.json +1 -1
- package/runtime/knowledge/docs/_BUILD_HASH.md +1 -1
- package/runtime/knowledge/docs/core/composables/useBlade/useBlade.docs.md +0 -1
- package/runtime/knowledge/docs/core/composables/useKeyboardShortcuts/useKeyboardShortcuts.docs.md +219 -0
- package/runtime/knowledge/docs/core/composables/useLatestRequest/useLatestRequest.docs.md +151 -0
- package/runtime/knowledge/docs/core/utilities/focus.docs.md +48 -0
- package/runtime/knowledge/docs/modules/assets-manager/assets-folder-manager.docs.md +201 -0
- package/runtime/knowledge/docs/ui/components/organisms/vc-search-bar/vc-search-bar.docs.md +284 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vc-shell/vc-app-skill",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.13.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.
|
|
1
|
+
2.13.0
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$comment": "Generated by scripts/generate-component-manifest.ts. Do not edit by hand.",
|
|
3
|
-
"framework": "@vc-shell/framework@2.
|
|
3
|
+
"framework": "@vc-shell/framework@2.13.0",
|
|
4
4
|
"docsRoot": "Paths in `source` and `docs` are relative to the @vc-shell/framework package root.",
|
|
5
5
|
"components": [
|
|
6
6
|
{
|
|
@@ -1 +1 @@
|
|
|
1
|
-
Synced from framework at commit
|
|
1
|
+
Synced from framework at commit 4c085d60d on 2026-11-20T13:53:51.100Z
|
|
@@ -801,7 +801,6 @@ if (param.value) {
|
|
|
801
801
|
| Resource | Description |
|
|
802
802
|
| ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
|
803
803
|
| [`defineBladeContext` / `injectBladeContext`](../bladeContext/index.docs.md) | Share reactive blade data with descendant widgets |
|
|
804
|
-
| [`useBladeRegistry`](../useBladeRegistry/) | Look up registered blade components by name |
|
|
805
804
|
| [`VcBlade`](../../../ui/components/organisms/vc-blade/vc-blade.docs.md) | The blade UI shell component (header, toolbar, content area) |
|
|
806
805
|
| [`useToolbar`](../useToolbar/useToolbar.docs.md) | Dynamic toolbar management for blades |
|
|
807
806
|
| [`usePopup`](../usePopup/usePopup.docs.md) | Confirmation dialogs, commonly used in close guards |
|
package/runtime/knowledge/docs/core/composables/useKeyboardShortcuts/useKeyboardShortcuts.docs.md
ADDED
|
@@ -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
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Assets Folder Manager
|
|
3
|
+
category: reference
|
|
4
|
+
group: modules
|
|
5
|
+
slug: assets-folder-manager
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Assets Folder Manager
|
|
9
|
+
|
|
10
|
+
A built-in blade that browses a folder of platform asset storage. It lists one folder level at a time, opens subfolders, and uploads, creates and deletes against storage directly. For a flat list of files owned by an entity, see [Assets Manager](./assets-manager.docs.md).
|
|
11
|
+
|
|
12
|
+
## Overview
|
|
13
|
+
|
|
14
|
+
`AssetsFolderManager` is registered by `AssetsManagerModule` and opened by name with `openBlade`. It is a browser only: it does not return a chosen file to the opener. Clicking a file opens `AssetsDetails`, the shared child blade of the assets module, with the file's preview and properties.
|
|
15
|
+
|
|
16
|
+
Every request goes to `/api/assets` with `fetch`. Storage is the source of truth: each upload, new folder and delete reloads the current level, there are no local edits.
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import { useBlade } from "@vc-shell/framework";
|
|
20
|
+
|
|
21
|
+
const { openBlade } = useBlade();
|
|
22
|
+
|
|
23
|
+
openBlade({
|
|
24
|
+
name: "AssetsFolderManager",
|
|
25
|
+
options: { rootUrl: "/stores/1", title: "Store files" },
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Options (via `useBlade`)
|
|
30
|
+
|
|
31
|
+
| Option | Type | Description |
|
|
32
|
+
| --------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
33
|
+
| `rootUrl` | `string` | Root folder, for example `/stores/<id>`. Required. The blade cannot leave it |
|
|
34
|
+
| `title` | `string?` | Blade title and root breadcrumb. Defaults to i18n `ASSETS_MANAGER.FOLDER.TITLE` |
|
|
35
|
+
| `folderActions` | `IAssetsFolderAction[]?` | Extra actions on folder rows and cards only |
|
|
36
|
+
| `entryInfo` | `(entry) => IAssetInfoItem[] \| Promise<...>` | Extra rows in the details blade. See [App hooks](#app-hooks) |
|
|
37
|
+
| `beforeDelete` | `(entries) => string \| undefined \| Promise<...>` | Extra warning in the delete confirmation. See [App hooks](#app-hooks) |
|
|
38
|
+
|
|
39
|
+
## Permissions
|
|
40
|
+
|
|
41
|
+
| Permission | Controls |
|
|
42
|
+
| ----------------------- | ----------------------------------------------------------------------------------------- |
|
|
43
|
+
| `platform:asset:create` | Toolbar New folder, Upload, Upload from URL, drag-and-drop, the empty-state upload button |
|
|
44
|
+
| `platform:asset:delete` | Toolbar Delete, row Delete, the selection column and card checkboxes, details Delete |
|
|
45
|
+
|
|
46
|
+
Without the permission the control is hidden. Browsing, search, Download and Copy link need no permission.
|
|
47
|
+
|
|
48
|
+
## Folder navigation and root guard
|
|
49
|
+
|
|
50
|
+
- Clicking a folder row opens it. Clicking a file opens the [details blade](#details-blade).
|
|
51
|
+
- A bar above the table holds the folder path (breadcrumbs) and the search field. The breadcrumbs lead back to every level. The root crumb shows the blade title, the last crumb is the current folder and is not a link.
|
|
52
|
+
- Navigation is limited to the root: a folder opens only if it is in the current listing, and a breadcrumb jump accepts only a crumb of the current trail. Nothing above `rootUrl` is reachable.
|
|
53
|
+
- Folders are listed first, then files, each group by name. Paging (20 per page) is client-side over the loaded level.
|
|
54
|
+
- Search filters the current folder by name through the API `keyword` parameter. Moving to another folder clears it. When nothing matches, the table says so instead of showing the empty-folder state.
|
|
55
|
+
- Copy link copies an absolute URL; a relative `url` from the API is resolved against the current origin.
|
|
56
|
+
- A root that does not exist yet (the API answers 404) shows as an empty folder. It is created by the first upload or new folder.
|
|
57
|
+
- A request that finishes after the user moved on is discarded, so a fast double click never shows the wrong folder.
|
|
58
|
+
|
|
59
|
+
## Table and grid view
|
|
60
|
+
|
|
61
|
+
The two buttons at the end of the bar switch between a table and a grid of cards. The choice is kept in `localStorage` under `VC_ASSETS_FOLDER_MANAGER_VIEW` (`"table"` or `"grid"`) and the blade opens in the table when nothing is stored or storage is blocked.
|
|
62
|
+
|
|
63
|
+
Both views show the same page of 20 entries, the same selection and the same row actions, so switching keeps the page and what is selected.
|
|
64
|
+
|
|
65
|
+
- A card shows a 4:3 preview (the image, a folder icon or the extension badge), the name and a line with the size, or "Folder", and the modified date.
|
|
66
|
+
- Clicking a card does what clicking a row does. Enter opens it, Space selects it when the user may delete.
|
|
67
|
+
- The checkbox (top left) and the actions menu (top right) show on hover and keyboard focus. While anything is selected every checkbox stays visible. On touch screens both are always visible.
|
|
68
|
+
|
|
69
|
+
## Details blade
|
|
70
|
+
|
|
71
|
+
Clicking a file opens `AssetsDetails` as a child blade. Clicking another file replaces it, the open file stays highlighted in the table or grid, and moving to another folder or searching closes it.
|
|
72
|
+
|
|
73
|
+
It opens in storage mode: no form, a header with the preview or extension tile, the file name and chips, the absolute URL with a copy button, then the File section with Type (`contentType` or the extension), Size, Dimensions (images only, measured once the image loads), Created and Modified. Rows from [`entryInfo`](#app-hooks) follow under a separator. See [Assets Details](../assets/assets-details.docs.md). The toolbar has Download, Copy link and Delete. Delete runs the folder blade's own delete, with the same confirmation and `beforeDelete` warning, and closes the details only when the file is gone.
|
|
74
|
+
|
|
75
|
+
The details follow the folder listing: after a reload they show the fresh entry, and they close when the file disappears. The blade options carry functions, so a page reload or a deep link to it opens nothing and the blade closes itself.
|
|
76
|
+
|
|
77
|
+
## App hooks
|
|
78
|
+
|
|
79
|
+
Two options let the opener add what only the app knows about a file.
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
// IAssetInfoItem is { label: string; value: string }, exported from the assets module
|
|
83
|
+
entryInfo?: (entry: BlobEntry) => IAssetInfoItem[] | Promise<IAssetInfoItem[]>;
|
|
84
|
+
beforeDelete?: (entries: BlobEntry[]) => string | undefined | Promise<string | undefined>;
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- `entryInfo` runs each time the details blade shows a file. Its rows appear under the built-in fields. A skeleton shows while it loads; if it throws, one muted line says the information could not be loaded and the rest of the blade works.
|
|
88
|
+
- `beforeDelete` gets exactly the entries being deleted, files and folders as selected. It runs before the confirmation; a returned string is added to the confirmation as a second paragraph. Return `undefined` for no warning. If it throws, the error is shown as a toast and nothing is deleted. What a folder's contents imply is up to the app.
|
|
89
|
+
|
|
90
|
+
Both texts are shown as plain text, never as HTML.
|
|
91
|
+
|
|
92
|
+
Example: a page builder that knows which pages use each file.
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
openBlade({
|
|
96
|
+
name: "AssetsFolderManager",
|
|
97
|
+
options: {
|
|
98
|
+
rootUrl: "/stores/1",
|
|
99
|
+
entryInfo: async (entry) => {
|
|
100
|
+
const pages = await pageApi.findPagesUsing(entry.url);
|
|
101
|
+
return [{ label: "Used on", value: pages.length ? `${pages.length} pages` : "Not used" }];
|
|
102
|
+
},
|
|
103
|
+
beforeDelete: async (entries) => {
|
|
104
|
+
const used = await pageApi.countPagesUsing(entries.map((entry) => entry.url));
|
|
105
|
+
return used ? `These files are used on ${used} pages. The pages will show a broken image.` : undefined;
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
});
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Drag and drop
|
|
112
|
+
|
|
113
|
+
Files dropped anywhere on the blade upload into the current folder. Dropped on a folder row or card, they upload into that folder instead: the folder is highlighted while files are over it, the upload goes through the same collision check against that folder, and the current level reloads afterwards. Both need `platform:asset:create`. Dropping is a desktop feature; touch screens have no file drag.
|
|
114
|
+
|
|
115
|
+
## Collision behaviour
|
|
116
|
+
|
|
117
|
+
Before uploading, the blade re-reads the current level without the search filter. Each file whose name matches an existing entry (case-insensitive) opens a popup with three choices:
|
|
118
|
+
|
|
119
|
+
| Choice | Result |
|
|
120
|
+
| --------- | ------------------------------------------------------------------------- |
|
|
121
|
+
| Overwrite | Uploads with `forceFileOverwrite=true` |
|
|
122
|
+
| Rename | Asks for a new name and checks it again, so a second collision asks again |
|
|
123
|
+
| Skip | The file is not uploaded. Closing the popup also skips |
|
|
124
|
+
|
|
125
|
+
Files without a collision upload straight away. If some uploads fail, the level reloads and one toast reports how many failed.
|
|
126
|
+
|
|
127
|
+
## Delete confirmation
|
|
128
|
+
|
|
129
|
+
Toolbar Delete, the row or card action and the details blade Delete all ask for confirmation. The text names up to three selected items and shows a count past that. When a folder is selected, the text says everything inside it is deleted too. Deleting a folder removes its contents in storage. A [`beforeDelete`](#app-hooks) warning is added below the text.
|
|
130
|
+
|
|
131
|
+
## Folder actions
|
|
132
|
+
|
|
133
|
+
`folderActions` adds row actions to folder rows. The opener supplies them, there is no global registry.
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
interface IAssetsFolderAction {
|
|
137
|
+
id: string;
|
|
138
|
+
title: string;
|
|
139
|
+
icon?: string; // defaults to lucide-folder-cog
|
|
140
|
+
permission?: string | string[]; // hidden when the user lacks it
|
|
141
|
+
clickHandler: (folder: BlobEntry, ctx: { reload: () => Promise<void> }) => void | Promise<void>;
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
openBlade({
|
|
147
|
+
name: "AssetsFolderManager",
|
|
148
|
+
options: {
|
|
149
|
+
rootUrl: "/stores/1",
|
|
150
|
+
folderActions: [
|
|
151
|
+
{
|
|
152
|
+
id: "publish-folder",
|
|
153
|
+
title: "Publish folder",
|
|
154
|
+
icon: "lucide-send",
|
|
155
|
+
permission: "platform:asset:create",
|
|
156
|
+
clickHandler: async (folder, { reload }) => {
|
|
157
|
+
await publish(folder.url);
|
|
158
|
+
await reload();
|
|
159
|
+
},
|
|
160
|
+
},
|
|
161
|
+
],
|
|
162
|
+
},
|
|
163
|
+
});
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
An error thrown by `clickHandler` is shown as a toast.
|
|
167
|
+
|
|
168
|
+
## Recipe: open an entity's folder from a widget
|
|
169
|
+
|
|
170
|
+
A widget on a store blade that opens the store's folder:
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
import { computed, type Ref } from "vue";
|
|
174
|
+
import { useBlade, useBladeWidgets } from "@vc-shell/framework";
|
|
175
|
+
|
|
176
|
+
export function useStoreWidgets(store: Ref<{ id: string; name: string } | undefined>) {
|
|
177
|
+
const { openBlade } = useBlade();
|
|
178
|
+
|
|
179
|
+
useBladeWidgets([
|
|
180
|
+
{
|
|
181
|
+
id: "StoreFilesWidget",
|
|
182
|
+
icon: "lucide-folder",
|
|
183
|
+
title: "Files",
|
|
184
|
+
isVisible: computed(() => !!store.value?.id),
|
|
185
|
+
onClick() {
|
|
186
|
+
if (!store.value) return;
|
|
187
|
+
openBlade({
|
|
188
|
+
name: "AssetsFolderManager",
|
|
189
|
+
options: { rootUrl: `/stores/${store.value.id}`, title: store.value.name },
|
|
190
|
+
});
|
|
191
|
+
},
|
|
192
|
+
},
|
|
193
|
+
]);
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## Related
|
|
198
|
+
|
|
199
|
+
- `framework/modules/assets-manager/components/assets-folder-manager/` -- the blade, its internal composable, grid and popups
|
|
200
|
+
- [Assets Details](../assets/assets-details.docs.md) -- the details blade opened on a file click
|
|
201
|
+
- [Assets Manager](./assets-manager.docs.md) -- the flat asset list blade for an entity's own assets
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: VcSearchBar
|
|
3
|
+
category: components
|
|
4
|
+
group: data-display
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# VcSearchBar
|
|
8
|
+
|
|
9
|
+
Search, applied filters and saved views for a list screen, in one row. It holds the filter state and reports it as plain filter values. `VcDataTable` renders it when you set `search-bar`; it also works on its own.
|
|
10
|
+
|
|
11
|
+
::storybook id="data-display-vcsearchbar--wide-blade"
|
|
12
|
+
|
|
13
|
+
## When to Use
|
|
14
|
+
|
|
15
|
+
- Use **VcSearchBar** for a list screen with a search and a few filters that users combine and save as views.
|
|
16
|
+
- Use it standalone when the data is not a table (cards, a gallery, a tree).
|
|
17
|
+
- When NOT to use: for a single text box with no filters, use `VcInput`; for a filter inside one table column, use `VcColumn` `filter`.
|
|
18
|
+
|
|
19
|
+
## Three Ways to Use It
|
|
20
|
+
|
|
21
|
+
### 1. On a table: `search-bar`
|
|
22
|
+
|
|
23
|
+
Set `search-bar` on `VcDataTable` next to `searchable` and `global-filters`. The table renders the bar instead of its classic search header and forwards `@search` and `@filter` as before. Without `search-bar` the table keeps the classic header. See [VcDataTable](../vc-data-table), "Search bar (opt-in)".
|
|
24
|
+
|
|
25
|
+
```vue
|
|
26
|
+
<VcDataTable :items="orders" state-key="orders-list" searchable search-bar :global-filters="orderFilters" :search-views="orderViews" @filter="onFilter" @search="onSearch" />
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### 2. Your own bar in the `#header` slot
|
|
30
|
+
|
|
31
|
+
For full control over the state, leave `searchable` and `global-filters` off and put the bar into the table's `#header` slot. Load data from the bar's `v-model` or `@change`.
|
|
32
|
+
|
|
33
|
+
```vue
|
|
34
|
+
<VcDataTable :items="orders" :loading="loading">
|
|
35
|
+
<template #header>
|
|
36
|
+
<VcSearchBar v-model="query" :fields="orderFields" :views="orderViews" storage-key="orders-list" @change="load" />
|
|
37
|
+
</template>
|
|
38
|
+
</VcDataTable>
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### 3. Standalone
|
|
42
|
+
|
|
43
|
+
```vue
|
|
44
|
+
<VcSearchBar v-model="query" :fields="fields" storage-key="orders" @change="load" />
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Layout
|
|
48
|
+
|
|
49
|
+
The bar is one row of 36px controls with its own 16px side and 8px top and bottom padding, so it needs no wrapper: the search, a divider, the applied filters as chips, then the split **Filters** button.
|
|
50
|
+
|
|
51
|
+
- **Search** takes the remaining width (at least 200px or 22% of the bar). It has a clear button when it holds text and a `/` hint when it is empty and unfocused.
|
|
52
|
+
- **Chips** read "Field: value" (several values: "First +1"), in the order the filters were applied. A click opens the field's editor in a popover; the × removes the filter. Toggle fields show just their name. Chips that do not fit go behind a **+N** button that opens the hidden fields as an accordion.
|
|
53
|
+
- **Filters** opens the [Filters panel](#filters-panel). With filters applied it shows the count and a × part that clears them all.
|
|
54
|
+
- The bar has no slots. Put your own buttons next to it, or use the table's `search-header-actions` slot.
|
|
55
|
+
|
|
56
|
+
The layout follows the bar's own width:
|
|
57
|
+
|
|
58
|
+
| Width | Layout |
|
|
59
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| 720px+ | Wide: chips in the row (`variant="inline"`), or the applied field names on the Filters button (`variant="summary"`) |
|
|
61
|
+
| 480-719px | Medium: no chips; the Filters button holds the count and the × that clears all |
|
|
62
|
+
| under 480px | Narrow: the Filters button is a funnel icon with a count badge; the search shows the short default placeholder |
|
|
63
|
+
|
|
64
|
+
::storybook id="data-display-vcsearchbar--medium-blade"
|
|
65
|
+
|
|
66
|
+
### Search syntax
|
|
67
|
+
|
|
68
|
+
- Typing `field:` suggests the field's values; `field:value` followed by a space becomes a chip when the value matches an option's value or label exactly (any case), or is the start of only one of them. A start shared by several options (`status:p` for Pending and Paid) stays text and keeps the suggestions open. The field name is the field's `key` (default: its `id`).
|
|
69
|
+
- A word of 2 or more letters suggests the fields it matches. ↑ and ↓ move through the suggestions, Enter picks one.
|
|
70
|
+
- An unknown field or value (`foo:bar`, `status:xyz`) stays search text.
|
|
71
|
+
|
|
72
|
+
### Keyboard
|
|
73
|
+
|
|
74
|
+
- `/` focuses the search of the active blade (or of a bar outside blades) when no text field has focus.
|
|
75
|
+
- Backspace in an empty search removes the last chip.
|
|
76
|
+
- Esc closes the suggestions, then clears the text, then leaves the search. It never closes the blade.
|
|
77
|
+
- A chip's editor, "+N", the Filters panel and the views menu take the focus when they open; Tab stays inside them, Esc closes them and returns the focus to their button. ↑, ↓, Home and End move through the views menu.
|
|
78
|
+
- Removing a chip with its × moves the focus to the next chip, else to "+N", the Filters button or the search.
|
|
79
|
+
|
|
80
|
+
## Filters Panel
|
|
81
|
+
|
|
82
|
+
On desktop the panel is a 360px popover aligned to the end of the Filters button. Everything in it applies at once.
|
|
83
|
+
|
|
84
|
+
- **Header:** "Filters · N active" and a close button.
|
|
85
|
+
- **Toggles:** toggle fields as switches, with a count when one is given.
|
|
86
|
+
- **Fields:** an accordion of the other fields, each with its value summary (or "Any") and a × when set. The first applied field starts open (or the first field when none is applied).
|
|
87
|
+
- **Editors:** a list field has checkboxes, a find box over 6 options, an "Only" link on hover and dimmed options with a zero count; a select with `operators: ["any", "not"]` adds "Is any of" and "Is not". A date field has "Any time", the relative ranges and a custom range. A number field has From and To (applied on Enter or with Apply) and optional presets. A custom field shows your component.
|
|
88
|
+
- **Unsaved row:** while the filters differ from the current view, a row above the footer offers revert, "Save" (not for "All") and "Save as view…".
|
|
89
|
+
- **Footer:** "N results · applied instantly" (with `result-count`) and **Clear filters**.
|
|
90
|
+
|
|
91
|
+
::storybook id="data-display-vcsearchbar--filters-panel"
|
|
92
|
+
|
|
93
|
+
## Saved Views
|
|
94
|
+
|
|
95
|
+
A view is a named set of filter values. The search text is not part of a view and never makes it modified.
|
|
96
|
+
|
|
97
|
+
- **All** is the system view: no filters. It always exists and cannot be changed.
|
|
98
|
+
- **Module views** come from the `views` prop and from [external registrations](#external-filters-and-views). One may be the `default`: the bar opens on it when the URL names no view and the bar starts with no values.
|
|
99
|
+
- **User views** are saved with "Save as new view…" and kept per browser in `localStorage` under `VC_SEARCHBAR_<KEY>` (the `storage-key` upper-cased). Each has a "⋯" menu with Rename and Delete; deleting the current one selects "All".
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
const orderViews: SearchBarView[] = [
|
|
103
|
+
{ id: "open", name: "Open orders", values: { status: ["New", "Processing"] }, default: true },
|
|
104
|
+
{ id: "paid", name: "Paid", values: { status: ["Paid"] } },
|
|
105
|
+
];
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Selecting a view replaces the filters. Any other change keeps the current view and marks it **Modified**; changing it back (in any order) clears the mark. The selector never switches to another view on its own because the filters happen to match it, with one exception: removing the last filter of a view selects "All", as Clear all does.
|
|
109
|
+
|
|
110
|
+
While modified, the view menu offers "Save changes to “X”" (not for "All"; for a module view it stores the change in this browser), "Save as new view…" and "Revert to “X”".
|
|
111
|
+
|
|
112
|
+
### Where the selector is
|
|
113
|
+
|
|
114
|
+
- **In a blade:** next to the blade title: a bookmark, the view name, a "Modified" badge and a chevron. The bar registers it with the blade; the screen adds nothing. With two bars in one blade the first one gets the header and the other shows the selector in its own row.
|
|
115
|
+
- **Outside a blade:** at the start of the bar's row.
|
|
116
|
+
- **On a phone:** the views are chips at the top of the filters sheet; the current one is filled and marked `*` when modified.
|
|
117
|
+
|
|
118
|
+
`view-counts` adds a count per view to the menu.
|
|
119
|
+
|
|
120
|
+
::storybook id="data-display-vcsearchbar--modified-view"
|
|
121
|
+
|
|
122
|
+
## Props
|
|
123
|
+
|
|
124
|
+
| Prop | Type | Default | Description |
|
|
125
|
+
| ----------------- | ---------------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
|
|
126
|
+
| `modelValue` | `SearchBarState` | - | `{ search, values }`. Optional: without it the bar keeps its own state |
|
|
127
|
+
| `fields` | `SearchBarField[]` | `[]` | Filters offered by this screen |
|
|
128
|
+
| `views` | `SearchBarView[]` | - | Module views; one may be the `default` |
|
|
129
|
+
| `storageKey` | `string` | - | Key of the user views and of the filters and view in the blade URL |
|
|
130
|
+
| `variant` | `"inline" \| "summary"` | `"inline"` | Wide bar: chips in the row, or the applied field names on the Filters button |
|
|
131
|
+
| `counts` | `Record<string, Record<string, number>>` | - | Result count per option value, per field id (`{ status: { Paid: 12 } }`) |
|
|
132
|
+
| `viewCounts` | `Record<string, number>` | - | Result count per view id, shown in the view menu |
|
|
133
|
+
| `resultCount` | `number` | - | Result count of the current filters: the panel footer and "Show N results" |
|
|
134
|
+
| `unfilteredCount` | `number` | - | Rows without the bar's filters and search: "filtered from M" in the phone summary |
|
|
135
|
+
| `placeholder` | `string` | - | Search placeholder and accessible name; a narrow bar shows the short default instead |
|
|
136
|
+
| `searchDebounce` | `number` | `300` | Delay in ms before the typed text reaches the state, `change` and `search` |
|
|
137
|
+
| `name` | `string` | - | Target of external filters and views; defaults to the name of the blade the bar is in |
|
|
138
|
+
| `searchable` | `boolean` | `true` | Show the search input |
|
|
139
|
+
| `disabled` | `boolean` | `false` | Disable the bar |
|
|
140
|
+
|
|
141
|
+
## Events
|
|
142
|
+
|
|
143
|
+
| Event | Payload | Description |
|
|
144
|
+
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
|
|
145
|
+
| `update:modelValue` | `SearchBarState` | Any change of search text or values |
|
|
146
|
+
| `change` | `SearchBarChange` | `{ search, filters, state }`. One per user action; the debounced text counts too |
|
|
147
|
+
| `update:search` | `string` | Every keystroke, undebounced |
|
|
148
|
+
| `search` | `string` | The debounced search text |
|
|
149
|
+
| `update:mode` | `SearchBarMode` | The bar's width mode (`wide`, `medium`, `narrow`), or `phone` on a phone; at mount and on every change |
|
|
150
|
+
|
|
151
|
+
`change.filters` holds the filters as plain values keyed by field, with relative dates resolved.
|
|
152
|
+
|
|
153
|
+
## Fields
|
|
154
|
+
|
|
155
|
+
A field is `{ id, label, filter, key?, operators? }`. `filter` selects the kind; the existing `ColumnFilterConfig` shapes keep working.
|
|
156
|
+
|
|
157
|
+
| Kind | `filter` | Value in `state.values[id]` |
|
|
158
|
+
| ---------- | ---------------------------------------- | -------------------------------------------------------------- |
|
|
159
|
+
| Text | `true` or `"field"` | `string` |
|
|
160
|
+
| Select | `{ options, multiple? }` | `string`, `string[]`, or `NotValue` when `operators` has `not` |
|
|
161
|
+
| Date range | `{ range: [startField, endField] }` | `{ start?, end? }` or a `RelativeDate` |
|
|
162
|
+
| Toggle | `{ toggle: true }` | `boolean` |
|
|
163
|
+
| Number | `{ number: true, min?, max?, presets? }` | `NumberValue` |
|
|
164
|
+
| Custom | `{ component, label, parse? }` | whatever your component emits |
|
|
165
|
+
|
|
166
|
+
Value shapes added by the bar:
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
type NumberValue = { op: "gte" | "lte" | "eq" | "between"; min?: number; max?: number };
|
|
170
|
+
type NotValue = { not: string[] };
|
|
171
|
+
type RelativeDate = { relative: "today" | "7d" | "30d" };
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- `NumberValue`: `gte` and `eq` carry `min`, `lte` carries `max`, `between` carries both. The editor writes `gte`, `lte` or `between`; `eq` comes only from code or a link.
|
|
175
|
+
- `NotValue`: the chip reads "Field: not Value".
|
|
176
|
+
- `RelativeDate`: the date editor's relative ranges. The bar resolves it to concrete dates in `change.filters`.
|
|
177
|
+
- `key` is the field name in the search syntax (default: `id`).
|
|
178
|
+
- `FilterOption.count` shows a count next to the option; the `counts` prop overrides it per state.
|
|
179
|
+
|
|
180
|
+
### Custom editors
|
|
181
|
+
|
|
182
|
+
A custom field gives a component and a label function. The component receives `modelValue` and emits `update:modelValue`. `label(value)` is the text on the chip after `Name:`.
|
|
183
|
+
|
|
184
|
+
A value read back from the URL or from a saved view is untrusted input. Give `parse(raw)` to check it: `raw` is the JSON-parsed value, return the value to apply or `undefined` to drop it (a throw drops it too). Without `parse` the bar accepts only a primitive, an array of primitives or a plain object whose entries are those, and drops anything with a `__proto__`, `constructor` or `prototype` key.
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
const fields: SearchBarField[] = [
|
|
188
|
+
{
|
|
189
|
+
id: "rating",
|
|
190
|
+
label: "Rating",
|
|
191
|
+
filter: {
|
|
192
|
+
component: StarsEditor,
|
|
193
|
+
label: (v) => `${v}+ stars`,
|
|
194
|
+
parse: (raw) => (typeof raw === "number" && raw >= 1 && raw <= 5 ? raw : undefined),
|
|
195
|
+
},
|
|
196
|
+
},
|
|
197
|
+
];
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## Search text and `v-model`
|
|
201
|
+
|
|
202
|
+
`v-model` carries the whole state, search text included; `state.search` follows the input after `search-debounce`. A filter changed while the text waits for that pause takes the text with it: `search` fires first, then one `change` carries both.
|
|
203
|
+
|
|
204
|
+
When the parent writes `v-model`, the bar updates its state, the input and the URL but emits neither `change` nor `search`: the parent that wrote the value loads the data itself. A write while the typed text waits for its pause drops that text. The table drives its bar this way (Clear all, the empty state's actions). The search text is never part of a view or of the remembered filters.
|
|
205
|
+
|
|
206
|
+
## Filters and the View in the URL
|
|
207
|
+
|
|
208
|
+
Inside a blade that has a URL, the applied filters go to the URL query under `<storage-key>_filters` and the current view under `<storage-key>_view`, next to the table's `_sort`, `_search` and `_page`. A link to the screen opens it with the same filters and view, and a reload keeps them.
|
|
209
|
+
|
|
210
|
+
- On mount, the values of `v-model` come first, then the URL's, then the default view. A `v-model` with a search and no values keeps its search and takes the URL's values. Values the bar starts with win over the default view: it is not applied, and the view reads as "All", modified, unless the URL names a view.
|
|
211
|
+
- A link that names a view but has no filters (`orders_view=overdue` from a dashboard) opens the view with its values. A view registered after mount applies when it arrives, unless a filter was set meanwhile.
|
|
212
|
+
- If filters were restored (or a view applied), the bar emits `update:modelValue` and `change` once so the data can be loaded; it emits nothing when there is nothing to apply.
|
|
213
|
+
- Every applied change rewrites the value; with nothing applied the parameter is removed. The current view is always written, "All" as `_view=all`; a link without `_view` opens the default view.
|
|
214
|
+
- A view id that no longer exists (a deleted user view) shows as "All", modified while its filters apply; the filters still apply.
|
|
215
|
+
- A blade without a URL, a bar outside a blade, or a bar without `storage-key` remembers nothing.
|
|
216
|
+
|
|
217
|
+
The value is short and readable: fields are separated by `;`, each one is `id:value`.
|
|
218
|
+
|
|
219
|
+
| Value | Example |
|
|
220
|
+
| -------------------- | ------------------------------------------------------------ |
|
|
221
|
+
| Select, multi-select | `status:Paid,New` |
|
|
222
|
+
| Excluded values | `!status:Paid` |
|
|
223
|
+
| Relative date | `created:7d` (also `today`, `30d`) |
|
|
224
|
+
| Date range | `created:2026-01-01..2026-01-31`, `created:2026-01-01..` |
|
|
225
|
+
| Toggle | `overdue:1` |
|
|
226
|
+
| Number | `total:>=100`, `total:<=100`, `total:=100`, `total:100..200` |
|
|
227
|
+
| Text | `name:Acme` |
|
|
228
|
+
| Custom editor | the value as JSON |
|
|
229
|
+
|
|
230
|
+
Relative dates stay relative: a link with `created:7d` opened next week shows that week's last 7 days. A `;`, `,`, `:` or `\` inside a value is escaped with `\`. Malformed parts are skipped. A part for a field the bar does not have yet stays in the URL and applies when the field appears. A field that goes away (an external registration removed) leaves `change.filters`, but its part stays in the URL and its value comes back with the field.
|
|
231
|
+
|
|
232
|
+
## On a Phone
|
|
233
|
+
|
|
234
|
+
- The bar is the search and a 36px Filters icon button with a count badge. A summary line under it reads "N results · View\* · filtered from M · K filters · Clear all" ("N items" when nothing is filtered). The view shows when it is not the system view or when its values were changed ("All\*"). The search has no `/` hint.
|
|
235
|
+
- The Filters button opens a bottom sheet: "Clear" on the left, "Filters" with the count, "Done" on the right; the views as chips with the unsaved row; the same fields as the desktop panel with larger rows; and a full-width "Show N results" button ("No matching results" at 0).
|
|
236
|
+
- A chip editor and the view menu are not used on a phone; everything goes through the sheet.
|
|
237
|
+
|
|
238
|
+
::storybook id="data-display-vcsearchbar--phone-filters-sheet"
|
|
239
|
+
|
|
240
|
+
## External Filters and Views
|
|
241
|
+
|
|
242
|
+
Modules add fields and views to another module's screen:
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
import { registerExternalSearchFilters, unregisterExternalSearchFilters } from "@vc-shell/framework";
|
|
246
|
+
|
|
247
|
+
registerExternalSearchFilters({
|
|
248
|
+
id: "reviews-rating",
|
|
249
|
+
targetBlades: ["orders"],
|
|
250
|
+
priority: 100,
|
|
251
|
+
fields: [{ id: "rating", label: "Rating", filter: { number: true } }],
|
|
252
|
+
views: [{ id: "top-rated", name: "Top rated", values: { rating: { op: "gte", min: 4 } } }],
|
|
253
|
+
});
|
|
254
|
+
|
|
255
|
+
unregisterExternalSearchFilters("reviews-rating");
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
- `targetBlades` lists blade names, compared case-insensitively. A bar answers to the name of the blade it sits in.
|
|
259
|
+
- Set the `name` prop to address a bar by another name: a bar outside a blade, or two bars in one blade. On `VcDataTable` the same prop is `search-name`.
|
|
260
|
+
- Contributed fields and views come after the screen's own, ordered by `priority` (lower first, default 100). Registering an existing `id` replaces it. The registry is reactive: a module that loads after the blade opened still reaches it.
|
|
261
|
+
- A field that registers late (a contributed one, or `fields` loaded after mount) still gets its value from the URL: that part of the URL is kept until the field arrives, then applies as one `change`.
|
|
262
|
+
|
|
263
|
+
## Known Limitations
|
|
264
|
+
|
|
265
|
+
- User views keep object and array values by reference: treat view values as immutable. Custom values must be cloneable to be saved in a view.
|
|
266
|
+
- Two bars with the same `storage-key` on one page keep separate caches and can overwrite each other.
|
|
267
|
+
- Views use `localStorage` even when `VcDataTable` has `state-storage="session"`.
|
|
268
|
+
- Back and forward navigation inside an open blade does not update the bar: the URL is read when the bar mounts.
|
|
269
|
+
- In the table, the restored `@filter` is sent before the screen's own `onMounted`. A screen whose `onMounted` load builds its query from scratch, ignoring what `@filter` set, still sends an unfiltered request after the filtered one: keep the filters in the query that load reads.
|
|
270
|
+
- The date editor's relative ranges have no arrow-key navigation.
|
|
271
|
+
- A click on a button in Safari does not focus it, so focus is not returned to it after a popover closes.
|
|
272
|
+
|
|
273
|
+
## Common Mistakes
|
|
274
|
+
|
|
275
|
+
- Putting a `VcSearchBar` into `#header` and also setting `search-bar` on the table: the table renders its own bar as well. Use one.
|
|
276
|
+
- Expecting user views or URL filters without `storage-key`: views live in memory and nothing goes to the URL. `VcDataTable` with `search-bar` and no `state-key` warns about it in development.
|
|
277
|
+
- Passing `v-model` with values and expecting the default view: values the bar starts with win.
|
|
278
|
+
- Targeting external filters with a module name instead of the blade name.
|
|
279
|
+
|
|
280
|
+
## Related Components
|
|
281
|
+
|
|
282
|
+
- [VcDataTable](../vc-data-table): renders this bar with `search-bar`.
|
|
283
|
+
- [VcBlade](../vc-blade): shows the view selector next to its title.
|
|
284
|
+
- [VcInput](../../molecules/vc-input): a plain text input.
|