@marktiderman/genesis-features 0.6.1 → 0.8.0

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 CHANGED
@@ -221,32 +221,50 @@ Blocks shipped so far: `createUpdates(…)` (`app-updates`, in `@marktiderman/ge
221
221
 
222
222
  ## Content packs
223
223
 
224
- A content pack is versioned data that fills installed blocks: session types and their agendas, metric
225
- templates, custom field definitions (genesis-forms fields on a work table), forms, roadmap templates and
226
- labels. Packs are code: the publishing package exports them, and an installer copies them into a tenant's
227
- editable rows, keeping each row's source (pack, version, key) so an update can tell what someone changed.
224
+ A content pack is versioned data that fills installed blocks: whatever those blocks hold (meeting types,
225
+ templates, checklists, forms) plus labels. Packs are code: the publishing package exports them, and an
226
+ installer copies them into a tenant's editable rows, keeping each row's source (pack, version, key) so an
227
+ update can tell what someone changed.
228
+
229
+ A pack's `sections` are keyed by the block that owns them. Genesis checks what every pack shares; what an
230
+ item holds is the block's business, checked by the validator it registers as `contributes.contentSection`:
228
231
 
229
232
  ```ts
230
- import { contentPackProblems, defineContentPack } from "@marktiderman/genesis-features/blocks";
231
-
232
- export const weeklyTeamRhythm = defineContentPack({
233
- id: "weekly-team-rhythm",
234
- name: "Weekly team rhythm",
235
- version: "1.0.0",
236
- publisher: "@marktiderman/genesis-content",
237
- requires: ["sessions", "metrics"],
238
- labels: { "pursuit.quarter": "Rocks" },
239
- sessionTypes: [{ key: "weekly", kind: "team", name: "Weekly meeting", agenda: [{ key: "check-in", title: "Check in", minutes: 5 }] }],
240
- metricTemplates: [{ key: "revenue", name: "Revenue", unitType: "currency", cadence: "weekly", goalDirection: "up" }],
233
+ import { contentPackProblems, defineBlock, defineContentPack } from "@marktiderman/genesis-features/blocks";
234
+
235
+ export const meetingsBlock = defineBlock({
236
+ id: "meetings",
237
+ contributes: {
238
+ // Returns every problem with this block's items in a pack.
239
+ contentSection: (items) =>
240
+ (items as { key: string; minutes?: number }[]).filter((m) => !((m.minutes ?? 0) > 0)).map((m) => `${m.key}: minutes must be more than 0`),
241
+ },
241
242
  });
242
243
 
243
- contentPackProblems(weeklyTeamRhythm, installedBlockIds); // [] when it can be installed
244
+ export const weeklyTeamRhythm = defineContentPack(
245
+ {
246
+ id: "weekly-team-rhythm",
247
+ name: "Weekly team rhythm",
248
+ version: "1.0.0",
249
+ publisher: "@acme/content",
250
+ requires: ["meetings"],
251
+ labels: { "project.phase": "Stage" },
252
+ sections: { meetings: [{ key: "weekly", name: "Weekly meeting", minutes: 60 }] },
253
+ },
254
+ { blocks: [meetingsBlock] },
255
+ );
256
+
257
+ contentPackProblems(weeklyTeamRhythm, { installed: installedBlockIds, blocks: [meetingsBlock] }); // [] when it can be installed
244
258
  ```
245
259
 
246
- `defineContentPack` lists every problem at once: ids, semver versions, keys (unique per section, stable
247
- across versions), references between roadmap items, field targets, and any section whose block
248
- `requires` doesn't list (`sessionTypes` → sessions, `metricTemplates` → metrics, `fieldDefinitions` →
249
- its target's block, `forms` → forms, `roadmapTemplates` → roadmap).
260
+ `defineContentPack` lists every problem at once: ids, semver versions, publisher, label keys, item keys
261
+ (unique per section, stable across versions), every block validator's problems, and any section whose
262
+ block `requires` doesn't list. `contentPackProblems(pack, installedBlockIds)` still takes the installed
263
+ blocks alone; `{ validators: { meetings: fn } }` gives validators by block id instead of blocks.
264
+
265
+ The typed sections packs had before (`sessionTypes`, `metricTemplates`, `fieldDefinitions`, `forms`,
266
+ `roadmapTemplates`) still work and are checked as before, but are deprecated: put that data in `sections`
267
+ under the block that owns it.
250
268
 
251
269
  ## The page
252
270
 
package/dist/blocks.d.ts CHANGED
@@ -1,5 +1,228 @@
1
1
  import { F as FeaturePlatform } from './platforms-NR0liM8L.js';
2
2
  export { a as FEATURE_PLATFORMS } from './platforms-NR0liM8L.js';
3
+ export { L as LayerPackage, M as ModuleMeta, a as PACKAGE_GROUPS, b as PACKAGE_LAYERS, c as PackageGroup, P as PackageLayer, d as PackageMeta, p as packageLayerProblems, e as readPackageMeta } from './packages-CWhdXtzS.js';
4
+
5
+ /**
6
+ * The typed sections content packs had before `sections`: session types,
7
+ * metric templates, custom fields, forms and roadmap templates, each tied to a
8
+ * block an app owns. Kept, and still checked as before, so packs written
9
+ * against them keep working. New packs put their data in `sections`, keyed by
10
+ * block id, and the block checks it.
11
+ *
12
+ * Everything here is deprecated and goes in the next major.
13
+ */
14
+
15
+ /**
16
+ * A content pack's settings for one session type, with its agenda.
17
+ * @deprecated Put session types in `sections` under the block that owns them, checked by that block's validator.
18
+ * @stability Beta
19
+ */
20
+ interface ContentPackSessionType {
21
+ key: string;
22
+ kind: string;
23
+ name: string;
24
+ description?: string;
25
+ defaultMinutes?: number;
26
+ agenda: readonly {
27
+ key: string;
28
+ title: string;
29
+ minutes: number;
30
+ }[];
31
+ }
32
+ /**
33
+ * A metric to start from.
34
+ * @deprecated Put metric templates in `sections` under the block that owns them, checked by that block's validator.
35
+ * @stability Beta
36
+ */
37
+ interface ContentPackMetricTemplate {
38
+ key: string;
39
+ name: string;
40
+ unitType: string;
41
+ unit?: string;
42
+ cadence: string;
43
+ goalDirection: string;
44
+ goalValue?: number;
45
+ goalMax?: number;
46
+ measureKind?: string;
47
+ rollup?: string;
48
+ }
49
+ /**
50
+ * Where a custom field lives, and the block that owns that table.
51
+ * @deprecated Custom fields belong in `sections` under the block that owns their table.
52
+ * @stability Beta
53
+ */
54
+ declare const CONTENT_PACK_FIELD_TARGETS: {
55
+ readonly pursuits: "pursuits";
56
+ readonly work_items: "pursuits";
57
+ readonly metrics: "metrics";
58
+ readonly sessions: "sessions";
59
+ };
60
+ /**
61
+ * @deprecated See {@link CONTENT_PACK_FIELD_TARGETS}.
62
+ * @stability Beta
63
+ */
64
+ type ContentPackFieldTarget = keyof typeof CONTENT_PACK_FIELD_TARGETS;
65
+ /**
66
+ * A custom field: a genesis-forms serializable field, on one of the work tables.
67
+ * @deprecated Put field definitions in `sections` under the block that owns their table.
68
+ * @stability Beta
69
+ */
70
+ interface ContentPackFieldDefinition {
71
+ key: string;
72
+ target: ContentPackFieldTarget;
73
+ label: string;
74
+ /** A genesis-forms serializable field: type, options, validation. */
75
+ field: {
76
+ readonly type: string;
77
+ readonly [key: string]: unknown;
78
+ };
79
+ required?: boolean;
80
+ visibility: "tenant" | "app" | "private";
81
+ }
82
+ /**
83
+ * A worksheet, assessment or form: a genesis-forms definition.
84
+ * @deprecated Put forms in `sections` under the block that owns them.
85
+ * @stability Beta
86
+ */
87
+ interface ContentPackForm {
88
+ key: string;
89
+ kind: "worksheet" | "assessment" | "form";
90
+ title: string;
91
+ definition: {
92
+ readonly [key: string]: unknown;
93
+ };
94
+ scoring?: unknown;
95
+ }
96
+ /**
97
+ * A roadmap to start from: items that release by a rule, linked to each other by key.
98
+ * @deprecated Put roadmap templates in `sections` under the block that owns them, checked by that block's validator.
99
+ * @stability Beta
100
+ */
101
+ interface ContentPackRoadmapTemplate {
102
+ key: string;
103
+ name: string;
104
+ items: readonly {
105
+ key: string;
106
+ kind: string;
107
+ title: string;
108
+ /** Another item's key in this template. */
109
+ ref?: string;
110
+ release: {
111
+ rule: string;
112
+ afterDays?: number;
113
+ anchor?: string;
114
+ };
115
+ }[];
116
+ }
117
+ /** The deprecated typed sections, as optional fields of a pack. */
118
+ interface LegacyContentPackSections {
119
+ /** @deprecated Use `sections`. */
120
+ sessionTypes?: readonly ContentPackSessionType[];
121
+ /** @deprecated Use `sections`. */
122
+ metricTemplates?: readonly ContentPackMetricTemplate[];
123
+ /** @deprecated Use `sections`. */
124
+ fieldDefinitions?: readonly ContentPackFieldDefinition[];
125
+ /** @deprecated Use `sections`. */
126
+ forms?: readonly ContentPackForm[];
127
+ /** @deprecated Use `sections`. */
128
+ roadmapTemplates?: readonly ContentPackRoadmapTemplate[];
129
+ }
130
+
131
+ /**
132
+ * Content packs: versioned data that fills installed blocks. A pack is code,
133
+ * reviewed like any other: the publishing package exports it, and an installer
134
+ * copies it into a tenant's editable rows, keeping each row's source (pack,
135
+ * version, key) so an update can tell what a person changed.
136
+ *
137
+ * A pack's `sections` are keyed by the block that owns them, and each holds
138
+ * that block's items. Genesis checks what every pack shares (id, version,
139
+ * publisher, requires, labels, and a unique `key` on every item); what an item
140
+ * holds is the block's business, checked by the validator the block registers
141
+ * (`contributes.contentSection` on `defineBlock`, or a `validators` map).
142
+ *
143
+ * `defineContentPack` checks a pack's shape; `contentPackProblems` with the
144
+ * installed blocks also checks that every block it fills is there. Keys, not
145
+ * ids, link things together, and stay the same across versions.
146
+ *
147
+ * No zod here: packs ship to phones with `/blocks`.
148
+ */
149
+
150
+ /**
151
+ * Checks one section's items for the block that owns it, and returns every
152
+ * problem (an empty list when they're fine). Messages are relative to the
153
+ * section ("weekly: minutes must be more than 0"): the checker puts the pack
154
+ * and section in front. A validator that throws is reported as a problem.
155
+ *
156
+ * @stability Beta
157
+ */
158
+ type ContentPackSectionValidator = (items: readonly unknown[]) => readonly string[];
159
+ /** A pack's sections: block id → that block's items. @stability Beta */
160
+ type ContentPackSections = Readonly<Record<string, readonly unknown[]>>;
161
+ /** One content pack, as its publisher defines it. @stability Beta */
162
+ interface ContentPackDef extends LegacyContentPackSections {
163
+ /** Kebab-case, unique per publisher. */
164
+ id: string;
165
+ name: string;
166
+ description?: string;
167
+ /** Semver. Updates are additive. */
168
+ version: string;
169
+ /** The package that publishes it. */
170
+ publisher: string;
171
+ /** The block ids it fills; installing is refused unless every one is installed. */
172
+ requires: readonly string[];
173
+ /** Taxonomy: label key → display text, e.g. `"project.phase": "Stage"`. */
174
+ labels?: Readonly<Record<string, string>>;
175
+ /**
176
+ * The data it fills, by block id. Every item has a `key`, unique in its
177
+ * section and the same across versions; the rest is checked by the block's
178
+ * validator.
179
+ */
180
+ sections?: ContentPackSections;
181
+ }
182
+ /** @stability Beta */
183
+ interface ContentPackCheckOptions {
184
+ /** The installed blocks: every block the pack requires must be one. */
185
+ installed?: EnabledBlocks;
186
+ /** Blocks whose `contributes.contentSection` checks their section's items. */
187
+ blocks?: readonly BlockDef<string, unknown>[];
188
+ /** Section validators by block id; these win over a block's own. */
189
+ validators?: Readonly<Record<string, ContentPackSectionValidator>>;
190
+ }
191
+ /** Thrown by {@link defineContentPack}; lists every problem at once. @stability Beta */
192
+ declare class ContentPackError extends Error {
193
+ readonly problems: string[];
194
+ constructor(problems: string[]);
195
+ }
196
+ /** The block ids a pack's sections need, whatever it declares. @stability Beta */
197
+ declare function contentPackBlocks(pack: ContentPackDef): string[];
198
+ /**
199
+ * Every problem with a pack: its shape, each section's items (through the
200
+ * validator its block registers, when given) and, given the installed blocks,
201
+ * any block it fills that isn't installed. An empty list means it can be
202
+ * installed. The second argument is the installed blocks, or options.
203
+ *
204
+ * @stability Beta
205
+ */
206
+ declare function contentPackProblems(pack: ContentPackDef, installedOrOptions?: EnabledBlocks | ContentPackCheckOptions): string[];
207
+ /**
208
+ * Declare a content pack: returns it unchanged, typed, after checking its
209
+ * shape (throws a {@link ContentPackError} listing every problem). Give the
210
+ * blocks it fills, or validators by block id, to check each section's items
211
+ * too. Whether its blocks are installed is checked at install time with
212
+ * {@link contentPackProblems}.
213
+ *
214
+ * ```ts
215
+ * export const weeklyTeamRhythm = defineContentPack({
216
+ * id: "weekly-team-rhythm", name: "Weekly team rhythm", version: "1.0.0",
217
+ * publisher: "@acme/content", requires: ["meetings"],
218
+ * labels: { "project.phase": "Stage" },
219
+ * sections: { meetings: [{ key: "weekly", name: "Weekly meeting", minutes: 60 }] },
220
+ * }, { blocks: [meetingsBlock] });
221
+ * ```
222
+ *
223
+ * @stability Beta
224
+ */
225
+ declare function defineContentPack<const T extends ContentPackDef>(pack: T, options?: Omit<ContentPackCheckOptions, "installed">): T;
3
226
 
4
227
  /**
5
228
  * A navigation entry a block offers. The app's nav tree places it (by the
@@ -112,6 +335,12 @@ interface BlockContributions<S = unknown> {
112
335
  /** Agent skills that come with it: repo or package paths to a `SKILL.md`. */
113
336
  skills?: readonly string[];
114
337
  privacy?: BlockPrivacy;
338
+ /**
339
+ * Checks this block's section of a content pack (`sections[<block id>]`):
340
+ * returns every problem with its items. `defineContentPack` and
341
+ * `contentPackProblems` run it when given the block.
342
+ */
343
+ contentSection?: ContentPackSectionValidator;
115
344
  }
116
345
  /**
117
346
  * One block. `id` is the block's FeatureId: the same id as its entry in the
@@ -232,147 +461,4 @@ type SlotOf<B> = B extends BlockDef<string, infer S> ? S : never;
232
461
  */
233
462
  declare function resolveBlocks<B extends BlockDef<string, unknown>>(blocks: readonly B[], enabled?: EnabledBlocks, options?: ResolveBlocksOptions): ResolvedBlocks<B>;
234
463
 
235
- /**
236
- * Content packs: versioned data that fills installed blocks (session types and
237
- * agendas, metric templates, custom field definitions, forms, roadmap templates,
238
- * labels). A pack is code, reviewed like any other: the publishing package
239
- * exports it, and an installer copies it into a tenant's editable rows, keeping
240
- * each row's source (pack, version, key) so an update can tell what a person
241
- * changed.
242
- *
243
- * `defineContentPack` checks a pack's shape; `contentPackProblems` with the
244
- * installed blocks also checks that every block it fills is there. Keys, not
245
- * ids, link things together, and stay the same across versions.
246
- *
247
- * No zod here: packs ship to phones with `/blocks`.
248
- */
249
-
250
- /** A content pack's settings for one session type, with its agenda. @stability Beta */
251
- interface ContentPackSessionType {
252
- key: string;
253
- kind: string;
254
- name: string;
255
- description?: string;
256
- defaultMinutes?: number;
257
- agenda: readonly {
258
- key: string;
259
- title: string;
260
- minutes: number;
261
- }[];
262
- }
263
- /** A metric to start from. @stability Beta */
264
- interface ContentPackMetricTemplate {
265
- key: string;
266
- name: string;
267
- unitType: string;
268
- unit?: string;
269
- cadence: string;
270
- goalDirection: string;
271
- goalValue?: number;
272
- goalMax?: number;
273
- measureKind?: string;
274
- rollup?: string;
275
- }
276
- /** Where a custom field lives, and the block that owns that table. @stability Beta */
277
- declare const CONTENT_PACK_FIELD_TARGETS: {
278
- readonly pursuits: "pursuits";
279
- readonly work_items: "pursuits";
280
- readonly metrics: "metrics";
281
- readonly sessions: "sessions";
282
- };
283
- /** @stability Beta */
284
- type ContentPackFieldTarget = keyof typeof CONTENT_PACK_FIELD_TARGETS;
285
- /** A custom field: a genesis-forms serializable field, on one of the work tables. @stability Beta */
286
- interface ContentPackFieldDefinition {
287
- key: string;
288
- target: ContentPackFieldTarget;
289
- label: string;
290
- /** A genesis-forms serializable field: type, options, validation. */
291
- field: {
292
- readonly type: string;
293
- readonly [key: string]: unknown;
294
- };
295
- required?: boolean;
296
- visibility: "tenant" | "app" | "private";
297
- }
298
- /** A worksheet, assessment or form: a genesis-forms definition. @stability Beta */
299
- interface ContentPackForm {
300
- key: string;
301
- kind: "worksheet" | "assessment" | "form";
302
- title: string;
303
- definition: {
304
- readonly [key: string]: unknown;
305
- };
306
- scoring?: unknown;
307
- }
308
- /** A roadmap to start from: items that release by a rule, linked to each other by key. @stability Beta */
309
- interface ContentPackRoadmapTemplate {
310
- key: string;
311
- name: string;
312
- items: readonly {
313
- key: string;
314
- kind: string;
315
- title: string;
316
- /** Another item's key in this template. */
317
- ref?: string;
318
- release: {
319
- rule: string;
320
- afterDays?: number;
321
- anchor?: string;
322
- };
323
- }[];
324
- }
325
- /** One content pack, as its publisher defines it. @stability Beta */
326
- interface ContentPackDef {
327
- /** Kebab-case, unique per publisher. */
328
- id: string;
329
- name: string;
330
- description?: string;
331
- /** Semver. Updates are additive. */
332
- version: string;
333
- /** The package that publishes it. */
334
- publisher: string;
335
- /** The block ids it fills; installing is refused unless every one is installed. */
336
- requires: readonly string[];
337
- /** Taxonomy: label key → display text, e.g. `"pursuit.quarter": "Rocks"`. */
338
- labels?: Readonly<Record<string, string>>;
339
- sessionTypes?: readonly ContentPackSessionType[];
340
- metricTemplates?: readonly ContentPackMetricTemplate[];
341
- fieldDefinitions?: readonly ContentPackFieldDefinition[];
342
- forms?: readonly ContentPackForm[];
343
- roadmapTemplates?: readonly ContentPackRoadmapTemplate[];
344
- }
345
- /** Thrown by {@link defineContentPack}; lists every problem at once. @stability Beta */
346
- declare class ContentPackError extends Error {
347
- readonly problems: string[];
348
- constructor(problems: string[]);
349
- }
350
- /** The block ids a pack's sections need, whatever it declares. @stability Beta */
351
- declare function contentPackBlocks(pack: ContentPackDef): string[];
352
- /**
353
- * Every problem with a pack: its shape and, given the installed blocks, any
354
- * block it fills that isn't installed. An empty list means it can be installed.
355
- *
356
- * @stability Beta
357
- */
358
- declare function contentPackProblems(pack: ContentPackDef, installed?: EnabledBlocks): string[];
359
- /**
360
- * Declare a content pack: returns it unchanged, typed, after checking its
361
- * shape (throws a {@link ContentPackError} listing every problem). Whether its
362
- * blocks are installed is checked at install time with
363
- * {@link contentPackProblems}.
364
- *
365
- * ```ts
366
- * export const weeklyTeamRhythm = defineContentPack({
367
- * id: "weekly-team-rhythm", name: "Weekly team rhythm", version: "1.0.0",
368
- * publisher: "@marktiderman/genesis-content", requires: ["sessions", "metrics"],
369
- * labels: { "pursuit.quarter": "Rocks" },
370
- * sessionTypes: [{ key: "weekly", kind: "team", name: "Weekly meeting", agenda: [{ key: "check-in", title: "Check in", minutes: 5 }] }],
371
- * });
372
- * ```
373
- *
374
- * @stability Beta
375
- */
376
- declare function defineContentPack<const T extends ContentPackDef>(pack: T): T;
377
-
378
- export { type BlockContributions, type BlockDataUse, type BlockDef, BlockError, type BlockMigration, type BlockNavItem, type BlockPrivacy, type BlockRoute, type BlockSettingsRow, CONTENT_PACK_FIELD_TARGETS, type ContentPackDef, ContentPackError, type ContentPackFieldDefinition, type ContentPackFieldTarget, type ContentPackForm, type ContentPackMetricTemplate, type ContentPackRoadmapTemplate, type ContentPackSessionType, type Contributed, type EnabledBlocks, FeaturePlatform, type ResolveBlocksOptions, type ResolvedBlocks, contentPackBlocks, contentPackProblems, defineBlock, defineContentPack, resolveBlocks };
464
+ export { type BlockContributions, type BlockDataUse, type BlockDef, BlockError, type BlockMigration, type BlockNavItem, type BlockPrivacy, type BlockRoute, type BlockSettingsRow, CONTENT_PACK_FIELD_TARGETS, type ContentPackCheckOptions, type ContentPackDef, ContentPackError, type ContentPackFieldDefinition, type ContentPackFieldTarget, type ContentPackForm, type ContentPackMetricTemplate, type ContentPackRoadmapTemplate, type ContentPackSectionValidator, type ContentPackSections, type ContentPackSessionType, type Contributed, type EnabledBlocks, FeaturePlatform, type ResolveBlocksOptions, type ResolvedBlocks, contentPackBlocks, contentPackProblems, defineBlock, defineContentPack, resolveBlocks };
package/dist/blocks.js CHANGED
@@ -1,4 +1,4 @@
1
- export { BlockError, CONTENT_PACK_FIELD_TARGETS, ContentPackError, contentPackBlocks, contentPackProblems, defineBlock, defineContentPack, resolveBlocks } from './chunk-OBVR6AZR.js';
1
+ export { BlockError, CONTENT_PACK_FIELD_TARGETS, ContentPackError, PACKAGE_GROUPS, PACKAGE_LAYERS, contentPackBlocks, contentPackProblems, defineBlock, defineContentPack, packageLayerProblems, readPackageMeta, resolveBlocks } from './chunk-6TSENYUN.js';
2
2
  import './chunk-VYUX7VAX.js';
3
3
  export { FEATURE_PLATFORMS } from './chunk-B6WRD3WF.js';
4
4
  //# sourceMappingURL=blocks.js.map