@inwink-mcp/backoffice-extension-helpers 1.0.7 → 1.0.8

package/templates/vite-extension/docs/inwink-api/query-language.md

@@ -0,0 +1,120 @@
+◂ Retour à [README](./README.md)
+
+# inwink JSON Query Language
+
+The query language is inspired by MongoDB syntax. Expressions are JSON objects where `$`-prefixed keys are operators and non-prefixed keys are entity property names.
+
+Utilisé par les `filters`, `orders` et `selects` des opérations [query](./query.md), [update](./update.md) (massupdate) et [delete](./delete.md) (massdelete).
+
+## Predicate Expressions (filters)
+
+### Comparison operators
+
+| Operator | Aliases | Meaning |
+|---|---|---|
+| `$eq` | `$equal` | Equals |
+| `$neq` | `$notEqual` | Not equals |
+| `$gt` | `$greaterThan` | Greater than |
+| `$gte` | `$greaterThanOrEqual` | Greater than or equal |
+| `$lt` | `$lessThan` | Less than |
+| `$lte` | `$lessThanOrEqual` | Less than or equal |
+
+**Implicit equality:** `{ "p1": "v1" }` is equivalent to `{ "p1": { "$eq": "v1" } }`.
+
+### Logical operators
+
+- `$and`: `{ "$and": [ { "p1": "v1" }, { "p2": "v2" } ] }`
+- `$or`: `{ "$or": [ { "p1": "v1" }, { "p2": "v2" } ] }`
+- `$not`: negates a predicate
+
+### Text operators (under `$text` namespace)
+
+| Operator | Example | Returns |
+|---|---|---|
+| `$contains` | `{ "p1": { "$text.$contains": "val" } }` | true if p1 contains "val" |
+| `$startsWith` | `{ "p1": { "$text.$startsWith": "val" } }` | true if p1 starts with "val" |
+| `$endWith` | `{ "p1": { "$text.$endWith": "val" } }` | true if p1 ends with "val" |
+| `$indexOf` | `{ "p1": { "$text.$indexOf": "val" } }` | position of first occurrence, -1 if none |
+| `$substring` | `{ "p1": { "$text.$substring": { "$startIndex": 1, "$length": 3 } } }` | substring extraction |
+| `$length` | `{ "p1": { "$text.$length": {} } }` | length of the string |
+
+Alternate syntax: `{ "p1": { "$text": { "$contains": "val" } } }` is equivalent.
+
+### Collection operators
+
+- `$any`: `{ "relateds": { "p1": "v1" } }` — true if at least one item in the collection matches.
+- `$all`: true if every item in the collection matches.
+
+### Date and time operators
+
+| Operator | Purpose |
+|---|---|
+| `$now` | Current date/time |
+| `$utcNow` | Current UTC date/time |
+| `$days`, `$hours`, `$minutes`, `$seconds`, `$milliseconds`, `$ticks`, `$timespan` | Duration construction |
+
+**Example — entities modified in the last 24 hours:**
+
+```json
+{ "validFrom": { "$gt": { "$utcNow": { "$substract": { "$days": 1 } } } } }
+```
+
+### Arithmetic operators
+
+`$add`, `$substract`, `$multiply`, `$divide`, `$modulo`
+
+**Example — sum of two properties:** `{ "p1": { "$add": { "p2": {} } } }`
+
+## Value Expressions
+
+A property is referenced by nesting JSON keys terminated with `{}`:
+
+- `{ "p1": {} }` → value of `p1`
+- `{ "p1": { "p2": {} } }` → value of `p1.p2` (deep access)
+
+## Verbose Binary Operator Syntax
+
+When fluent chaining doesn't work (e.g. when an operand is a terminal expression), use:
+
+```json
+{ "$operator": { "$left": { ... }, "$right": { ... } } }
+```
+
+## Ordering
+
+The `orders` array contains objects with `desc` (boolean) and `value` (a value expression):
+
+```json
+{
+  "orders": [
+    { "desc": true, "value": { "validFrom": {} } }
+  ]
+}
+```
+
+## Projection Expressions (selects)
+
+```json
+{ "$all": true, "secretField": false }
+```
+
+- `true` = include, `false` = exclude.
+- `$all` sets the default for all properties.
+- Nested objects define joins/expands: `{ "sessions": { "$all": true } }`
+
+## Localizable Properties and `$meta`
+
+Some properties (like `title`, `description`) are localized objects: `{ "fr": "...", "en": "..." }`. By default, operations apply to the event's default language.
+
+To force a specific language, wrap the expression in `$meta`:
+
+```json
+{
+  "$meta": {
+    "lang": "en",
+    "$token": { "title": { "$text.$contains": "search term" } }
+  }
+}
+```
+
+Nested `$meta` operators are cumulative; the closest ancestor `$meta` wins when a localizable property is evaluated.

package/templates/vite-extension/docs/inwink-api/query.md

@@ -0,0 +1,68 @@
+◂ Retour à [README](./README.md)
+
+# Query & Count (read entities)
+
+Pour la syntaxe des `filters`, `orders` et `selects`, voir [query-language.md](./query-language.md).
+
+## Query (read entities)
+
+```
+POST {api}/{shardId}/{entity}/query
+```
+
+**Request body:**
+
+```json
+{
+  "page": { "index": 0, "size": 50 },
+  "filters": { },
+  "orders": [ ],
+  "selects": { }
+}
+```
+
+- `page` — **required**. `index` starts at 0, `size` between 1 and 300 (recommended: 50).
+- `filters` — optional. A predicate expression (see "Query Language" section below).
+- `orders` — optional. An array of order clauses (see "Ordering" below). If omitted, the API sorts by `id` when available.
+- `selects` — optional. A projection expression (see "Projection" below). Defaults to `{ "$all": true }`.
+
+**Response:** `{ "data": [ ...entities ] }`
+
+### Pagination
+
+The API uses **stateless offset-based pagination** (no cursor). To fetch all records, increment `page.index` until `data.length < page.size`. Because pagination is stateless, **duplicates can occur across pages** — always deduplicate results by `id`. Missing records can also happen if the sort property is non-unique or mutable; omitting `orders` lets the API pick the safest sort.
+
+### Selecting specific fields
+
+Return only specific properties:
+
+```json
+{
+  "selects": { "$all": false, "mail": true, "firstname": true },
+  "page": { "index": 0, "size": 50 }
+}
+```
+
+### Expanding related entities (joins)
+
+```json
+{
+  "selects": {
+    "$all": true,
+    "speakers": { "$all": true }
+  },
+  "page": { "index": 0, "size": 50 }
+}
+```
+
+Related entities are **never loaded automatically** — you must explicitly request them in `selects`.
+
+---
+
+## Count
+
+```
+POST {api}/{shardId}/{entity}/count
+```
+
+Same body as query (supports `filters` and `page`) but without `selects`. Returns a **single integer**.

package/templates/vite-extension/docs/inwink-api/update.md

@@ -0,0 +1,34 @@
+◂ Retour à [README](./README.md)
+
+# Edit & Massupdate
+
+## Edit (Patch)
+
+```
+POST {api}/{shardId}/{entity}/{entityId}
+```
+
+**Request body:**
+
+```json
+{
+  "entity": { "firstname": "Jane" },
+  "selects": { "$all": true }
+}
+```
+
+**Important:** This is a **PATCH**, not a replace. Only properties present in the payload are updated. To clear a property, explicitly set it to `null`.
+
+`selects` contrôle les propriétés retournées (voir [query-language.md](./query-language.md)).
+
+---
+
+## Massupdate
+
+```
+POST {api}/{shardId}/{entity}/massupdate
+```
+
+Bulk EDIT like `UPDATE … WHERE` in SQL. S'appuie sur un filtre (voir [query-language.md](./query-language.md)).
+
+> Pour mettre à jour un lot d'entités identifiées une à une, voir aussi [import.md](./import.md).

package/templates/vite-extension/src/components/ConfirmDialog.tsx

@@ -0,0 +1,61 @@
+import { createContext, useCallback, useRef, useState, type ReactNode } from 'react';
+import Modal from './Modal';
+
+export interface ConfirmOptions {
+  title?: string;
+  message: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+}
+
+export type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
+
+export const ConfirmContext = createContext<ConfirmFn | null>(null);
+
+interface PendingConfirm extends ConfirmOptions {
+  resolve: (value: boolean) => void;
+}
+
+/**
+ * Fournit `useConfirm()` : une fonction `confirm(options)` qui ouvre un dialogue
+ * et résout `true`/`false` selon le choix de l'utilisateur. À monter une fois,
+ * haut dans l'arbre (cf. main.tsx). Idéal avant une action destructrice (`del`).
+ */
+export function ConfirmProvider({ children }: { children: ReactNode }) {
+  const [pending, setPending] = useState<PendingConfirm | null>(null);
+  const pendingRef = useRef<PendingConfirm | null>(null);
+  pendingRef.current = pending;
+
+  const confirm = useCallback<ConfirmFn>((options) => {
+    return new Promise<boolean>((resolve) => {
+      setPending({ ...options, resolve });
+    });
+  }, []);
+
+  const settle = useCallback((value: boolean) => {
+    pendingRef.current?.resolve(value);
+    setPending(null);
+  }, []);
+
+  return (
+    <ConfirmContext.Provider value={confirm}>
+      {children}
+      {pending && (
+        <Modal
+          title={pending.title ?? 'Confirmation'}
+          onClose={() => settle(false)}
+          footer={
+            <>
+              <button onClick={() => settle(false)}>{pending.cancelLabel ?? 'Annuler'}</button>
+              <button className="btn-primary" onClick={() => settle(true)}>
+                {pending.confirmLabel ?? 'Confirmer'}
+              </button>
+            </>
+          }
+        >
+          <p>{pending.message}</p>
+        </Modal>
+      )}
+    </ConfirmContext.Provider>
+  );
+}

package/templates/vite-extension/src/components/ErrorBoundary.css

@@ -0,0 +1,18 @@
+.error-boundary {
+  margin: 2rem auto;
+  max-width: 32rem;
+  padding: 1.5rem;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  background: var(--color-surface);
+  text-align: center;
+}
+
+.error-boundary__title {
+  margin-top: 0;
+}
+
+.error-boundary__message {
+  color: var(--color-text-muted);
+  word-break: break-word;
+}

package/templates/vite-extension/src/components/ErrorBoundary.tsx

@@ -0,0 +1,46 @@
+import './ErrorBoundary.css';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  /** Rendu de repli optionnel ; sinon, fallback par défaut avec « Réessayer ». */
+  fallback?: (error: Error, reset: () => void) => ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+/**
+ * Capture les erreurs de rendu des composants enfants et affiche un repli au
+ * lieu d'un écran blanc. À monter haut dans l'arbre (ex. autour de l'`Outlet`
+ * dans Layout). Ne capture PAS les erreurs asynchrones (gérées par `useAsync`).
+ */
+export default class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error('ErrorBoundary a capturé une erreur :', error, info);
+  }
+
+  private reset = () => this.setState({ error: null });
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    if (this.props.fallback) return this.props.fallback(error, this.reset);
+    return (
+      <div className="error-boundary" role="alert">
+        <h2 className="error-boundary__title">Une erreur est survenue</h2>
+        <p className="error-boundary__message">{error.message}</p>
+        <button className="btn-primary" onClick={this.reset}>
+          Réessayer
+        </button>
+      </div>
+    );
+  }
+}

package/templates/vite-extension/src/components/Layout.tsx

@@ -1,6 +1,7 @@
 import './Layout.css';
 import { Outlet } from 'react-router-dom';
 import Header from './Header';
+import ErrorBoundary from './ErrorBoundary';
 
 interface LayoutProps {
   title: string;
@@ -12,7 +13,9 @@ export default function Layout({ title }: LayoutProps) {
     <div className="app-layout">
       <Header title={title} />
       <main className="app-content">
-        <Outlet />
+        <ErrorBoundary>
+          <Outlet />
+        </ErrorBoundary>
       </main>
     </div>
   );

package/templates/vite-extension/src/components/Modal.css

@@ -0,0 +1,34 @@
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 900;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+  background: rgba(0, 0, 0, 0.4);
+}
+
+.modal {
+  width: 100%;
+  max-width: 28rem;
+  padding: 1.5rem;
+  border-radius: var(--radius);
+  background: var(--color-bg);
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
+}
+
+.modal__title {
+  margin-top: 0;
+}
+
+.modal__body {
+  color: var(--color-text);
+}
+
+.modal__footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  margin-top: 1.5rem;
+}

package/templates/vite-extension/src/components/Modal.tsx

@@ -0,0 +1,69 @@
+import './Modal.css';
+import { useEffect, useRef, type ReactNode } from 'react';
+
+interface ModalProps {
+  title: string;
+  onClose: () => void;
+  children: ReactNode;
+  /** Contenu du pied (boutons d'action). */
+  footer?: ReactNode;
+}
+
+const FOCUSABLE =
+  'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Boîte modale minimale : overlay, fermeture par Échap / clic extérieur, focus
+ * piégé à l'intérieur. Base pour ConfirmDialog et tout dialogue personnalisé.
+ */
+export default function Modal({ title, onClose, children, footer }: ModalProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    ref.current?.focus();
+
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        onClose();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      const focusables = ref.current?.querySelectorAll<HTMLElement>(FOCUSABLE);
+      if (!focusables || focusables.length === 0) return;
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      previouslyFocused?.focus();
+    };
+  }, [onClose]);
+
+  return (
+    <div className="modal-overlay" onMouseDown={onClose}>
+      <div
+        ref={ref}
+        className="modal"
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        tabIndex={-1}
+        onMouseDown={(e) => e.stopPropagation()}
+      >
+        <h2 className="modal__title">{title}</h2>
+        <div className="modal__body">{children}</div>
+        {footer && <div className="modal__footer">{footer}</div>}
+      </div>
+    </div>
+  );
+}

package/templates/vite-extension/src/components/feedback/EmptyState.css

@@ -0,0 +1,15 @@
+.empty-state {
+  padding: 2rem 1rem;
+  text-align: center;
+  color: var(--color-text-muted);
+}
+
+.empty-state__title {
+  margin: 0;
+  font-weight: 600;
+}
+
+.empty-state__message {
+  margin: 0.25rem 0 0;
+  font-size: 0.9rem;
+}

package/templates/vite-extension/src/components/feedback/EmptyState.tsx

@@ -0,0 +1,20 @@
+import './EmptyState.css';
+import type { ReactNode } from 'react';
+
+interface EmptyStateProps {
+  title?: string;
+  message?: string;
+  /** Action optionnelle (ex. bouton « Créer »). */
+  children?: ReactNode;
+}
+
+/** État « aucun résultat » réutilisable pour les listes vides. */
+export default function EmptyState({ title = 'Aucun résultat', message, children }: EmptyStateProps) {
+  return (
+    <div className="empty-state">
+      <p className="empty-state__title">{title}</p>
+      {message && <p className="empty-state__message">{message}</p>}
+      {children}
+    </div>
+  );
+}

package/templates/vite-extension/src/components/feedback/ErrorState.css

@@ -0,0 +1,12 @@
+.error-state {
+  padding: 1.25rem;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  background: var(--color-surface);
+  text-align: center;
+}
+
+.error-state__message {
+  margin: 0 0 0.75rem;
+  color: var(--color-text);
+}

package/templates/vite-extension/src/components/feedback/ErrorState.tsx

@@ -0,0 +1,28 @@
+import './ErrorState.css';
+import { InwinkApiError } from '../../hooks/useInwinkApi';
+
+interface ErrorStateProps {
+  error: unknown;
+  /** Callback de relance ; affiche un bouton « Réessayer » si fourni. */
+  onRetry?: () => void;
+}
+
+function describe(error: unknown): string {
+  if (error instanceof InwinkApiError) {
+    return error.status === 403
+      ? "Vous n'avez pas les droits pour cette action (403)."
+      : `Erreur lors de l'appel à l'API inwink (code ${error.status}).`;
+  }
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+/** Affiche une erreur d'appel API de façon lisible (gère `InwinkApiError`). */
+export default function ErrorState({ error, onRetry }: ErrorStateProps) {
+  return (
+    <div className="error-state" role="alert">
+      <p className="error-state__message">{describe(error)}</p>
+      {onRetry && <button onClick={onRetry}>Réessayer</button>}
+    </div>
+  );
+}

package/templates/vite-extension/src/components/feedback/Spinner.css

@@ -0,0 +1,21 @@
+.spinner {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  color: var(--color-text-muted);
+}
+
+.spinner__circle {
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid var(--color-border);
+  border-top-color: var(--color-accent);
+  border-radius: 50%;
+  animation: spinner-spin 0.6s linear infinite;
+}
+
+@keyframes spinner-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}

package/templates/vite-extension/src/components/feedback/Spinner.tsx

@@ -0,0 +1,15 @@
+import './Spinner.css';
+
+interface SpinnerProps {
+  label?: string;
+}
+
+/** Indicateur de chargement accessible. */
+export default function Spinner({ label = 'Chargement…' }: SpinnerProps) {
+  return (
+    <div className="spinner" role="status" aria-live="polite">
+      <span className="spinner__circle" aria-hidden />
+      <span className="spinner__label">{label}</span>
+    </div>
+  );
+}

package/templates/vite-extension/src/components/toast/ToastProvider.css

@@ -0,0 +1,59 @@
+.toast-stack {
+  position: fixed;
+  right: 1rem;
+  bottom: 1rem;
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  max-width: min(24rem, calc(100vw - 2rem));
+}
+
+.toast {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+  padding: 0.75rem 1rem;
+  border-radius: var(--radius);
+  background: var(--color-text);
+  color: #fff;
+  box-shadow: var(--shadow-sm);
+  animation: toast-in 0.15s ease;
+}
+
+.toast--success {
+  background: #1f8a4c;
+}
+
+.toast--error {
+  background: var(--color-accent);
+}
+
+.toast--info {
+  background: var(--color-text);
+}
+
+.toast__message {
+  flex: 1;
+  font-size: 0.9rem;
+}
+
+.toast__close {
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: inherit;
+  font-size: 1.1rem;
+  line-height: 1;
+}
+
+.toast__close:hover:not(:disabled) {
+  border-color: transparent;
+}
+
+@keyframes toast-in {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem);
+  }
+}