@joewinke/jatui 0.55.0 → 0.57.0

package/dist/utils/dialogFocus.js

@@ -0,0 +1,153 @@
+/**
+ * Dialog focus resolution (jatui-fo6o8)
+ *
+ * Shared rule for every surface that opens an overlay dialog/panel
+ * (Modal, Drawer, BottomSheet, Confirm*, InputDialog): on open, focus in
+ * this order —
+ *
+ *   1. an element with [data-autofocus] or the `autofocus` attribute inside
+ *      the container (a consumer's explicit opt-in);
+ *   2. else the first ENABLED, RENDERED text-entry control in the body
+ *      (not the header close button — buttons never qualify anyway): a
+ *      text-like <input>, an enabled <textarea>, or a contenteditable
+ *      element;
+ *   3. else the container element itself (today's behaviour — keeps Escape
+ *      working for read-only / confirm dialogs, see Modal's Escape note).
+ *
+ * "Rendered" matters: a focus() on an element that is not actually visible
+ * (display:none, inside a collapsed <details>, a [hidden]/[inert] ancestor,
+ * or visibility:hidden) is a silent no-op that leaves focus on <body>, which
+ * breaks the dialog's own Escape handling (Modal owns Escape on the dialog
+ * element). Unrendered candidates are skipped, and after focusing the target
+ * is verified to actually hold focus — else the fallback/container is
+ * focused instead.
+ *
+ * WAI-ARIA APG dialog pattern: focus the first field the user is expected
+ * to fill. `initialFocus` overrides the whole order —
+ *
+ *   - `HTMLElement` / `string` (a CSS selector, resolved inside the
+ *     container): focus exactly that; falls through to the default order
+ *     when the selector matches nothing.
+ *   - `'dialog'`: always focus the container (old behaviour — right for
+ *     read-only / confirm dialogs).
+ *   - `'first-input'` (default): the 1→2→3 order above.
+ */
+const TEXT_INPUT_TYPES = new Set([
+    'text',
+    'search',
+    'url',
+    'tel',
+    'email',
+    'password',
+    'number',
+    '',
+    undefined
+]);
+/** True for an element a user can type into: text-like input, enabled textarea, contenteditable. */
+export function isTextEntryControl(el) {
+    if (el instanceof HTMLTextAreaElement) {
+        if (el.disabled || el.readOnly)
+            return false;
+        return true;
+    }
+    if (el instanceof HTMLInputElement) {
+        if (el.disabled || el.readOnly)
+            return false;
+        return TEXT_INPUT_TYPES.has(el.getAttribute('type') ?? undefined);
+    }
+    if (el.getAttribute?.('contenteditable') === 'true' || el.isContentEditable)
+        return true;
+    return false;
+}
+/** True when the element is not actually rendered, so focusing it is a
+ * silent no-op. Checks that cannot be evaluated (non-DOM test fakes) are
+ * treated as rendered. */
+function isUnrendered(el) {
+    if (typeof el.getClientRects === 'function' && el.getClientRects().length === 0)
+        return true;
+    if (typeof el.closest === 'function' && el.closest('[hidden], [inert]'))
+        return true;
+    if (typeof window !== 'undefined' && typeof window.getComputedStyle === 'function') {
+        if (window.getComputedStyle(el).visibility === 'hidden')
+            return true;
+    }
+    return false;
+}
+/** Enabled + attribute-level enabled (not disabled/aria-disabled/hidden). */
+function isEnabled(el) {
+    if (el.hasAttribute('disabled'))
+        return false;
+    if (el.getAttribute('aria-disabled') === 'true')
+        return false;
+    if (el.hasAttribute('hidden'))
+        return false;
+    return true;
+}
+/**
+ * Resolve the element a dialog should focus when it opens, per the order
+ * above. Returns null when nothing matches and there is no fallback.
+ */
+export function resolveDialogFocusTarget(container, opts = {}) {
+    if (!container)
+        return null;
+    const { initialFocus: initialFocusProp = 'first-input', fallback } = opts;
+    let initialFocus = initialFocusProp;
+    // Explicit 'dialog' — the old behaviour, verbatim.
+    if (initialFocus === 'dialog')
+        return container;
+    // Explicit element.
+    if (initialFocus instanceof HTMLElement)
+        return initialFocus;
+    // Explicit selector (any string other than the 'first-input' sentinel),
+    // resolved INSIDE the container. A miss falls through
+    // to the default first-input order (a consumer selector targeting a
+    // conditionally-rendered field shouldn't strand focus on the dialog).
+    if (typeof initialFocus === 'string' && initialFocus !== 'first-input') {
+        const found = container.querySelector(initialFocus);
+        if (found)
+            return found;
+        initialFocus = 'first-input';
+    }
+    // null opts out of auto-focus entirely (Drawer/BottomSheet): return only
+    // the explicit fallback, never the container.
+    if (initialFocus === null)
+        return fallback ?? null;
+    if (initialFocus !== 'first-input' && initialFocus != null)
+        return null;
+    // 1. Consumer's explicit autofocus opt-ins.
+    const autofocused = container.querySelector('[data-autofocus], [autofocus]:not(input[autofocus][type="hidden"])');
+    if (autofocused && isEnabled(autofocused) && !isUnrendered(autofocused))
+        return autofocused;
+    // 2. First enabled, rendered text-entry control in the body. Buttons
+    //    (including the header close ✕) never qualify, so the header is safe
+    //    to include.
+    const candidates = container.querySelectorAll('input, textarea, [contenteditable="true"], [contenteditable=""]');
+    for (const el of candidates) {
+        if (isEnabled(el) && !isUnrendered(el) && isTextEntryControl(el))
+            return el;
+    }
+    // 3. The dialog/panel itself.
+    return fallback ?? container;
+}
+/**
+ * Focus a resolved target on the next frame (after the open transition has
+ * mounted the content). Mirrors the previous `requestAnimationFrame` timing
+ * so focus lands on real DOM, not a mounting tree.
+ */
+export function focusDialogTarget(container, opts = {}, rq = requestAnimationFrame.bind(window)) {
+    rq(() => {
+        const target = resolveDialogFocusTarget(container, opts);
+        if (!target)
+            return;
+        target.focus();
+        // Verify the focus actually landed — a focus() on an unrendered or
+        // otherwise unfocusable element is a silent no-op that leaves focus on
+        // <body>, which breaks the dialog's own Escape handling (Modal owns
+        // Escape on the dialog element). Fall back to the container.
+        if (typeof document !== 'undefined' && document.activeElement !== target) {
+            const fallbackEl = opts.fallback ?? container;
+            if (fallbackEl)
+                fallbackEl.focus();
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",