@dokebi/module 0.4.2 → 0.4.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.
@@ -1,305 +0,0 @@
1
- import type { OptionsDeclaration, SettingsDefinition } from '@dokebi/core';
2
- import { type ModuleAction } from './action.js';
3
- import { type DataField, type ModuleDataSource } from './data-source.js';
4
- import { type ModulePart } from './parts.js';
5
- import { type PresetKind } from './preset.js';
6
- export type { ModuleAction } from './action.js';
7
- export type { ModuleDataSource } from './data-source.js';
8
- /** A label: one text, or a text per locale (`{ en: 'Members', ko: '…' }`). */
9
- export type ModuleText = string | Readonly<Record<string, string>>;
10
- /** A permission key the module checks (`<module>.<action>`, as `members.read`). */
11
- export interface ModulePermission {
12
- readonly title: ModuleText;
13
- readonly description?: ModuleText;
14
- }
15
- /** A widget (a screen piece): an editor places it and fills its settings. */
16
- export interface ModuleWidget {
17
- readonly title: ModuleText;
18
- readonly description?: ModuleText;
19
- /** The settings a placed widget takes (`defineOptions`); the editor draws its fields from it. */
20
- readonly settings?: OptionsDeclaration<unknown>;
21
- /** The first HTML of the widget: a `.html` file of the module (`new URL(…, import.meta.url)`). */
22
- readonly template: URL;
23
- /**
24
- * The data the template draws (D-0198): called on the server for every placed widget with its
25
- * checked settings, the request and the module's context; what it returns joins the settings in
26
- * the template's scope (`{{ name }}`, `x-for`). JSON values only. Never shown by describe.
27
- */
28
- readonly load?: (input: ModuleWidgetLoadInput) => unknown;
29
- /**
30
- * A Vue component that runs the widget in the browser (D-0200, an island): the file URL of
31
- * `islands/<Name>.vue` of the module (`new URL('./islands/DataGrid.vue', import.meta.url)`).
32
- * @dokebi/pages draws the template on the server first, then the page mounts the component in
33
- * its place with `{ settings, data }` (the settings and what `load` returned) as props.
34
- */
35
- readonly island?: URL;
36
- }
37
- /**
38
- * A preset (dokebi-platform DEC-12, DEC-16): a folder shaped like an app's definition folder that an
39
- * editor copies into a new app of that kind. Its app.yaml holds only layout, modules and menu.
40
- */
41
- export interface ModulePreset {
42
- readonly title: ModuleText;
43
- /** The app kind it is for: admin or front. */
44
- readonly kind: PresetKind;
45
- /** The folder (`new URL('./presets/admin-basic/', import.meta.url)`), ending in `/`. */
46
- readonly folder: URL;
47
- }
48
- /** What a widget's `load` receives (D-0198). */
49
- export interface ModuleWidgetLoadInput {
50
- /** The settings of this placed widget, checked by the widget's `settings` declaration. */
51
- readonly settings: Readonly<Record<string, unknown>>;
52
- /** The request being answered (a Fastify request). */
53
- readonly request: unknown;
54
- /** The module's context (`ModuleContext` of @dokebi/module), once the module has set up. */
55
- readonly module: unknown;
56
- /**
57
- * The module group (`ModuleGroupApi` of @dokebi/module, D-0200): other modules' contracts
58
- * (`module(name)`) and the general read of their data sources (`data.read`). A widget that shows
59
- * another module's data reads it here, with the visitor's request, never around its permission.
60
- */
61
- readonly modules?: unknown;
62
- /**
63
- * The app that draws the widget (@dokebi/pages, D-0198): its title and the menu of app.yaml for
64
- * this visitor (`{ title, path, icon?, children }`, items without the permission left out). A
65
- * sidebar widget draws it. Absent when the widget is drawn outside a site.
66
- */
67
- readonly app?: {
68
- readonly title: string;
69
- readonly menu: readonly ModuleMenuEntry[];
70
- };
71
- /**
72
- * The page form the widget draws when it is the app's form widget (@dokebi/pages, D-0204):
73
- * `<x-form>`'s class (the fields' layout) and, in order, its `<x-field>` children (their
74
- * attributes in camelCase with `name` and `class`) and the HTML drawn between them. The x-form's
75
- * own attributes are the settings. Absent for every other widget.
76
- */
77
- readonly form?: {
78
- readonly class: string;
79
- readonly items: readonly ({
80
- readonly field: Readonly<Record<string, string | true | number>> & {
81
- readonly name: string;
82
- readonly class: string;
83
- };
84
- } | {
85
- readonly html: string;
86
- })[];
87
- };
88
- }
89
- /** One entry of an app's menu as a widget gets it (`ModuleWidgetLoadInput.app`). */
90
- export interface ModuleMenuEntry {
91
- readonly title: string;
92
- readonly path: string;
93
- readonly icon?: string;
94
- readonly children: readonly ModuleMenuEntry[];
95
- }
96
- /** A menu item the module proposes; the app that mounts the module decides where it goes. */
97
- export interface ModuleMenuItem {
98
- /** Unique in the module. */
99
- readonly id: string;
100
- readonly title: ModuleText;
101
- /** Below the mount prefix of the app: `''` is the module's root, `/new` a page under it. */
102
- readonly path: string;
103
- readonly icon?: string;
104
- /** The permission key that shows the item (a key of this module or `<other module>.<action>`). */
105
- readonly permission?: string;
106
- /** The id of another item of this module to nest under. */
107
- readonly parent?: string;
108
- /** Sort order among siblings, small first (-1000 to 1000, default 0). */
109
- readonly order?: number;
110
- }
111
- /** The contract fields of `defineModule` (all optional). */
112
- export interface ModuleContractFields {
113
- readonly title?: ModuleText;
114
- readonly description?: ModuleText;
115
- /** Other modules this one needs, by name, with an npm-style version range (`{ auth: '^0.1.0' }`). */
116
- readonly modules?: Readonly<Record<string, string>>;
117
- /**
118
- * The module's database folder with `migrations/<connection>/` and `seeds/<connection>/`
119
- * (`new URL('./db/', import.meta.url)`). dokebi-migrate reads `src/shared/modules/*\/db` with
120
- * the project's own folder (its `directories` option).
121
- */
122
- readonly db?: URL;
123
- /** The tables (or collections) the module owns. */
124
- readonly tables?: readonly string[];
125
- readonly permissions?: Readonly<Record<string, ModulePermission>>;
126
- readonly dataSources?: Readonly<Record<string, ModuleDataSource>>;
127
- /** The writes the module offers (D-0202): input fields, permission, the run. */
128
- readonly actions?: Readonly<Record<string, ModuleAction>>;
129
- readonly widgets?: Readonly<Record<string, ModuleWidget>>;
130
- readonly menu?: readonly ModuleMenuItem[];
131
- /** The module's settings in dokebi.yaml (`defineSettings` of @dokebi/core); checked at start. */
132
- readonly settings?: SettingsDefinition<unknown>;
133
- /** The module's translations, `locales/<language>/<namespace>.json` (read by @dokebi/i18n). */
134
- readonly locales?: URL;
135
- /**
136
- * The UI parts the module offers (D-0203): a `.json` file of the module
137
- * (`new URL('./parts.json', import.meta.url)`), `{ parts: [...] }` as parts.ts checks it —
138
- * components, directives, CSS classes and widgets with their props, slots, events, examples and
139
- * sample address. describe gives it as `parts`; an editor's MCP tools list and fetch parts there.
140
- */
141
- readonly parts?: URL;
142
- /**
143
- * The presets the module offers (dokebi-platform DEC-16): `{ <name>: { title, kind, folder } }`.
144
- * The folder is checked when the module sets up (preset.ts) and described with its files.
145
- */
146
- readonly presets?: Readonly<Record<string, ModulePreset>>;
147
- }
148
- export declare const CONTRACT_KEYS: readonly (keyof ModuleContractFields)[];
149
- /** The checked contract, frozen. */
150
- export interface ModuleContract {
151
- readonly title: ModuleText | undefined;
152
- readonly description: ModuleText | undefined;
153
- readonly modules: Readonly<Record<string, string>>;
154
- readonly db: URL | undefined;
155
- readonly tables: readonly string[];
156
- readonly permissions: Readonly<Record<string, ModulePermission>>;
157
- readonly dataSources: Readonly<Record<string, ModuleDataSource>>;
158
- readonly actions: Readonly<Record<string, ModuleAction>>;
159
- readonly widgets: Readonly<Record<string, ModuleWidget>>;
160
- readonly menu: readonly ModuleMenuItem[];
161
- readonly settings: SettingsDefinition<unknown> | undefined;
162
- readonly locales: URL | undefined;
163
- readonly parts: URL | undefined;
164
- readonly presets: Readonly<Record<string, ModulePreset>>;
165
- }
166
- /** Limits of one contract (D-0197). */
167
- export declare const CONTRACT_LIMITS: Readonly<{
168
- modules: 64;
169
- tables: 64;
170
- permissions: 256;
171
- dataSources: 64;
172
- actions: 64;
173
- widgets: 64;
174
- menu: 64;
175
- presets: 16;
176
- textChars: 200;
177
- locales: 32;
178
- /** Bytes of one widget template file. */
179
- templateBytes: 65536;
180
- /** Files listed per folder when the module is described. */
181
- describedFiles: 1000;
182
- }>;
183
- /** The island name the page registry and @dokebi/pages use: `<module>/<Name>`. */
184
- export declare const islandName: (module: string, island: URL) => string;
185
- /** Thrown for a contract that breaks a rule; index.ts turns it into INVALID_CONTRACT. */
186
- export declare class ContractIssue extends Error {
187
- }
188
- /** Checks the contract fields of a module definition (names only in messages, never values). */
189
- export declare function readContract(module: string, input: ModuleContractFields): ModuleContract;
190
- /** Checks the folder of every preset (preset.ts) and gives its files, by preset name. */
191
- export declare function readPresets(module: string, presets: Readonly<Record<string, ModulePreset>>): Promise<Record<string, readonly string[]>>;
192
- /** The first HTML of a widget: a UTF-8 file of at most CONTRACT_LIMITS.templateBytes. */
193
- export declare function readTemplate(template: URL): Promise<string>;
194
- /** What `dokebi describe --json` says about one module (JSON only, never a setting's value). */
195
- export interface DescribedModule {
196
- readonly name: string;
197
- readonly version: string;
198
- readonly title: ModuleText | null;
199
- readonly description: ModuleText | null;
200
- readonly requires: readonly string[];
201
- readonly modules: Readonly<Record<string, string>>;
202
- readonly tables: readonly string[];
203
- readonly db: {
204
- readonly folder: string;
205
- readonly migrations: Record<string, string[]>;
206
- readonly seeds: Record<string, string[]>;
207
- } | null;
208
- readonly permissions: readonly {
209
- key: string;
210
- title: ModuleText;
211
- description?: ModuleText;
212
- }[];
213
- readonly dataSources: readonly DescribedDataSource[];
214
- readonly actions: readonly DescribedAction[];
215
- readonly widgets: readonly {
216
- id: string;
217
- name: string;
218
- title: ModuleText;
219
- description?: ModuleText;
220
- settings: unknown;
221
- template: string;
222
- /** `<module>/<Name>` when the widget runs in the browser (D-0200), else null. */
223
- island: string | null;
224
- }[];
225
- readonly menu: readonly ModuleMenuItem[];
226
- readonly settings: {
227
- readonly section: string;
228
- readonly schema: unknown;
229
- } | null;
230
- readonly locales: {
231
- readonly folder: string;
232
- readonly languages: Record<string, string[]>;
233
- } | null;
234
- /** The UI parts the module offers (D-0203): its parts file, checked, or null. */
235
- readonly parts: {
236
- readonly file: string;
237
- readonly parts: readonly ModulePart[];
238
- } | null;
239
- /** The presets (dokebi-platform DEC-16): the folder relative to the project and its files. */
240
- readonly presets: readonly {
241
- id: string;
242
- name: string;
243
- title: ModuleText;
244
- kind: PresetKind;
245
- folder: string;
246
- files: readonly string[];
247
- }[];
248
- readonly contributes: readonly string[];
249
- readonly views: string | null;
250
- readonly routes: boolean;
251
- readonly sockets: boolean;
252
- readonly events: boolean;
253
- }
254
- /** A data source as describe gives it (D-0199): the declaration without the functions and hidden fields. */
255
- export interface DescribedDataSource {
256
- readonly id: string;
257
- readonly name: string;
258
- readonly title: ModuleText;
259
- readonly description?: ModuleText;
260
- /** False for a data source declared by name only (D-0197): it cannot be read yet. */
261
- readonly readable: boolean;
262
- readonly fields?: Readonly<Record<string, Omit<DataField, 'hidden'>>>;
263
- readonly sorts?: unknown;
264
- readonly search?: unknown;
265
- readonly filters?: unknown;
266
- readonly actions?: unknown;
267
- readonly permission?: string;
268
- /** Anyone may read (no permission). */
269
- readonly public?: true;
270
- readonly scopes?: readonly string[];
271
- readonly limit?: {
272
- readonly default: number;
273
- readonly max: number;
274
- };
275
- }
276
- /** An action as describe gives it (D-0202): the declaration without the functions. */
277
- export interface DescribedAction {
278
- readonly id: string;
279
- readonly name: string;
280
- readonly title: ModuleText;
281
- readonly description?: ModuleText;
282
- /** The input fields with their kinds and rules (what a form offers). */
283
- readonly input: unknown;
284
- /** The same as a JSON Schema (what an MCP tool publishes). */
285
- readonly schema: unknown;
286
- readonly key?: string;
287
- readonly version?: string;
288
- readonly permission: string;
289
- readonly scopes?: readonly string[];
290
- /** Runs in two steps: preview, then confirm. */
291
- readonly danger: boolean;
292
- }
293
- export declare function describeContract(input: {
294
- readonly name: string;
295
- readonly version: string;
296
- readonly requires: readonly string[];
297
- readonly contributes: readonly string[];
298
- readonly views: string | undefined;
299
- readonly hooks: {
300
- readonly routes: boolean;
301
- readonly sockets: boolean;
302
- readonly events: boolean;
303
- };
304
- readonly contract: ModuleContract;
305
- }): Promise<DescribedModule>;