Core Primitives

import { aria } from "@compa11y/core";

aria.hide(element);                         // aria-hidden="true"
aria.show(element);                         // removes aria-hidden
aria.setExpanded(element, true);            // aria-expanded="true"
aria.setSelected(element, true);            // aria-selected="true"
aria.setChecked(element, "mixed");          // aria-checked="mixed"
aria.setDisabled(element, true);            // aria-disabled="true"
aria.setRequired(element, true);            // aria-required="true"
aria.setInvalid(element, true);             // aria-invalid="true"
aria.setLabel(element, "Close");            // aria-label="Close"
aria.setLabelledBy(element, "title-id");    // aria-labelledby="title-id"
aria.setDescribedBy(element, "hint-id");    // aria-describedby="hint-id"
aria.setControls(element, "menu-id");       // aria-controls="menu-id"
aria.setLive(element, "polite");            // aria-live="polite"
aria.setRole(element, "dialog");            // role="dialog"
aria.setActiveDescendant(element, "opt-3"); // aria-activedescendant="opt-3"
aria.setOrientation(element, "vertical");   // aria-orientation="vertical"
aria.setCurrent(element, "page");           // aria-current="page"
aria.setPressed(element, true);             // aria-pressed="true"
aria.setModal(element, true);               // aria-modal="true"
aria.setHasPopup(element, "menu");          // aria-haspopup="menu"
aria.setBusy(element, true);                // aria-busy="true"

import { buildAriaProps } from "@compa11y/core";

const ariaProps = buildAriaProps({
  role: "dialog",
  label: "Settings",
  modal: true,
  expanded: false,
});
// { role: "dialog", "aria-label": "Settings", "aria-modal": "true", "aria-expanded": "false" }

<div {...ariaProps} />

import { mergeAriaIds } from "@compa11y/core";

const describedBy = mergeAriaIds(hintId, hasError ? errorId : null);
// "hint-1 error-1"  or  "hint-1"  depending on hasError

<input aria-describedby={describedBy} />

import { hasAccessibleName } from "@compa11y/core";

if (!hasAccessibleName(button)) {
  console.warn("Button is missing an accessible name");
}

import { createFocusTrap, hasFocusTrap, getActiveFocusTrap } from "@compa11y/core";

const trap = createFocusTrap(modalElement, {
  initialFocus: closeButton,         // Where to focus on activation
  returnFocus: true,                 // Return focus to previous element on deactivation
  escapeDeactivates: true,           // Escape key deactivates trap
  clickOutsideDeactivates: false,    // Click outside behavior
  onDeactivate: () => closeModal(),  // Callback on deactivation
});

trap.activate();    // Start trapping
trap.pause();       // Pause (for nested traps)
trap.unpause();     // Resume
trap.deactivate();  // Stop trapping, restore focus
trap.destroy();     // Cleanup without callback

// Stack management
hasFocusTrap();        // Any trap active?
getActiveFocusTrap();  // Get the topmost trap

import { initFocusVisible, isFocusVisible, getLastFocusSource, focusWithVisibleRing } from "@compa11y/core";

// Initialize once at app startup
const cleanup = initFocusVisible();

// Check focus type
isFocusVisible();               // true if last focus was keyboard-initiated
getLastFocusSource();           // 'keyboard' | 'mouse' | 'touch' | 'unknown'
hasVisibleFocus(element);       // Does this specific element have visible focus?

// Force visible focus (useful for programmatic focus in modals)
focusWithVisibleRing(firstButton);

// Manual override
setFocusVisible(element, true);

import { createFocusScope } from "@compa11y/core";

const scope = createFocusScope(container, {
  contain: true,        // Tab wraps within container
  restoreFocus: true,   // Restore focus on destroy
  autoFocus: true,      // Focus first element immediately
});

scope.focusFirst();
scope.focusLast();
scope.focusNext({ wrap: true });
scope.focusPrevious({ wrap: true });
scope.focusAt(2);
scope.getFocused();     // Currently focused element
scope.getElements();    // All focusable elements in scope
scope.destroy();        // Cleanup

import { createRovingTabindex } from "@compa11y/core";

const roving = createRovingTabindex(toolbar, '[role="button"]', {
  initialIndex: 0,
  orientation: "horizontal",
  wrap: true,
  onSelectionChange: (index, element) => console.log("Selected:", index),
});

roving.next();
roving.previous();
roving.first();
roving.last();
roving.goto(2);
roving.getIndex();  // Current index
roving.update();    // Refresh when DOM changes
roving.destroy();   // Cleanup

import { findFocusNeighbor } from "@compa11y/core";

const neighbor = findFocusNeighbor(deletedItem, {
  scope: listContainer,  // Search within (default: parent element)
  prefer: "previous",    // Try previous first, then next (default)
});

neighbor?.focus();

import { createFocusReturn } from "@compa11y/core";

const focusReturn = createFocusReturn();

// Before opening modal
focusReturn.save();              // Saves document.activeElement
focusReturn.save(triggerButton); // or save a specific element

// After closing modal
focusReturn.return();  // Focuses saved element, or its nearest neighbor

// With options
focusReturn.return({
  prefer: "next",            // Try next neighbor first if saved element is gone
  fallback: someOtherButton, // Last resort fallback
});

focusReturn.element; // Read the saved element (readonly)
focusReturn.clear(); // Clear without focusing

import { createKeyboardManager } from "@compa11y/core";

const kb = createKeyboardManager(
  {
    ArrowDown: () => focusNext(),
    ArrowUp: () => focusPrevious(),
    Enter: () => selectItem(),
    Escape: () => close(),
    "Ctrl+A": () => selectAll(),
    Space: () => toggleItem(),
  },
  {
    preventDefault: true,              // Default: true
    stopPropagation: true,             // Default: true
    targetSelector: '[role="option"]', // Only handle when target matches
  }
);

kb.attach(listElement);          // Start listening
kb.on("Delete", () => remove()); // Add handler after creation
kb.off("Delete");                // Remove a handler
kb.detach();                     // Stop listening
kb.destroy();                    // Full cleanup

import { normalizeKey, getKeyCombo } from "@compa11y/core";

normalizeKey(event); // ' ' → 'Space', 'Esc' → 'Escape', 'Left' → 'ArrowLeft'
getKeyCombo(event);  // 'Ctrl+A', 'Shift+Enter', 'Meta+Space'

import { KeyboardPatterns } from "@compa11y/core";

// Menu / Listbox pattern
KeyboardPatterns.menu({ onUp, onDown, onEnter, onEscape, onHome, onEnd });

// Tabs pattern
KeyboardPatterns.tabs({ onLeft, onRight, onHome, onEnd });

// Dialog pattern
KeyboardPatterns.dialog({ onEscape });

// 2D Grid pattern
KeyboardPatterns.grid({ onUp, onDown, onLeft, onRight, onHome, onEnd, onCtrlHome, onCtrlEnd });

import { createTypeAhead } from "@compa11y/core";

const typeAhead = createTypeAhead(["Apple", "Apricot", "Banana", "Cherry"], {
  timeout: 500, // Reset after 500ms of no typing
});

typeAhead.type("a");    // Returns 'Apple'
typeAhead.type("p");    // Returns 'Apricot' (search is now 'ap')
// After 500ms, resets
typeAhead.type("b");    // Returns 'Banana'
typeAhead.reset();      // Manual reset
typeAhead.getSearch();  // Current search string

import { initAnnouncer } from "@compa11y/core";

// Call once at app startup
const cleanup = initAnnouncer();

import {
  announce,
  announcePolite,
  announceAssertive,
  announceStatus,
  announceError,
  announceProgress,
  queueAnnouncement,
  clearAnnouncements,
} from "@compa11y/core";

// Basic announcements
announce("Form submitted");                         // Polite by default
announcePolite("3 search results found");           // Non-interrupting
announceAssertive("Error: invalid email address");  // Interrupts current speech

// Convenience functions
announceStatus("Saved");                               // Polite status update
announceError("Connection lost");                      // Assertive error
announceProgress(5, 10);                               // "5 of 10"
announceProgress(5, 10, "Step {current} of {total}"); // "Step 5 of 10"

// Advanced options
announce("Updated", {
  politeness: "polite",
  delay: 100,           // Delay in ms
  clearPrevious: true,  // Clear previous messages first
  timeout: 7000,        // Auto-clear after 7s (default)
});

// Queue rapid announcements (debounced)
queueAnnouncement("Processing...", { debounce: 300 });

// Clear all pending announcements
clearAnnouncements();

import { createAnnouncer } from "@compa11y/core";

const myAnnouncer = createAnnouncer({ politeness: "polite" });
myAnnouncer.announce("Done");
myAnnouncer.assertive("Error!");

import { generateId, generateIds, createIdScope, resetIdCounter } from "@compa11y/core";

generateId();            // 'compa11y-1'
generateId("button");    // 'compa11y-button-2'

const ids = generateIds(["label", "input", "error"] as const, "search");
// { label: 'compa11y-search-3-label', input: 'compa11y-search-3-input', error: 'compa11y-search-3-error' }

const scope = createIdScope("dropdown");
scope.id;                    // 'compa11y-dropdown-4'
scope.generate("trigger");   // 'compa11y-dropdown-4-trigger'
scope.generate("menu");      // 'compa11y-dropdown-4-menu'

resetIdCounter(); // For testing only

import {
  isBrowser,
  isMac,
  isIOS,
  isAndroid,
  isWindows,
  isTouchDevice,
  prefersReducedMotion,
  prefersHighContrast,
  prefersDarkMode,
  getScreenReaderHints,
  createMediaQueryListener,
} from "@compa11y/core";

isBrowser();       // true if running in browser (not SSR)
isMac();           // true on macOS
isIOS();           // true on iOS
isAndroid();       // true on Android
isWindows();       // true on Windows
isTouchDevice();   // true if device supports touch

// User preferences
prefersReducedMotion(); // true if user prefers reduced motion
prefersHighContrast();  // true if user prefers high contrast
prefersDarkMode();      // true if user prefers dark color scheme

// Screen reader hints (not 100% reliable)
const { possibleScreenReader, forcedColors } = getScreenReaderHints();

// Listen for preference changes
const cleanup = createMediaQueryListener(
  "(prefers-reduced-motion: reduce)",
  (prefersReduced) => setAnimations(!prefersReduced)
);

import { warn, checks, createComponentWarnings, setWarningHandler } from "@compa11y/core";

// Direct warning
warn("Button has no accessible label", "Button");

// Pre-built checks
checks.hasLabel(element, "Button");          // Warns if no accessible name
checks.hasLabelledBy(element, "Combobox");   // Warns if no aria-labelledby

// Component-specific warning factory
const warnings = createComponentWarnings("MyComponent");
warnings.missingProp("aria-label");
warnings.invalidValue("size", "huge", ["sm", "md", "lg"]);

// Custom warning handler (e.g., to throw in tests)
setWarningHandler((message, component) => {
  throw new Error(`[${component}] ${message}`);
});