@bitakit/cli 0.2.0 → 0.2.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 +128 -11
- package/package.json +4 -3
- package/skills/bitakit-app-development/README.md +121 -0
- package/skills/bitakit-app-development/SKILL.md +144 -0
- package/skills/bitakit-app-development/references/actions.md +198 -0
- package/skills/bitakit-app-development/references/interceptors.md +164 -0
- package/skills/bitakit-app-development/references/plugins-and-pages.md +165 -0
- package/skills/bitakit-app-development/references/services-and-events.md +173 -0
- package/skills/bitakit-app-development/references/settings.md +183 -0
- package/skills/bitakit-app-development/references/slots.md +165 -0
- package/skills/bitakit-app-development/references/testing-and-preview.md +171 -0
- package/src/add.mjs +96 -4
- package/src/agent-rules.mjs +53 -3
- package/src/agent-skill.mjs +152 -0
- package/src/check-page.mjs +385 -0
- package/src/cli.mjs +109 -18
- package/src/doctor-agent-files.mjs +66 -0
- package/src/doctor.mjs +5 -2
- package/src/index.mjs +16 -1
- package/src/init.mjs +72 -21
- package/src/slots.mjs +227 -0
- package/src/templates.mjs +86 -45
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# Services and events
|
|
2
|
+
|
|
3
|
+
Use a service when a feature owns state or logic that pages, Actions and other plugins share.
|
|
4
|
+
Use an event when the owning plugin must tell other plugins that something happened.
|
|
5
|
+
|
|
6
|
+
## Add a service
|
|
7
|
+
|
|
8
|
+
`npx bitakit add service todos/list` creates `src/plugins/todos/services/list.ts`. The path
|
|
9
|
+
names the service `todos.list`; a nested `services/archive/list.ts` would be `todos.archive.list`.
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { defineService } from '@bitakit/core';
|
|
13
|
+
|
|
14
|
+
export type Todo = { id: number; title: string };
|
|
15
|
+
|
|
16
|
+
// The todo list. It lives in memory, so a reload starts empty; call your API here later.
|
|
17
|
+
export default defineService(({ store, events }) => {
|
|
18
|
+
const state = store<{ todos: Todo[] }>({ todos: [] });
|
|
19
|
+
let next = 1;
|
|
20
|
+
return {
|
|
21
|
+
state,
|
|
22
|
+
add(title: string) {
|
|
23
|
+
const todo = { id: next++, title: title.trim() };
|
|
24
|
+
state.set((current) => ({ todos: [...current.todos, todo] }));
|
|
25
|
+
events.emit('todos.changed', { kind: 'added', title: todo.title });
|
|
26
|
+
},
|
|
27
|
+
remove(id: number) {
|
|
28
|
+
const removed = state.get().todos.find((todo) => todo.id === id);
|
|
29
|
+
state.set((current) => ({ todos: current.todos.filter((todo) => todo.id !== id) }));
|
|
30
|
+
if (removed) events.emit('todos.changed', { kind: 'removed', title: removed.title });
|
|
31
|
+
},
|
|
32
|
+
clear() {
|
|
33
|
+
state.set({ todos: [] });
|
|
34
|
+
events.emit('todos.changed', { kind: 'cleared' });
|
|
35
|
+
},
|
|
36
|
+
};
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- The factory receives `{ store, events, services, settings, config, onStart, onStop }` and
|
|
41
|
+
returns the instance. Destructure only what it uses.
|
|
42
|
+
- Return the store as `state`. Actions and `useServiceState` follow it automatically; the
|
|
43
|
+
service never notifies anyone by hand.
|
|
44
|
+
- `state.get()` reads. `state.set(next)` or `state.set((current) => next)` replaces the whole
|
|
45
|
+
value, so build new arrays and objects.
|
|
46
|
+
- `store()` is memory only: a reload starts empty. To persist, load in
|
|
47
|
+
`onStart(async ({ signal }) => ...)` and save inside the methods through the app's own API.
|
|
48
|
+
Release connections in `onStop`.
|
|
49
|
+
- Read settings at call time, as Actions do: `settings.todos.limit.get()`.
|
|
50
|
+
|
|
51
|
+
## Read a service in React
|
|
52
|
+
|
|
53
|
+
`src/plugins/summary/ui/slots/shell.header.end.tsx` shows the count in the Shell header.
|
|
54
|
+
`npx bitakit add slot summary/shell.header.end` writes the same slot as
|
|
55
|
+
`ui/slots/shell/header/end.tsx`; see [slots.md](slots.md).
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
'use client';
|
|
59
|
+
import { useServiceState } from '@bitakit/ui';
|
|
60
|
+
|
|
61
|
+
export default function TodoCount() {
|
|
62
|
+
// 0 is shown until the todos plugin is ready.
|
|
63
|
+
const count = useServiceState('todos.list', (state) => state.todos.length, 0);
|
|
64
|
+
return <span className="text-sm text-muted-foreground">{count} todos</span>;
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- `useServiceState(name, selector, fallback)` returns `fallback` until the runtime and the owning
|
|
69
|
+
plugin are ready, then re-renders only when the selected value changes. Select the smallest
|
|
70
|
+
value you need.
|
|
71
|
+
- The name is checked against the generated service map, so a typo fails `npm run typecheck`.
|
|
72
|
+
- `useService('todos.list')` returns the instance, or `undefined` until it is ready. To run an
|
|
73
|
+
operation from a control, bind its Action (`<Action id="todos.add">`) so pending and disabled
|
|
74
|
+
states come from the Action; see [actions.md](actions.md).
|
|
75
|
+
- Hooks need no `requires`: they show the fallback while the owner is starting or missing.
|
|
76
|
+
|
|
77
|
+
## Use another plugin's service in an Action or service
|
|
78
|
+
|
|
79
|
+
Actions and services reach every service as `services.<plugin>.<name>`. Here the `print` plugin
|
|
80
|
+
enables its toolbar Action only when the list has todos: `src/plugins/print/actions/list.ts`. It
|
|
81
|
+
targets the `todos.toolbar` slot, which the todos plugin declares and renders (see
|
|
82
|
+
[slots.md](slots.md)).
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { defineAction } from '@bitakit/core';
|
|
86
|
+
|
|
87
|
+
export default defineAction({
|
|
88
|
+
title: 'Print list',
|
|
89
|
+
slots: ['todos.toolbar'],
|
|
90
|
+
// Startup reports a missing todos.list service by name instead of failing on the first render.
|
|
91
|
+
requires: ['todos.list'],
|
|
92
|
+
enabled: ({ services }) => services.todos.list.state.get().todos.length > 0,
|
|
93
|
+
execute: () => window.print(),
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
- List every service of another plugin in `requires`. Startup and `npx bitakit doctor` then
|
|
98
|
+
report a missing or misspelled name and suggest the right one.
|
|
99
|
+
- A service whose factory reads another service lists it in `requires` in the second argument,
|
|
100
|
+
even inside its own plugin: `defineService(factory, { requires: ['todos.list'] })`. That also creates
|
|
101
|
+
`todos.list` first and reports cycles.
|
|
102
|
+
- `enabled`, `visible` and `title` functions re-run when `todos.list` changes, so the button
|
|
103
|
+
follows the list.
|
|
104
|
+
- For an optional dependency, leave out `requires` and check `app.has('todos.list')` before
|
|
105
|
+
reading; every Action function receives `app`. Reading a missing service throws, and `?.`
|
|
106
|
+
does not prevent that.
|
|
107
|
+
- Shared contracts (`defineContract('auth').of<AuthService>()` plus
|
|
108
|
+
`defineService(factory, { provides: authService })`) are for packages where any plugin may
|
|
109
|
+
provide a service such as `auth`. App features use plugin service names as shown here.
|
|
110
|
+
|
|
111
|
+
## Declare an event
|
|
112
|
+
|
|
113
|
+
`npx bitakit add events todos` takes only the plugin name and creates
|
|
114
|
+
`src/plugins/todos/events.ts`, the plugin's single events file.
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
import { defineEvents, event } from '@bitakit/core';
|
|
118
|
+
|
|
119
|
+
// Tells other plugins what changed; they listen with events.on('todos.changed', ...).
|
|
120
|
+
export default defineEvents({
|
|
121
|
+
changed: event<{ kind: 'added' | 'removed' | 'cleared'; title?: string }>(),
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
- The plugin ID prefixes each name: `changed` becomes `todos.changed`. Use letters, digits, `_`
|
|
126
|
+
or `-`, without dots.
|
|
127
|
+
- `event<T>()` types the payload; `event()` has none. `npm run typecheck` runs `bitakit generate`,
|
|
128
|
+
which adds the new event to the types.
|
|
129
|
+
- Emit after the state change, from the declaring plugin only: its services (see `clear()`
|
|
130
|
+
above) or its Actions through `execute: ({ events }) => ...`.
|
|
131
|
+
- When another plugin emits `todos.changed`, the runtime throws. That plugin listens instead,
|
|
132
|
+
or the owner adds the event it needs.
|
|
133
|
+
|
|
134
|
+
## Listen from another plugin
|
|
135
|
+
|
|
136
|
+
`src/plugins/activity/services/feed.ts` records each change without touching the todos folder.
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
import { defineService } from '@bitakit/core';
|
|
140
|
+
|
|
141
|
+
// Listens to the todos plugin without changing it; the listener ends when this plugin stops.
|
|
142
|
+
export default defineService(({ store, events }) => {
|
|
143
|
+
const state = store<{ entries: string[] }>({ entries: [] });
|
|
144
|
+
events.on('todos.changed', ({ data }) => {
|
|
145
|
+
const entry =
|
|
146
|
+
data.kind === 'cleared'
|
|
147
|
+
? 'Cleared the list'
|
|
148
|
+
: `${data.kind === 'added' ? 'Added' : 'Removed'} "${data.title}"`;
|
|
149
|
+
state.set((current) => ({ entries: [entry, ...current.entries].slice(0, 5) }));
|
|
150
|
+
});
|
|
151
|
+
return { state };
|
|
152
|
+
});
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
- Subscribe in the service factory. The runtime removes the listener when the plugin stops;
|
|
156
|
+
`events.on` also returns an unsubscribe function.
|
|
157
|
+
- The handler receives `{ type, data }` and `{ signal }`. `events.on` accepts one name, an array
|
|
158
|
+
of names, a prefix such as `'todos.*'`, or `'*'`.
|
|
159
|
+
- Events are not replayed. A plugin that starts later reads current data from `todos.list`.
|
|
160
|
+
- Delivery is synchronous and async handlers are not awaited, unless the event is declared with
|
|
161
|
+
`event({ cancelable: true })`; then `emit` waits and resolves to `false` if a handler cancelled.
|
|
162
|
+
A failing handler is logged and the other listeners still run.
|
|
163
|
+
- In React, `useEvent('todos.changed', ({ data }) => ...)` from `@bitakit/ui` listens while the
|
|
164
|
+
component is mounted and the runtime is ready. To display data, use `useServiceState` instead.
|
|
165
|
+
- Listeners live in a service or in `useEvent`; an Action definition does not subscribe.
|
|
166
|
+
|
|
167
|
+
## Explain it to the user
|
|
168
|
+
|
|
169
|
+
Name the owner and the contract: "The todos plugin owns the list in its `todos.list` service and
|
|
170
|
+
announces changes as `todos.changed`; activity listens to that event, and summary reads the
|
|
171
|
+
service, without changing the todos folder." Say where it appears (the todos page, the header
|
|
172
|
+
count) and how to try it: add a todo and watch the feed and the count update. Mention that the
|
|
173
|
+
list is in memory, so a reload clears it until the app saves it through its own API.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Settings (user preferences)
|
|
2
|
+
|
|
3
|
+
Use a setting for a value the user chooses and expects to keep after a reload: a limit, an
|
|
4
|
+
on/off choice, a display option. In-memory feature state belongs in a service `store()`.
|
|
5
|
+
|
|
6
|
+
## Declare settings
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npx bitakit add settings todos
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`src/plugins/todos/settings.ts` (one file per plugin; edit it when it already exists):
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
import { defineSettings, setting } from '@bitakit/core';
|
|
16
|
+
|
|
17
|
+
export default defineSettings(
|
|
18
|
+
{
|
|
19
|
+
limit: setting({ default: 20, control: 'number', label: 'Maximum todos' }),
|
|
20
|
+
newOnTop: setting({ default: false, label: 'New todos on top' }),
|
|
21
|
+
},
|
|
22
|
+
{ title: 'Todos', order: 10 },
|
|
23
|
+
);
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
- The key is `<plugin>.<name>`: `todos.limit`, `todos.newOnTop`. Names use letters, digits, `_`
|
|
27
|
+
or `-`, no dots. The command refuses to overwrite an existing `settings.ts`.
|
|
28
|
+
- `setting()` requires `default`. Optional: `label`, `description`, `control`, `options`,
|
|
29
|
+
`schema`, `scope`, `group`, `order`, `hidden`. The type follows `default`, `options` or `schema`.
|
|
30
|
+
- `control` is one of `switch`, `select`, `radio`, `cards`, `text`, `textarea`, `number`. Leave it
|
|
31
|
+
out to infer it: boolean → switch, `options` → select, number → number, string → text.
|
|
32
|
+
- `scope` is `user` (default), `device` or `organization`. An `organization` setting stays at its
|
|
33
|
+
default and read-only until the `auth` service reports an active organization; use it only in
|
|
34
|
+
such apps.
|
|
35
|
+
- `options` (`[{ value, label?, description? }]`) limits the value to the list; `schema` takes a
|
|
36
|
+
synchronous Standard Schema (zod, valibot) the app already depends on.
|
|
37
|
+
- The second argument styles the page: `title`, `description`, `icon`, `path` (URL segment,
|
|
38
|
+
default the plugin ID), `category`, `order`, `shortcut` (for example `'Alt+Shift+T'`).
|
|
39
|
+
|
|
40
|
+
## Read and write in Actions
|
|
41
|
+
|
|
42
|
+
The sample's `src/plugins/todos/actions/add.ts` reads `todos.limit`:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { defineAction } from '@bitakit/core';
|
|
46
|
+
|
|
47
|
+
export default defineAction<string>({
|
|
48
|
+
title: 'Add',
|
|
49
|
+
enabled: ({ input, services, settings }) =>
|
|
50
|
+
!!input?.trim() && services.todos.list.state.get().todos.length < settings.todos.limit.get(),
|
|
51
|
+
execute: ({ services, input }) => services.todos.list.add(input),
|
|
52
|
+
});
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
- Presentation functions (`title`, `enabled`, `visible`, `href`, `confirm`, ...) and `execute`
|
|
56
|
+
receive `settings`; `success` and `failure` do not.
|
|
57
|
+
Read with `settings.todos.limit.get()`; presentation re-runs when the value changes.
|
|
58
|
+
- Write with `settings.todos.newOnTop.set(value)` or `.reset()`. Both return a promise of
|
|
59
|
+
`'saved' | 'superseded' | 'cancelled'`. They reject on an invalid value, a read-only setting, a
|
|
60
|
+
failed save, or before stored values have loaded (`settings.todos.newOnTop.state().ready`).
|
|
61
|
+
- Read the setting where you need it; a copy in a service store goes stale.
|
|
62
|
+
|
|
63
|
+
## Read in a service
|
|
64
|
+
|
|
65
|
+
Services get the same `settings` in their factory. `src/plugins/todos/services/list.ts`:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import { defineService } from '@bitakit/core';
|
|
69
|
+
|
|
70
|
+
export type Todo = { id: number; title: string };
|
|
71
|
+
|
|
72
|
+
export default defineService(({ store, events, settings }) => {
|
|
73
|
+
const state = store<{ todos: Todo[] }>({ todos: [] });
|
|
74
|
+
let next = 1;
|
|
75
|
+
return {
|
|
76
|
+
state,
|
|
77
|
+
add(title: string) {
|
|
78
|
+
const todo = { id: next++, title: title.trim() };
|
|
79
|
+
const newOnTop = settings.todos.newOnTop.get();
|
|
80
|
+
state.set((current) => ({
|
|
81
|
+
todos: newOnTop ? [todo, ...current.todos] : [...current.todos, todo],
|
|
82
|
+
}));
|
|
83
|
+
events.emit('todos.changed', { kind: 'added', title: todo.title });
|
|
84
|
+
},
|
|
85
|
+
remove(id: number) {
|
|
86
|
+
const removed = state.get().todos.find((todo) => todo.id === id);
|
|
87
|
+
state.set((current) => ({ todos: current.todos.filter((todo) => todo.id !== id) }));
|
|
88
|
+
if (removed) events.emit('todos.changed', { kind: 'removed', title: removed.title });
|
|
89
|
+
},
|
|
90
|
+
clear() {
|
|
91
|
+
state.set({ todos: [] });
|
|
92
|
+
events.emit('todos.changed', { kind: 'cleared' });
|
|
93
|
+
},
|
|
94
|
+
};
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
- Call `.get()` inside methods, not in the factory body: the factory runs before stored values
|
|
99
|
+
load, so a value read there stays at its default. Each call sees the latest choice.
|
|
100
|
+
|
|
101
|
+
## Use a setting in React
|
|
102
|
+
|
|
103
|
+
`src/plugins/todos/ui/new-on-top-toggle.tsx`; import it in `ui/pages/index.tsx` and render
|
|
104
|
+
`<NewOnTopToggle />`:
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
'use client';
|
|
108
|
+
import { useSetting } from '@bitakit/ui';
|
|
109
|
+
import { Button } from '@bitakit/ui/components';
|
|
110
|
+
|
|
111
|
+
export function NewOnTopToggle() {
|
|
112
|
+
const newOnTop = useSetting('todos.newOnTop');
|
|
113
|
+
return (
|
|
114
|
+
<Button
|
|
115
|
+
variant="outline"
|
|
116
|
+
size="sm"
|
|
117
|
+
disabled={newOnTop.disabled}
|
|
118
|
+
onClick={() => newOnTop.set(!newOnTop.value)}
|
|
119
|
+
>
|
|
120
|
+
{newOnTop.value ? 'New todos on top' : 'New todos at the bottom'}
|
|
121
|
+
</Button>
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- `useSetting(key)` returns `{ value, ready, writable, pending, error?, disabled, set, reset,
|
|
127
|
+
key, definition }`; `disabled` covers not loaded, read-only and saving. Keys are typed by
|
|
128
|
+
`bitakit generate` (part of `npm run typecheck`).
|
|
129
|
+
- For the standard labelled field outside `/settings`, render
|
|
130
|
+
`<SettingField settingKey="todos.newOnTop" />` from `@bitakit/app-preferences`.
|
|
131
|
+
|
|
132
|
+
## Show and customize the Settings page
|
|
133
|
+
|
|
134
|
+
Each `settings.ts` gets a generated page at `/settings/todos` with a navigation entry (and a Quick
|
|
135
|
+
Search result when `@bitakit/quick-search` is installed, the create-app default). It needs `@bitakit/app-preferences` in `package.json` and the route
|
|
136
|
+
`src/app/settings/[[...section]]/page.tsx` rendering `<SettingsRoute />` (create-app default).
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
npx bitakit add settings-page todos
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
`src/plugins/todos/ui/settings/page.tsx` replaces the generated body and keeps its URL and
|
|
143
|
+
navigation:
|
|
144
|
+
|
|
145
|
+
```tsx
|
|
146
|
+
'use client';
|
|
147
|
+
import type { ReactNode } from 'react';
|
|
148
|
+
import type { SettingsCatalogField, SettingsCatalogSection } from '@bitakit/app-preferences';
|
|
149
|
+
|
|
150
|
+
export default function SettingsPage({
|
|
151
|
+
section,
|
|
152
|
+
renderField,
|
|
153
|
+
}: {
|
|
154
|
+
section: SettingsCatalogSection;
|
|
155
|
+
renderField: (field: SettingsCatalogField) => ReactNode;
|
|
156
|
+
}) {
|
|
157
|
+
return (
|
|
158
|
+
<>
|
|
159
|
+
<p className="text-sm text-muted-foreground">
|
|
160
|
+
Todos live in memory; these preferences are saved.
|
|
161
|
+
</p>
|
|
162
|
+
{section.fields.map(renderField)}
|
|
163
|
+
</>
|
|
164
|
+
);
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
- `renderField` keeps the standard control, saving state, inline error and reset. A `hidden`
|
|
169
|
+
setting stays off every page but works in code.
|
|
170
|
+
|
|
171
|
+
## Persistence
|
|
172
|
+
|
|
173
|
+
- Values are saved in browser storage by default, per browser (and per signed-in user for `user`
|
|
174
|
+
scope); another device or cleared site data starts from the defaults.
|
|
175
|
+
- To save on a server, add one host service with `provides: settingsStorage` (see the
|
|
176
|
+
`@bitakit/app-preferences` README); `settings.ts` files stay unchanged.
|
|
177
|
+
|
|
178
|
+
## Explain it to the user
|
|
179
|
+
|
|
180
|
+
Say which plugin owns the setting (`todos` declares `todos.newOnTop` in its `settings.ts`), who
|
|
181
|
+
reads it (the `todos.list` service when adding; `useSetting` in the page) and where to change it:
|
|
182
|
+
`/settings/todos`. To try it, turn on the switch there and add two todos on `/todos`: the newest is on top.
|
|
183
|
+
Reload: the switch is still on in this browser, and the todos are gone (they live in memory).
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Slots (extension points)
|
|
2
|
+
|
|
3
|
+
Use this when one plugin should show something inside another plugin's page or inside the
|
|
4
|
+
Shell (header, sidebar, toolbar). The owner declares and renders a named slot; other plugins
|
|
5
|
+
fill it from their own folder.
|
|
6
|
+
|
|
7
|
+
## Find a slot
|
|
8
|
+
|
|
9
|
+
Look for an existing slot before declaring one. `npx bitakit slots` lists every slot the app can
|
|
10
|
+
fill, grouped by owner (the app's plugins, then installed packages such as Shell), with what it
|
|
11
|
+
accepts and how many contributions the app's files already add. `npx bitakit slots --json` adds:
|
|
12
|
+
|
|
13
|
+
- `payload` and `payloadKeys`: the context each outlet passes, for example `["todoId"]`.
|
|
14
|
+
- `source`: the file that declares a local slot.
|
|
15
|
+
- `contributions`: the `ui/slots` components and the Actions whose `slots` list name it.
|
|
16
|
+
- `unknownTargets`: contributions whose slot nobody declares. They render nowhere; fix the name or
|
|
17
|
+
declare the slot.
|
|
18
|
+
|
|
19
|
+
Match `accepts`: an Action for `actions`, a `ui/slots` component for `component`. `null` means
|
|
20
|
+
the command cannot read it from the files, for example the payload of a package slot; the Shell
|
|
21
|
+
table below and the package's README (`@bitakit/shell`, `@bitakit/app-preferences`) list those
|
|
22
|
+
payloads. Packages add their own contributions at runtime.
|
|
23
|
+
|
|
24
|
+
## Declare a slot
|
|
25
|
+
|
|
26
|
+
`npx bitakit add slot-definition todos/toolbar` creates `src/plugins/todos/slots/toolbar.ts`.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { defineSlot } from '@bitakit/core';
|
|
30
|
+
|
|
31
|
+
export default defineSlot({ accepts: 'actions' });
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
- The path is the ID: `todos/slots/toolbar.ts` is `todos.toolbar`; `slots/row/menu.ts` and
|
|
35
|
+
`slots/row.menu.ts` are both `todos.row.menu`.
|
|
36
|
+
- The command writes `accepts: 'component'`. Set `accepts` to what the slot takes: `'actions'`
|
|
37
|
+
(buttons, links, menu items), `'component'` (React widgets) or `'data'` (needs a `schema`).
|
|
38
|
+
- `policy` is `'list'` by default. `'single'` allows one occupant; a second one fails as a
|
|
39
|
+
conflict. `'keyed'` requires a unique `key` per contribution (a repeated key fails as a
|
|
40
|
+
conflict); the outlet picks one with `entryKey`.
|
|
41
|
+
- `payload` is a schema for context the owner passes to every outlet, such as a row ID.
|
|
42
|
+
- A declaration renders nothing. The owner also mounts an outlet (next section).
|
|
43
|
+
|
|
44
|
+
## Render the slot where it belongs
|
|
45
|
+
|
|
46
|
+
A component slot needs one line in the owner's UI: `<PluginSlot name="todos.footer" />`
|
|
47
|
+
(the sample page already does this). An actions slot uses `useSlot` and the standard `Button`.
|
|
48
|
+
Add this to `src/plugins/todos/ui/pages/index.tsx` (it already imports `Action` and `Button`),
|
|
49
|
+
add `useSlot` to its `@bitakit/ui` import and render `<TodosToolbar />` above the `<ul>`:
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
function TodosToolbar() {
|
|
53
|
+
const toolbar = useSlot('todos.toolbar');
|
|
54
|
+
if (toolbar.error) throw toolbar.error;
|
|
55
|
+
if (!toolbar.items.length) return null;
|
|
56
|
+
return (
|
|
57
|
+
<div role="group" aria-label="Todo actions" className="flex flex-wrap gap-2">
|
|
58
|
+
{toolbar.items.map((item) => (
|
|
59
|
+
<Action key={item.key} id={item.action}>
|
|
60
|
+
<Button variant="outline" size="sm" />
|
|
61
|
+
</Action>
|
|
62
|
+
))}
|
|
63
|
+
</div>
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- Each item has `key`, `plugin`, `order`, `actionId`, `input` and `action` (the live control).
|
|
69
|
+
Use `item.key` as the React key and pass `item.action` to `<Action id>`.
|
|
70
|
+
- An empty `<Button />` gets the Action's icon, title, disabled and pending state.
|
|
71
|
+
- `useSlot` also returns `payload`, `pending`, `phase`, `error` and `diagnostics`. Items stay
|
|
72
|
+
empty while the slot is pending.
|
|
73
|
+
- For a slot with a payload, pass it at every outlet:
|
|
74
|
+
`useSlot('todos.row.menu', { payload: { todoId: todo.id } })` or
|
|
75
|
+
`<PluginSlot name="sidebar.footer" payload={{ collapsed }} />`.
|
|
76
|
+
|
|
77
|
+
## Contribute a component
|
|
78
|
+
|
|
79
|
+
`npx bitakit add slot summary/shell.header.end` creates
|
|
80
|
+
`src/plugins/summary/ui/slots/shell/header/end.tsx`.
|
|
81
|
+
|
|
82
|
+
```tsx
|
|
83
|
+
'use client';
|
|
84
|
+
import { useServiceState } from '@bitakit/ui';
|
|
85
|
+
|
|
86
|
+
export default function TodoCount() {
|
|
87
|
+
// The fallback keeps the header stable while todos starts or when it is not installed.
|
|
88
|
+
const count = useServiceState('todos.list', (state) => state.todos.length, 0);
|
|
89
|
+
return <span className="text-sm text-muted-foreground">{count} todos</span>;
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
- The file path is the full ID of the target slot (`todos.footer`, `shell.header.end`); your
|
|
94
|
+
own plugin name is not added. Dots and folders are
|
|
95
|
+
equal: `ui/slots/todos.footer.tsx` (the activity sample) equals `ui/slots/todos/footer.tsx`.
|
|
96
|
+
Keep one file per slot per plugin; two spellings fail generation as a duplicate.
|
|
97
|
+
- For a slot with a payload, the component receives it:
|
|
98
|
+
`({ payload }: SlotProps<'sidebar.footer'>)` with `SlotProps` from `@bitakit/ui`.
|
|
99
|
+
- Optional exports: `order` (ascending, default 0), `key` (required by keyed slots) and
|
|
100
|
+
`when` (`({ payload }) => boolean`, filters per outlet).
|
|
101
|
+
- `ui/slots` files fill component slots only. Actions slots take Actions (next section).
|
|
102
|
+
|
|
103
|
+
## Place an Action in an actions slot
|
|
104
|
+
|
|
105
|
+
`npx bitakit add action print/list` creates `src/plugins/print/actions/list.ts` (ID `print.list`).
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
import { defineAction } from '@bitakit/core';
|
|
109
|
+
|
|
110
|
+
export default defineAction({
|
|
111
|
+
title: 'Print list',
|
|
112
|
+
slots: ['todos.toolbar'],
|
|
113
|
+
execute: () => window.print(),
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
- `slots` chooses placement; `groups` never does. List several targets to show the same Action
|
|
118
|
+
in several places, for example `['todos.toolbar', 'shell.toolbar']`.
|
|
119
|
+
- For a payload slot, map the payload to the Action input, for example for a `todos.row.menu`
|
|
120
|
+
slot with payload `{ todoId }`:
|
|
121
|
+
`slots: [{ slot: 'todos.row.menu', input: ({ payload }) => payload.todoId }]` (`order` and
|
|
122
|
+
`key` also fit here).
|
|
123
|
+
- The owner's outlet decides the look; the Action supplies title, icon, guards and behavior.
|
|
124
|
+
- `npm run typecheck` rejects slot names that are not declared actions slots.
|
|
125
|
+
|
|
126
|
+
## Shell slots
|
|
127
|
+
|
|
128
|
+
The Shell layout is the `shell.layout` setting (`sidebar` or `navbar`).
|
|
129
|
+
|
|
130
|
+
| Slot | Accepts | Where it renders |
|
|
131
|
+
| -------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- |
|
|
132
|
+
| `shell.navigation` | Actions, usually with `href` (`todos.open`) | Sidebar menu, or the top menu in `navbar` |
|
|
133
|
+
| `shell.toolbar` | Actions | Header, right side, both layouts |
|
|
134
|
+
| `app-bar.end` | component | Header, right side, before the toolbar, both layouts |
|
|
135
|
+
| `shell.header.end` | component | Header, right side, after the toolbar, both layouts |
|
|
136
|
+
| `shell.header.start`, `shell.header.center` | component | Header left / center, both layouts |
|
|
137
|
+
| `shell.content.before`, `shell.content.after` | component | Above / below every page, both layouts |
|
|
138
|
+
| `shell.footer` | component | Page footer, both layouts |
|
|
139
|
+
| `sidebar.header`, `sidebar.body`, `sidebar.footer` | component, payload `{ collapsed }` | `sidebar` layout only |
|
|
140
|
+
|
|
141
|
+
- Put header widgets in `shell.header.end` (the summary example). Use `shell.toolbar` for
|
|
142
|
+
header buttons, so they keep the Shell's standard Button.
|
|
143
|
+
- For content that must stay visible in both layouts, use a header or content slot; the
|
|
144
|
+
`sidebar.*` slots are not rendered in `navbar`.
|
|
145
|
+
- Further Shell slots (header rows, drawers, navigation groups, page states) are listed in the
|
|
146
|
+
`@bitakit/shell` README; they render only in layouts that mount them.
|
|
147
|
+
|
|
148
|
+
## When nothing renders
|
|
149
|
+
|
|
150
|
+
- Check that an outlet is mounted: the owner's component calls `<PluginSlot>` or `useSlot`, the
|
|
151
|
+
page is open, and the selected Shell layout renders that slot.
|
|
152
|
+
- Log `useSlot('todos.toolbar').diagnostics` in the outlet. `reason` is `ready`, `empty`,
|
|
153
|
+
`filtered`, `initializing`, `validating-payload`, `update-pending`, `owner-unavailable`,
|
|
154
|
+
`invalid-payload` or `binding-error`. `excluded` lists each skipped entry with its `id`,
|
|
155
|
+
`plugin` and `reason` (`key`, `condition`, `action-hidden` or `action-unavailable`).
|
|
156
|
+
- Run `npx bitakit doctor`: it warns when a `ui/slots` file targets a slot nobody declares.
|
|
157
|
+
- Use only declared names: `npx bitakit slots` lists them. When no outlet exists where the user
|
|
158
|
+
wants content, the owning plugin declares a slot and renders it.
|
|
159
|
+
|
|
160
|
+
## Explain it to the user
|
|
161
|
+
|
|
162
|
+
Name the owner and the contributor: "todos owns the `todos.toolbar` slot and shows it above the
|
|
163
|
+
list; the print plugin adds its 'Print list' Action there without changing todos." Say where it
|
|
164
|
+
appears (todos page, Shell header) and how to try it: open `/todos` and look for the new button
|
|
165
|
+
or widget. Removing the contributor's folder removes only its contribution.
|