diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..376350c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,440 @@ +# Copilot Instructions - Auth Kit UI Module + +> **Purpose**: Development guidelines for the Auth Kit UI module - reusable React authentication components. + +--- + +## ๐ŸŽฏ Module Overview + +**Package**: `@ciscode/ui-authentication-kit` +**Type**: React Component Library +**Purpose**: Pre-built authentication UI components for React apps + +### Responsibilities: +- Login/Register forms +- Protected route wrappers +- Auth context providers +- Password reset UI +- User profile components + +--- + +## ๐Ÿ—๏ธ Module Structure + +``` +src/ + โ”œโ”€โ”€ components/ # React components + โ”‚ โ”œโ”€โ”€ LoginForm/ + โ”‚ โ”‚ โ”œโ”€โ”€ LoginForm.tsx + โ”‚ โ”‚ โ”œโ”€โ”€ LoginForm.test.tsx + โ”‚ โ”‚ โ””โ”€โ”€ index.ts + โ”‚ โ””โ”€โ”€ RegisterForm/ + โ”œโ”€โ”€ hooks/ # Custom hooks + โ”‚ โ”œโ”€โ”€ use-auth.ts + โ”‚ โ””โ”€โ”€ use-protected-route.ts + โ”œโ”€โ”€ context/ # Auth context provider + โ”‚ โ””โ”€โ”€ AuthProvider.tsx + โ”œโ”€โ”€ types/ # TypeScript types + โ”‚ โ””โ”€โ”€ auth.types.ts + โ””โ”€โ”€ index.ts # Exports +``` + +--- + +## ๐Ÿ“ Naming Conventions + +**Components**: `PascalCase.tsx` +- `LoginForm.tsx` +- `RegisterForm.tsx` +- `ProtectedRoute.tsx` + +**Hooks**: `camelCase.ts` with `use` prefix +- `use-auth.ts` +- `use-login.ts` + +**Types**: `kebab-case.ts` +- `auth.types.ts` + +--- + +## ๐Ÿงช Testing - Component Library Standards + +### Coverage Target: 80%+ + +**Unit Tests:** +- โœ… All custom hooks +- โœ… Utilities and helpers +- โœ… Context logic + +**Component Tests:** +- โœ… All components with user interactions +- โœ… Form validation logic +- โœ… Error state handling + +**Skip:** +- โŒ Purely presentational components (no logic) + +**Test location:** +``` +LoginForm/ + โ”œโ”€โ”€ LoginForm.tsx + โ””โ”€โ”€ LoginForm.test.tsx โ† Same directory +``` + +--- + +## ๐Ÿ“š Documentation - Complete + +### JSDoc for Hooks: + +```typescript +/** + * Hook for managing authentication state + * @returns Auth state and methods + * @example + * ```tsx + * const { user, login, logout, isAuthenticated } = useAuth(); + * + * const handleLogin = async () => { + * await login(email, password); + * }; + * ``` + */ +export function useAuth(): UseAuthReturn +``` + +### Component Documentation: + +```typescript +export interface LoginFormProps { + /** Callback when login succeeds */ + onSuccess?: (user: User) => void; + /** Callback when login fails */ + onError?: (error: Error) => void; + /** Show remember me checkbox */ + showRememberMe?: boolean; +} + +/** + * Login form component with validation + * + * @example + * ```tsx + * navigate('/dashboard')} + * showRememberMe={true} + * /> + * ``` + */ +export function LoginForm(props: LoginFormProps): JSX.Element +``` + +--- + +## ๐Ÿš€ Module Development Principles + +### 1. Headless & Customizable + +**Unstyled by default:** +```typescript +// Components accept className prop + + +// Or use default minimal styles +import '@ciscode/ui-authentication-kit/styles.css'; +``` + +### 2. Framework Agnostic (Data Layer) + +**No hardcoded API calls:** +```typescript +// โŒ BAD: Hardcoded API +const login = async (email, password) => { + await fetch('/api/login', ...); +}; + +// โœ… GOOD: Injected API client + + + +``` + +### 3. Accessibility First + +**ALWAYS:** +- โœ… ARIA labels on form fields +- โœ… Keyboard navigation +- โœ… Screen reader support +- โœ… Focus management +- โœ… Error announcements + +### 4. Export Strategy + +**Export ONLY public API:** +```typescript +// src/index.ts - Public exports +export { LoginForm } from './components/LoginForm'; +export { RegisterForm } from './components/RegisterForm'; +export { ProtectedRoute } from './components/ProtectedRoute'; +export { AuthProvider } from './context/AuthProvider'; + +// Hooks +export { useAuth } from './hooks/use-auth'; +export { useProtectedRoute } from './hooks/use-protected-route'; + +// Types (for TypeScript users) +export type { + LoginFormProps, + RegisterFormProps, + AuthProviderProps, + User, + AuthState +} from './types'; + +// โŒ NEVER export internal utilities +// export { validateEmail } from './utils/validation'; // FORBIDDEN +``` + +**Rationale:** +- Components = public UI API +- Hooks = public logic API +- Types = TypeScript contracts +- Internal utils = implementation details + +--- + +## ๐Ÿ”„ Workflow & Task Management + +### Task-Driven Development (UI Module) + +**1. Branch Creation:** +```bash +feature/UI-MODULE-123-add-password-strength +bugfix/UI-MODULE-456-fix-form-validation +refactor/UI-MODULE-789-extract-input-component +``` + +**2. Task Documentation:** +Create task file: +``` +docs/tasks/active/UI-MODULE-123-add-password-strength.md +``` + +**Task structure:** +```markdown +# UI-MODULE-123: Add Password Strength Indicator + +## Description +Visual feedback for password strength during registration + +## Implementation Details +- Component: PasswordStrength.tsx +- Uses zxcvbn library for strength calculation +- Accessible with ARIA live regions + +## Files Modified +- src/components/RegisterForm/RegisterForm.tsx +- src/components/PasswordStrength/PasswordStrength.tsx (new) + +## Breaking Changes +- None (backward compatible) + +## Accessibility +- ARIA live region announces strength changes +- Color-blind friendly indicators +``` + +**3. On Release:** +Move to: +``` +docs/tasks/archive/by-release/v2.0.0/UI-MODULE-123-add-password-strength.md +``` + +### Development Workflow + +**Simple changes:** +- Implement โ†’ Test โ†’ Update docs โ†’ Update CHANGELOG + +**Complex changes:** +- Discuss approach โ†’ Implement โ†’ Test accessibility โ†’ Update docs โ†’ CHANGELOG โ†’ Version bump + +**When blocked:** +- **DO**: Ask immediately +- **DON'T**: Break component APIs without approval + +--- + +## ๐ŸŽจ Component Patterns + +### Composition Over Configuration: + +```typescript +// โœ… GOOD: Composable + + + + + + + +// Also support all-in-one for quick use + +``` + +### Controlled & Uncontrolled: + +```typescript +// Uncontrolled (default) + + +// Controlled + +``` + +--- + +## ๐ŸŒ Internationalization + +**i18n Support:** +```typescript +// Provide translation function + + + + +// Or use default English + +``` + +**Translation keys:** +```typescript +'auth.login.email' โ†’ "Email" +'auth.login.password' โ†’ "Password" +'auth.login.submit' โ†’ "Login" +'auth.errors.invalid_credentials' โ†’ "Invalid email or password" +``` + +--- + +## ๐Ÿ“ฆ Versioning & Breaking Changes + +### Semantic Versioning + +**MAJOR** - Breaking: +- Changed component props (removed/renamed) +- Changed hook return values +- Changed context API + +**MINOR** - New features: +- New components +- New optional props +- New hooks + +**PATCH** - Fixes: +- Bug fixes +- Style improvements +- Documentation + +--- + +## ๐Ÿšซ Restrictions + +**NEVER without approval:** +- Breaking changes to component APIs +- Removing exported components +- Changing TypeScript types +- Major dependency upgrades + +**CAN do autonomously:** +- New components (non-breaking) +- Bug fixes +- Style improvements +- Documentation + +--- + +## โœ… Release Checklist + +- [ ] All tests passing +- [ ] Coverage >= 80% +- [ ] No ESLint/TypeScript errors +- [ ] All components documented +- [ ] Storybook examples updated (if exists) +- [ ] README with examples +- [ ] CHANGELOG updated +- [ ] Version bumped +- [ ] Accessibility verified +- [ ] Mobile responsive tested + +--- + +## ๐ŸŽจ Code Style + +**React Best Practices:** +- Functional components only +- Custom hooks for logic +- `React.memo()` for expensive components +- `useMemo/useCallback` where appropriate +- Composition over props drilling + +**TypeScript:** +- Strict mode enabled +- Props interfaces exported +- Generic types for flexibility + +--- + +## ๐Ÿ› Error Handling + +**User-facing errors:** +```typescript +// Show error in UI +const [error, setError] = useState(); + + setError(err.message)} +/> +{error && {error}} +``` + +**Developer errors:** +```typescript +// Throw for misuse +if (!apiClient) { + throw new Error('AuthProvider requires apiClient prop'); +} +``` + +--- + +## ๐Ÿ’ฌ Communication Style + +- Brief and direct +- Component-focused +- Highlight breaking changes +- Accessibility considerations + +--- + +## ๐Ÿ“‹ Summary + +**UI Module Principles:** +1. Customizable & unstyled by default +2. Accessible by design +3. Framework-agnostic data layer +4. Comprehensive testing +5. Complete TypeScript types +6. i18n support +7. Mobile responsive + +**When in doubt:** Ask. UI components impact user experience across apps. + +--- + +*Last Updated: January 30, 2026* +*Version: 1.0.0* diff --git a/docs/tasks/active/README.md b/docs/tasks/active/README.md new file mode 100644 index 0000000..46a8ba6 --- /dev/null +++ b/docs/tasks/active/README.md @@ -0,0 +1,17 @@ +# Active Tasks - Auth Kit UI Module + +UI component tasks in progress. + +## Workflow + +1. Create: `UI-MODULE-XXX-description.md` +2. Update during work +3. Archive on release: `archive/by-release/vX.X.X/` + +## UI-Specific Focus + +For UI module tasks, document: +- Component changes (props, behavior) +- Accessibility considerations +- Visual/responsive design +- Breaking changes in component API