Feat/template import export by Shubh-Raj · Pull Request #562 · accordproject/template-playground

Shubh-Raj · 2026-01-13T10:25:46Z

(Update description)

Closes #6

This PR adds the ability to export templates to .cta (Contract Template Archive) files and import them back, creating a complete round-trip workflow for saving and restoring template work.

Approach

The archive utility mirrors the CTA file structure used by cicero-core's TemplateSaver / TemplateLoader, using JSZip directly since cicero-core does not currently have a browser-compatible bundle (it depends on Node.js fs module).

Changes

Add jszip dependency for client-side ZIP archive handling
Add src/utils/archive/archive.ts with createArchive, extractArchive, and downloadBlob utilities
Add exportTemplate and importTemplate store actions with error handling
Add Export button (FiDownload icon) and Import button (FiUpload icon) to PlaygroundSidebar
File input restricted to .cta files only
Success/error toast messages on import
importTemplate clears agreementHtml to avoid stale content flash and rethrows for caller error handling
Add unit tests for archive utilities (round-trip, name extraction, error cases)
Add store action tests for exportTemplate and importTemplate
Update PlaygroundSidebar tests for new Export/Import buttons

Flags

Uses JSZip library for client-side archive creation/extraction
CTA format follows Accord Project structure: model/model.cto, text/grammar.tem.md, text/sample.md, package.json
The

Screenshots or Video

Screencast.from.2026-01-13.15-59-37.webm

Related Issues

Issue Export to "Contract Template Archive .CTA" file #6

Author Checklist

Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
Vital features and changes captured in unit and/or integration tests
Commits messages follow AP format
Extend the documentation, if necessary
Merging to main from fork:branchname

netlify · 2026-01-13T10:25:52Z

✅ Deploy Preview for ap-template-playground ready!

Name	Link
🔨 Latest commit	`81af571`
🔍 Latest deploy log	https://app.netlify.com/projects/ap-template-playground/deploys/69af276a727de30008966da4
😎 Deploy Preview	https://deploy-preview-562--ap-template-playground.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Shubh-Raj · 2026-02-11T19:03:46Z

Hi @dselman @mttrbrts @martinhalford — I completed this assigned issue a while back and wanted to follow up for a review whenever you’re available. Thank you!

Shubh-Raj · 2026-02-14T10:07:25Z

Resolved the merge conflicts.

Shubh-Raj · 2026-02-19T16:17:05Z

Following the recent meeting discussion in wg call, I would like to have more insights on the implicit/local state management. In my PR, importTemplate directly updates the store, but I’d love guidance on what to improve in this.

Happy to refactor my implementation accordingly.

Copilot

Pull request overview

This pull request implements a complete export/import workflow for templates using the .cta (Contract Template Archive) format, addressing Issue #6 which requested a way to save templates since there's currently no save functionality in the playground.

Changes:

Added JSZip-based archive utilities for creating and extracting CTA files with model, template, and data
Integrated export/import functionality into the Zustand store with proper error handling
Added Export and Import buttons to the PlaygroundSidebar UI with file picker integration

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/utils/archive/archive.ts	New utility module providing createArchive, extractArchive, and downloadBlob functions for CTA file handling
src/tests/utils/archive.test.ts	Unit tests for archive utilities including round-trip verification
src/store/store.ts	Added exportTemplate and importTemplate actions to store with error handling and state management
src/components/PlaygroundSidebar.tsx	Added Export/Import buttons with file input integration and handler functions
src/tests/components/PlaygroundSidebar.test.tsx	Updated tests to verify Export/Import buttons render correctly and mocked store functions
package.json	Added jszip dependency (v3.10.1) for ZIP file operations
README.md	Updated feature list to mention export/import capability

Copilot · 2026-02-24T14:32:39Z

src/store/store.ts

+      exportTemplate: async () => {
+        const { sampleName, modelCto, templateMarkdown, data } = get();
+        try {
+          const blob = await createArchive(sampleName, modelCto, templateMarkdown, data);
+          const filename = `${sampleName.toLowerCase().replace(/\s+/g, '-')}.cta`;
+          downloadBlob(blob, filename);
+        } catch (error) {
+          console.error('Export failed:', error);
+          set(() => ({
+            error: 'Failed to export template: ' + (error instanceof Error ? error.message : 'Unknown error'),
+            isProblemPanelVisible: true,
+          }));
+        }
+      },
+      importTemplate: async (file: File) => {
+        try {
+          const { name, model, template, data } = await extractArchive(file);
+          set(() => ({
+            sampleName: name,
+            templateMarkdown: template,
+            editorValue: template,
+            modelCto: model,
+            editorModelCto: model,
+            data: data,
+            editorAgreementData: data,
+            error: undefined,
+          }));
+          await get().rebuild();
+        } catch (error) {
+          console.error('Import failed:', error);
+          set(() => ({
+            error: 'Failed to import template: ' + (error instanceof Error ? error.message : 'Unknown error'),
+            isProblemPanelVisible: true,
+          }));
+        }
+      },


The new exportTemplate and importTemplate store actions lack unit test coverage. Following the pattern established in src/tests/store/generateSharebleLink.test.tsx, these critical actions should have tests that verify:

exportTemplate creates a proper archive and triggers download

importTemplate correctly updates store state with extracted data

Error handling works correctly for both actions (e.g., invalid files, missing fields)

This is important because these actions handle user data and file operations, which are prone to edge cases and errors.

Copilot · 2026-02-24T14:32:39Z

src/utils/archive/archive.ts

+  if (packageFile) {
+    try {
+      const pkg = JSON.parse(await packageFile.async('string'));
+      name = pkg.name || pkg.description || name;


The name extraction logic prioritizes pkg.name over pkg.description, but according to the CTA creation in createArchive, the name field is a kebab-case version (e.g., "test-template") while the description field contains the human-readable name (e.g., "Template: Test Template"). This mismatch means imported templates will show kebab-case names instead of the original user-friendly names. Consider extracting the name from the description field first (after removing the "Template: " prefix), then falling back to the name field.

Suggested change

name = pkg.name || pkg.description || name;

const description = typeof pkg.description === 'string' ? pkg.description.trim() : '';

const pkgName = typeof pkg.name === 'string' ? pkg.name.trim() : '';

if (description) {

const prefix = 'Template: ';

name = description.startsWith(prefix)

? description.slice(prefix.length).trim() || name

: description;

} else if (pkgName) {

name = pkgName;

}

Copilot · 2026-02-24T14:32:40Z

src/components/PlaygroundSidebar.tsx

+      <input
+        ref={fileInputRef}
+        type="file"
+        accept=".cta,.zip"


The file input accepts both .cta and .zip extensions, but the feature is specifically for CTA (Contract Template Archive) files. While CTA files are ZIP files internally, accepting generic .zip files could be confusing to users who might try to import any ZIP file. Consider accepting only .cta extension for clarity, or add validation in extractArchive to verify it's a valid CTA structure before processing.

Suggested change

accept=".cta,.zip"

accept=".cta"

Copilot · 2026-02-24T14:32:40Z

src/components/PlaygroundSidebar.tsx

+      onClick: () => void exportTemplate()
+    },
+    { 
+      title: "Import", 
+      icon: FiUpload,
+      onClick: handleImportClick


The Export and Import buttons don't provide user feedback on success. Following the pattern used in handleShare (which shows message.success('Link copied to clipboard!')), consider adding success feedback handlers in PlaygroundSidebar. For example:

Export: "Template exported successfully!"

Import: "Template imported successfully!"

This helps users confirm their actions completed as expected, especially since export happens silently (browser download) and import makes significant state changes.

Suggested change

onClick: () => void exportTemplate()

},

{

title: "Import",

icon: FiUpload,

onClick: handleImportClick

onClick: () => {

void exportTemplate();

message.success("Template exported successfully!");

}

},

{

title: "Import",

icon: FiUpload,

onClick: () => {

void handleImportClick();

message.success("Template imported successfully!");

}

Copilot · 2026-02-24T14:32:41Z

src/utils/archive/archive.ts

+    accordproject: {
+      template: 'clause',
+      runtime: 'es6'


The generated package.json lacks several fields that are typically present in Accord Project CTA archives, such as author, license, and potentially cicero versioning information. While the current minimal structure may work for basic import/export, consider adding these standard fields to ensure better compatibility with other Accord Project tools that may consume these archives. Reference the Accord Project CTA specification for complete field requirements.

Suggested change

accordproject: {

template: 'clause',

runtime: 'es6'

author: 'Template Playground User',

license: 'Apache-2.0',

accordproject: {

template: 'clause',

runtime: 'es6',

cicero: {

version: '*'

}

Copilot · 2026-02-24T14:32:41Z

src/components/PlaygroundSidebar.tsx

+      <input
+        ref={fileInputRef}
+        type="file"
+        accept=".cta,.zip"
+        onChange={(e) => void handleFileChange(e)}
+        style={{ display: 'none' }}
+      />


Consider adding end-to-end tests for the export/import workflow. Following the pattern in e2e/template-workflow.spec.ts, tests should verify:

Export button triggers a download

Import button opens file picker and successfully loads a template

Round-trip workflow: export a template, then import it back and verify data preservation

While the unit tests cover the utilities well, E2E tests would ensure the complete user workflow functions correctly, especially the file picker integration and browser download behavior.

Shashanth-V · 2026-02-24T16:17:19Z

Hi @Shubh-Raj ,

I’ve been studying this PR and the Template Playground architecture as part of my initial contributions. I noticed the Copilot suggestion about missing unit test coverage for exportTemplate and importTemplate.

I’d be happy to help by adding test coverage for:

Successful export archive generation
Import correctly updating store state
Error handling for invalid CTA files

Please let me know if this would be helpful and if I can contribute to this PR.

Thanks!

Shubh-Raj · 2026-02-25T08:03:25Z

Hi @Shubh-Raj ,

I’ve been studying this PR and the Template Playground architecture as part of my initial contributions. I noticed the Copilot suggestion about missing unit test coverage for exportTemplate and importTemplate.

I’d be happy to help by adding test coverage for:

Successful export archive generation

Import correctly updating store state

Error handling for invalid CTA files

Please let me know if this would be helpful and if I can contribute to this PR.

Thanks!

Thanks for your suggestion, but I am currently working on this.

mttrbrts

Please use the existing API for creating and loading archives. You shouldn't need to manage ZIP files directly.

Here's an example from the CLI tool
https://github.com/accordproject/template-archive/blob/main/packages/cicero-cli/lib/commands.js#L110

Shubh-Raj · 2026-03-09T18:14:52Z

Please use the existing API for creating and loading archives. You shouldn't need to manage ZIP files directly.

Here's an example from the CLI tool https://github.com/accordproject/template-archive/blob/main/packages/cicero-cli/lib/commands.js#L110

Hi @mttrbrts,
I traced the code path from the CLI example you linked: commands.js to Template.toArchive() to TemplateSaver.toArchive() and similarly Template.fromArchive() to TemplateLoader.fromArchive().

The actual archive packaging in both methods uses JSZip internally to create/extract the CTA structure (
package.json, model/*.cto, text/grammar.tem.md, text/sample.md).

Since the playground is a browser-based app and cicero-core doesn't have a browser-compatible bundle right now (it depends on Node.js fs module), I'm mirroring the same TemplateSaver/TemplateLoader logic using JSZip directly. The archive output follows the exact same CTA file structure.

I'm also addressing the Copilot review suggestions ie. fixing name extraction, restricting import to .cta only, adding success feedback, and adding tests. Will push the updates shortly.

Add jszip dependency and archive utility module that mirrors the CTA file structure used by cicero-core's TemplateSaver/TemplateLoader: - package.json with accordproject metadata - model/model.cto - text/grammar.tem.md - text/sample.md Signed-off-by: Shubh-Raj <shubhraj625@gmail.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 5 comments.

src/utils/archive/archive.ts

src/components/PlaygroundSidebar.tsx

src/store/store.ts

src/tests/utils/archive.test.ts

Add exportTemplate and importTemplate store actions that use the archive utility. Add Export/Import buttons to PlaygroundSidebar with file picker restricted to .cta files. Shows success toast on import and error toast on failure with try/catch/finally for proper cleanup. importTemplate rethrows errors for caller error handling and clears agreementHtml to avoid stale content flash. Signed-off-by: Shubh-Raj <shubhraj625@gmail.com>

Add unit tests for archive utilities and store actions: - createArchive produces valid ZIP blob - extractArchive reads back model, template, and data - extractArchive throws on missing model or grammar files - Name extraction from description field - Full round-trip data preservation - exportTemplate creates archive and triggers download - importTemplate updates store state with extracted data - Error handling for both store actions Signed-off-by: Shubh-Raj <shubhraj625@gmail.com>

Shubh-Raj requested a review from a team as a code owner January 13, 2026 10:25

Shubh-Raj mentioned this pull request Jan 23, 2026

Export to "Contract Template Archive .CTA" file #6

Open

Copilot AI review requested due to automatic review settings February 24, 2026 14:22

Copilot started reviewing on behalf of Shubh-Raj February 24, 2026 14:22 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

mttrbrts requested changes Feb 25, 2026

View reviewed changes

This was referenced Feb 25, 2026

feat: add functional Settings panel with dark mode and autosave #660

Closed

feat: persist editor state on page refresh #619

Closed

feat: Add "Save Locally" button to persist editor state across page reloads #765

Closed

Copilot AI review requested due to automatic review settings March 9, 2026 19:40

Shubh-Raj force-pushed the feat/template-import-export branch from 1d6051a to df12cfe Compare March 9, 2026 19:40

Copilot started reviewing on behalf of Shubh-Raj March 9, 2026 19:40 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

src/utils/archive/archive.ts Show resolved Hide resolved

src/components/PlaygroundSidebar.tsx Show resolved Hide resolved

src/components/PlaygroundSidebar.tsx Show resolved Hide resolved

src/store/store.ts Show resolved Hide resolved

src/tests/utils/archive.test.ts Show resolved Hide resolved

Shubh-Raj added 2 commits March 10, 2026 01:27

Shubh-Raj force-pushed the feat/template-import-export branch from df12cfe to 81af571 Compare March 9, 2026 20:02

Shubh-Raj requested a review from mttrbrts March 9, 2026 20:10

-      name = pkg.name || pkg.description || name;
+      const description = typeof pkg.description === 'string' ? pkg.description.trim() : '';
+      const pkgName = typeof pkg.name === 'string' ? pkg.name.trim() : '';
+      if (description) {
+        const prefix = 'Template: ';
+        name = description.startsWith(prefix)
+          ? description.slice(prefix.length).trim() || name
+          : description;
+      } else if (pkgName) {
+        name = pkgName;
+      }

Uh oh!

Conversation

Shubh-Raj commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approach

Changes

Flags

Screenshots or Video

Related Issues

Author Checklist

Uh oh!

netlify bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ap-template-playground ready!

Uh oh!

Shubh-Raj commented Feb 11, 2026

Uh oh!

Shubh-Raj commented Feb 14, 2026

Uh oh!

Shubh-Raj commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Shashanth-V commented Feb 24, 2026

Uh oh!

Shubh-Raj commented Feb 25, 2026

Uh oh!

mttrbrts left a comment

Choose a reason for hiding this comment

Uh oh!

Shubh-Raj commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Shubh-Raj commented Jan 13, 2026 •

edited

Loading

netlify bot commented Jan 13, 2026 •

edited

Loading