@webjsdev/ui 0.3.5 → 0.3.7

package/packages/registry/components/tabs.ts

@@ -43,8 +43,11 @@
  * Design tokens used: --muted, --muted-foreground, --foreground, --background,
  * --input, --ring.
  */
-import { WebComponent, html } from '@webjsdev/core';
-import { cn } from '../lib/utils.ts';
+import { WebComponent, html, prop } from '@webjsdev/core';
+import { cn, ensureId } from '../lib/utils.ts';
+
+// A tab `value` becomes part of an id, so reduce it to id-safe characters.
+const idSafe = (s: string): string => s.replace(/[^A-Za-z0-9_-]/g, '-');
 
 // --------------------------------------------------------------------------
 // Class helpers
@@ -92,20 +95,39 @@ const TABS_CONTENT_CLASS = 'flex-1 outline-none';
 // requestUpdate() to re-render against the new parent value.
 // --------------------------------------------------------------------------
 
-export class UiTabs extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-    orientation: { type: String, reflect: true },
-  };
-  declare value: string;
-  declare orientation: 'horizontal' | 'vertical';
-
+export class UiTabs extends WebComponent({
+  value: prop(String, { reflect: true }),
+  orientation: prop<'horizontal' | 'vertical'>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
     this.orientation = 'horizontal';
   }
 
+  // Assign the scope id BEFORE render so it is serialized onto this host's
+  // opening tag at SSR (willUpdate now runs server-side). Without this, the id
+  // was minted lazily during a CHILD trigger's render, AFTER this host's tag
+  // was already serialized without an id, so the host shipped no id; on
+  // hydration the client re-minted a DIFFERENT counter id and the trigger /
+  // panel ids mismatched SSR vs client, breaking hydration (#730).
+  willUpdate(): void {
+    ensureId(this, 'ui-tabs');
+  }
+
+  // Stable per-instance scope so a trigger and its panel agree on the
+  // shared id stem (`<scope>-trigger-<value>` / `<scope>-panel-<value>`)
+  // even when several tab sets reuse the same `value` names on one page.
+  get scopeId(): string {
+    return ensureId(this, 'ui-tabs');
+  }
+
+  // Builds the trigger / panel id pair a child derives from its `value`.
+  idsFor(value: string): { trigger: string; panel: string } {
+    const v = idSafe(value);
+    return { trigger: `${this.scopeId}-trigger-${v}`, panel: `${this.scopeId}-panel-${v}` };
+  }
+
   render() {
     return html`<div
       data-slot="tabs"
@@ -130,7 +152,7 @@ export class UiTabs extends WebComponent {
 
   _broadcast(): void {
     this.querySelectorAll<WebComponent>(
-      'ui-tabs-trigger, ui-tabs-content',
+      'ui-tabs-list, ui-tabs-trigger, ui-tabs-content',
     ).forEach((el) => el.requestUpdate?.());
   }
 }
@@ -140,21 +162,25 @@ UiTabs.register('ui-tabs');
 // <ui-tabs-list>
 // --------------------------------------------------------------------------
 
-export class UiTabsList extends WebComponent {
-  static properties = {
-    variant: { type: String, reflect: true },
-  };
-  declare variant: TabsListVariant;
-
+export class UiTabsList extends WebComponent({
+  variant: prop<TabsListVariant>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.variant = 'default';
   }
 
+  get _tabs(): UiTabs | null {
+    if (typeof this.closest !== 'function') return null;
+    return this.closest('ui-tabs') as UiTabs | null;
+  }
+
   render() {
+    const orientation = this._tabs?.orientation ?? 'horizontal';
     return html`<div
       data-slot="tabs-list"
       role="tablist"
+      aria-orientation=${orientation}
       data-variant=${this.variant}
       class=${tabsListClass({ variant: this.variant })}
     ><slot></slot></div>`;
@@ -166,12 +192,9 @@ UiTabsList.register('ui-tabs-list');
 // <ui-tabs-trigger value="...">
 // --------------------------------------------------------------------------
 
-export class UiTabsTrigger extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-  };
-  declare value: string;
-
+export class UiTabsTrigger extends WebComponent({
+  value: prop(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
@@ -188,10 +211,13 @@ export class UiTabsTrigger extends WebComponent {
   render() {
     const tabs = this._tabs;
     const active = !!tabs && tabs.value === this.value && this.value !== '';
+    const ids = tabs && this.value ? tabs.idsFor(this.value) : null;
     return html`<button
       type="button"
       role="tab"
       data-slot="tabs-trigger"
+      id=${ids ? ids.trigger : ''}
+      aria-controls=${ids ? ids.panel : ''}
       data-state=${active ? 'active' : 'inactive'}
       aria-selected=${String(active)}
       tabindex=${active ? '0' : '-1'}
@@ -235,12 +261,9 @@ UiTabsTrigger.register('ui-tabs-trigger');
 // <ui-tabs-content value="...">
 // --------------------------------------------------------------------------
 
-export class UiTabsContent extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-  };
-  declare value: string;
-
+export class UiTabsContent extends WebComponent({
+  value: prop(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
@@ -254,14 +277,20 @@ export class UiTabsContent extends WebComponent {
   render() {
     const tabs = this._tabs;
     const active = !!tabs && tabs.value === this.value && this.value !== '';
+    const ids = tabs && this.value ? tabs.idsFor(this.value) : null;
     // The host needs to be hidden when inactive so its rendered <section>
     // is removed from layout (light DOM has no :host CSS to scope this).
     // Use the native `hidden` IDL property rather than imperative
-    // setAttribute, so it reads as a property assignment.
+    // setAttribute, so it reads as a property assignment. `inert` on the
+    // host additionally pulls an inactive panel (and anything focusable
+    // inside it) out of the tab order and the accessibility tree.
     this.hidden = !active;
+    this.inert = !active;
     return html`<section
       data-slot="tabs-content"
       role="tabpanel"
+      id=${ids ? ids.panel : ''}
+      aria-labelledby=${ids ? ids.trigger : ''}
       tabindex="0"
       data-state=${active ? 'active' : 'inactive'}
       class=${TABS_CONTENT_CLASS}

package/packages/registry/components/toggle-group.ts

@@ -41,12 +41,14 @@
  * Events:
  *   `ui-value-change` on <ui-toggle-group>: `{ detail: { value } }` after selection changes.
  *
- * Keyboard: Enter / Space toggles the focused item (native button activation).
+ * Keyboard: Arrow keys move focus between items (roving tabindex, so the
+ * group is a single Tab stop), Home / End jump to the first / last item, and
+ * Enter / Space toggles the focused item.
  *
  * Design tokens used: inherited from toggleClass (--muted, --accent, --ring,
  * --input, --destructive).
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
 import { cn } from '../lib/utils.ts';
 import { toggleClass, type ToggleVariant, type ToggleSize } from './toggle.ts';
 
@@ -66,22 +68,14 @@ const ITEM_EXTRA =
 // their own renders before we read / write their state.
 // --------------------------------------------------------------------------
 
-export class UiToggleGroup extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-    type: { type: String, reflect: true },
-    variant: { type: String, reflect: true },
-    size: { type: String, reflect: true },
-    spacing: { type: String, reflect: true },
-    orientation: { type: String, reflect: true },
-  };
-  declare value: string;
-  declare type: 'single' | 'multiple';
-  declare variant: ToggleVariant;
-  declare size: ToggleSize;
-  declare spacing: string;
-  declare orientation: 'horizontal' | 'vertical';
-
+export class UiToggleGroup extends WebComponent({
+  value: prop(String, { reflect: true }),
+  type: prop<'single' | 'multiple'>(String, { reflect: true }),
+  variant: prop<ToggleVariant>(String, { reflect: true }),
+  size: prop<ToggleSize>(String, { reflect: true }),
+  spacing: prop(String, { reflect: true }),
+  orientation: prop<'horizontal' | 'vertical'>(String, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
@@ -117,9 +111,15 @@ export class UiToggleGroup extends WebComponent {
     queueMicrotask(() => this._reflectItems());
   }
 
+  _items(): UiToggleGroupItem[] {
+    return Array.from(this.querySelectorAll<UiToggleGroupItem>('ui-toggle-group-item'));
+  }
+
   _reflectItems(): void {
     const values = this._values;
-    this.querySelectorAll<UiToggleGroupItem>('ui-toggle-group-item').forEach((item) => {
+    const items = this._items();
+    const current = items.find((el) => el.tabIndex === 0);
+    items.forEach((item) => {
       const on = !!item.value && values.has(item.value);
       // Reflect both on the host (for CSS sibling selectors like
       // data-[spacing=0]:first:rounded-l-md that need to target the host
@@ -127,6 +127,31 @@ export class UiToggleGroup extends WebComponent {
       // item's render() refreshes its inner styling.
       item.pressed = on;
     });
+    this._roving(items, current);
+  }
+
+  // Roving tabindex (APG): exactly one item is in the tab order. Prefer the
+  // currently-focused item, then whichever was tabbable, then the first
+  // selected item, then the first item. Arrow keys move focus and shift the
+  // single tabbable slot via `focusItem`.
+  _roving(items: UiToggleGroupItem[], current?: UiToggleGroupItem): void {
+    if (!items.length) return;
+    const values = this._values;
+    const active =
+      typeof document !== 'undefined' ? (document.activeElement as Element | null) : null;
+    const focused = active ? items.find((i) => i === active) : undefined;
+    const selected = items.find((i) => !!i.value && values.has(i.value));
+    const tabbable = focused ?? current ?? selected ?? items[0];
+    items.forEach((item) => {
+      item.tabIndex = item === tabbable ? 0 : -1;
+    });
+  }
+
+  focusItem(item: UiToggleGroupItem): void {
+    this._items().forEach((el) => {
+      el.tabIndex = el === item ? 0 : -1;
+    });
+    item.focus();
   }
 
   _onItemClick = (e: Event): void => {
@@ -159,14 +184,10 @@ UiToggleGroup.register('ui-toggle-group');
 // Tailwind variant selectors on the joined-spacing rounded corners).
 // --------------------------------------------------------------------------
 
-export class UiToggleGroupItem extends WebComponent {
-  static properties = {
-    value: { type: String, reflect: true },
-    pressed: { type: Boolean, reflect: true },
-  };
-  declare value: string;
-  declare pressed: boolean;
-
+export class UiToggleGroupItem extends WebComponent({
+  value: prop(String, { reflect: true }),
+  pressed: prop(Boolean, { reflect: true }),
+}) {
   constructor() {
     super();
     this.value = '';
@@ -193,7 +214,10 @@ export class UiToggleGroupItem extends WebComponent {
   connectedCallback(): void {
     this.dataset.slot = 'toggle-group-item';
     this.role = 'button';
-    this.tabIndex = 0;
+    // Roving tabindex: start outside the tab order. The group promotes
+    // exactly one item to tabindex 0 in _reflectItems (runs after first
+    // render); Arrow keys move focus and the tabbable slot from there.
+    this.tabIndex = -1;
     this.addEventListener('click', this._onClick);
     this.addEventListener('keydown', this._onKeyDown);
     super.connectedCallback?.();
@@ -230,6 +254,24 @@ export class UiToggleGroupItem extends WebComponent {
     if (e.key === ' ' || e.key === 'Enter') {
       e.preventDefault();
       this._onClick();
+      return;
+    }
+    const group = this._group;
+    if (!group) return;
+    const horizontal = group.orientation !== 'vertical';
+    const nextKey = horizontal ? 'ArrowRight' : 'ArrowDown';
+    const prevKey = horizontal ? 'ArrowLeft' : 'ArrowUp';
+    const items = group._items();
+    const idx = items.indexOf(this);
+    if (idx === -1) return;
+    let target: UiToggleGroupItem | null = null;
+    if (e.key === nextKey) target = items[(idx + 1) % items.length] ?? null;
+    else if (e.key === prevKey) target = items[(idx - 1 + items.length) % items.length] ?? null;
+    else if (e.key === 'Home') target = items[0] ?? null;
+    else if (e.key === 'End') target = items[items.length - 1] ?? null;
+    if (target) {
+      e.preventDefault();
+      group.focusItem(target);
     }
   };
 }

package/packages/registry/components/toggle.ts

@@ -38,7 +38,7 @@
  * Design tokens used: --muted, --muted-foreground, --accent, --accent-foreground,
  * --input, --background, --ring, --destructive.
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
 import { cn } from '../lib/utils.ts';
 
 // cursor-pointer + select-none on BASE for both call sites: the
@@ -76,18 +76,12 @@ export function toggleClass(opts: { variant?: ToggleVariant; size?: ToggleSize }
 // project through the default slot inside the inner button.
 // --------------------------------------------------------------------------
 
-export class UiToggle extends WebComponent {
-  static properties = {
-    pressed: { type: Boolean, reflect: true },
-    variant: { type: String, reflect: true },
-    size: { type: String, reflect: true },
-    disabled: { type: Boolean, reflect: true },
-  };
-  declare pressed: boolean;
-  declare variant: ToggleVariant;
-  declare size: ToggleSize;
-  declare disabled: boolean;
-
+export class UiToggle extends WebComponent({
+  pressed: prop(Boolean, { reflect: true }),
+  variant: prop<ToggleVariant>(String, { reflect: true }),
+  size: prop<ToggleSize>(String, { reflect: true }),
+  disabled: prop(Boolean, { reflect: true }),
+}) {
   constructor() {
     super();
     this.pressed = false;

package/packages/registry/components/tooltip.ts

@@ -40,7 +40,8 @@
  *
  * Design tokens used: --foreground, --background.
  */
-import { WebComponent, html } from '@webjsdev/core';
+import { WebComponent, html, prop } from '@webjsdev/core';
+import { ensureId, onBeforeCache } from '../lib/utils.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // UA `[popover]` defaults paint a bordered, padded panel centered with
@@ -61,18 +62,13 @@ let lastTooltipHideAt = 0;
 // <ui-tooltip>
 // --------------------------------------------------------------------------
 
-export class UiTooltip extends WebComponent {
-  static properties = {
-    open: { type: Boolean, reflect: true },
-    delayDuration: { type: Number },
-    skipDelayDuration: { type: Number },
-  };
-  declare open: boolean;
+export class UiTooltip extends WebComponent({
+  open: prop(Boolean, { reflect: true }),
   // `delayDuration` / `skipDelayDuration` ride the `delay-duration` /
   // `skip-delay-duration` attributes (shadcn parity), read as typed props.
-  declare delayDuration: number;
-  declare skipDelayDuration: number;
-
+  delayDuration: Number,
+  skipDelayDuration: Number,
+}) {
   _showTimer: number | undefined;
   _hideTimer: number | undefined;
 
@@ -83,6 +79,45 @@ export class UiTooltip extends WebComponent {
     this.skipDelayDuration = 300;
   }
 
+  _disposeBeforeCache?: () => void;
+
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    // webjs projects slotted light-DOM children in a pass after the first
+    // render, so the trigger's focusable control is not in place yet at
+    // connect / firstUpdated. Defer to the next frame, by which point the
+    // projection has run and both the control and the tip content exist.
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => this._wireAria());
+    }
+    // Close before a back/forward snapshot so it does not restore open (#766).
+    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
+  }
+
+  disconnectedCallback(): void {
+    this._disposeBeforeCache?.();
+    super.disconnectedCallback?.();
+  }
+
+  // APG tooltip wiring: the focusable trigger references the tip via
+  // aria-describedby, so a screen reader appends the tip text to the
+  // trigger's own name ("Help, button, Helpful tip"). The tip is JS-driven,
+  // so doing this at runtime is correct.
+  _wireAria(): void {
+    const triggerHost = this.querySelector('ui-tooltip-trigger');
+    const content = this.querySelector<HTMLElement>('ui-tooltip-content [role="tooltip"]');
+    if (!triggerHost || !content) return;
+    const control =
+      triggerHost.querySelector<HTMLElement>('button, a[href], [tabindex], [role="button"]') ??
+      (triggerHost as HTMLElement);
+    const id = ensureId(content, 'ui-tooltip');
+    const existing = control.getAttribute('aria-describedby');
+    if (!existing) control.setAttribute('aria-describedby', id);
+    else if (!existing.split(/\s+/).includes(id)) {
+      control.setAttribute('aria-describedby', `${existing} ${id}`);
+    }
+  }
+
   // Back-compat getter for tests + external code that read `el.isOpen`
   // alongside the reactive `open` prop.
   get isOpen(): boolean { return this.open; }

package/packages/registry/lib/utils.ts

@@ -100,6 +100,33 @@ function variantPrefix(token: string): string {
   return i === -1 ? '' : token.slice(0, i + 1);
 }
 
+// ---------------------------------------------------------------------------
+// Stable DOM ids for wiring ARIA relationships (aria-controls /
+// aria-labelledby / aria-describedby) between sibling light-DOM nodes.
+// A monotonic counter is fine for uniqueness within a document: the id is
+// only consumed as an attribute value, never persisted. When SSR emits an
+// id on a host element, the upgraded element reuses it (ensureId is a no-op
+// when an id is already present), so the server and client agree.
+// ---------------------------------------------------------------------------
+
+let _idSeq = 0;
+
+/** A fresh, document-unique id string with a readable prefix. */
+export function domId(prefix = 'ui'): string {
+  _idSeq += 1;
+  return `${prefix}-${_idSeq}`;
+}
+
+/**
+ * Returns `el.id`, assigning a generated one (prefix-based) when absent.
+ * Idempotent, so an id already present (author-set, or carried over from
+ * SSR) is reused unchanged.
+ */
+export function ensureId(el: { id: string }, prefix = 'ui'): string {
+  if (!el.id) el.id = domId(prefix);
+  return el.id;
+}
+
 // ---------------------------------------------------------------------------
 // Custom-element base: SSR-safe. In the browser `Base = HTMLElement`. On
 // the server (Node, during SSR) `HTMLElement` is undefined; we substitute
@@ -239,3 +266,19 @@ export const helpClass = () => 'text-xs text-muted-foreground';
 
 /** Validation error text: replaces hint when the field is invalid. */
 export const errorClass = () => 'text-sm font-medium text-destructive';
+
+/**
+ * Run `reset` just before the webjs client router snapshots the page into its
+ * back/forward cache (the `webjs:before-cache` event). Transient overlays use
+ * this to close themselves so a restored snapshot is clean rather than, say, a
+ * hover-card frozen open after Back then Forward (#766). Wire it in
+ * `connectedCallback` and call the returned disposer in `disconnectedCallback`
+ * so the listener never leaks across soft navigations.
+ *
+ * SSR-safe: a no-op when there is no `document` (server / no client router).
+ */
+export function onBeforeCache(reset: () => void): () => void {
+  if (typeof document === 'undefined') return () => {};
+  document.addEventListener('webjs:before-cache', reset);
+  return () => document.removeEventListener('webjs:before-cache', reset);
+}

package/packages/registry/registry.json

@@ -188,7 +188,8 @@
       "name": "dialog",
       "type": "registry:ui",
       "registryDependencies": [
-        "lib-utils"
+        "lib-utils",
+        "button"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -203,6 +204,9 @@
     {
       "name": "dropdown-menu",
       "type": "registry:ui",
+      "registryDependencies": [
+        "popover"
+      ],
       "dependencies": [
         "@webjsdev/core"
       ],
@@ -216,6 +220,9 @@
     {
       "name": "hover-card",
       "type": "registry:ui",
+      "registryDependencies": [
+        "popover"
+      ],
       "dependencies": [
         "@webjsdev/core"
       ],
@@ -452,6 +459,9 @@
     {
       "name": "toggle-group",
       "type": "registry:ui",
+      "registryDependencies": [
+        "toggle"
+      ],
       "dependencies": [
         "@webjsdev/core"
       ],
@@ -465,6 +475,9 @@
     {
       "name": "tooltip",
       "type": "registry:ui",
+      "registryDependencies": [
+        "popover"
+      ],
       "dependencies": [
         "@webjsdev/core"
       ],