@geckou/ui-core 0.3.0 → 0.4.0

package/README.md

@@ -81,6 +81,53 @@ store.getSnapshot() // { isAllValid: false, invalidNames: ['startedOn'] }
 - Vue: `FormValidationManager`（`@geckou/ui-vue`）
 - React: `useFormValidation`（`@geckou/ui-react`）
 
+### スクロールロック
+
+```ts
+import { createScrollLock } from '@geckou/ui-core'
+
+const lock = createScrollLock()
+lock.toggle(isOpen) // 真偽でロック・解除
+lock.release() // アンマウント時
+```
+
+モーダル表示中のページ全体のスクロールを止めます。1 コンポーネント 1 ハンドルを持ち、
+表示状態を `toggle()` に渡します。モーダルを重ねても解除順で壊れないよう内部でロック数を数え、
+最初のロックで元の値を控えて最後の解除で戻します。
+
+**スクロールバー幅を補正します。** バーが常時表示される環境（デスクトップの Windows / Linux 等）では
+`overflow: hidden` にした瞬間にバーの幅ぶん内容が横へずれるため、最初のロックで
+`window.innerWidth - document.documentElement.clientWidth` を `body` の `padding-right` に足し、
+最後の解除で元へ戻します（既存のインライン値があれば `calc()` で加算します）。
+
+利用側の CSS で `html { scrollbar-gutter: stable }` を指定している場合、
+この差は 0 になるので補正は入りません。固定配置の要素（追従ヘッダー等）も
+ずれないようにしたいときは `scrollbar-gutter` を使うほうが確実です。
+
+SSR（`document` が無い環境）では何もしません。
+
+### フォーカストラップ
+
+```ts
+import { handleTabKey, getFocusableElements } from '@geckou/ui-core'
+
+const onKeyDown = (event: KeyboardEvent) => {
+  handleTabKey(dialogElement, event, document.activeElement)
+}
+```
+
+`aria-modal="true"` を出していても、背景を `inert` にしていない限り Tab / Shift+Tab は
+ダイアログの外へ抜けます。`handleTabKey()` に `keydown` を渡すと、コンテナ内の
+フォーカス可能な要素の端で折り返します（末尾で Tab → 先頭、先頭で Shift+Tab → 末尾）。
+
+| 関数 | 説明 |
+|---|---|
+| `handleTabKey(container, event, activeElement?)` | Tab / Shift+Tab を端で折り返す。フォーカスを移して既定動作を止めたら `true` を返す。Tab 以外と `container` が無い場合は何もしない |
+| `getFocusableElements(container)` | コンテナ内のフォーカス可能な要素を DOM 順（= Tab 順）で返す。`inert` が付いたものは除く |
+| `FOCUSABLE_SELECTOR` | 上記で使うセレクタ（`tabindex="-1"` と `disabled` を除く） |
+
+`ModalBox`（Vue / React）はこれを使っています。
+
 ### 定数・型
 
 ```ts
@@ -92,6 +139,14 @@ import type { Validates, Option, StateVariation, DateObject } from '@geckou/ui-c
 
 型の一覧は [Vue パッケージの README](../vue/README.md#types) を参照してください。
 
+## 0.4.0 の変更
+
+- `focus-trap` を追加（`handleTabKey` / `getFocusableElements` / `FOCUSABLE_SELECTOR`）。
+  React / Vue の `ModalBox` が Tab の循環に使う
+- `scroll-lock` がロック時にスクロールバー幅を `padding-right` として補正する。
+  スクロールバーが常時表示される環境で、モーダルの開閉のたびにページが横へずれていた。
+  `body` の `padding-right` を自分で指定している場合は `calc()` で合成される
+
 ## テスト
 
 ```bash

package/dist/focus-trap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ダイアログ内にフォーカスを閉じ込める（フォーカストラップ）。
+ *
+ * `aria-modal="true"` を出していても、背景を `inert` にしていない限り
+ * Tab / Shift+Tab はダイアログの外の要素へ抜けていく。モーダルの必須要件なので、
+ * Vue / React どちらの ModalBox からも同じロジックを使う（scroll-lock と同じ配置）。
+ *
+ * 使い方は `keydown` を受けて `handleTabKey(container, event, document.activeElement)`
+ * に渡すだけ。Tab 以外のキーと、コンテナが無い場合は何もしない。
+ */
+/** フォーカス可能な要素のセレクタ。`tabindex="-1"` はプログラム用なので除く */
+export declare const FOCUSABLE_SELECTOR: string;
+/**
+ * DOM の型を要求しない（core をフレームワーク・実行環境から独立に保つため。
+ * lib に DOM を足さない）。実体は HTMLElement だが、必要な部分だけを構造的に受ける
+ */
+export type FocusableLike = {
+    focus: () => void;
+    hasAttribute?: (name: string) => boolean;
+};
+export type FocusTrapContainer = FocusableLike & {
+    querySelectorAll: (selectors: string) => ArrayLike<FocusableLike>;
+};
+export type FocusTrapEvent = {
+    key: string;
+    shiftKey: boolean;
+    preventDefault: () => void;
+};
+/**
+ * コンテナ内のフォーカス可能な要素を、DOM 順（= Tab 順）で返す。
+ * `inert` が付いた要素はフォーカスできないので除く
+ */
+export declare function getFocusableElements(container: FocusTrapContainer | null): FocusableLike[];
+/**
+ * Tab / Shift+Tab を受けて、コンテナの端で折り返す。
+ *
+ * @param container ダイアログ本体（`role="dialog"` の要素）
+ * @param event `keydown` のイベント
+ * @param activeElement 現在フォーカスされている要素（`document.activeElement`）
+ * @returns フォーカスを移動して既定動作を止めたなら `true`
+ */
+export declare function handleTabKey(container: FocusTrapContainer | null, event: FocusTrapEvent, activeElement?: unknown): boolean;

package/dist/focus-trap.js

@@ -0,0 +1,72 @@
+/**
+ * ダイアログ内にフォーカスを閉じ込める（フォーカストラップ）。
+ *
+ * `aria-modal="true"` を出していても、背景を `inert` にしていない限り
+ * Tab / Shift+Tab はダイアログの外の要素へ抜けていく。モーダルの必須要件なので、
+ * Vue / React どちらの ModalBox からも同じロジックを使う（scroll-lock と同じ配置）。
+ *
+ * 使い方は `keydown` を受けて `handleTabKey(container, event, document.activeElement)`
+ * に渡すだけ。Tab 以外のキーと、コンテナが無い場合は何もしない。
+ */
+/** フォーカス可能な要素のセレクタ。`tabindex="-1"` はプログラム用なので除く */
+export const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+/**
+ * コンテナ内のフォーカス可能な要素を、DOM 順（= Tab 順）で返す。
+ * `inert` が付いた要素はフォーカスできないので除く
+ */
+export function getFocusableElements(container) {
+    if (!container)
+        return [];
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((element) => !element.hasAttribute?.('inert'));
+}
+/**
+ * Tab / Shift+Tab を受けて、コンテナの端で折り返す。
+ *
+ * @param container ダイアログ本体（`role="dialog"` の要素）
+ * @param event `keydown` のイベント
+ * @param activeElement 現在フォーカスされている要素（`document.activeElement`）
+ * @returns フォーカスを移動して既定動作を止めたなら `true`
+ */
+export function handleTabKey(container, event, activeElement) {
+    if (event.key !== 'Tab' || !container)
+        return false;
+    const focusable = getFocusableElements(container);
+    if (focusable.length === 0) {
+        // フォーカスできる要素が無いなら、外へ抜けさせないために Tab ごと止める
+        event.preventDefault();
+        container.focus();
+        return true;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = activeElement;
+    const index = active ? focusable.indexOf(active) : -1;
+    // 開いた直後はダイアログ自身にフォーカスがある（tabindex="-1"）
+    const isContainerItself = active === container;
+    if (event.shiftKey) {
+        // 先頭・ダイアログ自身・トラップの外にいるなら末尾へ回す
+        if (index === 0 || isContainerItself || index === -1) {
+            event.preventDefault();
+            last.focus();
+            return true;
+        }
+        return false;
+    }
+    // ダイアログ自身からの Tab はブラウザ既定で先頭へ進むので触らない
+    if (isContainerItself)
+        return false;
+    // 末尾・トラップの外にいるなら先頭へ回す
+    if (index === -1 || index === focusable.length - 1) {
+        event.preventDefault();
+        first.focus();
+        return true;
+    }
+    return false;
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/scroll-lock.js

@@ -2,8 +2,14 @@
  * ページ全体のスクロールロック。
  *
  * モーダルを重ねても解除順で壊れないよう、ロック数をカウントする。
- * 最初のロックで元の `overflow` を控え、最後の解除で戻す
- * （無条件に `''` にすると、アプリ側が持っていたインラインの `overflow` が消える）。
+ * 最初のロックで元の `overflow` と `padding-right` を控え、最後の解除で戻す
+ * （無条件に `''` にすると、アプリ側が持っていたインラインの値が消える）。
+ *
+ * スクロールバーが常時表示される環境（デスクトップの Windows / Linux など）では、
+ * `overflow: hidden` にした瞬間にバーの幅ぶんページが広がって内容が横へずれる。
+ * 最初のロックでその幅を `padding-right` として足し、最後の解除で元へ戻す。
+ * 利用側の CSS で `html { scrollbar-gutter: stable }` を使っているならこの補正は
+ * 0px になる（`window.innerWidth` と `clientWidth` が一致するため）。
  *
  * 呼び出し側は 1 コンポーネント 1 ハンドルを持ち、表示状態を `toggle()` に渡して、
  * アンマウント時に `release()` する。同じハンドルから同じ状態を二度要求しても
@@ -11,10 +17,26 @@
  */
 let lockCount = 0;
 let previousOverflow = '';
+let previousPaddingRight = '';
+function getGlobal() {
+    return globalThis;
+}
 function getBody() {
     // SSR では document が無い（Nuxt / Next.js のサーバー側）
-    const doc = globalThis.document;
-    return doc?.body ?? null;
+    return getGlobal().document?.body ?? null;
+}
+/**
+ * 常時表示のスクロールバーが占めている幅。
+ * オーバーレイ表示（macOS の既定・モバイル）や `scrollbar-gutter: stable` では 0 になる。
+ */
+function getScrollbarWidth() {
+    const global = getGlobal();
+    const innerWidth = global.innerWidth;
+    const clientWidth = global.document?.documentElement?.clientWidth;
+    if (typeof innerWidth !== 'number' || typeof clientWidth !== 'number')
+        return 0;
+    const width = innerWidth - clientWidth;
+    return width > 0 ? width : 0;
 }
 export function createScrollLock() {
     let isLocked = false;
@@ -26,11 +48,20 @@ export function createScrollLock() {
         lockCount += shouldLock ? 1 : -1;
         if (lockCount === 1 && shouldLock) {
             previousOverflow = body.style.overflow;
+            previousPaddingRight = body.style.paddingRight;
             body.style.overflow = 'hidden';
+            const scrollbarWidth = getScrollbarWidth();
+            if (scrollbarWidth > 0) {
+                // 既にインラインの padding-right があれば単位が分からないので calc で足す
+                body.style.paddingRight = previousPaddingRight
+                    ? `calc(${previousPaddingRight} + ${scrollbarWidth}px)`
+                    : `${scrollbarWidth}px`;
+            }
         }
         else if (lockCount <= 0) {
             lockCount = 0;
             body.style.overflow = previousOverflow;
+            body.style.paddingRight = previousPaddingRight;
         }
     };
     return { toggle, release: () => toggle(false) };

package/package.json

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