Vue: Generate Story snippets from docgen payload

code/lib/docgen-harness/src/compare/expect-current-or-better.test.ts

@@ -70,6 +70,18 @@ describe('expectCurrentOrBetter', () => {
     ).toThrow(/changed-summary/);
   });
 
+  it('reports an unparsable candidate instead of calling declared omissions stale', () => {
+    expect(() =>
+      expectCurrentOrBetter({
+        kind: 'snippet',
+        framework: 'vue3',
+        baseline: '<template>\n  <C :severity="severity" />\n</template>',
+        candidate: 'not a snippet',
+        declaredOmissions: ['severity'],
+      })
+    ).toThrow(/unparsable-candidate/);
+  });
+
   it('routes snippet input to the snippet comparator', () => {
     const baseline = '<sb-cmp [count]="3"></sb-cmp>';
     expect(() =>

code/lib/docgen-harness/src/compare/expect-current-or-better.ts

@@ -11,22 +11,56 @@ export type ExpectCurrentOrBetterInput =
       baseline: StrictArgTypes;
       candidate: StrictArgTypes;
     } & CompareArgTypesOptions)
-  | ({ kind: 'snippet' } & CompareSnippetInput);
+  | ({ kind: 'snippet' } & CompareSnippetInput & {
+        /**
+         * Args the candidate is expected to leave out even though the baseline represents them,
+         * because their source references a binding a static snippet cannot declare. The candidate
+         * records each one in `StoryDoc.warning`, and the runtime keeps its own snippet for readers
+         * who need the resolved value.
+         *
+         * Checked in both directions: an arg listed here that the candidate does represent fails, so
+         * the list cannot outlive the gap it documents.
+         */
+        declaredOmissions?: readonly string[];
+      });
 
 /** Throws a single error listing every violation, so a failure shows the whole gap at once. */
 export function expectCurrentOrBetter(input: ExpectCurrentOrBetterInput): void {
-  const violations: Violation[] =
-    input.kind === 'argTypes'
-      ? compareArgTypes(input.baseline, input.candidate, {
-          legacyBaseline: input.legacyBaseline,
-          strictTable: input.strictTable,
-        })
-      : compareSnippet(input);
-  if (violations.length > 0) {
-    const lines = violations.map((v) => `- [${v.kind}] ${v.arg}: ${v.message}`);
+  if (input.kind === 'argTypes') {
+    throwOnViolations(
+      compareArgTypes(input.baseline, input.candidate, {
+        legacyBaseline: input.legacyBaseline,
+        strictTable: input.strictTable,
+      })
+    );
+    return;
+  }
+
+  const declaredOmissions = input.declaredOmissions ?? [];
+  const violations = compareSnippet(input);
+  // An unparsable candidate leaves nothing omitted
+  throwOnViolations(violations.filter((v) => v.kind !== 'lost-representation'));
+
+  const omitted = new Set(violations.map((v) => v.arg));
+  const stale = declaredOmissions.filter((arg) => !omitted.has(arg));
+  if (stale.length > 0) {
     // eslint-disable-next-line local-rules/no-uncategorized-errors
     throw new Error(
-      `expectCurrentOrBetter found ${violations.length} violation(s):\n${lines.join('\n')}`
+      `The candidate snippet now represents ${stale.join(', ')} — remove it from declaredOmissions`
     );
   }
+
+  throwOnViolations(violations.filter((v) => !declaredOmissions.includes(v.arg)));
+}
+
+function throwOnViolations(violations: Violation[]): void {
+  if (violations.length === 0) {
+    return;
+  }
+
+  const lines = violations.map((v) => `- [${v.kind}] ${v.arg}: ${v.message}`);
+  // eslint-disable-next-line local-rules/no-uncategorized-errors
+  throw new Error(
+    `expectCurrentOrBetter found ${violations.length} violation(s):\n${lines.join('\n')}`
+  );
 }

code/lib/docgen-harness/src/vue3/__testfixtures__/cross-file-composed-utility/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-cross-file-composed-utility--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <UtilityComposedProps label="Picked" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/cross-file-extended-interface/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-cross-file-extended-interface--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <ExtendedInterfaceProps extra :id="7" name="Chained" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/cross-file-imported-interface/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-cross-file-imported-interface--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <ImportedInterfaceProps :count="2" label="Imported" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/cross-file-props-spread/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-cross-file-props-spread--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <CrossFilePropsSpread label="Text label" :optional="false" value="hello" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/cross-file-runtime-props/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-cross-file-runtime-props--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <CrossFileRuntimeProps :count="3" label="Imported" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/cross-file-union-alias/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-cross-file-union-alias--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <CrossFileUnionAlias size="small" variant="danger" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/define-expose/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-define-expose--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <DefineExpose label="Increment" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/define-props-destructured/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-define-props-destructured--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <DestructuredProps label="Sized" size="large" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/define-props-runtime-array/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-define-props-runtime-array--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <RuntimeArrayProps appearance="primary" label="Go" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/define-props-runtime-object/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-define-props-runtime-object--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <RuntimeObjectProps :count="3" label="Total" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/define-slots-with-props/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-define-slots-with-props--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <DefineSlotsWithProps disabled label="Save" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/events-jsdoc/story-docs.payload.snapshot

@@ -8,6 +8,15 @@
       "description": undefined,
       "id": "forms-events-jsdoc--with-handlers",
       "name": "With Handlers",
+      "snippet": "<script lang="ts" setup>
+const onCancel = () => {};
+
+const onSave = () => {};
+</script>
+
+<template>
+  <EventsJsdoc label="Save" @cancel="onCancel" @save="onSave" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/jsdoc-tags/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-jsdoc-tags--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <JsdocTags label="Old label" title="New title" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/prop-slot-name-collision/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-prop-slot-name-collision--icon-prop-as-written",
       "name": "Icon Prop As Written",
+      "snippet": "<template>
+  <PropSlotNameCollision icon="pi pi-check" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/props-basic-types/story-docs.payload.snapshot

@@ -8,12 +8,30 @@
       "description": undefined,
       "id": "forms-props-basic-types--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <PropsBasicTypes :count="2" enabled label="Hello" />
+</template>",
       "summary": undefined,
     },
     "forms-props-basic-types--unrepresentable-args": {
       "description": undefined,
       "id": "forms-props-basic-types--unrepresentable-args",
       "name": "Unrepresentable Args",
+      "snippet": "<script lang="ts" setup>
+const big = BigInt('9007199254740993');
+
+const config = { theme: 'dark', dense: true };
+
+const formatter = (value: number) => `#${value}`;
+
+const tags = ['alpha', 'beta'];
+
+const token = Symbol('fixture');
+</script>
+
+<template>
+  <PropsBasicTypes :big="big" :config="config" :formatter="formatter" label="Formatted" :tags="tags" :token="token" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/props-generic/story-docs.payload.snapshot

@@ -8,6 +8,13 @@
       "description": undefined,
       "id": "forms-props-generic--props-as-written",
       "name": "Props As Written",
+      "snippet": "<script lang="ts" setup>
+const items = ['alpha', 'beta'];
+</script>
+
+<template>
+  <PropsGeneric :items="items" selected="alpha" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/props-ts-enum/story-docs.payload.snapshot

@@ -8,7 +8,11 @@
       "description": undefined,
       "id": "forms-props-ts-enum--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <TsEnumProps :level="1" />
+</template>",
       "summary": undefined,
+      "warning": "Omitted args that cannot be resolved statically: severity: Severity.Warning",
     },
   },
 }

code/lib/docgen-harness/src/vue3/__testfixtures__/props-union-enum/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-props-union-enum--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <PropsUnionEnum size="medium" status="ok" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/recursive-type/story-docs.payload.snapshot

@@ -8,6 +8,16 @@
       "description": undefined,
       "id": "forms-recursive-type--props-as-written",
       "name": "Props As Written",
+      "snippet": "<script lang="ts" setup>
+const node = {
+  value: 'root',
+  children: [{ value: 'leaf', children: [] }],
+};
+</script>
+
+<template>
+  <RecursiveTree :node="node" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/runtime-multi-constructor/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-runtime-multi-constructor--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <RuntimeMultiConstructor :width="200" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/runtime-proptype-cast/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-runtime-proptype-cast--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <RuntimePropTypeCast kind="secondary" :measure="42" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/slots-template-only/story-docs.payload.snapshot

@@ -14,6 +14,20 @@
       "description": undefined,
       "id": "forms-slots-template-only--string-child",
       "name": "String Child",
+      "snippet": "<script lang="ts" setup>
+const _default = 'Plain text content';
+
+const header = 'Header text';
+</script>
+
+<template>
+  <TemplateOnlySlots>
+    {{ _default }}
+    <template #header>
+      {{ header }}
+    </template>
+  </TemplateOnlySlots>
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/slots/story-docs.payload.snapshot

@@ -14,6 +14,15 @@
       "description": undefined,
       "id": "forms-slots--string-child",
       "name": "String Child",
+      "snippet": "<script lang="ts" setup>
+const _default = 'Plain text content';
+</script>
+
+<template>
+  <SlotsShowcase heading="Plain">
+    {{ _default }}
+  </SlotsShowcase>
+</template>",
       "summary": undefined,
     },
     "forms-slots--v-node-child": {

code/lib/docgen-harness/src/vue3/__testfixtures__/type-intersection-whole/story-docs.payload.snapshot

@@ -8,6 +8,9 @@
       "description": undefined,
       "id": "forms-type-intersection-whole--props-as-written",
       "name": "Props As Written",
+      "snippet": "<template>
+  <TypeIntersectionWhole id="save-button" size="medium" />
+</template>",
       "summary": undefined,
     },
   },

code/lib/docgen-harness/src/vue3/__testfixtures__/type-intersection/story-docs.payload.snapshot

@@ -8,6 +8,13 @@
       "description": undefined,
       "id": "forms-type-intersection--props-as-written",
       "name": "Props As Written",
+      "snippet": "<script lang="ts" setup>
+const mixed = { label: 'Intersected', count: 2, extra: true };
+</script>
+
+<template>
+  <IntersectionProps :mixed="mixed" />
+</template>",
       "summary": undefined,
     },
   },