@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,198 @@
|
|
|
1
|
+
# Actions
|
|
2
|
+
|
|
3
|
+
Use this for a button, link, menu entry, shortcut or any operation a control runs. Define it once in
|
|
4
|
+
the owning plugin; every bound control gets label, disabled, pending, confirmation and messages from it.
|
|
5
|
+
|
|
6
|
+
## Add an Action
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
npx bitakit add action todos/sort
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- The file path is the ID, `<plugin>.<path>`: `actions/sort.ts` is `todos.sort`;
|
|
13
|
+
`npx bitakit add action todos/bulk/archive` writes `actions/bulk/archive.ts`, ID `todos.bulk.archive`.
|
|
14
|
+
The command never overwrites a file; to change the sample's `todos.clear`, edit `actions/clear.ts`.
|
|
15
|
+
App-wide Actions live in `src/actions/<name>.ts` (ID `<name>`); create those by hand.
|
|
16
|
+
- Each file default-exports one `defineAction({ ... })`; prefix helper files with `-`. Renaming the
|
|
17
|
+
file renames the ID; `npm run typecheck` flags stale IDs in `<Action>`, `useAction` and `slots`,
|
|
18
|
+
but search interceptor `action` targets and `<id>.*` catalog keys yourself.
|
|
19
|
+
- `title` is a literal or a translation key; a `<id>.title` catalog entry wins over a literal.
|
|
20
|
+
Without `title`, the last ID segment is used (`clear-done` shows "Clear done").
|
|
21
|
+
|
|
22
|
+
## Derive state from services and settings
|
|
23
|
+
|
|
24
|
+
`src/plugins/todos/actions/add.ts` (from the sample):
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { defineAction } from '@bitakit/core';
|
|
28
|
+
|
|
29
|
+
export default defineAction<string>({
|
|
30
|
+
title: 'Add',
|
|
31
|
+
// Bound buttons stay disabled while the input is empty or the list is full.
|
|
32
|
+
enabled: ({ input, services, settings }) =>
|
|
33
|
+
!!input?.trim() && services.todos.list.state.get().todos.length < settings.todos.limit.get(),
|
|
34
|
+
execute: ({ services, input }) => services.todos.list.add(input),
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `title`, `description`, `tooltip`, `variant`, `href`, `enabled`, `visible`, `checked` and `value`
|
|
39
|
+
take a value or a function of `{ input, services, config, settings, app }`. Functions re-run when
|
|
40
|
+
a store or setting they read changes; `input` there is raw and may be `undefined` (menus, search).
|
|
41
|
+
- `enabled: false` disables bound controls and `visible: false` renders nothing; both block
|
|
42
|
+
execution. They are UI rules, not server authorization.
|
|
43
|
+
- `input: z.string().trim().min(1)` (any Standard Schema or object with `parse`) replaces
|
|
44
|
+
`defineAction<string>`: it infers the type and `execute` gets the parsed value. zod is not in the
|
|
45
|
+
generated `package.json`; ask the user before adding it. A schema disables controls while the
|
|
46
|
+
input is invalid only when `enabled` is not set.
|
|
47
|
+
|
|
48
|
+
## Run, confirm and report
|
|
49
|
+
|
|
50
|
+
`src/plugins/todos/actions/clear.ts`:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
import { defineAction } from '@bitakit/core';
|
|
54
|
+
|
|
55
|
+
export default defineAction({
|
|
56
|
+
title: 'Clear all',
|
|
57
|
+
enabled: ({ services }) => services.todos.list.state.get().todos.length > 0,
|
|
58
|
+
confirm: {
|
|
59
|
+
title: 'Delete every todo?',
|
|
60
|
+
description: 'This cannot be undone.',
|
|
61
|
+
destructive: true,
|
|
62
|
+
},
|
|
63
|
+
execute: ({ services }) => services.todos.list.clear(),
|
|
64
|
+
success: 'All todos deleted',
|
|
65
|
+
});
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- `variant: 'destructive'` on an Action styles menu items only; give a bound `<Button>` its own
|
|
69
|
+
`variant` prop.
|
|
70
|
+
- `execute` gets `{ input, services, config, settings, app, events, signal, id, get, update }`. Its
|
|
71
|
+
return value becomes `{ status: 'completed', value }`; a throw makes the run fail.
|
|
72
|
+
- `confirm`: a string (title only), `{ title, description, destructive? }`, or a function returning
|
|
73
|
+
one of those or `false` to skip the question. Declining skips the run with reason `cancelled`.
|
|
74
|
+
- `success` / `failure`: a string (tried as a translation key first), `{ messageKey, values }`,
|
|
75
|
+
`false`, or a function of `{ result | error, input, services }`. Success is silent by default.
|
|
76
|
+
- `concurrency`: `'exclusive'` (default; skips a second run while one is pending), `'per-input'`
|
|
77
|
+
(pending per input, as `todos.remove` does for rows) or `'latest'` (aborts the previous `signal`).
|
|
78
|
+
|
|
79
|
+
## Use another plugin's service and place the Action
|
|
80
|
+
|
|
81
|
+
`npx bitakit add action print/list` creates `src/plugins/print/actions/list.ts` (ID `print.list`):
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { defineAction } from '@bitakit/core';
|
|
85
|
+
|
|
86
|
+
export default defineAction({
|
|
87
|
+
title: 'Print list',
|
|
88
|
+
slots: ['todos.toolbar'],
|
|
89
|
+
// todos.list belongs to another plugin; listing it turns a missing service into a startup error.
|
|
90
|
+
requires: ['todos.list'],
|
|
91
|
+
enabled: ({ services }) => services.todos.list.state.get().todos.length > 0,
|
|
92
|
+
execute: () => window.print(),
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
- `requires` lists services of other plugins only; the plugin's own services need no entry.
|
|
97
|
+
- `slots` places the Action in a declared actions slot ([slots.md](slots.md) declares and renders
|
|
98
|
+
`todos.toolbar`); `groups` is logical membership and never places UI.
|
|
99
|
+
- `shortcut: { keys: 'Mod+Shift+P' }` adds a keyboard shortcut with the same guards as a click. To
|
|
100
|
+
block or check another plugin's Action, use an interceptor ([interceptors.md](interceptors.md)).
|
|
101
|
+
- `href` makes a navigation Action, like the sample's `todos/actions/open.ts`:
|
|
102
|
+
`defineAction({ title: 'Todos', href: '/todos', slots: ['shell.navigation'] })`. The page is its
|
|
103
|
+
own file ([plugins-and-pages.md](plugins-and-pages.md)).
|
|
104
|
+
- `dialog: { component, size? }` opens a `ui/dialogs/` component (`npx bitakit add dialog
|
|
105
|
+
<plugin>/<name>`) instead of running `execute`; defining both throws.
|
|
106
|
+
|
|
107
|
+
## Bind controls
|
|
108
|
+
|
|
109
|
+
`src/plugins/todos/ui/todos-controls.tsx` (render `<TodosControls />` from `ui/pages/index.tsx`):
|
|
110
|
+
|
|
111
|
+
```tsx
|
|
112
|
+
'use client';
|
|
113
|
+
import { useState } from 'react';
|
|
114
|
+
import { Action, ActionButton, ActionLink } from '@bitakit/ui';
|
|
115
|
+
import { Button, Input } from '@bitakit/ui/components';
|
|
116
|
+
|
|
117
|
+
export function TodosControls() {
|
|
118
|
+
const [title, setTitle] = useState('');
|
|
119
|
+
return (
|
|
120
|
+
<div className="flex gap-2">
|
|
121
|
+
<Input
|
|
122
|
+
value={title}
|
|
123
|
+
aria-label="New todo"
|
|
124
|
+
onChange={(event) => setTitle(event.target.value)}
|
|
125
|
+
/>
|
|
126
|
+
{/* An empty child receives the Action's title. Keep the draft when the run was skipped. */}
|
|
127
|
+
<Action
|
|
128
|
+
id="todos.add"
|
|
129
|
+
input={title}
|
|
130
|
+
onExecuted={(result) => result.status === 'completed' && setTitle('')}
|
|
131
|
+
>
|
|
132
|
+
<Button />
|
|
133
|
+
</Action>
|
|
134
|
+
<ActionButton action="todos.clear" as={Button} variant="outline" />
|
|
135
|
+
<ActionLink action="todos.open" />
|
|
136
|
+
</div>
|
|
137
|
+
);
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- `<Action id input onExecuted onError kind pending>` merges `onClick`, `disabled` and `aria-busy`
|
|
142
|
+
into its one child; leave those to the Action. `onExecuted` also fires for `{ status: 'skipped' }`
|
|
143
|
+
(declined confirm, interceptor).
|
|
144
|
+
- `ActionButton` and `ActionLink` take `action` (not `id`, which stays the HTML attribute) and `as`.
|
|
145
|
+
- An `href` Action renders as a real link (a plain `<a>` child becomes the router link). A hidden
|
|
146
|
+
or unregistered Action renders nothing; a misspelled ID fails `npm run typecheck`.
|
|
147
|
+
|
|
148
|
+
## Build a custom control with useAction
|
|
149
|
+
|
|
150
|
+
`src/plugins/todos/ui/clear-button.tsx`:
|
|
151
|
+
|
|
152
|
+
```tsx
|
|
153
|
+
'use client';
|
|
154
|
+
import { useAction } from '@bitakit/ui';
|
|
155
|
+
import { Button } from '@bitakit/ui/components';
|
|
156
|
+
|
|
157
|
+
export function ClearButton() {
|
|
158
|
+
const clear = useAction('todos.clear');
|
|
159
|
+
if (!clear?.visible) return null;
|
|
160
|
+
return (
|
|
161
|
+
<Button variant="outline" {...clear.props()}>
|
|
162
|
+
{clear.pending ? 'Clearing…' : clear.title}
|
|
163
|
+
</Button>
|
|
164
|
+
);
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
- `useAction(id, input?)` is `undefined` until the Action is registered; then it holds the state
|
|
169
|
+
(`title`, `enabled`, `visible`, `pending`, `disabled`, `status`, `error`, ...), the getters `props()`,
|
|
170
|
+
`linkProps()`, `checkedProps()`, `valueProps()`, `menuItemProps()`, and `execute(input?)`, which
|
|
171
|
+
resolves to the outcome and rejects on failure (the getters report errors for you).
|
|
172
|
+
|
|
173
|
+
## Keep several Actions in one file
|
|
174
|
+
|
|
175
|
+
`src/plugins/print/actions.ts` can hold `print.list` (same ID) instead of `actions/list.ts`:
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
import { defineAction } from '@bitakit/core';
|
|
179
|
+
|
|
180
|
+
export default {
|
|
181
|
+
list: defineAction({
|
|
182
|
+
title: 'Print list',
|
|
183
|
+
slots: ['todos.toolbar'],
|
|
184
|
+
execute: () => window.print(),
|
|
185
|
+
}),
|
|
186
|
+
};
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
- Each key becomes `<plugin>.<key>`, so splitting into `actions/<key>.ts` later keeps the IDs; one
|
|
190
|
+
ID in both forms fails at startup as a duplicate.
|
|
191
|
+
- A bare `export default defineAction(...)` in `actions.ts` fails at app start ("Collection needs
|
|
192
|
+
named entries"); typecheck and doctor do not catch it.
|
|
193
|
+
|
|
194
|
+
## Explain it to the user
|
|
195
|
+
|
|
196
|
+
Name the owning plugin and ID (`todos.clear` in `src/plugins/todos/actions/clear.ts`), the service it
|
|
197
|
+
calls and where it appears (the todos page, `shell.navigation` or the `todos.toolbar` slot). Tell them
|
|
198
|
+
how to try it: open `/todos`, add a todo, use the button, and expect any confirmation or disabled rule.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Interceptors
|
|
2
|
+
|
|
3
|
+
Use an interceptor to block an Action run at the last moment, to observe Action runs across
|
|
4
|
+
plugins, or to watch calls to a service method, without editing the Action or service itself.
|
|
5
|
+
|
|
6
|
+
## Block an Action run
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npx bitakit add interceptor todos/no-duplicates
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The command writes `src/plugins/todos/interceptors/no-duplicates.ts` with a logging template that
|
|
13
|
+
observes `todos.*`. Replace its body:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { defineInterceptor } from '@bitakit/core';
|
|
17
|
+
|
|
18
|
+
export default defineInterceptor({
|
|
19
|
+
action: 'todos.add',
|
|
20
|
+
before: ({ input, services }) => {
|
|
21
|
+
const title = String(input ?? '')
|
|
22
|
+
.trim()
|
|
23
|
+
.toLowerCase();
|
|
24
|
+
// Returning false skips the run; any other value lets it continue.
|
|
25
|
+
return !services.todos.list.state
|
|
26
|
+
.get()
|
|
27
|
+
.todos.some((todo) => todo.title.toLowerCase() === title);
|
|
28
|
+
},
|
|
29
|
+
});
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- When `before` returns `false`, the caller receives `{ status: 'skipped', reason: 'intercepted' }`.
|
|
33
|
+
The run shows no toast, throws no error and changes no Action state. A returned promise is
|
|
34
|
+
awaited, and the control shows pending while it waits.
|
|
35
|
+
- `<Action onExecuted>` also fires for skipped runs. To keep the typed title after a blocked add,
|
|
36
|
+
check the status in the sample page:
|
|
37
|
+
`onExecuted={(result) => { if (result.status === 'completed') setTitle(''); }}`.
|
|
38
|
+
- Hook context: `id`, the raw `input` (typed `unknown`, so narrow it), `signal`, `get`, `update`,
|
|
39
|
+
`services`, `config`, `app` and `translate`. Read settings with
|
|
40
|
+
`app.settings.todos.limit.get()`. `app.events` only has `on`. The `settings` and `events`
|
|
41
|
+
shortcuts of an Action's `execute` are not available here.
|
|
42
|
+
- `before` runs only for a visible, enabled Action. If it throws, the run fails and `onError`
|
|
43
|
+
receives the error, so return `false` to block a run quietly.
|
|
44
|
+
- This is a client execution rule. Keep server authorization on the server.
|
|
45
|
+
|
|
46
|
+
## Watch Actions of another plugin
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npx bitakit add interceptor activity/todo-errors
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`src/plugins/activity/interceptors/todo-errors.ts`:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
import { defineInterceptor } from '@bitakit/core';
|
|
56
|
+
|
|
57
|
+
export default defineInterceptor({
|
|
58
|
+
action: 'todos.*',
|
|
59
|
+
// Without this, an interceptor only sees the Actions of its own plugin (activity).
|
|
60
|
+
scope: 'global',
|
|
61
|
+
after: ({ id, input }) => console.info('[activity] done', id, input),
|
|
62
|
+
onError: ({ id, error }) => console.error('[activity] failed', id, error),
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- `scope: 'plugin'` is the default for plugin interceptors and matches only Actions that the
|
|
67
|
+
same plugin registered, even when `action` names another plugin's ID. Set `scope: 'global'` to
|
|
68
|
+
reach other plugins.
|
|
69
|
+
- `action` takes one ID, a list of IDs, an ID prefix such as `'todos.*'`, or `'*'`. Omit it to
|
|
70
|
+
match every Action of the same plugin. Patterns match Action IDs, not `groups`.
|
|
71
|
+
- `after` receives `result`, the value returned by `execute`, for completed runs. `onError`
|
|
72
|
+
receives `error` for failed runs. Skipped runs reach neither hook. The return values and
|
|
73
|
+
promises of these hooks never change the outcome, and their own errors are only logged.
|
|
74
|
+
- `order` (default `0`) sorts all Action interceptors, lowest first. The first `before` that
|
|
75
|
+
returns `false` stops the remaining interceptors.
|
|
76
|
+
- `requires: ['todos.list']` makes startup fail with a clear message when that service is
|
|
77
|
+
missing. `npx bitakit doctor` checks these names.
|
|
78
|
+
|
|
79
|
+
## Add an app-wide interceptor
|
|
80
|
+
|
|
81
|
+
`bitakit add` has no app-level target. To add one, create `src/interceptors/action-log.ts`:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { defineInterceptor } from '@bitakit/core';
|
|
85
|
+
|
|
86
|
+
export default defineInterceptor({
|
|
87
|
+
action: '*',
|
|
88
|
+
after: ({ id }) => console.info('[action-log]', id),
|
|
89
|
+
});
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
- Files in `src/interceptors/` are global by default. Set `scope: 'plugin'` to limit one of them
|
|
93
|
+
to the app's own `src/actions`.
|
|
94
|
+
- All app interceptors are active by default. To select some of them, list their file names in
|
|
95
|
+
`bitakit.config.ts` next to `package.json` (create it if the app has none):
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
import { defineBitaKit } from '@bitakit/discovery';
|
|
99
|
+
|
|
100
|
+
export default defineBitaKit({
|
|
101
|
+
interceptors: { enabled: ['action-log'] },
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
A name without a matching file stops `bitakit generate`. This list never affects plugin
|
|
106
|
+
interceptors.
|
|
107
|
+
|
|
108
|
+
- Put rules that belong to one feature in that feature's plugin folder so the rule is removed
|
|
109
|
+
together with the plugin.
|
|
110
|
+
|
|
111
|
+
## Observe a service method
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
npx bitakit add interceptor todos/trace-list
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Replace the template in `src/plugins/todos/interceptors/trace-list.ts`:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import { defineInterceptor } from '@bitakit/core';
|
|
121
|
+
|
|
122
|
+
export default [
|
|
123
|
+
defineInterceptor({
|
|
124
|
+
service: 'todos.list',
|
|
125
|
+
method: 'add',
|
|
126
|
+
after: ({ args }) => console.info('[todos] added', args[0]),
|
|
127
|
+
}),
|
|
128
|
+
defineInterceptor({
|
|
129
|
+
service: 'todos.list',
|
|
130
|
+
method: 'clear',
|
|
131
|
+
before: () => console.info('[todos] clearing'),
|
|
132
|
+
}),
|
|
133
|
+
];
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
- Service hooks only observe. They receive `service`, `method` and `args`, plus the awaited
|
|
137
|
+
`result` or the `error`, and cannot block a call or change it. Leave `args` and `result`
|
|
138
|
+
unchanged.
|
|
139
|
+
- They see every call made through the service container, from Actions, pages and other
|
|
140
|
+
services. They do not see a service calling its own methods internally.
|
|
141
|
+
- Each definition targets either `action` or `service`. Setting both throws. To cover several
|
|
142
|
+
targets, default-export an array as above.
|
|
143
|
+
- Omit `method` to observe every public method. `service: 'todos.*'` matches a name prefix.
|
|
144
|
+
Hooks run synchronously, and their promises are ignored.
|
|
145
|
+
|
|
146
|
+
## Choose an interceptor, `enabled`, `execute` or an event
|
|
147
|
+
|
|
148
|
+
- For a rule the user should see before clicking, such as a disabled button, use the owner's
|
|
149
|
+
Action `enabled`. The sample `todos.add` already checks `todos.limit` there.
|
|
150
|
+
- For a rule that is part of the operation itself, put it in `execute` or in the service method.
|
|
151
|
+
- Use an interceptor for a rule over Actions you do not own, a rule shared by many Actions, or a
|
|
152
|
+
check that must run asynchronously at execution time.
|
|
153
|
+
- To react to a change, listen to the owner's event, as `activity` does with `todos.changed`.
|
|
154
|
+
Use an interceptor's `after` only when the owner emits no event.
|
|
155
|
+
|
|
156
|
+
## Explain it to the user
|
|
157
|
+
|
|
158
|
+
- Say which plugin owns the interceptor (for example "todos, in
|
|
159
|
+
`src/plugins/todos/interceptors/no-duplicates.ts`") and which Action ID or service it targets.
|
|
160
|
+
If it uses `scope: 'global'`, say that it reaches Actions of other plugins.
|
|
161
|
+
- Say what the user will notice. A blocked run does nothing visible: the todo is not added and
|
|
162
|
+
no message appears. Observers only write to the browser console.
|
|
163
|
+
- To try it, open `/todos`, add "Milk" twice and see that only one appears. For an observer, open
|
|
164
|
+
the browser console and add or clear a todo.
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Plugins and pages
|
|
2
|
+
|
|
3
|
+
Use this when the user asks for a new feature, a new screen or a sidebar entry. The example is
|
|
4
|
+
`about`: a page-only plugin at `/about` with a link in the Shell sidebar.
|
|
5
|
+
|
|
6
|
+
## Create a plugin
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
npx bitakit add plugin about
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- Default: `ui/pages/index.tsx` (served at `/about`) and, only when `@bitakit/shell` is in
|
|
13
|
+
`package.json`, `actions/open.ts`, which places the link in `shell.navigation`. Without Shell
|
|
14
|
+
the page is reached by URL only.
|
|
15
|
+
- `--example` writes a complete feature: `services/list.ts`, `events.ts`, the Actions `add`,
|
|
16
|
+
`remove`, `clear` and `open`, and a list page. `--minimal` writes only `services/list.ts`,
|
|
17
|
+
`events.ts` and `actions/add.ts`: no page and no link.
|
|
18
|
+
- The templates are a starting point. Replace their bodies, placeholder subtitles ("Edit this
|
|
19
|
+
page in ...") and tutorial comments with the real feature, and delete files it does not need.
|
|
20
|
+
- Names start with a lowercase letter and use lowercase letters, digits and single hyphens
|
|
21
|
+
(`about`, `release-notes`). Choose a name the app does not already own: the CLI refuses
|
|
22
|
+
`settings`, `api`, `login` and `register` because those are app routes (`--minimal` skips this
|
|
23
|
+
check), and `app` is the app's own plugin ID, so `bitakit generate` rejects it as a duplicate.
|
|
24
|
+
`npx bitakit info` lists the existing plugin IDs.
|
|
25
|
+
- The CLI never overwrites. It stops when the folder or file already exists.
|
|
26
|
+
|
|
27
|
+
## Folder = feature, file path = ID
|
|
28
|
+
|
|
29
|
+
Everything for one feature lives in `src/plugins/<name>/`. Discovery derives IDs and URLs from
|
|
30
|
+
file paths, so there is nothing to register.
|
|
31
|
+
|
|
32
|
+
| File in `src/plugins/...` | Becomes |
|
|
33
|
+
| --------------------------------------------- | ------------------------------- |
|
|
34
|
+
| `about/actions/open.ts` | Action `about.open` |
|
|
35
|
+
| `todos/services/list.ts` | Service `todos.list` |
|
|
36
|
+
| `about/ui/pages/index.tsx` | Page `/about` |
|
|
37
|
+
| `about/ui/pages/team.tsx` or `team/index.tsx` | Page `/about/team` |
|
|
38
|
+
| `todos/ui/pages/[id].tsx` | Page `/todos/<id>`, `params.id` |
|
|
39
|
+
|
|
40
|
+
- Dots and folders mean the same: `ui/pages/team.history.tsx` equals `ui/pages/team/history.tsx`.
|
|
41
|
+
- Every file with a default export under `ui/pages/` becomes a page (a `-` name prefix excludes
|
|
42
|
+
a file). Put shared components in `ui/components/`, which discovery treats as ordinary imports.
|
|
43
|
+
- Renaming a file changes its ID or URL. Update the `href`s and `<Action id>`s that use it.
|
|
44
|
+
|
|
45
|
+
## Add a page
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
npx bitakit add page about/team
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
This writes `src/plugins/about/ui/pages/team.tsx` for `/about/team`; nested names such as
|
|
52
|
+
`about/team/history` work too. The plugin's root page is `ui/pages/index.tsx`:
|
|
53
|
+
|
|
54
|
+
```tsx
|
|
55
|
+
'use client';
|
|
56
|
+
import { PageHeader } from '@bitakit/ui/components';
|
|
57
|
+
|
|
58
|
+
export default function AboutPage() {
|
|
59
|
+
return (
|
|
60
|
+
<div className="flex flex-col gap-6">
|
|
61
|
+
<PageHeader title="About" subtitle="What this app is for and who builds it." />
|
|
62
|
+
<p className="text-sm text-muted-foreground">This app keeps a short list of things to do.</p>
|
|
63
|
+
</div>
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- Start every file under `ui/` with `'use client'`. The page is the default export.
|
|
69
|
+
- `PageHeader` renders the page's heading: `title`, optional `subtitle`, and `trailing` for
|
|
70
|
+
page-level buttons. Build the rest from `@bitakit/ui/components` (`Button`, `Input`, `Badge`,
|
|
71
|
+
`Separator`, ...) and theme classes such as `text-muted-foreground`; layout with flex and gap.
|
|
72
|
+
- Bind each button that runs an operation to its Action (`<Action id="todos.add"><Button /></Action>`)
|
|
73
|
+
and read service state with `useServiceState`, as `todos/ui/pages/index.tsx` does.
|
|
74
|
+
|
|
75
|
+
## Read a URL parameter
|
|
76
|
+
|
|
77
|
+
`bitakit add page` accepts plain names only, so create a parameter page by hand:
|
|
78
|
+
`src/plugins/todos/ui/pages/[id].tsx`.
|
|
79
|
+
|
|
80
|
+
```tsx
|
|
81
|
+
'use client';
|
|
82
|
+
import { useServiceState } from '@bitakit/ui';
|
|
83
|
+
import { PageHeader } from '@bitakit/ui/components';
|
|
84
|
+
|
|
85
|
+
// Served at /todos/<id>; URL parameters are always strings, so convert before comparing.
|
|
86
|
+
export default function TodoPage({ params }: { params: { id: string } }) {
|
|
87
|
+
const todo = useServiceState('todos.list', (state) =>
|
|
88
|
+
state.todos.find((candidate) => candidate.id === Number(params.id)),
|
|
89
|
+
);
|
|
90
|
+
return <PageHeader title={todo?.title ?? 'Todo not found'} subtitle={`Todo ${params.id}`} />;
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- `PluginPage` passes the decoded segments as the `params` prop. Each `[name]` matches exactly
|
|
95
|
+
one segment; catch-all and optional segments are not supported in plugin pages.
|
|
96
|
+
- An exact page wins over a parameter page: `ui/pages/new.tsx` serves `/todos/new` before `[id]`.
|
|
97
|
+
- Render a "not found" state yourself when the parameter matches nothing.
|
|
98
|
+
|
|
99
|
+
## Choose a layout
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
npx bitakit add layout full-page
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Replace the template in `src/layouts/full-page.tsx` with `import { AppShell } from '@bitakit/shell';`
|
|
106
|
+
and `export default AppShell.FullPage;`. A page opts in with one export:
|
|
107
|
+
|
|
108
|
+
```tsx
|
|
109
|
+
'use client';
|
|
110
|
+
import { PageHeader } from '@bitakit/ui/components';
|
|
111
|
+
|
|
112
|
+
// The name of src/layouts/full-page.tsx: this page renders without the sidebar and header.
|
|
113
|
+
export const layout = 'full-page';
|
|
114
|
+
|
|
115
|
+
export default function AboutTeamPage() {
|
|
116
|
+
return <PageHeader title="Team" subtitle="The people behind this app." />;
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- Values: no export or `'app'` for the normal frame, `'blank'` for a bare page, or the file name
|
|
121
|
+
of a layout in `src/layouts/<name>.tsx`. An unknown name stops startup with an error that names the
|
|
122
|
+
missing `src/layouts/<name>.tsx` and the valid choices.
|
|
123
|
+
- Shell's `AppShell` applies the choice. In an app without Shell, read its layout before relying
|
|
124
|
+
on `export const layout`.
|
|
125
|
+
- `AppShell.FullPage` keeps Shell's page spacing and the `shell.content.before/after` regions;
|
|
126
|
+
`'blank'` keeps nothing.
|
|
127
|
+
|
|
128
|
+
## Link the page in the sidebar
|
|
129
|
+
|
|
130
|
+
`src/plugins/about/actions/open.ts`:
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
import { defineAction } from '@bitakit/core';
|
|
134
|
+
|
|
135
|
+
export default defineAction({
|
|
136
|
+
title: 'About',
|
|
137
|
+
href: '/about',
|
|
138
|
+
groups: ['navigation'],
|
|
139
|
+
slots: ['shell.navigation'],
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
- `slots: ['shell.navigation']` places the link; `groups` is only a logical query. Shell renders
|
|
144
|
+
an Action with `href` as a native link, labelled by `title`.
|
|
145
|
+
- `src/configs/shell.ts` names the navigation slot (`navigationSlot: 'shell.navigation'`). Other
|
|
146
|
+
placements, such as `shell.toolbar` or a plugin's own Action slot, are in [slots.md](slots.md).
|
|
147
|
+
- `npx bitakit doctor` warns when a link's `href` has no page or app route.
|
|
148
|
+
|
|
149
|
+
## Plugin pages and app routes
|
|
150
|
+
|
|
151
|
+
- The catch-all route `src/app/(app)/[...path]/page.tsx` renders `<PluginPage>` inside
|
|
152
|
+
`AppShell`. Plugin pages render in the browser once the BitaKit runtime is ready; the server
|
|
153
|
+
sends no page content for them.
|
|
154
|
+
- Keep pages that need server rendering, Next.js `metadata`, server-side redirects or API route
|
|
155
|
+
handlers as native routes in `src/app` (for example `src/app/(app)/pricing/page.tsx`).
|
|
156
|
+
- An app route at the same path wins over a plugin page; doctor reports it as an error.
|
|
157
|
+
- Check with `npm run typecheck` (it runs `bitakit generate`) and `npx bitakit doctor`, which
|
|
158
|
+
confirms that every plugin page can be reached and every navigation link has a page.
|
|
159
|
+
|
|
160
|
+
## Explain it to the user
|
|
161
|
+
|
|
162
|
+
Say which plugin owns the page (`src/plugins/about`), that its URL comes from the file
|
|
163
|
+
`ui/pages/index.tsx` (`/about`), and that the sidebar entry is the Action `about.open` placed in
|
|
164
|
+
Shell's `shell.navigation` slot. To try it: start the dev server, click "About" in the navigation (the
|
|
165
|
+
sidebar, or the top bar in Shell's navbar layout) or open `/about`.
|