@objectstack/sdui-parser 17.2.0 → 17.3.0

package/dist/index.d.ts

@@ -39,7 +39,20 @@ interface ParseResult {
 type ManifestInputType = 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'color' | 'date' | 'code' | 'file' | 'slot';
 interface ManifestInput {
     name: string;
-    type: ManifestInputType;
+    /**
+     * The input's coarse type: ONE kind, or an ARRAY of kinds when the key's
+     * contract is a union (objectui#3832).
+     *
+     * A value passes {@link validateTree}'s coarse check when ANY arm accepts it,
+     * and is reported when none does — the array widens what is legal, it does
+     * not switch the check off.
+     *
+     * The single-kind form is unchanged and stays the canonical spelling for a
+     * one-arm key: `manifestFromConfigs` collapses a one-element array back to
+     * the bare string, so a manifest gains arrays only where a union was really
+     * declared and every already-published entry serializes byte-identically.
+     */
+    type: ManifestInputType | ManifestInputType[];
     required?: boolean;
     /** allowed values for `enum` inputs */
     enum?: Array<string | {
@@ -94,9 +107,25 @@ interface ValidationResult {
 declare function parseJsx(source: string, options?: ParseOptions): ParseResult;
 /**
  * Interpret a braced attribute value `{...}`.
- * JSON-literal values (numbers, booleans, null, strings, arrays, objects with
- * quoted keys) are materialized. Anything else is kept as a deferred expression
- * marker `{ $expr }` — typed and validated later, NEVER evaluated here.
+ *
+ * Strict-JSON values are materialized by `JSON.parse`, exactly as they always
+ * were. Beyond that, the JS **literal subset** below is materialized too
+ * (objectui#6614 Q1-A, maintainer ruling 2026-08-28). Anything left over — a
+ * genuine expression — is kept as the deferred marker `{ $expr }`: typed and
+ * validated later, drawing `inert-expression`, and NEVER evaluated here.
+ *
+ * ORDER IS LOAD-BEARING. `JSON.parse` runs FIRST and is untouched, so every
+ * input JSON accepts takes byte-identically the path it took before the literal
+ * subset existed. The reader below only ever sees strings `JSON.parse` has
+ * already thrown on, which makes strict-JSON invariance a property of the
+ * structure rather than of a test.
+ *
+ * LOCKSTEP: this grammar is the port of objectui's `packages/sdui-parser` copy
+ * (objectui#6614). The two copies must agree on the accepted grammar AND on
+ * diagnostic codes — if they drift, the save gate and the renderer speak
+ * different dialects and a page can save clean and render inert
+ * (objectstack#12719 states the invariant; #12977 carries this half of it).
+ * Change this block only together with the objectui copy.
  */
 declare function interpretBrace(raw: string): unknown;
 
@@ -111,6 +140,128 @@ declare function interpretBrace(raw: string): unknown;
 
 declare function validateTree(tree: SchemaElement | null, manifest: Manifest): ValidationResult;
 
+/**
+ * Unconsumed dashboard-widget `options` keys (objectui#5709), ported into this
+ * copy in lockstep (objectstack#12810).
+ *
+ * `@objectstack/spec`'s `DashboardWidgetOptionsSchema` ends in `.passthrough()`
+ * ("declared query keys + open renderer extras"), so ANY key parses, validates
+ * and lints cleanly — including one no renderer reads. That is how a showcase
+ * dashboard shipped `options: { invert: true }` on a gauge with a comment
+ * saying what it was believed to do, and rendered the un-inverted measure with
+ * no diagnostic anywhere (objectui#5709). The 2026-08-23 maintainer ruling:
+ * open extras stay open — they just stop being SILENT. A key that reaches no
+ * renderer draws a WARNING naming the consumed set. Not an error: no gate
+ * weakening and no new red gates were ruled.
+ *
+ * ## LOCKSTEP — what is byte-equal here and what deliberately is not
+ *
+ * Two copies of this parser exist: objectui's `packages/sdui-parser` and this
+ * hoisted `@objectstack/sdui-parser`. The invariant they owe each other is that
+ * both agree on the accepted grammar AND on diagnostic codes — if they drift,
+ * the save gate and the renderer speak different dialects and a page can save
+ * clean and render inert, or the reverse (objectstack#12719, objectstack#12810).
+ *
+ * Everything from the `import` line below to end of file is a byte-equal port of
+ * objectui's `src/dashboard-widget-options.ts` SAVE FOR ONE TOKEN, called out
+ * at the site itself: the emitted `code` is spelled as an inline literal here
+ * and as the constant there, because this repo runs a vocabulary gate objectui
+ * does not. The emitted `code`, `severity`, `message` and the whole census
+ * scope are identical, and `__tests__/dashboard-widget-options.test.ts`
+ * re-derives that rather than trusting it — including an explicit pin that the
+ * literal equals `UNCONSUMED_WIDGET_OPTION`. Change these functions only
+ * together with the objectui copy.
+ *
+ * THIS HEADER is the one deliberate divergence, and it has to be: objectui's
+ * header cites the maintenance machinery that derives the census — its
+ * `DatasetWidget.tsx` / `DashboardRenderer.tsx` read sites, its
+ * `plugin-dashboard.mdx` claim and its two census tests. NONE of those files
+ * exists in this repo (measured: no dashboard renderer package here at all), so
+ * copying those sentences would ship claims this checkout cannot support and
+ * nothing here would ever notice them going false. What follows instead states
+ * where each half of the census is derivable, and from what.
+ *
+ * ## The accepted set, and where each half is authoritative
+ *
+ * The spec REQUIRES `dataset` on every widget (`DashboardWidgetSchema`, this
+ * repo: `packages/spec/src/ui/dashboard.zod.ts`), and both of objectui's
+ * dashboard surfaces route a dataset-bound widget to `DatasetWidget`. On that —
+ * the only spec-legal — path the renderer-consumed `options` keys are exactly
+ * the five the spec DECLARES:
+ *
+ *   dateGranularity, sortBy, sortOrder, limit   (query-affecting, framework#3588)
+ *   stageOrder                                  (funnel/pyramid stage order)
+ *
+ * plus ONE undeclared key with a real read site:
+ *
+ *   description — the metric-card sub-caption channel. `translateDashboard`
+ *   OVERLAYS the `widgets.{id}.subCaption` translation onto this key, and that
+ *   pipeline lives IN THIS REPO: `packages/spec/src/system/i18n-resolver.ts`
+ *   documents `WidgetLike.options` as "the renderer-extras bag …
+ *   `translateDashboard` writes exactly one key into it — `description`"
+ *   (objectstack#5428 item 4, objectstack#7862). Warning on a key the
+ *   platform's own translation pipeline writes would be a false positive on
+ *   legal metadata, so it is in the accepted set even though the dataset-bound
+ *   render path does not currently display it.
+ *
+ * Notably NOT consumed on the path a widget really renders through:
+ * `thresholds` and `format`. Both were widely believed to work; both draw this
+ * warning, which is the point. Their closure claims are objectui's to derive —
+ * `thresholds` by a repo-wide read-site scan there, `format` by the bounded
+ * claim that the dataset-bound path formats from the MEASURE's own metadata —
+ * and they are NOT restated here as claims about this repo, which has no
+ * renderer to make them about.
+ *
+ * ## The drift risk that lives on THIS side
+ *
+ * The spec whose `.passthrough()` this reasons about ships from this repo. So
+ * the one way this list can go stale HERE is a new DECLARED key landing in
+ * `DashboardWidgetOptionsSchema` without landing in the array below: the key
+ * would be spec-legal, renderer-consumed on the objectui side, and warned about
+ * here — a false positive on legal metadata. `@objectstack/sdui-parser` takes
+ * no dependency on `@objectstack/spec` (it is dependency-free and hoistable by
+ * design), so that cross-check is not mechanized in this copy; the census test
+ * next door pins the array and names the spec file to re-read when it moves.
+ *
+ * ## Scope — where the warning deliberately does NOT fire
+ *
+ *   - Widgets WITHOUT `dataset`: the legacy inline forms (`options.data`
+ *     arrays, `provider: 'object'` bags) consume a much larger, spread-shaped
+ *     key set, whose true reach is each child component's prop surface. That
+ *     form is spec-illegal today (`dataset` is required) and its census would be
+ *     the unmaintainable one; skipping it keeps every warning this module emits
+ *     a statement about the path the widget actually renders through.
+ *   - Widgets in the legacy COMPONENT format (`widget.component`): `options`
+ *     is not part of that contract.
+ *   - Widgets carrying the spec's own escape hatch
+ *     `suppressWarnings: ['unconsumed-widget-option']` — the spec models
+ *     per-widget diagnostic suppression (`DashboardWidgetSchema.suppressWarnings`,
+ *     "Build diagnostic rule ids suppressed on this widget"), so an author with
+ *     a genuine out-of-band consumer can say so in metadata.
+ */
+
+/** The diagnostic `code` — also the id `suppressWarnings` suppresses. */
+declare const UNCONSUMED_WIDGET_OPTION = "unconsumed-widget-option";
+/**
+ * Component types that host a dashboard `widgets` array. Both resolve to the
+ * surfaces measured by the census above (`DashboardRenderer`,
+ * `DashboardGridLayout`), which share one dispatch (`widgetDispatch.ts`).
+ */
+declare const DASHBOARD_WIDGET_HOST_TYPES: ReadonlySet<string>;
+/**
+ * The accepted set: every `options` key with a renderer read site on the
+ * dataset-bound path, plus the sub-caption convention key. Alphabetical; the
+ * warning message prints it verbatim. Derivation and evidence: file header.
+ */
+declare const CONSUMED_WIDGET_OPTION_KEYS: readonly string[];
+/**
+ * Diagnostics for `options` keys no renderer consumes, over one dashboard-host
+ * node's `widgets` array. Pure and shallow by design: it never descends into
+ * `children` (the caller's walk owns that) and answers `[]` for every shape
+ * outside its census — see the scope notes in the file header.
+ */
+declare function checkDashboardWidgetOptions(node: SchemaElement): Diagnostic[];
+
 /**
  * ObjectUI — codegen the JSX type surface from the registry manifest (ADR-0080 §3)
  *
@@ -135,6 +286,53 @@ declare function propsName(type: string): string;
  */
 declare function generateBlockList(manifest: Manifest): string;
 
+/**
+ * ObjectUI — the arms of a manifest input's coarse type (objectui#3832)
+ *
+ * `ManifestInput.type` carries ONE coarse kind, or an ARRAY of kinds when the
+ * key's contract is a union. Every reader of that field needs the same two
+ * decisions made the same way — how to see the arms, and which single form to
+ * publish — so they live here once instead of at each call site. A reader that
+ * forgets is not loud: `switch (input.type)` handed an array falls through to
+ * the default branch and reports NOTHING, which looks exactly like a value that
+ * validated cleanly.
+ */
+
+/** The eleven coarse kinds, as a runtime set for guarding untyped input. */
+declare const MANIFEST_INPUT_TYPES: ReadonlySet<string>;
+/**
+ * The declared arms of an input's coarse type, always as an array.
+ *
+ * Exported (not merely internal) so a third-party manifest consumer — a
+ * designer panel, a codegen, a validator of its own — reads the arms through
+ * the same accessor this package's own gate does, rather than re-deriving the
+ * `Array.isArray` branch and getting it subtly wrong on the union form.
+ */
+declare function inputTypeArms(type: ManifestInput['type'] | undefined): ManifestInputType[];
+/**
+ * Project a DECLARED type (which may come from an untyped registry config) into
+ * the canonical published form: a bare string for one arm, an array for a real
+ * union.
+ *
+ * Two deliberate asymmetries between the single and array forms:
+ *
+ *  - A single unrecognized kind still becomes `'string'`. That coercion predates
+ *    the union work and is kept exactly: with one arm there is no other
+ *    information to fall back on, and a manifest whose `type` is off-vocabulary
+ *    would make every consumer's switch silently inert.
+ *  - An unrecognized arm INSIDE an array is DROPPED, not coerced. Promoting it
+ *    to `'string'` would publish an arm the author never declared — a widening
+ *    invented by the serializer — and the surviving arms already carry the
+ *    declaration. If dropping empties the array, the single-arm fallback applies
+ *    so the output is always a valid manifest.
+ *
+ * Collapsing one arm to the bare string is what keeps this a backward-compatible
+ * extension of `sdui.manifest.json`: every input declared today serializes to
+ * the byte-identical entry it does now, and arrays appear only where a union was
+ * really declared.
+ */
+declare function canonicalizeInputType(type: unknown): ManifestInputType | ManifestInputType[];
+
 /**
  * @objectstack/sdui-parser — constrained JSX-source → SDUI SchemaNode tree (ADR-0080)
  *
@@ -166,7 +364,14 @@ interface RegistryConfigLike {
     category?: string;
     inputs?: Array<{
         name: string;
-        type: string;
+        /**
+         * One coarse kind, or the arms of a union (objectui#3832). Typed loosely
+         * (`string`) on purpose — this interface is the STRUCTURAL boundary that
+         * keeps this package free of a dependency on the registry, so an
+         * off-vocabulary value has to be representable here and is normalized by
+         * `canonicalizeInputType` on the way in.
+         */
+        type: string | string[];
         required?: boolean;
         enum?: Array<string | {
             value: unknown;
@@ -181,4 +386,4 @@ declare function manifestFromConfigs(configs: RegistryConfigLike[], opts?: {
     publicOnly?: boolean;
 }): Manifest;
 
-export { type CodegenOptions, type CompileResult, type Diagnostic, type Manifest, type ManifestComponent, type ManifestInput, type ManifestInputType, type ParseOptions, type ParseResult, type RegistryConfigLike, type SchemaElement, type SchemaNode, type Severity, type ValidationResult, compile, generateBlockList, generateDts, interpretBrace, manifestFromConfigs, parseJsx, propsName, validateTree };
+export { CONSUMED_WIDGET_OPTION_KEYS, type CodegenOptions, type CompileResult, DASHBOARD_WIDGET_HOST_TYPES, type Diagnostic, MANIFEST_INPUT_TYPES, type Manifest, type ManifestComponent, type ManifestInput, type ManifestInputType, type ParseOptions, type ParseResult, type RegistryConfigLike, type SchemaElement, type SchemaNode, type Severity, UNCONSUMED_WIDGET_OPTION, type ValidationResult, canonicalizeInputType, checkDashboardWidgetOptions, compile, generateBlockList, generateDts, inputTypeArms, interpretBrace, manifestFromConfigs, parseJsx, propsName, validateTree };