@bitakit/core 0.1.1 → 0.2.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 (158) hide show
  1. package/README.md +47 -161
  2. package/assets/bitakit-logo-dark.svg +11 -0
  3. package/assets/bitakit-logo.svg +11 -0
  4. package/discovery/index.d.ts +1 -41
  5. package/discovery/index.mjs +1 -4
  6. package/dist/actions/action-list.d.ts +4 -0
  7. package/dist/actions/action-list.js +58 -16
  8. package/dist/actions/action.d.ts +2 -0
  9. package/dist/actions/action.js +4 -0
  10. package/dist/actions/brand.d.ts +21 -0
  11. package/dist/actions/brand.js +36 -0
  12. package/dist/actions/core.d.ts +4 -3
  13. package/dist/actions/core.js +4 -2
  14. package/dist/actions/execution.d.ts +2 -2
  15. package/dist/actions/execution.js +61 -9
  16. package/dist/actions/feedback.d.ts +2 -0
  17. package/dist/actions/feedback.js +8 -0
  18. package/dist/actions/groups.js +5 -1
  19. package/dist/actions/instance-bindings.js +3 -2
  20. package/dist/actions/interceptors.d.ts +9 -3
  21. package/dist/actions/interceptors.js +31 -3
  22. package/dist/actions/navigation.d.ts +2 -1
  23. package/dist/actions/navigation.js +10 -5
  24. package/dist/actions/reference.js +10 -5
  25. package/dist/actions/types.d.ts +9 -1
  26. package/dist/app/access.d.ts +4 -4
  27. package/dist/app/access.js +33 -71
  28. package/dist/app/action-access.d.ts +2 -2
  29. package/dist/app/action-access.js +6 -4
  30. package/dist/app/service-error.d.ts +2 -2
  31. package/dist/app/service-error.js +10 -6
  32. package/dist/app/types.d.ts +76 -33
  33. package/dist/config-service.d.ts +30 -6
  34. package/dist/config-service.js +25 -9
  35. package/dist/configuration.d.ts +6 -3
  36. package/dist/configuration.js +8 -6
  37. package/dist/contracts.d.ts +4 -2
  38. package/dist/contracts.js +3 -3
  39. package/dist/contribution-origin.d.ts +4 -1
  40. package/dist/contribution-origin.js +14 -1
  41. package/dist/contributions/action.d.ts +26 -0
  42. package/dist/contributions/action.js +171 -0
  43. package/dist/contributions/host.d.ts +14 -11
  44. package/dist/contributions/index.d.ts +1 -26
  45. package/dist/contributions/index.js +1 -18
  46. package/dist/conventions.d.ts +8 -4
  47. package/dist/conventions.js +12 -31
  48. package/dist/core.d.ts +41 -18
  49. package/dist/core.js +25 -13
  50. package/dist/definitions.d.ts +272 -306
  51. package/dist/definitions.js +28 -56
  52. package/dist/destinations.d.ts +25 -0
  53. package/dist/destinations.js +21 -0
  54. package/dist/discovered.d.ts +52 -21
  55. package/dist/discovered.js +89 -35
  56. package/dist/events/define.d.ts +43 -0
  57. package/dist/events/define.js +17 -0
  58. package/dist/events/service.d.ts +35 -8
  59. package/dist/events/service.js +184 -42
  60. package/dist/events/types.d.ts +29 -9
  61. package/dist/inspection/inventory.d.ts +86 -0
  62. package/dist/inspection/inventory.js +132 -0
  63. package/dist/interceptors/define.d.ts +76 -0
  64. package/dist/interceptors/define.js +23 -0
  65. package/dist/interceptors/service-observers.d.ts +6 -3
  66. package/dist/interceptors/service-observers.js +13 -10
  67. package/dist/lifecycle/cleanup.d.ts +5 -0
  68. package/dist/lifecycle/cleanup.js +41 -0
  69. package/dist/lifecycle/controller.d.ts +82 -0
  70. package/dist/lifecycle/controller.js +276 -0
  71. package/dist/lifecycle/reconcile.d.ts +19 -0
  72. package/dist/lifecycle/reconcile.js +68 -0
  73. package/dist/lifecycle/state.d.ts +53 -0
  74. package/dist/lifecycle/state.js +86 -0
  75. package/dist/names.d.ts +10 -0
  76. package/dist/names.js +1 -0
  77. package/dist/pages.d.ts +39 -6
  78. package/dist/pages.js +93 -11
  79. package/dist/presentation.d.ts +9 -0
  80. package/dist/runtime.d.ts +166 -28
  81. package/dist/runtime.js +1485 -248
  82. package/dist/schema.d.ts +13 -0
  83. package/dist/schema.js +38 -0
  84. package/dist/scope.d.ts +59 -4
  85. package/dist/scope.js +133 -11
  86. package/dist/service-key.d.ts +33 -14
  87. package/dist/service-key.js +21 -5
  88. package/dist/service-names.d.ts +39 -0
  89. package/dist/service-names.js +175 -0
  90. package/dist/services.d.ts +24 -5
  91. package/dist/services.js +230 -37
  92. package/dist/settings/access.d.ts +19 -0
  93. package/dist/settings/access.js +78 -0
  94. package/dist/settings/define.d.ts +97 -0
  95. package/dist/settings/define.js +83 -0
  96. package/dist/settings/storage.d.ts +45 -0
  97. package/dist/settings/storage.js +102 -0
  98. package/dist/settings/store.d.ts +74 -0
  99. package/dist/settings/store.js +345 -0
  100. package/dist/slots/action-placement.d.ts +47 -0
  101. package/dist/slots/action-placement.js +1 -0
  102. package/dist/slots/define.d.ts +52 -0
  103. package/dist/slots/define.js +12 -0
  104. package/dist/slots/normalize.d.ts +7 -0
  105. package/dist/slots/normalize.js +36 -0
  106. package/dist/slots/runtime.d.ts +43 -0
  107. package/dist/slots/runtime.js +348 -0
  108. package/dist/slots/types.d.ts +113 -0
  109. package/dist/slots/types.js +1 -0
  110. package/dist/startup-error.d.ts +21 -0
  111. package/dist/startup-error.js +29 -0
  112. package/dist/store.d.ts +24 -0
  113. package/dist/store.js +40 -0
  114. package/dist/translation.d.ts +9 -4
  115. package/dist/translation.js +2 -3
  116. package/examples/todos/actions/create.mjs +1 -3
  117. package/examples/todos/actions/delete.mjs +3 -10
  118. package/examples/todos/actions/list.mjs +1 -3
  119. package/examples/todos/events.mjs +5 -0
  120. package/examples/todos/plugin.mjs +4 -2
  121. package/examples/todos/services/tasks.mjs +14 -20
  122. package/examples/todos.mjs +8 -7
  123. package/package.json +37 -9
  124. package/testing/index.d.ts +59 -0
  125. package/testing/index.mjs +150 -0
  126. package/discovery/entries.mjs +0 -124
  127. package/discovery/generate.mjs +0 -321
  128. package/discovery/host.mjs +0 -12
  129. package/discovery/modules.mjs +0 -13
  130. package/discovery/packages.mjs +0 -57
  131. package/discovery/watch.mjs +0 -23
  132. package/dist/app/service-aliases.d.ts +0 -4
  133. package/dist/app/service-aliases.js +0 -14
  134. package/dist/contributions/command.d.ts +0 -8
  135. package/dist/contributions/command.js +0 -59
  136. package/dist/contributions/dialog.d.ts +0 -8
  137. package/dist/contributions/dialog.js +0 -18
  138. package/dist/contributions/form.d.ts +0 -10
  139. package/dist/contributions/form.js +0 -67
  140. package/dist/contributions/native.d.ts +0 -11
  141. package/dist/contributions/native.js +0 -87
  142. package/dist/contributions/shared.d.ts +0 -19
  143. package/dist/contributions/shared.js +0 -48
  144. package/dist/contributions/stateful-action.d.ts +0 -29
  145. package/dist/contributions/stateful-action.js +0 -33
  146. package/dist/events/action-setup.d.ts +0 -19
  147. package/dist/events/action-setup.js +0 -24
  148. package/dist/interceptors/service.d.ts +0 -37
  149. package/dist/interceptors/service.js +0 -7
  150. package/dist/replacements.d.ts +0 -22
  151. package/dist/replacements.js +0 -54
  152. package/dist/validation.d.ts +0 -2
  153. package/dist/validation.js +0 -16
  154. package/docs/auth.md +0 -106
  155. package/docs/events.md +0 -157
  156. package/docs/file-contributions.md +0 -174
  157. package/docs/reference.md +0 -404
  158. package/docs/todo-tutorial.md +0 -88
@@ -1,58 +1,101 @@
1
1
  import type { ActionReference, KnownActionId } from '../actions/core.js';
2
2
  import type { ConfigMap } from '../config-service.js';
3
- import type { Plugin } from '../definitions.js';
4
- import type { ServiceKey } from '../service-key.js';
5
- /** Published contracts are exposed inside app.services. */
6
- export type PublicServiceKeys = Readonly<Record<string, ServiceKey<any>>>;
7
- /** Extended by app discovery; package installation alone does not declare availability. */
8
- export interface PublicServiceMap {
9
- }
3
+ import type { Plugin, ServiceDefinition, ServiceMap } from '../definitions.js';
4
+ import type { ContractName } from '../service-key.js';
5
+ import type { SettingsOf } from '../settings/define.js';
6
+ import type { SettingsAccess } from '../settings/access.js';
7
+ import type { ActionTree, SlotTree } from '../discovered.js';
8
+ import type { CancelableOf, EventsOf } from '../events/define.js';
9
+ import type { SlotEntry } from '../slots/define.js';
10
10
  /** Optional packages contribute their own typed facades without Core depending on them. */
11
11
  export interface AppExtensionMap {
12
12
  }
13
- type PublishedKeys<P> = P extends {
14
- publicServices: infer Keys extends PublicServiceKeys;
13
+ type Intersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
14
+ type Instance<D> = D extends ServiceDefinition<infer T> ? T : never;
15
+ type Exposed<D> = D extends {
16
+ exposeAs: infer Alias extends string;
15
17
  } ? {
16
- readonly [K in keyof Keys]: Keys[K] extends ServiceKey<infer T> ? T : never;
18
+ readonly [A in Alias]: Instance<D>;
17
19
  } : {};
18
- type PublishedDefinition<D> = D extends {
19
- exposeAs: infer Name extends string;
20
- create: (...args: any[]) => infer T;
21
- } ? {
22
- readonly [K in Name]: T;
20
+ /** A contract created as `serviceKey<T, 'name'>('name')` types `services.name`; plain names add nothing. */
21
+ type Provided<D> = D extends {
22
+ provides: infer Key;
23
+ } ? string extends ContractName<Key> ? {} : {
24
+ readonly [A in ContractName<Key>]: Instance<D>;
23
25
  } : {};
24
- type PublishedDefinitions<P> = P extends {
25
- services: readonly (infer D)[];
26
- } ? Intersection<PublishedDefinition<D>> : {};
27
- type Published<P> = P extends unknown ? PublishedKeys<P> & PublishedDefinitions<P> : never;
28
- type Intersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
29
- export type PublicServicesOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [never] ? {} : Intersection<Published<Plugins[number]>>;
30
- /** Service reads resolve the current runtime container; they never copy or own service state. */
26
+ type RecordServices<Id extends string, R> = {
27
+ readonly [K in keyof R & string as `${Id}.${K}`]: Instance<R[K]>;
28
+ } & Intersection<{
29
+ [K in keyof R & string]: Exposed<R[K]> & Provided<R[K]>;
30
+ }[keyof R & string]>;
31
+ type ArrayServices<D> = (D extends {
32
+ id: infer Id extends string;
33
+ } ? {
34
+ readonly [K in Id]: Instance<D>;
35
+ } : {}) & Exposed<D> & Provided<D>;
36
+ type PluginServices<P> = P extends {
37
+ id: infer Id extends string;
38
+ services: infer S;
39
+ } ? S extends readonly (infer D)[] ? Intersection<ArrayServices<D>> : S extends Readonly<Record<string, ServiceDefinition<any>>> ? RecordServices<Id, S> : {} : {};
40
+ /** `ServiceMap` entries of manually composed plugins, for `useBitaKitApp<typeof plugins>()`. */
41
+ export type PublicServicesOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [never] ? {} : Intersection<Plugins[number] extends infer P ? (P extends unknown ? PluginServices<P> : never) : never>;
42
+ /** `SettingsMap` entries of manually composed plugins, including installed package plugins. */
43
+ export type PublicSettingsOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [never] ? {} : Intersection<Plugins[number] extends infer P ? P extends {
44
+ id: infer Id extends string;
45
+ settings: infer S;
46
+ } ? SettingsOf<S, Id> : {} : never>;
47
+ /**
48
+ * `ActionMap` entries of manually composed or installed package plugins. Record keys become
49
+ * `<plugin>.<key>`; array entries carry no literal ID type and add nothing.
50
+ */
51
+ export type PublicActionsOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [never] ? {} : Intersection<Plugins[number] extends infer P ? P extends {
52
+ id: infer Id extends string;
53
+ actions: infer A;
54
+ } ? A extends readonly unknown[] ? {} : ActionTree<A, Id> : {} : never>;
55
+ /** `EventMap` entries of manually composed or installed package plugins. */
56
+ export type PublicEventsOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [never] ? {} : Intersection<Plugins[number] extends infer P ? P extends {
57
+ id: infer Id extends string;
58
+ events: infer E;
59
+ } ? EventsOf<E, Id> : {} : never>;
60
+ /** `CancelableEventMap` entries of manually composed or installed package plugins. */
61
+ export type PublicCancelableOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [never] ? {} : Intersection<Plugins[number] extends infer P ? P extends {
62
+ id: infer Id extends string;
63
+ events: infer E;
64
+ } ? CancelableOf<E, Id> : {} : never>;
65
+ /** Typed slot contracts from manual plugin records or explicit-ID arrays. */
66
+ export type PublicSlotsOf<Plugins extends readonly Plugin[]> = [Plugins[number]] extends [never] ? {} : Intersection<Plugins[number] extends infer P ? P extends {
67
+ id: infer Id extends string;
68
+ slots: infer S;
69
+ } ? S extends readonly (infer D)[] ? [D] extends [never] ? {} : Intersection<D extends {
70
+ id: infer Name extends string;
71
+ } ? SlotEntry<D, Name> : {}> : SlotTree<S, Id> : {} : never>;
31
72
  type AtPath<Path extends string, Value> = Path extends `${infer Head}.${infer Tail}` ? {
32
73
  readonly [K in Head]: AtPath<Tail, Value>;
33
74
  } : {
34
75
  readonly [K in Path]: Value;
35
76
  };
36
- /** The same dotted names drive generated completion and runtime namespaces. */
77
+ /** Dotted names become nested namespaces: `todos.items` is `services.todos.items`. */
37
78
  export type Namespace<Entries extends object> = keyof Entries extends never ? {} : Intersection<{
38
79
  [K in keyof Entries & string]: AtPath<K, Entries[K]>;
39
80
  }[keyof Entries & string]>;
40
81
  type Immutable<T> = T extends object ? {
41
82
  readonly [K in keyof T]: Immutable<T[K]>;
42
83
  } : T;
43
- export type FoundationActions = Namespace<{
84
+ export type BitaKitActions = Namespace<{
44
85
  [K in KnownActionId]: ActionReference<K>;
45
86
  }>;
46
- export interface FoundationApp<Public extends object = PublicServiceMap> extends AppExtensionMap {
47
- readonly events: import('../events/types.js').Events;
48
- readonly actions: FoundationActions;
87
+ export interface BitaKitApp<Services extends object = ServiceMap> extends AppExtensionMap {
88
+ /** Listen only: a plugin emits its own events through the scoped `events` of its services and Actions. */
89
+ readonly events: Pick<import('../events/types.js').Events, 'on'>;
90
+ readonly actions: BitaKitActions;
49
91
  readonly config: Namespace<Immutable<ConfigMap>>;
50
- readonly services: Namespace<Public>;
92
+ /** Live, typed access; missing reads throw. Use has/service hooks for owner readiness. */
93
+ readonly services: Namespace<Services>;
94
+ /** Typed setting handles of every plugin; values load after mount, defaults before. */
95
+ readonly settings: SettingsAccess;
96
+ /** Initial startup completed; compatible updates retain this until full shutdown. */
51
97
  readonly ready: boolean;
52
- readonly optional: {
53
- readonly services: Namespace<{
54
- [K in keyof Public]: Public[K] | undefined;
55
- }>;
56
- };
98
+ /** Whether a service and its owner are ready right now, by ID or alias. */
99
+ has(service: string): boolean;
57
100
  }
58
101
  export {};
@@ -1,24 +1,45 @@
1
- /** Immutable configuration. User preferences continue to belong to AppPreferences. */
1
+ /** Immutable configuration. User preferences belong to settings, not here. */
2
2
  export interface ConfigMap {
3
3
  }
4
4
  export type ConfigValues = Readonly<Record<string, unknown>>;
5
5
  declare const configDefinition: unique symbol;
6
+ /** zod, valibot and friends: `parse`, or the Standard Schema `~standard.validate` (sync). */
6
7
  export type ConfigSchema<T> = {
7
8
  parse(input: unknown): T;
9
+ } | {
10
+ '~standard': {
11
+ validate(input: unknown): {
12
+ value: T;
13
+ } | {
14
+ issues: readonly {
15
+ message: string;
16
+ }[];
17
+ };
18
+ };
8
19
  };
9
20
  export type ConfigDefinition<T = ConfigValues> = {
10
21
  readonly [configDefinition]: true;
11
22
  readonly defaults?: Partial<T>;
12
23
  readonly schema?: ConfigSchema<T>;
13
24
  };
25
+ type SchemaOutput<S> = S extends {
26
+ parse(input: unknown): infer T;
27
+ } ? T : S extends {
28
+ '~standard': {
29
+ validate(input: unknown): infer R;
30
+ };
31
+ } ? Extract<Awaited<R>, {
32
+ value: unknown;
33
+ }>['value'] : never;
34
+ /** `defineConfig({ defaults })`, `defineConfig({ schema })` or both. Files may also export a plain object. */
14
35
  export declare function defineConfig<T extends ConfigValues>(value: {
15
36
  defaults: T;
37
+ schema?: undefined;
16
38
  }): ConfigDefinition<T>;
17
- export declare function defineConfig<T>(value: {
18
- schema: ConfigSchema<T>;
19
- defaults?: Partial<T>;
20
- }): ConfigDefinition<T>;
21
- export declare function defineConfig<T extends ConfigValues>(value: T): T;
39
+ export declare function defineConfig<S extends ConfigSchema<any>>(value: {
40
+ schema: S;
41
+ defaults?: Partial<SchemaOutput<S>>;
42
+ }): ConfigDefinition<SchemaOutput<S>>;
22
43
  export declare function isConfigDefinition(value: unknown): value is ConfigDefinition;
23
44
  export declare function isConfigObject(value: unknown): value is Record<string, unknown>;
24
45
  export type ConfigPath = string | readonly string[];
@@ -32,6 +53,7 @@ export declare class ConfigScope<T = ConfigValues> {
32
53
  scope<U = ConfigValues>(path: ConfigPath): ConfigScope<U>;
33
54
  snapshot(): T;
34
55
  }
56
+ /** `plugin`: the module's whole tree. `action`: positioned at `actions.<action path>`. */
35
57
  export type ConfigContext = {
36
58
  plugin: ConfigScope;
37
59
  action: ConfigScope;
@@ -42,6 +64,8 @@ export declare class ConfigService {
42
64
  id: string;
43
65
  config?: ConfigValues | ConfigDefinition;
44
66
  }[], overrides?: Readonly<Record<string, ConfigValues>>);
67
+ /** Adopt prevalidated module scopes without replacing the public configuration service. */
68
+ replace(next: ConfigService): void;
45
69
  plugin<K extends keyof ConfigMap & string>(id: K): ConfigScope<ConfigMap[K]>;
46
70
  plugin<T = ConfigValues>(id: string): ConfigScope<T>;
47
71
  context(id: string, actionPath?: readonly string[]): ConfigContext;
@@ -1,8 +1,8 @@
1
- const configDefinition = Symbol('foundation.config');
1
+ const configDefinition = Symbol.for('bitakit.core.config');
2
2
  export function defineConfig(value) {
3
- return 'defaults' in value || (value.schema && typeof value.schema.parse === 'function')
4
- ? { ...value, [configDefinition]: true }
5
- : value;
3
+ if (!value || typeof value !== 'object' || (!('defaults' in value) && !('schema' in value)))
4
+ throw new Error('defineConfig expects { defaults } and/or { schema }.');
5
+ return { ...value, [configDefinition]: true };
6
6
  }
7
7
  export function isConfigDefinition(value) {
8
8
  return !!value && typeof value === 'object' && configDefinition in value;
@@ -13,6 +13,16 @@ export function isConfigObject(value) {
13
13
  !Array.isArray(value) &&
14
14
  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
15
15
  }
16
+ function parseWith(schema, input) {
17
+ if ('parse' in schema)
18
+ return schema.parse(input);
19
+ const result = schema['~standard'].validate(input);
20
+ if (result && typeof result.then === 'function')
21
+ throw new TypeError('Config schemas must validate synchronously.');
22
+ if ('issues' in result)
23
+ throw new Error(`Invalid config: ${result.issues.map((issue) => issue.message).join('; ')}`);
24
+ return result.value;
25
+ }
16
26
  function immutable(value) {
17
27
  if (Array.isArray(value))
18
28
  return Object.freeze(value.map(immutable));
@@ -23,10 +33,10 @@ function immutable(value) {
23
33
  return value;
24
34
  }
25
35
  function resolve(defaults, override) {
26
- if (isConfigDefinition(defaults))
27
- return immutable(defaults.schema
28
- ? defaults.schema.parse(resolve(defaults.defaults ?? {}, override))
29
- : resolve(defaults.defaults ?? {}, override));
36
+ if (isConfigDefinition(defaults)) {
37
+ const merged = resolve(defaults.defaults ?? {}, override);
38
+ return immutable(defaults.schema ? parseWith(defaults.schema, merged) : merged);
39
+ }
30
40
  if (isConfigObject(defaults) && (override === undefined || isConfigObject(override))) {
31
41
  const extra = (override ?? {});
32
42
  return Object.freeze(Object.fromEntries([...new Set([...Object.keys(defaults), ...Object.keys(extra)])].map((key) => [
@@ -68,7 +78,13 @@ export class ConfigService {
68
78
  }
69
79
  for (const id of Object.keys(overrides))
70
80
  if (!this.modules.has(id))
71
- throw new Error(`Unknown config module "${id}".`);
81
+ throw new Error(`configOverrides names "${id}", but no plugin with that ID is enabled. Known: ${[...this.modules.keys()].join(', ')}.`);
82
+ }
83
+ /** Adopt prevalidated module scopes without replacing the public configuration service. */
84
+ replace(next) {
85
+ this.modules.clear();
86
+ for (const [id, scope] of next.modules)
87
+ this.modules.set(id, scope);
72
88
  }
73
89
  plugin(id) {
74
90
  const scope = this.modules.get(id);
@@ -1,4 +1,7 @@
1
- import type { FoundationConfig } from './definitions.js';
2
- export type FoundationOverrides = Pick<FoundationConfig, 'actions' | 'plugins' | 'interceptors' | 'providers'>;
1
+ import type { BitaKitRuntimeConfig, ProviderDefinition } from './definitions.js';
2
+ export type BitaKitOverrides = Pick<BitaKitRuntimeConfig, 'actions' | 'plugins' | 'interceptors'> & {
3
+ /** Replaces the app's React providers (`ui.providers`); plugin providers are added unless this is set. */
4
+ providers?: readonly ProviderDefinition[];
5
+ };
3
6
  /** Undefined inherits. An explicit list replaces that domain, including an empty list. */
4
- export declare function resolveFoundationConfig(discovered: FoundationConfig, overrides?: FoundationOverrides): FoundationConfig;
7
+ export declare function resolveBitaKitConfig(discovered: BitaKitRuntimeConfig, overrides?: BitaKitOverrides): BitaKitRuntimeConfig;
@@ -1,5 +1,6 @@
1
+ const providersOf = (plugin) => plugin.ui?.providers ?? [];
1
2
  /** Undefined inherits. An explicit list replaces that domain, including an empty list. */
2
- export function resolveFoundationConfig(discovered, overrides = {}) {
3
+ export function resolveBitaKitConfig(discovered, overrides = {}) {
3
4
  const selectedPlugins = overrides.plugins ?? discovered.plugins ?? [];
4
5
  const config = {
5
6
  ...discovered,
@@ -12,7 +13,6 @@ export function resolveFoundationConfig(discovered, overrides = {}) {
12
13
  })),
13
14
  actions: overrides.actions ?? discovered.actions ?? [],
14
15
  interceptors: overrides.interceptors ?? discovered.interceptors ?? [],
15
- providers: overrides.providers ?? discovered.providers ?? [],
16
16
  };
17
17
  const removed = new Set((discovered.plugins ?? [])
18
18
  .filter((plugin) => !selectedPlugins.some((selected) => selected.id === plugin.id))
@@ -25,11 +25,12 @@ export function resolveFoundationConfig(discovered, overrides = {}) {
25
25
  throw new Error(`Invalid or duplicate plugin "${plugin.id}".`);
26
26
  pluginIds.add(plugin.id);
27
27
  }
28
- const pluginProviders = (config.plugins ?? []).flatMap((plugin) => plugin.providers ?? []);
29
- if (overrides.providers === undefined && pluginProviders.length)
30
- config.providers = [...pluginProviders, ...config.providers];
28
+ const pluginProviders = (config.plugins ?? []).flatMap((plugin) => providersOf(plugin));
29
+ const providers = overrides.providers === undefined
30
+ ? [...pluginProviders, ...providersOf(discovered)]
31
+ : overrides.providers;
31
32
  const seen = new Set();
32
- for (const provider of config.providers) {
33
+ for (const provider of providers) {
33
34
  if (!provider.id || seen.has(provider.id))
34
35
  throw new Error(`Invalid or duplicate provider "${provider.id}".`);
35
36
  for (const id of provider.requires ?? []) {
@@ -38,5 +39,6 @@ export function resolveFoundationConfig(discovered, overrides = {}) {
38
39
  }
39
40
  seen.add(provider.id);
40
41
  }
42
+ config.ui = { ...discovered.ui, providers };
41
43
  return config;
42
44
  }
@@ -6,6 +6,8 @@ export type AuthSnapshot = {
6
6
  name?: string;
7
7
  email?: string;
8
8
  } | null;
9
+ /** The active organization, when the provider tracks one; scopes organization settings. */
10
+ organizationId?: string | null;
9
11
  pending: boolean;
10
12
  error: unknown;
11
13
  };
@@ -28,5 +30,5 @@ export interface TranslationService {
28
30
  getCatalog?(namespace?: string): TranslationCatalog | undefined;
29
31
  subscribe(listener: () => void): () => void;
30
32
  }
31
- export declare const authService: import("./service-key.js").ServiceKey<AuthService>;
32
- export declare const translationService: import("./service-key.js").ServiceKey<TranslationService>;
33
+ export declare const authService: import("./service-key.js").ServiceKey<AuthService, "auth">;
34
+ export declare const translationService: import("./service-key.js").ServiceKey<TranslationService, "i18n">;
package/dist/contracts.js CHANGED
@@ -1,3 +1,3 @@
1
- import { serviceKey } from './service-key.js';
2
- export const authService = serviceKey('auth');
3
- export const translationService = serviceKey('i18n');
1
+ import { defineContract } from './service-key.js';
2
+ export const authService = defineContract('auth').of();
3
+ export const translationService = defineContract('i18n').of();
@@ -1,3 +1,6 @@
1
1
  export declare function contributionPath(entry: object): readonly string[] | undefined;
2
+ /** Project-relative file that declared a contribution, recorded by discovery for diagnostics. */
3
+ export declare function contributionSource(entry: object): string | undefined;
2
4
  export declare function preserveContributionPath(from: object, to: object): object;
3
- export declare function setContributionPath(entry: object, path: readonly string[]): void;
5
+ export declare function setContributionPath(entry: object, path: readonly string[], source?: string): void;
6
+ export declare function setContributionSource(entry: object, source: string): void;
@@ -1,13 +1,26 @@
1
1
  const origins = new WeakMap();
2
+ const sources = new WeakMap();
2
3
  export function contributionPath(entry) {
3
4
  return origins.get(entry);
4
5
  }
6
+ /** Project-relative file that declared a contribution, recorded by discovery for diagnostics. */
7
+ export function contributionSource(entry) {
8
+ return sources.get(entry);
9
+ }
5
10
  export function preserveContributionPath(from, to) {
6
11
  const path = origins.get(from);
7
12
  if (path)
8
13
  origins.set(to, path);
14
+ const source = sources.get(from);
15
+ if (source)
16
+ sources.set(to, source);
9
17
  return to;
10
18
  }
11
- export function setContributionPath(entry, path) {
19
+ export function setContributionPath(entry, path, source) {
12
20
  origins.set(entry, path);
21
+ if (source)
22
+ sources.set(entry, source);
23
+ }
24
+ export function setContributionSource(entry, source) {
25
+ sources.set(entry, source);
13
26
  }
@@ -0,0 +1,26 @@
1
+ import type { ActionContext, ActionDefinition, ActionPresentation, RegistrationOptions } from '@bitakit/core/actions';
2
+ import { CANCEL } from '@bitakit/core/actions';
3
+ import type { ConfigContext } from '../config-service.js';
4
+ import type { ResolvedContribution } from '../definitions.js';
5
+ import type { Events } from '../events/types.js';
6
+ import type { ContributionHost, Override } from './host.js';
7
+ export type Registration = {
8
+ id: string;
9
+ placement: RegistrationOptions;
10
+ definition: ActionDefinition;
11
+ };
12
+ export type Adapted = {
13
+ definition: ResolvedContribution;
14
+ requires: readonly string[];
15
+ registrations: readonly Registration[];
16
+ /** Installed by the runtime around this action's executions. */
17
+ confirm?: (context: ActionContext) => Promise<typeof CANCEL | undefined>;
18
+ };
19
+ /** Configuration caps: false wins over any reactive result; true never bypasses guards. */
20
+ export declare function cap(presentation: ActionPresentation, override: Override): ActionPresentation;
21
+ /**
22
+ * The one adapter: static fields register as-is, function-valued fields are evaluated per
23
+ * input in `resolve`, `href` executes as navigation, `dialog` opens the host dialog and
24
+ * `execute` runs with validation, feedback and the shared execution guards.
25
+ */
26
+ export declare function adaptAction(resolved: ResolvedContribution, host: ContributionHost, config: ConfigContext, events: Events, available?: () => boolean): Adapted;
@@ -0,0 +1,171 @@
1
+ import { CANCEL, navigate } from '@bitakit/core/actions';
2
+ import { ActionFailure } from '../actions/feedback.js';
3
+ import { isThenable, validate, validateSync } from '../schema.js';
4
+ const dynamicKeys = [
5
+ 'title',
6
+ 'description',
7
+ 'tooltip',
8
+ 'variant',
9
+ 'href',
10
+ 'enabled',
11
+ 'visible',
12
+ 'checked',
13
+ 'value',
14
+ ];
15
+ /** Configuration caps: false wins over any reactive result; true never bypasses guards. */
16
+ export function cap(presentation, override) {
17
+ if (!override)
18
+ return presentation;
19
+ return {
20
+ ...presentation,
21
+ enabled: override.enabled === false ? false : presentation.enabled,
22
+ visible: override.visible === false ? false : presentation.visible,
23
+ };
24
+ }
25
+ // Validation helpers are shared with settings.
26
+ /**
27
+ * The one adapter: static fields register as-is, function-valued fields are evaluated per
28
+ * input in `resolve`, `href` executes as navigation, `dialog` opens the host dialog and
29
+ * `execute` runs with validation, feedback and the shared execution guards.
30
+ */
31
+ export function adaptAction(resolved, host, config, events, available = () => true) {
32
+ const override = host.override(resolved.id);
33
+ // Only `false` caps apply to the definition; `true` never bypasses the action's own guards.
34
+ const definition = override
35
+ ? {
36
+ ...resolved,
37
+ ...(override.enabled === false ? { enabled: false } : {}),
38
+ ...(override.visible === false ? { visible: false } : {}),
39
+ }
40
+ : resolved;
41
+ const context = (input) => ({
42
+ input,
43
+ services: host.services,
44
+ config,
45
+ settings: host.app.settings,
46
+ app: host.app,
47
+ });
48
+ const evaluate = (value, input) => typeof value === 'function'
49
+ ? value(context(input))
50
+ : value;
51
+ const resolve = (input) => {
52
+ // A registered definition must not render or read its services before its owner is ready.
53
+ if (!available())
54
+ return { enabled: false, visible: false };
55
+ const presentation = {};
56
+ for (const key of dynamicKeys) {
57
+ const value = definition[key];
58
+ if (typeof value === 'function')
59
+ presentation[key] = evaluate(value, input);
60
+ }
61
+ // A schema disables the action while the current input is invalid, unless `enabled` decides.
62
+ if (definition.input && definition.enabled === undefined) {
63
+ const checked = validateSync(definition.input, input);
64
+ if (checked)
65
+ presentation.enabled = checked.ok;
66
+ }
67
+ return cap(presentation, override);
68
+ };
69
+ const isStatic = (value) => typeof value !== 'function';
70
+ const execute = definition.dialog
71
+ ? ({ input }) => {
72
+ if (!host.dialog())
73
+ host.openDialog(definition, input);
74
+ }
75
+ : definition.execute
76
+ ? (context) => {
77
+ const run = definition.execute;
78
+ const failure = (error, input) => new ActionFailure(context.get()
79
+ ? host.feedback(definition, 'failure', definition.failure, {
80
+ error,
81
+ input,
82
+ services: host.services,
83
+ }).message
84
+ : false, error);
85
+ const succeed = (result, input) => {
86
+ if (context.get())
87
+ host.notify(host.feedback(definition, 'success', definition.success, {
88
+ result,
89
+ input,
90
+ services: host.services,
91
+ }).message, 'success');
92
+ return result;
93
+ };
94
+ // Synchronous handlers stay synchronous, so the list shows pending only for real promises.
95
+ const start = (input) => {
96
+ const full = {
97
+ ...context,
98
+ input,
99
+ services: host.services,
100
+ config,
101
+ settings: host.app.settings,
102
+ app: host.app,
103
+ events,
104
+ };
105
+ let result;
106
+ try {
107
+ result = run(full);
108
+ }
109
+ catch (error) {
110
+ throw failure(error, input);
111
+ }
112
+ return isThenable(result)
113
+ ? Promise.resolve(result).then((value) => succeed(value, input), (error) => {
114
+ throw failure(error, input);
115
+ })
116
+ : succeed(result, input);
117
+ };
118
+ if (!definition.input)
119
+ return start(context.input);
120
+ const checked = validateSync(definition.input, context.input);
121
+ if (checked) {
122
+ if (!checked.ok)
123
+ throw failure(checked.error, context.input);
124
+ return start(checked.value);
125
+ }
126
+ return validate(definition.input, context.input).then(start, (error) => {
127
+ throw failure(error, context.input);
128
+ });
129
+ }
130
+ : definition.href !== undefined
131
+ ? (context) => navigate(context, isStatic(definition.href) ? undefined : evaluate(definition.href, context.input))
132
+ : undefined;
133
+ const registration = {
134
+ id: definition.id,
135
+ title: host.title(definition),
136
+ description: host.description(definition),
137
+ tooltip: host.tooltip(definition),
138
+ icon: definition.icon,
139
+ variant: isStatic(definition.variant) ? definition.variant : undefined,
140
+ href: isStatic(definition.href) ? definition.href : undefined,
141
+ enabled: isStatic(definition.enabled) ? definition.enabled : undefined,
142
+ visible: isStatic(definition.visible) ? definition.visible : undefined,
143
+ checked: isStatic(definition.checked) ? definition.checked : undefined,
144
+ value: isStatic(definition.value) ? definition.value : undefined,
145
+ groups: (definition.groups ?? []).map(host.getGroup),
146
+ order: definition.order,
147
+ dividerBefore: definition.dividerBefore,
148
+ shortcut: definition.shortcut,
149
+ internal: definition.internal,
150
+ metadata: definition.metadata,
151
+ concurrency: definition.concurrency,
152
+ concurrencyKey: definition.concurrencyKey,
153
+ resolve,
154
+ execute,
155
+ };
156
+ const confirm = definition.confirm
157
+ ? async (context) => {
158
+ const request = evaluate(definition.confirm, context.input);
159
+ if (!request)
160
+ return undefined;
161
+ const accepted = await host.confirm(typeof request === 'string' ? { title: request, description: '' } : request);
162
+ return accepted ? undefined : CANCEL;
163
+ }
164
+ : undefined;
165
+ return {
166
+ definition,
167
+ requires: definition.requires ?? [],
168
+ registrations: [{ id: definition.id, placement: {}, definition: registration }],
169
+ confirm,
170
+ };
171
+ }
@@ -1,7 +1,8 @@
1
1
  import type { ActionGroup, ActionList } from '@bitakit/core/actions';
2
2
  import type { Feedback, MessageValues } from '../actions/feedback.js';
3
3
  import type { ResolvedContribution, Services, Translator } from '../definitions.js';
4
- import type { FoundationApp } from '../app/types.js';
4
+ import type { BitaKitApp } from '../app/types.js';
5
+ import type { Confirmation } from '../confirmation.js';
5
6
  export type FeedbackOutcome = {
6
7
  message: string | false;
7
8
  closeDialog: boolean;
@@ -10,31 +11,33 @@ export type Override = Readonly<{
10
11
  enabled?: boolean;
11
12
  visible?: boolean;
12
13
  }> | undefined;
13
- /** Contributions that open the shared dialog host. */
14
- export type OpenableDefinition = Exclude<ResolvedContribution, {
15
- kind: 'action' | 'native';
16
- }>;
14
+ /** An action with a `dialog` component; executing it opens the shared dialog host. */
15
+ export type OpenableDefinition = ResolvedContribution & {
16
+ dialog: NonNullable<ResolvedContribution['dialog']>;
17
+ };
17
18
  export type DialogState = {
18
19
  definition: OpenableDefinition;
19
20
  input: unknown;
20
21
  token: symbol;
21
22
  };
22
- /** Runtime capabilities available to contribution adapters. Registration ownership stays with the runtime. */
23
+ /** Runtime capabilities available to the action adapter. Registration ownership stays with the runtime. */
23
24
  export interface ContributionHost {
24
- readonly app: FoundationApp;
25
+ readonly app: BitaKitApp;
25
26
  readonly actions: ActionList;
26
27
  readonly services: Services;
27
- /** A translator bound to the current locale, with `has` always answering. */
28
28
  translator(): Translator;
29
29
  title(definition: ResolvedContribution): string;
30
30
  description(definition: ResolvedContribution): string | undefined;
31
+ tooltip(definition: ResolvedContribution): string | undefined;
31
32
  text(key: string | undefined, fallback: string, values?: MessageValues): string;
32
- feedback<C>(definition: ResolvedContribution, kind: 'success' | 'failure', option: Feedback<C>, context: C): FeedbackOutcome;
33
+ feedback<C>(definition: ResolvedContribution, kind: 'success' | 'failure', option: Feedback<C> | undefined, context: C & {
34
+ error?: unknown;
35
+ }): FeedbackOutcome;
33
36
  /** Presentation only; a failing notifier never changes the business outcome. */
34
- notify(message: string | false): void;
37
+ notify(message: string | false, kind?: 'success' | 'failure'): void;
35
38
  getGroup(entry: string | ActionGroup): ActionGroup;
36
39
  override(id: string): Override;
37
40
  dialog(): DialogState | null;
38
41
  openDialog(definition: OpenableDefinition, input: unknown): void;
39
- rememberFormFeedback(state: DialogState, outcome: FeedbackOutcome): void;
42
+ confirm(request: Confirmation): Promise<boolean>;
40
43
  }