@bitakit/core 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +174 -325
- package/assets/bitakit-banner.png +0 -0
- package/assets/bitakit-logo-dark.svg +11 -0
- package/assets/bitakit-logo.svg +11 -0
- package/discovery/generate.mjs +2 -8
- package/dist/actions/action-list.d.ts +1 -1
- package/dist/actions/action-list.js +53 -4
- package/dist/actions/action.d.ts +3 -3
- package/dist/actions/types.d.ts +4 -0
- package/dist/app/access.js +2 -1
- package/dist/app/service-aliases.d.ts +4 -0
- package/dist/app/service-aliases.js +14 -0
- package/dist/app/types.d.ts +12 -1
- package/dist/auth-navigation.d.ts +13 -0
- package/dist/auth-navigation.js +33 -0
- package/dist/contracts.d.ts +5 -0
- package/dist/contributions/command.js +9 -0
- package/dist/contributions/index.d.ts +1 -0
- package/dist/core.d.ts +4 -0
- package/dist/core.js +2 -0
- package/dist/definitions.d.ts +30 -4
- package/dist/discovered.d.ts +9 -5
- package/dist/discovered.js +3 -2
- package/dist/events/action-setup.d.ts +19 -0
- package/dist/events/action-setup.js +24 -0
- package/dist/events/service.d.ts +18 -0
- package/dist/events/service.js +98 -0
- package/dist/events/types.d.ts +19 -0
- package/dist/events/types.js +1 -0
- package/dist/replacements.d.ts +1 -1
- package/dist/runtime.d.ts +2 -0
- package/dist/runtime.js +18 -2
- package/dist/service-key.d.ts +6 -0
- package/dist/service-key.js +0 -1
- package/dist/services.d.ts +2 -1
- package/dist/services.js +5 -1
- package/docs/auth.md +106 -0
- package/docs/events.md +157 -0
- package/docs/file-contributions.md +13 -0
- package/docs/reference.md +404 -0
- package/docs/todo-tutorial.md +88 -0
- package/examples/todos/actions/create.mjs +7 -0
- package/examples/todos/actions/delete.mjs +14 -0
- package/examples/todos/actions/list.mjs +7 -0
- package/examples/todos/plugin.mjs +11 -0
- package/examples/todos/services/tasks.mjs +30 -0
- package/examples/todos.mjs +17 -0
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,382 +1,231 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/assets/bitakit-banner.png" alt="BitaKit — Your app. Your building blocks. An AI-friendly composition layer for modern applications." width="1024">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
# BitaKit Core
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
**Build bigger apps from smaller, pluggable features — together with your team and AI.**
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
Each immediate plugin folder supplies its default plugin ID. `plugin.config.ts` is
|
|
14
|
-
optional. `defineService({ create: () => ({ ... }) })` infers its public name from the
|
|
15
|
-
relative service path; `defineAction({ execute: ({ app }) => ... })` infers its ID
|
|
16
|
-
from the plugin ID and action path. Explicit `id` values override these defaults.
|
|
17
|
-
Discovery generates registration and types, including service method inputs and outputs.
|
|
18
|
-
|
|
19
|
-
Use `app.services.documents` and `app.actions.documents.create.execute()`. Action references
|
|
20
|
-
delegate to the existing ActionList, preserving execution guards and lifecycle behavior.
|
|
21
|
-
Internal actions stay out of enumeration. React ActionButton, ActionBinding and useAction
|
|
22
|
-
accept these references; a reference must belong to the same provider's ActionList.
|
|
23
|
-
|
|
24
|
-
`app.config.<plugin>.<path>` reads the immutable resolved configuration snapshot, including
|
|
25
|
-
host overrides. `defineConfig({ defaults: { pageSize: 20 } })` works without a schema;
|
|
26
|
-
optional schemas retain their parse contract. Low-level scoped reads remain available through
|
|
27
|
-
`runtime.configuration` and the existing action/service config context.
|
|
28
|
-
Optional packages can project instance-local facades through `appExtensions` and augment
|
|
29
|
-
`AppExtensionMap`. Core owns no Settings implementation or duplicate state.
|
|
30
|
-
|
|
31
|
-
Plugins publish selected existing service keys through `publicServices`. Public names must be unique within the service namespace.
|
|
32
|
-
|
|
33
|
-
```ts
|
|
34
|
-
const documents = serviceKey<Documents>('editor.documents');
|
|
35
|
-
export default function documentsPlugin() {
|
|
36
|
-
return definePlugin({
|
|
37
|
-
id: 'documents',
|
|
38
|
-
publicServices: { documents },
|
|
39
|
-
services: [provideService(documents, { create: () => createDocumentsService() })],
|
|
40
|
-
});
|
|
41
|
-
}
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
`runtime.app.services.documents` resolves that same container instance. Required access reports
|
|
45
|
-
FoundationServiceError (`code`, `service`, `reason`, optional `plugin`) when unavailable.
|
|
46
|
-
`app.optional.services.documents` returns undefined before mount or when unavailable. After mount,
|
|
47
|
-
`app.ready` is true; disposal makes optional reads unavailable again. Obtaining a service
|
|
48
|
-
does not subscribe to its data. Existing dependency checks and reverse cleanup still apply.
|
|
49
|
-
Do not cache service instances across runtime replacement.
|
|
50
|
-
|
|
51
|
-
The React hook `useFoundationApp` lives in UI and follows readiness; Core remains usable
|
|
52
|
-
without React. Its default public contract is generated from local contributions and installed opt-in plugins.
|
|
53
|
-
Manual typed compositions use `FoundationApp<PublicServicesOf<typeof plugins>>` or the
|
|
54
|
-
corresponding hook generic. Keep precise factory return types instead of widening them to
|
|
55
|
-
`Plugin` if callers need public-service completion.
|
|
56
|
-
|
|
57
|
-
A package can opt into discovery with public package exports and metadata:
|
|
58
|
-
|
|
59
|
-
```json
|
|
60
|
-
{
|
|
61
|
-
"exports": {
|
|
62
|
-
"./package.json": "./package.json",
|
|
63
|
-
"./foundation": "./dist/foundation.js"
|
|
64
|
-
},
|
|
65
|
-
"foundation": { "plugin": "./foundation" }
|
|
66
|
-
}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
The plugin entry default-exports a synchronous factory returning one Plugin. By default it
|
|
70
|
-
receives no arguments. Optional metadata `"configuration": "shell"` passes that path from the
|
|
71
|
-
resolved root app config (including defaults and app overrides), or `{}` when absent. It describes services/providers; it must not acquire external resources at factory
|
|
72
|
-
time. Core owns their creation and cleanup. Direct dependencies and optionalDependencies
|
|
73
|
-
are considered; transitive and development dependencies are not automatically activated.
|
|
74
|
-
Only packages exposing their package.json and explicit Foundation metadata participate.
|
|
75
|
-
`foundation.config.ts` can disable all package contributions with `packages: false`, or
|
|
76
|
-
individual packages with `packages: { 'package-name': false }`.
|
|
77
|
-
|
|
78
|
-
An optional `foundation.discovery` export default-exports a Node-safe function returning
|
|
79
|
-
contribution kind descriptors. Explicit `kinds` overrides replace package defaults by name.
|
|
80
|
-
Client plugin factories are never executed by build discovery; these discovery adapters
|
|
81
|
-
are trusted build code. Removing/disabling a package removes its generated import and types.
|
|
82
|
-
Local source discovery continues through the same existing pipeline.
|
|
83
|
-
|
|
84
|
-
Source responsibilities: `app/types.ts` owns public typing, `app/access.ts` projects current
|
|
85
|
-
services, and `app/service-error.ts` owns diagnostics. `discovery/packages.mjs` reads opt-in
|
|
86
|
-
metadata; `discovery/generate.mjs` emits imports and app types. None is a second runtime registry.
|
|
87
|
-
|
|
88
|
-
Framework-independent Actions, plugin lifecycle and services. React bindings live in the separate @bitakit/ui package. Import general APIs from `@bitakit/core` and UI APIs from `@bitakit/ui`. This package does not create another ActionProvider, settings store, router, authentication session, or API client.
|
|
9
|
+
BitaKit gives **developers and AI coding assistants a shared structure** for building
|
|
10
|
+
applications. Organize a feature into a plugin, put reusable behavior in services,
|
|
11
|
+
and expose operations through actions. Each piece has a clear home, a clear role,
|
|
12
|
+
and typed connections to the rest of your app.
|
|
89
13
|
|
|
90
|
-
|
|
14
|
+
**Keep Next.js, TanStack Start, or your own stack.** BitaKit adds feature organization
|
|
15
|
+
and shared lifecycle management alongside your framework. You keep control of your
|
|
16
|
+
routes, UI, business rules, and data.
|
|
91
17
|
|
|
92
|
-
##
|
|
18
|
+
## Contents
|
|
93
19
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
},
|
|
104
|
-
async submit(values, { services }) {
|
|
105
|
-
return services.users.invite(values);
|
|
106
|
-
},
|
|
107
|
-
});
|
|
108
|
-
```
|
|
20
|
+
- [Install](#install)
|
|
21
|
+
- [Why add BitaKit?](#why-add-bitakit)
|
|
22
|
+
- [How the pieces fit](#how-the-pieces-fit)
|
|
23
|
+
- [Try a To-do plugin](#try-a-to-do-plugin)
|
|
24
|
+
- [Type safety that follows your feature](#type-safety-that-follows-your-feature)
|
|
25
|
+
- [React to events](#react-to-events)
|
|
26
|
+
- [What belongs outside Core?](#what-belongs-outside-core)
|
|
27
|
+
- [Go deeper](#go-deeper)
|
|
28
|
+
- [License](#license)
|
|
109
29
|
|
|
110
|
-
|
|
30
|
+
## Install
|
|
111
31
|
|
|
112
|
-
```
|
|
113
|
-
|
|
32
|
+
```sh
|
|
33
|
+
npm install @bitakit/core
|
|
114
34
|
```
|
|
115
35
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
`add()` accepts a core ActionDefinition. Declarative forms/dialogs are supplied in the plugin's `actions` contribution array (or discovered by the Next adapter); use `attach()` for their placements. `attach()` adds a placement without changing the action's global order. Set `order` on the action definition when ordering matters.
|
|
119
|
-
|
|
120
|
-
## Optional conventions
|
|
121
|
-
|
|
122
|
-
Explicit properties win over conventions. A definition with `id: 'custom.invite'` keeps that ID even if its file moves. With no `title`, the default key is `<id>.title`; each field uses `<id>.fields.<name>`. `title`, `description` and field `label` accept a translation key when present in the current catalog, otherwise literal text. There are no separate action key properties. Button, menu, dialog heading and submit button read the same action title; the dialog reads its action description. Missing labels fall back to a readable ID/field name. Supply a translator with `has(key)` (such as next-intl's translator) to avoid querying missing keys.
|
|
36
|
+
Core works in **Node.js and the browser**, without React or a router.
|
|
123
37
|
|
|
124
|
-
|
|
38
|
+
Starting a new application? Let the generator connect the packages for you:
|
|
125
39
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
```ts
|
|
129
|
-
success: ({ result }) => ({
|
|
130
|
-
messageKey: 'users.invite.created',
|
|
131
|
-
values: { invitationId: result.invitationId },
|
|
132
|
-
}),
|
|
133
|
-
failure: ({ error }) => error instanceof InviteLimitError
|
|
134
|
-
? { messageKey: 'users.invite.limit' }
|
|
135
|
-
: undefined, // default failure text
|
|
40
|
+
```sh
|
|
41
|
+
npx @bitakit/create-app my-app
|
|
136
42
|
```
|
|
137
43
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
Command failures throw `ActionFailure`: `feedback` contains the selected string or `false`, and `cause` retains the original error. The runtime observes failed execution once and sends explicit feedback to `notify(message, kind)`, where kind is `success` or `failure`. Do not toast the same `ActionFailure` again in `onError`. Form failures also retain their inline feedback. The notifier may return a promise; throws and rejections cannot change execution outcomes. `setNotifier` returns owner-safe cleanup. No parallel execution or notification registry is introduced.
|
|
143
|
-
|
|
144
|
-
## Host integration
|
|
145
|
-
|
|
146
|
-
FoundationProvider owns the root ActionProvider or reuses an existing outer provider. Supply stable `config`, `ui`, `translate`, localized `labels`, and an optional outcome-aware `notify(message, kind)` callback to the generic UI entry. The Next adapter provides standard UI, labels and navigation defaults. The package owns form state, validation, pending/error behavior and lifecycle.
|
|
147
|
-
|
|
148
|
-
A standalone React application can supply an explicit `FoundationConfig`; Next is not required. The provider owns no global singleton. Services are created on mount, in dependency order, and disposed in reverse order. Their optional `dispose(instance)` handles external resources. Locale changes update presentation through the original registrations without recreating services or pending actions. Changing the config object replaces that plugin composition deliberately.
|
|
149
|
-
|
|
150
|
-
Form actions register the public opening action and an `<id>.submit` registration flagged `internal`: it stays executable so interceptors, pending state and execution events apply, but `useActions()` and group views hide it. Both use the existing execution engine. Submission validates required/text/email/select fields even if invoked programmatically; the form maintains drafts on failures. Disable/hide checks apply again at execution. Closing is blocked during a pending submission. Only one foundation dialog is open at a time. `render` can override the form body using `values`, `setValue`, `submit`, `pending`, `enabled`, and `error`. `defineDialogAction` provides a custom body without form submission machinery.
|
|
44
|
+
The generator requires Node.js 24 or newer. Choose Next.js or experimental TanStack
|
|
45
|
+
Start, then select the optional features you want. React bindings and framework
|
|
46
|
+
adapters are available as separate packages.
|
|
151
47
|
|
|
152
|
-
|
|
48
|
+
## Why add BitaKit?
|
|
153
49
|
|
|
154
|
-
|
|
50
|
+
Your framework handles pages and rendering. As an app grows, you also need a clear
|
|
51
|
+
way to organize features, share behavior, connect dependencies, and clean up resources.
|
|
52
|
+
BitaKit gives those pieces a common structure.
|
|
155
53
|
|
|
156
|
-
|
|
54
|
+
- **Smaller pieces. Clearer ownership.** Keep a feature's services and actions together
|
|
55
|
+
in a plugin. Teams can work on focused parts of the app with explicit connections
|
|
56
|
+
between them.
|
|
57
|
+
- **A shared language for humans and AI.** Predictable files and typed contracts make
|
|
58
|
+
it easier to describe a change, give an AI assistant focused context, and review
|
|
59
|
+
its work. The same conventions guide both developers and coding assistants.
|
|
60
|
+
- **Pluggable features.** Compose the capabilities your app needs. Add a plugin,
|
|
61
|
+
configure its defaults, or replace supported contributions through the same APIs.
|
|
62
|
+
- **Less repeated wiring.** With discovery configured, file paths supply names and
|
|
63
|
+
generated types. Core handles startup, dependencies, registration, and cleanup.
|
|
64
|
+
- **Type-safe connections.** Service methods, action inputs and results, and known
|
|
65
|
+
event payloads carry their types to callers. Your editor helps you connect the pieces.
|
|
66
|
+
- **Your stack stays yours.** Start with headless Core. Add React bindings, settings,
|
|
67
|
+
an app shell, or provider integrations when they help your product.
|
|
157
68
|
|
|
158
|
-
|
|
69
|
+
**Room to grow.** As your app and team grow, keep changes focused on small features
|
|
70
|
+
with explicit dependencies. This is about scaling your codebase and collaboration;
|
|
71
|
+
performance and infrastructure remain choices for your application.
|
|
159
72
|
|
|
160
|
-
##
|
|
73
|
+
## How the pieces fit
|
|
161
74
|
|
|
162
|
-
|
|
75
|
+
Imagine a **To-do plugin** that lets someone add a task:
|
|
163
76
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
77
|
+
```text
|
|
78
|
+
Application — chooses which plugins to use
|
|
79
|
+
│
|
|
80
|
+
▼
|
|
81
|
+
BitaKit Core — starts plugins and checks their dependencies
|
|
82
|
+
│
|
|
83
|
+
└── To-do plugin — groups one feature's contributions
|
|
84
|
+
├── Service: holds tasks and provides add/list operations
|
|
85
|
+
└── Action: calls the service to add a task
|
|
86
|
+
|
|
87
|
+
Button or server code
|
|
88
|
+
│ executes "todos.create"
|
|
89
|
+
▼
|
|
90
|
+
Action ──calls──▶ To-do service ──returns──▶ Task
|
|
91
|
+
|
|
92
|
+
Application UI displays the result; Core does not render it.
|
|
177
93
|
```
|
|
178
94
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
95
|
+
| Concept | What it does | In this example |
|
|
96
|
+
| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
|
|
97
|
+
| **Plugin** | Bundles the parts of a feature. | The To-do feature. |
|
|
98
|
+
| **Service** | Owns reusable behavior and, when needed, state or resources. | Stores tasks and exposes `create()` and `list()`. |
|
|
99
|
+
| **Action** | Provides a named operation that application code or UI can execute. | `todos.create` adds a task through the service. |
|
|
100
|
+
| **Core runtime** | Coordinates dependencies, registrations, startup, and cleanup. | Creates the service and registers the action. |
|
|
182
101
|
|
|
183
|
-
|
|
102
|
+
Core manages the lifecycle of plugin-created services. A service that acquires
|
|
103
|
+
resources can supply disposal logic. Core does not automatically save data to a
|
|
104
|
+
database or subscribe your UI to service changes.
|
|
184
105
|
|
|
185
|
-
|
|
106
|
+
## Try a To-do plugin
|
|
186
107
|
|
|
187
|
-
-
|
|
188
|
-
|
|
189
|
-
- Empty array: select none.
|
|
108
|
+
Follow the [To-do tutorial](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/todo-tutorial.md) to run three actions: create a
|
|
109
|
+
task, list tasks, and delete a task. Each action lives in its own file:
|
|
190
110
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
>
|
|
203
|
-
<App />
|
|
204
|
-
</FoundationProvider>
|
|
111
|
+
```text
|
|
112
|
+
examples/
|
|
113
|
+
├── todos.mjs # Starts the runtime and executes the actions
|
|
114
|
+
└── todos/
|
|
115
|
+
├── plugin.mjs # Groups the service and actions
|
|
116
|
+
├── services/
|
|
117
|
+
│ └── tasks.mjs # In-memory task operations
|
|
118
|
+
└── actions/
|
|
119
|
+
├── create.mjs # todos.create
|
|
120
|
+
├── list.mjs # todos.list
|
|
121
|
+
└── delete.mjs # todos.delete
|
|
205
122
|
```
|
|
206
123
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
Host services supplied through `services` retain host ownership. Plugin-created services and interceptor registrations are cleaned up with the runtime. Keep service objects and explicit arrays stable; replacing their identity deliberately replaces the runtime composition. Translation changes alone preserve the ActionList, mounted services and pending actions.
|
|
124
|
+
The plugin uses explicit imports, so no framework or discovery setup is required.
|
|
125
|
+
The script creates three tasks, lists them, deletes the second, and lists the two
|
|
126
|
+
remaining tasks. Stopping the runtime releases its registrations. Data stays in
|
|
127
|
+
memory and is lost on restart.
|
|
212
128
|
|
|
213
|
-
|
|
129
|
+
With a configured framework adapter, contribution files can instead live under
|
|
130
|
+
`src/plugins/todos/services` and `src/plugins/todos/actions`. Its build integration
|
|
131
|
+
generates registration and types. Installing Core alone does not scan folders.
|
|
132
|
+
See [file contributions](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/file-contributions.md) for the exact conventions.
|
|
214
133
|
|
|
215
|
-
##
|
|
134
|
+
## Type safety that follows your feature
|
|
216
135
|
|
|
217
|
-
|
|
136
|
+
Define a service once, then use its method types wherever you call it. Discovery
|
|
137
|
+
connects supported files to typed service access, action IDs, and configuration.
|
|
138
|
+
Shared service keys let separate packages agree on the same contract.
|
|
218
139
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
constructor() {
|
|
222
|
-
super({ title: 'Nav.logout' });
|
|
223
|
-
}
|
|
224
|
-
async execute() {
|
|
225
|
-
await logout();
|
|
226
|
-
}
|
|
227
|
-
}
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
For Action dependencies, export a function receiving the typed `ActionEnvironment` (`services`, `translate`, `config`) and returning an Action. The same context is passed to class constructors that need it. Constructors/functions should only create instances; put subscriptions in `connect()` so the ActionList owns cleanup. Discovery does not execute these exports. Plain, form and dialog definitions remain supported. Do not export mutable singleton Action instances.
|
|
231
|
-
|
|
232
|
-
`execute(input, context)` receives the invocation context as its second argument, and its return value becomes the completed result's `value`. A class may declare `success` and `failure` feedback fields; they run through the same translated feedback pipeline as declarative definitions. Without them, class actions keep raw errors and stay silent, so navigation and setting bindings never toast by accident.
|
|
140
|
+
Use `exposeAs` when you want a custom public service name; otherwise discovery uses
|
|
141
|
+
the file path. Known event names and payloads are connected through `EventMap`.
|
|
233
142
|
|
|
234
|
-
|
|
143
|
+
Unknown action IDs remain allowed unless strict mode is enabled. TypeScript checks
|
|
144
|
+
code; validate external data and authorize requests at your application boundaries.
|
|
145
|
+
See the [type-safety guide](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/reference.md)
|
|
146
|
+
for examples.
|
|
235
147
|
|
|
236
|
-
|
|
148
|
+
## React to events
|
|
237
149
|
|
|
238
|
-
|
|
150
|
+
Available since Core 0.1.1, each runtime owns one event service. Services emit
|
|
151
|
+
notifications after updating their data; actions declare `events` and `onEvent`.
|
|
239
152
|
|
|
240
|
-
|
|
241
|
-
module lists values under `contributions: { [kind]: values }`; exactly one module claims each kind
|
|
242
|
-
with `installs: { [kind]: (values, { module, app, services }) => cleanup }`. During mount the
|
|
243
|
-
runtime installs contributions after services, translation and interceptors and before actions and
|
|
244
|
-
setup, kind by kind in module dependency order. The cleanup belongs to the contributing module's
|
|
245
|
-
scope. A contributed kind without an installer, or a kind claimed twice, fails the mount.
|
|
246
|
-
Integrations type their kinds by augmenting `ContributionMap`.
|
|
247
|
-
|
|
248
|
-
`runtime.contributionsOf(kind)` returns the same values in install order without mounting, so a UI
|
|
249
|
-
integration can prepare an initial render snapshot that equals the mounted state.
|
|
250
|
-
`scopeModule(scope)` identifies the module of a runtime-issued `PluginScope` (the scope passed to
|
|
251
|
-
`setup`); integrations use it to derive ownership instead of trusting caller-supplied owner strings.
|
|
252
|
-
|
|
253
|
-
Discovery supports integration kinds in `foundation.config.ts`:
|
|
153
|
+
With file discovery configured, IDs can be omitted:
|
|
254
154
|
|
|
255
155
|
```ts
|
|
256
|
-
|
|
257
|
-
|
|
156
|
+
// src/services/todos.ts
|
|
157
|
+
import { defineService } from '@bitakit/core';
|
|
158
|
+
|
|
159
|
+
export default defineService({
|
|
160
|
+
create({ events }) {
|
|
161
|
+
let items: { id: number; title: string }[] = [];
|
|
162
|
+
let nextId = 1;
|
|
163
|
+
return {
|
|
164
|
+
list: () => [...items],
|
|
165
|
+
add(title: string) {
|
|
166
|
+
const todo = { id: nextId++, title };
|
|
167
|
+
items.push(todo);
|
|
168
|
+
events.emit('todos.changed', { kind: 'added', id: todo.id });
|
|
169
|
+
},
|
|
170
|
+
remove(id: number) {
|
|
171
|
+
items = items.filter((todo) => todo.id !== id);
|
|
172
|
+
events.emit('todos.changed', { kind: 'removed', id });
|
|
173
|
+
},
|
|
174
|
+
};
|
|
175
|
+
},
|
|
258
176
|
});
|
|
259
177
|
```
|
|
260
178
|
|
|
261
|
-
Each kind names the folder that identifies it inside every module root and the normalizer to
|
|
262
|
-
import. Generation emits `contributions: { 'settings.renderers': normalize([files], moduleId) }` for
|
|
263
|
-
the app and each enabled plugin; it never executes the files. Folders cannot collide with built-in
|
|
264
|
-
kinds or each other, and a plugin manifest can override a kind's folder through `entries`.
|
|
265
|
-
|
|
266
|
-
## Provider plugins and typed services
|
|
267
|
-
|
|
268
|
-
Provider adapters live in separate packages: `@bitakit/better-auth` and
|
|
269
|
-
`@bitakit/next-intl`. They return ordinary plugins. Pass them through `plugins`;
|
|
270
|
-
there is no separate integration lifecycle or configuration list. Core has no vendor imports.
|
|
271
|
-
Plugins may contribute services and ordered providers as well as actions, pages and views.
|
|
272
|
-
Use `serviceKey<T>`, `provideService` and `getService` to preserve input/output types without
|
|
273
|
-
pretending that an optional provider is always installed. See `docs/integrations.md`.
|
|
274
|
-
|
|
275
|
-
Plain Actions can declare `watch: ['auth']` and derive contextual presentation with `resolve(input, { services })`. The runtime validates the observable service, subscribes once per service (even for multiple Actions), refreshes the shared ActionList on changes and owns cleanup. There is no copied session state and no Action-level subscription boilerplate. `requires` remains useful for non-observable dependencies.
|
|
276
|
-
|
|
277
|
-
### Paket-Styles
|
|
278
|
-
|
|
279
|
-
Für die Verwendung der Oberfläche in einem Tailwind-4-Host `@import '@bitakit/core/styles.css';` einbinden. Der öffentliche Einstieg registriert die eigenen ausgelieferten Klassen; er definiert kein zweites Theme.
|
|
280
|
-
|
|
281
|
-
Core has no React dependencies or renderer source files. Presentation values are opaque host extension types. The backend runtime does not require the UI package. See the headless-boundary regression test.
|
|
282
|
-
|
|
283
|
-
## Typed custom Action state
|
|
284
|
-
|
|
285
179
|
```ts
|
|
286
|
-
// src/
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
180
|
+
// src/actions/todos/delete.ts
|
|
181
|
+
import { defineAction } from '@bitakit/core';
|
|
182
|
+
|
|
183
|
+
export default defineAction<number>({
|
|
184
|
+
requires: ['todos'],
|
|
185
|
+
events: ['todos.changed'],
|
|
186
|
+
setup({ services, action }) {
|
|
187
|
+
action.enabled = services.todos.list().length > 0;
|
|
188
|
+
},
|
|
189
|
+
onEvent(event, { services, action }) {
|
|
190
|
+
action.enabled = services.todos.list().length > 0;
|
|
296
191
|
},
|
|
192
|
+
execute: ({ services, input }) => services.todos.remove(input),
|
|
297
193
|
});
|
|
298
194
|
```
|
|
299
195
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
its own inferred definition can cause a TypeScript augmentation cycle, including with the
|
|
305
|
-
original API; avoid that self-reference or supply an explicit definition type.
|
|
196
|
+
Here discovery supplies `todos` and `todos.delete` from the paths (with no explicit
|
|
197
|
+
app namespace). Plugin contributions also receive their plugin namespace. Provide
|
|
198
|
+
an explicit `id` when you need a custom identity. Direct imports without discovery,
|
|
199
|
+
including the Node tutorial above, still need explicit IDs.
|
|
306
200
|
|
|
307
|
-
`
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
Late updates from a removed or replaced registration return false.
|
|
313
|
-
|
|
314
|
-
Core exports ActionStatus.Idle, Pending, Succeeded and Failed. Snapshots expose status and
|
|
315
|
-
error; the executor owns both. The existing pending guard prevents concurrent execution of
|
|
316
|
-
the same registration. Skipped calls preserve the previous status/error (an intercepted call
|
|
317
|
-
may temporarily enter Pending). ExecutionResult retains its completed/skipped contract, and
|
|
318
|
-
failed executions still reject. A successful retry clears the error.
|
|
319
|
-
|
|
320
|
-
Source responsibilities: actions/state.ts owns lifecycle names and mapped state types;
|
|
321
|
-
contributions/stateful-action.ts adapts instance-style authoring. ActionList remains the sole
|
|
322
|
-
snapshot store, and actions/execution.ts owns lifecycle transitions.
|
|
323
|
-
|
|
324
|
-
## Mixed interceptor files
|
|
325
|
-
|
|
326
|
-
Both interceptor kinds share `interceptors/`. Subfolders and dotted filenames organize entries;
|
|
327
|
-
the helper's discriminator decides the kind. Default-export a single definition, a named object
|
|
328
|
-
collection, or an array (including collections containing arrays).
|
|
329
|
-
|
|
330
|
-
```ts
|
|
331
|
-
// src/plugins/documents/interceptors/logging.ts
|
|
332
|
-
import { defineActionInterceptor, defineServiceInterceptor } from '@bitakit/core';
|
|
333
|
-
|
|
334
|
-
export default [
|
|
335
|
-
defineActionInterceptor({ before() { console.log('Action started'); } }),
|
|
336
|
-
defineServiceInterceptor({
|
|
337
|
-
service: 'documents',
|
|
338
|
-
method: 'save',
|
|
339
|
-
before({ args }) { console.log(args[0]); },
|
|
340
|
-
after({ result }) { console.log(result.title); },
|
|
341
|
-
onError({ error }) { console.error(error); },
|
|
342
|
-
}),
|
|
343
|
-
];
|
|
344
|
-
```
|
|
201
|
+
`events: ['todos.loaded', 'todos.changed']` calls `onEvent` for
|
|
202
|
+
**each** matching event. Handlers receive `{ type, data }` and can be synchronous or
|
|
203
|
+
asynchronous. Core owns subscriptions created in action `setup` and service
|
|
204
|
+
`create`, including cleanup after failed setup. No manual unsubscribe is needed.
|
|
205
|
+
For dynamic subscriptions, `setup` still offers `events.watch`. React components use `useWatchEvent` from `@bitakit/ui`.
|
|
345
206
|
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
and awaited result types. Action interceptors retain existing plugin/global scope and cancellation;
|
|
349
|
-
`defineInterceptor` remains the legacy Action helper. Service observers explicitly target a service,
|
|
350
|
-
independently of the organizing folder. `order` sorts observers ascending with stable ties.
|
|
207
|
+
See [events and action setup](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/events.md) for payload typing, errors, async
|
|
208
|
+
cancellation, and the distinction from observable-service `watch`.
|
|
351
209
|
|
|
352
|
-
|
|
353
|
-
callbacks are not awaited. Do not mutate observed arguments or results. Business methods retain
|
|
354
|
-
synchronous return behavior, original Promises and original errors. The wrapper binds methods and
|
|
355
|
-
getters to their original instance, preserving private fields. Internal self-calls and calls through
|
|
356
|
-
an original reference outside the container bypass observation. Symbol methods and constructors
|
|
357
|
-
are not observed. The method facade supports ordinary object/class services, including frozen
|
|
358
|
-
objects; it is not a general-purpose transparent reflection or callable-function proxy.
|
|
210
|
+
## What belongs outside Core?
|
|
359
211
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
212
|
+
- **React rendering:** the UI bindings and your visual components.
|
|
213
|
+
- **Routes and navigation:** your application's router and its BitaKit adapter.
|
|
214
|
+
- **Settings:** the separate App Preferences package.
|
|
215
|
+
- **Email, authentication, and persistence:** optional integrations or your own services.
|
|
363
216
|
|
|
364
|
-
|
|
365
|
-
`interceptors/service-observers.ts` wraps method access. `services.ts` owns construction/disposal,
|
|
366
|
-
and runtime routes Action definitions to the existing Action interception pipeline.
|
|
217
|
+
Plugins are trusted application code. Core is not a sandbox or a remote plugin marketplace.
|
|
367
218
|
|
|
219
|
+
## Go deeper
|
|
368
220
|
|
|
369
|
-
|
|
221
|
+
- [Runnable To-do example](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/examples/todos.mjs)
|
|
222
|
+
- [Core reference](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/reference.md): configuration, typed services, actions, lifecycle, and advanced integration.
|
|
223
|
+
- [File contributions and configuration](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/file-contributions.md): discovery and folder conventions.
|
|
224
|
+
- [npm package](https://www.npmjs.com/package/@bitakit/core)
|
|
370
225
|
|
|
371
|
-
|
|
372
|
-
Commands with a required typed input must supply `shortcut.input` of that type; the adapter never
|
|
373
|
-
infers input from focused controls or a last-clicked row. Class Actions, commands and form/dialog
|
|
374
|
-
openers retain this metadata. Internal form-submit registrations are excluded. Browser handling
|
|
375
|
-
belongs to UI's existing ActionProvider; see its README for scopes and collision behavior.
|
|
226
|
+
## License
|
|
376
227
|
|
|
377
|
-
|
|
228
|
+
[MIT](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/LICENSE). Third-party dependencies retain their own licenses.
|
|
378
229
|
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
host, URL execution reports an error. The UI ActionProvider supplies browser navigation by
|
|
382
|
-
default; the optional Next and TanStack providers use the application's existing router.
|
|
230
|
+
See [client authentication](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/auth.md) for the shared provider contract, externally
|
|
231
|
+
configured login/logout paths, UI bindings and an adapter template.
|
|
Binary file
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<svg width="300" height="130" viewBox="0 0 300 130" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<g clip-path="url(#clip0_2271_10)">
|
|
3
|
+
<path d="M6 30H15V76C15 81.2667 16.3333 85.3667 19 88.3C21.7333 91.1667 25.4667 92.6 30.2 92.6C35.1333 92.6 39 91.2 41.8 88.4C44.6 85.5333 46 81.4 46 76C46 70.8667 44.4667 66.8333 41.4 63.9C38.4 60.9 34.4333 59.4 29.5 59.4C25.3 59.4 21.6667 60.6 18.6 63V54C22.2667 52 26.2333 51 30.5 51C37.5667 51 43.4 53.3 48 57.9C52.6667 62.4333 55 68.4667 55 76C55 83.9333 52.5667 90.1 47.7 94.5C42.9 98.8333 36.8333 101 29.5 101C22.5 101 16.8333 98.7333 12.5 94.2C8.16667 89.6667 6 83.6 6 76V30ZM78.4727 100H69.6727V60.4H61.4727L65.4727 52H78.4727V100ZM69.2727 42C68.406 40.8667 67.9727 39.6333 67.9727 38.3C67.9727 36.9667 68.406 35.7667 69.2727 34.7C70.1393 33.5667 71.4727 33 73.2727 33C75.0727 33 76.406 33.5667 77.2727 34.7C78.1393 35.7667 78.5727 36.9667 78.5727 38.3C78.5727 39.6333 78.1393 40.8667 77.2727 42C76.406 43.0667 75.0727 43.6 73.2727 43.6C71.4727 43.6 70.1393 43.0667 69.2727 42ZM86.8398 60.4L104.74 42.5V52H118.24V60.4H104.74V81C104.74 83.3333 105.107 85.2667 105.84 86.8C106.64 88.3333 107.773 89.4333 109.24 90.1C110.707 90.7 112.073 91.1 113.34 91.3C114.673 91.5 116.307 91.6 118.24 91.6V100C110.573 100 104.907 98.5333 101.24 95.6C97.5732 92.6667 95.7398 87.8 95.7398 81V60.4H86.8398ZM154.477 71.8V80.8C151.944 78.8667 148.844 77.9 145.177 77.9C142.044 77.9 139.611 78.5333 137.877 79.8C136.144 81 135.277 82.7333 135.277 85C135.277 89.4 138.544 91.6 145.077 91.6H158.277V72.5C158.277 64.4333 154.344 60.4 146.477 60.4H130.477V52H146.977C153.444 52 158.411 53.6 161.877 56.8C165.344 60 167.077 64.6 167.077 70.6V100H144.777C139.111 100 134.611 98.7333 131.277 96.2C127.944 93.6667 126.277 89.9667 126.277 85.1C126.277 80.2333 128.044 76.5333 131.577 74C135.111 71.4667 139.544 70.2 144.877 70.2C147.877 70.2 151.077 70.7333 154.477 71.8Z" fill="white"/>
|
|
4
|
+
<path d="M205.67 52H215.37L203.27 72.9C211.47 75.1 215.57 81.7333 215.57 92.8V100H206.77V92.7C206.77 88.2333 205.437 84.8 202.77 82.4C200.17 79.9333 196.437 78.7 191.57 78.7C190.037 78.7 188.47 78.8 186.87 79V100H178.07V30H186.87V71.1C189.67 70.7 192.47 70.7 195.27 71.1L205.67 52ZM239.117 100H230.317V60.4H222.117L226.117 52H239.117V100ZM229.917 42C229.051 40.8667 228.617 39.6333 228.617 38.3C228.617 36.9667 229.051 35.7667 229.917 34.7C230.784 33.5667 232.117 33 233.917 33C235.717 33 237.051 33.5667 237.917 34.7C238.784 35.7667 239.217 36.9667 239.217 38.3C239.217 39.6333 238.784 40.8667 237.917 42C237.051 43.0667 235.717 43.6 233.917 43.6C232.117 43.6 230.784 43.0667 229.917 42ZM247.484 60.4L265.384 42.5V52H278.884V60.4H265.384V81C265.384 83.3333 265.751 85.2667 266.484 86.8C267.284 88.3333 268.418 89.4333 269.884 90.1C271.351 90.7 272.718 91.1 273.984 91.3C275.318 91.5 276.951 91.6 278.884 91.6V100C271.218 100 265.551 98.5333 261.884 95.6C258.218 92.6667 256.384 87.8 256.384 81V60.4H247.484Z" fill="#EBB759"/>
|
|
5
|
+
</g>
|
|
6
|
+
<defs>
|
|
7
|
+
<clipPath id="clip0_2271_10">
|
|
8
|
+
<rect width="300" height="130" fill="white"/>
|
|
9
|
+
</clipPath>
|
|
10
|
+
</defs>
|
|
11
|
+
</svg>
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<svg width="300" height="130" viewBox="0 0 300 130" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<g clip-path="url(#clip0_2269_3)">
|
|
3
|
+
<path d="M6 30H15V76C15 81.2667 16.3333 85.3667 19 88.3C21.7333 91.1667 25.4667 92.6 30.2 92.6C35.1333 92.6 39 91.2 41.8 88.4C44.6 85.5333 46 81.4 46 76C46 70.8667 44.4667 66.8333 41.4 63.9C38.4 60.9 34.4333 59.4 29.5 59.4C25.3 59.4 21.6667 60.6 18.6 63V54C22.2667 52 26.2333 51 30.5 51C37.5667 51 43.4 53.3 48 57.9C52.6667 62.4333 55 68.4667 55 76C55 83.9333 52.5667 90.1 47.7 94.5C42.9 98.8333 36.8333 101 29.5 101C22.5 101 16.8333 98.7333 12.5 94.2C8.16667 89.6667 6 83.6 6 76V30ZM78.4727 100H69.6727V60.4H61.4727L65.4727 52H78.4727V100ZM69.2727 42C68.406 40.8667 67.9727 39.6333 67.9727 38.3C67.9727 36.9667 68.406 35.7667 69.2727 34.7C70.1393 33.5667 71.4727 33 73.2727 33C75.0727 33 76.406 33.5667 77.2727 34.7C78.1393 35.7667 78.5727 36.9667 78.5727 38.3C78.5727 39.6333 78.1393 40.8667 77.2727 42C76.406 43.0667 75.0727 43.6 73.2727 43.6C71.4727 43.6 70.1393 43.0667 69.2727 42ZM86.8398 60.4L104.74 42.5V52H118.24V60.4H104.74V81C104.74 83.3333 105.107 85.2667 105.84 86.8C106.64 88.3333 107.773 89.4333 109.24 90.1C110.707 90.7 112.073 91.1 113.34 91.3C114.673 91.5 116.307 91.6 118.24 91.6V100C110.573 100 104.907 98.5333 101.24 95.6C97.5732 92.6667 95.7398 87.8 95.7398 81V60.4H86.8398ZM154.477 71.8V80.8C151.944 78.8667 148.844 77.9 145.177 77.9C142.044 77.9 139.611 78.5333 137.877 79.8C136.144 81 135.277 82.7333 135.277 85C135.277 89.4 138.544 91.6 145.077 91.6H158.277V72.5C158.277 64.4333 154.344 60.4 146.477 60.4H130.477V52H146.977C153.444 52 158.411 53.6 161.877 56.8C165.344 60 167.077 64.6 167.077 70.6V100H144.777C139.111 100 134.611 98.7333 131.277 96.2C127.944 93.6667 126.277 89.9667 126.277 85.1C126.277 80.2333 128.044 76.5333 131.577 74C135.111 71.4667 139.544 70.2 144.877 70.2C147.877 70.2 151.077 70.7333 154.477 71.8Z" fill="#122F4D"/>
|
|
4
|
+
<path d="M205.67 52H215.37L203.27 72.9C211.47 75.1 215.57 81.7333 215.57 92.8V100H206.77V92.7C206.77 88.2333 205.437 84.8 202.77 82.4C200.17 79.9333 196.437 78.7 191.57 78.7C190.037 78.7 188.47 78.8 186.87 79V100H178.07V30H186.87V71.1C189.67 70.7 192.47 70.7 195.27 71.1L205.67 52ZM239.117 100H230.317V60.4H222.117L226.117 52H239.117V100ZM229.917 42C229.051 40.8667 228.617 39.6333 228.617 38.3C228.617 36.9667 229.051 35.7667 229.917 34.7C230.784 33.5667 232.117 33 233.917 33C235.717 33 237.051 33.5667 237.917 34.7C238.784 35.7667 239.217 36.9667 239.217 38.3C239.217 39.6333 238.784 40.8667 237.917 42C237.051 43.0667 235.717 43.6 233.917 43.6C232.117 43.6 230.784 43.0667 229.917 42ZM247.484 60.4L265.384 42.5V52H278.884V60.4H265.384V81C265.384 83.3333 265.751 85.2667 266.484 86.8C267.284 88.3333 268.418 89.4333 269.884 90.1C271.351 90.7 272.718 91.1 273.984 91.3C275.318 91.5 276.951 91.6 278.884 91.6V100C271.218 100 265.551 98.5333 261.884 95.6C258.218 92.6667 256.384 87.8 256.384 81V60.4H247.484Z" fill="#EBB759"/>
|
|
5
|
+
</g>
|
|
6
|
+
<defs>
|
|
7
|
+
<clipPath id="clip0_2269_3">
|
|
8
|
+
<rect width="300" height="130" fill="white"/>
|
|
9
|
+
</clipPath>
|
|
10
|
+
</defs>
|
|
11
|
+
</svg>
|