@ciscode/ui-authentication-kit 1.0.7 → 1.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +213 -33
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,44 +1,224 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @ciscode/ui-authentication-kit
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
(components + hooks + utilities).
|
|
3
|
+
> **Production-ready authentication UI components for React applications**
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@ciscode/ui-authentication-kit)
|
|
6
|
+
[](LICENSE)
|
|
7
7
|
|
|
8
|
-
-
|
|
9
|
-
- Vitest testing
|
|
10
|
-
- ESLint + Prettier (flat config)
|
|
11
|
-
- Changesets (manual release flow, no automation PR)
|
|
12
|
-
- Husky (pre-commit + pre-push)
|
|
13
|
-
- Enforced public API via `src/index.ts`
|
|
14
|
-
- Dependency-free styling (Tailwind-compatible by convention only)
|
|
15
|
-
- `react` and `react-dom` as peerDependencies
|
|
8
|
+
Complete authentication solution with built-in pages, RBAC support, and session management. Drop-in components that work with any backend API.
|
|
16
9
|
|
|
17
|
-
##
|
|
10
|
+
## ✨ Features
|
|
18
11
|
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
12
|
+
- 🔐 **Pre-built Auth Pages** - Login, Register, Password Reset, Profile
|
|
13
|
+
- 🛡️ **RBAC Support** - Role-based access control with permissions
|
|
14
|
+
- 🔄 **Session Management** - Automatic token refresh and expiration handling
|
|
15
|
+
- 🎨 **Customizable** - Headless components, bring your own styles
|
|
16
|
+
- ♿ **Accessible** - ARIA-compliant, keyboard navigation
|
|
17
|
+
- 🌍 **i18n Ready** - Multi-language support via `@ciscode/ui-translate-core`
|
|
18
|
+
- 📱 **Responsive** - Mobile-first design
|
|
19
|
+
- 🚀 **TypeScript** - Full type safety
|
|
23
20
|
|
|
24
|
-
|
|
21
|
+
## 📦 Installation
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
```bash
|
|
24
|
+
npm install @ciscode/ui-authentication-kit
|
|
25
|
+
# or
|
|
26
|
+
yarn add @ciscode/ui-authentication-kit
|
|
27
|
+
# or
|
|
28
|
+
pnpm add @ciscode/ui-authentication-kit
|
|
29
|
+
```
|
|
27
30
|
|
|
28
|
-
|
|
29
|
-
- `npm test` – run tests (vitest)
|
|
30
|
-
- `npm run typecheck` – TypeScript typecheck
|
|
31
|
-
- `npm run lint` – ESLint
|
|
32
|
-
- `npm run format` / `npm run format:write` – Prettier
|
|
33
|
-
- `npx changeset` – create a changeset
|
|
31
|
+
### Peer Dependencies
|
|
34
32
|
|
|
35
|
-
|
|
33
|
+
```bash
|
|
34
|
+
npm install react react-dom react-router-dom axios jwt-decode react-cookie lucide-react @ciscode/ui-translate-core
|
|
35
|
+
```
|
|
36
36
|
|
|
37
|
-
|
|
38
|
-
- Merge to `develop`
|
|
39
|
-
- Add a changeset for user-facing changes: `npx changeset`
|
|
40
|
-
- Promote `develop` → `master`
|
|
41
|
-
- Tag `vX.Y.Z` to publish (npm OIDC)
|
|
37
|
+
## 🚀 Quick Start
|
|
42
38
|
|
|
43
|
-
|
|
44
|
-
|
|
39
|
+
### 1. Wrap your app with `AuthProvider`
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
import { AuthProvider } from '@ciscode/ui-authentication-kit';
|
|
43
|
+
import { BrowserRouter } from 'react-router-dom';
|
|
44
|
+
|
|
45
|
+
function App() {
|
|
46
|
+
return (
|
|
47
|
+
<BrowserRouter>
|
|
48
|
+
<AuthProvider
|
|
49
|
+
config={{
|
|
50
|
+
apiUrl: 'https://api.example.com',
|
|
51
|
+
loginPath: '/auth/login',
|
|
52
|
+
registerPath: '/auth/register',
|
|
53
|
+
profilePath: '/auth/profile',
|
|
54
|
+
logoutPath: '/auth/logout',
|
|
55
|
+
redirectAfterLogin: '/dashboard',
|
|
56
|
+
redirectAfterLogout: '/',
|
|
57
|
+
}}
|
|
58
|
+
>
|
|
59
|
+
{/* Your app routes */}
|
|
60
|
+
</AuthProvider>
|
|
61
|
+
</BrowserRouter>
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### 2. Use authentication state
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
import { useAuthState } from '@ciscode/ui-authentication-kit';
|
|
70
|
+
|
|
71
|
+
function Dashboard() {
|
|
72
|
+
const { user, isAuthenticated, logout } = useAuthState();
|
|
73
|
+
|
|
74
|
+
if (!isAuthenticated) {
|
|
75
|
+
return <div>Please log in</div>;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
return (
|
|
79
|
+
<div>
|
|
80
|
+
<h1>Welcome, {user?.name}!</h1>
|
|
81
|
+
<button onClick={logout}>Logout</button>
|
|
82
|
+
</div>
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### 3. Protect routes with permissions
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
import { RequirePermissions } from '@ciscode/ui-authentication-kit';
|
|
91
|
+
|
|
92
|
+
function AdminPanel() {
|
|
93
|
+
return (
|
|
94
|
+
<RequirePermissions
|
|
95
|
+
fallbackpermessions={['admin.view', 'admin.edit']}
|
|
96
|
+
fallbackRoles={['super-admin']}
|
|
97
|
+
redirectTo="/unauthorized"
|
|
98
|
+
>
|
|
99
|
+
<div>Admin Content</div>
|
|
100
|
+
</RequirePermissions>
|
|
101
|
+
);
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## 📚 Documentation
|
|
106
|
+
|
|
107
|
+
- **[API Reference](docs/API.md)** - Complete API documentation
|
|
108
|
+
- **[Examples](docs/EXAMPLES.md)** - Integration examples
|
|
109
|
+
- **[Styling Guide](docs/STYLING.md)** - Customization guide
|
|
110
|
+
- **[Accessibility](docs/ACCESSIBILITY.md)** - A11y patterns
|
|
111
|
+
- **[Migration Guide](docs/MIGRATION.md)** - Upgrade guides
|
|
112
|
+
- **[Architecture](docs/ARCHITECTURE.md)** - Project structure
|
|
113
|
+
- **[Release Guide](docs/RELEASE.md)** - Release workflow
|
|
114
|
+
|
|
115
|
+
## 🎯 Key Components
|
|
116
|
+
|
|
117
|
+
| Component | Description |
|
|
118
|
+
| -------------------- | -------------------------------------------------- |
|
|
119
|
+
| `AuthProvider` | Root provider for authentication state and routing |
|
|
120
|
+
| `ProfilePage` | User profile management UI |
|
|
121
|
+
| `RequirePermissions` | Permission-based route guard |
|
|
122
|
+
| `RbacProvider` | Role-based access control context |
|
|
123
|
+
|
|
124
|
+
## 🪝 Core Hooks
|
|
125
|
+
|
|
126
|
+
| Hook | Description |
|
|
127
|
+
| ---------------------- | -------------------------------------------------------- |
|
|
128
|
+
| `useAuthState()` | Access auth state (user, isAuthenticated, login, logout) |
|
|
129
|
+
| `useHasRole(role)` | Check if user has a specific role |
|
|
130
|
+
| `useHasModule(module)` | Check if user has access to a module |
|
|
131
|
+
| `useCan(permission)` | Check if user has a permission |
|
|
132
|
+
| `useGrant()` | Access RBAC grant management |
|
|
133
|
+
|
|
134
|
+
## 🔐 RBAC Example
|
|
135
|
+
|
|
136
|
+
```tsx
|
|
137
|
+
import { RbacProvider, useHasRole, useCan } from '@ciscode/ui-authentication-kit';
|
|
138
|
+
|
|
139
|
+
function App() {
|
|
140
|
+
return (
|
|
141
|
+
<RbacProvider>
|
|
142
|
+
<Dashboard />
|
|
143
|
+
</RbacProvider>
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function Dashboard() {
|
|
148
|
+
const isAdmin = useHasRole('admin');
|
|
149
|
+
const canEditUsers = useCan('users.edit');
|
|
150
|
+
|
|
151
|
+
return (
|
|
152
|
+
<div>
|
|
153
|
+
{isAdmin && <AdminPanel />}
|
|
154
|
+
{canEditUsers && <EditButton />}
|
|
155
|
+
</div>
|
|
156
|
+
);
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## 🌐 Internationalization
|
|
161
|
+
|
|
162
|
+
The kit integrates with `@ciscode/ui-translate-core` for multi-language support:
|
|
163
|
+
|
|
164
|
+
```tsx
|
|
165
|
+
import { TranslateProvider } from '@ciscode/ui-translate-core';
|
|
166
|
+
|
|
167
|
+
<TranslateProvider locale="en" translations={translations}>
|
|
168
|
+
<AuthProvider config={config}>
|
|
169
|
+
<App />
|
|
170
|
+
</AuthProvider>
|
|
171
|
+
</TranslateProvider>;
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## 🛠️ Development
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
# Install dependencies
|
|
178
|
+
npm install
|
|
179
|
+
|
|
180
|
+
# Build the library
|
|
181
|
+
npm run build
|
|
182
|
+
|
|
183
|
+
# Run tests
|
|
184
|
+
npm test
|
|
185
|
+
|
|
186
|
+
# Type check
|
|
187
|
+
npm run typecheck
|
|
188
|
+
|
|
189
|
+
# Lint
|
|
190
|
+
npm run lint
|
|
191
|
+
|
|
192
|
+
# Format code
|
|
193
|
+
npm run format:write
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## 🤝 Contributing
|
|
197
|
+
|
|
198
|
+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
|
|
199
|
+
|
|
200
|
+
1. Fork the repository
|
|
201
|
+
2. Create a feature branch from `develop`
|
|
202
|
+
3. Make your changes with tests
|
|
203
|
+
4. Submit a PR to `develop`
|
|
204
|
+
|
|
205
|
+
## 📄 License
|
|
206
|
+
|
|
207
|
+
ISC © [CISCODE](https://github.com/CISCODE-MA)
|
|
208
|
+
|
|
209
|
+
## 🔗 Links
|
|
210
|
+
|
|
211
|
+
- [GitHub Repository](https://github.com/CISCODE-MA/AuthKit-UI)
|
|
212
|
+
- [NPM Package](https://www.npmjs.com/package/@ciscode/ui-authentication-kit)
|
|
213
|
+
- [Report Issues](https://github.com/CISCODE-MA/AuthKit-UI/issues)
|
|
214
|
+
|
|
215
|
+
## 📊 Browser Support
|
|
216
|
+
|
|
217
|
+
- Chrome (latest)
|
|
218
|
+
- Firefox (latest)
|
|
219
|
+
- Safari (latest)
|
|
220
|
+
- Edge (latest)
|
|
221
|
+
|
|
222
|
+
## 🙏 Acknowledgments
|
|
223
|
+
|
|
224
|
+
Built with modern React patterns and best practices. Designed for enterprise applications.
|