@neuravision/construct 2.1.1 → 2.1.3

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to `@neuravision/construct` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.3] - 2026-07-17
+
+### Fixed
+
+- Chip: custom icons composed into the `.ct-chip__icon` slot (a `.ct-icon` — also when wrapped
+  by a framework component host — or a bare `<svg>`) now adopt the slot's 1em size. Previously
+  `.ct-icon` kept its fixed `--icon-md` box and overflowed the slot onto the chip label
+  (visible as a copy icon overlapping the first characters of ID chips).
+
+## [2.1.2] - 2026-07-16
+
+### Added
+
+- Datum grammar, extended from signature to system-wide vocabulary:
+  - `component.datum.*` tokens (edge width, tick, origin, mark, scale steps) — the grammar's
+    dimensions are now part of the published token contract and themable per product.
+  - `ct-eyebrow--numbered` (+ `ct-eyebrow-set` scope): auto-incremented, zero-padded sheet
+    numbers in the eyebrow, like an engineering drawing set.
+  - `ct-datum-scale--progress`: the scale's origin segment becomes meaning-bearing and reports
+    progress via `--ct-datum-scale-progress`; fill uses `brand-accent-strong` (≥3:1 per theme).
+  - `ct-datum-frame`: the corner registration mark generalised beyond cards for figures, code
+    samples, and media exhibits.
+  - Chart datum reference line (`ct-chart__datum-line` + `ct-chart__datum-label`) for threshold,
+    target, and "today" markers — dashed so the reference is shape-encoded, with a forced-colors
+    `CanvasText` fallback.
+  - Tables speak the grammar: `tr[aria-current]`/`[aria-selected]`/`[data-state="selected"]` rows
+    carry the orange leading edge (with forced-colors border fallback), and the actively sorted
+    column header (`aria-sort`) carries the datum underline.
+  - A "The Datum" section in `docs/guidelines.md` documenting the dosage rule (one datum per
+    surface), the text/edge/fill color contract, and the motion rule.
+
+### Changed
+
+- The datum now enters instead of popping: tab indicators draw in from their origin
+  (`transform`-based), and active leading edges on list items, sidebar nav items, and cards
+  slide in via a `box-shadow` transition (`--duration-fast`, disabled by
+  `prefers-reduced-motion`). The active card's shadow list is reordered
+  (`ambient, inset edge`) so it interpolates; consumers overriding `box-shadow` on active
+  states should re-check their overrides.
+- The datum scale's origin now anchors to the inline start in RTL writing modes.
+- Table rows using `aria-selected`/`aria-current` markup, previously unstyled, now receive the
+  selected-row treatment (muted background + leading edge).
+
+- Preset themes: a new `themes/` package entry for validated, opt-in brand skins that compile
+  through the `construct-theme` CLI instead of being baked into `tokens.css`. First preset:
+  `walnut` — a warm ivory light theme with walnut-brown brand color, AAA body-text contrast
+  (≥ 7:1) enforced by `contrast` gates, validated in `npm run check` via `themes:validate`.
+
+### Fixed
+
+- Tabs: anchor-based triggers (router-driven tabs rendering `<a class="ct-tabs__trigger">`)
+  no longer inherit the global link underline and link `:active` color from `foundations.css`.
+  The trigger label showed a text underline stacked above the orange active indicator; the
+  indicator is the only active-tab signal now.
+
 ## [2.1.1] - 2026-07-16
 
 ### Changed

package/README.md

@@ -118,6 +118,19 @@ Load the generated token stylesheet after all Construct style entries, because f
 
 Application-specific overrides may follow it. Keeping the generated theme last among Construct imports ensures its root and scoped values win deterministically.
 
+### Preset themes
+
+The package ships validated preset themes in [`themes/`](themes/README.md) — brand skins that
+compile through the same CLI instead of being baked into `tokens.css`:
+
+```bash
+npx construct-theme --theme node_modules/@neuravision/construct/themes/walnut.theme.json --out-dir ./src/generated/construct
+```
+
+| Preset | Character |
+|--------|-----------|
+| `walnut` | Warm ivory light theme with walnut-brown brand color; AAA body-text contrast enforced by built-in gates |
+
 ## 🧩 Components
 
 49 standalone component style entries, documented and accessibility-tested in [Storybook](https://samyssmile.github.io/construct/).

package/behaviors/combobox.js

@@ -14,8 +14,10 @@ import {
   ensureId,
   focusElement,
   getTextLabel,
+  isComposingEvent,
   isDisabled,
   nextEnabledIndex,
+  warnAccessibility,
 } from './internal/dom.js';
 import { createPopupLayer } from './internal/popup-layer.js';
 
@@ -94,6 +96,13 @@ export function createComboboxController(options) {
 
   const status = options.status == null ? null : assertElement(options.status, 'options.status');
   if (status) assertSameDocument([status], input.ownerDocument, 'options.status');
+  if (!status) {
+    warnAccessibility(
+      'Combobox: no options.status element was provided, so filter results are never ' +
+        'announced to screen readers (WCAG 4.1.3). Pass a visually hidden live-region ' +
+        'element via options.status.',
+    );
+  }
   const originalStatusText = status?.textContent;
   const originalInputValue = input.value;
   const filter = options.filter === true
@@ -198,6 +207,12 @@ export function createComboboxController(options) {
     return result === false ? availableOptions() : result;
   }
 
+  /* Which option receives the visual highlight when the listbox opens:
+     'default' = selected option or first available, 'last' = last available
+     (ArrowUp open per APG), 'none' = open without moving visual focus
+     (Alt+ArrowDown per APG). */
+  let pendingOpenFocus = 'default';
+
   const layer = createPopupLayer({
     additionalControls: toggleButton ? [toggleButton] : [],
     attributes,
@@ -216,10 +231,16 @@ export function createComboboxController(options) {
     trigger: input,
     onOpen(detail, checkpoint) {
       const available = applyFilterRaw();
-      const selected = selectedIndex >= 0 && isAvailable(optionElements[selectedIndex])
-        ? selectedIndex
-        : optionElements.indexOf(available[0]);
-      if (selected >= 0) setActive(selected);
+      let initial = -1;
+      if (pendingOpenFocus === 'last') {
+        initial = optionElements.indexOf(available.at(-1));
+      } else if (pendingOpenFocus === 'default') {
+        initial = selectedIndex >= 0 && isAvailable(optionElements[selectedIndex])
+          ? selectedIndex
+          : optionElements.indexOf(available[0]);
+      }
+      pendingOpenFocus = 'default';
+      if (initial >= 0) setActive(initial);
       focusElement(input);
       checkpoint();
       options.onOpen?.(detail);
@@ -330,9 +351,27 @@ export function createComboboxController(options) {
 
   function onInputKeyDown(event) {
     if (!isInteractive()) return;
+    /* IME composition: Enter commits composed text and arrows navigate
+       candidates — the widget must not hijack them. */
+    if (isComposingEvent(event)) return;
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
+      /* APG: Alt+ArrowDown opens without moving visual focus,
+         Alt+ArrowUp closes and keeps the current value. */
+      if (event.altKey) {
+        if (event.key === 'ArrowDown') {
+          if (!layer.isOpen) {
+            pendingOpenFocus = 'none';
+            open('keyboard');
+          }
+        } else if (layer.isOpen) {
+          close('keyboard', { restoreFocus: false });
+        }
+        return;
+      }
       if (!layer.isOpen) {
+        /* APG: ArrowUp opens with visual focus on the last option. */
+        pendingOpenFocus = event.key === 'ArrowUp' ? 'last' : 'default';
         open('keyboard');
         return;
       }

package/behaviors/dropdown.js

@@ -11,7 +11,7 @@ import {
   createDisposables,
   createTypeahead,
   dispatch,
-  focusElement,
+  focusIntoView,
   getItemValue,
   isDisabled,
   nextEnabledIndex,
@@ -82,7 +82,7 @@ export function createDropdownController(options) {
     items.forEach((item, itemIndex) => {
       attributes.set(item, 'data-highlighted', itemIndex === index ? '' : null);
     });
-    if (focus) focusElement(items[index]);
+    if (focus) focusIntoView(items[index]);
     return true;
   }
 
@@ -239,11 +239,25 @@ export function createDropdownController(options) {
     } else if ((event.key === 'Enter' || event.key === ' ') && !layer.isOpen) {
       event.preventDefault();
       open('keyboard');
+    } else if (!layer.isOpen) {
+      /* APG menu button: a printable character opens the menu and moves
+         focus to the first matching item. */
+      const match = typeahead.find(event, items);
+      if (match >= 0) {
+        event.preventDefault();
+        open('keyboard');
+        setHighlighted(match);
+      }
     }
   });
   disposables.listen(menu, 'keydown', onMenuKeyDown);
   items.forEach((item, index) => {
     disposables.listen(item, 'focus', () => setHighlighted(index, { focus: false }));
+    /* Focus follows the pointer, as in native menus — otherwise the roving
+       focus item and the hovered item can show two competing highlights. */
+    disposables.listen(item, 'pointermove', () => {
+      if (layer.isOpen && focusIndex !== index && !isDisabled(item)) setHighlighted(index);
+    });
     disposables.listen(item, 'click', (event) => {
       if (isDisabled(item)) {
         event.preventDefault();

package/behaviors/index.d.ts

@@ -36,6 +36,8 @@ export interface DialogControllerOptions {
   trapFocus?: boolean;
   returnFocus?: boolean;
   lockScroll?: boolean;
+  /** Additionally set `inert` on the container's DOM siblings while open. */
+  inertBackground?: boolean;
   onOpen?(detail: OpenCloseDetail<DialogController>): void;
   onClose?(detail: OpenCloseDetail<DialogController>): void;
 }

package/behaviors/internal/dialog-controller.js

@@ -10,9 +10,12 @@ import {
   dispatch,
   ensureId,
   focusElement,
+  focusIntoView,
   getFocusableElements,
+  isComposingEvent,
   isElement,
   isDisabled,
+  warnAccessibility,
 } from './dom.js';
 import {
   closeOwnedOverlays,
@@ -101,10 +104,13 @@ export function createDialogController(options, registry, defaults) {
   const trapFocus = options.trapFocus !== false;
   const returnFocus = options.returnFocus !== false;
   const lockScroll = options.lockScroll !== false;
+  const inertBackground = options.inertBackground === true;
   let open = options.open ?? container.getAttribute('data-state') === 'open';
   let previouslyFocused = null;
   let releaseBodyLock = null;
   let removeFromStack = null;
+  let inertedElements = null;
+  let warnedMissingName = false;
 
   const dialogId = ensureId(dialog, `${defaults.idPrefix}-dialog`, attributes);
   attributes.set(dialog, 'role', dialog.getAttribute('role') ?? 'dialog');
@@ -125,6 +131,42 @@ export function createDialogController(options, registry, defaults) {
     removeFromStack = null;
     releaseBodyLock?.();
     releaseBodyLock = null;
+    releaseBackgroundInert();
+  }
+
+  /* aria-modal hides background content from modern AT, but legacy virtual
+     cursors can still wander behind the dialog. Opt-in `inertBackground`
+     additionally inerts the container's DOM siblings up to <body>. Nodes
+     appended after opening (e.g. portaled popups) are unaffected. */
+  function applyBackgroundInert() {
+    if (!inertBackground || inertedElements) return;
+    inertedElements = [];
+    for (let node = container; node.parentElement && node !== document.body; node = node.parentElement) {
+      for (const sibling of node.parentElement.children) {
+        if (sibling === node || sibling.inert) continue;
+        const tag = sibling.tagName;
+        if (tag === 'SCRIPT' || tag === 'STYLE' || tag === 'LINK' || tag === 'TEMPLATE') continue;
+        sibling.inert = true;
+        inertedElements.push(sibling);
+      }
+    }
+  }
+
+  function releaseBackgroundInert() {
+    if (!inertedElements) return;
+    for (const element of inertedElements) element.inert = false;
+    inertedElements = null;
+  }
+
+  function warnWhenUnnamed() {
+    if (warnedMissingName) return;
+    warnedMissingName = true;
+    if (!dialog.hasAttribute('aria-label') && !dialog.hasAttribute('aria-labelledby')) {
+      warnAccessibility(
+        `${defaults.name}: the dialog element has neither aria-labelledby nor aria-label. ` +
+          'Dialogs must expose an accessible name (WCAG 4.1.2).',
+      );
+    }
   }
 
   function registerDialogOverlay() {
@@ -140,7 +182,7 @@ export function createDialogController(options, registry, defaults) {
   function focusInside(checkpoint = lifecycle.assertAlive) {
     const target = resolveInitialFocus(options.initialFocus, dialog);
     checkpoint();
-    if (target && focusElement(target)) {
+    if (target && focusIntoView(target)) {
       checkpoint();
       return;
     }
@@ -151,8 +193,8 @@ export function createDialogController(options, registry, defaults) {
   }
 
   function restoreDialogFocus(target) {
-    if (focusElement(target)) return true;
-    if (target !== trigger && focusElement(trigger)) return true;
+    if (focusIntoView(target)) return true;
+    if (target !== trigger && focusIntoView(trigger)) return true;
 
     const active = document.activeElement;
     if (isElement(active) && dialog.contains(active) && typeof active.blur === 'function') {
@@ -173,8 +215,10 @@ export function createDialogController(options, registry, defaults) {
       previouslyFocused = isElement(document.activeElement) ? document.activeElement : null;
       open = true;
       syncState();
+      warnWhenUnnamed();
       removeFromStack = registerDialogOverlay();
       if (lockScroll) releaseBodyLock = lockBodyScroll(document);
+      applyBackgroundInert();
       try {
         focusInside(checkpoint);
         options.onOpen?.(detail);
@@ -232,6 +276,9 @@ export function createDialogController(options, registry, defaults) {
 
   function onDocumentKeyDown(event) {
     if (!open) return;
+    /* Never treat keys as dialog shortcuts while an IME composition is
+       active — Escape/Tab are cancelling or committing composed text. */
+    if (isComposingEvent(event)) return;
 
     if (
       event.key === 'Escape' &&
@@ -283,15 +330,28 @@ export function createDialogController(options, registry, defaults) {
   });
 
   if (backdrop) {
-    disposables.listen(backdrop, 'click', (event) => {
-      if (
+    /* Close only when the pointer both went down AND came up on the backdrop
+       itself. A plain click listener also fires when a drag (e.g. selecting
+       text in a form field) starts inside the dialog and is released over
+       the backdrop — the click retargets to their common ancestor, which is
+       the backdrop — and would discard the user's in-progress work. Routing
+       the pointerdown through the overlay stack also keeps a single gesture
+       from dismissing a popup and this dialog together. */
+    let pointerDownOnBackdrop = false;
+    disposables.listen(backdrop, 'pointerdown', (event) => {
+      pointerDownOnBackdrop =
         open &&
         closeOnBackdrop &&
         event.target === backdrop &&
-        consumeTopOverlayEvent(event, document, token)
-      ) {
-        closeDialog('backdrop');
-      }
+        consumeTopOverlayEvent(event, document, token);
+    });
+    disposables.listen(backdrop, 'pointercancel', () => {
+      pointerDownOnBackdrop = false;
+    });
+    disposables.listen(backdrop, 'pointerup', (event) => {
+      const shouldClose = pointerDownOnBackdrop && event.target === backdrop;
+      pointerDownOnBackdrop = false;
+      if (shouldClose && open) closeDialog('backdrop');
     });
   }
 
@@ -320,6 +380,14 @@ export function createDialogController(options, registry, defaults) {
       if (!lifecycle.destroy()) return;
       if (open) {
         open = false;
+        /* Frameworks often unmount an open dialog without closing it first;
+           without a hand-off the browser drops focus to <body> and silently
+           teleports keyboard/AT users to the top of the page. */
+        const active = document.activeElement;
+        if (isElement(active) && dialog.contains(active)) {
+          restoreDialogFocus(previouslyFocused?.isConnected ? previouslyFocused : trigger);
+        }
+        previouslyFocused = null;
         releaseOpenResources();
       }
       disposables.dispose();
@@ -332,8 +400,10 @@ export function createDialogController(options, registry, defaults) {
   syncState();
   if (open) {
     previouslyFocused = isElement(document.activeElement) ? document.activeElement : null;
+    warnWhenUnnamed();
     removeFromStack = registerDialogOverlay();
     if (lockScroll) releaseBodyLock = lockBodyScroll(document);
+    applyBackgroundInert();
     try {
       focusInside();
     } catch (error) {

package/behaviors/internal/dom.js

@@ -116,12 +116,14 @@ export function getFocusableElements(container) {
   if (container.matches(FOCUSABLE_SELECTOR)) candidates.push(container);
   candidates.push(...container.querySelectorAll(FOCUSABLE_SELECTOR));
 
-  return candidates.filter(
-    (element) =>
-      !isDisabled(element) &&
-      element.getAttribute('aria-hidden') !== 'true' &&
-      isRendered(element),
-  );
+  return candidates.filter((element) => {
+    if (isDisabled(element) || element.getAttribute('aria-hidden') === 'true') return false;
+    /* The selector only excludes tabindex="-1"; any other negative value
+       (e.g. "-2") is equally removed from the tab order. */
+    const tabindex = element.getAttribute('tabindex');
+    if (tabindex !== null && Number.parseInt(tabindex, 10) < 0) return false;
+    return isRendered(element);
+  });
 }
 
 export function focusElement(element) {
@@ -133,6 +135,24 @@ export function focusElement(element) {
   return element.ownerDocument.activeElement === element;
 }
 
+/**
+ * Focuses an element and scrolls it minimally into view. focusElement uses
+ * preventScroll to avoid browser-default jump scrolling, so controller-driven
+ * focus moves (trap wraparound, roving focus, highlight) must restore
+ * visibility themselves or the focus indicator can leave the viewport
+ * (WCAG 2.4.11 Focus Not Obscured).
+ */
+export function focusIntoView(element) {
+  const focused = focusElement(element);
+  if (focused) element.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+  return focused;
+}
+
+/** Emits a non-fatal accessibility authoring warning. */
+export function warnAccessibility(message) {
+  if (typeof console !== 'undefined') console.warn(`[construct] ${message}`);
+}
+
 export function createAttributeStore() {
   const originals = new Map();
 
@@ -266,6 +286,17 @@ export function orientationDelta(key, orientation, element) {
   return 0;
 }
 
+/**
+ * Detects keydown events fired while an IME composition is in progress.
+ * Such events must never trigger widget shortcuts (Enter/Escape/arrows):
+ * the user is committing or cancelling composed text, not operating the
+ * widget. keyCode 229 covers Chromium, which reports real key values
+ * during composition; `isComposing` covers the standards path.
+ */
+export function isComposingEvent(event) {
+  return event.isComposing === true || event.keyCode === 229;
+}
+
 export function createTypeahead({ timeout = 500 } = {}) {
   if (!Number.isFinite(timeout) || timeout < 0) {
     throw new RangeError('Typeahead timeout must be a non-negative finite number.');
@@ -287,7 +318,7 @@ export function createTypeahead({ timeout = 500 } = {}) {
         event.altKey ||
         event.ctrlKey ||
         event.metaKey ||
-        event.isComposing
+        isComposingEvent(event)
       ) {
         return -1;
       }

package/behaviors/internal/overlay.js

@@ -1,4 +1,4 @@
-import { focusElement, getFocusableElements, isElement } from './dom.js';
+import { focusIntoView, getFocusableElements, isElement } from './dom.js';
 
 const bodyLocks = new WeakMap();
 const overlayStates = new WeakMap();
@@ -216,7 +216,7 @@ export function trapTabKey(event, containers) {
   }
   if (!focusable.length) {
     event.preventDefault();
-    focusElement(scopes[0]);
+    focusIntoView(scopes[0]);
     return true;
   }
 
@@ -227,13 +227,13 @@ export function trapTabKey(event, containers) {
 
   if (event.shiftKey && (!activeInside || active === first)) {
     event.preventDefault();
-    focusElement(last);
+    focusIntoView(last);
     return true;
   }
 
   if (!event.shiftKey && (!activeInside || active === last)) {
     event.preventDefault();
-    focusElement(first);
+    focusIntoView(first);
     return true;
   }
 

package/behaviors/internal/popup-layer.js

@@ -4,6 +4,7 @@ import {
   ensureId,
   eventTargetsOutside,
   focusElement,
+  isComposingEvent,
   isElement,
 } from './dom.js';
 import { consumeTopOverlayEvent, pushOverlay } from './overlay.js';
@@ -134,6 +135,7 @@ export function createPopupLayer({
       !open ||
       !closeOnEscape ||
       event.key !== 'Escape' ||
+      isComposingEvent(event) ||
       !consumeTopOverlayEvent(event, document, token)
     ) return;
     event.preventDefault();

package/behaviors/popover.js

@@ -176,7 +176,10 @@ export function createPopoverController(options) {
   function toggle(reason = 'programmatic') {
     return lifecycle.run('toggle', (checkpoint) => {
       if (isDisabled(trigger)) return false;
-      pendingFocus = Boolean(options.focusOnOpen);
+      /* Same focus-entry default as open(): configuring initialFocus means
+         trigger activation must move focus in too, or keyboard users may
+         never reach popover content rendered elsewhere in the DOM. */
+      pendingFocus = Boolean(options.initialFocus || options.focusOnOpen);
       try {
         const changed = layer.toggle(reason);
         checkpoint();
@@ -216,17 +219,23 @@ export function createPopoverController(options) {
   }
 
   if (options.openOnHover) {
-    disposables.listen(root, 'pointerenter', (event) => {
-      if (event.pointerType !== 'touch') {
-        hovered = true;
-        scheduleOpen('hover');
-      }
-    });
-    disposables.listen(root, 'pointerleave', (event) => {
-      if (event.pointerType !== 'touch') {
-        hovered = false;
-        scheduleClose('hover');
-      }
+    /* When no wrapper root exists, root falls back to the (hidden) popover,
+       which can never receive pointerenter — hover must then be driven by
+       the trigger as well. */
+    const hoverTargets = root.contains(trigger) ? [root] : [root, trigger];
+    hoverTargets.forEach((target) => {
+      disposables.listen(target, 'pointerenter', (event) => {
+        if (event.pointerType !== 'touch') {
+          hovered = true;
+          scheduleOpen('hover');
+        }
+      });
+      disposables.listen(target, 'pointerleave', (event) => {
+        if (event.pointerType !== 'touch') {
+          hovered = false;
+          scheduleClose('hover');
+        }
+      });
     });
   }
 

package/behaviors/select-menu.js

@@ -204,14 +204,18 @@ export function createSelectMenuController(options) {
 
   function onTriggerKeyDown(event) {
     if (isDisabled(trigger)) {
-      if (['ArrowDown', 'ArrowUp', 'Home', 'End', 'Enter', ' '].includes(event.key)) {
+      if (['ArrowDown', 'ArrowUp', 'Home', 'End', 'PageUp', 'PageDown', 'Enter', ' '].includes(event.key)) {
         event.preventDefault();
       }
       return;
     }
 
     if (event.key === 'Tab' && layer.isOpen) {
-      close('tab', { restoreFocus: false });
+      /* APG select-only combobox: Tab commits the visually focused option
+         before the browser moves focus on — otherwise keyboard users
+         silently keep the old value where mouse users' click commits. */
+      if (activeIndex >= 0 && activeIndex !== selectedIndex) select(activeIndex, 'keyboard');
+      if (layer.isOpen) close('tab', { restoreFocus: false });
       return;
     }
 
@@ -240,6 +244,20 @@ export function createSelectMenuController(options) {
       return;
     }
 
+    if (event.key === 'PageUp' || event.key === 'PageDown') {
+      event.preventDefault();
+      if (!layer.isOpen) open('keyboard');
+      const direction = event.key === 'PageDown' ? 1 : -1;
+      let index = activeIndex >= 0 ? activeIndex : selectedIndex;
+      for (let step = 0; step < 10; step += 1) {
+        const next = nextEnabledIndex(optionElements, index, direction, false);
+        if (next < 0) break;
+        index = next;
+      }
+      if (index >= 0) setActive(index);
+      return;
+    }
+
     const match = typeahead.find(event, optionElements, activeIndex >= 0 ? activeIndex : selectedIndex);
     if (match >= 0) {
       event.preventDefault();

package/behaviors/tabs.js

@@ -13,9 +13,11 @@ import {
   dispatch,
   ensureId,
   focusElement,
+  focusIntoView,
   isDisabled,
   nextEnabledIndex,
   orientationDelta,
+  warnAccessibility,
 } from './internal/dom.js';
 
 const controllers = new WeakMap();
@@ -31,7 +33,15 @@ function resolvePanels(tablist, tabs, suppliedPanels) {
   if (controlledPanels.every(Boolean)) return controlledPanels;
 
   const scope = tablist.parentElement ?? tablist;
-  return [...scope.querySelectorAll('[role="tabpanel"], [data-ct-tab-panel]')];
+  const positional = [...scope.querySelectorAll('[role="tabpanel"], [data-ct-tab-panel]')];
+  if (positional.length > 1) {
+    warnAccessibility(
+      'Tabs: panels were paired with tabs by DOM position. If panel order differs from ' +
+        'tab order, tabs announce the wrong panels — set aria-controls on each tab or ' +
+        'pass options.panels explicitly.',
+    );
+  }
+  return positional;
 }
 
 /**
@@ -161,7 +171,8 @@ export function createTabsController(options) {
     sync();
     movingFocus = true;
     try {
-      focusElement(tabs[index]);
+      /* Overflowing tablists scroll; keep the roving focus visible. */
+      focusIntoView(tabs[index]);
     } finally {
       movingFocus = false;
     }