@openplanr/protocol 0.14.0 → 0.15.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.
@@ -233,7 +233,10 @@
233
233
  ]
234
234
  },
235
235
  "nativeId": {
236
- "$ref": "common.schema.json#/$defs/identifier"
236
+ "type": "string",
237
+ "pattern": "^(?:[a-z][a-z0-9]*(?:-[a-z0-9]+)*:)?[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
238
+ "minLength": 1,
239
+ "maxLength": 128
237
240
  },
238
241
  "generatedPath": {
239
242
  "$ref": "common.schema.json#/$defs/relativePath"
package/src/contracts.mjs CHANGED
@@ -14,6 +14,7 @@ import { dirname, join, relative, resolve, sep } from 'node:path';
14
14
  import { fileURLToPath } from 'node:url';
15
15
  import { PROTOCOL_V115_CONTRACTS, validateDiagramReviewArtifact } from './browser-contracts.mjs';
16
16
  import { deepFreeze } from './canonical-json.mjs';
17
+ import { validateDesignProps } from './design-contracts.mjs';
17
18
  import { DESIGN_HANDOFF_CONTRACT_FILES } from './design-handoff-contracts.mjs';
18
19
  import {
19
20
  assertDiagramData,
@@ -84,6 +85,7 @@ const foundationPaths = {
84
85
  'design-document': {
85
86
  '1.9.0': 'schemas/v1.9.0/design-document.schema.json',
86
87
  '1.20.0': 'schemas/v1.20.0/design-document.schema.json',
88
+ '1.22.0': 'schemas/v1.22.0/design-document.schema.json',
87
89
  },
88
90
  'design-review-workspace': { '1.9.0': 'schemas/v1.9.0/design-review-workspace.schema.json' },
89
91
  'design-workspace-create': { '1.9.0': 'schemas/v1.9.0/design-workspace-create.schema.json' },
@@ -94,6 +96,7 @@ const foundationPaths = {
94
96
  '1.10.0': 'schemas/v1.10.0/design-review-bundle.schema.json',
95
97
  '1.16.0': 'schemas/v1.16.0/design-review-bundle.schema.json',
96
98
  '1.20.0': 'schemas/v1.20.0/design-review-bundle.schema.json',
99
+ '1.22.0': 'schemas/v1.22.0/design-review-bundle.schema.json',
97
100
  },
98
101
  'design-review-context': { '1.10.0': 'schemas/v1.10.0/design-review-context.schema.json' },
99
102
  'design-review-handoff': { '1.10.0': 'schemas/v1.10.0/design-review-handoff.schema.json' },
@@ -1381,6 +1384,18 @@ function validateStudioArtifact(kind, value, resolved) {
1381
1384
  }
1382
1385
  function validateGenericArtifact(kind, value, resolved) {
1383
1386
  const errors = validateResolvedArtifact(value, resolved);
1387
+ if (
1388
+ !errors.length &&
1389
+ resolved.protocolVersion === '1.22.0' &&
1390
+ ['design-document', 'design-review-bundle'].includes(kind)
1391
+ )
1392
+ errors.push(
1393
+ ...validateDesignProps(kind === 'design-document' ? value : value.design).map((detail) => ({
1394
+ path: '$',
1395
+ rule: 'design-props',
1396
+ detail,
1397
+ })),
1398
+ );
1384
1399
  if (kind === 'guided-questionnaire' && resolved.protocolVersion === '1.2.0')
1385
1400
  errors.push(...guidedQuestionnaireCompatibilityErrors(value));
1386
1401
  return errors;
@@ -14,11 +14,18 @@ export interface DesignFrame {
14
14
  height: number | 'auto';
15
15
  }
16
16
 
17
+ export type DesignProp =
18
+ | { type: 'enum'; options: string[]; default: string }
19
+ | { type: 'boolean'; default: boolean };
20
+
21
+ export type DesignPropValue = string | boolean;
22
+
17
23
  export interface DesignScreen {
18
24
  id: string;
19
25
  title: string;
20
26
  description?: string;
21
27
  source: DesignSource;
28
+ props?: Record<string, DesignProp>;
22
29
  /** Stable feedback anchors, unique within this screen. */
23
30
  anchors?: string[];
24
31
  }
@@ -32,6 +39,7 @@ export interface DesignVariant {
32
39
  issue?: string;
33
40
  /** Sparse screen overrides inherit unchanged sources from screens. */
34
41
  sources?: Record<string, DesignSource>;
42
+ props?: Record<string, Record<string, DesignPropValue>>;
35
43
  }
36
44
 
37
45
  export interface DesignBoardPosition {
@@ -56,7 +64,7 @@ export interface DesignLayout {
56
64
 
57
65
  export interface DesignDocument {
58
66
  kind: 'openplanr-design-document';
59
- schemaVersion: '1.0.0';
67
+ schemaVersion: '1.0.0' | '1.1.0';
60
68
  id: string;
61
69
  title: string;
62
70
  brief: {
@@ -79,8 +87,14 @@ export interface DesignDocument {
79
87
 
80
88
  export declare const DESIGN_DOCUMENT_VERSION: '1.0.0';
81
89
  export declare const DESIGN_DOCUMENT_V1_SCHEMA: Readonly<Record<string, unknown>>;
90
+ export declare const DESIGN_DOCUMENT_V120_SCHEMA: Readonly<Record<string, unknown>>;
82
91
  export declare const DESIGN_DOCUMENT_SCHEMA: Readonly<Record<string, unknown>>;
83
92
  export declare function validateDesignDocument(value: unknown): { ok: boolean; errors: string[] };
84
93
  export declare function assertDesignDocument(value: unknown): DesignDocument;
85
94
 
86
95
  export declare function initialFrameHeight(document: Pick<DesignDocument, 'frames'>): number;
96
+
97
+ export declare function validateDesignProps(document: {
98
+ screens: Pick<DesignScreen, 'id' | 'props'>[];
99
+ variants: Pick<DesignVariant, 'props'>[];
100
+ }): string[];
@@ -175,8 +175,8 @@ export const DESIGN_DOCUMENT_V1_SCHEMA = freeze({
175
175
  },
176
176
  });
177
177
 
178
- /** @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_SCHEMA} */
179
- export const DESIGN_DOCUMENT_SCHEMA = freeze({
178
+ /** @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_V120_SCHEMA} */
179
+ export const DESIGN_DOCUMENT_V120_SCHEMA = freeze({
180
180
  ...DESIGN_DOCUMENT_V1_SCHEMA,
181
181
  $id: 'https://openplanr.dev/schemas/v1.20.0/design-document.schema.json',
182
182
  'x-openplanr-contract': { id: 'design-document', version: '1.20.0' },
@@ -235,6 +235,135 @@ export const DESIGN_DOCUMENT_SCHEMA = freeze({
235
235
  },
236
236
  });
237
237
 
238
+ const PROP_TOKEN_SCHEMA = {
239
+ type: 'string',
240
+ minLength: 1,
241
+ maxLength: 128,
242
+ pattern: '^[a-z][a-z0-9-]*(?![\\s\\S])',
243
+ };
244
+ const propTokenPattern = new RegExp(PROP_TOKEN_SCHEMA.pattern, 'u');
245
+ const isPropToken = (value) =>
246
+ typeof value === 'string' &&
247
+ value.length <= PROP_TOKEN_SCHEMA.maxLength &&
248
+ propTokenPattern.test(value);
249
+
250
+ const currentDocument =
251
+ /** @type {{ properties: Record<string, unknown>; [key: string]: unknown }} */ (
252
+ structuredClone(DESIGN_DOCUMENT_V120_SCHEMA)
253
+ );
254
+ currentDocument.$id = 'https://openplanr.dev/schemas/v1.22.0/design-document.schema.json';
255
+ currentDocument['x-openplanr-contract'] = { id: 'design-document', version: '1.22.0' };
256
+ currentDocument.properties.schemaVersion = { enum: ['1.0.0', '1.1.0'] };
257
+ const screenSchema = /** @type {{ items: { properties: Record<string, unknown> } }} */ (
258
+ currentDocument.properties.screens
259
+ );
260
+ screenSchema.items.properties.props = {
261
+ type: 'object',
262
+ propertyNames: PROP_TOKEN_SCHEMA,
263
+ additionalProperties: {
264
+ oneOf: [
265
+ {
266
+ type: 'object',
267
+ additionalProperties: false,
268
+ required: ['type', 'options', 'default'],
269
+ properties: {
270
+ type: { const: 'enum' },
271
+ options: {
272
+ type: 'array',
273
+ minItems: 1,
274
+ uniqueItems: true,
275
+ items: PROP_TOKEN_SCHEMA,
276
+ },
277
+ default: PROP_TOKEN_SCHEMA,
278
+ },
279
+ },
280
+ {
281
+ type: 'object',
282
+ additionalProperties: false,
283
+ required: ['type', 'default'],
284
+ properties: { type: { const: 'boolean' }, default: { type: 'boolean' } },
285
+ },
286
+ ],
287
+ },
288
+ };
289
+ const variantSchema = /** @type {{ items: { properties: Record<string, unknown> } }} */ (
290
+ currentDocument.properties.variants
291
+ );
292
+ variantSchema.items.properties.props = {
293
+ type: 'object',
294
+ propertyNames: { $ref: '#/$defs/id' },
295
+ additionalProperties: {
296
+ type: 'object',
297
+ propertyNames: PROP_TOKEN_SCHEMA,
298
+ additionalProperties: { anyOf: [PROP_TOKEN_SCHEMA, { type: 'boolean' }] },
299
+ },
300
+ };
301
+ currentDocument.allOf = [
302
+ {
303
+ if: { properties: { schemaVersion: { const: '1.1.0' } }, required: ['schemaVersion'] },
304
+ else: {
305
+ properties: {
306
+ screens: { items: { not: { required: ['props'] } } },
307
+ variants: { items: { not: { required: ['props'] } } },
308
+ },
309
+ },
310
+ },
311
+ ];
312
+ /** @type {typeof import('./design-contracts.d.mts').DESIGN_DOCUMENT_SCHEMA} */
313
+ export const DESIGN_DOCUMENT_SCHEMA = freeze(currentDocument);
314
+
315
+ /** Validate prop references and values after structural validation.
316
+ * @type {typeof import('./design-contracts.d.mts').validateDesignProps}
317
+ */
318
+ export function validateDesignProps(document) {
319
+ const errors = [];
320
+ const checkToken = (value, path) => {
321
+ if (!isPropToken(value))
322
+ errors.push(
323
+ `${path}: ${JSON.stringify(value)} must be a lowercase token matching ${PROP_TOKEN_SCHEMA.pattern} with at most ${PROP_TOKEN_SCHEMA.maxLength} characters`,
324
+ );
325
+ };
326
+ const screens = new Map(document.screens.map((screen) => [screen.id, screen]));
327
+ for (const [index, screen] of document.screens.entries()) {
328
+ for (const [name, prop] of Object.entries(screen.props ?? {})) {
329
+ const path = `$.screens[${index}].props.${name}`;
330
+ checkToken(name, path);
331
+ if (prop.type === 'enum') {
332
+ for (const [optionIndex, option] of prop.options.entries())
333
+ checkToken(option, `${path}.options[${optionIndex}]`);
334
+ checkToken(prop.default, `${path}.default`);
335
+ if (!prop.options.includes(prop.default))
336
+ errors.push(`${path}.default: '${prop.default}' is not an enum option`);
337
+ }
338
+ }
339
+ }
340
+ for (const [index, variant] of document.variants.entries()) {
341
+ for (const [screenId, values] of Object.entries(variant.props ?? {})) {
342
+ const screen = screens.get(screenId);
343
+ const path = `$.variants[${index}].props.${screenId}`;
344
+ if (!screen) {
345
+ errors.push(`${path}: unknown screen '${screenId}'`);
346
+ continue;
347
+ }
348
+ for (const [name, value] of Object.entries(values)) {
349
+ checkToken(name, `${path}.${name}`);
350
+ if (typeof value === 'string') checkToken(value, `${path}.${name}`);
351
+ const props = screen.props ?? {};
352
+ const prop = Object.hasOwn(props, name) ? props[name] : undefined;
353
+ if (!prop) errors.push(`${path}.${name}: unknown prop '${name}' on screen '${screenId}'`);
354
+ else if (prop.type === 'boolean' && typeof value !== 'boolean')
355
+ errors.push(`${path}.${name}: expected a boolean, received ${JSON.stringify(value)}`);
356
+ else if (
357
+ prop.type === 'enum' &&
358
+ (typeof value !== 'string' || !prop.options.includes(value))
359
+ )
360
+ errors.push(`${path}.${name}: ${JSON.stringify(value)} is not an enum option`);
361
+ }
362
+ }
363
+ }
364
+ return errors;
365
+ }
366
+
238
367
  /**
239
368
  * Validate structure plus stable identity and cross-reference constraints.
240
369
  * @returns {ReturnType<typeof import('./design-contracts.d.mts').validateDesignDocument>}
@@ -243,7 +372,17 @@ export function validateDesignDocument(value) {
243
372
  const errors = validateJson(value, DESIGN_DOCUMENT_SCHEMA).map(
244
373
  ({ path, detail }) => `${path}: ${detail}`,
245
374
  );
375
+ if (
376
+ value?.schemaVersion === '1.0.0' &&
377
+ ['screens', 'variants'].some(
378
+ (field) =>
379
+ Array.isArray(value[field]) &&
380
+ value[field].some((item) => item && Object.hasOwn(item, 'props')),
381
+ )
382
+ )
383
+ errors.push('$.schemaVersion: props require schemaVersion "1.1.0"');
246
384
  if (errors.length > 0) return { ok: false, errors };
385
+ errors.push(...validateDesignProps(value));
247
386
 
248
387
  for (const field of ['frames', 'screens', 'flows', 'variants']) {
249
388
  const seen = new Set();