feat(page-number): chapter-prefixed section page numbering (SD-3029)

apps/docs/document-api/reference/_generated-manifest.json

@@ -1078,5 +1078,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "5f439c4117bbb2e55f227e7711df415c1173f8c476954c6e412a4b8b45edd1a3"
+  "sourceHash": "fc2e513626b5bfc6383d968b9bffdcea0f086469bf867a588dd7319c8b75c7de"
 }

apps/docs/document-api/reference/index.mdx

@@ -116,7 +116,7 @@ The tables below are grouped by namespace.
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-page-setup"><code>sections.setPageSetup</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setPageSetup(...)</code></span> | Set page size/orientation properties for a section. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-columns"><code>sections.setColumns</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setColumns(...)</code></span> | Set column configuration for a section. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-line-numbering"><code>sections.setLineNumbering</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setLineNumbering(...)</code></span> | Enable or configure line numbering for a section. |
-| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-page-numbering"><code>sections.setPageNumbering</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setPageNumbering(...)</code></span> | Set page numbering format/start for a section. |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-page-numbering"><code>sections.setPageNumbering</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setPageNumbering(...)</code></span> | Set page numbering format/start and chapter numbering settings for a section. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-title-page"><code>sections.setTitlePage</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setTitlePage(...)</code></span> | Enable or disable title-page behavior for a section. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-odd-even-headers-footers"><code>sections.setOddEvenHeadersFooters</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setOddEvenHeadersFooters(...)</code></span> | Enable or disable odd/even header-footer mode in document settings. |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/sections/set-vertical-align"><code>sections.setVerticalAlign</code></a></span> | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.sections.setVerticalAlign(...)</code></span> | Set vertical page alignment for a section. |

apps/docs/document-api/reference/sections/get.mdx

@@ -111,6 +111,8 @@ Returns a SectionInfo object with full section properties including margins, col
 | `pageBorders.top.style` | string | no |  |
 | `pageBorders.zOrder` | enum | no | `"front"`, `"back"` |
 | `pageNumbering` | object | no |  |
+| `pageNumbering.chapterSeparator` | enum | no | `"hyphen"`, `"period"`, `"colon"`, `"emDash"`, `"enDash"` |
+| `pageNumbering.chapterStyle` | integer | no |  |
 | `pageNumbering.format` | enum | no | `"decimal"`, `"lowerLetter"`, `"upperLetter"`, `"lowerRoman"`, `"upperRoman"`, `"numberInDash"` |
 | `pageNumbering.start` | integer | no |  |
 | `pageSetup` | object | no |  |
@@ -614,6 +616,20 @@ Returns a SectionInfo object with full section properties including margins, col
     "pageNumbering": {
       "additionalProperties": false,
       "properties": {
+        "chapterSeparator": {
+          "enum": [
+            "hyphen",
+            "period",
+            "colon",
+            "emDash",
+            "enDash"
+          ],
+          "type": "string"
+        },
+        "chapterStyle": {
+          "minimum": 1,
+          "type": "integer"
+        },
         "format": {
           "enum": [
             "decimal",

apps/docs/document-api/reference/sections/list.mdx

@@ -586,6 +586,20 @@ Returns a SectionsListResult with an ordered array of section summaries and thei
           "pageNumbering": {
             "additionalProperties": false,
             "properties": {
+              "chapterSeparator": {
+                "enum": [
+                  "hyphen",
+                  "period",
+                  "colon",
+                  "emDash",
+                  "enDash"
+                ],
+                "type": "string"
+              },
+              "chapterStyle": {
+                "minimum": 1,
+                "type": "integer"
+              },
               "format": {
                 "enum": [
                   "decimal",

apps/docs/document-api/reference/sections/set-page-numbering.mdx

@@ -1,14 +1,14 @@
 ---
 title: sections.setPageNumbering
 sidebarTitle: sections.setPageNumbering
-description: Set page numbering format/start for a section.
+description: Set page numbering format/start and chapter numbering settings for a section.
 ---
 
 {/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}
 
 ## Summary
 
-Set page numbering format/start for a section.
+Set page numbering format/start and chapter numbering settings for a section.
 
 - Operation ID: `sections.setPageNumbering`
 - API member path: `editor.doc.sections.setPageNumbering(...)`
@@ -20,7 +20,7 @@ Set page numbering format/start for a section.
 
 ## Expected result
 
-Returns a SectionMutationResult receipt; reports NO_OP if page numbering format already matches.
+Returns a SectionMutationResult receipt; reports NO_OP if page numbering settings already match.
 
 ## Input fields
 
@@ -42,6 +42,24 @@ Returns a SectionMutationResult receipt; reports NO_OP if page numbering format
 | `target.kind` | `"section"` | yes | Constant: `"section"` |
 | `target.sectionId` | string | yes |  |
 
+### Variant 3 (target.kind="section")
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chapterStyle` | integer | yes |  |
+| `target` | SectionAddress | yes | SectionAddress |
+| `target.kind` | `"section"` | yes | Constant: `"section"` |
+| `target.sectionId` | string | yes |  |
+
+### Variant 4 (target.kind="section")
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chapterSeparator` | enum | yes | `"hyphen"`, `"period"`, `"colon"`, `"emDash"`, `"enDash"` |
+| `target` | SectionAddress | yes | SectionAddress |
+| `target.kind` | `"section"` | yes | Constant: `"section"` |
+| `target.sectionId` | string | yes |  |
+
 ### Example request
 
 ```json
@@ -107,7 +125,7 @@ Returns a SectionMutationResult receipt; reports NO_OP if page numbering format
 ```json
 {
   "additionalProperties": false,
-  "oneOf": [
+  "anyOf": [
     {
       "required": [
         "target",
@@ -119,9 +137,35 @@ Returns a SectionMutationResult receipt; reports NO_OP if page numbering format
         "target",
         "format"
       ]
+    },
+    {
+      "required": [
+        "target",
+        "chapterStyle"
+      ]
+    },
+    {
+      "required": [
+        "target",
+        "chapterSeparator"
+      ]
     }
   ],
   "properties": {
+    "chapterSeparator": {
+      "enum": [
+        "hyphen",
+        "period",
+        "colon",
+        "emDash",
+        "enDash"
+      ],
+      "type": "string"
+    },
+    "chapterStyle": {
+      "minimum": 1,
+      "type": "integer"
+    },
     "format": {
       "enum": [
         "decimal",

packages/document-api/src/contract/operation-definitions.ts

@@ -1259,8 +1259,8 @@ export const OPERATION_DEFINITIONS = {
   },
   'sections.setPageNumbering': {
     memberPath: 'sections.setPageNumbering',
-    description: 'Set page numbering format/start for a section.',
-    expectedResult: 'Returns a SectionMutationResult receipt; reports NO_OP if page numbering format already matches.',
+    description: 'Set page numbering format/start and chapter numbering settings for a section.',
+    expectedResult: 'Returns a SectionMutationResult receipt; reports NO_OP if page numbering settings already match.',
     requiresDocumentContext: true,
     metadata: mutationOperation({
       idempotency: 'conditional',

packages/document-api/src/contract/schemas.ts

@@ -1281,6 +1281,8 @@ const sectionLineNumberingSchema = objectSchema(
 const sectionPageNumberingSchema = objectSchema({
   start: { type: 'integer', minimum: 1 },
   format: sectionPageNumberFormatSchema,
+  chapterStyle: { type: 'integer', minimum: 1 },
+  chapterSeparator: { type: 'string', enum: ['hyphen', 'period', 'colon', 'emDash', 'enDash'] },
 });
 
 const sectionHeaderFooterRefsSchema = objectSchema({
@@ -4018,10 +4020,17 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
           target: sectionAddressSchema,
           start: { type: 'integer', minimum: 1 },
           format: sectionPageNumberFormatSchema,
+          chapterStyle: { type: 'integer', minimum: 1 },
+          chapterSeparator: { type: 'string', enum: ['hyphen', 'period', 'colon', 'emDash', 'enDash'] },
         },
         ['target'],
       ),
-      oneOf: [{ required: ['target', 'start'] }, { required: ['target', 'format'] }],
+      anyOf: [
+        { required: ['target', 'start'] },
+        { required: ['target', 'format'] },
+        { required: ['target', 'chapterStyle'] },
+        { required: ['target', 'chapterSeparator'] },
+      ],
     },
     output: sectionMutationResultSchemaFor('sections.setPageNumbering'),
     success: sectionMutationSuccessSchema,

packages/document-api/src/index.ts

@@ -1429,6 +1429,7 @@ export type {
   SectionPageBorders,
   SectionPageMargins,
   SectionPageNumbering,
+  SectionPageNumberingChapterSeparator,
   SectionPageNumberingFormat,
   SectionPageSetup,
   SectionRangeDomain,

packages/document-api/src/sections/sections.test.ts

@@ -105,7 +105,57 @@ describe('sections API validation', () => {
       executeSectionsSetPageNumbering(adapter, {
         target: { kind: 'section', sectionId: 'section-0' },
       }),
-    ).toThrow(/requires at least one of start or format/i);
+    ).toThrow(/requires at least one of start, format, chapterStyle, or chapterSeparator/i);
+  });
+
+  it('accepts chapterStyle for setPageNumbering', () => {
+    const setPageNumbering = mock(makeAdapter().setPageNumbering);
+    const adapter = makeAdapter({ setPageNumbering });
+
+    executeSectionsSetPageNumbering(adapter, {
+      target: { kind: 'section', sectionId: 'section-0' },
+      chapterStyle: 1,
+    });
+
+    expect(setPageNumbering).toHaveBeenCalledWith(
+      { target: { kind: 'section', sectionId: 'section-0' }, chapterStyle: 1 },
+      { changeMode: 'direct', dryRun: false, expectedRevision: undefined },
+    );
+  });
+
+  it('accepts valid chapterSeparator for setPageNumbering', () => {
+    const setPageNumbering = mock(makeAdapter().setPageNumbering);
+    const adapter = makeAdapter({ setPageNumbering });
+
+    executeSectionsSetPageNumbering(adapter, {
+      target: { kind: 'section', sectionId: 'section-0' },
+      chapterSeparator: 'enDash',
+    });
+
+    expect(setPageNumbering).toHaveBeenCalledWith(
+      { target: { kind: 'section', sectionId: 'section-0' }, chapterSeparator: 'enDash' },
+      { changeMode: 'direct', dryRun: false, expectedRevision: undefined },
+    );
+  });
+
+  it('rejects invalid chapterSeparator for setPageNumbering', () => {
+    const adapter = makeAdapter();
+    expect(() =>
+      executeSectionsSetPageNumbering(adapter, {
+        target: { kind: 'section', sectionId: 'section-0' },
+        chapterSeparator: 'slash' as any,
+      }),
+    ).toThrow(/chapterSeparator/i);
+  });
+
+  it('rejects chapterStyle less than 1 for setPageNumbering', () => {
+    const adapter = makeAdapter();
+    expect(() =>
+      executeSectionsSetPageNumbering(adapter, {
+        target: { kind: 'section', sectionId: 'section-0' },
+        chapterStyle: 0,
+      }),
+    ).toThrow(/chapterStyle/i);
   });
 
   it('requires at least one field for setPageBorders', () => {

packages/document-api/src/sections/sections.ts

@@ -10,6 +10,7 @@ import type {
   SectionHeaderFooterVariant,
   SectionDirection,
   SectionOrientation,
+  SectionPageNumberingChapterSeparator,
   SectionVerticalAlign,
   SectionsClearHeaderFooterRefInput,
   SectionsClearPageBordersInput,
@@ -41,6 +42,7 @@ export type {
   SectionBreakType,
   SectionHeaderFooterKind,
   SectionHeaderFooterVariant,
+  SectionPageNumberingChapterSeparator,
   SectionsClearHeaderFooterRefInput,
   SectionsClearPageBordersInput,
   SectionsGetInput,
@@ -81,6 +83,13 @@ const PAGE_NUMBER_FORMATS = [
   'upperRoman',
   'numberInDash',
 ] as const;
+const PAGE_NUMBER_CHAPTER_SEPARATORS: readonly SectionPageNumberingChapterSeparator[] = [
+  'hyphen',
+  'period',
+  'colon',
+  'emDash',
+  'enDash',
+] as const;
 const PAGE_BORDER_DISPLAYS = ['allPages', 'firstPage', 'notFirstPage'] as const;
 const PAGE_BORDER_OFFSET_FROM_VALUES = ['page', 'text'] as const;
 const PAGE_BORDER_Z_ORDER_VALUES = ['front', 'back'] as const;
@@ -390,17 +399,25 @@ export function executeSectionsSetPageNumbering(
   options?: MutationOptions,
 ): SectionMutationResult {
   assertSectionTarget(input, 'sections.setPageNumbering');
-  if (!hasAnyDefined(input as unknown as Record<string, unknown>, ['start', 'format'])) {
+  if (
+    !hasAnyDefined(input as unknown as Record<string, unknown>, ['start', 'format', 'chapterStyle', 'chapterSeparator'])
+  ) {
     throw new DocumentApiValidationError(
       'INVALID_INPUT',
-      'sections.setPageNumbering requires at least one of start or format.',
+      'sections.setPageNumbering requires at least one of start, format, chapterStyle, or chapterSeparator.',
     );
   }
 
   if (input.start !== undefined) assertPositiveInteger(input.start, 'sections.setPageNumbering.start');
   if (input.format !== undefined) {
     assertOneOf(input.format, 'sections.setPageNumbering.format', PAGE_NUMBER_FORMATS);
   }
+  if (input.chapterStyle !== undefined) {
+    assertPositiveInteger(input.chapterStyle, 'sections.setPageNumbering.chapterStyle');
+  }
+  if (input.chapterSeparator !== undefined) {
+    assertOneOf(input.chapterSeparator, 'sections.setPageNumbering.chapterSeparator', PAGE_NUMBER_CHAPTER_SEPARATORS);
+  }
 
   return adapter.setPageNumbering(input, normalizeMutationOptions(options));
 }

packages/document-api/src/sections/sections.types.ts

@@ -36,6 +36,8 @@ export type SectionPageNumberingFormat =
   | 'upperRoman'
   | 'numberInDash';
 
+export type SectionPageNumberingChapterSeparator = 'hyphen' | 'period' | 'colon' | 'emDash' | 'enDash';
+
 export interface SectionPageMargins {
   top?: number;
   right?: number;
@@ -73,6 +75,8 @@ export interface SectionLineNumbering {
 export interface SectionPageNumbering {
   start?: number;
   format?: SectionPageNumberingFormat;
+  chapterStyle?: number;
+  chapterSeparator?: SectionPageNumberingChapterSeparator;
 }
 
 export interface SectionHeaderFooterRefs {
@@ -227,6 +231,8 @@ export interface SectionsSetLineNumberingInput extends SectionTargetInput {
 export interface SectionsSetPageNumberingInput extends SectionTargetInput {
   start?: number;
   format?: SectionPageNumberingFormat;
+  chapterStyle?: number;
+  chapterSeparator?: SectionPageNumberingChapterSeparator;
 }
 
 export interface SectionsSetTitlePageInput extends SectionTargetInput {

packages/document-api/src/types/sd-sections.ts

@@ -51,6 +51,8 @@ export interface SDSection {
   pageNumbering?: {
     start?: number;
     format?: 'decimal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman' | 'numberInDash';
+    chapterStyle?: number;
+    chapterSeparator?: 'hyphen' | 'period' | 'colon' | 'emDash' | 'enDash';
   };
   titlePage?: boolean;
   oddEvenHeadersFooters?: boolean;