From 68de7e2266684364d016eb04f4dde3e598480458 Mon Sep 17 00:00:00 2001
From: Guillaume Chau <guillaume.b.chau@gmail.com>
Date: Tue, 20 Dec 2022 11:54:10 +0100
Subject: [PATCH] fix(docs): scroll to URL anchor

---
 examples/vue3/src/LongFile1.story.md          | 115 +++++++++++++++++
 examples/vue3/src/LongFile2.story.md          | 121 ++++++++++++++++++
 .../src/app/components/panel/StoryDocs.vue    |  21 ++-
 3 files changed, 256 insertions(+), 1 deletion(-)
 create mode 100644 examples/vue3/src/LongFile1.story.md
 create mode 100644 examples/vue3/src/LongFile2.story.md

diff --git a/examples/vue3/src/LongFile1.story.md b/examples/vue3/src/LongFile1.story.md
new file mode 100644
index 00000000..8ac88da0
--- /dev/null
+++ b/examples/vue3/src/LongFile1.story.md
@@ -0,0 +1,115 @@
+# How to write stories?
+
+Stories are vue files ending with `.story.vue`. You just need to use the `<Story>` tag at the root of your template.
+
+```vue
+<!-- Meow.story.vue -->
+<template>
+  <Story>
+    🐱
+  </Story>
+</template>
+```
+
+The title of the story is provided with the (optional) `title` prop:
+
+```vue
+<template>
+  <Story title="🐱 Meow">
+    🐱
+  </Story>
+</template>
+```
+
+You can of course add `<style>` and/or `<script>` elements just like you would with any `.vue` file.
+
+For example, you will usually import and use a component in your story:
+
+```vue
+<!-- Meow.story.vue -->
+<script setup>
+import Meow from './Meow.vue'
+</script>
+
+<template>
+  <Story>
+    <Meow/>
+  </Story>
+</template>
+```
+
+## Variants
+
+Stories can have different variants representing the same component. You can define variants using the `<Variant>` tag. Similar to the story, you can provide a title to your variant with the `title` prop.
+
+```vue{3-11}
+<template>
+  <Story title="Cars">
+    <Variant title="default">
+      🚗
+    </Variant>
+    <Variant title="Fast">
+      🏎️
+    </Variant>
+    <Variant title="Slow">
+      🚜
+    </Variant>
+  </Story>
+</template>
+```
+
+## Layout
+
+You can change the layout of the variant by using the `layout` prop with an object. The `type` property is required to specify which layout to use.
+
+### Single layout
+
+This is the default layout, displaying one variant at a time. The default behavior is to isolate the story with an iframe. 
+
+Additional `layout` properties:
+- `iframe`: (default: `true`) enables the iframe, useful when your CSS has media queries for responsive design.
+
+```vue{4}
+<template>
+  <Story
+    title="Cars"
+    :layout="{ type: 'single', iframe: true }"
+  >
+    <Variant title="default">
+      🚗
+    </Variant>
+    <Variant title="Fast">
+      🏎️
+    </Variant>
+    <Variant title="Slow">
+      🚜
+    </Variant>
+  </Story>
+</template>
+```
+
+### Grid layout
+
+Display all the variants in a grid.
+
+Additional `layout` properties:
+- `width`: Column size. Can be number (pixels) or string (like `'100%'`).
+
+```vue{4}
+<template>
+  <Story
+    title="Cars"
+    :layout="{ type: 'grid', width: 200 }"
+  >
+    <Variant title="default">
+      🚗
+    </Variant>
+    <Variant title="Fast">
+      🏎️
+    </Variant>
+    <Variant title="Slow">
+      🚜
+    </Variant>
+  </Story>
+</template>
+```
diff --git a/examples/vue3/src/LongFile2.story.md b/examples/vue3/src/LongFile2.story.md
new file mode 100644
index 00000000..6564f4e7
--- /dev/null
+++ b/examples/vue3/src/LongFile2.story.md
@@ -0,0 +1,121 @@
+# Hierarchy
+
+You can customize the story explorer tree.
+
+## Using the title
+
+By default, Histoire uses the title of your stories to create the hierarchy. If you want to put a story in a specific folder or subfolder, just write the path as the title of your Story.
+
+```vue{2}
+<template>
+  <Story title="Folder/Sub Folder/My story" >
+    <!-- Your story goes here -->
+  </Story>
+</template>
+```
+
+## Using the file path
+
+If you want to use the real path of your story files, you can change that in your [Histoire configuration file](/guide/config).
+
+```ts{5}
+// histoire.config.ts
+
+export default defineConfig({ 
+  tree: {
+    file: 'path',
+  },
+})
+```
+
+## Custom logic
+
+If you want a custom hierarchy, you can define your own function that takes an object with the `title` and the `path` of your story as an argument, and returns an array of string being the path of your story in the app.
+
+```ts{5}
+// histoire.config.ts
+
+export default defineConfig({ 
+  tree: {
+    file: ({ title, path }) => title.split('/'), // equivalent to default behavior
+  },
+})
+```
+
+## Sorting
+
+By default, files and stories are sorted by ascending order. But you might want to sort things differently, for example display some stories at the beginning. You can do so by providing a sorting function in your configuration file.
+
+```ts{5}
+// histoire.config.ts
+
+export default defineConfig({ 
+  tree: {
+    order: (a, b) => a.localeCompare(b), // equivalent to default behavior
+  },
+})
+```
+
+## Groups
+
+Sometimes, you might have additional organization needs for the stories. Besides folders, Histoire also provides groups, which are little different:
+
+- expanded by default
+- only root level
+- manual order
+- independant from the hierarchy defined thanks to `tree.file` (see above)
+
+You can define groups in your configuration with the `groups` property. It's an array of group objects with the following properties:
+
+- `title`: the title of the group (use an empty string to have an untoggable group)
+- `id` (optional): the id of the group, useful to reference it using the `Story` `group` prop
+- `include` (optional): function that takes a file object [1] and returns a boolean, true if the file should be included in the group.
+
+[1]: the file objects have the following properties:
+- `title`: the title of the story
+- `path`: the path of the story file
+
+The stories are distributed in groups according to the following rules in this order:
+- `group` prop of the `<Story>`
+- `include` function of the groups, respecting the order in the `groups` array (a story may only appear in one group maximum)
+
+Files not included in a group are always displayed after the last group.
+
+Example:
+
+```ts
+// histoire.config.ts
+
+export default defineConfig({ 
+  tree: {
+    groups: [
+      {
+        id: 'top',
+        title: '', // No toggle
+      },
+      {
+        title: 'My Group',
+        include: file => /Code gen|Controls|Docs/.test(file.title),
+      },
+      {
+        title: 'Components',
+        include: file => !file.title.includes('Serialize'),
+      },
+      {
+        title: 'Others',
+        include: file => true,
+      },
+    ],
+  },
+})
+```
+
+You can use the `group` prop to reference a group in your stories using its `id`.
+
+```vue{2}
+<template>
+  <Story group="top">
+    This is a demo book using Vue 3.
+  </Story>
+</template>
+```
diff --git a/packages/histoire-app/src/app/components/panel/StoryDocs.vue b/packages/histoire-app/src/app/components/panel/StoryDocs.vue
index 629d5520..b4f63742 100644
--- a/packages/histoire-app/src/app/components/panel/StoryDocs.vue
+++ b/packages/histoire-app/src/app/components/panel/StoryDocs.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import { PropType, Ref, ref, toRefs, watchEffect } from 'vue'
+import { onMounted, onUpdated, PropType, Ref, ref, toRefs, watchEffect } from 'vue'
 import type { Story } from '../../types'
 // @ts-expect-error virtual module
 import { markdownFiles } from 'virtual:$histoire-markdown-files'
@@ -85,6 +85,25 @@ function onClick (e: MouseEvent) {
     router.push(targetHref)
   }
 }
+
+// Handle URL anchor
+function scrollToAnchor () {
+  if (location.hash) {
+    const anchor = document.querySelector(location.hash)
+    if (anchor) {
+      anchor.scrollIntoView()
+      return true
+    }
+  }
+}
+
+onMounted(() => {
+  scrollToAnchor()
+})
+
+onUpdated(() => {
+  scrollToAnchor()
+})
 </script>
 
 <template>