@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.
Files changed (108) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +382 -0
  3. package/discovery/entries.mjs +124 -0
  4. package/discovery/generate.mjs +327 -0
  5. package/discovery/host.mjs +12 -0
  6. package/discovery/index.d.ts +41 -0
  7. package/discovery/index.mjs +4 -0
  8. package/discovery/modules.mjs +13 -0
  9. package/discovery/packages.mjs +57 -0
  10. package/discovery/watch.mjs +23 -0
  11. package/dist/actions/action-list.d.ts +69 -0
  12. package/dist/actions/action-list.js +247 -0
  13. package/dist/actions/action.d.ts +96 -0
  14. package/dist/actions/action.js +145 -0
  15. package/dist/actions/base/url-action.d.ts +8 -0
  16. package/dist/actions/base/url-action.js +15 -0
  17. package/dist/actions/core.d.ts +14 -0
  18. package/dist/actions/core.js +8 -0
  19. package/dist/actions/dependencies.d.ts +8 -0
  20. package/dist/actions/dependencies.js +34 -0
  21. package/dist/actions/execution.d.ts +4 -0
  22. package/dist/actions/execution.js +64 -0
  23. package/dist/actions/feedback.d.ts +17 -0
  24. package/dist/actions/feedback.js +21 -0
  25. package/dist/actions/groups.d.ts +13 -0
  26. package/dist/actions/groups.js +21 -0
  27. package/dist/actions/instance-bindings.d.ts +16 -0
  28. package/dist/actions/instance-bindings.js +93 -0
  29. package/dist/actions/interceptors.d.ts +24 -0
  30. package/dist/actions/interceptors.js +42 -0
  31. package/dist/actions/navigation.d.ts +12 -0
  32. package/dist/actions/navigation.js +42 -0
  33. package/dist/actions/reference.d.ts +17 -0
  34. package/dist/actions/reference.js +39 -0
  35. package/dist/actions/state.d.ts +11 -0
  36. package/dist/actions/state.js +8 -0
  37. package/dist/actions/types.d.ts +99 -0
  38. package/dist/actions/types.js +1 -0
  39. package/dist/app/access.d.ts +4 -0
  40. package/dist/app/access.js +85 -0
  41. package/dist/app/action-access.d.ts +4 -0
  42. package/dist/app/action-access.js +20 -0
  43. package/dist/app/service-error.d.ts +8 -0
  44. package/dist/app/service-error.js +19 -0
  45. package/dist/app/types.d.ts +47 -0
  46. package/dist/app/types.js +1 -0
  47. package/dist/config-service.d.ts +49 -0
  48. package/dist/config-service.js +83 -0
  49. package/dist/configuration.d.ts +4 -0
  50. package/dist/configuration.js +42 -0
  51. package/dist/confirmation.d.ts +14 -0
  52. package/dist/confirmation.js +26 -0
  53. package/dist/contracts.d.ts +27 -0
  54. package/dist/contracts.js +3 -0
  55. package/dist/contribution-origin.d.ts +3 -0
  56. package/dist/contribution-origin.js +13 -0
  57. package/dist/contributions/command.d.ts +8 -0
  58. package/dist/contributions/command.js +50 -0
  59. package/dist/contributions/dialog.d.ts +8 -0
  60. package/dist/contributions/dialog.js +18 -0
  61. package/dist/contributions/form.d.ts +10 -0
  62. package/dist/contributions/form.js +67 -0
  63. package/dist/contributions/host.d.ts +40 -0
  64. package/dist/contributions/host.js +1 -0
  65. package/dist/contributions/index.d.ts +26 -0
  66. package/dist/contributions/index.js +18 -0
  67. package/dist/contributions/native.d.ts +11 -0
  68. package/dist/contributions/native.js +87 -0
  69. package/dist/contributions/shared.d.ts +19 -0
  70. package/dist/contributions/shared.js +48 -0
  71. package/dist/contributions/stateful-action.d.ts +29 -0
  72. package/dist/contributions/stateful-action.js +33 -0
  73. package/dist/conventions.d.ts +4 -0
  74. package/dist/conventions.js +38 -0
  75. package/dist/core.d.ts +21 -0
  76. package/dist/core.js +18 -0
  77. package/dist/definitions.d.ts +356 -0
  78. package/dist/definitions.js +60 -0
  79. package/dist/discovered.d.ts +49 -0
  80. package/dist/discovered.js +120 -0
  81. package/dist/interceptors/service-observers.d.ts +3 -0
  82. package/dist/interceptors/service-observers.js +80 -0
  83. package/dist/interceptors/service.d.ts +37 -0
  84. package/dist/interceptors/service.js +7 -0
  85. package/dist/messages.d.ts +9 -0
  86. package/dist/messages.js +21 -0
  87. package/dist/metadata.d.ts +3 -0
  88. package/dist/metadata.js +13 -0
  89. package/dist/pages.d.ts +8 -0
  90. package/dist/pages.js +22 -0
  91. package/dist/presentation.d.ts +4 -0
  92. package/dist/presentation.js +1 -0
  93. package/dist/replacements.d.ts +22 -0
  94. package/dist/replacements.js +54 -0
  95. package/dist/runtime.d.ts +88 -0
  96. package/dist/runtime.js +445 -0
  97. package/dist/scope.d.ts +34 -0
  98. package/dist/scope.js +78 -0
  99. package/dist/service-key.d.ts +13 -0
  100. package/dist/service-key.js +14 -0
  101. package/dist/services.d.ts +6 -0
  102. package/dist/services.js +53 -0
  103. package/dist/translation.d.ts +13 -0
  104. package/dist/translation.js +43 -0
  105. package/dist/validation.d.ts +2 -0
  106. package/dist/validation.js +16 -0
  107. package/docs/file-contributions.md +161 -0
  108. package/package.json +48 -0
@@ -0,0 +1,87 @@
1
+ import { Action } from '@bitakit/core/actions';
2
+ import { ActionFailure } from '../actions/feedback.js';
3
+ import { resolveContribution } from '../conventions.js';
4
+ import { applyOverride, cap, groupsOf, texts } from './shared.js';
5
+ /**
6
+ * Class and function exports: one fresh instance per runtime. Metadata declared on the instance
7
+ * wins; translation, overrides and opt-in feedback are applied to that instance.
8
+ */
9
+ export function adaptNative(resolved, host, config) {
10
+ const instance = resolved.load({ services: host.services, translate: host.translator(), config });
11
+ if (!(instance instanceof Action))
12
+ throw new Error(`Action export "${resolved.id}" must return an Action instance.`);
13
+ let effective = resolved;
14
+ if (resolved.fromExport) {
15
+ const snapshot = instance.snapshot();
16
+ effective = resolveContribution({
17
+ ...resolved,
18
+ ...snapshot,
19
+ id: instance.id ?? resolved.id,
20
+ title: snapshot.title || undefined,
21
+ fromExport: false,
22
+ });
23
+ }
24
+ const { definition, override } = applyOverride(effective, host);
25
+ if (override) {
26
+ const resolve = instance.resolve.bind(instance);
27
+ instance.resolve = (input) => cap(resolve(input), override);
28
+ }
29
+ const shared = texts(host, definition);
30
+ instance.title = shared.title;
31
+ if (shared.description !== undefined)
32
+ instance.description = shared.description;
33
+ if (definition.icon !== undefined)
34
+ instance.icon = definition.icon;
35
+ if (shared.tooltip !== undefined)
36
+ instance.tooltip = shared.tooltip;
37
+ if (definition.enabled !== undefined)
38
+ instance.enabled = definition.enabled;
39
+ if (definition.visible !== undefined)
40
+ instance.visible = definition.visible;
41
+ if (definition.shortcut !== undefined)
42
+ instance.shortcut = definition.shortcut;
43
+ if (definition.dependsOn !== undefined)
44
+ instance.dependsOn = definition.dependsOn;
45
+ if (instance.success !== undefined || instance.failure !== undefined)
46
+ attachFeedback(instance, definition, host);
47
+ const groups = [
48
+ ...new Map([...(instance.snapshot().groups ?? []), ...groupsOf(host, definition)].map((group) => [
49
+ group.id,
50
+ group,
51
+ ])).values(),
52
+ ];
53
+ return {
54
+ definition,
55
+ requires: definition.requires ?? [],
56
+ watch: [],
57
+ registrations: [
58
+ {
59
+ id: definition.id,
60
+ instance,
61
+ placement: { groups, order: definition.order, dividerBefore: definition.dividerBefore },
62
+ },
63
+ ],
64
+ };
65
+ }
66
+ /** Same pipeline as plain commands, but only for feedback the class declares itself. */
67
+ function attachFeedback(instance, definition, host) {
68
+ const run = instance.execute.bind(instance);
69
+ instance.execute = async (input, context) => {
70
+ const live = () => !context || context.get() !== undefined;
71
+ let result;
72
+ try {
73
+ result = await run(input, context);
74
+ }
75
+ catch (error) {
76
+ if (instance.failure === undefined)
77
+ throw error;
78
+ const feedback = live()
79
+ ? host.feedback(definition, 'failure', instance.failure, { error, input }).message
80
+ : false;
81
+ throw new ActionFailure(feedback, error);
82
+ }
83
+ if (instance.success !== undefined && live())
84
+ host.notify(host.feedback(definition, 'success', instance.success, { result, input }).message);
85
+ return result;
86
+ };
87
+ }
@@ -0,0 +1,19 @@
1
+ import type { ActionDefinition, ActionPresentation } from '@bitakit/core/actions';
2
+ import type { ResolvedContribution } from '../definitions.js';
3
+ import type { ContributionHost, OpenableDefinition, Override } from './host.js';
4
+ /** Every kind reads title, description and tooltip through the same translation rules. */
5
+ export declare function texts(host: ContributionHost, definition: ResolvedContribution): {
6
+ title: string;
7
+ description: string | undefined;
8
+ tooltip: string | undefined;
9
+ };
10
+ /** Configuration caps: false wins over any reactive result; true never bypasses guards. */
11
+ export declare function cap(presentation: ActionPresentation, override: Override): ActionPresentation;
12
+ /** Merge the host override into the definition once; the cap also applies to reactive results. */
13
+ export declare function applyOverride<T extends ResolvedContribution>(resolved: T, host: ContributionHost): {
14
+ definition: T;
15
+ override: Override;
16
+ };
17
+ export declare function groupsOf(host: ContributionHost, definition: ResolvedContribution): import("@bitakit/core/actions").ActionGroup<unknown>[];
18
+ /** The public action of a form or dialog: executing it opens the shared dialog host. */
19
+ export declare function opener(host: ContributionHost, definition: OpenableDefinition, resolve: (input: unknown) => ActionPresentation): ActionDefinition;
@@ -0,0 +1,48 @@
1
+ /** Every kind reads title, description and tooltip through the same translation rules. */
2
+ export function texts(host, definition) {
3
+ return {
4
+ title: host.title(definition),
5
+ description: host.description(definition),
6
+ tooltip: definition.tooltip === undefined
7
+ ? undefined
8
+ : host.text(definition.tooltip, host.text(`${definition.id}.tooltip`, definition.tooltip)),
9
+ };
10
+ }
11
+ /** Configuration caps: false wins over any reactive result; true never bypasses guards. */
12
+ export function cap(presentation, override) {
13
+ if (!override)
14
+ return presentation;
15
+ return {
16
+ ...presentation,
17
+ enabled: override.enabled === false ? false : presentation.enabled,
18
+ visible: override.visible === false ? false : presentation.visible,
19
+ };
20
+ }
21
+ /** Merge the host override into the definition once; the cap also applies to reactive results. */
22
+ export function applyOverride(resolved, host) {
23
+ const override = host.override(resolved.id);
24
+ return { definition: override ? { ...resolved, ...override } : resolved, override };
25
+ }
26
+ export function groupsOf(host, definition) {
27
+ return (definition.groups ?? []).map(host.getGroup);
28
+ }
29
+ /** The public action of a form or dialog: executing it opens the shared dialog host. */
30
+ export function opener(host, definition, resolve) {
31
+ return {
32
+ id: definition.id,
33
+ ...texts(host, definition),
34
+ groups: groupsOf(host, definition),
35
+ order: definition.order,
36
+ icon: definition.icon,
37
+ dividerBefore: definition.dividerBefore,
38
+ dependsOn: definition.dependsOn,
39
+ shortcut: definition.shortcut,
40
+ enabled: definition.enabled,
41
+ visible: definition.visible,
42
+ resolve,
43
+ execute: ({ input }) => {
44
+ if (!host.dialog())
45
+ host.openDialog(definition, input);
46
+ },
47
+ };
48
+ }
@@ -0,0 +1,29 @@
1
+ import type { FoundationApp } from '../app/types.js';
2
+ import type { ConfigContext } from '../config-service.js';
3
+ import type { PlainDefinition, Services } from '../definitions.js';
4
+ export interface ActionInstance<State extends object> {
5
+ readonly app: FoundationApp;
6
+ readonly services: Services;
7
+ readonly config: ConfigContext;
8
+ readonly state: {
9
+ get(): Readonly<State>;
10
+ update(change: (current: Readonly<State>) => State): boolean;
11
+ };
12
+ }
13
+ export interface StatefulDefinition<Input, State extends object, Result, Id extends string> extends PlainDefinition<Input, Result> {
14
+ kind: 'action';
15
+ id?: Id;
16
+ initialState: State;
17
+ }
18
+ type StatefulOptions<Input, State extends object, Result, Id extends string> = Omit<PlainDefinition<Input, Result>, 'kind' | 'execute' | 'id' | 'initialState'> & {
19
+ id?: Id;
20
+ title?: string;
21
+ initialState: State;
22
+ execute(input: Input): Result | Promise<Result>;
23
+ } & ThisType<ActionInstance<NoInfer<State>>>;
24
+ export interface StatefulBuilder<Input> {
25
+ <State extends object, Result, const Id extends string = string>(options: StatefulOptions<Input, State, Result, Id>): StatefulDefinition<Input, State, Result, Id>;
26
+ }
27
+ /** Adapts instance-style authoring to the existing command and registration lifetime. */
28
+ export declare function statefulAction<Input>(): StatefulBuilder<Input>;
29
+ export {};
@@ -0,0 +1,33 @@
1
+ /** Adapts instance-style authoring to the existing command and registration lifetime. */
2
+ export function statefulAction() {
3
+ return (options) => {
4
+ const { execute, ...definition } = options;
5
+ const adapted = {
6
+ ...definition,
7
+ kind: 'action',
8
+ execute(context) {
9
+ const read = () => {
10
+ const snapshot = context.get();
11
+ if (!snapshot)
12
+ throw new Error('This Action registration is no longer active.');
13
+ return snapshot.state;
14
+ };
15
+ const instance = Object.freeze({
16
+ app: context.app,
17
+ services: context.services,
18
+ config: context.config,
19
+ state: Object.freeze({
20
+ get: read,
21
+ update: (change) => {
22
+ if (!context.get())
23
+ return false;
24
+ return context.update({ state: Object.freeze(change(read())) });
25
+ },
26
+ }),
27
+ });
28
+ return execute.call(instance, context.input);
29
+ },
30
+ };
31
+ return adapted;
32
+ };
33
+ }
@@ -0,0 +1,4 @@
1
+ import type { Contribution, ResolvedContribution } from './definitions.js';
2
+ /** Build adapters supply a path-derived ID; explicit consumers supply their own ID. */
3
+ export declare function resolveContribution<T extends Contribution>(entry: T, inferredId?: string, useConventions?: boolean): ResolvedContribution;
4
+ export declare function fallbackTitle(definition: ResolvedContribution): string;
@@ -0,0 +1,38 @@
1
+ import { preserveContributionPath } from './contribution-origin.js';
2
+ import { Action } from '@bitakit/core/actions';
3
+ /** Build adapters supply a path-derived ID; explicit consumers supply their own ID. */
4
+ export function resolveContribution(entry, inferredId, useConventions = true) {
5
+ const definition = typeof entry === 'function'
6
+ ? {
7
+ kind: 'native',
8
+ fromExport: true,
9
+ load: (context) => entry.prototype instanceof Action
10
+ ? new entry(context)
11
+ : entry(context),
12
+ }
13
+ : entry;
14
+ const normalized = definition;
15
+ if (!normalized || !['action', 'form', 'dialog', 'native'].includes(normalized.kind))
16
+ throw new Error(`Invalid action export in "${inferredId ?? 'manual registration'}". Export an Action class, function or action definition.`);
17
+ const automatic = normalized.conventions ?? useConventions;
18
+ if (normalized.replaces && normalized.id && normalized.id !== normalized.replaces)
19
+ throw new Error('A replacement must retain the target action ID.');
20
+ const id = normalized.replaces ?? normalized.id ?? (automatic ? inferredId : undefined);
21
+ if (!id && normalized.kind === 'native' && normalized.fromExport)
22
+ return { ...normalized, id: '', conventions: automatic };
23
+ if (!id)
24
+ throw new Error('Action needs an explicit ID when path conventions are unavailable or disabled.');
25
+ if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/.test(id))
26
+ throw new Error(`Invalid action ID: ${id}`);
27
+ if (!automatic && normalized.title === undefined)
28
+ throw new Error(`Action "${id}" needs an explicit title.`);
29
+ return preserveContributionPath(entry, {
30
+ ...normalized,
31
+ id,
32
+ conventions: automatic,
33
+ });
34
+ }
35
+ export function fallbackTitle(definition) {
36
+ const name = definition.id.split(/[./:]/).at(-1).replace(/[-_]/g, ' ');
37
+ return name.charAt(0).toUpperCase() + name.slice(1);
38
+ }
package/dist/core.d.ts ADDED
@@ -0,0 +1,21 @@
1
+ export * from './definitions.js';
2
+ export type { FoundationApp, AppExtensionMap, Namespace, PublicServiceKeys, PublicServiceMap, PublicServicesOf, } from './app/types.js';
3
+ export { FoundationServiceError } from './app/service-error.js';
4
+ export { resolveFoundationConfig, type FoundationOverrides } from './configuration.js';
5
+ export { FoundationRuntime } from './runtime.js';
6
+ export { PluginScope, scopeModule, type ScopeModule } from './scope.js';
7
+ export { validateFields } from './validation.js';
8
+ export { mergePluginMessages } from './messages.js';
9
+ export { resolveContribution } from './conventions.js';
10
+ export { ConfirmationController, type Confirmation } from './confirmation.js';
11
+ export * from './contracts.js';
12
+ export { resolveText, createTranslationPlugin } from './translation.js';
13
+ export { findPluginPage, validatePluginPages } from './pages.js';
14
+ export * from './actions/core.js';
15
+ export { serviceKey, getService, provideService, type ServiceKey } from './service-key.js';
16
+ export { pluginMetadata } from './metadata.js';
17
+ export { ConfigService, ConfigScope, defineConfig, type ConfigContext, type ConfigValues, type ConfigDefinition, type ConfigSchema, type ConfigMap, type ConfigPath, type ConfigAt, } from './config-service.js';
18
+ export * from './discovered.js';
19
+ export type { PresentationTypes, PresentationType } from './presentation.js';
20
+ export type { ActionInstance, StatefulDefinition, StatefulBuilder, } from './contributions/stateful-action.js';
21
+ export { defineServiceInterceptor, type ServiceInterceptor } from './interceptors/service.js';
package/dist/core.js ADDED
@@ -0,0 +1,18 @@
1
+ export * from './definitions.js';
2
+ export { FoundationServiceError } from './app/service-error.js';
3
+ export { resolveFoundationConfig } from './configuration.js';
4
+ export { FoundationRuntime } from './runtime.js';
5
+ export { PluginScope, scopeModule } from './scope.js';
6
+ export { validateFields } from './validation.js';
7
+ export { mergePluginMessages } from './messages.js';
8
+ export { resolveContribution } from './conventions.js';
9
+ export { ConfirmationController } from './confirmation.js';
10
+ export * from './contracts.js';
11
+ export { resolveText, createTranslationPlugin } from './translation.js';
12
+ export { findPluginPage, validatePluginPages } from './pages.js';
13
+ export * from './actions/core.js';
14
+ export { serviceKey, getService, provideService } from './service-key.js';
15
+ export { pluginMetadata } from './metadata.js';
16
+ export { ConfigService, ConfigScope, defineConfig, } from './config-service.js';
17
+ export * from './discovered.js';
18
+ export { defineServiceInterceptor } from './interceptors/service.js';
@@ -0,0 +1,356 @@
1
+ import type { ServiceInterceptor } from './interceptors/service.js';
2
+ import { type StatefulBuilder } from './contributions/stateful-action.js';
3
+ import type { ConfigContext, ConfigValues, ConfigDefinition } from './config-service.js';
4
+ import type { AuthService, TranslationService } from './contracts.js';
5
+ import type { PresentationType } from './presentation.js';
6
+ import type { ActionContext, ActionShortcut, Action, ActionDefinition, ActionPresentation, ActionGroup } from '@bitakit/core/actions';
7
+ import type { PluginScope } from './scope.js';
8
+ import type { Feedback, MessageValues } from './actions/feedback.js';
9
+ import type { PublicServiceKeys } from './app/types.js';
10
+ import type { FoundationApp } from './app/types.js';
11
+ /** Augmented by generated service declarations. No global runtime container. */
12
+ export interface ServiceMap {
13
+ auth?: AuthService;
14
+ i18n?: TranslationService;
15
+ }
16
+ export type Services = Readonly<ServiceMap>;
17
+ export type Translator = ((key: string, values?: MessageValues) => string) & {
18
+ has?: (key: string) => boolean;
19
+ };
20
+ export interface ServiceDefinition<T = unknown> {
21
+ id: string;
22
+ requires?: readonly string[];
23
+ create(context: {
24
+ services: Services;
25
+ config: ConfigContext;
26
+ }): T;
27
+ dispose?: (instance: T) => void;
28
+ }
29
+ export declare function defineService<const ID extends string, T>(definition: ServiceDefinition<T> & {
30
+ id: ID;
31
+ }): ServiceDefinition<T> & {
32
+ id: ID;
33
+ };
34
+ export declare function defineService<T>(definition: Omit<ServiceDefinition<T>, 'id'>): Omit<ServiceDefinition<T>, 'id'>;
35
+ export type FoundationInterceptor = {
36
+ before(context: ActionContext & {
37
+ config: ConfigContext;
38
+ }): boolean | void | Promise<boolean | void>;
39
+ };
40
+ export type InterceptorDefinition = {
41
+ requires?: readonly string[];
42
+ order?: number;
43
+ scope?: 'plugin' | 'global';
44
+ create(context: {
45
+ services: Services;
46
+ translate: Translator;
47
+ config: ConfigContext;
48
+ }): FoundationInterceptor;
49
+ };
50
+ export declare function defineInterceptor(definition: InterceptorDefinition): InterceptorDefinition;
51
+ export declare function defineInterceptor(definition: FoundationInterceptor & {
52
+ order?: number;
53
+ scope?: 'plugin' | 'global';
54
+ }): FoundationInterceptor;
55
+ export type ActionInterceptorEntry = (InterceptorDefinition | FoundationInterceptor) & {
56
+ kind?: 'action';
57
+ order?: number;
58
+ scope?: 'plugin' | 'global';
59
+ };
60
+ export type InterceptorEntry = ActionInterceptorEntry | ServiceInterceptor;
61
+ /** Explicit Action discriminator; the legacy defineInterceptor helper remains supported. */
62
+ export declare function defineActionInterceptor<T extends ActionInterceptorEntry>(definition: T): T & {
63
+ kind: 'action';
64
+ };
65
+ /** Ordered outside-in. Dependencies must already appear before this provider. */
66
+ export type ProviderDefinition = {
67
+ id: string;
68
+ component: PresentationType<'provider'>;
69
+ requires?: readonly string[];
70
+ };
71
+ export declare function defineProvider(definition: ProviderDefinition): ProviderDefinition;
72
+ export type Field = {
73
+ type: 'text' | 'email' | 'select';
74
+ label?: string;
75
+ required?: boolean;
76
+ defaultValue?: string;
77
+ options?: readonly {
78
+ value: string;
79
+ label: string;
80
+ }[];
81
+ };
82
+ export type Fields = Readonly<Record<string, Field>>;
83
+ export type Values<F extends Fields> = {
84
+ [K in keyof F]: string;
85
+ };
86
+ export type FormRenderProps = {
87
+ values: Readonly<Record<string, string>>;
88
+ setValue(name: string, value: string): void;
89
+ submit(event: {
90
+ preventDefault(): void;
91
+ }): void;
92
+ pending: boolean;
93
+ enabled: boolean;
94
+ error: string | null;
95
+ };
96
+ export type ActionConventions = Partial<Pick<ActionDefinition, 'title' | 'description' | 'icon' | 'tooltip' | 'shortcut' | 'enabled' | 'visible' | 'dependsOn' | 'dividerBefore'>> & {
97
+ id?: string;
98
+ /** App-only: explicitly replace a plugin action while preserving its public ID. */
99
+ replaces?: string;
100
+ groups?: readonly (string | ActionGroup)[];
101
+ order?: number;
102
+ conventions?: boolean;
103
+ /** Explicit local config path for manual registration; discovery supplies it otherwise. */
104
+ configPath?: readonly string[];
105
+ };
106
+ /** Literal `id`/`replaces` values survive the builders so ActionMap entries use the effective ID. */
107
+ type Identity<Id extends string, Replaces extends string> = {
108
+ id?: Id;
109
+ replaces?: Replaces;
110
+ };
111
+ export type FormDefinition<F extends Fields = Fields, Result = unknown> = ActionConventions & {
112
+ kind: 'form';
113
+ requires?: readonly string[];
114
+ fields: F;
115
+ submit(values: Values<F>, context: {
116
+ services: Services;
117
+ config: ConfigContext;
118
+ input?: unknown;
119
+ }): Result | Promise<Result>;
120
+ closeOnSuccess?: boolean;
121
+ success?: Feedback<{
122
+ result: NoInfer<Awaited<Result>>;
123
+ input: Values<F>;
124
+ services: Services;
125
+ }>;
126
+ failure?: Feedback<{
127
+ error: unknown;
128
+ input: Values<F>;
129
+ services: Services;
130
+ }>;
131
+ render?: (props: FormRenderProps) => PresentationType<'node'>;
132
+ };
133
+ export declare function defineFormAction<const F extends Fields, Result, const Id extends string = string, const Replaces extends string = string>(definition: Omit<FormDefinition<F, Result>, 'kind' | 'id' | 'replaces'> & Identity<Id, Replaces>): FormDefinition<F, Result> & Identity<Id, Replaces>;
134
+ export type DialogDefinition<Input = unknown> = ActionConventions & {
135
+ kind: 'dialog';
136
+ size?: 'default' | 'wide';
137
+ requires?: readonly string[];
138
+ watch?: readonly string[];
139
+ resolve?: (input: Input, context: {
140
+ services: Services;
141
+ config: ConfigContext;
142
+ }) => ActionPresentation;
143
+ render(props: {
144
+ input: Input;
145
+ close(): void;
146
+ services: Services;
147
+ }): PresentationType<'node'>;
148
+ };
149
+ export declare function defineDialogAction<Input = unknown, const Id extends string = string, const Replaces extends string = string>(definition: Omit<DialogDefinition<Input>, 'kind' | 'id' | 'replaces'> & Identity<Id, Replaces>): DialogDefinition<Input> & Identity<Id, Replaces>;
150
+ /** Context supplied automatically to an exported Action class or function. */
151
+ export type ActionEnvironment = {
152
+ services: Services;
153
+ translate: Translator;
154
+ config: ConfigContext;
155
+ };
156
+ export type ActionExport = (new (context: ActionEnvironment) => Action<any, any>) | ((context: ActionEnvironment) => Action<any, any>);
157
+ /** Internal normalized representation; application code exports classes/functions directly. */
158
+ export type NativeDefinition = ActionConventions & {
159
+ kind: 'native';
160
+ requires?: readonly string[];
161
+ load(context: ActionEnvironment): Action<any, any>;
162
+ fromExport?: boolean;
163
+ };
164
+ /** Navigation retains native link semantics and programmatic URLAction execution. */
165
+ export declare function defineURLAction<const Id extends string = string, const Replaces extends string = string>(definition: Omit<ActionConventions, 'id' | 'replaces'> & Identity<Id, Replaces> & {
166
+ href: string;
167
+ }): NativeDefinition & Identity<Id, Replaces>;
168
+ export type PlainDefinition<Input = unknown, Result = unknown> = Omit<ActionConventions, 'shortcut'> & Omit<ActionDefinition, 'id' | 'title' | 'groups' | 'execute' | 'resolve' | 'shortcut'> & {
169
+ shortcut?: ActionShortcut<NoInfer<Input>>;
170
+ kind: 'action';
171
+ requires?: readonly string[];
172
+ /** Observable services that invalidate presentation; subscribed once per runtime. */
173
+ watch?: readonly string[];
174
+ resolve?: (input: Input, context: {
175
+ services: Services;
176
+ config: ConfigContext;
177
+ }) => ActionPresentation;
178
+ execute?: (context: ActionContext<Input> & {
179
+ services: Services;
180
+ config: ConfigContext;
181
+ app: FoundationApp;
182
+ }) => Result | Promise<Result>;
183
+ success?: Feedback<{
184
+ result: NoInfer<Awaited<Result>>;
185
+ input: Input;
186
+ services: Services;
187
+ }>;
188
+ failure?: Feedback<{
189
+ error: unknown;
190
+ input: Input;
191
+ services: Services;
192
+ }>;
193
+ };
194
+ /**
195
+ * `Result` is inferred from `execute`. Type `Input` by annotating the first `resolve`
196
+ * parameter, or pass both arguments explicitly: `defineAction<MemberContext, void>({...})`.
197
+ */
198
+ export declare function defineAction<Input>(): StatefulBuilder<Input>;
199
+ export declare function defineAction<Input = unknown, Result = void, const Id extends string = string, const Replaces extends string = string>(definition: Omit<PlainDefinition<Input, Result>, 'kind' | 'id' | 'replaces'> & Identity<Id, Replaces> & {
200
+ unavailable?: {
201
+ messageKey: string;
202
+ };
203
+ }): PlainDefinition<Input, Result> & Identity<Id, Replaces>;
204
+ export type Contribution = FormDefinition<any, any> | DialogDefinition<any> | NativeDefinition | PlainDefinition<any, any> | ActionExport;
205
+ export type ResolvedContribution = Exclude<Contribution, ActionExport> & {
206
+ id: string;
207
+ };
208
+ export type ResolvedForm = FormDefinition<Fields, any> & {
209
+ id: string;
210
+ };
211
+ /** A literal string wins; a widened `string` or a missing value falls back. */
212
+ type LiteralOr<Value, Fallback> = [NonNullable<Value>] extends [string] ? string extends NonNullable<Value> ? Fallback : NonNullable<Value> : Fallback;
213
+ /** The ID a contribution registers under when discovered at `Path`: `replaces`, then `id`, then the path. */
214
+ export type EffectiveActionId<T, Path extends string> = T extends {
215
+ replaces?: infer Replaces;
216
+ } ? LiteralOr<Replaces, T extends {
217
+ id?: infer Id;
218
+ } ? LiteralOr<Id, Path> : Path> : Path;
219
+ /**
220
+ * Input and result of a definition for ActionMap. Class and function exports establish their ID
221
+ * at construction and therefore contribute no entry; augment ActionMap manually for those.
222
+ */
223
+ export type ActionSignature<T> = T extends ActionExport ? never : T extends PlainDefinition<infer Input, infer Result> ? {
224
+ input: Input;
225
+ result: Awaited<Result>;
226
+ } & (T extends {
227
+ initialState: infer State;
228
+ } ? {
229
+ state: State;
230
+ } : {}) : T extends FormDefinition<any, any> ? {
231
+ input: unknown;
232
+ result: void;
233
+ } : T extends DialogDefinition<infer Input> ? {
234
+ input: Input;
235
+ result: void;
236
+ } : T extends NativeDefinition ? {
237
+ input: void;
238
+ result: void;
239
+ } : never;
240
+ /** One ActionMap entry for a discovered file; build tooling intersects these into the augmentation. */
241
+ export type ActionEntry<T, Path extends string> = [ActionSignature<T>] extends [never] ? {} : {
242
+ [Key in EffectiveActionId<T, Path>]: ActionSignature<T>;
243
+ };
244
+ export type Setup = (context: {
245
+ app: PluginScope;
246
+ services: Services;
247
+ }) => void | (() => void);
248
+ /**
249
+ * Contribution kinds provided by optional integrations, keyed by kind name. An integration
250
+ * augments this map with the value type its normalizer produces, e.g. `'settings.sections': Section`.
251
+ */
252
+ export interface ContributionMap {
253
+ }
254
+ /** Declarative values a module contributes; Core routes each kind to the installer that claims it. */
255
+ export type ContributionSet = {
256
+ readonly [K in keyof ContributionMap]?: readonly ContributionMap[K][];
257
+ } & {
258
+ readonly [kind: string]: readonly unknown[] | undefined;
259
+ };
260
+ export type ContributionContext = {
261
+ /** The contributing module. */
262
+ module: string;
263
+ /** True for the application module. */
264
+ app: boolean;
265
+ services: Services;
266
+ };
267
+ /**
268
+ * Installs one module's values of a kind. Runs during mount after services, translation and
269
+ * interceptors, before actions and setup. The returned cleanup belongs to the contributing module.
270
+ */
271
+ export type ContributionInstaller<T = unknown> = (values: readonly T[], context: ContributionContext) => void | (() => void);
272
+ export type ContributionInstallers = {
273
+ readonly [K in keyof ContributionMap]?: ContributionInstaller<ContributionMap[K]>;
274
+ } & {
275
+ readonly [kind: string]: ContributionInstaller<any> | undefined;
276
+ };
277
+ export declare function defineSetup(setup: Setup): Setup;
278
+ export type PluginView = {
279
+ slot: string;
280
+ component: PresentationType<'component'>;
281
+ order?: number;
282
+ };
283
+ export declare function defineView(view: PluginView): PluginView;
284
+ export type PluginPageDefinition = {
285
+ path: string;
286
+ component: PresentationType<'component'>;
287
+ };
288
+ export declare function definePage(page: PluginPageDefinition): PluginPageDefinition;
289
+ export type Plugin = {
290
+ /** Public app aliases for existing typed service keys; internal services remain private. */
291
+ publicServices?: PublicServiceKeys;
292
+ /** Instance-local projections owned by optional packages; never a second state store. */
293
+ appExtensions?: Readonly<Record<string, (runtime: import('./runtime.js').FoundationRuntime) => unknown>>;
294
+ config?: ConfigValues | ConfigDefinition;
295
+ interceptors?: readonly InterceptorEntry[];
296
+ providers?: readonly ProviderDefinition[];
297
+ metadata?: PluginMetadata;
298
+ pages?: readonly PluginPageDefinition[];
299
+ views?: readonly PluginView[];
300
+ id: string;
301
+ dependencies?: readonly string[];
302
+ services?: readonly ServiceDefinition<any>[];
303
+ actions?: readonly Contribution[];
304
+ setup?: Setup;
305
+ /** Declarative values for installers provided by integrations. */
306
+ contributions?: ContributionSet;
307
+ /** Installers for contribution kinds this module owns. One module per kind. */
308
+ installs?: ContributionInstallers;
309
+ };
310
+ export declare function definePlugin<const T extends Plugin>(plugin: T): T;
311
+ export type FoundationConfig = {
312
+ publicServices?: PublicServiceKeys;
313
+ /** Instance-local projections owned by optional packages; never a second state store. */
314
+ appExtensions?: Readonly<Record<string, (runtime: import('./runtime.js').FoundationRuntime) => unknown>>;
315
+ metadata?: PluginMetadata;
316
+ dependencies?: readonly string[];
317
+ pages?: readonly PluginPageDefinition[];
318
+ views?: readonly PluginView[];
319
+ setup?: Setup;
320
+ appId?: string;
321
+ config?: ConfigValues | ConfigDefinition;
322
+ configOverrides?: Readonly<Record<string, ConfigValues>>;
323
+ services?: readonly ServiceDefinition<any>[];
324
+ groups?: readonly string[];
325
+ actionOverrides?: Readonly<Record<string, {
326
+ enabled?: boolean;
327
+ visible?: boolean;
328
+ }>>;
329
+ actions?: readonly Contribution[];
330
+ interceptors?: readonly InterceptorEntry[];
331
+ providers?: readonly ProviderDefinition[];
332
+ plugins?: readonly Plugin[];
333
+ contributions?: ContributionSet;
334
+ installs?: ContributionInstallers;
335
+ };
336
+ /** Public display information only; package authors remain the source of truth. */
337
+ export type PluginMetadata = {
338
+ /** Optional presentation image; the UI falls back to the plugin icon. */
339
+ coverImage?: string;
340
+ icon?: PresentationType<'icon'>;
341
+ name?: string;
342
+ version?: string;
343
+ description?: string;
344
+ author?: string | {
345
+ name: string;
346
+ email?: string;
347
+ url?: string;
348
+ };
349
+ homepage?: string;
350
+ bugs?: string | {
351
+ url?: string;
352
+ email?: string;
353
+ };
354
+ license?: string;
355
+ };
356
+ export {};