@elastic/isomer-sdk 0.0.0 → 0.2.0

package/dist/cjs/validate/url.js

@@ -0,0 +1,116 @@
+"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.assetUrl = exports.navigationHref = exports.ASSET_URL_MESSAGE = exports.NAVIGATION_HREF_MESSAGE = exports.ASSET_URL_RULE = exports.NAVIGATION_HREF_RULE = exports.BLOCKED_HREF = exports.sanitizeParsedAssetUrl = exports.sanitizeParsedNavigationHref = exports.sanitizeAssetUrl = exports.sanitizeNavigationHref = void 0;
+const zod_helpers_1 = require("../define/zod_helpers");
+// The one URL trust policy every URL-bearing field goes through, as a Zod
+// refinement and again as render-time sanitization. See `docs/url-trust.md`.
+const NAMED_REFERENCES = {
+    bsol: '\\',
+    colon: ':',
+    gt: '>',
+    lt: '<',
+    newline: '\n',
+    sol: '/',
+    tab: '\t',
+};
+// Numeric references, which browsers decode without a trailing `;`, and the
+// named ones that spell a scheme, path, or tag character.
+const CHARACTER_REFERENCE_RE = /&(?:#x([0-9a-f]+);?|#([0-9]+);?|(bsol|colon|gt|lt|newline|sol|tab);)/gi;
+const decodeReference = (match, hex, decimal, name) => {
+    if (name)
+        return NAMED_REFERENCES[name.toLowerCase()] ?? match;
+    const codePoint = Number.parseInt(hex ?? decimal ?? '', hex ? 16 : 10);
+    return codePoint > 0 && codePoint <= 0x10ffff
+        ? String.fromCodePoint(codePoint)
+        : '\ufffd';
+};
+// The control characters browsers drop when parsing a URL.
+const stripControls = (value) => 
+// eslint-disable-next-line no-control-regex -- stripping control characters is the point.
+value.replace(/[\u0000-\u001f\u007f]/g, '').trim();
+// The URL as a sink sees it: references decoded once, then controls stripped,
+// so an obfuscated scheme is checked as it would act. Only the decision reads
+// it; the policy returns the authored value, since a consumer that decodes
+// again must decode what was checked, not a decoded copy.
+const decisionForm = (value) => stripControls(value.replace(CHARACTER_REFERENCE_RE, decodeReference));
+// `<` and `>` must be percent-encoded in a URL, so their unencoded presence
+// means the value is malformed or a parser-confusion attempt (an unterminated
+// `<dest` would otherwise read as a relative path). Reject rather than strip.
+const HAS_ANGLE_BRACKET_RE = /[<>]/;
+const HAS_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+const NAVIGATION_SCHEME_RE = /^(?:https?|mailto):/i;
+const ASSET_SCHEME_RE = /^(?:https?:|data:image\/)/i;
+// `//host` — and the `\` variants browsers fold into `/` — resolve against the
+// current protocol onto a foreign host, so they are not relative paths.
+const PROTOCOL_RELATIVE_RE = /^[/\\][/\\]/;
+// Whether a URL in decision form passes, given which schemes are allowed.
+const passes = (decided, schemes) => decided !== '' &&
+    !PROTOCOL_RELATIVE_RE.test(decided) &&
+    !HAS_ANGLE_BRACKET_RE.test(decided) &&
+    (!HAS_SCHEME_RE.test(decided) || schemes.test(decided));
+/**
+ * Returns the URL, trimmed and with control characters stripped, when it
+ * satisfies the navigation policy (`https:` / `http:` / `mailto:` / relative
+ * path), `null` otherwise.
+ */
+const sanitizeNavigationHref = (href) => passes(decisionForm(href), NAVIGATION_SCHEME_RE) ? stripControls(href) : null;
+exports.sanitizeNavigationHref = sanitizeNavigationHref;
+/**
+ * Returns the URL, trimmed and with control characters stripped, when it
+ * satisfies the asset policy (`https:` / `http:` / relative path /
+ * `data:image/*`), `null` otherwise.
+ */
+const sanitizeAssetUrl = (url) => passes(decisionForm(url), ASSET_SCHEME_RE) ? stripControls(url) : null;
+exports.sanitizeAssetUrl = sanitizeAssetUrl;
+/** Checks a Markdown parser's decoded destination without decoding it again. */
+const sanitizeParsedNavigationHref = (href) => {
+    const normalized = stripControls(href);
+    return passes(normalized, NAVIGATION_SCHEME_RE) ? normalized : null;
+};
+exports.sanitizeParsedNavigationHref = sanitizeParsedNavigationHref;
+/** Checks a Markdown parser's decoded image destination. */
+const sanitizeParsedAssetUrl = (url) => {
+    const normalized = stripControls(url);
+    return passes(normalized, ASSET_SCHEME_RE) ? normalized : null;
+};
+exports.sanitizeParsedAssetUrl = sanitizeParsedAssetUrl;
+/**
+ * Render-time replacement for a navigation href that failed the policy: an
+ * inert same-document link, so the label stays visible without a destination.
+ */
+exports.BLOCKED_HREF = '#';
+/** What {@link navigationHref} accepts, for a field description to state. */
+exports.NAVIGATION_HREF_RULE = 'an https, http, or mailto URL, or a relative path';
+/** What {@link assetUrl} accepts, for a field description to state. */
+exports.ASSET_URL_RULE = 'an https, http, or data:image URL, or a relative path';
+/** Validation message for {@link navigationHref}. */
+exports.NAVIGATION_HREF_MESSAGE = `must be ${exports.NAVIGATION_HREF_RULE}`;
+/** Validation message for {@link assetUrl}. */
+exports.ASSET_URL_MESSAGE = `must be ${exports.ASSET_URL_RULE}`;
+const urlSchema = (passes, rule, message, { max }) => (max === undefined ? (0, zod_helpers_1.requiredString)() : (0, zod_helpers_1.requiredString)().max(max))
+    .refine(passes, { error: message })
+    .describe(`${rule[0].toUpperCase()}${rule.slice(1)}.`);
+/**
+ * Zod schema for an `href`-like field: the validation layer of the two-layer
+ * policy, paired with {@link sanitizeNavigationHref} at render time.
+ *
+ * Its description states the rule, since a refinement's message does not
+ * reach the authoring JSON Schema. A field that describes itself should end
+ * with {@link NAVIGATION_HREF_RULE} so the model still reads it.
+ */
+const navigationHref = (options = {}) => urlSchema((value) => (0, exports.sanitizeNavigationHref)(value) !== null, exports.NAVIGATION_HREF_RULE, exports.NAVIGATION_HREF_MESSAGE, options);
+exports.navigationHref = navigationHref;
+/**
+ * Zod schema for a `src`-like field, paired with {@link sanitizeAssetUrl} at
+ * render time. Describes itself as {@link navigationHref} does, with
+ * {@link ASSET_URL_RULE}.
+ */
+const assetUrl = (options = {}) => urlSchema((value) => (0, exports.sanitizeAssetUrl)(value) !== null, exports.ASSET_URL_RULE, exports.ASSET_URL_MESSAGE, options);
+exports.assetUrl = assetUrl;
+//# sourceMappingURL=url.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../../src/validate/url.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 { requiredString } from '../define/zod_helpers';\n\n// The one URL trust policy every URL-bearing field goes through, as a Zod\n// refinement and again as render-time sanitization. See `docs/url-trust.md`.\n\nconst NAMED_REFERENCES: Readonly<Record<string, string>> = {\n  bsol: '\\\\',\n  colon: ':',\n  gt: '>',\n  lt: '<',\n  newline: '\\n',\n  sol: '/',\n  tab: '\\t',\n};\n\n// Numeric references, which browsers decode without a trailing `;`, and the\n// named ones that spell a scheme, path, or tag character.\nconst CHARACTER_REFERENCE_RE =\n  /&(?:#x([0-9a-f]+);?|#([0-9]+);?|(bsol|colon|gt|lt|newline|sol|tab);)/gi;\n\nconst decodeReference = (\n  match: string,\n  hex: string | undefined,\n  decimal: string | undefined,\n  name: string | undefined\n): string => {\n  if (name) return NAMED_REFERENCES[name.toLowerCase()] ?? match;\n  const codePoint = Number.parseInt(hex ?? decimal ?? '', hex ? 16 : 10);\n  return codePoint > 0 && codePoint <= 0x10ffff\n    ? String.fromCodePoint(codePoint)\n    : '\\ufffd';\n};\n\n// The control characters browsers drop when parsing a URL.\nconst stripControls = (value: string): string =>\n  // eslint-disable-next-line no-control-regex -- stripping control characters is the point.\n  value.replace(/[\\u0000-\\u001f\\u007f]/g, '').trim();\n\n// The URL as a sink sees it: references decoded once, then controls stripped,\n// so an obfuscated scheme is checked as it would act. Only the decision reads\n// it; the policy returns the authored value, since a consumer that decodes\n// again must decode what was checked, not a decoded copy.\nconst decisionForm = (value: string): string =>\n  stripControls(value.replace(CHARACTER_REFERENCE_RE, decodeReference));\n\n// `<` and `>` must be percent-encoded in a URL, so their unencoded presence\n// means the value is malformed or a parser-confusion attempt (an unterminated\n// `<dest` would otherwise read as a relative path). Reject rather than strip.\nconst HAS_ANGLE_BRACKET_RE = /[<>]/;\nconst HAS_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;\nconst NAVIGATION_SCHEME_RE = /^(?:https?|mailto):/i;\nconst ASSET_SCHEME_RE = /^(?:https?:|data:image\\/)/i;\n// `//host` — and the `\\` variants browsers fold into `/` — resolve against the\n// current protocol onto a foreign host, so they are not relative paths.\nconst PROTOCOL_RELATIVE_RE = /^[/\\\\][/\\\\]/;\n\n// Whether a URL in decision form passes, given which schemes are allowed.\nconst passes = (decided: string, schemes: RegExp): boolean =>\n  decided !== '' &&\n  !PROTOCOL_RELATIVE_RE.test(decided) &&\n  !HAS_ANGLE_BRACKET_RE.test(decided) &&\n  (!HAS_SCHEME_RE.test(decided) || schemes.test(decided));\n\n/**\n * Returns the URL, trimmed and with control characters stripped, when it\n * satisfies the navigation policy (`https:` / `http:` / `mailto:` / relative\n * path), `null` otherwise.\n */\nexport const sanitizeNavigationHref = (href: string): string | null =>\n  passes(decisionForm(href), NAVIGATION_SCHEME_RE) ? stripControls(href) : null;\n\n/**\n * Returns the URL, trimmed and with control characters stripped, when it\n * satisfies the asset policy (`https:` / `http:` / relative path /\n * `data:image/*`), `null` otherwise.\n */\nexport const sanitizeAssetUrl = (url: string): string | null =>\n  passes(decisionForm(url), ASSET_SCHEME_RE) ? stripControls(url) : null;\n\n/** Checks a Markdown parser's decoded destination without decoding it again. */\nexport const sanitizeParsedNavigationHref = (href: string): string | null => {\n  const normalized = stripControls(href);\n  return passes(normalized, NAVIGATION_SCHEME_RE) ? normalized : null;\n};\n\n/** Checks a Markdown parser's decoded image destination. */\nexport const sanitizeParsedAssetUrl = (url: string): string | null => {\n  const normalized = stripControls(url);\n  return passes(normalized, ASSET_SCHEME_RE) ? normalized : null;\n};\n\n/**\n * Render-time replacement for a navigation href that failed the policy: an\n * inert same-document link, so the label stays visible without a destination.\n */\nexport const BLOCKED_HREF = '#';\n\n/** What {@link navigationHref} accepts, for a field description to state. */\nexport const NAVIGATION_HREF_RULE =\n  'an https, http, or mailto URL, or a relative path';\n\n/** What {@link assetUrl} accepts, for a field description to state. */\nexport const ASSET_URL_RULE =\n  'an https, http, or data:image URL, or a relative path';\n\n/** Validation message for {@link navigationHref}. */\nexport const NAVIGATION_HREF_MESSAGE = `must be ${NAVIGATION_HREF_RULE}`;\n\n/** Validation message for {@link assetUrl}. */\nexport const ASSET_URL_MESSAGE = `must be ${ASSET_URL_RULE}`;\n\n/** Options for {@link navigationHref} and {@link assetUrl}. */\nexport interface UrlSchemaOptions {\n  /** Longest accepted value, in characters. */\n  max?: number;\n}\n\nconst urlSchema = (\n  passes: (value: string) => boolean,\n  rule: string,\n  message: string,\n  { max }: UrlSchemaOptions\n) =>\n  (max === undefined ? requiredString() : requiredString().max(max))\n    .refine(passes, { error: message })\n    .describe(`${rule[0]!.toUpperCase()}${rule.slice(1)}.`);\n\n/**\n * Zod schema for an `href`-like field: the validation layer of the two-layer\n * policy, paired with {@link sanitizeNavigationHref} at render time.\n *\n * Its description states the rule, since a refinement's message does not\n * reach the authoring JSON Schema. A field that describes itself should end\n * with {@link NAVIGATION_HREF_RULE} so the model still reads it.\n */\nexport const navigationHref = (options: UrlSchemaOptions = {}) =>\n  urlSchema(\n    (value) => sanitizeNavigationHref(value) !== null,\n    NAVIGATION_HREF_RULE,\n    NAVIGATION_HREF_MESSAGE,\n    options\n  );\n\n/**\n * Zod schema for a `src`-like field, paired with {@link sanitizeAssetUrl} at\n * render time. Describes itself as {@link navigationHref} does, with\n * {@link ASSET_URL_RULE}.\n */\nexport const assetUrl = (options: UrlSchemaOptions = {}) =>\n  urlSchema(\n    (value) => sanitizeAssetUrl(value) !== null,\n    ASSET_URL_RULE,\n    ASSET_URL_MESSAGE,\n    options\n  );\n"]}

package/dist/cjs/validate/validation.js

@@ -0,0 +1,165 @@
+"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);
+            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.SURFACE_NAMES.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}"`,
+}));
+/**
+ * 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  childNodePath,\n  createChildNodeWalker,\n  rendersOnSurface,\n  SURFACE_NAMES,\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/** Options for {@link createCompositionValidator}. */\nexport interface CompositionValidatorOptions {\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 = collectEmptySurfaceWarnings(body, walk);\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  SURFACE_NAMES.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 * 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,72 @@
+/**
+ * Every surface a node renders on or is hidden from, in render order.
+ *
+ * `html` is not here: the runtime's `html` surface wraps `react` output in a
+ * document, and no node targets it.
+ */
+export declare const SURFACE_NAMES: readonly ["react", "snapshot", "text", "markdown", "slack"];
+/** One of the {@link SURFACE_NAMES}. */
+export type SurfaceName = (typeof SURFACE_NAMES)[number];
+/** @deprecated Use {@link SURFACE_NAMES}. */
+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;;;;;GAKG;AACH,eAAO,MAAM,aAAa,6DAMhB,CAAC;AAEX,wCAAwC;AACxC,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,6CAA6C;AAC7C,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAAkB,CAAC;AAExE,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,104 @@
+/*
+ * 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 surface a node renders on or is hidden from, in render order.
+ *
+ * `html` is not here: the runtime's `html` surface wraps `react` output in a
+ * document, and no node targets it.
+ */
+export const SURFACE_NAMES = [
+    'react',
+    'snapshot',
+    'text',
+    'markdown',
+    'slack',
+];
+/** @deprecated Use {@link SURFACE_NAMES}. */
+export const BODY_NODE_SURFACES = SURFACE_NAMES;
+/**
+ * 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