Merge remote-tracking branch 'origin/main' into feat/pds-landing-page

Author: danielroe

.env.example

@@ -1,2 +1,5 @@
 #secure password, can use openssl rand -hex 32
-NUXT_SESSION_PASSWORD=""
+NUXT_SESSION_PASSWORD=""
+
+#HMAC secret for image proxy URL signing, can use openssl rand -hex 32
+NUXT_IMAGE_PROXY_SECRET=""

.github/workflows/chromatic.yml

@@ -0,0 +1,46 @@
+name: chromatic
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number || github.sha }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  chromatic:
+    name: 📚 Chromatic
+    runs-on: ubuntu-24.04-arm
+
+    steps:
+      - name: ☑️ Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: lts/*
+
+      - uses: pnpm/action-setup@1e1c8eafbd745f64b1ef30a7d7ed7965034c486c # 1e1c8eafbd745f64b1ef30a7d7ed7965034c486c
+        name: 🟧 Install pnpm
+        with:
+          cache: true
+
+      - name: 📦 Install dependencies
+        run: pnpm install
+
+      - name: 🧪 Run Chromatic Visual and Accessibility Tests
+        uses: chromaui/action@a8ce9c58f59be5cc7090cadfc8f130fb08fcf0c3 # v15.1.0
+        env:
+          CHROMATIC_BRANCH: ${{ github.event.pull_request.head.ref || github.ref_name }}
+          CHROMATIC_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+          CHROMATIC_SLUG: ${{ github.repository }}

.gitignore

@@ -45,4 +45,9 @@ file-tree-sprite.svg
 
 # output
 .vercel
+
+# Storybook
+*storybook.log
+storybook-static
+
 .nvmrc

.storybook/main.ts

@@ -0,0 +1,54 @@
+import type { StorybookConfig } from '@storybook-vue/nuxt'
+
+const config = {
+  stories: ['../app/**/*.stories.@(js|ts)'],
+  addons: ['@storybook/addon-a11y', '@storybook/addon-docs', '@storybook/addon-themes'],
+  framework: '@storybook-vue/nuxt',
+  features: {
+    backgrounds: false,
+  },
+  async viteFinal(config) {
+    config.plugins ??= []
+
+    config.plugins.push({
+      name: 'ignore-internals',
+      transform(_, id) {
+        if (id.includes('/app/pages/blog/') && id.endsWith('.md')) {
+          return 'export default {}'
+        }
+      },
+    })
+    // 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
+  },
+} satisfies StorybookConfig
+
+export default config

.storybook/preview.ts

@@ -0,0 +1,103 @@
+import type { Preview } from '@storybook-vue/nuxt'
+import { withThemeByDataAttribute } from '@storybook/addon-themes'
+import { currentLocales } from '../config/i18n'
+import { fn } from 'storybook/test'
+import { ACCENT_COLORS } from '../shared/utils/constants'
+
+// related: https://github.com/npmx-dev/npmx.dev/blob/1431d24be555bca5e1ae6264434d49ca15173c43/test/nuxt/setup.ts#L12-L26
+// Stub Nuxt specific globals
+// @ts-expect-error - dynamic global name
+globalThis['__NUXT_COLOR_MODE__'] ??= {
+  preference: 'system',
+  value: 'dark',
+  getColorScheme: fn(() => 'dark'),
+  addColorScheme: fn(),
+  removeColorScheme: fn(),
+}
+// @ts-expect-error - dynamic global name
+globalThis.defineOgImageComponent = fn()
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+  // 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',
+      toolbar: {
+        icon: 'paintbrush',
+        dynamicTitle: true,
+        items: [
+          ...Object.keys(ACCENT_COLORS.light).map(color => ({
+            value: color,
+            title: color.charAt(0).toUpperCase() + color.slice(1),
+          })),
+          { value: undefined, title: 'No Accent' },
+        ],
+      },
+    },
+  },
+  decorators: [
+    withThemeByDataAttribute({
+      themes: {
+        Light: 'light',
+        Dark: 'dark',
+      },
+      defaultTheme: 'Dark',
+      attributeName: 'data-theme',
+    }),
+    (story, context) => {
+      const { locale, accentColor } = context.globals as {
+        locale: string
+        accentColor?: string
+      }
+
+      // Set accent color from globals
+      if (accentColor) {
+        document.documentElement.style.setProperty('--accent-color', `var(--swatch-${accentColor})`)
+      } else {
+        document.documentElement.style.removeProperty('--accent-color')
+      }
+
+      return {
+        template: '<story />',
+        // Set locale from globals
+        created() {
+          if (this.$i18n) {
+            this.$i18n.setLocale(locale)
+          }
+        },
+        updated() {
+          if (this.$i18n) {
+            this.$i18n.setLocale(locale)
+          }
+        },
+      }
+    },
+  ],
+}
+
+export default preview

.vscode/settings.json

@@ -3,5 +3,9 @@
   "editor.formatOnSave": true,
   "i18n-ally.keystyle": "nested",
   "i18n-ally.localesPaths": ["./i18n/locales"],
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "explorer.fileNesting.enabled": true,
+  "explorer.fileNesting.patterns": {
+    "*.vue": "${capture}.stories.ts"
+  }
 }

CONTRIBUTING.md

@@ -60,6 +60,13 @@ This focus helps guide our project decisions as a community and what we choose t
   - [Lighthouse performance tests](#lighthouse-performance-tests)
   - [End to end tests](#end-to-end-tests)
   - [Test fixtures (mocking external APIs)](#test-fixtures-mocking-external-apis)
+- [Storybook](#storybook)
+  - [Component categories](#component-categories)
+  - [Coverage guidelines](#coverage-guidelines)
+  - [Project conventions](#project-conventions)
+  - [Configuration](#configuration)
+  - [Global app settings](#global-app-settings)
+  - [Known limitations](#known-limitations)
 - [Submitting changes](#submitting-changes)
   - [Before submitting](#before-submitting)
   - [Pull request process](#pull-request-process)
@@ -172,10 +179,11 @@ shared/                 # Shared between app and server
 └── types/              # TypeScript type definitions
 
 cli/                    # Local connector CLI (separate workspace)
+
 test/                   # Vitest tests
 ├── unit/               # Unit tests (*.spec.ts)
-└── nuxt/               # Nuxt component tests
-tests/                  # Playwright E2E tests
+├── nuxt/               # Nuxt component tests
+└── e2e/                # Playwright E2E tests
 ```
 
 > [!TIP]
@@ -458,6 +466,7 @@ The following scripts help manage translation files. `en.json` is the reference
 | `pnpm i18n:check:fix [locale]` | Same as check, but adds missing keys to other locales with English placeholders.                                                                                                        |
 | `pnpm i18n:report`             | Audits translation keys against code usage in `.vue` and `.ts` files. Reports missing keys (used in code but not in locale), unused keys (in locale but not in code), and dynamic keys. |
 | `pnpm i18n:report:fix`         | Removes unused keys from `en.json` and all other locale files.                                                                                                                          |
+| `pnpm i18n:schema`             | Generates a JSON Schema from `en.json` at `i18n/schema.json`. Locale files reference this schema for IDE validation and autocompletion.                                                 |
 
 ### Adding a new locale
 
@@ -885,6 +894,117 @@ The mock connector supports test endpoints for state manipulation:
 - `/__test__/user-packages` - Set user's packages
 - `/__test__/package` - Set package collaborators
 
+## Storybook
+
+Storybook is a development environment for UI components that helps catch UI changes and provides integrations for various testing types. For testing, Storybook offers:
+
+- **Accessibility tests** - Built-in a11y checks
+- **Visual tests** - Compare JPG screenshots
+- **Vitest tests** - Use stories directly in the unit tests
+
+### Component categories
+
+The plan is to organize components into 3 categories.
+
+#### UI Library Components
+
+Generic and reusable components used throughout the application.
+
+- Examples: Button, Input, Modal, Card
+- **Testing focus:** Props, variants, accessibility
+- **Coverage:** All variants and states
+
+#### Composite Components
+
+Single-use components that encapsulate one feature.
+
+- Examples: UserProfile, WeeklyDownloadStats
+- **Testing focus:** Integration patterns, user interactions
+- **Coverage:** Common usage scenarios
+
+#### Page Components
+
+**Full-page layouts** should match what the users see.
+
+- Examples: HomePage, Dashboard, CheckoutPage
+- **Testing focus:** Layout, responsive behavior, integration testing
+- **Coverage:** Critical user flows and breakpoints
+
+### Coverage guidelines
+
+#### Which Components Need Stories?
+
+TBD
+
+### Project conventions
+
+#### Place `.stories.ts` files next to the component
+
+```sh
+components/
+├── Button.vue
+└── Button.stories.ts
+```
+
+#### Story Template
+
+```ts
+// *.stories.ts
+import type { Meta, StoryObj } from '@storybook-vue/nuxt'
+import Component from './Button.vue'
+
+const meta = {
+  component: Component,
+  // component scope configuration goes here
+} satisfies Meta<typeof Component>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  // story scope configuration goes here
+}
+```
+
+#### JSDocs Annotation
+
+The component should include descriptive comments.
+
+```ts
+// Button.vue
+<script setup lang="ts">
+const props = withDefaults(
+  defineProps<{
+    /** Whether the button is disabled */
+    disabled?: boolean
+    /**
+     * HTML button type attribute
+     * @default "button"
+    type?: 'button' | 'submit'
+    // ...
+  }>)
+</script>
+```
+
+### Configuration
+
+Stories can be configured at three levels:
+
+- **Global scope** (`.storybook/preview.ts`) - Applies to all stories
+- **Component scope** - Applies to all stories for a specific component
+- **Story scope** - Applies to individual stories only
+
+### Global app settings
+
+Global application settings are added to the Storybook toolbar for easy testing and viewing. Configure these in `.storybook/preview.ts` under the `globalTypes` and `decorators` properties.
+
+### Known limitations
+
+- Changing `i18n` in the toolbar doesn't update the language. A manual story reload is required.
+- `autodocs` currently is non-functional due bugs, its usage is discouraged at this time.
+- `pnpm storybook` may log warnings or non-breaking errors for Nuxt modules due to the lack of mocks. If the UI renders correctly, these can be safely ignored.
+- Do not `import type` from `.vue` files. The `vue-docgen-api` parser used by `@storybook/addon-docs` cannot follow type imports across SFCs and will crash. Extract shared types into a separate `.ts` file instead.
+
 ## Submitting changes
 
 ### Before submitting