feat: Add documentation (fix #44) (#60)

Co-authored-by: Guillaume Chau <[email protected]>

docs/.vitepress/config.js

@@ -3,7 +3,7 @@ module.exports = {
   description: 'Fast stories powered by Vite',
 
   themeConfig: {
-    repo: 'Akryum/histoire',
+    repo: 'histoire-dev/histoire',
     docsDir: 'docs',
     docsBranch: 'main',
     editLinks: true,
@@ -33,18 +33,70 @@ module.exports = {
     ],
 
     sidebar: {
-      // catch-all fallback
-      // '/': [
-      //   {
-      //     text: 'Guide',
-      //     children: [
-      //       {
-      //         text: 'Getting Started',
-      //         link: '/guide/',
-      //       },
-      //     ],
-      //   },
-      // ],
+      '/': [
+        {
+          text: 'Getting Started',
+          children: [
+            {
+              text: 'Introduction',
+              link: '/guide/intro',
+            },
+            {
+              text: 'Install',
+              link: '/guide/install',
+            },
+            {
+              text: 'Configuration',
+              link: '/guide/config',
+            },
+          ],
+        },
+        {
+          text: 'Write stories',
+          children: [
+            {
+              text: 'Introduction',
+              link: '/guide/stories',
+            },
+            {
+              text: 'Variant',
+              link: '/guide/variant',
+            },
+            {
+              text: 'State & Controls',
+              link: '/guide/controls',
+            },
+            {
+              text: 'Documentation',
+              link: '/guide/docs',
+            },
+            {
+              text: 'Serialization',
+              link: '/guide/serialization',
+            },
+            {
+              text: 'Hierarchy',
+              link: '/guide/hierarchy',
+            },
+          ],
+        },
+        {
+          text: 'Theme',
+          children: [
+            {
+              text: 'Configuration',
+              link: '/guide/theme',
+            },
+            {
+              text: 'Customization',
+              link: '/guide/customization',
+            },
+          ],
+        }, {
+          text: 'API Reference',
+          children: [],
+        },
+      ],
     },
   },
 }

docs/guide/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+Todo

docs/guide/config.md

@@ -0,0 +1,65 @@
+# Configuration
+
+To customize your experience, you can configure several parts of Histoire.
+
+## Standalone file
+
+The first option is to create a new file at the root of your project called `histoire.config.{js,ts}`. The configuration file must export the configuration object as default. Histoire provides a helper function `defineConfig` to enforce TypeScript typing.
+
+```ts
+import { defineConfig } from 'histoire'
+
+export default defineConfig({
+  // your Histoire configuration
+})
+```
+
+## Vite config file
+
+The second option is to provide the Histoire config object directly in your Vite config file `vite.config.{js,ts}`. To have the correct TypeScript check, make sure to use this [triple slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at the very top of your config file:
+
+```ts
+/// <reference types="histoire" />
+```
+
+Here's what your vite config file should look like:
+
+```ts
+/// <reference types="histoire" />
+
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  histoire: {
+    // your Histoire configuration
+  },
+})
+```
+
+## Global JS and CSS
+
+Your components may be using globally defined CSS (like CSS frameworks) or JS (like stores or helpers). Histoire provides an easy way to inject anything into each story by linking a setup file.
+
+```ts
+// histoire.config.ts
+
+export default defineConfig({ 
+  setupFile: '/src/histoire.setup.ts'
+})
+```
+
+Histoire provides a `defineVue3StorySetup` function to access the current app, story and variant for your convenience. You can use it inside your setup file like this:
+
+```ts
+// src/histoire.setup.ts
+
+import './histoire.css' // Import global CSS
+
+import { createPinia } from "pinia";
+import { defineVue3StorySetup } from 'histoire/client'
+
+export default defineVue3StorySetup(({ app, story, variant }) => {
+  const pinia = createPinia();
+  app.use(pinia); // Add Pinia store
+})
+```

docs/guide/controls.md

@@ -0,0 +1,115 @@
+# State & Controls
+
+Controls give you the ability to interact with your components arguments.
+
+## Defining a state
+
+The first step is to define the state that will be share to your story. You need to write a function that return the state as an object and put it in the `init-state` attribute of your variant.
+
+State is then provided to your component by using the `state` slot prop.
+
+```vue{4-9,16,18-22}
+<script lang="ts" setup>
+import MyButton from './MyButton.vue'
+
+function initState () {
+  return {
+    disabled: false,
+    content: "Hello world"
+  }
+}
+</script>
+
+<template>
+  <Story title="Cars">
+    <Variant
+      title="default"
+      :init-state="initState"
+    >
+      <template #default="{ state }">
+        <MyButton :disabled="state.disabled">
+          {{ state.content }}
+        </MyButton>
+      </template>
+    </Variant>
+  </Story>
+</template>
+```
+
+## Creating a panel
+
+To create the control panel, Histoire provides a `controls` slot. You can create your panel however you like in it.
+
+```vue{23-26}
+<script lang="ts" setup>
+import MyButton from './MyButton.vue'
+
+function initState () {
+  return {
+    disabled: false,
+    content: "Hello world"
+  }
+}
+</script>
+
+<template>
+  <Story title="Cars">
+    <Variant
+      title="default"
+      :init-state="initState"
+    >
+      <template #default="{ state }">
+        <MyButton :disabled="state.disabled">
+          {{ state.content }}
+        </MyButton>
+      </template>
+      <template #controls="{ state }">
+        Content: <input type="text" v-model="state.content" />
+        Disabled: <input type="checkbox" v-model="state.disabled" />
+      </template>
+    </Variant>
+  </Story>
+</template>
+```
+
+## Builtin controls
+
+To build a control panel a bit more easily, Histoire provides builtin controls specifically designed for this.
+
+```vue{24-25}
+<script lang="ts" setup>
+import MyButton from './MyButton.vue'
+
+function initState () {
+  return {
+    disabled: false,
+    content: "Hello world"
+  }
+}
+</script>
+
+<template>
+  <Story title="Cars">
+    <Variant
+      title="default"
+      :init-state="initState"
+    >
+      <template #default="{ state }">
+        <MyButton :disabled="state.disabled">
+          {{ state.content }}
+        </MyButton>
+      </template>
+      <template #controls="{ state }">
+        <HstText v-model="state.text" title="Content" />
+        <HstCheckbox v-model="state.disabled" title="Disabled" />
+      </template>
+    </Variant>
+  </Story>
+</template>
+```
+
+Available controls:
+- `HstCheckbox`
+- `HstNumber`
+- `HstText`
+- `HstTextarea`

docs/guide/customization.md

@@ -0,0 +1,88 @@
+# Theme customization
+
+To better match your colors guidelines, you can customize every colors used in the app. Note that Histoire uses Tailwind for its UI, so the colors pattern must match the Tailwind pattern.
+
+## Use builtin patterns
+
+Histoire provides some builtin patterns to easily change the color of the app.
+
+```ts
+// histoire.config.ts
+
+import { defaultColors } from 'histoire'
+
+export default defineConfig({ 
+  theme: {
+    colors: {
+      gray: defaultColors.zinc,
+      primary: defaultColors.cyan
+    }
+  }
+})
+```
+
+Available colors patterns:
+- `slate`
+- `gray`
+- `zinc`
+- `neutral`
+- `stone`
+- `red`
+- `orange`
+- `amber`
+- `yellow`
+- `lime`
+- `green`
+- `emerald`
+- `teal`
+- `cyan`
+- `sky`
+- `blue`
+- `indigo`
+- `violet`
+- `purple`
+- `fuchsia`
+- `pink`
+- `rose`
+
+## Use custom colors
+
+You can also define your own colors.
+
+```ts
+// histoire.config.ts
+
+export default defineConfig({ 
+  theme: {
+    colors: {
+      gray: {
+        50: '#fafafa',
+        100: '#f4f4f5',
+        200: '#e4e4e7',
+        300: '#d4d4d8',
+        400: '#a1a1aa',
+        500: '#71717a',
+        600: '#52525b',
+        700: '#3f3f46',
+        750: '#323238',
+        800: '#27272a',
+        850: '#1f1f21',
+        900: '#18181b',
+        950: '#101012',
+      },
+      primary: {
+        50: '#ecfeff',
+        100: '#cffafe',
+        200: '#a5f3fc',
+        300: '#67e8f9',
+        400: '#22d3ee',
+        500: '#06b6d4',
+        600: '#0891b2',
+        700: '#0e7490',
+        800: '#155e75',
+        900: '#164e63',
+      }
+    }
+  }
+})
+```

docs/guide/docs.md

@@ -0,0 +1,15 @@
+# Documentation
+
+Histoire lets you write markdown documentation for your stories. You just have to use the `docs` tag in your story file.
+
+```vue{5-9}
+<template>
+  <!-- Your story goes here -->
+</template>
+
+<docs lang="md">
+# My documentation
+
+Checkout this [cool video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)!
+</docs>
+```