Update docs - describe parsing errors (tajo#138)

talshani · May 11, 2022 · e2069f4 · e2069f4
1 parent 515d069
commit e2069f4
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 28 deletions.
diff --git a/.changeset/slimy-snails-bow.md b/.changeset/slimy-snails-bow.md
@@ -0,0 +1,6 @@
+---
+"@ladle/react": patch
+"website": patch
+---
+
+Add a section explaining the limitations of story syntax - some parts need to be static so they can be parsed.
diff --git a/packages/ladle/lib/app/src/no-stories-error.tsx b/packages/ladle/lib/app/src/no-stories-error.tsx
@@ -1,6 +1,6 @@
 /* eslint-disable react/no-unescaped-entities */
 import * as React from "react";
-import { Code, Link } from "./ui";
+import { Link } from "./ui";
 
 const NoStoriesError: React.FC<{ error: string }> = ({ error }) => {
   console.log(error);
@@ -9,33 +9,12 @@ const NoStoriesError: React.FC<{ error: string }> = ({ error }) => {
       <h1>❌ Error when discovering stories ❌</h1>
       <pre>{error}</pre>
       <p>
-        <strong>Please restart Ladle, after fixing this issue.</strong>
+        <Link href="https://ladle.dev/docs/stories#limitations">
+          More information.
+        </Link>
       </p>
-      <h2>General limitations</h2>
       <p>
-        There are <b>some limitations</b> when it comes to the syntax of
-        stories:
-      </p>
-      <ul>
-        <li>
-          <Code>storyName</Code> and the default <Code>title</Code> need to be a
-          string literals. <Code>Story.storyName = "Renamed"</Code> is fine but{" "}
-          <Code>Story.storyName = "Renamed" + "Oof"</Code> not.
-        </li>
-        <li>
-          File names and named exports (or storyNames) are normalized and used
-          together as an unique identifier for each story. There cannot be two
-          stories with the same ID. Please, rename your stories or story files.
-        </li>
-        <li>
-          <Code>meta</Code> parameter needs to be serializable so it can be
-          shared through the{" "}
-          <Link href="https://ladle.dev/docs/meta">meta.json</Link> file.
-        </li>
-      </ul>
-      <p>
-        These limitations are in place to support some features like the
-        automatic code-splitting and meta file.
+        <strong>Please restart Ladle after fixing this issue.</strong>
       </p>
       <p>
         <Link href="https://github.com/tajo/ladle">Github</Link>

diff --git a/packages/ladle/lib/cli/vite-plugin/vite-plugin.js b/packages/ladle/lib/cli/vite-plugin/vite-plugin.js
@@ -79,9 +79,9 @@ function ladlePlugin(config, configFolder, mode) {
           detectDuplicateStoryNames(entryData);
           return getGeneratedList(entryData, configFolder, config);
         } catch (/** @type {any} */ e) {
-          printError("Error when generating the story list:");
-          console.log("");
+          printError("\nStory discovering failed:\n");
           printError(e);
+          printError("\nMore info: https://ladle.dev/docs/stories#limitations");
           if (mode === "production") {
             process.exit(1);
           }

diff --git a/packages/website/docs/stories.md b/packages/website/docs/stories.md
@@ -45,6 +45,8 @@ export const Button = () => <button>My Button</button>;
 Button.storyName = "Renamed Button";
 ```
 
+All story names and titles [need to be string literals](#limitations).
+
 You can also replace the filename (level name) part:
 
 ```tsx
@@ -147,3 +149,38 @@ CardWorld.args = {
   label: "World",
 };
 ```
+
+## Limitations
+
+There are limitations in place to support features like the automatic code-splitting or [meta](./meta) file. Some parts of the stories syntax must be static and serializable.
+
+### `storyName`, `title` and `meta` need to be serializable
+
+```tsx
+export default {
+  title: "Welcome",
+  meta: {
+    key: "value",
+  },
+};
+export const Story = () => "Hey";
+Story.storyName = "Renamed";
+```
+
+however, this does not work
+
+```tsx
+export default {
+  title: "Welcome" + " Everybody",
+  meta: {
+    key: 1 + 2,
+  },
+};
+export const Story = () => "Hey";
+const newName = "Renamed";
+Story.storyName = newName;
+```
+
+### Story names and files need to be unique
+
+File names and named exports (or storyNames) are [normalized](#navigation-and-routes) and used together as an unique identifier for each story. There cannot be two stories with the same ID. If that occurs, Ladle tells you what stories and files are clashing and you need to rename something.