@geckou/ui-core 0.4.0 → 0.6.0

package/README.md

@@ -128,6 +128,36 @@ const onKeyDown = (event: KeyboardEvent) => {
 
 `ModalBox`（Vue / React）はこれを使っています。
 
+### モーダルの重なり順
+
+```ts
+import { createModalLayer } from '@geckou/ui-core'
+
+const layer = createModalLayer()
+layer.toggle(isOpen, dialogElement) // 表示状態と、判定に使う要素（要素は必須）
+layer.isTopmost() // キー入力を処理してよいのは true のときだけ
+layer.release() // アンマウント時
+```
+
+モーダルを重ねたとき、Escape や Tab を処理してよいのは最前面の 1 枚だけです。
+`ModalBox` はハンドラを `document` に bubble で登録するため、重なると全部が同じ
+イベントを受け取ります。実行順は DOM の深さではなく登録順で決まる（React は
+`onClose` の同一性が変わると再登録され、effect は子から先に走る）ので、
+順序には頼れません。
+
+判定の決め手は **DOM の包含関係**です。入れ子のモーダルは内側が外側の中に
+描画されるので、他のレイヤーを内包しているものは外側だと分かります。
+互いに内包しない（入れ子でない）モーダルが並んだときだけ、後から開いたものを
+最前面とします。
+
+| メソッド | 説明 |
+|---|---|
+| `toggle(shouldBeActive, element)` | 真偽で登録・解除する。`element` は最前面判定に使う要素（ダイアログ本体）。省略可にすると要素の無いレイヤーが積まれて包含判定が効かなくなるため必須（未取得なら明示的に `null`） |
+| `isTopmost()` | このレイヤーが最前面か。登録していなければ `false` |
+| `release()` | アンマウント時に呼ぶ。登録中なら解除する |
+
+`ModalBox`（Vue / React）はこれを使っています。
+
 ### 定数・型
 
 ```ts
@@ -139,6 +169,11 @@ import type { Validates, Option, StateVariation, DateObject } from '@geckou/ui-c
 
 型の一覧は [Vue パッケージの README](../vue/README.md#types) を参照してください。
 
+## 0.6.0 の変更
+
+- `modal-stack` を追加（`createModalLayer`）。重なったモーダルのうち最前面の 1 枚を
+  DOM の包含関係で決める。React / Vue の `ModalBox` が Escape / Tab の担当判定に使う
+
 ## 0.4.0 の変更
 
 - `focus-trap` を追加（`handleTabKey` / `getFocusableElements` / `FOCUSABLE_SELECTOR`）。

package/dist/focus-trap.d.ts

@@ -17,6 +17,9 @@ export declare const FOCUSABLE_SELECTOR: string;
 export type FocusableLike = {
     focus: () => void;
     hasAttribute?: (name: string) => boolean;
+    closest?: (selectors: string) => unknown;
+    matches?: (selectors: string) => boolean;
+    checkVisibility?: () => boolean;
 };
 export type FocusTrapContainer = FocusableLike & {
     querySelectorAll: (selectors: string) => ArrayLike<FocusableLike>;
@@ -28,7 +31,18 @@ export type FocusTrapEvent = {
 };
 /**
  * コンテナ内のフォーカス可能な要素を、DOM 順（= Tab 順）で返す。
- * `inert` が付いた要素はフォーカスできないので除く
+ *
+ * セレクタだけでは「実際にはフォーカスできない要素」が混ざる。
+ * 混ざると端の要素が no-op になって Tab が止まるか、preventDefault を挟んだ後に
+ * ブラウザ既定の移動が起きてダイアログの外へ抜けるため、ここで落とす。
+ *
+ * - `inert` 配下（閉じた SlideDownUi / DropdownUi の中身）。自身の属性だけでは足りない
+ * - `<fieldset disabled>` 配下（`:disabled` は継承する。`:not([disabled])` では消せない）
+ * - `display: none` で描画されていないもの（`hidden` な TabUI のパネルの中身など）。
+ *   引数なしの `checkVisibility()` は `visibility: hidden` / `opacity: 0` は落とさない
+ *
+ * `closest` / `matches` / `checkVisibility` は任意（`FocusableLike` は DOM 型を
+ * 要求しない）。持たない実装では従来どおりの結果になる
  */
 export declare function getFocusableElements(container: FocusTrapContainer | null): FocusableLike[];
 /**

package/dist/focus-trap.js

@@ -19,12 +19,28 @@ export const FOCUSABLE_SELECTOR = [
 ].join(', ');
 /**
  * コンテナ内のフォーカス可能な要素を、DOM 順（= Tab 順）で返す。
- * `inert` が付いた要素はフォーカスできないので除く
+ *
+ * セレクタだけでは「実際にはフォーカスできない要素」が混ざる。
+ * 混ざると端の要素が no-op になって Tab が止まるか、preventDefault を挟んだ後に
+ * ブラウザ既定の移動が起きてダイアログの外へ抜けるため、ここで落とす。
+ *
+ * - `inert` 配下（閉じた SlideDownUi / DropdownUi の中身）。自身の属性だけでは足りない
+ * - `<fieldset disabled>` 配下（`:disabled` は継承する。`:not([disabled])` では消せない）
+ * - `display: none` で描画されていないもの（`hidden` な TabUI のパネルの中身など）。
+ *   引数なしの `checkVisibility()` は `visibility: hidden` / `opacity: 0` は落とさない
+ *
+ * `closest` / `matches` / `checkVisibility` は任意（`FocusableLike` は DOM 型を
+ * 要求しない）。持たない実装では従来どおりの結果になる
  */
 export function getFocusableElements(container) {
     if (!container)
         return [];
-    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((element) => !element.hasAttribute?.('inert'));
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((element) => 
+    // closest を持たない実装のために、自身の inert も見る（DOM では冗長）
+    !element.hasAttribute?.('inert') &&
+        !element.closest?.('[inert]') &&
+        !element.matches?.(':disabled') &&
+        (element.checkVisibility?.() ?? true));
 }
 /**
  * Tab / Shift+Tab を受けて、コンテナの端で折り返す。

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from './text.js';
 export * from './form-validation-store.js';
 export * from './scroll-lock.js';
 export * from './focus-trap.js';
+export * from './modal-stack.js';

package/dist/index.js

@@ -6,3 +6,4 @@ export * from './text.js';
 export * from './form-validation-store.js';
 export * from './scroll-lock.js';
 export * from './focus-trap.js';
+export * from './modal-stack.js';

package/dist/modal-stack.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 開いているモーダルの重なり順。
+ *
+ * ModalBox は Escape / Tab のハンドラを `document` に bubble で登録するため、
+ * モーダルを重ねると全部のハンドラが同じイベントを受け取る。実行順は DOM の
+ * 深さではなく登録順で決まる（React は onClose の同一性が変わると再登録されて
+ * 順序が入れ替わり、React の effect は子から先に走る）ので、順序には頼れない。
+ *
+ * そこで「誰が最前面か」をここで判定する。決め手は DOM の包含関係。
+ * 入れ子のモーダルは内側が外側の中に描画されるので、他のレイヤーを内包している
+ * ものは外側だと分かる。互いに内包しない（入れ子でない）モーダルが並んだときだけ、
+ * 後から開いたものを最前面とする。
+ *
+ * 呼び出し側は 1 コンポーネント 1 ハンドルを持ち、表示状態と自分の要素を
+ * `toggle()` に渡して、アンマウント時に `release()` する。
+ */
+/**
+ * 包含判定しか使わないので、DOM の型は要求しない
+ * （core をフレームワーク・実行環境から独立に保つため。lib に DOM を足さない）。
+ * メソッド記法なので引数は双変になり、`HTMLElement` をそのまま渡せる
+ */
+type ElementLike = {
+    contains(other: ElementLike | null): boolean;
+};
+export type ModalLayer = {
+    /**
+     * 引数の真偽で登録・解除を切り替える。
+     * `element` には最前面判定に使う要素（ダイアログ本体）を渡す。
+     * 省略可にすると `toggle(true)` だけで要素の無いレイヤーが積まれ、
+     * 包含判定が効かなくなるので必須にしている（未取得なら明示的に null）
+     */
+    toggle: (shouldBeActive: boolean, element: ElementLike | null) => void;
+    /** このレイヤーが最前面か。キーイベントを処理してよいのは true のときだけ */
+    isTopmost: () => boolean;
+    /** アンマウント時に呼ぶ。登録中なら解除する */
+    release: () => void;
+};
+export declare function createModalLayer(): ModalLayer;
+export {};

package/dist/modal-stack.js

@@ -0,0 +1,46 @@
+/**
+ * 開いているモーダルの重なり順。
+ *
+ * ModalBox は Escape / Tab のハンドラを `document` に bubble で登録するため、
+ * モーダルを重ねると全部のハンドラが同じイベントを受け取る。実行順は DOM の
+ * 深さではなく登録順で決まる（React は onClose の同一性が変わると再登録されて
+ * 順序が入れ替わり、React の effect は子から先に走る）ので、順序には頼れない。
+ *
+ * そこで「誰が最前面か」をここで判定する。決め手は DOM の包含関係。
+ * 入れ子のモーダルは内側が外側の中に描画されるので、他のレイヤーを内包している
+ * ものは外側だと分かる。互いに内包しない（入れ子でない）モーダルが並んだときだけ、
+ * 後から開いたものを最前面とする。
+ *
+ * 呼び出し側は 1 コンポーネント 1 ハンドルを持ち、表示状態と自分の要素を
+ * `toggle()` に渡して、アンマウント時に `release()` する。
+ */
+const layers = [];
+function contains(layer, other) {
+    return Boolean(layer.element && other.element && layer.element.contains(other.element));
+}
+export function createModalLayer() {
+    const layer = { element: null };
+    let isActive = false;
+    const toggle = (shouldBeActive, element) => {
+        // 要素は再描画で差し替わりうるので、状態が変わらなくても取り直す
+        layer.element = shouldBeActive ? element : null;
+        if (isActive === shouldBeActive)
+            return;
+        isActive = shouldBeActive;
+        if (shouldBeActive) {
+            layers.push(layer);
+            return;
+        }
+        const index = layers.lastIndexOf(layer);
+        if (index >= 0)
+            layers.splice(index, 1);
+    };
+    const isTopmost = () => {
+        if (!isActive)
+            return false;
+        // 他のレイヤーを内包しているものは「外側」なので候補から外す
+        const innermost = layers.filter((candidate) => !layers.some((other) => other !== candidate && contains(candidate, other)));
+        return innermost[innermost.length - 1] === layer;
+    };
+    return { toggle, isTopmost, release: () => toggle(false, null) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geckou/ui-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Framework-agnostic logic shared by @geckou/ui-vue and @geckou/ui-react",
   "type": "module",
   "main": "dist/index.js",