@edgedev/template-engine 0.1.0

package/README.md

@@ -0,0 +1,332 @@
+# @edge/template-engine
+
+Utility function with rendering logic. Feed it content, values, and meta data and receive HTML you can drop into any Vue (or non-Vue) surface.
+
+## Install
+
+```bash
+npm install @edge/template-engine
+```
+
+## Usage
+
+```ts
+import renderTemplate from '@edge/template-engine'
+
+const html = renderTemplate(contentString, valueMap, metaDefinition)
+```
+
+Treat `valueMap` and `metaDefinition` as override objects: they selectively replace values/meta defined within the template, and any omitted parameter (or key) falls back to the template's embedded defaults.
+
+### Full Page Rendering
+
+Use `pageRender` when you need to hydrate multiple blocks, render their HTML, and collect the UnoCSS used across the entire page.
+
+```ts
+import { pageRender } from '@edge/template-engine'
+
+const theme = {
+  extend: {
+    colors: { brand: '#2563eb' },
+    fontFamily: { brand: ['Inter', 'sans-serif'] },
+  },
+}
+
+const { blocks, css } = await pageRender(
+  [
+    {
+      name: 'hero',
+      content: '<section class="bg-brand text-white">{{{#text {"field":"headline"} }}}</section>',
+      values: { headline: 'Launch in days, not months.' },
+    },
+    {
+      name: 'listing',
+      content: `
+        <ul>
+          {{{#array {"field":"items","as":"item"} }}}
+            <li class="flex gap-2">
+              <span class="font-semibold">{{ item.title }}</span>
+              <span class="text-sm text-gray-500">{{ item.subtitle }}</span>
+            </li>
+          {{{/array}}}
+        </ul>
+      `,
+      meta: {
+        items: { schema: { title: 'text', subtitle: 'text' } },
+      },
+    },
+  ],
+  theme,
+  '<div class="hidden md:block fixed inset-0 pointer-events-none radial-gradient-mask"></div>',
+  {
+    uniqueKey: 'org-123:site-456',
+    clientOptions: {
+      binding: env?.MY_INDEX_KV,
+      accountId: process.env.CF_ACCOUNT_ID!,
+      namespaceId: process.env.CF_NAMESPACE_ID!,
+      apiToken: process.env.CF_API_TOKEN!,
+    },
+  },
+)
+
+// blocks => [{ name: 'hero', html: '<section ...>...</section>' }, ...]
+// css => aggregated UnoCSS needed for all rendered HTML + extraHtml
+```
+
+- Each block is hydrated first using the provided hydrate options, then rendered via `renderTemplate`.
+- `extraHtml` is optional helper markup that should also contribute to UnoCSS generation (e.g. layout shells).
+- The returned `css` string is ready to inline or serve as critical CSS. Rendered blocks remain accessible individually if you need to target specific components.
+
+The renderer supports:
+
+- Root-level and nested `#array` / `#subarray` blocks with aliases
+- Conditional `#if` / `#else` blocks
+- Simple blocks (`#text`, `#image`, `#textarea`, `#richtext`)
+- Schema-aware formatting for `number`, `integer`, `money`, and `richtext` types using the provided `meta`
+
+See `src/index.ts` for the full list of helpers that mimic the original Vue component.
+
+## Comprehensive Example
+
+```ts
+const content = `
+<section class="playbook">
+  <header>
+    <h1>{{{#text {"field":"title"} }}}</h1>
+    <p>{{{#textarea {"field":"summary"} }}}</p>
+    <img :src="{{{#image {"field":"heroImage"} }}}" alt="Hero" />
+    {{{#richtext {"field":"body"} }}}
+  </header>
+
+  <div class="cta">
+    <a href="{{{ {"field":"heroHref","value":"https://edge.co"} }}}">{{{ {"field":"heroCta","type":"text"} }}}</a>
+  </div>
+
+  <ul class="stats">
+    {{{#array {"field":"stats","as":"stat"} }}}
+      <li>
+        <span class="label">{{ stat.label }}</span>
+        <span class="value">{{ stat.value }}</span>
+      </li>
+    {{{/array}}}
+  </ul>
+
+  <section class="team">
+    {{{#array {"field":"team","as":"member","schema":{"budget":"money"}} }}}
+      <article>
+        <h3>{{ member.name }}</h3>
+        <p>{{ member.role }}</p>
+        {{{#if {"cond":"item.isLead == true"} }}}
+          <span class="badge">Lead</span>
+        {{{#else}}}
+          <span class="badge muted">Contributor</span>
+        {{{/if}}}
+        <p class="bio">{{ member.bio }}</p>
+        <div>Annual budget: {{ member.budget }}</div>
+
+        <ul>
+          {{{#subarray:project {"field":"item.projects","limit":2} }}}
+            <li>
+              <strong>{{ project.name }}</strong>
+              <span>{{ project.status }}</span>
+            </li>
+          {{{/subarray}}}
+        </ul>
+      </article>
+    {{{/array}}}
+  </section>
+</section>
+`
+
+const values = {
+  title: 'Q4 Launch Playbook',
+  summary: 'Tactics and timelines for the winter product drop.',
+  heroImage: 'https://cdn.edge.co/playbook-hero.png',
+  heroHref: 'https://edge.co/campaigns/playbook',
+  heroCta: 'View Campaign Timeline',
+  body: '<p><strong>Note:</strong> This block accepts raw HTML.</p>',
+  stats: [
+    { label: 'Net-new leads', value: 3400 },
+    { label: 'Pipeline ($)', value: 1750000 },
+  ],
+  team: [
+    {
+      name: 'Mia Chen',
+      role: 'Program Manager',
+      isLead: true,
+      budget: 125000,
+      bio: 'Owns launch roadmap & GTM alignment.',
+      projects: [
+        { name: 'Hubble', status: 'Active' },
+        { name: 'Lumen', status: 'Planning' },
+      ],
+    },
+    {
+      name: 'Jonas Patel',
+      role: 'Growth Engineer',
+      isLead: false,
+      budget: 60000,
+      bio: '<em>Automates activation experiments.</em>',
+      projects: [
+        { name: 'Arcade', status: 'QA' },
+      ],
+    },
+  ],
+}
+
+const meta = {
+  stats: {
+    // object-based schema (field -> type)
+    schema: {
+      value: 'number',
+    },
+  },
+  team: {
+    // array-based schema (common on older Edge configs)
+    schema: [
+      { field: 'budget', type: 'money' },
+      { field: 'bio', type: 'richtext' },
+    ],
+  },
+}
+
+const html = renderTemplate(content, values, meta)
+```
+
+Key behaviors demonstrated:
+
+- `{{{#text}}}`, `{{{#textarea}}}`, `{{{#image}}}`, and `{{{#richtext}}}` show the simple block helpers.
+- `{{ {"field":"...","type":"text"} }}` illustrates double-brace placeholders with type-aware escaping.
+- `#array` handles the root `stats` and `team` lists, while `#subarray` reaches into each member’s nested `projects`.
+- The `schema` on `stats` (object form) and `team` (array form) ensures `value`, `budget`, and `bio` pick up number/money/richtext formatting.
+- The conditional `#if/#else` block switches the badge copy based on `item.isLead`.
+- `limit` on `#subarray` trims the nested list to the first two entries.
+
+## Cloudflare KV Index Client
+
+The package also exposes a helper for working with Cloudflare KV index namespaces. Initialize it once with your credentials (and optional Worker KV binding) and reuse the client to run prefix queries.
+
+```ts
+import { createKvIndexClient } from '@edge/template-engine'
+
+const kvClient = createKvIndexClient({
+  // Optional: the Workers KV binding when running inside a Worker / Pages Function.
+  binding: env?.MY_INDEX_KV,
+
+  // Required: account + namespace identifiers for the REST fallback.
+  accountId: process.env.CF_ACCOUNT_ID!,
+  namespaceId: process.env.CF_NAMESPACE_ID!,
+  apiToken: process.env.CF_API_TOKEN!,
+
+  // Optional: custom fetch (defaults to globalThis.fetch).
+  fetch: globalThis.fetch,
+})
+
+// Example 1: expect at most one canonical match.
+const [post] = await kvClient.queryIndex({
+  baseKey: 'post', // the client automatically prefixes keys with "idx:"
+  searchKey: 'slug',
+  uniqueKey: 'user-34329473094',
+  searchValue: 'blog:dasfadsfasd',
+})
+
+// Example 2: gather multiple raw index hits (no canonical pointer needed).
+const relatedPosts = await kvClient.queryIndex({
+  baseKey: 'post',
+  searchKey: 'tag',
+  uniqueKey: 'user-34329473094',
+  searchValue: ['launch', 'beta'], // arrays fan out to multiple prefix searches
+})
+
+// `post` is the canonical object (when exactly one match is found).
+// `relatedPosts` is an array of parsed index meta objects (no manual JSON.parse needed).
+
+// Fetch an exact key if you already know the canonical identifier.
+const canonical = await kvClient.getKey('post:canonical:user-34329473094')
+// -> returns an object (or null) and emits console.warn indicating whether the binding or API was used.
+```
+
+## Hydrating Collections from KV
+
+Templates can declare `#array` blocks that describe KV-backed collections. Use `hydrateValues` to resolve those collections before rendering.
+
+```ts
+import {
+  hydrateValues,
+  renderTemplate,
+  type HydrateValuesOptions,
+} from '@edge/template-engine'
+
+const options: HydrateValuesOptions = {
+  content: contentString,
+  values: initialValueOverrides,
+  meta: metaDefinitionOverride,
+  uniqueKey: 'workspace-1234', // the namespace segment used when indexing
+  clientOptions: {
+    // Optional binding (Workers runtime)
+    binding: env?.MY_INDEX_KV,
+
+    // REST fallback credentials (e.g. during SSR/build)
+    accountId: process.env.CF_ACCOUNT_ID!,
+    namespaceId: process.env.CF_NAMESPACE_ID!,
+    apiToken: process.env.CF_API_TOKEN!,
+
+    fetch: globalThis.fetch,
+  },
+}
+
+const hydratedValues = await hydrateValues(options)
+const html = renderTemplate(contentString, hydratedValues, metaDefinitionOverride)
+```
+
+Key details:
+
+- `hydrateValues` reads any `collection`, `queryItems`, `queryOptions`, `order`, and `limit` settings from the template markup or meta overrides.
+- Each query item fans out to `kvClient.queryIndex` calls, combining responses and deduplicating by `canonical`.
+- Filters (`queryOptions`) and ordering rules execute in JS after the index lookups, and the final array is written back to the corresponding field in the returned `values`.
+- If the collection cannot be fetched, the resolver falls back to any inline `value` you provided or leaves an empty array.
+
+## UnoCSS SSR Helpers
+
+When your rendered HTML relies on UnoCSS utilities, the package exposes helpers to generate the exact CSS during SSR or at build time.
+
+```ts
+import {
+  unoCssFromHtml,
+  normalizeTheme,
+  buildCssVarsBlock,
+} from '@edge/template-engine'
+
+const theme = {
+  extend: {
+    colors: {
+      brand: '#2563eb',
+    },
+    fontFamily: {
+      brand: ['Inter', 'sans-serif'],
+    },
+  },
+  variants: {
+    dark: {
+      extend: {
+        colors: {
+          brand: '#3b82f6',
+        },
+      },
+    },
+  },
+}
+
+const { css, hash } = await unoCssFromHtml(renderedHtml, theme)
+
+// Inject the CSS into your HTML shell, or cache it under the returned hash.
+const cssVarsBlock = buildCssVarsBlock(theme) // optional: inline preflight variables yourself
+const unoTheme = normalizeTheme(theme) // optional: feed into other Uno-powered tooling
+```
+
+Details:
+
+- `unoCssFromHtml(html, theme)` returns `{ css, hash }`, producing minified output that already includes preflights and the custom font-family rules bundled here.
+- `normalizeTheme` strips the `extend` wrapper so your theme matches Uno’s expected shape if you need to share it elsewhere.
+- `buildCssVarsBlock` mirrors the default preflight while letting you embed the CSS variables manually if desired.
+- The generator is cached per theme hash, and transformer dependencies are loaded lazily; ensure your runtime supports dynamic `import()` (Node 18+, modern bundlers, Workers, etc.).

package/dist/hydrateValues.d.ts

@@ -0,0 +1,11 @@
+import { type KvIndexClientOptions } from './kvIndexClient';
+import type { TemplateMeta, TemplateValues } from './types';
+export interface HydrateValuesOptions {
+    content: string;
+    meta?: TemplateMeta;
+    values?: TemplateValues;
+    uniqueKey: string;
+    clientOptions: KvIndexClientOptions;
+}
+export declare const hydrateValues: (options: HydrateValuesOptions) => Promise<TemplateValues>;
+//# sourceMappingURL=hydrateValues.d.ts.map

package/dist/hydrateValues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrateValues.d.ts","sourceRoot":"","sources":["../src/hydrateValues.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAKV,YAAY,EACZ,cAAc,EACf,MAAM,SAAS,CAAA;AAEhB,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,oBAAoB,CAAA;CACpC;AAooBD,eAAO,MAAM,aAAa,GACxB,SAAS,oBAAoB,KAC5B,OAAO,CAAC,cAAc,CAqFxB,CAAA"}