@relevate/katachi 0.1.0

package/dist/targets/shared.js

@@ -0,0 +1,278 @@
+/**
+ * Escapes a string for insertion into Rust string literals used by Askama wrappers.
+ */
+function escapeDoubleQuotes(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * Chooses a stable quote style for generated HTML attributes so mixed template
+ * syntax stays readable and editor highlighting does not break.
+ */
+function wrapHtmlAttribute(value) {
+    if (!value.includes("'")) {
+        return `'${value}'`;
+    }
+    if (!value.includes('"')) {
+        return `"${value}"`;
+    }
+    return `'${value.replace(/'/g, "'")}'`;
+}
+/**
+ * Best-effort translation of Rust-ish template expressions into TSX-friendly syntax.
+ *
+ * This exists to support incremental Askama migrations. It is not the ideal
+ * final authoring model, but it keeps existing ports workable.
+ */
+function translateRustExprToTsx(source) {
+    let result = source.trim();
+    result = result.replace(/([A-Za-z0-9_().]+)\.clone\(\)\.unwrap\(\)/g, "$1");
+    result = result.replace(/([A-Za-z0-9_().]+)\.unwrap\(\)/g, "$1");
+    result = result.replace(/([A-Za-z0-9_().]+)\.is_some\(\)/g, "($1 != null)");
+    result = result.replace(/([A-Za-z0-9_().]+)\.is_none\(\)/g, "($1 == null)");
+    result = result.replace(/!\s*([A-Za-z0-9_().]+)\.is_empty\(\)/g, "($1.length > 0)");
+    result = result.replace(/([A-Za-z0-9_().]+)\.is_empty\(\)/g, "($1.length === 0)");
+    result = result.replace(/([A-Za-z0-9_().]+)\.len\(\)/g, "$1.length");
+    result = result.replace(/\s===\s/g, " === ");
+    result = result.replace(/\s!==\s/g, " !== ");
+    result = result.replace(/\s==\s/g, " === ");
+    result = result.replace(/\s!=\s/g, " !== ");
+    return result;
+}
+/**
+ * Rewrites JS/TS equality operators into Askama-compatible syntax.
+ */
+function translateTsxExprToAskama(source) {
+    return source.replace(/\s===\s/g, " == ").replace(/\s!==\s/g, " != ");
+}
+/**
+ * Emits a portable expression into TSX/React-family output.
+ */
+export function emitTsxExpr(expr) {
+    switch (expr.kind) {
+        case "var":
+            return expr.name;
+        case "string":
+            return JSON.stringify(expr.value);
+        case "bool":
+            return expr.value ? "true" : "false";
+        case "number":
+            return String(expr.value);
+        case "intrinsic": {
+            const [arg] = expr.args;
+            const emittedArg = arg ? emitTsxExpr(arg) : "undefined";
+            switch (expr.name) {
+                case "len":
+                    return `(${emittedArg}?.length ?? 0)`;
+                case "isEmpty":
+                    return `((${emittedArg}?.length ?? 0) === 0)`;
+                case "isSome":
+                    return `(${emittedArg} != null)`;
+                case "isNone":
+                    return `(${emittedArg} == null)`;
+            }
+        }
+        case "raw":
+            return translateRustExprToTsx(expr.source);
+        case "eq":
+            return `(${emitTsxExpr(expr.left)} === ${emitTsxExpr(expr.right)})`;
+        case "neq":
+            return `(${emitTsxExpr(expr.left)} !== ${emitTsxExpr(expr.right)})`;
+        case "and":
+            return `(${emitTsxExpr(expr.left)} && ${emitTsxExpr(expr.right)})`;
+        case "or":
+            return `(${emitTsxExpr(expr.left)} || ${emitTsxExpr(expr.right)})`;
+        case "not":
+            return `!(${emitTsxExpr(expr.expr)})`;
+    }
+}
+/**
+ * Emits a portable expression into Askama syntax.
+ */
+export function emitAskamaExpr(expr) {
+    switch (expr.kind) {
+        case "var":
+            return expr.name;
+        case "string":
+            return `"${escapeDoubleQuotes(expr.value)}"`;
+        case "bool":
+            return expr.value ? "true" : "false";
+        case "number":
+            return String(expr.value);
+        case "intrinsic": {
+            const [arg] = expr.args;
+            const emittedArg = arg ? emitAskamaExpr(arg) : "";
+            switch (expr.name) {
+                case "len":
+                    return `${emittedArg}.len()`;
+                case "isEmpty":
+                    return `${emittedArg}.is_empty()`;
+                case "isSome":
+                    return `${emittedArg}.is_some()`;
+                case "isNone":
+                    return `${emittedArg}.is_none()`;
+            }
+        }
+        case "raw":
+            return translateTsxExprToAskama(expr.source);
+        case "eq":
+            return `${emitAskamaExpr(expr.left)} == ${emitAskamaExpr(expr.right)}`;
+        case "neq":
+            return `${emitAskamaExpr(expr.left)} != ${emitAskamaExpr(expr.right)}`;
+        case "and":
+            return `${emitAskamaExpr(expr.left)} && ${emitAskamaExpr(expr.right)}`;
+        case "or":
+            return `${emitAskamaExpr(expr.left)} || ${emitAskamaExpr(expr.right)}`;
+        case "not":
+            return `!(${emitAskamaExpr(expr.expr)})`;
+    }
+}
+/**
+ * Shared JSX/TSX tree emitter used by both React and static JSX targets.
+ */
+export function emitTsxNode(node, emitAttr, indent = 0) {
+    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) => emitTsxNode(child, emitAttr, indent + 2))
+                .join("\n");
+            const elsePart = (node.else ?? [])
+                .map((child) => emitTsxNode(child, emitAttr, indent + 2))
+                .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 iteratorArgs = node.indexName
+                ? `${node.item}, ${node.indexName}`
+                : `${node.item}, __index`;
+            const body = node.children
+                .map((child) => emitTsxNode(child, emitAttr, indent + 2))
+                .join("\n");
+            return `${pad}{(${eachExpr} ?? []).map((${iteratorArgs}) => (\n${pad}  <>\n${body}\n${pad}  </>\n${pad}))}`;
+        }
+        case "element": {
+            const attrEntries = Object.entries(node.attrs ?? {});
+            const multilineOpen = `${pad}<${node.tag}\n${attrEntries
+                .map(([name, value]) => `${pad}  ${emitAttr(name, value)}`)
+                .join("\n")}\n${pad}>`;
+            const children = (node.children ?? []).map((child) => emitTsxNode(child, emitAttr, indent + 1));
+            if (children.length === 0) {
+                if (attrEntries.length === 0) {
+                    return `${pad}<${node.tag} />`;
+                }
+                return `${pad}<${node.tag}\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 `${multilineOpen}\n${children.join("\n")}\n${pad}</${node.tag}>`;
+        }
+        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));
+            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}>`;
+        }
+    }
+}
+function toPascalCase(value) {
+    return value
+        .replace(/(^|[-_ ]+)([a-zA-Z0-9])/g, (_match, _sep, char) => char.toUpperCase())
+        .replace(/[^a-zA-Z0-9]/g, "");
+}
+export function toCamelCase(value) {
+    const pascal = toPascalCase(value);
+    return pascal.length === 0 ? pascal : pascal[0].toLowerCase() + pascal.slice(1);
+}
+export function toRustType(type) {
+    switch (type) {
+        case "string":
+            return "&'a str";
+        case "bool":
+            return "bool";
+        case "number":
+            return "i64";
+        case "children":
+            return "&'a str";
+        case "string[]":
+            return "&'a [&'a str]";
+        case "string[][]":
+            return "&'a [&'a [&'a str]]";
+        default:
+            return "&'a str";
+    }
+}
+export function toTsType(type) {
+    switch (type) {
+        case "string":
+            return "string";
+        case "bool":
+            return "boolean";
+        case "number":
+            return "number";
+        case "children":
+            return "ReactNode";
+        default:
+            return type;
+    }
+}
+/**
+ * Builds import lines for nested template components in TSX-family targets.
+ */
+export function buildTsxImportLines(template) {
+    return (template.imports ?? [])
+        .map((entry) => template.componentRegistry?.[entry.localName]?.reactImport
+        ? `import ${entry.localName} from "${template.componentRegistry[entry.localName].reactImport}";`
+        : null)
+        .filter((line) => Boolean(line))
+        .join("\n");
+}
+/**
+ * Wraps an emitted TSX template body in a component module.
+ */
+export function buildTsxComponentSource(template, body) {
+    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";
+${componentImports ? `${componentImports}\n` : ""}
+
+export type ${propsTypeName} = {
+${propLines.join("\n")}
+};
+
+export default function ${template.name}({ ${destructuredProps} }: ${propsTypeName}) {
+  return (
+${body}
+  );
+}
+`;
+}
+export { escapeDoubleQuotes, wrapHtmlAttribute };

package/dist/targets/static-jsx.d.ts

@@ -0,0 +1,4 @@
+import type { Node } from "../core/ast.js";
+import type { BuildTemplate } from "../core/types.js";
+export declare function emitStaticJsx(node: Node, indent?: number): string;
+export declare function emitStaticJsxComponent(template: BuildTemplate): string;

package/dist/targets/static-jsx.js

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

package/dist/verify-examples.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/verify-examples.js

@@ -0,0 +1,14 @@
+import { buildProject } from "./core/build.js";
+import { verifyAskamaFixtures } from "./core/verify.js";
+import { basicExampleRoot, exampleFixtures } from "./core/example-fixtures.js";
+/**
+ * Verifies a small public Askama fixture set that ships with the repository.
+ * This is intended for OSS consumers and repo contributors as the public
+ * end-to-end smoke test project.
+ */
+buildProject({
+    projectRoot: basicExampleRoot,
+});
+verifyAskamaFixtures({
+    fixtures: exampleFixtures,
+});

package/docs/architecture.md

@@ -0,0 +1,122 @@
+# Architecture
+
+This document is for contributors working on Katachi itself.
+
+Katachi has four major layers:
+
+1. Authoring input
+2. Parser
+3. Portable AST
+4. Target emitters
+
+## Flow
+
+```txt
+src/templates/**/*.template.tsx
+  -> core/parser.ts
+  -> core/ast.ts node model
+  -> target emitters
+  -> dist/*
+```
+
+## Canonical source
+
+The canonical source is restricted TSX, not React semantics and not Askama syntax.
+
+That distinction matters:
+
+- authoring uses TSX because it is ergonomic
+- the compiler owns the meaning of that TSX subset
+- outputs are generated for each target separately
+
+## AST
+
+[src/core/ast.ts](../src/core/ast.ts) defines the portable template model.
+[src/core/types.ts](../src/core/types.ts) defines the shared compiler interfaces around that model.
+
+Key node kinds:
+
+- `text`
+- `slot`
+- `print`
+- `if`
+- `for`
+- `element`
+- `component`
+
+Key attribute kinds:
+
+- `text`
+- `expr`
+- `classList`
+
+This AST is the real source of truth once parsing is complete.
+
+## Parser
+
+[src/core/parser.ts](../src/core/parser.ts) lowers restricted TSX into AST nodes.
+
+Responsibilities:
+
+- parse elements and attributes
+- 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.
+
+## Targets
+
+Each output format gets its own emitter module:
+
+- [src/targets/react.ts](../src/targets/react.ts)
+- [src/targets/static-jsx.ts](../src/targets/static-jsx.ts)
+- [src/targets/askama.ts](../src/targets/askama.ts)
+
+Shared cross-target emitter helpers live in:
+
+- [src/targets/shared.ts](../src/targets/shared.ts)
+
+The build registry is:
+
+- [src/targets/index.ts](../src/targets/index.ts)
+
+## Build entrypoint
+
+[src/core/build.ts](../src/core/build.ts) does project-level orchestration:
+
+- scan template files
+- parse all templates
+- resolve template imports
+- build per-template component registries
+- invoke each configured output target
+- write files into `dist/`
+
+## Verification
+
+[src/core/verify.ts](../src/core/verify.ts) compares generated Askama partials against expected Askama fixtures.
+
+That comparison uses normalization so it can separate:
+
+- exact match
+- format-only differences
+- functional differences
+
+This is currently the main regression safety net for Askama output.
+
+## Design principles
+
+- one canonical semantic representation
+- targets own their own emission strategy
+- authoring should be ergonomic
+- compiler internals should stay target-agnostic where possible
+- generated output should become more target-idiomatic over time
+
+## Near-term architecture improvements
+
+- replace the handwritten parser with a real TSX AST pipeline
+- formalize the target interface further
+- add a reusable programmatic API separate from the build script
+- decide whether to keep a single-package repo or split `core` and `cli` packages later

package/docs/getting-started.md

@@ -0,0 +1,154 @@
+# Getting Started
+
+This guide is for using Katachi in your own project, not for working on the
+Katachi repository itself.
+
+## 1. Install Katachi
+
+With pnpm:
+
+```bash
+pnpm add -D @relevate/katachi
+```
+
+With npm:
+
+```bash
+npm install --save-dev @relevate/katachi
+```
+
+If you only want to try it without installing it first:
+
+```bash
+pnpm dlx @relevate/katachi build
+```
+
+or:
+
+```bash
+npx @relevate/katachi build
+```
+
+## 2. Update `tsconfig.json`
+
+Katachi templates use TSX syntax, but they are not normal React components.
+Tell TypeScript to load Katachi's JSX typing layer:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "types": ["node", "@relevate/katachi/jsx"]
+  }
+}
+```
+
+If you already use a `types` array, append `@relevate/katachi/jsx` instead of
+replacing your existing entries.
+
+## 3. Create a template
+
+By default, Katachi reads from:
+
+```txt
+src/templates/**/*.template.tsx
+```
+
+Example:
+
+```tsx
+import { If, type TemplateNode } from "@relevate/katachi";
+
+export type Props = {
+  tone: "calm" | "urgent";
+  title: string;
+  children?: TemplateNode;
+};
+
+export default function NoticePanel({ tone, title, children }: Props) {
+  return (
+    <aside
+      className={[
+        "rounded-3xl border px-5 py-4",
+        tone == "calm" && "border-sky-200 bg-sky-50/80",
+        tone == "urgent" && "border-rose-200 bg-rose-50/80",
+      ]}
+    >
+      <h3>{title}</h3>
+      <If test={tone == "urgent"}>
+        <p>Action recommended</p>
+      </If>
+      {children}
+    </aside>
+  );
+}
+```
+
+## 4. Build outputs
+
+From your project root:
+
+```bash
+pnpm exec katachi build
+```
+
+Without installing locally:
+
+```bash
+pnpm dlx @relevate/katachi build
+```
+
+With npm:
+
+```bash
+npx @relevate/katachi build
+```
+
+You can also point Katachi at custom paths:
+
+```bash
+pnpm exec katachi build --templates ./katachi/templates --dist ./generated
+```
+
+## 5. Consume the generated files
+
+By default, Katachi writes:
+
+- `dist/react/**/*.tsx`
+- `dist/jsx-static/**/*.tsx`
+- `dist/askama/**/*.rs`
+- `dist/askama/includes/**/*.html`
+
+Typical usage:
+
+- use `dist/react` in your editor or React app
+- use `dist/askama` and `dist/askama/includes` in your Rust/Askama app
+
+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
+environment.
+
+## Nested components
+
+Import other Katachi templates with the `.template` path:
+
+```tsx
+import Glyph from "./glyph.template";
+```
+
+Then use them as normal capitalized TSX components:
+
+```tsx
+<Glyph name="spark" size="16" tone="calm" className="h-4 w-4" />
+```
+
+Katachi resolves those imports into:
+
+- TSX imports for React output
+- Askama include wiring for Askama output
+
+## Next steps
+
+- See [syntax.md](./syntax.md) for the supported syntax.
+- See [targets.md](./targets.md) for output details.
+- See [../examples/basic/README.md](../examples/basic/README.md) for a fuller consumer-style example.