@asteby/metacore-notifications 38.0.0 → 38.1.0

package/README.md

@@ -51,6 +51,101 @@ import { NotificationsDropdown } from '@asteby/metacore-notifications'
 - `metadata.addon_key` / `apartado` — module chip (Inventario, Almacén, POS, …)
 - `metadata.color` — optional CSS/hex override for the icon disc
 
+## Host with its own contract
+
+Everything below is optional; without these props the dropdown behaves exactly
+as before (`GET apiBasePath` → `{ data: [] }`, one `PATCH ${apiBasePath}/${id}`
+per item, unread count computed over the loaded page, empty message while
+loading or on a failed request). Only the live-toast id changed (`ntf-<id>`).
+
+| Prop | Purpose |
+|---|---|
+| `listParams` | Object or `(perPage) => object` replacing the default `orderBy/orderDir/per_page` query. |
+| `parseList(body)` | Reads the response: `{ items, unreadCount?, total? }`. A server `unreadCount` wins over the local count. |
+| `normalizeItem(raw)` | Maps each row **and each live payload** to a `NotificationItem` (`read_at` → `is_read`, `action_url` → `link`…). `NotificationItem.id` may be `string \| number`. |
+| `onMarkRead(ids)` / `onMarkAllRead()` | Replace the default PATCHes. Optimistic update, rolled back if the promise rejects. With only `onMarkRead`, "mark all" calls it with the unread ids. |
+| `onDelete(id)` | Shows a trash button per row (second click confirms; rolled back on failure). Labels: `delete`, `confirmDelete`. |
+| `fetchUnreadCount` + `unreadPollMs` | Server counter, polled only while the tab is visible (and on becoming visible). `0`/unset = no polling. |
+| `badgeMax`, `triggerAriaLabel(unread)` | Badge cap (default `99` → `99+`) and trigger `aria-label`. |
+| `onIngest(payload, item)` | Called once per NEW live notification (after dedup) — sound, query invalidation, hidden-tab push belong to the host. |
+| `footer`, `closeOnClick`, `renderAvatar`, `item.user` | Extra footer (`ReactNode` or `(close) => ReactNode`), menu close behaviour, custom avatar or `user: { name, avatar }` with initials fallback. |
+| `richText`, `reloadAfterPermission` | See below; `reloadAfterPermission={false}` skips the page reload after granting push permission. |
+| `showLoadStates` (default `false`) | Opt in to the "loading" and "error + retry" states (`labels.loading / error / retry`). Off, the list shows the usual empty message while loading and after a failed request, as before. |
+
+`onNotificationClick` receives the full normalized item (metadata included).
+When it is present nothing is opened by default; without it only absolute
+`http(s)` links are opened (`window.open`), relative links are a no-op — pass
+`onNotificationClick` to navigate inside a SPA. The live toast delegates its
+click to the same handler.
+
+`closeOnClick`: Radix already closes the menu when an item is selected, so the
+unset default keeps closing. `true` closes explicitly, `false` keeps it open.
+
+Deleting from the keyboard: focus the row (arrow keys) and press `Delete`
+(Supr); a live region announces `labels.confirmDeleteKey` ("Pulsa Supr otra vez
+para eliminar") and a second `Delete` on the same row confirms. Moving focus
+away cancels. The trash button is a pointer-only affordance (`aria-hidden`,
+`tabIndex=-1`) because an interactive control inside a `role="menuitem"` is not
+valid ARIA and Radix only focuses items.
+
+Concurrency: optimistic rollbacks are incremental (they only count rows still
+present and currently read/unread, so live notifications that arrived meanwhile
+are kept), a failed delete restores the row with its current read flag, and
+`fetchUnreadCount` results that overlap an in-flight action are discarded (the
+next poll reconciles). `listParams` as a function must be deterministic (no
+`Date.now()`): it is serialized every render to detect changes. Links are opened
+with `window.open(url, '_blank', 'noopener,noreferrer')`; live toasts use the id
+`ntf-<id>` so numeric ids cannot collide with sonner's own.
+
+### Example: `{ notifications, unread_count }` + `read_at`
+
+```tsx
+<NotificationsDropdown
+  apiClient={api}
+  apiBasePath='/notifications'
+  listParams={(n) => ({ limit: n })}
+  parseList={(body) => {
+    const b = body as { notifications: unknown[]; unread_count: number }
+    return { items: b.notifications, unreadCount: b.unread_count }
+  }}
+  normalizeItem={(raw) => {
+    const r = raw as Record<string, any>
+    return {
+      id: r.id, // numeric ids are fine
+      title: r.title,
+      message: r.body ?? '',
+      type: r.type ?? 'info',
+      is_read: r.read_at != null,
+      created_at: r.created_at,
+      link: r.action_url,
+      image: r.image_url,
+      metadata: r.meta_payload,
+    }
+  }}
+  onMarkRead={(ids) => api.post('/notifications/mark-read', { notification_ids: ids }).then(() => {})}
+  onMarkAllRead={() => api.post('/notifications/mark-read', { mark_all: true }).then(() => {})}
+  onDelete={(id) => api.delete(`/notifications/${id}`).then(() => {})}
+  fetchUnreadCount={() => api.get('/notifications/unread-count').then((r) => r.data.count)}
+  unreadPollMs={60_000}
+  onNotificationClick={(n) => navigate({ to: n.link })}
+  onIngest={(payload, item) => playSound()}
+  footer={(close) => <Link to='/notifications' onClick={close}>Ver todas</Link>}
+  richText={false}
+/>
+```
+
+### Rich text and XSS
+
+By default (`richText` true) bodies go through `formatNotificationBodyHtml`,
+a small **regex/tokenizer sanitizer** (allowlist: `strong b em i u mark code br
+span`, no attributes; any other `<` is escaped) rendered with
+`dangerouslySetInnerHTML`. It has hostile-input tests (`<img onerror>`,
+`javascript:` hrefs, `on*` attributes, `<svg onload>`, malformed nesting,
+`<b/onclick=…>`), but it is not a DOM-based sanitizer. The body of campaigns
+and other **user-authored content is untrusted**: pass `richText={false}` to
+the dropdown (and to `showNotificationToast`) so it is painted as plain text
+escaped by React.
+
 ## API
 
 - `GET {apiBasePath}` → `{ data: NotificationItem[] }`

package/dist/dropdown.d.ts

@@ -2,6 +2,10 @@ import type { NotificationsDropdownProps } from './types';
 /**
  * Bell-icon dropdown: REST list + live ingest (SSE preferred, WebSocket
  * fallback) + optional canonical card toast on every new item.
+ *
+ * Every prop beyond `apiClient` / `apiBasePath` is optional; without them the
+ * component keeps its original contract (`{ data: [] }` list, one PATCH per
+ * item, local unread count).
  */
-export declare function NotificationsDropdown({ apiClient, apiBasePath, enableBadge, onNotificationClick, perPage, locale, labels: labelsOverride, resolveImageUrl, subscribeToNotifications, sseUrl, sseAccessToken, preferSse, showToastOnIngest, }: NotificationsDropdownProps): import("react").JSX.Element;
+export declare function NotificationsDropdown({ apiClient, apiBasePath, enableBadge, onNotificationClick, perPage, locale, labels: labelsOverride, resolveImageUrl, subscribeToNotifications, sseUrl, sseAccessToken, preferSse, showToastOnIngest, listParams, parseList, normalizeItem, onMarkRead, onMarkAllRead, onDelete, fetchUnreadCount, unreadPollMs, badgeMax, triggerAriaLabel, onIngest, footer, closeOnClick, renderAvatar, richText, reloadAfterPermission, showLoadStates, }: NotificationsDropdownProps): import("react").JSX.Element;
 //# sourceMappingURL=dropdown.d.ts.map

package/dist/dropdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dropdown.d.ts","sourceRoot":"","sources":["../src/dropdown.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAIV,0BAA0B,EAC3B,MAAM,SAAS,CAAA;AAuBhB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,WAAW,EACX,WAAkB,EAClB,mBAAmB,EACnB,OAAY,EACZ,MAAW,EACX,MAAM,EAAE,cAAc,EACtB,eAAe,EACf,wBAAwB,EACxB,MAAM,EACN,cAAc,EACd,SAAS,EACT,iBAAwB,GACzB,EAAE,0BAA0B,+BA4N5B"}
+{"version":3,"file":"dropdown.d.ts","sourceRoot":"","sources":["../src/dropdown.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAMV,0BAA0B,EAC3B,MAAM,SAAS,CAAA;AA+ChB;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,WAAW,EACX,WAAkB,EAClB,mBAAmB,EACnB,OAAY,EACZ,MAAW,EACX,MAAM,EAAE,cAAc,EACtB,eAAe,EACf,wBAAwB,EACxB,MAAM,EACN,cAAc,EACd,SAAS,EACT,iBAAwB,EACxB,UAAU,EACV,SAAS,EACT,aAAa,EACb,UAAU,EACV,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,QAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,QAAe,EACf,qBAA4B,EAC5B,cAAsB,GACvB,EAAE,0BAA0B,+BAke5B"}