help-layer 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Y1-Effy
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.ja.md

@@ -0,0 +1,217 @@
+# HelpLayer
+
+[![npm](https://img.shields.io/npm/v/help-layer.svg)](https://www.npmjs.com/package/help-layer)
+[![license](https://img.shields.io/npm/l/help-layer.svg)](./LICENSE)
+[![repo](https://img.shields.io/badge/GitHub-Y1--Effy%2FHelpLayer-181717?logo=github)](https://github.com/Y1-Effy/HelpLayer)
+
+[English](./README.md) | **日本語**
+
+既存の Web アプリに**後付けできる、フレームワーク非依存の「解説モード」ライブラリ**です。
+モード ON 中だけ対象要素の近くに「？」マーカーを出し、クリックで説明ポップアップを表示します。
+元アプリのイベントには一切触れず、透明な遮断レイヤーで操作を吸収するので、既存コードを書き換えずに導入できます。
+
+- 依存は [`@floating-ui/dom`](https://floating-ui.com/) のみ・軽量（プリビルドの IIFE で約 30KB / min、`@floating-ui/dom` 同梱）
+- Shadow DOM 貫通・SPA の動的要素・マーカー同士の重なり回避・画面端でのポップアップ自動調整に対応
+- ON→OFF で追加した DOM・イベント・スタイルを**完全後始末**
+
+## インストール
+
+```sh
+npm install help-layer
+```
+
+バンドラを使わず `<script>` 1本で導入したい場合は、プリビルドの IIFE を読み込めばグローバル `HelpLayer` が生えます（後述）。
+
+## クイックスタート
+
+### 1. config オブジェクトで定義する
+
+対象要素に `data-help-id` を付け、その値をキーにした説明を渡します。
+
+```html
+<button data-help-id="save">保存</button>
+<button id="help-toggle">解説モード</button>
+```
+
+```js
+import { initHelpLayer } from 'help-layer';
+
+initHelpLayer({
+  toggle: '#help-toggle',
+  config: {
+    save: { title: '保存', text: '入力内容を保存します。' },
+  },
+});
+```
+
+### 2. マークアップに直接書く（config なしでも可）
+
+説明をマークアップと同居させたい場合は、`data-help-title` / `data-help-text` を要素に直接書くだけで対象になります。
+`config` と併用でき、**同じキーが config にあれば config が優先**されます。
+
+```html
+<button data-help-title="保存" data-help-text="入力内容を保存します。">保存</button>
+```
+
+```js
+initHelpLayer({ toggle: '#help-toggle', config: {} });
+```
+
+### `<script>` だけで使う（バンドラなし）
+
+CDN から読む場合は、改ざん検知のため **バージョンを固定** し、**SRI（`integrity`）** を付けることを推奨します。
+
+```html
+<script
+  src="https://unpkg.com/help-layer@1.0.0/dist/help-layer.iife.js"
+  integrity="sha384-……（公開版のハッシュに差し替え）"
+  crossorigin="anonymous"></script>
+<script>
+  HelpLayer.initHelpLayer({
+    toggle: '#help-toggle',
+    config: { save: { title: '保存', text: '入力内容を保存します。' } },
+  });
+</script>
+```
+
+> `integrity` のハッシュは公開した実ファイルから生成します。例:
+> `curl -s https://unpkg.com/help-layer@1.0.0/dist/help-layer.iife.js | openssl dgst -sha384 -binary | openssl base64 -A`
+> （バージョンを固定しないと SRI と不整合になり読み込みが拒否されます。）
+
+## 自由配置（要素に紐づけない説明）
+
+`position` を指定すると、特定要素ではなくページ座標にマーカーを置けます（画面全体の説明などに）。
+
+```js
+config: {
+  intro: { title: 'この画面について', text: '…', position: { top: 80, left: 560 } },
+}
+```
+
+## API
+
+```js
+const help = initHelpLayer(options);
+help.enable();   // ON
+help.disable();  // OFF
+help.toggle();   // 反転
+help.isActive(); // boolean
+help.open(key);  // 指定キーの説明を開く（OFF 中なら自動で ON）
+help.close();    // 開いている説明を閉じる（モードは ON のまま）
+help.update(newConfig); // config を差し替え（ON 中なら無音で再構築。onEnable/onDisable は呼ばれない）
+help.destroy();  // リスナー解除＋完全後始末
+```
+
+### options
+
+| オプション | 型 | 既定 | 説明 |
+|------|------|------|------|
+| `config` | `object` | （必須） | キー→`{ title, text, position? }`。`data-help-id` 値 or 自由配置キー |
+| `toggle` | `string \| HTMLElement` | なし | ON/OFF するトグル要素。省略時は API 制御のみ |
+| `attribute` | `string` | `'data-help-id'` | 対象を示す属性名 |
+| `render` | `(record) => Node \| null` | なし | 本文を自前 DOM で描画。返り値が無ければ安全なテキスト表示にフォールバック（タイトルは常に `record.title`） |
+| `markerLabel` | `string` | `'?'` | マーカーに表示する文字 |
+| `markerPlacement` | `Placement` | `'top-end'` | マーカーを重ねる隅（`top-end`/`top-start`/`bottom-end`/`bottom-start`） |
+| `popupPlacement` | `Placement` | `'bottom-start'` | ポップアップ初期配置（画面端では自動で flip/shift） |
+| `nonce` | `string` | なし | 厳格な CSP（`style-src 'nonce-…'`）下で注入 `<style>` を許可するための nonce（後述） |
+| `silent` | `boolean` | `false` | 未登録キーの警告ログを抑止 |
+
+### コールバック
+
+| オプション | タイミング |
+|------|------|
+| `onEnable` | モードを ON にした直後 |
+| `onDisable` | モードを OFF にした直後 |
+| `onOpen(record)` | 説明ポップアップを開いた時 |
+| `onClose` | 説明ポップアップを閉じた時 |
+
+> ※ ON 中に説明を開いたまま `update()` / `disable()` / `destroy()` すると、後始末で説明が閉じるため `onClose` が一度発火します。
+
+### 本文に改行を入れる / リンクを置く
+
+本文は安全のため既定で `textContent`（HTML を解釈しない）ですが、`\n` は改行として表示されます。
+リンクや装飾が必要なら `render` で任意の DOM を返してください。
+
+```js
+initHelpLayer({
+  config,
+  render(record) {
+    if (record.key !== 'save') {
+      return null; // 既定のテキスト表示にフォールバック
+    }
+    const a = document.createElement('a');
+    a.href = '/docs/save';
+    a.textContent = 'くわしくはこちら';
+    return a;
+  },
+});
+```
+
+> ⚠️ **セキュリティ:** `render` が返した DOM は**そのまま挿入され、ライブラリ側ではサニタイズしません**。
+> ユーザー入力など未信頼のデータを使う場合は、`innerHTML` で組み立てず `textContent` を使うか、
+> [DOMPurify](https://github.com/cure53/DOMPurify) 等で無害化してから返してください（XSS 防止）。
+> 既定（`render` 未指定）の `title`/`text` 描画は `textContent` なので安全です。
+
+## テーマ（CSS カスタムプロパティ）
+
+見た目はホスト側 CSS で以下の変数を上書きするだけで変えられます。ダークモード（`prefers-color-scheme: dark`）の
+既定値も内蔵していますが、変数を指定すればそちらが常に優先されます。
+
+| 変数 | 既定 | 用途 |
+|------|------|------|
+| `--help-layer-marker-size` | `22px` | マーカー直径 |
+| `--help-layer-marker-bg` | `#2563eb` | マーカー背景色 |
+| `--help-layer-marker-color` | `#fff` | マーカー文字色 |
+| `--help-layer-popup-bg` | `#fff` | ポップアップ背景色 |
+| `--help-layer-popup-color` | `#1f2933` | ポップアップ文字色 |
+| `--help-layer-popup-max-width` | `280px` | ポップアップ最大幅 |
+| `--help-layer-popup-max-height` | `50vh` | ポップアップ本文の最大高さ（超過時は本文のみスクロール） |
+| `--help-layer-accent` | `#1d4ed8` | フォーカスリング色 |
+| `--help-layer-overlay-bg` | `transparent` | 遮断レイヤー（スクリム）背景色。`rgba(0,0,0,0.15)` 等で操作不能状態を可視化 |
+| `--help-layer-overlay-cursor` | `default` | 遮断領域上のカーソル。`not-allowed` / `help` 等 |
+
+## 既知の制約
+
+- closed な Shadow DOM は JS から到達できないため非対応（open のみ貫通）。
+- マーカーを隅へ重ねるオフセットは既定マーカーサイズ（22px）前提。`--help-layer-marker-size` を大きく変えると
+  わずかにズレることがあります。
+
+## セキュリティ
+
+- 設計上、`title` / `text` の描画は `textContent` のみで、`innerHTML` / `eval` / `new Function` は**一切使いません**。
+- 外部通信（`fetch` 等）・`localStorage` / `cookie` などのストレージ利用も**ありません**（完全ローカル動作）。
+- 唯一、未信頼データが DOM に届きうる経路は `render` オプションです。戻り値はサニタイズされないため、
+  ユーザー入力を含む場合は呼び出し側で無害化してください（上記「本文に改行を入れる / リンクを置く」参照）。
+- ランタイム依存は `@floating-ui/dom` のみ。CDN 利用時は前述のとおりバージョン固定＋SRI を推奨します。
+
+### Content Security Policy（CSP）
+
+本ライブラリは `innerHTML` / `eval` を使わないため **Trusted Types（`require-trusted-types-for 'script'`）に
+そのまま対応** しています。位置決めは要素の `.style`（CSSOM）への直接代入で行うため CSP の対象外です。
+
+一点だけ注意が必要なのは、見た目用に注入する **`<style>` タグ** です。`style-src` に `'unsafe-inline'` も
+nonce も無い**厳格な CSP** ではこの `<style>` がブロックされ、マーカーやポップアップのスタイルが当たりません。
+`style-src 'nonce-…'` 運用のサイトでは、リクエストごとの nonce を `nonce` オプションで渡してください。
+
+```js
+// サーバが毎リクエスト発行する nonce（CSP ヘッダの style-src 'nonce-xxxx' と同じ値）を渡す
+initHelpLayer({ config, toggle: '#help-toggle', nonce: pageNonce });
+```
+
+これで注入される `<style nonce="xxxx">` が CSP に許可され、厳格 CSP 下でも正しく表示されます。
+`'unsafe-inline'` を許可しているサイトや CSP 未設定のサイトでは `nonce` は不要です。
+
+## 開発
+
+| 目的 | コマンド |
+|------|----------|
+| テスト | `npm test` |
+| Lint / 型チェック / 一括 | `npm run lint` / `npm run typecheck` / `npm run check` |
+| デモ起動 | `npm run demo` |
+| 配布物ビルド | `npm run build`（`dist/` に ESM・IIFE・型定義） |
+
+## リポジトリ
+
+- ソース: <https://github.com/Y1-Effy/HelpLayer>
+- バグ報告・要望: <https://github.com/Y1-Effy/HelpLayer/issues>
+- ライセンス: [ISC](./LICENSE)

package/README.md

@@ -0,0 +1,218 @@
+# HelpLayer
+
+[![npm](https://img.shields.io/npm/v/help-layer.svg)](https://www.npmjs.com/package/help-layer)
+[![license](https://img.shields.io/npm/l/help-layer.svg)](./LICENSE)
+[![repo](https://img.shields.io/badge/GitHub-Y1--Effy%2FHelpLayer-181717?logo=github)](https://github.com/Y1-Effy/HelpLayer)
+
+**English** | [日本語](./README.ja.md)
+
+A **framework-agnostic "help mode" library you can drop into any existing web app**.
+While the mode is ON, it shows a "?" marker next to each target element; clicking it opens a description popup.
+It never touches the host app's own event listeners — a transparent blocking layer absorbs interaction instead — so you can adopt it without rewriting existing code.
+
+- Only one dependency, [`@floating-ui/dom`](https://floating-ui.com/); lightweight (the prebuilt IIFE is ~30KB minified, with `@floating-ui/dom` bundled in)
+- Pierces Shadow DOM, follows SPA dynamic elements, avoids marker-to-marker overlap, and auto-adjusts the popup at screen edges
+- Fully cleans up the DOM, listeners, and styles it added when you turn it OFF
+
+## Installation
+
+```sh
+npm install help-layer
+```
+
+If you'd rather drop it in with a single `<script>` and no bundler, load the prebuilt IIFE and a global `HelpLayer` is exposed (see below).
+
+## Quick start
+
+### 1. Define targets with a config object
+
+Add `data-help-id` to a target element and pass a description keyed by that value.
+
+```html
+<button data-help-id="save">Save</button>
+<button id="help-toggle">Help mode</button>
+```
+
+```js
+import { initHelpLayer } from 'help-layer';
+
+initHelpLayer({
+  toggle: '#help-toggle',
+  config: {
+    save: { title: 'Save', text: 'Saves your input.' },
+  },
+});
+```
+
+### 2. Write it inline in your markup (no config needed)
+
+If you'd rather keep descriptions next to your markup, just add `data-help-title` / `data-help-text` to an element and it becomes a target.
+This can be combined with `config`, and **if the same key exists in `config`, the config wins**.
+
+```html
+<button data-help-title="Save" data-help-text="Saves your input.">Save</button>
+```
+
+```js
+initHelpLayer({ toggle: '#help-toggle', config: {} });
+```
+
+### Use it with just a `<script>` (no bundler)
+
+When loading from a CDN, we recommend **pinning the version** and adding **SRI (`integrity`)** so tampering is detectable.
+
+```html
+<script
+  src="https://unpkg.com/help-layer@1.0.0/dist/help-layer.iife.js"
+  integrity="sha384-……(replace with the published file's hash)"
+  crossorigin="anonymous"></script>
+<script>
+  HelpLayer.initHelpLayer({
+    toggle: '#help-toggle',
+    config: { save: { title: 'Save', text: 'Saves your input.' } },
+  });
+</script>
+```
+
+> Generate the `integrity` hash from the actually published file, e.g.:
+> `curl -s https://unpkg.com/help-layer@1.0.0/dist/help-layer.iife.js | openssl dgst -sha384 -binary | openssl base64 -A`
+> (If you don't pin the version, the SRI will mismatch and the browser will refuse to load it.)
+
+## Free placement (descriptions not bound to an element)
+
+Specify `position` to place a marker at a page coordinate instead of on a specific element (useful for whole-screen descriptions, etc.).
+
+```js
+config: {
+  intro: { title: 'About this screen', text: '…', position: { top: 80, left: 560 } },
+}
+```
+
+## API
+
+```js
+const help = initHelpLayer(options);
+help.enable();   // ON
+help.disable();  // OFF
+help.toggle();   // flip ON/OFF
+help.isActive(); // boolean
+help.open(key);  // open the description for the given key (auto-enables if OFF)
+help.close();    // close the open description (the mode stays ON)
+help.update(newConfig); // replace the config (rebuilds silently if ON; onEnable/onDisable are not called)
+help.destroy();  // detach listeners + full cleanup
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|------|------|------|------|
+| `config` | `object` | (required) | key → `{ title, text, position? }`. The key is a `data-help-id` value or a free-placement key |
+| `toggle` | `string \| HTMLElement` | none | the toggle element that switches ON/OFF. If omitted, control is programmatic-only |
+| `attribute` | `string` | `'data-help-id'` | attribute name marking targets |
+| `render` | `(record) => Node \| null` | none | render the body with your own DOM. Falls back to safe text display when nothing is returned (the title is always `record.title`) |
+| `markerLabel` | `string` | `'?'` | the character shown on the marker |
+| `markerPlacement` | `Placement` | `'top-end'` | corner to overlap the marker onto (`top-end`/`top-start`/`bottom-end`/`bottom-start`) |
+| `popupPlacement` | `Placement` | `'bottom-start'` | initial popup placement (flips/shifts automatically at screen edges) |
+| `nonce` | `string` | none | nonce to allow the injected `<style>` under a strict CSP (`style-src 'nonce-…'`); see below |
+| `silent` | `boolean` | `false` | suppress the warning log for unregistered keys |
+
+### Callbacks
+
+| Option | When it fires |
+|------|------|
+| `onEnable` | right after the mode is turned ON |
+| `onDisable` | right after the mode is turned OFF |
+| `onOpen(record)` | when a description popup is opened |
+| `onClose` | when a description popup is closed |
+
+> Note: if a description is open when you call `update()` / `disable()` / `destroy()`, the cleanup closes it, so `onClose` fires once.
+
+### Line breaks & links in the body
+
+For safety the body is rendered with `textContent` by default (HTML is not interpreted), but `\n` is shown as a line break.
+If you need links or styling, return your own DOM from `render`.
+
+```js
+initHelpLayer({
+  config,
+  render(record) {
+    if (record.key !== 'save') {
+      return null; // fall back to the default text display
+    }
+    const a = document.createElement('a');
+    a.href = '/docs/save';
+    a.textContent = 'Learn more';
+    return a;
+  },
+});
+```
+
+> ⚠️ **Security:** the DOM returned by `render` is **inserted as-is and is not sanitized by the library**.
+> If you use untrusted data (e.g. user input), don't build it with `innerHTML` — use `textContent`, or
+> neutralize it with something like [DOMPurify](https://github.com/cure53/DOMPurify) before returning it (to prevent XSS).
+> The default (no `render`) `title`/`text` rendering uses `textContent`, so it is safe.
+
+## Theming (CSS custom properties)
+
+You can change the look just by overriding the following variables in your host CSS. Dark-mode defaults
+(`prefers-color-scheme: dark`) are built in, but any variable you set always wins via `var()`.
+
+| Variable | Default | Purpose |
+|------|------|------|
+| `--help-layer-marker-size` | `22px` | marker diameter |
+| `--help-layer-marker-bg` | `#2563eb` | marker background color |
+| `--help-layer-marker-color` | `#fff` | marker text color |
+| `--help-layer-popup-bg` | `#fff` | popup background color |
+| `--help-layer-popup-color` | `#1f2933` | popup text color |
+| `--help-layer-popup-max-width` | `280px` | popup max width |
+| `--help-layer-popup-max-height` | `50vh` | popup body max height (the body scrolls when exceeded) |
+| `--help-layer-accent` | `#1d4ed8` | focus ring color |
+| `--help-layer-overlay-bg` | `transparent` | blocking-layer (scrim) background; e.g. `rgba(0,0,0,0.15)` to signal the host is inactive |
+| `--help-layer-overlay-cursor` | `default` | cursor over the blocked area; e.g. `not-allowed` / `help` |
+
+## Known limitations
+
+- Closed Shadow DOM is unreachable from JS, so it is unsupported (only open shadow roots are pierced).
+- The offset that overlaps the marker onto a corner assumes the default marker size (22px). Changing
+  `--help-layer-marker-size` significantly may cause a slight drift.
+
+## Security
+
+- By design, `title` / `text` are rendered with `textContent` only; `innerHTML` / `eval` / `new Function` are **never used**.
+- There is **no external communication** (`fetch`, etc.) and **no storage use** (`localStorage` / `cookie`) — it runs fully locally.
+- The only path through which untrusted data could reach the DOM is the `render` option. Its return value is not sanitized, so
+  neutralize it on the caller side if it contains user input (see "Line breaks & links in the body" above).
+- The only runtime dependency is `@floating-ui/dom`. When using a CDN, pin the version and add SRI as noted above.
+
+### Content Security Policy (CSP)
+
+Because this library never uses `innerHTML` / `eval`, it **works as-is with Trusted Types
+(`require-trusted-types-for 'script'`)**. Positioning is done by assigning directly to an element's `.style` (CSSOM),
+which is outside the scope of CSP.
+
+The one thing to watch out for is the **`<style>` tag** injected for appearance. Under a **strict CSP** whose
+`style-src` has neither `'unsafe-inline'` nor a nonce, this `<style>` is blocked and the markers/popup get no styles.
+On sites that operate with `style-src 'nonce-…'`, pass the per-request nonce via the `nonce` option.
+
+```js
+// pass the nonce your server issues per request (the same value as `style-src 'nonce-xxxx'` in the CSP header)
+initHelpLayer({ config, toggle: '#help-toggle', nonce: pageNonce });
+```
+
+This lets the injected `<style nonce="xxxx">` be allowed by the CSP, so it renders correctly even under a strict CSP.
+On sites that allow `'unsafe-inline'` or have no CSP, `nonce` is not needed.
+
+## Development
+
+| Purpose | Command |
+|------|----------|
+| Test | `npm test` |
+| Lint / typecheck / all | `npm run lint` / `npm run typecheck` / `npm run check` |
+| Run the demo | `npm run demo` |
+| Build the distribution | `npm run build` (emits ESM, IIFE, and type definitions to `dist/`) |
+
+## Repository
+
+- Source: <https://github.com/Y1-Effy/HelpLayer>
+- Issues & requests: <https://github.com/Y1-Effy/HelpLayer/issues>
+- License: [ISC](./LICENSE)

package/dist/help-layer.esm.js

@@ -0,0 +1,139 @@
+var D="help-layer-popup-title";function z(){let e=document.createElement("div");return e.className="help-layer-blocking-layer",e}function B(e,t="?"){let n=document.createElement("button");return n.type="button",n.className="help-layer-marker",n.textContent=t,n.setAttribute("aria-label",`Help: ${e}`),n}function j(){let e=document.createElement("div");e.className="help-layer-popup",e.setAttribute("role","dialog"),e.setAttribute("aria-labelledby",D),e.tabIndex=-1;let t=document.createElement("div");t.className="help-layer-popup__title",t.id=D;let n=document.createElement("div");n.className="help-layer-popup__text";let r=document.createElement("button");return r.type="button",r.className="help-layer-popup__close",r.textContent="\xD7",r.setAttribute("aria-label","Close"),e.append(t,n,r),{root:e,titleEl:t,textEl:n,closeEl:r}}import{autoUpdate as P,computePosition as H,flip as ye,offset as K,shift as xe}from"@floating-ui/dom";function F(e,t){let n=e.width||0,r=e.height||0,o=e.left-t.x,i=e.top-t.y;return{x:o,y:i,left:o,top:i,right:o+n,bottom:i+r,width:n,height:r}}function q(e){return{contextElement:document.body,getBoundingClientRect(){return F(e(),{x:window.scrollX,y:window.scrollY})}}}function Z(e,t,n){e.style.left=`${t}px`,e.style.top=`${n}px`}var T=11;function ge(e){let t=e.endsWith("-start");return{mainAxis:-T,crossAxis:t?T:-T}}function G(e,t,n,r="top-end"){return P(e,t,()=>{H(e,t,{placement:r,middleware:[K(ge(r))]}).then(({x:i,y:p})=>{Z(t,i,p),n&&n()})},{animationFrame:!0})}function V(e,t,n="bottom-start"){let r=()=>{H(e,t,{placement:n,middleware:[K(8),ye({padding:8}),xe({padding:8})]}).then(({x:i,y:p})=>{Z(t,i,p)})},o=P(e,t,r,{animationFrame:!0});return{update:r,cleanup:o}}function U(e,t,n){return P(e,t,n)}function be(e){let t=e.left,n=e.top,r=e.right,o=e.bottom;return`polygon(
+    0px 0px, 100% 0px, 100% 100%, 0px 100%, 0px 0px,
+    ${t}px ${n}px, ${t}px ${o}px, ${r}px ${o}px, ${r}px ${n}px, ${t}px ${n}px
+  )`}function W(e,{toggleEl:t,onBackgroundClick:n,isLibraryElement:r,onEscape:o}){let i=z();if(document.body.appendChild(i),e.track(()=>i.remove()),t){let g=U(t,i,()=>{i.style.clipPath=be(t.getBoundingClientRect())});e.track(g)}n&&(i.addEventListener("click",n),e.track(()=>i.removeEventListener("click",n)));let p=document.activeElement;p instanceof HTMLElement&&p!==document.body&&p!==t&&p.blur();let h=c=>{r(c.target)||(c.stopPropagation(),t?t.focus({preventScroll:!0}):c.target instanceof HTMLElement&&c.target.blur())};document.addEventListener("focusin",h,!0),e.track(()=>document.removeEventListener("focusin",h,!0));let d=c=>{r(c.target)||(c.stopPropagation(),c.preventDefault())},y=c=>{if(c.key==="Escape"){c.stopPropagation(),c.preventDefault();return}d(c)},m=c=>{if(c.key==="Escape"){c.stopPropagation(),c.preventDefault(),o&&o();return}d(c)};return document.addEventListener("keydown",m,!0),document.addEventListener("keyup",y,!0),document.addEventListener("keypress",y,!0),e.track(()=>{document.removeEventListener("keydown",m,!0),document.removeEventListener("keyup",y,!0),document.removeEventListener("keypress",y,!0)}),i}function S(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function Y(e){return S(e)&&typeof e.top=="number"&&typeof e.left=="number"}function R(e){if(!S(e))throw new Error("helpConfig must be a plain object");for(let[t,n]of Object.entries(e)){if(!S(n))throw new Error(`helpConfig["${t}"] must be an object`);if(typeof n.title!="string"||n.title==="")throw new Error(`helpConfig["${t}"].title must be a non-empty string`);if(typeof n.text!="string"||n.text==="")throw new Error(`helpConfig["${t}"].text must be a non-empty string`);if(n.position!==void 0&&!Y(n.position))throw new Error(`helpConfig["${t}"].position must be { top: number, left: number }`)}}function X(e){return Object.entries(e).map(([t,n])=>Y(n.position)?{key:t,title:n.title,text:n.text,kind:"free",target:null,position:{top:n.position.top,left:n.position.left}}:{key:t,title:n.title,text:n.text,kind:"element",target:null,position:null})}function J(e,t={}){let n=t.minDistance??26,r=t.iterations??6,o=e.map(i=>({x:i.x,y:i.y}));for(let i=0;i<r;i++){let p=!1;for(let h=0;h<o.length;h++)for(let d=h+1;d<o.length;d++){let y=o[h],m=o[d],c=m.x-y.x,g=m.y-y.y,s=Math.hypot(c,g);if(s>=n)continue;s===0&&(c=1,g=0,s=1);let l=(n-s)/2,f=c/s,a=g/s;y.x-=f*l,y.y-=a*l,m.x+=f*l,m.y+=a*l,p=!0}if(!p)break}return o.map((i,p)=>({dx:i.x-e[p].x,dy:i.y-e[p].y}))}var Q="help-layer-target-highlight";function ve(e){return e.kind==="free"?q(()=>({top:e.position.top,left:e.position.left,width:0,height:0})):e.target}function ee(e,{onMarkerClick:t,onOverlapResolved:n,markerLabel:r="?",markerPlacement:o="top-end"}){let i=new Map,p=null,h=!1;function d(){p=null;let s=[...i.values()];if(s.length<=1){let a=s.length===1?s[0].el:null;a&&a.style.transform&&(a.style.transform="",n&&n());return}s.forEach(a=>{a.el.style.transform=""});let l=s.map(a=>{let u=a.el.getBoundingClientRect();return{x:u.left+u.width/2,y:u.top+u.height/2}}),f=J(l);s.forEach((a,u)=>{let{dx:b,dy:v}=f[u];a.el.style.transform=b||v?`translate(${b}px, ${v}px)`:""}),n&&n()}function y(){p!==null||h||(p=requestAnimationFrame(d))}function m(s){if(i.has(s.id))return;let l=B(s.title,r);document.body.appendChild(l);let f=()=>t(s,l);l.addEventListener("click",f);let a=G(ve(s),l,y,o),u=s.kind==="element"?s.target:null,b=()=>u&&u.classList.add(Q),v=()=>u&&u.classList.remove(Q);u&&(l.addEventListener("mouseenter",b),l.addEventListener("mouseleave",v),l.addEventListener("focus",b),l.addEventListener("blur",v));let w=!1,L=()=>{w||(w=!0,a(),l.removeEventListener("click",f),u&&(l.removeEventListener("mouseenter",b),l.removeEventListener("mouseleave",v),l.removeEventListener("focus",b),l.removeEventListener("blur",v),v()),l.remove(),i.delete(s.id),y())};i.set(s.id,{record:s,el:l,cleanup:L})}function c(s){let l=i.get(s);l&&l.cleanup()}function g(s){s.forEach(m)}return e.track(()=>{h=!0,p!==null&&(cancelAnimationFrame(p),p=null),[...i.values()].forEach(s=>s.cleanup())}),{mount:m,unmount:c,mountAll:g,has(s){return i.has(s)},findByKey(s){for(let l of i.values())if(l.record.key===s)return l;return null}}}function A(e,t,n,r){typeof e.querySelectorAll=="function"&&e.querySelectorAll("*").forEach(o=>{n&&o.matches(t)&&n(o),o.shadowRoot&&(r&&r(o.shadowRoot),A(o.shadowRoot,t,n,r))})}function ne(e,t){let n=[];return A(e,t,r=>n.push(r)),n}function ke(e){let t=[];return A(e,"*",null,n=>t.push(n)),t}function te(e,t){let n=[],r=[];if(e.nodeType!==1)return{matches:n,shadowRoots:r};let o=e;return typeof o.matches=="function"&&o.matches(t)&&n.push(o),o.shadowRoot&&(r.push(o.shadowRoot),A(o.shadowRoot,t,i=>n.push(i),i=>r.push(i))),A(o,t,i=>n.push(i),i=>r.push(i)),{matches:n,shadowRoots:r}}function oe({root:e=document,selector:t,onAdded:n,onRemoved:r}){let o=new Set,i=d=>{for(let y of d)y.addedNodes.forEach(m=>{let{matches:c,shadowRoots:g}=te(m,t);c.forEach(s=>n(s)),g.forEach(h)}),y.removedNodes.forEach(m=>{te(m,t).matches.forEach(c=>r(c))})},p=new MutationObserver(i);function h(d){o.has(d)||(o.add(d),p.observe(d,{childList:!0,subtree:!0}))}return h(e),ke(e).forEach(h),{disconnect(){p.disconnect(),o.clear()}}}var _="data-help-title",M="data-help-text";function O(e="data-help-id"){return`[${e}], [${_}]`}function N(e){let t=new Map;for(let n of e)n.kind==="element"&&t.set(n.key,n);return t}function re(e){return e.filter(t=>t.kind==="free").map(t=>({id:t.key,kind:"free",key:t.key,title:t.title,text:t.text,position:t.position}))}function I(e,t,n="data-help-id"){let r=e.getAttribute(n),o=r!=null?t.get(r):void 0,i=o?o.title:e.getAttribute(_),p=o?o.text:e.getAttribute(M);return!i||!p?null:{id:e,kind:"element",key:r,title:i,text:p,target:e}}function ie(e,t=document,{silent:n=!1,attribute:r="data-help-id"}={}){let o=N(e),i=[];return ne(t,O(r)).forEach(p=>{let h=I(p,o,r);if(!h){if(!n){let d=p.getAttribute(r);console.warn(d!=null?`[help-layer] element with ${r}="${d}" has no matching helpConfig entry or inline ${_}/${M}`:`[help-layer] element needs both ${_} and ${M} (or a ${r} matching helpConfig)`)}return}i.push(h)}),i}function le(e,{onClose:t,render:n,popupPlacement:r="bottom-start"}={}){let{root:o,titleEl:i,textEl:p,closeEl:h}=j();document.body.appendChild(o),h.addEventListener("click",()=>f());let d=null,y=null,m=null;function c(){m&&(m.cleanup(),m=null)}function g(a,u){i.textContent=a.title;let b=n?n(a):null;p.textContent="",b?p.appendChild(b):p.textContent=a.text,o.style.display="block",d=a.id,y=u,c(),m=V(u,o,r),o.focus({preventScroll:!0})}function s(){m&&m.update()}function l(){let a=d!==null;c(),d=null,y=null,o.style.display="none",a&&t&&t()}function f(a){let u=a??y;l(),u&&u.isConnected&&typeof u.focus=="function"&&u.focus({preventScroll:!0})}return e.track(()=>{l(),o.remove()}),{root:o,isOpen(a){return d===a},getOpenId(){return d},open:g,close:f,reposition:s}}function ae(){let e=[];return{track(t){e.push(t)},teardownAll(){for(;e.length>0;)e.pop()()}}}var Ee="data-help-layer-style",we=`
+.help-layer-blocking-layer {
+  position: fixed;
+  inset: 0;
+  /* Default transparent (unchanged). Set --help-layer-overlay-bg to tint it into a scrim that signals
+     "the host app is inactive". The clip-path hole isn't painted, so the toggle stays untinted. */
+  background: var(--help-layer-overlay-bg, transparent);
+  /* Cursor over the blocked area only (the toggle shows through the hole and keeps its own cursor).
+     e.g. not-allowed / help makes "this won't respond" obvious without needing a tint. */
+  cursor: var(--help-layer-overlay-cursor, default);
+  z-index: 2147483000;
+}
+
+.help-layer-marker {
+  /* reset of the button element */
+  appearance: none;
+  -webkit-appearance: none;
+  margin: 0;
+  padding: 0;
+  border: none;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--help-layer-marker-size, 22px);
+  height: var(--help-layer-marker-size, 22px);
+  border-radius: 50%;
+  background: var(--help-layer-marker-bg, #2563eb);
+  color: var(--help-layer-marker-color, #fff);
+  font-family: sans-serif;
+  font-size: 13px;
+  font-weight: bold;
+  line-height: var(--help-layer-marker-size, 22px);
+  text-align: center;
+  cursor: pointer;
+  user-select: none;
+  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.35);
+  z-index: 2147483001;
+}
+
+.help-layer-marker:focus-visible {
+  outline: 3px solid var(--help-layer-accent, #1d4ed8);
+  outline-offset: 2px;
+}
+
+.help-layer-popup {
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: none;
+  max-width: var(--help-layer-popup-max-width, 280px);
+  background: var(--help-layer-popup-bg, #fff);
+  color: var(--help-layer-popup-color, #1f2933);
+  border-radius: 6px;
+  padding: 12px 14px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+  font-family: sans-serif;
+  font-size: 13px;
+  line-height: 1.5;
+  z-index: 2147483002;
+}
+
+.help-layer-popup:focus {
+  outline: none;
+}
+
+.help-layer-popup:focus-visible {
+  outline: 3px solid var(--help-layer-accent, #1d4ed8);
+  outline-offset: 2px;
+}
+
+.help-layer-popup__title {
+  font-weight: bold;
+  margin-bottom: 4px;
+  /* Reserve space so it doesn't overlap the \xD7 button at the top-right. */
+  padding-right: 16px;
+}
+
+.help-layer-popup__text {
+  /* Render the body's 
+ as line breaks (still textContent, so no XSS risk). */
+  white-space: pre-line;
+  /* Keep long text from spilling off-screen; only the body scrolls within the popup. */
+  max-height: var(--help-layer-popup-max-height, 50vh);
+  overflow-y: auto;
+}
+
+.help-layer-popup__close {
+  /* reset of the button element */
+  appearance: none;
+  -webkit-appearance: none;
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: none;
+  border-radius: 4px;
+  background: transparent;
+  color: inherit;
+  font-size: 16px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.help-layer-popup__close:hover {
+  background: rgba(0, 0, 0, 0.08);
+}
+
+.help-layer-popup__close:focus-visible {
+  outline: 2px solid var(--help-layer-accent, #1d4ed8);
+  outline-offset: 1px;
+}
+
+/*
+ * Show an outline on the target element only while the marker is hovered/focused (clarifies "which element this explains").
+ * Make only the outline !important so it can beat host-side outline resets.
+ */
+.help-layer-target-highlight {
+  outline: 2px solid var(--help-layer-accent, #1d4ed8) !important;
+  outline-offset: 2px !important;
+}
+
+/*
+ * Dark-mode defaults. If the user specifies CSS variables, those always win via var(), so here we
+ * only swap the dark fallback values (the properties themselves aren't re-declared).
+ */
+@media (prefers-color-scheme: dark) {
+  .help-layer-popup {
+    background: var(--help-layer-popup-bg, #1f2933);
+    color: var(--help-layer-popup-color, #e5e7eb);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.55);
+  }
+}
+`;function se(e){let t=document.createElement("style");return t.setAttribute(Ee,""),e&&t.setAttribute("nonce",e),t.textContent=we,document.head.appendChild(t),t}function pe(e){e.remove()}function Le(e){let t=typeof e=="string"?document.querySelector(e):e;if(!t)throw new Error(`help-layer: toggle element not found for selector "${e}"`);return t}function ce({config:e,toggle:t,onEnable:n,onDisable:r,onOpen:o,onClose:i,silent:p=!1,attribute:h="data-help-id",render:d,markerLabel:y="?",markerPlacement:m="top-end",popupPlacement:c="bottom-start",nonce:g}){let s=e;R(s);let l=t!=null?Le(t):null,f=null,a=null,u=null;function b(){if(f)return;f=ae(),l&&f.track(()=>{l.isConnected&&typeof l.focus=="function"&&l.focus({preventScroll:!0})});let E=se(g);f.track(()=>pe(E));let k=X(s),he=N(k);a=le(f,{onClose:i,render:d,popupPlacement:c}),u=ee(f,{markerLabel:y,markerPlacement:m,onMarkerClick:(x,C)=>{if(a.isOpen(x.id)){a.close();return}a.open(x,C),o&&o(x)},onOverlapResolved:()=>a.reposition()}),u.mountAll(re(k)),u.mountAll(ie(k,document,{silent:p,attribute:h}));let me=oe({selector:O(h),onAdded:x=>{let C=I(x,he,h);C&&!u.has(C.id)&&u.mount(C)},onRemoved:x=>{a.isOpen(x)&&a.close(l??void 0),u.unmount(x)}});f.track(()=>me.disconnect()),W(f,{toggleEl:l,onBackgroundClick:()=>a.close(),isLibraryElement:x=>!!x&&((l?l.contains(x):!1)||a.root.contains(x)||typeof x.closest=="function"&&!!x.closest(".help-layer-marker")),onEscape:()=>{a.getOpenId()!==null?a.close():L()}})}function v(){f&&(f.teardownAll(),f=null,a=null,u=null)}function w(){f||(b(),n&&n())}function L(){f&&(v(),r&&r())}function $(){f?L():w()}function ue(E){if(f||w(),!u||!a)return;let k=u.findByKey(E);if(!k){p||console.warn(`[help-layer] open(): no help marker for key "${E}"`);return}a.open(k.record,k.el),o&&o(k.record)}function fe(){a&&a.close()}function de(E){R(E),s=E,f&&(v(),b())}return l&&l.addEventListener("click",$),{enable:w,disable:L,toggle:$,isActive(){return f!==null},open:ue,close:fe,update:de,destroy(){L(),l&&l.removeEventListener("click",$)}}}function rt(e){return ce(e)}export{rt as initHelpLayer};
+//# sourceMappingURL=help-layer.esm.js.map