create-astram-app 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced NestJS server (deny-by-default, built-in auth/identity to switch on) and, with --with-frontend, a React admin/auth UI, over the immutable @astram/* framework packages.",
   "type": "module",

package/template/README.md

@@ -122,6 +122,24 @@ action })` for guarded ones. Anything unclassified is denied by design (403; wit
 
 `server/src/features/` starts empty — it's your space.
 
+## Send your own notifications
+
+The header has a bell (personal notices) and an Announcements icon; both show unread notices,
+and **View all notifications** opens the full page (`/notifications`) with search, filters,
+mark unread and archive. Your features can post into the same menus:
+
+1. With `auth: true`, register each kind in `ShieldModule.forRoot({ notificationKinds })`:
+   `category: 'personal'` (bell) or `'announcement'`, a `label` users see (≤ 40 characters) and
+   an optional `severity` (`info` | `success` | `warning`). See the comment in
+   `server/src/app.module.ts`.
+2. Post with `server/src/notifications/app-notifications.service.ts` (an example to copy; add it
+   to your module's `providers`):
+   `notifyUsers(tenantId, [userId], { kind: 'app.task_assigned', title: 'Order 123 needs your approval', link: '/orders/123' })`.
+   Clicking the notice opens `link`; that page still checks access itself. Take `tenantId` from
+   the session or the record you saved, never from the request body.
+3. How long notices are kept: `NOTIFICATION_READ_RETENTION_DAYS` (default 90) and
+   `NOTIFICATION_MAX_RETENTION_DAYS` (default 365) in `server/.env` (see `server/_env.example`).
+
 ## Bootstrap your organisation
 
 `npm run bootstrap:org` (in `server/`) creates your organisation (tenants, companies,

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node scripts/run-tests.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.10.0",
+    "@astram/frontend-core": "^0.11.0",
     "@astram/sdk": "^0.2.1",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",

package/template/frontend/src/App.jsx

@@ -41,6 +41,7 @@ import GrantsPage from './pages/cross-tenant/GrantsPage';
 import GrantForm from './pages/cross-tenant/GrantForm';
 import InboxPage from './pages/cross-tenant/InboxPage';
 import SecuritySettingsPage from './pages/security/SecuritySettingsPage';
+import NotificationsPage from './pages/notifications/NotificationsPage';
 
 /** Only-when-signed-out (auth screens bounce authenticated users to the app). */
 function PublicOnly({ children }) {
@@ -164,6 +165,17 @@ export default function App() {
           </RequireAuth>
         }
       />
+      {/* Notifications (G-035) — every notice of the signed-in user in the active company,
+          reached from the bell / Announcements "View all notifications". Signed in only, no
+          permission key: the server binds every call to the session's own user and company. */}
+      <Route
+        path="/notifications"
+        element={
+          <RequireAuth>
+            <NotificationsPage />
+          </RequireAuth>
+        }
+      />
       {/* Account — a persistent layout with per-tab child routes (bookmarkable, back
           works). /account redirects to the Profile tab. */}
       <Route

package/template/frontend/src/pages/notifications/NotificationsPage.jsx

@@ -0,0 +1,550 @@
+/**
+ * NotificationsPage — every notice of the signed-in user in the active company (G-035,
+ * notification-center SPEC §5F), reached from the bell and Announcements menus ("View all
+ * notifications"). Any signed-in user; no permission key: the server binds every call to the
+ * session's user and company, so a user only ever sees and changes their own notices.
+ *
+ * Tabs Notifications (`personal`) / Announcements (`announcement`); a server-paged EntityList
+ * with search, Type / Status / Date filters and page sizes 10/20/50/100. Tab, filters, search,
+ * page and limit live in the URL (notificationList.js), so a reload or a shared link keeps the
+ * view. A row click marks the notice read and follows its link when app-relative. Row actions
+ * and the bulk bar mark read / unread and archive / unarchive; "Mark all read" clears the tab.
+ * After each change the list reloads and the header badges refresh.
+ *
+ * Title, body and type label are plain React text (never HTML). No raw uuids: a row's uuid is a
+ * React key and a call argument only; the type shows `kindLabel`, never `kind`.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useNavigate, useSearchParams } from 'react-router-dom';
+import { Bell, CheckCheck, Loader2, MoreHorizontal, RotateCw } from 'lucide-react';
+import { toast } from 'sonner';
+import { useAuth } from '@/auth/AuthContext';
+import AppShell from '@/shell/AppShell';
+import { useNotificationCounts } from '@/shell/useNotificationCounts';
+import { badgeText, safeAppLink, severityInfo } from '@/shell/notificationsView';
+import PageHeader from '@/components/PageHeader';
+import EntityList, { EntityListControls, EntityListPager } from '@/components/EntityList';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Checkbox } from '@/components/ui/checkbox';
+import { DateField } from '@/components/ui/date-field';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { cn } from '@/lib/utils';
+import {
+  BULK_ACTIONS,
+  BULK_MAX,
+  DATE_OPTIONS,
+  PAGE_SIZES,
+  STATUS_OPTIONS,
+  TABS,
+  buildListQuery,
+  bulkDoneText,
+  dateRange,
+  emptyText,
+  keepSelection,
+  kindOptionsFor,
+  pageStateToParams,
+  readPageState,
+  receivedText,
+  rowActions,
+  statusLabel,
+  statusVariant,
+} from './notificationList';
+
+// Radix Select items cannot carry an empty value: '' (All / Any) travels as this sentinel.
+const ALL = '__all__';
+const toSelect = (v) => (v ? v : ALL);
+const fromSelect = (v) => (v === ALL ? '' : v);
+
+/** The single-notice service call for each action. */
+const SINGLE_CALL = {
+  read: 'markNotificationRead',
+  unread: 'markNotificationUnread',
+  archive: 'archiveNotification',
+  unarchive: 'unarchiveNotification',
+};
+
+/** One filter select (Type / Status / Date). */
+function FilterSelect({ label, value, options, onChange, className }) {
+  return (
+    <Select value={toSelect(value)} onValueChange={(v) => onChange(fromSelect(v))}>
+      <SelectTrigger className={cn('h-9', className)} aria-label={label}>
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        {options.map((o) => (
+          <SelectItem key={o.value || ALL} value={toSelect(o.value)}>
+            {o.label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
+/** The tab strip (WAI-ARIA tabs: arrow keys move between the two tabs). */
+function CategoryTabs({ tab, counts, onChange }) {
+  const onKeyDown = (e) => {
+    if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
+    e.preventDefault();
+    const i = TABS.findIndex((t) => t.value === tab);
+    const next = TABS[(i + (e.key === 'ArrowRight' ? 1 : TABS.length - 1)) % TABS.length];
+    onChange(next.value);
+    document.getElementById(`notifications-tab-${next.value}`)?.focus();
+  };
+  return (
+    <div role="tablist" aria-label="Notification type" className="mb-3 flex gap-1 border-b">
+      {TABS.map((t) => {
+        const active = t.value === tab;
+        const unread = badgeText(counts[t.value]);
+        return (
+          <button
+            key={t.value}
+            id={`notifications-tab-${t.value}`}
+            type="button"
+            role="tab"
+            aria-selected={active}
+            aria-controls="notifications-panel"
+            tabIndex={active ? 0 : -1}
+            onClick={() => onChange(t.value)}
+            onKeyDown={onKeyDown}
+            className={cn(
+              '-mb-px inline-flex items-center gap-2 border-b-2 px-3 py-2 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+              active
+                ? 'border-primary text-foreground'
+                : 'border-transparent text-muted-foreground hover:text-foreground',
+            )}
+          >
+            {t.label}
+            {unread && (
+              <Badge variant="info" className="px-1.5 py-0">
+                {unread}
+                <span className="sr-only"> unread</span>
+              </Badge>
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export default function NotificationsPage() {
+  const { tokens, notifications } = useAuth();
+  const counts = useNotificationCounts();
+  const { refresh } = counts;
+  const navigate = useNavigate();
+  const token = tokens?.accessToken ?? null;
+  const [searchParams, setSearchParams] = useSearchParams();
+  // The URL is the one source of the view; every change writes it back (replace, no history spam).
+  const state = useMemo(() => readPageState(searchParams), [searchParams]);
+
+  const [data, setData] = useState({ status: 'loading', rows: [], total: 0, error: '' });
+  const [kinds, setKinds] = useState([]);
+  const [selected, setSelected] = useState(() => new Set());
+  const [busy, setBusy] = useState(false);
+  // Bumped per load: only the latest answer applies (a slow older answer never overwrites it).
+  const loadSeq = useRef(0);
+
+  const update = useCallback(
+    (patch) => setSearchParams(pageStateToParams({ ...state, ...patch }), { replace: true }),
+    [state, setSearchParams],
+  );
+
+  const load = useCallback(
+    async (signal) => {
+      if (!token) return;
+      const seq = ++loadSeq.current;
+      setData((d) => ({ ...d, status: 'loading' }));
+      const r = await notifications.listNotifications(
+        token,
+        buildListQuery(state, Date.now()),
+        signal,
+      );
+      if (signal?.aborted || seq !== loadSeq.current) return;
+      if (r.ok) {
+        setData({ status: 'ready', rows: r.rows, total: r.total, error: '' });
+        setSelected((s) => keepSelection(s, r.rows));
+      } else {
+        setData({ status: 'error', rows: [], total: 0, error: r.error });
+      }
+    },
+    [notifications, token, state],
+  );
+
+  useEffect(() => {
+    const ac = new AbortController();
+    void load(ac.signal);
+    return () => ac.abort();
+  }, [load]);
+
+  // The Type filter's options: the kinds this user has notices of (failure ⇒ only "All types").
+  useEffect(() => {
+    if (!token) return undefined;
+    const ac = new AbortController();
+    void (async () => {
+      const r = await notifications.listNotificationKinds(token);
+      if (!ac.signal.aborted && r.ok) setKinds(r.kinds);
+    })();
+    return () => ac.abort();
+  }, [notifications, token]);
+
+  // Past the last page (e.g. the last row on it was archived away): step back to the last page.
+  useEffect(() => {
+    if (data.status !== 'ready' || data.rows.length > 0 || state.page <= 1 || data.total <= 0) {
+      return;
+    }
+    update({ page: Math.max(1, Math.ceil(data.total / state.limit)) });
+  }, [data, state.page, state.limit, update]);
+
+  const kindOptions = useMemo(
+    () => [{ value: '', label: 'All types' }, ...kindOptionsFor(kinds, state.tab)],
+    [kinds, state.tab],
+  );
+  const range = dateRange(state);
+
+  /** After a successful change: reload this page and the header badges. */
+  const afterChange = useCallback(() => {
+    void load();
+    void refresh();
+  }, [load, refresh]);
+
+  // One notice, one action. A failure shows the fixed error text and leaves the row as it was.
+  const actOne = useCallback(
+    async (action, row) => {
+      if (!token || busy) return;
+      setBusy(true);
+      const r = await notifications[SINGLE_CALL[action]](token, row.uuid);
+      setBusy(false);
+      if (!r.ok) {
+        toast.error(r.error);
+        return;
+      }
+      afterChange();
+    },
+    [notifications, token, busy, afterChange],
+  );
+
+  const actBulk = async (action) => {
+    const uuids = [...selected].slice(0, BULK_MAX);
+    if (!token || busy || uuids.length === 0) return;
+    setBusy(true);
+    const r = await notifications.bulkUpdateNotifications(token, action, uuids);
+    setBusy(false);
+    if (!r.ok) {
+      toast.error(r.error);
+      return;
+    }
+    toast.success(bulkDoneText(action, r.updated));
+    setSelected(new Set());
+    afterChange();
+  };
+
+  const markAllRead = async () => {
+    if (!token || busy) return;
+    setBusy(true);
+    const r = await notifications.markAllNotificationsRead(token, state.tab);
+    setBusy(false);
+    if (!r.ok) {
+      toast.error(r.error);
+      return;
+    }
+    toast.success(bulkDoneText('read', r.updated));
+    afterChange();
+  };
+
+  // Row click: mark read (if unread), then follow an app-relative link; else reload in place.
+  const openRow = useCallback(
+    async (row) => {
+      if (busy) return;
+      if (!row.readAt && token) {
+        const r = await notifications.markNotificationRead(token, row.uuid);
+        if (!r.ok) toast.error(r.error);
+      }
+      const link = safeAppLink(row.link);
+      void refresh();
+      if (link) navigate(link);
+      else void load();
+    },
+    [busy, token, notifications, refresh, navigate, load],
+  );
+
+  const pageUuids = data.rows.map((r) => r.uuid);
+  const selectedOnPage = pageUuids.filter((u) => selected.has(u)).length;
+  const allChecked =
+    selectedOnPage > 0 && selectedOnPage === pageUuids.length
+      ? true
+      : selectedOnPage > 0
+        ? 'indeterminate'
+        : false;
+
+  const toggleOne = (uuid, on) =>
+    setSelected((s) => {
+      const next = new Set(s);
+      if (on) next.add(uuid);
+      else next.delete(uuid);
+      return next;
+    });
+  const toggleAll = (on) => setSelected(on ? new Set(pageUuids) : new Set());
+
+  const columns = [
+    {
+      key: 'select',
+      label: (
+        <Checkbox
+          checked={allChecked}
+          onCheckedChange={(v) => toggleAll(v === true)}
+          disabled={data.rows.length === 0}
+          aria-label="Select all notifications on this page"
+        />
+      ),
+      render: (row) => (
+        <Checkbox
+          checked={selected.has(row.uuid)}
+          onCheckedChange={(v) => toggleOne(row.uuid, v === true)}
+          aria-label={`Select “${row.title}”`}
+        />
+      ),
+    },
+    {
+      key: 'severity',
+      label: <span className="sr-only">Severity</span>,
+      render: (row) => {
+        const s = severityInfo(row.severity);
+        return (
+          <span className="inline-flex items-center">
+            <span aria-hidden="true" className={cn('size-2 rounded-full', s.dotClass)} />
+            <span className="sr-only">{s.label}</span>
+          </span>
+        );
+      },
+    },
+    {
+      key: 'notification',
+      label: 'Notification',
+      render: (row) => (
+        <div className="min-w-0 max-w-xl text-left">
+          <div className={cn('text-sm', row.readAt ? 'font-normal' : 'font-semibold')}>
+            {row.title}
+          </div>
+          {row.body && (
+            <div className="mt-0.5 line-clamp-2 whitespace-pre-line text-xs text-muted-foreground">
+              {row.body}
+            </div>
+          )}
+          <div className="mt-1 text-[11px] text-muted-foreground">{row.kindLabel}</div>
+        </div>
+      ),
+    },
+    {
+      key: 'received',
+      label: 'Received',
+      render: (row) => (
+        <span className="whitespace-nowrap text-sm">{receivedText(row.createdAt) || '—'}</span>
+      ),
+    },
+    {
+      key: 'status',
+      label: 'Status',
+      render: (row) => <Badge variant={statusVariant(row)}>{statusLabel(row)}</Badge>,
+    },
+    {
+      key: 'actions',
+      label: <span className="sr-only">Actions</span>,
+      render: (row) => (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <button
+              type="button"
+              disabled={busy}
+              aria-label={`Actions for “${row.title}”`}
+              className="inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+            >
+              <MoreHorizontal className="size-4" />
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-40">
+            {rowActions(row).map((a) => (
+              <DropdownMenuItem key={a.action} onClick={() => void actOne(a.action, row)}>
+                {a.label}
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ),
+    },
+  ];
+
+  // EntityList keys rows by `id` (never shown).
+  const listRows = data.rows.map((row) => ({ ...row, id: row.uuid }));
+
+  return (
+    <AppShell title="Notifications">
+      <div className="p-4">
+        <PageHeader
+          title="Notifications"
+          icon={Bell}
+          actions={
+            <>
+              <EntityListControls
+                search={state.search}
+                onSearchChange={(search) => update({ search, page: 1 })}
+                searchPlaceholder="Search notifications…"
+              />
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                className="shrink-0"
+                disabled={busy || data.status !== 'ready'}
+                onClick={() => void markAllRead()}
+              >
+                <CheckCheck className="size-4" aria-hidden="true" />
+                Mark all read
+              </Button>
+            </>
+          }
+        />
+
+        <CategoryTabs
+          tab={state.tab}
+          counts={counts}
+          onChange={(tab) => {
+            if (tab !== state.tab) update({ tab, kind: '', page: 1 });
+          }}
+        />
+
+        <div
+          id="notifications-panel"
+          role="tabpanel"
+          aria-labelledby={`notifications-tab-${state.tab}`}
+        >
+          <div className="mb-3 flex flex-wrap items-center gap-2">
+            <FilterSelect
+              label="Type"
+              value={state.kind}
+              options={kindOptions}
+              onChange={(kind) => update({ kind, page: 1 })}
+              className="w-44"
+            />
+            <FilterSelect
+              label="Status"
+              value={state.status}
+              options={STATUS_OPTIONS}
+              onChange={(status) => update({ status, page: 1 })}
+              className="w-32"
+            />
+            <FilterSelect
+              label="Date"
+              value={state.date}
+              options={DATE_OPTIONS}
+              onChange={(date) =>
+                update(date === 'custom' ? { date, page: 1 } : { date, from: '', to: '', page: 1 })
+              }
+              className="w-36"
+            />
+            {state.date === 'custom' && (
+              <>
+                <DateField
+                  value={state.from}
+                  max={state.to || undefined}
+                  onChange={(e) => update({ from: e.target.value, page: 1 })}
+                  aria-label="From date"
+                  aria-invalid={range.invalid || undefined}
+                  className="w-40"
+                />
+                <span className="text-sm text-muted-foreground">to</span>
+                <DateField
+                  value={state.to}
+                  min={state.from || undefined}
+                  onChange={(e) => update({ to: e.target.value, page: 1 })}
+                  aria-label="To date"
+                  aria-invalid={range.invalid || undefined}
+                  className="w-40"
+                />
+              </>
+            )}
+            {range.invalid && (
+              <p role="alert" className="text-xs text-destructive">
+                The start date is after the end date; no date filter is applied.
+              </p>
+            )}
+          </div>
+
+          {selected.size > 0 && (
+            <div
+              role="region"
+              aria-label="Selected notifications"
+              className="mb-3 flex flex-wrap items-center gap-2 rounded-lg border bg-muted/40 px-3 py-2 text-sm"
+            >
+              <span className="mr-1 font-medium">{selected.size} selected</span>
+              {BULK_ACTIONS.map((a) => (
+                <Button
+                  key={a.action}
+                  type="button"
+                  size="sm"
+                  variant="outline"
+                  disabled={busy}
+                  onClick={() => void actBulk(a.action)}
+                >
+                  {a.label}
+                </Button>
+              ))}
+              <Button
+                type="button"
+                size="sm"
+                variant="ghost"
+                disabled={busy}
+                onClick={() => setSelected(new Set())}
+              >
+                Clear selection
+              </Button>
+              {busy && <Loader2 className="size-4 animate-spin" aria-hidden="true" />}
+            </div>
+          )}
+
+          <EntityList
+            columns={columns}
+            rows={listRows}
+            loading={data.status === 'loading'}
+            error={data.status === 'error' ? data.error : ''}
+            emptyLabel={emptyText(state)}
+            onRowClick={(row) => void openRow(row)}
+          />
+
+          {data.status === 'error' && (
+            <div className="mt-3 flex justify-end">
+              <Button type="button" size="sm" variant="outline" onClick={() => void load()}>
+                <RotateCw className="size-4" aria-hidden="true" />
+                Try again
+              </Button>
+            </div>
+          )}
+
+          <EntityListPager
+            total={data.total}
+            page={state.page}
+            limit={state.limit}
+            loading={data.status === 'loading'}
+            error={data.status === 'error' ? data.error : ''}
+            pageSizes={PAGE_SIZES}
+            onPageChange={(page) => update({ page })}
+            onLimitChange={(limit) => update({ limit, page: 1 })}
+          />
+        </div>
+      </div>
+    </AppShell>
+  );
+}