@bitakit/core 0.1.2 → 0.2.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.
Files changed (157) hide show
  1. package/README.md +44 -207
  2. package/discovery/index.d.ts +1 -41
  3. package/discovery/index.mjs +1 -4
  4. package/dist/actions/action-list.d.ts +4 -0
  5. package/dist/actions/action-list.js +58 -16
  6. package/dist/actions/action.d.ts +2 -0
  7. package/dist/actions/action.js +4 -0
  8. package/dist/actions/brand.d.ts +21 -0
  9. package/dist/actions/brand.js +36 -0
  10. package/dist/actions/core.d.ts +4 -3
  11. package/dist/actions/core.js +4 -2
  12. package/dist/actions/execution.d.ts +2 -2
  13. package/dist/actions/execution.js +61 -9
  14. package/dist/actions/feedback.d.ts +2 -0
  15. package/dist/actions/feedback.js +8 -0
  16. package/dist/actions/groups.js +5 -1
  17. package/dist/actions/instance-bindings.js +3 -2
  18. package/dist/actions/interceptors.d.ts +9 -3
  19. package/dist/actions/interceptors.js +31 -3
  20. package/dist/actions/navigation.d.ts +2 -1
  21. package/dist/actions/navigation.js +10 -5
  22. package/dist/actions/reference.js +10 -5
  23. package/dist/actions/types.d.ts +9 -1
  24. package/dist/app/access.d.ts +4 -4
  25. package/dist/app/access.js +33 -71
  26. package/dist/app/action-access.d.ts +2 -2
  27. package/dist/app/action-access.js +6 -4
  28. package/dist/app/service-error.d.ts +2 -2
  29. package/dist/app/service-error.js +10 -6
  30. package/dist/app/types.d.ts +76 -33
  31. package/dist/config-service.d.ts +30 -6
  32. package/dist/config-service.js +25 -9
  33. package/dist/configuration.d.ts +6 -3
  34. package/dist/configuration.js +8 -6
  35. package/dist/contracts.d.ts +4 -2
  36. package/dist/contracts.js +3 -3
  37. package/dist/contribution-origin.d.ts +4 -1
  38. package/dist/contribution-origin.js +14 -1
  39. package/dist/contributions/action.d.ts +26 -0
  40. package/dist/contributions/action.js +171 -0
  41. package/dist/contributions/host.d.ts +14 -11
  42. package/dist/contributions/index.d.ts +1 -26
  43. package/dist/contributions/index.js +1 -18
  44. package/dist/conventions.d.ts +8 -4
  45. package/dist/conventions.js +12 -31
  46. package/dist/core.d.ts +41 -18
  47. package/dist/core.js +25 -13
  48. package/dist/definitions.d.ts +272 -306
  49. package/dist/definitions.js +28 -56
  50. package/dist/destinations.d.ts +25 -0
  51. package/dist/destinations.js +21 -0
  52. package/dist/discovered.d.ts +52 -21
  53. package/dist/discovered.js +89 -35
  54. package/dist/events/define.d.ts +43 -0
  55. package/dist/events/define.js +17 -0
  56. package/dist/events/service.d.ts +35 -8
  57. package/dist/events/service.js +184 -42
  58. package/dist/events/types.d.ts +29 -9
  59. package/dist/inspection/inventory.d.ts +86 -0
  60. package/dist/inspection/inventory.js +132 -0
  61. package/dist/interceptors/define.d.ts +76 -0
  62. package/dist/interceptors/define.js +23 -0
  63. package/dist/interceptors/service-observers.d.ts +6 -3
  64. package/dist/interceptors/service-observers.js +13 -10
  65. package/dist/lifecycle/cleanup.d.ts +5 -0
  66. package/dist/lifecycle/cleanup.js +41 -0
  67. package/dist/lifecycle/controller.d.ts +82 -0
  68. package/dist/lifecycle/controller.js +276 -0
  69. package/dist/lifecycle/reconcile.d.ts +19 -0
  70. package/dist/lifecycle/reconcile.js +68 -0
  71. package/dist/lifecycle/state.d.ts +53 -0
  72. package/dist/lifecycle/state.js +86 -0
  73. package/dist/names.d.ts +10 -0
  74. package/dist/names.js +1 -0
  75. package/dist/pages.d.ts +39 -6
  76. package/dist/pages.js +93 -11
  77. package/dist/presentation.d.ts +9 -0
  78. package/dist/runtime.d.ts +166 -28
  79. package/dist/runtime.js +1485 -248
  80. package/dist/schema.d.ts +13 -0
  81. package/dist/schema.js +38 -0
  82. package/dist/scope.d.ts +59 -4
  83. package/dist/scope.js +133 -11
  84. package/dist/service-key.d.ts +33 -14
  85. package/dist/service-key.js +21 -5
  86. package/dist/service-names.d.ts +39 -0
  87. package/dist/service-names.js +175 -0
  88. package/dist/services.d.ts +24 -5
  89. package/dist/services.js +230 -37
  90. package/dist/settings/access.d.ts +19 -0
  91. package/dist/settings/access.js +78 -0
  92. package/dist/settings/define.d.ts +97 -0
  93. package/dist/settings/define.js +83 -0
  94. package/dist/settings/storage.d.ts +45 -0
  95. package/dist/settings/storage.js +102 -0
  96. package/dist/settings/store.d.ts +74 -0
  97. package/dist/settings/store.js +345 -0
  98. package/dist/slots/action-placement.d.ts +47 -0
  99. package/dist/slots/action-placement.js +1 -0
  100. package/dist/slots/define.d.ts +52 -0
  101. package/dist/slots/define.js +12 -0
  102. package/dist/slots/normalize.d.ts +7 -0
  103. package/dist/slots/normalize.js +36 -0
  104. package/dist/slots/runtime.d.ts +43 -0
  105. package/dist/slots/runtime.js +348 -0
  106. package/dist/slots/types.d.ts +113 -0
  107. package/dist/slots/types.js +1 -0
  108. package/dist/startup-error.d.ts +21 -0
  109. package/dist/startup-error.js +29 -0
  110. package/dist/store.d.ts +24 -0
  111. package/dist/store.js +40 -0
  112. package/dist/translation.d.ts +9 -4
  113. package/dist/translation.js +2 -3
  114. package/examples/todos/actions/create.mjs +1 -3
  115. package/examples/todos/actions/delete.mjs +3 -10
  116. package/examples/todos/actions/list.mjs +1 -3
  117. package/examples/todos/events.mjs +5 -0
  118. package/examples/todos/plugin.mjs +4 -2
  119. package/examples/todos/services/tasks.mjs +14 -20
  120. package/examples/todos.mjs +8 -7
  121. package/package.json +36 -9
  122. package/testing/index.d.ts +59 -0
  123. package/testing/index.mjs +150 -0
  124. package/assets/bitakit-banner.png +0 -0
  125. package/discovery/entries.mjs +0 -124
  126. package/discovery/generate.mjs +0 -321
  127. package/discovery/host.mjs +0 -12
  128. package/discovery/modules.mjs +0 -13
  129. package/discovery/packages.mjs +0 -57
  130. package/discovery/watch.mjs +0 -23
  131. package/dist/app/service-aliases.d.ts +0 -4
  132. package/dist/app/service-aliases.js +0 -14
  133. package/dist/contributions/command.d.ts +0 -8
  134. package/dist/contributions/command.js +0 -59
  135. package/dist/contributions/dialog.d.ts +0 -8
  136. package/dist/contributions/dialog.js +0 -18
  137. package/dist/contributions/form.d.ts +0 -10
  138. package/dist/contributions/form.js +0 -67
  139. package/dist/contributions/native.d.ts +0 -11
  140. package/dist/contributions/native.js +0 -87
  141. package/dist/contributions/shared.d.ts +0 -19
  142. package/dist/contributions/shared.js +0 -48
  143. package/dist/contributions/stateful-action.d.ts +0 -29
  144. package/dist/contributions/stateful-action.js +0 -33
  145. package/dist/events/action-setup.d.ts +0 -19
  146. package/dist/events/action-setup.js +0 -24
  147. package/dist/interceptors/service.d.ts +0 -37
  148. package/dist/interceptors/service.js +0 -7
  149. package/dist/replacements.d.ts +0 -22
  150. package/dist/replacements.js +0 -54
  151. package/dist/validation.d.ts +0 -2
  152. package/dist/validation.js +0 -16
  153. package/docs/auth.md +0 -106
  154. package/docs/events.md +0 -157
  155. package/docs/file-contributions.md +0 -174
  156. package/docs/reference.md +0 -404
  157. package/docs/todo-tutorial.md +0 -88
@@ -1,382 +1,348 @@
1
- import type { Events, EventErrorHandler, FoundationEvent } from './events/types.js';
2
- import type { ActionSetup, ActionSetupContext } from './events/action-setup.js';
3
- import type { ServiceInterceptor } from './interceptors/service.js';
4
- import { type StatefulBuilder } from './contributions/stateful-action.js';
1
+ import type { Events } from './events/types.js';
2
+ import type { EventsDefinition } from './events/define.js';
3
+ import type { Store } from './store.js';
5
4
  import type { ConfigContext, ConfigValues, ConfigDefinition } from './config-service.js';
6
- import type { AuthService, TranslationService } from './contracts.js';
5
+ import type { SettingsAccess } from './settings/access.js';
6
+ import type { SettingsDefinition, SettingsSectionOptions } from './settings/define.js';
7
7
  import type { PresentationType } from './presentation.js';
8
- import type { ActionContext, ActionShortcut, Action, ActionDefinition, ActionPresentation, ActionGroup } from '@bitakit/core/actions';
8
+ import type { ActionContext, ActionShortcut, ActionGroup } from '@bitakit/core/actions';
9
9
  import type { PluginScope } from './scope.js';
10
10
  import type { Feedback, MessageValues } from './actions/feedback.js';
11
- import type { PublicServiceKeys } from './app/types.js';
12
- import type { FoundationApp } from './app/types.js';
13
- /** Augmented by generated service declarations. No global runtime container. */
11
+ import type { BitaKitApp, Namespace } from './app/types.js';
12
+ import type { ServiceKey } from './service-key.js';
13
+ import type { InterceptorSpec } from './interceptors/define.js';
14
+ import type { Confirmation } from './confirmation.js';
15
+ import type { Cleanup } from './lifecycle/cleanup.js';
16
+ import type { SlotDefinition, SlotDefinitions } from './slots/define.js';
17
+ /** Service IDs and aliases with their instance types. Generated from discovery; augmentable by hand. */
14
18
  export interface ServiceMap {
15
- auth?: AuthService;
16
- i18n?: TranslationService;
17
19
  }
18
- export type Services = Readonly<ServiceMap>;
20
+ /** What every contribution sees as `services`: `services.<plugin>.<name>`, plus contract aliases. */
21
+ export type Services = Namespace<ServiceMap>;
19
22
  export type Translator = ((key: string, values?: MessageValues) => string) & {
20
23
  has?: (key: string) => boolean;
21
24
  };
22
- export interface ServiceDefinition<T = unknown> {
23
- id: string;
24
- /** Optional name for this same instance in app.services. Discovery defaults to the file path. */
25
- exposeAs?: string;
26
- requires?: readonly string[];
27
- create(context: {
28
- services: Services;
29
- config: ConfigContext;
30
- events: Events;
31
- }): T;
32
- dispose?: (instance: T) => void;
33
- }
34
- export declare function defineService<const ID extends string, T, const Name extends string>(definition: ServiceDefinition<T> & {
35
- id: ID;
36
- exposeAs: Name;
37
- }): ServiceDefinition<T> & {
38
- id: ID;
39
- exposeAs: Name;
40
- };
41
- export declare function defineService<T, const Name extends string>(definition: Omit<ServiceDefinition<T>, 'id'> & {
42
- exposeAs: Name;
43
- }): Omit<ServiceDefinition<T>, 'id'> & {
44
- exposeAs: Name;
45
- };
46
- export declare function defineService<const ID extends string, T>(definition: ServiceDefinition<T> & {
47
- id: ID;
48
- }): ServiceDefinition<T> & {
49
- id: ID;
50
- };
51
- export declare function defineService<T>(definition: Omit<ServiceDefinition<T>, 'id'>): Omit<ServiceDefinition<T>, 'id'>;
52
- export type FoundationInterceptor = {
53
- before(context: ActionContext & {
54
- config: ConfigContext;
55
- }): boolean | void | Promise<boolean | void>;
25
+ export type ServiceContext = {
26
+ services: Services;
27
+ config: ConfigContext;
28
+ events: Events;
29
+ /** Typed setting handles: `settings.todos.pageSize.get()`. */
30
+ settings: SettingsAccess;
31
+ /** Observable state; actions and `useServiceState` follow it automatically. */
32
+ store<T>(initial: T): Store<T>;
33
+ /** Awaited in dependency order before the app is ready. */
34
+ onStart(hook: (context: {
35
+ signal: AbortSignal;
36
+ }) => void | Promise<void>): void;
37
+ /** Awaited when the runtime stops, in reverse dependency/registration order. */
38
+ onStop(hook: () => void | Promise<void>): void;
56
39
  };
57
- export type InterceptorDefinition = {
40
+ export type ServiceOptions = {
41
+ /** Optional explicit ID; otherwise discovery derives `<plugin>.<file>`. */
42
+ id?: string;
43
+ /** Services this one needs inside `create`; also an explicit startup check. */
58
44
  requires?: readonly string[];
59
- order?: number;
60
- scope?: 'plugin' | 'global';
61
- create(context: {
62
- services: Services;
63
- translate: Translator;
64
- config: ConfigContext;
65
- }): FoundationInterceptor;
66
- };
67
- export declare function defineInterceptor(definition: InterceptorDefinition): InterceptorDefinition;
68
- export declare function defineInterceptor(definition: FoundationInterceptor & {
69
- order?: number;
70
- scope?: 'plugin' | 'global';
71
- }): FoundationInterceptor;
72
- export type ActionInterceptorEntry = (InterceptorDefinition | FoundationInterceptor) & {
73
- kind?: 'action';
74
- order?: number;
75
- scope?: 'plugin' | 'global';
45
+ /** Registers the instance under a shared contract key as well, such as `auth`. */
46
+ provides?: ServiceKey<any>;
47
+ /** An extra flat alias in `services`; use sparingly. */
48
+ exposeAs?: string;
76
49
  };
77
- export type InterceptorEntry = ActionInterceptorEntry | ServiceInterceptor;
78
- /** Explicit Action discriminator; the legacy defineInterceptor helper remains supported. */
79
- export declare function defineActionInterceptor<T extends ActionInterceptorEntry>(definition: T): T & {
80
- kind: 'action';
50
+ export type ServiceDefinition<T = unknown> = ServiceOptions & {
51
+ readonly kind: 'service';
52
+ create(context: ServiceContext): T;
81
53
  };
82
- /** Ordered outside-in. Dependencies must already appear before this provider. */
83
- export type ProviderDefinition = {
84
- id: string;
85
- component: PresentationType<'provider'>;
86
- requires?: readonly string[];
54
+ /** The instance type a contract key demands. */
55
+ type ContractOf<Key> = Key extends ServiceKey<infer Contract, string> ? Contract : unknown;
56
+ /**
57
+ * With `provides`, the factory's instance must satisfy the contract; the constraint is checked
58
+ * after inference, so a destructured context parameter still infers the instance type.
59
+ */
60
+ export declare function defineService<const Options extends ServiceOptions & {
61
+ provides: ServiceKey<any>;
62
+ }, T extends ContractOf<Options['provides']>>(create: (context: ServiceContext) => T, options: Options): ServiceDefinition<T> & Options;
63
+ export declare function defineService<T, const Options extends ServiceOptions & {
64
+ provides?: undefined;
65
+ } = {}>(create: (context: ServiceContext) => T, options?: Options): ServiceDefinition<T> & Options;
66
+ export declare function isServiceDefinition(value: unknown): value is ServiceDefinition;
67
+ /**
68
+ * What presentation functions and `confirm` receive. Menus, search, group items and slot
69
+ * placements without an input mapping evaluate them without input, so `input` may be undefined;
70
+ * they also see the raw value before schema validation. Only `execute` receives the parsed input.
71
+ */
72
+ export type PresentationContext<Input = unknown> = {
73
+ input: Input | undefined;
74
+ services: Services;
75
+ config: ConfigContext;
76
+ settings: SettingsAccess;
77
+ app: BitaKitApp;
87
78
  };
88
- export declare function defineProvider(definition: ProviderDefinition): ProviderDefinition;
89
- export type Field = {
90
- type: 'text' | 'email' | 'select';
91
- label?: string;
92
- required?: boolean;
93
- defaultValue?: string;
94
- options?: readonly {
95
- value: string;
96
- label: string;
97
- }[];
79
+ /** A value, or a function of the current input and services; functions re-run on service changes. */
80
+ export type Dynamic<Input, Value> = Value | ((context: PresentationContext<Input>) => Value);
81
+ export type ExecuteContext<Input = unknown> = ActionContext<Input> & {
82
+ services: Services;
83
+ config: ConfigContext;
84
+ settings: SettingsAccess;
85
+ app: BitaKitApp;
86
+ events: Events;
87
+ /** Aborts when the registration is disposed, or when a newer `latest` run supersedes this one. */
88
+ signal: AbortSignal;
98
89
  };
99
- export type Fields = Readonly<Record<string, Field>>;
100
- export type Values<F extends Fields> = {
101
- [K in keyof F]: string;
90
+ export type Concurrency = 'exclusive' | 'per-input' | 'latest';
91
+ export type DialogSpec = {
92
+ component: PresentationType<'component'>;
93
+ /**
94
+ * A frame the host registered under `dialogs`. Built in: `dialog` (the default) and `command`,
95
+ * a search palette whose content leads with its own search field.
96
+ */
97
+ kind?: string;
98
+ size?: 'default' | 'wide';
102
99
  };
103
- export type FormRenderProps = {
104
- values: Readonly<Record<string, string>>;
105
- setValue(name: string, value: string): void;
106
- submit(event: {
107
- preventDefault(): void;
108
- }): void;
109
- pending: boolean;
110
- enabled: boolean;
111
- error: string | null;
100
+ /** The dialog of an action in object form, whichever way it was declared. */
101
+ export declare function dialogOf(spec: Pick<ActionSpecInput<any, any>, 'dialog' | 'dialogSize'>): DialogSpec | undefined;
102
+ /** zod, valibot and friends: `parse`, or Standard Schema `~standard.validate`. */
103
+ export type InputSchema<T> = {
104
+ parse(input: unknown): T;
105
+ } | {
106
+ '~standard': {
107
+ validate(input: unknown): {
108
+ value: T;
109
+ } | {
110
+ issues: readonly {
111
+ message: string;
112
+ }[];
113
+ } | Promise<{
114
+ value: T;
115
+ } | {
116
+ issues: readonly {
117
+ message: string;
118
+ }[];
119
+ }>;
120
+ };
112
121
  };
113
- export type ActionConventions = Partial<Pick<ActionDefinition, 'title' | 'description' | 'icon' | 'tooltip' | 'shortcut' | 'enabled' | 'visible' | 'dependsOn' | 'dividerBefore'>> & {
122
+ export type SchemaOutput<S> = S extends {
123
+ parse(input: unknown): infer T;
124
+ } ? T : S extends {
125
+ '~standard': {
126
+ validate(input: unknown): infer R;
127
+ };
128
+ } ? Extract<Awaited<R>, {
129
+ value: unknown;
130
+ }>['value'] : never;
131
+ export type ActionSpecInput<Input = unknown, Result = unknown> = {
132
+ /** Manual composition only; discovery derives `<plugin>.<file>`. */
114
133
  id?: string;
115
- /** App-only: explicitly replace a plugin action while preserving its public ID. */
116
- replaces?: string;
134
+ /** A literal or a translation key. The `<id>.title` key wins when the catalog has it. */
135
+ title?: Dynamic<Input, string>;
136
+ description?: Dynamic<Input, string | undefined>;
137
+ tooltip?: Dynamic<Input, string | undefined>;
138
+ /** Static: a component value cannot be told apart from a presentation function. */
139
+ icon?: PresentationType<'icon'>;
140
+ variant?: Dynamic<Input, 'default' | 'destructive' | undefined>;
141
+ /** A navigation action: rendered as a link, executed as navigation. */
142
+ href?: Dynamic<Input, string | undefined>;
143
+ enabled?: Dynamic<Input, boolean>;
144
+ visible?: Dynamic<Input, boolean>;
145
+ checked?: Dynamic<Input, boolean | undefined>;
146
+ /** `{} | null | undefined` instead of `unknown`, so a function here keeps its contextual types. */
147
+ value?: Dynamic<Input, {} | null | undefined>;
117
148
  groups?: readonly (string | ActionGroup)[];
149
+ /** Explicit UI placements; groups remain logical membership. */
150
+ slots?: readonly import('./slots/action-placement.js').ActionSlotPlacement<Input>[];
118
151
  order?: number;
119
- conventions?: boolean;
120
- /** Explicit local config path for manual registration; discovery supplies it otherwise. */
121
- configPath?: readonly string[];
122
- };
123
- /** Literal `id`/`replaces` values survive the builders so ActionMap entries use the effective ID. */
124
- type Identity<Id extends string, Replaces extends string> = {
125
- id?: Id;
126
- replaces?: Replaces;
127
- };
128
- export type FormDefinition<F extends Fields = Fields, Result = unknown> = ActionConventions & {
129
- kind: 'form';
152
+ dividerBefore?: boolean;
153
+ shortcut?: ActionShortcut<Input>;
154
+ /** Validates and types the input. */
155
+ input?: InputSchema<Input>;
156
+ /** Services from other plugins this action uses; an explicit startup check. */
130
157
  requires?: readonly string[];
131
- fields: F;
132
- submit(values: Values<F>, context: {
133
- services: Services;
134
- config: ConfigContext;
135
- input?: unknown;
136
- }): Result | Promise<Result>;
137
- closeOnSuccess?: boolean;
158
+ /** `exclusive` skips while running, `per-input` tracks each input, `latest` aborts the previous run. */
159
+ concurrency?: Concurrency;
160
+ /** Key for `per-input` pending when the input is not a primitive. */
161
+ concurrencyKey?: (input: Input) => string;
162
+ /** Ask before running; declining skips with reason "cancelled". */
163
+ confirm?: Dynamic<Input, Confirmation | string | false | undefined>;
164
+ /**
165
+ * Opens this component in the host dialog instead of running `execute`. The object form
166
+ * names the host frame (`kind`, for example `sheet`) and the size; the host decides the look.
167
+ */
168
+ dialog?: PresentationType<'component'> | DialogSpec;
169
+ /** @deprecated Use `dialog: { component, size }`. */
170
+ dialogSize?: 'default' | 'wide';
171
+ execute?: (context: ExecuteContext<Input>) => Result | Promise<Result>;
138
172
  success?: Feedback<{
139
- result: NoInfer<Awaited<Result>>;
140
- input: Values<F>;
173
+ result: Awaited<Result>;
174
+ input: Input;
141
175
  services: Services;
142
176
  }>;
143
177
  failure?: Feedback<{
144
178
  error: unknown;
145
- input: Values<F>;
179
+ input: Input;
146
180
  services: Services;
147
181
  }>;
148
- render?: (props: FormRenderProps) => PresentationType<'node'>;
182
+ /** Executable by ID but excluded from menus, search and enumeration. */
183
+ internal?: boolean;
184
+ /** Opaque host metadata; Core never interprets it. */
185
+ metadata?: unknown;
149
186
  };
150
- 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>;
151
- export type DialogDefinition<Input = unknown> = ActionConventions & {
152
- kind: 'dialog';
153
- size?: 'default' | 'wide';
154
- requires?: readonly string[];
155
- watch?: readonly string[];
156
- resolve?: (input: Input, context: {
157
- services: Services;
158
- config: ConfigContext;
159
- }) => ActionPresentation;
160
- render(props: {
161
- input: Input;
162
- close(): void;
163
- services: Services;
164
- }): PresentationType<'node'>;
187
+ export type ActionSpec<Input = unknown, Result = unknown> = ActionSpecInput<Input, Result> & {
188
+ readonly kind: 'action';
165
189
  };
166
- 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>;
167
- /** Context supplied automatically to an exported Action class or function. */
168
- export type ActionEnvironment = {
190
+ /**
191
+ * The one way to define an action. Pass an `input` schema to infer the input type, or name it
192
+ * explicitly: `defineAction<string>({ ... })`.
193
+ */
194
+ export declare function defineAction<S extends InputSchema<any>, Result = unknown>(spec: ActionSpecInput<SchemaOutput<S>, Result> & {
195
+ input: S;
196
+ }): ActionSpec<SchemaOutput<S>, Result>;
197
+ export declare function defineAction<Input = unknown, Result = unknown>(spec: ActionSpecInput<Input, Result> & {
198
+ input?: undefined;
199
+ }): ActionSpec<Input, Result>;
200
+ export declare function isActionSpec(value: unknown): value is ActionSpec;
201
+ /** `scope` is the plugin's own scope (slots, groups, cleanup); `app` always means the whole application. */
202
+ export type Setup = (context: {
203
+ scope: PluginScope;
169
204
  services: Services;
170
- translate: Translator;
171
- config: ConfigContext;
205
+ }) => void | Cleanup;
206
+ /** A component placed in a named slot of a layout. */
207
+ export type PluginView = {
208
+ slot: string;
209
+ component: PresentationType<'component'>;
210
+ order?: number;
211
+ id?: string;
212
+ key?: string;
213
+ availability?: import('./slots/types.js').SlotAvailability;
214
+ when?: import('./slots/types.js').SlotPredicate;
172
215
  };
173
- export type ActionExport = (new (context: ActionEnvironment) => Action<any, any>) | ((context: ActionEnvironment) => Action<any, any>);
174
- /** Internal normalized representation; application code exports classes/functions directly. */
175
- export type NativeDefinition = ActionConventions & {
176
- kind: 'native';
177
- requires?: readonly string[];
178
- load(context: ActionEnvironment): Action<any, any>;
179
- fromExport?: boolean;
216
+ export type PluginPageDefinition = {
217
+ path: string;
218
+ component: PresentationType<'component'>;
219
+ /** Layout name; `app` by default, `blank` for none. */
220
+ layout?: string;
180
221
  };
181
- /** Navigation retains native link semantics and programmatic URLAction execution. */
182
- export declare function defineURLAction<const Id extends string = string, const Replaces extends string = string>(definition: Omit<ActionConventions, 'id' | 'replaces'> & Identity<Id, Replaces> & {
183
- href: string;
184
- }): NativeDefinition & Identity<Id, Replaces>;
185
- export type PlainDefinition<Input = unknown, Result = unknown, Name extends string = string> = Omit<ActionConventions, 'shortcut'> & Omit<ActionDefinition, 'id' | 'title' | 'groups' | 'execute' | 'resolve' | 'shortcut'> & {
186
- shortcut?: ActionShortcut<NoInfer<Input>>;
187
- kind: 'action';
188
- /** Runs once per registration; events.watch subscriptions are automatically owned. */
189
- setup?: ActionSetup;
190
- /** Named custom events delivered to onEvent; independent of observable-service watch. */
191
- events?: readonly Name[];
192
- onEvent?(event: FoundationEvent<NoInfer<Name>>, context: ActionSetupContext & {
193
- signal: AbortSignal;
194
- }): void | Promise<void>;
222
+ /** Ordered outside-in. Dependencies must already appear before this provider. */
223
+ export type ProviderDefinition = {
224
+ id: string;
225
+ component: PresentationType<'provider'>;
195
226
  requires?: readonly string[];
196
- /** Observable services that invalidate presentation; subscribed once per runtime. */
197
- watch?: readonly string[];
198
- resolve?: (input: Input, context: {
199
- services: Services;
200
- config: ConfigContext;
201
- }) => ActionPresentation;
202
- execute?: (context: ActionContext<Input> & {
203
- services: Services;
204
- config: ConfigContext;
205
- app: FoundationApp;
206
- }) => Result | Promise<Result>;
207
- success?: Feedback<{
208
- result: NoInfer<Awaited<Result>>;
209
- input: Input;
210
- services: Services;
211
- }>;
212
- failure?: Feedback<{
213
- error: unknown;
214
- input: Input;
215
- services: Services;
216
- }>;
217
227
  };
218
- /**
219
- * `Result` is inferred from `execute`. Type `Input` by annotating the first `resolve`
220
- * parameter, or pass both arguments explicitly: `defineAction<MemberContext, void>({...})`.
221
- */
222
- export declare function defineAction<Input>(): StatefulBuilder<Input>;
223
- export declare function defineAction<Input = unknown, Result = void, const Id extends string = string, const Replaces extends string = string, const Name extends string = string>(definition: Omit<PlainDefinition<Input, Result, Name>, 'kind' | 'id' | 'replaces'> & Identity<Id, Replaces> & {
224
- unavailable?: {
225
- messageKey: string;
226
- };
227
- }): PlainDefinition<Input, Result, Name> & Identity<Id, Replaces>;
228
- export type Contribution = FormDefinition<any, any> | DialogDefinition<any> | NativeDefinition | PlainDefinition<any, any> | ActionExport;
229
- export type ResolvedContribution = Exclude<Contribution, ActionExport> & {
230
- id: string;
228
+ /** `ui/settings/page.tsx`: replaces the generated settings page of the plugin. */
229
+ export type PluginSettingsPage = {
230
+ /** Wraps the entire page, including extension outlets, in the owner's access boundary. */
231
+ boundary?: PresentationType<'component'>;
232
+ /** False when the page renders its own shared PageHeader. */
233
+ showHeader?: boolean;
234
+ component?: PresentationType<'component'>;
235
+ /** Additional independently addressable pages, rendered by the existing settings host. */
236
+ pages?: readonly (SettingsSectionOptions & {
237
+ id: string;
238
+ showHeader?: boolean;
239
+ boundary?: PresentationType<'component'>;
240
+ component: PresentationType<'component'>;
241
+ })[];
231
242
  };
232
- export type ResolvedForm = FormDefinition<Fields, any> & {
233
- id: string;
243
+ export type PluginUI = {
244
+ pages?: readonly PluginPageDefinition[];
245
+ slots?: readonly PluginView[];
246
+ providers?: readonly ProviderDefinition[];
247
+ settings?: PluginSettingsPage;
248
+ /** App only: `src/layouts/<name>.tsx`; pages choose one with `export const layout = '<name>'`. */
249
+ layouts?: Readonly<Record<string, PresentationType<'component'>>>;
234
250
  };
235
- /** A literal string wins; a widened `string` or a missing value falls back. */
236
- type LiteralOr<Value, Fallback> = [NonNullable<Value>] extends [string] ? string extends NonNullable<Value> ? Fallback : NonNullable<Value> : Fallback;
237
- /** The ID a contribution registers under when discovered at `Path`: `replaces`, then `id`, then the path. */
238
- export type EffectiveActionId<T, Path extends string> = T extends {
239
- replaces?: infer Replaces;
240
- } ? LiteralOr<Replaces, T extends {
241
- id?: infer Id;
242
- } ? LiteralOr<Id, Path> : Path> : Path;
243
- /**
244
- * Input and result of a definition for ActionMap. Class and function exports establish their ID
245
- * at construction and therefore contribute no entry; augment ActionMap manually for those.
246
- */
247
- export type ActionSignature<T> = T extends ActionExport ? never : T extends PlainDefinition<infer Input, infer Result> ? {
248
- input: Input;
249
- result: Awaited<Result>;
250
- } & (T extends {
251
- initialState: infer State;
252
- } ? {
253
- state: State;
254
- } : {}) : T extends FormDefinition<any, any> ? {
255
- input: unknown;
256
- result: void;
257
- } : T extends DialogDefinition<infer Input> ? {
258
- input: Input;
259
- result: void;
260
- } : T extends NativeDefinition ? {
261
- input: void;
262
- result: void;
263
- } : never;
264
- /** One ActionMap entry for a discovered file; build tooling intersects these into the augmentation. */
265
- export type ActionEntry<T, Path extends string> = [ActionSignature<T>] extends [never] ? {} : {
266
- [Key in EffectiveActionId<T, Path>]: ActionSignature<T>;
251
+ /** Public display information only; package authors remain the source of truth. */
252
+ export type PluginMetadata = {
253
+ coverImage?: string;
254
+ /** Catalog labels; presentation only, never permissions or dependencies. */
255
+ tags?: readonly string[];
256
+ icon?: PresentationType<'icon'>;
257
+ name?: string;
258
+ version?: string;
259
+ description?: string;
260
+ author?: string | {
261
+ name: string;
262
+ email?: string;
263
+ url?: string;
264
+ };
265
+ homepage?: string;
266
+ bugs?: string | {
267
+ url?: string;
268
+ email?: string;
269
+ };
270
+ license?: string;
267
271
  };
268
- export type Setup = (context: {
269
- app: PluginScope;
270
- services: Services;
271
- }) => void | (() => void);
272
- /**
273
- * Contribution kinds provided by optional integrations, keyed by kind name. An integration
274
- * augments this map with the value type its normalizer produces, e.g. `'settings.sections': Section`.
275
- */
272
+ /** Contribution kinds provided by optional integrations, keyed by kind name. */
276
273
  export interface ContributionMap {
277
274
  }
278
- /** Declarative values a module contributes; Core routes each kind to the installer that claims it. */
279
275
  export type ContributionSet = {
280
276
  readonly [K in keyof ContributionMap]?: readonly ContributionMap[K][];
281
277
  } & {
282
278
  readonly [kind: string]: readonly unknown[] | undefined;
283
279
  };
284
280
  export type ContributionContext = {
285
- /** The contributing module. */
286
281
  module: string;
287
- /** True for the application module. */
288
282
  app: boolean;
289
283
  services: Services;
290
284
  };
291
- /**
292
- * Installs one module's values of a kind. Runs during mount after services, translation and
293
- * interceptors, before actions and setup. The returned cleanup belongs to the contributing module.
294
- */
295
- export type ContributionInstaller<T = unknown> = (values: readonly T[], context: ContributionContext) => void | (() => void);
285
+ export type ContributionInstaller<T = unknown> = (values: readonly T[], context: ContributionContext) => void | Cleanup;
296
286
  export type ContributionInstallers = {
297
287
  readonly [K in keyof ContributionMap]?: ContributionInstaller<ContributionMap[K]>;
298
288
  } & {
299
289
  readonly [kind: string]: ContributionInstaller<any> | undefined;
300
290
  };
301
- export declare function defineSetup(setup: Setup): Setup;
302
- export type PluginView = {
303
- slot: string;
304
- component: PresentationType<'component'>;
305
- order?: number;
306
- };
307
- export declare function defineView(view: PluginView): PluginView;
308
- export type PluginPageDefinition = {
309
- path: string;
310
- component: PresentationType<'component'>;
311
- };
312
- export declare function definePage(page: PluginPageDefinition): PluginPageDefinition;
291
+ /** Services and actions may be records keyed by name (IDs become `<plugin>.<name>`) or arrays with IDs. */
313
292
  export type Plugin = {
314
- /** Aliases for externally supplied services or existing compositions. Prefer service.exposeAs. */
315
- publicServices?: PublicServiceKeys;
316
- /** Instance-local projections owned by optional packages; never a second state store. */
317
- appExtensions?: Readonly<Record<string, (runtime: import('./runtime.js').FoundationRuntime) => unknown>>;
318
- config?: ConfigValues | ConfigDefinition;
319
- interceptors?: readonly InterceptorEntry[];
320
- providers?: readonly ProviderDefinition[];
321
- metadata?: PluginMetadata;
322
- pages?: readonly PluginPageDefinition[];
323
- views?: readonly PluginView[];
324
293
  id: string;
325
294
  dependencies?: readonly string[];
326
- services?: readonly ServiceDefinition<any>[];
327
- actions?: readonly Contribution[];
295
+ /**
296
+ * The plugin that owns this one; discovery sets it for a nested plugin folder. It counts as a
297
+ * dependency, so the parent starts first. Disabling or removing the parent always includes its
298
+ * descendants; disabling this plugin never affects the parent.
299
+ */
300
+ parent?: string;
301
+ metadata?: PluginMetadata;
302
+ services?: readonly ServiceDefinition<any>[] | Readonly<Record<string, ServiceDefinition<any>>>;
303
+ actions?: readonly ActionSpec<any, any>[] | Readonly<Record<string, ActionSpec<any, any>>>;
304
+ /** Owned declarations; `ui.slots` contains components contributed to a target. */
305
+ slots?: SlotDefinitions | readonly SlotDefinition[];
306
+ events?: EventsDefinition<any>;
307
+ settings?: SettingsDefinition<any>;
308
+ config?: ConfigValues | ConfigDefinition;
309
+ interceptors?: readonly InterceptorSpec[];
328
310
  setup?: Setup;
311
+ ui?: PluginUI;
329
312
  /** Declarative values for installers provided by integrations. */
330
313
  contributions?: ContributionSet;
331
314
  /** Installers for contribution kinds this module owns. One module per kind. */
332
315
  installs?: ContributionInstallers;
333
316
  };
334
317
  export declare function definePlugin<const T extends Plugin>(plugin: T): T;
335
- export type FoundationConfig = {
336
- /** Receives synchronous throws and async rejections from event handlers. */
337
- onEventError?: EventErrorHandler;
338
- publicServices?: PublicServiceKeys;
339
- /** Instance-local projections owned by optional packages; never a second state store. */
340
- appExtensions?: Readonly<Record<string, (runtime: import('./runtime.js').FoundationRuntime) => unknown>>;
341
- metadata?: PluginMetadata;
342
- dependencies?: readonly string[];
343
- pages?: readonly PluginPageDefinition[];
344
- views?: readonly PluginView[];
345
- setup?: Setup;
318
+ export type BitaKitRuntimeConfig = Omit<Plugin, 'id' | 'dependencies' | 'parent'> & {
346
319
  appId?: string;
347
- config?: ConfigValues | ConfigDefinition;
320
+ dependencies?: readonly string[];
321
+ /** Receives synchronous throws and async rejections from event handlers. */
322
+ onEventError?: import('./events/types.js').EventErrorHandler;
348
323
  configOverrides?: Readonly<Record<string, ConfigValues>>;
349
- services?: readonly ServiceDefinition<any>[];
350
324
  groups?: readonly string[];
351
325
  actionOverrides?: Readonly<Record<string, {
352
326
  enabled?: boolean;
353
327
  visible?: boolean;
354
328
  }>>;
355
- actions?: readonly Contribution[];
356
- interceptors?: readonly InterceptorEntry[];
357
- providers?: readonly ProviderDefinition[];
358
329
  plugins?: readonly Plugin[];
359
- contributions?: ContributionSet;
360
- installs?: ContributionInstallers;
361
330
  };
362
- /** Public display information only; package authors remain the source of truth. */
363
- export type PluginMetadata = {
364
- /** Optional presentation image; the UI falls back to the plugin icon. */
365
- coverImage?: string;
366
- icon?: PresentationType<'icon'>;
367
- name?: string;
368
- version?: string;
369
- description?: string;
370
- author?: string | {
371
- name: string;
372
- email?: string;
373
- url?: string;
374
- };
375
- homepage?: string;
376
- bugs?: string | {
377
- url?: string;
378
- email?: string;
379
- };
380
- license?: string;
331
+ /** A literal string wins; a widened `string` or a missing value falls back. */
332
+ type LiteralOr<Value, Fallback> = [NonNullable<Value>] extends [string] ? string extends NonNullable<Value> ? Fallback : NonNullable<Value> : Fallback;
333
+ /** The ID a contribution registers under when discovered at `Path`: `id`, then the path. */
334
+ export type EffectiveActionId<T, Path extends string> = T extends {
335
+ id?: infer Id;
336
+ } ? LiteralOr<Id, Path> : Path;
337
+ export type ActionSignature<T> = T extends ActionSpec<infer Input, infer Result> ? {
338
+ input: Input;
339
+ result: Awaited<Result>;
340
+ } : never;
341
+ export type ActionEntry<T, Path extends string> = [ActionSignature<T>] extends [never] ? {} : {
342
+ [Key in EffectiveActionId<T, Path>]: ActionSignature<T>;
343
+ };
344
+ export type Contribution = ActionSpec<any, any>;
345
+ export type ResolvedContribution = ActionSpec<any, any> & {
346
+ id: string;
381
347
  };
382
348
  export {};