livelocale 0.12.1 → 1.0.0

package/README.md

@@ -5,8 +5,8 @@
       <img src="brand/logo.svg" alt="livelocale" height="64">
     </picture>
   </h1>
-  <p><strong>Click any text in your app. Fix the translation. Ship it as a pull request.</strong></p>
-  <p>Keep next-intl or react-i18next. LiveLocale adds in-context editing for Next.js and React + Vite: no account, no server, no browser extension. Your translations stay as JSON in git.</p>
+  <p><strong>The editing and review layer on top of next-intl or react-i18next.</strong></p>
+  <p>Your content people fix text on the real site, and you get each fix as an edit to your JSON locale files in git, or as a pull request. For Next.js and React + Vite: no account, no server, no browser extension.</p>
 
   <p align="center">
     <a href="https://github.com/Araby99/livelocale/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/Araby99/livelocale/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI Status" /></a>
@@ -18,6 +18,16 @@
 
 ---
 
+**It is not an i18n library.** next-intl or react-i18next keeps doing routing, locale detection,
+date and number formatting and message rendering; livelocale only edits and reviews the text.
+
+- **Freelancing?** Your client fixes their own copy through a
+  [share link](https://livelocale.js.org/docs/guides/share-links.html), and you review a pull
+  request instead of collecting screenshots.
+- **Only want CI?** [`npx livelocale check --hardcoded`](https://livelocale.js.org/docs/guides/ci-check.html)
+  works without the Studio. Translating on your own? The CI check alone catches missing keys and
+  hard-coded text.
+
 Run your app beside the livelocale Studio, hold Alt and click a line of text, and fix it. The save
 goes straight into your locale JSON file as an ordinary edit you commit. In development every
 translated string carries an invisible watermark, so the Studio knows which key you clicked; in
@@ -87,6 +97,20 @@ npx livelocale studio
 Open `http://localhost:3010`, hold Alt (Option on a Mac), click a line of text and press
 **Save Changes**. `git diff locales/` shows the fix.
 
+## Supported versions
+
+| Needs                                     | Tested in CI                               |
+| ----------------------------------------- | ------------------------------------------ |
+| Node.js 18 or later                       | Node.js 20 and 24; the built package on 18 |
+| Next.js 13 or later                       | Next.js 16                                 |
+| React 18 or later                         | React 18                                   |
+| Vite 5 or later                           | Vite 8                                     |
+| TypeScript 4.7 to 6 (`check --hardcoded`) | TypeScript 5                               |
+
+From 1.0 on, livelocale follows semantic versioning, and share links people already sent keep
+working in newer versions. [Versioning and stability](https://livelocale.js.org/docs/reference/stability.html)
+lists what that covers and what is internal.
+
 ## Docs
 
 - [Get started](https://livelocale.js.org/docs/): Next.js, Vite + React, or any static host.
@@ -94,6 +118,7 @@ Open `http://localhost:3010`, hold Alt (Option on a Mac), click a line of text a
 - [Share links](https://livelocale.js.org/docs/guides/share-links.html): fixes from the deployed site, no account and no install.
 - [Catch untranslated text in CI](https://livelocale.js.org/docs/guides/ci-check.html): missing keys, placeholder drift and hardcoded text.
 - [CLI reference](https://livelocale.js.org/docs/reference/cli/index.html): every command and flag.
+- [Versioning and stability](https://livelocale.js.org/docs/reference/stability.html): what semver covers, and the versions CI tests.
 
 ## Contributing
 

package/dist/client/index.cjs

@@ -194,6 +194,7 @@ function isLiveLocaleEnabled() {
 }
 
 // src/client/iframe-bridge.ts
+var CLIENT_FEATURES = ["edit-mode"];
 var DEFAULT_STUDIO_ORIGIN = "http://localhost:3010";
 var STUDIO_ORIGIN_STORAGE_KEY = "livelocale-studio-origin";
 function toHttpOrigin(value) {
@@ -237,6 +238,8 @@ function resolveStudioOrigin(search, storage, sameOriginParent) {
 var MAX_VISIBLE_TEXTS = 100;
 var MAX_VISIBLE_TEXT_LENGTH = 200;
 var KEY_PATTERN = /^[a-zA-Z0-9._-]+$/;
+var FEATURE_PATTERN = /^[a-z0-9-]+$/;
+var MAX_FEATURES = 16;
 var MAX_LOCATION_LENGTH = 2048;
 var LOCATION_CONTROL_RE = /[\u0000-\u001f\u007f-\u009f]/;
 var LOCATION_PROBE_ORIGIN = "http://livelocale.invalid";
@@ -291,7 +294,7 @@ var IframeBridge = class {
         return;
       }
     }
-    if (type === "VISIBLE_KEYS_CHANGED") {
+    if (type === "VISIBLE_KEYS_CHANGED" || type === "RENDERED_KEYS_CHANGED") {
       if (!Array.isArray(payload)) return;
       const validKeys = payload.filter(
         (k) => typeof k === "string" && /^[a-zA-Z0-9._-]+$/.test(k)
@@ -314,7 +317,15 @@ var IframeBridge = class {
     }
     if (type === "READY" || type === "LOCATION_CHANGED") {
       const url = toLocationUrl(payload);
-      payload = url === null ? {} : { url };
+      const next = url === null ? {} : { url };
+      const features = payload?.features;
+      if (type === "READY" && Array.isArray(features)) {
+        next.features = features.filter((f) => typeof f === "string" && FEATURE_PATTERN.test(f)).slice(0, MAX_FEATURES);
+      }
+      payload = next;
+    }
+    if (type === "TAP_UNKEYED") {
+      payload = void 0;
     }
     const message = {
       source: "livelocale-client",
@@ -366,9 +377,27 @@ function debounce(fn, wait) {
   };
   return debounced;
 }
+var EDITABLE_SELECTOR = 'input, textarea, select, [contenteditable]:not([contenteditable="false"])';
+var EDIT_STYLE_ID = "livelocale-edit-style";
+var EDIT_ATTRIBUTE = "data-livelocale-edit";
+var PICKED_ATTRIBUTE = "data-livelocale-picked";
+var REVEAL_MARGIN = 16;
+function isRendered(el) {
+  const visible = typeof el.checkVisibility === "function" ? el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }) : el.getClientRects().length > 0;
+  if (!visible) return false;
+  const rect = el.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}
+function hasOwnText(el) {
+  for (const child of el.childNodes) {
+    if (child.nodeType === Node.TEXT_NODE && (child.nodeValue ?? "").trim() !== "") return true;
+  }
+  return false;
+}
 var DOMInterceptor = class {
   onElementSelected;
   onVisibleKeysChanged;
+  onUnkeyedTap;
   hoveredElement = null;
   observer = null;
   inputSanitizersAttached = false;
@@ -377,11 +406,19 @@ var DOMInterceptor = class {
   overlayBadge = null;
   // ─── Alt key state ───────────────────────────────────────────────────────
   isAltHeld = false;
+  // ─── Edit mode (touch) ───────────────────────────────────────────────────
+  // Kept across destroy()/init() so the Studio's CLEAR_SELECTION, which
+  // re-inits the interceptor, never unfreezes the site.
+  editMode = false;
+  active = false;
+  /** The element carrying `PICKED_ATTRIBUTE`, if any. */
+  pickedElement = null;
   // Debounced key-broadcast to avoid flooding the parent on rapid DOM mutations
   broadcastVisibleKeys;
-  constructor(onElementSelected, onVisibleKeysChanged) {
+  constructor(onElementSelected, onVisibleKeysChanged, onUnkeyedTap) {
     this.onElementSelected = onElementSelected;
     this.onVisibleKeysChanged = onVisibleKeysChanged;
+    this.onUnkeyedTap = onUnkeyedTap;
     this.broadcastVisibleKeys = debounce(() => {
       if (this.onVisibleKeysChanged) {
         this.onVisibleKeysChanged(this.getActiveKeys());
@@ -429,6 +466,75 @@ var DOMInterceptor = class {
     }
     return texts;
   }
+  /**
+   * Returns the unique keys that have at least one rendered, visible element
+   * (see `isRendered`), in document order. Keys only inside closed menus,
+   * hidden slides or a layout hidden at this width are left out.
+   */
+  getRenderedKeys() {
+    const keys = /* @__PURE__ */ new Set();
+    document.querySelectorAll("[data-i18n-key]").forEach((el) => {
+      const key = el.getAttribute("data-i18n-key");
+      if (key && !keys.has(key) && isRendered(el)) keys.add(key);
+    });
+    return Array.from(keys);
+  }
+  /** The first rendered, visible element carrying `key`, else `null`. */
+  findRenderedElement(key) {
+    for (const el of document.querySelectorAll("[data-i18n-key]")) {
+      if (el.getAttribute("data-i18n-key") === key && isRendered(el)) return el;
+    }
+    return null;
+  }
+  /**
+   * Scrolls the first visible element with `key` to the centre and selects
+   * it as a tap would. Returns false, selecting nothing, when no element with
+   * that key is visible or the interceptor is not running. A key that is no
+   * longer visible (a carousel moved on with no DOM change the observer sees)
+   * reports the keys again, so the Studio's next try uses a fresh list.
+   */
+  selectKey(key) {
+    if (!this.active) return false;
+    const el = this.findRenderedElement(key);
+    if (!el) {
+      this.broadcastVisibleKeys();
+      return false;
+    }
+    if (typeof el.scrollIntoView === "function") el.scrollIntoView({ block: "center" });
+    this.select(el, key);
+    return true;
+  }
+  /**
+   * Scrolls so the first visible element with `key` sits fully between the
+   * frame's top and `bottomInset` CSS px above its bottom (where the Studio's
+   * sheet starts), without selecting it. Does nothing when it already does,
+   * or when no element with that key is visible. A tall element keeps its top
+   * in view rather than its bottom.
+   */
+  revealKey(key, bottomInset) {
+    if (!this.active) return;
+    const el = this.findRenderedElement(key);
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const limit = window.innerHeight - bottomInset;
+    if (rect.top >= 0 && rect.bottom <= limit) return;
+    const delta = Math.min(rect.bottom - limit + REVEAL_MARGIN, rect.top - REVEAL_MARGIN);
+    window.scrollBy(0, delta);
+  }
+  /**
+   * Turns Edit mode on or off. In Edit mode no tap reaches the site: a tap on
+   * keyed text selects it, a tap on other text calls `onUnkeyedTap`, and
+   * anything else does nothing. Scrolling still works. The mode is kept on
+   * the instance and re-applied by `init()`.
+   */
+  setEditMode(on) {
+    const changed = this.editMode !== on;
+    this.editMode = on;
+    if (!this.active) return;
+    if (on) this.attachEditMode();
+    else this.detachEditMode();
+    if (changed) this.broadcastVisibleKeys();
+  }
   /**
    * Initializes the DOM event interceptors in development mode.
    * Also launches the watermark scanner and MutationObserver.
@@ -453,6 +559,8 @@ var DOMInterceptor = class {
     this.scanSubtree(document.body);
     this.attachMutationObserver();
     this.attachInputSanitizers();
+    this.active = true;
+    if (this.editMode) this.attachEditMode();
     this.broadcastVisibleKeys();
   }
   /**
@@ -473,6 +581,8 @@ var DOMInterceptor = class {
     window.removeEventListener("keydown", this.handleKeyDown, true);
     window.removeEventListener("keyup", this.handleKeyUp, true);
     window.removeEventListener("beforeinput", this.handleBeforeInput, true);
+    this.detachEditMode();
+    this.active = false;
     document.removeEventListener("submit", this.handleFormSubmit, true);
     if (this.observer) {
       this.observer.disconnect();
@@ -487,6 +597,87 @@ var DOMInterceptor = class {
     this.hoveredElement = null;
     this.broadcastVisibleKeys.cancel();
   }
+  // ─── Edit Mode ───────────────────────────────────────────────────────────
+  attachEditMode() {
+    window.addEventListener("pointerdown", this.stopFromSite, true);
+    window.addEventListener("pointerup", this.stopFromSite, true);
+    window.addEventListener("mousedown", this.stopFromSite, true);
+    window.addEventListener("mouseup", this.stopFromSite, true);
+    window.addEventListener("touchstart", this.stopFromSite, { capture: true, passive: true });
+    window.addEventListener("touchend", this.stopFromSite, { capture: true, passive: true });
+    window.addEventListener("focusin", this.handleEditFocus, true);
+    if (!document.getElementById(EDIT_STYLE_ID)) {
+      const style = document.createElement("style");
+      style.id = EDIT_STYLE_ID;
+      style.textContent = `html[${EDIT_ATTRIBUTE}] [data-i18n-key]{outline:1px dashed rgba(79,195,220,.7);outline-offset:2px}html[${EDIT_ATTRIBUTE}] [data-i18n-key][${PICKED_ATTRIBUTE}]{outline:2px solid #FFB224;outline-offset:3px}`;
+      document.head.appendChild(style);
+    }
+    document.documentElement.setAttribute(EDIT_ATTRIBUTE, "");
+    this.hideOverlay();
+    this.hoveredElement = null;
+  }
+  detachEditMode() {
+    window.removeEventListener("pointerdown", this.stopFromSite, true);
+    window.removeEventListener("pointerup", this.stopFromSite, true);
+    window.removeEventListener("mousedown", this.stopFromSite, true);
+    window.removeEventListener("mouseup", this.stopFromSite, true);
+    window.removeEventListener("touchstart", this.stopFromSite, true);
+    window.removeEventListener("touchend", this.stopFromSite, true);
+    window.removeEventListener("focusin", this.handleEditFocus, true);
+    document.documentElement.removeAttribute(EDIT_ATTRIBUTE);
+    document.getElementById(EDIT_STYLE_ID)?.remove();
+    this.clearPicked();
+  }
+  /** Moves the picked-text marker to `element`. */
+  markPicked(element) {
+    this.clearPicked();
+    element.setAttribute(PICKED_ATTRIBUTE, "");
+    this.pickedElement = element;
+  }
+  clearPicked() {
+    this.pickedElement?.removeAttribute(PICKED_ATTRIBUTE);
+    this.pickedElement = null;
+  }
+  // Sites open menus on press events; in Edit mode none of them reaches the
+  // site. Never preventDefault here: on touchstart it would stop scrolling.
+  stopFromSite = (event) => {
+    event.stopImmediatePropagation();
+  };
+  handleEditFocus = (event) => {
+    const target = event.target;
+    if (!target || typeof target.matches !== "function") return;
+    if (target.matches(EDITABLE_SELECTOR) || target.isContentEditable) target.blur();
+  };
+  /** Edit-mode click: cancelled whatever the target, then a selection or the notice. */
+  handleEditClick(event) {
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    const target = event.target;
+    if (!target || typeof target.closest !== "function") return;
+    const keyedElement = target.closest("[data-i18n-key]");
+    const key = keyedElement?.getAttribute("data-i18n-key");
+    if (keyedElement && key) {
+      this.select(keyedElement, key);
+    } else if (hasOwnText(target)) {
+      this.onUnkeyedTap?.();
+    }
+  }
+  /**
+   * Reports `element`, which carries `key`, as selected with its clean text. In Edit mode it
+   * also gets the picked-text marker; an Alt+Click pick on a desktop does not.
+   */
+  select(element, key) {
+    if (this.editMode) this.markPicked(element);
+    const rawText = element.innerText || "";
+    const cleanText = stripWatermark(rawText);
+    const fallbackValue = element.getAttribute("data-i18n-template") || cleanText;
+    const currentValue = cleanText;
+    this.onElementSelected({
+      key,
+      fallbackValue,
+      currentValue
+    });
+  }
   // ─── Floating Overlay ────────────────────────────────────────────────────
   /**
    * Creates and injects a single floating overlay div into the document body.
@@ -730,6 +921,7 @@ var DOMInterceptor = class {
   };
   // ─── Mouse / Click Handlers ───────────────────────────────────────────────
   handleMouseOver = (event) => {
+    if (this.editMode) return;
     const target = event.target;
     if (!target || typeof target.closest !== "function") return;
     const keyedElement = target.closest("[data-i18n-key]");
@@ -758,6 +950,10 @@ var DOMInterceptor = class {
     this.hoveredElement = null;
   };
   handleClick = (event) => {
+    if (this.editMode) {
+      this.handleEditClick(event);
+      return;
+    }
     if (!event.altKey) return;
     const target = event.target;
     if (!target || typeof target.closest !== "function") return;
@@ -767,15 +963,7 @@ var DOMInterceptor = class {
     if (key === null) return;
     event.preventDefault();
     event.stopPropagation();
-    const rawText = keyedElement.innerText || "";
-    const cleanText = stripWatermark(rawText);
-    const fallbackValue = keyedElement.getAttribute("data-i18n-template") || cleanText;
-    const currentValue = cleanText;
-    this.onElementSelected({
-      key,
-      fallbackValue,
-      currentValue
-    });
+    this.select(keyedElement, key);
   };
   handleCopy = (event) => {
     const selection = window.getSelection()?.toString() || "";
@@ -1036,16 +1224,22 @@ if (typeof window !== "undefined" && isLiveLocaleEnabled() && window.parent !==
     },
     (keys) => {
       bridge.sendToParent("VISIBLE_KEYS_CHANGED", keys);
+      bridge.sendToParent("RENDERED_KEYS_CHANGED", interceptor.getRenderedKeys());
       bridge.sendToParent("VISIBLE_TEXTS_CHANGED", interceptor.getVisibleTexts());
+    },
+    () => {
+      bridge.sendToParent("TAP_UNKEYED");
     }
   );
   interceptor.init();
   const locationUrl = () => window.location.pathname + window.location.search + window.location.hash;
-  bridge.sendToParent("READY", { url: locationUrl() });
+  bridge.sendToParent("READY", { url: locationUrl(), features: CLIENT_FEATURES });
   watchLocation(window, (url) => bridge.sendToParent("LOCATION_CHANGED", { url }));
   window.addEventListener("pagehide", () => bridge.sendToParent("LEAVING"));
   window.addEventListener("pageshow", (event) => {
-    if (event.persisted) bridge.sendToParent("READY", { url: locationUrl() });
+    if (event.persisted) {
+      bridge.sendToParent("READY", { url: locationUrl(), features: CLIENT_FEATURES });
+    }
   });
   bridge.listenToParent((type, payload) => {
     if (type === "APPLY_PREVIEW") {
@@ -1063,6 +1257,18 @@ if (typeof window !== "undefined" && isLiveLocaleEnabled() && window.parent !==
     } else if (type === "NAVIGATE") {
       const href = navigationHref(payload, window.location.origin);
       if (href !== null) followNavigation(window.location, href);
+    } else if (type === "SET_EDIT_MODE") {
+      if (payload && typeof payload.on === "boolean") {
+        interceptor.setEditMode(payload.on);
+      }
+    } else if (type === "SELECT_KEY") {
+      if (payload && typeof payload.key === "string") {
+        interceptor.selectKey(payload.key);
+      }
+    } else if (type === "REVEAL_KEY") {
+      if (payload && typeof payload.key === "string" && typeof payload.bottomInset === "number" && Number.isFinite(payload.bottomInset) && payload.bottomInset >= 0) {
+        interceptor.revealKey(payload.key, payload.bottomInset);
+      }
     }
   });
   window.__LIVELOCALE_CLIENT__ = {