docs(ui): add ButtonGroup stories to storybook

.storybook/main.ts

@@ -2,7 +2,12 @@ import type { StorybookConfig } from '@storybook-vue/nuxt'
 
 const config = {
   stories: ['../app/**/*.stories.@(js|ts)'],
-  addons: ['@storybook/addon-a11y', '@storybook/addon-docs', '@storybook/addon-themes'],
+  addons: [
+    '@storybook/addon-a11y',
+    '@storybook/addon-docs',
+    '@storybook/addon-themes',
+    'storybook-i18n',
+  ],
   framework: '@storybook-vue/nuxt',
   staticDirs: ['./.public'],
   features: {
@@ -19,34 +24,6 @@ const config = {
         }
       },
     })
-    // Replace the built-in vue-docgen plugin with a fault-tolerant version.
-    // vue-docgen-api can crash on components that import types from other
-    // .vue files (it tries to parse the SFC with @babel/parser as plain TS).
-    // This wrapper catches those errors so the build doesn't fail.
-    const docgenPlugin = config.plugins?.find(
-      (p): p is Extract<typeof p, { name: string }> =>
-        !!p && typeof p === 'object' && 'name' in p && p.name === 'storybook:vue-docgen-plugin',
-    )
-
-    if (docgenPlugin && 'transform' in docgenPlugin) {
-      const hook = docgenPlugin.transform
-      // Vite plugin hooks can be a function or an object with a `handler` property
-      const originalFn = typeof hook === 'function' ? hook : hook?.handler
-      if (originalFn) {
-        const wrapped = async function (this: unknown, ...args: unknown[]) {
-          try {
-            return await originalFn.apply(this, args)
-          } catch {
-            return undefined
-          }
-        }
-        if (typeof hook === 'function') {
-          docgenPlugin.transform = wrapped as typeof hook
-        } else if (hook) {
-          hook.handler = wrapped as typeof hook.handler
-        }
-      }
-    }
 
     return config
   },

.storybook/manager.ts

@@ -1,11 +1,6 @@
 import { addons } from 'storybook/manager-api'
-import { create } from 'storybook/theming'
-
-const npmxTheme = create({
-  brandTitle: 'npmx Storybook',
-  brandImage: '/npmx-storybook.svg',
-})
+import npmxDark from './theme'
 
 addons.setConfig({
-  theme: npmxTheme,
+  theme: npmxDark,
 })

.storybook/preview-head.html

@@ -0,0 +1,6 @@
+<style>
+  /* Override docs story canvas background to match npmx theme */
+  .docs-story {
+    background-color: var(--bg, oklch(0.171 0 0)) !important;
+  }
+</style>

.storybook/preview.ts

@@ -1,8 +1,10 @@
 import type { Preview } from '@storybook-vue/nuxt'
 import { withThemeByDataAttribute } from '@storybook/addon-themes'
+import { addons } from 'storybook/preview-api'
 import { currentLocales } from '../config/i18n'
 import { fn } from 'storybook/test'
 import { ACCENT_COLORS } from '../shared/utils/constants'
+import npmxDark from './theme'
 
 // related: https://github.com/npmx-dev/npmx.dev/blob/1431d24be555bca5e1ae6264434d49ca15173c43/test/nuxt/setup.ts#L12-L26
 // Stub Nuxt specific globals
@@ -17,6 +19,14 @@ globalThis['__NUXT_COLOR_MODE__'] ??= {
 // @ts-expect-error - dynamic global name
 globalThis.defineOgImageComponent = fn()
 
+// Subscribe to locale changes from storybook-i18n addon (once, outside decorator)
+let currentI18nInstance: any = null
+addons.getChannel().on('LOCALE_CHANGED', (newLocale: string) => {
+  if (currentI18nInstance) {
+    currentI18nInstance.setLocale(newLocale)
+  }
+})
+
 const preview: Preview = {
   parameters: {
     controls: {
@@ -25,25 +35,22 @@ const preview: Preview = {
         date: /Date$/i,
       },
     },
+    docs: {
+      theme: npmxDark,
+    },
+  },
+  initialGlobals: {
+    locale: 'en-US',
+    locales: currentLocales.reduce(
+      (acc, locale) => {
+        acc[locale.code] = locale.name
+        return acc
+      },
+      {} as Record<string, string>,
+    ),
   },
   // Provides toolbars to switch things like theming and language
   globalTypes: {
-    locale: {
-      name: 'Locale',
-      description: 'UI language',
-      defaultValue: 'en-US',
-      toolbar: {
-        icon: 'globe',
-        dynamicTitle: true,
-        items: [
-          // English is at the top so it's easier to reset to it
-          { value: 'en-US', title: 'English (US)' },
-          ...currentLocales
-            .filter(locale => locale.code !== 'en-US')
-            .map(locale => ({ value: locale.code, title: locale.name })),
-        ],
-      },
-    },
     accentColor: {
       name: 'Accent Color',
       description: 'Accent color',
@@ -70,9 +77,9 @@ const preview: Preview = {
       attributeName: 'data-theme',
     }),
     (story, context) => {
-      const { locale, accentColor } = context.globals as {
-        locale: string
+      const { accentColor, locale } = context.globals as {
         accentColor?: string
+        locale?: string
       }
 
       // Set accent color from globals
@@ -84,14 +91,12 @@ const preview: Preview = {
 
       return {
         template: '<story />',
-        // Set locale from globals
         created() {
-          if (this.$i18n) {
-            this.$i18n.setLocale(locale)
-          }
-        },
-        updated() {
-          if (this.$i18n) {
+          // Store i18n instance for LOCALE_CHANGED events
+          currentI18nInstance = this.$i18n
+
+          // Set initial locale when component is created
+          if (locale && this.$i18n) {
             this.$i18n.setLocale(locale)
           }
         },

.storybook/theme.ts

@@ -0,0 +1,13 @@
+import { create } from 'storybook/theming/create'
+
+const npmxDark = create({
+  base: 'dark',
+
+  brandTitle: 'npmx Storybook',
+  brandImage: '/npmx-storybook.svg',
+
+  // UI
+  appContentBg: '#101010', // oklch(0.171 0 0)
+})
+
+export default npmxDark

app/components/Button/Base.vue

@@ -1,6 +1,13 @@
 <script setup lang="ts">
 import type { IconClass } from '~/types'
 
+/**
+ * A base button component that supports multiple variants, sizes, and states as well as icons and keyboard shortcuts.
+ */
+defineOptions({
+  name: 'ButtonBase',
+})
+
 const props = withDefaults(
   defineProps<{
     disabled?: boolean

app/components/Button/ButtonBase.stories.ts

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from '@storybook-vue/nuxt'
+import ButtonBase from './Base.vue'
+
+const meta = {
+  component: ButtonBase,
+  parameters: {
+    docs: {
+      source: {
+        type: 'dynamic',
+        transform: (code: string) =>
+          code.replace(/<Base\b/g, '<ButtonBase').replace(/<\/Base>/g, '</ButtonBase>'),
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ButtonBase>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    default: 'Button Text',
+  },
+}
+
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
+}
+
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
+}
+
+export const Small: Story = {
+  args: {
+    size: 'small',
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
+}
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
+}
+
+export const WithIcon: Story = {
+  args: {
+    classicon: 'i-lucide:search',
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("search.button") }}</ButtonBase>`,
+  }),
+}
+
+export const WithKeyboardShortcut: Story = {
+  args: {
+    ariaKeyshortcuts: '/',
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("search.button") }}</ButtonBase>`,
+  }),
+}
+
+export const Block: Story = {
+  args: {
+    block: true,
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
+}