@praxiis/ui 0.0.1 → 0.0.3

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,
+    }),
+  };
+}

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,
+  };
+}

package/src/providers/ThemeProvider/index.ts

@@ -20,15 +20,3 @@ export type {
 
 // Default themes
 export { lightTheme, darkTheme, defaultTheme } from './defaultTheme';
-
-// Theme factory
-export {
-  createTheme,
-  createThemePair,
-  horizonTheme,
-  sageTheme,
-  sunsetTheme,
-  oceanTheme,
-  lavenderTheme,
-  roseTheme,
-} from './createTheme';

package/src/providers/index.ts

@@ -5,14 +5,6 @@
  */
 
 export {
-  createTheme,
-  createThemePair,
-  horizonTheme,
-  sageTheme,
-  sunsetTheme,
-  oceanTheme,
-  lavenderTheme,
-  roseTheme,
   lightTheme,
   darkTheme,
   defaultTheme,

package/src/providers/ThemeProvider/createTheme.ts

@@ -1,304 +0,0 @@
-/**
- * El Sendero Design System - Theme Factory
- *
- * Create custom themes by extending the base theme with overrides.
- *
- * @example
- * const myTheme = createTheme(defaultTheme, {
- *   colors: {
- *     accent: {
- *       primary: '#8B5CF6', // Purple accent
- *     }
- *   }
- * });
- */
-
-import { Theme, ThemeOverrides, DeepPartial } from './types';
-import { lightTheme, darkTheme } from './defaultTheme';
-
-// =============================================================================
-// DEEP MERGE UTILITY
-// =============================================================================
-
-/**
- * Deep merge two objects, with source values overriding target
- */
-function deepMerge<T extends object>(
-  target: T,
-  source: DeepPartial<T>
-): T {
-  const result = { ...target };
-
-  for (const key in source) {
-    if (Object.prototype.hasOwnProperty.call(source, key)) {
-      const sourceValue = source[key as keyof typeof source];
-      const targetValue = (target as Record<string, unknown>)[key];
-
-      if (
-        sourceValue !== null &&
-        typeof sourceValue === 'object' &&
-        !Array.isArray(sourceValue) &&
-        targetValue !== null &&
-        typeof targetValue === 'object' &&
-        !Array.isArray(targetValue)
-      ) {
-        result[key as keyof T] = deepMerge(
-          targetValue as Record<string, unknown>,
-          sourceValue as DeepPartial<Record<string, unknown>>
-        ) as T[keyof T];
-      } else if (sourceValue !== undefined) {
-        result[key as keyof T] = sourceValue as T[keyof T];
-      }
-    }
-  }
-
-  return result;
-}
-
-// =============================================================================
-// CREATE THEME
-// =============================================================================
-
-/**
- * Create a custom theme by extending a base theme with overrides.
- *
- * @param baseTheme - The theme to extend (usually defaultTheme)
- * @param overrides - Partial theme object with your customizations
- * @returns A complete Theme object with your overrides applied
- *
- * @example
- * // Create a sage-accented theme
- * const sageTheme = createTheme(defaultTheme, {
- *   name: 'Sage',
- *   colors: {
- *     accent: {
- *       primary: '#6B8F6B',
- *       primaryHover: '#557255',
- *       primaryPressed: '#445944',
- *     }
- *   }
- * });
- *
- * @example
- * // Create a more rounded theme
- * const softTheme = createTheme(defaultTheme, {
- *   radii: {
- *     md: 16,
- *     lg: 24,
- *     xl: 32,
- *   }
- * });
- */
-export function createTheme(
-  baseTheme: Theme,
-  overrides: ThemeOverrides
-): Theme {
-  return deepMerge(baseTheme, overrides);
-}
-
-// =============================================================================
-// CREATE THEME PAIR
-// =============================================================================
-
-/**
- * Create both light and dark versions of a custom theme.
- *
- * @param overrides - Overrides to apply to both light and dark themes
- * @param lightOverrides - Additional overrides for light theme only
- * @param darkOverrides - Additional overrides for dark theme only
- * @returns Object with light and dark theme variants
- *
- * @example
- * const { light, dark } = createThemePair(
- *   { name: 'MyBrand' },
- *   { colors: { accent: { primary: '#A68B6A' } } }, // Light-specific
- *   { colors: { accent: { primary: '#C4A285' } } }  // Dark-specific
- * );
- */
-export function createThemePair(
-  overrides: ThemeOverrides = {},
-  lightOverrides: ThemeOverrides = {},
-  darkOverrides: ThemeOverrides = {}
-): { light: Theme; dark: Theme } {
-  return {
-    light: createTheme(
-      createTheme(lightTheme, overrides),
-      lightOverrides
-    ),
-    dark: createTheme(
-      createTheme(darkTheme, overrides),
-      darkOverrides
-    ),
-  };
-}
-
-// =============================================================================
-// PRESET THEMES
-// =============================================================================
-
-/**
- * Horizon Default - Blue with a calming feel
- */
-export const horizonTheme = createThemePair({
-  name: 'Horizon',
-});
-
-/**
- * Sage Theme - Green-focused for hope and growth
- */
-export const sageTheme = createThemePair(
-  { name: 'Sage' },
-  {
-    colors: {
-      accent: {
-        primary: '#6B8F6B',
-        primaryHover: '#557255',
-        primaryPressed: '#445944',
-      },
-      text: {
-        link: '#6B8F6B',
-      },
-      border: {
-        focus: '#6B8F6B',
-      },
-    },
-  },
-  {
-    colors: {
-      accent: {
-        primary: '#8FAF8F',
-        primaryHover: '#B3C7B3',
-        primaryPressed: '#6B8F6B',
-      },
-      text: {
-        link: '#8FAF8F',
-      },
-      border: {
-        focus: '#8FAF8F',
-      },
-    },
-  }
-);
-
-/**
- * Sunset Theme - Warm coral/peach for energy and comfort
- */
-export const sunsetTheme = createThemePair(
-  { name: 'Sunset' },
-  {
-    colors: {
-      accent: {
-        primary: '#E8836B',
-        primaryHover: '#CC6B55',
-        primaryPressed: '#A85545',
-      },
-      text: {
-        link: '#E8836B',
-      },
-      border: {
-        focus: '#E8836B',
-      },
-    },
-  },
-  {
-    colors: {
-      accent: {
-        primary: '#FF9B85',
-        primaryHover: '#FFBAA8',
-        primaryPressed: '#E8836B',
-      },
-      text: {
-        link: '#FF9B85',
-      },
-      border: {
-        focus: '#FF9B85',
-      },
-    },
-  }
-);
-
-/**
- * Ocean Theme - Teal/cyan accents, calming water vibes
- */
-export const oceanTheme = createThemePair(
-  {
-    colors: {
-      accent: {
-        primary: '#0E9AA5',
-        primaryHover: '#0B7E87',
-        primaryPressed: '#086269',
-      },
-      text: { link: '#0E9AA5' },
-      border: { focus: '#0E9AA5' },
-    },
-  },
-  {
-    colors: {
-      accent: {
-        primary: '#2DD4BF',
-        primaryHover: '#5EEAD4',
-        primaryPressed: '#0E9AA5',
-      },
-      text: { link: '#2DD4BF' },
-      border: { focus: '#2DD4BF' },
-    },
-  }
-);
-
-/**
- * Lavender Theme - Soft purple accents, relaxing and spiritual
- */
-export const lavenderTheme = createThemePair(
-  { name: 'Lavender' },
-  {
-    colors: {
-      accent: {
-        primary: '#8B5CF6',
-        primaryHover: '#7C3AED',
-        primaryPressed: '#6D28D9',
-      },
-      text: { link: '#8B5CF6' },
-      border: { focus: '#8B5CF6' },
-    },
-  },
-  {
-    colors: {
-      accent: {
-        primary: '#A78BFA',
-        primaryHover: '#C4B5FD',
-        primaryPressed: '#8B5CF6',
-      },
-      text: { link: '#A78BFA' },
-      border: { focus: '#A78BFA' },
-    },
-  }
-);
-
-/**
- * Rose Theme - Warm pink/rose accents, gentle and nurturing
- */
-export const roseTheme = createThemePair(
-  { name: 'Rose' },
-  {
-    colors: {
-      accent: {
-        primary: '#E11D6C',
-        primaryHover: '#BE185D',
-        primaryPressed: '#9D174D',
-      },
-      text: { link: '#E11D6C' },
-      border: { focus: '#E11D6C' },
-    },
-  },
-  {
-    colors: {
-      accent: {
-        primary: '#F472B6',
-        primaryHover: '#F9A8D4',
-        primaryPressed: '#E11D6C',
-      },
-      text: { link: '#F472B6' },
-      border: { focus: '#F472B6' },
-    },
-  }
-);