@object-ui/plugin-detail 17.6.0 → 18.0.0

package/dist/renderers/recordActivityFeed.d.ts

@@ -1,5 +1,5 @@
 import { FeedItem, FeedItemType } from '@object-ui/types';
-import { FeedFilterMode } from '../RecordActivityTimeline';
+import { FeedFilterMode } from '../RecordActivityTimeline.js';
 /** Spec default for `RecordActivityProps.limit`. */
 export declare const DEFAULT_ACTIVITY_LIMIT = 20;
 /**
@@ -39,33 +39,182 @@ export declare const DEFAULT_ACTIVITY_LIMIT = 20;
  *    ADR-0052 §5b.2 `activityMilestones[].type` is applied verbatim by
  *    plugin-audit's `audit-writers.ts` (`if (milestone.type) activityType =
  *    milestone.type`). That is how `completed` is produced, and it is a general
- *    door, not a special case.
+ *    door, not a special case. A row that door wrote also carries
+ *    `metadata.kind: 'milestone'`, and the mapper overrides this table's
+ *    `completed` entry for it: see {@link MILESTONE_ACTIVITY_FEED_TYPE}
+ *    (objectui#12106).
  *
  * So `scheduled` is a value that is written, stored and queryable while being
  * undeclared upstream. Dropping it was not a decision this map made; it was the
- * absence of one. Its producer is HotCRM's `schedule_meeting` action
- * (`src/actions/global.actions.ts` — `type: EVENT_STATUS === 'held' ?
- * 'completed' : 'scheduled'`), registered for `crm_lead`, `crm_contact`,
- * `crm_account`, `crm_opportunity` and `crm_case`: the held branch reached the
- * timeline, the scheduled branch never did.
+ * absence of one. Its producer is HotCRM's activity-action factory
+ * (`src/sales/actions/activity-actions.ts`, once `src/actions/global.actions.ts`
+ * — `type: EVENT_STATUS === 'held' ? 'completed' : 'scheduled'`), which builds
+ * `log_call`, `log_meeting` and `schedule_meeting` for `crm_lead`,
+ * `crm_contact`, `crm_account`, `crm_opportunity` and `crm_case`: the held
+ * branch reached the timeline, the scheduled branch never did.
  *
  * `scheduled` → `event` is the semantic pairing and it is what makes the
- * declared `event` feed type reachable at all. Note the two branches of that
- * one producer now land at different DEFAULT visibility, which is the intended
- * reading: a held meeting is `completed` → `task`, hidden unless
- * `showCompleted`; a not-yet-held meeting is `scheduled` → `event`, shown,
- * because an upcoming meeting is the part of a timeline you still act on.
- *
- * Whether the upstream enum should GAIN `scheduled` is a platform ruling, not
- * this block's to make — filed as objectstack#11424. Until it is ruled, the
- * honest statement of this table is the one the test now pins: the upstream
- * declaration PLUS the values a shipped producer measurably writes.
- *
- * Values outside BOTH groups are still dropped — see
- * {@link activityRowToFeedItem}, which now says so out loud instead of
- * silently.
+ * declared `event` feed type reachable at all. Both branches of that producer
+ * show by default: a not-yet-held meeting is `scheduled` → `event`, because an
+ * upcoming meeting is the part of a timeline you still act on; a held one is
+ * `completed` → `task`, and shows because it is a LOGGED INTERACTION, a `task`
+ * item that points at the record it was logged as (objectui#12228, see
+ * {@link isLoggedInteraction}). Until objectui#12228 the held branch was hidden
+ * unless `showCompleted`.
+ *
+ * ## The vocabulary is OPEN — ruled. Do NOT restore set-equality.
+ *
+ * Maintainer ruling of 2026-08-24 (objectstack `88b9d749a`), **direction 4**:
+ * `sys_activity.type` is AUTHOR-EXTENSIBLE. The declared select options are the
+ * platform's BUILT-IN set, not the column's domain, and the two facts above are
+ * why — readonly fields are never validated on write, and ADR-0052 §5b.2
+ * forwards an author's `activityMilestones[].type` into the column verbatim.
+ *
+ * So the relation this table stands in is a SUPERSET, in one direction only:
+ *
+ *  - **map ⊇ built-ins** — every value the platform declares has an entry here,
+ *    either a feed type or a deliberate `undefined` exclusion. A new built-in
+ *    with no entry is a gap, and objectui#5969's pin turns red for it.
+ *  - **NOT built-ins ⊇ map**, and NOT set-equality in either spelling. An
+ *    author-extended value legitimately exists outside the declaration, so a
+ *    pin that required the two sets to match would be false by construction.
+ *
+ * ⛔ A reader who finds no equality check here is looking at a DECISION, not an
+ * omission: objectui#5840 removed the old set-equality pin on purpose, because
+ * pinning to the closed declaration meant dropping stored rows, and
+ * objectui#5969 replaced it with the two-directional pin under this ruling.
+ *
+ * (`scheduled` — the value #5840 was about — has since been declared upstream
+ * by objectstack#11522, superseding objectstack#11424. That is precisely the
+ * drift a hand-maintained equality pin cannot survive, and the reason the pin
+ * is a superset assertion plus a fallback rather than a census of two groups.)
+ *
+ * A value outside this table is NO LONGER DROPPED: it renders through
+ * {@link UNMAPPED_ACTIVITY_FEED_TYPE}. See {@link activityRowToFeedItem}.
  */
 export declare const ACTIVITY_TYPE_TO_FEED_TYPE: Readonly<Record<string, FeedItemType | undefined>>;
+/**
+ * The presentation an `sys_activity.type` value outside
+ * {@link ACTIVITY_TYPE_TO_FEED_TYPE} renders through.
+ *
+ * The second half of the direction-4 ruling (2026-08-24, objectstack `88b9d749a`): if
+ * the column is author-extensible, then a value this map has never heard of is
+ * REAL RECORD ACTIVITY that an author extended the platform with — not a
+ * mistake — and dropping it is the objectui#5840 failure mode reappearing for
+ * every author who ever writes one. Stored, queryable, invisible.
+ *
+ * `system` is the generic bucket rather than a new feed type because
+ * `FeedItemType` is a CLOSED spec enum owned by `@objectstack/spec` — minting a
+ * kind for "we don't know" is a platform change, not this block's.
+ *
+ * ⚠️ This is a FLOOR under the map, never a substitute for it. objectui#5840
+ * rejected a catch-all *offered as the fix* — an unmeasured type rendering as
+ * `system` is not the same data as a type someone read and mapped. What makes
+ * the catch-all safe here is that it does not stand alone: the superset pin
+ * above forces every built-in to keep its OWN presentation, so the fallback can
+ * only ever receive values nobody has ruled on yet, and the diagnostic below
+ * names each one so somebody can.
+ */
+export declare const UNMAPPED_ACTIVITY_FEED_TYPE: FeedItemType;
+/**
+ * The feed type a milestone row renders as when its `type` would otherwise land
+ * on a feed type `showCompleted` hides (objectui#12106).
+ *
+ * Today that is a `completed` row that a milestone fired, such as "Case
+ * resolved", or a task's own "Task completed" on that task's page. Triage
+ * ruled route B: a milestone is not a completed activity, so it shows whatever
+ * `showCompleted` says. `showCompleted` keeps its spec meaning ("Include
+ * completed activities") for every row without the marker.
+ *
+ * `system`, not `task` with an exemption, because every other reader of the
+ * feed type then stays right with no new member on `FeedItem`:
+ *
+ *  - `filterMode: 'tasks_only'` and `types: ['task']` keep meaning tasks. A
+ *    case milestone is not one.
+ *  - {@link COMPLETED_FEED_TYPES} stays exact: `task` is still produced only by
+ *    completed activities.
+ *  - The icon and colour are the ones every other author-typed milestone
+ *    already gets (`escalated` reaches `system` through
+ *    {@link UNMAPPED_ACTIVITY_FEED_TYPE}), and the ones app-shell's
+ *    `ActivityItem` surface gives `completed`.
+ *  - A host feed arrives already mapped, so the rule needs nothing carried
+ *    past this module.
+ */
+export declare const MILESTONE_ACTIVITY_FEED_TYPE: FeedItemType;
+/**
+ * Feed kinds an ObjectUI surface produces WITHOUT going through
+ * {@link ACTIVITY_TYPE_TO_FEED_TYPE}.
+ *
+ * Exactly one today: `comment`, built from `sys_comment` rows by app-shell's
+ * `RecordDetailView` (the `sys_comment` read, and the two optimistic rows the
+ * composer writes) and handed to this block through `DiscussionContext`. It
+ * cannot be derived here — app-shell depends on this package, not the other way
+ * round — so it is DECLARED, and `feedTypeProducerCensus-5877.test.ts` re-runs
+ * the census over the repository so the declaration cannot go stale silently.
+ *
+ * ## Census, and the pathspec it was taken over (objectui#5877)
+ *
+ * Every `.ts` / `.tsx` file in the repository that is not a test, at every top
+ * level (`packages/`, `apps/`, `examples/`, `scripts/`, `e2e/`), narrowed to the
+ * files that mention `FeedItem` at all — you cannot construct one without
+ * naming the type — then read for `FeedItemType` literals. 1622 files scanned,
+ * 13 mention `FeedItem`, one produces a kind off this map. A census is only as
+ * wide as its pathspec, so the pathspec is stated rather than implied, and the
+ * test above holds it.
+ *
+ * ⛔ NOT counted, deliberately: app-shell's `sharedUserFeeds.ts` /
+ * `activityItemType.ts` read the same `sys_activity` rows but produce
+ * `ActivityItemType` (`create` / `update` / `delete` / `comment` / `system`), a
+ * DIFFERENT five-value vocabulary that is not a projection of this one in either
+ * direction (objectui#6730 records why converging them costs rows). A row it
+ * turns into an `ActivityItem` never becomes a `FeedItem`, so it produces
+ * nothing for this feed. `ActivityEntry` in `@object-ui/types` is a third
+ * vocabulary again, and has no producer at all.
+ *
+ * ⚠️ Also NOT counted, and the reason the diagnostic below names it: a HOST can
+ * hand this block a feed of its own (`items` on the node, or a
+ * `DiscussionContext` it mounts itself). Those items are produced outside this
+ * repository, so no census taken here can bound their kinds.
+ */
+export declare const FEED_TYPES_PRODUCED_OFF_MAP: readonly FeedItemType[];
+/**
+ * Feed kinds this repository has decided NOT to adopt — as opposed to kinds
+ * nothing happens to produce.
+ *
+ * The distinction matters more than the diagnostic that uses it. Reporting a
+ * decision as a defect is how a warning channel gets trained out of an author's
+ * attention, and these three are decisions: `created` / `deleted` / `shared`
+ * rows are mapped to `field_change` ON PURPOSE, because `RecordDetailView` and
+ * this block must agree about what a `created` row IS before either can move to
+ * the richer kind. Adopting them is a change to that shared map, not to this
+ * block. The reasoning is written out at {@link ACTIVITY_TYPE_TO_FEED_TYPE}.
+ *
+ * ⚠️ This list is a TRANSCRIPTION of that prose, not a derivation, and there is
+ * no way to make it one: the decision exists as a comment, and a comment is not
+ * machine-readable. Two consequences, both load-bearing:
+ *
+ *  1. it is only as true as the prose it was copied from, so it is edited
+ *     together with that prose and never on its own;
+ *  2. a kind that is NOT on this list is not thereby known to be an oversight.
+ *     It is only known to have no producer. Whether somebody decided against it
+ *     and did not write it down is not recorded anywhere this code can read, and
+ *     the message below says so rather than guessing.
+ *
+ * ⛔ Do not extend it by inference. A kind belongs here when a decision about it
+ * is written down, not when its absence looks deliberate.
+ */
+export declare const DELIBERATELY_UNADOPTED_FEED_TYPES: readonly FeedItemType[];
+/**
+ * Every feed kind some ObjectUI surface can put on a record feed.
+ *
+ * DERIVED from the producers themselves — the map's range, its fallback, and
+ * the declared off-map producer above — never a second hand-written list of
+ * kinds. Giving an unproduced kind a producer (one new entry in
+ * {@link ACTIVITY_TYPE_TO_FEED_TYPE}) therefore retires its diagnostic in the
+ * same edit, with nothing else to remember. A hand-kept copy would not, and
+ * that copy is exactly what this file's header records the cost of.
+ */
+export declare const PRODUCED_FEED_TYPES: ReadonlySet<FeedItemType>;
 /** A row as `sys_activity` returns it. Loose on purpose: the block reads a
  *  system table it does not own, and an unknown column is not an error. */
 export interface SysActivityRow {
@@ -80,6 +229,12 @@ export interface SysActivityRow {
     source_id?: string | number | null;
     [k: string]: unknown;
 }
+/** Test seam: forget which `types` entries have already been named. */
+export declare function resetUnrecognisedFeedTypeWarnings(): void;
+/** Test seam: forget which unproduced `types` entries have already been named. */
+export declare function resetUnproducedFeedTypeWarnings(): void;
+/** Test seam: forget which `filterMode` values have already been named. */
+export declare function resetUnrecognisedFilterModeWarnings(): void;
 /**
  * Coerce an authored `filterMode` to a value the timeline understands.
  *
@@ -87,10 +242,40 @@ export interface SysActivityRow {
  * `<Select>` handed a value with no matching item renders blank and the
  * dropdown reads as broken. Same posture as objectui#3151 — an unrecognised
  * filter token is skipped, never turned into a filter that can't match.
+ *
+ * ## Why that fallback needs a diagnostic (objectui#5891)
+ *
+ * `'all'` is the WIDEST of the four declared modes — `filterItems` in
+ * `RecordActivityTimeline` narrows to ONE feed type for each of the other three
+ * and returns the feed untouched for `'all'` — so every unrecognised value
+ * lands on the one option that shows the author MORE than they asked for. A
+ * near-miss like `comments-only` or `commentsOnly` therefore opens the panel on
+ * the unfiltered stream, and the tell is a PLAUSIBLE result (a populated
+ * timeline) rather than an empty one that gets investigated. That is the same
+ * shape objectui#5841 removed from the sibling `types` sanitiser.
+ *
+ * The ruling on this card (triage, 2026-08-25) is that the defect is the
+ * INVISIBILITY, not the fallback: `filterMode` seeds a control the user can
+ * change, and there is no defensible narrower default to fall back to instead.
+ * So nothing that renders changes here — what changes is that the fold is now
+ * SAID OUT LOUD, once per distinct offending value on each block (see
+ * {@link warnOnce}).
+ *
+ * `block` is the registered name of the block the value was authored on
+ * (`record:activity`, `record:chatter`, `record:discussion`). It is REQUIRED,
+ * not defaulted: the message is addressed to that block's author, and a default
+ * would hand every caller that forgot it some other block's name — the defect
+ * objectui#9557 removed.
+ *
+ * Absent (`undefined` / `null`) is silent: no `filterMode` was authored, which
+ * is not a mistake, and a warning about a decision teaches authors to ignore
+ * the channel. Only a value the author actually wrote is reported.
+ *
+ * The declared modes named in the message are read from `@objectstack/spec`'s
+ * `FeedFilterMode` at runtime, never re-typed here — see the file header for
+ * what a hand copy of a spec enum cost.
  */
-export declare function normalizeFilterMode(value: unknown): FeedFilterMode;
-/** Test seam: forget which `types` entries have already been named. */
-export declare function resetUnrecognisedFeedTypeWarnings(): void;
+export declare function normalizeFilterMode(value: unknown, block: string): FeedFilterMode;
 /**
  * Sanitise an authored `types` allow-list. Narrowing or refusal, never widening.
  *
@@ -103,6 +288,7 @@ export declare function resetUnrecognisedFeedTypeWarnings(): void;
  * | `[]`                          | `[]`        | nothing — the author said "no kinds" |
  * | `['crm_task']` (none known)   | `[]`        | nothing, plus one diagnostic   |
  * | `['task', 'crm_task']`        | `['task']`  | the recognised members, plus one diagnostic |
+ * | `['approval']` (no producer)  | `['approval']` | nothing, plus one diagnostic — the kind is declared and honoured, but nothing emits it (objectui#5877) |
  *
  * `undefined` now means "no `types` key was authored" and ONLY that. It used to
  * mean that OR "everything you authored was dropped", and {@link applyFeedConfig}
@@ -121,13 +307,57 @@ export declare function resetUnrecognisedFeedTypeWarnings(): void;
  * Membership is read from `@objectstack/spec`'s `FeedItemType` at runtime, never
  * re-typed here — see the file header for what a hand copy of a spec enum cost.
  *
- * NOT pure: an entry it cannot recognise logs once (see {@link warnOnce}). The
- * failure being repaired is invisibility, so the diagnostic is the other half of
- * the fix rather than a nicety.
+ * NOT pure, on TWO independent channels (see {@link warnOnce}) — the failure
+ * being repaired is invisibility in both cases, so the diagnostics are the other
+ * half of the fix rather than a nicety:
+ *
+ *  - an entry it cannot recognise logs once (no declared kind matches it);
+ *  - a RECOGNISED entry that no producer emits logs once as well, on its own
+ *    channel — see {@link warnUnproducedFeedTypes}. That one changes nothing
+ *    about the return value: the kind is declared, so it is kept and honoured.
+ *
+ * Both channels name, and dedupe per, the REQUIRED `block` the list was
+ * authored on — see {@link normalizeFilterMode} for why it has no default.
+ */
+export declare function normalizeFeedTypes(value: unknown, block: string): FeedItemType[] | undefined;
+/**
+ * The ONE resolver for this block's row cap (objectui#10096, objectui#10145).
+ *
+ * A refused value is dropped for this block's own default.
+ *
+ * ⛔ Not `Math.floor`, which objectui#10096 replaced: flooring REPAIRED an
+ * authored `2.5` into a two-row window and handed it back as a result, so the
+ * author got a silently different number than the one they wrote. Refusing and
+ * defaulting is the answer the sibling `record:history` gives through
+ * `normalizeHistoryLimit`, and the answer objectui#9925 landed at three further
+ * read points (all three test `typeof value === 'number'` first, as this does).
+ *
+ * `NaN` and both infinities are refused (not integers); `0` and negatives are
+ * refused (not positive); `undefined` is the unauthored case and resolves to
+ * the default without being a refusal.
+ *
+ * ⚠️ FAIL-SOFT on purpose: throwing would take out a record page over one
+ * declaration. It is NOT silent — the renderers that call this state every
+ * refusal through `describeRefusedFeedLimit` (objectui#10097 ruled "always
+ * warn" for the family; objectui#10145 extends the refused set to non-numbers).
+ * This function stays pure so it can run on every render.
+ *
+ * ⭐ Shared with `record:chatter` / `record:discussion`, which resolve
+ * `feed.limit` through this same function — `RecordChatterProps.feed` is
+ * `RecordActivityProps`, so it is the same declared member and the same
+ * refusal.
  */
-export declare function normalizeFeedTypes(value: unknown): FeedItemType[] | undefined;
-/** Coerce `limit` to a positive integer, falling back to the spec default. */
 export declare function normalizeLimit(value: unknown): number;
+/**
+ * The diagnostic half of the row-cap refusal for the blocks that resolve
+ * through `normalizeLimit` (`record:activity`, `record:chatter`,
+ * `record:discussion`). `null` means "nothing to say": an absent `limit`
+ * (`undefined` / `null`) is not a mistake, and a usable one is not either.
+ *
+ * Callers fire it from an effect keyed on the declaration — the channel
+ * objectui#9925 uses at its three read points — never from render.
+ */
+export declare function describeRefusedFeedLimit(block: string, authored: unknown): string | null;
 /**
  * Timestamp of a `sys_activity` row.
  *
@@ -139,13 +369,49 @@ export declare function normalizeLimit(value: unknown): number;
 export declare function activityTimestamp(row: SysActivityRow): string;
 /** Test seam: forget which unknown types have already been warned about. */
 export declare function resetUnknownActivityTypeWarnings(): void;
+/**
+ * The name of whoever acted on a `sys_activity` row, or `null` when the row
+ * names nobody this viewer can name (objectui#12067). One reading for every
+ * surface that shows these rows: `record:history`, and through
+ * {@link activityRowToFeedItem} the `record:activity` block and the console
+ * record page's merged feed.
+ *
+ *  1. `actor_name`, when it is non-blank. It is the snapshot the writer took at
+ *     the time of the action, so it wins even over the user's current name.
+ *  2. `actor_id`, a lookup to `sys_user`. A read that passes
+ *     `$expand: ['actor_id']` gets the user's record in place of the id, and
+ *     that record's `name` (`sys_user`'s declared name field) names the actor.
+ *     The engine expands every row of a page in one batched read. This is the
+ *     row the `@objectstack/*` 17.7.0 writer leaves: `actor_id` set and no
+ *     `actor_name` (objectstack#22510 fills `actor_name` from then on).
+ *  3. `null`, so the caller shows its existing fallback. That covers a row
+ *     with neither, and an `actor_id` the engine kept as the bare id because
+ *     this viewer may not read that user or the user is gone. A raw id is
+ *     never shown as a name.
+ */
+export declare function activityActorName(row: SysActivityRow): string | null;
 /**
  * One `sys_activity` row → one {@link FeedItem}, or `null` when the row is not
  * record activity (see {@link ACTIVITY_TYPE_TO_FEED_TYPE}).
  *
- * Two different `null`s, and the difference is the point: a type the table
- * maps to `undefined` is a deliberate exclusion and returns quietly; a type the
- * table does not contain at all is an unmapped producer and says so once.
+ * Three outcomes, and the difference between the last two is the whole of the
+ * direction-4 ruling (2026-08-24, objectstack `88b9d749a`):
+ *
+ *  - a type mapped to a feed type renders with THAT presentation;
+ *  - a type the table maps to `undefined` is a DELIBERATE exclusion — `null`,
+ *    quietly, because a warning about a decision teaches authors to ignore the
+ *    channel;
+ *  - a type the table does not contain at all is an AUTHOR-EXTENDED value under
+ *    the ruled open vocabulary. It renders through
+ *    {@link UNMAPPED_ACTIVITY_FEED_TYPE} and says so once. It used to return
+ *    `null` here, which made every extended value invisible — the same outcome
+ *    objectui#5840 was filed for, reached by a different route.
+ *
+ * One override sits on top of the first outcome (objectui#12106): a row whose
+ * type maps to a feed type `showCompleted` hides, but which carries the
+ * milestone marker, renders as {@link MILESTONE_ACTIVITY_FEED_TYPE}. A
+ * milestone is not a completed activity. A row without the marker is mapped
+ * exactly as before.
  */
 export declare function activityRowToFeedItem(row: SysActivityRow, systemActorLabel: string): FeedItem | null;
 /** The subset of `RecordActivityProps` that decides which items survive. */
@@ -173,8 +439,52 @@ export interface AppliedFeed {
  * `pageSize` is the effective window (`limit` on first render, grown by
  * "Load more"); it is separate from `config.limit` so paging does not have to
  * rewrite the authored config.
+ *
+ * `block` is the registered name of the block whose config this is; the
+ * `types` diagnostics are addressed to it (objectui#9557, see
+ * {@link normalizeFilterMode}).
  */
-export declare function applyFeedConfig(items: readonly FeedItem[], config: FeedConfigFilters, pageSize: number): AppliedFeed;
+export declare function applyFeedConfig(items: readonly FeedItem[], config: FeedConfigFilters, pageSize: number, block: string): AppliedFeed;
 /** Sort a feed chronologically and de-duplicate by id (feeds are append-only). */
 export declare function mergeFeedItems(...groups: readonly FeedItem[][]): FeedItem[];
+/**
+ * Whether a rejected feed read — `sys_activity` or `sys_comment` — was REFUSED
+ * (objectui#11195): the server answered, and the answer was "not for you".
+ *
+ * A refused read and an empty read are different answers about the record, and
+ * the panel used to give both the same one. Every failure on the feed landed on
+ * `No activity recorded` / `No comments yet`, so a member the server refused
+ * read a permission wall as a record where nothing had happened. The panel now
+ * shows a no-permission state for a refused read instead, and keeps the empty
+ * state for a read that answered with zero rows.
+ *
+ * The verdict is `classifyLoadError`'s (`@object-ui/react`), the read
+ * classifier `ListView`'s error panel and `RecordAttachmentsPanel` already
+ * share. Nothing here reads a status or a code of its own. Refused means the
+ * two kinds that are about the caller:
+ *
+ *   - `forbidden`: 403, or a `PERMISSION_DENIED` / `FORBIDDEN` envelope;
+ *   - `unauthorized`: 401, or `UNAUTHORIZED` / `UNAUTHENTICATED`.
+ *
+ * ⚠️ The 401 half is a deliberate difference from `RecordAttachmentsPanel`,
+ * whose `denied` state does not claim a 401. The triage on objectui#11195 ruled
+ * it for this panel: any refused read (401 / 403, or a permission envelope)
+ * shows the no-permission state.
+ *
+ * NOT refused, so these keep today's empty state:
+ *
+ *   - `api-disabled` (`OBJECT_API_DISABLED` 404 / `OBJECT_API_METHOD_NOT_ALLOWED`
+ *     405): a property of the object's metadata, not of the caller, and no
+ *     permission grant changes it;
+ *   - a bare 404 (`sys_activity` on a deployment without the audit plugin).
+ *     The ObjectStack adapter already answers that as zero rows; another
+ *     adapter's rejection classifies as `network` and lands here;
+ *   - `rejected` (400) and `network` (a 5xx, an unreachable server). Those are
+ *     failures, not refusals. The panel has no error state of its own, so they
+ *     still render the empty state.
+ *
+ * ⛔ A refusal is not retried. A refused read is the same answer on every
+ * retry, so the callers write it into state and do not re-issue the read.
+ */
+export declare function isRefusedFeedRead(err: unknown): boolean;
 //# sourceMappingURL=recordActivityFeed.d.ts.map

package/dist/renderers/recordActivityFeed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recordActivityFeed.d.ts","sourceRoot":"","sources":["../../src/renderers/recordActivityFeed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKhE,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC,CAazF,CAAC;AAgBF;2EAC2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAIlE;AAkCD,uEAAuE;AACvE,wBAAgB,iCAAiC,IAAI,IAAI,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,GAAG,SAAS,CAuC7E;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAM7D;AAiCD,4EAA4E;AAC5E,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,cAAc,EACnB,gBAAgB,EAAE,MAAM,GACvB,QAAQ,GAAG,IAAI,CAoBjB;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,MAAM,GACf,WAAW,CAyCb;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,GAAG,MAAM,EAAE,SAAS,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,CAU3E"}
+{"version":3,"file":"recordActivityFeed.d.ts","sourceRoot":"","sources":["../../src/renderers/recordActivityFeed.ts"],"names":[],"mappings":"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"}

package/dist/renderers/recordBinding.d.ts

@@ -0,0 +1,180 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * The ONE-RECORD binding of the record blocks (objectui#12294).
+ *
+ * `PageComponentSchema.dataSource` is the spec's per-element data binding, and
+ * the spec declares it on every page component ("Overrides the page-level
+ * object context for this block"). `ElementDataSourceGate` (`@object-ui/react`)
+ * honours it for the LIST-shaped blocks by mapping the binding onto keys the
+ * block then queries with. The record blocks query nothing: they read the row
+ * the record page put in `RecordContextProvider`. So on an `app` page, with no
+ * record page around them, `record:details`, `record:highlights` and
+ * `record:quick_actions` drew an empty box or "no actions configured" even
+ * with a binding that returns one row.
+ *
+ * This module is the one-record consumer those three share, and
+ * {@link recordBindingBlock} is the one way a record block takes it. The gate
+ * still resolves the binding (the named view, the AND-combined filter, the
+ * sort, and every configuration panel the family draws), so a record block's
+ * binding means exactly what it means on a list block. What this adds is the
+ * last hop: read the bound set, take its FIRST row, and provide that row
+ * through the existing `RecordContextProvider` — so the block bodies are
+ * unchanged and there is no second rendering path inside a block.
+ *
+ * ## Semantics of the bound set (the card's, verbatim in intent)
+ *
+ *  - 0 rows → the block's authored `emptyState` when it declares one (see
+ *    "The authored empty state" below). Without one, the block is mounted under
+ *    a record context that names the bound object and NO record, so each block
+ *    draws what it draws for a record that is not there: `record:details` its
+ *    "record not found" state, `record:highlights` nothing,
+ *    `record:quick_actions` its empty bar. A row the caller may not read never
+ *    comes back from the server, and a read the server refuses outright
+ *    (`classifyLoadError` → `forbidden`) is treated the same, so "absent" and
+ *    "not yours to read" are indistinguishable — and the authored empty state
+ *    is drawn for both.
+ *  - 1 row → that record.
+ *  - more than one row → the FIRST by the binding's `sort`. Only one row is
+ *    ever asked for (`$top: 1`): the first row of the authored `limit` and the
+ *    first row of a one-row read are the same row under the same `sort`.
+ *    `objectui validate` warns on a record block whose binding has no
+ *    `limit: 1`, so an author says which one they mean.
+ *
+ * The row is read with the adapter the page already uses, so under the
+ * caller's identity: nothing here widens what the server serves.
+ *
+ * ## The authored empty state (objectui#12932)
+ *
+ * The spec declares `emptyState` on the three bound record blocks
+ * (`RecordDetailsProps`, `RecordHighlightsProps`, `RecordQuickActionsProps`;
+ * objectstack#24266), the list view's own `EmptyStateSchema` by reference:
+ * `{ title, message, icon, link }`. It is drawn on ONE condition, the spec's:
+ * the block carries a `dataSource` binding and the settled read answered no
+ * row. {@link BoundRecordEmptyState} draws it IN PLACE of the block body, with
+ * the pieces `ObjectGrid` draws its authored empty state with —
+ * `DataEmptyState`, `resolveIcon` for the `icon`, the spec's own
+ * `resolveI18nLabel` for `title` and `message` against the display locale,
+ * and the one shared `EmptyStateLink` for `link` — so one key draws one
+ * picture on every surface that takes it.
+ *
+ * It is NOT drawn while the read is in flight (the loading state), for a read
+ * that failed (the error panel stays the error panel), for a bound row that is
+ * there but leaves the block nothing to show, or on an unbound block: an
+ * unbound block reads the record page's record and never reaches this module's
+ * read. A block that declares none keeps its own no-record state above.
+ *
+ * ## The record page path is untouched
+ *
+ * {@link BoundRecordScope} renders its children AS THEY ARE when the block
+ * carries no binding: no provider, no element, no fetch. A record page's own
+ * `RecordContextProvider` therefore still reaches the block, byte-identically.
+ * With a binding, the binding wins, as the spec says it does: the bound record
+ * shadows the page record for this block only.
+ *
+ * ## Freshness: the data-invalidation bus (objectstack#4444's bar)
+ *
+ * A fetching record context that does not listen to the bus shows a STALE
+ * record that looks correct after a write elsewhere on the page — harder to
+ * notice than an empty one. So the read is keyed on `useDataInvalidation` for
+ * the bound OBJECT, the same bus `RecordDetailView` keys its record read on.
+ * Object-scoped, not row-scoped, because the binding is a query: a write to any
+ * row of the object can change which row is first. A refetch replaces the row
+ * in place (no remount), and an equal answer is not republished as a new object
+ * (AGENTS.md #10).
+ *
+ * ## What a bound block does NOT join
+ *
+ * A bound block sits inside the record page's providers when it is placed on a
+ * record page, and two of them are about THAT page's record:
+ *
+ *  - the page's inline-edit session (`InlineEditProvider`): a bound
+ *    `record:details` or `record:highlights` joining it would put the bound
+ *    record's fields into the page record's draft, and the page's Save bar
+ *    would write them to the page record. The bound scope mounts a read-only
+ *    session instead (`canEdit: false`), which is also what an `app` page,
+ *    with no session at all, already gives these blocks;
+ *  - the page's highlight-field registry (`HighlightFieldsProvider`): a bound
+ *    `record:highlights` would otherwise hide fields from the PAGE record's
+ *    `record:details`. The bound scope gets its own registry.
+ *
+ * ## The PARENT binding of `record:related_list` ({@link ParentRecordBinding})
+ *
+ * `record:related_list` is the one record block with two bindings (ruling B on
+ * objectui#12296): its node-level `dataSource` is the CHILD rows the list
+ * draws (objectstack#6953), and the spec row's `parentDataSource` is the record
+ * the list hangs off. The parent binding is read here, by the same one-record
+ * read: the same gate, the same first row by `sort`, the same invalidation bus,
+ * provided through the same `RecordContextProvider` the related-list body
+ * already reads. It differs from the three blocks above in ONE place, and the
+ * spec's describe is why: no row is a LOUD ABSENCE drawn in the block's place,
+ * never an empty record context — under one the list would query nothing and
+ * draw an empty list, which reads as "this record has no related records", a
+ * wrong fact in the silent direction.
+ */
+import * as React from 'react';
+/**
+ * Wrap a record block's body so its `dataSource` binding supplies its record,
+ * and declare the key through the seam.
+ *
+ * The one way a record block takes the binding, so a fourth one cannot take it
+ * differently: `ElementDataSourceGate` resolves the binding (and draws the
+ * family's panels for an unresolvable view, a refused filter, or no adapter),
+ * {@link BoundRecordScope} reads and provides the first row, and
+ * `elementDataSourceBlock` makes the registration publish the injected
+ * `dataSource` input — from `@object-ui/core`, the import source
+ * `check:element-data-source-declaration` holds every call site to.
+ *
+ * `requiresDataSource` is set for a BOUND block only: a bound block with no
+ * adapter has nothing to read its row with, and says so through the family's
+ * no-data-source panel. An unbound block is the record page path, left as it was.
+ *
+ * @param Body     The block's renderer, unchanged: it reads `useRecordContext()`.
+ * @param blockKey The registry key (`record:details`, …); the panel test ids are
+ *                 derived from it the way `record-related-list` spells its own.
+ */
+export declare function recordBindingBlock<RendererProps extends {
+    schema?: unknown;
+}>(Body: React.ComponentType<RendererProps>, blockKey: string): React.FC<RendererProps>;
+export interface ParentRecordBindingProps {
+    /**
+     * The PARENT binding as authored — `record:related_list`'s
+     * `parentDataSource`, the spec's `ElementDataSourceSchema` by reference.
+     * Anything that is not a binding the gate would resolve (absent included)
+     * leaves the children exactly as they are.
+     */
+    binding: unknown;
+    /** The block's registry key, named in the no-adapter panel. */
+    blockKey: string;
+    /** `data-testid` stem for this scope's states (`<stem>-loading-record`, …). */
+    testId: string;
+    /** Heading of the panels a binding that cannot be read draws. */
+    errorTitle?: string;
+    /** What the block draws in its own place when no row answers: the loud absence. */
+    absent: React.ReactNode;
+    children: React.ReactNode;
+}
+/**
+ * The parent record of a block, from a binding of its own (ruling B on
+ * objectui#12296, the spec's `RecordRelatedListProps.parentDataSource`).
+ *
+ * Unbound → the children as they are, so the record page's own context still
+ * reaches the block, byte-identically. Bound → the binding is resolved by
+ * `ElementDataSourceGate` (a named view, the AND-combined filter, the sort, and
+ * the family's panels for a view that does not resolve, a refused filter, or no
+ * adapter), its FIRST row is read by {@link BoundRecordProvider} — the one
+ * read the three one-record blocks take, keyed on the same invalidation bus —
+ * and provided through `RecordContextProvider` as the children's record. No row
+ * draws `absent` instead of the children.
+ *
+ * The gate is handed the parent binding ALONE, as a node's `dataSource`, and
+ * never the block's own schema: with the schema, the gate's filter and sort
+ * mapping would compose the block's own `filter` and `sort` — the CHILD list's
+ * — into the parent's query.
+ */
+export declare function ParentRecordBinding({ binding, blockKey, testId, errorTitle, absent, children, }: ParentRecordBindingProps): React.ReactElement;
+//# sourceMappingURL=recordBinding.d.ts.map

package/dist/renderers/recordBinding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordBinding.d.ts","sourceRoot":"","sources":["../../src/renderers/recordBinding.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqHG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA+C/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,SAAS;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAC3E,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,aAAa,CAAC,EACxC,QAAQ,EAAE,MAAM,GACf,KAAK,CAAC,EAAE,CAAC,aAAa,CAAC,CA0BzB;AA6FD,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,QAAQ,EACR,MAAM,EACN,UAAU,EACV,MAAM,EACN,QAAQ,GACT,EAAE,wBAAwB,GAAG,KAAK,CAAC,YAAY,CAgC/C"}