refactor(demo): single-use clause library + brand-blue fields

Make the clause library a single-use inclusion checklist instead of a duplicate
stamp tool. A clause is either "In contract" or available to "Add clause": a
clause already placed can't be inserted again - clicking its card reveals the
existing section, while an available card adds it (click or drag) and then flips
to "In contract". Drops the "used N times" surface. This teaches the right model:
fields are reusable variables, clauses are governed sections included once.

- Add a library-only "Return of Materials" clause carrying a nested Receiving
  party slot, so insert-with-nested-fields stays demonstrable now that the seeded
  Permitted Use is "In contract" and no longer insertable.
- Recolor fields and clauses to the SuperDoc brand blue (--sd-color-blue-500/600,
  per brand.md) instead of amber. They render as tinted/outlined pills, so they
  stay distinct from the solid-blue primary buttons.
- Update tests (single-use status badges, add-once-no-duplicate, nested-field on
  add), the README, and code comments to the single-use + blue model.

Author: caio-pizzol

demos/__tests__/contract-templates-smart-tags.spec.ts

@@ -132,7 +132,7 @@ test('a smart-field pill does not shift its box on hover or click (no jitter)',
   }
 });
 
-test('a block clause keeps its amber left rail and box across hover/select (no jitter)', async ({ page }) => {
+test('a block clause keeps its left rail and box across hover/select (no jitter)', async ({ page }) => {
   test.skip(process.env.DEMO !== 'contract-templates', 'contract-templates demo only');
 
   await page.route('**/ingest.superdoc.dev/**', (r) =>
@@ -148,7 +148,7 @@ test('a block clause keeps its amber left rail and box across hover/select (no j
   await page.waitForSelector(sel);
 
   // Block SDTs strip border + fill on .sdt-group-hover / .ProseMirror-selectednode;
-  // the demo overrides them. Guard the 4px amber left rail and box stay constant.
+  // the demo overrides them. Guard the 4px left rail and box stay constant.
   const box = () =>
     page.evaluate((s) => {
       const el = document.querySelector(s) as HTMLElement;
@@ -289,7 +289,7 @@ test('a field value broadcasts to every occurrence, including one nested in a lo
     .toBe(2);
 });
 
-test('clicking a clause card inserts a locked block clause at the cursor', async ({ page }) => {
+test('the clause library is single-use: seeded clauses are In contract, others Add clause', async ({ page }) => {
   test.skip(process.env.DEMO !== 'contract-templates', 'contract-templates demo only');
 
   await page.route('**/ingest.superdoc.dev/**', (r) =>
@@ -303,37 +303,60 @@ test('clicking a clause card inserts a locked block clause at the cursor', async
   );
   await page.waitForSelector('.clause[data-clause-id]');
 
-  // Caret in the (unlocked) title so the clause inserts at a clean block boundary.
+  // A seeded clause is already in the contract; a library-only one is available.
+  await expect(page.locator('.clause[data-clause-id="permittedUse"] .clause-status')).toHaveText('In contract');
+  await expect(page.locator('.clause[data-clause-id="permittedUse"]')).toHaveClass(/is-present/);
+  await expect(page.locator('.clause[data-clause-id="indemnification"] .clause-status')).toHaveText('Add clause');
+  await expect(page.locator('.clause[data-clause-id="indemnification"]')).toHaveClass(/is-available/);
+});
+
+test('clicking an available clause adds it once (single-use, then In contract)', async ({ page }) => {
+  test.skip(process.env.DEMO !== 'contract-templates', 'contract-templates demo only');
+
+  await page.route('**/ingest.superdoc.dev/**', (r) =>
+    r.fulfill({ status: 204, contentType: 'application/json', body: '{}' }),
+  );
+  await page.goto('/');
+  await page.waitForFunction(
+    () => (window as any).__demo?.state?.ui?.contentControls?.getSnapshot()?.items?.length > 0,
+    null,
+    { timeout: 30_000 },
+  );
+  await page.waitForSelector('.clause[data-clause-id="indemnification"]');
+
+  // Caret in the (unlocked) title so the clause adds at a clean block boundary.
   await page.evaluate(() => {
     (window as any).__demo.superdoc.activeEditor.commands?.setTextSelection?.({ from: 6, to: 6 });
   });
 
-  const sectionId = await page.getAttribute('.clause[data-clause-id]', 'data-clause-id');
-  expect(sectionId).toBeTruthy();
-
-  // Count controls for this clause + confirm they're all locked.
-  const clauseInfo = () =>
-    page.evaluate((sid) => {
+  const indemnificationInfo = () =>
+    page.evaluate(() => {
       const doc = (window as any).__demo.doc();
       const items = doc.contentControls.list({}).items.filter((c: any) => {
         try {
-          return JSON.parse(c.properties?.tag ?? '{}').sectionId === sid;
+          return JSON.parse(c.properties?.tag ?? '{}').sectionId === 'indemnification';
         } catch {
           return false;
         }
       });
       return { count: items.length, allLocked: items.every((c: any) => c.lockMode === 'contentLocked') };
-    }, sectionId);
+    });
+
+  expect((await indemnificationInfo()).count).toBe(0);
+  await page.click('.clause[data-clause-id="indemnification"]');
 
-  const before = await clauseInfo();
-  await page.click(`.clause[data-clause-id="${sectionId}"]`);
+  // It's added once, locked, and the card flips to In contract.
+  await expect.poll(async () => (await indemnificationInfo()).count, { timeout: 6_000 }).toBe(1);
+  expect((await indemnificationInfo()).allLocked).toBe(true);
+  await expect(page.locator('.clause[data-clause-id="indemnification"] .clause-status')).toHaveText('In contract');
 
-  // A new block clause for this section appears, and every occurrence is locked.
-  await expect.poll(async () => (await clauseInfo()).count, { timeout: 6_000 }).toBe(before.count + 1);
-  expect((await clauseInfo()).allLocked).toBe(true);
+  // Clicking again does NOT duplicate it (single-use; reveals the existing one).
+  await page.click('.clause[data-clause-id="indemnification"]');
+  await page.waitForTimeout(500);
+  expect((await indemnificationInfo()).count).toBe(1);
 });
 
-test('inserting Permitted Use nests real smart fields that fill from the form', async ({ page }) => {
+test('adding the Return of Materials clause nests a real smart field that fills from the form', async ({ page }) => {
   test.skip(process.env.DEMO !== 'contract-templates', 'contract-templates demo only');
 
   await page.route('**/ingest.superdoc.dev/**', (r) =>
@@ -345,15 +368,14 @@ test('inserting Permitted Use nests real smart fields that fill from the form',
     null,
     { timeout: 30_000 },
   );
-  await page.waitForSelector('.clause[data-clause-id="permittedUse"]');
+  await page.waitForSelector('.clause[data-clause-id="returnOfMaterials"]');
 
-  // Caret in the (unlocked) title so the clause inserts at a clean block boundary.
+  // Caret in the (unlocked) title so the clause adds at a clean block boundary.
   await page.evaluate(() => {
     (window as any).__demo.superdoc.activeEditor.commands?.setTextSelection?.({ from: 6, to: 6 });
   });
 
-  // Count Receiving party smart fields in the document (an inline structuredContent
-  // whose tag carries that key) - the Permitted Use clause carries one as a slot.
+  // Receiving party smart fields in the document (Return of Materials carries one).
   const receivingPartyControls = () =>
     page.evaluate(() => {
       const doc = (window as any).__demo.doc();
@@ -362,13 +384,13 @@ test('inserting Permitted Use nests real smart fields that fill from the form',
     });
 
   const before = (await receivingPartyControls()).length; // 2 seeded
-  await page.click('.clause[data-clause-id="permittedUse"]');
+  await page.click('.clause[data-clause-id="returnOfMaterials"]');
 
-  // Inserting the clause adds a real nested Receiving party SDT (not plain text).
+  // Adding the clause creates a real nested Receiving party SDT (not plain text).
   await expect.poll(async () => (await receivingPartyControls()).length, { timeout: 6_000 }).toBe(before + 1);
 
   // Filling Receiving party in the Values form reaches every occurrence,
-  // including the one just nested inside the inserted clause.
+  // including the one just nested inside the added clause.
   await page.click('.tab[data-tab="values"]');
   await page.fill('input[data-field="receivingParty"]', 'Beacon Bio');
   await expect

demos/contract-templates/README.md

@@ -12,8 +12,8 @@ The starting document is `public/nda-template.docx`: inline plain-text fields an
 
 **Template tab, the building-block library.** Two catalogs, fields and clauses, each styled to match what it inserts:
 
-- Smart-field chips wear the same amber token look as the in-document field (CSS on `.superdoc-structured-content-inline[data-sdt-tag*='smartField']`). Drag a chip onto the document, or click to insert it at the cursor. An unfilled field shows its field-name token (e.g. `DISCLOSING_PARTY`) as a stand-in placeholder. That token is literal text content, not a native SDT placeholder.
-- Clause cards wear the same amber block look as the in-document clause and carry metadata: category, jurisdiction, version, and how many times the clause is placed ("Used 2 times"). The catalog includes clauses that aren't in the document yet. Drag a card onto the document, or click to insert it at the cursor.
+- Smart-field chips wear the same blue token look as the in-document field (CSS on `.superdoc-structured-content-inline[data-sdt-tag*='smartField']`). Drag a chip onto the document, or click to insert it at the cursor. An unfilled field shows its field-name token (e.g. `DISCLOSING_PARTY`) as a stand-in placeholder. That token is literal text content, not a native SDT placeholder.
+- Clause cards wear the same blue block look as the in-document clause and carry metadata (category, jurisdiction, version) and a status. A clause is single-use, like an inclusion checklist: a card already in the contract reads **In contract** and clicking it reveals the existing clause; an available card reads **Add clause** and drags or clicks in. The catalog includes clauses that aren't in the document yet (e.g. Indemnification, Return of Materials).
 
 Inserts resolve the drop point with `ui.viewport.positionAt({ x, y })` and create the control with `editor.doc.create.contentControl({ kind, at, content, tag, lockMode })`. A field inserts inline at the exact caret; a clause snaps to a block boundary so it lands as a clean section instead of splitting a paragraph. Clicking a control in the document highlights its chip or card (`content-control:click`).
 

demos/contract-templates/src/main.ts

@@ -18,11 +18,13 @@
  *   - Every control is `contentLocked`, so it can't be edited by typing in the
  *     document. This is a locked template surface; the custom UI drives changes.
  *   - Template tab = the building-block library. Two catalogs: smart-field chips
- *     and clause cards (each with category / jurisdiction / version and a "used
- *     N times" count). Drag or click a chip to insert an inline field, or a card
- *     to insert a block clause. An unfilled field shows its field-name token
- *     (e.g. DISCLOSING_PARTY) as a stand-in placeholder - literal text content,
- *     not a native SDT placeholder.
+ *     (reusable variables) and clause cards (governed sections, single-use). A
+ *     chip drags/clicks in as an inline field. A clause card shows category /
+ *     jurisdiction / version and a status: "Add clause" when available (drag or
+ *     click to add) or "In contract" once placed (click reveals the existing one
+ *     - a clause appears once, like an inclusion checklist). An unfilled field
+ *     shows its field-name token (e.g. DISCLOSING_PARTY) as a stand-in
+ *     placeholder - literal text content, not a native SDT placeholder.
  *   - A clause is assembled from structured `parts`: prose plus `{ field }`
  *     slots. Inserting it creates the block and wraps each slot as a nested,
  *     locked inline smart field - so an inserted "Permitted Use" carries real
@@ -113,7 +115,8 @@ type ClauseId =
   | 'termination'
   | 'governingLaw'
   | 'limitationOfLiability'
-  | 'indemnification';
+  | 'indemnification'
+  | 'returnOfMaterials';
 
 type ClauseCategory = 'Core' | 'Confidentiality' | 'Termination' | 'Risk Allocation';
 
@@ -202,7 +205,7 @@ const CLAUSE_LIBRARY: LibraryClause[] = [
     parts: ['Each party’s aggregate liability under this Agreement is limited to fees paid in the twelve (12) months preceding the claim.'],
   },
   {
-    // A library-only clause: not in the seeded document, so it starts "Used 0".
+    // A library-only clause: not in the seeded document, so it starts "Add clause".
     // Insert it to add a new governed section to the contract.
     id: 'indemnification',
     label: 'Indemnification',
@@ -211,6 +214,20 @@ const CLAUSE_LIBRARY: LibraryClause[] = [
     version: 'v1',
     parts: ['Each party will indemnify and hold the other harmless from third-party claims arising out of its breach of this Agreement.'],
   },
+  {
+    // Library-only and carries a nested field slot: adding it shows that an
+    // inserted clause's embedded variables become real, broadcast-linked SDTs.
+    id: 'returnOfMaterials',
+    label: 'Return of Materials',
+    category: 'Confidentiality',
+    jurisdiction: 'General',
+    version: 'v1',
+    parts: [
+      'Upon termination or at the disclosing party’s request, ',
+      { field: 'receivingParty' },
+      ' will promptly return or destroy all Confidential Information in its possession.',
+    ],
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -592,7 +609,7 @@ async function insertClause(clauseId: ClauseId, blockId: string): Promise<void>
   }
 
   // Lock the clause now that its slots are wrapped, then refresh the cards
-  // ("Used N") and scroll the new clause into view.
+  // (the card flips to "In contract") and scroll the new clause into view.
   reportMutation(doc.contentControls.setLockMode({ target: clauseTarget, lockMode: 'contentLocked' }), 'Lock clause');
   renderClausesPanel();
   void ui.contentControls.scrollIntoView({ id: clauseTarget.nodeId, block: 'center' });
@@ -602,9 +619,14 @@ async function insertClause(clauseId: ClauseId, blockId: string): Promise<void>
 function insertClauseAtCursor(clauseId: ClauseId): void {
   const ui = state.ui;
   if (!ui || !state.editor?.doc) return;
+  // Single-use: if it's already in the contract, reveal it instead of duplicating.
+  if (isClauseInDocument(clauseId)) {
+    revealClause(clauseId);
+    return;
+  }
   const seg = ui.selection.capture()?.target?.segments?.[0];
   if (!seg) {
-    setStatus('Place the cursor in the document (or drag the clause in), then click a clause to insert it.');
+    setStatus('Place the cursor in the document, then click a clause to add it.');
     return;
   }
   void insertClause(clauseId, seg.blockId);
@@ -651,7 +673,10 @@ function setupPaletteDragDrop(): () => void {
       insertField(field.key, field.label, { kind: 'selection', start: point, end: point });
     } else if (clauseId) {
       const clause = CLAUSE_LIBRARY.find((c) => c.id === clauseId);
-      if (clause) void insertClause(clause.id, hit.point.blockId); // offset 0 (block boundary)
+      if (!clause) return;
+      // Single-use: a clause already in the contract reveals instead of duplicating.
+      if (isClauseInDocument(clause.id)) revealClause(clause.id);
+      else void insertClause(clause.id, hit.point.blockId); // offset 0 (block boundary)
     }
   };
 
@@ -785,8 +810,10 @@ function highlightActiveClause(): void {
 
 /**
  * Template tab: the contract's building blocks. Two catalogs - inline Smart tags
- * (variable chips) and block Clauses (cards with metadata + usage count). Both
- * drag or click to insert; values are filled on the Values tab.
+ * (reusable variable chips, drag or click to insert) and block Clauses (governed,
+ * single-use cards with metadata + a status; an available clause adds by drag or
+ * click, one already in the contract reveals it). Values are filled on the
+ * Values tab.
  */
 function renderFieldsPanel(): void {
   fieldsPanelEl.innerHTML = '';
@@ -797,7 +824,7 @@ function renderFieldsPanel(): void {
 /**
  * Clauses section of the Template tab: a search + the clause cards. Mirrors the
  * Smart-tags section's style (group header, search) but the clauses render as
- * compact amber cards, not pills, since they're block controls. Creates the
+ * compact blue cards, not pills, since they're block controls. Creates the
  * list container (clausesListEl) that renderClausesPanel re-renders into.
  */
 function renderClausesSection(): void {
@@ -873,11 +900,11 @@ function renderValuesPanel(): void {
 
 /**
  * Render the clause cards: one card per clause, styled like the in-document
- * block clause (amber left rail). Like the smart-tag chips, a card is draggable
+ * block clause (blue left rail). Like the smart-tag chips, a card is draggable
  * into the document or click-to-insert at the cursor (insertClause snaps to a
  * block boundary). A card highlights when its clause is clicked in the document.
  */
-/** Every control in the document for a given clause (a clause can be placed more than once). */
+/** Every control in the document for a given clause (used internally for counts). */
 function clauseControls(clauseId: ClauseId): ContentControlInfo[] {
   const doc = state.editor?.doc;
   if (!doc) return [];
@@ -887,32 +914,51 @@ function clauseControls(clauseId: ClauseId): ContentControlInfo[] {
   });
 }
 
+/** A clause is single-use: it's either in the contract or available to add. */
+function isClauseInDocument(clauseId: ClauseId): boolean {
+  return clauseControls(clauseId).length > 0;
+}
+
+/** Scroll the clause's placement into view and highlight its card. */
+function revealClause(clauseId: ClauseId): void {
+  const ctrl = clauseControls(clauseId)[0];
+  if (!state.ui || !ctrl) return;
+  state.activeClauseId = clauseId;
+  highlightActiveClause();
+  void state.ui.contentControls.scrollIntoView({ id: ctrl.target.nodeId, block: 'center' });
+}
+
 /**
- * Render the clause library catalog: a card per available clause with its
- * category / jurisdiction / version and how many times it's placed in the
- * document. A card wears the in-document block clause's amber look. Drag a card
- * in, or click to insert it at the cursor; the card highlights when its clause
- * is clicked in the document.
+ * Render the clause library as a single-use inclusion checklist. Each card shows
+ * the clause's category / jurisdiction / version and whether it's "In contract"
+ * or available to "Add clause". A clause is governed and appears once: a card
+ * that's already in the contract can't be inserted again - clicking it reveals
+ * the existing clause instead; an available card inserts (click) or drags in.
  */
 function renderClausesPanel(): void {
   const list = clausesListEl;
   if (!list) return;
   list.innerHTML = '';
   for (const clause of CLAUSE_LIBRARY) {
-    const used = clauseControls(clause.id).length;
-    const usedText = used === 0 ? 'Not used' : `Used ${used} time${used === 1 ? '' : 's'}`;
+    const inDoc = isClauseInDocument(clause.id);
     const card = document.createElement('article');
-    card.className = 'clause' + (clause.id === state.activeClauseId ? ' is-active' : '');
+    card.className =
+      'clause ' + (inDoc ? 'is-present' : 'is-available') + (clause.id === state.activeClauseId ? ' is-active' : '');
     card.dataset.clauseId = clause.id;
-    card.draggable = true;
-    card.title = `Drag into the document, or click to insert the ${clause.label} clause at the cursor`;
+    card.draggable = !inDoc; // single-use: can't drag a clause that's already in
+    card.title = inDoc
+      ? `${clause.label} is in the contract — click to reveal it`
+      : `Drag into the document, or click to add the ${clause.label} clause at the cursor`;
     card.innerHTML = `
-      <h3 class="clause-label">${escapeHtml(clause.label)}</h3>
-      <p class="clause-meta">${escapeHtml(clause.category)} · ${escapeHtml(clause.jurisdiction)} · ${escapeHtml(clause.version)} · ${escapeHtml(usedText)}</p>
+      <div class="clause-head">
+        <h3 class="clause-label">${escapeHtml(clause.label)}</h3>
+        <span class="clause-status">${inDoc ? 'In contract' : 'Add clause'}</span>
+      </div>
+      <p class="clause-meta">${escapeHtml(clause.category)} · ${escapeHtml(clause.jurisdiction)} · ${escapeHtml(clause.version)}</p>
     `;
-    card.addEventListener('click', () => insertClauseAtCursor(clause.id));
+    card.addEventListener('click', () => (isClauseInDocument(clause.id) ? revealClause(clause.id) : insertClauseAtCursor(clause.id)));
     card.addEventListener('dragstart', (event) => {
-      if (!event.dataTransfer) return;
+      if (!event.dataTransfer || isClauseInDocument(clause.id)) return;
       event.dataTransfer.setData(CLAUSE_MIME, clause.id);
       event.dataTransfer.effectAllowed = 'copy';
     });