@bitakit/core 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +382 -0
- package/discovery/entries.mjs +124 -0
- package/discovery/generate.mjs +327 -0
- package/discovery/host.mjs +12 -0
- package/discovery/index.d.ts +41 -0
- package/discovery/index.mjs +4 -0
- package/discovery/modules.mjs +13 -0
- package/discovery/packages.mjs +57 -0
- package/discovery/watch.mjs +23 -0
- package/dist/actions/action-list.d.ts +69 -0
- package/dist/actions/action-list.js +247 -0
- package/dist/actions/action.d.ts +96 -0
- package/dist/actions/action.js +145 -0
- package/dist/actions/base/url-action.d.ts +8 -0
- package/dist/actions/base/url-action.js +15 -0
- package/dist/actions/core.d.ts +14 -0
- package/dist/actions/core.js +8 -0
- package/dist/actions/dependencies.d.ts +8 -0
- package/dist/actions/dependencies.js +34 -0
- package/dist/actions/execution.d.ts +4 -0
- package/dist/actions/execution.js +64 -0
- package/dist/actions/feedback.d.ts +17 -0
- package/dist/actions/feedback.js +21 -0
- package/dist/actions/groups.d.ts +13 -0
- package/dist/actions/groups.js +21 -0
- package/dist/actions/instance-bindings.d.ts +16 -0
- package/dist/actions/instance-bindings.js +93 -0
- package/dist/actions/interceptors.d.ts +24 -0
- package/dist/actions/interceptors.js +42 -0
- package/dist/actions/navigation.d.ts +12 -0
- package/dist/actions/navigation.js +42 -0
- package/dist/actions/reference.d.ts +17 -0
- package/dist/actions/reference.js +39 -0
- package/dist/actions/state.d.ts +11 -0
- package/dist/actions/state.js +8 -0
- package/dist/actions/types.d.ts +99 -0
- package/dist/actions/types.js +1 -0
- package/dist/app/access.d.ts +4 -0
- package/dist/app/access.js +85 -0
- package/dist/app/action-access.d.ts +4 -0
- package/dist/app/action-access.js +20 -0
- package/dist/app/service-error.d.ts +8 -0
- package/dist/app/service-error.js +19 -0
- package/dist/app/types.d.ts +47 -0
- package/dist/app/types.js +1 -0
- package/dist/config-service.d.ts +49 -0
- package/dist/config-service.js +83 -0
- package/dist/configuration.d.ts +4 -0
- package/dist/configuration.js +42 -0
- package/dist/confirmation.d.ts +14 -0
- package/dist/confirmation.js +26 -0
- package/dist/contracts.d.ts +27 -0
- package/dist/contracts.js +3 -0
- package/dist/contribution-origin.d.ts +3 -0
- package/dist/contribution-origin.js +13 -0
- package/dist/contributions/command.d.ts +8 -0
- package/dist/contributions/command.js +50 -0
- package/dist/contributions/dialog.d.ts +8 -0
- package/dist/contributions/dialog.js +18 -0
- package/dist/contributions/form.d.ts +10 -0
- package/dist/contributions/form.js +67 -0
- package/dist/contributions/host.d.ts +40 -0
- package/dist/contributions/host.js +1 -0
- package/dist/contributions/index.d.ts +26 -0
- package/dist/contributions/index.js +18 -0
- package/dist/contributions/native.d.ts +11 -0
- package/dist/contributions/native.js +87 -0
- package/dist/contributions/shared.d.ts +19 -0
- package/dist/contributions/shared.js +48 -0
- package/dist/contributions/stateful-action.d.ts +29 -0
- package/dist/contributions/stateful-action.js +33 -0
- package/dist/conventions.d.ts +4 -0
- package/dist/conventions.js +38 -0
- package/dist/core.d.ts +21 -0
- package/dist/core.js +18 -0
- package/dist/definitions.d.ts +356 -0
- package/dist/definitions.js +60 -0
- package/dist/discovered.d.ts +49 -0
- package/dist/discovered.js +120 -0
- package/dist/interceptors/service-observers.d.ts +3 -0
- package/dist/interceptors/service-observers.js +80 -0
- package/dist/interceptors/service.d.ts +37 -0
- package/dist/interceptors/service.js +7 -0
- package/dist/messages.d.ts +9 -0
- package/dist/messages.js +21 -0
- package/dist/metadata.d.ts +3 -0
- package/dist/metadata.js +13 -0
- package/dist/pages.d.ts +8 -0
- package/dist/pages.js +22 -0
- package/dist/presentation.d.ts +4 -0
- package/dist/presentation.js +1 -0
- package/dist/replacements.d.ts +22 -0
- package/dist/replacements.js +54 -0
- package/dist/runtime.d.ts +88 -0
- package/dist/runtime.js +445 -0
- package/dist/scope.d.ts +34 -0
- package/dist/scope.js +78 -0
- package/dist/service-key.d.ts +13 -0
- package/dist/service-key.js +14 -0
- package/dist/services.d.ts +6 -0
- package/dist/services.js +53 -0
- package/dist/translation.d.ts +13 -0
- package/dist/translation.js +43 -0
- package/dist/validation.d.ts +2 -0
- package/dist/validation.js +16 -0
- package/docs/file-contributions.md +161 -0
- package/package.json +48 -0
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
import { ActionStatus } from './state.js';
|
|
2
|
+
import { freezeGroups } from './groups.js';
|
|
3
|
+
import { ExecutionLifecycle } from './interceptors.js';
|
|
4
|
+
import { createExecutor } from './execution.js';
|
|
5
|
+
import { createStore } from 'zustand/vanilla';
|
|
6
|
+
import { NavigationHost, safeHref } from './navigation.js';
|
|
7
|
+
import { InstanceBindings } from './instance-bindings.js';
|
|
8
|
+
import { Action } from './action.js';
|
|
9
|
+
import { affectedActions, dependencyEnabled, freezeDependencies } from './dependencies.js';
|
|
10
|
+
/** No global state. This can also be used outside React. */
|
|
11
|
+
export function createActionList(initialActions = [], options = {}) {
|
|
12
|
+
const environment = options.environment ?? new NavigationHost();
|
|
13
|
+
const store = createStore(() => ({ actions: Object.create(null) }));
|
|
14
|
+
const lifecycle = new ExecutionLifecycle();
|
|
15
|
+
const owners = new Map();
|
|
16
|
+
const placements = new Map();
|
|
17
|
+
let disposed = false;
|
|
18
|
+
const bindings = new InstanceBindings(environment);
|
|
19
|
+
let definitions = Object.create(null);
|
|
20
|
+
const source = (id) => (Object.hasOwn(definitions, id) ? definitions[id] : undefined);
|
|
21
|
+
function publish(changed) {
|
|
22
|
+
const affected = changed
|
|
23
|
+
? affectedActions(definitions, changed)
|
|
24
|
+
: new Set(Object.keys(definitions));
|
|
25
|
+
const previous = store.getState().actions;
|
|
26
|
+
const next = Object.create(null);
|
|
27
|
+
const cache = new Map();
|
|
28
|
+
const prerequisiteEnabled = (action) => {
|
|
29
|
+
// Unbound snapshots have no invocation input; contextual resolve() evaluates with input below.
|
|
30
|
+
try {
|
|
31
|
+
return action.enabled && (action.resolve?.(undefined)?.enabled ?? true);
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
return false;
|
|
35
|
+
}
|
|
36
|
+
};
|
|
37
|
+
for (const action of Object.values(definitions)) {
|
|
38
|
+
next[action.id] =
|
|
39
|
+
!affected.has(action.id) && previous[action.id]
|
|
40
|
+
? previous[action.id]
|
|
41
|
+
: Object.freeze({
|
|
42
|
+
...action,
|
|
43
|
+
...options.project?.(action),
|
|
44
|
+
enabled: action.enabled &&
|
|
45
|
+
(action.dependsOn ?? []).every((id) => dependencyEnabled(id, definitions, prerequisiteEnabled, new Set([action.id]), cache)),
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
store.setState({ actions: next });
|
|
49
|
+
}
|
|
50
|
+
function setPending(id, pending, status, error) {
|
|
51
|
+
const action = source(id);
|
|
52
|
+
if (!action)
|
|
53
|
+
return;
|
|
54
|
+
definitions = {
|
|
55
|
+
...definitions,
|
|
56
|
+
[id]: Object.freeze({ ...action, pending, status: status ?? action.status, error }),
|
|
57
|
+
};
|
|
58
|
+
publish(id);
|
|
59
|
+
}
|
|
60
|
+
const get = (id) => {
|
|
61
|
+
const { actions } = store.getState();
|
|
62
|
+
return Object.hasOwn(actions, id) ? actions[id] : undefined;
|
|
63
|
+
};
|
|
64
|
+
function resolve(id, input) {
|
|
65
|
+
const action = source(id);
|
|
66
|
+
if (!action)
|
|
67
|
+
return undefined;
|
|
68
|
+
const presentation = action.resolve?.(input);
|
|
69
|
+
const resolved = {
|
|
70
|
+
...action,
|
|
71
|
+
...presentation,
|
|
72
|
+
id: action.id,
|
|
73
|
+
groups: action.groups,
|
|
74
|
+
pending: action.pending,
|
|
75
|
+
execute: action.execute,
|
|
76
|
+
resolve: action.resolve,
|
|
77
|
+
enabled: dependencyEnabled(id, definitions, (item) => item.enabled &&
|
|
78
|
+
(item.id === id
|
|
79
|
+
? (presentation?.enabled ?? true)
|
|
80
|
+
: (item.resolve?.(input)?.enabled ?? true))),
|
|
81
|
+
visible: action.visible && (presentation?.visible ?? true),
|
|
82
|
+
};
|
|
83
|
+
return Object.freeze({ ...resolved, ...options.project?.(resolved) });
|
|
84
|
+
}
|
|
85
|
+
function update(id, patch) {
|
|
86
|
+
const current = source(id);
|
|
87
|
+
if (!current || disposed)
|
|
88
|
+
return false;
|
|
89
|
+
// Preserve identity and runtime state even if untyped callers pass extra fields.
|
|
90
|
+
const next = Object.freeze({
|
|
91
|
+
...current,
|
|
92
|
+
...patch,
|
|
93
|
+
id,
|
|
94
|
+
pending: current.pending,
|
|
95
|
+
status: current.status,
|
|
96
|
+
error: current.error,
|
|
97
|
+
groups: freezeGroups(patch.groups ?? current.groups),
|
|
98
|
+
dependsOn: freezeDependencies(Object.hasOwn(patch, 'dependsOn') ? patch.dependsOn : current.dependsOn),
|
|
99
|
+
enabled: patch.enabled ?? current.enabled,
|
|
100
|
+
visible: patch.visible ?? current.visible,
|
|
101
|
+
});
|
|
102
|
+
if (next.href !== undefined && !safeHref(next.href))
|
|
103
|
+
throw new Error('Invalid navigation target.');
|
|
104
|
+
options.validate?.(next, store.getState().actions);
|
|
105
|
+
bindings.apply(id, patch);
|
|
106
|
+
definitions = { ...definitions, [id]: next };
|
|
107
|
+
publish(id);
|
|
108
|
+
return true;
|
|
109
|
+
}
|
|
110
|
+
function register(definition, placement = {}) {
|
|
111
|
+
if (definition instanceof Action) {
|
|
112
|
+
if (!definition.id)
|
|
113
|
+
throw new Error('Use add(id, action) for an action without an ID.');
|
|
114
|
+
return add(definition.id, definition, placement);
|
|
115
|
+
}
|
|
116
|
+
if (disposed)
|
|
117
|
+
throw new Error('Action list has been disposed.');
|
|
118
|
+
if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/.test(definition.id)) {
|
|
119
|
+
throw new Error('Action IDs must be nonempty and contain letters, numbers, dots, underscores, colons, slashes or hyphens.');
|
|
120
|
+
}
|
|
121
|
+
const { id } = definition;
|
|
122
|
+
if (owners.has(id))
|
|
123
|
+
throw new Error(`Action "${id}" is already registered.`);
|
|
124
|
+
const owner = Symbol(id);
|
|
125
|
+
const action = Object.freeze({
|
|
126
|
+
...definition,
|
|
127
|
+
...placement,
|
|
128
|
+
groups: freezeGroups(placement.groups ?? definition.groups),
|
|
129
|
+
dependsOn: freezeDependencies(definition.dependsOn),
|
|
130
|
+
enabled: definition.enabled ?? true,
|
|
131
|
+
visible: definition.visible ?? true,
|
|
132
|
+
pending: false,
|
|
133
|
+
status: ActionStatus.Idle,
|
|
134
|
+
state: definition.initialState === undefined
|
|
135
|
+
? undefined
|
|
136
|
+
: Object.freeze(structuredClone(definition.initialState)),
|
|
137
|
+
error: undefined,
|
|
138
|
+
});
|
|
139
|
+
if (action.href !== undefined && !safeHref(action.href))
|
|
140
|
+
throw new Error('Invalid navigation target.');
|
|
141
|
+
options.validate?.(action, store.getState().actions);
|
|
142
|
+
owners.set(id, owner);
|
|
143
|
+
definitions = { ...definitions, [id]: action };
|
|
144
|
+
publish(id);
|
|
145
|
+
return {
|
|
146
|
+
update: (patch) => owners.get(id) === owner && update(id, patch),
|
|
147
|
+
unregister() {
|
|
148
|
+
if (owners.get(id) !== owner)
|
|
149
|
+
return;
|
|
150
|
+
owners.delete(id);
|
|
151
|
+
for (const key of placements.keys())
|
|
152
|
+
if (key.startsWith(`${id}\u0000`))
|
|
153
|
+
placements.delete(key);
|
|
154
|
+
const next = { ...definitions };
|
|
155
|
+
delete next[id];
|
|
156
|
+
definitions = next;
|
|
157
|
+
publish(id);
|
|
158
|
+
},
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
function add(id, action, placement = {}) {
|
|
162
|
+
const definition = {
|
|
163
|
+
...action.snapshot(),
|
|
164
|
+
id,
|
|
165
|
+
resolve: (input) => action.resolve(input),
|
|
166
|
+
// Class actions receive the same invocation context as plain handlers.
|
|
167
|
+
execute: (context) => action.execute(context.input, context),
|
|
168
|
+
};
|
|
169
|
+
const registration = register(definition, placement);
|
|
170
|
+
return {
|
|
171
|
+
update: registration.update,
|
|
172
|
+
unregister: bindings.attach(id, action, registration),
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
const execute = createExecutor(setPending, owners, environment, get, resolve, update, lifecycle);
|
|
176
|
+
function dispose() {
|
|
177
|
+
if (disposed)
|
|
178
|
+
return;
|
|
179
|
+
disposed = true;
|
|
180
|
+
bindings.dispose();
|
|
181
|
+
lifecycle.clear();
|
|
182
|
+
owners.clear();
|
|
183
|
+
placements.clear();
|
|
184
|
+
definitions = Object.create(null);
|
|
185
|
+
store.setState({ actions: Object.create(null) });
|
|
186
|
+
}
|
|
187
|
+
for (const action of initialActions)
|
|
188
|
+
register(action);
|
|
189
|
+
let initialState;
|
|
190
|
+
return {
|
|
191
|
+
get,
|
|
192
|
+
resolve,
|
|
193
|
+
/** Re-evaluate host presentation after a locale or external context change. */
|
|
194
|
+
refresh: () => {
|
|
195
|
+
if (!disposed)
|
|
196
|
+
publish();
|
|
197
|
+
},
|
|
198
|
+
use: (interceptor) => lifecycle.use(interceptor),
|
|
199
|
+
subscribeExecution: (listener) => lifecycle.subscribe(listener),
|
|
200
|
+
add,
|
|
201
|
+
register,
|
|
202
|
+
/** Attach an existing action without duplicating it; cleanup owns only this placement. */
|
|
203
|
+
attach(id, group) {
|
|
204
|
+
const action = get(id);
|
|
205
|
+
const owner = owners.get(id);
|
|
206
|
+
if (!action || !owner)
|
|
207
|
+
throw new Error(`Unknown action "${id}".`);
|
|
208
|
+
const key = `${id}\u0000${group.id}`;
|
|
209
|
+
let entry = placements.get(key);
|
|
210
|
+
if (!entry) {
|
|
211
|
+
entry = {
|
|
212
|
+
count: 0,
|
|
213
|
+
original: action.groups?.some((item) => item.id === group.id) ?? false,
|
|
214
|
+
};
|
|
215
|
+
if (!entry.original)
|
|
216
|
+
update(id, { groups: [...(action.groups ?? []), group] });
|
|
217
|
+
placements.set(key, entry);
|
|
218
|
+
}
|
|
219
|
+
entry.count++;
|
|
220
|
+
const owned = entry;
|
|
221
|
+
let active = true;
|
|
222
|
+
return () => {
|
|
223
|
+
if (!active)
|
|
224
|
+
return;
|
|
225
|
+
active = false;
|
|
226
|
+
if (owners.get(id) !== owner || placements.get(key) !== owned)
|
|
227
|
+
return;
|
|
228
|
+
if (--owned.count)
|
|
229
|
+
return;
|
|
230
|
+
placements.delete(key);
|
|
231
|
+
if (!owned.original)
|
|
232
|
+
update(id, {
|
|
233
|
+
groups: get(id)?.groups?.filter((item) => item.id !== group.id),
|
|
234
|
+
});
|
|
235
|
+
};
|
|
236
|
+
},
|
|
237
|
+
update,
|
|
238
|
+
/** Known IDs from ActionMap type their input and result; other IDs stay untyped. */
|
|
239
|
+
execute: execute,
|
|
240
|
+
dispose,
|
|
241
|
+
mount: (navigate) => bindings.mount(navigate),
|
|
242
|
+
/** Read-only subscription surface; mutation stays in the methods above. */
|
|
243
|
+
getState: store.getState,
|
|
244
|
+
getInitialState: () => (initialState ??= store.getState()),
|
|
245
|
+
subscribe: store.subscribe,
|
|
246
|
+
};
|
|
247
|
+
}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { Feedback } from './feedback.js';
|
|
2
|
+
import type { ActionContext, ActionShortcut, ActionDefinition, ActionIcon, ActionPresentation } from './types.js';
|
|
3
|
+
/** Context handed to the `success` feedback of a class-based action. */
|
|
4
|
+
export type ActionOutcome<Input, Result> = {
|
|
5
|
+
result: Result;
|
|
6
|
+
input: Input;
|
|
7
|
+
};
|
|
8
|
+
/** Context handed to the `failure` feedback of a class-based action. */
|
|
9
|
+
export type ActionError<Input> = {
|
|
10
|
+
error: unknown;
|
|
11
|
+
input: Input;
|
|
12
|
+
};
|
|
13
|
+
export type ActionOptions<Input, Result = unknown> = Omit<ActionDefinition, 'id' | 'execute' | 'resolve' | 'shortcut'> & {
|
|
14
|
+
id?: string;
|
|
15
|
+
shortcut?: ActionShortcut<Input>;
|
|
16
|
+
value?: Input;
|
|
17
|
+
execute?: (input: Input, context?: ActionContext<Input>) => Result | Promise<Result>;
|
|
18
|
+
/** Optional outcome feedback, resolved and displayed by the foundation runtime. */
|
|
19
|
+
success?: Feedback<ActionOutcome<Input, Result>>;
|
|
20
|
+
failure?: Feedback<ActionError<Input>>;
|
|
21
|
+
};
|
|
22
|
+
/** Reusable behavior and observable presentation state. No registration or UI. */
|
|
23
|
+
export declare class Action<Input = void, Result = unknown> {
|
|
24
|
+
readonly id?: string;
|
|
25
|
+
/**
|
|
26
|
+
* Opt-in feedback for runtime-registered class actions. Undefined keeps the raw error for the
|
|
27
|
+
* caller and shows no success message, matching direct ActionList usage.
|
|
28
|
+
*/
|
|
29
|
+
success?: Feedback<ActionOutcome<Input, Result>>;
|
|
30
|
+
failure?: Feedback<ActionError<Input>>;
|
|
31
|
+
private navigator?;
|
|
32
|
+
private state;
|
|
33
|
+
private listeners;
|
|
34
|
+
private handler?;
|
|
35
|
+
constructor(options?: ActionOptions<Input, Result>);
|
|
36
|
+
/** The list supplies the invocation context; subclasses may ignore it. */
|
|
37
|
+
execute(input: Input, context?: ActionContext<Input>): unknown;
|
|
38
|
+
isEnabled(_input: Input): boolean;
|
|
39
|
+
isVisible(_input: Input): boolean;
|
|
40
|
+
/** Derived per invocation; never written into shared class state. */
|
|
41
|
+
getPresentation(_input: Input): ActionPresentation;
|
|
42
|
+
resolve(input: Input): ActionPresentation;
|
|
43
|
+
get shortcut(): ActionShortcut<Input> | undefined;
|
|
44
|
+
set shortcut(value: ActionShortcut<Input> | undefined);
|
|
45
|
+
get tooltip(): string | undefined;
|
|
46
|
+
set tooltip(value: string | undefined);
|
|
47
|
+
/** Supplied once by the provider; subclasses use the same navigation service. */
|
|
48
|
+
bindNavigation(navigate: (href: string) => void): void;
|
|
49
|
+
protected navigate(href: string): void;
|
|
50
|
+
/** Optional external-state subscription, owned by the mounted list. */
|
|
51
|
+
connect(): void | (() => void);
|
|
52
|
+
subscribe(listener: () => void): () => void;
|
|
53
|
+
private set;
|
|
54
|
+
get title(): string;
|
|
55
|
+
set title(value: string);
|
|
56
|
+
get description(): string | undefined;
|
|
57
|
+
set description(value: string | undefined);
|
|
58
|
+
get icon(): ActionIcon | undefined;
|
|
59
|
+
set icon(value: ActionIcon | undefined);
|
|
60
|
+
get href(): string | undefined;
|
|
61
|
+
set href(value: string | undefined);
|
|
62
|
+
get enabled(): boolean;
|
|
63
|
+
set enabled(value: boolean);
|
|
64
|
+
get visible(): boolean;
|
|
65
|
+
get dependsOn(): readonly string[] | undefined;
|
|
66
|
+
set dependsOn(value: readonly string[] | undefined);
|
|
67
|
+
set visible(value: boolean);
|
|
68
|
+
get checked(): boolean | undefined;
|
|
69
|
+
set checked(value: boolean | undefined);
|
|
70
|
+
get value(): Input | undefined;
|
|
71
|
+
set value(value: Input | undefined);
|
|
72
|
+
get metadata(): unknown;
|
|
73
|
+
set metadata(value: unknown);
|
|
74
|
+
snapshot(): {
|
|
75
|
+
enabled?: boolean | undefined;
|
|
76
|
+
visible?: boolean | undefined;
|
|
77
|
+
id?: string | undefined;
|
|
78
|
+
title: string;
|
|
79
|
+
description?: string | undefined;
|
|
80
|
+
tooltip?: string | undefined;
|
|
81
|
+
shortcut?: ActionShortcut<Input> | undefined;
|
|
82
|
+
variant?: "default" | "destructive" | undefined;
|
|
83
|
+
icon?: ActionIcon;
|
|
84
|
+
href?: string | undefined;
|
|
85
|
+
dependsOn?: readonly string[] | undefined;
|
|
86
|
+
checked?: boolean | undefined;
|
|
87
|
+
value?: Input | undefined;
|
|
88
|
+
initialState?: object | undefined;
|
|
89
|
+
state?: unknown;
|
|
90
|
+
internal?: boolean | undefined;
|
|
91
|
+
metadata?: unknown;
|
|
92
|
+
groups?: readonly import("./groups.js").ActionGroup<any>[] | undefined;
|
|
93
|
+
order?: number | undefined;
|
|
94
|
+
dividerBefore?: boolean | undefined;
|
|
95
|
+
};
|
|
96
|
+
}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { safeHref } from './navigation.js';
|
|
2
|
+
/** Reusable behavior and observable presentation state. No registration or UI. */
|
|
3
|
+
export class Action {
|
|
4
|
+
id;
|
|
5
|
+
/**
|
|
6
|
+
* Opt-in feedback for runtime-registered class actions. Undefined keeps the raw error for the
|
|
7
|
+
* caller and shows no success message, matching direct ActionList usage.
|
|
8
|
+
*/
|
|
9
|
+
success;
|
|
10
|
+
failure;
|
|
11
|
+
navigator;
|
|
12
|
+
state;
|
|
13
|
+
listeners = new Set();
|
|
14
|
+
handler;
|
|
15
|
+
constructor(options = { title: '' }) {
|
|
16
|
+
const { execute, success, failure, ...state } = options;
|
|
17
|
+
this.id = options.id;
|
|
18
|
+
this.state = { enabled: true, visible: true, ...state };
|
|
19
|
+
this.handler = execute;
|
|
20
|
+
this.success = success;
|
|
21
|
+
this.failure = failure;
|
|
22
|
+
}
|
|
23
|
+
/** The list supplies the invocation context; subclasses may ignore it. */
|
|
24
|
+
execute(input, context) {
|
|
25
|
+
return this.handler?.(input, context);
|
|
26
|
+
}
|
|
27
|
+
isEnabled(_input) {
|
|
28
|
+
return true;
|
|
29
|
+
}
|
|
30
|
+
isVisible(_input) {
|
|
31
|
+
return true;
|
|
32
|
+
}
|
|
33
|
+
/** Derived per invocation; never written into shared class state. */
|
|
34
|
+
getPresentation(_input) {
|
|
35
|
+
return {};
|
|
36
|
+
}
|
|
37
|
+
resolve(input) {
|
|
38
|
+
return {
|
|
39
|
+
...this.getPresentation(input),
|
|
40
|
+
enabled: this.isEnabled(input),
|
|
41
|
+
visible: this.isVisible(input),
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
get shortcut() {
|
|
45
|
+
return this.state.shortcut;
|
|
46
|
+
}
|
|
47
|
+
set shortcut(value) {
|
|
48
|
+
this.set('shortcut', value);
|
|
49
|
+
}
|
|
50
|
+
get tooltip() {
|
|
51
|
+
return this.state.tooltip;
|
|
52
|
+
}
|
|
53
|
+
set tooltip(value) {
|
|
54
|
+
this.set('tooltip', value);
|
|
55
|
+
}
|
|
56
|
+
/** Supplied once by the provider; subclasses use the same navigation service. */
|
|
57
|
+
bindNavigation(navigate) {
|
|
58
|
+
this.navigator = navigate;
|
|
59
|
+
}
|
|
60
|
+
navigate(href) {
|
|
61
|
+
if (!safeHref(href))
|
|
62
|
+
throw new Error('Invalid navigation target.');
|
|
63
|
+
if (this.navigator)
|
|
64
|
+
this.navigator(href);
|
|
65
|
+
else
|
|
66
|
+
throw new Error('Navigation requires a mounted provider.');
|
|
67
|
+
}
|
|
68
|
+
/** Optional external-state subscription, owned by the mounted list. */
|
|
69
|
+
connect() { }
|
|
70
|
+
subscribe(listener) {
|
|
71
|
+
this.listeners.add(listener);
|
|
72
|
+
return () => {
|
|
73
|
+
this.listeners.delete(listener);
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
set(key, value) {
|
|
77
|
+
if (Object.is(this.state[key], value))
|
|
78
|
+
return;
|
|
79
|
+
this.state = { ...this.state, [key]: value };
|
|
80
|
+
this.listeners.forEach((listener) => listener());
|
|
81
|
+
}
|
|
82
|
+
get title() {
|
|
83
|
+
return this.state.title;
|
|
84
|
+
}
|
|
85
|
+
set title(value) {
|
|
86
|
+
this.set('title', value);
|
|
87
|
+
}
|
|
88
|
+
get description() {
|
|
89
|
+
return this.state.description;
|
|
90
|
+
}
|
|
91
|
+
set description(value) {
|
|
92
|
+
this.set('description', value);
|
|
93
|
+
}
|
|
94
|
+
get icon() {
|
|
95
|
+
return this.state.icon;
|
|
96
|
+
}
|
|
97
|
+
set icon(value) {
|
|
98
|
+
this.set('icon', value);
|
|
99
|
+
}
|
|
100
|
+
get href() {
|
|
101
|
+
return this.state.href;
|
|
102
|
+
}
|
|
103
|
+
set href(value) {
|
|
104
|
+
this.set('href', value);
|
|
105
|
+
}
|
|
106
|
+
get enabled() {
|
|
107
|
+
return this.state.enabled ?? true;
|
|
108
|
+
}
|
|
109
|
+
set enabled(value) {
|
|
110
|
+
this.set('enabled', value);
|
|
111
|
+
}
|
|
112
|
+
get visible() {
|
|
113
|
+
return this.state.visible ?? true;
|
|
114
|
+
}
|
|
115
|
+
get dependsOn() {
|
|
116
|
+
return this.state.dependsOn;
|
|
117
|
+
}
|
|
118
|
+
set dependsOn(value) {
|
|
119
|
+
this.set('dependsOn', value);
|
|
120
|
+
}
|
|
121
|
+
set visible(value) {
|
|
122
|
+
this.set('visible', value);
|
|
123
|
+
}
|
|
124
|
+
get checked() {
|
|
125
|
+
return this.state.checked;
|
|
126
|
+
}
|
|
127
|
+
set checked(value) {
|
|
128
|
+
this.set('checked', value);
|
|
129
|
+
}
|
|
130
|
+
get value() {
|
|
131
|
+
return this.state.value;
|
|
132
|
+
}
|
|
133
|
+
set value(value) {
|
|
134
|
+
this.set('value', value);
|
|
135
|
+
}
|
|
136
|
+
get metadata() {
|
|
137
|
+
return this.state.metadata;
|
|
138
|
+
}
|
|
139
|
+
set metadata(value) {
|
|
140
|
+
this.set('metadata', value);
|
|
141
|
+
}
|
|
142
|
+
snapshot() {
|
|
143
|
+
return { ...this.state };
|
|
144
|
+
}
|
|
145
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { Action, type ActionOptions } from '../action.js';
|
|
2
|
+
export type URLActionOptions = ActionOptions<void> & {
|
|
3
|
+
href: string;
|
|
4
|
+
};
|
|
5
|
+
export declare class URLAction extends Action<void> {
|
|
6
|
+
constructor(url: string | URLActionOptions, options?: ActionOptions<void>);
|
|
7
|
+
execute(): void;
|
|
8
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { Action } from '../action.js';
|
|
2
|
+
import { safeHref } from '../navigation.js';
|
|
3
|
+
export class URLAction extends Action {
|
|
4
|
+
constructor(url, options = { title: '' }) {
|
|
5
|
+
const resolved = typeof url === 'string' ? { ...options, href: url } : url;
|
|
6
|
+
if (!safeHref(resolved.href))
|
|
7
|
+
throw new Error('Invalid navigation target.');
|
|
8
|
+
super({ ...resolved, value: undefined });
|
|
9
|
+
}
|
|
10
|
+
execute() {
|
|
11
|
+
if (!this.href)
|
|
12
|
+
throw new Error('A URL is required.');
|
|
13
|
+
this.navigate(this.href);
|
|
14
|
+
}
|
|
15
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export { Action } from './action.js';
|
|
2
|
+
export { resolveActionId, type ActionReference } from './reference.js';
|
|
3
|
+
export type { ActionOptions, ActionOutcome, ActionError } from './action.js';
|
|
4
|
+
export { createActionList } from './action-list.js';
|
|
5
|
+
export type { ActionList } from './action-list.js';
|
|
6
|
+
export type * from './types.js';
|
|
7
|
+
export { URLAction } from './base/url-action.js';
|
|
8
|
+
export { NavigationHost, safeHref } from './navigation.js';
|
|
9
|
+
export { ActionGroup } from './groups.js';
|
|
10
|
+
export type { RegistrationOptions } from './groups.js';
|
|
11
|
+
export type { ActionInterceptor, ExecutionEvent } from './interceptors.js';
|
|
12
|
+
export { ActionFailure } from './feedback.js';
|
|
13
|
+
export type { Feedback, FeedbackMessage, FeedbackResult, MessageValues } from './feedback.js';
|
|
14
|
+
export { ActionStatus, type ActionStateValue } from './state.js';
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export { Action } from './action.js';
|
|
2
|
+
export { resolveActionId } from './reference.js';
|
|
3
|
+
export { createActionList } from './action-list.js';
|
|
4
|
+
export { URLAction } from './base/url-action.js';
|
|
5
|
+
export { NavigationHost, safeHref } from './navigation.js';
|
|
6
|
+
export { ActionGroup } from './groups.js';
|
|
7
|
+
export { ActionFailure } from './feedback.js';
|
|
8
|
+
export { ActionStatus } from './state.js';
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { ActionSnapshot } from './types.js';
|
|
2
|
+
type Actions = Readonly<Record<string, ActionSnapshot>>;
|
|
3
|
+
export declare function freezeDependencies(ids?: readonly string[]): readonly string[] | undefined;
|
|
4
|
+
/** Missing nodes and cycles fail closed. No dependency handler is executed. */
|
|
5
|
+
export declare function dependencyEnabled(id: string, actions: Actions, enabled: (action: ActionSnapshot) => boolean, visiting?: Set<string>, cache?: Map<string, boolean>): boolean;
|
|
6
|
+
/** Invalidate contextual bindings too, even when their unbound enabled value stays the same. */
|
|
7
|
+
export declare function affectedActions(actions: Actions, changed: string): Set<string>;
|
|
8
|
+
export {};
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
export function freezeDependencies(ids) {
|
|
2
|
+
return ids ? Object.freeze([...new Set(ids)]) : undefined;
|
|
3
|
+
}
|
|
4
|
+
/** Missing nodes and cycles fail closed. No dependency handler is executed. */
|
|
5
|
+
export function dependencyEnabled(id, actions, enabled, visiting = new Set(), cache = new Map()) {
|
|
6
|
+
if (cache.has(id))
|
|
7
|
+
return cache.get(id);
|
|
8
|
+
if (!Object.hasOwn(actions, id) || visiting.has(id))
|
|
9
|
+
return false;
|
|
10
|
+
const action = actions[id];
|
|
11
|
+
visiting.add(id);
|
|
12
|
+
const result = enabled(action) &&
|
|
13
|
+
(action.dependsOn ?? []).every((dependency) => dependencyEnabled(dependency, actions, enabled, visiting, cache));
|
|
14
|
+
visiting.delete(id);
|
|
15
|
+
cache.set(id, result);
|
|
16
|
+
return result;
|
|
17
|
+
}
|
|
18
|
+
/** Invalidate contextual bindings too, even when their unbound enabled value stays the same. */
|
|
19
|
+
export function affectedActions(actions, changed) {
|
|
20
|
+
const affected = new Set([changed]);
|
|
21
|
+
const dependents = new Map();
|
|
22
|
+
for (const action of Object.values(actions)) {
|
|
23
|
+
for (const id of action.dependsOn ?? []) {
|
|
24
|
+
const items = dependents.get(id) ?? [];
|
|
25
|
+
items.push(action.id);
|
|
26
|
+
dependents.set(id, items);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
for (const id of affected) {
|
|
30
|
+
for (const dependent of dependents.get(id) ?? [])
|
|
31
|
+
affected.add(dependent);
|
|
32
|
+
}
|
|
33
|
+
return affected;
|
|
34
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { ActionStatus } from './state.js';
|
|
2
|
+
import type { ActionSnapshot, ActionPatch, ExecutionResult } from './types.js';
|
|
3
|
+
import type { ExecutionLifecycle } from './interceptors.js';
|
|
4
|
+
export declare function createExecutor(setPending: (id: string, pending: boolean, status?: ActionStatus, error?: unknown) => void, owners: Map<string, symbol>, environment: unknown, get: (id: string) => ActionSnapshot | undefined, resolve: (id: string, input?: unknown) => ActionSnapshot | undefined, update: (id: string, patch: ActionPatch) => boolean, lifecycle: ExecutionLifecycle): (id: string, input?: unknown) => Promise<ExecutionResult>;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { ActionStatus } from './state.js';
|
|
2
|
+
export function createExecutor(setPending, owners, environment, get, resolve, update, lifecycle) {
|
|
3
|
+
return async function execute(id, input) {
|
|
4
|
+
const owner = owners.get(id);
|
|
5
|
+
const context = Object.freeze({
|
|
6
|
+
id,
|
|
7
|
+
input,
|
|
8
|
+
environment,
|
|
9
|
+
get: () => (owners.get(id) === owner ? get(id) : undefined),
|
|
10
|
+
update: (patch) => owners.get(id) === owner && update(id, patch),
|
|
11
|
+
});
|
|
12
|
+
const skip = (reason) => {
|
|
13
|
+
const result = { status: 'skipped', reason };
|
|
14
|
+
lifecycle.emit({ id, context, phase: 'skipped', result });
|
|
15
|
+
return result;
|
|
16
|
+
};
|
|
17
|
+
const action = resolve(id, input);
|
|
18
|
+
if (!action)
|
|
19
|
+
return skip('missing');
|
|
20
|
+
if (!action.visible)
|
|
21
|
+
return skip('hidden');
|
|
22
|
+
if (!action.enabled)
|
|
23
|
+
return skip('disabled');
|
|
24
|
+
if (action.pending)
|
|
25
|
+
return skip('pending');
|
|
26
|
+
if (!action.execute)
|
|
27
|
+
return skip('no-handler');
|
|
28
|
+
let status = action.status;
|
|
29
|
+
let failure = action.error;
|
|
30
|
+
setPending(id, true, ActionStatus.Pending);
|
|
31
|
+
lifecycle.emit({ id, context, phase: 'started' });
|
|
32
|
+
try {
|
|
33
|
+
if (lifecycle.hasInterceptors && !(await lifecycle.allow(context)))
|
|
34
|
+
return skip('intercepted');
|
|
35
|
+
if (owners.get(id) !== owner)
|
|
36
|
+
return skip('replaced');
|
|
37
|
+
const current = resolve(id, input);
|
|
38
|
+
if (!current?.visible)
|
|
39
|
+
return skip('hidden');
|
|
40
|
+
if (!current.enabled)
|
|
41
|
+
return skip('disabled');
|
|
42
|
+
if (!current.execute)
|
|
43
|
+
return skip('no-handler');
|
|
44
|
+
// The handler's return value travels to the caller; it is never stored in action state.
|
|
45
|
+
const value = await current.execute(context);
|
|
46
|
+
status = ActionStatus.Succeeded;
|
|
47
|
+
failure = undefined;
|
|
48
|
+
const result = { status: 'completed', value };
|
|
49
|
+
lifecycle.emit({ id, context, phase: 'completed', result });
|
|
50
|
+
return result;
|
|
51
|
+
}
|
|
52
|
+
catch (error) {
|
|
53
|
+
status = ActionStatus.Failed;
|
|
54
|
+
failure = error;
|
|
55
|
+
lifecycle.emit({ id, context, phase: 'failed', error });
|
|
56
|
+
throw error;
|
|
57
|
+
}
|
|
58
|
+
finally {
|
|
59
|
+
if (owners.get(id) === owner && get(id)) {
|
|
60
|
+
setPending(id, false, status, failure);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
};
|
|
64
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export type MessageValues = Record<string, string | number | Date>;
|
|
2
|
+
export type FeedbackMessage = {
|
|
3
|
+
message?: string;
|
|
4
|
+
messageKey?: string;
|
|
5
|
+
values?: MessageValues;
|
|
6
|
+
closeDialog?: boolean;
|
|
7
|
+
};
|
|
8
|
+
export type FeedbackResult = FeedbackMessage | string | false | undefined;
|
|
9
|
+
/** A literal message, a message key, `false` for silence, or a callback returning one of these. */
|
|
10
|
+
export type Feedback<Context> = FeedbackResult | ((context: Context) => FeedbackResult);
|
|
11
|
+
/** Feedback callbacks cannot turn a successful operation into a failed operation. */
|
|
12
|
+
export declare function evaluateFeedback<C>(feedback: Feedback<C>, context: C): FeedbackMessage | false;
|
|
13
|
+
/** Carries only the selected display message; the original error remains in cause. */
|
|
14
|
+
export declare class ActionFailure extends Error {
|
|
15
|
+
readonly feedback: string | false;
|
|
16
|
+
constructor(feedback: string | false, cause: unknown);
|
|
17
|
+
}
|