termaui 0.2.0 → 0.3.0

package/dist/terma-clusters.esm.js

@@ -0,0 +1,84 @@
+/* ==========================================================================
+   terma-clusters.esm.js v0.2.0
+   ESM build of terma-clusters — named exports for bundlers (Vite, webpack,
+   Rollup, esbuild) and native ES module imports.
+
+   Usage:
+     import { isTibetanCombining, tibetanClusters } from 'termaui/dist/terma-clusters.esm.js';
+
+     const clusters = tibetanClusters("བོད་");
+     // → [{ text: "བོ", cpCount: 2 }, { text: "ད", cpCount: 1 }, { text: "་", cpCount: 1 }]
+   ========================================================================== */
+
+/**
+ * isTibetanCombining(code)
+ *
+ * Returns true if the given Unicode codepoint (integer) is a Tibetan
+ * combining mark that must attach to a preceding base character.
+ *
+ * Covered ranges:
+ *   U+0F71–U+0F84  vowel signs, virama (ི ུ ེ ོ etc.)
+ *   U+0F86–U+0F87  sign marks (྆ ྇)
+ *   U+0F90–U+0FBC  subjoined consonants (ྐ ྒ ྲ ྱ ླ ྷ etc.)
+ *   U+0F35         ngas bzung nyi zla (༵)
+ *   U+0F37         ngas bzung snam bu (༷)
+ *   U+0F39         tsa-phru lenition mark (༹)
+ *   U+0F7E         anusvara — rje su nga ro (ཾ)
+ *   U+0F7F         visarga — rnam bcad (ཿ)
+ */
+export function isTibetanCombining(code) {
+  return (
+    (code >= 0x0F71 && code <= 0x0F84) ||
+    (code >= 0x0F86 && code <= 0x0F87) ||
+    (code >= 0x0F90 && code <= 0x0FBC) ||
+    code === 0x0F35 || code === 0x0F37 || code === 0x0F39 ||
+    code === 0x0F7E || code === 0x0F7F
+  );
+}
+
+/**
+ * tibetanClusters(str)
+ *
+ * Splits a Tibetan string into grapheme clusters. Each cluster is one
+ * base character followed by zero or more combining marks.
+ *
+ * Returns an array of objects:
+ *   text     {string}  — the cluster (one or more codepoints)
+ *   cpCount  {number}  — number of Unicode codepoints in this cluster
+ *
+ * Example:
+ *   tibetanClusters("བོད་")
+ *   → [
+ *       { text: "བོ", cpCount: 2 },   // base + naro vowel
+ *       { text: "ད",  cpCount: 1 },   // standalone base
+ *       { text: "་",  cpCount: 1 },   // tsheg — not combining
+ *     ]
+ */
+export function tibetanClusters(str) {
+  const codepoints = [...str];  // spread handles surrogate pairs correctly
+  const clusters = [];
+  let currentText = '';
+  let currentCount = 0;
+
+  for (const cp of codepoints) {
+    const code = cp.codePointAt(0);
+    if (isTibetanCombining(code) && currentCount > 0) {
+      currentText += cp;
+      currentCount++;
+    } else {
+      if (currentCount > 0) {
+        clusters.push({ text: currentText, cpCount: currentCount });
+      }
+      currentText = cp;
+      currentCount = 1;
+    }
+  }
+
+  if (currentCount > 0) {
+    clusters.push({ text: currentText, cpCount: currentCount });
+  }
+
+  return clusters;
+}
+
+export default { isTibetanCombining, tibetanClusters };

package/dist/terma-clusters.js

@@ -0,0 +1,123 @@
+/* ==========================================================================
+   terma-clusters.js v0.2.0
+   Tibetan grapheme clustering utilities for termaUI.
+
+   Prevents dotted-circle artifacts (◌) when Tibetan text is split into
+   individual codepoints for per-character DOM rendering — typing tutors,
+   diff views, search highlights, animated text, syntax highlighters.
+
+   Root cause: Tibetan vowel signs and subjoined consonants are Unicode
+   combining marks. Placed in a DOM element without their base character,
+   fonts render them on a dotted-circle placeholder. Grapheme clustering
+   groups each base + its combining marks into a single DOM element.
+
+   Usage (browser — sets window.termaClusters global):
+     <script src="https://cdn.jsdelivr.net/npm/termaui/dist/terma-clusters.js"></script>
+     <script>
+       const clusters = termaClusters.tibetanClusters("བོད་");
+       // → [
+       //     { text: "བོ", cpCount: 2 },  // base + naro vowel
+       //     { text: "ད",  cpCount: 1 },  // standalone base
+       //     { text: "་",  cpCount: 1 },  // tsheg (not combining)
+       //   ]
+     </script>
+
+   Usage (bundler — ESM):
+     import { isTibetanCombining, tibetanClusters } from 'termaui/dist/terma-clusters.esm.js';
+   ========================================================================== */
+
+const termaClusters = (() => {
+  'use strict';
+
+  /**
+   * isTibetanCombining(code)
+   *
+   * Returns true if the given Unicode codepoint (integer) is a Tibetan
+   * combining mark — a character that must attach to a preceding base
+   * character to render correctly.
+   *
+   * Covered ranges:
+   *   U+0F71–U+0F84  vowel signs, virama (ི ུ ེ ོ etc.)
+   *   U+0F86–U+0F87  sign marks (྆ ྇)
+   *   U+0F90–U+0FBC  subjoined consonants (ྐ ྒ ྲ ྱ ླ ྷ etc.)
+   *   U+0F35         ngas bzung nyi zla (༵)
+   *   U+0F37         ngas bzung snam bu (༷)
+   *   U+0F39         tsa-phru lenition mark (༹)
+   *   U+0F7E         anusvara — rje su nga ro (ཾ)
+   *   U+0F7F         visarga — rnam bcad (ཿ)
+   */
+  function isTibetanCombining(code) {
+    return (
+      (code >= 0x0F71 && code <= 0x0F84) ||
+      (code >= 0x0F86 && code <= 0x0F87) ||
+      (code >= 0x0F90 && code <= 0x0FBC) ||
+      code === 0x0F35 || code === 0x0F37 || code === 0x0F39 ||
+      code === 0x0F7E || code === 0x0F7F
+    );
+  }
+
+  /**
+   * tibetanClusters(str)
+   *
+   * Splits a Tibetan string into grapheme clusters. Each cluster is one
+   * base character followed by zero or more combining marks.
+   *
+   * Returns an array of objects:
+   *   text     {string}  — the cluster (one or more codepoints)
+   *   cpCount  {number}  — number of Unicode codepoints in this cluster
+   *
+   * Example:
+   *   tibetanClusters("བོད་")
+   *   → [
+   *       { text: "བོ", cpCount: 2 },   // བ + ོ  (base + naro vowel)
+   *       { text: "ད",  cpCount: 1 },   // standalone base
+   *       { text: "་",  cpCount: 1 },   // tsheg — not a combining mark
+   *     ]
+   *
+   * Wrap each cluster in a <span class="tr-cluster"> rather than wrapping
+   * individual codepoints, to prevent dotted-circle artifacts:
+   *
+   *   BROKEN:  <span>བ</span><span>ོ</span>  →  བ + ◌ོ
+   *   CORRECT: <span class="tr-cluster">བོ</span>  →  བོ
+   */
+  function tibetanClusters(str) {
+    const codepoints = [...str];  // spread handles surrogate pairs correctly
+    const clusters = [];
+    let currentText = '';
+    let currentCount = 0;
+
+    for (const cp of codepoints) {
+      const code = cp.codePointAt(0);
+      if (isTibetanCombining(code) && currentCount > 0) {
+        // Attach combining mark to the current cluster
+        currentText += cp;
+        currentCount++;
+      } else {
+        // Flush previous cluster, start a new one
+        if (currentCount > 0) {
+          clusters.push({ text: currentText, cpCount: currentCount });
+        }
+        currentText = cp;
+        currentCount = 1;
+      }
+    }
+
+    if (currentCount > 0) {
+      clusters.push({ text: currentText, cpCount: currentCount });
+    }
+
+    return clusters;
+  }
+
+  return { isTibetanCombining, tibetanClusters };
+})();
+
+// Expose as window.termaClusters in browser environments
+if (typeof window !== 'undefined') {
+  window.termaClusters = termaClusters;
+}
+
+// Export for module environments (CommonJS / Node)
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = termaClusters;
+}

package/dist/terma.esm.js

@@ -1,15 +1,19 @@
 /* ==========================================================================
-   terma.js v0.1.0 — ESM Module
+   terma.js v0.2.0 — ESM Module
    Tibetan text processing utilities for termaUI.
-   Handles line-breaking, justification, and punctuation protection
-   that CSS alone cannot solve.
+   Handles line-breaking, justification, punctuation protection, and
+   grapheme clustering to prevent dotted-circle artifacts.
 
    Usage (bundler / import statement):
      import terma from 'termaui';
      terma.prepareAll();
 
    Named imports also work:
-     import { prepare, prepareAll, normalize, normalizeAll } from 'termaui';
+     import { prepare, prepareAll, cluster, clusterAll, normalize, normalizeAll } from 'termaui';
+
+   Auto-clustering: if window.termaClusters is available (terma-clusters.js
+   loaded), prepare() automatically wraps combining marks into .tr-cluster
+   spans — no extra code required.
    ========================================================================== */
 
 'use strict';
@@ -23,6 +27,71 @@ const GTER_MA = '\u0F14';           // ༔  terma sign
 const VISARGA = '\u0F7F';           // ཿ  visarga
 const ZWS = '\u200B';               // zero-width space (break opportunity)
 const WJ = '\u2060';                // word joiner (prevents break)
+const TIBETAN_RE = /[\u0F00-\u0FFF]/;
+
+// ── Head-mark alignment (Layer 2) ──────────────────────────
+const _ascentCache = {};
+
+function _measureAscentRatio(fontFamily) {
+  if (_ascentCache[fontFamily] !== undefined) return _ascentCache[fontFamily];
+  var canvas = document.createElement('canvas');
+  var ctx = canvas.getContext('2d');
+  ctx.font = '100px ' + fontFamily;
+  var m = ctx.measureText('\u0F42');
+  if (typeof m.actualBoundingBoxAscent !== 'number') {
+    _ascentCache[fontFamily] = null;
+    return null;
+  }
+  var ratio = m.actualBoundingBoxAscent / 100;
+  _ascentCache[fontFamily] = ratio;
+  return ratio;
+}
+
+function _alignHeadMarks(el) {
+  if (typeof document === 'undefined') return;
+
+  var ps = getComputedStyle(el);
+  var pSize = parseFloat(ps.fontSize);
+  var pRatio = _measureAscentRatio(ps.fontFamily);
+  if (pRatio === null) return;
+
+  var spans = el.querySelectorAll(
+    'span[class*="tr-text-"], span[style*="font-size"]'
+  );
+
+  for (var i = 0; i < spans.length; i++) {
+    var span = spans[i];
+    if (span.classList.contains('tr-mixed')) continue;
+    if (span.classList.contains('tr-cluster')) continue;
+
+    if (!TIBETAN_RE.test(span.textContent)) {
+      span.classList.add('tt-latin');
+      span.style.verticalAlign = 'baseline';
+      span.style.lineHeight = '';
+      continue;
+    }
+
+    span.classList.remove('tt-latin');
+
+    var ss = getComputedStyle(span);
+    var sSize = parseFloat(ss.fontSize);
+
+    if (Math.abs(pSize - sSize) < 0.5) {
+      span.style.verticalAlign = '';
+      span.style.lineHeight = '';
+      continue;
+    }
+
+    var sRatio = _measureAscentRatio(ss.fontFamily);
+    if (sRatio === null) continue;
+
+    var offset = pRatio * pSize - sRatio * sSize;
+    span.style.verticalAlign = offset.toFixed(2) + 'px';
+    span.style.lineHeight = '1';
+  }
+
+  el.dataset.termaAligned = 'true';
+}
 
 /**
  * Walk all text nodes inside an element.
@@ -37,49 +106,72 @@ function walkTextNodes(el, callback) {
   }
 }
 
+/**
+ * _clusterTextNodes(el)  [private]
+ *
+ * Walks all text nodes inside el that contain Tibetan text with
+ * combining marks and replaces each with a series of
+ * <span class="tr-cluster"> elements — one per grapheme cluster.
+ */
+function _clusterTextNodes(el) {
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  const nodes = [];
+  while (walker.nextNode()) nodes.push(walker.currentNode);
+
+  for (const node of nodes) {
+    const text = node.textContent;
+    if (!text || !TIBETAN_RE.test(text)) continue;
+
+    const clusters = window.termaClusters.tibetanClusters(text);
+    if (!clusters.some(c => c.cpCount > 1)) continue;
+
+    const frag = document.createDocumentFragment();
+    for (const c of clusters) {
+      const span = document.createElement('span');
+      span.className = 'tr-cluster';
+      span.textContent = c.text;
+      frag.appendChild(span);
+    }
+    node.parentNode.replaceChild(frag, node);
+  }
+}
+
 /**
  * prepare(element)
  *
  * Processes Tibetan text inside the given element:
  *
- * 1. Replaces tsheg before any clause-ending mark with non-breaking tsheg (༌)
- *    to prevent bad breaks. Covers:
- *      - shad (།  U+0F0D) — standard clause marker
- *      - nyis-shad (༎  U+0F0E) — double clause marker
- *      - gter-ma (༔  U+0F14) — terma / treasure-text sign
- *    Example: ང་། → ང༌།  |  ར་༎ → ར༌༎  |  ར་༔ → ར༌༔
+ * 0. Auto-clusters combining marks into .tr-cluster spans (if
+ *    window.termaClusters is available) — prevents dotted-circle artifacts.
  *
- * 2. Wraps double-shad sequences (། །) with word-joiners so they
- *    never split across lines.
+ * 1. Replaces tsheg before clause-ending marks with non-breaking tsheg (༌).
+ *    Covers shad (།), nyis-shad (༎), gter-ma (༔).
  *
- * 3. Inserts zero-width spaces after tsheg (་) to give browsers
- *    proper line-break opportunities — the #1 Tibetan rendering fix.
+ * 2. Wraps double-shad sequences (། །) with word-joiners.
  *
- * Call this after the DOM is ready. Safe to call multiple times —
- * already-processed elements are skipped.
+ * 3. Inserts zero-width spaces after tsheg for line-break opportunities.
+ *
+ * Safe to call multiple times — already-processed elements are skipped.
  */
 export function prepare(el) {
   if (!el) return;
   if (el.dataset.termaPrepared) return;
 
+  // Steps 1–3: text-node mutations first — regexes need tsheg and following
+  // punctuation in the same text node, which clustering would split apart.
   walkTextNodes(el, (node) => {
     let text = node.textContent;
 
-    // Step 1: Replace tsheg before clause-ending marks with non-breaking tsheg.
-    // Covers shad (།), nyis-shad (༎), and gter-ma (༔).
-    // The captured group ($1) preserves whichever mark was present.
     text = text.replace(
       new RegExp(TSHEG + '([' + SHAD + NYIS_SHAD + GTER_MA + '])', 'g'),
       TSHEG_NONBREAK + '$1'
     );
 
-    // Step 2: Protect double-shad from splitting
     text = text.replace(
       new RegExp(SHAD + ' ' + SHAD, 'g'),
       SHAD + WJ + ' ' + WJ + SHAD
     );
 
-    // Step 3: Insert zero-width space after tsheg for line-break opportunities
     text = text.replace(
       new RegExp(TSHEG + '(?!' + ZWS + ')', 'g'),
       TSHEG + ZWS
@@ -90,6 +182,15 @@ export function prepare(el) {
     }
   });
 
+  // Step 4: auto-cluster after text fixes — splitting before would prevent
+  // the tsheg→non-breaking-tsheg regex from seeing adjacent characters.
+  if (typeof window !== 'undefined' && window.termaClusters) {
+    _clusterTextNodes(el);
+  }
+
+  // Step 5: head-mark alignment
+  _alignHeadMarks(el);
+
   el.dataset.termaPrepared = 'true';
 }
 
@@ -104,6 +205,74 @@ export function prepareAll(selector) {
   document.querySelectorAll(sel).forEach(prepare);
 }
 
+/**
+ * prepareEditable(element)
+ *
+ * Prepares a contenteditable element for live Tibetan text entry.
+ * Calls prepare() immediately, then re-applies it on every input event
+ * so ZWS insertions survive further typing.
+ *
+ * Use instead of prepare() for <div contenteditable> typing tutors,
+ * Tibetan note-taking UIs, or any live-edit Tibetan surface.
+ * Pair with [contenteditable][lang="bo"] { white-space: pre-wrap; }
+ * (included in termaui.css by default) to prevent ZWS collapse.
+ *
+ * Safe to call multiple times on the same element — already-attached
+ * listeners are skipped.
+ */
+export function prepareEditable(el) {
+  if (!el) return;
+  if (el.dataset.termaEditable) return;
+  prepare(el);
+  let debounce;
+  el.addEventListener('input', () => {
+    clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      delete el.dataset.termaPrepared;
+      prepare(el);
+    }, 150);
+  });
+  el.dataset.termaEditable = 'true';
+}
+
+/**
+ * prepareAllEditables(selector?)
+ *
+ * Convenience: prepareEditable() on all [contenteditable][lang="bo"]
+ * elements, or all elements matching the given selector.
+ */
+export function prepareAllEditables(selector) {
+  const sel = selector || '[contenteditable][lang="bo"]';
+  document.querySelectorAll(sel).forEach(prepareEditable);
+}
+
+/**
+ * cluster(element)
+ *
+ * Explicitly applies grapheme clustering to all Tibetan text nodes
+ * inside the element. Requires window.termaClusters to be available.
+ *
+ * Note: prepare() calls this automatically when terma-clusters.js is loaded.
+ */
+export function cluster(el) {
+  if (!el) return;
+  if (typeof window === 'undefined' || !window.termaClusters) return;
+  if (el.dataset.termaClustered) return;
+  _clusterTextNodes(el);
+  el.dataset.termaClustered = 'true';
+}
+
+/**
+ * clusterAll(selector?)
+ *
+ * Convenience: cluster all [lang="bo"] elements on the page,
+ * or all elements matching the given selector.
+ */
+export function clusterAll(selector) {
+  const sel = selector || '[lang="bo"]';
+  document.querySelectorAll(sel).forEach(cluster);
+}
+
 /**
  * normalize(element)
  *
@@ -134,6 +303,51 @@ export function normalizeAll(selector) {
   document.querySelectorAll(sel).forEach(normalize);
 }
 
-const terma = { prepare, prepareAll, normalize, normalizeAll };
+/**
+ * alignHeadMarks(element)
+ *
+ * Applies pixel-perfect Tibetan head-mark alignment to sized spans.
+ * Note: prepare() calls this automatically.
+ */
+export function alignHeadMarks(el) {
+  if (!el) return;
+  _alignHeadMarks(el);
+}
+
+/**
+ * alignHeadMarksAll(selector?)
+ *
+ * Convenience: alignHeadMarks on all [lang="bo"] elements.
+ */
+export function alignHeadMarksAll(selector) {
+  const sel = selector || '[lang="bo"]';
+  document.querySelectorAll(sel).forEach(alignHeadMarks);
+}
+
+/**
+ * measureAscentRatio(fontFamily)
+ *
+ * Returns the ascent ratio for a font family via Canvas TextMetrics.
+ */
+export function measureAscentRatio(fontFamily) {
+  return _measureAscentRatio(fontFamily);
+}
+
+// Re-align after webfont swap
+if (typeof document !== 'undefined' && document.fonts) {
+  document.fonts.ready.then(function () {
+    for (var k in _ascentCache) delete _ascentCache[k];
+    var aligned = document.querySelectorAll('[data-terma-aligned]');
+    for (var i = 0; i < aligned.length; i++) {
+      _alignHeadMarks(aligned[i]);
+    }
+  });
+}
+
+const terma = {
+  prepare, prepareAll, prepareEditable, prepareAllEditables,
+  cluster, clusterAll, normalize, normalizeAll,
+  alignHeadMarks, alignHeadMarksAll, measureAscentRatio
+};
 
 export default terma;