inclusive-elements 0.5.5 → 0.6.1

package/dist/types/alerts/alerts.d.ts

@@ -1,17 +1,30 @@
+export type AlertPoliteness = 'polite' | 'assertive';
 export type AlertOptions = {
     key?: string;
     duration?: number;
+    politeness?: AlertPoliteness;
 };
 export default class AlertsElement extends HTMLElement {
     static duration: number;
+    static politeness: AlertPoliteness;
     private timeouts;
     private index;
     connectedCallback(): void;
+    disconnectedCallback(): void;
     show(el: HTMLElement, options?: AlertOptions): string;
     dismiss(el: HTMLElement): void;
     dismiss(key: string): void;
     clear(): void;
-    speak(message: string): void;
+    speak(message: string, options?: AlertOptions): void;
+    private dismissAlert;
+    private leaveAlert;
     private startTimeout;
     private clearTimeout;
+    private pauseOnInteraction;
+    private resumeOnInteraction;
+    private handleInteraction;
+    private getAlerts;
+    private syncAlertPoliteness;
+    private getAuthoredPoliteness;
+    private getAlertFromTarget;
 }

package/dist/types/index.d.ts

@@ -1,9 +1,6 @@
-export { default as AccordionElement } from './accordion/accordion';
 export { default as AlertsElement } from './alerts/alerts';
-export { default as DisclosureElement } from './disclosure/disclosure';
+export type { AlertOptions, AlertPoliteness } from './alerts/alerts';
 export { default as MenuElement } from './menu/menu';
-export { default as ModalElement } from './modal/modal';
-export { default as PopupElement } from './popup/popup';
 export { default as TabsElement } from './tabs/tabs';
 export { default as ToolbarElement } from './toolbar/toolbar';
 export { default as TooltipElement } from './tooltip/tooltip';

package/dist/types/menu/menu.d.ts

@@ -1,12 +1,42 @@
 export default class MenuElement extends HTMLElement {
     static searchDelay: number;
+    static observedAttributes: string[];
+    private itemSync?;
     private search;
     private searchTimeout?;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private get items();
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private get horizontal();
+    private syncDocumentListeners;
+    private removeDocumentListeners;
+    private onDocumentClick;
+    private onDocumentKeyDown;
     private onKeyDown;
-    private navigate;
-    private focusItemAtIndex;
+    private onClick;
+    private onMouseEnter;
+    private isActive;
+    private syncItems;
+    private getItems;
+    private getEnabledItems;
+    private isItemEnabled;
+    private belongsToThisMenu;
+    private getActiveItem;
+    private getItemForEvent;
+    private getRootTriggerForEvent;
+    private getTriggers;
+    private getParentMenuTrigger;
+    private getParentMenu;
+    private getSubmenu;
+    private openSubmenu;
+    private closeSubmenus;
+    private closeSelfAndDescendants;
+    private closeMenuTree;
+    private focusRootMenuTrigger;
+    private getRootMenuTrigger;
+    private handleTypeahead;
+    private updateTypeaheadSearch;
+    private findTypeaheadMatch;
+    private getItemLabel;
+    private showPopoverWithSource;
 }

package/dist/types/tabs/tabs.d.ts

@@ -4,14 +4,21 @@ type SelectTabOptions = {
 };
 export default class TabsElement extends HTMLElement {
     private idPrefix;
+    private structureSync?;
+    private managedPanelTabindex;
     connectedCallback(): void;
     disconnectedCallback(): void;
     selectTab(index: number, options?: SelectTabOptions): boolean;
     private onKeyDown;
     private onClick;
-    private get initialTabIndex();
+    private syncStructure;
+    private get vertical();
     private get tablist();
-    private get tabs();
-    private get tabpanels();
+    private tabPairs;
+    private getSelectedIndex;
+    private getEventTabIndex;
+    private applySelection;
+    private syncPanelTabindex;
+    private hasAuthorManagedTabindex;
 }
 export {};

package/dist/types/toolbar/toolbar.d.ts

@@ -1,8 +1,11 @@
 export default class ToolbarElement extends HTMLElement {
+    private structureSync?;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private onInitialFocus;
+    private onFocus;
     private onKeyDown;
-    private focusControlAtIndex;
+    private syncControls;
+    private syncCurrentControl;
+    private get vertical();
     private get controls();
 }

package/dist/types/tooltip/tooltip.d.ts

@@ -1,28 +1,36 @@
 export default class TooltipElement extends HTMLElement {
     static delay: number;
-    static placement: string;
-    static tooltipClass: string;
-    private parent?;
-    private tooltip?;
+    static observedAttributes: string[];
+    private owner?;
     private timeout?;
-    private disabledObserver?;
-    private showing;
-    private cleanup?;
-    private prevInnerHTML?;
-    private focusKeyPressed;
-    private onMouseEnter;
-    private onFocus;
-    private onMouseLeave;
-    private onBlur;
+    private sync;
+    private ownerObserver?;
+    private siblingObserver?;
+    private managedDescription?;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     get disabled(): boolean;
     set disabled(val: boolean);
-    private onKeyDown;
-    private onKeyUp;
-    private isFocusTriggerKey;
-    show(): void;
+    show(owner?: HTMLElement | undefined): void;
     hide(): void;
+    private onToggle;
+    private onDocumentKeyDown;
+    private syncOwner;
+    private resolveOwner;
+    private resolveExplicitOwner;
+    private setOwner;
+    private onOwnerFocusIn;
+    private onOwnerFocusOut;
+    private onOwnerPointerEnter;
+    private onTooltipPointerEnter;
+    private onInteractivePointerLeave;
+    private onOwnerClick;
     private afterDelay;
-    private createTooltip;
+    private containsInteractiveTarget;
+    private updateManagedDescription;
+    private getDescriptionTokens;
+    private ensureTooltipId;
+    private supportsHoverInteraction;
+    private isOwnerDisabled;
 }

package/dist/types/utils.d.ts

@@ -1,4 +1,15 @@
-/**
- * Determine whether the user is trying to open a link in a new tab.
- */
-export declare function shouldOpenInNewTab(e: MouseEvent): boolean;
+export declare function createQueuedSync(element: HTMLElement, sync: () => void): {
+    queue: () => void;
+    disconnect(): void;
+};
+export declare function createQueuedElementSync(element: HTMLElement, options: MutationObserverInit, sync: () => void): {
+    observe(): void;
+    disconnect(): void;
+    queue: () => void;
+};
+export declare function getLookupRoot(element: HTMLElement): Document | ShadowRoot;
+export declare function getRovingIndexForKey(key: string, options: {
+    currentIndex: number;
+    length: number;
+    vertical: boolean;
+}): number | undefined;

package/package.json

@@ -1,34 +1,45 @@
 {
     "name": "inclusive-elements",
-    "version": "0.5.5",
-    "description": "Accessible, lightweight, unstyled implementations of common UI controls.",
-    "module": "dist/inclusive-elements.js",
+    "version": "0.6.1",
+    "description": "Accessible, lightweight, unstyled implementations of UI patterns that still need runtime help.",
     "type": "module",
+    "module": "dist/index.js",
     "types": "dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/types/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
     "license": "MIT",
     "repository": "tobyzerner/inclusive-elements",
     "files": [
-        "dist"
+        "dist",
+        "CHANGELOG.md",
+        "src/*/README.md"
     ],
     "sideEffects": false,
     "scripts": {
         "dev": "vite",
         "build": "tsc --noEmit && vite build && tsc --emitDeclarationOnly",
+        "prepare": "pnpm build",
+        "test": "vitest run",
         "preview": "vite preview",
         "release": "release-it"
     },
     "dependencies": {
-        "@floating-ui/dom": "^1.7.4",
-        "focus-trap": "^7.6.5",
-        "hello-goodbye": "^0.2.2",
-        "tabbable": "^6.2.0"
+        "tabbable": "^6.4.0",
+        "transition-kit": "^1.0.0"
     },
     "devDependencies": {
         "@release-it/conventional-changelog": "^5.1.1",
+        "jsdom": "^29.0.1",
         "prettier": "^2.8.8",
         "release-it": "^15.11.0",
-        "typescript": "^5.9.2",
-        "vite": "^4.5.14"
+        "typescript": "^5.9.3",
+        "vite": "^8.0.1",
+        "vitest": "^4.1.0"
     },
     "release-it": {
         "git": {
@@ -45,9 +56,6 @@
                 "infile": "CHANGELOG.md",
                 "header": "# Changelog"
             }
-        },
-        "hooks": {
-            "after:bump": "npm run build"
         }
     },
     "prettier": {

package/src/accordion/README.md

@@ -0,0 +1,36 @@
+# Accordion
+
+**A native-first accordion pattern using `<details name>`.**
+
+## Example
+
+```html
+<details name="faq">
+    <summary>Returns</summary>
+    <div>
+        <p>30 day returns.</p>
+    </div>
+</details>
+
+<details name="faq">
+    <summary>Warranty</summary>
+    <div>
+        <p>Two years included.</p>
+    </div>
+</details>
+```
+
+## Platform Requirements
+
+-   Requires modern browser support for grouped `<details name>` behavior.
+
+## Behavior
+
+-   Giving related `<details>` elements the same `name` makes them behave like an accordion, where opening one closes the others.
+-   The browser provides the disclosure semantics and keyboard interaction.
+-   This keeps the pattern lightweight and easy to style, without a custom wrapper element.
+
+## Further Reading
+
+-   [MDN: `<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details)
+-   [ARIA Authoring Practices Guide: Accordion Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)

package/src/alerts/README.md

@@ -0,0 +1,133 @@
+# Alerts
+
+**An accessible alert pattern with a supporting custom element.**
+
+`ui-alerts` manages a stack of alert elements, normalizes their announcement semantics, and handles timed dismissal.
+
+## Example
+
+```js
+import { AlertsElement } from 'inclusive-elements';
+
+window.customElements.define('ui-alerts', AlertsElement);
+
+const alerts = document.createElement('ui-alerts');
+document.body.appendChild(alerts);
+
+function createAlert(type, message) {
+    const el = document.createElement('div');
+    el.className = type;
+    el.textContent = message;
+    return el;
+}
+
+alerts.show(createAlert('error', 'There was an error'));
+alerts.speak('Hello stranger!');
+```
+
+## Behavior
+
+### Container
+
+-   `<ui-alerts>` is the container and timing manager for a stack of alert elements.
+-   Any alerts already present as children when the element connects are reprocessed in place so they are announced and animated.
+
+### Announcement Semantics
+
+-   Each alert can be announced politely or assertively.
+-   `show(..., { politeness })` takes precedence. Otherwise, existing authored live-region semantics on the alert are preserved before falling back to the element default.
+-   Polite alerts use `role="status"` and `aria-live="polite"`.
+-   Assertive alerts use `role="alert"` and `aria-live="assertive"`.
+
+### Timing And Replacement
+
+-   Alerts auto-dismiss after their configured duration.
+-   Hovering or focusing an alert clears its dismissal timer, and the full duration starts again when pointer or focus leaves the alert.
+-   Showing a new alert with an existing `key` dismisses the previous alert with that key before the new one is announced.
+
+## API
+
+```ts
+import type { AlertOptions } from 'inclusive-elements';
+
+// Default dismissal time for alerts that do not provide one.
+// Use 0 or a negative value to disable auto-dismiss by default.
+AlertsElement.duration = 10000;
+
+// Default politeness for alerts that do not provide one.
+AlertsElement.politeness = 'polite';
+
+const options: AlertOptions = {
+    // Reuse this key to replace an earlier alert with the same key.
+    key: 'save-complete',
+
+    // Override the default dismissal time for this alert only.
+    // Use 0 or a negative value to require manual dismissal.
+    duration: 5000,
+
+    // Use 'assertive' for urgent announcements that should interrupt.
+    politeness: 'assertive',
+};
+
+// Appends the element, announces it, starts dismissal timing,
+// and returns the key used for this alert.
+const key = alerts.show(el, options);
+
+// Dismiss a specific alert element.
+alerts.dismiss(el);
+
+// Dismiss any current alerts using this key.
+alerts.dismiss(key);
+
+// Dismiss every alert in the container.
+alerts.clear();
+
+// Announce plain text without creating your own element.
+alerts.speak(message, { politeness: 'polite' });
+```
+
+## Styling
+
+`ui-alerts` is unstyled. The supported animation hooks are:
+
+-   New alerts receive `enter-*` classes so CSS can animate them in.
+-   Dismissed alerts animate out using `leave-*` classes and are then removed.
+-   Existing alerts animate into their new positions using the `move` class.
+
+```css
+ui-alerts {
+    position: fixed;
+    top: 0;
+    right: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-end;
+    pointer-events: none;
+}
+
+ui-alerts > * {
+    pointer-events: auto;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    ui-alerts > .enter-active,
+    ui-alerts > .leave-active,
+    ui-alerts > .move {
+        transition: opacity 0.2s ease, transform 0.2s ease;
+    }
+
+    ui-alerts > .move {
+        transition: transform 0.2s ease;
+    }
+
+    ui-alerts > .enter-from,
+    ui-alerts > .leave-to {
+        opacity: 0;
+        transform: translateY(-0.5rem);
+    }
+}
+```
+
+## Further Reading
+
+-   [ARIA Authoring Practices Guide: Alert Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/)

package/src/dialog/README.md

@@ -0,0 +1,57 @@
+# Dialog
+
+**A native-first modal dialog pattern using `<dialog>`.**
+
+## Example
+
+```html
+<button command="show-modal" commandfor="delete-dialog">Delete</button>
+```
+
+```html
+<button type="button" id="delete-trigger">Delete</button>
+
+<script type="module">
+    document
+        .getElementById('delete-trigger')
+        ?.addEventListener('click', () => {
+            document.getElementById('delete-dialog')?.showModal();
+        });
+</script>
+```
+
+```html
+<dialog id="delete-dialog" aria-labelledby="delete-title">
+    <h2 id="delete-title">Delete item?</h2>
+    <p>This action cannot be undone.</p>
+
+    <form method="dialog">
+        <button value="cancel" autofocus>Cancel</button>
+        <button value="confirm">Delete</button>
+    </form>
+</dialog>
+```
+
+## Platform Requirements
+
+-   Requires modern browser support for `<dialog>`.
+-   Declarative `command="show-modal"` and `commandfor` buttons are newer platform features. Use `showModal()` when you need the imperative fallback.
+
+## Behavior
+
+-   `<dialog>` provides the modal container and top-layer behavior.
+-   Declarative `command="show-modal"` / `commandfor` buttons and imperative `showModal()` calls are both valid ways to open the dialog.
+-   The browser manages focus movement, Escape handling, and inert background behavior.
+
+## Accessibility Notes
+
+-   Give the dialog an accessible name with visible text and `aria-labelledby`, or with `aria-label` when no visible title fits.
+-   Provide an obvious dismiss action inside the dialog, not just Escape or backdrop dismissal.
+-   Use `<form method="dialog">` or `close()` intentionally so the close behavior is explicit in your markup and scripts.
+-   Native modal dialogs usually restore focus appropriately when they close. Only manage focus yourself when the opener is gone or your workflow needs a different destination.
+-   This pattern is for modal tasks that need blocking attention. For non-modal surfaces, use a popover or another native pattern instead.
+
+## Further Reading
+
+-   [MDN: `<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog)
+-   [ARIA Authoring Practices Guide: Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)

package/src/disclosure/README.md

@@ -0,0 +1,28 @@
+# Disclosure
+
+**A native-first disclosure pattern using `<details>` and `<summary>`.**
+
+## Example
+
+```html
+<details>
+    <summary>Shipping information</summary>
+    <div>
+        <p>Ships in 2–3 business days.</p>
+    </div>
+</details>
+```
+
+## Behavior
+
+-   `<summary>` acts as the built-in control for toggling the disclosure.
+-   The browser manages the open state and accessibility semantics.
+
+## Accessibility Notes
+
+-   Write summary text that clearly describes the hidden content, not generic labels such as "More" without context.
+
+## Further Reading
+
+-   [MDN: `<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details)
+-   [ARIA Authoring Practices Guide: Disclosure Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)

package/src/menu/README.md

@@ -0,0 +1,103 @@
+# Menu
+
+**An accessible menu pattern built on native popovers with a supporting custom element.**
+
+`ui-menu` keeps the popup surface native and adds the menu behaviors the platform does not provide by itself, including arrow-key navigation, typeahead, and submenu coordination.
+
+## Example
+
+```js
+import { MenuElement } from 'inclusive-elements';
+
+window.customElements.define('ui-menu', MenuElement);
+```
+
+```html
+<button type="button" popovertarget="actions-menu" aria-haspopup="menu">
+    Actions
+</button>
+
+<ui-menu id="actions-menu" popover data-placement="bottom-start">
+    <button type="button" role="menuitem">Edit</button>
+    <button type="button" role="menuitem">Archive</button>
+    <button
+        type="button"
+        role="menuitem"
+        popovertarget="more-menu"
+        aria-haspopup="menu"
+    >
+        More
+    </button>
+</ui-menu>
+
+<ui-menu id="more-menu" popover data-placement="right-start">
+    <button type="button" role="menuitem">Duplicate</button>
+    <button type="button" role="menuitem">Delete</button>
+</ui-menu>
+```
+
+## Platform Requirements
+
+-   Requires modern browser support for the Popover API.
+-   The styling examples use CSS anchor positioning.
+
+## Behavior
+
+### Structure
+
+-   Add `popover` to the root `<ui-menu>` and point a button at it with `popovertarget` and `aria-haspopup="menu"`.
+-   Give direct children a menu item role such as `role="menuitem"`. `ui-menu` adds `role="menu"` and `tabindex="-1"` to the menu itself and manages direct menuitem children with `tabindex="-1"` as well.
+
+### Navigation
+
+-   By default, menus are vertical. Arrow Down and Arrow Up move through the enabled items and wrap at the ends.
+-   Pressing Arrow Down or Arrow Up on the root trigger opens the menu and focuses the first or last enabled item.
+-   Typeahead matches and moves focus to enabled items by their `aria-label` when present, otherwise by their text content.
+
+### Horizontal Menus
+
+-   To make a horizontal popup menu, set `aria-orientation="horizontal"` on `<ui-menu>`. This keeps the element a `menu`, not a `menubar`, and works well for patterns such as reaction pickers.
+-   In a horizontal popup menu, Left and Right move through the enabled items and wrap at the ends.
+
+### Submenus
+
+-   To create a submenu, make a menu item that points at another `<ui-menu>` with `popovertarget` and `aria-haspopup="menu"`.
+-   Submenus open on click, hover, Enter, or Space, Right Arrow in vertical menus, and Down Arrow in horizontal menus.
+-   Submenus close with Left Arrow in vertical menus and Up Arrow in horizontal menus.
+
+### Closing
+
+-   Clicking a regular menu item closes the open menu tree.
+-   Escape also closes the open menu tree.
+-   Tab closes the open menu tree before normal tab order continues.
+
+## API
+
+```ts
+// Time in milliseconds before the accumulated typeahead search resets.
+MenuElement.searchDelay = 800;
+```
+
+## Styling
+
+`ui-menu` is unstyled. Position the popover surface with native anchor positioning:
+
+```css
+[popover] {
+    position: fixed;
+    position-anchor: auto;
+}
+
+[popover][data-placement='bottom-start'] {
+    position-area: block-end span-inline-start;
+}
+
+[popover][data-placement='right-start'] {
+    position-area: inline-end span-block-start;
+}
+```
+
+## Further Reading
+
+-   [ARIA Authoring Practices Guide: Menu and Menubar Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)
+-   [MDN: Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API/Using)