slicejs-web-framework 4.1.0 → 4.2.0

package/Slice/Components/Structural/Translator/dom.js

@@ -0,0 +1,253 @@
+/**
+ * `data-t` in the DOM: which texts an element gets, and writing them.
+ *
+ *   <h1 data-t="home.title"></h1>                     text ← home.title
+ *   <input data-t="home.search" placeholder>          placeholder ← home.search.placeholder
+ *   <button data-t="cart.count" data-t-count="3">     text ← cart.count with { count: 3 }
+ *   <p data-t="signup.terms">                         "Acepto los {link}." rebuilt around
+ *     <a data-t-slot="link" data-t="signup.link"></a>  the slot element, which keeps its
+ *   </p>                                               attributes and listeners
+ *
+ * `templateKeys()` is the rule the CLI reuses (`slice translator check`) to know which keys
+ * a template needs, so the two cannot drift.
+ */
+
+/** Attributes translated when present on an element with `data-t`, by tag ('*' = any). */
+export const TRANSLATABLE_ATTRIBUTES = Object.freeze({
+   placeholder: '*',
+   title: '*',
+   alt: '*',
+   'aria-label': '*',
+   'aria-description': '*',
+   'aria-placeholder': '*',
+   'aria-roledescription': '*',
+   'aria-valuetext': '*',
+   label: ['OPTION', 'OPTGROUP', 'TRACK'],
+   value: ['INPUT'],
+});
+
+/** `data-t-*` names that are directives, not message params. */
+export const RESERVED_PARAMS = Object.freeze(['text', 'slot']);
+
+/** Elements that never hold text. */
+const VOID_ELEMENTS = new Set([
+   'AREA', 'BASE', 'BR', 'COL', 'EMBED', 'HR', 'IMG', 'INPUT', 'LINK', 'META', 'SOURCE', 'TRACK', 'WBR',
+   'SELECT',
+]);
+
+const INPUT_VALUE_TYPES = new Set(['button', 'submit', 'reset']);
+
+const SLOT_MARK = '\u0000';
+const SLOT_PATTERN = /\u0000slot:([^\u0000]+)\u0000/;
+
+/**
+ * `aria-label` → `ariaLabel`; `user-name` → `userName`.
+ * @param {string} name
+ * @returns {string}
+ */
+export function camelCase(name) {
+   return name.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+}
+
+/**
+ * Translatable attributes present on an element (even empty).
+ * @param {{ tagName: string, hasAttribute(name: string): boolean, getAttribute(name: string): string|null }} element
+ * @returns {string[]}
+ */
+export function translatableAttributes(element) {
+   const tag = String(element.tagName || '').toUpperCase();
+   const found = [];
+   for (const [attribute, tags] of Object.entries(TRANSLATABLE_ATTRIBUTES)) {
+      if (!element.hasAttribute(attribute)) continue;
+      if (tags !== '*' && !tags.includes(tag)) continue;
+      if (attribute === 'value' && !INPUT_VALUE_TYPES.has(String(element.getAttribute('type') || '').toLowerCase())) {
+         continue;
+      }
+      found.push(attribute);
+   }
+   return found;
+}
+
+/**
+ * The keys an element with `data-t` needs: its text (unless it only fills attributes) and
+ * `key.<attribute>` for each translatable attribute present.
+ * @param {{ tagName: string, hasAttribute(name: string): boolean, getAttribute(name: string): string|null }} element
+ * @returns {{ key: string, text: string|null, attributes: Record<string, string> }|null}
+ */
+export function templateKeys(element) {
+   const key = (element.getAttribute('data-t') || '').trim();
+   if (!key) return null;
+   /** @type {Record<string, string>} */
+   const attributes = {};
+   const present = translatableAttributes(element);
+   for (const attribute of present) attributes[attribute] = `${key}.${camelCase(attribute)}`;
+   const tag = String(element.tagName || '').toUpperCase();
+   const fillsText = !VOID_ELEMENTS.has(tag) && (present.length === 0 || element.hasAttribute('data-t-text'));
+   return { key, text: fillsText ? key : null, attributes };
+}
+
+/**
+ * Message params from `data-t-*` attributes: `data-t-count="3"` → `{ count: 3 }`.
+ * Numeric strings become numbers so plurals and number formatting work.
+ * @param {Element} element
+ * @returns {Record<string, string|number>}
+ */
+export function paramsOf(element) {
+   /** @type {Record<string, string|number>} */
+   const params = {};
+   for (const { name, value } of Array.from(element.attributes)) {
+      if (!name.startsWith('data-t-')) continue;
+      const param = name.slice(7);
+      if (!param || RESERVED_PARAMS.includes(param)) continue;
+      params[camelCase(param)] = /^-?\d+(\.\d+)?$/.test(value.trim()) ? Number(value) : value;
+   }
+   return params;
+}
+
+/**
+ * Elements under `root` (and `root` itself) that carry `data-t`.
+ * @param {ParentNode & Partial<Element>} root
+ * @returns {Element[]}
+ */
+export function translatableIn(root) {
+   const list = [];
+   if (root && typeof root.hasAttribute === 'function' && root.hasAttribute('data-t')) list.push(/** @type {Element} */ (root));
+   if (root && typeof root.querySelectorAll === 'function') list.push(...root.querySelectorAll('[data-t]'));
+   return list;
+}
+
+/**
+ * @typedef {Object} DomContext
+ * @property {(key: string, params?: Record<string, any>) => string} t
+ * @property {() => string} signature  locale + dictionary version, to skip elements already up to date
+ * @property {WeakMap<Element, string>} applied
+ * @property {WeakMap<Element, Map<string, Element>>} slots
+ * @property {(message: string) => void} [warn]
+ */
+
+/**
+ * Translate one element. Skips it when nothing changed since the last pass (same locale,
+ * dictionaries, key and params), so the observer and explicit passes can overlap freely.
+ * @param {Element} element
+ * @param {DomContext} context
+ * @returns {boolean} whether something was written
+ */
+export function translateElement(element, context) {
+   const keys = templateKeys(element);
+   if (!keys) return false;
+
+   const params = paramsOf(element);
+   const stamp = `${context.signature()}|${keys.key}|${JSON.stringify(params)}|${Object.keys(keys.attributes).join(',')}|${keys.text ? 1 : 0}`;
+   if (context.applied.get(element) === stamp) return false;
+   context.applied.set(element, stamp);
+
+   for (const [attribute, key] of Object.entries(keys.attributes)) {
+      const text = context.t(key, params);
+      if (element.getAttribute(attribute) !== text) element.setAttribute(attribute, text);
+   }
+
+   if (keys.text) {
+      writeText(element, keys.key, params, context);
+   } else if (Object.keys(keys.attributes).length === 0) {
+      context.warn?.(`data-t="${keys.key}" on <${element.tagName.toLowerCase()}> has nothing to fill: add a translatable attribute (placeholder, aria-label…)`);
+   }
+   return true;
+}
+
+/**
+ * Translate every `data-t` element under `root`.
+ * @param {ParentNode} root
+ * @param {DomContext} context
+ * @returns {number} elements written
+ */
+export function translateTree(root, context) {
+   let written = 0;
+   for (const element of translatableIn(root)) {
+      if (translateElement(element, context)) written++;
+   }
+   return written;
+}
+
+/**
+ * @param {Element} element
+ * @param {string} key
+ * @param {Record<string, any>} params
+ * @param {DomContext} context
+ */
+function writeText(element, key, params, context) {
+   const slots = slotsOf(element, context);
+
+   if (slots.size > 0) {
+      /** @type {Record<string, any>} */
+      const withSlots = { ...params };
+      for (const name of slots.keys()) withSlots[name] = `${SLOT_MARK}slot:${name}${SLOT_MARK}`;
+      const message = context.t(key, withSlots);
+      const nodes = [];
+      const used = new Set();
+      const parts = message.split(SLOT_PATTERN);
+      // split with a capture group alternates: text, slot name, text, slot name, …
+      parts.forEach((part, index) => {
+         if (index % 2 === 0) {
+            if (part) nodes.push(element.ownerDocument.createTextNode(part));
+            return;
+         }
+         const slot = slots.get(part);
+         if (slot && !used.has(part)) {
+            used.add(part);
+            nodes.push(slot);
+         }
+      });
+      element.replaceChildren(...nodes);
+      for (const [name, slot] of slots) {
+         if (used.has(name)) slot.__sliceSlotDetached = false;
+         else if (!slot.isConnected) slot.__sliceSlotDetached = true;
+      }
+      return;
+   }
+
+   const text = context.t(key, params);
+   if (element.children.length === 0) {
+      if (element.textContent !== text) element.textContent = text;
+      return;
+   }
+
+   // Child elements without data-t-slot (an icon in a button): keep them and replace only
+   // the element's own text, where the first visible text was (or at the end).
+   const ownText = Array.from(element.childNodes).filter((node) => node.nodeType === 3);
+   const anchor = ownText.find((node) => (node.textContent || '').trim() !== '');
+   if (anchor && ownText.filter((node) => (node.textContent || '').trim() !== '').length === 1 && anchor.textContent === text) {
+      return;
+   }
+   const node = element.ownerDocument.createTextNode(text);
+   if (anchor) element.insertBefore(node, anchor);
+   else element.appendChild(node);
+   for (const old of ownText) if ((old.textContent || '').trim() !== '') old.remove();
+}
+
+/**
+ * Slot elements of `element`: descendants with `data-t-slot` whose closest `data-t`
+ * ancestor is `element`. Remembered, so a locale whose message omits a slot does not lose
+ * it for the next locale.
+ * @param {Element} element
+ * @param {DomContext} context
+ * @returns {Map<string, Element>}
+ */
+function slotsOf(element, context) {
+   let slots = context.slots.get(element);
+   if (!slots) slots = new Map();
+   const present = new Map();
+   for (const candidate of element.querySelectorAll('[data-t-slot]')) {
+      if (candidate.parentElement?.closest('[data-t]') !== element) continue;
+      const name = candidate.getAttribute('data-t-slot');
+      if (!name) continue;
+      present.set(name, candidate);
+   }
+   // A slot the app removed is gone; one this helper detached to show a message without
+   // it is kept for the next locale (that is why the cache exists).
+   for (const [name, node] of slots) {
+      if (!node.isConnected && !node.__sliceSlotDetached) slots.delete(name);
+   }
+   for (const [name, node] of present) slots.set(name, node);
+   if (slots.size) context.slots.set(element, slots);
+   return slots;
+}

package/Slice/Components/Structural/Translator/localePath.js

@@ -0,0 +1,90 @@
+/**
+ * The locale in the URL (`localePrefix`, feature 0003 §7). Pure: no DOM, no `slice` global, no
+ * imports — the server-side SEO code uses the same rules.
+ *
+ *   localePrefix: "always"          /es/pricing   /en/pricing   (`/` redirects to a locale)
+ *   localePrefix: "except-default"  /pricing      /en/pricing   (default locale has no prefix)
+ *   localePrefix: false             /pricing      (the locale is never in the URL)
+ *
+ * Routes are declared once, without a locale; the prefix is added and removed here.
+ */
+
+/** @typedef {false|'always'|'except-default'} LocalePrefix */
+
+/**
+ * Normalize the `localePrefix` option: anything else means "not in the URL".
+ * @param {unknown} value
+ * @returns {LocalePrefix}
+ */
+export function normalizeLocalePrefix(value) {
+   return value === 'always' || value === 'except-default' ? value : false;
+}
+
+/**
+ * Split `?query#hash` off a path.
+ * @param {string} path
+ * @returns {[string, string]} [pathname, suffix]
+ */
+export function splitSuffix(path) {
+   const index = path.search(/[?#]/);
+   return index === -1 ? [path, ''] : [path.slice(0, index), path.slice(index)];
+}
+
+/**
+ * Remove a known locale prefix: `/en/pricing?x=1` → `{ locale: 'en', path: '/pricing?x=1' }`.
+ * The match is case-insensitive and returns the locale as configured. A first segment that
+ * is not a configured locale (`/fr/…`, `/docs/…`) is part of the path.
+ * @param {string} url
+ * @param {readonly string[]} locales
+ * @returns {{ locale: string|null, path: string }}
+ */
+export function splitLocalePath(url, locales) {
+   const value = typeof url === 'string' && url ? url : '/';
+   const [pathname, suffix] = splitSuffix(value);
+   const match = /^\/([^/]+)(\/.*)?$/.exec(pathname);
+   if (!match || !Array.isArray(locales)) return { locale: null, path: value };
+   const segment = match[1].toLowerCase();
+   const locale = locales.find((candidate) => candidate.toLowerCase() === segment);
+   if (!locale) return { locale: null, path: value };
+   return { locale, path: `${match[2] || '/'}${suffix}` };
+}
+
+/**
+ * The URL of an app path in a locale.
+ * @param {string} path app path, without locale (may carry `?query#hash`)
+ * @param {string|null} locale
+ * @param {{ localePrefix: LocalePrefix, defaultLocale: string }} options
+ * @returns {string}
+ */
+export function localizePath(path, locale, { localePrefix, defaultLocale }) {
+   const value = typeof path === 'string' && path ? path : '/';
+   if (!localePrefix || !locale) return value;
+   if (localePrefix === 'except-default' && locale === defaultLocale) return value;
+   const [pathname, suffix] = splitSuffix(value);
+   return `/${locale}${pathname === '/' ? '' : pathname}${suffix}`;
+}
+
+/**
+ * The locale a URL stands for: its prefix, or — with "except-default" — the default locale
+ * when there is none. `null` with "always" and no prefix (the locale must be chosen and the
+ * URL redirected), and always `null` without a prefix.
+ * @param {string} url
+ * @param {{ localePrefix: LocalePrefix, defaultLocale: string, locales: readonly string[] }} options
+ * @returns {string|null}
+ */
+export function localeOfUrl(url, { localePrefix, defaultLocale, locales }) {
+   if (!localePrefix) return null;
+   const { locale } = splitLocalePath(url, locales);
+   if (locale) return locale;
+   return localePrefix === 'except-default' ? defaultLocale : null;
+}
+
+/**
+ * Whether `href` is something `localizePath` must leave alone: another origin, a scheme
+ * (`mailto:`), a protocol-relative URL, a fragment, a query, or a relative path.
+ * @param {string} href
+ * @returns {boolean}
+ */
+export function isExternalHref(href) {
+   return typeof href !== 'string' || !href.startsWith('/') || href.startsWith('//');
+}

package/Slice/Components/Structural/Translator/localized.js

@@ -0,0 +1,80 @@
+/**
+ * Localized content values: `{ en: ..., es: ... }` → the branch for the active locale.
+ *
+ * Pure on purpose (no DOM, no `slice` global, no imports) so the browser runtime, the CLI
+ * and the server can share exactly one resolver. This is not a dictionary lookup: it never
+ * sees keys, only a value that carries one branch per locale. UI messages still live in
+ * dictionaries and go through `t()`; content records use this.
+ */
+
+const LOCALE_TAG = /^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$/i;
+const MAX_DEPTH = 24;
+
+/** `en` and `en-US` are the same language for branch selection. */
+function sameLocale(a, b) {
+   const left = String(a).toLowerCase();
+   const right = String(b).toLowerCase();
+   return left === right || left.split('-')[0] === right.split('-')[0];
+}
+
+/** @param {unknown} value @returns {value is Record<string, any>} */
+function isPlainObject(value) {
+   if (!value || typeof value !== 'object') return false;
+   const proto = Object.getPrototypeOf(value);
+   return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Whether `value` is an object whose keys are locale tags (`{ en: …, es: … }`).
+ * With a configured list, every key must be one of those locales; without one (translator
+ * disabled), every key has to look like a language tag.
+ * @param {unknown} value
+ * @param {readonly string[]} [locales]
+ * @returns {boolean}
+ */
+export function isLocalizedObject(value, locales) {
+   if (!isPlainObject(value)) return false;
+   const keys = Object.keys(value);
+   if (keys.length === 0) return false;
+   if (Array.isArray(locales) && locales.length > 0) {
+      const configured = new Set(locales.map((locale) => String(locale).toLowerCase()));
+      // Every key must be a locale tag, and at least one must be configured. The extra tags
+      // still count: with the translator off (locales = [browser]) `{ en, es }` must resolve
+      // to the browser branch instead of leaking the whole object into the UI.
+      return keys.every((key) => configured.has(key.toLowerCase()) || LOCALE_TAG.test(key))
+         && keys.some((key) => [...configured].some((locale) => sameLocale(key, locale)));
+   }
+   return keys.every((key) => LOCALE_TAG.test(key));
+}
+
+/**
+ * Resolve a value for one locale. Localized objects pick their branch; arrays and plain
+ * objects are walked recursively; everything else is returned untouched.
+ *
+ * Fallback order: `locale` → `fallbackLocale` → `defaultLocale`. A localized object with
+ * none of those branches resolves to `undefined` (the caller decides whether that is an
+ * error; the content validator catches it before deploy).
+ * @param {any} value
+ * @param {{ locale?: string, fallbackLocale?: string|null, defaultLocale?: string, locales?: readonly string[] }} [options]
+ * @param {number} [depth]
+ * @returns {any}
+ */
+export function localize(value, options = {}, depth = 0) {
+   if (value === null || value === undefined || depth > MAX_DEPTH) return value;
+   if (Array.isArray(value)) return value.map((item) => localize(item, options, depth + 1));
+   if (!isPlainObject(value)) return value;
+
+   if (isLocalizedObject(value, options.locales)) {
+      const chain = [options.locale, options.fallbackLocale, options.defaultLocale]
+         .filter((locale) => typeof locale === 'string' && locale);
+      for (const locale of chain) {
+         const key = Object.keys(value).find((candidate) => sameLocale(candidate, locale));
+         if (key !== undefined) return localize(value[key], options, depth + 1);
+      }
+      return undefined;
+   }
+
+   const out = {};
+   for (const [key, item] of Object.entries(value)) out[key] = localize(item, options, depth + 1);
+   return out;
+}

package/Slice/Components/Structural/Translator/markers.js

@@ -0,0 +1,148 @@
+/**
+ * Key references for component props: `slice.t.ref('orders.save')`.
+ *
+ * A marker is what an app passes instead of a string. The framework resolves it before
+ * the component sees it (the component only ever receives text) and assigns the prop
+ * again when the locale changes. Pure: no DOM, no `slice` global.
+ */
+
+// Self-contained on purpose: the CLI bundler inlines the helpers a Structural component
+// imports, but not helpers imported by those helpers.
+/** @param {unknown} value @returns {value is Record<string, any>} */
+function isPlainObject(value) {
+   if (!value || typeof value !== 'object') return false;
+   const proto = Object.getPrototypeOf(value);
+   return proto === Object.prototype || proto === null;
+}
+
+export class TranslationRef {
+   /** @type {(() => void) | undefined} */
+   #onStringify;
+
+   /**
+    * @param {string} key
+    * @param {Record<string, any>} [params]
+    * @param {() => void} [onStringify] called when the marker is used as text by mistake
+    */
+   constructor(key, params, onStringify) {
+      this.key = String(key);
+      this.params = params && typeof params === 'object' ? Object.freeze({ ...params }) : undefined;
+      this.#onStringify = onStringify;
+      Object.freeze(this);
+   }
+
+   /**
+    * A marker that ends up as text (`'Save: ' + marker`) shows its key, and warns in
+    * development: it was meant for a prop, not for string concatenation.
+    * @returns {string}
+    */
+   toString() {
+      this.#onStringify?.();
+      return this.key;
+   }
+
+   /** @param {string} hint */
+   [Symbol.toPrimitive](hint) {
+      return hint === 'number' ? NaN : this.toString();
+   }
+
+   toJSON() {
+      return this.toString();
+   }
+}
+
+/**
+ * A reference to a *list* of messages for a component prop, from `slice.t.ref.list()`.
+ * It resolves to an array, and the whole prop is assigned again on a locale change.
+ */
+export class TranslationListRef {
+   /** @type {(() => void) | undefined} */
+   #onStringify;
+
+   /**
+    * @param {string} key
+    * @param {Record<string, any>} [params]
+    * @param {() => void} [onStringify] called when the marker is used as text by mistake
+    */
+   constructor(key, params, onStringify) {
+      this.key = String(key);
+      this.params = params && typeof params === 'object' ? Object.freeze({ ...params }) : undefined;
+      this.#onStringify = onStringify;
+      Object.freeze(this);
+   }
+
+   /** @returns {string} */
+   toString() {
+      this.#onStringify?.();
+      return this.key;
+   }
+
+   /** @param {string} hint */
+   [Symbol.toPrimitive](hint) {
+      return hint === 'number' ? NaN : this.toString();
+   }
+
+   toJSON() {
+      return this.toString();
+   }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is TranslationRef}
+ */
+export function isMarker(value) {
+   return value instanceof TranslationRef;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is TranslationListRef}
+ */
+export function isListMarker(value) {
+   return value instanceof TranslationListRef;
+}
+
+/**
+ * Whether a prop value holds a marker: itself, or nested in arrays and plain objects.
+ * Class instances (components, Dates, Maps…) are not walked.
+ * @param {unknown} value
+ * @param {number} [depth]
+ * @returns {boolean}
+ */
+export function containsMarker(value, depth = 0) {
+   if (isMarker(value) || isListMarker(value)) return true;
+   if (depth > 8) return false;
+   if (Array.isArray(value)) return value.some((item) => containsMarker(item, depth + 1));
+   if (isPlainObject(value)) return Object.values(value).some((item) => containsMarker(item, depth + 1));
+   return false;
+}
+
+/**
+ * A copy of `value` with every marker replaced by `translate(key, params)` (or
+ * `translateList(key, params)` for a list marker). Arrays and plain objects are copied only
+ * along the paths that hold markers; everything else keeps its identity. Markers inside a
+ * marker's params resolve too.
+ * @param {unknown} value
+ * @param {(key: string, params?: Record<string, any>) => string} translate
+ * @param {number} [depth]
+ * @param {((key: string, params?: Record<string, any>) => any) | null} [translateList]
+ * @returns {any}
+ */
+export function resolveMarkers(value, translate, depth = 0, translateList = null) {
+   if (isMarker(value) || isListMarker(value)) {
+      const params = value.params ? resolveMarkers(value.params, translate, depth + 1, translateList) : undefined;
+      if (isListMarker(value)) {
+         return typeof translateList === 'function' ? translateList(value.key, params) : translate(value.key, params);
+      }
+      return translate(value.key, params);
+   }
+   if (depth > 8 || !containsMarker(value, depth)) return value;
+   if (Array.isArray(value)) return value.map((item) => resolveMarkers(item, translate, depth + 1, translateList));
+   /** @type {Record<string, any>} */
+   const copy = {};
+   for (const [key, item] of Object.entries(/** @type {Record<string, any>} */ (value))) {
+      copy[key] = resolveMarkers(item, translate, depth + 1, translateList);
+   }
+   return copy;
+}