@praxiis/ui 0.0.1 → 0.0.2

package/src/components/CalendarStrip/CalendarStrip.a11y.ts

@@ -0,0 +1,51 @@
+/**
+ * CalendarStrip Accessibility Helpers
+ *
+ * Generates accessibility props for the CalendarStrip container.
+ *
+ * WCAG References:
+ * - 1.3.1 Info and Relationships: Date range context must be conveyed to AT
+ * - 4.1.2 Name, Role, Value: Landmark regions need descriptive labels
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+/**
+ * Generate accessibility props for the CalendarStrip container.
+ *
+ * Accepts pre-translated strings so the function stays pure and i18n-agnostic.
+ *
+ * @example
+ * getCalendarStripA11y({
+ *   label: t.calendar.datePicker.label,
+ *   selectedLabel: t.calendar.datePicker.selected,
+ *   daysShownLabel: t.calendar.datePicker.daysShown,
+ *   selectedDate: new Date(2026, 1, 19),
+ *   dateCount: 7,
+ * });
+ * // { accessible: true, accessibilityRole: "list", accessibilityLabel: "Date picker, Feb 19 selected, 7 days shown" }
+ */
+export function getCalendarStripA11y({
+  label,
+  selectedLabel,
+  daysShownLabel,
+  selectedDate,
+  dateCount,
+}: {
+  label: string;
+  selectedLabel: string;
+  daysShownLabel: string;
+  selectedDate: Date;
+  dateCount: number;
+}) {
+  const formatted = selectedDate.toLocaleDateString([], {
+    month: "short",
+    day: "numeric",
+  });
+
+  return {
+    accessible: true,
+    accessibilityRole: "list" as const,
+    accessibilityLabel: `${label}, ${formatted} ${selectedLabel}, ${dateCount} ${daysShownLabel}`,
+  };
+}

package/src/components/CalendarStrip/DayCard/DayCard.a11y.ts

@@ -0,0 +1,52 @@
+/**
+ * DayCard Accessibility Helpers
+ *
+ * Generates accessibility props for the DayCard component.
+ *
+ * WCAG References:
+ * - 1.3.1 Info and Relationships: Date context must be conveyed to AT
+ * - 4.1.2 Name, Role, Value: Interactive elements need role, label, and state
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import { DayCardA11yParams, DayCardA11yProps } from "./DayCard.types";
+
+/**
+ * Generate accessibility props for a DayCard.
+ *
+ * Combines day, month and selection state into a descriptive label
+ * so screen readers announce the full date and its status.
+ *
+ * @param params - Date context and state for the card
+ * @returns Props to spread onto the DayCard Pressable
+ *
+ * @example
+ * const a11yProps = getDayCardA11y({
+ *   date: new Date(2026, 1, 19),
+ *   isSelected: true,
+ *   isToday: false,
+ *   dayLabel: "Thu",
+ *   monthLabel: "Feb",
+ * });
+ * // {
+ * //   accessible: true,
+ * //   accessibilityRole: "button",
+ * //   accessibilityLabel: "Thu 19 Feb, selected",
+ * //   accessibilityState: { selected: true },
+ * // }
+ */
+export function getDayCardA11y(params: DayCardA11yParams): DayCardA11yProps {
+  const { date, isSelected, isToday, dayLabel, monthLabel, todayLabel, selectedLabel } = params;
+
+  const parts: string[] = [dayLabel, String(date.getDate()), monthLabel];
+  if (isToday) parts.push(todayLabel);
+  if (isSelected) parts.push(selectedLabel);
+
+  return {
+    accessible: true,
+    accessibilityRole: "button",
+    accessibilityLabel: parts.join(" "),
+    accessibilityState: { selected: isSelected },
+  };
+}

package/src/components/EmptyState/EmptyState.a11y.ts

@@ -0,0 +1,53 @@
+/**
+ * EmptyState Accessibility Helpers
+ *
+ * Generates accessibility props for the EmptyState component.
+ *
+ * WCAG References:
+ * - 1.3.1 Info and Relationships: Content structure must be conveyed
+ * - 4.1.2 Name, Role, Value: Informational content needs appropriate labels
+ *
+ * EmptyState components communicate important status information to users
+ * and should be accessible to screen readers with proper labels.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships
+ */
+
+import { EmptyStateA11yParams, EmptyStateA11yProps } from "./EmptyState.types";
+
+/**
+ * Generate accessibility props for EmptyState.
+ *
+ * Combines title and description into a comprehensive accessibility label
+ * for screen readers. The empty state is treated as an informational text
+ * region.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the EmptyState container
+ *
+ * @example
+ * const a11yProps = getEmptyStateA11y({
+ *   title: "No items found",
+ *   description: "Try adjusting your search"
+ * });
+ * // {
+ * //   accessible: true,
+ * //   accessibilityRole: "text",
+ * //   accessibilityLabel: "No items found. Try adjusting your search"
+ * // }
+ */
+export function getEmptyStateA11y(params: EmptyStateA11yParams): EmptyStateA11yProps {
+  const { title, description, accessibilityLabel } = params;
+
+  // Use custom label if provided, otherwise combine title and description
+  let label = accessibilityLabel;
+  if (!label) {
+    label = description ? `${title}. ${description}` : title;
+  }
+
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: label,
+  };
+}

package/src/components/Header/Header.a11y.ts

@@ -0,0 +1,82 @@
+/**
+ * Header Accessibility Helpers
+ *
+ * Generates accessibility props for the Header component.
+ *
+ * WCAG References:
+ * - 1.3.1 Info and Relationships: Headers need proper role
+ * - 2.4.6 Headings and Labels: Descriptive labels
+ * - 4.1.2 Name, Role, Value: Back button needs label
+ *
+ * The header uses "header" role to indicate a page/section heading.
+ * The back button uses "button" role with translated labels.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels
+ */
+
+import { AccessibilityRole } from "react-native";
+import {
+  HeaderA11yParams,
+  HeaderA11yProps,
+  HeaderBackButtonA11yParams,
+} from "./Header.types";
+
+/**
+ * Generate accessibility props for the back button.
+ *
+ * @param params - Back button accessibility parameters
+ * @returns Object to spread onto the back button
+ *
+ * @warning Logs console warning in dev if accessibilityLabel missing
+ *
+ * @example
+ * const a11yProps = getHeaderBackButtonA11y({
+ *   accessibilityLabel: "Go back",
+ *   accessibilityHint: "Returns to previous screen",
+ * });
+ */
+export function getHeaderBackButtonA11y(
+  params: HeaderBackButtonA11yParams,
+): HeaderA11yProps {
+  const { accessibilityLabel, accessibilityHint } = params;
+
+  if (!accessibilityLabel && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[Header] Missing accessibilityLabel for back button (WCAG 4.1.2)",
+    );
+  }
+
+  return {
+    accessibilityRole: "button" as AccessibilityRole,
+    accessibilityLabel,
+    accessibilityHint,
+  };
+}
+
+/**
+ * Generate accessibility props for the header container.
+ *
+ * @param params - Header accessibility parameters
+ * @returns Object to spread onto the header container
+ *
+ * @warning Logs console warning in dev if accessibilityLabel missing
+ *
+ * @example
+ * const a11yProps = getHeaderA11y({
+ *   accessibilityLabel: "Settings page header",
+ * });
+ * // { accessibilityRole: "header", accessibilityLabel: "Settings page header" }
+ */
+export function getHeaderA11y(params: HeaderA11yParams): HeaderA11yProps {
+  const { accessibilityLabel, accessibilityHint } = params;
+
+  if (!accessibilityLabel && process.env.NODE_ENV !== "production") {
+    console.warn("[Header] Missing accessibilityLabel (WCAG 4.1.2)");
+  }
+
+  return {
+    accessibilityRole: "header",
+    accessibilityLabel,
+    accessibilityHint,
+  };
+}

package/src/components/ScheduleItem/ScheduleItem/ScheduleItem.a11y.ts

@@ -0,0 +1,15 @@
+import type {
+  ScheduleItemA11yParams,
+  ScheduleItemA11yProps,
+} from "./ScheduleItem.types";
+
+export function getScheduleItemA11y(
+  params: ScheduleItemA11yParams,
+): ScheduleItemA11yProps {
+  const { title, timeRange, onPress } = params;
+  return {
+    accessible: true,
+    accessibilityRole: onPress ? "button" : "text",
+    accessibilityLabel: `${title}, ${timeRange}`,
+  };
+}

package/src/primitives/actions/Button/Button.a11y.ts

@@ -0,0 +1,38 @@
+import { ButtonA11yParams, ButtonA11yProps } from "./Button.types";
+
+/**
+ * Get accessibility props for the Button component.
+ *
+ * Implements WCAG 4.1.2 (Name, Role, Value) requirements:
+ * - accessibilityRole: "button" for proper identification
+ * - accessibilityLabel: Required for screen readers (warns if missing)
+ * - accessibilityHint: Optional additional context
+ * - accessibilityState: Communicates disabled and busy states
+ *
+ * @param params - Accessibility parameters
+ * @returns Accessibility props for the button
+ */
+export function getButtonA11y(params: ButtonA11yParams): ButtonA11yProps {
+  const { title, accessibilityLabel, accessibilityHint, disabled, isLoading } =
+    params;
+
+  if (!title && process.env.NODE_ENV !== "production") {
+    console.warn("[Button] Missing title (WCAG 4.1.2)");
+  }
+
+  if (!accessibilityLabel && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[Button] Missing accessibilityLabel. Using title as fallback (WCAG 4.1.2)"
+    );
+  }
+
+  return {
+    accessibilityRole: "button",
+    accessibilityLabel: accessibilityLabel || title,
+    accessibilityHint,
+    accessibilityState: {
+      disabled: disabled || isLoading,
+      busy: isLoading,
+    },
+  };
+}

package/src/primitives/actions/IconButton/IconButton.a11y.ts

@@ -0,0 +1,55 @@
+/**
+ * IconButton Accessibility Helpers
+ *
+ * Generates accessibility props for the IconButton component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Buttons need proper role and label
+ * - 1.1.1 Non-text Content: Icon-only buttons require text alternatives
+ *
+ * Since IconButton has no visible text, accessibilityLabel is
+ * REQUIRED (not optional like text buttons).
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import {
+  IconButtonA11yParams,
+  IconButtonA11yProps,
+} from "./IconButton.types";
+
+/**
+ * Generate accessibility props for IconButton.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the IconButton component
+ *
+ * @warning Logs console warning in dev if accessibilityLabel missing.
+ *          IconButton MUST have an accessibilityLabel since there's no visible text.
+ *
+ * @example
+ * const a11yProps = getIconButtonA11y({
+ *   accessibilityLabel: "Add to favorites",
+ *   disabled: false,
+ *   isLoading: false,
+ * });
+ */
+export function getIconButtonA11y(
+  params: IconButtonA11yParams
+): IconButtonA11yProps {
+  const { accessibilityLabel, accessibilityHint, disabled, isLoading } = params;
+
+  if (!accessibilityLabel && process.env.NODE_ENV !== "production") {
+    console.warn("[IconButton] Missing accessibilityLabel (WCAG 4.1.2)");
+  }
+
+  return {
+    accessibilityLabel,
+    accessibilityHint,
+    accessibilityRole: "button",
+    accessibilityState: {
+      disabled: disabled || isLoading,
+      busy: isLoading,
+    },
+  };
+}

package/src/primitives/content/Avatar/Avatar.a11y.ts

@@ -0,0 +1,50 @@
+/**
+ * Avatar Accessibility Helpers
+ *
+ * Generates accessibility props for the Avatar component.
+ *
+ * WCAG References:
+ * - 1.1.1 Non-text Content: Images need text alternatives
+ * - 4.1.2 Name, Role, Value: Provide meaningful labels
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content
+ */
+
+import { AvatarA11yParams, AvatarA11yProps } from "./Avatar.types";
+
+/**
+ * Generate accessibility props for Avatar.
+ *
+ * @param params - Name, custom label, status, and pre-translated strings
+ * @returns Object to spread onto the Avatar component
+ *
+ * @example
+ * const a11yProps = getAvatarA11y({
+ *   name: "John Doe",
+ *   status: "online",
+ *   fallbackLabel: "User avatar",
+ *   statusLabels: { online: "online", offline: "offline", busy: "busy", away: "away" },
+ * });
+ * // {
+ * //   accessible: true,
+ * //   accessibilityRole: "image",
+ * //   accessibilityLabel: "John Doe, online"
+ * // }
+ */
+export function getAvatarA11y(params: AvatarA11yParams): AvatarA11yProps {
+  const { name, accessibilityLabel, status, fallbackLabel, statusLabels } = params;
+
+  // Build label: custom label > name > fallback
+  let label = accessibilityLabel || name || fallbackLabel;
+
+  // Append status if present
+  if (status !== "none") {
+    label = `${label}, ${statusLabels[status]}`;
+  }
+
+  return {
+    accessible: true,
+    accessibilityRole: "image",
+    accessibilityLabel: label,
+  };
+}

package/src/primitives/content/Badge/Badge.a11y.ts

@@ -0,0 +1,83 @@
+/**
+ * Badge Accessibility Helpers
+ *
+ * Generates accessibility props for the Badge component.
+ *
+ * WCAG References:
+ * - 1.3.1 Info and Relationships: Convey meaning through accessible labels
+ * - 4.1.2 Name, Role, Value: Provide meaningful labels
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships
+ */
+
+import {
+  BadgeA11yParams,
+  BadgeA11yProps,
+} from "./Badge.types";
+
+/**
+ * Generate accessibility props for Badge.
+ *
+ * @param params - Label, dot mode, color, custom label, and pre-translated strings
+ * @returns Object to spread onto the Badge component
+ *
+ * @example
+ * const a11yProps = getBadgeA11y({
+ *   label: "New",
+ *   dot: false,
+ *   color: "primary",
+ *   fallbackLabel: "badge",
+ *   statusIndicatorLabel: "status indicator",
+ *   colorLabels: { primary: "indicator", success: "success", warning: "warning", error: "error", info: "information" },
+ * });
+ * // {
+ * //   accessible: true,
+ * //   accessibilityRole: "text",
+ * //   accessibilityLabel: "New"
+ * // }
+ *
+ * @example
+ * const a11yProps = getBadgeA11y({
+ *   dot: true,
+ *   color: "success",
+ *   fallbackLabel: "badge",
+ *   statusIndicatorLabel: "status indicator",
+ *   colorLabels: { primary: "indicator", success: "success", warning: "warning", error: "error", info: "information" },
+ * });
+ * // {
+ * //   accessible: true,
+ * //   accessibilityRole: "text",
+ * //   accessibilityLabel: "success status indicator"
+ * // }
+ */
+export function getBadgeA11y(params: BadgeA11yParams): BadgeA11yProps {
+  const { label, dot, color, accessibilityLabel, fallbackLabel, statusIndicatorLabel, colorLabels } = params;
+
+  // Use custom label if provided
+  if (accessibilityLabel) {
+    return {
+      accessible: true,
+      accessibilityRole: "text",
+      accessibilityLabel,
+    };
+  }
+
+  // Dot mode: describe as status indicator
+  if (dot) {
+    return {
+      accessible: true,
+      accessibilityRole: "text",
+      accessibilityLabel: `${colorLabels[color as string] ?? String(color)} ${statusIndicatorLabel}`,
+    };
+  }
+
+  // Text/number label
+  const labelText =
+    label !== undefined && label !== null ? String(label) : fallbackLabel;
+
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: labelText,
+  };
+}

package/src/primitives/content/Card/Card.a11y.ts

@@ -0,0 +1,60 @@
+/**
+ * Card Accessibility Helpers
+ *
+ * Generates accessibility props for the Card component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Pressable cards need proper role and label
+ *
+ * Cards have conditional accessibility based on pressable state:
+ * - Non-pressable: role="none" (content container only)
+ * - Pressable: role="button" with required label
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import { CardA11yParams, CardA11yProps } from "./Card.types";
+
+/**
+ * Generate accessibility props for Card.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the Card component
+ *
+ * @warning Logs console warning in dev if pressable card missing accessibilityLabel
+ *
+ * @example
+ * // Non-pressable card
+ * const a11yProps = getCardA11y({ disabled: false });
+ * // { accessibilityRole: "none" }
+ *
+ * @example
+ * // Pressable card
+ * const a11yProps = getCardA11y({
+ *   accessibilityLabel: "View product",
+ *   disabled: false,
+ *   onPress: handlePress,
+ * });
+ * // { accessibilityRole: "button", accessibilityLabel: "View product", accessibilityState: { disabled: false } }
+ */
+export function getCardA11y(params: CardA11yParams): CardA11yProps {
+  const { accessibilityLabel, disabled, onPress } = params;
+
+  if (!accessibilityLabel && onPress && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[Card] Missing accessibilityLabel for pressable card (WCAG 4.1.2)"
+    );
+  }
+
+  const isPressable = !!onPress;
+
+  return {
+    accessibilityRole: isPressable ? "button" : "none",
+    accessibilityLabel: accessibilityLabel || undefined,
+    accessibilityState: isPressable
+      ? {
+          disabled,
+        }
+      : undefined,
+  };
+}

package/src/primitives/content/Chip/Chip.a11y.ts

@@ -0,0 +1,101 @@
+/**
+ * Chip Accessibility Helpers
+ *
+ * Generates accessibility props for the Chip component.
+ *
+ * WCAG References:
+ * - 4.1.2 Name, Role, Value: Provide semantic role and state
+ * - 1.3.1 Info and Relationships: Convey selected state
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/name-role-value
+ */
+
+import { ChipA11yParams, ChipA11yProps } from "./Chip.types";
+
+/**
+ * Get accessibility props for the Chip component.
+ *
+ * Implements WCAG 4.1.2 (Name, Role, Value) requirements:
+ * - accessibilityRole: "checkbox" for selectable, "button" for action/dismissible
+ * - accessibilityLabel: Required for screen readers
+ * - accessibilityHint: Optional additional context
+ * - accessibilityState: Communicates disabled and selected/checked states
+ *
+ * @param params - Accessibility parameters
+ * @returns Accessibility props for the chip
+ *
+ * @example
+ * // Selectable chip
+ * const a11yProps = getChipA11y({
+ *   label: "Option A",
+ *   selected: true,
+ *   isSelectable: true,
+ *   isDismissible: false,
+ *   disabled: false,
+ * });
+ * // {
+ * //   accessibilityRole: "checkbox",
+ * //   accessibilityLabel: "Option A",
+ * //   accessibilityState: { disabled: false, checked: true }
+ * // }
+ *
+ * @example
+ * // Dismissible chip
+ * const a11yProps = getChipA11y({
+ *   label: "Filter",
+ *   selected: false,
+ *   isSelectable: false,
+ *   isDismissible: true,
+ *   disabled: false,
+ * });
+ * // {
+ * //   accessibilityRole: "button",
+ * //   accessibilityLabel: "Filter",
+ * //   accessibilityHint: "Double tap to remove",
+ * //   accessibilityState: { disabled: false }
+ * // }
+ */
+export function getChipA11y(params: ChipA11yParams): ChipA11yProps {
+  const {
+    label,
+    accessibilityLabel,
+    accessibilityHint,
+    disabled,
+    selected,
+    isSelectable,
+    isDismissible,
+    toggleHint,
+    removeHint,
+  } = params;
+
+  if (!label && process.env.NODE_ENV !== "production") {
+    console.warn("[Chip] Missing label (WCAG 4.1.2)");
+  }
+
+  const finalLabel = accessibilityLabel || label;
+
+  // Selectable chips use checkbox role
+  if (isSelectable) {
+    return {
+      accessibilityRole: "checkbox",
+      accessibilityLabel: finalLabel,
+      accessibilityHint: accessibilityHint || toggleHint,
+      accessibilityState: {
+        disabled,
+        checked: selected,
+      },
+    };
+  }
+
+  // Dismissible and action chips use button role
+  return {
+    accessibilityRole: "button",
+    accessibilityLabel: finalLabel,
+    accessibilityHint:
+      accessibilityHint || (isDismissible ? removeHint : undefined),
+    accessibilityState: {
+      disabled,
+      selected: isSelectable ? selected : undefined,
+    },
+  };
+}

package/src/primitives/content/Icon/Icon.a11y.ts

@@ -0,0 +1,43 @@
+/**
+ * Icon Accessibility Helpers
+ *
+ * Generates accessibility props for the Icon component.
+ *
+ * WCAG References:
+ * - 1.1.1 Non-text Content: Icons need text alternatives
+ * - 4.1.2 Name, Role, Value: Proper role and label required
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content
+ */
+
+import { IconA11yParams, IconA11yProps } from "./Icon.types";
+
+/**
+ * Generate accessibility props for Icon.
+ *
+ * Icons are treated as images for accessibility purposes.
+ * Decorative icons (without accessibilityLabel) will still
+ * be announced but with no descriptive text.
+ *
+ * @param params - Accessibility parameters
+ * @returns Object to spread onto the Icon component
+ *
+ * @warning Logs console warning in dev if accessibilityLabel missing
+ *
+ * @example
+ * const a11yProps = getIconA11y({ accessibilityLabel: "Settings" });
+ * // { accessibilityRole: "image", accessibilityLabel: "Settings" }
+ */
+export function getIconA11y(params: IconA11yParams): IconA11yProps {
+  const { accessibilityLabel, accessibilityHint } = params;
+
+  if (!accessibilityLabel && process.env.NODE_ENV !== "production") {
+    console.warn("[Icon] Missing accessibilityLabel (WCAG 4.1.2)");
+  }
+
+  return {
+    accessibilityRole: "image",
+    accessibilityLabel,
+    accessibilityHint,
+  };
+}