docs: add headless and storybook-utils to VitePress (#14)

apps/docs/src/.vitepress/config.ts

@@ -29,21 +29,58 @@ export default defineConfig({
       { text: "Q&A", link: "https://github.com/schwarzit/onyx/discussions/categories/q-a" },
     ],
     socialLinks: [{ icon: "github", link: packageJson.repository.url }],
-    sidebar: [
-      {
-        text: "Introduction",
-        collapsed: false,
-        items: [
-          { text: "Getting Started", link: "/getting-started" },
-          { text: "The Team", link: "/team" },
-        ],
-      },
-      {
-        text: "Components",
-        base: "/components",
-        collapsed: false,
-        items: getComponents().map((name) => ({ text: name, link: `/${name}` })),
-      },
-    ],
+    sidebar: {
+      // default sidebar items
+      "/": [
+        {
+          text: "Introduction",
+          collapsed: false,
+          items: [
+            { text: "Getting Started", link: "/getting-started" },
+            { text: "The Team", link: "/team" },
+          ],
+        },
+        {
+          text: "Advanced",
+          collapsed: false,
+          items: [
+            {
+              text: "Additional packages",
+              link: "/packages/",
+            },
+          ],
+        },
+        {
+          text: "Components",
+          base: "/components",
+          collapsed: false,
+          items: getComponents().map((name) => ({ text: name, link: `/${name}` })),
+        },
+      ],
+      // standalone sidebar for documentation about our additional packages
+      "/packages/": [
+        {
+          text: "Introduction",
+          items: [
+            { text: "Back to Onyx", link: "/getting-started" },
+            { text: "About", link: "/packages/" },
+          ],
+        },
+        {
+          text: "Additional packages",
+          base: "/packages",
+          items: [
+            {
+              text: "@sit-onyx/headless",
+              link: "/headless",
+            },
+            {
+              text: "@sit-onyx/storybook-utils",
+              link: "/storybook-utils",
+            },
+          ],
+        },
+      ],
+    },
   },
 });

apps/docs/src/packages/headless.md

@@ -0,0 +1,58 @@
+---
+outline: [2, 3]
+---
+
+<script lang="ts" setup>
+import packageJson from "../../../../packages/headless/package.json";
+</script>
+
+# @sit-onyx/headless
+
+::: warning Work in progress / Active development
+This library is currently in early / active development.
+:::
+
+{{ packageJson.description }}.
+
+Inspired by [Melt UI](https://melt-ui.com).
+
+## Installation
+
+<!--
+Make sure that this chapter is kept up to date with installation steps in
+packages/headless/README.md file.
+ -->
+
+Install the npm package with your corresponding package manager:
+
+::: code-group
+
+```sh [pnpm]
+pnpm add @sit-onyx/headless
+```
+
+```sh [npm]
+npm install @sit-onyx/headless
+```
+
+```sh [yarn]
+yarn install @sit-onyx/headless
+```
+
+:::
+
+## Composables
+
+### useComboBox
+
+```vue
+<script lang="ts" setup>
+import { createCombobox } from "@sit-onyx/headless";
+
+const {
+  elements: {
+    ...
+  }
+ } = createCombobox();
+</script>
+```

apps/docs/src/packages/index.md

@@ -0,0 +1,18 @@
+<script lang="ts" setup>
+import headlessPackageJson from "../../../../packages/headless/package.json";
+import storybookUtilsPackageJson from "../../../../packages/storybook-utils/package.json";
+
+// make sure to also add a sidebar item in ../.vitepress/config.ts and a file matching the package name in this folder
+// to make the link below work when adding another package to this list.
+const packages = [headlessPackageJson, storybookUtilsPackageJson];
+</script>
+
+# Additional packages
+
+Besides the [`sit-onyx`](/getting-started) package that contains our Vue.js components, we also offer additional npm packages that you might find helpful such as:
+
+<ul>
+  <li v-for="p in packages" :key="p.name">
+    <a :href="`/packages/${p.name.replace('@sit-onyx/', '')}`">{{ p.name }}</a>: {{ p.description }}
+  </li>
+</ul>

apps/docs/src/packages/storybook-utils.md

@@ -0,0 +1,106 @@
+---
+outline: [2, 3]
+---
+
+<script lang="ts" setup>
+import packageJson from "../../../../packages/storybook-utils/package.json";
+</script>
+
+# @sit-onyx/storybook-utils
+
+{{ packageJson.description }}.
+
+## Installation
+
+<!--
+Make sure that this chapter is kept up to date with installation steps in
+packages/storybook-utils/README.md file.
+ -->
+
+Install the npm package with your corresponding package manager:
+
+::: code-group
+
+```sh [pnpm]
+pnpm add -D @sit-onyx/storybook-utils storybook-dark-mode
+```
+
+```sh [npm]
+npm install -D @sit-onyx/storybook-utils storybook-dark-mode
+```
+
+```sh [yarn]
+yarn install -D @sit-onyx/storybook-utils storybook-dark-mode
+```
+
+:::
+
+## Utilities
+
+### createPreview
+
+Creates a default Storybook preview configuration for a project that uses `Onyx`. Includes the following features:
+
+- Improved controls (sorting and expanded controls so descriptions etc. are also shown in a single story)
+- Improved Vue-specific code highlighting (e.g. using `@` instead of `v-on:`)
+- Setup for dark mode (including docs page). Requires addon [`storybook-dark-mode`](https://storybook.js.org/addons/storybook-dark-mode) to be enabled in .storybook/main.ts file
+- Support for setting the light/dark mode when Storybook is embedded as an iframe (via query parameter, e.g. `?theme=dark`).
+
+::: code-group
+
+```ts [.storybook/preview.ts]
+import { createPreview } from "@sit-onyx/storybook-utils";
+
+const preview = {
+  // we need to destructure here because as of Storybook 7.6
+  // it can not statically analyze that the `preview` variable is an object
+  ...createPreview({
+    // optional overrides...
+  }),
+};
+
+export default preview;
+```
+
+```ts [.storybook/main.ts]
+import type { StorybookConfig } from "@storybook/vue3-vite";
+
+const config: StorybookConfig = {
+  addons: ["storybook-dark-mode"],
+  // ...
+};
+
+export default config;
+```
+
+:::
+
+### defineStorybookActionsAndVModels
+
+Utility to define Storybook meta for a given Vue component which will take care of defining argTypes for the given events as well as implementing v-model handlers so that the Storybook controls are updated when you interact with the component.
+
+Supports auto-completion for event names. Should be preferred over manually defining argTypes for `*.stories.ts` files.
+
+::: code-group
+
+```ts [TestInput.stories.ts]
+import { defineStorybookActionsAndVModels } from "@sit-onyx/storybook-utils";
+import type { Meta, StoryObj } from "@storybook/vue3";
+import TestInput from "./TestInput.vue";
+
+/**
+ * The input component can be used to...
+ */
+const meta: Meta<typeof TestInput> = {
+  title: "components/TestInput",
+  ...defineStorybookActionsAndVModels({
+    component: TestInput,
+    events: ["update:modelValue", "change"],
+  }),
+};
+
+export default meta;
+type Story = StoryObj<typeof TestInput>;
+```
+
+:::

packages/storybook-utils/src/actions.ts

@@ -5,8 +5,8 @@ import type { DefineStorybookActionsAndVModelsOptions, ExtractVueEventNames } fr
 
 /**
  * Utility to define Storybook meta for a given Vue component which will take care of defining argTypes for
- * the given events as well as implementing v-model handlers.
- * Should be preferred over manually defining argTypes for a *.stories.ts file.
+ * the given events as well as implementing v-model handlers so that the Storybook controls are updated when you interact with the component.
+ * Should be preferred over manually defining argTypes for *.stories.ts files.
  *
  * @example
  * ```ts

packages/storybook-utils/src/preview.ts

@@ -10,6 +10,7 @@ import { DARK_MODE_EVENT_NAME } from "storybook-dark-mode";
  * - Improved controls (sorting and expanded controls so descriptions etc. are also shown in a single story)
  * - Improved Vue-specific code highlighting (e.g. using `@` instead of `v-on:`)
  * - Setup for dark mode (including docs page). Requires addon `storybook-dark-mode` to be enabled in .storybook/main.ts file
+ * - Support for setting the light/dark mode when Storybook is embedded as an iframe (via query parameter, e.g. `?theme=dark`)
  *
  * @param overrides Custom preview / overrides, will be deep merged with the default preview.
  *