@stripe/extensibility-jsonschema-tools 0.6.3 → 0.6.6

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/dist/index.d.ts CHANGED
@@ -1,2839 +1,38 @@
1
- import * as ts from 'typescript';
2
- export { ExtendedJSONSchema7, getSchemaExtension, jsonSchema7Schema, setSchemaExtension, uiSchemaSchema } from '@formspec/build/browser';
3
-
4
- /**
5
- * Per-declaration metadata policy input.
6
- *
7
- * @public
8
- */
9
- declare interface DeclarationMetadataPolicyInput$2 {
10
- /** Policy for JSON-facing serialized names. */
11
- readonly apiName?: MetadataValuePolicyInput$2 | undefined;
12
- /** Policy for human-facing labels and titles. */
13
- readonly displayName?: MetadataValuePolicyInput$2 | undefined;
14
- }
15
-
16
- /* Excluded from this release type: DynamicTypeNode */
17
-
18
- /* Excluded from this release type: EnumMember */
19
-
20
- /* Excluded from this release type: EnumMemberConstraintNode */
21
-
22
- /**
23
- * Enum-member display names remain unset unless authored explicitly.
24
- *
25
- * @public
26
- */
27
- declare interface EnumMemberDisplayNameDisabledPolicyInput$2 {
28
- /** Leaves missing enum-member display names unresolved. */
29
- readonly mode: "disabled";
30
- }
31
-
32
- /**
33
- * Missing enum-member display names may be inferred.
34
- *
35
- * @public
36
- */
37
- declare interface EnumMemberDisplayNameInferIfMissingPolicyInput$2 {
38
- /** Infers an enum-member display name when it is not authored explicitly. */
39
- readonly mode: "infer-if-missing";
40
- /** Callback used to infer the missing display name. */
41
- readonly infer: EnumMemberMetadataInferenceFn$2;
42
- }
43
-
44
- /**
45
- * Enum-member display-name policy input.
46
- *
47
- * @public
48
- */
49
- declare type EnumMemberDisplayNamePolicyInput$2 = EnumMemberDisplayNameDisabledPolicyInput$2 | EnumMemberDisplayNameRequireExplicitPolicyInput$2 | EnumMemberDisplayNameInferIfMissingPolicyInput$2;
50
-
51
- /**
52
- * Enum members must declare display names explicitly.
53
- *
54
- * @public
55
- */
56
- declare interface EnumMemberDisplayNameRequireExplicitPolicyInput$2 {
57
- /** Fails when an enum member has no authored display name. */
58
- readonly mode: "require-explicit";
59
- }
60
-
61
- /**
62
- * Build-facing context passed to enum-member metadata inference callbacks.
63
- *
64
- * Enum members are resolved separately from declaration-level metadata so they
65
- * do not participate in the shared declaration-kind model used by TSDoc and
66
- * extension metadata slots.
67
- *
68
- * @public
69
- */
70
- declare interface EnumMemberMetadataInferenceContext$2 {
71
- /** Authoring surface the enum originated from. */
72
- readonly surface: MetadataAuthoringSurface$2;
73
- /** Logical member identifier used for policy inference. */
74
- readonly logicalName: string;
75
- /** Underlying enum value before stringification. */
76
- readonly memberValue: string | number;
77
- /** Optional build-only context supplied by the resolver. */
78
- readonly buildContext?: unknown;
79
- }
80
-
81
- /**
82
- * Callback used to infer enum-member display names.
83
- *
84
- * @public
85
- */
86
- declare type EnumMemberMetadataInferenceFn$2 = (context: EnumMemberMetadataInferenceContext$2) => string;
87
-
88
- /**
89
- * User-facing enum-member metadata policy input.
90
- *
91
- * @public
92
- */
93
- declare interface EnumMemberMetadataPolicyInput$2 {
94
- /** Policy for human-facing enum-member labels. */
95
- readonly displayName?: EnumMemberDisplayNamePolicyInput$2 | undefined;
96
- }
97
-
98
- /**
99
- * Authoring surfaces that can contribute metadata.
100
- *
101
- * @public
102
- */
103
- declare type MetadataAuthoringSurface$2 = "tsdoc" | "chain-dsl";
104
-
105
- /**
106
- * Declaration categories that metadata policy can target.
107
- *
108
- * @public
109
- */
110
- declare type MetadataDeclarationKind$2 = "type" | "field" | "method";
111
-
112
- /**
113
- * Build-facing context passed to metadata inference callbacks.
114
- *
115
- * `buildContext` is intentionally opaque so browser/runtime packages do not
116
- * need to depend on TypeScript compiler types.
117
- *
118
- * @public
119
- */
120
- declare interface MetadataInferenceContext$2 {
121
- /** Authoring surface the metadata is being resolved for. */
122
- readonly surface: MetadataAuthoringSurface$2;
123
- /** Declaration kind currently being resolved. */
124
- readonly declarationKind: MetadataDeclarationKind$2;
125
- /** Logical identifier before any metadata policy is applied. */
126
- readonly logicalName: string;
127
- /** Optional build-only context supplied by the resolver. */
128
- readonly buildContext?: unknown;
129
- }
130
-
131
- /**
132
- * Callback used to infer a scalar metadata value.
133
- *
134
- * @public
135
- */
136
- declare type MetadataInferenceFn$2 = (context: MetadataInferenceContext$2) => string;
137
-
138
- /**
139
- * Context passed to pluralization callbacks.
140
- *
141
- * @public
142
- */
143
- declare interface MetadataPluralizationContext$2 extends MetadataInferenceContext$2 {
144
- /** Singular value that pluralization should derive from. */
145
- readonly singular: string;
146
- }
147
-
148
- /**
149
- * Pluralization disabled.
150
- *
151
- * @public
152
- */
153
- declare interface MetadataPluralizationDisabledPolicyInput$2 {
154
- /** Disables automatic plural-value generation. */
155
- readonly mode?: "disabled" | undefined;
156
- }
157
-
158
- /**
159
- * Callback used to derive plural metadata from a singular value.
160
- *
161
- * @public
162
- */
163
- declare type MetadataPluralizationFn$2 = (context: MetadataPluralizationContext$2) => string;
164
-
165
- /**
166
- * Pluralization may be inferred when absent.
167
- *
168
- * @public
169
- */
170
- declare interface MetadataPluralizationInferIfMissingPolicyInput$2 {
171
- /** Infers plural values whenever no explicit plural is present. */
172
- readonly mode: "infer-if-missing";
173
- /** Callback that derives a plural form from the resolved singular value. */
174
- readonly inflect: MetadataPluralizationFn$2;
175
- }
176
-
177
- /**
178
- * Pluralization policy input.
179
- *
180
- * @public
181
- */
182
- declare type MetadataPluralizationPolicyInput$2 = MetadataPluralizationDisabledPolicyInput$2 | MetadataPluralizationRequireExplicitPolicyInput$2 | MetadataPluralizationInferIfMissingPolicyInput$2;
183
-
184
- /**
185
- * Pluralization must be authored explicitly.
186
- *
187
- * @public
188
- */
189
- declare interface MetadataPluralizationRequireExplicitPolicyInput$2 {
190
- /** Requires plural values to be authored directly. */
191
- readonly mode: "require-explicit";
192
- }
193
-
194
- /**
195
- * User-facing metadata policy configuration.
196
- *
197
- * @public
198
- */
199
- declare interface MetadataPolicyInput$1 {
200
- /** Policy applied to named types and the analyzed root declaration. */
201
- readonly type?: DeclarationMetadataPolicyInput$2 | undefined;
202
- /** Policy applied to fields and object properties. */
203
- readonly field?: DeclarationMetadataPolicyInput$2 | undefined;
204
- /** Policy applied to callable/method declarations. */
205
- readonly method?: DeclarationMetadataPolicyInput$2 | undefined;
206
- /** Policy applied to enum-member display names during build-time IR resolution. */
207
- readonly enumMember?: EnumMemberMetadataPolicyInput$2 | undefined;
208
- }
209
-
210
- /**
211
- * Scalar metadata disabled unless provided explicitly elsewhere.
212
- *
213
- * @public
214
- */
215
- declare interface MetadataValueDisabledPolicyInput$2 {
216
- /** Disables inference for this scalar metadata value. */
217
- readonly mode?: "disabled" | undefined;
218
- /** Optional policy controlling plural forms of this scalar value. */
219
- readonly pluralization?: MetadataPluralizationPolicyInput$2 | undefined;
220
- }
221
-
222
- /**
223
- * Scalar metadata may be inferred when missing.
224
- *
225
- * @public
226
- */
227
- declare interface MetadataValueInferIfMissingPolicyInput$2 {
228
- /** Infers this scalar metadata value when it is not authored explicitly. */
229
- readonly mode: "infer-if-missing";
230
- /** Callback used to infer the missing singular value. */
231
- readonly infer: MetadataInferenceFn$2;
232
- /** Optional policy controlling plural forms of this scalar value. */
233
- readonly pluralization?: MetadataPluralizationPolicyInput$2 | undefined;
234
- }
235
-
236
- /**
237
- * Scalar metadata policy input.
238
- *
239
- * @public
240
- */
241
- declare type MetadataValuePolicyInput$2 = MetadataValueDisabledPolicyInput$2 | MetadataValueRequireExplicitPolicyInput$2 | MetadataValueInferIfMissingPolicyInput$2;
242
-
243
- /**
244
- * Scalar metadata must be authored explicitly.
245
- *
246
- * @public
247
- */
248
- declare interface MetadataValueRequireExplicitPolicyInput$2 {
249
- /** Requires this scalar metadata value to be authored directly. */
250
- readonly mode: "require-explicit";
251
- /** Optional policy controlling plural forms of this scalar value. */
252
- readonly pluralization?: MetadataPluralizationPolicyInput$2 | undefined;
253
- }
254
-
255
- /**
256
- * `@formspec/build` - Build tools for FormSpec
257
- *
258
- * This package provides generators to compile FormSpec forms into:
259
- * - JSON Schema 2020-12 (for validation)
260
- * - JSON Forms UI Schema (for rendering)
261
- *
262
- * @example
263
- * ```typescript
264
- * import { buildFormSchemas } from "@formspec/build";
265
- * import { formspec, field, group } from "@formspec/dsl";
266
- *
267
- * const form = formspec(
268
- * group("Customer",
269
- * field.text("name", { label: "Name", required: true }),
270
- * field.text("email", { label: "Email" }),
271
- * ),
272
- * );
273
- *
274
- * const { jsonSchema, uiSchema } = buildFormSchemas(form);
275
- * ```
276
- *
277
- * @packageDocumentation
278
- */
279
-
280
-
281
-
282
- /**
283
- * Registration for mapping a built-in TSDoc tag onto a custom constraint when
284
- * it is used on a particular custom type.
285
- *
286
- * @public
287
- */
288
- declare interface BuiltinConstraintBroadeningRegistration_2 {
289
- /** The built-in tag being broadened, without the `@` prefix. */
290
- readonly tagName: BuiltinConstraintName$1;
291
- /** The custom constraint to emit for this built-in tag. */
292
- readonly constraintName: string;
293
- /** Parser from raw TSDoc text to extension payload. */
294
- readonly parseValue: (raw: string) => ExtensionPayloadValue$1;
295
- }
296
-
297
- /**
298
- * Registration for mapping a built-in TSDoc tag onto a custom constraint when
299
- * it is used on a particular custom type.
300
- *
301
- * @public
302
- */
303
- declare interface BuiltinConstraintBroadeningRegistration_3 {
304
- /** The built-in tag being broadened, without the `@` prefix. */
305
- readonly tagName: BuiltinConstraintName_2;
306
- /** The custom constraint to emit for this built-in tag. */
307
- readonly constraintName: string;
308
- /** Parser from raw TSDoc text to extension payload. */
309
- readonly parseValue: (raw: string) => ExtensionPayloadValue_2;
310
- }
311
-
312
- /**
313
- * Type of a built-in constraint name.
314
- *
315
- * @public
316
- */
317
- declare type BuiltinConstraintName$1 = "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "minItems" | "maxItems" | "uniqueItems" | "pattern" | "const" | "enumOptions";
318
-
319
- /**
320
- * Type of a built-in constraint name.
321
- *
322
- * @public
323
- */
324
- declare type BuiltinConstraintName_2 = "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "minItems" | "maxItems" | "uniqueItems" | "pattern" | "const" | "enumOptions";
325
-
326
- /**
327
- * A Categorization element (tab-based layout).
328
- *
329
- * @public
330
- */
331
- declare interface Categorization {
332
- /** Discriminator identifying a categorization layout. */
333
- readonly type: "Categorization";
334
- /** Categories rendered as tabs or steps. */
335
- readonly elements: Category[];
336
- /** Optional label for the overall categorization container. */
337
- readonly label?: string | undefined;
338
- /** Optional rule controlling visibility or enablement. */
339
- readonly rule?: Rule | undefined;
340
- /** Renderer-specific categorization options. */
341
- readonly options?: Record<string, unknown> | undefined;
342
- /** Additional renderer-specific extension properties. */
343
- readonly [k: string]: unknown;
344
- }
345
-
346
- /**
347
- * A Category element, used inside a Categorization layout.
348
- *
349
- * @public
350
- */
351
- declare interface Category {
352
- /** Discriminator identifying a category inside a categorization layout. */
353
- readonly type: "Category";
354
- /** Category label shown in tabs or step navigation. */
355
- readonly label: string;
356
- /** Child elements rendered inside the category. */
357
- readonly elements: UISchemaElement[];
358
- /** Optional rule controlling visibility or enablement. */
359
- readonly rule?: Rule | undefined;
360
- /** Renderer-specific category options. */
361
- readonly options?: Record<string, unknown> | undefined;
362
- /** Additional renderer-specific extension properties. */
363
- readonly [k: string]: unknown;
364
- }
365
-
366
-
367
- /**
368
- * Complete constraint configuration for a FormSpec project.
369
- *
370
- * @public
371
- */
372
- declare interface ConstraintConfig {
373
- /** Field type constraints */
374
- fieldTypes?: FieldTypeConstraints;
375
- /** Layout and structure constraints */
376
- layout?: LayoutConstraints;
377
- /** UI Schema feature constraints */
378
- uiSchema?: UISchemaConstraints;
379
- /** Field configuration option constraints */
380
- fieldOptions?: FieldOptionConstraints;
381
- /** Control options constraints */
382
- controlOptions?: ControlOptionConstraints;
383
- }
384
-
385
- /**
386
- * Semantic metadata for ordered custom constraints that should participate in
387
- * the generic contradiction/broadening logic.
388
- *
389
- * @public
390
- */
391
- declare interface ConstraintSemanticRole$1 {
392
- /**
393
- * Logical family identifier shared by related constraints, for example
394
- * `"decimal-bound"` or `"date-bound"`.
395
- */
396
- readonly family: string;
397
- /** Whether this constraint acts as a lower or upper bound. */
398
- readonly bound: "lower" | "upper" | "exact";
399
- /** Whether equality is allowed when comparing against the bound. */
400
- readonly inclusive: boolean;
401
- }
402
-
403
- /**
404
- * Semantic metadata for ordered custom constraints that should participate in
405
- * the generic contradiction/broadening logic.
406
- *
407
- * @public
408
- */
409
- declare interface ConstraintSemanticRole_2 {
410
- /**
411
- * Logical family identifier shared by related constraints, for example
412
- * `"decimal-bound"` or `"date-bound"`.
413
- */
414
- readonly family: string;
415
- /** Whether this constraint acts as a lower or upper bound. */
416
- readonly bound: "lower" | "upper" | "exact";
417
- /** Whether equality is allowed when comparing against the bound. */
418
- readonly inclusive: boolean;
419
- }
420
-
421
-
422
- /**
423
- * Declarative authoring-side registration for a custom TSDoc constraint tag.
424
- *
425
- * @public
426
- */
427
- declare interface ConstraintTagRegistration_2 {
428
- /** Tag name without the `@` prefix, e.g. `"maxSigFig"`. */
429
- readonly tagName: string;
430
- /** The custom constraint that this tag should produce. */
431
- readonly constraintName: string;
432
- /** Parser from raw TSDoc text to JSON-serializable payload. */
433
- readonly parseValue: (raw: string) => ExtensionPayloadValue$1;
434
- /**
435
- * Optional precise applicability predicate for the field type being parsed.
436
- * When omitted, the target custom constraint registration controls type
437
- * applicability during validation.
438
- */
439
- readonly isApplicableToType?: (type: ExtensionApplicableType$1) => boolean;
440
- }
441
-
442
- /**
443
- * Declarative authoring-side registration for a custom TSDoc constraint tag.
444
- *
445
- * @public
446
- */
447
- declare interface ConstraintTagRegistration_3 {
448
- /** Tag name without the `@` prefix, e.g. `"maxSigFig"`. */
449
- readonly tagName: string;
450
- /** The custom constraint that this tag should produce. */
451
- readonly constraintName: string;
452
- /** Parser from raw TSDoc text to JSON-serializable payload. */
453
- readonly parseValue: (raw: string) => ExtensionPayloadValue_2;
454
- /**
455
- * Optional precise applicability predicate for the field type being parsed.
456
- * When omitted, the target custom constraint registration controls type
457
- * applicability during validation.
458
- */
459
- readonly isApplicableToType?: (type: ExtensionApplicableType_2) => boolean;
460
- }
461
-
462
- /**
463
- * A Control element that binds to a JSON Schema property.
464
- *
465
- * @public
466
- */
467
- declare interface ControlElement {
468
- /** Discriminator identifying a JSON Forms control element. */
469
- readonly type: "Control";
470
- /** JSON Pointer scope that this control binds to. */
471
- readonly scope: string;
472
- /** Optional label override, or `false` to suppress the label. */
473
- readonly label?: string | false | undefined;
474
- /** Optional rule controlling visibility or enablement. */
475
- readonly rule?: Rule | undefined;
476
- /** Renderer-specific control options. */
477
- readonly options?: Record<string, unknown> | undefined;
478
- /** Additional renderer-specific extension properties. */
479
- readonly [k: string]: unknown;
480
- }
481
-
482
- /**
483
- * Control options constraints - control which JSONForms Control.options are allowed.
484
- * These are renderer-specific options that may not be universally supported.
485
- *
486
- * @public
487
- */
488
- declare interface ControlOptionConstraints {
489
- /** format - renderer format hint (e.g., "radio", "textarea") */
490
- format?: Severity;
491
- /** readonly - read-only mode */
492
- readonly?: Severity;
493
- /** multi - multi-select for enums */
494
- multi?: Severity;
495
- /** showUnfocusedDescription - show description when unfocused */
496
- showUnfocusedDescription?: Severity;
497
- /** hideRequiredAsterisk - hide required indicator */
498
- hideRequiredAsterisk?: Severity;
499
- /** Custom control options (extensible dictionary) */
500
- custom?: Record<string, Severity>;
501
- }
502
-
503
- /**
504
- * Registration for a custom annotation that may produce JSON Schema keywords.
505
- *
506
- * Custom annotations are referenced by FormSpec's internal custom-annotation nodes.
507
- * They describe or present a field but do not affect which values are valid.
508
- *
509
- * @public
510
- */
511
- declare interface CustomAnnotationRegistration_2 {
512
- /** The annotation name, unique within the extension. */
513
- readonly annotationName: string;
514
- /**
515
- * Optionally converts the annotation value into JSON Schema keywords.
516
- * If omitted, the annotation has no JSON Schema representation (UI-only).
517
- */
518
- readonly toJsonSchema?: (value: ExtensionPayloadValue$1, vendorPrefix: string) => Record<string, unknown>;
519
- }
520
-
521
- /**
522
- * Registration for a custom annotation that may produce JSON Schema keywords.
523
- *
524
- * Custom annotations are referenced by FormSpec's internal custom-annotation nodes.
525
- * They describe or present a field but do not affect which values are valid.
526
- *
527
- * @public
528
- */
529
- declare interface CustomAnnotationRegistration_3 {
530
- /** The annotation name, unique within the extension. */
531
- readonly annotationName: string;
532
- /**
533
- * Optionally converts the annotation value into JSON Schema keywords.
534
- * If omitted, the annotation has no JSON Schema representation (UI-only).
535
- */
536
- readonly toJsonSchema?: (value: ExtensionPayloadValue_2, vendorPrefix: string) => Record<string, unknown>;
537
- }
538
-
539
-
540
- /**
541
- * Registration for a custom constraint that maps to JSON Schema keywords.
542
- *
543
- * Custom constraints are referenced by FormSpec's internal custom-constraint nodes.
544
- *
545
- * @public
546
- */
547
- declare interface CustomConstraintRegistration_2 {
548
- /** The constraint name, unique within the extension. */
549
- readonly constraintName: string;
550
- /**
551
- * How this constraint composes with other constraints of the same kind.
552
- * - "intersect": combine with logical AND (both must hold)
553
- * - "override": last writer wins
554
- */
555
- readonly compositionRule: "intersect" | "override";
556
- /**
557
- * TypeNode kinds this constraint is applicable to, or `null` for any type.
558
- * Used by the validator to emit TYPE_MISMATCH diagnostics.
559
- */
560
- readonly applicableTypes: readonly ExtensionApplicableType$1["kind"][] | null;
561
- /**
562
- * Optional precise type predicate used when kind-level applicability is too
563
- * broad (for example, constraints that apply to integer-like primitives but
564
- * not strings).
565
- */
566
- readonly isApplicableToType?: (type: ExtensionApplicableType$1) => boolean;
567
- /**
568
- * Optional comparator for payloads belonging to the same custom constraint.
569
- * Return values follow the `Array.prototype.sort()` contract.
570
- */
571
- readonly comparePayloads?: (left: ExtensionPayloadValue$1, right: ExtensionPayloadValue$1) => number;
572
- /**
573
- * Optional semantic family metadata for generic contradiction/broadening
574
- * handling across ordered constraints.
575
- */
576
- readonly semanticRole?: ConstraintSemanticRole$1;
577
- /**
578
- * Converts the custom constraint's payload into JSON Schema keywords.
579
- *
580
- * @param payload - The opaque JSON payload stored on the custom constraint node.
581
- * @param vendorPrefix - The vendor prefix for extension keywords.
582
- * @returns A JSON Schema fragment with the constraint keywords.
583
- */
584
- readonly toJsonSchema: (payload: ExtensionPayloadValue$1, vendorPrefix: string) => Record<string, unknown>;
585
- /**
586
- * When true, `toJsonSchema` may emit vocabulary keywords that do not carry
587
- * the vendor prefix. By default, all keys returned from `toJsonSchema` must
588
- * start with `${vendorPrefix}-`; setting this flag relaxes that check so
589
- * the constraint can produce standard or custom vocabulary keywords such as
590
- * `decimalMinimum`.
591
- *
592
- * Use this for constraints that define their own JSON Schema vocabulary
593
- * rather than namespacing under the vendor prefix.
594
- */
595
- readonly emitsVocabularyKeywords?: boolean;
596
- }
597
-
598
- /**
599
- * Registration for a custom constraint that maps to JSON Schema keywords.
600
- *
601
- * Custom constraints are referenced by FormSpec's internal custom-constraint nodes.
602
- *
603
- * @public
604
- */
605
- declare interface CustomConstraintRegistration_3 {
606
- /** The constraint name, unique within the extension. */
607
- readonly constraintName: string;
608
- /**
609
- * How this constraint composes with other constraints of the same kind.
610
- * - "intersect": combine with logical AND (both must hold)
611
- * - "override": last writer wins
612
- */
613
- readonly compositionRule: "intersect" | "override";
614
- /**
615
- * TypeNode kinds this constraint is applicable to, or `null` for any type.
616
- * Used by the validator to emit TYPE_MISMATCH diagnostics.
617
- */
618
- readonly applicableTypes: readonly ExtensionApplicableType_2["kind"][] | null;
619
- /**
620
- * Optional precise type predicate used when kind-level applicability is too
621
- * broad (for example, constraints that apply to integer-like primitives but
622
- * not strings).
623
- */
624
- readonly isApplicableToType?: (type: ExtensionApplicableType_2) => boolean;
625
- /**
626
- * Optional comparator for payloads belonging to the same custom constraint.
627
- * Return values follow the `Array.prototype.sort()` contract.
628
- */
629
- readonly comparePayloads?: (left: ExtensionPayloadValue_2, right: ExtensionPayloadValue_2) => number;
630
- /**
631
- * Optional semantic family metadata for generic contradiction/broadening
632
- * handling across ordered constraints.
633
- */
634
- readonly semanticRole?: ConstraintSemanticRole_2;
635
- /**
636
- * Converts the custom constraint's payload into JSON Schema keywords.
637
- *
638
- * @param payload - The opaque JSON payload stored on the custom constraint node.
639
- * @param vendorPrefix - The vendor prefix for extension keywords.
640
- * @returns A JSON Schema fragment with the constraint keywords.
641
- */
642
- readonly toJsonSchema: (payload: ExtensionPayloadValue_2, vendorPrefix: string) => Record<string, unknown>;
643
- /**
644
- * When true, `toJsonSchema` may emit vocabulary keywords that do not carry
645
- * the vendor prefix. By default, all keys returned from `toJsonSchema` must
646
- * start with `${vendorPrefix}-`; setting this flag relaxes that check so
647
- * the constraint can produce standard or custom vocabulary keywords such as
648
- * `decimalMinimum`.
649
- *
650
- * Use this for constraints that define their own JSON Schema vocabulary
651
- * rather than namespacing under the vendor prefix.
652
- */
653
- readonly emitsVocabularyKeywords?: boolean;
654
- }
655
-
656
-
657
- /**
658
- * Registration for a custom type that maps to a JSON Schema representation.
659
- *
660
- * Custom types are referenced by FormSpec's internal custom-type IR nodes and
661
- * resolved to JSON Schema via `toJsonSchema` during generation.
662
- *
663
- * @public
664
- */
665
- declare interface CustomTypeRegistration_2 {
666
- /** The type name, unique within the extension. */
667
- readonly typeName: string;
668
- /**
669
- * Optional TypeScript surface names that should resolve to this custom type
670
- * during TSDoc/class analysis. Defaults to `typeName` when omitted.
671
- * @deprecated Prefer `brand` for structural detection or type parameters
672
- * on `defineCustomType<T>()` for symbol-based detection. String name
673
- * matching will be removed in a future major version.
674
- */
675
- readonly tsTypeNames?: readonly string[];
676
- /**
677
- * Optional brand identifier for structural type detection.
678
- *
679
- * When provided, the type resolver checks `type.getProperties()` for a
680
- * computed property whose name matches this identifier. This is more
681
- * reliable than `tsTypeNames` for aliased branded types because it does not
682
- * depend on the local type name.
683
- *
684
- * Brand detection is attempted after name-based resolution (`tsTypeNames`)
685
- * as a structural fallback. If both match, name-based resolution wins.
686
- *
687
- * The value should match the identifier text of a `unique symbol` declaration
688
- * used as a computed property key on the branded type. For example, if the
689
- * type is `string & { readonly [__decimalBrand]: true }`, the brand is
690
- * `"__decimalBrand"`.
691
- *
692
- * Brand identifiers are stored as plain strings in the extension registry, so
693
- * they must be unique across the extensions loaded into the same build.
694
- *
695
- * Note: `"__integerBrand"` is reserved for the builtin Integer type.
696
- */
697
- readonly brand?: string;
698
- /**
699
- * Converts the custom type's payload into a JSON Schema fragment.
700
- *
701
- * @param payload - The opaque JSON payload stored on the custom type node.
702
- * @param vendorPrefix - The vendor prefix for extension keywords (e.g., "x-stripe").
703
- * @returns A JSON Schema fragment representing this type.
704
- */
705
- readonly toJsonSchema: (payload: ExtensionPayloadValue$1, vendorPrefix: string) => Record<string, unknown>;
706
- /* Excluded from this release type: serializeDefault */
707
- /**
708
- * Optional broadening of built-in constraint tags so they can apply to this
709
- * custom type without modifying the core built-in constraint tables.
710
- */
711
- readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration_2[];
712
- }
713
-
714
- /**
715
- * Registration for a custom type that maps to a JSON Schema representation.
716
- *
717
- * Custom types are referenced by FormSpec's internal custom-type IR nodes and
718
- * resolved to JSON Schema via `toJsonSchema` during generation.
719
- *
720
- * @public
721
- */
722
- declare interface CustomTypeRegistration_3 {
723
- /** The type name, unique within the extension. */
724
- readonly typeName: string;
725
- /**
726
- * Optional TypeScript surface names that should resolve to this custom type
727
- * during TSDoc/class analysis. Defaults to `typeName` when omitted.
728
- * @deprecated Prefer `brand` for structural detection or type parameters
729
- * on `defineCustomType<T>()` for symbol-based detection. String name
730
- * matching will be removed in a future major version.
731
- */
732
- readonly tsTypeNames?: readonly string[];
733
- /**
734
- * Optional brand identifier for structural type detection.
735
- *
736
- * When provided, the type resolver checks `type.getProperties()` for a
737
- * computed property whose name matches this identifier. This is more
738
- * reliable than `tsTypeNames` for aliased branded types because it does not
739
- * depend on the local type name.
740
- *
741
- * Brand detection is attempted after name-based resolution (`tsTypeNames`)
742
- * as a structural fallback. If both match, name-based resolution wins.
743
- *
744
- * The value should match the identifier text of a `unique symbol` declaration
745
- * used as a computed property key on the branded type. For example, if the
746
- * type is `string & { readonly [__decimalBrand]: true }`, the brand is
747
- * `"__decimalBrand"`.
748
- *
749
- * Brand identifiers are stored as plain strings in the extension registry, so
750
- * they must be unique across the extensions loaded into the same build.
751
- *
752
- * Note: `"__integerBrand"` is reserved for the builtin Integer type.
753
- */
754
- readonly brand?: string;
755
- /**
756
- * Converts the custom type's payload into a JSON Schema fragment.
757
- *
758
- * @param payload - The opaque JSON payload stored on the custom type node.
759
- * @param vendorPrefix - The vendor prefix for extension keywords (e.g., "x-stripe").
760
- * @returns A JSON Schema fragment representing this type.
761
- */
762
- readonly toJsonSchema: (payload: ExtensionPayloadValue_2, vendorPrefix: string) => Record<string, unknown>;
763
- /* Excluded from this release type: serializeDefault */
764
- /**
765
- * Optional broadening of built-in constraint tags so they can apply to this
766
- * custom type without modifying the core built-in constraint tables.
767
- */
768
- readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration_3[];
769
- }
770
-
771
- /**
772
- * Per-declaration metadata policy input.
773
- *
774
- * @public
775
- */
776
- declare interface DeclarationMetadataPolicyInput$1 {
777
- /** Policy for JSON-facing serialized names. */
778
- readonly apiName?: MetadataValuePolicyInput$1 | undefined;
779
- /** Policy for human-facing labels and titles. */
780
- readonly displayName?: MetadataValuePolicyInput$1 | undefined;
781
- }
782
-
783
- /**
784
- * Discriminator-specific schema generation options.
785
- *
786
- * @public
787
- */
788
- declare interface DiscriminatorResolutionOptions {
789
- /**
790
- * Optional prefix applied only to metadata-derived discriminator values.
791
- *
792
- * Literal discriminator identities taken directly from a bound type remain
793
- * unchanged.
794
- */
795
- readonly apiNamePrefix?: string | undefined;
796
- }
797
-
798
-
799
- /**
800
- * Enum-member display names remain unset unless authored explicitly.
801
- *
802
- * @public
803
- */
804
- declare interface EnumMemberDisplayNameDisabledPolicyInput$1 {
805
- /** Leaves missing enum-member display names unresolved. */
806
- readonly mode: "disabled";
807
- }
808
-
809
- /**
810
- * Missing enum-member display names may be inferred.
811
- *
812
- * @public
813
- */
814
- declare interface EnumMemberDisplayNameInferIfMissingPolicyInput$1 {
815
- /** Infers an enum-member display name when it is not authored explicitly. */
816
- readonly mode: "infer-if-missing";
817
- /** Callback used to infer the missing display name. */
818
- readonly infer: EnumMemberMetadataInferenceFn$1;
819
- }
820
-
821
- /**
822
- * Enum-member display-name policy input.
823
- *
824
- * @public
825
- */
826
- declare type EnumMemberDisplayNamePolicyInput$1 = EnumMemberDisplayNameDisabledPolicyInput$1 | EnumMemberDisplayNameRequireExplicitPolicyInput$1 | EnumMemberDisplayNameInferIfMissingPolicyInput$1;
827
-
828
- /**
829
- * Enum members must declare display names explicitly.
830
- *
831
- * @public
832
- */
833
- declare interface EnumMemberDisplayNameRequireExplicitPolicyInput$1 {
834
- /** Fails when an enum member has no authored display name. */
835
- readonly mode: "require-explicit";
836
- }
837
-
838
- /**
839
- * Build-facing context passed to enum-member metadata inference callbacks.
840
- *
841
- * Enum members are resolved separately from declaration-level metadata so they
842
- * do not participate in the shared declaration-kind model used by TSDoc and
843
- * extension metadata slots.
844
- *
845
- * @public
846
- */
847
- declare interface EnumMemberMetadataInferenceContext$1 {
848
- /** Authoring surface the enum originated from. */
849
- readonly surface: MetadataAuthoringSurface_2;
850
- /** Logical member identifier used for policy inference. */
851
- readonly logicalName: string;
852
- /** Underlying enum value before stringification. */
853
- readonly memberValue: string | number;
854
- /** Optional build-only context supplied by the resolver. */
855
- readonly buildContext?: unknown;
856
- }
857
-
858
- /**
859
- * Callback used to infer enum-member display names.
860
- *
861
- * @public
862
- */
863
- declare type EnumMemberMetadataInferenceFn$1 = (context: EnumMemberMetadataInferenceContext$1) => string;
864
-
865
- /**
866
- * User-facing enum-member metadata policy input.
867
- *
868
- * @public
869
- */
870
- declare interface EnumMemberMetadataPolicyInput$1 {
871
- /** Policy for human-facing enum-member labels. */
872
- readonly displayName?: EnumMemberDisplayNamePolicyInput$1 | undefined;
873
- }
874
-
875
-
876
- /**
877
- * A curated type shape exposed to extension applicability hooks.
878
- *
879
- * This intentionally exposes only the fields needed to determine tag/type
880
- * applicability without committing the entire canonical IR as public API.
881
- *
882
- * @public
883
- */
884
- declare type ExtensionApplicableType$1 = {
885
- readonly kind: "primitive";
886
- readonly primitiveKind: "string" | "number" | "integer" | "bigint" | "boolean" | "null";
887
- } | {
888
- readonly kind: "custom";
889
- readonly typeId: string;
890
- readonly payload: ExtensionPayloadValue$1;
891
- } | {
892
- readonly kind: Exclude<ExtensionTypeKind$1, "primitive" | "custom">;
893
- };
894
-
895
- /**
896
- * A curated type shape exposed to extension applicability hooks.
897
- *
898
- * This intentionally exposes only the fields needed to determine tag/type
899
- * applicability without committing the entire canonical IR as public API.
900
- *
901
- * @public
902
- */
903
- declare type ExtensionApplicableType_2 = {
904
- readonly kind: "primitive";
905
- readonly primitiveKind: "string" | "number" | "integer" | "bigint" | "boolean" | "null";
906
- } | {
907
- readonly kind: "custom";
908
- readonly typeId: string;
909
- readonly payload: ExtensionPayloadValue_2;
910
- } | {
911
- readonly kind: Exclude<ExtensionTypeKind_2, "primitive" | "custom">;
912
- };
913
-
914
-
915
- /**
916
- * A complete extension definition bundling types, constraints, annotations,
917
- * and vocabulary keywords.
918
- *
919
- * @example
920
- * ```typescript
921
- * const monetaryExtension = defineExtension({
922
- * extensionId: "x-stripe/monetary",
923
- * types: [
924
- * defineCustomType({
925
- * typeName: "Decimal",
926
- * toJsonSchema: (_payload, prefix) => ({
927
- * type: "string",
928
- * [`${prefix}-decimal`]: true,
929
- * }),
930
- * }),
931
- * ],
932
- * });
933
- * ```
934
- *
935
- * @public
936
- */
937
- declare interface ExtensionDefinition_2 {
938
- /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
939
- readonly extensionId: string;
940
- /** Custom type registrations provided by this extension. */
941
- readonly types?: readonly CustomTypeRegistration_2[];
942
- /** Custom constraint registrations provided by this extension. */
943
- readonly constraints?: readonly CustomConstraintRegistration_2[];
944
- /** Authoring-side TSDoc tag registrations provided by this extension. */
945
- readonly constraintTags?: readonly ConstraintTagRegistration_2[];
946
- /** Metadata-slot registrations shared by build- and lint-time analysis. */
947
- readonly metadataSlots?: readonly MetadataSlotRegistration$1[];
948
- /** Custom annotation registrations provided by this extension. */
949
- readonly annotations?: readonly CustomAnnotationRegistration_2[];
950
- /** Vocabulary keyword registrations provided by this extension. */
951
- readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration$1[];
952
- }
953
-
954
- /**
955
- * A complete extension definition bundling types, constraints, annotations,
956
- * and vocabulary keywords.
957
- *
958
- * @example
959
- * ```typescript
960
- * const monetaryExtension = defineExtension({
961
- * extensionId: "x-stripe/monetary",
962
- * types: [
963
- * defineCustomType({
964
- * typeName: "Decimal",
965
- * toJsonSchema: (_payload, prefix) => ({
966
- * type: "string",
967
- * [`${prefix}-decimal`]: true,
968
- * }),
969
- * }),
970
- * ],
971
- * });
972
- * ```
973
- *
974
- * @public
975
- */
976
- declare interface ExtensionDefinition_3 {
977
- /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
978
- readonly extensionId: string;
979
- /** Custom type registrations provided by this extension. */
980
- readonly types?: readonly CustomTypeRegistration_3[];
981
- /** Custom constraint registrations provided by this extension. */
982
- readonly constraints?: readonly CustomConstraintRegistration_3[];
983
- /** Authoring-side TSDoc tag registrations provided by this extension. */
984
- readonly constraintTags?: readonly ConstraintTagRegistration_3[];
985
- /** Metadata-slot registrations shared by build- and lint-time analysis. */
986
- readonly metadataSlots?: readonly MetadataSlotRegistration_2[];
987
- /** Custom annotation registrations provided by this extension. */
988
- readonly annotations?: readonly CustomAnnotationRegistration_3[];
989
- /** Vocabulary keyword registrations provided by this extension. */
990
- readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration_2[];
991
- }
992
-
993
- /**
994
- * A JSON-serializable payload value used by extension registration hooks.
995
- *
996
- * @public
997
- */
998
- declare type ExtensionPayloadValue$1 = null | boolean | number | string | readonly ExtensionPayloadValue$1[] | {
999
- readonly [key: string]: ExtensionPayloadValue$1;
1000
- };
1001
-
1002
- /**
1003
- * A JSON-serializable payload value used by extension registration hooks.
1004
- *
1005
- * @public
1006
- */
1007
- declare type ExtensionPayloadValue_2 = null | boolean | number | string | readonly ExtensionPayloadValue_2[] | {
1008
- readonly [key: string]: ExtensionPayloadValue_2;
1009
- };
1010
-
1011
- /**
1012
- * A registry of extensions that provides lookup by fully-qualified ID.
1013
- *
1014
- * Type IDs follow the format: `<extensionId>/<typeName>`
1015
- * Constraint IDs follow the format: `<extensionId>/<constraintName>`
1016
- * Annotation IDs follow the format: `<extensionId>/<annotationName>`
1017
- *
1018
- * @public
1019
- */
1020
- declare interface ExtensionRegistry {
1021
- /** The extensions registered in this registry (in registration order). */
1022
- readonly extensions: readonly ExtensionDefinition_2[];
1023
- /* Excluded from this release type: setupDiagnostics */
1024
- /**
1025
- * Look up a custom type registration by its fully-qualified type ID.
1026
- *
1027
- * @param typeId - The fully-qualified type ID (e.g., "x-stripe/monetary/Decimal").
1028
- * @returns The registration if found, otherwise `undefined`.
1029
- */
1030
- findType(typeId: string): CustomTypeRegistration_2 | undefined;
1031
- /**
1032
- * Look up a custom type registration by a TypeScript-facing type name.
1033
- *
1034
- * This is used during TSDoc/class analysis to resolve extension-defined
1035
- * custom types from source-level declarations.
1036
- */
1037
- findTypeByName(typeName: string): ExtensionTypeLookupResult | undefined;
1038
- /**
1039
- * Look up a custom type registration by a brand identifier.
1040
- *
1041
- * This is used during class analysis to resolve extension-defined custom types
1042
- * via structural brand detection (`unique symbol` computed property keys).
1043
- * Brand identifiers are stored as plain strings, so they must be unique
1044
- * across all extensions loaded into the registry.
1045
- *
1046
- * @param brand - The identifier text of the `unique symbol` brand variable.
1047
- */
1048
- findTypeByBrand(brand: string): ExtensionTypeLookupResult | undefined;
1049
- /**
1050
- * Look up a custom type by its TypeScript symbol identity.
1051
- *
1052
- * Built from `defineCustomType<T>()` type parameter extraction in the config file.
1053
- * This is the most precise detection path — it uses `ts.Symbol` identity, which is
1054
- * immune to import aliases and name collisions.
1055
- *
1056
- * Returns `undefined` until {@link MutableExtensionRegistry.setSymbolMap} has been
1057
- * called (i.e., before the TypeScript program is available), or when the symbol is
1058
- * not registered via a type parameter.
1059
- *
1060
- * @param symbol - The canonical TypeScript symbol to look up.
1061
- */
1062
- findTypeBySymbol(symbol: ts.Symbol): ExtensionTypeLookupResult | undefined;
1063
- /**
1064
- * Look up a custom constraint registration by its fully-qualified constraint ID.
1065
- *
1066
- * @param constraintId - The fully-qualified constraint ID.
1067
- * @returns The registration if found, otherwise `undefined`.
1068
- */
1069
- findConstraint(constraintId: string): CustomConstraintRegistration_2 | undefined;
1070
- /**
1071
- * Look up a TSDoc custom constraint-tag registration by tag name.
1072
- */
1073
- findConstraintTag(tagName: string): {
1074
- readonly extensionId: string;
1075
- readonly registration: ConstraintTagRegistration_2;
1076
- } | undefined;
1077
- /**
1078
- * Look up built-in tag broadening for a given custom type ID.
1079
- */
1080
- findBuiltinConstraintBroadening(typeId: string, tagName: string): {
1081
- readonly extensionId: string;
1082
- readonly registration: BuiltinConstraintBroadeningRegistration_2;
1083
- } | undefined;
1084
- /**
1085
- * Look up a custom annotation registration by its fully-qualified annotation ID.
1086
- *
1087
- * @param annotationId - The fully-qualified annotation ID.
1088
- * @returns The registration if found, otherwise `undefined`.
1089
- */
1090
- findAnnotation(annotationId: string): CustomAnnotationRegistration_2 | undefined;
1091
- }
1092
-
1093
- /**
1094
- * Top-level type kinds that extension applicability hooks may inspect.
1095
- *
1096
- * @public
1097
- */
1098
- declare type ExtensionTypeKind$1 = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
1099
-
1100
- /**
1101
- * Top-level type kinds that extension applicability hooks may inspect.
1102
- *
1103
- * @public
1104
- */
1105
- declare type ExtensionTypeKind_2 = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
1106
-
1107
- /**
1108
- * The result of a successful extension type lookup.
1109
- *
1110
- * Returned by {@link ExtensionRegistry.findTypeByName},
1111
- * {@link ExtensionRegistry.findTypeByBrand}, and
1112
- * {@link ExtensionRegistry.findTypeBySymbol}.
1113
- *
1114
- * @public
1115
- */
1116
- declare interface ExtensionTypeLookupResult {
1117
- /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
1118
- readonly extensionId: string;
1119
- /** The custom type registration matched by this lookup. */
1120
- readonly registration: CustomTypeRegistration_2;
1121
- }
1122
-
1123
- /**
1124
- * Field configuration option constraints - control which field options are allowed.
1125
- *
1126
- * @public
1127
- */
1128
- declare interface FieldOptionConstraints {
1129
- /** label - field label text */
1130
- label?: Severity;
1131
- /** placeholder - input placeholder text */
1132
- placeholder?: Severity;
1133
- /** required - whether field is required */
1134
- required?: Severity;
1135
- /** minValue - minimum value for numbers */
1136
- minValue?: Severity;
1137
- /** maxValue - maximum value for numbers */
1138
- maxValue?: Severity;
1139
- /** minItems - minimum array length */
1140
- minItems?: Severity;
1141
- /** maxItems - maximum array length */
1142
- maxItems?: Severity;
1143
- }
1144
-
1145
- /**
1146
- * Field type constraints - control which field types are allowed.
1147
- * Fine-grained control over each DSL field builder.
1148
- *
1149
- * @public
1150
- */
1151
- declare interface FieldTypeConstraints {
1152
- /** field.text() - basic text input */
1153
- text?: Severity;
1154
- /** field.number() - numeric input */
1155
- number?: Severity;
1156
- /** field.boolean() - checkbox/toggle */
1157
- boolean?: Severity;
1158
- /** field.enum() with literal options */
1159
- staticEnum?: Severity;
1160
- /** field.dynamicEnum() - runtime-fetched options */
1161
- dynamicEnum?: Severity;
1162
- /** field.dynamicSchema() - runtime-fetched schema */
1163
- dynamicSchema?: Severity;
1164
- /** field.array() / field.arrayWithConfig() */
1165
- array?: Severity;
1166
- /** field.object() / field.objectWithConfig() */
1167
- object?: Severity;
1168
- }
1169
-
1170
-
1171
- /**
1172
- * Top-level FormSpec configuration file structure.
1173
- * The .formspec.yml file uses this structure.
1174
- *
1175
- * @public
1176
- */
1177
- declare interface FormSpecConfig {
1178
- /**
1179
- * Extension definitions providing custom types, constraints,
1180
- * annotations, and vocabulary keywords.
1181
- */
1182
- readonly extensions?: readonly ExtensionDefinition_3[];
1183
- /** Constraint surface configuration — controls which field types,
1184
- * layouts, UI features, and field/control options are allowed. */
1185
- readonly constraints?: ConstraintConfig;
1186
- /**
1187
- * Metadata inference and naming policy. Controls how apiName,
1188
- * displayName, and plural forms are derived when not authored.
1189
- */
1190
- readonly metadata?: MetadataPolicyInput_2;
1191
- /**
1192
- * Vendor prefix for extension-emitted JSON Schema keywords.
1193
- * Must start with "x-".
1194
- * @defaultValue "x-formspec"
1195
- */
1196
- readonly vendorPrefix?: string;
1197
- /**
1198
- * JSON Schema representation for static enums.
1199
- * - "enum": compact `enum` output, plus a display-name extension when labels exist
1200
- * - "oneOf": per-member `const` output, with `title` only for distinct labels
1201
- * - "smart-size": uses `enum` unless a distinct display label would be lost
1202
- * @defaultValue "enum"
1203
- */
1204
- readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
1205
- /**
1206
- * Per-package configuration overrides for monorepos.
1207
- * Keys are glob patterns matched against file paths relative to
1208
- * the config file's directory. Values merge with root settings.
1209
- */
1210
- readonly packages?: Readonly<Record<string, FormSpecPackageOverride>>;
1211
- }
1212
-
1213
- /**
1214
- * Per-package overrides that merge with the root config.
1215
- * Only settings that genuinely vary per package are overridable.
1216
- *
1217
- * @public
1218
- */
1219
- declare interface FormSpecPackageOverride {
1220
- /** Override constraint surface for this package. */
1221
- readonly constraints?: ConstraintConfig;
1222
- /** Override enum serialization for this package. */
1223
- readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
1224
- /** Override metadata policy for this package. */
1225
- readonly metadata?: MetadataPolicyInput_2;
1226
- }
1227
-
1228
- /**
1229
- * Options for generating schemas from a decorated class.
1230
- *
1231
- * @public
1232
- */
1233
- declare interface GenerateFromClassOptions extends StaticSchemaGenerationOptions {
1234
- /** Path to the TypeScript source file */
1235
- filePath: string;
1236
- /** Class name to analyze */
1237
- className: string;
1238
- }
1239
-
1240
- /**
1241
- * Result of generating schemas from a decorated class.
1242
- *
1243
- * @public
1244
- */
1245
- declare interface GenerateFromClassResult {
1246
- /** JSON Schema 2020-12 for validation */
1247
- jsonSchema: JsonSchema2020;
1248
- /** JSON Forms UI Schema for rendering */
1249
- uiSchema: UISchema;
1250
- }
1251
-
1252
- /**
1253
- * Generates JSON Schema and UI Schema from a decorated TypeScript class.
1254
- *
1255
- * This is a high-level entry point that handles the entire pipeline:
1256
- * creating a TypeScript program, finding the class, analyzing it to IR,
1257
- * and generating schemas — all in one call.
1258
- *
1259
- * @example
1260
- * ```typescript
1261
- * const result = generateSchemasFromClass({
1262
- * filePath: "./src/forms.ts",
1263
- * className: "UserForm",
1264
- * });
1265
- * console.log(result.jsonSchema);
1266
- * ```
1267
- *
1268
- * @param options - File path, class name, and optional compiler options
1269
- * @returns Generated JSON Schema and UI Schema
1270
- *
1271
- * @public
1272
- */
1273
- declare function generateSchemasFromClass(options: GenerateFromClassOptions): GenerateFromClassResult;
1274
-
1275
- /**
1276
- * Options for generating schemas from a named type (class, interface, or type alias).
1277
- *
1278
- * @public
1279
- */
1280
- declare interface GenerateSchemasOptions extends StaticSchemaGenerationOptions {
1281
- /** Path to the TypeScript source file */
1282
- readonly filePath: string;
1283
- /** Name of the exported class, interface, or type alias to analyze */
1284
- readonly typeName: string;
1285
- /**
1286
- * Controls whether error-severity diagnostics throw or are returned in the result.
1287
- */
1288
- readonly errorReporting: "throw" | "diagnostics";
1289
- }
1290
-
1291
- /**
1292
- * A group element with a label.
1293
- *
1294
- * @public
1295
- */
1296
- declare interface GroupLayout {
1297
- /** Discriminator identifying a labeled group container. */
1298
- readonly type: "Group";
1299
- /** Group label shown by compatible renderers. */
1300
- readonly label: string;
1301
- /** Child elements rendered inside the group. */
1302
- readonly elements: UISchemaElement[];
1303
- /** Optional rule controlling visibility or enablement. */
1304
- readonly rule?: Rule | undefined;
1305
- /** Renderer-specific group options. */
1306
- readonly options?: Record<string, unknown> | undefined;
1307
- /** Additional renderer-specific extension properties. */
1308
- readonly [k: string]: unknown;
1309
- }
1310
-
1311
- /**
1312
- * A horizontal layout element.
1313
- *
1314
- * @public
1315
- */
1316
- declare interface HorizontalLayout {
1317
- /** Discriminator identifying a horizontal layout container. */
1318
- readonly type: "HorizontalLayout";
1319
- /** Child elements rendered side by side. */
1320
- readonly elements: UISchemaElement[];
1321
- /** Optional rule controlling visibility or enablement. */
1322
- readonly rule?: Rule | undefined;
1323
- /** Renderer-specific layout options. */
1324
- readonly options?: Record<string, unknown> | undefined;
1325
- /** Additional renderer-specific extension properties. */
1326
- readonly [k: string]: unknown;
1327
- }
1328
-
1329
- /**
1330
- * A JSON Schema 2020-12 document, sub-schema, or keyword collection.
1331
- *
1332
- * This interface covers the subset of JSON Schema 2020-12 that this generator
1333
- * emits, plus an index signature for custom `x-formspec-*` extension keywords.
1334
- *
1335
- * @public
1336
- */
1337
- declare interface JsonSchema2020 {
1338
- /** Declared JSON Schema dialect URI for the document root. */
1339
- $schema?: string;
1340
- /** Reference to another schema location. */
1341
- $ref?: string;
1342
- /** Named reusable schema definitions keyed by definition name. */
1343
- $defs?: Record<string, JsonSchema2020>;
1344
- /** JSON Schema type keyword for the current node. */
1345
- type?: string;
1346
- /** Object properties keyed by property name. */
1347
- properties?: Record<string, JsonSchema2020>;
1348
- /** Property names that must be present on object values. */
1349
- required?: string[];
1350
- /** Item schema applied to array elements. */
1351
- items?: JsonSchema2020;
1352
- /** Whether, or how, additional object properties are allowed. */
1353
- additionalProperties?: boolean | JsonSchema2020;
1354
- /** Closed set of allowed scalar values. */
1355
- enum?: readonly (string | number)[];
1356
- /** Literal value the instance must equal. */
1357
- const?: unknown;
1358
- /** Schemas that must all validate successfully. */
1359
- allOf?: readonly JsonSchema2020[];
1360
- /** Schemas of which exactly one should validate successfully. */
1361
- oneOf?: readonly JsonSchema2020[];
1362
- /** Schemas of which at least one may validate successfully. */
1363
- anyOf?: readonly JsonSchema2020[];
1364
- /** Inclusive numeric lower bound. */
1365
- minimum?: number;
1366
- /** Inclusive numeric upper bound. */
1367
- maximum?: number;
1368
- /** Exclusive numeric lower bound. */
1369
- exclusiveMinimum?: number;
1370
- /** Exclusive numeric upper bound. */
1371
- exclusiveMaximum?: number;
1372
- /** Required numeric step interval. */
1373
- multipleOf?: number;
1374
- /** Inclusive minimum string length. */
1375
- minLength?: number;
1376
- /** Inclusive maximum string length. */
1377
- maxLength?: number;
1378
- /** Inclusive minimum array length. */
1379
- minItems?: number;
1380
- /** Inclusive maximum array length. */
1381
- maxItems?: number;
1382
- /** Regular expression pattern applied to string values. */
1383
- pattern?: string;
1384
- /** Whether array elements must be unique. */
1385
- uniqueItems?: boolean;
1386
- /** Format hint for downstream validators and tooling. */
1387
- format?: string;
1388
- /** Human-readable title for the schema node. */
1389
- title?: string;
1390
- /** Human-readable description for the schema node. */
1391
- description?: string;
1392
- /** Default value suggested for the schema node. */
1393
- default?: unknown;
1394
- /** Whether the schema node is deprecated. */
1395
- deprecated?: boolean;
1396
- /** Additional vendor-prefixed extension keywords. */
1397
- [key: `x-${string}`]: unknown;
1398
- }
1399
-
1400
- /**
1401
- * A Label element for displaying static text.
1402
- *
1403
- * @public
1404
- */
1405
- declare interface LabelElement {
1406
- /** Discriminator identifying a static text label element. */
1407
- readonly type: "Label";
1408
- /** Static text content rendered by the label element. */
1409
- readonly text: string;
1410
- /** Optional rule controlling visibility or enablement. */
1411
- readonly rule?: Rule | undefined;
1412
- /** Renderer-specific label options. */
1413
- readonly options?: Record<string, unknown> | undefined;
1414
- /** Additional renderer-specific extension properties. */
1415
- readonly [k: string]: unknown;
1416
- }
1417
-
1418
- /**
1419
- * Layout and structure constraints - control grouping, conditionals, nesting.
1420
- *
1421
- * @public
1422
- */
1423
- declare interface LayoutConstraints {
1424
- /** group() - visual grouping of fields */
1425
- group?: Severity;
1426
- /** when() - conditional field visibility */
1427
- conditionals?: Severity;
1428
- /** Maximum nesting depth for objects/arrays (0 = flat only) */
1429
- maxNestingDepth?: number;
1430
- }
1431
-
1432
- /**
1433
- * JSONForms layout type constraints.
1434
- *
1435
- * @public
1436
- */
1437
- declare interface LayoutTypeConstraints {
1438
- /** VerticalLayout - stack elements vertically */
1439
- VerticalLayout?: Severity;
1440
- /** HorizontalLayout - arrange elements horizontally */
1441
- HorizontalLayout?: Severity;
1442
- /** Group - visual grouping with label */
1443
- Group?: Severity;
1444
- /** Categorization - tabbed/wizard interface */
1445
- Categorization?: Severity;
1446
- /** Category - individual tab/step in Categorization */
1447
- Category?: Severity;
1448
- }
1449
-
1450
- /**
1451
- * Authoring surfaces that can contribute metadata.
1452
- *
1453
- * @public
1454
- */
1455
- declare type MetadataAuthoringSurface$1 = "tsdoc" | "chain-dsl";
1456
-
1457
- /**
1458
- * Authoring surfaces that can contribute metadata.
1459
- *
1460
- * @public
1461
- */
1462
- declare type MetadataAuthoringSurface_2 = "tsdoc" | "chain-dsl";
1463
-
1464
- /**
1465
- * Declaration categories that metadata policy can target.
1466
- *
1467
- * @public
1468
- */
1469
- declare type MetadataDeclarationKind$1 = "type" | "field" | "method";
1470
-
1471
- /**
1472
- * Declaration categories that metadata policy can target.
1473
- *
1474
- * @public
1475
- */
1476
- declare type MetadataDeclarationKind_2 = "type" | "field" | "method";
1477
-
1478
- /**
1479
- * Build-facing context passed to metadata inference callbacks.
1480
- *
1481
- * `buildContext` is intentionally opaque so browser/runtime packages do not
1482
- * need to depend on TypeScript compiler types.
1483
- *
1484
- * @public
1485
- */
1486
- declare interface MetadataInferenceContext$1 {
1487
- /** Authoring surface the metadata is being resolved for. */
1488
- readonly surface: MetadataAuthoringSurface$1;
1489
- /** Declaration kind currently being resolved. */
1490
- readonly declarationKind: MetadataDeclarationKind$1;
1491
- /** Logical identifier before any metadata policy is applied. */
1492
- readonly logicalName: string;
1493
- /** Optional build-only context supplied by the resolver. */
1494
- readonly buildContext?: unknown;
1495
- }
1496
-
1497
- /**
1498
- * Build-facing context passed to metadata inference callbacks.
1499
- *
1500
- * `buildContext` is intentionally opaque so browser/runtime packages do not
1501
- * need to depend on TypeScript compiler types.
1502
- *
1503
- * @public
1504
- */
1505
- declare interface MetadataInferenceContext_2 {
1506
- /** Authoring surface the metadata is being resolved for. */
1507
- readonly surface: MetadataAuthoringSurface_2;
1508
- /** Declaration kind currently being resolved. */
1509
- readonly declarationKind: MetadataDeclarationKind_2;
1510
- /** Logical identifier before any metadata policy is applied. */
1511
- readonly logicalName: string;
1512
- /** Optional build-only context supplied by the resolver. */
1513
- readonly buildContext?: unknown;
1514
- }
1515
-
1516
- /**
1517
- * Callback used to infer a scalar metadata value.
1518
- *
1519
- * @public
1520
- */
1521
- declare type MetadataInferenceFn$1 = (context: MetadataInferenceContext_2) => string;
1522
-
1523
- /**
1524
- * Context passed to pluralization callbacks.
1525
- *
1526
- * @public
1527
- */
1528
- declare interface MetadataPluralizationContext$1 extends MetadataInferenceContext_2 {
1529
- /** Singular value that pluralization should derive from. */
1530
- readonly singular: string;
1531
- }
1532
-
1533
- /**
1534
- * Pluralization disabled.
1535
- *
1536
- * @public
1537
- */
1538
- declare interface MetadataPluralizationDisabledPolicyInput$1 {
1539
- /** Disables automatic plural-value generation. */
1540
- readonly mode?: "disabled" | undefined;
1541
- }
1542
-
1543
- /**
1544
- * Callback used to derive plural metadata from a singular value.
1545
- *
1546
- * @public
1547
- */
1548
- declare type MetadataPluralizationFn$1 = (context: MetadataPluralizationContext$1) => string;
1549
-
1550
- /**
1551
- * Pluralization may be inferred when absent.
1552
- *
1553
- * @public
1554
- */
1555
- declare interface MetadataPluralizationInferIfMissingPolicyInput$1 {
1556
- /** Infers plural values whenever no explicit plural is present. */
1557
- readonly mode: "infer-if-missing";
1558
- /** Callback that derives a plural form from the resolved singular value. */
1559
- readonly inflect: MetadataPluralizationFn$1;
1560
- }
1561
-
1562
- /**
1563
- * Pluralization policy input.
1564
- *
1565
- * @public
1566
- */
1567
- declare type MetadataPluralizationPolicyInput$1 = MetadataPluralizationDisabledPolicyInput$1 | MetadataPluralizationRequireExplicitPolicyInput$1 | MetadataPluralizationInferIfMissingPolicyInput$1;
1568
-
1569
- /**
1570
- * Pluralization must be authored explicitly.
1571
- *
1572
- * @public
1573
- */
1574
- declare interface MetadataPluralizationRequireExplicitPolicyInput$1 {
1575
- /** Requires plural values to be authored directly. */
1576
- readonly mode: "require-explicit";
1577
- }
1578
-
1579
- /**
1580
- * User-facing metadata policy configuration.
1581
- *
1582
- * @public
1583
- */
1584
- declare interface MetadataPolicyInput_2 {
1585
- /** Policy applied to named types and the analyzed root declaration. */
1586
- readonly type?: DeclarationMetadataPolicyInput$1 | undefined;
1587
- /** Policy applied to fields and object properties. */
1588
- readonly field?: DeclarationMetadataPolicyInput$1 | undefined;
1589
- /** Policy applied to callable/method declarations. */
1590
- readonly method?: DeclarationMetadataPolicyInput$1 | undefined;
1591
- /** Policy applied to enum-member display names during build-time IR resolution. */
1592
- readonly enumMember?: EnumMemberMetadataPolicyInput$1 | undefined;
1593
- }
1594
-
1595
- /**
1596
- * Supported qualifier registration for an extensible metadata slot.
1597
- *
1598
- * @public
1599
- */
1600
- declare interface MetadataQualifierRegistration$1 {
1601
- /** Qualifier text without the leading colon. */
1602
- readonly qualifier: string;
1603
- /**
1604
- * Optional source qualifier to use as the base input for this qualifier's
1605
- * inference hook. Defaults to the slot's bare/default value when omitted.
1606
- */
1607
- readonly sourceQualifier?: string | undefined;
1608
- /** Optional inference hook for this qualified value. */
1609
- readonly inferValue?: MetadataSlotInferenceFn$1 | undefined;
1610
- }
1611
-
1612
- /**
1613
- * Supported qualifier registration for an extensible metadata slot.
1614
- *
1615
- * @public
1616
- */
1617
- declare interface MetadataQualifierRegistration_2 {
1618
- /** Qualifier text without the leading colon. */
1619
- readonly qualifier: string;
1620
- /**
1621
- * Optional source qualifier to use as the base input for this qualifier's
1622
- * inference hook. Defaults to the slot's bare/default value when omitted.
1623
- */
1624
- readonly sourceQualifier?: string | undefined;
1625
- /** Optional inference hook for this qualified value. */
1626
- readonly inferValue?: MetadataSlotInferenceFn_2 | undefined;
1627
- }
1628
-
1629
- /**
1630
- * Stable slot identifier for extensible metadata analysis.
1631
- *
1632
- * @public
1633
- */
1634
- declare type MetadataSlotId$1 = string;
1635
-
1636
- /**
1637
- * Stable slot identifier for extensible metadata analysis.
1638
- *
1639
- * @public
1640
- */
1641
- declare type MetadataSlotId_2 = string;
1642
-
1643
- /**
1644
- * Context passed to extensible metadata inference hooks.
1645
- *
1646
- * @public
1647
- */
1648
- declare interface MetadataSlotInferenceContext$1 extends MetadataInferenceContext$1 {
1649
- /** Stable logical slot identifier. */
1650
- readonly slotId: MetadataSlotId$1;
1651
- /** Tag name associated with the slot, without the `@` prefix. */
1652
- readonly tagName: string;
1653
- /** Optional qualifier being inferred (for example `plural`). */
1654
- readonly qualifier?: string | undefined;
1655
- /** Resolved bare/default value used as the base input for derived qualifiers. */
1656
- readonly baseValue?: string | undefined;
1657
- }
1658
-
1659
- /**
1660
- * Context passed to extensible metadata inference hooks.
1661
- *
1662
- * @public
1663
- */
1664
- declare interface MetadataSlotInferenceContext_2 extends MetadataInferenceContext_2 {
1665
- /** Stable logical slot identifier. */
1666
- readonly slotId: MetadataSlotId_2;
1667
- /** Tag name associated with the slot, without the `@` prefix. */
1668
- readonly tagName: string;
1669
- /** Optional qualifier being inferred (for example `plural`). */
1670
- readonly qualifier?: string | undefined;
1671
- /** Resolved bare/default value used as the base input for derived qualifiers. */
1672
- readonly baseValue?: string | undefined;
1673
- }
1674
-
1675
- /**
1676
- * Callback used to infer an extensible metadata slot value.
1677
- *
1678
- * @public
1679
- */
1680
- declare type MetadataSlotInferenceFn$1 = (context: MetadataSlotInferenceContext$1) => string;
1681
-
1682
- /**
1683
- * Callback used to infer an extensible metadata slot value.
1684
- *
1685
- * @public
1686
- */
1687
- declare type MetadataSlotInferenceFn_2 = (context: MetadataSlotInferenceContext_2) => string;
1688
-
1689
- /**
1690
- * Extensible metadata slot definition shared across build- and lint-time analysis.
1691
- *
1692
- * @public
1693
- */
1694
- declare interface MetadataSlotRegistration$1 {
1695
- /** Stable logical slot identifier. */
1696
- readonly slotId: MetadataSlotId$1;
1697
- /** Tag name associated with this slot, without the `@` prefix. */
1698
- readonly tagName: string;
1699
- /** Declaration kinds where the slot is meaningful. */
1700
- readonly declarationKinds: readonly MetadataDeclarationKind$1[];
1701
- /** Whether a bare tag without a qualifier is supported. Defaults to true. */
1702
- readonly allowBare?: boolean | undefined;
1703
- /** Supported qualifiers for this slot. */
1704
- readonly qualifiers?: readonly MetadataQualifierRegistration$1[] | undefined;
1705
- /** Optional inference hook for the bare/default slot value. */
1706
- readonly inferValue?: MetadataSlotInferenceFn$1 | undefined;
1707
- /**
1708
- * Optional applicability hook for declaration-specific rules beyond
1709
- * declaration kind. `buildContext` may carry compiler objects.
1710
- */
1711
- readonly isApplicable?: ((context: MetadataInferenceContext$1) => boolean) | undefined;
1712
- }
1713
-
1714
- /**
1715
- * Extensible metadata slot definition shared across build- and lint-time analysis.
1716
- *
1717
- * @public
1718
- */
1719
- declare interface MetadataSlotRegistration_2 {
1720
- /** Stable logical slot identifier. */
1721
- readonly slotId: MetadataSlotId_2;
1722
- /** Tag name associated with this slot, without the `@` prefix. */
1723
- readonly tagName: string;
1724
- /** Declaration kinds where the slot is meaningful. */
1725
- readonly declarationKinds: readonly MetadataDeclarationKind_2[];
1726
- /** Whether a bare tag without a qualifier is supported. Defaults to true. */
1727
- readonly allowBare?: boolean | undefined;
1728
- /** Supported qualifiers for this slot. */
1729
- readonly qualifiers?: readonly MetadataQualifierRegistration_2[] | undefined;
1730
- /** Optional inference hook for the bare/default slot value. */
1731
- readonly inferValue?: MetadataSlotInferenceFn_2 | undefined;
1732
- /**
1733
- * Optional applicability hook for declaration-specific rules beyond
1734
- * declaration kind. `buildContext` may carry compiler objects.
1735
- */
1736
- readonly isApplicable?: ((context: MetadataInferenceContext_2) => boolean) | undefined;
1737
- }
1738
-
1739
- /**
1740
- * Scalar metadata disabled unless provided explicitly elsewhere.
1741
- *
1742
- * @public
1743
- */
1744
- declare interface MetadataValueDisabledPolicyInput$1 {
1745
- /** Disables inference for this scalar metadata value. */
1746
- readonly mode?: "disabled" | undefined;
1747
- /** Optional policy controlling plural forms of this scalar value. */
1748
- readonly pluralization?: MetadataPluralizationPolicyInput$1 | undefined;
1749
- }
1750
-
1751
- /**
1752
- * Scalar metadata may be inferred when missing.
1753
- *
1754
- * @public
1755
- */
1756
- declare interface MetadataValueInferIfMissingPolicyInput$1 {
1757
- /** Infers this scalar metadata value when it is not authored explicitly. */
1758
- readonly mode: "infer-if-missing";
1759
- /** Callback used to infer the missing singular value. */
1760
- readonly infer: MetadataInferenceFn$1;
1761
- /** Optional policy controlling plural forms of this scalar value. */
1762
- readonly pluralization?: MetadataPluralizationPolicyInput$1 | undefined;
1763
- }
1764
-
1765
- /**
1766
- * Scalar metadata policy input.
1767
- *
1768
- * @public
1769
- */
1770
- declare type MetadataValuePolicyInput$1 = MetadataValueDisabledPolicyInput$1 | MetadataValueRequireExplicitPolicyInput$1 | MetadataValueInferIfMissingPolicyInput$1;
1771
-
1772
- /**
1773
- * Scalar metadata must be authored explicitly.
1774
- *
1775
- * @public
1776
- */
1777
- declare interface MetadataValueRequireExplicitPolicyInput$1 {
1778
- /** Requires this scalar metadata value to be authored directly. */
1779
- readonly mode: "require-explicit";
1780
- /** Optional policy controlling plural forms of this scalar value. */
1781
- readonly pluralization?: MetadataPluralizationPolicyInput$1 | undefined;
1782
- }
1783
-
1784
- /**
1785
- * Rule for conditional element visibility/enablement.
1786
- *
1787
- * @public
1788
- */
1789
- declare interface Rule {
1790
- /** UI effect to apply when the rule condition matches. */
1791
- readonly effect: RuleEffect;
1792
- /** Predicate that controls when the UI effect applies. */
1793
- readonly condition: SchemaBasedCondition;
1794
- }
1795
-
1796
- /**
1797
- * JSON Schema subset used in rule conditions.
1798
- *
1799
- * @public
1800
- */
1801
- declare interface RuleConditionSchema {
1802
- /** Literal value the condition schema must equal. */
1803
- const?: unknown;
1804
- /** Allowed values for the condition schema. */
1805
- enum?: readonly unknown[];
1806
- /** JSON Schema type required by the condition schema. */
1807
- type?: string;
1808
- /** Negated branch of the condition schema. */
1809
- not?: RuleConditionSchema;
1810
- /** Inclusive numeric lower bound in the condition schema. */
1811
- minimum?: number;
1812
- /** Inclusive numeric upper bound in the condition schema. */
1813
- maximum?: number;
1814
- /** Exclusive numeric lower bound in the condition schema. */
1815
- exclusiveMinimum?: number;
1816
- /** Exclusive numeric upper bound in the condition schema. */
1817
- exclusiveMaximum?: number;
1818
- /** Inclusive minimum string length in the condition schema. */
1819
- minLength?: number;
1820
- /** Nested property conditions keyed by property name. */
1821
- properties?: Record<string, RuleConditionSchema>;
1822
- /** Property names that must be present for the condition to match. */
1823
- required?: string[];
1824
- /** Schemas that must all match for the condition to succeed. */
1825
- allOf?: RuleConditionSchema[];
1826
- }
1827
-
1828
- /**
1829
- * JSONForms rule constraints.
1830
- *
1831
- * @public
1832
- */
1833
- declare interface RuleConstraints {
1834
- /** Whether rules are enabled at all */
1835
- enabled?: Severity;
1836
- /** Fine-grained control over rule effects */
1837
- effects?: RuleEffectConstraints;
1838
- }
1839
-
1840
- /**
1841
- * JSON Forms UI Schema type definitions.
1842
- *
1843
- * These are the consumer-facing TypeScript shapes. Runtime validation remains
1844
- * defined separately in `./schema.ts`.
1845
- *
1846
- * See: https://jsonforms.io/docs/uischema/
1847
- */
1848
- /**
1849
- * Rule effect types for conditional visibility.
1850
- *
1851
- * @public
1852
- */
1853
- declare type RuleEffect = "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
1854
-
1855
- /**
1856
- * JSONForms rule effect constraints.
1857
- *
1858
- * @public
1859
- */
1860
- declare interface RuleEffectConstraints {
1861
- /** SHOW - show element when condition is true */
1862
- SHOW?: Severity;
1863
- /** HIDE - hide element when condition is true */
1864
- HIDE?: Severity;
1865
- /** ENABLE - enable element when condition is true */
1866
- ENABLE?: Severity;
1867
- /** DISABLE - disable element when condition is true */
1868
- DISABLE?: Severity;
1869
- }
1870
-
1871
- /**
1872
- * Condition for a rule.
1873
- *
1874
- * @public
1875
- */
1876
- declare interface SchemaBasedCondition {
1877
- /** JSON Pointer scope the rule evaluates against. */
1878
- readonly scope: string;
1879
- /** JSON Schema fragment evaluated at the scoped location. */
1880
- readonly schema: RuleConditionSchema;
1881
- }
1882
-
1883
- /**
1884
- * Severity level for constraint violations.
1885
- * - "error": Violation fails validation
1886
- * - "warn": Violation emits warning but passes
1887
- * - "off": Feature is allowed (no violation)
1888
- *
1889
- * @public
1890
- */
1891
- declare type Severity = "error" | "warn" | "off";
1892
-
1893
- /**
1894
- * Shared options for schema generation flows that support custom extensions.
1895
- *
1896
- * @public
1897
- */
1898
- declare interface StaticSchemaGenerationOptions {
1899
- /**
1900
- * FormSpec project configuration. When provided, resolves `extensionRegistry`,
1901
- * `vendorPrefix`, `enumSerialization`, and `metadata` from the config object.
1902
- * Direct options take precedence over config values.
1903
- */
1904
- readonly config?: FormSpecConfig | undefined;
1905
- /**
1906
- * Registry used to resolve custom types, constraints, and annotations.
1907
- * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
1908
- */
1909
- readonly extensionRegistry?: ExtensionRegistry | undefined;
1910
- /**
1911
- * Vendor prefix for emitted extension keywords.
1912
- * @defaultValue "x-formspec"
1913
- * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
1914
- */
1915
- readonly vendorPrefix?: string | undefined;
1916
- /**
1917
- * JSON Schema representation to use for static enums.
1918
- * @defaultValue "enum"
1919
- * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
1920
- */
1921
- readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
1922
- /**
1923
- * Metadata resolution policy for static schema generation.
1924
- * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
1925
- */
1926
- readonly metadata?: MetadataPolicyInput$1 | undefined;
1927
- /** Discriminator-specific schema generation behavior. */
1928
- readonly discriminator?: DiscriminatorResolutionOptions | undefined;
1929
- /**
1930
- * Absolute path to the FormSpec config file (e.g., `formspec.config.ts`).
1931
- *
1932
- * When provided alongside a `config` that includes extensions, the build
1933
- * pipeline includes the config file in the TypeScript program and extracts
1934
- * `defineCustomType<T>()` type parameters. This enables symbol-based custom
1935
- * type detection — the most precise resolution path, immune to import aliases
1936
- * and name collisions.
1937
- *
1938
- * Obtain this from `loadFormSpecConfig()`:
1939
- * ```typescript
1940
- * const { config, configPath } = await loadFormSpecConfig();
1941
- * await generateSchemas({ filePath, typeName, config, configPath, errorReporting: "throw" });
1942
- * ```
1943
- */
1944
- readonly configPath?: string | undefined;
1945
- }
1946
-
1947
-
1948
- /**
1949
- * Root UI Schema (always a layout — not a Control, Category, or Label).
1950
- *
1951
- * @public
1952
- */
1953
- declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout | Categorization;
1954
-
1955
- /**
1956
- * UI Schema feature constraints - control JSONForms-specific features.
1957
- *
1958
- * @public
1959
- */
1960
- declare interface UISchemaConstraints {
1961
- /** Layout type constraints */
1962
- layouts?: LayoutTypeConstraints;
1963
- /** Rule (conditional) constraints */
1964
- rules?: RuleConstraints;
1965
- }
1966
-
1967
- /**
1968
- * Union of all UI Schema element types.
1969
- *
1970
- * @public
1971
- */
1972
- declare type UISchemaElement = ControlElement | VerticalLayout | HorizontalLayout | GroupLayout | Categorization | Category | LabelElement;
1973
-
1974
- /**
1975
- * A vertical layout element.
1976
- *
1977
- * @public
1978
- */
1979
- declare interface VerticalLayout {
1980
- /** Discriminator identifying a vertical layout container. */
1981
- readonly type: "VerticalLayout";
1982
- /** Child elements rendered in vertical order. */
1983
- readonly elements: UISchemaElement[];
1984
- /** Optional rule controlling visibility or enablement. */
1985
- readonly rule?: Rule | undefined;
1986
- /** Renderer-specific layout options. */
1987
- readonly options?: Record<string, unknown> | undefined;
1988
- /** Additional renderer-specific extension properties. */
1989
- readonly [k: string]: unknown;
1990
- }
1991
-
1992
- /**
1993
- * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
1994
- *
1995
- * @public
1996
- */
1997
- declare interface VocabularyKeywordRegistration$1 {
1998
- /** The keyword name (without vendor prefix). */
1999
- readonly keyword: string;
2000
- /** JSON Schema that describes the valid values for this keyword. */
2001
- readonly schema: ExtensionPayloadValue$1;
2002
- }
2003
-
2004
- /**
2005
- * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
2006
- *
2007
- * @public
2008
- */
2009
- declare interface VocabularyKeywordRegistration_2 {
2010
- /** The keyword name (without vendor prefix). */
2011
- readonly keyword: string;
2012
- /** JSON Schema that describes the valid values for this keyword. */
2013
- readonly schema: ExtensionPayloadValue_2;
2014
- }
2015
-
2016
1
  /**
2017
- * Generates JSON Schema and UI Schema using Stripe's canonical config.
2
+ * `@stripe/extensibility-jsonschema-tools`
2018
3
  *
2019
- * Passes {@link _stripeFormSpecConfig} via the `config` field so formspec's
2020
- * internal `resolveOptions` handles extension registry, metadata policy,
2021
- * and enum serialization consistently.
4
+ * Build-time tooling for JSON Schema form specifications.
5
+ * Includes schema generation from TypeScript classes and interfaces
6
+ * annotated with JSDoc constraint tags.
2022
7
  *
2023
- * @internal
8
+ * @packageDocumentation
2024
9
  */
2025
- declare function _generateSchemas(options: Omit<GenerateSchemasOptions, 'errorReporting'>): GenerateFromClassResult;
2026
-
2027
- /**
2028
- * Post-processes a generated JSON Schema to fix path-targeted constraints on
2029
- * Decimal sub-properties. Mutates the schema in place for efficiency.
2030
- *
2031
- * When formspec emits `$ref` + sibling `properties` for path-targeted
2032
- * constraints, any numeric constraint keywords targeting a Decimal sub-property
2033
- * must be broadened to the corresponding `decimal*` keyword with a string value.
2034
- *
2035
- * @internal
2036
- */
2037
- declare function _fixupDecimalPathConstraints(schema: JsonSchema2020): JsonSchema2020;
2038
-
2039
- /**
2040
- * Registration for mapping a built-in TSDoc tag onto a custom constraint when
2041
- * it is used on a particular custom type.
2042
- *
2043
- * @public
2044
- */
2045
- declare interface BuiltinConstraintBroadeningRegistration {
2046
- /** The built-in tag being broadened, without the `@` prefix. */
2047
- readonly tagName: BuiltinConstraintName;
2048
- /** The custom constraint to emit for this built-in tag. */
2049
- readonly constraintName: string;
2050
- /** Parser from raw TSDoc text to extension payload. */
2051
- readonly parseValue: (raw: string) => ExtensionPayloadValue;
2052
- }
2053
-
2054
- /**
2055
- * Type of a built-in constraint name.
2056
- *
2057
- * @public
2058
- */
2059
- declare type BuiltinConstraintName = "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "minItems" | "maxItems" | "uniqueItems" | "pattern" | "const" | "enumOptions";
2060
-
2061
- /* Excluded from this release type: ConditionalLayoutNode */
2062
-
2063
- /* Excluded from this release type: ConstConstraintNode */
2064
-
2065
- /* Excluded from this release type: ConstraintNode */
2066
-
2067
- /**
2068
- * Semantic metadata for ordered custom constraints that should participate in
2069
- * the generic contradiction/broadening logic.
2070
- *
2071
- * @public
2072
- */
2073
- declare interface ConstraintSemanticRole {
2074
- /**
2075
- * Logical family identifier shared by related constraints, for example
2076
- * `"decimal-bound"` or `"date-bound"`.
2077
- */
2078
- readonly family: string;
2079
- /** Whether this constraint acts as a lower or upper bound. */
2080
- readonly bound: "lower" | "upper" | "exact";
2081
- /** Whether equality is allowed when comparing against the bound. */
2082
- readonly inclusive: boolean;
2083
- }
2084
-
2085
- /**
2086
- * Declarative authoring-side registration for a custom TSDoc constraint tag.
2087
- *
2088
- * @public
2089
- */
2090
- declare interface ConstraintTagRegistration {
2091
- /** Tag name without the `@` prefix, e.g. `"maxSigFig"`. */
2092
- readonly tagName: string;
2093
- /** The custom constraint that this tag should produce. */
2094
- readonly constraintName: string;
2095
- /** Parser from raw TSDoc text to JSON-serializable payload. */
2096
- readonly parseValue: (raw: string) => ExtensionPayloadValue;
2097
- /**
2098
- * Optional precise applicability predicate for the field type being parsed.
2099
- * When omitted, the target custom constraint registration controls type
2100
- * applicability during validation.
2101
- */
2102
- readonly isApplicableToType?: (type: ExtensionApplicableType) => boolean;
2103
- }
2104
-
2105
- /* Excluded from this release type: CustomAnnotationNode */
2106
-
2107
- /**
2108
- * Registration for a custom annotation that may produce JSON Schema keywords.
2109
- *
2110
- * Custom annotations are referenced by FormSpec's internal custom-annotation nodes.
2111
- * They describe or present a field but do not affect which values are valid.
2112
- *
2113
- * @public
2114
- */
2115
- declare interface CustomAnnotationRegistration {
2116
- /** The annotation name, unique within the extension. */
2117
- readonly annotationName: string;
2118
- /**
2119
- * Optionally converts the annotation value into JSON Schema keywords.
2120
- * If omitted, the annotation has no JSON Schema representation (UI-only).
2121
- */
2122
- readonly toJsonSchema?: (value: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
2123
- }
2124
-
2125
- /* Excluded from this release type: CustomConstraintNode */
2126
-
2127
- /**
2128
- * Registration for a custom constraint that maps to JSON Schema keywords.
2129
- *
2130
- * Custom constraints are referenced by FormSpec's internal custom-constraint nodes.
2131
- *
2132
- * @public
2133
- */
2134
- declare interface CustomConstraintRegistration {
2135
- /** The constraint name, unique within the extension. */
2136
- readonly constraintName: string;
2137
- /**
2138
- * How this constraint composes with other constraints of the same kind.
2139
- * - "intersect": combine with logical AND (both must hold)
2140
- * - "override": last writer wins
2141
- */
2142
- readonly compositionRule: "intersect" | "override";
2143
- /**
2144
- * TypeNode kinds this constraint is applicable to, or `null` for any type.
2145
- * Used by the validator to emit TYPE_MISMATCH diagnostics.
2146
- */
2147
- readonly applicableTypes: readonly ExtensionApplicableType["kind"][] | null;
2148
- /**
2149
- * Optional precise type predicate used when kind-level applicability is too
2150
- * broad (for example, constraints that apply to integer-like primitives but
2151
- * not strings).
2152
- */
2153
- readonly isApplicableToType?: (type: ExtensionApplicableType) => boolean;
2154
- /**
2155
- * Optional comparator for payloads belonging to the same custom constraint.
2156
- * Return values follow the `Array.prototype.sort()` contract.
2157
- */
2158
- readonly comparePayloads?: (left: ExtensionPayloadValue, right: ExtensionPayloadValue) => number;
2159
- /**
2160
- * Optional semantic family metadata for generic contradiction/broadening
2161
- * handling across ordered constraints.
2162
- */
2163
- readonly semanticRole?: ConstraintSemanticRole;
2164
- /**
2165
- * Converts the custom constraint's payload into JSON Schema keywords.
2166
- *
2167
- * @param payload - The opaque JSON payload stored on the custom constraint node.
2168
- * @param vendorPrefix - The vendor prefix for extension keywords.
2169
- * @returns A JSON Schema fragment with the constraint keywords.
2170
- */
2171
- readonly toJsonSchema: (payload: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
2172
- /**
2173
- * When true, `toJsonSchema` may emit vocabulary keywords that do not carry
2174
- * the vendor prefix. By default, all keys returned from `toJsonSchema` must
2175
- * start with `${vendorPrefix}-`; setting this flag relaxes that check so
2176
- * the constraint can produce standard or custom vocabulary keywords such as
2177
- * `decimalMinimum`.
2178
- *
2179
- * Use this for constraints that define their own JSON Schema vocabulary
2180
- * rather than namespacing under the vendor prefix.
2181
- */
2182
- readonly emitsVocabularyKeywords?: boolean;
2183
- }
2184
-
2185
- /* Excluded from this release type: CustomTypeNode */
2186
-
2187
- /**
2188
- * Registration for a custom type that maps to a JSON Schema representation.
2189
- *
2190
- * Custom types are referenced by FormSpec's internal custom-type IR nodes and
2191
- * resolved to JSON Schema via `toJsonSchema` during generation.
2192
- *
2193
- * @public
2194
- */
2195
- declare interface CustomTypeRegistration {
2196
- /** The type name, unique within the extension. */
2197
- readonly typeName: string;
2198
- /**
2199
- * Optional TypeScript surface names that should resolve to this custom type
2200
- * during TSDoc/class analysis. Defaults to `typeName` when omitted.
2201
- * @deprecated Prefer `brand` for structural detection or type parameters
2202
- * on `defineCustomType<T>()` for symbol-based detection. String name
2203
- * matching will be removed in a future major version.
2204
- */
2205
- readonly tsTypeNames?: readonly string[];
2206
- /**
2207
- * Optional brand identifier for structural type detection.
2208
- *
2209
- * When provided, the type resolver checks `type.getProperties()` for a
2210
- * computed property whose name matches this identifier. This is more
2211
- * reliable than `tsTypeNames` for aliased branded types because it does not
2212
- * depend on the local type name.
2213
- *
2214
- * Brand detection is attempted after name-based resolution (`tsTypeNames`)
2215
- * as a structural fallback. If both match, name-based resolution wins.
2216
- *
2217
- * The value should match the identifier text of a `unique symbol` declaration
2218
- * used as a computed property key on the branded type. For example, if the
2219
- * type is `string & { readonly [__decimalBrand]: true }`, the brand is
2220
- * `"__decimalBrand"`.
2221
- *
2222
- * Brand identifiers are stored as plain strings in the extension registry, so
2223
- * they must be unique across the extensions loaded into the same build.
2224
- *
2225
- * Note: `"__integerBrand"` is reserved for the builtin Integer type.
2226
- */
2227
- readonly brand?: string;
2228
- /**
2229
- * Converts the custom type's payload into a JSON Schema fragment.
2230
- *
2231
- * @param payload - The opaque JSON payload stored on the custom type node.
2232
- * @param vendorPrefix - The vendor prefix for extension keywords (e.g., "x-stripe").
2233
- * @returns A JSON Schema fragment representing this type.
2234
- */
2235
- readonly toJsonSchema: (payload: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
2236
- /* Excluded from this release type: serializeDefault */
2237
- /**
2238
- * Optional broadening of built-in constraint tags so they can apply to this
2239
- * custom type without modifying the core built-in constraint tables.
2240
- */
2241
- readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration[];
2242
- }
2243
-
2244
- /**
2245
- * Per-declaration metadata policy input.
2246
- *
2247
- * @public
2248
- */
2249
- declare interface DeclarationMetadataPolicyInput {
2250
- /** Policy for JSON-facing serialized names. */
2251
- readonly apiName?: MetadataValuePolicyInput | undefined;
2252
- /** Policy for human-facing labels and titles. */
2253
- readonly displayName?: MetadataValuePolicyInput | undefined;
2254
- }
2255
-
2256
- /* Excluded from this release type: DynamicTypeNode */
2257
-
2258
- /* Excluded from this release type: EnumMember */
2259
-
2260
- /* Excluded from this release type: EnumMemberConstraintNode */
2261
-
2262
- /**
2263
- * Enum-member display names remain unset unless authored explicitly.
2264
- *
2265
- * @public
2266
- */
2267
- declare interface EnumMemberDisplayNameDisabledPolicyInput {
2268
- /** Leaves missing enum-member display names unresolved. */
2269
- readonly mode: "disabled";
2270
- }
2271
-
2272
- /**
2273
- * Missing enum-member display names may be inferred.
2274
- *
2275
- * @public
2276
- */
2277
- declare interface EnumMemberDisplayNameInferIfMissingPolicyInput {
2278
- /** Infers an enum-member display name when it is not authored explicitly. */
2279
- readonly mode: "infer-if-missing";
2280
- /** Callback used to infer the missing display name. */
2281
- readonly infer: EnumMemberMetadataInferenceFn;
2282
- }
2283
-
2284
- /**
2285
- * Enum-member display-name policy input.
2286
- *
2287
- * @public
2288
- */
2289
- declare type EnumMemberDisplayNamePolicyInput = EnumMemberDisplayNameDisabledPolicyInput | EnumMemberDisplayNameRequireExplicitPolicyInput | EnumMemberDisplayNameInferIfMissingPolicyInput;
2290
-
2291
- /**
2292
- * Enum members must declare display names explicitly.
2293
- *
2294
- * @public
2295
- */
2296
- declare interface EnumMemberDisplayNameRequireExplicitPolicyInput {
2297
- /** Fails when an enum member has no authored display name. */
2298
- readonly mode: "require-explicit";
2299
- }
2300
-
2301
- /**
2302
- * Build-facing context passed to enum-member metadata inference callbacks.
2303
- *
2304
- * Enum members are resolved separately from declaration-level metadata so they
2305
- * do not participate in the shared declaration-kind model used by TSDoc and
2306
- * extension metadata slots.
2307
- *
2308
- * @public
2309
- */
2310
- declare interface EnumMemberMetadataInferenceContext {
2311
- /** Authoring surface the enum originated from. */
2312
- readonly surface: MetadataAuthoringSurface;
2313
- /** Logical member identifier used for policy inference. */
2314
- readonly logicalName: string;
2315
- /** Underlying enum value before stringification. */
2316
- readonly memberValue: string | number;
2317
- /** Optional build-only context supplied by the resolver. */
2318
- readonly buildContext?: unknown;
2319
- }
2320
-
2321
- /**
2322
- * Callback used to infer enum-member display names.
2323
- *
2324
- * @public
2325
- */
2326
- declare type EnumMemberMetadataInferenceFn = (context: EnumMemberMetadataInferenceContext) => string;
2327
-
2328
- /**
2329
- * User-facing enum-member metadata policy input.
2330
- *
2331
- * @public
2332
- */
2333
- declare interface EnumMemberMetadataPolicyInput {
2334
- /** Policy for human-facing enum-member labels. */
2335
- readonly displayName?: EnumMemberDisplayNamePolicyInput | undefined;
2336
- }
2337
-
2338
- /**
2339
- * A curated type shape exposed to extension applicability hooks.
2340
- *
2341
- * This intentionally exposes only the fields needed to determine tag/type
2342
- * applicability without committing the entire canonical IR as public API.
2343
- *
2344
- * @public
2345
- */
2346
- declare type ExtensionApplicableType = {
2347
- readonly kind: "primitive";
2348
- readonly primitiveKind: "string" | "number" | "integer" | "bigint" | "boolean" | "null";
2349
- } | {
2350
- readonly kind: "custom";
2351
- readonly typeId: string;
2352
- readonly payload: ExtensionPayloadValue;
2353
- } | {
2354
- readonly kind: Exclude<ExtensionTypeKind, "primitive" | "custom">;
2355
- };
2356
-
2357
- /**
2358
- * A complete extension definition bundling types, constraints, annotations,
2359
- * and vocabulary keywords.
2360
- *
2361
- * @example
2362
- * ```typescript
2363
- * const monetaryExtension = defineExtension({
2364
- * extensionId: "x-stripe/monetary",
2365
- * types: [
2366
- * defineCustomType({
2367
- * typeName: "Decimal",
2368
- * toJsonSchema: (_payload, prefix) => ({
2369
- * type: "string",
2370
- * [`${prefix}-decimal`]: true,
2371
- * }),
2372
- * }),
2373
- * ],
2374
- * });
2375
- * ```
2376
- *
2377
- * @public
2378
- */
2379
- declare interface ExtensionDefinition {
2380
- /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
2381
- readonly extensionId: string;
2382
- /** Custom type registrations provided by this extension. */
2383
- readonly types?: readonly CustomTypeRegistration[];
2384
- /** Custom constraint registrations provided by this extension. */
2385
- readonly constraints?: readonly CustomConstraintRegistration[];
2386
- /** Authoring-side TSDoc tag registrations provided by this extension. */
2387
- readonly constraintTags?: readonly ConstraintTagRegistration[];
2388
- /** Metadata-slot registrations shared by build- and lint-time analysis. */
2389
- readonly metadataSlots?: readonly MetadataSlotRegistration[];
2390
- /** Custom annotation registrations provided by this extension. */
2391
- readonly annotations?: readonly CustomAnnotationRegistration[];
2392
- /** Vocabulary keyword registrations provided by this extension. */
2393
- readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];
2394
- }
2395
-
2396
- /**
2397
- * A JSON-serializable payload value used by extension registration hooks.
2398
- *
2399
- * @public
2400
- */
2401
- declare type ExtensionPayloadValue = null | boolean | number | string | readonly ExtensionPayloadValue[] | {
2402
- readonly [key: string]: ExtensionPayloadValue;
2403
- };
2404
-
2405
- /**
2406
- * Top-level type kinds that extension applicability hooks may inspect.
2407
- *
2408
- * @public
2409
- */
2410
- declare type ExtensionTypeKind = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
2411
-
2412
- /**
2413
- * Authoring surfaces that can contribute metadata.
2414
- *
2415
- * @public
2416
- */
2417
- declare type MetadataAuthoringSurface = "tsdoc" | "chain-dsl";
2418
-
2419
- /**
2420
- * Declaration categories that metadata policy can target.
2421
- *
2422
- * @public
2423
- */
2424
- declare type MetadataDeclarationKind = "type" | "field" | "method";
2425
-
2426
- /**
2427
- * Build-facing context passed to metadata inference callbacks.
2428
- *
2429
- * `buildContext` is intentionally opaque so browser/runtime packages do not
2430
- * need to depend on TypeScript compiler types.
2431
- *
2432
- * @public
2433
- */
2434
- declare interface MetadataInferenceContext {
2435
- /** Authoring surface the metadata is being resolved for. */
2436
- readonly surface: MetadataAuthoringSurface;
2437
- /** Declaration kind currently being resolved. */
2438
- readonly declarationKind: MetadataDeclarationKind;
2439
- /** Logical identifier before any metadata policy is applied. */
2440
- readonly logicalName: string;
2441
- /** Optional build-only context supplied by the resolver. */
2442
- readonly buildContext?: unknown;
2443
- }
2444
-
2445
- /**
2446
- * Callback used to infer a scalar metadata value.
2447
- *
2448
- * @public
2449
- */
2450
- declare type MetadataInferenceFn = (context: MetadataInferenceContext) => string;
2451
-
2452
- /**
2453
- * Context passed to pluralization callbacks.
2454
- *
2455
- * @public
2456
- */
2457
- declare interface MetadataPluralizationContext extends MetadataInferenceContext {
2458
- /** Singular value that pluralization should derive from. */
2459
- readonly singular: string;
2460
- }
2461
-
2462
- /**
2463
- * Pluralization disabled.
2464
- *
2465
- * @public
2466
- */
2467
- declare interface MetadataPluralizationDisabledPolicyInput {
2468
- /** Disables automatic plural-value generation. */
2469
- readonly mode?: "disabled" | undefined;
2470
- }
2471
-
2472
- /**
2473
- * Callback used to derive plural metadata from a singular value.
2474
- *
2475
- * @public
2476
- */
2477
- declare type MetadataPluralizationFn = (context: MetadataPluralizationContext) => string;
2478
-
2479
- /**
2480
- * Pluralization may be inferred when absent.
2481
- *
2482
- * @public
2483
- */
2484
- declare interface MetadataPluralizationInferIfMissingPolicyInput {
2485
- /** Infers plural values whenever no explicit plural is present. */
2486
- readonly mode: "infer-if-missing";
2487
- /** Callback that derives a plural form from the resolved singular value. */
2488
- readonly inflect: MetadataPluralizationFn;
2489
- }
2490
-
2491
- /**
2492
- * Pluralization policy input.
2493
- *
2494
- * @public
2495
- */
2496
- declare type MetadataPluralizationPolicyInput = MetadataPluralizationDisabledPolicyInput | MetadataPluralizationRequireExplicitPolicyInput | MetadataPluralizationInferIfMissingPolicyInput;
2497
-
2498
- /**
2499
- * Pluralization must be authored explicitly.
2500
- *
2501
- * @public
2502
- */
2503
- declare interface MetadataPluralizationRequireExplicitPolicyInput {
2504
- /** Requires plural values to be authored directly. */
2505
- readonly mode: "require-explicit";
2506
- }
2507
-
2508
- /**
2509
- * User-facing metadata policy configuration.
2510
- *
2511
- * @public
2512
- */
2513
- declare interface MetadataPolicyInput {
2514
- /** Policy applied to named types and the analyzed root declaration. */
2515
- readonly type?: DeclarationMetadataPolicyInput | undefined;
2516
- /** Policy applied to fields and object properties. */
2517
- readonly field?: DeclarationMetadataPolicyInput | undefined;
2518
- /** Policy applied to callable/method declarations. */
2519
- readonly method?: DeclarationMetadataPolicyInput | undefined;
2520
- /** Policy applied to enum-member display names during build-time IR resolution. */
2521
- readonly enumMember?: EnumMemberMetadataPolicyInput | undefined;
2522
- }
2523
-
2524
- /**
2525
- * Supported qualifier registration for an extensible metadata slot.
2526
- *
2527
- * @public
2528
- */
2529
- declare interface MetadataQualifierRegistration {
2530
- /** Qualifier text without the leading colon. */
2531
- readonly qualifier: string;
2532
- /**
2533
- * Optional source qualifier to use as the base input for this qualifier's
2534
- * inference hook. Defaults to the slot's bare/default value when omitted.
2535
- */
2536
- readonly sourceQualifier?: string | undefined;
2537
- /** Optional inference hook for this qualified value. */
2538
- readonly inferValue?: MetadataSlotInferenceFn | undefined;
2539
- }
2540
-
2541
- /**
2542
- * Stable slot identifier for extensible metadata analysis.
2543
- *
2544
- * @public
2545
- */
2546
- declare type MetadataSlotId = string;
2547
-
2548
- /**
2549
- * Context passed to extensible metadata inference hooks.
2550
- *
2551
- * @public
2552
- */
2553
- declare interface MetadataSlotInferenceContext extends MetadataInferenceContext {
2554
- /** Stable logical slot identifier. */
2555
- readonly slotId: MetadataSlotId;
2556
- /** Tag name associated with the slot, without the `@` prefix. */
2557
- readonly tagName: string;
2558
- /** Optional qualifier being inferred (for example `plural`). */
2559
- readonly qualifier?: string | undefined;
2560
- /** Resolved bare/default value used as the base input for derived qualifiers. */
2561
- readonly baseValue?: string | undefined;
2562
- }
2563
-
2564
- /**
2565
- * Callback used to infer an extensible metadata slot value.
2566
- *
2567
- * @public
2568
- */
2569
- declare type MetadataSlotInferenceFn = (context: MetadataSlotInferenceContext) => string;
2570
-
2571
- /**
2572
- * Extensible metadata slot definition shared across build- and lint-time analysis.
2573
- *
2574
- * @public
2575
- */
2576
- declare interface MetadataSlotRegistration {
2577
- /** Stable logical slot identifier. */
2578
- readonly slotId: MetadataSlotId;
2579
- /** Tag name associated with this slot, without the `@` prefix. */
2580
- readonly tagName: string;
2581
- /** Declaration kinds where the slot is meaningful. */
2582
- readonly declarationKinds: readonly MetadataDeclarationKind[];
2583
- /** Whether a bare tag without a qualifier is supported. Defaults to true. */
2584
- readonly allowBare?: boolean | undefined;
2585
- /** Supported qualifiers for this slot. */
2586
- readonly qualifiers?: readonly MetadataQualifierRegistration[] | undefined;
2587
- /** Optional inference hook for the bare/default slot value. */
2588
- readonly inferValue?: MetadataSlotInferenceFn | undefined;
2589
- /**
2590
- * Optional applicability hook for declaration-specific rules beyond
2591
- * declaration kind. `buildContext` may carry compiler objects.
2592
- */
2593
- readonly isApplicable?: ((context: MetadataInferenceContext) => boolean) | undefined;
2594
- }
2595
-
2596
- /**
2597
- * Scalar metadata disabled unless provided explicitly elsewhere.
2598
- *
2599
- * @public
2600
- */
2601
- declare interface MetadataValueDisabledPolicyInput {
2602
- /** Disables inference for this scalar metadata value. */
2603
- readonly mode?: "disabled" | undefined;
2604
- /** Optional policy controlling plural forms of this scalar value. */
2605
- readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
2606
- }
2607
-
2608
- /**
2609
- * Scalar metadata may be inferred when missing.
2610
- *
2611
- * @public
2612
- */
2613
- declare interface MetadataValueInferIfMissingPolicyInput {
2614
- /** Infers this scalar metadata value when it is not authored explicitly. */
2615
- readonly mode: "infer-if-missing";
2616
- /** Callback used to infer the missing singular value. */
2617
- readonly infer: MetadataInferenceFn;
2618
- /** Optional policy controlling plural forms of this scalar value. */
2619
- readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
2620
- }
2621
-
2622
- /**
2623
- * Scalar metadata policy input.
2624
- *
2625
- * @public
2626
- */
2627
- declare type MetadataValuePolicyInput = MetadataValueDisabledPolicyInput | MetadataValueRequireExplicitPolicyInput | MetadataValueInferIfMissingPolicyInput;
2628
-
2629
- /**
2630
- * Scalar metadata must be authored explicitly.
2631
- *
2632
- * @public
2633
- */
2634
- declare interface MetadataValueRequireExplicitPolicyInput {
2635
- /** Requires this scalar metadata value to be authored directly. */
2636
- readonly mode: "require-explicit";
2637
- /** Optional policy controlling plural forms of this scalar value. */
2638
- readonly pluralization?: MetadataPluralizationPolicyInput | undefined;
2639
- }
2640
-
2641
- /**
2642
- * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
2643
- *
2644
- * @public
2645
- */
2646
- declare interface VocabularyKeywordRegistration {
2647
- /** The keyword name (without vendor prefix). */
2648
- readonly keyword: string;
2649
- /** JSON Schema that describes the valid values for this keyword. */
2650
- readonly schema: ExtensionPayloadValue;
2651
- }
2652
-
2653
- /**
2654
- * Extract config type schemas from extension class exports.
2655
- *
2656
- * Given a file path and export name, resolves the class declaration,
2657
- * walks its `implements` clause to find generic type arguments, and
2658
- * extracts JSON Schema + UI Schema from each config type.
2659
- */
2660
-
2661
- /**
2662
- * Options for extracting config schemas from a class export.
2663
- *
2664
- * @internal
2665
- */
2666
- interface _ExtractConfigSchemasOptions {
2667
- /** Absolute path to the TypeScript source file */
2668
- filePath: string;
2669
- /**
2670
- * Export name to resolve. Use `"default"` for the file's default export,
2671
- * or a named export identifier (e.g., `"LoyaltyDiscount"`).
2672
- */
2673
- exportName: string;
2674
- }
2675
- /**
2676
- * UI schema describing how to render a configuration form.
2677
- *
2678
- * @internal
2679
- */
2680
- type _ConfigUiSchema = UISchema;
2681
- /**
2682
- * A single config schema extracted from a generic type argument.
2683
- *
2684
- * @internal
2685
- */
2686
- interface _ConfigSchemaResult {
2687
- /** Name of the interface whose generic type argument was resolved */
2688
- interfaceName: string;
2689
- /** Name of the resolved config type */
2690
- typeName: string;
2691
- /** Absolute path to the source file that defines the config type */
2692
- sourceFilePath: string;
2693
- /** JSON Schema for validation */
2694
- jsonSchema: JsonSchema2020;
2695
- /** UI Schema for rendering */
2696
- uiSchema: _ConfigUiSchema;
2697
- }
2698
- /**
2699
- * Result of extracting config schemas from a class export.
2700
- *
2701
- * @internal
2702
- */
2703
- interface _ExtractConfigSchemasResult {
2704
- /** Config schemas extracted from the class's `implements` clauses */
2705
- schemas: _ConfigSchemaResult[];
2706
- }
2707
- /**
2708
- * A resolved type argument from an `implements` clause.
2709
- *
2710
- * @internal
2711
- */
2712
- interface _ConfigTypeRef {
2713
- /** Name of the interface whose generic type argument was resolved */
2714
- interfaceName: string;
2715
- /** Name of the resolved config type */
2716
- typeName: string;
2717
- /** Absolute path to the source file that defines the config type */
2718
- sourceFilePath: string;
2719
- }
2720
- /**
2721
- * Resolves the generic type arguments from a class's `implements` clause.
2722
- *
2723
- * Given a file and export name, this function:
2724
- * 1. Resolves the exported class declaration
2725
- * 2. Walks its `implements` clauses to find generic type arguments
2726
- * 3. Returns a `ConfigTypeRef` for each resolved type argument
2727
- *
2728
- * Primitive and anonymous type arguments (no resolvable symbol) are silently
2729
- * skipped. Use this when you need the type locations but not the JSON Schema.
2730
- *
2731
- * @example
2732
- * ```typescript
2733
- * // Given: export class LoyaltyDiscount implements DiscountCalculation<LoyaltyDiscountConfig>
2734
- * const refs = resolveConfigTypeArgs({ filePath: '...', exportName: 'default' });
2735
- * // refs[0].typeName === 'LoyaltyDiscountConfig'
2736
- * ```
2737
- *
2738
- * @param options - File path and export name
2739
- * @returns Array of resolved config type references
2740
- * @throws If the export name is not found (lists available exports).
2741
- * @throws If the export exists but is not a class declaration.
2742
- *
2743
- * @internal
2744
- */
2745
- declare function _resolveConfigTypeArgs(options: _ExtractConfigSchemasOptions): _ConfigTypeRef[];
2746
- /**
2747
- * Extracts config schemas from the generic type arguments in a class's
2748
- * `implements` clause.
2749
- *
2750
- * Calls `resolveConfigTypeArgs` then runs `generateSchemas` on each result.
2751
- * Use `resolveConfigTypeArgs` directly when you need the type locations but
2752
- * not the JSON Schema.
2753
- *
2754
- * @param options - File path and export name
2755
- * @returns Envelope containing an array of config schema results
2756
- * @throws If the export name is not found (lists available exports).
2757
- * @throws If the export exists but is not a class declaration.
2758
- *
2759
- * @internal
2760
- */
2761
- declare function _extractConfigSchemas(options: _ExtractConfigSchemasOptions): _ExtractConfigSchemasResult;
2762
-
2763
- /**
2764
- * FormSpec extension for Stripe stdlib types.
2765
- *
2766
- * Registers custom type handlers for Decimal and other stdlib types so that
2767
- * formspec generates the correct JSON Schema representations.
2768
- */
2769
-
2770
- /**
2771
- * Stripe stdlib extension for FormSpec.
2772
- *
2773
- * Registers the following custom types:
2774
- * - `Decimal` → `{ type: "string", format: "decimal" }` with numeric constraint broadening
2775
- * - `Date` → `{ type: "string", format: "date-time" }`
2776
- *
2777
- * Decimal constraint tags (`@minimum`, `@maximum`, etc.) are broadened to emit
2778
- * custom JSON Schema keywords (`decimalMinimum`, `decimalMaximum`, etc.) with
2779
- * string values to preserve arbitrary decimal precision.
2780
- *
2781
- * Integer and PositiveInteger are handled natively by FormSpec (via `__integerBrand`)
2782
- * and no longer require custom type registration.
2783
- *
2784
- * @internal
2785
- */
2786
- declare const _stripeStdlibExtension: ExtensionDefinition;
2787
- /**
2788
- * Pre-built extension registry containing the Stripe stdlib extension.
2789
- *
2790
- * Pass this to `generateSchemas` to enable proper JSON Schema generation
2791
- * for Stripe stdlib types like `Decimal`.
2792
- *
2793
- * @example
2794
- * ```typescript
2795
- * import { generateSchemas } from '@stripe/extensibility-jsonschema-tools';
2796
- * import { stripeExtensionRegistry } from '@stripe/extensibility-jsonschema-tools';
2797
- *
2798
- * const result = generateSchemas({
2799
- * filePath: './src/config.ts',
2800
- * typeName: 'MyConfig',
2801
- * extensionRegistry: stripeExtensionRegistry,
2802
- * });
2803
- * ```
2804
- *
2805
- * @internal
2806
- */
2807
- declare const _stripeExtensionRegistry: ExtensionRegistry;
2808
-
2809
- /**
2810
- * Canonical Stripe defaults for all FormSpec schema generation.
2811
- *
2812
- * Passes the centralized `_stripeFormSpecConfig` via the `config` field.
2813
- * As of formspec 0.1.0-alpha.46, all schema generation functions
2814
- * (including `generateSchemasFromDeclaration`, `generateSchemasFromType`,
2815
- * etc.) resolve config internally via `resolveStaticOptions()`.
2816
- *
2817
- * @internal
2818
- */
2819
-
2820
10
  /** @internal */
2821
- declare const _stripeSchemaDefaults: StaticSchemaGenerationOptions;
2822
-
2823
- /**
2824
- * Canonical Stripe FormSpecConfig shared by all formspec consumers.
2825
- *
2826
- * Ensures the build system, ESLint plugin, and language server all
2827
- * honor the same extensions, metadata policy, and serialization options.
2828
- *
2829
- * @internal
2830
- */
2831
-
2832
- /**
2833
- * Shared FormSpecConfig for all Stripe formspec consumers (build, ESLint, language server).
2834
- *
2835
- * @internal
2836
- */
2837
- declare const _stripeFormSpecConfig: FormSpecConfig;
2838
-
2839
- export { type BuiltinConstraintBroadeningRegistration, type BuiltinConstraintName, type Categorization, type Category, type ConstraintSemanticRole, type ConstraintTagRegistration, type ControlElement, type CustomAnnotationRegistration, type CustomConstraintRegistration, type CustomTypeRegistration, type DeclarationMetadataPolicyInput, type DiscriminatorResolutionOptions, type EnumMemberMetadataPolicyInput, type ExtensionApplicableType, type ExtensionDefinition, type ExtensionPayloadValue, type ExtensionRegistry, type ExtensionTypeKind, type ExtensionTypeLookupResult, type FormSpecConfig, type GenerateFromClassOptions, type GenerateFromClassResult, type GenerateSchemasOptions, type GroupLayout, type HorizontalLayout, type JsonSchema2020, type LabelElement, type MetadataAuthoringSurface, type MetadataDeclarationKind, type MetadataInferenceContext, type MetadataInferenceFn, type MetadataPluralizationDisabledPolicyInput, type MetadataPluralizationFn, type MetadataPluralizationInferIfMissingPolicyInput, type MetadataPluralizationPolicyInput, type MetadataPluralizationRequireExplicitPolicyInput, type MetadataPolicyInput, type MetadataQualifierRegistration, type MetadataSlotId, type MetadataSlotInferenceContext, type MetadataSlotInferenceFn, type MetadataSlotRegistration, type MetadataValueDisabledPolicyInput, type MetadataValueInferIfMissingPolicyInput, type MetadataValuePolicyInput, type MetadataValueRequireExplicitPolicyInput, type Rule, type RuleConditionSchema, type RuleEffect, type SchemaBasedCondition, type StaticSchemaGenerationOptions, type UISchema, type UISchemaElement, type VerticalLayout, type VocabularyKeywordRegistration, type _ConfigSchemaResult, type _ConfigTypeRef, type _ConfigUiSchema, type _ExtractConfigSchemasOptions, type _ExtractConfigSchemasResult, _extractConfigSchemas, _fixupDecimalPathConstraints, _generateSchemas, _resolveConfigTypeArgs, _stripeExtensionRegistry, _stripeFormSpecConfig, _stripeSchemaDefaults, _stripeStdlibExtension, generateSchemasFromClass };
11
+ export { _generateSchemas } from './generate-schemas.js';
12
+ /** @internal */
13
+ export { _fixupDecimalPathConstraints } from './fixup-decimal-path-constraints.js';
14
+ /** @internal */
15
+ export { generateSchemasFromClass } from '@formspec/build';
16
+ /** @internal */
17
+ export { getSchemaExtension, setSchemaExtension } from '@formspec/build/browser';
18
+ /** @internal */
19
+ export { jsonSchema7Schema, uiSchemaSchema } from '@formspec/build/browser';
20
+ /** @internal */
21
+ export type { JsonSchema2020 } from '@formspec/build';
22
+ /** @internal */
23
+ export type { ExtendedJSONSchema7 } from '@formspec/build/browser';
24
+ /** @internal */
25
+ export type { BuiltinConstraintBroadeningRegistration, BuiltinConstraintName, ConstraintSemanticRole, ConstraintTagRegistration, CustomAnnotationRegistration, CustomConstraintRegistration, CustomTypeRegistration, DeclarationMetadataPolicyInput, EnumMemberMetadataPolicyInput, ExtensionApplicableType, ExtensionDefinition, ExtensionPayloadValue, ExtensionTypeKind, MetadataAuthoringSurface, MetadataPolicyInput, MetadataPluralizationDisabledPolicyInput, MetadataPluralizationFn, MetadataPluralizationInferIfMissingPolicyInput, MetadataPluralizationPolicyInput, MetadataPluralizationRequireExplicitPolicyInput, MetadataQualifierRegistration, MetadataSlotId, MetadataSlotInferenceContext, MetadataSlotInferenceFn, MetadataSlotRegistration, MetadataValuePolicyInput, MetadataDeclarationKind, MetadataInferenceFn, MetadataInferenceContext, MetadataValueDisabledPolicyInput, MetadataValueInferIfMissingPolicyInput, MetadataValueRequireExplicitPolicyInput, VocabularyKeywordRegistration, } from '@formspec/core';
26
+ /** @internal */
27
+ export type { UISchema, UISchemaElement, ControlElement, VerticalLayout, HorizontalLayout, GroupLayout, Categorization, Category, LabelElement, Rule, RuleEffect, RuleConditionSchema, SchemaBasedCondition, } from '@formspec/build';
28
+ /** @internal */
29
+ export type { DiscriminatorResolutionOptions, ExtensionTypeLookupResult, FormSpecConfig, GenerateFromClassOptions, GenerateFromClassResult, GenerateSchemasOptions, StaticSchemaGenerationOptions, ExtensionRegistry, } from '@formspec/build';
30
+ /** @internal */
31
+ export { _resolveConfigTypeArgs, _extractConfigSchemas, type _ConfigTypeRef, type _ExtractConfigSchemasOptions, type _ExtractConfigSchemasResult, type _ConfigSchemaResult, type _ConfigUiSchema, } from './extract-config-schemas.js';
32
+ /** @internal */
33
+ export { _stripeStdlibExtension, _stripeExtensionRegistry } from './stdlib-extension.js';
34
+ /** @internal */
35
+ export { _stripeSchemaDefaults } from './stripe-schema-defaults.js';
36
+ /** @internal */
37
+ export { _stripeFormSpecConfig } from './stripe-formspec-config.js';
38
+ //# sourceMappingURL=index.d.ts.map