@astratra/saas-kit-ui 1.0.1 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Astratra
+Copyright (c) 2026 Astratra contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,9 +1,6 @@
 # @astratra/saas-kit-ui
 
-Interface React reutilisable pour demarrer rapidement un dashboard SaaS
-Astratra. Le package expose une application dashboard complete et quelques
-primitives (`AuthProvider`, `useAuth`, `apiFetch`) pour composer une interface
-plus specifique.
+Interface React réutilisable pour démarrer rapidement un tableau de bord SaaS. Le paquet expose une application complète (connexion, vue d'ensemble, utilisateurs, réglages) et quelques primitives (`AuthProvider`, `useAuth`, `apiFetch`) pour composer une interface plus spécifique. Il est prévu pour un backend `@astratra/saas-kit`.
 
 ## Installation
 
@@ -11,10 +8,9 @@ plus specifique.
 npm install @astratra/saas-kit-ui react react-dom
 ```
 
-Dans le repo Astratra, `examples/dashboard-ui` montre son integration avec un
-backend `@astratra/saas-kit`.
+React 18 ou plus récent. Le dépôt contient `examples/dashboard-ui`, qui montre l'intégration avec un backend `@astratra/saas-kit`.
 
-## Utilisation
+## Exemple
 
 ```jsx
 import React from 'react';
@@ -28,42 +24,73 @@ createRoot(document.getElementById('root')).render(
 );
 ```
 
-Par defaut, l'interface appelle `http://localhost:4000`. Avec Vite, definis
-`VITE_API_URL` pour pointer vers ton backend :
+Le paquet importe sa feuille de styles avec l'application ; elle est aussi disponible séparément via `@astratra/saas-kit-ui/styles.css`. Par défaut, l'interface appelle `http://localhost:4000`. Avec Vite, définissez `VITE_API_URL` pour pointer vers votre backend :
 
 ```bash
-VITE_API_URL=http://localhost:4000 npm run dev
+VITE_API_URL=https://api.exemple.fr npm run dev
 ```
 
-## Surface exportee
-
-- `AstratraDashboardApp` : dashboard complet login/users/settings/overview.
-- `AuthProvider` et `useAuth` : session bearer token en memoire.
-- `apiFetch` et `ApiError` : client minimal compatible avec les reponses
-  `apiResponse` d'`@astratra/core`.
-
-Le package ne contient pas de serveur Express et ne fixe aucun domaine metier.
-Le backend reste fourni par `@astratra/saas-kit` ou par ton application.
-
-## `AuthProvider`/`useAuth` vs `@astratra/react`
-
-Deux packages Astratra exposent des primitives de session React, avec des
-choix différents et volontaires — ce n'est pas un doublon accidentel :
-
-- **`AuthProvider`/`useAuth` (ce package)** : garde le JWT en mémoire JS et
-  l'attache en `Authorization: Bearer` via `apiFetch`. Couplé au dashboard
-  complet `AstratraDashboardApp` (login/users/settings/overview) — conçu
-  pour démarrer vite avec un backend `@astratra/saas-kit` standard, pas pour
-  être réutilisé isolément dans une UI déjà existante.
-- **`SessionProvider`/`useSession` (`@astratra/react`)** : ne stocke aucun
-  token côté client — la session vit dans un cookie `HttpOnly` géré par le
-  backend, l'app injecte juste `getSession`/`signIn`/`signOut`. Pas de
-  dashboard imposé, pas de routes fixes ; à choisir quand tu construis ta
-  propre UI par-dessus `@astratra/saas-kit` (avec les cookies de session
-  activés côté `@astratra/security`) plutôt que d'utiliser
-  `AstratraDashboardApp` tel quel.
-
-En résumé : utilise ce package si `AstratraDashboardApp` te convient tel
-quel ; utilise `@astratra/react` si tu construis ta propre interface et que
-ton backend utilise les sessions cookie `HttpOnly` plutôt qu'un token Bearer
-géré côté client.
+## Ce que le tableau de bord attend du backend
+
+| Écran | Appels |
+| --- | --- |
+| Connexion | `POST /auth/login` avec `{ email, password }` ; réponse `{ token, user }`. |
+| Vue d'ensemble | `GET /dashboard/summary` |
+| Utilisateurs | `GET /users?limit=50&offset=0`, `POST /users` |
+| Réglages | `GET /settings`, `PATCH /settings/<clé>` avec `{ value }` |
+
+Les réponses suivent le format `apiResponse` d'`@astratra/core` : `{ success, data, message }`.
+
+## Exports
+
+| Export | Rôle |
+| --- | --- |
+| `AstratraDashboardApp` (aussi export par défaut) | Tableau de bord complet. |
+| `AuthProvider`, `useAuth` | Session par jeton Bearer gardé en mémoire ; `useAuth()` rend `isAuthenticated`, `token`, `user`, `login`, `logout` et `request`. |
+| `apiFetch(chemin, options)`, `ApiError` | Client minimal. Options : `apiUrl`, `token`, `method`, `body`, `fetcher`, `onUnauthorized`. |
+| `Layout`, `Notice` | Composants de mise en page et de message. |
+| `DashboardScreen`, `LoginScreen`, `SettingsScreen`, `UsersScreen` | Les écrans, réutilisables séparément. |
+
+## Ce que le paquet ne fait pas
+
+- Il ne contient pas de serveur et ne fixe aucun domaine métier ; le backend est fourni par `@astratra/saas-kit` ou par votre application.
+- Le jeton n'est gardé qu'en mémoire : un rechargement de la page déconnecte l'utilisateur.
+- Il n'est pas conçu pour être branché sur une interface existante qui utilise des sessions par cookie `HttpOnly` : voir `@astratra/react`.
+
+## `AuthProvider`/`useAuth` et `@astratra/react`
+
+- **`AuthProvider`/`useAuth` (ce paquet)** : garde le JWT en mémoire et l'envoie en `Authorization: Bearer` via `apiFetch`. Couplé à `AstratraDashboardApp`.
+- **`SessionProvider`/`useSession` (`@astratra/react`)** : ne stocke aucun jeton côté client ; la session vit dans un cookie `HttpOnly` géré par le backend. Pas de tableau de bord imposé.
+
+Utilisez ce paquet si `AstratraDashboardApp` vous convient tel quel ; utilisez `@astratra/react` si vous construisez votre propre interface sur des sessions par cookie.
+
+## Licence
+
+MIT.
+
+## FeedbackBar : 👍 / 👎 sous une réponse d'IA
+
+Le même composant que dans `@astratra/native-ui`, pour le web. Contrôlé :
+l'application garde `value` et parle à son serveur (par exemple
+`createFeedbackRouter` de `@astratra/agent`).
+
+```jsx
+import { FeedbackBar } from '@astratra/saas-kit-ui';
+
+<FeedbackBar
+  value={feedback?.rating ?? null}
+  onSubmit={(payload) => api.giveFeedback(runId, payload)} // { rating, reason?, comment? }
+  onRemove={() => api.removeFeedback(runId)}
+  locale="fr"
+/>
+```
+
+Le pouce haut part aussitôt ; le pouce bas ouvre un panneau (raison,
+commentaire facultatif) ; appuyer sur le pouce choisi le retire. Libellés par
+défaut en anglais et en français (`locale`), remplaçables un par un (`labels`) ;
+raisons ajoutables (`reasons`) ; `icons` remplace les émojis ; `haptics` est une
+fonction facultative (rien par défaut). Accessibilité : groupe nommé, boutons à
+`aria-pressed`, puces `radio`, panneau `dialog`, Échap le ferme. Le style vient
+des classes `.astratra-feedback*` de `styles.css` et des variables CSS du kit.
+Les règles pures (`feedbackPress`, `buildFeedbackPayload`, `resolveFeedbackLabels`,
+`feedbackReasonOptions`, `clampComment`) sont exportées.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astratra/saas-kit-ui",
-  "version": "1.0.1",
-  "description": "Reusable React dashboard shell for Astratra SaaS applications.",
+  "version": "1.1.0",
+  "description": "Reusable React dashboard shell for Astratra SaaS applications, plus a thumbs up/down feedback bar for AI answers.",
   "engines": {
     "node": ">=20"
   },

package/src/components/FeedbackBar.js

@@ -0,0 +1,70 @@
+import { createElement as h, useId, useState } from 'react';
+import {
+  FEEDBACK_COMMENT_MAX,
+  FEEDBACK_REASONS,
+  buildFeedbackPayload,
+  feedbackPress,
+  feedbackReasonOptions,
+  resolveFeedbackLabels
+} from '../lib/feedbackBar.js';
+
+const THUMBS = { up: '\u{1F44D}', down: '\u{1F44E}' };
+
+/**
+ * Thumbs up / thumbs down under an AI answer. Controlled: the app keeps
+ * `value` and talks to its server in `onSubmit` / `onRemove`. Up is sent at
+ * once; down opens a small panel for a reason and an optional comment;
+ * pressing the chosen thumb again withdraws it. Words come from `labels` and
+ * `locale`. Colours come from the kit's CSS variables, with fallbacks.
+ */
+export default function FeedbackBar({
+  value = null, onSubmit, onRemove, disabled = false, reasons = FEEDBACK_REASONS, maxComment = FEEDBACK_COMMENT_MAX,
+  labels, locale, icons, haptics, defaultOpen = false, className, style, id
+}) {
+  const words = resolveFeedbackLabels({ locale, labels });
+  const [asking, setAsking] = useState(Boolean(defaultOpen));
+  const [reason, setReason] = useState(null);
+  const [comment, setComment] = useState('');
+  const titleId = useId();
+  const tick = () => { if (typeof haptics === 'function') { try { haptics(); } catch (_error) { /* never blocks a rating */ } } };
+  const close = () => { setAsking(false); setReason(null); setComment(''); };
+  const press = (rating) => {
+    if (disabled) return;
+    tick();
+    const action = feedbackPress(value, rating);
+    if (action.type === 'remove') onRemove?.();
+    else if (action.type === 'ask') setAsking(true);
+    else if (action.type === 'submit') onSubmit?.(action.payload);
+  };
+  const send = () => {
+    tick();
+    const payload = buildFeedbackPayload({ rating: 'down', reason, comment, reasons, maxComment });
+    close();
+    onSubmit?.(payload);
+  };
+  const thumb = (rating) => h('button', {
+    key: rating, type: 'button', disabled, 'aria-pressed': value === rating, 'aria-label': words[rating], title: words[rating],
+    className: 'astratra-feedback__thumb', 'data-rating': rating, onClick: () => press(rating)
+  }, icons?.[rating] ?? h('span', { 'aria-hidden': 'true' }, THUMBS[rating]));
+
+  const options = feedbackReasonOptions({ reasons, labels: words, selected: reason });
+  return h('div', { id, role: 'group', 'aria-label': words.group, className: ['astratra-feedback', className].filter(Boolean).join(' '), style },
+    thumb('up'), thumb('down'),
+    asking && h('div', {
+      role: 'dialog', 'aria-modal': 'false', 'aria-labelledby': titleId, className: 'astratra-feedback__sheet',
+      onKeyDown: (event) => { if (event.key === 'Escape') close(); }
+    },
+    h('p', { id: titleId, className: 'astratra-feedback__title' }, words.sheetTitle),
+    h('div', { role: 'radiogroup', 'aria-labelledby': titleId, className: 'astratra-feedback__reasons' },
+      options.map((option) => h('button', {
+        key: option.id, type: 'button', role: 'radio', 'aria-checked': option.selected, className: 'astratra-feedback__chip',
+        onClick: () => setReason(option.selected ? null : option.id)
+      }, option.label))),
+    h('label', { className: 'astratra-feedback__comment' },
+      h('span', { className: 'astratra-feedback__label' }, words.commentLabel),
+      h('textarea', { value: comment, maxLength: maxComment, placeholder: words.commentPlaceholder, rows: 3, onChange: (event) => setComment(event.target.value) }),
+      h('span', { className: 'astratra-feedback__counter', 'aria-hidden': 'true' }, words.counter(Array.from(comment).length, maxComment))),
+    h('div', { className: 'astratra-feedback__actions' },
+      h('button', { type: 'button', className: 'astratra-feedback__cancel', onClick: close }, words.cancel),
+      h('button', { type: 'button', className: 'astratra-feedback__send', onClick: send }, words.submit))));
+}

package/src/index.jsx

@@ -7,3 +7,14 @@ export { default as DashboardScreen } from './screens/Dashboard.jsx';
 export { default as LoginScreen } from './screens/Login.jsx';
 export { default as SettingsScreen } from './screens/Settings.jsx';
 export { default as UsersScreen } from './screens/Users.jsx';
+export { default as FeedbackBar } from './components/FeedbackBar.js';
+export {
+  FEEDBACK_COMMENT_MAX,
+  FEEDBACK_LABELS,
+  FEEDBACK_REASONS,
+  buildFeedbackPayload,
+  clampComment,
+  feedbackPress,
+  feedbackReasonOptions,
+  resolveFeedbackLabels
+} from './lib/feedbackBar.js';

package/src/lib/feedbackBar.js

@@ -0,0 +1,61 @@
+// Pure rules of the feedback bar (thumbs up / down on an AI answer).
+// Same rules as the mobile bar in @astratra/native-ui; no React here.
+
+export const FEEDBACK_REASONS = Object.freeze(['inaccurate', 'incomplete', 'off_topic', 'wrong_source', 'too_long', 'unsafe', 'other']);
+export const FEEDBACK_COMMENT_MAX = 500;
+
+export const FEEDBACK_LABELS = Object.freeze({
+  en: Object.freeze({
+    group: 'Rate this answer', up: 'Good answer', down: 'Bad answer', sheetTitle: 'What went wrong?',
+    commentLabel: 'Comment (optional)', commentPlaceholder: 'Tell us more (optional)', submit: 'Send', cancel: 'Cancel',
+    reasons: Object.freeze({ inaccurate: 'Inaccurate', incomplete: 'Incomplete', off_topic: 'Off topic', wrong_source: 'Wrong source', too_long: 'Too long', unsafe: 'Unsafe', other: 'Other' }),
+    counter: (used, max) => `${used}/${max}`
+  }),
+  fr: Object.freeze({
+    group: 'Évaluer cette réponse', up: 'Bonne réponse', down: 'Mauvaise réponse', sheetTitle: "Qu'est-ce qui n'allait pas ?",
+    commentLabel: 'Commentaire (facultatif)', commentPlaceholder: 'Dites-nous en plus (facultatif)', submit: 'Envoyer', cancel: 'Annuler',
+    reasons: Object.freeze({ inaccurate: 'Inexacte', incomplete: 'Incomplète', off_topic: 'Hors sujet', wrong_source: 'Mauvaise source', too_long: 'Trop longue', unsafe: 'Dangereuse', other: 'Autre' }),
+    counter: (used, max) => `${used}/${max}`
+  })
+});
+
+const TEXT_KEYS = ['group', 'up', 'down', 'sheetTitle', 'commentLabel', 'commentPlaceholder', 'submit', 'cancel'];
+
+/** Labels for a locale ('fr…' is French, anything else English), with the app's overrides on top. */
+export function resolveFeedbackLabels({ locale, labels } = {}) {
+  const language = typeof locale === 'string' ? locale.toLowerCase().split(/[-_]/)[0] : 'en';
+  const base = FEEDBACK_LABELS[language] || FEEDBACK_LABELS.en;
+  const given = labels && typeof labels === 'object' ? labels : {};
+  const out = {};
+  for (const key of TEXT_KEYS) out[key] = typeof given[key] === 'string' && given[key] ? given[key] : base[key];
+  out.reasons = { ...base.reasons, ...(given.reasons && typeof given.reasons === 'object' ? given.reasons : {}) };
+  out.counter = typeof given.counter === 'function' ? given.counter : base.counter;
+  return out;
+}
+
+/** What pressing a thumb does: withdraw the chosen one, send up at once, ask why for down. */
+export function feedbackPress(value, rating) {
+  if (rating !== 'up' && rating !== 'down') return { type: 'none' };
+  if (value === rating) return { type: 'remove' };
+  return rating === 'up' ? { type: 'submit', payload: { rating: 'up' } } : { type: 'ask' };
+}
+
+export function clampComment(text, max = FEEDBACK_COMMENT_MAX) {
+  if (typeof text !== 'string') return '';
+  const chars = Array.from(text);
+  return chars.length <= max ? text : chars.slice(0, max).join('');
+}
+
+/** The body to send: a reason only with 'down' and only if listed; blank comment dropped; trimmed and cut. */
+export function buildFeedbackPayload({ rating, reason, comment, reasons = FEEDBACK_REASONS, maxComment = FEEDBACK_COMMENT_MAX } = {}) {
+  if (rating !== 'up' && rating !== 'down') throw new Error("rating must be 'up' or 'down'.");
+  const payload = { rating };
+  if (rating === 'down' && typeof reason === 'string' && reasons.includes(reason)) payload.reason = reason;
+  const text = clampComment(typeof comment === 'string' ? comment.trim() : '', maxComment).trim();
+  if (text) payload.comment = text;
+  return payload;
+}
+
+export function feedbackReasonOptions({ reasons = FEEDBACK_REASONS, labels, selected }) {
+  return reasons.map((id) => ({ id, label: labels.reasons[id] || id, selected: id === selected }));
+}

package/src/styles/global.css

@@ -96,3 +96,123 @@ h3 {
     transition-duration: 1ms !important;
   }
 }
+
+/* FeedbackBar: thumbs up / down under an AI answer. */
+.astratra-feedback {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.astratra-feedback__thumb {
+  width: 32px;
+  height: 32px;
+  display: inline-grid;
+  place-items: center;
+  border: 1px solid var(--line, #2e3a31);
+  border-radius: 999px;
+  background: transparent;
+  cursor: pointer;
+  opacity: 0.7;
+  transition: opacity 120ms, background 120ms;
+}
+
+.astratra-feedback__thumb:hover:not(:disabled),
+.astratra-feedback__thumb:focus-visible {
+  opacity: 1;
+  background: var(--panel-raised, #1a231d);
+}
+
+.astratra-feedback__thumb[aria-pressed="true"] {
+  opacity: 1;
+  border-color: var(--lime, #d9ff66);
+  background: var(--panel-raised, #1a231d);
+}
+
+.astratra-feedback__thumb:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.astratra-feedback__sheet {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  z-index: 10;
+  width: min(360px, 90vw);
+  display: grid;
+  gap: 10px;
+  padding: 14px;
+  border: 1px solid var(--line-bright, #46584c);
+  border-radius: 12px;
+  background: var(--panel, #141b17);
+  color: var(--cream, #f4f1e6);
+}
+
+.astratra-feedback__title {
+  margin: 0;
+  font-weight: 600;
+}
+
+.astratra-feedback__reasons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.astratra-feedback__chip {
+  padding: 5px 10px;
+  border: 1px solid var(--line, #2e3a31);
+  border-radius: 999px;
+  background: transparent;
+  cursor: pointer;
+}
+
+.astratra-feedback__chip[aria-checked="true"] {
+  border-color: var(--lime, #d9ff66);
+  background: var(--panel-raised, #1a231d);
+}
+
+.astratra-feedback__comment {
+  display: grid;
+  gap: 4px;
+}
+
+.astratra-feedback__label,
+.astratra-feedback__counter {
+  font-size: 0.8em;
+  color: var(--muted, #7c8a7a);
+}
+
+.astratra-feedback__counter {
+  text-align: right;
+}
+
+.astratra-feedback__comment textarea {
+  resize: vertical;
+  padding: 8px;
+  border: 1px solid var(--line, #2e3a31);
+  border-radius: 8px;
+  background: var(--bg, #0d1310);
+}
+
+.astratra-feedback__actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+}
+
+.astratra-feedback__cancel,
+.astratra-feedback__send {
+  padding: 6px 14px;
+  border: 1px solid var(--line, #2e3a31);
+  border-radius: 8px;
+  background: transparent;
+  cursor: pointer;
+}
+
+.astratra-feedback__send {
+  border-color: var(--lime, #d9ff66);
+  color: var(--lime, #d9ff66);
+}