From 0f76456848d27e89f21e74e0918fdde687372d80 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 11:47:22 +0000 Subject: [PATCH 1/2] docs(spec): the record-page timeline total's description reads it as an upper bound of the drawn entries RecordPageTimelineCountSchema's docblock and its total .describe() now say what the RecordPageTimelineRequestSchema docblock says: the total counts the sources' rows as that schema's table defines them, so it is an upper bound of the entries the panel draws. Regenerated the API reference page. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01QsR2jUNaEANxba2LHLfyuZ --- .changeset/29138-timeline-total-describe.md | 10 ++++++++++ content/docs/references/api/record-page.mdx | 4 ++-- packages/spec/src/api/record-page.zod.ts | 12 ++++++++++-- 3 files changed, 22 insertions(+), 4 deletions(-) create mode 100644 .changeset/29138-timeline-total-describe.md diff --git a/.changeset/29138-timeline-total-describe.md b/.changeset/29138-timeline-total-describe.md new file mode 100644 index 00000000000..c89b8697fea --- /dev/null +++ b/.changeset/29138-timeline-total-describe.md @@ -0,0 +1,10 @@ +--- +'@objectstack/spec': patch +--- + +docs(spec): the record-page `timeline` total's published description reads it as an upper bound of the drawn 动态 entries + +Clause-②: no +Metadata-protocol: none + +`RecordPageTimelineCountSchema.total`'s `.describe()`, which ships in the published JSON schema and the API reference, and the schema's docblock now say what the `RecordPageTimelineRequestSchema` docblock says: the total counts the rows of the sources the request named, as that schema's table defines them and as the caller may read them. That makes it an upper bound of the entries the 动态 panel draws, not their number. The panel draws fewer where its `showCompleted` / `types` configuration filters entries out, and where a ledger row has no displayable diff. Description text only: no key, type, bound, default or export changes, and no behaviour changes. diff --git a/content/docs/references/api/record-page.mdx b/content/docs/references/api/record-page.mdx index 69f69e145b7..7c56e4bec72 100644 --- a/content/docs/references/api/record-page.mdx +++ b/content/docs/references/api/record-page.mdx @@ -548,7 +548,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **total** | `integer` | ✅ | How many entries the record's timeline stream holds for this caller, over the sources the request named. | +| **total** | `integer` | ✅ | The rows of the sources the request named, counted as this caller may read them: an upper bound of the entries the timeline panel draws, not their number. The panel draws fewer where its `showCompleted` / `types` configuration filters entries out, and where a ledger row has no displayable diff. | ### Nested Shape: `RecordPageResponse.timeline[option 2]` @@ -596,7 +596,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **total** | `integer` | ✅ | How many entries the record's timeline stream holds for this caller, over the sources the request named. | +| **total** | `integer` | ✅ | The rows of the sources the request named, counted as this caller may read them: an upper bound of the entries the timeline panel draws, not their number. The panel draws fewer where its `showCompleted` / `types` configuration filters entries out, and where a ledger row has no displayable diff. | --- diff --git a/packages/spec/src/api/record-page.zod.ts b/packages/spec/src/api/record-page.zod.ts index 7a11240da19..d0c4d6a55d2 100644 --- a/packages/spec/src/api/record-page.zod.ts +++ b/packages/spec/src/api/record-page.zod.ts @@ -313,10 +313,18 @@ export const RecordPageStreamRowsSchema = lazySchema(() => z.object({ export type RecordPageStreamRows = z.input; export type RecordPageStreamRowsParsed = z.infer; -/** [#28737] The `timeline` part: how many entries the record's 动态 stream holds. */ +/** + * [#28737] The `timeline` part: the size of the record's 动态 stream, counted + * by the reads `RecordPageTimelineRequestSchema` names, as the caller. The + * total counts the sources' rows as that schema's table defines them, so it is + * an upper bound of the entries the 动态 panel draws, not their number. The + * panel draws fewer where its `showCompleted` / `types` configuration filters + * entries out, and where a ledger row has no displayable diff and so draws no + * entry. + */ export const RecordPageTimelineCountSchema = lazySchema(() => z.object({ total: z.number().int().min(0).describe( - 'How many entries the record\'s timeline stream holds for this caller, over the sources the request named.', + 'The rows of the sources the request named, counted as this caller may read them: an upper bound of the entries the timeline panel draws, not their number. The panel draws fewer where its `showCompleted` / `types` configuration filters entries out, and where a ledger row has no displayable diff.', ), }).strict()); export type RecordPageTimelineCount = z.input; From 3d670128cf3ea57a2845ad44ea6d11b03212657d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 12:56:22 +0000 Subject: [PATCH 2/2] docs(types): the record-page timeline total's docblock reads it as an upper bound of the drawn entries The RecordPageResponse.timeline docblock in @object-ui/types says what the spec's RecordPageTimelineCountSchema now says: the total counts the sources' rows, so it is an upper bound of the entries the panel draws, and names the two cases where the panel draws fewer. Comment only. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01QsR2jUNaEANxba2LHLfyuZ --- .changeset/29138-timeline-total-describe.md | 3 +++ ui/packages/types/src/data.ts | 9 ++++++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/.changeset/29138-timeline-total-describe.md b/.changeset/29138-timeline-total-describe.md index c89b8697fea..304eba9a27a 100644 --- a/.changeset/29138-timeline-total-describe.md +++ b/.changeset/29138-timeline-total-describe.md @@ -1,5 +1,6 @@ --- '@objectstack/spec': patch +'@object-ui/types': patch --- docs(spec): the record-page `timeline` total's published description reads it as an upper bound of the drawn 动态 entries @@ -8,3 +9,5 @@ Clause-②: no Metadata-protocol: none `RecordPageTimelineCountSchema.total`'s `.describe()`, which ships in the published JSON schema and the API reference, and the schema's docblock now say what the `RecordPageTimelineRequestSchema` docblock says: the total counts the rows of the sources the request named, as that schema's table defines them and as the caller may read them. That makes it an upper bound of the entries the 动态 panel draws, not their number. The panel draws fewer where its `showCompleted` / `types` configuration filters entries out, and where a ledger row has no displayable diff. Description text only: no key, type, bound, default or export changes, and no behaviour changes. + +The `RecordPageResponse.timeline` docblock in `@object-ui/types`, the UI's mirror of the response, says the same: the total counts the sources' rows, so it is an upper bound of the drawn entries, and the panel draws fewer in the same two cases. Comment only: no type, member or export changes. diff --git a/ui/packages/types/src/data.ts b/ui/packages/types/src/data.ts index 64d5fe76701..b5c4cdf1ac3 100644 --- a/ui/packages/types/src/data.ts +++ b/ui/packages/types/src/data.ts @@ -423,9 +423,12 @@ export interface RecordPagePayload { /** The record's newest attachments and their count, or their read's refusal (objectstack#28470). */ attachments?: { total: number; records: Record[] } | { error: RecordPagePartRefusal }; /** - * How many entries the record's 动态 stream holds over the sources the - * request named (objectstack#28737), or the refusal of a comment or - * activity read. + * The size of the record's 动态 stream over the sources the request named + * (objectstack#28737), or the refusal of a comment or activity read. The + * total counts the sources' rows, so it is an upper bound of the entries the + * 动态 panel draws, not their number: the panel draws fewer where its + * `showCompleted` / `types` configuration filters entries out, and where a + * ledger row has no displayable diff and so draws no entry. */ timeline?: { total: number } | { error: RecordPagePartRefusal }; }