a11y-alert-dialog 0.1.0

package/A11Y.md

@@ -0,0 +1,207 @@
+# Accessibility Contract (A11Y.md)
+
+This document defines the **non-negotiable accessibility guarantees** of the
+Accessible Alert library.
+
+If any change violates this contract, it is considered a **breaking bug**,
+not a feature request.
+
+Accessibility is **not optional** in this project.
+
+---
+
+## 🎯 Core Principle
+
+> If a user can operate a keyboard, they must be able to fully operate this dialog.
+
+This library is designed to work for:
+- Keyboard-only users
+- Screen reader users
+- Users with motor impairments
+- Users relying on assistive technologies (switch devices, voice control)
+
+---
+
+## 🚫 Non-Negotiable Rules
+
+The following rules **must never be disabled, bypassed, or overridden**.
+
+---
+
+## 1. Focus Management
+
+### 1.1 Before Opening a Dialog
+- The currently focused element **MUST** be stored.
+- If no element is focused, `document.body` is used as fallback.
+
+### 1.2 When Dialog Opens
+- Focus **MUST** move inside the dialog immediately.
+- Focus **MUST NOT** remain on background content.
+- Initial focus priority:
+  1. Primary action button (Confirm)
+  2. First focusable element inside the dialog
+
+### 1.3 While Dialog Is Open
+- Focus **MUST NOT** escape the dialog.
+- Background content **MUST NOT** be focusable.
+
+### 1.4 When Dialog Closes
+- Focus **MUST** be restored to the previously focused element.
+- If the original element no longer exists, focus moves to:
+  - The closest available parent
+  - Or `document.body` as final fallback
+
+❌ Losing focus after closing is a **critical accessibility failure**.
+
+---
+
+## 2. Focus Trap
+
+### Requirements
+- `Tab` and `Shift + Tab` navigation **MUST** loop inside the dialog.
+- Focus trapping **MUST** work without relying on CSS hacks.
+- Focus trap **MUST** handle dynamically added or removed focusable elements.
+
+### Forbidden
+- Disabling focus trap
+- Allowing focus to move into the page behind the dialog
+
+---
+
+## 3. Keyboard Interaction
+
+Keyboard support is **mandatory and always enabled**.
+
+### Required Key Bindings
+
+| Key | Behavior |
+|----|---------|
+| Tab | Move focus forward |
+| Shift + Tab | Move focus backward |
+| Enter | Activate primary action |
+| Esc | Cancel or close dialog |
+
+### Rules
+- Keyboard behavior **MUST NOT** depend on mouse interaction.
+- Keyboard handling **MUST NOT** interfere with text input fields.
+- `Esc` **MUST ALWAYS** close the dialog.
+
+---
+
+## 4. Screen Reader Semantics
+
+### Dialog Roles
+- Use `role="dialog"` for normal dialogs
+- Use `role="alertdialog"` for destructive or dangerous actions
+
+### ARIA Attributes
+Each dialog **MUST** include:
+- `aria-modal="true"`
+- `aria-labelledby` referencing the dialog title
+- `aria-describedby` referencing the dialog description (if present)
+
+### Announcements
+- Screen readers **MUST** announce:
+  - Dialog type (dialog / alert dialog)
+  - Title
+  - Description
+- Announcement **MUST** occur immediately when the dialog opens.
+
+---
+
+## 5. Visual & Motion Safety
+
+### Motion
+- Respect `prefers-reduced-motion`
+- Avoid animations that:
+  - Cause dizziness
+  - Delay keyboard interaction
+  - Block screen reader announcements
+
+### Visibility
+- Focused elements **MUST** have visible focus indicators.
+- Focus indicators **MUST NOT** be removed.
+
+---
+
+## 6. Timing & Control
+
+### Forbidden Behaviors
+- Auto-close timers
+- Forced timeouts
+- Auto-confirm actions
+
+Users **MUST** remain in control at all times.
+
+---
+
+## 7. HTML Semantics
+
+### Required
+- Use native interactive elements:
+  - `<button>` for actions
+  - `<input>` for form fields
+
+### Forbidden
+- Clickable `<div>` or `<span>` for core actions
+- Custom elements without proper ARIA roles
+
+Voice control and assistive tools depend on correct semantics.
+
+---
+
+## 8. API-Level Constraints
+
+The public API **MUST NOT** expose options that allow:
+
+- Disabling focus management
+- Disabling keyboard handling
+- Injecting custom HTML for critical controls
+- Bypassing screen reader semantics
+
+If an API option can break accessibility, it must be removed.
+
+---
+
+## 9. Testing Requirements
+
+### Manual Testing (Required)
+Every release **MUST** be tested with:
+- Keyboard only (no mouse)
+- At least one screen reader:
+  - NVDA (Windows) or
+  - VoiceOver (macOS)
+
+### Automated Testing
+Recommended (not sufficient alone):
+- jest-axe
+- Keyboard navigation tests (Playwright)
+
+Automated tests **DO NOT** replace manual accessibility testing.
+
+---
+
+## 10. Definition of Done (Accessibility)
+
+A feature is considered **DONE** only if:
+
+- It works without a mouse
+- It works with a keyboard only
+- It announces correctly in a screen reader
+- It does not break focus restoration
+- It does not violate any rule in this document
+
+---
+
+## ⚠️ Final Warning
+
+Accessibility bugs are treated as **critical bugs**, not minor issues.
+
+No feature, customization, or visual improvement is allowed to violate this contract.
+
+---
+
+## 💬 Philosophy
+
+> Accessibility is not about edge cases.  
+> It is about real people trying to use your software.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 xShiroeNguyenx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# Accessible Alert
+
+> An alert / dialog library that works without a mouse.
+
+**Accessible Alert** is a **framework-agnostic JavaScript library** for displaying
+`alert`, `confirm`, and `prompt` dialogs with **accessibility-first (a11y-first)**
+design.
+
+If you can use a **keyboard**, you can use this library.
+
+---
+
+## ✨ Why does this library exist?
+
+Most alert/modal libraries:
+- Prioritize visuals and animations
+- Treat accessibility as an afterthought
+- Break keyboard navigation and screen readers easily
+
+👉 **Accessible Alert** is built the opposite way:
+
+> Accessibility is the foundation, not a feature added later.
+
+---
+
+## ✅ Accessibility Guarantees (A11Y Contract)
+
+This library **always guarantees**:
+
+- No mouse required
+- Fully usable with keyboard only (Tab / Enter / Esc)
+- Correct focus management at all times
+- Focus is never lost after closing dialogs
+- Proper screen reader announcements
+- No auto-close behaviors that steal control from users
+
+Standards:
+- WCAG 2.1 AA
+- WAI-ARIA Authoring Practices (Dialog)
+
+---
+
+## 📦 Installation
+
+### NPM
+```bash
+npm install accessible-alert
+```
+
+### CDN
+```html
+<script src="https://unpkg.com/accessible-alert"></script>
+```
+
+---
+
+## 🚀 Basic Usage
+
+### Alert
+```js
+await alert("Saved successfully")
+```
+
+### Confirm
+```js
+const ok = await confirm({
+  title: "Delete user",
+  description: "This action cannot be undone",
+  danger: true
+})
+
+if (ok) {
+  deleteUser()
+}
+```
+
+### Prompt
+```js
+const name = await prompt({
+  title: "Your name",
+  placeholder: "Enter your name"
+})
+```
+
+---
+
+## ⌨️ Keyboard Behavior (Always Enabled)
+
+| Key | Action |
+|----|-------|
+| Tab | Move forward within the dialog |
+| Shift + Tab | Move backward |
+| Enter | Confirm primary action |
+| Esc | Cancel / Close dialog |
+
+Keyboard support **cannot be disabled**.
+
+---
+
+## 🧠 How Accessibility Is Handled
+
+### Focus Management
+- Saves the currently focused element before opening
+- Automatically moves focus into the dialog
+- Restores focus to the original element after closing
+
+### Focus Trap
+- Tab navigation is trapped inside the dialog
+- Focus never escapes to the background
+- No CSS hacks or pointer-event tricks
+
+### Screen Reader Support
+- Uses `role="dialog"` or `role="alertdialog"`
+- Proper `aria-labelledby` and `aria-describedby`
+- Dialog content is announced immediately on open
+
+---
+
+## 🧩 API Design Principles
+
+- Promise-based API
+- No callbacks
+- No configuration options that can break accessibility
+- No custom HTML injection for critical controls
+
+```js
+await confirm({ title: "Are you sure?" })
+```
+
+> If an API allows breaking accessibility, the API is wrong.
+
+---
+
+## ❌ What This Library Does NOT Support
+
+To protect accessibility, this library intentionally does NOT support:
+
+- Auto-close timers
+- Disabling focus trapping
+- Custom button HTML
+- Complex animations
+- Theme systems
+- Toast-style notifications
+
+👉 If you want flashy UI effects, this library is **not** for you.
+
+---
+
+## 🧪 Testing
+
+Manually tested with:
+- Keyboard-only navigation
+- NVDA (Windows)
+- VoiceOver (macOS)
+
+Automated testing includes:
+- jest-axe
+- Playwright keyboard tests
+
+---
+
+## 🎯 When Should You Use This Library?
+
+✔ Internal tools  
+✔ Admin dashboards  
+✔ SaaS products  
+✔ Enterprise / Government / Fintech  
+✔ Any project where accessibility is a real requirement  
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 💬 Philosophy
+
+> “If you can use a keyboard, you can use this alert.”

package/dist/index.cjs

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  alert: () => alert,
+  confirm: () => confirm
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/focus.ts
+var previousFocus = null;
+function saveFocus() {
+  previousFocus = document.activeElement;
+}
+function restoreFocus() {
+  if (previousFocus && document.contains(previousFocus)) {
+    previousFocus.focus();
+  } else {
+    document.body.focus();
+  }
+}
+
+// src/core/focusTrap.ts
+function trapFocus(container) {
+  function getFocusable() {
+    return Array.from(
+      container.querySelectorAll(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      )
+    );
+  }
+  function handle(e) {
+    if (e.key !== "Tab") return;
+    const items = getFocusable();
+    if (!items.length) return;
+    const first = items[0];
+    const last = items[items.length - 1];
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  }
+  container.addEventListener("keydown", handle);
+  return () => container.removeEventListener("keydown", handle);
+}
+
+// src/core/Dialog.ts
+function openDialog(options) {
+  return new Promise((resolve) => {
+    saveFocus();
+    const overlay = document.createElement("div");
+    overlay.style.position = "fixed";
+    overlay.style.inset = "0";
+    overlay.style.background = "rgba(0,0,0,0.4)";
+    const dialog = document.createElement("div");
+    dialog.setAttribute("role", options.role ?? "dialog");
+    dialog.setAttribute("aria-modal", "true");
+    dialog.style.background = "white";
+    dialog.style.padding = "1rem";
+    dialog.style.maxWidth = "400px";
+    dialog.style.margin = "20vh auto";
+    const title = document.createElement("h2");
+    title.id = "dialog-title";
+    title.textContent = options.title;
+    dialog.setAttribute("aria-labelledby", title.id);
+    dialog.appendChild(title);
+    if (options.description) {
+      const desc = document.createElement("p");
+      desc.id = "dialog-desc";
+      desc.textContent = options.description;
+      dialog.setAttribute("aria-describedby", desc.id);
+      dialog.appendChild(desc);
+    }
+    const actions = document.createElement("div");
+    const btnConfirm = document.createElement("button");
+    btnConfirm.textContent = options.confirmText ?? "OK";
+    actions.appendChild(btnConfirm);
+    let btnCancel = null;
+    if (options.cancelText !== null) {
+      btnCancel = document.createElement("button");
+      btnCancel.textContent = options.cancelText ?? "Cancel";
+      actions.appendChild(btnCancel);
+    }
+    dialog.appendChild(actions);
+    overlay.appendChild(dialog);
+    document.body.appendChild(overlay);
+    const releaseTrap = trapFocus(dialog);
+    btnConfirm.focus();
+    function close(result) {
+      releaseTrap();
+      overlay.remove();
+      restoreFocus();
+      resolve(result);
+    }
+    btnConfirm.onclick = () => close(true);
+    btnCancel && (btnCancel.onclick = () => close(false));
+    dialog.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") close(false);
+    });
+  });
+}
+
+// src/api/alert.ts
+function alert(message) {
+  return openDialog({
+    title: message,
+    role: "dialog",
+    confirmText: "OK",
+    cancelText: null
+  });
+}
+
+// src/api/confirm.ts
+function confirm(options) {
+  return openDialog({
+    ...options,
+    role: "alertdialog",
+    confirmText: "Confirm",
+    cancelText: "Cancel"
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  alert,
+  confirm
+});

package/dist/index.d.cts

@@ -0,0 +1,8 @@
+declare function alert(message: string): Promise<boolean>;
+
+declare function confirm(options: {
+    title: string;
+    description?: string;
+}): Promise<boolean>;
+
+export { alert, confirm };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare function alert(message: string): Promise<boolean>;
+
+declare function confirm(options: {
+    title: string;
+    description?: string;
+}): Promise<boolean>;
+
+export { alert, confirm };

package/dist/index.js

@@ -0,0 +1,119 @@
+// src/core/focus.ts
+var previousFocus = null;
+function saveFocus() {
+  previousFocus = document.activeElement;
+}
+function restoreFocus() {
+  if (previousFocus && document.contains(previousFocus)) {
+    previousFocus.focus();
+  } else {
+    document.body.focus();
+  }
+}
+
+// src/core/focusTrap.ts
+function trapFocus(container) {
+  function getFocusable() {
+    return Array.from(
+      container.querySelectorAll(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      )
+    );
+  }
+  function handle(e) {
+    if (e.key !== "Tab") return;
+    const items = getFocusable();
+    if (!items.length) return;
+    const first = items[0];
+    const last = items[items.length - 1];
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  }
+  container.addEventListener("keydown", handle);
+  return () => container.removeEventListener("keydown", handle);
+}
+
+// src/core/Dialog.ts
+function openDialog(options) {
+  return new Promise((resolve) => {
+    saveFocus();
+    const overlay = document.createElement("div");
+    overlay.style.position = "fixed";
+    overlay.style.inset = "0";
+    overlay.style.background = "rgba(0,0,0,0.4)";
+    const dialog = document.createElement("div");
+    dialog.setAttribute("role", options.role ?? "dialog");
+    dialog.setAttribute("aria-modal", "true");
+    dialog.style.background = "white";
+    dialog.style.padding = "1rem";
+    dialog.style.maxWidth = "400px";
+    dialog.style.margin = "20vh auto";
+    const title = document.createElement("h2");
+    title.id = "dialog-title";
+    title.textContent = options.title;
+    dialog.setAttribute("aria-labelledby", title.id);
+    dialog.appendChild(title);
+    if (options.description) {
+      const desc = document.createElement("p");
+      desc.id = "dialog-desc";
+      desc.textContent = options.description;
+      dialog.setAttribute("aria-describedby", desc.id);
+      dialog.appendChild(desc);
+    }
+    const actions = document.createElement("div");
+    const btnConfirm = document.createElement("button");
+    btnConfirm.textContent = options.confirmText ?? "OK";
+    actions.appendChild(btnConfirm);
+    let btnCancel = null;
+    if (options.cancelText !== null) {
+      btnCancel = document.createElement("button");
+      btnCancel.textContent = options.cancelText ?? "Cancel";
+      actions.appendChild(btnCancel);
+    }
+    dialog.appendChild(actions);
+    overlay.appendChild(dialog);
+    document.body.appendChild(overlay);
+    const releaseTrap = trapFocus(dialog);
+    btnConfirm.focus();
+    function close(result) {
+      releaseTrap();
+      overlay.remove();
+      restoreFocus();
+      resolve(result);
+    }
+    btnConfirm.onclick = () => close(true);
+    btnCancel && (btnCancel.onclick = () => close(false));
+    dialog.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") close(false);
+    });
+  });
+}
+
+// src/api/alert.ts
+function alert(message) {
+  return openDialog({
+    title: message,
+    role: "dialog",
+    confirmText: "OK",
+    cancelText: null
+  });
+}
+
+// src/api/confirm.ts
+function confirm(options) {
+  return openDialog({
+    ...options,
+    role: "alertdialog",
+    confirmText: "Confirm",
+    cancelText: "Cancel"
+  });
+}
+export {
+  alert,
+  confirm
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "a11y-alert-dialog",
+  "version": "0.1.0",
+  "description": "Accessibility-first alert and dialog library that works without a mouse",
+  "license": "MIT",
+  "author": "Nguyen Khanh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nguyenkhanh/a11y-alert-dialog"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "A11Y.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "playwright test",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "alert",
+    "dialog",
+    "modal",
+    "keyboard",
+    "wcag",
+    "aria"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "@playwright/test": "^1.40.0"
+  }
+}