@vc-shell/vc-app-skill 2.6.0-rc.0-pr356.38334f4 → 2.6.0-rc.1
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/docs/_BUILD_HASH.md +1 -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/ui/components/molecules/vc-color-input/vc-color-input.docs.md +10 -9
- package/runtime/knowledge/docs/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md +21 -20
- package/runtime/knowledge/docs/ui/components/molecules/vc-input/vc-input.docs.md +27 -26
- package/runtime/knowledge/docs/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md +1 -0
- package/runtime/knowledge/docs/ui/components/molecules/vc-textarea/vc-textarea.docs.md +1 -0
- package/runtime/knowledge/docs/ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md +20 -19
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vc-shell/vc-app-skill",
|
|
3
|
-
"version": "2.6.0-rc.
|
|
3
|
+
"version": "2.6.0-rc.1",
|
|
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.6.0-rc.
|
|
1
|
+
2.6.0-rc.1
|
|
@@ -1 +1 @@
|
|
|
1
|
-
Synced from framework at commit
|
|
1
|
+
Synced from framework at commit 371aa8ec5 on 2026-09-08T10:09:34.584Z
|
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 `ShortcutKbd` chip component inside a tooltip. `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 (`ShortcutKbd`, wrapped in `VcTooltip`). 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
|
package/runtime/knowledge/docs/ui/components/molecules/vc-color-input/vc-color-input.docs.md
CHANGED
|
@@ -50,15 +50,16 @@ const color = ref<string | null>(null);
|
|
|
50
50
|
|
|
51
51
|
## Key Props
|
|
52
52
|
|
|
53
|
-
| Prop | Type | Default | Description
|
|
54
|
-
| ------------------------ | ---------------------- | ----------- |
|
|
55
|
-
| `modelValue` | `string \| null` | `undefined` | Color value via `v-model` (hex string or CSS color name)
|
|
56
|
-
| `label` | `string` | -- | Label text above the field
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
53
|
+
| Prop | Type | Default | Description |
|
|
54
|
+
| ------------------------ | ---------------------- | ----------- | ---------------------------------------------------------------------- |
|
|
55
|
+
| `modelValue` | `string \| null` | `undefined` | Color value via `v-model` (hex string or CSS color name) |
|
|
56
|
+
| `label` | `string` | -- | Label text above the field |
|
|
57
|
+
| `ariaLabel` | `string` | -- | Accessible name for the text input when no visible `label` is provided |
|
|
58
|
+
| `placeholder` | `string` | -- | Placeholder text |
|
|
59
|
+
| `clearable` | `boolean` | `false` | Shows a clear button when a value is present |
|
|
60
|
+
| `size` | `"default" \| "small"` | `"default"` | Field height variant |
|
|
61
|
+
| `error` / `errorMessage` | `boolean` / `string` | -- | Error styling and validation message |
|
|
62
|
+
| `disabled` | `boolean` | `false` | Disables the input and color picker |
|
|
62
63
|
|
|
63
64
|
## Events
|
|
64
65
|
|
package/runtime/knowledge/docs/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md
CHANGED
|
@@ -294,26 +294,27 @@ const date = ref<Date | null>(new Date("2025-01-15"));
|
|
|
294
294
|
|
|
295
295
|
## Props
|
|
296
296
|
|
|
297
|
-
| Prop | Type | Default | Description
|
|
298
|
-
| ------------------- | ---------------------------- | ---------------- |
|
|
299
|
-
| `modelValue` | `Date \| string \| null` | `undefined` | Bound value via `v-model`
|
|
300
|
-
| `type` | `"date" \| "datetime-local"` | `"date"` | Date only or date + time mode
|
|
301
|
-
| `label` | `string` | -- | Label text above the field
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `
|
|
306
|
-
| `
|
|
307
|
-
| `
|
|
308
|
-
| `
|
|
309
|
-
| `
|
|
310
|
-
| `
|
|
311
|
-
| `
|
|
312
|
-
| `
|
|
313
|
-
| `
|
|
314
|
-
| `
|
|
315
|
-
| `
|
|
316
|
-
| `
|
|
297
|
+
| Prop | Type | Default | Description |
|
|
298
|
+
| ------------------- | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
299
|
+
| `modelValue` | `Date \| string \| null` | `undefined` | Bound value via `v-model` |
|
|
300
|
+
| `type` | `"date" \| "datetime-local"` | `"date"` | Date only or date + time mode |
|
|
301
|
+
| `label` | `string` | -- | Label text above the field |
|
|
302
|
+
| `ariaLabel` | `string` | -- | Accessible name for the date input when no visible `label` is provided; applied through the library's `ariaLabels.input` option |
|
|
303
|
+
| `placeholder` | `string` | auto (localized) | Placeholder text; auto-generated from locale if not provided |
|
|
304
|
+
| `hint` | `string` | -- | Helper text below the field |
|
|
305
|
+
| `tooltip` | `string` | -- | Tooltip on the label info icon |
|
|
306
|
+
| `clearable` | `boolean` | `false` | Shows a clear button when a date is selected |
|
|
307
|
+
| `loading` | `boolean` | `false` | Shows a spinning loader icon |
|
|
308
|
+
| `size` | `"default" \| "small"` | `"default"` | Field height variant |
|
|
309
|
+
| `required` | `boolean` | `false` | Shows a required indicator |
|
|
310
|
+
| `error` | `boolean` | `false` | Enables error styling |
|
|
311
|
+
| `errorMessage` | `string` | -- | Error message below the field |
|
|
312
|
+
| `disabled` | `boolean` | `false` | Disables the date picker |
|
|
313
|
+
| `autofocus` | `boolean` | `false` | Focus the field on mount |
|
|
314
|
+
| `name` | `string` | `"Field"` | HTML name attribute |
|
|
315
|
+
| `multilanguage` | `boolean` | `false` | Shows language badge on the label |
|
|
316
|
+
| `currentLanguage` | `string` | -- | Language code for the badge |
|
|
317
|
+
| `datePickerOptions` | `VueDatePickerProps` | -- | Pass-through options to VueDatePicker |
|
|
317
318
|
|
|
318
319
|
## Events
|
|
319
320
|
|
|
@@ -671,32 +671,33 @@ VcInput blocks the minus key for both `number` and `integer` types. If you need
|
|
|
671
671
|
|
|
672
672
|
### Props
|
|
673
673
|
|
|
674
|
-
| Prop | Type | Default | Description
|
|
675
|
-
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
|
676
|
-
| `modelValue` | `string \| number \| Date \| null` | `undefined` | Bound value via `v-model`
|
|
677
|
-
| `type` | `"text" \| "password" \| "email" \| "tel" \| "url" \| "time" \| "number" \| "integer" \| "date" \| "datetime-local" \| "color"` | `"text"` | Input type. `date`/`datetime-local` delegate to VcDatePicker; `color` delegates to VcColorInput
|
|
678
|
-
| `label` | `string` | -- | Label text displayed above the field
|
|
679
|
-
| `placeholder` | `string` | -- | Placeholder text inside the field
|
|
680
|
-
| `hint` | `string` | -- | Help text displayed below the field
|
|
681
|
-
| `tooltip` | `string` | -- | Tooltip text shown on hover next to the label
|
|
682
|
-
| `prefix` | `string` | -- | Static text rendered before the input value
|
|
683
|
-
| `suffix` | `string` | -- | Static text rendered after the input value
|
|
684
|
-
| `name` | `string` | `"Field"` | HTML `name` attribute on the native input
|
|
685
|
-
| `clearable` | `boolean` | `false` | Shows a clear (x) button when the field has a value
|
|
686
|
-
| `disabled` | `boolean` | `false` | Disables the input (also inherits from `VcInputGroup` context)
|
|
687
|
-
| `required` | `boolean` | `false` | Adds a red asterisk to the label (visual only, no validation)
|
|
688
|
-
| `loading` | `boolean` | `false` | Shows a spinning loader icon inside the field
|
|
689
|
-
| `autofocus` | `boolean` | `false` | Auto-focuses the input on mount
|
|
690
|
-
| `autocomplete` | `string` | -- | Autofill hint set on the native input (e.g. `"username"`, `"current-password"`)
|
|
691
|
-
| `
|
|
692
|
-
| `
|
|
693
|
-
| `
|
|
694
|
-
| `
|
|
695
|
-
| `
|
|
696
|
-
| `
|
|
697
|
-
| `
|
|
698
|
-
| `
|
|
699
|
-
| `
|
|
674
|
+
| Prop | Type | Default | Description |
|
|
675
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
676
|
+
| `modelValue` | `string \| number \| Date \| null` | `undefined` | Bound value via `v-model` |
|
|
677
|
+
| `type` | `"text" \| "password" \| "email" \| "tel" \| "url" \| "time" \| "number" \| "integer" \| "date" \| "datetime-local" \| "color"` | `"text"` | Input type. `date`/`datetime-local` delegate to VcDatePicker; `color` delegates to VcColorInput |
|
|
678
|
+
| `label` | `string` | -- | Label text displayed above the field |
|
|
679
|
+
| `placeholder` | `string` | -- | Placeholder text inside the field |
|
|
680
|
+
| `hint` | `string` | -- | Help text displayed below the field |
|
|
681
|
+
| `tooltip` | `string` | -- | Tooltip text shown on hover next to the label |
|
|
682
|
+
| `prefix` | `string` | -- | Static text rendered before the input value |
|
|
683
|
+
| `suffix` | `string` | -- | Static text rendered after the input value |
|
|
684
|
+
| `name` | `string` | `"Field"` | HTML `name` attribute on the native input |
|
|
685
|
+
| `clearable` | `boolean` | `false` | Shows a clear (x) button when the field has a value |
|
|
686
|
+
| `disabled` | `boolean` | `false` | Disables the input (also inherits from `VcInputGroup` context) |
|
|
687
|
+
| `required` | `boolean` | `false` | Adds a red asterisk to the label (visual only, no validation) |
|
|
688
|
+
| `loading` | `boolean` | `false` | Shows a spinning loader icon inside the field |
|
|
689
|
+
| `autofocus` | `boolean` | `false` | Auto-focuses the input on mount |
|
|
690
|
+
| `autocomplete` | `string` | -- | Autofill hint set on the native input (e.g. `"username"`, `"current-password"`) |
|
|
691
|
+
| `ariaLabel` | `string` | -- | Accessible name used when no visible `label` is provided; forwarded to the delegated date picker and color input too |
|
|
692
|
+
| `error` | `boolean` | `false` | Activates error styling (red border and ring) |
|
|
693
|
+
| `errorMessage` | `string` | -- | Error text shown below the field; also activates error styling when truthy |
|
|
694
|
+
| `debounce` | `string \| number` | -- | Delay in ms before emitting model updates |
|
|
695
|
+
| `maxlength` | `string \| number` | `"1024"` | Maximum character length |
|
|
696
|
+
| `step` | `string` | `"1"` | Step granularity for number inputs |
|
|
697
|
+
| `size` | `"default" \| "small"` | `"default"` | Field height variant (36px / 32px) |
|
|
698
|
+
| `multilanguage` | `boolean` | `false` | Shows a language indicator badge on the label |
|
|
699
|
+
| `currentLanguage` | `string` | -- | Language code to display in the multilanguage badge |
|
|
700
|
+
| `datePickerOptions` | `VueDatePickerProps` | -- | Options forwarded to VcDatePicker (only when `type` is `date` or `datetime-local`) |
|
|
700
701
|
|
|
701
702
|
### Events
|
|
702
703
|
|
package/runtime/knowledge/docs/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md
CHANGED
|
@@ -268,6 +268,7 @@ Replace the default dropdown toggle with a custom element using the `button` slo
|
|
|
268
268
|
| `name` | `string` | -- | HTML name attribute for the input |
|
|
269
269
|
| `multilanguage` | `boolean` | `false` | Enable multilanguage editing (forwarded to VcSelect) |
|
|
270
270
|
| `currentLanguage` | `string` | -- | Active language for multilanguage mode (forwarded to VcSelect) |
|
|
271
|
+
| `ariaLabel` | `string` | -- | Accessible name for the value input when no visible `label` is provided |
|
|
271
272
|
|
|
272
273
|
## Events
|
|
273
274
|
|
|
@@ -251,6 +251,7 @@ const description = ref<string>("");
|
|
|
251
251
|
| `name` | `string` | `"Field"` | Field name used for validation/id generation (not applied as an HTML name attribute on the textarea) |
|
|
252
252
|
| `multilanguage` | `boolean` | `false` | Shows language badge on the label |
|
|
253
253
|
| `currentLanguage` | `string` | -- | Language code displayed in the badge |
|
|
254
|
+
| `ariaLabel` | `string` | -- | Accessible name used when no visible `label` is provided |
|
|
254
255
|
|
|
255
256
|
## Events
|
|
256
257
|
|
|
@@ -46,25 +46,26 @@ The prop names match the `DynamicObjectProperty` shape returned by the platform
|
|
|
46
46
|
|
|
47
47
|
## Key Props
|
|
48
48
|
|
|
49
|
-
| Prop | Type | Default | Description
|
|
50
|
-
| -------------------- | ---------------------------- | ---------- |
|
|
51
|
-
| `property` | `T` | _required_ | Property object with `id` and metadata
|
|
52
|
-
| `modelValue` | `any` | _required_ | Current property value (v-model)
|
|
53
|
-
| `valueType` | `string` | _required_ | Type: ShortText, LongText, Number, Integer, DateTime, Boolean, Measure, Color
|
|
54
|
-
| `name` | `string` | _required_ | Property name for display and field identification
|
|
55
|
-
| `required` | `boolean` | _required_ | Whether the field is required
|
|
56
|
-
| `disabled` | `boolean` | `false` | Disables the input
|
|
57
|
-
| `dictionary` | `boolean` | `false` | Uses VcSelect/VcMultivalue with options
|
|
58
|
-
| `multivalue` | `boolean` | `false` | Supports multiple values
|
|
59
|
-
| `multilanguage` | `boolean` | `false` | Supports localized values
|
|
60
|
-
| `currentLanguage` | `string` | - | Active locale used for localized values
|
|
61
|
-
| `optionsGetter` | `Function` | _required_ | Async loader for dictionary options, called as `(propertyId, keyword?, locale?)`
|
|
62
|
-
| `measurementsGetter` | `Function` | - | Async loader for measurement units
|
|
63
|
-
| `optionsValue` | `string` | `"id"` | Field on each option used as its value (VcSelect mapping)
|
|
64
|
-
| `optionsLabel` | `string` | `"value"` | Inert. The option label is fixed to `"value"` when `multilanguage` is true and `"alias"` otherwise; only `optionsValue` is honored for VcSelect mapping.
|
|
65
|
-
| `displayNames` | `{ name?; languageCode? }[]` | - | Localized display names used to resolve the field label per locale
|
|
66
|
-
| `placeholder` | `string` | - | Placeholder text for the input
|
|
67
|
-
| `rules` | `object` | - | Validation rules: `{ min, max, regex }`
|
|
49
|
+
| Prop | Type | Default | Description |
|
|
50
|
+
| -------------------- | ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `property` | `T` | _required_ | Property object with `id` and metadata |
|
|
52
|
+
| `modelValue` | `any` | _required_ | Current property value (v-model) |
|
|
53
|
+
| `valueType` | `string` | _required_ | Type: ShortText, LongText, Number, Integer, DateTime, Boolean, Measure, Color |
|
|
54
|
+
| `name` | `string` | _required_ | Property name for display and field identification |
|
|
55
|
+
| `required` | `boolean` | _required_ | Whether the field is required |
|
|
56
|
+
| `disabled` | `boolean` | `false` | Disables the input |
|
|
57
|
+
| `dictionary` | `boolean` | `false` | Uses VcSelect/VcMultivalue with options |
|
|
58
|
+
| `multivalue` | `boolean` | `false` | Supports multiple values |
|
|
59
|
+
| `multilanguage` | `boolean` | `false` | Supports localized values |
|
|
60
|
+
| `currentLanguage` | `string` | - | Active locale used for localized values |
|
|
61
|
+
| `optionsGetter` | `Function` | _required_ | Async loader for dictionary options, called as `(propertyId, keyword?, locale?)` |
|
|
62
|
+
| `measurementsGetter` | `Function` | - | Async loader for measurement units |
|
|
63
|
+
| `optionsValue` | `string` | `"id"` | Field on each option used as its value (VcSelect mapping) |
|
|
64
|
+
| `optionsLabel` | `string` | `"value"` | Inert. The option label is fixed to `"value"` when `multilanguage` is true and `"alias"` otherwise; only `optionsValue` is honored for VcSelect mapping. |
|
|
65
|
+
| `displayNames` | `{ name?; languageCode? }[]` | - | Localized display names used to resolve the field label per locale |
|
|
66
|
+
| `placeholder` | `string` | - | Placeholder text for the input |
|
|
67
|
+
| `rules` | `object` | - | Validation rules: `{ min, max, regex }` |
|
|
68
|
+
| `hideLabel` | `boolean` | `false` | Hides the control's own visible label so the consumer can render its own label row (e.g. to place an action next to the property name). Validation and the placeholder fallback are unaffected. The display name is forwarded as the control's accessible name for nine control families: short text, number, integer, long text, boolean, datetime, colour, Measure, and the fallback used for an unrecognized `valueType`. Dictionary and multivalue properties (VcSelect, VcMultivalue) are **not** covered — their focusable triggers carry no accessible name, so those properties still need a visible label. |
|
|
68
69
|
|
|
69
70
|
::storybook id="data-display-vcdynamicproperty--property-form" height="500"
|
|
70
71
|
|