@praxiis/ui 0.0.1 → 0.0.2

package/src/primitives/overlays/Modal/Modal.a11y.ts

@@ -0,0 +1,64 @@
+/**
+ * Modal Accessibility Helpers
+ *
+ * Generates accessibility props for the Modal component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Modal needs proper label and modal indication
+ * - 1.3.1 Info and Relationships: State must be programmatically determinable
+ * - 2.4.3 Focus Order: Modal must trap focus when visible
+ *
+ * The modal uses accessibilityViewIsModal to indicate to assistive
+ * technologies that content behind the modal is not accessible.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import type { ModalA11yParams, ModalA11yProps, ModalCloseButtonA11yParams } from "./Modal.types";
+
+/**
+ * Generate accessibility props for Modal container.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the Modal container
+ *
+ * @warning Logs console warning in dev if title and accessibilityLabel are both missing
+ *
+ * @example
+ * const a11yProps = getModalA11y({
+ *   title: "Confirm Delete",
+ *   position: "center",
+ * });
+ * // { accessible: true, accessibilityRole: "none", accessibilityLabel: "Confirm Delete dialog", accessibilityViewIsModal: true }
+ */
+export function getModalA11y(params: ModalA11yParams): ModalA11yProps {
+  const { title, position, accessibilityLabel, fallbackTitle, positionLabels } = params;
+
+  if (!accessibilityLabel && !title && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[Modal] Missing title or accessibilityLabel (WCAG 4.1.2)"
+    );
+  }
+
+  const positionLabel = positionLabels[position];
+
+  return {
+    accessible: true,
+    accessibilityRole: "none",
+    accessibilityLabel:
+      accessibilityLabel || `${title || fallbackTitle} ${positionLabel}`,
+    accessibilityViewIsModal: true,
+  };
+}
+
+/**
+ * Get accessibility props for the modal close button.
+ */
+export function getModalCloseButtonA11yProps(params: ModalCloseButtonA11yParams) {
+  return {
+    accessible: true as const,
+    accessibilityRole: "button" as const,
+    accessibilityLabel: params.closeLabel,
+    accessibilityHint: params.closeHint,
+  };
+}