@bitakit/cli 0.2.1 → 0.2.3

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.
@@ -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.