Merge pull request #186 from storybookjs/restore-template-component

Restore & add support for legacy syntax
storybookjs · Oct 16, 2024 · 0dcacba · 0dcacba
2 parents 1732cd7 + ff8a94d
commit 0dcacba
Show file tree

Hide file tree

Showing 72 changed files with 6,683 additions and 4,648 deletions.
diff --git a/.storybook/main.ts b/.storybook/main.ts
@@ -17,7 +17,16 @@ const config: StorybookConfig = {
     },
   ].filter(Boolean) as StorybookConfig['stories'],
   framework: '@storybook/svelte-vite',
-  addons: ['../dist/preset.js', '@storybook/addon-essentials', '@storybook/addon-interactions'],
+  addons: [
+    {
+      name: '../dist/preset.js',
+      options: {
+        legacyTemplate: true,
+      },
+    },
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+  ],
 };
 
 export default config;
diff --git a/ERRORS.md b/ERRORS.md
@@ -125,6 +125,11 @@ Below is a demonstration of correct usage:
 {/snippet}
 ```
 
+### SB_SVELTE_CSF_PARSER_EXTRACT_SVELTE_0009
+
+Storybook stories indexer parser threw an unrecognized error.
+If you see this error, [please report it on the issue tracker on GitHub](https://github.com/storybookjs/addon-svelte-csf/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBug%5D).
+
 ## `PARSER_EXTRACT_COMPILED`
 
 > [!NOTE]
@@ -325,3 +330,58 @@ eg. `Some story name!!` will be converted to `SomeStoryName`.
 You can fix this collision by providing a unique `exportName` prop with`<Story exportName="SomeUniqueExportName" ... />`.
 
 See more in [the `exportName` API docs](./README.md#custom-export-name).
+
+## `LEGACY_API`
+
+### `SB_SVELTE_CSF_LEGACY_API_0001`
+
+`<Story/>` component prop `template` value must be a text with string reference to existing `<Template />`'s `id` prop.
+
+It cannot be a shorthand or a dynamic value.
+
+```diff
+<Story
+-  template
+-  template={dynamicId}
++  template="custom-template"
+/>
+```
+
+### `SB_SVELTE_CSF_LEGACY_API_0002`
+
+You are using legacy template API, with deprecated components.\
+To enable support for legacy API, tweak this addon options in your _(`./.storybook/main.(j|t)s`)_ file:
+
+See [the Legacy API section](./README.md#legacy-api) for more details.
+
+```diff
+addons: [
+    // ... other addons
+-    '@storybook/addon-svelte-csf',
++   {
++       name: '@storybook/addon-svelte-csf',
++       options: {
++           legacyTemplate: true,
++       },
++   },
+],
+```
+
+### `SB_SVELTE_CSF_LEGACY_API_0003`
+
+You have more than one unidentified `<Template>` components _(without an `id` prop)_ in your stories file.
+This leads to unwanted behaviour at runtime.
+
+To solve this issue, assign an `id` prop to the other `<Template>`(s) components.
+
+```diff
+- <Template>
++ <Template id="template-1">
+```
+
+And for the stories `<Story />` component(s) which are supposed to use this template, use the `template` prop with id as string reference.
+
+```diff
+- <Story>
++ <Story template="template-1">
+```
diff --git a/README.md b/README.md
@@ -257,6 +257,31 @@ If you need to customize the type of the `args`, you can pass in a generic type
 const { Story } = defineMeta<{ anotherProp: boolean }>( ... );
 ```
 
+### Legacy API
+
+Version 5 of the addon changes the API from v4 in key areas, as described above. However a feature flag has been introduced to maintain support for the `<Template>`-based legacy API as it was prior to v5.
+
+To enable supoprt for the legacy API, make the following change to your main Storybook config:
+
+```diff
+export default {
+  addons: [
+-    '@storybook/addon-svelte-csf',
++    {
++      name: '@storybook/addon-svelte-csf',
++      options: {
++         legacyTemplate: true
++    },
+    ...
+  ],
+  ...
+}
+```
+
+This can make the overall experience slower, because it adds more transformation steps on top of the existing ones. It should only be used temporarily while migrating to the new API. It's highly likely that the legacy support will be dropped in future major versions of the addon.
+
+The legacy support is not bullet-proof, and it might not work in all scenarios that previously worked. If you're experiencing issues or getting errors after upgrading to v5, try migrating the problematic stories files to the modern API.
+
 ## Version compatibility
 
 ### latest

diff --git a/package.json b/package.json
@@ -14,6 +14,9 @@
   "license": "MIT",
   "type": "module",
   "imports": {
+    "#tests/*": {
+      "development": "./tests/*.ts"
+    },
     "#*": {
       "development": "./src/*.ts",
       "default": "./dist/*.js"
@@ -62,22 +65,23 @@
     "@storybook/node-logger": "^8.0.0",
     "@storybook/types": "^8.0.0",
     "dedent": "^1.5.3",
+    "es-toolkit": "^1.13.1",
     "esrap": "^1.2.2",
-    "lodash-es": "^4.17.21",
     "magic-string": "^0.30.10",
+    "svelte-ast-print": "0.2.6",
     "zimmerframe": "^1.1.2"
   },
   "devDependencies": {
     "@auto-it/released": "^11.1.6",
-    "@storybook/addon-actions": "^8.2.2",
-    "@storybook/addon-essentials": "^8.2.2",
-    "@storybook/addon-interactions": "^8.2.2",
-    "@storybook/client-logger": "^8.2.2",
+    "@storybook/addon-actions": "^8.3.5",
+    "@storybook/addon-essentials": "^8.3.5",
+    "@storybook/addon-interactions": "^8.3.5",
+    "@storybook/client-logger": "^8.3.5",
     "@storybook/eslint-config-storybook": "^4.0.0",
-    "@storybook/preview-api": "^8.2.2",
-    "@storybook/svelte": "^8.2.2",
-    "@storybook/svelte-vite": "^8.2.2",
-    "@storybook/test": "^8.2.2",
+    "@storybook/preview-api": "^8.3.5",
+    "@storybook/svelte": "^8.3.5",
+    "@storybook/svelte-vite": "^8.3.5",
+    "@storybook/test": "^8.3.5",
     "@sveltejs/package": "^2.3.2",
     "@sveltejs/vite-plugin-svelte": "4.0.0-next.3",
     "@tsconfig/svelte": "^5.0.4",
@@ -94,9 +98,9 @@
     "prettier-plugin-svelte": "^3.2.5",
     "rimraf": "^5.0.7",
     "rollup": "^4.18.0",
-    "storybook": "^8.2.2",
-    "svelte": "5.0.0-next.244",
-    "svelte-check": "^3.8.4",
+    "storybook": "^8.3.5",
+    "svelte": "5.0.0-next.267",
+    "svelte-check": "^4.0.5",
     "tslib": "^2.6.3",
     "type-fest": "^4.20.1",
     "typescript": "^5.5.2",
@@ -109,10 +113,10 @@
   "peerDependencies": {
     "@storybook/svelte": "^8.0.0",
     "@sveltejs/vite-plugin-svelte": "^4.0.0-next.0 || ^4.0.0",
-    "svelte": "^5.0.0-next.244 || ^5.0.0",
+    "svelte": "^5.0.0-next.267 || ^5.0.0",
     "vite": "^5.0.0"
   },
-  "packageManager": "pnpm@9.1.3+sha512.7c2ea089e1a6af306409c4fc8c4f0897bdac32b772016196c469d9428f1fe2d5a21daf8ad6512762654ac645b5d9136bb210ec9a00afa8dbc4677843ba362ecd",
+  "packageManager": "pnpm@9.5.0+sha256.dbdf5961c32909fb030595a9daa1dae720162e658609a8f92f2fa99835510ca5",
   "publishConfig": {
     "access": "public"
   },