feat(types): establish domain types as SSOT for infographic data contracts

src/templates/types.ts

@@ -1,5 +1,10 @@
 import type { InfographicOptions, ParsedInfographicOptions } from '../options';
+import type { Data } from '../types/data';
 
+/**
+ * Template options are the configuration subset used to define a template.
+ * Templates receive data (via the Data interface) and options, then render an infographic.
+ */
 export type TemplateOptions = Omit<
   Partial<InfographicOptions>,
   'container' | 'template' | 'data'
@@ -9,3 +14,9 @@ export type ParsedTemplateOptions = Omit<
   Partial<ParsedInfographicOptions>,
   'container' | 'template' | 'data'
 >;
+
+/**
+ * The canonical data type that all templates consume.
+ * This alias makes it explicit that templates work with the shared Data contract.
+ */
+export type TemplateData = Data;

src/types/data.ts

@@ -1,5 +1,9 @@
 import type { ResourceConfig } from '../resource';
 
+/**
+ * Base datum structure for all infographic data elements.
+ * This is the fundamental building block for items and relations.
+ */
 export interface BaseDatum {
   id?: string;
   icon?: string | ResourceConfig;
@@ -10,6 +14,10 @@ export interface BaseDatum {
   [key: string]: any;
 }
 
+/**
+ * Item datum represents a single data point in the infographic.
+ * Used across all template types (list, hierarchy, sequence, etc).
+ */
 export interface ItemDatum extends BaseDatum {
   illus?: string | ResourceConfig;
   /** for hierarchical structure */
@@ -18,6 +26,10 @@ export interface ItemDatum extends BaseDatum {
   group?: string;
 }
 
+/**
+ * Relation datum represents a connection between two items.
+ * Used in relation-based templates (network, flow, etc).
+ */
 export interface RelationDatum extends BaseDatum {
   id?: string;
   from: string;
@@ -33,6 +45,22 @@ export interface RelationDatum extends BaseDatum {
   arrowType?: 'arrow' | 'triangle' | 'diamond';
 }
 
+/**
+ * The core data contract for all AntV Infographic templates.
+ * This is the single source of truth for infographic input data structure.
+ * All templates, syntax parsers, and runtime consumers should use this interface.
+ * 
+ * @example
+ * ```ts
+ * const data: Data = {
+ *   title: 'Q1 Sales Report',
+ *   items: [
+ *     { label: 'Product A', value: 100 },
+ *     { label: 'Product B', value: 200 }
+ *   ]
+ * };
+ * ```
+ */
 export interface Data {
   title?: string;
   desc?: string;

src/types/index.ts

@@ -1,3 +1,4 @@
+// Re-export all types for backward compatibility
 export type * from './attrs';
 export type * from './data';
 export type * from './element';
@@ -6,3 +7,18 @@ export type * from './font';
 export type * from './padding';
 export type * from './resource';
 export type * from './text';
+export type * from './template';
+
+// Domain model aliases - the recommended way to import infographic data types
+export type {
+  Data as InfographicData,
+  ItemDatum as InfographicItem,
+  RelationDatum as InfographicRelation,
+  BaseDatum as InfographicBaseDatum,
+} from './data';
+
+export type {
+  Template,
+  TemplateMetadata,
+  TemplateCategory,
+} from './template';

src/types/template.ts

@@ -0,0 +1,55 @@
+import type { Data } from './data';
+
+/**
+ * Template category classification.
+ * Each template belongs to one of these structural categories.
+ */
+export type TemplateCategory =
+  | 'list'
+  | 'compare'
+  | 'sequence'
+  | 'hierarchy'
+  | 'relation'
+  | 'geo'
+  | 'chart';
+
+/**
+ * Template metadata describing its purpose and characteristics.
+ */
+export interface TemplateMetadata {
+  /** Unique template identifier */
+  id: string;
+  /** Human-readable template name */
+  name: string;
+  /** Structural category this template belongs to */
+  category: TemplateCategory;
+  /** Optional description of the template's use case */
+  description?: string;
+  /** Optional keywords for searchability */
+  tags?: string[];
+}
+
+/**
+ * The core template contract.
+ * All infographic templates should conform to this interface.
+ * 
+ * @example
+ * ```ts
+ * const myTemplate: Template = {
+ *   metadata: {
+ *     id: 'list-simple',
+ *     name: 'Simple List',
+ *     category: 'list'
+ *   },
+ *   render: (data: Data, options) => {
+ *     // render logic
+ *   }
+ * };
+ * ```
+ */
+export interface Template<TOptions = any> {
+  /** Template metadata */
+  metadata: TemplateMetadata;
+  /** Render function that takes data and returns an infographic representation */
+  render: (data: Data, options?: TOptions) => any;
+}