@startsimpli/ui 0.4.78 → 0.4.79

package/src/components/activity/ActivityFeedPanel.tsx

@@ -0,0 +1,208 @@
+'use client';
+
+/**
+ * ActivityFeedPanel — THE page-level activity composer (startsim-768w.19.5).
+ *
+ * The whole "what happened here" surface in one place: header, filter bar,
+ * day-grouped timeline, infinite scroll over the paginated endpoint, and three
+ * distinct nothing-to-show states (never recorded / filtered out / failed to
+ * load). An app supplies an injected client + its theme classNames and nothing
+ * else — rule #9 ships the composer, not just the primitive.
+ *
+ * CLIENT-INJECTED: the app passes `{ list: (p) => api.foundry.activity(slug, p) }`,
+ * which is what keeps @startsimpli/api out of packages/ui.
+ *
+ * THE UI MAKES NO VISIBILITY DECISIONS. There is no level check, no category
+ * vocabulary and no allowlist below this line. The endpoint already returned
+ * 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.
+ */
+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 { ErrorState } from '../states';
+import { ActivityFilterBar } from './ActivityFilterBar';
+import {
+  deriveActivityFilterOptions,
+  toActivityTimelineItems,
+} from './activity-events';
+import type {
+  ActivityClient,
+  ActivityEvent,
+  ActivityFilterOption,
+  ActivityFilterValue,
+} from './types';
+import {
+  ACTIVITY_FEED_PANEL_DEFAULTS,
+  type ActivityFeedPanelClassNames,
+} from './activity-feed-panel-default-class-names';
+
+export interface ActivityFeedPanelProps {
+  client: ActivityClient;
+  /** Cache namespace, e.g. `['foundry', slug, 'activity']`. The live filters
+   *  are appended, so invalidating the prefix refreshes every filtered view. */
+  queryKey?: readonly unknown[];
+  pageSize?: number;
+  refetchInterval?: number | false;
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Rendered at the right of the header — e.g. the current state badge. */
+  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;
+  showFilters?: boolean;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  filteredEmptyTitle?: string;
+  filteredEmptyDescription?: string;
+  errorTitle?: string;
+  activityIcons?: Record<string, ComponentType<any>>;
+  activityColors?: Record<string, string>;
+  defaultIcon?: ComponentType<any>;
+  classNames?: ActivityFeedPanelClassNames;
+}
+
+/** Typing shouldn't fire a request per keystroke; every other control should
+ *  apply at once. */
+function useDebounced<T>(value: T, ms: number): T {
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setSettled(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return settled;
+}
+
+/**
+ * Options accumulate across pages and across filtered views: once a person or
+ * an event type has been seen, it stays offerable, so narrowing to one action
+ * does not empty the picker you narrowed with. Still derived only from rows the
+ * user actually received.
+ */
+function useStickyOptions(events: ActivityEvent[]) {
+  const seen = useRef({ actors: new Map<string, string>(), actions: new Map<string, string>() });
+  return useMemo(() => {
+    const fresh = deriveActivityFilterOptions(events);
+    fresh.actors.forEach((o) => seen.current.actors.set(o.value, o.label));
+    fresh.actions.forEach((o) => seen.current.actions.set(o.value, o.label));
+    const sort = (m: Map<string, string>): ActivityFilterOption[] =>
+      [...m].map(([value, label]) => ({ value, label })).sort((a, b) => a.label.localeCompare(b.label));
+    return { actors: sort(seen.current.actors), actions: sort(seen.current.actions) };
+  }, [events]);
+}
+
+export function ActivityFeedPanel({
+  client,
+  queryKey = ['activity'],
+  pageSize = 25,
+  refetchInterval = false,
+  title = 'Activity',
+  description = 'Everything that happened here, newest first — as much as your access level allows.',
+  headerAside,
+  renderFooter,
+  showFilters = true,
+  emptyTitle = 'Nothing recorded yet',
+  emptyDescription = 'Actions taken here will show up in this list.',
+  filteredEmptyTitle = 'No activity matches these filters',
+  filteredEmptyDescription = 'Widen the date range or clear a filter to see more.',
+  errorTitle = 'Could not load activity',
+  activityIcons,
+  activityColors,
+  defaultIcon = ActivityIcon,
+  classNames = {},
+}: ActivityFeedPanelProps) {
+  const cx = { ...ACTIVITY_FEED_PANEL_DEFAULTS, ...classNames };
+
+  const [filters, setFilters] = useState<ActivityFilterValue>({});
+  const debouncedQ = useDebounced(filters.q ?? '', 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;
+    return debouncedQ ? { ...rest, q: debouncedQ } : rest;
+  }, [filters, debouncedQ]);
+
+  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),
+    refetchInterval,
+  });
+
+  const events = useMemo(
+    () => (query.data?.pages ?? []).flatMap((p) => p?.results ?? []),
+    [query.data],
+  );
+  const items = useMemo(() => toActivityTimelineItems(events), [events]);
+  const options = useStickyOptions(events);
+
+  const isFiltered = Object.keys(filters).length > 0;
+  const total = query.data?.pages?.[0]?.count ?? events.length;
+
+  const loadMore = () => {
+    if (query.hasNextPage && !query.isFetchingNextPage) query.fetchNextPage();
+  };
+
+  return (
+    <section className={cx.root} data-testid="activity-feed-panel">
+      <div className={cx.header}>
+        <div className={cx.heading}>
+          <h2 className={cx.title}>{title}</h2>
+          {description && <p className={cx.description}>{description}</p>}
+        </div>
+        {headerAside}
+      </div>
+
+      {showFilters && (
+        <div className={cx.filters}>
+          <ActivityFilterBar
+            value={filters}
+            onChange={setFilters}
+            actors={options.actors}
+            actions={options.actions}
+            classNames={cx.filterBar}
+          />
+        </div>
+      )}
+
+      <div className={cx.body}>
+        {query.isError ? (
+          <ErrorState
+            title={errorTitle}
+            message={(query.error as Error)?.message || 'Please try again.'}
+            onRetry={() => query.refetch()}
+          />
+        ) : (
+          <ActivityTimeline
+            activities={items}
+            loading={query.isLoading}
+            groupByDay
+            autoLoadMore
+            hasMore={!!query.hasNextPage}
+            onLoadMore={loadMore}
+            emptyTitle={isFiltered ? filteredEmptyTitle : emptyTitle}
+            emptyDescription={isFiltered ? filteredEmptyDescription : emptyDescription}
+            activityIcons={activityIcons}
+            activityColors={activityColors}
+            defaultIcon={defaultIcon}
+            loadMoreLabel={query.isFetchingNextPage ? 'Loading…' : 'Load more'}
+          />
+        )}
+      </div>
+
+      {events.length > 0 && total > events.length && (
+        <p className={cx.countLine}>
+          Showing {events.length} of {total} events.
+        </p>
+      )}
+
+      {renderFooter?.(events)}
+    </section>
+  );
+}

package/src/components/activity/ActivityFilterBar.tsx

@@ -0,0 +1,180 @@
+'use client';
+
+/**
+ * ActivityFilterBar — narrow an event stream by person, event type and date.
+ *
+ * Two invariants:
+ *   1. FILTERS SUBTRACT ONLY. Every change is handed straight to the server as
+ *      a query param; nothing here hides a row the caller received, and asking
+ *      for something the caller's level cannot see returns an empty page rather
+ *      than a hint that it exists.
+ *   2. THE OPTIONS ARE DERIVED, never declared. `actors` / `actions` come from
+ *      `deriveActivityFilterOptions(rowsTheUserReceived)`, so a new event type
+ *      appears in the picker on its own.
+ */
+import { X } from 'lucide-react';
+import type { ActivityFilterOption, ActivityFilterValue } from './types';
+import {
+  ACTIVITY_FILTER_BAR_DEFAULTS,
+  type ActivityFilterBarClassNames,
+} from './activity-filter-bar-default-class-names';
+
+export interface ActivityFilterBarProps {
+  value: ActivityFilterValue;
+  onChange: (next: ActivityFilterValue) => void;
+  /** Derived from the rows the user received — never a hardcoded list. */
+  actors?: ActivityFilterOption[];
+  actions?: ActivityFilterOption[];
+  searchPlaceholder?: string;
+  anyActorLabel?: string;
+  anyActionLabel?: string;
+  classNames?: ActivityFilterBarClassNames;
+}
+
+type FilterKey = keyof ActivityFilterValue;
+
+/** Drop empty keys so an "unfiltered" value is `{}` — the thing the panel and
+ *  the query key compare against. */
+function prune(value: ActivityFilterValue): ActivityFilterValue {
+  const out: ActivityFilterValue = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === 'string' && v.trim()) out[k as FilterKey] = v;
+  }
+  return out;
+}
+
+/** `2026-07-20` -> the instant the day starts / ends, in ISO-8601, because the
+ *  server bounds on a timestamp. A bare date would silently exclude the whole
+ *  of the `until` day. */
+function dayStart(date: string): string {
+  return `${date}T00:00:00.000Z`;
+}
+function dayEnd(date: string): string {
+  return `${date}T23:59:59.999Z`;
+}
+/** ISO instant -> the `YYYY-MM-DD` a date input wants back. */
+function asDateInput(iso?: string): string {
+  return iso ? iso.slice(0, 10) : '';
+}
+
+/** Show the DAY THE USER PICKED. The stored value is a UTC day boundary, so
+ *  handing it straight to `new Date()` and formatting locally shifts it back a
+ *  day west of Greenwich — the chip would contradict the date input above it. */
+function shortDate(iso: string): string {
+  const d = new Date(`${iso.slice(0, 10)}T12:00:00`);
+  return Number.isNaN(d.getTime())
+    ? iso
+    : d.toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric' });
+}
+
+export function activityFilterCount(value: ActivityFilterValue): number {
+  return Object.keys(prune(value)).length;
+}
+
+export function ActivityFilterBar({
+  value,
+  onChange,
+  actors = [],
+  actions = [],
+  searchPlaceholder = 'Search activity…',
+  anyActorLabel = 'Anyone',
+  anyActionLabel = 'All events',
+  classNames = {},
+}: ActivityFilterBarProps) {
+  const cx = { ...ACTIVITY_FILTER_BAR_DEFAULTS, ...classNames };
+
+  const set = (key: FilterKey, next: string | undefined) =>
+    onChange(prune({ ...value, [key]: next ?? '' }));
+
+  const labelFor = (options: ActivityFilterOption[], v: string) =>
+    options.find((o) => o.value === v)?.label ?? v;
+
+  const chips: Array<{ key: FilterKey; name: string; text: string }> = [];
+  if (value.actor) chips.push({ key: 'actor', name: 'person', text: `Person: ${labelFor(actors, value.actor)}` });
+  if (value.action) chips.push({ key: 'action', name: 'event', text: `Event: ${labelFor(actions, value.action)}` });
+  if (value.since) chips.push({ key: 'since', name: 'from date', text: `From ${shortDate(value.since)}` });
+  if (value.until) chips.push({ key: 'until', name: 'to date', text: `To ${shortDate(value.until)}` });
+  if (value.q) chips.push({ key: 'q', name: 'search', text: `Search: ${value.q}` });
+
+  return (
+    <div className={cx.root} data-testid="activity-filter-bar">
+      <div className={cx.controls}>
+        <input
+          type="search"
+          aria-label="Search activity"
+          placeholder={searchPlaceholder}
+          className={cx.search}
+          value={value.q ?? ''}
+          onChange={(e) => set('q', e.target.value)}
+        />
+
+        <select
+          aria-label="Filter by person"
+          className={cx.select}
+          value={value.actor ?? ''}
+          onChange={(e) => set('actor', e.target.value)}
+        >
+          <option value="">{anyActorLabel}</option>
+          {actors.map((o) => (
+            <option key={o.value} value={o.value}>
+              {o.label}
+            </option>
+          ))}
+        </select>
+
+        <select
+          aria-label="Filter by event"
+          className={cx.select}
+          value={value.action ?? ''}
+          onChange={(e) => set('action', e.target.value)}
+        >
+          <option value="">{anyActionLabel}</option>
+          {actions.map((o) => (
+            <option key={o.value} value={o.value}>
+              {o.label}
+            </option>
+          ))}
+        </select>
+
+        <div className={cx.dateGroup}>
+          <input
+            type="date"
+            aria-label="From date"
+            className={cx.date}
+            value={asDateInput(value.since)}
+            onChange={(e) => set('since', e.target.value ? dayStart(e.target.value) : '')}
+          />
+          <span className={cx.dateSeparator}>to</span>
+          <input
+            type="date"
+            aria-label="To date"
+            className={cx.date}
+            value={asDateInput(value.until)}
+            onChange={(e) => set('until', e.target.value ? dayEnd(e.target.value) : '')}
+          />
+        </div>
+      </div>
+
+      {chips.length > 0 && (
+        <div className={cx.chips} data-testid="activity-active-filters">
+          {chips.map((chip) => (
+            <span key={chip.key} className={cx.chip}>
+              {chip.text}
+              <button
+                type="button"
+                aria-label={`Remove filter: ${chip.name}`}
+                className={cx.chipRemove}
+                onClick={() => set(chip.key, '')}
+              >
+                <X className="h-3 w-3" />
+              </button>
+            </span>
+          ))}
+          <button type="button" className={cx.clearAll} onClick={() => onChange({})}>
+            Clear all
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}