Merge remote-tracking branch 'upstream/main' into feat/tiff-image-support

Author: gpardhivvarma

.github/workflows/ci-examples.yml

@@ -12,15 +12,31 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        example: [react, vue, vanilla, cdn, angular]
+        example: [react, vue, vanilla, cdn, angular, nuxt, laravel]
     steps:
       - uses: actions/checkout@v6
 
+      - name: Setup PHP
+        if: matrix.example == 'laravel'
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
           node-version: '20'
 
+      - name: Install Composer dependencies
+        if: matrix.example == 'laravel'
+        working-directory: examples/getting-started/laravel
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Prepare Laravel environment
+        if: matrix.example == 'laravel'
+        working-directory: examples/getting-started/laravel
+        run: cp .env.example .env && php artisan key:generate
+
       - name: Install example dependencies
         if: matrix.example != 'cdn'
         working-directory: examples/getting-started/${{ matrix.example }}

.github/workflows/pr-labels.yml

@@ -90,7 +90,9 @@ jobs:
         if: >-
           github.event.action == 'opened' &&
           github.event.pull_request.author_association != 'MEMBER' &&
-          github.event.pull_request.author_association != 'OWNER'
+          github.event.pull_request.author_association != 'OWNER' &&
+          github.event.pull_request.author_association != 'COLLABORATOR' &&
+          github.event.pull_request.user.type != 'Bot'
         uses: actions/github-script@v7
         with:
           script: |

README.md

@@ -144,6 +144,8 @@ Special thanks to these community members who have contributed code to SuperDoc:
 <a href="https://github.com/asumaran"><img src="https://github.com/asumaran.png" width="50" height="50" alt="asumaran" title="Alfredo Sumaran" /></a>
 <a href="https://github.com/J-Michalek"><img src="https://github.com/J-Michalek.png" width="50" height="50" alt="J-Michalek" title="Jakub Michálek" /></a>
 <a href="https://github.com/gm1357"><img src="https://github.com/gm1357.png" width="50" height="50" alt="gm1357" title="Gabriel Machado" /></a>
+<a href="https://github.com/roncallyt"><img src="https://github.com/roncallyt.png" width="50" height="50" alt="roncallyt" title="Thomerson Roncally" /></a>
+<a href="https://github.com/gpardhivvarma"><img src="https://github.com/gpardhivvarma.png" width="50" height="50" alt="gpardhivvarma" title="G Pardhiv Varma" /></a>
 
 Want to see your avatar here? Check the [Contributing Guide](CONTRIBUTING.md) to get started.
 

apps/cli/scripts/export-sdk-contract.ts

@@ -89,6 +89,7 @@ const INTENT_NAMES = {
   'doc.sections.setLinkToPrevious': 'set_section_link_to_previous',
   'doc.sections.setPageBorders': 'set_section_page_borders',
   'doc.sections.clearPageBorders': 'clear_section_page_borders',
+  'doc.create.tableOfContents': 'create_table_of_contents',
   'doc.lists.list': 'list_lists',
   'doc.lists.get': 'get_list',
   'doc.lists.insert': 'insert_list',
@@ -105,6 +106,11 @@ const INTENT_NAMES = {
   'doc.trackChanges.list': 'list_tracked_changes',
   'doc.trackChanges.get': 'get_tracked_change',
   'doc.trackChanges.decide': 'decide_tracked_change',
+  'doc.toc.list': 'list_table_of_contents',
+  'doc.toc.get': 'get_table_of_contents',
+  'doc.toc.configure': 'configure_table_of_contents',
+  'doc.toc.update': 'update_table_of_contents',
+  'doc.toc.remove': 'remove_table_of_contents',
   'doc.query.match': 'query_match',
   'doc.mutations.preview': 'preview_mutations',
   'doc.mutations.apply': 'apply_mutations',

apps/cli/src/__tests__/conformance/harness.ts

@@ -2,7 +2,7 @@ import { copyFile, mkdtemp, mkdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { run } from '../../index';
-import { resolveListDocFixture, resolveSourceDocFixture } from '../fixtures';
+import { resolveListDocFixture, resolveSourceDocFixture, resolveTocDocFixture } from '../fixtures';
 
 type RunResult = {
   code: number;
@@ -48,6 +48,12 @@ export type ListItemAddress = {
   nodeId: string;
 };
 
+export type TocAddress = {
+  kind: 'block';
+  nodeType: 'tableOfContents';
+  nodeId: string;
+};
+
 function parseEnvelope(raw: RunResult): CommandEnvelope {
   const source = raw.stdout.trim() || raw.stderr.trim();
   if (!source) {
@@ -119,6 +125,36 @@ export class ConformanceHarness {
     return filePath;
   }
 
+  async copyTocFixtureDoc(label: string, stateDir: string): Promise<string> {
+    const filePath = path.join(this.docsDir, `${this.nextId()}-${label}.docx`);
+
+    try {
+      await copyFile(await resolveTocDocFixture(), filePath);
+      const probe = await this.runCli(['toc', 'list', filePath, '--limit', '1'], stateDir);
+      if (probe.result.code === 0) {
+        return filePath;
+      }
+    } catch {
+      // Fall back to creating a TOC fixture from the generic source doc.
+    }
+
+    const sourceDoc = await this.copyFixtureDoc(`${label}-seed`);
+    const seededPath = path.join(this.docsDir, `${this.nextId()}-${label}-seeded.docx`);
+    const { result, envelope } = await this.runCli(
+      ['create', 'table-of-contents', sourceDoc, '--out', seededPath],
+      stateDir,
+    );
+
+    if (result.code !== 0 || envelope.ok !== true) {
+      const details = envelope.ok
+        ? 'unexpected non-success envelope'
+        : `${envelope.error.code}: ${envelope.error.message}`;
+      throw new Error(`Unable to seed TOC fixture for ${label}: ${details}`);
+    }
+
+    return seededPath;
+  }
+
   createOutputPath(label: string): string {
     return path.join(this.docsDir, `${this.nextId()}-${label}.docx`);
   }
@@ -236,6 +272,27 @@ export class ConformanceHarness {
     return address;
   }
 
+  async firstTocAddress(docPath: string, stateDir: string): Promise<TocAddress> {
+    const { result, envelope } = await this.runCli(['toc', 'list', docPath, '--limit', '1'], stateDir);
+    if (result.code !== 0) {
+      throw new Error(`Unable to resolve first table of contents for ${docPath}`);
+    }
+
+    assertSuccessEnvelope(envelope);
+    const data = envelope.data as {
+      result?: {
+        items?: Array<{
+          address?: TocAddress;
+        }>;
+      };
+    };
+    const address = data.result?.items?.[0]?.address;
+    if (!address) {
+      throw new Error(`No table of contents address found in ${docPath}`);
+    }
+    return address;
+  }
+
   async addCommentFixture(
     stateDir: string,
     label: string,

apps/cli/src/__tests__/conformance/scenarios.ts

@@ -334,6 +334,43 @@ function tableScopedMutationScenario(
   };
 }
 
+function tocMutationScenario(
+  op: string,
+  extraArgs: string[],
+): (harness: ConformanceHarness) => Promise<ScenarioInvocation> {
+  return async (harness) => {
+    const label = `toc-${op.replace(/\./g, '-')}`;
+    const stateDir = await harness.createStateDir(`${label}-success`);
+    const docPath = await harness.copyTocFixtureDoc(`${label}-source`, stateDir);
+    const tocTarget = await harness.firstTocAddress(docPath, stateDir);
+    return {
+      stateDir,
+      args: [
+        ...commandTokens(`doc.${op}` as CliOperationId),
+        docPath,
+        '--target-json',
+        JSON.stringify(tocTarget),
+        ...extraArgs,
+        '--out',
+        harness.createOutputPath(`${label}-out`),
+      ],
+    };
+  };
+}
+
+function tocReadWithTargetScenario(op: string): (harness: ConformanceHarness) => Promise<ScenarioInvocation> {
+  return async (harness) => {
+    const label = `toc-${op.replace(/\./g, '-')}`;
+    const stateDir = await harness.createStateDir(`${label}-success`);
+    const docPath = await harness.copyTocFixtureDoc(`${label}-source`, stateDir);
+    const tocTarget = await harness.firstTocAddress(docPath, stateDir);
+    return {
+      stateDir,
+      args: [...commandTokens(`doc.${op}` as CliOperationId), docPath, '--target-json', JSON.stringify(tocTarget)],
+    };
+  };
+}
+
 export const SUCCESS_SCENARIOS = {
   'doc.open': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-open-success');
@@ -582,6 +619,23 @@ export const SUCCESS_SCENARIOS = {
       ],
     };
   },
+  'doc.create.tableOfContents': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-create-toc-success');
+    const docPath = await harness.copyFixtureDoc('doc-create-toc');
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.create.tableOfContents'),
+        docPath,
+        '--at-json',
+        JSON.stringify({ kind: 'documentStart' }),
+        '--config-json',
+        JSON.stringify({ hyperlinks: true, outlineLevels: { from: 1, to: 3 } }),
+        '--out',
+        harness.createOutputPath('doc-create-toc-output'),
+      ],
+    };
+  },
   'doc.create.paragraph': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-create-paragraph-success');
     const docPath = await harness.copyFixtureDoc('doc-create-paragraph');
@@ -1160,6 +1214,18 @@ export const SUCCESS_SCENARIOS = {
       ],
     };
   },
+  'doc.toc.list': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-toc-list-success');
+    const docPath = await harness.copyTocFixtureDoc('doc-toc-list', stateDir);
+    return {
+      stateDir,
+      args: [...commandTokens('doc.toc.list'), docPath, '--limit', '1'],
+    };
+  },
+  'doc.toc.get': tocReadWithTargetScenario('toc.get'),
+  'doc.toc.configure': tocMutationScenario('toc.configure', ['--patch-json', JSON.stringify({ hyperlinks: false })]),
+  'doc.toc.update': tocMutationScenario('toc.update', []),
+  'doc.toc.remove': tocMutationScenario('toc.remove', []),
   'doc.session.list': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-session-list-success');
     await harness.openSessionFixture(stateDir, 'doc-session-list', 'session-list-success');

apps/cli/src/__tests__/fixtures.ts

@@ -15,8 +15,15 @@ const LIST_SOURCE_DOC_CANDIDATES = [
   path.join(REPO_ROOT, 'e2e-tests/test-data/basic-documents/lists-complex-items.docx'),
 ];
 
+const TOC_SOURCE_DOC_CANDIDATES = [
+  path.join(REPO_ROOT, 'test-corpus/basic/table-of-contents.docx'),
+  path.join(REPO_ROOT, 'test-corpus/basic/table-of-contents-sdt.docx'),
+  path.join(REPO_ROOT, 'test-corpus/layout/toc-with-heading2.docx'),
+];
+
 let resolvedSourceDoc: string | null = null;
 let resolvedListSourceDoc: string | null = null;
+let resolvedTocSourceDoc: string | null = null;
 
 async function resolveFixture(candidates: string[], fixtureLabel: string): Promise<string> {
   for (const candidate of candidates) {
@@ -42,3 +49,9 @@ export async function resolveListDocFixture(): Promise<string> {
   resolvedListSourceDoc = await resolveFixture(LIST_SOURCE_DOC_CANDIDATES, 'list');
   return resolvedListSourceDoc;
 }
+
+export async function resolveTocDocFixture(): Promise<string> {
+  if (resolvedTocSourceDoc != null) return resolvedTocSourceDoc;
+  resolvedTocSourceDoc = await resolveFixture(TOC_SOURCE_DOC_CANDIDATES, 'table-of-contents');
+  return resolvedTocSourceDoc;
+}

apps/cli/src/cli/operation-hints.ts

@@ -57,6 +57,7 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   'styles.apply': 'applied stylesheet defaults',
   'create.paragraph': 'created paragraph',
   'create.heading': 'created heading',
+  'create.tableOfContents': 'created table of contents',
   'lists.list': 'listed items',
   'lists.get': 'resolved list item',
   'lists.insert': 'inserted list item',
@@ -73,6 +74,11 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   'trackChanges.list': 'listed tracked changes',
   'trackChanges.get': 'resolved tracked change',
   'trackChanges.decide': 'reviewed tracked change',
+  'toc.list': 'listed tables of contents',
+  'toc.get': 'resolved table of contents',
+  'toc.configure': 'configured table of contents',
+  'toc.update': 'updated table of contents',
+  'toc.remove': 'removed table of contents',
   'query.match': 'matched selectors',
   'mutations.preview': 'previewed mutations',
   'mutations.apply': 'applied mutations',
@@ -164,6 +170,7 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   'styles.apply': 'receipt',
   'create.paragraph': 'createResult',
   'create.heading': 'createResult',
+  'create.tableOfContents': 'createResult',
   'lists.list': 'listResult',
   'lists.get': 'listItemInfo',
   'lists.insert': 'listsMutationResult',
@@ -180,6 +187,11 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   'trackChanges.list': 'trackChangeList',
   'trackChanges.get': 'trackChangeInfo',
   'trackChanges.decide': 'trackChangeMutationReceipt',
+  'toc.list': 'plain',
+  'toc.get': 'plain',
+  'toc.configure': 'plain',
+  'toc.update': 'plain',
+  'toc.remove': 'plain',
   'query.match': 'plain',
   'mutations.preview': 'plain',
   'mutations.apply': 'plain',
@@ -255,6 +267,7 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   'styles.apply': 'receipt',
   'create.paragraph': 'result',
   'create.heading': 'result',
+  'create.tableOfContents': 'result',
   'lists.list': 'result',
   'lists.get': 'item',
   'lists.insert': 'result',
@@ -271,6 +284,11 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   'trackChanges.list': 'result',
   'trackChanges.get': 'change',
   'trackChanges.decide': 'receipt',
+  'toc.list': 'result',
+  'toc.get': 'result',
+  'toc.configure': 'result',
+  'toc.update': 'result',
+  'toc.remove': 'result',
   'query.match': 'result',
   'mutations.preview': 'result',
   'mutations.apply': 'result',
@@ -352,6 +370,7 @@ export type OperationFamily =
   | 'comments'
   | 'lists'
   | 'tables'
+  | 'toc'
   | 'textMutation'
   | 'create'
   | 'blocks'
@@ -374,6 +393,7 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   'styles.apply': 'general',
   'create.paragraph': 'create',
   'create.heading': 'create',
+  'create.tableOfContents': 'create',
   'lists.list': 'lists',
   'lists.get': 'lists',
   'lists.insert': 'lists',
@@ -390,6 +410,11 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   'trackChanges.list': 'trackChanges',
   'trackChanges.get': 'trackChanges',
   'trackChanges.decide': 'trackChanges',
+  'toc.list': 'query',
+  'toc.get': 'query',
+  'toc.configure': 'toc',
+  'toc.update': 'toc',
+  'toc.remove': 'toc',
   'query.match': 'query',
   'mutations.preview': 'general',
   'mutations.apply': 'general',