@livetemplate/client 0.11.5 → 0.11.7

package/dist/dom/directives.d.ts

@@ -153,4 +153,157 @@ export declare function setupToastClickOutside(): void;
  *   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;
+/**
+ * Apply url-hash directives. `lvt-fx:url-hash="<actionName>"` plus a
+ * `data-lvt-url-hash="<hash>"` attribute on an element (typically the
+ * `<body>`) wires a two-way bridge between server state and
+ * `location.hash`:
+ *
+ *  - **State → URL** (every render): if `data-lvt-url-hash` differs
+ *    from `location.hash`, mirror the data-attr into the URL via
+ *    `history.pushState` when the path component changed (everything
+ *    before the first `:`) or `history.replaceState` when only the
+ *    target (line range / anchor) changed. Replace is the right
+ *    default for line scrolls so the back-button cycles between files,
+ *    not between every clicked line.
+ *  - **URL → State** (on `hashchange` AND initial arm): dispatch
+ *    `{action: <actionName>, data: {hash: <hash>}}` so the server can
+ *    parse the hash and update its state (which then renders back as
+ *    a matching data-attr — closing the loop).
+ *
+ * The directive uses `history.pushState`/`replaceState` (not
+ * `location.hash = ...`) for the state→URL direction precisely so
+ * those writes do NOT fire `hashchange` — only true user-initiated
+ * navigation (anchor click, address-bar edit, back-button) reaches
+ * the URL→state listener. This avoids the obvious infinite loop.
+ *
+ * Idempotent across renders: same action → keep listener + update
+ * send. Different action → cleanup + re-arm. Detached / attribute-
+ * removed elements are swept on every call (same pattern as
+ * area-select). The window listener is registered on first arm and
+ * removed when the armed map becomes empty.
+ *
+ * Coexistence with `setupHashLink`: prereview-style hashes
+ * (`README.md:L4`, `foo/bar.html:h-anchor`) never match a
+ * `document.getElementById(...)`, so the existing dialog/popover/
+ * details hash machinery silently no-ops. If a deep-link hash
+ * happens to collide with an element id, both handlers will fire —
+ * the server is expected to no-op on hashes that don't resolve to a
+ * known file.
+ *
+ * **Pre-encoding contract**: `data-lvt-url-hash` must hold the hash
+ * value already in URL-encoded form. The directive writes the
+ * attribute verbatim into `history.pushState`/`replaceState`, so a
+ * value containing spaces, `[`, `]`, `%`, or other reserved
+ * characters needs to be percent-encoded by the server. The hash
+ * sent to the action on `hashchange` is also passed through unmodified
+ * (no decoding) — both directions are byte-exact mirrors of what's
+ * in `location.hash`.
+ *
+ * **URL/state divergence after a non-deep-link initial load**: if
+ * the user lands with a native-anchor hash (`#hero`) AND the server
+ * has a selected file, the directive leaves the URL on `#hero` (case
+ * b) — URL and server state diverge until the user navigates. This
+ * is intentional: popovers/anchors aren't ours to overwrite. The
+ * next user action that triggers a server render will re-sync only
+ * once URL and state share a deep-link hash.
+ *
+ * **Path-only deep links require an extension**: the
+ * `looksLikeDeepLinkHash` heuristic dispatches only hashes
+ * containing `:`, `/`, or `.`. Extension-less root files
+ * (`#Makefile`, `#Dockerfile`, `#LICENSE`) won't dispatch as
+ * path-only deep links — use the line form (`#Makefile:L1`)
+ * instead. The trade-off favours not clobbering native-anchor
+ * machinery for single-token hashes.
+ */
+export declare function handleURLHashDirective(rootElement: Element, send: (message: {
+    action: string;
+    data: Record<string, unknown>;
+}) => void): void;
+/**
+ * Cancel url-hash listeners for every armed element under root. Same
+ * lifecycle role as teardownAreaSelectForRoot.
+ */
+export declare function teardownURLHashForRoot(rootElement: Element): void;
+/**
+ * Test-only: reset the per-page dedupe Set that suppresses repeated
+ * `warnIfUnencodedHash` calls for the same hash value. Production
+ * code shouldn't need this — the Set is bounded by the number of
+ * unique malformed hashes — but tests that re-use the same hash
+ * across cases need to clear it or the second test won't see the
+ * warning. Mirrors `__resetAnimatedElementsForTesting`.
+ */
+export declare function __resetURLHashUnencodedWarnedForTesting(): 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;AAkFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAyGpE"}
+{"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;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,sBAAsB,CACpC,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,CAyFN;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CA0BjE;AAgFD;;;;;;;GAOG;AACH,wBAAgB,uCAAuC,IAAI,IAAI,CAE9D"}