@bitakit/core 0.1.2 → 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 (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,87 +0,0 @@
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
- }
@@ -1,19 +0,0 @@
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;
@@ -1,48 +0,0 @@
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
- }
@@ -1,29 +0,0 @@
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 {};
@@ -1,33 +0,0 @@
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
- }
@@ -1,19 +0,0 @@
1
- import type { ActionRegistration, ActionPresentation } from '../actions/types.js';
2
- import type { FoundationApp } from '../app/types.js';
3
- import type { ConfigContext } from '../config-service.js';
4
- import type { Services } from '../definitions.js';
5
- import type { Events } from './types.js';
6
- /** Presentation writes use the existing ActionList store and registration identity guards. */
7
- export type SetupAction = ActionPresentation & {
8
- get: ActionRegistration['get'];
9
- update: ActionRegistration['update'];
10
- };
11
- export type ActionSetupContext = {
12
- events: Events;
13
- services: Services;
14
- action: SetupAction;
15
- app: FoundationApp;
16
- config: ConfigContext;
17
- };
18
- export type ActionSetup = (context: ActionSetupContext) => void | (() => void);
19
- export declare function setupAction(handle: ActionRegistration): SetupAction;
@@ -1,24 +0,0 @@
1
- export function setupAction(handle) {
2
- const action = { get: handle.get, update: handle.update };
3
- const keys = [
4
- 'enabled',
5
- 'visible',
6
- 'checked',
7
- 'title',
8
- 'description',
9
- 'tooltip',
10
- 'icon',
11
- 'href',
12
- 'value',
13
- 'variant',
14
- ];
15
- for (const key of keys)
16
- Object.defineProperty(action, key, {
17
- enumerable: true,
18
- get: () => handle.get()?.[key],
19
- set: (value) => {
20
- handle.update({ [key]: value });
21
- },
22
- });
23
- return Object.freeze(action);
24
- }
@@ -1,37 +0,0 @@
1
- import type { PublicServiceMap } from '../app/types.js';
2
- import type { ServiceMap } from '../definitions.js';
3
- type Contracts = PublicServiceMap & ServiceMap;
4
- type Methods<S> = {
5
- [K in keyof S & string]: S[K] extends (...args: any[]) => any ? K : never;
6
- }[keyof S & string];
7
- type Service<Name extends string> = Name extends keyof Contracts ? NonNullable<Contracts[Name]> : Record<string, (...args: any[]) => unknown>;
8
- type Method<Name extends string, Key extends string> = Key extends keyof Service<Name> ? Extract<Service<Name>[Key], (...args: any[]) => any> : (...args: any[]) => unknown;
9
- type Call<Name extends string, Key extends string> = {
10
- readonly service: Name;
11
- readonly method: Key;
12
- readonly args: Readonly<Parameters<Method<Name, Key>>>;
13
- };
14
- export type ServiceInterceptor = {
15
- readonly kind: 'service';
16
- readonly service: string;
17
- readonly method?: string;
18
- readonly order?: number;
19
- before?: (call: any) => void;
20
- after?: (call: any) => void;
21
- onError?: (call: any) => void;
22
- };
23
- /** Observes one method or all public methods; callbacks never replace arguments or results. */
24
- export declare function defineServiceInterceptor<const Name extends string, const Key extends Methods<Service<Name>> = Methods<Service<Name>>>(definition: {
25
- service: Name;
26
- method?: Key;
27
- order?: number;
28
- before?: (call: Call<Name, Key>) => void;
29
- after?: (call: Call<Name, Key> & {
30
- readonly result: Awaited<ReturnType<Method<Name, Key>>>;
31
- }) => void;
32
- onError?: (call: Call<Name, Key> & {
33
- readonly error: unknown;
34
- }) => void;
35
- }): ServiceInterceptor;
36
- export declare function isServiceInterceptor(value: object): value is ServiceInterceptor;
37
- export {};
@@ -1,7 +0,0 @@
1
- /** Observes one method or all public methods; callbacks never replace arguments or results. */
2
- export function defineServiceInterceptor(definition) {
3
- return { ...definition, kind: 'service' };
4
- }
5
- export function isServiceInterceptor(value) {
6
- return 'kind' in value && value.kind === 'service';
7
- }
@@ -1,22 +0,0 @@
1
- import type { Contribution, Plugin } from './definitions.js';
2
- /** Replace only a named plugin contribution, retaining its public ID and placements. */
3
- export declare function applyActionReplacements(plugins: readonly Plugin[], appActions: readonly Contribution[]): {
4
- plugins: {
5
- actions: (import("./definitions.js").FormDefinition<any, any> | import("./definitions.js").DialogDefinition<any> | import("./definitions.js").NativeDefinition | import("./definitions.js").PlainDefinition<any, any, string> | (new (context: import("./definitions.js").ActionEnvironment) => import("./core.js").Action<any, any>) | ((context: import("./definitions.js").ActionEnvironment) => import("./core.js").Action<any, any>))[];
6
- publicServices?: import("./core.js").PublicServiceKeys;
7
- appExtensions?: Readonly<Record<string, (runtime: import("./runtime.js").FoundationRuntime) => unknown>>;
8
- config?: import("./config-service.js").ConfigValues | import("./config-service.js").ConfigDefinition;
9
- interceptors?: readonly import("./definitions.js").InterceptorEntry[];
10
- providers?: readonly import("./definitions.js").ProviderDefinition[];
11
- metadata?: import("./definitions.js").PluginMetadata;
12
- pages?: readonly import("./definitions.js").PluginPageDefinition[];
13
- views?: readonly import("./definitions.js").PluginView[];
14
- id: string;
15
- dependencies?: readonly string[];
16
- services?: readonly import("./definitions.js").ServiceDefinition<any>[];
17
- setup?: import("./definitions.js").Setup;
18
- contributions?: import("./definitions.js").ContributionSet;
19
- installs?: import("./definitions.js").ContributionInstallers;
20
- }[];
21
- actions: Contribution[];
22
- };
@@ -1,54 +0,0 @@
1
- import { preserveContributionPath } from './contribution-origin.js';
2
- import { resolveContribution } from './conventions.js';
3
- /** Replace only a named plugin contribution, retaining its public ID and placements. */
4
- export function applyActionReplacements(plugins, appActions) {
5
- const replacements = new Map();
6
- const ownActions = [];
7
- for (const action of appActions) {
8
- const definition = resolveContribution(action);
9
- if (!definition.replaces) {
10
- ownActions.push(action);
11
- continue;
12
- }
13
- if (replacements.has(definition.replaces))
14
- throw new Error(`Multiple app replacements for action "${definition.replaces}".`);
15
- replacements.set(definition.replaces, definition);
16
- }
17
- const targets = new Map();
18
- for (const plugin of plugins)
19
- for (const action of plugin.actions ?? []) {
20
- const definition = resolveContribution(action);
21
- if (definition.replaces)
22
- throw new Error('Only app actions may replace plugin actions.');
23
- // Bare native exports can establish their ID at construction; registration validates those.
24
- if (!definition.id)
25
- continue;
26
- if (targets.has(definition.id))
27
- throw new Error(`Duplicate plugin action "${definition.id}".`);
28
- targets.set(definition.id, definition);
29
- }
30
- for (const id of replacements.keys()) {
31
- if (!targets.has(id))
32
- throw new Error(`Cannot replace missing plugin action "${id}". The target needs a discovery or explicit definition ID.`);
33
- }
34
- const resolvedPlugins = plugins.map((plugin) => ({
35
- ...plugin,
36
- actions: (plugin.actions ?? []).map((action) => {
37
- const original = resolveContribution(action);
38
- const replacement = replacements.get(original.id);
39
- if (!replacement)
40
- return action;
41
- return preserveContributionPath(original, {
42
- ...replacement,
43
- id: original.id,
44
- groups: replacement.groups ?? original.groups,
45
- order: replacement.order ?? original.order,
46
- title: replacement.title ?? original.title,
47
- description: replacement.description ?? original.description,
48
- icon: replacement.icon ?? original.icon,
49
- replaces: undefined,
50
- });
51
- }),
52
- }));
53
- return { plugins: resolvedPlugins, actions: ownActions };
54
- }
@@ -1,2 +0,0 @@
1
- import type { Fields } from './definitions.js';
2
- export declare function validateFields(fields: Fields, input: unknown): Record<string, string>;
@@ -1,16 +0,0 @@
1
- export function validateFields(fields, input) {
2
- if (!input || typeof input !== 'object')
3
- throw new Error('Invalid form input.');
4
- const values = Object.create(null);
5
- for (const [name, field] of Object.entries(fields)) {
6
- const value = input[name];
7
- if (typeof value !== 'string' || (field.required && !value.trim()))
8
- throw new Error(`Invalid field: ${name}`);
9
- if (value && field.type === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
10
- throw new Error(`Invalid email: ${name}`);
11
- if (field.type === 'select' && !field.options?.some((option) => option.value === value))
12
- throw new Error(`Invalid option: ${name}`);
13
- values[name] = value;
14
- }
15
- return values;
16
- }
package/docs/auth.md DELETED
@@ -1,106 +0,0 @@
1
- # Client authentication
2
-
3
- These APIs are available in the workspace; they require a release before use from npm.
4
- Core owns the `AuthService` contract. Optional provider plugins supply the session;
5
- `@bitakit/ui` observes it and uses the existing framework navigation binding.
6
- There is no second session store. Server authentication and authorization remain
7
- with the provider and application server.
8
-
9
- ## Better Auth and external paths
10
-
11
- ```ts
12
- import { betterAuthPlugin } from '@bitakit/better-auth';
13
-
14
- const authPlugin = betterAuthPlugin(client, {
15
- paths: {
16
- signIn: '/account/login',
17
- afterSignIn: '/customers',
18
- afterSignOut: '/',
19
- },
20
- });
21
- // Add authPlugin to the existing FoundationProvider plugin list.
22
- ```
23
-
24
- Paths are application-owned, safe root-relative URLs. No routes are created.
25
- `useAuth().signIn({ returnTo })` navigates to the configured login page with a
26
- `returnTo` query parameter, unless the adapter supplies a native `signIn` handler.
27
- External or login-loop return destinations fall back to `afterSignIn`.
28
-
29
- The login page must pass `resolveAuthReturnTo(paths, returnToFromURL)` to the native
30
- provider login API as its completion destination. `afterSignIn` is a fallback,
31
- not an automatic session-change redirect. Providers requiring absolute callbacks
32
- should resolve the validated path against the configured **application** origin,
33
- not the authentication-server origin. Keep secrets and server configuration on the server.
34
-
35
- ```tsx
36
- import { AuthBoundary, useAuth } from '@bitakit/ui';
37
- import { LoadingPage, ErrorPage } from '@bitakit/shell/pages';
38
-
39
- function ProtectedContent({ children }) {
40
- return (
41
- <AuthBoundary
42
- pending={<LoadingPage />}
43
- renderError={() => <ErrorPage />}
44
- >
45
- {children}
46
- </AuthBoundary>
47
- );
48
- }
49
-
50
- function AccountControls() {
51
- const { user, pending, signOut } = useAuth();
52
- // Bind signOut to the application's existing Action or button handler.
53
- // Handle a rejected promise using the application's existing error presentation.
54
- }
55
- ```
56
-
57
- `AuthBoundary` waits for pending session resolution and does not redirect on session
58
- errors. `redirect={false}` allows host-owned unauthenticated presentation. It is a
59
- client rendering convenience, never a security boundary. Keep native server checks.
60
- `useAuth().signOut()` awaits the adapter and then navigates to `afterSignOut`;
61
- the boundary does not race that operation with a login redirect. A subsequent
62
- protected route can start login normally. Calling a native SDK or service directly
63
- does not invoke this UI navigation policy. Configure only one owner for logout navigation.
64
-
65
- ## Writing another adapter
66
-
67
- Implement the existing `AuthService`, register it with `provideService(authService, ...)`,
68
- and use an ordinary plugin. No Core change, provider registry or host bootstrap is needed.
69
- The following is an adapter template: `source` is a normalized SDK bridge that the
70
- adapter author implements using their provider's public APIs, not an Auth.js or Clerk API.
71
-
72
- ```ts
73
- import {
74
- authService, configureAuthPaths, definePlugin, provideService,
75
- type AuthPaths, type AuthService,
76
- } from '@bitakit/core';
77
-
78
- export function customAuthPlugin(source: AuthService, paths: AuthPaths) {
79
- return definePlugin({
80
- id: 'custom-auth',
81
- services: [provideService(authService, {
82
- create: () => ({
83
- paths: configureAuthPaths(paths),
84
- getSnapshot: () => source.getSnapshot(),
85
- subscribe: listener => source.subscribe(listener),
86
- signOut: () => source.signOut(),
87
- ...(source.signIn
88
- ? { signIn: options => source.signIn!(options) }
89
- : {}),
90
- }),
91
- })],
92
- });
93
- }
94
- ```
95
-
96
- The bridge must return a stable `{ user, pending, error }` snapshot until it changes;
97
- `user` contains at least `id`, and `null` means signed out only once `pending` is false
98
- and `error` is absent. Subscribe to native SDK updates and return an unsubscribe
99
- function. Preserve SDK failures, await sign-out, and release any adapter-owned
100
- resources through the ordinary service/plugin lifecycle. Keep React-only SDK providers
101
- inside the optional integration package using existing plugin providers.
102
-
103
- Auth.js and Clerk adapters are not implemented here. Their native session/login APIs
104
- must be mapped inside their optional packages; organizations, registration and password
105
- recovery are not standardized by this small contract. Better Auth remains the working
106
- reference in `packages/better-auth/src/index.ts`.