@praxiis/ui 0.0.1 → 0.0.2

package/src/primitives/feedback/ProgressBar/ProgressBar.a11y.ts

@@ -0,0 +1,68 @@
+/**
+ * ProgressBar Accessibility Helpers
+ *
+ * Generates accessibility props for the ProgressBar component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Progress bars need proper role and value
+ * - The progressbar role requires min, max, and now values
+ *
+ * The progress bar uses "progressbar" role with explicit value range
+ * to provide determinate progress feedback to assistive technologies.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role
+ */
+
+import { clampProgress, progressToPercent } from "./ProgressBar.helpers";
+import {
+  ProgressBarA11yParams,
+  ProgressBarA11yProps,
+} from "./ProgressBar.types";
+
+/**
+ * Generate accessibility props for ProgressBar.
+ *
+ * Creates a determinate progress indicator with:
+ * - accessibilityRole: "progressbar"
+ * - accessibilityValue: { min: 0, max: 100, now: current percentage }
+ * - accessibilityLabel: Description of what's in progress
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the ProgressBar component
+ *
+ * @warning Logs console warning in dev if accessibilityLabel missing
+ *
+ * @example
+ * const a11yProps = getProgressBarA11y({
+ *   progress: 0.75,
+ *   accessibilityLabel: "File upload"
+ * });
+ * // {
+ * //   accessibilityRole: "progressbar",
+ * //   accessibilityLabel: "File upload",
+ * //   accessibilityValue: { min: 0, max: 100, now: 75 }
+ * // }
+ */
+export function getProgressBarA11y(
+  params: ProgressBarA11yParams
+): ProgressBarA11yProps {
+  const { progress, accessibilityLabel, fallbackLabel } = params;
+
+  if (!accessibilityLabel && process.env.NODE_ENV !== "production") {
+    console.warn("[ProgressBar] Missing accessibilityLabel (WCAG 4.1.2)");
+  }
+
+  const clampedProgress = clampProgress(progress);
+  const progressPercent = progressToPercent(clampedProgress);
+
+  return {
+    accessibilityRole: "progressbar",
+    accessibilityLabel: accessibilityLabel || fallbackLabel,
+    accessibilityValue: {
+      min: 0,
+      max: 100,
+      now: progressPercent,
+    },
+  };
+}

package/src/primitives/feedback/Skeleton/Skeleton.a11y.ts

@@ -0,0 +1,46 @@
+/**
+ * Skeleton Accessibility Helpers
+ *
+ * Generates accessibility props for the Skeleton component.
+ *
+ * WCAG References:
+ * - 1.3.1 Info and Relationships: Decorative content should be hidden
+ * - 4.1.2 Name, Role, Value: Non-interactive elements need appropriate roles
+ *
+ * Skeletons are purely decorative loading placeholders and should be
+ * completely hidden from assistive technologies. The actual loading
+ * state should be communicated through other means (e.g., live regions,
+ * loading spinners with proper labels).
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships
+ */
+
+import { SkeletonA11yParams, SkeletonA11yProps } from "./Skeleton.types";
+
+/**
+ * Generate accessibility props for Skeleton.
+ *
+ * Skeletons are hidden from screen readers as they are decorative.
+ * Loading state should be communicated through semantic live regions
+ * or dedicated loading indicators with proper accessibility labels.
+ *
+ * @param _params - Accessibility parameters (currently unused, reserved for future)
+ * @returns Object to spread onto the Skeleton component
+ *
+ * @example
+ * const a11yProps = getSkeletonA11y({});
+ * // {
+ * //   accessible: false,
+ * //   accessibilityRole: "none",
+ * //   accessibilityElementsHidden: true,
+ * //   importantForAccessibility: "no-hide-descendants"
+ * // }
+ */
+export function getSkeletonA11y(_params: SkeletonA11yParams = {}): SkeletonA11yProps {
+  return {
+    accessible: false,
+    accessibilityRole: "none",
+    accessibilityElementsHidden: true,
+    importantForAccessibility: "no-hide-descendants",
+  };
+}

package/src/primitives/feedback/Spinner/Spinner.a11y.ts

@@ -0,0 +1,47 @@
+/**
+ * Spinner Accessibility Helpers
+ *
+ * Generates accessibility props for the Spinner component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Spinners need proper role and label
+ * - 2.2.2 Pause, Stop, Hide: Users should be informed of loading state
+ *
+ * The spinner uses "progressbar" role with busy state to indicate
+ * that content is loading and the interface may change.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import { SpinnerA11yParams, SpinnerA11yProps } from "./Spinner.types";
+
+/**
+ * Generate accessibility props for Spinner.
+ *
+ * Spinners are announced as indeterminate progress indicators.
+ * The busy state informs assistive technology that the UI is updating.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the Spinner component
+ *
+ * @warning Logs console warning in dev if accessibilityLabel missing
+ *
+ * @example
+ * const a11yProps = getSpinnerA11y({ accessibilityLabel: "Loading messages" });
+ * // { accessibilityRole: "progressbar", accessibilityLabel: "Loading messages", accessibilityState: { busy: true } }
+ */
+export function getSpinnerA11y(
+  params: SpinnerA11yParams
+): SpinnerA11yProps {
+  const { accessibilityLabel, fallbackLabel } = params;
+
+  if (!accessibilityLabel && process.env.NODE_ENV !== "production") {
+    console.warn("[Spinner] Missing accessibilityLabel (WCAG 4.1.2)");
+  }
+
+  return {
+    accessibilityLabel: accessibilityLabel || fallbackLabel,
+    accessibilityRole: "progressbar",
+    accessibilityState: { busy: true },
+  };
+}

package/src/primitives/feedback/Toast/Toast.a11y.ts

@@ -0,0 +1,75 @@
+/**
+ * Toast Accessibility Helpers
+ *
+ * Generates accessibility props for the Toast component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Toasts need proper role and label
+ * - 4.1.3 Status Messages: Use aria-live regions for toast announcements
+ *
+ * The toast uses "alert" role with appropriate live region urgency:
+ * - Error: assertive (immediate announcement)
+ * - Success/Warning/Info: polite (waits for current speech to complete)
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/status-messages
+ */
+
+import { ToastA11yParams, ToastA11yProps, ToastVariant } from "./Toast.types";
+
+/**
+ * Determines live region urgency based on variant.
+ *
+ * @param variant - Toast variant
+ * @returns "assertive" for errors, "polite" for others
+ * @internal
+ */
+function getLiveRegionUrgency(
+  variant: ToastVariant
+): "polite" | "assertive" {
+  // Errors should interrupt immediately for critical feedback
+  return variant === "error" ? "assertive" : "polite";
+}
+
+/**
+ * Generate accessibility props for Toast.
+ *
+ * Toasts are announced as alerts with appropriate urgency.
+ * Error toasts interrupt immediately; others wait politely.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the Toast component
+ *
+ * @example
+ * const a11yProps = getToastA11y({
+ *   variant: "success",
+ *   message: "Changes saved",
+ * });
+ * // {
+ * //   accessibilityRole: "alert",
+ * //   accessibilityLabel: "Success: Changes saved",
+ * //   accessibilityLiveRegion: "polite"
+ * // }
+ *
+ * @example
+ * const a11yProps = getToastA11y({
+ *   variant: "error",
+ *   message: "Failed to save",
+ * });
+ * // {
+ * //   accessibilityRole: "alert",
+ * //   accessibilityLabel: "Error: Failed to save",
+ * //   accessibilityLiveRegion: "assertive"
+ * // }
+ */
+export function getToastA11y(params: ToastA11yParams): ToastA11yProps {
+  const { variant, accessibilityLabel, message, variantPrefixes } = params;
+
+  // Build default label with translated variant prefix for context
+  const defaultLabel = `${variantPrefixes[variant]}: ${message}`;
+
+  return {
+    accessibilityLabel: accessibilityLabel ?? defaultLabel,
+    accessibilityRole: "alert",
+    accessibilityLiveRegion: getLiveRegionUrgency(variant),
+  };
+}

package/src/primitives/inputs/Checkbox/Checkbox.a11y.ts

@@ -0,0 +1,47 @@
+/**
+ * Checkbox Accessibility Helpers
+ *
+ * Generates accessibility props for the Checkbox component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Checkboxes need proper role and label
+ * - 1.3.1 Info and Relationships: State must be programmatically determinable
+ *
+ * The checkbox uses "checkbox" role with checked state to indicate
+ * the current selection.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import { CheckboxA11yParams, CheckboxA11yProps } from "./Checkbox.types";
+
+/**
+ * Generate accessibility props for Checkbox.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the Checkbox component
+ *
+ * @warning Logs console warning in dev if both label and accessibilityLabel missing
+ *
+ * @example
+ * const a11yProps = getCheckboxA11y({
+ *   label: "Accept terms",
+ *   checked: true,
+ *   disabled: false,
+ * });
+ * // { accessibilityRole: "checkbox", accessibilityLabel: "Accept terms", accessibilityState: { checked: true, disabled: false } }
+ */
+export function getCheckboxA11y(params: CheckboxA11yParams): CheckboxA11yProps {
+  const { label, accessibilityLabel, accessibilityHint, checked, disabled } = params;
+
+  if (!accessibilityLabel && !label && process.env.NODE_ENV !== "production") {
+    console.warn("[Checkbox] Missing label or accessibilityLabel (WCAG 4.1.2)");
+  }
+
+  return {
+    accessibilityLabel: accessibilityLabel || label || "Checkbox",
+    accessibilityHint,
+    accessibilityRole: "checkbox",
+    accessibilityState: { checked, disabled },
+  };
+}

package/src/primitives/inputs/RadioButton/RadioButton.a11y.ts

@@ -0,0 +1,48 @@
+/**
+ * RadioButton Accessibility Helpers
+ *
+ * Generates accessibility props for the RadioButton component.
+ * Follows WCAG 2.1 guidelines for radio button accessibility.
+ */
+
+import { RadioButtonA11yParams, RadioButtonA11yProps } from "./RadioButton.types";
+
+/**
+ * Generate accessibility props for RadioButton.
+ *
+ * Provides proper semantic information for screen readers:
+ * - Role: "radio" for proper radio button semantics
+ * - State: checked and disabled states
+ * - Label: Uses provided label or accessibility label
+ *
+ * @param params - Accessibility configuration
+ * @returns Accessibility props object
+ *
+ * @example
+ * const a11yProps = getRadioButtonA11y({
+ *   label: "Option A",
+ *   checked: true,
+ *   disabled: false,
+ * });
+ * // Returns: { accessibilityRole: "radio", accessibilityState: { checked: true, disabled: false }, ... }
+ */
+export function getRadioButtonA11y(params: RadioButtonA11yParams): RadioButtonA11yProps {
+  const {
+    label,
+    accessibilityLabel,
+    accessibilityHint,
+    checked,
+    disabled,
+    fallbackLabel,
+  } = params;
+
+  return {
+    accessibilityLabel: accessibilityLabel || label || fallbackLabel,
+    accessibilityHint,
+    accessibilityRole: "radio",
+    accessibilityState: {
+      checked,
+      disabled,
+    },
+  };
+}

package/src/primitives/inputs/SegmentedControl/SegmentedControl.a11y.ts

@@ -0,0 +1,59 @@
+import type { SegmentOption } from "./SegmentedControl.types";
+
+/**
+ * Accessibility props for the SegmentedControl container
+ */
+export function getSegmentedControlContainerA11y(
+  optionsCount: number,
+  i18n: { containerLabel: string; optionsLabel: string },
+): {
+  accessible: boolean;
+  accessibilityRole: "radiogroup";
+  accessibilityLabel: string;
+} {
+  return {
+    accessible: true,
+    accessibilityRole: "radiogroup",
+    accessibilityLabel: `${i18n.containerLabel} ${optionsCount} ${i18n.optionsLabel}`,
+  };
+}
+
+/**
+ * Accessibility props for individual segments
+ */
+export function getSegmentA11y(
+  option: SegmentOption,
+  index: number,
+  totalOptions: number,
+  isSelected: boolean,
+  i18n: {
+    selectedLabel: string;
+    currentlySelectedHint: string;
+    doubleTapToSelectHint: string;
+    ofLabel: string;
+  },
+): {
+  accessible: boolean;
+  accessibilityRole: "radio";
+  accessibilityState: {
+    selected: boolean;
+    disabled: boolean;
+  };
+  accessibilityLabel: string;
+  accessibilityHint: string;
+} {
+  const positionText = `${index + 1} ${i18n.ofLabel} ${totalOptions}`;
+
+  return {
+    accessible: true,
+    accessibilityRole: "radio",
+    accessibilityState: {
+      selected: isSelected,
+      disabled: option.disabled ?? false,
+    },
+    accessibilityLabel: `${option.label}, ${positionText}${isSelected ? `, ${i18n.selectedLabel}` : ""}`,
+    accessibilityHint: isSelected
+      ? i18n.currentlySelectedHint
+      : `${i18n.doubleTapToSelectHint} ${option.label}`,
+  };
+}

package/src/primitives/inputs/SelectSheet/SelectSheet.a11y.ts

@@ -0,0 +1,117 @@
+/**
+ * SelectSheet Accessibility Helpers
+ *
+ * Accessibility utilities for the SelectSheet component.
+ */
+
+import { AccessibilityProps } from "react-native";
+
+import { SelectSheetMode, SelectSheetPosition } from "./SelectSheet.types";
+
+/**
+ * Get accessibility props for the sheet container
+ */
+export function getSheetA11yProps(params: {
+  title?: string;
+  position: SelectSheetPosition;
+  accessibilityLabel?: string;
+  positionLabels: { bottom: string; top: string; center: string };
+  fallbackTitle: string;
+}): AccessibilityProps {
+  const { title, position, accessibilityLabel, positionLabels, fallbackTitle } = params;
+
+  const positionLabel = positionLabels[position];
+
+  return {
+    accessible: true,
+    accessibilityRole: "none",
+    accessibilityLabel:
+      accessibilityLabel || `${title || fallbackTitle} ${positionLabel}`,
+    accessibilityViewIsModal: true,
+  };
+}
+
+/**
+ * Get accessibility props for an option row
+ */
+export function getOptionA11yProps(params: {
+  label: string;
+  isSelected: boolean;
+  isDisabled: boolean;
+  isMultiple: boolean;
+  index: number;
+  total: number;
+  selectedLabel: string;
+  disabledLabel: string;
+  ofLabel: string;
+}): AccessibilityProps {
+  const { label, isSelected, isDisabled, isMultiple, index, total, selectedLabel, disabledLabel, ofLabel } = params;
+
+  const role = isMultiple ? "checkbox" : "radio";
+  const selectedText = isSelected ? `, ${selectedLabel}` : "";
+  const disabledText = isDisabled ? `, ${disabledLabel}` : "";
+  const positionText = `${index + 1} ${ofLabel} ${total}`;
+
+  return {
+    accessible: true,
+    accessibilityRole: role,
+    accessibilityLabel: `${label}${selectedText}${disabledText}, ${positionText}`,
+    accessibilityState: {
+      checked: isSelected,
+      disabled: isDisabled,
+    },
+  };
+}
+
+/**
+ * Get accessibility props for the done button
+ */
+export function getDoneButtonA11yProps(params: {
+  selectedCount: number;
+  mode: SelectSheetMode;
+  doneLabel: string;
+  itemsSelectedLabel: string;
+  doneHint: string;
+}): AccessibilityProps {
+  const { selectedCount, mode, doneLabel, itemsSelectedLabel, doneHint } = params;
+
+  const countText =
+    mode === "multiple" ? ` with ${selectedCount} ${itemsSelectedLabel}` : "";
+
+  return {
+    accessible: true,
+    accessibilityRole: "button",
+    accessibilityLabel: `${doneLabel}${countText}`,
+    accessibilityHint: doneHint,
+  };
+}
+
+/**
+ * Get accessibility props for the close button
+ */
+export function getCloseButtonA11yProps(params: {
+  closeLabel: string;
+  closeHint: string;
+}): AccessibilityProps {
+  return {
+    accessible: true,
+    accessibilityRole: "button",
+    accessibilityLabel: params.closeLabel,
+    accessibilityHint: params.closeHint,
+  };
+}
+
+/**
+ * Get announcement for selection change
+ */
+export function getSelectionAnnouncement(
+  label: string,
+  isSelected: boolean,
+  isMultiple: boolean,
+  i18n: { selectedLabel: string; deselectedLabel: string },
+): string {
+  if (isMultiple) {
+    return isSelected ? `${label} ${i18n.selectedLabel}` : `${label} ${i18n.deselectedLabel}`;
+  }
+  return `${label} ${i18n.selectedLabel}`;
+}

package/src/primitives/inputs/Switch/Switch.a11y.ts

@@ -0,0 +1,29 @@
+import { SwitchA11yParams, SwitchA11yProps } from "./Switch.types";
+
+/**
+ * Get accessibility props for the Switch component.
+ *
+ * Implements WCAG 4.1.2 (Name, Role, Value) requirements:
+ * - accessibilityRole: "switch" for proper identification
+ * - accessibilityLabel: Required for screen readers (warns if missing)
+ * - accessibilityHint: Optional additional context
+ * - accessibilityState: Communicates checked and disabled states
+ *
+ * @param params - Accessibility parameters
+ * @returns Accessibility props for the switch
+ */
+export function getSwitchA11y(params: SwitchA11yParams): SwitchA11yProps {
+  const { label, accessibilityLabel, accessibilityHint, value, disabled } =
+    params;
+
+  if (!accessibilityLabel && !label && process.env.NODE_ENV !== "production") {
+    console.warn("[Switch] Missing label or accessibilityLabel (WCAG 4.1.2)");
+  }
+
+  return {
+    accessibilityLabel: accessibilityLabel || label || "Switch",
+    accessibilityHint,
+    accessibilityRole: "switch",
+    accessibilityState: { checked: value, disabled },
+  };
+}

package/src/primitives/inputs/TextInput/TextInput.a11y.ts

@@ -0,0 +1,77 @@
+/**
+ * TextInput Accessibility Helpers
+ *
+ * Generates accessibility props for the TextInput component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Inputs need proper labels
+ * - 3.3.1 Error Identification: Errors announced via hint
+ * - 3.3.2 Labels or Instructions: Required fields indicated
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions
+ */
+
+import { TextInputA11yParams, TextInputA11yProps } from "./TextInput.types";
+
+/**
+ * Generate accessibility props for TextInput.
+ *
+ * Implements WCAG requirements:
+ * - accessibilityLabel: Uses label prop as fallback, adds "required" suffix
+ * - accessibilityHint: Error message takes precedence over custom hint
+ * - accessibilityState: Communicates disabled state
+ *
+ * @param params - Accessibility parameters
+ * @returns Accessibility props for the text input
+ *
+ * @warning Logs console warning in dev if both label and accessibilityLabel missing
+ *
+ * @example
+ * const a11yProps = getTextInputA11y({
+ *   label: "Email",
+ *   required: true,
+ *   disabled: false,
+ *   error: "Invalid email",
+ * });
+ * // { accessibilityLabel: "Email, required", accessibilityHint: "Error: Invalid email", accessibilityState: { disabled: false } }
+ */
+export function getTextInputA11y(
+  params: TextInputA11yParams
+): TextInputA11yProps {
+  const {
+    label,
+    accessibilityLabel,
+    accessibilityHint,
+    disabled,
+    error,
+    required,
+    fallbackLabel,
+    requiredLabel,
+    errorPrefixLabel,
+  } = params;
+
+  if (!accessibilityLabel && !label && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[TextInput] Missing label or accessibilityLabel (WCAG 4.1.2)"
+    );
+  }
+
+  const baseLabel = accessibilityLabel || label || fallbackLabel;
+  const fullLabel = required ? `${baseLabel}, ${requiredLabel}` : baseLabel;
+
+  // Error takes precedence, then custom hint
+  let finalHint: string | undefined;
+  if (error) {
+    finalHint = `${errorPrefixLabel}: ${error}`;
+  } else if (accessibilityHint) {
+    finalHint = accessibilityHint;
+  }
+
+  return {
+    accessibilityLabel: fullLabel,
+    accessibilityHint: finalHint,
+    accessibilityState: {
+      disabled,
+    },
+  };
+}

package/src/primitives/layout/Divider/Divider.a11y.ts

@@ -0,0 +1,55 @@
+/**
+ * Divider Accessibility Helpers
+ *
+ * Generates accessibility props for the Divider component.
+ *
+ * WCAG References:
+ * - Decorative elements should be hidden from assistive technologies
+ * - When a divider has semantic meaning (with label), it should be announced
+ *
+ * The divider uses "none" role by default as it's purely decorative.
+ * When a label is present, it's announced via accessibilityLabel.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import { DividerA11yParams, DividerA11yProps } from "./Divider.types";
+
+/**
+ * Generate accessibility props for Divider.
+ *
+ * Dividers are typically decorative, so they use role="none" and
+ * are not accessible by default. When a label is present, the
+ * divider becomes accessible with the label as its description.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the Divider component
+ *
+ * @example
+ * // Decorative divider (hidden from AT)
+ * const a11yProps = getDividerA11y({ orientation: "horizontal" });
+ * // { accessibilityRole: "none", accessible: false }
+ *
+ * @example
+ * // Divider with label (announced by AT)
+ * const a11yProps = getDividerA11y({
+ *   orientation: "horizontal",
+ *   label: "OR",
+ *   accessibilityLabel: "Or"
+ * });
+ * // { accessibilityRole: "none", accessible: true, accessibilityLabel: "Or" }
+ */
+export function getDividerA11y(params: DividerA11yParams): DividerA11yProps {
+  const { label, accessibilityLabel } = params;
+
+  // If there's a label or explicit a11y label, make it accessible
+  const hasSemanticMeaning = Boolean(label || accessibilityLabel);
+
+  return {
+    accessibilityRole: "none",
+    accessible: hasSemanticMeaning,
+    ...(hasSemanticMeaning && {
+      accessibilityLabel: accessibilityLabel || label,
+    }),
+  };
+}