@khairold/xml-render 0.1.0

package/README.md

@@ -0,0 +1,372 @@
+# @khairold/xml-render
+
+A type-safe XML-like tag parser and renderer framework for React and React Native. Parse structured content from text streams and render with custom components.
+
+## Features
+
+- **Type-safe parsing** - Define tags with Zod schemas, get full TypeScript inference
+- **Streaming support** - Parse content progressively as it streams in
+- **Platform agnostic** - Separate entry points for React and React Native
+- **Error boundaries** - Individual segment errors don't crash the entire UI
+- **Immutable by design** - All registry and catalog instances are frozen
+
+## Installation
+
+```bash
+npm install @khairold/xml-render zod
+# or
+bun add @khairold/xml-render zod
+```
+
+Peer dependencies:
+- `zod` ^3.0.0 (for attribute schemas)
+- `react` ^18.0.0
+- `react-native` (optional, for React Native renderer)
+
+## Quick Start
+
+```tsx
+import { z } from 'zod';
+import { createRegistry, createParser } from '@khairold/xml-render';
+import { createCatalog, XmlRender } from '@khairold/xml-render/react';
+
+// 1. Define your tags with Zod schemas
+const registry = createRegistry({
+  callout: {
+    schema: z.object({ type: z.enum(['info', 'warning', 'error']) }),
+    hasContent: true,
+  },
+  image: {
+    schema: z.object({ src: z.string(), alt: z.string().optional() }),
+    selfClosing: true,
+  },
+});
+
+// 2. Create a parser
+const parser = createParser(registry);
+
+// 3. Create a component catalog
+const catalog = createCatalog(registry, {
+  components: {
+    callout: ({ segment }) => (
+      <div className={`callout callout-${segment.attributes?.type}`}>
+        {segment.content}
+      </div>
+    ),
+    image: ({ segment }) => (
+      <img src={segment.attributes?.src} alt={segment.attributes?.alt} />
+    ),
+  },
+  textRenderer: ({ segment }) => <span>{segment.content}</span>,
+});
+
+// 4. Parse and render
+const text = 'Hello <callout type="info">Important message!</callout> World';
+const segments = parser.parse(text);
+
+function App() {
+  return <XmlRender segments={segments} catalog={catalog} />;
+}
+```
+
+## API Reference
+
+### Core Functions
+
+#### `createRegistry(definitions)`
+
+Creates an immutable tag registry from tag definitions.
+
+```ts
+import { z } from 'zod';
+import { createRegistry } from '@khairold/xml-render';
+
+const registry = createRegistry({
+  chart: {
+    schema: z.object({
+      type: z.enum(['bar', 'line', 'pie']),
+      title: z.string().optional(),
+    }),
+    hasContent: true,      // Tag contains inner content (default: true)
+    selfClosing: false,    // Tag must have closing tag (default: false)
+  },
+  image: {
+    schema: z.object({
+      src: z.string(),
+      alt: z.string().optional(),
+    }),
+    selfClosing: true,     // Self-closing tag like <image />
+    hasContent: false,
+  },
+});
+```
+
+**Registry methods:**
+- `registry.tagNames` - Array of all registered tag names
+- `registry.hasTag(name)` - Check if a tag is registered
+- `registry.getTag(name)` - Get the definition for a tag
+- `registry.validateAttributes(name, attrs)` - Validate attributes with Zod schema
+- `registry.isSelfClosing(name)` - Check if tag is self-closing
+- `registry.hasContent(name)` - Check if tag has content
+
+#### `createParser(registry)`
+
+Creates a parser instance bound to a registry.
+
+```ts
+import { createParser } from '@khairold/xml-render';
+
+const parser = createParser(registry);
+
+// Parse complete text
+const segments = parser.parse('Hello <callout type="info">World</callout>');
+// [
+//   { type: 'text', content: 'Hello ' },
+//   { type: 'callout', content: 'World', attributes: { type: 'info' } },
+// ]
+```
+
+**Parser methods:**
+- `parser.parse(text)` - Parse complete text into segments
+- `parser.createState()` - Create initial state for streaming
+- `parser.parseChunk(chunk, state)` - Parse streaming chunk
+- `parser.finalize(state)` - Flush remaining buffer at stream end
+
+### Streaming Usage
+
+For real-time content streaming (e.g., LLM responses):
+
+```ts
+import { createParser, type ParserState } from '@khairold/xml-render';
+
+const parser = createParser(registry);
+
+// Initialize streaming state
+let state = parser.createState();
+let allSegments: Segments<typeof registry.definitions> = [];
+
+// Process each chunk as it arrives
+function onChunk(chunk: string) {
+  const result = parser.parseChunk(chunk, state);
+
+  // Update state for next chunk (immutable pattern)
+  state = result.state;
+
+  // Append complete segments
+  allSegments = [...allSegments, ...result.segments];
+
+  // Check if currently buffering a tag
+  if (result.isBuffering && result.bufferingTag) {
+    // Show loading placeholder for the buffering tag type
+    showPlaceholder(result.bufferingTag);
+  }
+}
+
+// When stream ends, finalize to flush any remaining content
+function onStreamEnd() {
+  const finalSegments = parser.finalize(state);
+  allSegments = [...allSegments, ...finalSegments];
+}
+```
+
+### React Renderer
+
+```tsx
+import { createCatalog, XmlRender, XmlRenderProvider } from '@khairold/xml-render/react';
+```
+
+#### `createCatalog(registry, options)`
+
+Creates a component catalog mapping tag types to renderers.
+
+```tsx
+const catalog = createCatalog(registry, {
+  components: {
+    // Each component receives { segment, index } props
+    callout: ({ segment }) => (
+      <div className={`callout-${segment.attributes?.type}`}>
+        {segment.content}
+      </div>
+    ),
+    chart: ({ segment }) => (
+      <ChartComponent
+        type={segment.attributes?.type}
+        title={segment.attributes?.title}
+        data={JSON.parse(segment.content)}
+      />
+    ),
+  },
+  // Optional: custom text renderer (default: <span>{content}</span>)
+  textRenderer: ({ segment }) => <MarkdownText>{segment.content}</MarkdownText>,
+});
+```
+
+#### `<XmlRender>` Component
+
+Renders an array of segments using the catalog.
+
+```tsx
+// Option 1: Pass catalog directly
+<XmlRender segments={segments} catalog={catalog} />
+
+// Option 2: Use context provider
+<XmlRenderProvider catalog={catalog}>
+  <XmlRender segments={segments} />
+</XmlRenderProvider>
+
+// With custom fallback for unknown segment types
+<XmlRender
+  segments={segments}
+  catalog={catalog}
+  fallback={(segment, index) => (
+    <div>Unknown: {segment.type}</div>
+  )}
+/>
+
+// With custom error fallback
+<XmlRender
+  segments={segments}
+  catalog={catalog}
+  errorFallback={(error, segmentType) => (
+    <div>Error rendering {segmentType}: {error.message}</div>
+  )}
+/>
+```
+
+### React Native Renderer
+
+```tsx
+import { createCatalog, XmlRender, XmlRenderProvider } from '@khairold/xml-render/react-native';
+```
+
+The React Native API is identical to React. The only differences are:
+- Default text renderer uses `<Text>` instead of `<span>`
+- Container uses `<View>` instead of `<div>`
+- Error boundary styles use React Native `StyleSheet`
+
+### Type Utilities
+
+```ts
+import {
+  type ParsedSegment,
+  type Segments,
+  type SegmentType,
+  type ParserState,
+  type InferAttributes,
+  isSegmentType,
+} from '@khairold/xml-render';
+
+// Get attribute type for a specific tag
+type ChartAttrs = InferAttributes<typeof registry.definitions.chart>;
+// { type: 'bar' | 'line' | 'pie'; title?: string }
+
+// Type-safe segment type checking
+const segment: ParsedSegment<typeof registry.definitions> = /* ... */;
+if (isSegmentType(segment, 'chart', registry)) {
+  // segment.attributes is typed as ChartAttrs
+  console.log(segment.attributes.type);
+}
+```
+
+## Example: Tag Definitions
+
+### Callout (notification box)
+
+```ts
+const calloutDef = {
+  callout: {
+    schema: z.object({
+      type: z.enum(['info', 'warning', 'error']).default('info'),
+    }),
+    hasContent: true,
+  },
+};
+// Usage: <callout type="warning">Watch out!</callout>
+```
+
+### Table (markdown table)
+
+```ts
+const tableDef = {
+  table: {
+    schema: z.object({}),
+    hasContent: true,
+  },
+};
+// Usage: <table>| Col1 | Col2 |\n|---|---|\n| A | B |</table>
+```
+
+### Chart (data visualization)
+
+```ts
+const chartDef = {
+  chart: {
+    schema: z.object({
+      type: z.enum(['bar', 'line', 'pie']).default('bar'),
+      title: z.string().optional(),
+    }),
+    hasContent: true,
+  },
+};
+// Usage: <chart type="pie" title="Sales">{"labels":["Q1","Q2"],"data":[100,200]}</chart>
+```
+
+### Image (self-closing)
+
+```ts
+const imageDef = {
+  image: {
+    schema: z.object({
+      src: z.string(),
+      alt: z.string().optional(),
+    }),
+    selfClosing: true,
+    hasContent: false,
+  },
+};
+// Usage: <image src="photo.jpg" alt="A photo" />
+```
+
+## Platform-Specific Imports
+
+```ts
+// Core (parser + registry) - platform agnostic
+import { createRegistry, createParser } from '@khairold/xml-render';
+
+// React (web)
+import { createCatalog, XmlRender } from '@khairold/xml-render/react';
+
+// React Native (mobile)
+import { createCatalog, XmlRender } from '@khairold/xml-render/react-native';
+```
+
+## Parsing Behavior
+
+- **Unknown tags** pass through as literal text (not parsed)
+- **Malformed/unclosed tags** fall back to text segments
+- **XML entities** are decoded: `&lt;` `&gt;` `&amp;` `&quot;`
+- **Attribute parsing** supports both single and double quotes
+- **Case insensitive** tag matching
+
+## Error Handling
+
+Each segment is wrapped in an ErrorBoundary. If a component throws:
+- **Development**: Shows error message with segment type
+- **Production**: Renders a hidden/minimal fallback
+
+```tsx
+// Custom error handling
+<XmlRender
+  segments={segments}
+  catalog={catalog}
+  errorFallback={(error, segmentType) => (
+    <div className="render-error">
+      Failed to render {segmentType}
+    </div>
+  )}
+/>
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @aura/xml-render - Core XML Parsing Library
+ *
+ * A type-safe XML-like tag parser and renderer framework.
+ * Supports both complete text parsing and streaming for real-time content.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { createRegistry, createParser } from '@aura/xml-render';
+ *
+ * // Define your tags with Zod schemas
+ * const registry = createRegistry({
+ *   callout: {
+ *     schema: z.object({ type: z.enum(['info', 'warning', 'error']) }),
+ *     hasContent: true,
+ *   },
+ * });
+ *
+ * // Create a parser and parse content
+ * const parser = createParser(registry);
+ * const segments = parser.parse('Hello <callout type="info">Important!</callout>');
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createRegistry } from "./registry";
+export { createParser } from "./parser";
+export * from "./types";
+export { isSegmentType } from "./types";
+export type { TagDefinition, TagDefinitions, Registry, InferAttributes, SafeParseResult, } from "./registry";
+export type { Parser, ParsedSegment, SegmentType, Segments, ParserState, StreamingParseResult, } from "./parser";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAOxC,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAOxC,YAAY,EACV,aAAa,EACb,cAAc,EACd,QAAQ,EACR,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,MAAM,EACN,aAAa,EACb,WAAW,EACX,QAAQ,EACR,WAAW,EACX,oBAAoB,GACrB,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * @aura/xml-render - Core XML Parsing Library
+ *
+ * A type-safe XML-like tag parser and renderer framework.
+ * Supports both complete text parsing and streaming for real-time content.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { createRegistry, createParser } from '@aura/xml-render';
+ *
+ * // Define your tags with Zod schemas
+ * const registry = createRegistry({
+ *   callout: {
+ *     schema: z.object({ type: z.enum(['info', 'warning', 'error']) }),
+ *     hasContent: true,
+ *   },
+ * });
+ *
+ * // Create a parser and parse content
+ * const parser = createParser(registry);
+ * const segments = parser.parse('Hello <callout type="info">Important!</callout>');
+ * ```
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Core Functions
+// ============================================================================
+// Registry - Define your XML tags
+export { createRegistry } from "./registry";
+// Parser - Parse text into segments
+export { createParser } from "./parser";
+// ============================================================================
+// Type Exports - Import from here for best DX
+// ============================================================================
+// Consolidated types file - preferred import location for types
+export * from "./types";
+// Re-export type guard helper
+export { isSegmentType } from "./types";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E,kCAAkC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,+EAA+E;AAC/E,8CAA8C;AAC9C,+EAA+E;AAE/E,gEAAgE;AAChE,cAAc,SAAS,CAAC;AAExB,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/parser.d.ts

@@ -0,0 +1,129 @@
+/**
+ * XML Parser for xml-render
+ *
+ * Creates a registry-aware parser that converts text containing XML-like tags
+ * into typed segments. Supports complete text parsing and streaming.
+ */
+import type { Registry, TagDefinitions, InferAttributes } from "./registry";
+/**
+ * A parsed segment representing either plain text or a recognized tag
+ */
+export interface ParsedSegment<TDefs extends TagDefinitions = TagDefinitions, TType extends keyof TDefs | "text" = keyof TDefs | "text"> {
+    /** The segment type: 'text' or a registered tag name */
+    type: TType;
+    /** The content inside the tag, or the text content for 'text' segments */
+    content: string;
+    /** Attributes parsed from the tag (undefined for 'text' segments) */
+    attributes?: TType extends keyof TDefs ? InferAttributes<TDefs[TType]> : undefined;
+}
+/**
+ * Union of all segment types for a given registry
+ */
+export type SegmentType<TDefs extends TagDefinitions> = keyof TDefs | "text";
+/**
+ * A segment array that can contain any valid segment for the registry
+ */
+export type Segments<TDefs extends TagDefinitions> = Array<ParsedSegment<TDefs, keyof TDefs | "text">>;
+/**
+ * Parser state for handling incomplete/streaming content
+ */
+export interface ParserState {
+    /** Accumulated text buffer */
+    buffer: string;
+    /** Whether we're currently inside an unclosed component tag */
+    inComponent: boolean;
+    /** The tag name being processed, if any */
+    currentTag: string | null;
+    /** Attributes string for the current tag */
+    currentAttrs: string;
+    /** Index in buffer where current tag started */
+    tagStartIndex: number;
+}
+/**
+ * Result of parsing a streaming chunk
+ */
+export interface StreamingParseResult<TDefs extends TagDefinitions> {
+    /** Segments that are complete and can be rendered */
+    segments: Segments<TDefs>;
+    /** Updated parser state for next chunk */
+    state: ParserState;
+    /** Whether we're currently buffering (waiting for more data) */
+    isBuffering: boolean;
+    /** The type of tag being buffered, if any */
+    bufferingTag: keyof TDefs | null;
+}
+/**
+ * Parser interface returned by createParser
+ */
+export interface Parser<TDefs extends TagDefinitions> {
+    /**
+     * Parse a complete text string into segments.
+     * This is the main entry point for non-streaming use cases.
+     *
+     * @param text - The complete text to parse
+     * @returns Array of parsed segments in order
+     */
+    parse(text: string): Segments<TDefs>;
+    /**
+     * Create initial parser state for streaming parsing.
+     *
+     * @returns Fresh parser state
+     */
+    createState(): ParserState;
+    /**
+     * Parse a chunk of streaming text.
+     * Handles incomplete tags by buffering until complete.
+     *
+     * @param chunk - New text chunk to process
+     * @param state - Current parser state
+     * @returns Parse result with complete segments and updated state
+     */
+    parseChunk(chunk: string, state: ParserState): StreamingParseResult<TDefs>;
+    /**
+     * Finalize parsing, returning any remaining buffered content as text.
+     * Call this when streaming is complete.
+     *
+     * @param state - Current parser state
+     * @returns Final segments including any buffered content
+     */
+    finalize(state: ParserState): Segments<TDefs>;
+    /** The registry used by this parser */
+    readonly registry: Registry<TDefs>;
+}
+/**
+ * Create a parser instance bound to a registry.
+ *
+ * The parser recognizes tags defined in the registry and converts them
+ * into typed segments. Unknown tags are treated as literal text.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { createRegistry, createParser } from '@aura/xml-render';
+ *
+ * const registry = createRegistry({
+ *   callout: {
+ *     schema: z.object({ type: z.enum(['info', 'warning', 'error']) }),
+ *     hasContent: true,
+ *   },
+ *   image: {
+ *     schema: z.object({ src: z.string(), alt: z.string().optional() }),
+ *     selfClosing: true,
+ *   },
+ * });
+ *
+ * const parser = createParser(registry);
+ *
+ * const segments = parser.parse('Hello <callout type="info">Important!</callout> World');
+ * // [
+ * //   { type: 'text', content: 'Hello ' },
+ * //   { type: 'callout', content: 'Important!', attributes: { type: 'info' } },
+ * //   { type: 'text', content: ' World' },
+ * // ]
+ * ```
+ *
+ * @param registry - The tag registry to use for parsing
+ * @returns A parser instance
+ */
+export declare function createParser<TDefs extends TagDefinitions>(registry: Registry<TDefs>): Parser<TDefs>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,aAAa,CAC5B,KAAK,SAAS,cAAc,GAAG,cAAc,EAC7C,KAAK,SAAS,MAAM,KAAK,GAAG,MAAM,GAAG,MAAM,KAAK,GAAG,MAAM;IAEzD,wDAAwD;IACxD,IAAI,EAAE,KAAK,CAAC;IACZ,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,UAAU,CAAC,EAAE,KAAK,SAAS,MAAM,KAAK,GAClC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAC7B,SAAS,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,SAAS,cAAc,IAAI,MAAM,KAAK,GAAG,MAAM,CAAC;AAE7E;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,cAAc,IAAI,KAAK,CACxD,aAAa,CAAC,KAAK,EAAE,MAAM,KAAK,GAAG,MAAM,CAAC,CAC3C,CAAC;AA8BF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IACrB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,cAAc;IAChE,qDAAqD;IACrD,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1B,0CAA0C;IAC1C,KAAK,EAAE,WAAW,CAAC;IACnB,gEAAgE;IAChE,WAAW,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,KAAK,GAAG,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,MAAM,CAAC,KAAK,SAAS,cAAc;IAClD;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAErC;;;;OAIG;IACH,WAAW,IAAI,WAAW,CAAC;IAE3B;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAE3E;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE9C,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,YAAY,CAAC,KAAK,SAAS,cAAc,EACvD,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,MAAM,CAAC,KAAK,CAAC,CA+Tf"}