@relevate/katachi 0.1.0

package/docs/syntax.md

@@ -0,0 +1,236 @@
+# Template Syntax
+
+Katachi templates are written in restricted TSX.
+
+That means:
+
+- templates look like TSX
+- editors can parse them
+- the compiler only accepts a subset that can lower cleanly into the portable AST
+
+This guide focuses on the supported syntax you can use in a normal Katachi
+project.
+
+## File shape
+
+A template file should export:
+
+- `Props`
+- a default component function
+
+Example:
+
+```tsx
+import { For, If, isEmpty, len, safe, type TemplateNode } from "@relevate/katachi";
+
+export type Props = {
+  title: string;
+  rows: string[][];
+  children?: TemplateNode;
+};
+
+export default function Example({ title, rows, children }: Props) {
+  return (
+    <section>
+      <h2>{title}</h2>
+      <For each={rows} as="row">
+        <div>{safe(row[0])}</div>
+      </For>
+      <If test={len(rows) == 0}>
+        <p>Empty</p>
+      </If>
+      {children}
+    </section>
+  );
+}
+```
+
+In a real project, place these files in:
+
+```txt
+src/templates/**/*.template.tsx
+```
+
+## Supported constructs
+
+### Intrinsic elements
+
+Normal lowercase JSX tags work as expected:
+
+```tsx
+<div />
+<span>{value}</span>
+<img src={src} alt={alt} />
+```
+
+### Imported template components
+
+Capitalized tags are treated as template component invocations.
+
+```tsx
+import Icon from "./icon.template";
+
+<Icon icon="search" size="16" />
+```
+
+### Children and slots
+
+`children` is treated as a slot.
+
+```tsx
+type Props = {
+  children?: TemplateNode;
+};
+```
+
+```tsx
+<div>{children}</div>
+```
+
+### `If`
+
+Use `If` for conditional rendering.
+
+```tsx
+import { If } from "@relevate/katachi";
+
+<If test={variant == "warning"}>
+  <p>Warning</p>
+</If>
+```
+
+### `For`
+
+Use `For` for loops.
+
+```tsx
+import { For } from "@relevate/katachi";
+
+<For each={rows} as="row">
+  <div>{row}</div>
+</For>
+```
+
+Optional index binding:
+
+```tsx
+<For each={rows} as="row" index="i">
+  <div>{i}</div>
+</For>
+```
+
+### `safe(...)`
+
+Use `safe(...)` for raw/safe HTML output.
+
+```tsx
+import { safe } from "@relevate/katachi";
+
+<div>{safe(value)}</div>
+```
+
+### Portable helpers
+
+Use Katachi's portable helpers instead of target-specific template methods.
+
+```tsx
+import { If, isEmpty, isNone, isSome, len } from "@relevate/katachi";
+
+<If test={len(rows) == 0}>
+  <p>Empty</p>
+</If>
+
+<If test={isSome(breadcrumbs)}>
+  <div>{breadcrumbs}</div>
+</If>
+
+<If test={isNone(errorMessage) || isEmpty(errorMessage)}>
+  <p>No details</p>
+</If>
+```
+
+### Dynamic classes
+
+Both `class` and `className` are supported in authoring input.
+
+```tsx
+<div
+  className={[
+    "rounded-xl border",
+    variant == "note" && "border-primary/20 bg-primary/5",
+    variant == "warning" && "border-amber-500/20 bg-amber-50/50",
+  ]}
+/>
+```
+
+This is Katachi syntax hosted in TSX. The compiler normalizes it and emits target-specific output.
+
+## Expressions
+
+Supported directly:
+
+- variables
+- string literals
+- boolean literals
+- number literals
+- `==`, `!=`, `===`, `!==`
+- `&&`
+- `||`
+- `!`
+
+Best-effort passthrough currently exists for some Rust-ish expressions:
+
+- `.len()`
+- `.is_empty()`
+- `.is_some()`
+- `.is_none()`
+- `.unwrap()`
+- `.clone().unwrap()`
+
+These are migration shims for existing Askama-style templates. Prefer the
+portable helpers in new Katachi templates:
+
+- `len(value)`
+- `isEmpty(value)`
+- `isSome(value)`
+- `isNone(value)`
+
+## Helper exports
+
+`@relevate/katachi` exports:
+
+- `ClassValue`
+- `TemplateNode`
+- `If`
+- `For`
+- `safe`
+- `len`
+- `isEmpty`
+- `isSome`
+- `isNone`
+
+These are the public helper exports you use inside template files.
+
+## What is not supported
+
+Not all TSX is valid Katachi input.
+
+Examples of unsupported or intentionally out-of-scope areas:
+
+- hooks
+- arbitrary function calls as template logic
+- local mutation
+- arbitrary statements in component bodies
+- imports used for runtime React behavior
+- framework-specific runtime features
+
+In practice, treat template files as declarative template sources, not general
+React modules.
+
+## Recommended style
+
+- keep component bodies declarative
+- prefer `If` and `For` instead of ad hoc expression trees
+- use imported Katachi templates for nested components
+- prefer `className` in authoring files for editor familiarity
+- keep prop types simple and serializable where possible

package/docs/targets.md

@@ -0,0 +1,53 @@
+# Targets
+
+Katachi emits multiple outputs from the same template source.
+
+This guide is about what gets generated and how you would typically use those
+outputs in a real project.
+
+## Current targets
+
+### `react`
+
+- output folder: `dist/react`
+- file type: `.tsx`
+- purpose: React-consumable component output for apps and editor environments
+
+### `jsx-static`
+
+- output folder: `dist/jsx-static`
+- file type: `.tsx`
+- purpose: TSX output oriented toward static readability
+
+### `askama`
+
+- output folder: `dist/askama`
+- file type: `.rs`
+- purpose: Rust Askama wrapper output
+
+### `askama-includes`
+
+- output folder: `dist/askama/includes`
+- file type: `.html`
+- purpose: Askama partial 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.
+
+## Relative imports and includes
+
+Nested Katachi templates keep their relative structure in generated output.
+
+That means:
+
+- a nested React component import stays relative in `dist/react`
+- a nested Askama include stays relative in `dist/askama/includes`
+
+## Internal note
+
+If you are extending Katachi itself, the target registry lives in
+[src/targets/index.ts](../src/targets/index.ts), and each target has its own
+emitter module under [src/targets](../src/targets).

package/examples/basic/README.md

@@ -0,0 +1,67 @@
+# Basic Example
+
+This example is a small consumer-style Katachi project you can copy from when
+setting up your own repo.
+
+It includes:
+
+- authoring templates in `src/templates/`
+- a `tsconfig.json` that adds `@relevate/katachi/jsx` to `compilerOptions.types`
+- expected Askama partials in `components/`
+
+The example templates intentionally cover a useful slice of normal Katachi
+usage:
+
+- simple wrappers with `children`
+- imported nested components
+- dynamic `className` arrays
+- `If`
+- nested `For`
+- `safe(...)`
+- mixed HTML and expression attributes
+
+## Example components
+
+- `badge-chip.template.tsx`
+- `comparison-table.template.tsx`
+- `glyph.template.tsx`
+- `hover-note.template.tsx`
+- `media-frame.template.tsx`
+- `notice-panel.template.tsx`
+- `resource-tile.template.tsx`
+- `stack-shell.template.tsx`
+
+## Build the example project
+
+From the Katachi repo root:
+
+```bash
+pnpm exec katachi build --project ./examples/basic
+```
+
+That writes generated output to:
+
+- `examples/basic/dist/react`
+- `examples/basic/dist/jsx-static`
+- `examples/basic/dist/askama`
+
+## Verify the public Askama fixtures
+
+From the Katachi repo root:
+
+```bash
+pnpm verify:examples
+```
+
+That builds `examples/basic` and compares the generated Askama partials against
+the expected files in `examples/basic/components`.
+
+If you are trying to understand how a consumer project should look, start here
+and then read [docs/getting-started.md](../../docs/getting-started.md).
+
+The important parts to copy into your own project are:
+
+- `src/templates/`
+- `tsconfig.json`
+- the `@relevate/katachi/jsx` type entry
+- your chosen `katachi build` command

package/examples/basic/components/badge-chip.html

@@ -0,0 +1,3 @@
+<span class="inline-flex items-center rounded-full px-2.5 py-1 text-xs font-semibold tracking-wide {% if tone == "neutral" %}bg-slate-100 text-slate-700{% endif %} {% if tone == "accent" %}bg-amber-100 text-amber-700{% endif %}">
+  {{ label }}
+</span>

package/examples/basic/components/comparison-table.html

@@ -0,0 +1,24 @@
+<div class="overflow-x-auto rounded-3xl border border-slate-200 bg-white">
+  <table class="min-w-full divide-y divide-slate-200">
+    <thead>
+      <tr>
+        {% for cell in head %}
+          <th class="bg-slate-50 px-4 py-3 text-left text-xs font-semibold uppercase tracking-[0.2em] text-slate-500">
+            {{ cell|safe }}
+          </th>
+        {% endfor %}
+      </tr>
+    </thead>
+    <tbody>
+      {% for row in rows %}
+        <tr class="odd:bg-white even:bg-slate-50/60">
+          {% for cell in row %}
+            <td class="px-4 py-3 text-sm text-slate-700">
+              {{ cell|safe }}
+            </td>
+          {% endfor %}
+        </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</div>

package/examples/basic/components/glyph.html

@@ -0,0 +1,6 @@
+<svg
+  class="{{ className }}"
+  data-tone="{{ tone }}"
+  data-size="{{ size }}"
+  data-name="{{ name }}"
+/>

package/examples/basic/components/hover-note.html

@@ -0,0 +1,6 @@
+<span
+  data-hover-note="{{ label }}"
+  class="cursor-help underline decoration-dotted underline-offset-4"
+>
+  {{ children|safe }}
+</span>

package/examples/basic/components/media-frame.html

@@ -0,0 +1,15 @@
+<figure class="overflow-hidden rounded-[28px] border border-slate-200 bg-white shadow-sm">
+  {% if eyebrow != null %}
+    <div class="border-b border-slate-200 px-5 py-3 text-[11px] font-semibold uppercase tracking-[0.28em] text-slate-500">
+      {{ eyebrow }}
+    </div>
+  {% endif %}
+  <div class="bg-slate-50 p-4">
+    {{ children|safe }}
+  </div>
+  {% if caption_html != null %}
+    <figcaption class="border-t border-slate-200 px-5 py-4 text-sm leading-6 text-slate-600">
+      {{ caption_html|safe }}
+    </figcaption>
+  {% endif %}
+</figure>

package/examples/basic/components/notice-panel.html

@@ -0,0 +1,24 @@
+<aside
+  class="rounded-3xl border px-5 py-4 backdrop-blur-sm {% if tone == "calm" %}border-sky-200 bg-sky-50/80{% endif %} {% if tone == "urgent" %}border-rose-200 bg-rose-50/80{% endif %} {% if tone == "success" %}border-emerald-200 bg-emerald-50/80{% endif %}"
+>
+  <div class="flex items-start gap-3">
+    {% let className = "mt-0.5 h-5 w-5 shrink-0" %}
+    {% let tone = tone %}
+    {% let size = "18" %}
+    {% let name = icon %}
+    {% include "./includes/glyph.html" %}
+    <div class="min-w-0 flex-1">
+      <h3 class="text-sm font-semibold tracking-tight">
+        {{ title }}
+      </h3>
+      <div class="mt-2 text-sm leading-6 text-slate-700">
+        {{ children|safe }}
+      </div>
+    </div>
+  </div>
+  {% if tone == "urgent" %}
+    <p class="mt-3 text-xs font-medium uppercase tracking-[0.24em] text-rose-700">
+      Action recommended
+    </p>
+  {% endif %}
+</aside>

package/examples/basic/components/resource-tile.html

@@ -0,0 +1,24 @@
+<li class="list-none" role="option" tabIndex="{{ -1 }}" aria-selected="{{ selected }}">
+  <a href="{{ href }}" class="group block rounded-2xl border border-slate-200 bg-white p-4 transition hover:border-slate-300 hover:shadow-sm">
+    <div class="flex items-start gap-3">
+      {% let className = "mt-0.5 h-5 w-5 shrink-0 text-slate-500" %}
+      {% let tone = "slate" %}
+      {% let size = "18" %}
+      {% let name = icon %}
+      {% include "./includes/glyph.html" %}
+      <div class="min-w-0 flex-1">
+        {% if eyebrow_html != null %}
+          <div class="truncate text-xs font-medium uppercase tracking-[0.2em] text-slate-500">
+            {{ eyebrow_html|safe }}
+          </div>
+        {% endif %}
+        <div class="mt-1 truncate text-sm font-semibold text-slate-900">
+          {{ title_html|safe }}
+        </div>
+        <p class="mt-1 text-sm leading-6 text-slate-600">
+          {{ summary_html|safe }}
+        </p>
+      </div>
+    </div>
+  </a>
+</li>

package/examples/basic/components/stack-shell.html

@@ -0,0 +1,3 @@
+<section class="mx-auto max-w-4xl space-y-6 rounded-[28px] border border-slate-200 bg-white/90 p-6 shadow-[0_24px_80px_-40px_rgba(15,23,42,0.45)]">
+  {{ children|safe }}
+</section>

package/examples/basic/dist/askama/badge-chip.rs

@@ -0,0 +1,18 @@
+use askama::Template;
+
+#[derive(Template)]
+#[template(
+    ext = "html",
+    source = r#"
+<span
+  class='inline-flex items-center rounded-full px-2.5 py-1 text-xs font-semibold tracking-wide {% if tone == "neutral" %}bg-slate-100 text-slate-700{% endif %} {% if tone == "accent" %}bg-amber-100 text-amber-700{% endif %}'
+>
+  {{ label }}
+</span>
+"#
+)]
+pub struct BadgeChipTemplate<'a> {
+    pub label: &'a str,
+    pub tone: &'a str,
+}
+

package/examples/basic/dist/askama/comparison-table.rs

@@ -0,0 +1,47 @@
+use askama::Template;
+
+#[derive(Template)]
+#[template(
+    ext = "html",
+    source = r#"
+<div
+  class='overflow-x-auto rounded-3xl border border-slate-200 bg-white'
+>
+  <table
+    class='min-w-full divide-y divide-slate-200'
+  >
+    <thead>
+      <tr>
+        {% for cell in head %}
+          <th
+            class='bg-slate-50 px-4 py-3 text-left text-xs font-semibold uppercase tracking-[0.2em] text-slate-500'
+          >
+            {{ cell|safe }}
+          </th>
+        {% endfor %}
+      </tr>
+    </thead>
+    <tbody>
+      {% for row in rows %}
+        <tr
+          class='odd:bg-white even:bg-slate-50/60'
+        >
+          {% for cell in row %}
+            <td
+              class='px-4 py-3 text-sm text-slate-700'
+            >
+              {{ cell|safe }}
+            </td>
+          {% endfor %}
+        </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</div>
+"#
+)]
+pub struct ComparisonTableTemplate<'a> {
+    pub head: &'a [&'a str],
+    pub rows: &'a [&'a [&'a str]],
+}
+

package/examples/basic/dist/askama/glyph.rs

@@ -0,0 +1,21 @@
+use askama::Template;
+
+#[derive(Template)]
+#[template(
+    ext = "html",
+    source = r#"
+<svg
+  class='{{ className }}'
+  data-tone='{{ tone }}'
+  data-size='{{ size }}'
+  data-name='{{ name }}'
+/>
+"#
+)]
+pub struct GlyphTemplate<'a> {
+    pub className: &'a str,
+    pub tone: &'a str,
+    pub size: &'a str,
+    pub name: &'a str,
+}
+

package/examples/basic/dist/askama/hover-note.rs

@@ -0,0 +1,19 @@
+use askama::Template;
+
+#[derive(Template)]
+#[template(
+    ext = "html",
+    source = r#"
+<span
+  data-hover-note='{{ label }}'
+  class='cursor-help underline decoration-dotted underline-offset-4'
+>
+  {{ children|safe }}
+</span>
+"#
+)]
+pub struct HoverNoteTemplate<'a> {
+    pub label: &'a str,
+    pub children: &'a str,
+}
+

package/examples/basic/dist/askama/includes/badge-chip.html

@@ -0,0 +1,5 @@
+<span
+  class='inline-flex items-center rounded-full px-2.5 py-1 text-xs font-semibold tracking-wide {% if tone == "neutral" %}bg-slate-100 text-slate-700{% endif %} {% if tone == "accent" %}bg-amber-100 text-amber-700{% endif %}'
+>
+  {{ label }}
+</span>

package/examples/basic/dist/askama/includes/comparison-table.html

@@ -0,0 +1,34 @@
+<div
+  class='overflow-x-auto rounded-3xl border border-slate-200 bg-white'
+>
+  <table
+    class='min-w-full divide-y divide-slate-200'
+  >
+    <thead>
+      <tr>
+        {% for cell in head %}
+          <th
+            class='bg-slate-50 px-4 py-3 text-left text-xs font-semibold uppercase tracking-[0.2em] text-slate-500'
+          >
+            {{ cell|safe }}
+          </th>
+        {% endfor %}
+      </tr>
+    </thead>
+    <tbody>
+      {% for row in rows %}
+        <tr
+          class='odd:bg-white even:bg-slate-50/60'
+        >
+          {% for cell in row %}
+            <td
+              class='px-4 py-3 text-sm text-slate-700'
+            >
+              {{ cell|safe }}
+            </td>
+          {% endfor %}
+        </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</div>

package/examples/basic/dist/askama/includes/glyph.html

@@ -0,0 +1,6 @@
+<svg
+  class='{{ className }}'
+  data-tone='{{ tone }}'
+  data-size='{{ size }}'
+  data-name='{{ name }}'
+/>

package/examples/basic/dist/askama/includes/hover-note.html

@@ -0,0 +1,6 @@
+<span
+  data-hover-note='{{ label }}'
+  class='cursor-help underline decoration-dotted underline-offset-4'
+>
+  {{ children|safe }}
+</span>

package/examples/basic/dist/askama/includes/media-frame.html

@@ -0,0 +1,23 @@
+<figure
+  class='overflow-hidden rounded-[28px] border border-slate-200 bg-white shadow-sm'
+>
+  {% if eyebrow != null %}
+    <div
+      class='border-b border-slate-200 px-5 py-3 text-[11px] font-semibold uppercase tracking-[0.28em] text-slate-500'
+    >
+      {{ eyebrow }}
+    </div>
+  {% endif %}
+  <div
+    class='bg-slate-50 p-4'
+  >
+    {{ children|safe }}
+  </div>
+  {% if caption_html != null %}
+    <figcaption
+      class='border-t border-slate-200 px-5 py-4 text-sm leading-6 text-slate-600'
+    >
+      {{ caption_html|safe }}
+    </figcaption>
+  {% endif %}
+</figure>