@compagnat/dc-common-ui 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,104 @@
+# @compagnat/dc-common-ui
+
+Reusable React components and hooks library.
+
+## Installation
+
+```bash
+npm install @compagnat/dc-common-ui
+```
+
+## Usage
+
+### AuthProvider
+
+Wraps your app with Cognito authentication. The configuration must be provided via the `config` prop.
+
+```tsx
+import { AuthProvider, useAuth, type AuthConfig } from '@compagnat/dc-common-ui';
+import AdminPanelSettingsIcon from '@mui/icons-material/AdminPanelSettings';
+import PersonOutlineIcon from '@mui/icons-material/PersonOutline';
+
+const authConfig: AuthConfig = {
+  userPoolId: 'YOUR_USER_POOL_ID',
+  clientId: 'YOUR_CLIENT_ID',
+  getUserIcon: (username) => {
+    if (username === 'compagnat') return <AdminPanelSettingsIcon />;
+    return <PersonOutlineIcon />;
+  },
+};
+
+function App() {
+  return (
+    <AuthProvider config={authConfig}>
+      <YourApp />
+    </AuthProvider>
+  );
+}
+```
+
+Consume auth state with the `useAuth` hook:
+
+```tsx
+function Profile() {
+  const { isAuthenticated, username, roles, userIcon, login, logout } = useAuth();
+  // ...
+}
+```
+
+#### `AuthConfig`
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `userPoolId` | `string` | yes | Cognito User Pool ID |
+| `clientId` | `string` | yes | Cognito App Client ID |
+| `getUserIcon` | `(username: string \| null \| undefined) => ReactNode` | no | Resolves a user icon from the username |
+
+#### Standalone API helpers
+
+These functions work outside React components (e.g. in API layers):
+
+```ts
+import { GetAccessToken, GetClientKey, HasRole } from '@compagnat/dc-common-ui';
+```
+
+- `GetAccessToken()` — returns the current JWT or `null`
+- `GetClientKey()` — returns the `custom:clientKey` claim or `''`
+- `GetSubClientKey()` — returns the `custom:subClientKey` claim or `''`
+- `HasRole(role)` — checks if the user has the given Cognito group role
+
+> **Note:** These functions rely on the `AuthProvider` being mounted to initialise the Cognito pool.
+
+### CookieConsent
+
+```tsx
+import { CookieConsentProvider, useCookieConsent, CookieConsentBanner } from '@compagnat/dc-common-ui';
+```
+
+Gestion du consentement aux cookies avec GTM.
+
+### Logger
+
+Pino logger configurable at runtime. By default it's disabled (`silent` level). Call `configureLogger` early in your app boot:
+
+```ts
+import { configureLogger, logger } from '@compagnat/dc-common-ui';
+
+configureLogger({ level: 'info', name: 'my-app' });
+logger.info('App started');
+```
+
+#### `LoggerConfig`
+
+| Property | Type   | Required | Description                     |
+|----------|--------|----------|---------------------------------|
+| `level`  | `string` | no     | Log level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`). Defaults to `'error'` |
+| `name`   | `string` | no     | Logger name passed to pino      |
+
+### MessageProvider
+
+```tsx
+import { MessageProvider, useMessage, sendGlobalSuccessMessage } from '@compagnat/dc-common-ui';
+```
+
+Global message queue for toasts / snackbars.