From 158f4c96ae48f0b93dace855067651976a78ac23 Mon Sep 17 00:00:00 2001 From: Lars Rickert Date: Wed, 3 Jan 2024 10:36:19 +0100 Subject: [PATCH] docs: add headless and storybook-utils to VitePress (#14) --- apps/docs/src/.vitepress/config.ts | 69 ++++++++++---- apps/docs/src/packages/headless.md | 58 ++++++++++++ apps/docs/src/packages/index.md | 18 ++++ apps/docs/src/packages/storybook-utils.md | 106 ++++++++++++++++++++++ packages/storybook-utils/src/actions.ts | 4 +- packages/storybook-utils/src/preview.ts | 1 + 6 files changed, 238 insertions(+), 18 deletions(-) create mode 100644 apps/docs/src/packages/headless.md create mode 100644 apps/docs/src/packages/index.md create mode 100644 apps/docs/src/packages/storybook-utils.md diff --git a/apps/docs/src/.vitepress/config.ts b/apps/docs/src/.vitepress/config.ts index 289f04fa4e..d2ab9d637b 100644 --- a/apps/docs/src/.vitepress/config.ts +++ b/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", + }, + ], + }, + ], + }, }, }); diff --git a/apps/docs/src/packages/headless.md b/apps/docs/src/packages/headless.md new file mode 100644 index 0000000000..f7ee0c9d2a --- /dev/null +++ b/apps/docs/src/packages/headless.md @@ -0,0 +1,58 @@ +--- +outline: [2, 3] +--- + + + +# @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 + + + +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 + +``` diff --git a/apps/docs/src/packages/index.md b/apps/docs/src/packages/index.md new file mode 100644 index 0000000000..a58bd38ff9 --- /dev/null +++ b/apps/docs/src/packages/index.md @@ -0,0 +1,18 @@ + + +# 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: + + diff --git a/apps/docs/src/packages/storybook-utils.md b/apps/docs/src/packages/storybook-utils.md new file mode 100644 index 0000000000..542407a6d3 --- /dev/null +++ b/apps/docs/src/packages/storybook-utils.md @@ -0,0 +1,106 @@ +--- +outline: [2, 3] +--- + + + +# @sit-onyx/storybook-utils + +{{ packageJson.description }}. + +## Installation + + + +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 = { + title: "components/TestInput", + ...defineStorybookActionsAndVModels({ + component: TestInput, + events: ["update:modelValue", "change"], + }), +}; + +export default meta; +type Story = StoryObj; +``` + +::: diff --git a/packages/storybook-utils/src/actions.ts b/packages/storybook-utils/src/actions.ts index 8c0d61bec4..b5c32d3ffd 100644 --- a/packages/storybook-utils/src/actions.ts +++ b/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 diff --git a/packages/storybook-utils/src/preview.ts b/packages/storybook-utils/src/preview.ts index 323268e30b..61a9617b92 100644 --- a/packages/storybook-utils/src/preview.ts +++ b/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. *