@elastic/isomer-sdk 0.0.0 → 0.1.0

package/dist/cjs/validate/validation.js

@@ -0,0 +1,208 @@
+"use strict";
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCompositionParser = exports.createCompositionValidator = exports.compositionToRender = exports.enforceValidationMode = exports.CompositionValidationError = exports.warningsForSurface = void 0;
+const body_node_base_1 = require("../composition/body_node_base");
+const one_line_1 = require("../composition/one_line");
+const validation_error_1 = require("../composition/validation_error");
+Object.defineProperty(exports, "CompositionValidationError", { enumerable: true, get: function () { return validation_error_1.CompositionValidationError; } });
+const composition_schema_1 = require("./composition_schema");
+const input_budget_1 = require("./input_budget");
+const node_issues_1 = require("./node_issues");
+const checkedComposition = Symbol.for('elastic.isomer.checked_composition');
+/** Narrows a result's warnings to the surface a caller is about to render. */
+const warningsForSurface = (result, surface) => result.warnings.filter((warning) => warning.surface === surface);
+exports.warningsForSurface = warningsForSurface;
+/** Raises {@link CompositionValidationError} when `mode` is `throw` and `result` is invalid, or in any mode when {@link checkInputBudget} refused the input, which nothing can render. */
+const enforceValidationMode = (result, mode) => {
+    if (!result.valid &&
+        (mode === 'throw' || result.errors.some(input_budget_1.isInputRefusal))) {
+        throw new validation_error_1.CompositionValidationError(result.errors);
+    }
+};
+exports.enforceValidationMode = enforceValidationMode;
+/** The composition `result` checked, which is what a render draws. Throws {@link CompositionValidationError} when `mode` is `'throw'` and `result` is invalid, or in any mode when {@link checkInputBudget} refused the input. */
+const compositionToRender = (result, mode) => {
+    (0, exports.enforceValidationMode)(result, mode);
+    const { composition } = result;
+    if (composition === undefined) {
+        throw new validation_error_1.CompositionValidationError(result.errors);
+    }
+    return composition;
+};
+exports.compositionToRender = compositionToRender;
+/** The body's nodes, as {@link IssueRoot}s for a node issue formatter. */
+const bodyRoots = (value) => {
+    const { body } = (value ?? {});
+    return Array.isArray(body)
+        ? body.map((node, index) => [node, `body[${index}]`])
+        : [];
+};
+/**
+ * Builds the trusted-input validator: {@link checkInputBudget}, then the schema and the semantic passes on its copy, which the result carries.
+ *
+ * `definitions` is memoized on array identity, so a caller that rebuilds the
+ * array per call (`createCompositionValidator(packs.flatMap(…))`) resolves a
+ * fresh discriminated union each time. Hold the array `composePacks` returns
+ * and reuse it across the validator, the parser, and the authoring context.
+ */
+const createCompositionValidator = (definitions, options = {}) => {
+    const schema = (0, composition_schema_1.getCompositionSchemaForDefinitions)(definitions);
+    const walk = (0, body_node_base_1.createChildNodeWalker)(definitions);
+    const formatIssues = (0, node_issues_1.createNodeIssueFormatter)(definitions);
+    return (composition) => {
+        const checked = (0, input_budget_1.checkInputBudget)(composition, options.inputBudget);
+        if (!checked.valid) {
+            return {
+                valid: false,
+                errors: [checked.error],
+                warnings: [],
+                composition: undefined,
+            };
+        }
+        const plain = checked.value;
+        const result = schema.safeParse(plain, { reportInput: true });
+        if (result.success) {
+            const { body } = plain;
+            const idErrors = collectDuplicateNodeIdErrors(body, walk);
+            const warnings = [
+                ...collectEmptySurfaceWarnings(body, walk),
+                ...(options.sizesFromNodeHeights
+                    ? collectMissingSvgHeightWarnings(body, definitions, walk)
+                    : []),
+            ];
+            return {
+                valid: idErrors.length === 0,
+                errors: idErrors,
+                warnings,
+                composition: plain,
+            };
+        }
+        return {
+            valid: false,
+            errors: formatIssues(bodyRoots(plain), result.error.issues),
+            warnings: [],
+            composition: plain,
+        };
+    };
+};
+exports.createCompositionValidator = createCompositionValidator;
+/**
+ * Builds the untrusted-input parser: {@link checkInputBudget}, then the schema only on its copy, reported rather than thrown.
+ *
+ * Deliberately narrower than {@link createCompositionValidator}. This answers
+ * "is this a `Composition`", not "is this a good one" — it does not run the
+ * duplicate-id pass or produce warnings, so a composition with two nodes
+ * sharing an `id` parses as valid. Id uniqueness is a `validate` guarantee, so
+ * a caller that wants the semantic checks runs `validate` on the result.
+ *
+ * Shares {@link createCompositionValidator}'s memoization identity requirement.
+ */
+const createCompositionParser = (definitions, { inputBudget } = {}) => {
+    const schema = (0, composition_schema_1.getCompositionSchemaForDefinitions)(definitions);
+    const formatIssues = (0, node_issues_1.createNodeIssueFormatter)(definitions);
+    return (value) => {
+        const checked = (0, input_budget_1.checkInputBudget)(value, inputBudget);
+        if (!checked.valid) {
+            return { valid: false, errors: [checked.error] };
+        }
+        const result = schema.safeParse(checked.value, { reportInput: true });
+        if (result.success) {
+            return {
+                valid: true,
+                errors: [],
+                composition: result.data,
+            };
+        }
+        return {
+            valid: false,
+            errors: formatIssues(bodyRoots(checked.value), result.error.issues),
+        };
+    };
+};
+exports.createCompositionParser = createCompositionParser;
+/** Warns once per surface that the whole body renders nothing on. */
+const collectEmptySurfaceWarnings = (body, walk) => body_node_base_1.BODY_NODE_SURFACES.filter((surface) => !body.some((node) => (0, body_node_base_1.rendersOnSurface)(node, surface, walk))).map((surface) => ({
+    surface,
+    message: `composition renders no nodes on surface "${surface}"`,
+}));
+/**
+ * Warns for each node that renders to `svg` but declares no `svgHeight`.
+ *
+ * `metrics.svgHeight` is optional, so `dispatcher.estimateSvgHeight` returns
+ * `0` for such a node and a frame that sums node heights sizes short.
+ *
+ * Whether a runtime consults the metric at all is the caller's to decide; see
+ * {@link CompositionValidatorOptions.sizesFromNodeHeights}. A fixed-size frame
+ * never does, and warning about a value nothing reads is how a warning channel
+ * gets ignored.
+ */
+const collectMissingSvgHeightWarnings = (body, definitions, walk) => {
+    const unmeasured = new Set(definitions
+        .filter((definition) => !definition.metrics?.svgHeight)
+        .map((definition) => definition.type));
+    if (unmeasured.size === 0) {
+        return [];
+    }
+    const warnings = [];
+    const visit = (node, path) => {
+        if (!node || typeof node !== 'object' || !(0, body_node_base_1.isVisibleOnSurface)(node, 'svg')) {
+            return;
+        }
+        const { type } = node;
+        if (typeof type === 'string' && unmeasured.has(type)) {
+            warnings.push({
+                surface: 'svg',
+                path,
+                message: `${path} type ${(0, one_line_1.quoteText)(type)} declares no svgHeight metric and will be measured as 0, sizing the frame short`,
+            });
+        }
+        walk(node).forEach(({ node: child, path: field }) => {
+            visit(child, (0, body_node_base_1.childNodePath)(path, field));
+        });
+    };
+    body.forEach((node, index) => visit(node, `body[${index}]`));
+    return warnings;
+};
+/**
+ * Errors for each node whose `id` repeats one already seen, naming the first
+ * use.
+ *
+ * Errors rather than warnings, because ids are what a host addresses a node by.
+ * Run by `validate` and deliberately not by `parse`; see
+ * {@link createCompositionParser}.
+ */
+const collectDuplicateNodeIdErrors = (body, walk) => {
+    const errors = [];
+    const seen = new Map();
+    const visit = (node, path) => {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        const { id, type } = node;
+        if (typeof id === 'string') {
+            const first = seen.get(id);
+            if (first) {
+                errors.push({
+                    path: `${path}.id`,
+                    message: `duplicates id ${(0, one_line_1.quoteText)(id)} first used at ${first}`,
+                    ...(typeof type === 'string' ? { nodeType: type } : {}),
+                });
+            }
+            else {
+                seen.set(id, path);
+            }
+        }
+        walk(node).forEach(({ node: child, path: field }) => {
+            visit(child, (0, body_node_base_1.childNodePath)(path, field));
+        });
+    };
+    body.forEach((node, index) => visit(node, `body[${index}]`));
+    return errors;
+};
+//# sourceMappingURL=validation.js.map

package/dist/cjs/validate/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/validate/validation.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport {\n  BODY_NODE_SURFACES,\n  childNodePath,\n  createChildNodeWalker,\n  isVisibleOnSurface,\n  rendersOnSurface,\n  type SurfaceName,\n} from '../composition/body_node_base';\nimport type { Composition } from '../composition/composition';\nimport type { PrimitiveNode } from '../composition/node';\nimport { quoteText } from '../composition/one_line';\nimport {\n  CompositionValidationError,\n  type ValidationError,\n} from '../composition/validation_error';\nimport type { AnyPrimitiveDefinition } from '../define/primitive_module';\n\nimport { getCompositionSchemaForDefinitions } from './composition_schema';\nimport {\n  checkInputBudget,\n  type InputBudget,\n  isInputRefusal,\n} from './input_budget';\nimport { createNodeIssueFormatter, type IssueRoot } from './node_issues';\n\n/**\n * A non-fatal validation finding, scoped to the surface it concerns.\n *\n * Warnings carry `surface` because every one of them is a statement about one\n * render target — a composition that draws nothing on `slack` is not news to a\n * caller rendering HTML. Without the scope a host receives every surface's\n * findings on every call and learns to ignore the channel.\n * {@link warningsForSurface} is the filter.\n */\nexport interface ValidationWarning {\n  /** The render target this finding concerns, never the composition as a whole. */\n  surface: SurfaceName;\n  /**\n   * Path of the offending node within the composition, absent for\n   * whole-composition findings.\n   */\n  path?: string;\n  /** Safe to show a user, and phrased for whoever can act on it. */\n  message: string;\n}\n\n/**\n * The outcome of `validate`: errors are fatal, warnings are advisory.\n *\n * `valid` tracks `errors` only — a composition can be valid and still carry\n * warnings, which is the normal case for a surface gap.\n */\nexport interface ValidationResult {\n  /** True when `errors` is empty, regardless of `warnings`. */\n  valid: boolean;\n  /** Fatal findings. Empty when `valid`. */\n  errors: ValidationError[];\n  /** Advisory findings, empty when there are none. */\n  warnings: ValidationWarning[];\n}\n\nconst checkedComposition = Symbol.for('elastic.isomer.checked_composition');\n\n/** The copy {@link createCompositionValidator} checked, which a validating render draws in place of the caller's value. The brand is type-only. */\nexport type CheckedComposition<TNode extends PrimitiveNode = PrimitiveNode> =\n  Composition<TNode> & { readonly [checkedComposition]: true };\n\n/** A {@link ValidationResult} with the composition it describes. */\nexport interface CheckedValidationResult<\n  TNode extends PrimitiveNode = PrimitiveNode,\n> extends ValidationResult {\n  /** Undefined only when {@link checkInputBudget} refused the input. */\n  composition: CheckedComposition<TNode> | undefined;\n}\n\n/** Narrows a result's warnings to the surface a caller is about to render. */\nexport const warningsForSurface = (\n  result: ValidationResult,\n  surface: SurfaceName\n): ValidationWarning[] =>\n  result.warnings.filter((warning) => warning.surface === surface);\n\n/** Whether a render reports validation findings or raises on them. */\nexport type ValidationErrorMode = 'collect' | 'throw';\n\nexport { CompositionValidationError };\n\n/** Raises {@link CompositionValidationError} when `mode` is `throw` and `result` is invalid, or in any mode when {@link checkInputBudget} refused the input, which nothing can render. */\nexport const enforceValidationMode = (\n  result: ValidationResult,\n  mode?: ValidationErrorMode\n): void => {\n  if (\n    !result.valid &&\n    (mode === 'throw' || result.errors.some(isInputRefusal))\n  ) {\n    throw new CompositionValidationError(result.errors);\n  }\n};\n\n/** The composition `result` checked, which is what a render draws. Throws {@link CompositionValidationError} when `mode` is `'throw'` and `result` is invalid, or in any mode when {@link checkInputBudget} refused the input. */\nexport const compositionToRender = <TNode extends PrimitiveNode>(\n  result: CheckedValidationResult<TNode>,\n  mode?: ValidationErrorMode\n): CheckedComposition<TNode> => {\n  enforceValidationMode(result, mode);\n  const { composition } = result;\n  if (composition === undefined) {\n    throw new CompositionValidationError(result.errors);\n  }\n  return composition;\n};\n\n/** Runtime facts the semantic passes need beyond the primitive inventory. */\nexport interface CompositionValidatorOptions {\n  /**\n   * Whether any frame the runtime can draw with sizes itself from node heights,\n   * which is what makes a missing `metrics.svgHeight` matter.\n   *\n   * A runtime-wide question rather than a per-node one, because a frame is a\n   * runtime input: any node can be drawn under any frame, so the metric is\n   * load-bearing as soon as one frame consults it. Defaults to `false`, so a\n   * runtime with no frame at all reports nothing about a value nothing reads.\n   */\n  sizesFromNodeHeights?: boolean;\n  /** Limits checked before the schema runs; see {@link checkInputBudget}. */\n  inputBudget?: InputBudget;\n}\n\n/** The body's nodes, as {@link IssueRoot}s for a node issue formatter. */\nconst bodyRoots = (value: unknown): IssueRoot[] => {\n  const { body } = (value ?? {}) as { body?: unknown };\n  return Array.isArray(body)\n    ? body.map((node, index) => [node, `body[${index}]`] as const)\n    : [];\n};\n\n/**\n * Builds the trusted-input validator: {@link checkInputBudget}, then the schema and the semantic passes on its copy, which the result carries.\n *\n * `definitions` is memoized on array identity, so a caller that rebuilds the\n * array per call (`createCompositionValidator(packs.flatMap(…))`) resolves a\n * fresh discriminated union each time. Hold the array `composePacks` returns\n * and reuse it across the validator, the parser, and the authoring context.\n */\nexport const createCompositionValidator = <\n  TNode extends PrimitiveNode = PrimitiveNode,\n>(\n  definitions: readonly AnyPrimitiveDefinition[],\n  options: CompositionValidatorOptions = {}\n): ((composition: Composition<TNode>) => CheckedValidationResult<TNode>) => {\n  const schema = getCompositionSchemaForDefinitions(definitions);\n  const walk = createChildNodeWalker(definitions);\n  const formatIssues = createNodeIssueFormatter(definitions);\n  return (composition) => {\n    const checked = checkInputBudget(composition, options.inputBudget);\n    if (!checked.valid) {\n      return {\n        valid: false,\n        errors: [checked.error],\n        warnings: [],\n        composition: undefined,\n      };\n    }\n    const plain = checked.value as CheckedComposition<TNode>;\n    const result = schema.safeParse(plain, { reportInput: true });\n    if (result.success) {\n      const { body } = plain;\n      const idErrors = collectDuplicateNodeIdErrors(body, walk);\n      const warnings = [\n        ...collectEmptySurfaceWarnings(body, walk),\n        ...(options.sizesFromNodeHeights\n          ? collectMissingSvgHeightWarnings(body, definitions, walk)\n          : []),\n      ];\n      return {\n        valid: idErrors.length === 0,\n        errors: idErrors,\n        warnings,\n        composition: plain,\n      };\n    }\n    return {\n      valid: false,\n      errors: formatIssues(bodyRoots(plain), result.error.issues),\n      warnings: [],\n      composition: plain,\n    };\n  };\n};\n\n/** The outcome of `parse`. */\nexport interface ParsedComposition {\n  /** True when the value matched the schema. Says nothing about id uniqueness. */\n  valid: boolean;\n  /** Schema failures. Empty when `valid`. */\n  errors: ValidationError[];\n  /** The parsed document, present only when `valid`. */\n  composition?: Composition;\n}\n\n/**\n * Builds the untrusted-input parser: {@link checkInputBudget}, then the schema only on its copy, reported rather than thrown.\n *\n * Deliberately narrower than {@link createCompositionValidator}. This answers\n * \"is this a `Composition`\", not \"is this a good one\" — it does not run the\n * duplicate-id pass or produce warnings, so a composition with two nodes\n * sharing an `id` parses as valid. Id uniqueness is a `validate` guarantee, so\n * a caller that wants the semantic checks runs `validate` on the result.\n *\n * Shares {@link createCompositionValidator}'s memoization identity requirement.\n */\nexport const createCompositionParser = (\n  definitions: readonly AnyPrimitiveDefinition[],\n  { inputBudget }: Pick<CompositionValidatorOptions, 'inputBudget'> = {}\n): ((value: unknown) => ParsedComposition) => {\n  const schema = getCompositionSchemaForDefinitions(definitions);\n  const formatIssues = createNodeIssueFormatter(definitions);\n  return (value) => {\n    const checked = checkInputBudget(value, inputBudget);\n    if (!checked.valid) {\n      return { valid: false, errors: [checked.error] };\n    }\n    const result = schema.safeParse(checked.value, { reportInput: true });\n    if (result.success) {\n      return {\n        valid: true,\n        errors: [],\n        composition: result.data as unknown as Composition,\n      };\n    }\n    return {\n      valid: false,\n      errors: formatIssues(bodyRoots(checked.value), result.error.issues),\n    };\n  };\n};\n\n/** Warns once per surface that the whole body renders nothing on. */\nconst collectEmptySurfaceWarnings = (\n  body: readonly unknown[],\n  walk: ReturnType<typeof createChildNodeWalker>\n): ValidationWarning[] =>\n  BODY_NODE_SURFACES.filter(\n    (surface) => !body.some((node) => rendersOnSurface(node, surface, walk))\n  ).map((surface) => ({\n    surface,\n    message: `composition renders no nodes on surface \"${surface}\"`,\n  }));\n\n/**\n * Warns for each node that renders to `svg` but declares no `svgHeight`.\n *\n * `metrics.svgHeight` is optional, so `dispatcher.estimateSvgHeight` returns\n * `0` for such a node and a frame that sums node heights sizes short.\n *\n * Whether a runtime consults the metric at all is the caller's to decide; see\n * {@link CompositionValidatorOptions.sizesFromNodeHeights}. A fixed-size frame\n * never does, and warning about a value nothing reads is how a warning channel\n * gets ignored.\n */\nconst collectMissingSvgHeightWarnings = (\n  body: readonly unknown[],\n  definitions: readonly AnyPrimitiveDefinition[],\n  walk: ReturnType<typeof createChildNodeWalker>\n): ValidationWarning[] => {\n  const unmeasured = new Set(\n    definitions\n      .filter((definition) => !definition.metrics?.svgHeight)\n      .map((definition) => definition.type)\n  );\n  if (unmeasured.size === 0) {\n    return [];\n  }\n  const warnings: ValidationWarning[] = [];\n  const visit = (node: unknown, path: string): void => {\n    if (!node || typeof node !== 'object' || !isVisibleOnSurface(node, 'svg')) {\n      return;\n    }\n    const { type } = node as { type?: unknown };\n    if (typeof type === 'string' && unmeasured.has(type)) {\n      warnings.push({\n        surface: 'svg',\n        path,\n        message: `${path} type ${quoteText(type)} declares no svgHeight metric and will be measured as 0, sizing the frame short`,\n      });\n    }\n    walk(node).forEach(({ node: child, path: field }) => {\n      visit(child, childNodePath(path, field));\n    });\n  };\n  body.forEach((node, index) => visit(node, `body[${index}]`));\n  return warnings;\n};\n\n/**\n * Errors for each node whose `id` repeats one already seen, naming the first\n * use.\n *\n * Errors rather than warnings, because ids are what a host addresses a node by.\n * Run by `validate` and deliberately not by `parse`; see\n * {@link createCompositionParser}.\n */\nconst collectDuplicateNodeIdErrors = (\n  body: readonly unknown[],\n  walk: ReturnType<typeof createChildNodeWalker>\n): ValidationError[] => {\n  const errors: ValidationError[] = [];\n  const seen = new Map<string, string>();\n  const visit = (node: unknown, path: string): void => {\n    if (!node || typeof node !== 'object') {\n      return;\n    }\n    const { id, type } = node as { id?: unknown; type?: unknown };\n    if (typeof id === 'string') {\n      const first = seen.get(id);\n      if (first) {\n        errors.push({\n          path: `${path}.id`,\n          message: `duplicates id ${quoteText(id)} first used at ${first}`,\n          ...(typeof type === 'string' ? { nodeType: type } : {}),\n        });\n      } else {\n        seen.set(id, path);\n      }\n    }\n    walk(node).forEach(({ node: child, path: field }) => {\n      visit(child, childNodePath(path, field));\n    });\n  };\n  body.forEach((node, index) => visit(node, `body[${index}]`));\n  return errors;\n};\n"]}

package/dist/cjs/validate/value_schemas.js

@@ -0,0 +1,53 @@
+"use strict";
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.displayValueSchema = exports.structuredValueSchema = exports.renderThemeSchema = exports.namedColorSchema = void 0;
+// Zod for the value shapes the sdk already owns types for: `NamedColor`, and
+// the structured display value.
+//
+// Only the shapes the sdk owns belong here. That is what lets any vocabulary
+// package validate a color or a display value without depending on another
+// pack's schemas.
+const zod_1 = require("zod");
+const named_color_1 = require("../composition/named_color");
+const structured_value_1 = require("../composition/structured_value");
+const zod_format_1 = require("../define/zod_format");
+const zod_helpers_1 = require("../define/zod_helpers");
+// An enum whose own message names the accepted values, as validation reports it.
+const closedEnum = (values) => zod_1.z.enum(values, { error: () => (0, zod_format_1.oneOf)(values) });
+/** Derived from {@link ALL_NAMED_COLORS} rather than restating the literals. */
+exports.namedColorSchema = closedEnum(named_color_1.ALL_NAMED_COLORS);
+/** `RenderTheme`: the light/dark preference a caller asks for. */
+exports.renderThemeSchema = closedEnum(['auto', 'light', 'dark']);
+/**
+ * The raw quantity plus a format hint, formatted once in a primitive's model so
+ * every surface renders the same string. See `StructuredValue`.
+ */
+exports.structuredValueSchema = zod_1.z.object({
+    raw: zod_1.z.union([zod_1.z.number(), (0, zod_helpers_1.requiredString)()], {
+        error: () => 'must be a finite number or a non-empty string',
+    }),
+    format: closedEnum(structured_value_1.STRUCTURED_VALUE_FORMATS).optional(),
+    precision: zod_1.z
+        .number({ error: () => 'must be an integer between 0 and 6' })
+        .int({ error: 'must be an integer between 0 and 6' })
+        .min(0, { error: 'must be an integer between 0 and 6' })
+        .max(6, { error: 'must be an integer between 0 and 6' })
+        .optional(),
+    currency: zod_1.z
+        .string({ error: () => 'must be a three-letter currency code' })
+        .regex(/^[A-Za-z]{3}$/, {
+        error: 'must be a three-letter currency code',
+    })
+        .optional(),
+});
+/** Value-bearing fields accept preformatted prose or a structured value. */
+exports.displayValueSchema = zod_1.z.union([(0, zod_helpers_1.requiredString)(), exports.structuredValueSchema], {
+    error: () => 'must be a non-empty string or a structured value ({ raw, format?, precision?, currency? })',
+});
+//# sourceMappingURL=value_schemas.js.map

package/dist/cjs/validate/value_schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value_schemas.js","sourceRoot":"","sources":["../../../src/validate/value_schemas.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,6EAA6E;AAC7E,gCAAgC;AAChC,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,kBAAkB;AAElB,6BAAwB;AAExB,4DAA+E;AAC/E,sEAA2E;AAC3E,qDAA6C;AAC7C,uDAAuD;AAEvD,iFAAiF;AACjF,MAAM,UAAU,GAAG,CACjB,MAAS,EACT,EAAE,CAAC,OAAC,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,IAAA,kBAAK,EAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEpD,gFAAgF;AACnE,QAAA,gBAAgB,GAAG,UAAU,CACxC,8BAAiD,CAClD,CAAC;AAEF,kEAAkE;AACrD,QAAA,iBAAiB,GAAG,UAAU,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAEvE;;;GAGG;AACU,QAAA,qBAAqB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5C,GAAG,EAAE,OAAC,CAAC,KAAK,CAAC,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,IAAA,4BAAc,GAAE,CAAC,EAAE;QAC3C,KAAK,EAAE,GAAG,EAAE,CAAC,+CAA+C;KAC7D,CAAC;IACF,MAAM,EAAE,UAAU,CAAC,2CAAwB,CAAC,CAAC,QAAQ,EAAE;IACvD,SAAS,EAAE,OAAC;SACT,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,oCAAoC,EAAE,CAAC;SAC7D,GAAG,CAAC,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;SACpD,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;SACvD,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;SACvD,QAAQ,EAAE;IACb,QAAQ,EAAE,OAAC;SACR,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,sCAAsC,EAAE,CAAC;SAC/D,KAAK,CAAC,eAAe,EAAE;QACtB,KAAK,EAAE,sCAAsC;KAC9C,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAEH,4EAA4E;AAC/D,QAAA,kBAAkB,GAAG,OAAC,CAAC,KAAK,CACvC,CAAC,IAAA,4BAAc,GAAE,EAAE,6BAAqB,CAAC,EACzC;IACE,KAAK,EAAE,GAAG,EAAE,CACV,4FAA4F;CAC/F,CACF,CAAC","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\n// Zod for the value shapes the sdk already owns types for: `NamedColor`, and\n// the structured display value.\n//\n// Only the shapes the sdk owns belong here. That is what lets any vocabulary\n// package validate a color or a display value without depending on another\n// pack's schemas.\n\nimport { z } from 'zod';\n\nimport { ALL_NAMED_COLORS, type NamedColor } from '../composition/named_color';\nimport { STRUCTURED_VALUE_FORMATS } from '../composition/structured_value';\nimport { oneOf } from '../define/zod_format';\nimport { requiredString } from '../define/zod_helpers';\n\n// An enum whose own message names the accepted values, as validation reports it.\nconst closedEnum = <const T extends readonly [string, ...string[]]>(\n  values: T\n) => z.enum(values, { error: () => oneOf(values) });\n\n/** Derived from {@link ALL_NAMED_COLORS} rather than restating the literals. */\nexport const namedColorSchema = closedEnum(\n  ALL_NAMED_COLORS as [NamedColor, ...NamedColor[]]\n);\n\n/** `RenderTheme`: the light/dark preference a caller asks for. */\nexport const renderThemeSchema = closedEnum(['auto', 'light', 'dark']);\n\n/**\n * The raw quantity plus a format hint, formatted once in a primitive's model so\n * every surface renders the same string. See `StructuredValue`.\n */\nexport const structuredValueSchema = z.object({\n  raw: z.union([z.number(), requiredString()], {\n    error: () => 'must be a finite number or a non-empty string',\n  }),\n  format: closedEnum(STRUCTURED_VALUE_FORMATS).optional(),\n  precision: z\n    .number({ error: () => 'must be an integer between 0 and 6' })\n    .int({ error: 'must be an integer between 0 and 6' })\n    .min(0, { error: 'must be an integer between 0 and 6' })\n    .max(6, { error: 'must be an integer between 0 and 6' })\n    .optional(),\n  currency: z\n    .string({ error: () => 'must be a three-letter currency code' })\n    .regex(/^[A-Za-z]{3}$/, {\n      error: 'must be a three-letter currency code',\n    })\n    .optional(),\n});\n\n/** Value-bearing fields accept preformatted prose or a structured value. */\nexport const displayValueSchema = z.union(\n  [requiredString(), structuredValueSchema],\n  {\n    error: () =>\n      'must be a non-empty string or a structured value ({ raw, format?, precision?, currency? })',\n  }\n);\n"]}

package/dist/composition/action_event.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A named event a node can raise, for the host to interpret.
+ *
+ * The SDK carries the reference and never dispatches it: side effects are the
+ * host's, so `name` means whatever its handler decides.
+ */
+export interface ActionEventRef {
+    /** Agreed between the composition's author and the host's handler. */
+    name: string;
+    /** Payload passed through untouched, so it must be JSON-serializable. */
+    context?: Record<string, unknown>;
+}
+//# sourceMappingURL=action_event.d.ts.map

package/dist/composition/action_event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_event.d.ts","sourceRoot":"","sources":["../../src/composition/action_event.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC"}

package/dist/composition/action_event.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+export {};
+//# sourceMappingURL=action_event.js.map

package/dist/composition/action_event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_event.js","sourceRoot":"","sources":["../../src/composition/action_event.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\n/**\n * A named event a node can raise, for the host to interpret.\n *\n * The SDK carries the reference and never dispatches it: side effects are the\n * host's, so `name` means whatever its handler decides.\n */\nexport interface ActionEventRef {\n  /** Agreed between the composition's author and the host's handler. */\n  name: string;\n  /** Payload passed through untouched, so it must be JSON-serializable. */\n  context?: Record<string, unknown>;\n}\n"]}

package/dist/composition/body_node_base.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The five surfaces a node renders on or is hidden from.
+ *
+ * Spelled out rather than derived as `keyof SurfaceMap<…>`: the keys never vary
+ * with the pack types, and TypeScript can fail to prove a `keyof` over one
+ * instantiation transfers to another, silently widening to `any`.
+ */
+export type SurfaceName = 'react' | 'svg' | 'text' | 'markdown' | 'slack';
+/** Every {@link SurfaceName}, for callers that iterate them. */
+export declare const BODY_NODE_SURFACES: readonly SurfaceName[];
+/** The two fields every primitive node carries, whatever its pack. */
+export interface BodyNodeBase {
+    /** Unique within a composition, which `validate` enforces and `parse` does not. */
+    id?: string;
+    /** Surfaces this node appears on. Absent means every surface. */
+    surfaces?: SurfaceName[];
+}
+/**
+ * A child node together with the field path locating it inside its parent, so
+ * an error path can name the field a child actually lives under. A container
+ * that returned bare nodes would leave every caller guessing the field name.
+ */
+export interface ChildNodeRef {
+    /** Erased: one walker spans every pack's node types, so it can name none of them. */
+    node: unknown;
+    /** Relative to the parent, e.g. `items[0].node`, `items[2].description`. */
+    path: string;
+}
+/**
+ * Walks nested nodes and, for a hybrid container, reports whether the parent
+ * still produces output of its own. A non-empty `children` result is the
+ * complete source of rendered content unless
+ * {@link ChildNodeWalker.hasOwnContent} is true for that node.
+ */
+export type ChildNodeWalker = ((node: unknown) => ChildNodeRef[]) & {
+    hasOwnContent?(node: unknown): boolean;
+};
+/**
+ * Builds the {@link ChildNodeWalker} for one composition's inventory.
+ *
+ * Pass every pack's definitions: a walker missing one cannot see children of a
+ * container that pack defines, and a tree walk would stop at its boundary.
+ */
+export declare const createChildNodeWalker: (definitions: readonly {
+    type: string;
+    children?: unknown;
+    hasOwnContent?: unknown;
+}[]) => ChildNodeWalker;
+/** Joins a parent path with a {@link ChildNodeRef.path} fragment. */
+export declare const childNodePath: (parent: string, child: string) => string;
+/**
+ * Whether any node visible on `surface` matches, descending through container
+ * children via `walk`. A node (or a container ancestor) hidden from `surface`
+ * is skipped along with its children.
+ *
+ * `walk` must span every pack in the composition: a walker built from one
+ * pack's definitions cannot see children of a container defined in another.
+ */
+export declare const someBodyNode: (nodes: readonly unknown[], surface: SurfaceName, predicate: (node: unknown) => boolean, walk: ChildNodeWalker) => boolean;
+/** Whether `node`'s own `surfaces` hint admits `surface`, ignoring its children. */
+export declare const isVisibleOnSurface: (node: unknown, surface: SurfaceName) => boolean;
+/**
+ * Whether `node` puts anything on `surface` — itself or through a descendant.
+ *
+ * Stronger than {@link isVisibleOnSurface}: a container every one of whose
+ * children is hidden renders nothing, even though its own hint allows the
+ * surface. A hybrid container that also owns string fields declares
+ * {@link ChildNodeWalker.hasOwnContent} and keeps rendering regardless.
+ */
+export declare const rendersOnSurface: (node: unknown, surface: SurfaceName, walk: ChildNodeWalker) => boolean;
+//# sourceMappingURL=body_node_base.d.ts.map

package/dist/composition/body_node_base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body_node_base.d.ts","sourceRoot":"","sources":["../../src/composition/body_node_base.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAE1E,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAMpD,CAAC;AAEF,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,IAAI,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,KAAK,YAAY,EAAE,CAAC,GAAG;IAClE,aAAa,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;CACxC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,aAAa,SAAS;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,EAAE,KACF,eAyCF,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG,MACxC,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,SAAS,OAAO,EAAE,EACzB,SAAS,WAAW,EACpB,WAAW,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,EACrC,MAAM,eAAe,KACpB,OAcC,CAAC;AAEL,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,GAC7B,MAAM,OAAO,EACb,SAAS,WAAW,KACnB,OAMF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,OAAO,EACb,SAAS,WAAW,EACpB,MAAM,eAAe,KACpB,OAWF,CAAC"}

package/dist/composition/body_node_base.js

@@ -0,0 +1,97 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+/** Every {@link SurfaceName}, for callers that iterate them. */
+export const BODY_NODE_SURFACES = [
+    'react',
+    'svg',
+    'text',
+    'markdown',
+    'slack',
+];
+/**
+ * Builds the {@link ChildNodeWalker} for one composition's inventory.
+ *
+ * Pass every pack's definitions: a walker missing one cannot see children of a
+ * container that pack defines, and a tree walk would stop at its boundary.
+ */
+export const createChildNodeWalker = (definitions) => {
+    const childrenByType = new Map();
+    const ownContentByType = new Map();
+    for (const definition of definitions) {
+        if (typeof definition.children === 'function') {
+            childrenByType.set(definition.type, definition.children);
+        }
+        if (typeof definition.hasOwnContent === 'function') {
+            ownContentByType.set(definition.type, definition.hasOwnContent);
+        }
+    }
+    const walk = ((node) => {
+        if (!node || typeof node !== 'object') {
+            return [];
+        }
+        const { type } = node;
+        if (typeof type !== 'string') {
+            return [];
+        }
+        return [...(childrenByType.get(type)?.(node) ?? [])];
+    });
+    walk.hasOwnContent = (node) => {
+        if (!node || typeof node !== 'object') {
+            return false;
+        }
+        const { type } = node;
+        if (typeof type !== 'string') {
+            return false;
+        }
+        return ownContentByType.get(type)?.(node) ?? false;
+    };
+    return walk;
+};
+/** Joins a parent path with a {@link ChildNodeRef.path} fragment. */
+export const childNodePath = (parent, child) => `${parent}.${child}`;
+/**
+ * Whether any node visible on `surface` matches, descending through container
+ * children via `walk`. A node (or a container ancestor) hidden from `surface`
+ * is skipped along with its children.
+ *
+ * `walk` must span every pack in the composition: a walker built from one
+ * pack's definitions cannot see children of a container defined in another.
+ */
+export const someBodyNode = (nodes, surface, predicate, walk) => nodes.some((node) => {
+    if (!isVisibleOnSurface(node, surface)) {
+        return false;
+    }
+    return (predicate(node) ||
+        someBodyNode(walk(node).map((child) => child.node), surface, predicate, walk));
+});
+/** Whether `node`'s own `surfaces` hint admits `surface`, ignoring its children. */
+export const isVisibleOnSurface = (node, surface) => {
+    if (!node || typeof node !== 'object') {
+        return false;
+    }
+    const { surfaces } = node;
+    return !Array.isArray(surfaces) || surfaces.includes(surface);
+};
+/**
+ * Whether `node` puts anything on `surface` — itself or through a descendant.
+ *
+ * Stronger than {@link isVisibleOnSurface}: a container every one of whose
+ * children is hidden renders nothing, even though its own hint allows the
+ * surface. A hybrid container that also owns string fields declares
+ * {@link ChildNodeWalker.hasOwnContent} and keeps rendering regardless.
+ */
+export const rendersOnSurface = (node, surface, walk) => {
+    if (!isVisibleOnSurface(node, surface)) {
+        return false;
+    }
+    const children = walk(node);
+    if (children.length === 0 || walk.hasOwnContent?.(node)) {
+        return true;
+    }
+    return children.some(({ node: child }) => rendersOnSurface(child, surface, walk));
+};
+//# sourceMappingURL=body_node_base.js.map

package/dist/composition/body_node_base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body_node_base.js","sourceRoot":"","sources":["../../src/composition/body_node_base.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\n/**\n * The five surfaces a node renders on or is hidden from.\n *\n * Spelled out rather than derived as `keyof SurfaceMap<…>`: the keys never vary\n * with the pack types, and TypeScript can fail to prove a `keyof` over one\n * instantiation transfers to another, silently widening to `any`.\n */\nexport type SurfaceName = 'react' | 'svg' | 'text' | 'markdown' | 'slack';\n\n/** Every {@link SurfaceName}, for callers that iterate them. */\nexport const BODY_NODE_SURFACES: readonly SurfaceName[] = [\n  'react',\n  'svg',\n  'text',\n  'markdown',\n  'slack',\n];\n\n/** The two fields every primitive node carries, whatever its pack. */\nexport interface BodyNodeBase {\n  /** Unique within a composition, which `validate` enforces and `parse` does not. */\n  id?: string;\n  /** Surfaces this node appears on. Absent means every surface. */\n  surfaces?: SurfaceName[];\n}\n\n/**\n * A child node together with the field path locating it inside its parent, so\n * an error path can name the field a child actually lives under. A container\n * that returned bare nodes would leave every caller guessing the field name.\n */\nexport interface ChildNodeRef {\n  /** Erased: one walker spans every pack's node types, so it can name none of them. */\n  node: unknown;\n  /** Relative to the parent, e.g. `items[0].node`, `items[2].description`. */\n  path: string;\n}\n\n/**\n * Walks nested nodes and, for a hybrid container, reports whether the parent\n * still produces output of its own. A non-empty `children` result is the\n * complete source of rendered content unless\n * {@link ChildNodeWalker.hasOwnContent} is true for that node.\n */\nexport type ChildNodeWalker = ((node: unknown) => ChildNodeRef[]) & {\n  hasOwnContent?(node: unknown): boolean;\n};\n\n/**\n * Builds the {@link ChildNodeWalker} for one composition's inventory.\n *\n * Pass every pack's definitions: a walker missing one cannot see children of a\n * container that pack defines, and a tree walk would stop at its boundary.\n */\nexport const createChildNodeWalker = (\n  definitions: readonly {\n    type: string;\n    children?: unknown;\n    hasOwnContent?: unknown;\n  }[]\n): ChildNodeWalker => {\n  const childrenByType = new Map<\n    string,\n    (node: unknown) => readonly ChildNodeRef[]\n  >();\n  const ownContentByType = new Map<string, (node: unknown) => boolean>();\n  for (const definition of definitions) {\n    if (typeof definition.children === 'function') {\n      childrenByType.set(\n        definition.type,\n        definition.children as (node: unknown) => readonly ChildNodeRef[]\n      );\n    }\n    if (typeof definition.hasOwnContent === 'function') {\n      ownContentByType.set(\n        definition.type,\n        definition.hasOwnContent as (node: unknown) => boolean\n      );\n    }\n  }\n  const walk = ((node: unknown) => {\n    if (!node || typeof node !== 'object') {\n      return [];\n    }\n    const { type } = node as { type?: unknown };\n    if (typeof type !== 'string') {\n      return [];\n    }\n    return [...(childrenByType.get(type)?.(node) ?? [])];\n  }) as ChildNodeWalker;\n  walk.hasOwnContent = (node) => {\n    if (!node || typeof node !== 'object') {\n      return false;\n    }\n    const { type } = node as { type?: unknown };\n    if (typeof type !== 'string') {\n      return false;\n    }\n    return ownContentByType.get(type)?.(node) ?? false;\n  };\n  return walk;\n};\n\n/** Joins a parent path with a {@link ChildNodeRef.path} fragment. */\nexport const childNodePath = (parent: string, child: string): string =>\n  `${parent}.${child}`;\n\n/**\n * Whether any node visible on `surface` matches, descending through container\n * children via `walk`. A node (or a container ancestor) hidden from `surface`\n * is skipped along with its children.\n *\n * `walk` must span every pack in the composition: a walker built from one\n * pack's definitions cannot see children of a container defined in another.\n */\nexport const someBodyNode = (\n  nodes: readonly unknown[],\n  surface: SurfaceName,\n  predicate: (node: unknown) => boolean,\n  walk: ChildNodeWalker\n): boolean =>\n  nodes.some((node) => {\n    if (!isVisibleOnSurface(node, surface)) {\n      return false;\n    }\n    return (\n      predicate(node) ||\n      someBodyNode(\n        walk(node).map((child) => child.node),\n        surface,\n        predicate,\n        walk\n      )\n    );\n  });\n\n/** Whether `node`'s own `surfaces` hint admits `surface`, ignoring its children. */\nexport const isVisibleOnSurface = (\n  node: unknown,\n  surface: SurfaceName\n): boolean => {\n  if (!node || typeof node !== 'object') {\n    return false;\n  }\n  const { surfaces } = node as { surfaces?: unknown };\n  return !Array.isArray(surfaces) || surfaces.includes(surface);\n};\n\n/**\n * Whether `node` puts anything on `surface` — itself or through a descendant.\n *\n * Stronger than {@link isVisibleOnSurface}: a container every one of whose\n * children is hidden renders nothing, even though its own hint allows the\n * surface. A hybrid container that also owns string fields declares\n * {@link ChildNodeWalker.hasOwnContent} and keeps rendering regardless.\n */\nexport const rendersOnSurface = (\n  node: unknown,\n  surface: SurfaceName,\n  walk: ChildNodeWalker\n): boolean => {\n  if (!isVisibleOnSurface(node, surface)) {\n    return false;\n  }\n  const children = walk(node);\n  if (children.length === 0 || walk.hasOwnContent?.(node)) {\n    return true;\n  }\n  return children.some(({ node: child }) =>\n    rendersOnSurface(child, surface, walk)\n  );\n};\n"]}

package/dist/composition/composition.d.ts

@@ -0,0 +1,71 @@
+import type { RenderTheme } from './named_color.js';
+import type { PrimitiveNode } from './node.js';
+/**
+ * The wire format: one typed document that every surface renders from.
+ *
+ * Crosses process and vendor boundaries, so the JSON shape is the contract and
+ * the TypeScript name is not: {@link Composition.type} reads `view`, the
+ * discriminator an agent is prompted on.
+ */
+export interface Composition<TNode extends PrimitiveNode = PrimitiveNode> {
+    /** Root marker. Always `view`; see the note on {@link Composition}. */
+    type: 'view';
+    /**
+     * Wire-format version. A literal rather than `number` so an unknown future
+     * version cannot parse as valid, and optional with no default because absent
+     * already means v1 — writing one in would rewrite stored documents.
+     */
+    version?: 1;
+    title?: string;
+    subtitle?: string;
+    /** Light/dark preference, not a resolved value; `auto` resolves light. */
+    theme?: RenderTheme;
+    /** At least one node, which the schema enforces via `.min(1)`. */
+    body: TNode[];
+    meta?: CompositionMeta;
+}
+/**
+ * Context a host may surface beside the render.
+ *
+ * Advisory and pass-through throughout: nothing here changes what the body
+ * renders to, and the SDK reads none of it. Timestamps are plain strings by
+ * convention ISO 8601, which the schema does not enforce — a host that parses
+ * one should tolerate anything.
+ */
+export interface CompositionMeta {
+    /** Origin of the composition itself, e.g. the agent or feature that composed it. */
+    source?: string;
+    /** When the composition was produced. */
+    generatedAt?: string;
+    /** Overrides the accessible name a surface derives from `title`. */
+    ariaLabel?: string;
+    /** Where the underlying data came from, as opposed to who composed it. */
+    provenance?: {
+        /** Data origin, e.g. an index or dataset name. */
+        source?: string;
+        /** The query that produced the data, for a host that offers "show me how". */
+        query?: string;
+        /** Service or connector that answered the query. */
+        provider?: string;
+    };
+    /** How current the data is, for a host that shows an as-of or staleness badge. */
+    freshness?: {
+        /** When the data was current, which may precede `generatedAt`. */
+        asOf?: string;
+        /** Asserted by the producer rather than derived, so a host should prefer it to comparing `asOf`. */
+        stale?: boolean;
+        /** How long `asOf` stays current. Not range-checked. */
+        ttlSeconds?: number;
+    };
+    /**
+     * Set when the composition rendered anyway despite losing some data, so a
+     * host can mark it incomplete rather than presenting it as whole.
+     */
+    partialFailure?: {
+        /** True when some of the data behind the composition was lost before it rendered. */
+        degraded?: boolean;
+        /** Human-readable cause, safe to show a user. */
+        reason?: string;
+    };
+}
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../../src/composition/composition.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,SAAS,aAAa,GAAG,aAAa;IACtE,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,kEAAkE;IAClE,IAAI,EAAE,KAAK,EAAE,CAAC;IACd,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE;QACX,kDAAkD;QAClD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,8EAA8E;QAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,oDAAoD;QACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,kFAAkF;IAClF,SAAS,CAAC,EAAE;QACV,kEAAkE;QAClE,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,oGAAoG;QACpG,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,wDAAwD;QACxD,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF;;;OAGG;IACH,cAAc,CAAC,EAAE;QACf,qFAAqF;QACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,iDAAiD;QACjD,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH"}

package/dist/composition/composition.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+export {};
+//# sourceMappingURL=composition.js.map

package/dist/composition/composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.js","sourceRoot":"","sources":["../../src/composition/composition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport type { RenderTheme } from './named_color';\nimport type { PrimitiveNode } from './node';\n\n/**\n * The wire format: one typed document that every surface renders from.\n *\n * Crosses process and vendor boundaries, so the JSON shape is the contract and\n * the TypeScript name is not: {@link Composition.type} reads `view`, the\n * discriminator an agent is prompted on.\n */\nexport interface Composition<TNode extends PrimitiveNode = PrimitiveNode> {\n  /** Root marker. Always `view`; see the note on {@link Composition}. */\n  type: 'view';\n  /**\n   * Wire-format version. A literal rather than `number` so an unknown future\n   * version cannot parse as valid, and optional with no default because absent\n   * already means v1 — writing one in would rewrite stored documents.\n   */\n  version?: 1;\n  title?: string;\n  subtitle?: string;\n  /** Light/dark preference, not a resolved value; `auto` resolves light. */\n  theme?: RenderTheme;\n  /** At least one node, which the schema enforces via `.min(1)`. */\n  body: TNode[];\n  meta?: CompositionMeta;\n}\n\n/**\n * Context a host may surface beside the render.\n *\n * Advisory and pass-through throughout: nothing here changes what the body\n * renders to, and the SDK reads none of it. Timestamps are plain strings by\n * convention ISO 8601, which the schema does not enforce — a host that parses\n * one should tolerate anything.\n */\nexport interface CompositionMeta {\n  /** Origin of the composition itself, e.g. the agent or feature that composed it. */\n  source?: string;\n  /** When the composition was produced. */\n  generatedAt?: string;\n  /** Overrides the accessible name a surface derives from `title`. */\n  ariaLabel?: string;\n  /** Where the underlying data came from, as opposed to who composed it. */\n  provenance?: {\n    /** Data origin, e.g. an index or dataset name. */\n    source?: string;\n    /** The query that produced the data, for a host that offers \"show me how\". */\n    query?: string;\n    /** Service or connector that answered the query. */\n    provider?: string;\n  };\n  /** How current the data is, for a host that shows an as-of or staleness badge. */\n  freshness?: {\n    /** When the data was current, which may precede `generatedAt`. */\n    asOf?: string;\n    /** Asserted by the producer rather than derived, so a host should prefer it to comparing `asOf`. */\n    stale?: boolean;\n    /** How long `asOf` stays current. Not range-checked. */\n    ttlSeconds?: number;\n  };\n  /**\n   * Set when the composition rendered anyway despite losing some data, so a\n   * host can mark it incomplete rather than presenting it as whole.\n   */\n  partialFailure?: {\n    /** True when some of the data behind the composition was lost before it rendered. */\n    degraded?: boolean;\n    /** Human-readable cause, safe to show a user. */\n    reason?: string;\n  };\n}\n"]}