create-astram-app 0.13.0 → 0.14.0

package/template/frontend/src/shell/NotificationsMenu.jsx

@@ -1,8 +1,11 @@
 /**
  * NotificationsMenu — the header bell (G-027 step 5): the user's PERSONAL notices (changes to
- * their own access). Badge = unread personal count (useNotificationCounts). The list loads when
- * the menu opens; opening marks nothing read. Clicking a notice marks it read and follows its
- * link only when app-relative; "Mark all read" clears the category. Text only, never HTML.
+ * their own access, and app notices). Badge = unread personal count (useNotificationCounts). The
+ * list (unread only, newest 20; G-035) loads when the menu opens; opening marks nothing read.
+ * Each row carries its severity dot. Clicking a notice marks it read and follows its link only
+ * when app-relative; "Mark all read" clears the category; "View all notifications" opens the
+ * Notifications page (`/notifications?tab=personal`), with "N more" when over 20 are unread.
+ * Text only, never HTML.
  *
  * Also exports the pieces AnnouncementsMenu reuses: `HeaderMenuTrigger` (the header icon button
  * with tooltip and count badge) and `NoticeSection` (one category's notices).
@@ -10,7 +13,7 @@
 import { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
-import { Bell, CheckCheck, Loader2, RotateCw } from 'lucide-react';
+import { Bell, CheckCheck, ListChecks, Loader2, RotateCw } from 'lucide-react';
 import { toast } from 'sonner';
 import { useAuth } from '@/auth/AuthContext';
 import { cn } from '@/lib/utils';
@@ -22,7 +25,16 @@ import {
   DropdownMenuLabel,
   DropdownMenuSeparator,
 } from '@/components/ui/dropdown-menu';
-import { badgeLabel, badgeText, relativeTime, safeAppLink } from './notificationsView';
+import {
+  DROPDOWN_LIMIT,
+  badgeLabel,
+  badgeText,
+  moreText,
+  relativeTime,
+  safeAppLink,
+  severityInfo,
+  viewAllHref,
+} from './notificationsView';
 import { useNotificationCounts } from './useNotificationCounts';
 
 /**
@@ -110,19 +122,19 @@ export function MenuError({ text, onRetry }) {
   );
 }
 
-const LIST_LIMIT = 20;
-
 /**
- * One category's latest notices. Mounted only while the menu is open (Radix unmounts closed
- * content), so it loads on open. `heading` (optional) labels the section.
+ * One category's newest UNREAD notices (G-035: at most 20, plus "N more" and a "View all
+ * notifications" link to the Notifications page tab). Mounted only while the menu is open
+ * (Radix unmounts closed content), so it loads on open. `heading` (optional) labels the section;
+ * `emptyText` defaults to "You're all caught up".
  */
-export function NoticeSection({ category, heading, emptyText }) {
+export function NoticeSection({ category, heading, emptyText = 'You’re all caught up' }) {
   const { tokens, notifications } = useAuth();
   const counts = useNotificationCounts();
   const { refresh } = counts;
   const navigate = useNavigate();
   const token = tokens?.accessToken ?? null;
-  const [view, setView] = useState({ status: 'loading', rows: [], error: '', now: 0 });
+  const [view, setView] = useState({ status: 'loading', rows: [], total: 0, error: '', now: 0 });
   const [busyAll, setBusyAll] = useState(false);
   const alive = useRef(true);
   // Bumped per list load and when "Mark all read" starts, so only the latest load applies: a
@@ -139,9 +151,14 @@ export function NoticeSection({ category, heading, emptyText }) {
   const load = useCallback(async () => {
     if (!token) return;
     const seq = ++loadSeq.current;
-    const r = await notifications.listNotifications(token, { category, limit: LIST_LIMIT });
+    const r = await notifications.listNotifications(token, {
+      category,
+      unread: true,
+      limit: DROPDOWN_LIMIT,
+    });
     if (!alive.current || seq !== loadSeq.current) return;
-    if (r.ok) setView({ status: 'ready', rows: r.rows, error: '', now: Date.now() });
+    if (r.ok)
+      setView({ status: 'ready', rows: r.rows, total: r.total, error: '', now: Date.now() });
     else setView((v) => ({ ...v, status: 'error', error: r.error }));
   }, [notifications, token, category]);
 
@@ -181,6 +198,8 @@ export function NoticeSection({ category, heading, emptyText }) {
 
   const unreadInList = view.rows.some((row) => !row.readAt);
   const unreadCount = category === 'personal' ? counts.personal : counts.announcement;
+  const more = moreText(view.total, view.rows.length);
+  const allHref = viewAllHref(category);
 
   return (
     <section aria-label={heading || undefined}>
@@ -197,6 +216,7 @@ export function NoticeSection({ category, heading, emptyText }) {
       {view.status === 'ready' &&
         view.rows.map((row) => {
           const unread = !row.readAt;
+          const severity = severityInfo(row.severity);
           return (
             <DropdownMenuItem
               key={row.uuid}
@@ -205,14 +225,11 @@ export function NoticeSection({ category, heading, emptyText }) {
             >
               <span
                 aria-hidden="true"
-                className={cn(
-                  'mt-1.5 size-2 shrink-0 rounded-full',
-                  unread ? 'bg-primary' : 'bg-transparent',
-                )}
+                className={cn('mt-1.5 size-2 shrink-0 rounded-full', severity.dotClass)}
               />
               <span className="min-w-0 flex-1">
                 <span className={cn('block text-sm', unread ? 'font-semibold' : 'font-normal')}>
-                  {unread && <span className="sr-only">Unread: </span>}
+                  <span className="sr-only">{`${severity.label}${unread ? ', unread' : ''}: `}</span>
                   {row.title}
                 </span>
                 {row.body && (
@@ -244,6 +261,20 @@ export function NoticeSection({ category, heading, emptyText }) {
           Mark all read
         </DropdownMenuItem>
       )}
+      {view.status !== 'loading' && (
+        <div className="flex items-center justify-between gap-2 border-t border-border px-1 pt-1">
+          <DropdownMenuItem
+            onSelect={() => navigate(allHref)}
+            className="text-xs font-medium text-primary focus:text-primary"
+          >
+            <ListChecks aria-hidden="true" />
+            View all notifications
+          </DropdownMenuItem>
+          {view.status === 'ready' && more && (
+            <span className="px-2 text-xs text-muted-foreground">{more}</span>
+          )}
+        </div>
+      )}
     </section>
   );
 }
@@ -256,7 +287,7 @@ export default function NotificationsMenu() {
       <DropdownMenuContent align="end" className="w-96 max-w-[calc(100vw-2rem)]">
         <DropdownMenuLabel>Notifications</DropdownMenuLabel>
         <DropdownMenuSeparator />
-        <NoticeSection category="personal" emptyText="You have no notifications." />
+        <NoticeSection category="personal" />
       </DropdownMenuContent>
     </DropdownMenu>
   );

package/template/frontend/src/shell/notificationsView.js

@@ -1,7 +1,8 @@
 /**
  * notificationsView — React-free helpers for the header bell and Announcements menus (G-027
- * step 5). Kept pure so `node --test` covers them (notificationsView.test.mjs); the menus in
- * NotificationsMenu.jsx / AnnouncementsMenu.jsx only render what these return.
+ * step 5; unread-only lists, severity dot and "View all" footer, G-035). Kept pure so
+ * `node --test` covers them (notificationsView.test.mjs); the menus in NotificationsMenu.jsx /
+ * AnnouncementsMenu.jsx and the Notifications page only render what these return.
  */
 
 /** The counts poll interval (spec §10: 60 s, plus window focus). */
@@ -136,3 +137,41 @@ export function announcementsBadgeCount(counts) {
   const t = Number.isFinite(counts?.tasks) ? counts.tasks : 0;
   return a + t;
 }
+
+// --- G-035 notification center: unread-only dropdowns, severity, "View all" -----------------
+
+/** How many unread notices a dropdown loads (spec §10: 20 unread). */
+export const DROPDOWN_LIMIT = 20;
+
+/** The Notifications page tab for a category: `personal` (bell) or `announcement`. */
+export function viewAllHref(category) {
+  const tab = category === 'announcement' ? 'announcement' : 'personal';
+  return `/notifications?tab=${tab}`;
+}
+
+/**
+ * The dropdown footer's "N more" (N = unread total − rows shown), or '' when every unread
+ * notice is already shown (or the numbers are not counts).
+ */
+export function moreText(total, shown) {
+  if (!Number.isFinite(total) || !Number.isFinite(shown)) return '';
+  const n = Math.floor(total) - Math.floor(shown);
+  return n > 0 ? `${n} more` : '';
+}
+
+const SEVERITY = Object.freeze({
+  info: Object.freeze({ label: 'Info', dotClass: 'bg-primary' }),
+  success: Object.freeze({ label: 'Success', dotClass: 'bg-ok' }),
+  warning: Object.freeze({ label: 'Warning', dotClass: 'bg-warn' }),
+});
+
+/**
+ * A notice's severity dot: `{ label, dotClass }` (theme tokens only). Anything but `success` or
+ * `warning` reads as `info`, the default (spec §10). The label goes in sr-only text beside the
+ * dot, so colour is never the only signal.
+ */
+export function severityInfo(severity) {
+  return Object.prototype.hasOwnProperty.call(SEVERITY, severity)
+    ? SEVERITY[severity]
+    : SEVERITY.info;
+}

package/template/frontend/src/shell/notificationsView.test.mjs

@@ -6,7 +6,11 @@
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  DROPDOWN_LIMIT,
   POLL_MS,
+  moreText,
+  severityInfo,
+  viewAllHref,
   announcementsBadgeCount,
   badgeLabel,
   badgeText,
@@ -180,3 +184,37 @@ describe('shouldPoll', () => {
     assert.equal(POLL_MS, 60_000);
   });
 });
+
+describe('dropdown footer (G-035)', () => {
+  test('loads 20 unread', () => {
+    assert.equal(DROPDOWN_LIMIT, 20);
+  });
+  test('25 unread, 20 shown ⇒ "5 more" (spec §12)', () => {
+    assert.equal(moreText(25, 20), '5 more');
+  });
+  test('all shown, or not counts ⇒ no "N more"', () => {
+    assert.equal(moreText(20, 20), '');
+    assert.equal(moreText(3, 3), '');
+    assert.equal(moreText(0, 0), '');
+    assert.equal(moreText(undefined, 0), '');
+    assert.equal(moreText(5, NaN), '');
+  });
+  test('View all links to the category tab', () => {
+    assert.equal(viewAllHref('personal'), '/notifications?tab=personal');
+    assert.equal(viewAllHref('announcement'), '/notifications?tab=announcement');
+    assert.equal(viewAllHref('anything'), '/notifications?tab=personal');
+  });
+});
+
+describe('severityInfo', () => {
+  test('theme-token dot and an sr label per severity', () => {
+    assert.deepEqual({ ...severityInfo('info') }, { label: 'Info', dotClass: 'bg-primary' });
+    assert.deepEqual({ ...severityInfo('success') }, { label: 'Success', dotClass: 'bg-ok' });
+    assert.deepEqual({ ...severityInfo('warning') }, { label: 'Warning', dotClass: 'bg-warn' });
+  });
+  test('unknown or missing ⇒ info (the default)', () => {
+    for (const s of [undefined, null, '', 'error', 'toString']) {
+      assert.equal(severityInfo(s).label, 'Info');
+    }
+  });
+});

package/template/server/_env.example

@@ -190,7 +190,9 @@ NODE_ENV=development
 
 # --- OPTIONAL: in-app notification retention ---
 # Read notices are deleted after the first value (days, 1-3650), every notice after the second
-# (at least the first, at most 3650), counted from when the notice was posted.
+# (at least the first, at most 3650), counted from when the notice was posted. Archived notices
+# follow the same rule (archiving never keeps a notice longer). Unset ⇒ 90 and 365; an invalid
+# value stops the server at start-up naming the setting. A clean-up runs every hour.
 # NOTIFICATION_READ_RETENTION_DAYS=90
 # NOTIFICATION_MAX_RETENTION_DAYS=365
 

package/template/server/package.json

@@ -23,10 +23,10 @@
   "dependencies": {
     "@astram/core": "1.14.0",
     "@astram/engine": "0.16.2",
-    "@astram/guard": "0.25.1",
+    "@astram/guard": "0.27.0",
     "@astram/guide": "^0.2.8",
-    "@astram/identity": "0.23.0",
-    "@astram/messaging": "0.1.11",
+    "@astram/identity": "0.25.0",
+    "@astram/messaging": "0.1.13",
     "@astram/migrate": "0.7.4",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",

package/template/server/src/app.module.ts

@@ -88,6 +88,9 @@ import { DemoController } from './health/demo.controller';
  *   `recordAuthorization` or `decisionAuthority` to `ShieldModule`: boot fails (one source).
  *   Every route is `@Classified` — enforced by the same deny-by-default guard. Omit the
  *   module and login still works; the admin pages 404.
+ *   Company hierarchy comes with it: a parent-company admin administers the companies below
+ *   theirs (the session's subtree is resolved at sign-in). No `scopeSubtreeResolver` option
+ *   is needed; pass one to `ShieldModule.forRoot` only to replace the framework's.
  *
  *   ⛔ IF YOU REGISTER YOUR OWN OWNED OBJECT TYPES (e.g. a `Note`): pass them to
  *   `IdentityFeatureModule.forRoot({ extraObjects: [Note] })` (the ONE place: their action
@@ -106,6 +109,19 @@ import { DemoController } from './health/demo.controller';
  *        ],
  *   The frontend ships the matching pages/widget (RecordPoliciesPage, ShareDialog)
  *   already wired to `useAuth().recordPolicy` / `.recordShare`.
+ *
+ * OPTIONAL — YOUR OWN NOTIFICATIONS (with `auth: true`): register each kind you post, then post
+ *   with `src/notifications/app-notifications.service.ts` (an example to copy). `personal` kinds
+ *   show in the bell, `announcement` kinds under the Announcements icon; users see `label` as the
+ *   type (≤ 40 characters; unset ⇒ made from the kind) and `severity` (info | success | warning)
+ *   as a coloured dot. Kinds are dotted lower-case names; `shield.` is reserved:
+ *        ShieldModule.forRoot({ auth: true, logoutRequiresProof: true,
+ *          notificationKinds: [
+ *            { kind: 'app.task_assigned', category: 'personal', label: 'Task assigned', severity: 'warning' },
+ *            { kind: 'app.release_news', category: 'announcement', label: 'Release news' },
+ *          ] }),
+ *   How long notices are kept: NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS
+ *   in `.env` (see `_env.example`).
  */
 @Module({
   // Enforcement-only by default (boots with no config). For real login + the identity

package/template/server/src/notifications/app-notifications.service.spec.ts

@@ -0,0 +1,26 @@
+import type { NotificationService } from '@astram/guard';
+import { AppNotificationsService } from './app-notifications.service';
+
+describe('AppNotificationsService (example)', () => {
+  it('posts the kind, title, body and link to the given users in the given company', async () => {
+    const post = vi.fn().mockResolvedValue({ created: 2, skipped: 0 });
+    const svc = new AppNotificationsService({ post } as unknown as NotificationService);
+
+    const result = await svc.notifyUsers('company-1', ['user-1', 'user-2'], {
+      kind: 'app.task_assigned',
+      title: 'Order 123 needs your approval',
+      link: '/orders/123',
+    });
+
+    expect(result).toEqual({ created: 2, skipped: 0 });
+    expect(post).toHaveBeenCalledWith({
+      tenantId: 'company-1',
+      recipients: ['user-1', 'user-2'],
+      kind: 'app.task_assigned',
+      title: 'Order 123 needs your approval',
+      body: null,
+      link: '/orders/123',
+      dedupeKey: null,
+    });
+  });
+});

package/template/server/src/notifications/app-notifications.service.ts

@@ -0,0 +1,41 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { SHIELD_NOTIFICATIONS, type NotificationService } from '@astram/guard';
+
+/**
+ * EXAMPLE — send your own notices to the bell and Announcements menus (copy and extend).
+ *
+ * Not registered by default: add `AppNotificationsService` to a module's `providers` once
+ * `ShieldModule.forRoot({ auth: true, notificationKinds: [...] })` is on (`SHIELD_NOTIFICATIONS`
+ * exists only with `auth: true`). Register every kind you post in `notificationKinds`
+ * (see `app.module.ts`): `category: 'personal'` shows in the bell, `'announcement'` under the
+ * Announcements icon; `label` is what users see as the type, `severity` colours the dot.
+ *
+ * Rules:
+ * - `tenantId` comes from the session (`principal.tenantId`) or the record you just saved, never
+ *   from a request body or query.
+ * - `link` is an app path (`/orders/123`): clicking the notice opens it. The target page still
+ *   checks access itself — a notice never grants anything.
+ * - Notices are plain text: no passwords, tokens or other users' data in the title or body.
+ * - Only active users with an active membership in `tenantId` receive it; the rest are skipped.
+ */
+@Injectable()
+export class AppNotificationsService {
+  constructor(@Inject(SHIELD_NOTIFICATIONS) private readonly notifications: NotificationService) {}
+
+  /** Post one notice to each user ⇒ `{ created, skipped }` (1–1000 users per call). */
+  async notifyUsers(
+    tenantId: string,
+    userIds: readonly string[],
+    notice: { kind: string; title: string; body?: string; link?: string; dedupeKey?: string },
+  ): Promise<{ created: number; skipped: number }> {
+    return this.notifications.post({
+      tenantId,
+      recipients: userIds,
+      kind: notice.kind,
+      title: notice.title,
+      body: notice.body ?? null,
+      link: notice.link ?? null,
+      dedupeKey: notice.dedupeKey ?? null,
+    });
+  }
+}