livelocale 0.12.1 → 1.0.0

package/dist/client/index.d.ts

@@ -1,17 +1,47 @@
-export { W as WrapOptions, d as decodeKey, e as encodeKey, h as hasWatermark, r as removeWatermarks, s as sanitizeZeroWidth, a as stripWatermark, u as unwrap, w as wrapNextIntl, b as wrapTranslationEngine } from '../wrap-COvz8N3U.js';
+export { W as WrapOptions, d as decodeKey, e as encodeKey, h as hasWatermark, r as removeWatermarks, s as sanitizeZeroWidth, a as stripWatermark, u as unwrap, w as wrapNextIntl, b as wrapTranslationEngine } from '../wrap-BbTu7D0Q.js';
 
-type ClientMessageType = 'ELEMENT_SELECTED' | 'READY' | 'ERROR' | 'VISIBLE_KEYS_CHANGED' | 'VISIBLE_TEXTS_CHANGED' | 'LOCATION_CHANGED' | 'LEAVING';
-type StudioMessageType = 'APPLY_PREVIEW' | 'COMMIT_PREVIEW' | 'CLEAR_SELECTION' | 'NAVIGATE';
-/** A key on the page with the text it shows now; the Studio infers the page locale from these. */
+/**
+ * The messages the in-page client sends the Studio. The wire protocol is stable; this
+ * type is not, because new messages are added in minor releases.
+ *
+ * @internal Not part of the public API: semver does not cover it and it may change in any
+ * release. See https://livelocale.js.org/docs/reference/stability.html
+ */
+type ClientMessageType = 'ELEMENT_SELECTED' | 'READY' | 'ERROR' | 'VISIBLE_KEYS_CHANGED' | 'VISIBLE_TEXTS_CHANGED' | 'LOCATION_CHANGED' | 'LEAVING' | 'RENDERED_KEYS_CHANGED' | 'TAP_UNKEYED';
+/**
+ * The messages the Studio sends the in-page client.
+ *
+ * @internal Not part of the public API: semver does not cover it and it may change in any
+ * release. See https://livelocale.js.org/docs/reference/stability.html
+ */
+type StudioMessageType = 'APPLY_PREVIEW' | 'COMMIT_PREVIEW' | 'CLEAR_SELECTION' | 'NAVIGATE' | 'SET_EDIT_MODE' | 'SELECT_KEY' | 'REVEAL_KEY';
+/**
+ * A key on the page with the text it shows now; the Studio infers the page locale from these.
+ *
+ * @internal Not part of the public API: semver does not cover it and it may change in any
+ * release. See https://livelocale.js.org/docs/reference/stability.html
+ */
 interface VisibleText {
     key: string;
     text: string;
 }
+/**
+ * The ELEMENT_SELECTED payload.
+ *
+ * @internal Not part of the public API: semver does not cover it and it may change in any
+ * release. See https://livelocale.js.org/docs/reference/stability.html
+ */
 interface TranslationPayload {
     key: string;
     fallbackValue: string;
     currentValue: string;
 }
+/**
+ * The postMessage transport between the in-page client and the Studio.
+ *
+ * @internal Not part of the public API: semver does not cover it and it may change in any
+ * release. See https://livelocale.js.org/docs/reference/stability.html
+ */
 declare class IframeBridge {
     private allowedOrigin;
     constructor(allowedOrigin: string);
@@ -25,21 +55,32 @@ declare class IframeBridge {
     listenToParent(callback: (type: StudioMessageType, payload: any) => void): () => void;
 }
 
+/**
+ * The in-page engine the client starts on its own inside the Studio.
+ *
+ * @internal Not part of the public API: semver does not cover it and it may change in any
+ * release. See https://livelocale.js.org/docs/reference/stability.html
+ */
 declare class DOMInterceptor {
     private onElementSelected;
     private onVisibleKeysChanged?;
+    private onUnkeyedTap?;
     private hoveredElement;
     private observer;
     private inputSanitizersAttached;
     private overlay;
     private overlayBadge;
     private isAltHeld;
+    private editMode;
+    private active;
+    /** The element carrying `PICKED_ATTRIBUTE`, if any. */
+    private pickedElement;
     private broadcastVisibleKeys;
     constructor(onElementSelected: (payload: {
         key: string;
         fallbackValue: string;
         currentValue: string;
-    }) => void, onVisibleKeysChanged?: (keys: string[]) => void);
+    }) => void, onVisibleKeysChanged?: (keys: string[]) => void, onUnkeyedTap?: () => void);
     /**
      * Returns the unique set of translation keys currently visible in the DOM.
      */
@@ -53,6 +94,37 @@ declare class DOMInterceptor {
      * `limit` entries are returned.
      */
     getVisibleTexts(limit?: number): VisibleText[];
+    /**
+     * 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(): string[];
+    /** The first rendered, visible element carrying `key`, else `null`. */
+    private findRenderedElement;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string, bottomInset: number): void;
+    /**
+     * 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: boolean): void;
     /**
      * Initializes the DOM event interceptors in development mode.
      * Also launches the watermark scanner and MutationObserver.
@@ -63,6 +135,20 @@ declare class DOMInterceptor {
      * the floating overlay, and the form-sanitization listeners.
      */
     destroy(): void;
+    private attachEditMode;
+    private detachEditMode;
+    /** Moves the picked-text marker to `element`. */
+    private markPicked;
+    private clearPicked;
+    private stopFromSite;
+    private handleEditFocus;
+    /** Edit-mode click: cancelled whatever the target, then a selection or the notice. */
+    private handleEditClick;
+    /**
+     * 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.
+     */
+    private select;
     /**
      * Creates and injects a single floating overlay div into the document body.
      * The overlay is positioned using fixed coordinates from getBoundingClientRect()

package/dist/client/index.js

@@ -159,6 +159,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) {
@@ -202,6 +203,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";
@@ -256,7 +259,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)
@@ -279,7 +282,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",
@@ -331,9 +342,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;
@@ -342,11 +371,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());
@@ -394,6 +431,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.
@@ -418,6 +524,8 @@ var DOMInterceptor = class {
     this.scanSubtree(document.body);
     this.attachMutationObserver();
     this.attachInputSanitizers();
+    this.active = true;
+    if (this.editMode) this.attachEditMode();
     this.broadcastVisibleKeys();
   }
   /**
@@ -438,6 +546,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();
@@ -452,6 +562,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.
@@ -695,6 +886,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]");
@@ -723,6 +915,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;
@@ -732,15 +928,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() || "";
@@ -1001,16 +1189,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") {
@@ -1028,6 +1222,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__ = {