@startsimpli/ui 0.4.141 → 0.4.142

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.141",
+  "version": "0.4.142",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -49,9 +49,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/i18n": "^0.1.3",
+    "@startsimpli/api": "^0.5.66",
     "@startsimpli/auth": "^0.4.38",
-    "@startsimpli/api": "^0.5.66"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/activity/ActivityFeedPanel.tsx

@@ -17,12 +17,28 @@
  * exactly the rows the signed-in user may see; a row that arrives is rendered,
  * and an action string this build has never heard of renders with a humanised
  * label. Filtering happens SERVER-SIDE (repo rule #8) and can only subtract.
+ *
+ * ── EXTENDED IN PLACE, NOT FORKED (bd startsim-ucg5u) ───────────────────────
+ *
+ * The record-edit feed (`/api/v1/revisions/`) is a different stream with a
+ * different paging contract: a CURSOR, no `count`, and `?page=` is a 400. It
+ * composes this panel through four optional props, each of which leaves the
+ * page-numbered foundry/account feeds rendering exactly as before:
+ *
+ * - `paging="cursor"` — sends `cursor` (never `page`), reads `next_cursor`, and
+ *   prints no count the server did not send;
+ * - `filters` + `onFiltersChange` — CONTROLLED filters, so a host keeps them in
+ *   the URL (a page, never a Next layout, which does not re-render on soft
+ *   navigation);
+ * - `toParams` — the host maps filters to params, so a key a strict route does
+ *   not know (it 400s) is never sent;
+ * - `toItems` / `renderFilters` — the host's own rows and filter bar.
  */
 import { ComponentType, ReactNode, useEffect, useMemo, useRef, useState } from 'react';
 import { useInfiniteQuery } from '@tanstack/react-query';
 import { Activity as ActivityIcon } from 'lucide-react';
 
-import { ActivityTimeline } from '../ActivityTimeline';
+import { ActivityTimeline, type ActivityTimelineItem } from '../ActivityTimeline';
 import { ErrorState } from '../states';
 import { ActivityFilterBar } from './ActivityFilterBar';
 import {
@@ -40,8 +56,21 @@ import {
   type ActivityFeedPanelClassNames,
 } from './activity-feed-panel-default-class-names';
 
-export interface ActivityFeedPanelProps {
-  client: ActivityClient;
+export interface ActivityFeedPanelProps<E = ActivityEvent, F extends object = ActivityFilterValue> {
+  client: ActivityClient<E>;
+  /** `page` (default) pages by number and reads `count`; `cursor` sends the
+   *  server's `next_cursor` and never sends `page`. */
+  paging?: 'page' | 'cursor';
+  /** CONTROLLED filters. With these the panel holds no filter state of its own. */
+  filters?: F;
+  onFiltersChange?: (next: F) => void;
+  /** Filters → query params. Defaults to the filters as they are (with `q`
+   *  debounced). A host over a strict route drops anything it does not accept. */
+  toParams?: (filters: F) => Record<string, unknown>;
+  /** The host's rows. Defaults to the shared event-stream mapping. */
+  toItems?: (events: E[]) => ActivityTimelineItem[];
+  /** The host's filter bar, replacing the default one. */
+  renderFilters?: (args: { value: F; onChange: (next: F) => void; events: E[] }) => ReactNode;
   /** Cache namespace, e.g. `['foundry', slug, 'activity']`. The live filters
    *  are appended, so invalidating the prefix refreshes every filtered view. */
   queryKey?: readonly unknown[];
@@ -53,7 +82,7 @@ export interface ActivityFeedPanelProps {
   headerAside?: ReactNode;
   /** Given every loaded row, so a host can surface an invariant (e.g. "the
    *  newest status event disagrees with the state badge"). */
-  renderFooter?: (events: ActivityEvent[]) => ReactNode;
+  renderFooter?: (events: E[]) => ReactNode;
   showFilters?: boolean;
   emptyTitle?: string;
   emptyDescription?: string;
@@ -95,8 +124,14 @@ function useStickyOptions(events: ActivityEvent[]) {
   }, [events]);
 }
 
-export function ActivityFeedPanel({
+export function ActivityFeedPanel<E = ActivityEvent, F extends object = ActivityFilterValue>({
   client,
+  paging = 'page',
+  filters: controlledFilters,
+  onFiltersChange,
+  toParams,
+  toItems,
+  renderFilters,
   queryKey = ['activity'],
   pageSize = 25,
   refetchInterval = false,
@@ -119,36 +154,64 @@ export function ActivityFeedPanel({
   activityColors,
   defaultIcon = ActivityIcon,
   classNames = {},
-}: ActivityFeedPanelProps) {
+}: ActivityFeedPanelProps<E, F>) {
   const cx = { ...ACTIVITY_FEED_PANEL_DEFAULTS, ...classNames };
 
-  const [filters, setFilters] = useState<ActivityFilterValue>({});
-  const debouncedQ = useDebounced(filters.q ?? '', 300);
+  const [ownFilters, setOwnFilters] = useState<F>({} as F);
+  const controlled = controlledFilters !== undefined;
+  const filters = controlled ? controlledFilters : ownFilters;
+  const setFilters = (next: F) => {
+    if (!controlled) setOwnFilters(next);
+    onFiltersChange?.(next);
+  };
+  const typedQ = (filters as { q?: unknown }).q;
+  const debouncedQ = useDebounced(typeof typedQ === 'string' ? typedQ : '', 300);
 
   // What actually goes to the server. `q` lags the input by a beat; everything
-  // else applies immediately.
-  const params = useMemo(() => {
-    const { q: _typed, ...rest } = filters;
+  // else applies immediately. A host mapping (`toParams`) owns the whole shape.
+  const params = useMemo<Record<string, unknown>>(() => {
+    if (toParams) return toParams(filters);
+    const { q: _typed, ...rest } = filters as Record<string, unknown>;
     return debouncedQ ? { ...rest, q: debouncedQ } : rest;
-  }, [filters, debouncedQ]);
+  }, [filters, debouncedQ, toParams]);
 
+  const cursorMode = paging === 'cursor';
   const query = useInfiniteQuery({
-    queryKey: [...queryKey, params],
-    queryFn: ({ pageParam }) => client.list({ ...params, page: pageParam as number, pageSize }),
-    initialPageParam: 1,
-    getNextPageParam: (last, all) => (last?.next ? all.length + 1 : undefined),
+    queryKey: [...queryKey, params, paging],
+    queryFn: ({ pageParam }) =>
+      client.list(
+        cursorMode
+          ? { ...params, ...(pageParam ? { cursor: pageParam as string } : {}), pageSize }
+          : { ...params, page: pageParam as number, pageSize },
+      ),
+    initialPageParam: (cursorMode ? null : 1) as number | string | null,
+    getNextPageParam: (last, all) => {
+      if (cursorMode) {
+        const cursor = last?.next_cursor ?? last?.nextCursor;
+        return cursor ? cursor : undefined;
+      }
+      return last?.next ? all.length + 1 : undefined;
+    },
     refetchInterval,
   });
 
-  const events = useMemo(
+  const events = useMemo<E[]>(
     () => (query.data?.pages ?? []).flatMap((p) => p?.results ?? []),
     [query.data],
   );
-  const items = useMemo(() => toActivityTimelineItems(events), [events]);
-  const options = useStickyOptions(events);
+  const items = useMemo(
+    () => (toItems ? toItems(events) : toActivityTimelineItems(events as unknown as ActivityEvent[])),
+    [events, toItems],
+  );
+  const options = useStickyOptions(events as unknown as ActivityEvent[]);
 
-  const isFiltered = Object.keys(filters).length > 0;
-  const total = query.data?.pages?.[0]?.count ?? events.length;
+  const isFiltered = Object.values(filters as Record<string, unknown>).some(
+    (v) => typeof v === 'string' ? v.trim() !== '' : v !== undefined && v !== null,
+  );
+  // Only a count the SERVER sent. A cursor stream sends none, and "Showing 25 of
+  // 25" over a stream with more pages would be a confident lie.
+  const serverCount = query.data?.pages?.[0]?.count;
+  const total = typeof serverCount === 'number' ? serverCount : undefined;
 
   const loadMore = () => {
     if (query.hasNextPage && !query.isFetchingNextPage) query.fetchNextPage();
@@ -166,13 +229,17 @@ export function ActivityFeedPanel({
 
       {showFilters && (
         <div className={cx.filters}>
-          <ActivityFilterBar
-            value={filters}
-            onChange={setFilters}
-            actors={options.actors}
-            actions={options.actions}
-            classNames={cx.filterBar}
-          />
+          {renderFilters ? (
+            renderFilters({ value: filters, onChange: setFilters, events })
+          ) : (
+            <ActivityFilterBar
+              value={filters as ActivityFilterValue}
+              onChange={(next) => setFilters(next as F)}
+              actors={options.actors}
+              actions={options.actions}
+              classNames={cx.filterBar}
+            />
+          )}
         </div>
       )}
 
@@ -201,7 +268,7 @@ export function ActivityFeedPanel({
         )}
       </div>
 
-      {events.length > 0 && total > events.length && (
+      {events.length > 0 && total !== undefined && total > events.length && (
         <p className={cx.countLine}>
           Showing {events.length} of {total} events.
         </p>

package/src/components/activity/__tests__/activity-feed-cursor.test.tsx

@@ -0,0 +1,107 @@
+/**
+ * RED for bd startsim-ucg5u — the shared ActivityFeedPanel, extended IN PLACE
+ * (not forked) so a cursor-paged stream with host-owned filters can compose it.
+ *
+ * `GET /api/v1/revisions/` returns `{next, next_cursor, results}`: no `count`,
+ * and `?page=` is a 400. So the panel must be able to page by cursor, never send
+ * `page`, never print a count it was not given, and take its filters from the
+ * host (the URL) rather than its own state. Page-number mode is untouched — the
+ * existing suite is the proof.
+ */
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+import { ActivityFeedPanel, type ActivityEvent } from '../index'
+
+function mount(ui: React.ReactElement) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: 0 } } })
+  return render(<QueryClientProvider client={qc}>{ui}</QueryClientProvider>)
+}
+
+const ev = (id: string): ActivityEvent => ({ id, action: 'member_invited', created_at: '2026-10-07T10:00:00Z' })
+
+describe('ActivityFeedPanel — cursor paging', () => {
+  it('sends no page param, then the server cursor, and stops when there is none', async () => {
+    const list = jest
+      .fn()
+      .mockResolvedValueOnce({ next: 'http://x/?cursor=c2', next_cursor: 'c2', results: [ev('a')] })
+      .mockResolvedValueOnce({ next: null, next_cursor: null, results: [ev('b')] })
+    mount(<ActivityFeedPanel client={{ list }} paging="cursor" pageSize={1} />)
+    await screen.findByRole('heading', { name: /member invited/i })
+    const first = list.mock.calls[0][0]
+    expect(first).not.toHaveProperty('page')
+    expect(first).not.toHaveProperty('cursor')
+    expect(first).toMatchObject({ pageSize: 1 })
+
+    fireEvent.click(await screen.findByRole('button', { name: /load more/i }))
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(2))
+    expect(list.mock.calls[1][0]).toMatchObject({ cursor: 'c2' })
+    expect(list.mock.calls[1][0]).not.toHaveProperty('page')
+    await waitFor(() => expect(screen.queryByRole('button', { name: /load more/i })).not.toBeInTheDocument())
+  })
+
+  it('reads a camelised nextCursor too', async () => {
+    const list = jest
+      .fn()
+      .mockResolvedValueOnce({ next: 'x', nextCursor: 'c9', results: [ev('a')] })
+      .mockResolvedValueOnce({ next: null, results: [] })
+    mount(<ActivityFeedPanel client={{ list }} paging="cursor" />)
+    fireEvent.click(await screen.findByRole('button', { name: /load more/i }))
+    await waitFor(() => expect(list.mock.calls[1]?.[0]).toMatchObject({ cursor: 'c9' }))
+  })
+
+  it('never prints a count the server did not send', async () => {
+    const list = jest.fn().mockResolvedValue({ next: 'x', next_cursor: 'c2', results: [ev('a')] })
+    mount(<ActivityFeedPanel client={{ list }} paging="cursor" />)
+    await screen.findByRole('heading', { name: /member invited/i })
+    expect(screen.queryByText(/showing .* of/i)).not.toBeInTheDocument()
+  })
+})
+
+describe('ActivityFeedPanel — host-owned filters and rows', () => {
+  it('takes filters from the host and reports changes instead of holding them', async () => {
+    const list = jest.fn().mockResolvedValue({ count: 0, next: null, results: [] })
+    const onFiltersChange = jest.fn()
+    mount(
+      <ActivityFeedPanel
+        client={{ list }}
+        filters={{ actor: 'u1' }}
+        onFiltersChange={onFiltersChange}
+      />,
+    )
+    await waitFor(() => expect(list).toHaveBeenCalled())
+    expect(list.mock.calls[0][0]).toMatchObject({ actor: 'u1' })
+    fireEvent.click(await screen.findByRole('button', { name: /clear all/i }))
+    expect(onFiltersChange).toHaveBeenCalledWith({})
+  })
+
+  it('maps filters to params through the host, so unknown keys never reach a strict route', async () => {
+    const list = jest.fn().mockResolvedValue({ next: null, results: [] })
+    mount(
+      <ActivityFeedPanel
+        client={{ list }}
+        paging="cursor"
+        filters={{ actor: '', q: 'ignored' }}
+        toParams={(f) => (f.actor ? { actor: f.actor } : {})}
+      />,
+    )
+    await waitFor(() => expect(list).toHaveBeenCalled())
+    expect(list.mock.calls[0][0]).toEqual({ pageSize: 25 })
+  })
+
+  it('renders rows and filters through the host when asked', async () => {
+    const list = jest.fn().mockResolvedValue({ next: null, results: [ev('a')] })
+    mount(
+      <ActivityFeedPanel
+        client={{ list }}
+        toItems={(events) =>
+          events.map((e) => ({ id: e.id, type: 'custom', title: `custom row ${e.id}`, occurredAt: e.created_at }))
+        }
+        renderFilters={() => <div data-testid="host-filters" />}
+      />,
+    )
+    expect(await screen.findByText('custom row a')).toBeInTheDocument()
+    expect(screen.getByTestId('host-filters')).toBeInTheDocument()
+    expect(screen.queryByTestId('activity-filter-bar')).not.toBeInTheDocument()
+  })
+})

package/src/components/activity/types.ts

@@ -67,11 +67,16 @@ export interface ActivityQuery extends ActivityFilterValue {
   [key: string]: unknown;
 }
 
-export interface ActivityPage {
-  count: number;
+export interface ActivityPage<E = ActivityEvent> {
+  /** Absent on a CURSOR-paged stream, which computes no count (bd
+   *  startsim-ucg5u) — the panel then prints none rather than inventing one. */
+  count?: number;
   next?: string | null;
   previous?: string | null;
-  results: ActivityEvent[];
+  /** The cursor for the next page, on a cursor-paged stream. */
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results: E[];
 }
 
 /**
@@ -79,8 +84,8 @@ export interface ActivityPage {
  * (`(p) => api.foundry.activity(slug, p)`), which is what keeps @startsimpli/api
  * out of packages/ui and the app wrapper under ten lines.
  */
-export interface ActivityClient {
-  list(params: ActivityQuery): Promise<ActivityPage>;
+export interface ActivityClient<E = ActivityEvent> {
+  list(params: ActivityQuery): Promise<ActivityPage<E>>;
 }
 
 export interface ActivityFilterOption {

package/src/components/collection/DraftReviewWorkspace.tsx

@@ -17,7 +17,7 @@ import { Badge } from '../ui/badge';
 import { notify } from '../toast/use-notify';
 import { MarkdownRenderer } from '../blog/MarkdownRenderer';
 import type { CollectionClient, EntityRecord } from './types';
-import { declaredBlob, readData, writeData } from './data';
+import { declaredBlob, readData, writeData, writeOptionsFor } from './data';
 import { scopeKey } from './scoped-client';
 import {
   groupDrafts,
@@ -134,7 +134,7 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
     let data: Record<string, unknown> = { ...record.data };
     for (const [k, v] of Object.entries(changes)) data = writeData(data, k, v);
     data = declaredBlob(data, (draftType?.attributes ?? []).map((a) => a.name));
-    return client.updateEntity(record.id, { data });
+    return client.updateEntity(record.id, { data }, writeOptionsFor(record));
   }
 
   async function pick(group: DraftGroup, cand: EntityRecord) {

package/src/components/collection/InlineReviewActions.tsx

@@ -27,7 +27,7 @@ import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover';
 import { notify } from '../toast/use-notify';
 import { cn } from '../../lib/utils';
 import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
-import { writeData } from './data';
+import { writeData, writeOptionsFor } from './data';
 import {
   activeDecisionKey,
   applyDecisionToData,
@@ -110,7 +110,8 @@ export function InlineReviewActions({ client, type, record, config, onSaved }: I
       // rename `source_1` to `source1` (bd startsim-8hgmq.18, collection/data.ts).
       let data = applyDecisionToData(record.data, d, cfg, declaredNames);
       if (noteText !== undefined) data = writeData(data, cfg.noteAttr, noteText.trim());
-      await client.updateEntity(record.id, { data });
+      // Asserts the version of the ROW it merged over (bd startsim-jkkn7.20).
+      await client.updateEntity(record.id, { data }, writeOptionsFor(record));
       onSaved?.();
       return true;
     } catch (err) {

package/src/components/collection/ReviewDrawer.tsx

@@ -18,7 +18,7 @@
  * queue (prev/next), and optional ReviewConfig / render-props. Defaults match the
  * OGMC content schema but everything is a prop — nothing here is tenant-specific.
  */
-import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import {
   ChevronLeft,
   ChevronRight,
@@ -42,7 +42,7 @@ import {
 import { notify } from '../toast/use-notify';
 import { cn } from '../../lib/utils';
 import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
-import { declaredBlob, readData, writeData } from './data';
+import { declaredBlob, isVersionNumber, readData, writeData } from './data';
 import { parseSources } from './drafts';
 import {
   activeDecisionKey,
@@ -77,8 +77,10 @@ export interface ReviewDrawerProps {
     type: EntityTypeDef;
     /** Return to review mode without saving. */
     back: () => void;
-    /** Refetch the parent + return to review mode. */
-    saved: () => void;
+    /** Refetch the parent + return to review mode. Pass the SAVED record and the
+     *  drawer moves onto it — its data and its version — so the next decision
+     *  asserts the version the editor just produced (bd startsim-jkkn7.20). */
+    saved: (record?: EntityRecord) => void;
   }) => ReactNode;
   /**
    * App-specific extra content under the record (e.g. a topic's drafts).
@@ -117,6 +119,15 @@ function ReviewDrawerInner({
   const [mode, setMode] = useState<'review' | 'edit'>('review');
   // Local optimistic copy so a click reflects instantly (the parent also refetches).
   const [data, setData] = useState<Record<string, unknown>>(() => ({ ...record.data }));
+  /**
+   * THE VERSION OF THE BLOB ABOVE, held beside it (bd startsim-jkkn7.20). `data`
+   * is seeded once per record id and every decision merges onto it, so the
+   * precondition must be the version THAT blob came from — never the parent's
+   * newer row after a list refetch, which would make a stale blob look current
+   * and erase whatever landed in between with a 200. Moves only when a write
+   * this drawer made succeeds, or the field editor hands back its saved record.
+   */
+  const versionRef = useRef<number | undefined>(isVersionNumber(record.version) ? record.version : undefined);
   const [busy, setBusy] = useState<string | null>(null);
   const [noteOpen, setNoteOpen] = useState(false);
   const [note, setNote] = useState(() => fieldStr(record.data, cfg.noteAttr));
@@ -169,14 +180,24 @@ function ReviewDrawerInner({
     let nextData: Record<string, unknown> = { ...data };
     for (const [k, v] of Object.entries(changes)) nextData = writeData(nextData, k, v);
     nextData = declaredBlob(nextData, declaredNames);
+    const before = data;
     setData(nextData); // optimistic
     setBusy(key);
     try {
-      await client.updateEntity(record.id, { data: nextData });
+      const held = versionRef.current;
+      const saved = await client.updateEntity(
+        record.id,
+        { data: nextData },
+        held !== undefined ? { expectedVersion: held } : undefined,
+      );
+      // THE ONLY PLACE THE HELD VERSION ADVANCES: a write this drawer made.
+      if (isVersionNumber(saved?.version)) versionRef.current = saved.version;
       onSaved?.();
       if (advance && next) onNavigate(next);
     } catch (err) {
-      setData({ ...record.data }); // roll back
+      // Back to what THIS drawer held, not the parent's row: after a refetch
+      // the prop can be a newer record than the blob the version belongs to.
+      setData(before); // roll back
       notify.error(err instanceof Error ? err.message : 'Could not save.');
     } finally {
       setBusy(null);
@@ -305,7 +326,14 @@ function ReviewDrawerInner({
                 record,
                 type,
                 back: () => setMode('review'),
-                saved: () => {
+                saved: (savedRecord?: EntityRecord) => {
+                  if (savedRecord) {
+                    setData({ ...savedRecord.data });
+                    setNote(fieldStr(savedRecord.data, cfg.noteAttr));
+                    versionRef.current = isVersionNumber(savedRecord.version)
+                      ? savedRecord.version
+                      : versionRef.current;
+                  }
                   onSaved?.();
                   setMode('review');
                 },

package/src/components/collection/TopicReviewWorkspace.tsx

@@ -17,7 +17,7 @@ import { Textarea } from '../ui/textarea';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select';
 import { notify } from '../toast/use-notify';
 import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
-import { declaredBlob, readData, writeData } from './data';
+import { declaredBlob, readData, writeData, writeOptionsFor } from './data';
 import { scopeKey } from './scoped-client';
 
 const STATUSES = ['suggested', 'ready', 'rejected', 'written'] as const;
@@ -115,7 +115,7 @@ export function TopicReviewWorkspace({ client, markets = [], renderDetail }: Top
       // The FULL blob, spread from the record — so an attribute this workspace
       // never touches (the scope path among them) survives a PATCH that
       // REPLACES the blob rather than merging it. A write is never a move.
-      await client.updateEntity(record.id, { data });
+      await client.updateEntity(record.id, { data }, writeOptionsFor(record));
       await qc.invalidateQueries({ queryKey: ['entities', 'topic'] });
     } catch (err) {
       notify.error(err instanceof Error ? err.message : 'Could not save.');