@json-to-office/shared 0.1.1 → 0.7.0

package/dist/chunk-HS3W472G.js

@@ -0,0 +1,182 @@
+import {
+  isValidSemver,
+  latestVersion
+} from "./chunk-244MHDOZ.js";
+import {
+  formatErrorSummary,
+  transformValueErrors
+} from "./chunk-ZKD5BAMU.js";
+
+// src/plugin/createComponent.ts
+function createVersion(version) {
+  return version;
+}
+function createComponent(component) {
+  if (!component.name) {
+    throw new Error("Component name is required");
+  }
+  if (!component.versions || typeof component.versions !== "object") {
+    throw new Error(`Component "${component.name}" requires a versions map`);
+  }
+  const versionKeys = Object.keys(component.versions);
+  if (versionKeys.length === 0) {
+    throw new Error(
+      `Component "${component.name}" must have at least one version`
+    );
+  }
+  for (const key of versionKeys) {
+    if (!isValidSemver(key)) {
+      throw new Error(
+        `Component "${component.name}": invalid semver key "${key}". Expected format: major.minor.patch`
+      );
+    }
+    const entry = component.versions[key];
+    if (!entry.propsSchema) {
+      throw new Error(
+        `Component "${component.name}" version "${key}" requires a propsSchema`
+      );
+    }
+    if (!entry.render || typeof entry.render !== "function") {
+      throw new Error(
+        `Component "${component.name}" version "${key}" requires a render function`
+      );
+    }
+  }
+  return component;
+}
+
+// src/plugin/version-resolver.ts
+function resolveComponentVersion(componentName, versions, requestedVersion) {
+  const versionKeys = Object.keys(versions);
+  if (requestedVersion) {
+    const entry = versions[requestedVersion];
+    if (!entry) {
+      throw new Error(
+        `Component "${componentName}" does not have version "${requestedVersion}". Available versions: ${versionKeys.join(", ")}`
+      );
+    }
+    return entry;
+  }
+  const latest = latestVersion(versionKeys);
+  return versions[latest];
+}
+
+// src/plugin/errors.ts
+var DuplicateComponentError = class _DuplicateComponentError extends Error {
+  componentName;
+  code = "DUPLICATE_COMPONENT";
+  constructor(componentName) {
+    super(
+      `Cannot register component "${componentName}": a component with this name is already registered. Component names must be unique within a document generator.`
+    );
+    this.name = "DuplicateComponentError";
+    this.componentName = componentName;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _DuplicateComponentError);
+    }
+  }
+};
+var ComponentValidationError = class extends Error {
+  errors;
+  props;
+  constructor(errors, props) {
+    const propsStr = props !== void 0 ? `
+Props: ${JSON.stringify(props, null, 2)}` : "";
+    const message = `Document validation failed:
+${errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}${propsStr}`;
+    super(message);
+    this.name = "ComponentValidationError";
+    this.errors = errors;
+    this.props = props;
+  }
+};
+
+// src/plugin/validation.ts
+import { Value } from "@sinclair/typebox/value";
+function validateAgainstSchema(schema, data, options) {
+  try {
+    let processedData = Value.Clone(data);
+    if (options?.applyDefaults) {
+      processedData = Value.Default(schema, processedData);
+    }
+    if (options?.clean) {
+      processedData = Value.Clean(schema, processedData);
+    }
+    if (!Value.Check(schema, processedData)) {
+      const errors = [...Value.Errors(schema, processedData)];
+      const transformedErrors = transformValueErrors(errors, {
+        jsonString: options?.jsonString,
+        maxErrors: options?.maxErrors || 100
+      });
+      return { valid: false, errors: transformedErrors };
+    }
+    return { valid: true, data: processedData };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [
+        {
+          path: "root",
+          message: error instanceof Error ? error.message : "Unknown validation error",
+          code: "validation_exception"
+        }
+      ]
+    };
+  }
+}
+function validateCustomComponentProps(componentSchema, config, options) {
+  const name = options?.componentName ?? "custom";
+  try {
+    const result = validateAgainstSchema(componentSchema, config, {
+      ...options,
+      clean: options?.clean ?? true,
+      applyDefaults: options?.applyDefaults ?? true
+    });
+    return {
+      ...result,
+      success: result.valid,
+      data: result.data,
+      componentName: name,
+      isCustomComponent: true
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      success: false,
+      errors: [
+        {
+          path: "props",
+          message: error instanceof Error ? error.message : "Unknown validation error",
+          code: "validation_exception"
+        }
+      ],
+      componentName: name,
+      isCustomComponent: true
+    };
+  }
+}
+function isValidationSuccess(result) {
+  return result.valid === true && result.data !== void 0;
+}
+function getValidationSummary(result) {
+  if (result.valid) {
+    return "Validation successful";
+  }
+  if (!result.errors || result.errors.length === 0) {
+    return "Validation failed with unknown error";
+  }
+  return formatErrorSummary(result.errors);
+}
+
+export {
+  createVersion,
+  createComponent,
+  resolveComponentVersion,
+  DuplicateComponentError,
+  ComponentValidationError,
+  validateAgainstSchema,
+  validateCustomComponentProps,
+  isValidationSuccess,
+  getValidationSummary
+};
+//# sourceMappingURL=chunk-HS3W472G.js.map

package/dist/chunk-HS3W472G.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin/createComponent.ts","../src/plugin/version-resolver.ts","../src/plugin/errors.ts","../src/plugin/validation.ts"],"sourcesContent":["import { type TSchema, type Static } from '@sinclair/typebox';\nimport { isValidSemver } from '../utils/semver';\nimport type { AddWarningFunction } from '../types/warnings';\n\n/**\n * Render function context - parameters passed to render.\n * TTheme defaults to unknown so format-specific packages can narrow it.\n */\nexport interface RenderContext<T, TTheme = unknown> {\n  /** The validated props for this component */\n  props: T;\n  /** The resolved theme configuration */\n  theme: TTheme;\n  /** Function to add warnings during processing */\n  addWarning: AddWarningFunction;\n  /** For container components: processed nested children */\n  children?: unknown[];\n}\n\n/**\n * Render function that transforms custom component props into standard components.\n */\nexport type RenderFunction<\n  TProps,\n  TComponentDefinition = unknown,\n  TTheme = unknown,\n> = (context: RenderContext<TProps, TTheme>) => Promise<TComponentDefinition[]>;\n\n/**\n * A single version entry within a versioned component.\n * Each version is self-contained with its own schema, render, and metadata.\n */\nexport interface ComponentVersion<\n  TComponentDefinition = unknown,\n  TPropsSchema extends TSchema = TSchema,\n  TTheme = unknown,\n> {\n  /** TypeBox schema for props validation */\n  propsSchema: TPropsSchema;\n  /** Async render function to transform props into standard components */\n  render: RenderFunction<Static<TPropsSchema>, TComponentDefinition, TTheme>;\n  /** Whether this version supports nested children */\n  hasChildren?: boolean;\n  /** Optional description for this version */\n  description?: string;\n}\n\n/**\n * Map of semver version strings to their version definitions.\n */\nexport type ComponentVersionMap<\n  TComponentDefinition = unknown,\n  TTheme = unknown,\n> = Record<string, ComponentVersion<TComponentDefinition, any, TTheme>>;\n\n/**\n * Custom component definition with multiple semver-keyed versions.\n */\nexport interface CustomComponent<\n  TComponentDefinition = unknown,\n  TVersions extends ComponentVersionMap<\n    TComponentDefinition,\n    any\n  > = ComponentVersionMap<TComponentDefinition, any>,\n  TName extends string = string,\n> {\n  /** Unique name for the component type */\n  name: TName;\n  /** Map of semver version strings to version definitions */\n  versions: TVersions;\n}\n\n/**\n * Create a single version entry with full type inference for props.\n */\nexport function createVersion<\n  TPropsSchema extends TSchema,\n  TComponentDefinition = unknown,\n  TTheme = unknown,\n>(\n  version: ComponentVersion<TComponentDefinition, TPropsSchema, TTheme>\n): ComponentVersion<TComponentDefinition, TPropsSchema, TTheme> {\n  return version;\n}\n\n/**\n * Create a custom component with multiple semver-keyed versions.\n */\nexport function createComponent<\n  TComponentDefinition = unknown,\n  TVersions extends ComponentVersionMap<\n    TComponentDefinition,\n    any\n  > = ComponentVersionMap<TComponentDefinition, any>,\n  TName extends string = string,\n>(\n  component: CustomComponent<TComponentDefinition, TVersions, TName>\n): CustomComponent<TComponentDefinition, TVersions, TName> {\n  if (!component.name) {\n    throw new Error('Component name is required');\n  }\n\n  if (!component.versions || typeof component.versions !== 'object') {\n    throw new Error(`Component \"${component.name}\" requires a versions map`);\n  }\n\n  const versionKeys = Object.keys(component.versions);\n  if (versionKeys.length === 0) {\n    throw new Error(\n      `Component \"${component.name}\" must have at least one version`\n    );\n  }\n\n  for (const key of versionKeys) {\n    if (!isValidSemver(key)) {\n      throw new Error(\n        `Component \"${component.name}\": invalid semver key \"${key}\". Expected format: major.minor.patch`\n      );\n    }\n    const entry = component.versions[key];\n    if (!entry.propsSchema) {\n      throw new Error(\n        `Component \"${component.name}\" version \"${key}\" requires a propsSchema`\n      );\n    }\n    if (!entry.render || typeof entry.render !== 'function') {\n      throw new Error(\n        `Component \"${component.name}\" version \"${key}\" requires a render function`\n      );\n    }\n  }\n\n  return component;\n}\n","import { latestVersion } from '../utils/semver';\nimport type { ComponentVersion, ComponentVersionMap } from './createComponent';\n\n/**\n * Resolve the correct version entry for a component.\n *\n * - If `requestedVersion` is provided and found, return it.\n * - If `requestedVersion` is provided but missing, throw with available versions.\n * - If `requestedVersion` is absent, return the latest semver version.\n */\nexport function resolveComponentVersion(\n  componentName: string,\n  versions: ComponentVersionMap,\n  requestedVersion?: string\n): ComponentVersion {\n  const versionKeys = Object.keys(versions);\n\n  if (requestedVersion) {\n    const entry = versions[requestedVersion];\n    if (!entry) {\n      throw new Error(\n        `Component \"${componentName}\" does not have version \"${requestedVersion}\". ` +\n          `Available versions: ${versionKeys.join(', ')}`\n      );\n    }\n    return entry;\n  }\n\n  const latest = latestVersion(versionKeys);\n  return versions[latest];\n}\n","import type { ValidationError } from '../validation/unified';\n\n/**\n * Error thrown when attempting to register a component with a duplicate name\n */\nexport class DuplicateComponentError extends Error {\n  public readonly componentName: string;\n  public readonly code = 'DUPLICATE_COMPONENT';\n\n  constructor(componentName: string) {\n    super(\n      `Cannot register component \"${componentName}\": a component with this name is already registered. ` +\n        'Component names must be unique within a document generator.'\n    );\n    this.name = 'DuplicateComponentError';\n    this.componentName = componentName;\n\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, DuplicateComponentError);\n    }\n  }\n}\n\n/**\n * Custom validation error class\n */\nexport class ComponentValidationError extends Error {\n  public errors: ValidationError[];\n  public props: unknown;\n\n  constructor(errors: ValidationError[], props?: unknown) {\n    const propsStr =\n      props !== undefined ? `\\nProps: ${JSON.stringify(props, null, 2)}` : '';\n    const message = `Document validation failed:\\n${errors\n      .map((e) => `  ${e.path}: ${e.message}`)\n      .join('\\n')}${propsStr}`;\n    super(message);\n    this.name = 'ComponentValidationError';\n    this.errors = errors;\n    this.props = props;\n  }\n}\n","import { Value } from '@sinclair/typebox/value';\nimport type { Static, TSchema } from '@sinclair/typebox';\nimport type { ValidationResult as BaseValidationResult } from '../validation/unified';\nimport {\n  transformValueErrors,\n  formatErrorSummary,\n} from '../validation/unified';\n\n/**\n * Validation options for plugin components\n */\nexport interface PluginValidationOptions {\n  /** Apply Value.Clean to remove unknown properties */\n  clean?: boolean;\n  /** Apply Value.Default to add default values */\n  applyDefaults?: boolean;\n  /** Maximum number of errors to collect */\n  maxErrors?: number;\n  /** Original JSON string for position calculation */\n  jsonString?: string;\n  /** Calculate line/column for JSON errors */\n  calculatePosition?: boolean;\n}\n\n/**\n * Generic validation result extending the base non-generic one\n */\nexport interface PluginValidationResult<T = unknown>\n  extends BaseValidationResult {\n  data?: T;\n}\n\n/**\n * Component-specific validation result\n */\nexport interface ComponentValidationResult<T = unknown>\n  extends PluginValidationResult<T> {\n  componentName?: string;\n  isCustomComponent?: boolean;\n  success?: boolean;\n}\n\n/**\n * Base validation: schema check + optional clean/defaults\n */\nexport function validateAgainstSchema<T extends TSchema>(\n  schema: T,\n  data: unknown,\n  options?: PluginValidationOptions\n): PluginValidationResult<Static<T>> {\n  try {\n    let processedData: unknown = Value.Clone(data);\n\n    if (options?.applyDefaults) {\n      processedData = Value.Default(schema, processedData);\n    }\n\n    if (options?.clean) {\n      processedData = Value.Clean(schema, processedData);\n    }\n\n    if (!Value.Check(schema, processedData)) {\n      const errors = [...Value.Errors(schema, processedData)];\n      const transformedErrors = transformValueErrors(errors, {\n        jsonString: options?.jsonString,\n        maxErrors: options?.maxErrors || 100,\n      });\n\n      return { valid: false, errors: transformedErrors };\n    }\n\n    return { valid: true, data: processedData as Static<T> };\n  } catch (error) {\n    return {\n      valid: false,\n      errors: [\n        {\n          path: 'root',\n          message:\n            error instanceof Error ? error.message : 'Unknown validation error',\n          code: 'validation_exception',\n        },\n      ],\n    };\n  }\n}\n\n/**\n * Validate custom component props against a TypeBox schema.\n * Hardcodes clean + applyDefaults for consistent plugin behavior.\n */\nexport function validateCustomComponentProps<T>(\n  componentSchema: TSchema,\n  config: unknown,\n  options?: PluginValidationOptions & { componentName?: string }\n): ComponentValidationResult<T> {\n  const name = options?.componentName ?? 'custom';\n  try {\n    const result = validateAgainstSchema(componentSchema, config, {\n      ...options,\n      clean: options?.clean ?? true,\n      applyDefaults: options?.applyDefaults ?? true,\n    });\n\n    return {\n      ...result,\n      success: result.valid,\n      data: result.data as T,\n      componentName: name,\n      isCustomComponent: true,\n    };\n  } catch (error) {\n    return {\n      valid: false,\n      success: false,\n      errors: [\n        {\n          path: 'props',\n          message:\n            error instanceof Error ? error.message : 'Unknown validation error',\n          code: 'validation_exception',\n        },\n      ],\n      componentName: name,\n      isCustomComponent: true,\n    };\n  }\n}\n\n/**\n * Utility to check if validation result is successful with type guard\n */\nexport function isValidationSuccess<T>(\n  result: PluginValidationResult<T>\n): result is PluginValidationResult<T> & { valid: true; data: T } {\n  return result.valid === true && result.data !== undefined;\n}\n\n/**\n * Get validation error summary\n */\nexport function getValidationSummary(result: PluginValidationResult): string {\n  if (result.valid) {\n    return 'Validation successful';\n  }\n\n  if (!result.errors || result.errors.length === 0) {\n    return 'Validation failed with unknown error';\n  }\n\n  return formatErrorSummary(result.errors);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,6 +1,21 @@
 export { C as ComponentDefinition, a as ComponentSchemaConfig, c as convertToJsonSchema, b as createComponentSchema, d as createComponentSchemaObject, e as exportSchemaToFile, f as fixSchemaReferences } from './schema-utils-CbCi6dEk.js';
 export { AddWarningFunction, GenerationWarning } from './types/warnings.js';
-export { DEFAULT_ERROR_CONFIG, ERROR_EMOJIS, ErrorFormatterConfig, TransformedError, ValidationError, ValidationResult, calculatePosition, clearComponentNamesCache, createErrorConfig, createJsonParseError, extractStandardComponentNames, formatErrorMessage, formatErrorSummary, getLiteralValue, getObjectSchemaPropertyNames, getSchemaMetadata, groupErrorsByPath, isLiteralSchema, isObjectSchema, isUnionSchema, transformValueError, transformValueErrors } from './validation/unified/index.js';
+export { DEFAULT_ERROR_CONFIG, ERROR_EMOJIS, ErrorFormatterConfig, calculatePosition, clearComponentNamesCache, createErrorConfig, createJsonParseError, extractStandardComponentNames, formatErrorMessage, formatErrorSummary, getLiteralValue, getObjectSchemaPropertyNames, getSchemaMetadata, groupErrorsByPath, isLiteralSchema, isObjectSchema, isUnionSchema, transformValueError, transformValueErrors } from './validation/unified/index.js';
+export { T as TransformedError, V as ValidationError, a as ValidationResult } from './types-BWFZ7OaO.js';
+export { ComponentValidationError, ComponentValidationResult, ComponentVersion, ComponentVersionMap, CustomComponent, DuplicateComponentError, PluginValidationOptions, PluginValidationResult, RenderContext, RenderFunction, createComponent, createVersion, getValidationSummary, isValidationSuccess, resolveComponentVersion, validateCustomComponentProps } from './plugin/index.js';
 export { ParsedSemver, compareSemver, isValidSemver, latestVersion, parseSemver } from './utils/semver.js';
 import '@sinclair/typebox';
 import '@sinclair/typebox/value';
+
+/**
+ * Service configuration types for external integrations (e.g. Highcharts export server)
+ */
+interface HighchartsServiceConfig {
+    serverUrl?: string;
+    headers?: Record<string, string>;
+}
+interface ServicesConfig {
+    highcharts?: HighchartsServiceConfig;
+}
+
+export type { HighchartsServiceConfig, ServicesConfig };

package/dist/index.js

@@ -1,3 +1,13 @@
+import {
+  ComponentValidationError,
+  DuplicateComponentError,
+  createComponent,
+  createVersion,
+  getValidationSummary,
+  isValidationSuccess,
+  resolveComponentVersion,
+  validateCustomComponentProps
+} from "./chunk-HS3W472G.js";
 import {
   convertToJsonSchema,
   createComponentSchema,
@@ -32,16 +42,20 @@ import {
   transformValueErrors
 } from "./chunk-ZKD5BAMU.js";
 export {
+  ComponentValidationError,
   DEFAULT_ERROR_CONFIG,
+  DuplicateComponentError,
   ERROR_EMOJIS,
   calculatePosition,
   clearComponentNamesCache,
   compareSemver,
   convertToJsonSchema,
+  createComponent,
   createComponentSchema,
   createComponentSchemaObject,
   createErrorConfig,
   createJsonParseError,
+  createVersion,
   exportSchemaToFile,
   extractStandardComponentNames,
   fixSchemaReferences,
@@ -50,14 +64,18 @@ export {
   getLiteralValue,
   getObjectSchemaPropertyNames,
   getSchemaMetadata,
+  getValidationSummary,
   groupErrorsByPath,
   isLiteralSchema,
   isObjectSchema,
   isUnionSchema,
   isValidSemver,
+  isValidationSuccess,
   latestVersion,
   parseSemver,
+  resolveComponentVersion,
   transformValueError,
-  transformValueErrors
+  transformValueErrors,
+  validateCustomComponentProps
 };
 //# sourceMappingURL=index.js.map

package/dist/plugin/index.d.ts

@@ -0,0 +1,137 @@
+import { TSchema, Static } from '@sinclair/typebox';
+import { AddWarningFunction } from '../types/warnings.js';
+import { V as ValidationError, a as ValidationResult } from '../types-BWFZ7OaO.js';
+
+/**
+ * Render function context - parameters passed to render.
+ * TTheme defaults to unknown so format-specific packages can narrow it.
+ */
+interface RenderContext<T, TTheme = unknown> {
+    /** The validated props for this component */
+    props: T;
+    /** The resolved theme configuration */
+    theme: TTheme;
+    /** Function to add warnings during processing */
+    addWarning: AddWarningFunction;
+    /** For container components: processed nested children */
+    children?: unknown[];
+}
+/**
+ * Render function that transforms custom component props into standard components.
+ */
+type RenderFunction<TProps, TComponentDefinition = unknown, TTheme = unknown> = (context: RenderContext<TProps, TTheme>) => Promise<TComponentDefinition[]>;
+/**
+ * A single version entry within a versioned component.
+ * Each version is self-contained with its own schema, render, and metadata.
+ */
+interface ComponentVersion<TComponentDefinition = unknown, TPropsSchema extends TSchema = TSchema, TTheme = unknown> {
+    /** TypeBox schema for props validation */
+    propsSchema: TPropsSchema;
+    /** Async render function to transform props into standard components */
+    render: RenderFunction<Static<TPropsSchema>, TComponentDefinition, TTheme>;
+    /** Whether this version supports nested children */
+    hasChildren?: boolean;
+    /** Optional description for this version */
+    description?: string;
+}
+/**
+ * Map of semver version strings to their version definitions.
+ */
+type ComponentVersionMap<TComponentDefinition = unknown, TTheme = unknown> = Record<string, ComponentVersion<TComponentDefinition, any, TTheme>>;
+/**
+ * Custom component definition with multiple semver-keyed versions.
+ */
+interface CustomComponent<TComponentDefinition = unknown, TVersions extends ComponentVersionMap<TComponentDefinition, any> = ComponentVersionMap<TComponentDefinition, any>, TName extends string = string> {
+    /** Unique name for the component type */
+    name: TName;
+    /** Map of semver version strings to version definitions */
+    versions: TVersions;
+}
+/**
+ * Create a single version entry with full type inference for props.
+ */
+declare function createVersion<TPropsSchema extends TSchema, TComponentDefinition = unknown, TTheme = unknown>(version: ComponentVersion<TComponentDefinition, TPropsSchema, TTheme>): ComponentVersion<TComponentDefinition, TPropsSchema, TTheme>;
+/**
+ * Create a custom component with multiple semver-keyed versions.
+ */
+declare function createComponent<TComponentDefinition = unknown, TVersions extends ComponentVersionMap<TComponentDefinition, any> = ComponentVersionMap<TComponentDefinition, any>, TName extends string = string>(component: CustomComponent<TComponentDefinition, TVersions, TName>): CustomComponent<TComponentDefinition, TVersions, TName>;
+
+/**
+ * Resolve the correct version entry for a component.
+ *
+ * - If `requestedVersion` is provided and found, return it.
+ * - If `requestedVersion` is provided but missing, throw with available versions.
+ * - If `requestedVersion` is absent, return the latest semver version.
+ */
+declare function resolveComponentVersion(componentName: string, versions: ComponentVersionMap, requestedVersion?: string): ComponentVersion;
+
+/**
+ * Error thrown when attempting to register a component with a duplicate name
+ */
+declare class DuplicateComponentError extends Error {
+    readonly componentName: string;
+    readonly code = "DUPLICATE_COMPONENT";
+    constructor(componentName: string);
+}
+/**
+ * Custom validation error class
+ */
+declare class ComponentValidationError extends Error {
+    errors: ValidationError[];
+    props: unknown;
+    constructor(errors: ValidationError[], props?: unknown);
+}
+
+/**
+ * Validation options for plugin components
+ */
+interface PluginValidationOptions {
+    /** Apply Value.Clean to remove unknown properties */
+    clean?: boolean;
+    /** Apply Value.Default to add default values */
+    applyDefaults?: boolean;
+    /** Maximum number of errors to collect */
+    maxErrors?: number;
+    /** Original JSON string for position calculation */
+    jsonString?: string;
+    /** Calculate line/column for JSON errors */
+    calculatePosition?: boolean;
+}
+/**
+ * Generic validation result extending the base non-generic one
+ */
+interface PluginValidationResult<T = unknown> extends ValidationResult {
+    data?: T;
+}
+/**
+ * Component-specific validation result
+ */
+interface ComponentValidationResult<T = unknown> extends PluginValidationResult<T> {
+    componentName?: string;
+    isCustomComponent?: boolean;
+    success?: boolean;
+}
+/**
+ * Base validation: schema check + optional clean/defaults
+ */
+declare function validateAgainstSchema<T extends TSchema>(schema: T, data: unknown, options?: PluginValidationOptions): PluginValidationResult<Static<T>>;
+/**
+ * Validate custom component props against a TypeBox schema.
+ * Hardcodes clean + applyDefaults for consistent plugin behavior.
+ */
+declare function validateCustomComponentProps<T>(componentSchema: TSchema, config: unknown, options?: PluginValidationOptions & {
+    componentName?: string;
+}): ComponentValidationResult<T>;
+/**
+ * Utility to check if validation result is successful with type guard
+ */
+declare function isValidationSuccess<T>(result: PluginValidationResult<T>): result is PluginValidationResult<T> & {
+    valid: true;
+    data: T;
+};
+/**
+ * Get validation error summary
+ */
+declare function getValidationSummary(result: PluginValidationResult): string;
+
+export { ComponentValidationError, type ComponentValidationResult, type ComponentVersion, type ComponentVersionMap, type CustomComponent, DuplicateComponentError, type PluginValidationOptions, type PluginValidationResult, type RenderContext, type RenderFunction, createComponent, createVersion, getValidationSummary, isValidationSuccess, resolveComponentVersion, validateAgainstSchema, validateCustomComponentProps };

package/dist/plugin/index.js

@@ -0,0 +1,25 @@
+import {
+  ComponentValidationError,
+  DuplicateComponentError,
+  createComponent,
+  createVersion,
+  getValidationSummary,
+  isValidationSuccess,
+  resolveComponentVersion,
+  validateAgainstSchema,
+  validateCustomComponentProps
+} from "../chunk-HS3W472G.js";
+import "../chunk-244MHDOZ.js";
+import "../chunk-ZKD5BAMU.js";
+export {
+  ComponentValidationError,
+  DuplicateComponentError,
+  createComponent,
+  createVersion,
+  getValidationSummary,
+  isValidationSuccess,
+  resolveComponentVersion,
+  validateAgainstSchema,
+  validateCustomComponentProps
+};
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-BWFZ7OaO.d.ts

@@ -0,0 +1,17 @@
+interface ValidationError {
+    path: string;
+    message: string;
+    code?: string;
+    value?: unknown;
+    suggestion?: string;
+    line?: number;
+    column?: number;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors?: ValidationError[];
+}
+/** Backward-compat alias used by pptx shared */
+type TransformedError = ValidationError;
+
+export type { TransformedError as T, ValidationError as V, ValidationResult as a };

package/dist/validation/unified/index.d.ts

@@ -1,22 +1,8 @@
 import { ValueError } from '@sinclair/typebox/value';
+import { V as ValidationError } from '../../types-BWFZ7OaO.js';
+export { T as TransformedError, a as ValidationResult } from '../../types-BWFZ7OaO.js';
 import { TSchema, TLiteral, TObject, TUnion } from '@sinclair/typebox';
 
-interface ValidationError {
-    path: string;
-    message: string;
-    code?: string;
-    value?: unknown;
-    suggestion?: string;
-    line?: number;
-    column?: number;
-}
-interface ValidationResult {
-    valid: boolean;
-    errors?: ValidationError[];
-}
-/** Backward-compat alias used by pptx shared */
-type TransformedError = ValidationError;
-
 interface ErrorFormatterConfig {
     includeEmojis?: boolean;
     verbosity?: 'minimal' | 'normal' | 'detailed';
@@ -63,4 +49,4 @@ declare function getSchemaMetadata(schema: TSchema): {
     literal?: unknown;
 };
 
-export { DEFAULT_ERROR_CONFIG, ERROR_EMOJIS, type ErrorFormatterConfig, type TransformedError, type ValidationError, type ValidationResult, calculatePosition, clearComponentNamesCache, createErrorConfig, createJsonParseError, extractStandardComponentNames, formatErrorMessage, formatErrorSummary, getLiteralValue, getObjectSchemaPropertyNames, getSchemaMetadata, groupErrorsByPath, isLiteralSchema, isObjectSchema, isUnionSchema, transformValueError, transformValueErrors };
+export { DEFAULT_ERROR_CONFIG, ERROR_EMOJIS, type ErrorFormatterConfig, ValidationError, calculatePosition, clearComponentNamesCache, createErrorConfig, createJsonParseError, extractStandardComponentNames, formatErrorMessage, formatErrorSummary, getLiteralValue, getObjectSchemaPropertyNames, getSchemaMetadata, groupErrorsByPath, isLiteralSchema, isObjectSchema, isUnionSchema, transformValueError, transformValueErrors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-to-office/shared",
-  "version": "0.1.1",
+  "version": "0.7.0",
   "description": "Format-agnostic shared types, schemas and validation utilities",
   "type": "module",
   "main": "dist/index.js",
@@ -31,6 +31,11 @@
       "import": "./dist/cache/index.js",
       "default": "./dist/cache/index.js"
     },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*.js",