@lokascript/htmx-adapter 2.8.0

package/src/canonicalize.ts

@@ -0,0 +1,186 @@
+/**
+ * Localized → canonical attribute canonicalization for upstream htmx.
+ *
+ * htmx v4 has no hook to override how core resolves an attribute name —
+ * it reads `hx-get` literally. Until an upstream resolver seam exists
+ * (see docs/UPSTREAM_HOOK_PROPOSAL.md), this module makes localized
+ * authoring work by copying each localized attribute to its canonical
+ * name on the same element *before* htmx processes the node:
+ *
+ *   <button lang="es" hx-obtener="/api">  →  + hx-get="/api"
+ *
+ * Design rules (mirroring the loka-js invariants where the mechanism
+ * allows):
+ *
+ * - **The authored attribute is never removed or rewritten** — devtools
+ *   keeps showing what the author wrote. The one exception is an
+ *   author-written canonical `hx-trigger` whose *value* uses localized
+ *   event names (`hx-trigger="clic"`): there is no separate canonical
+ *   target to write to, so the value is translated in place (idempotent —
+ *   the maps are localized → canonical, so a second pass is a no-op).
+ * - **An existing canonical attribute always wins.** If the element
+ *   already has `hx-get`, a localized `hx-obtener` never overwrites it.
+ * - **No vocab, no work.** With no languages registered every function
+ *   here is a cheap no-op, so stock htmx pages pay ~nothing.
+ *
+ * Only attributes in the `hx-` / `sse-` / `ws-` namespaces are ever
+ * considered — the brand prefix is preserved across languages (Phase 8
+ * convention: Spanish writes `hx-obtener`, not `xx-obtener`), so the
+ * prefix doubles as the discovery anchor.
+ */
+
+import { langOf } from './lang-resolver.js';
+import { hasAnyVocab, vocabFor, warnMissingLangOnce } from './registry.js';
+import { claimHxOnAttribute, hasBodyExecutor } from './hx-on.js';
+import { isResolverMode } from './resolver.js';
+
+/** Attribute namespaces the adapter touches. */
+const NS_RE = /^(?:hx|sse|ws)-/;
+
+/**
+ * Translate localized event names inside an `hx-trigger` value.
+ *
+ * hx-trigger grammar: comma-separated specs, each `eventName[filter]
+ * modifier…`. Only the leading event token of each spec is translated
+ * (preserving an attached `[...]` filter); modifiers like `delay:500ms`,
+ * `from:body`, `once` are language-invariant and left alone. Unknown
+ * tokens pass through untouched, which also makes translation idempotent
+ * (the maps are localized → canonical only).
+ */
+export function translateTriggerValue(value: string, events: Record<string, string>): string {
+  return value
+    .split(',')
+    .map(spec => {
+      const trimmed = spec.trim();
+      if (!trimmed) return trimmed;
+      const parts = trimmed.split(/\s+/);
+      const m = parts[0].match(/^([^[\s]+)(\[.*)?$/);
+      if (m) {
+        const translated = events[m[1]];
+        if (translated) parts[0] = translated + (m[2] ?? '');
+      }
+      return parts.join(' ');
+    })
+    .join(', ');
+}
+
+/**
+ * Canonicalize one element's localized htmx attributes in place.
+ * Returns true if any attribute was added or updated.
+ */
+export function canonicalizeElement(elt: Element): boolean {
+  if (!elt.attributes || elt.attributes.length === 0) return false;
+
+  // Cheap prefilter before any lang resolution: bail unless some
+  // attribute is in our namespaces.
+  let hasNsAttr = false;
+  for (const attr of Array.from(elt.attributes)) {
+    if (NS_RE.test(attr.name)) {
+      hasNsAttr = true;
+      break;
+    }
+  }
+  if (!hasNsAttr) return false;
+
+  const executorMode = hasBodyExecutor();
+  const lang = langOf(elt);
+  if (lang === 'en' && !executorMode) return false;
+
+  const vocab = vocabFor(lang);
+  if (lang !== 'en' && !vocab) {
+    warnMissingLangOnce(lang);
+    // Executor mode still claims canonical-named hx-on:* attrs below —
+    // body semantics don't depend on vocab being loaded.
+    if (!executorMode) return false;
+  }
+
+  const attrs = vocab?.attrs ?? {};
+  const events = vocab?.events ?? {};
+  let changed = false;
+
+  // Snapshot — we mutate the attribute list while iterating.
+  for (const attr of Array.from(elt.attributes)) {
+    const name = attr.name;
+    if (!NS_RE.test(name)) continue;
+
+    // Executor mode owns the hx-on family outright: canonical-named
+    // attrs are claimed (listener installed, attr removed so htmx never
+    // JS-evals the hyperscript body)…
+    if (executorMode && name.startsWith('hx-on:')) {
+      if (claimHxOnAttribute(elt, name, lang, events)) changed = true;
+      continue;
+    }
+
+    // Exact match: hx-obtener → hx-get.
+    let canonical = attrs[name];
+
+    // Colon family (hx-on:*): hx-en:clic → hx-on:click. The base is
+    // looked up in attrs, the event suffix in events.
+    let colonBase: string | undefined;
+    if (!canonical) {
+      const colon = name.indexOf(':');
+      if (colon > 0) {
+        colonBase = attrs[name.slice(0, colon)];
+        if (colonBase) {
+          const suffix = name.slice(colon + 1);
+          canonical = `${colonBase}:${events[suffix] ?? suffix}`;
+        }
+      }
+    }
+
+    if (!canonical) continue;
+
+    // …and localized-named hx-on attrs are claimed in place: no
+    // canonical sibling is created, the authored attr stays verbatim
+    // (htmx never recognized it).
+    if (executorMode && colonBase === 'hx-on') {
+      if (claimHxOnAttribute(elt, name, lang, events)) changed = true;
+      continue;
+    }
+
+    if (canonical === name || elt.hasAttribute(canonical)) continue;
+
+    let value = attr.value;
+    if (canonical === 'hx-trigger') value = translateTriggerValue(value, events);
+    elt.setAttribute(canonical, value);
+    changed = true;
+  }
+
+  // Author-written canonical hx-trigger with localized event values
+  // (`hx-trigger="clic"`). Translated in place — the only mutation of an
+  // authored attribute, because there is no separate canonical target.
+  const trigger = elt.getAttribute('hx-trigger');
+  if (trigger !== null && Object.keys(events).length > 0) {
+    const translated = translateTriggerValue(trigger, events);
+    if (translated !== trigger) {
+      elt.setAttribute('hx-trigger', translated);
+      changed = true;
+    }
+  }
+
+  return changed;
+}
+
+/**
+ * Canonicalize an element and all its descendants. Returns the number of
+ * elements that changed. This is what the htmx extension hook and the
+ * initial document sweep call — htmx processes subtrees, so we mirror
+ * that granularity.
+ */
+export function canonicalizeTree(root: Element | Document | DocumentFragment | null): number {
+  if (!root) return 0;
+  // Resolver mode (patched htmx answers reads directly) stands the
+  // canonicalization shim down entirely — zero DOM mutation.
+  if (isResolverMode()) return 0;
+  // Executor mode must sweep even with no vocab loaded (English
+  // hyperscript bodies need claiming too).
+  if (!hasAnyVocab() && !hasBodyExecutor()) return 0;
+  let count = 0;
+  if (root instanceof Element && canonicalizeElement(root)) count++;
+  if (typeof (root as Element).querySelectorAll === 'function') {
+    for (const el of Array.from((root as Element).querySelectorAll('*'))) {
+      if (canonicalizeElement(el)) count++;
+    }
+  }
+  return count;
+}

package/src/extension.ts

@@ -0,0 +1,122 @@
+/**
+ * htmx extension + auto-sweep wiring.
+ *
+ * Primary target is **htmx v4**, whose extensions register via
+ * `htmx.registerExtension(name, ext)` and hook lifecycle events through
+ * underscore-named methods (event name with `:` → `_`), each receiving
+ * `(elt, detail)`. Verified against htmx 4.0.0-beta5 (see
+ * test/browser/vendor/README.md): `process(root)` fires
+ * `htmx:before:process` on the processed root — `document.body`
+ * initially, each swapped-in subtree afterwards — BEFORE any element
+ * init or hx-on binding, so canonicalizing in `htmx_before_process`
+ * covers everything htmx will read. `htmx_before_process_node` is kept
+ * as a defensive alias for other v4 prereleases that used per-node
+ * naming; an unmatched key is inert.
+ *
+ * A v2 fallback (`htmx.defineExtension` + `onEvent('htmx:beforeProcessNode')`)
+ * is included because the localized attribute names are version-agnostic
+ * data — but v2 support is best-effort, not a tested target.
+ *
+ * The extension hook alone is not enough for the *initial* page: script
+ * order decides whether our sweep beats htmx's own DOMContentLoaded scan.
+ * `installAutoSweep()` handles that — load this adapter (and vocab
+ * modules) BEFORE the htmx <script> tag, mirroring loka-js's
+ * "orchestrator before libraries" rule, and the sweep listener registers
+ * ahead of htmx's.
+ */
+
+import { canonicalizeTree } from './canonicalize.js';
+import { onVocabUpdate } from './registry.js';
+import { onBodyHooksChanged } from './hx-on.js';
+
+export const EXTENSION_NAME = 'lokascript-i18n';
+
+/** Minimal shape of the htmx global we interact with. */
+export interface HtmxLike {
+  /** htmx v4 registration entry point. */
+  registerExtension?(name: string, extension: object): void;
+  /** htmx v1/v2 registration entry point. */
+  defineExtension?(name: string, extension: object): void;
+}
+
+/**
+ * Build the extension object. v4 hooks and the v2 `onEvent` callback are
+ * both present — each API only reads the members it knows about.
+ */
+export function createExtension(): object {
+  return {
+    // htmx v4 (verified on 4.0.0-beta5): fires on each process() root
+    // before element init and hx-on binding.
+    htmx_before_process(elt: Element): void {
+      canonicalizeTree(elt);
+    },
+    // Defensive alias for v4 prereleases with per-node hook naming.
+    htmx_before_process_node(elt: Element): void {
+      canonicalizeTree(elt);
+    },
+    // htmx v1/v2 fallback: single event dispatcher.
+    onEvent(name: string, evt: CustomEvent & { target?: EventTarget | null }): void {
+      if (name !== 'htmx:beforeProcessNode') return;
+      const detail = evt?.detail as { elt?: Element } | undefined;
+      const elt = detail?.elt ?? (evt?.target instanceof Element ? evt.target : null);
+      if (elt) canonicalizeTree(elt);
+    },
+  };
+}
+
+/**
+ * Register the extension with an htmx global. Returns which API accepted
+ * it (`'v4'` / `'v2'`) or `null` if the object exposes neither.
+ */
+export function registerWith(htmx: HtmxLike | undefined | null): 'v4' | 'v2' | null {
+  if (!htmx) return null;
+  const ext = createExtension();
+  if (typeof htmx.registerExtension === 'function') {
+    htmx.registerExtension(EXTENSION_NAME, ext);
+    return 'v4';
+  }
+  if (typeof htmx.defineExtension === 'function') {
+    htmx.defineExtension(EXTENSION_NAME, ext);
+    return 'v2';
+  }
+  return null;
+}
+
+/**
+ * Sweep the whole document now (if parsed) or on DOMContentLoaded, and
+ * re-sweep whenever a vocab module registers after the initial sweep
+ * (e.g. a vocab <script> below htmx, or dynamic registration).
+ *
+ * Returns a cleanup function (mainly for tests).
+ */
+export function installAutoSweep(doc: Document = document): () => void {
+  const sweep = (): void => {
+    canonicalizeTree(doc.body ?? doc.documentElement);
+  };
+
+  let removeDomListener: (() => void) | null = null;
+  if (doc.readyState === 'loading') {
+    const onReady = (): void => sweep();
+    doc.addEventListener('DOMContentLoaded', onReady, { once: true });
+    removeDomListener = () => doc.removeEventListener('DOMContentLoaded', onReady);
+  } else {
+    sweep();
+  }
+
+  const unsubscribeVocab = onVocabUpdate(() => {
+    if (doc.readyState !== 'loading') sweep();
+  });
+
+  // A body executor configured after the initial sweep flips the hx-on
+  // family into executor mode — re-sweep so already-canonicalized
+  // hx-on:* attrs get claimed (listener installed, attr removed).
+  const unsubscribeBodyHooks = onBodyHooksChanged(() => {
+    if (doc.readyState !== 'loading') sweep();
+  });
+
+  return () => {
+    removeDomListener?.();
+    unsubscribeVocab();
+    unsubscribeBodyHooks();
+  };
+}

package/src/hx-on.ts

@@ -0,0 +1,197 @@
+/**
+ * hx-on body support — opt-in "executor mode".
+ *
+ * Upstream htmx evals `hx-on:*` bodies as JavaScript. In the hyperfixi
+ * ecosystem the convention is hyperscript bodies (`hx-on:click="toggle
+ * .active on me"`), which htmx's JS eval cannot run — and localized
+ * bodies (`hx-en:clic="alternar .active"`) doubly so. This module lets a
+ * page opt in to hyperscript-body semantics by configuring an executor:
+ *
+ *   setBodyExecutor((code, elt, evt) => _hyperscript.evaluate(code, { me: elt, event: evt }))
+ *   setBodyTranslator((body, lang) => HyperscriptI18n.preprocess(body, lang))
+ *
+ * With an executor set, the adapter CLAIMS every hx-on-family attribute
+ * (localized-named or canonical-named — all bodies are treated as
+ * hyperscript; mixed JS/hyperscript pages have no reliable detection):
+ * it installs a real event listener that runs the (lazily translated)
+ * body through the executor, and keeps htmx away from it:
+ *
+ * - Localized-named attrs (`hx-en:clic`) stay verbatim in the DOM — htmx
+ *   never recognized them anyway — and NO canonical `hx-on:*` sibling is
+ *   created.
+ * - Canonical-named attrs (`hx-on:click`) are REMOVED after claiming.
+ *   This is the one place the adapter deletes an authored attribute: if
+ *   it stayed, htmx would eval the hyperscript body as JS — a console
+ *   error plus a double-execution attempt on every fire. Documented as
+ *   the executor-mode exception in the README.
+ *
+ * With no executor set (the default), none of this runs and bodies keep
+ * upstream JS semantics — the behavior-preservation invariant.
+ *
+ * Translation is lazy (first event fire, memoized) so a translator that
+ * loads after the initial sweep still applies. Both auto-detection
+ * (`autoDetectBodyHooks`) and manual configuration are supported; the
+ * executor is also re-read at fire time so replacing it takes effect on
+ * live listeners.
+ */
+
+export type BodyExecutor = (code: string, elt: Element, evt: Event) => unknown;
+export type BodyTranslator = (body: string, lang: string) => string;
+
+let executor: BodyExecutor | null = null;
+let translator: BodyTranslator | null = null;
+
+/** Listeners notified when the executor is set/cleared (drives re-sweeps). */
+const hookChangeListeners = new Set<() => void>();
+
+/**
+ * Per-element set of already-claimed EVENT names (sweep idempotency).
+ * Keyed by resolved event name rather than attribute name so a localized
+ * attr and its canonical form never both install a listener — e.g. after
+ * a v1 (no-executor) sweep created an `hx-on:click` sibling of
+ * `hx-en:clic` and an executor registered later, the re-sweep claims one
+ * of them and neutralizes the other. When both are genuinely authored,
+ * DOM attribute order decides which body wins.
+ */
+let claimed = new WeakMap<Element, Set<string>>();
+
+/** Configure the body executor. Setting/clearing it notifies subscribers. */
+export function setBodyExecutor(fn: BodyExecutor | null): void {
+  executor = fn;
+  for (const listener of hookChangeListeners) listener();
+}
+
+/** Configure the body translator (localized body → English hyperscript). */
+export function setBodyTranslator(fn: BodyTranslator | null): void {
+  translator = fn;
+}
+
+export function hasBodyExecutor(): boolean {
+  return executor !== null;
+}
+
+export function hasBodyTranslator(): boolean {
+  return translator !== null;
+}
+
+/** Subscribe to executor changes. Returns an unsubscribe fn. */
+export function onBodyHooksChanged(listener: () => void): () => void {
+  hookChangeListeners.add(listener);
+  return () => {
+    hookChangeListeners.delete(listener);
+  };
+}
+
+/**
+ * Resolve the DOM event name for an hx-on attribute suffix.
+ * `hx-on::after-swap` shorthand (leading `:`) means the `htmx:` namespace;
+ * plain suffixes translate through the vocab events map.
+ */
+function eventNameForSuffix(rawSuffix: string, events: Record<string, string>): string {
+  if (rawSuffix.startsWith(':')) return `htmx${rawSuffix}`;
+  return events[rawSuffix] ?? rawSuffix;
+}
+
+/**
+ * Claim one hx-on-family attribute on an element: install the executor
+ * listener and neutralize htmx's view of it. Returns true if the claim
+ * happened now (false when no executor, already claimed, or malformed).
+ *
+ * `lang` is the element's language at claim time — used for lazy body
+ * translation. `events` is the language's event-name map (for the
+ * listener's event name; the shorthand/unknown cases pass through).
+ */
+export function claimHxOnAttribute(
+  elt: Element,
+  attrName: string,
+  lang: string,
+  events: Record<string, string>
+): boolean {
+  if (!executor) return false;
+
+  const colon = attrName.indexOf(':');
+  if (colon <= 0) return false; // colon-form only; legacy composite hx-on="…" unsupported
+
+  const eventName = eventNameForSuffix(attrName.slice(colon + 1), events);
+  const already = claimed.get(elt);
+  if (already?.has(eventName)) {
+    // Duplicate claim for an already-claimed event — no second listener,
+    // but canonical-named attrs still get neutralized so htmx never
+    // JS-evals them.
+    if (attrName.startsWith('hx-on:') && elt.hasAttribute(attrName)) {
+      elt.removeAttribute(attrName);
+      return true;
+    }
+    return false;
+  }
+
+  const body = elt.getAttribute(attrName) ?? '';
+
+  // Lazy, memoized translation: translator may register after the sweep,
+  // and repeated fires shouldn't re-translate.
+  let translatedBody: string | null = null;
+  elt.addEventListener(eventName, evt => {
+    if (!executor) return; // executor cleared after claim — go quiet
+    if (translatedBody === null) {
+      translatedBody = lang !== 'en' && translator ? translator(body, lang) : body;
+    }
+    try {
+      executor(translatedBody, elt, evt);
+    } catch (err) {
+      if (typeof console !== 'undefined') {
+        console.error(`[htmx-i18n] hx-on body execution failed (${attrName} → ${eventName})`, err);
+      }
+    }
+  });
+
+  // Canonical-named claims are removed so htmx never JS-evals the
+  // hyperscript body (double-execution guard). Localized names are
+  // invisible to htmx and stay verbatim.
+  if (attrName.startsWith('hx-on:')) elt.removeAttribute(attrName);
+
+  if (already) {
+    already.add(eventName);
+  } else {
+    claimed.set(elt, new Set([eventName]));
+  }
+  return true;
+}
+
+/**
+ * Auto-detect body hooks from page globals — called by the browser entry
+ * at load and again at DOMContentLoaded. Never overwrites hooks that
+ * were set explicitly.
+ *
+ * - `window._hyperscript` → executor (original _hyperscript; pairs with
+ *   `@lokascript/hyperscript-adapter` for multilingual `_=` too)
+ * - `window.HyperscriptI18n.preprocess` → translator (the
+ *   hyperscript-adapter browser bundles expose exactly this)
+ */
+export function autoDetectBodyHooks(win: object): void {
+  const w = win as {
+    _hyperscript?: ((code: string) => unknown) & {
+      evaluate?: (code: string, ctx?: object) => unknown;
+    };
+    HyperscriptI18n?: { preprocess?: (src: string, lang: string) => string };
+  };
+
+  if (!executor && typeof w._hyperscript === 'function') {
+    const hs = w._hyperscript;
+    setBodyExecutor((code, elt, evt) =>
+      typeof hs.evaluate === 'function' ? hs.evaluate(code, { me: elt, event: evt }) : hs(code)
+    );
+  }
+
+  if (!translator && typeof w.HyperscriptI18n?.preprocess === 'function') {
+    const preprocess = w.HyperscriptI18n.preprocess;
+    setBodyTranslator((body, lang) => preprocess(body, lang));
+  }
+}
+
+/** Reset all body-hook state. Mainly for tests. */
+export function resetBodyHooks(): void {
+  executor = null;
+  translator = null;
+  hookChangeListeners.clear();
+  claimed = new WeakMap();
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @lokascript/htmx-adapter — multilingual adapter for upstream htmx v4.
+ *
+ * Lets authors write `hx-*` / `sse-*` / `ws-*` attributes in 24 languages
+ * against the stock htmx library. Localized names are canonicalized on
+ * the element before htmx processes it (see canonicalize.ts); vocab data
+ * is the same generated `packages/core/vocab/htmx/{lang}.js` modules the
+ * embedded hyperfixi htmx-compat layer uses.
+ *
+ * Programmatic use:
+ *
+ *   import { register, registerWith, installAutoSweep } from '@lokascript/htmx-adapter';
+ *   register('es', { hyperfixi: { attrs: { 'hx-obtener': 'hx-get' }, events: { clic: 'click' } } });
+ *   registerWith(window.htmx);   // v4 extension (v2 fallback)
+ *   installAutoSweep();          // initial-page sweep
+ *
+ * Browser IIFE (`./browser` export) does all of the above automatically.
+ */
+
+export { langOf, normLang } from './lang-resolver.js';
+export {
+  register,
+  vocabFor,
+  isLangRegistered,
+  hasAnyVocab,
+  onVocabUpdate,
+  resetRegistry,
+  type HtmxVocab,
+  type VocabPayload,
+} from './registry.js';
+export { canonicalizeElement, canonicalizeTree, translateTriggerValue } from './canonicalize.js';
+export {
+  EXTENSION_NAME,
+  createExtension,
+  registerWith,
+  installAutoSweep,
+  type HtmxLike,
+} from './extension.js';
+export {
+  attributeResolver,
+  additionalAttributeSelectors,
+  installResolverMode,
+  isResolverMode,
+  setResolverMode,
+} from './resolver.js';
+export {
+  setBodyExecutor,
+  setBodyTranslator,
+  hasBodyExecutor,
+  hasBodyTranslator,
+  onBodyHooksChanged,
+  claimHxOnAttribute,
+  autoDetectBodyHooks,
+  resetBodyHooks,
+  type BodyExecutor,
+  type BodyTranslator,
+} from './hx-on.js';

package/src/lang-resolver.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-element language resolution for localized htmx attribute names.
+ *
+ * Mirrors `packages/core/src/htmx/lang-resolver.ts` (which in turn mirrors
+ * loka-js's `lang-resolver.js`) so a page migrating between hyperfixi's
+ * embedded htmx-compat layer and this upstream-htmx adapter resolves
+ * languages identically. Resolution order:
+ *
+ *   1. `data-hyperfixi-lang` attribute on the element itself
+ *   2. `data-hyperfixi-lang` on any ancestor
+ *   3. `lang` attribute on any ancestor (HTML standard)
+ *   4. `'en'` fallback
+ *
+ * Results are normalized to the part before the first `-`/`_` (`es-MX` →
+ * `es`) and lowercased so callers can index vocab maps by 2-letter code
+ * without caring about regional variants.
+ */
+
+/** Normalize a language tag — `es-MX` / `ES_mx` → `es`. */
+export function normLang(s: string | null | undefined): string {
+  if (!s) return 'en';
+  return s.split(/[-_]/)[0].toLowerCase();
+}
+
+/** Resolve the language code for an element via ancestor walk. */
+export function langOf(elt: Element): string {
+  const own = elt.getAttribute?.('data-hyperfixi-lang');
+  if (own) return normLang(own);
+  const dx = elt.closest?.('[data-hyperfixi-lang]');
+  if (dx) return normLang(dx.getAttribute('data-hyperfixi-lang'));
+  const la = elt.closest?.('[lang]');
+  if (la) return normLang(la.getAttribute('lang'));
+  return 'en';
+}