@lokascript/htmx-adapter 2.8.0

package/src/registry.ts

@@ -0,0 +1,112 @@
+/**
+ * Vocab registry for the upstream-htmx adapter.
+ *
+ * Accepts the SAME payload shape as hyperfixi core's htmx-compat
+ * orchestrator (`packages/core/src/htmx/i18n-orchestrator.ts`), so the
+ * generated vocab modules under `packages/core/vocab/htmx/{lang}.js`
+ * (which call `window.__hyperfixi_i18n.register(lang, payload)`) work
+ * verbatim against this adapter — one generated artifact, two consumers.
+ *
+ *   register('es', {
+ *     hyperfixi: {
+ *       attrs: { 'hx-obtener': 'hx-get', 'sse-conectar': 'sse-connect' },
+ *       events: { clic: 'click', cambiar: 'change' },
+ *     },
+ *   });
+ *
+ * Unlike core's orchestrator this registry needs no inverted index: the
+ * adapter canonicalizes (localized → canonical), which is exactly the
+ * direction the parse maps are published in. There is deliberately no
+ * KEYS copy here either — the vocab data is self-describing (full
+ * attribute names on both sides), so the canonical key set lives only in
+ * core's generator (`packages/core/scripts/gen-htmx-vocab.mjs`).
+ */
+
+import { normLang } from './lang-resolver.js';
+
+export interface HtmxVocab {
+  /** Map of localized attribute name → canonical English form (fully qualified). */
+  attrs?: Record<string, string>;
+  /** Map of localized event name → canonical English form (`'clic'` → `'click'`). */
+  events?: Record<string, string>;
+}
+
+export interface VocabPayload {
+  hyperfixi?: HtmxVocab;
+}
+
+/** Per-language vocab, keyed by normalized language code. */
+const REG = new Map<string, HtmxVocab>();
+
+/** Languages we've already warned about being missing. */
+const warnedMissingLang = new Set<string>();
+
+/** Listeners notified after a vocab registration completes. */
+const vocabUpdateListeners = new Set<() => void>();
+
+/**
+ * Register a vocab module for a language. Idempotent — re-registering a
+ * language replaces its vocab entirely.
+ */
+export function register(code: string, data: VocabPayload): void {
+  const lang = normLang(code);
+  REG.set(lang, data?.hyperfixi ?? {});
+  warnedMissingLang.delete(lang); // we know about it now
+  for (const listener of vocabUpdateListeners) listener();
+}
+
+/** Look up the vocab registered for a (normalized) language code. */
+export function vocabFor(lang: string): HtmxVocab | undefined {
+  return REG.get(lang);
+}
+
+/** Inspect whether any vocab is registered for a language. Mainly for tests. */
+export function isLangRegistered(code: string): boolean {
+  return REG.has(normLang(code));
+}
+
+/** True if at least one language has registered vocab. */
+export function hasAnyVocab(): boolean {
+  return REG.size > 0;
+}
+
+/** All language codes with registered vocab. */
+export function vocabLangs(): string[] {
+  return [...REG.keys()];
+}
+
+/** Subscribe to vocab-registration notifications. Returns an unsubscribe fn. */
+export function onVocabUpdate(listener: () => void): () => void {
+  vocabUpdateListeners.add(listener);
+  return () => {
+    vocabUpdateListeners.delete(listener);
+  };
+}
+
+/**
+ * Warn once per language that an element sits in a lang scope with no
+ * registered vocab, so authors notice unloaded vocab modules instead of
+ * silently getting English-only behavior.
+ */
+export function warnMissingLangOnce(lang: string): void {
+  if (warnedMissingLang.has(lang)) return;
+  warnedMissingLang.add(lang);
+  if (typeof console !== 'undefined') {
+    console.warn(
+      `[htmx-i18n] No vocab registered for lang="${lang}". ` +
+        `Elements in this language scope keep their localized attribute names ` +
+        `and htmx will not see them. Load the ${lang} vocab module ` +
+        `(packages/core/vocab/htmx/${lang}.js) before htmx processes the page.`
+    );
+  }
+}
+
+/**
+ * Reset registry state — drop all registrations and listeners. Mainly for
+ * tests; production code should leave registrations in place.
+ */
+export function resetRegistry(): void {
+  REG.clear();
+  warnedMissingLang.clear();
+  vocabUpdateListeners.clear();
+}

package/src/resolver.ts

@@ -0,0 +1,104 @@
+/**
+ * Resolver mode — the adapter's mechanism-(c) form, usable today against
+ * the reference-patched htmx build (docs/reference-patches/) and ready
+ * for upstream if the attribute-resolver seam lands.
+ *
+ * Where the default shim CANONICALIZES (copies localized attrs onto the
+ * element), resolver mode answers htmx's attribute lookups directly:
+ * core asks "what should I read for `hx-get` on this element?" and the
+ * resolver returns the localized name actually present (`hx-obtener`)
+ * for the element's language scope. Zero DOM mutation, fully
+ * devtools-faithful — the loka-js ideal.
+ *
+ * Two seams must both be fed (the loka-js lesson): the per-element
+ * resolver answers reads, and `additionalAttributeSelectors` feeds the
+ * document-level discovery scan, which a per-element function cannot
+ * drive. `installResolverMode()` wires both and keeps the selector list
+ * fresh as vocab modules register.
+ *
+ * Scope: value-bearing attributes only. The hx-on colon family stays
+ * with the shim/executor mode — its event name is part of the attribute
+ * NAME, which is a different question than "what name holds this
+ * value". Trigger VALUES (`hx-trigger="clic"`) are also name-level
+ * out-of-scope; keep authoring canonical event values, or pair with
+ * executor mode.
+ */
+
+import { langOf } from './lang-resolver.js';
+import { onVocabUpdate, vocabFor, vocabLangs } from './registry.js';
+
+let resolverModeActive = false;
+
+/** True while resolver mode owns localization (the shim stands down). */
+export function isResolverMode(): boolean {
+  return resolverModeActive;
+}
+
+/** Mainly for tests; installResolverMode() manages this in production. */
+export function setResolverMode(active: boolean): void {
+  resolverModeActive = active;
+}
+
+/**
+ * The per-element resolver htmx consults on attribute reads:
+ * `(elt, canonicalName) → localized name present on elt, or null`.
+ */
+export function attributeResolver(elt: Element, name: string): string | null {
+  const lang = langOf(elt);
+  if (lang === 'en') return null;
+  const attrs = vocabFor(lang)?.attrs;
+  if (!attrs) return null;
+  for (const [localized, canonical] of Object.entries(attrs)) {
+    if (canonical === name && elt.hasAttribute?.(localized)) return localized;
+  }
+  return null;
+}
+
+/**
+ * CSS attribute selectors for every registered localized name, for
+ * htmx's discovery scan (`config.additionalAttributeSelectors`). The
+ * hx-on family is excluded — see the module header.
+ */
+export function additionalAttributeSelectors(): string[] {
+  const names = new Set<string>();
+  for (const lang of vocabLangs()) {
+    const attrs = vocabFor(lang)?.attrs ?? {};
+    for (const [localized, canonical] of Object.entries(attrs)) {
+      if (canonical === 'hx-on') continue;
+      names.add(`[${localized}]`);
+    }
+  }
+  return [...names];
+}
+
+interface ResolverConfigurableHtmx {
+  config?: {
+    attributeResolver?: ((elt: Element, name: string) => string | null) | null;
+    additionalAttributeSelectors?: string[];
+  };
+}
+
+/**
+ * Wire resolver mode into a (reference-patched) htmx instance: install
+ * the resolver, feed the discovery selectors, keep them fresh on vocab
+ * registration, and stand the canonicalization shim down. Returns an
+ * uninstall function that restores shim behavior.
+ */
+export function installResolverMode(htmx: ResolverConfigurableHtmx): () => void {
+  if (!htmx?.config) {
+    throw new Error('[htmx-i18n] installResolverMode: htmx.config not found');
+  }
+  const cfg = htmx.config;
+  cfg.attributeResolver = attributeResolver;
+  cfg.additionalAttributeSelectors = additionalAttributeSelectors();
+  const unsubscribe = onVocabUpdate(() => {
+    cfg.additionalAttributeSelectors = additionalAttributeSelectors();
+  });
+  resolverModeActive = true;
+  return () => {
+    unsubscribe();
+    cfg.attributeResolver = null;
+    cfg.additionalAttributeSelectors = [];
+    resolverModeActive = false;
+  };
+}