@relevate/katachi 0.1.0 → 0.2.0

package/dist/targets/shared.d.ts

@@ -1,4 +1,4 @@
-import type { AttrValue, Expr, Node } from "../core/ast.js";
+import type { AttrValue, Expr, Node, TagName } from "../core/ast.js";
 import type { BuildTemplate } from "../core/types.js";
 /**
  * Escapes a string for insertion into Rust string literals used by Askama wrappers.
@@ -17,11 +17,22 @@ export declare function emitTsxExpr(expr: Expr): string;
  * Emits a portable expression into Askama syntax.
  */
 export declare function emitAskamaExpr(expr: Expr): string;
+export declare function emitInterpolatedTagName(tag: TagName, emitExpr: (expr: Expr) => string): string;
+export declare function emitTsxTagExpr(tag: TagName): string;
+interface TsxEmitContext {
+    hoistedTagNames: WeakMap<Extract<Node, {
+        kind: "element";
+    }>, string>;
+}
 export type TsxAttrEmitter = (name: string, value: AttrValue) => string;
 /**
  * Shared JSX/TSX tree emitter used by both React and static JSX targets.
  */
-export declare function emitTsxNode(node: Node, emitAttr: TsxAttrEmitter, indent?: number): string;
+export declare function emitTsxNode(node: Node, emitAttr: TsxAttrEmitter, indent?: number, context?: TsxEmitContext): string;
+/**
+ * React-specific JSX/TSX tree emitter that uses <Fragment key={...}> in .map() calls.
+ */
+export declare function emitReactNode(node: Node, emitAttr: TsxAttrEmitter, indent?: number, context?: TsxEmitContext): string;
 export declare function toCamelCase(value: string): string;
 export declare function toRustType(type: string): string;
 export declare function toTsType(type: string): string;
@@ -32,5 +43,14 @@ export declare function buildTsxImportLines(template: BuildTemplate): string;
 /**
  * Wraps an emitted TSX template body in a component module.
  */
-export declare function buildTsxComponentSource(template: BuildTemplate, body: string): string;
+export declare function buildTsxComponentSource(template: BuildTemplate, body: string, hoists?: string[]): string;
+/**
+ * Wraps an emitted React TSX template body in a component module.
+ * Only imports ReactNode when a prop uses it, and imports Fragment when needed.
+ */
+export declare function buildReactComponentSource(template: BuildTemplate, body: string, hoists?: string[]): string;
+export declare function emitTsxWithHoists(template: BuildTemplate, emitNode: (node: Node, emitAttr: TsxAttrEmitter, indent: number, context?: TsxEmitContext) => string, emitAttr: TsxAttrEmitter): {
+    body: string;
+    hoists: string[];
+};
 export { escapeDoubleQuotes, wrapHtmlAttribute };

package/dist/targets/shared.js

@@ -69,6 +69,8 @@ export function emitTsxExpr(expr) {
                     return `(${emittedArg} != null)`;
                 case "isNone":
                     return `(${emittedArg} == null)`;
+                default:
+                    return emittedArg;
             }
         }
         case "raw":
@@ -110,6 +112,8 @@ export function emitAskamaExpr(expr) {
                     return `${emittedArg}.is_some()`;
                 case "isNone":
                     return `${emittedArg}.is_none()`;
+                default:
+                    return emittedArg;
             }
         }
         case "raw":
@@ -126,10 +130,114 @@ export function emitAskamaExpr(expr) {
             return `!(${emitAskamaExpr(expr.expr)})`;
     }
 }
+function emitTagInterpolationPart(expr, emitExpr) {
+    return expr.kind === "string" ? expr.value : `{{ ${emitExpr(expr)} }}`;
+}
+export function emitInterpolatedTagName(tag, emitExpr) {
+    if (tag.kind === "static") {
+        return tag.name;
+    }
+    return tag.parts.map((part) => emitTagInterpolationPart(part, emitExpr)).join("");
+}
+export function emitTsxTagExpr(tag) {
+    if (tag.kind === "static") {
+        return JSON.stringify(tag.name);
+    }
+    if (tag.parts.length === 1 && tag.parts[0]?.kind !== "string") {
+        return emitTsxExpr(tag.parts[0]);
+    }
+    const segments = tag.parts.map((part) => {
+        if (part.kind === "string") {
+            return part.value.replace(/[`\\$]/g, "\\$&");
+        }
+        return `\${${emitTsxExpr(part)}}`;
+    });
+    return `\`${segments.join("")}\``;
+}
+function exprUsesBoundName(expr, boundNames) {
+    switch (expr.kind) {
+        case "var":
+            return boundNames.has(expr.name);
+        case "string":
+        case "bool":
+        case "number":
+            return false;
+        case "intrinsic":
+            return expr.args.some((arg) => exprUsesBoundName(arg, boundNames));
+        case "raw":
+            return Array.from(boundNames).some((name) => new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(expr.source));
+        case "eq":
+        case "neq":
+        case "and":
+        case "or":
+            return (exprUsesBoundName(expr.left, boundNames) || exprUsesBoundName(expr.right, boundNames));
+        case "not":
+            return exprUsesBoundName(expr.expr, boundNames);
+    }
+}
+function tagUsesBoundName(tag, boundNames) {
+    if (tag.kind === "static") {
+        return false;
+    }
+    return tag.parts.some((part) => exprUsesBoundName(part, boundNames));
+}
+function collectHoistedDynamicTags(node, hoists, hoistedTagNames, boundNames = new Set(), nextId = { value: 0 }) {
+    switch (node.kind) {
+        case "if":
+            node.then.forEach((child) => collectHoistedDynamicTags(child, hoists, hoistedTagNames, boundNames, nextId));
+            (node.else ?? []).forEach((child) => collectHoistedDynamicTags(child, hoists, hoistedTagNames, boundNames, nextId));
+            return;
+        case "for": {
+            const loopBoundNames = new Set(boundNames);
+            loopBoundNames.add(node.item);
+            if (node.indexName) {
+                loopBoundNames.add(node.indexName);
+            }
+            node.children.forEach((child) => collectHoistedDynamicTags(child, hoists, hoistedTagNames, loopBoundNames, nextId));
+            return;
+        }
+        case "element":
+            if (node.tag.kind === "dynamic" && !tagUsesBoundName(node.tag, boundNames)) {
+                nextId.value += 1;
+                const tagName = nextId.value === 1 ? "Tag" : `Tag${nextId.value}`;
+                hoistedTagNames.set(node, tagName);
+                hoists.push(`  const ${tagName} = ${emitTsxTagExpr(node.tag)} as ElementType;`);
+            }
+            (node.children ?? []).forEach((child) => collectHoistedDynamicTags(child, hoists, hoistedTagNames, boundNames, nextId));
+            return;
+        case "component":
+            (node.children ?? []).forEach((child) => collectHoistedDynamicTags(child, hoists, hoistedTagNames, boundNames, nextId));
+            return;
+        default:
+            return;
+    }
+}
+function buildTsxEmitContext(template) {
+    const hoists = [];
+    const context = {
+        hoistedTagNames: new WeakMap(),
+    };
+    collectHoistedDynamicTags(template.template, hoists, context.hoistedTagNames);
+    return { context, hoists };
+}
+function emitDynamicTsxElement(tagExpr, tagComponentName, attrs, children, emitAttr, indent, emitNode, context) {
+    const pad = "  ".repeat(indent);
+    const attrEntries = Object.entries(attrs);
+    const attrBlock = attrEntries.length > 0
+        ? `\n${attrEntries
+            .map(([name, value]) => `${pad}      ${emitAttr(name, value)}`)
+            .join("\n")}\n${pad}    `
+        : "";
+    if (children.length === 0) {
+        return `${pad}{(() => {\n${pad}  const ${tagComponentName} = ${tagExpr};\n${pad}  return <${tagComponentName}${attrBlock} />;\n${pad}})()}`;
+    }
+    const childBlock = children.map((child) => emitNode(child, emitAttr, indent + 3, context)).join("\n");
+    return `${pad}{(() => {\n${pad}  const ${tagComponentName} = ${tagExpr};\n${pad}  return (\n${pad}    <${tagComponentName}${attrBlock}>\n${childBlock}\n${pad}    </${tagComponentName}>\n${pad}  );\n${pad}})()}`;
+}
 /**
  * Shared JSX/TSX tree emitter used by both React and static JSX targets.
  */
-export function emitTsxNode(node, emitAttr, indent = 0) {
+export function emitTsxNode(node, emitAttr, indent = 0, context) {
     const pad = "  ".repeat(indent);
     switch (node.kind) {
         case "text":
@@ -140,10 +248,10 @@ export function emitTsxNode(node, emitAttr, indent = 0) {
             return `${pad}{${emitTsxExpr(node.expr)}}`;
         case "if": {
             const thenPart = node.then
-                .map((child) => emitTsxNode(child, emitAttr, indent + 2))
+                .map((child) => emitTsxNode(child, emitAttr, indent + 2, context))
                 .join("\n");
             const elsePart = (node.else ?? [])
-                .map((child) => emitTsxNode(child, emitAttr, indent + 2))
+                .map((child) => emitTsxNode(child, emitAttr, indent + 2, context))
                 .join("\n");
             if (elsePart) {
                 return `${pad}{${emitTsxExpr(node.test)} ? (\n${pad}  <>\n${thenPart}\n${pad}  </>\n${pad}) : (\n${pad}  <>\n${elsePart}\n${pad}  </>\n${pad})}`;
@@ -156,35 +264,154 @@ export function emitTsxNode(node, emitAttr, indent = 0) {
                 ? `${node.item}, ${node.indexName}`
                 : `${node.item}, __index`;
             const body = node.children
-                .map((child) => emitTsxNode(child, emitAttr, indent + 2))
+                .map((child) => emitTsxNode(child, emitAttr, indent + 2, context))
                 .join("\n");
             return `${pad}{(${eachExpr} ?? []).map((${iteratorArgs}) => (\n${pad}  <>\n${body}\n${pad}  </>\n${pad}))}`;
         }
         case "element": {
+            if (node.tag.kind === "dynamic") {
+                const hoistedTagName = context?.hoistedTagNames.get(node);
+                if (hoistedTagName) {
+                    const attrEntries = Object.entries(node.attrs ?? {});
+                    const multilineOpen = `${pad}<${hoistedTagName}\n${attrEntries
+                        .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                        .join("\n")}\n${pad}>`;
+                    const children = (node.children ?? []).map((child) => emitTsxNode(child, emitAttr, indent + 1, context));
+                    if (children.length === 0) {
+                        if (attrEntries.length === 0) {
+                            return `${pad}<${hoistedTagName} />`;
+                        }
+                        return `${pad}<${hoistedTagName}\n${attrEntries
+                            .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                            .join("\n")}\n${pad}/>`;
+                    }
+                    if (attrEntries.length === 0) {
+                        return `${pad}<${hoistedTagName}>\n${children.join("\n")}\n${pad}</${hoistedTagName}>`;
+                    }
+                    return `${multilineOpen}\n${children.join("\n")}\n${pad}</${hoistedTagName}>`;
+                }
+                return emitDynamicTsxElement(emitTsxTagExpr(node.tag), "KatachiTag", node.attrs ?? {}, node.children ?? [], emitAttr, indent, emitTsxNode, context);
+            }
+            const attrEntries = Object.entries(node.attrs ?? {});
+            const multilineOpen = `${pad}<${node.tag.name}\n${attrEntries
+                .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                .join("\n")}\n${pad}>`;
+            const children = (node.children ?? []).map((child) => emitTsxNode(child, emitAttr, indent + 1, context));
+            if (children.length === 0) {
+                if (attrEntries.length === 0) {
+                    return `${pad}<${node.tag.name} />`;
+                }
+                return `${pad}<${node.tag.name}\n${attrEntries
+                    .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                    .join("\n")}\n${pad}/>`;
+            }
+            if (attrEntries.length === 0) {
+                return `${pad}<${node.tag.name}>\n${children.join("\n")}\n${pad}</${node.tag.name}>`;
+            }
+            return `${multilineOpen}\n${children.join("\n")}\n${pad}</${node.tag.name}>`;
+        }
+        case "component": {
+            const propEntries = Object.entries(node.props ?? {});
+            const multilineOpen = `${pad}<${node.name}\n${propEntries
+                .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                .join("\n")}\n${pad}>`;
+            const children = (node.children ?? []).map((child) => emitTsxNode(child, emitAttr, indent + 1, context));
+            if (children.length === 0) {
+                if (propEntries.length === 0) {
+                    return `${pad}<${node.name} />`;
+                }
+                return `${pad}<${node.name}\n${propEntries
+                    .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                    .join("\n")}\n${pad}/>`;
+            }
+            if (propEntries.length === 0) {
+                return `${pad}<${node.name}>\n${children.join("\n")}\n${pad}</${node.name}>`;
+            }
+            return `${multilineOpen}\n${children.join("\n")}\n${pad}</${node.name}>`;
+        }
+    }
+}
+/**
+ * React-specific JSX/TSX tree emitter that uses <Fragment key={...}> in .map() calls.
+ */
+export function emitReactNode(node, emitAttr, indent = 0, context) {
+    const pad = "  ".repeat(indent);
+    switch (node.kind) {
+        case "text":
+            return `${pad}${node.value}`;
+        case "slot":
+            return `${pad}{${node.name}}`;
+        case "print":
+            return `${pad}{${emitTsxExpr(node.expr)}}`;
+        case "if": {
+            const thenPart = node.then
+                .map((child) => emitReactNode(child, emitAttr, indent + 2, context))
+                .join("\n");
+            const elsePart = (node.else ?? [])
+                .map((child) => emitReactNode(child, emitAttr, indent + 2, context))
+                .join("\n");
+            if (elsePart) {
+                return `${pad}{${emitTsxExpr(node.test)} ? (\n${pad}  <>\n${thenPart}\n${pad}  </>\n${pad}) : (\n${pad}  <>\n${elsePart}\n${pad}  </>\n${pad})}`;
+            }
+            return `${pad}{${emitTsxExpr(node.test)} && (\n${pad}  <>\n${thenPart}\n${pad}  </>\n${pad})}`;
+        }
+        case "for": {
+            const eachExpr = emitTsxExpr(node.each);
+            const indexVar = node.indexName ?? "__index";
+            const iteratorArgs = `${node.item}, ${indexVar}`;
+            const body = node.children
+                .map((child) => emitReactNode(child, emitAttr, indent + 2, context))
+                .join("\n");
+            return `${pad}{(${eachExpr} ?? []).map((${iteratorArgs}) => (\n${pad}  <Fragment key={${indexVar}}>\n${body}\n${pad}  </Fragment>\n${pad}))}`;
+        }
+        case "element": {
+            if (node.tag.kind === "dynamic") {
+                const hoistedTagName = context?.hoistedTagNames.get(node);
+                if (hoistedTagName) {
+                    const attrEntries = Object.entries(node.attrs ?? {});
+                    const multilineOpen = `${pad}<${hoistedTagName}\n${attrEntries
+                        .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                        .join("\n")}\n${pad}>`;
+                    const children = (node.children ?? []).map((child) => emitReactNode(child, emitAttr, indent + 1, context));
+                    if (children.length === 0) {
+                        if (attrEntries.length === 0) {
+                            return `${pad}<${hoistedTagName} />`;
+                        }
+                        return `${pad}<${hoistedTagName}\n${attrEntries
+                            .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                            .join("\n")}\n${pad}/>`;
+                    }
+                    if (attrEntries.length === 0) {
+                        return `${pad}<${hoistedTagName}>\n${children.join("\n")}\n${pad}</${hoistedTagName}>`;
+                    }
+                    return `${multilineOpen}\n${children.join("\n")}\n${pad}</${hoistedTagName}>`;
+                }
+                return emitDynamicTsxElement(emitTsxTagExpr(node.tag), "KatachiTag", node.attrs ?? {}, node.children ?? [], emitAttr, indent, emitReactNode, context);
+            }
             const attrEntries = Object.entries(node.attrs ?? {});
-            const multilineOpen = `${pad}<${node.tag}\n${attrEntries
+            const multilineOpen = `${pad}<${node.tag.name}\n${attrEntries
                 .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
                 .join("\n")}\n${pad}>`;
-            const children = (node.children ?? []).map((child) => emitTsxNode(child, emitAttr, indent + 1));
+            const children = (node.children ?? []).map((child) => emitReactNode(child, emitAttr, indent + 1, context));
             if (children.length === 0) {
                 if (attrEntries.length === 0) {
-                    return `${pad}<${node.tag} />`;
+                    return `${pad}<${node.tag.name} />`;
                 }
-                return `${pad}<${node.tag}\n${attrEntries
+                return `${pad}<${node.tag.name}\n${attrEntries
                     .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
                     .join("\n")}\n${pad}/>`;
             }
             if (attrEntries.length === 0) {
-                return `${pad}<${node.tag}>\n${children.join("\n")}\n${pad}</${node.tag}>`;
+                return `${pad}<${node.tag.name}>\n${children.join("\n")}\n${pad}</${node.tag.name}>`;
             }
-            return `${multilineOpen}\n${children.join("\n")}\n${pad}</${node.tag}>`;
+            return `${multilineOpen}\n${children.join("\n")}\n${pad}</${node.tag.name}>`;
         }
         case "component": {
             const propEntries = Object.entries(node.props ?? {});
             const multilineOpen = `${pad}<${node.name}\n${propEntries
                 .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
                 .join("\n")}\n${pad}>`;
-            const children = (node.children ?? []).map((child) => emitTsxNode(child, emitAttr, indent + 1));
+            const children = (node.children ?? []).map((child) => emitReactNode(child, emitAttr, indent + 1, context));
             if (children.length === 0) {
                 if (propEntries.length === 0) {
                     return `${pad}<${node.name} />`;
@@ -219,6 +446,10 @@ export function toRustType(type) {
             return "i64";
         case "children":
             return "&'a str";
+        case "children[]":
+            return "&'a [&'a str]";
+        case "children[][]":
+            return "&'a [&'a [&'a str]]";
         case "string[]":
             return "&'a [&'a str]";
         case "string[][]":
@@ -237,6 +468,10 @@ export function toTsType(type) {
             return "number";
         case "children":
             return "ReactNode";
+        case "children[]":
+            return "ReactNode[]";
+        case "children[][]":
+            return "ReactNode[][]";
         default:
             return type;
     }
@@ -252,16 +487,83 @@ export function buildTsxImportLines(template) {
         .filter((line) => Boolean(line))
         .join("\n");
 }
+/**
+ * Checks whether the AST contains any "for" nodes, which means
+ * the React target needs to import Fragment.
+ */
+function astUsesForNode(node) {
+    switch (node.kind) {
+        case "for":
+            return true;
+        case "if":
+            return (node.then.some(astUsesForNode) || (node.else ?? []).some(astUsesForNode));
+        case "element":
+            return (node.children ?? []).some(astUsesForNode);
+        case "component":
+            return (node.children ?? []).some(astUsesForNode);
+        default:
+            return false;
+    }
+}
 /**
  * Wraps an emitted TSX template body in a component module.
  */
-export function buildTsxComponentSource(template, body) {
+export function buildTsxComponentSource(template, body, hoists = []) {
+    const props = template.props ?? [];
+    const propsTypeName = `${template.name}Props`;
+    const propLines = props.map((prop) => `  ${prop.name}${prop.optional ? "?" : ""}: ${toTsType(prop.type)};`);
+    const destructuredProps = props.map((prop) => prop.name).join(", ");
+    const componentImports = buildTsxImportLines(template);
+    const needsElementType = hoists.length > 0;
+    return `import type { ${needsElementType ? "ElementType, " : ""}ReactNode } from "react";
+${componentImports ? `${componentImports}\n` : ""}
+
+export type ${propsTypeName} = {
+${propLines.join("\n")}
+};
+
+export default function ${template.name}({ ${destructuredProps} }: ${propsTypeName}) {
+${hoists.join("\n")}${hoists.length > 0 ? "\n" : ""}  return (
+${body}
+  );
+}
+`;
+}
+/**
+ * Wraps an emitted React TSX template body in a component module.
+ * Only imports ReactNode when a prop uses it, and imports Fragment when needed.
+ */
+export function buildReactComponentSource(template, body, hoists = []) {
     const props = template.props ?? [];
     const propsTypeName = `${template.name}Props`;
     const propLines = props.map((prop) => `  ${prop.name}${prop.optional ? "?" : ""}: ${toTsType(prop.type)};`);
     const destructuredProps = props.map((prop) => prop.name).join(", ");
     const componentImports = buildTsxImportLines(template);
-    return `import type { ReactNode } from "react";
+    const needsReactNode = props.some((prop) => prop.type === "children" || prop.type === "children[]" || prop.type === "children[][]");
+    const needsFragment = astUsesForNode(template.template);
+    const needsElementType = hoists.length > 0;
+    const reactImports = [];
+    if (needsFragment) {
+        reactImports.push("Fragment");
+    }
+    const reactTypeImports = [];
+    if (needsElementType) {
+        reactTypeImports.push("ElementType");
+    }
+    if (needsReactNode) {
+        reactTypeImports.push("ReactNode");
+    }
+    let importLine = "";
+    if (reactImports.length > 0 && reactTypeImports.length > 0) {
+        importLine = `import { ${reactImports.join(", ")}, type ${reactTypeImports.join(", type ")} } from "react";`;
+    }
+    else if (reactImports.length > 0) {
+        importLine = `import { ${reactImports.join(", ")} } from "react";`;
+    }
+    else if (reactTypeImports.length > 0) {
+        importLine = `import type { ${reactTypeImports.join(", ")} } from "react";`;
+    }
+    return `${importLine}
 ${componentImports ? `${componentImports}\n` : ""}
 
 export type ${propsTypeName} = {
@@ -269,10 +571,17 @@ ${propLines.join("\n")}
 };
 
 export default function ${template.name}({ ${destructuredProps} }: ${propsTypeName}) {
-  return (
+${hoists.join("\n")}${hoists.length > 0 ? "\n" : ""}  return (
 ${body}
   );
 }
 `;
 }
+export function emitTsxWithHoists(template, emitNode, emitAttr) {
+    const { context, hoists } = buildTsxEmitContext(template);
+    return {
+        body: emitNode(template.template, emitAttr, 2, context),
+        hoists,
+    };
+}
 export { escapeDoubleQuotes, wrapHtmlAttribute };

package/dist/targets/static-jsx.js

@@ -1,4 +1,4 @@
-import { buildTsxComponentSource, emitTsxExpr, emitTsxNode } from "./shared.js";
+import { buildTsxComponentSource, emitTsxExpr, emitTsxNode, emitTsxWithHoists } from "./shared.js";
 /**
  * Emits TSX meant to read more statically by inlining class string interpolation.
  */
@@ -14,15 +14,28 @@ function emitStaticJsxAttr(name, value) {
                 if (item.kind === "static") {
                     return item.value;
                 }
+                if (item.kind === "dynamic") {
+                    return `\${${emitTsxExpr(item.expr)}}`;
+                }
                 return `\${${emitTsxExpr(item.test)} ? ${JSON.stringify(item.value)} : ""}`;
             });
             return `${attrName}={\`${segments.join(" ").trim()}\`}`;
         }
+        case "concat": {
+            const segments = value.parts.map((part) => {
+                if (part.kind === "string") {
+                    return part.value;
+                }
+                return `\${${emitTsxExpr(part)}}`;
+            });
+            return `${attrName}={\`${segments.join("")}\`}`;
+        }
     }
 }
 export function emitStaticJsx(node, indent = 0) {
     return emitTsxNode(node, emitStaticJsxAttr, indent);
 }
 export function emitStaticJsxComponent(template) {
-    return buildTsxComponentSource(template, emitStaticJsx(template.template, 2));
+    const { body, hoists } = emitTsxWithHoists(template, emitTsxNode, emitStaticJsxAttr);
+    return buildTsxComponentSource(template, body, hoists);
 }

package/docs/architecture.md

@@ -62,7 +62,6 @@ Responsibilities:
 - normalize `className` to internal `class`
 - convert `If` and `For`
 - convert `{children}` to slot nodes
-- convert `{safe(value)}` to safe print nodes
 - resolve imported template components later during build
 
 The parser is currently handwritten and string-based. That is fine for a prototype, but a stronger long-term direction is to parse real TSX via Babel, SWC, or the TypeScript compiler and then lower from that AST.

package/docs/getting-started.md

@@ -118,11 +118,13 @@ By default, Katachi writes:
 - `dist/jsx-static/**/*.tsx`
 - `dist/askama/**/*.rs`
 - `dist/askama/includes/**/*.html`
+- `dist/liquid/snippets/**/*.liquid`
 
 Typical usage:
 
 - use `dist/react` in your editor or React app
 - use `dist/askama` and `dist/askama/includes` in your Rust/Askama app
+- use `dist/liquid/snippets` in Shopify themes or other Liquid consumers
 
 If you are evaluating Katachi for a shared component library, this is the
 normal model: author once, then consume the generated output from each target

package/docs/syntax.md

@@ -21,7 +21,7 @@ A template file should export:
 Example:
 
 ```tsx
-import { For, If, isEmpty, len, safe, type TemplateNode } from "@relevate/katachi";
+import { Element, For, If, isEmpty, len, type TemplateNode } from "@relevate/katachi";
 
 export type Props = {
   title: string;
@@ -32,9 +32,9 @@ export type Props = {
 export default function Example({ title, rows, children }: Props) {
   return (
     <section>
-      <h2>{title}</h2>
+      <Element tag={["h", 2]}>{title}</Element>
       <For each={rows} as="row">
-        <div>{safe(row[0])}</div>
+        <div>{row[0]}</div>
       </For>
       <If test={len(rows) == 0}>
         <p>Empty</p>
@@ -63,6 +63,22 @@ Normal lowercase JSX tags work as expected:
 <img src={src} alt={alt} />
 ```
 
+### Dynamic intrinsic elements
+
+Use `Element` when the tag name itself needs to vary.
+
+```tsx
+import { Element } from "@relevate/katachi";
+
+<Element tag={["h", level]} className="headline">
+  {title}
+</Element>
+```
+
+`tag` accepts either a plain expression like `tag={tagName}` or a structured
+tuple like `tag={["h", level]}` when you want a fixed prefix with one dynamic
+part.
+
 ### Imported template components
 
 Capitalized tags are treated as template component invocations.
@@ -119,16 +135,27 @@ Optional index binding:
 </For>
 ```
 
-### `safe(...)`
+### `TemplateNode`
 
-Use `safe(...)` for raw/safe HTML output.
+Use `TemplateNode` for props or children that carry markup-like content.
 
 ```tsx
-import { safe } from "@relevate/katachi";
+import type { TemplateNode } from "@relevate/katachi";
 
-<div>{safe(value)}</div>
+type Props = {
+  title_html: TemplateNode;
+  children?: TemplateNode;
+};
+
+<h2>{title_html}</h2>
+<div>{children}</div>
 ```
 
+For Askama output, `TemplateNode` values are treated as markup content and are
+emitted with `|safe`. On Liquid output, they are emitted as plain Liquid
+output, so trusted or sanitized HTML should be handled before it reaches the
+target.
+
 ### Portable helpers
 
 Use Katachi's portable helpers instead of target-specific template methods.
@@ -202,8 +229,8 @@ portable helpers in new Katachi templates:
 - `ClassValue`
 - `TemplateNode`
 - `If`
+- `Element`
 - `For`
-- `safe`
 - `len`
 - `isEmpty`
 - `isSome`

package/docs/targets.md

@@ -31,11 +31,19 @@ outputs in a real project.
 - file type: `.html`
 - purpose: Askama partial output
 
+### `liquid`
+
+- output folder: `dist/liquid/snippets`
+- file type: `.liquid`
+- purpose: Shopify Liquid snippet output
+
 ## Which output should you use?
 
 - Use `dist/react` if your consumer is a React app or an editor surface built in React.
 - Use `dist/jsx-static` if you want a TSX artifact that reads a bit more statically.
 - Use `dist/askama` and `dist/askama/includes` if your consumer is Rust + Askama.
+- Use `dist/liquid/snippets` if your consumer is a Shopify theme or another
+  Liquid environment.
 
 ## Relative imports and includes
 
@@ -45,6 +53,14 @@ That means:
 
 - a nested React component import stays relative in `dist/react`
 - a nested Askama include stays relative in `dist/askama/includes`
+- a nested Shopify Liquid component becomes a `{% render %}` call using the
+  snippet path in `dist/liquid/snippets`
+
+## Liquid-specific notes
+
+- The Liquid target emits Shopify-compatible snippet files.
+- `TemplateNode` values lower to plain Liquid output on this target, so trusted
+  or sanitized HTML should be handled before the Liquid layer.
 
 ## Internal note
 

package/examples/basic/README.md

@@ -17,7 +17,7 @@ usage:
 - dynamic `className` arrays
 - `If`
 - nested `For`
-- `safe(...)`
+- `TemplateNode` content props
 - mixed HTML and expression attributes
 
 ## Example components
@@ -44,6 +44,7 @@ That writes generated output to:
 - `examples/basic/dist/react`
 - `examples/basic/dist/jsx-static`
 - `examples/basic/dist/askama`
+- `examples/basic/dist/liquid/snippets`
 
 ## Verify the public Askama fixtures