@livetemplate/client 0.11.4 → 0.11.6

package/dist/dom/directives.d.ts

@@ -104,4 +104,125 @@ export declare function handleToastDirectives(rootElement: Element): void;
  * the user clicks outside the toast stack. Called once at connect time.
  */
 export declare function setupToastClickOutside(): void;
+/**
+ * Activate Declarative Shadow DOM for `<template shadowrootmode>` elements
+ * that the client inserted via DOM APIs (innerHTML setter, morphdom's
+ * createElement+appendChild path). The HTML parser activates declarative
+ * shadow roots only at parse time or via setHTMLUnsafe / parseHTMLUnsafe;
+ * a `<template shadowrootmode>` set via `.innerHTML = ...` is parked as a
+ * plain template with content but no attached shadow root. This sweep
+ * closes that gap so server-emitted shadow roots survive a client
+ * re-render.
+ *
+ * For each matching template found under rootElement:
+ *  - attach a shadow root on the parent (open by default; "closed" when
+ *    shadowrootmode="closed");
+ *  - move the template's content into the shadow root (replaceChildren
+ *    accepts a DocumentFragment and re-parents its children atomically,
+ *    so re-renders cleanly reset prior shadow content);
+ *  - remove the template.
+ *
+ * Hosts that can't accept a shadow root (a small fixed set: <input>,
+ * <textarea>, void elements, etc.) silently drop the template — better
+ * than an unhandled exception that kills the render.
+ *
+ * Closed-mode roots are tracked in a module-level WeakMap so re-renders
+ * can locate them (parent.shadowRoot returns null for closed roots).
+ *
+ * Idempotent: a re-run with no remaining templates is one qsa walk and
+ * an early return (sub-millisecond on hundreds-of-rows pages).
+ *
+ * Known limitations:
+ *
+ * - Nested DSD is inert on EVERY render, not just re-renders. A
+ *   `<template>`'s content lives in a DocumentFragment (`tpl.content`),
+ *   not in the light DOM, and `querySelectorAll` does not descend into
+ *   that fragment. So a `<template shadowrootmode>` nested inside
+ *   another `<template>` is never in the qsa result. Once the outer
+ *   shadow has been attached, the inner template ends up behind a
+ *   shadow boundary — still unreachable. The fix would be a recursive
+ *   sweep per new shadow root from within this loop.
+ *
+ * - Shadow-root options (`delegatesFocus`, `clonable`, `serializable`,
+ *   even `mode`) are fixed at first attach. A re-render that toggles
+ *   `shadowrootdelegatesfocus` on a host that already has a shadow root
+ *   won't change the existing root's focus behaviour — re-attach isn't
+ *   possible. Matches the HTML parser, which would have made the same
+ *   one-shot decision; if the server needs to flip these flags, it
+ *   needs to swap the host element entirely. The mode-mismatch case
+ *   also logs a console.warn so the divergence is visible.
+ */
+export declare function handleShadowRootHydration(rootElement: Element): void;
+/**
+ * Apply area-select directives. `lvt-fx:area-select="<actionName>"` on
+ * an element (typically an `<img>` inside a positioned parent) lets
+ * the user drag a rectangle locally — a `<div>` overlay tracks the
+ * gesture in real time without a server round-trip — and on
+ * `pointerup` dispatches a single livetemplate action with the final
+ * `{x, y, w, h}` as 0..1 fractions of the element's rendered bounding
+ * rect. The image's intrinsic dimensions don't matter for the
+ * fractions: any uniform scale (zoom, responsive layout) preserves
+ * the fraction. The consumer scales to pixels using the natural size
+ * if it needs them.
+ *
+ * Contract:
+ *  - Host's `parentElement` must establish a positioning context
+ *    (`position: relative` / `absolute` / `fixed`). The overlay is
+ *    `position: absolute` inside that parent so it follows the host
+ *    on scroll / reflow.
+ *  - Consumers usually pair this with `touch-action: none` on the
+ *    host so iOS Safari doesn't interpret the drag as a pinch/scroll.
+ *  - `<img>` and other natively-draggable hosts work automatically:
+ *    the directive calls `preventDefault()` on `dragstart` so the
+ *    browser's native drag (which would otherwise steal the gesture)
+ *    is suppressed.
+ *  - On pointer-cancel (e.g. system gesture, app switch), the overlay
+ *    is removed and no action is dispatched — same effect as cancelling
+ *    a click on `mouseleave`.
+ *  - Drags smaller than `MIN_AREA_FRACTION` in BOTH dimensions are
+ *    dropped — a click on the host still fires normal `click`
+ *    handlers via the compatibility mouse events.
+ *  - For text-bearing hosts, set `user-select: none` (the directive
+ *    deliberately does NOT call `preventDefault()` on `pointerdown`
+ *    so click handlers still receive the gesture; that means the
+ *    browser's default text-selection-on-drag behaviour also fires
+ *    unless the host opts out via CSS).
+ *  - The overlay uses `z-index: var(--lvt-area-select-z-index, 9999)`.
+ *    9999 is high enough for most use cases but can collide with
+ *    portals / modals / drawers that also sit at a high z-index.
+ *    Set `--lvt-area-select-z-index` on the host (or any ancestor)
+ *    to override. Color + fill follow the same pattern via
+ *    `--lvt-area-select-color` and `--lvt-area-select-fill`.
+ *  - **No keyboard equivalent.** Pointer-only by design (a keyboard-
+ *    selected rectangle requires a different UX — focus + arrow keys
+ *    to position + arrow keys to size). Consumers needing a11y for
+ *    area selection should provide a parallel form-based affordance.
+ *
+ * Idempotent across renders: an element re-armed with the same action
+ * keeps its existing listeners. A different action causes a tear-down
+ * and re-arm. Disconnected elements (and elements whose attribute was
+ * cleared by a server diff) get their listeners cleaned up by the
+ * sweep at the top of every call — we use a regular Map (not WeakMap)
+ * specifically so the sweep can iterate.
+ *
+ * Module-level singleton: `areaSelectArmed` is shared across all
+ * LiveTemplateClient instances in the same window. If two clients
+ * ever arm the same element with different actions, the second wins
+ * and the first client's send() is orphaned. Single-client use is
+ * unaffected.
+ */
+export declare function handleAreaSelectDirectives(rootElement: Element, send: (message: {
+    action: string;
+    data: Record<string, unknown>;
+}) => void): void;
+/**
+ * Cancel area-select listeners for every armed element under root.
+ * Mirrors teardownAutoClickTimers: meant for the client's disconnect /
+ * destroy lifecycle so the module-level singleton doesn't outlive a
+ * client that was torn down without a subsequent
+ * handleAreaSelectDirectives call (e.g. network error closed the
+ * socket while an element was armed). Without this, a SPA that mounts
+ * + tears down livetemplate trees would leak listeners across mounts.
+ */
+export declare function teardownAreaSelectForRoot(rootElement: Element): void;
 //# sourceMappingURL=directives.d.ts.map

package/dist/dom/directives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../dom/directives.ts"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iCAAiC,IAAI,IAAI,CAKxD;AAsBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CA0CvF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAWrE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAiBN;AAiLD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAiBpE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAUvE;AAaD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAMjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CA8FpE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAQlE;AAwCD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CA4BhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAW7C"}
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../dom/directives.ts"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iCAAiC,IAAI,IAAI,CAKxD;AAsBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CA0CvF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAWrE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,OAAO,EACpB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAiBN;AAiLD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAiBpE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAUvE;AAaD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAMjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CA8FpE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAQlE;AAwCD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CA4BhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAW7C;AAkFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAyGpE;AA4CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,OAAO,EACpB,IAAI,EAAE,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,KAAK,IAAI,GACzE,IAAI,CAyCN;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAQpE"}