feat: add Storybook for backend-free UI work

.storybook/main.ts

@@ -0,0 +1,51 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { StorybookConfig } from '@storybook/nextjs'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.resolve(__dirname, '..')
+const srcDir = path.join(repoRoot, 'src')
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx|mdx)'],
+  addons: [],
+  framework: {
+    name: '@storybook/nextjs',
+    options: {
+      nextConfigPath: path.join(repoRoot, 'next.config.mjs'),
+    },
+  },
+  typescript: {
+    reactDocgen: false,
+  },
+  webpackFinal: async (config) => {
+    config.resolve = config.resolve ?? {}
+    config.resolve.alias = {
+      ...(config.resolve.alias ?? {}),
+      '@/contracts/argus-api': path.join(
+        srcDir,
+        'core/shared/contracts/argus-api.types.ts'
+      ),
+      '@/contracts/dashboard-api': path.join(
+        srcDir,
+        'core/shared/contracts/dashboard-api.types.ts'
+      ),
+      '@/contracts/infra-api': path.join(
+        srcDir,
+        'core/shared/contracts/infra-api.types.ts'
+      ),
+      '@': srcDir,
+      'next-safe-action/hooks$': path.join(
+        __dirname,
+        'mocks/next-safe-action-hooks.tsx'
+      ),
+      [path.join(srcDir, 'core/server/actions/key-actions')]: path.join(
+        __dirname,
+        'mocks/key-actions.ts'
+      ),
+    }
+    return config
+  },
+}
+
+export default config

.storybook/mocks/key-actions.ts

@@ -0,0 +1,6 @@
+// Storybook stub: prevents server-only deps from being bundled.
+// Real impl lives at src/core/server/actions/key-actions.ts.
+// The mocked useAction in next-safe-action-hooks.tsx never invokes these.
+export const createApiKeyAction = (() => {}) as unknown as never
+export const deleteApiKeyAction = (() => {}) as unknown as never
+export const updateApiKeyAction = (() => {}) as unknown as never

.storybook/mocks/next-safe-action-hooks.tsx

@@ -0,0 +1,75 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+} from 'react'
+
+export type MockActionMode =
+  | 'success'
+  | 'pending'
+  | 'server-error'
+  | 'idle'
+
+export const MockActionContext = createContext<MockActionMode>('success')
+
+interface MockHookOpts {
+  onSuccess?: (args: { data: unknown; input: unknown }) => void
+  onError?: (args: { error: { serverError?: string } }) => void
+}
+
+export function useAction(_action: unknown, opts: MockHookOpts = {}) {
+  const mode = useContext(MockActionContext)
+  const [isPending, setIsPending] = useState(false)
+
+  useEffect(() => {
+    setIsPending(false)
+  }, [mode])
+
+  const execute = useCallback(
+    (input: { name?: string; teamSlug?: string }) => {
+      if (mode === 'pending') {
+        setIsPending(true)
+        return
+      }
+
+      setIsPending(true)
+      window.setTimeout(() => {
+        setIsPending(false)
+        if (mode === 'server-error') {
+          opts.onError?.({
+            error: { serverError: 'Failed to create API key (story mock).' },
+          })
+          return
+        }
+
+        const safeName = (input?.name ?? 'demo')
+          .toLowerCase()
+          .replace(/[^a-z0-9]/g, '_')
+        opts.onSuccess?.({
+          data: {
+            createdApiKey: { key: `sb_${safeName}_demo123abc456def789ghi` },
+          },
+          input,
+        })
+      }, 600)
+    },
+    [mode, opts]
+  )
+
+  return {
+    execute,
+    executeAsync: execute,
+    isPending,
+    isExecuting: isPending,
+    status: isPending ? ('executing' as const) : ('idle' as const),
+    result: undefined,
+    reset: () => {},
+    hasSucceeded: false,
+    hasErrored: false,
+  }
+}
+
+export const useOptimisticAction = useAction
+export const useStateAction = useAction

.storybook/preview.tsx

@@ -0,0 +1,51 @@
+import type { Decorator, Preview } from '@storybook/nextjs'
+import { ThemeProvider } from 'next-themes'
+import { Toaster } from '@/ui/primitives/toaster'
+import { TooltipProvider } from '@/ui/primitives/tooltip'
+import {
+  type MockActionMode,
+  MockActionContext,
+} from './mocks/next-safe-action-hooks'
+import '../src/styles/globals.css'
+
+const withProviders: Decorator = (Story, ctx) => {
+  const actionMode =
+    (ctx.parameters?.actionMode as MockActionMode | undefined) ?? 'success'
+
+  return (
+    <ThemeProvider
+      attribute="class"
+      defaultTheme="dark"
+      enableSystem={false}
+      disableTransitionOnChange
+    >
+      <TooltipProvider>
+        <MockActionContext.Provider value={actionMode}>
+          <div className="bg-bg text-fg flex min-h-[100svh] flex-col items-center justify-center p-8">
+            <Story />
+          </div>
+          <Toaster />
+        </MockActionContext.Provider>
+      </TooltipProvider>
+    </ThemeProvider>
+  )
+}
+
+const preview: Preview = {
+  parameters: {
+    layout: 'fullscreen',
+    backgrounds: { disable: true },
+    nextjs: {
+      appDirectory: true,
+      navigation: {
+        params: { teamSlug: 'demo-team' },
+      },
+    },
+  },
+  decorators: [withProviders],
+  initialGlobals: {
+    backgrounds: { value: undefined },
+  },
+}
+
+export default preview