create-astram-app 0.13.0 → 0.14.0

package/template/frontend/src/pages/notifications/notificationList.js

@@ -0,0 +1,268 @@
+/**
+ * notificationList — React-free helpers for the Notifications page (G-035, notification-center
+ * SPEC §5F): URL state ⇄ list query, date presets, status labels, row and bulk actions, empty
+ * text. Kept pure so `node --test` covers them (notificationList.test.mjs); NotificationsPage.jsx
+ * only renders what these return. (Not named `notificationsPage.js`: on a case-insensitive file
+ * system `./NotificationsPage` would resolve to it.)
+ *
+ * The URL holds the whole view (tab, kind, status, date, from, to, search, page, limit) so a
+ * reload or a shared link keeps it. A hand-edited URL never poisons the state: every value is
+ * checked and falls back to its default.
+ */
+
+/** Tabs (spec §10): category → label. */
+export const TABS = Object.freeze([
+  Object.freeze({ value: 'personal', label: 'Notifications' }),
+  Object.freeze({ value: 'announcement', label: 'Announcements' }),
+]);
+
+/** Page sizes (spec §10) and the default. */
+export const PAGE_SIZES = Object.freeze([10, 20, 50, 100]);
+export const DEFAULT_LIMIT = 20;
+
+/** Status filter (spec §10): '' = All (the server leaves archived notices out). */
+export const STATUS_OPTIONS = Object.freeze([
+  Object.freeze({ value: '', label: 'All' }),
+  Object.freeze({ value: 'unread', label: 'Unread' }),
+  Object.freeze({ value: 'read', label: 'Read' }),
+  Object.freeze({ value: 'archived', label: 'Archived' }),
+]);
+
+/** Date filter (spec §10): '' = any time, the three presets, or a custom from–to. */
+export const DATE_OPTIONS = Object.freeze([
+  Object.freeze({ value: '', label: 'Any time' }),
+  Object.freeze({ value: '7', label: 'Last 7 days' }),
+  Object.freeze({ value: '30', label: 'Last 30 days' }),
+  Object.freeze({ value: '90', label: 'Last 90 days' }),
+  Object.freeze({ value: 'custom', label: 'Custom range' }),
+]);
+
+/** The longest search the server takes (characters after trimming, spec §3). */
+export const SEARCH_MAX = 100;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAY_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const STATUSES = new Set(['unread', 'read', 'archived']);
+const DATES = new Set(['7', '30', '90', 'custom']);
+// The guard's kind shape (`NOTIFICATION_KIND_PATTERN`); the server checks the length. This only
+// keeps junk out of the URL-derived state.
+const KIND_RE = /^(?=.{1,128}$)[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+
+/** `YYYY-MM-DD` naming a real calendar day, else ''. */
+export function validDay(value) {
+  if (typeof value !== 'string') return '';
+  const m = DAY_RE.exec(value);
+  if (!m) return '';
+  const y = Number(m[1]);
+  const mo = Number(m[2]);
+  const d = Number(m[3]);
+  const at = new Date(Date.UTC(y, mo - 1, d));
+  if (at.getUTCFullYear() !== y || at.getUTCMonth() !== mo - 1 || at.getUTCDate() !== d) return '';
+  return value;
+}
+
+/** The UTC calendar day of a ms timestamp as `YYYY-MM-DD` (the server reads days as UTC). */
+export function utcDay(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * The page state from the URL (`URLSearchParams` or anything with `get`). Unknown or malformed
+ * values fall back to the defaults: tab `personal`, everything else empty, page 1, limit 20.
+ */
+export function readPageState(sp) {
+  const get = (k) => {
+    const v = sp?.get?.(k);
+    return typeof v === 'string' ? v : '';
+  };
+  const tab = get('tab') === 'announcement' ? 'announcement' : 'personal';
+  const kind = KIND_RE.test(get('kind')) ? get('kind') : '';
+  const status = STATUSES.has(get('status')) ? get('status') : '';
+  const date = DATES.has(get('date')) ? get('date') : '';
+  const page = Number.parseInt(get('page'), 10);
+  const limit = Number.parseInt(get('limit'), 10);
+  return {
+    tab,
+    kind,
+    status,
+    date,
+    from: date === 'custom' ? validDay(get('from')) : '',
+    to: date === 'custom' ? validDay(get('to')) : '',
+    search: get('search').slice(0, SEARCH_MAX),
+    page: Number.isFinite(page) && page >= 1 ? page : 1,
+    limit: PAGE_SIZES.includes(limit) ? limit : DEFAULT_LIMIT,
+  };
+}
+
+/**
+ * The URL params for a page state, defaults left out to keep the link short. `tab` is always
+ * written so a shared link names its tab. Returns a plain object for `setSearchParams`.
+ */
+export function pageStateToParams(state) {
+  const p = { tab: state.tab === 'announcement' ? 'announcement' : 'personal' };
+  if (state.kind) p.kind = state.kind;
+  if (state.status) p.status = state.status;
+  if (state.date) p.date = state.date;
+  if (state.date === 'custom' && state.from) p.from = state.from;
+  if (state.date === 'custom' && state.to) p.to = state.to;
+  // Spaces only ⇒ no search: keep it out of the URL (the server treats it the same way).
+  const search = typeof state.search === 'string' ? state.search.trim() : '';
+  if (search) p.search = search;
+  if (state.page > 1) p.page = String(state.page);
+  if (state.limit !== DEFAULT_LIMIT) p.limit = String(state.limit);
+  return p;
+}
+
+/**
+ * `{ from, to }` (UTC days, inclusive) for a date filter. A preset of N days covers today and
+ * the N − 1 days before it, with no `to` (up to now). Custom passes the chosen days through;
+ * an inverted range (from after to) is `{ invalid: true }` and filters nothing until fixed.
+ */
+export function dateRange(state, now = Date.now()) {
+  if (state.date === '7' || state.date === '30' || state.date === '90') {
+    const days = Number(state.date);
+    return { from: utcDay(now - (days - 1) * DAY_MS), to: '' };
+  }
+  if (state.date === 'custom') {
+    const from = validDay(state.from);
+    const to = validDay(state.to);
+    if (from && to && from > to) return { from: '', to: '', invalid: true };
+    return { from, to };
+  }
+  return { from: '', to: '' };
+}
+
+/**
+ * The `listNotifications` query for a page state: `{ category, page, limit }` plus only the
+ * filters that are set. Search is trimmed (blank ⇒ none, spec §3).
+ */
+export function buildListQuery(state, now = Date.now()) {
+  const q = {
+    category: state.tab === 'announcement' ? 'announcement' : 'personal',
+    page: state.page >= 1 ? state.page : 1,
+    limit: PAGE_SIZES.includes(state.limit) ? state.limit : DEFAULT_LIMIT,
+  };
+  if (state.kind) q.kind = state.kind;
+  if (state.status) q.status = state.status;
+  const { from, to } = dateRange(state, now);
+  if (from) q.from = from;
+  if (to) q.to = to;
+  const search = typeof state.search === 'string' ? state.search.trim() : '';
+  if (search) q.search = search;
+  return q;
+}
+
+/** True when a search or any filter narrows the list (the empty text differs). */
+export function hasActiveFilters(state) {
+  const search = typeof state.search === 'string' ? state.search.trim() : '';
+  return Boolean(search || state.kind || state.status || state.date);
+}
+
+/** The no-rows text (spec §10, §12). */
+export function emptyText(state) {
+  return hasActiveFilters(state) ? 'No matching notifications' : 'No notifications yet';
+}
+
+/** A row's status: archived wins over read/unread. */
+export function rowStatus(row) {
+  if (row?.archivedAt) return 'archived';
+  return row?.readAt ? 'read' : 'unread';
+}
+
+const STATUS_LABEL = { unread: 'Unread', read: 'Read', archived: 'Archived' };
+const STATUS_VARIANT = { unread: 'info', read: 'secondary', archived: 'outline' };
+
+/** The Status column text: Unread / Read / Archived. */
+export function statusLabel(row) {
+  return STATUS_LABEL[rowStatus(row)];
+}
+
+/** The Status column badge variant (`ui/badge` variants). */
+export function statusVariant(row) {
+  return STATUS_VARIANT[rowStatus(row)];
+}
+
+/**
+ * The single-row actions: an unread row ⇒ Mark read + Archive; a read row ⇒ Mark unread +
+ * Archive; an archived row ⇒ Unarchive only (it comes back as read, spec §12).
+ * Each `{ action, label }`, `action` being the bulk action name.
+ */
+export function rowActions(row) {
+  const status = rowStatus(row);
+  if (status === 'archived') return [{ action: 'unarchive', label: 'Unarchive' }];
+  return [
+    status === 'unread'
+      ? { action: 'read', label: 'Mark read' }
+      : { action: 'unread', label: 'Mark unread' },
+    { action: 'archive', label: 'Archive' },
+  ];
+}
+
+/** The bulk bar's actions, in order (spec §10). */
+export const BULK_ACTIONS = Object.freeze([
+  Object.freeze({ action: 'read', label: 'Mark read' }),
+  Object.freeze({ action: 'unread', label: 'Mark unread' }),
+  Object.freeze({ action: 'archive', label: 'Archive' }),
+  Object.freeze({ action: 'unarchive', label: 'Unarchive' }),
+]);
+
+/** The most notices one bulk call takes (spec §10; frontend-core `NOTIFICATION_BULK_MAX`). */
+export const BULK_MAX = 100;
+
+const BULK_DONE = {
+  read: 'marked read',
+  unread: 'marked unread',
+  archive: 'archived',
+  unarchive: 'unarchived',
+};
+
+/** The toast after a bulk call: "3 notifications archived" / "1 notification marked read". */
+export function bulkDoneText(action, updated) {
+  const n = Number.isFinite(updated) && updated > 0 ? Math.floor(updated) : 0;
+  return `${n} ${n === 1 ? 'notification' : 'notifications'} ${BULK_DONE[action] ?? 'updated'}`;
+}
+
+/** The Type filter options: the kinds of this tab's category, by label (never the raw kind). */
+export function kindOptionsFor(kinds, category) {
+  if (!Array.isArray(kinds)) return [];
+  return kinds
+    .filter((k) => k && k.category === category && typeof k.kind === 'string')
+    .map((k) => ({
+      value: k.kind,
+      label: typeof k.label === 'string' && k.label ? k.label : 'Other',
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/**
+ * When a notice arrived, as a date and time ("27 Oct 2026, 14:05" in en-GB); '' when
+ * unparsable. `opts` ({ locale, timeZone }) pins the output in tests.
+ */
+export function receivedText(iso, { locale, timeZone } = {}) {
+  if (typeof iso !== 'string' || iso === '') return '';
+  const at = Date.parse(iso);
+  if (Number.isNaN(at)) return '';
+  try {
+    return new Date(at).toLocaleString(locale, {
+      day: 'numeric',
+      month: 'short',
+      year: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+      ...(timeZone ? { timeZone } : {}),
+    });
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The selection kept after a reload: only uuids still on the page. `selected` is a Set; the
+ * result is a new Set (or the same one when nothing dropped out).
+ */
+export function keepSelection(selected, rows) {
+  if (!(selected instanceof Set) || selected.size === 0) return selected;
+  const onPage = new Set((rows || []).map((r) => r?.uuid));
+  const kept = new Set([...selected].filter((u) => onPage.has(u)));
+  return kept.size === selected.size ? selected : kept;
+}

package/template/frontend/src/pages/notifications/notificationList.test.mjs

@@ -0,0 +1,273 @@
+// notificationList.test.mjs — Notifications page helpers (G-035, notification-center SPEC §5F,
+// §10, §12): URL state ⇄ list query, date presets → from/to, status labels, row and bulk
+// actions, empty text, the Type filter options.
+//
+//   node --test src/pages/notifications/notificationList.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  BULK_ACTIONS,
+  DEFAULT_LIMIT,
+  PAGE_SIZES,
+  buildListQuery,
+  bulkDoneText,
+  dateRange,
+  emptyText,
+  hasActiveFilters,
+  keepSelection,
+  kindOptionsFor,
+  pageStateToParams,
+  readPageState,
+  receivedText,
+  rowActions,
+  rowStatus,
+  statusLabel,
+  statusVariant,
+  validDay,
+} from './notificationList.js';
+
+const sp = (s) => new URLSearchParams(s);
+const now = Date.parse('2026-10-27T10:30:00.000Z');
+
+describe('readPageState', () => {
+  test('defaults: personal tab, no filters, page 1, limit 20', () => {
+    assert.deepEqual(readPageState(sp('')), {
+      tab: 'personal',
+      kind: '',
+      status: '',
+      date: '',
+      from: '',
+      to: '',
+      search: '',
+      page: 1,
+      limit: 20,
+    });
+    assert.equal(DEFAULT_LIMIT, 20);
+    assert.deepEqual([...PAGE_SIZES], [10, 20, 50, 100]);
+  });
+
+  test('a full URL round-trips', () => {
+    const s = readPageState(
+      sp(
+        'tab=announcement&kind=app.task_assigned&status=archived&date=custom&from=2026-10-01&to=2026-10-20&search=batch&page=3&limit=50',
+      ),
+    );
+    assert.deepEqual(s, {
+      tab: 'announcement',
+      kind: 'app.task_assigned',
+      status: 'archived',
+      date: 'custom',
+      from: '2026-10-01',
+      to: '2026-10-20',
+      search: 'batch',
+      page: 3,
+      limit: 50,
+    });
+    assert.deepEqual(readPageState(sp(new URLSearchParams(pageStateToParams(s)).toString())), s);
+  });
+
+  test('hand-edited junk falls back to the defaults', () => {
+    const s = readPageState(sp('tab=other&kind=Bad Kind&status=deleted&date=365&page=-2&limit=33'));
+    assert.equal(s.tab, 'personal');
+    assert.equal(s.kind, '');
+    assert.equal(s.status, '');
+    assert.equal(s.date, '');
+    assert.equal(s.page, 1);
+    assert.equal(s.limit, 20);
+  });
+
+  test('from/to only with date=custom, and only real days', () => {
+    assert.equal(readPageState(sp('date=7&from=2026-10-01')).from, '');
+    assert.equal(readPageState(sp('date=custom&from=2026-02-30')).from, '');
+    assert.equal(readPageState(sp('date=custom&to=2026-10-05')).to, '2026-10-05');
+  });
+
+  test('search is capped at 100 characters', () => {
+    assert.equal(readPageState(sp(`search=${'x'.repeat(150)}`)).search.length, 100);
+  });
+});
+
+describe('pageStateToParams', () => {
+  test('defaults leave only the tab', () => {
+    assert.deepEqual(pageStateToParams(readPageState(sp(''))), { tab: 'personal' });
+  });
+  test('from/to are written only for a custom range', () => {
+    const p = pageStateToParams({
+      ...readPageState(sp('')),
+      date: '30',
+      from: '2026-10-01',
+      to: '2026-10-02',
+    });
+    assert.deepEqual(p, { tab: 'personal', date: '30' });
+  });
+  test('a spaces-only search stays out of the URL; a real one is trimmed', () => {
+    const base = readPageState(sp(''));
+    assert.deepEqual(pageStateToParams({ ...base, search: '   ' }), { tab: 'personal' });
+    assert.deepEqual(pageStateToParams({ ...base, search: '  batch ' }), {
+      tab: 'personal',
+      search: 'batch',
+    });
+  });
+});
+
+describe('date presets → from/to (UTC days)', () => {
+  const base = readPageState(sp(''));
+  test('Last 7 days = today and the 6 days before, no upper bound', () => {
+    assert.deepEqual(dateRange({ ...base, date: '7' }, now), { from: '2026-10-21', to: '' });
+  });
+  test('Last 30 and 90 days', () => {
+    assert.equal(dateRange({ ...base, date: '30' }, now).from, '2026-09-28');
+    assert.equal(dateRange({ ...base, date: '90' }, now).from, '2026-07-30');
+  });
+  test('custom passes the days through; an inverted range is flagged and dropped', () => {
+    assert.deepEqual(dateRange({ ...base, date: 'custom', from: '2026-10-01', to: '' }, now), {
+      from: '2026-10-01',
+      to: '',
+    });
+    assert.deepEqual(
+      dateRange({ ...base, date: 'custom', from: '2026-10-20', to: '2026-10-01' }, now),
+      { from: '', to: '', invalid: true },
+    );
+  });
+  test('any time ⇒ no bounds', () => {
+    assert.deepEqual(dateRange(base, now), { from: '', to: '' });
+  });
+  test('validDay rejects non-days', () => {
+    assert.equal(validDay('2026-10-27'), '2026-10-27');
+    for (const v of ['2026-1-27', '2026-13-01', 'yesterday', '', null])
+      assert.equal(validDay(v), '');
+  });
+});
+
+describe('buildListQuery', () => {
+  test('defaults: category, page and limit only', () => {
+    assert.deepEqual(buildListQuery(readPageState(sp('')), now), {
+      category: 'personal',
+      page: 1,
+      limit: 20,
+    });
+  });
+  test('every filter set', () => {
+    const q = buildListQuery(
+      readPageState(
+        sp(
+          'tab=announcement&kind=app.news&status=unread&date=7&search=%20batch%20&page=2&limit=10',
+        ),
+      ),
+      now,
+    );
+    assert.deepEqual(q, {
+      category: 'announcement',
+      page: 2,
+      limit: 10,
+      kind: 'app.news',
+      status: 'unread',
+      from: '2026-10-21',
+      search: 'batch',
+    });
+  });
+  test('a blank search is no search (spec §12)', () => {
+    const q = buildListQuery({ ...readPageState(sp('')), search: '   ' }, now);
+    assert.equal('search' in q, false);
+  });
+  test('Status All sends no status (server ⇒ not archived)', () => {
+    assert.equal('status' in buildListQuery(readPageState(sp('status=')), now), false);
+  });
+});
+
+describe('empty text', () => {
+  const base = readPageState(sp(''));
+  test('no filters ⇒ "No notifications yet"', () => {
+    assert.equal(hasActiveFilters(base), false);
+    assert.equal(emptyText(base), 'No notifications yet');
+    assert.equal(emptyText({ ...base, search: '  ' }), 'No notifications yet');
+  });
+  test('any filter or search ⇒ "No matching notifications"', () => {
+    for (const patch of [{ search: 'x' }, { kind: 'app.a' }, { status: 'read' }, { date: '7' }]) {
+      assert.equal(emptyText({ ...base, ...patch }), 'No matching notifications');
+    }
+  });
+});
+
+describe('status', () => {
+  const unread = { readAt: null, archivedAt: null };
+  const read = { readAt: '2026-10-27T09:00:00.000Z', archivedAt: null };
+  const archived = { readAt: '2026-10-27T09:00:00.000Z', archivedAt: '2026-10-27T09:10:00.000Z' };
+  test('labels and badge variants', () => {
+    assert.equal(statusLabel(unread), 'Unread');
+    assert.equal(statusLabel(read), 'Read');
+    assert.equal(statusLabel(archived), 'Archived');
+    assert.equal(rowStatus({ readAt: null, archivedAt: '2026-10-27T09:10:00.000Z' }), 'archived');
+    assert.equal(statusVariant(unread), 'info');
+    assert.equal(statusVariant(read), 'secondary');
+    assert.equal(statusVariant(archived), 'outline');
+  });
+  test('row actions follow the status', () => {
+    assert.deepEqual(
+      rowActions(unread).map((a) => a.action),
+      ['read', 'archive'],
+    );
+    assert.deepEqual(
+      rowActions(read).map((a) => a.action),
+      ['unread', 'archive'],
+    );
+    assert.deepEqual(
+      rowActions(archived).map((a) => a.action),
+      ['unarchive'],
+    );
+  });
+  test('bulk offers the four actions', () => {
+    assert.deepEqual(
+      BULK_ACTIONS.map((a) => a.action),
+      ['read', 'unread', 'archive', 'unarchive'],
+    );
+  });
+  test('bulk toast text', () => {
+    assert.equal(bulkDoneText('archive', 3), '3 notifications archived');
+    assert.equal(bulkDoneText('read', 1), '1 notification marked read');
+    assert.equal(bulkDoneText('unread', undefined), '0 notifications marked unread');
+  });
+});
+
+describe('Type filter options', () => {
+  const kinds = [
+    { kind: 'app.task_assigned', label: 'Task assigned', category: 'personal' },
+    { kind: 'shield.access_changed', label: 'Access change', category: 'personal' },
+    { kind: 'app.news', label: 'News', category: 'announcement' },
+  ];
+  test('only the tab’s category, by label, sorted', () => {
+    assert.deepEqual(kindOptionsFor(kinds, 'personal'), [
+      { value: 'shield.access_changed', label: 'Access change' },
+      { value: 'app.task_assigned', label: 'Task assigned' },
+    ]);
+    assert.deepEqual(kindOptionsFor(kinds, 'announcement'), [{ value: 'app.news', label: 'News' }]);
+  });
+  test('never shows the raw kind as a label', () => {
+    const [opt] = kindOptionsFor([{ kind: 'app.x', label: '', category: 'personal' }], 'personal');
+    assert.notEqual(opt.label, 'app.x');
+  });
+  test('not a list ⇒ none', () => {
+    assert.deepEqual(kindOptionsFor(undefined, 'personal'), []);
+  });
+});
+
+describe('receivedText', () => {
+  test('date and time; unparsable ⇒ empty', () => {
+    const text = receivedText('2026-10-27T14:05:00.000Z', { locale: 'en-GB', timeZone: 'UTC' });
+    assert.match(text, /27 Oct 2026/);
+    assert.match(text, /14:05/);
+    assert.equal(receivedText('nope'), '');
+    assert.equal(receivedText(undefined), '');
+  });
+});
+
+describe('keepSelection', () => {
+  test('drops uuids no longer on the page', () => {
+    const s = new Set(['a', 'b', 'c']);
+    assert.deepEqual([...keepSelection(s, [{ uuid: 'a' }, { uuid: 'c' }])], ['a', 'c']);
+  });
+  test('same set back when nothing dropped', () => {
+    const s = new Set(['a']);
+    assert.equal(keepSelection(s, [{ uuid: 'a' }, { uuid: 'b' }]), s);
+  });
+});

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

@@ -5,7 +5,8 @@
  * On open: for holders of `identity:role:update`, the open admin tasks (a new permission no role
  * in a company holds yet): "Grant…" opens `/access/add?key=` with the key ticked; "Reviewed, not
  * needed" confirms (naming the permission and company) then dismisses. Below, the announcement
- * notices with the same read behaviour as the bell. The `can` gate is cosmetic: the server
+ * notices with the same behaviour as the bell (unread only, severity dot, "View all
+ * notifications" to `/notifications?tab=announcement`; G-035). The `can` gate is cosmetic: the server
  * decides, and a 403 on the task list hides the section. Labels and company names only — the
  * task's company id and key are used in calls and URLs, never shown.
  */
@@ -164,11 +165,7 @@ export default function AnnouncementsMenu() {
           <DropdownMenuLabel>Announcements</DropdownMenuLabel>
           <DropdownMenuSeparator />
           {canTasks && <TasksSection onDismiss={setTarget} />}
-          <NoticeSection
-            category="announcement"
-            heading={canTasks ? 'News' : undefined}
-            emptyText="No announcements."
-          />
+          <NoticeSection category="announcement" heading={canTasks ? 'News' : undefined} />
         </DropdownMenuContent>
       </DropdownMenu>