Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,45 @@
/**
* Smoke test for the Storybook-local i18next bootstrap (#62 Task F).
*
* The point of this test is to lock in the contract that the locale
* toolbar global drives a real `react-i18next` instance — not just html
* attributes — so future stories that call `useTranslation` resolve
* against the bundled `apps/web/public/locales` tree at the picked
* language. Failures here mean a story would render English even when
* the toolbar reads "DE", which is precisely the regression we're
* guarding against now that the locale picker is functional.
*/
import { describe, expect, it } from "vitest";
import { getStorybookI18n, setStorybookLocale } from "./i18n";
describe("storybook i18n bootstrap", () => {
it("seeds the `common` namespace for both shipped locales", () => {
const i18n = getStorybookI18n();
// `action.save` lives in `common.json` and is present in both EN + DE.
expect(i18n.hasResourceBundle("en", "common")).toBe(true);
expect(i18n.hasResourceBundle("de", "common")).toBe(true);
expect(i18n.getResource("en", "common", "action.save")).toBe("Save");
expect(i18n.getResource("de", "common", "action.save")).toBeTruthy();
});
it("switches language when the toolbar global flips", async () => {
const i18n = getStorybookI18n();
setStorybookLocale("de");
// changeLanguage is async; wait one microtask for the i18next promise.
await Promise.resolve();
expect(i18n.language).toBe("de");
setStorybookLocale("en");
await Promise.resolve();
expect(i18n.language).toBe("en");
});
it("falls back to the default locale for unknown values", async () => {
const i18n = getStorybookI18n();
// `ar` is registered as a toolbar item for RTL preview but we don't
// ship Arabic resources — the helper must coerce it back to the
// configured default so stories don't render empty keys.
setStorybookLocale("ar");
await Promise.resolve();
expect(["de", "en"]).toContain(i18n.language);
});
});
@@ -0,0 +1,67 @@
/**
* Minimal in-Storybook i18next instance (#62 Task F).
*
* Bootstraps a real (synchronous) i18next + react-i18next instance so the
* locale toolbar global has actual effect on stories that call
* `useTranslation`. Resources are inlined at build time via Vite's
* `import.meta.glob` against the apps/web public-locales tree, so we don't
* need an i18next-http-backend (Storybook has no Express loader to serve
* them from).
*
* Only a handful of namespaces are seeded — the ones today's 21 stories
* could plausibly reference (`common`, `translations`, `auth`, `errors`).
* Adding more is a one-line resource-map change.
*/
import i18next, { type i18n as I18n } from "i18next";
import { initReactI18next } from "react-i18next";
import { defaultLocale, i18nConfig, supportedLocales, type SupportedLocale } from "@toolctrl/i18n";
type LocaleResources = Record<string, Record<string, unknown>>;
type ResourceTree = Partial<Record<SupportedLocale | "ar", LocaleResources>>;
// Eager glob — Vite inlines every matched JSON at build time, which is fine
// for a 9-file, <100kB locale tree. The pattern resolves relative to this
// file: ../../../apps/web/public/locales/<locale>/<ns>.json.
const localeModules = import.meta.glob("../../../apps/web/public/locales/*/*.json", {
eager: true,
}) as Record<string, { default: Record<string, unknown> }>;
function buildResources(): ResourceTree {
const out: ResourceTree = {};
for (const [path, mod] of Object.entries(localeModules)) {
// path looks like ".../apps/web/public/locales/en/common.json"
const match = /\/locales\/([^/]+)\/([^/]+)\.json$/.exec(path);
if (!match) continue;
const [, locale, namespace] = match;
const bucket = (out[locale as SupportedLocale] ??= {});
bucket[namespace] = mod.default;
}
return out;
}
let cached: I18n | undefined;
export function getStorybookI18n(): I18n {
if (cached) return cached;
const resources = buildResources();
const instance = i18next.createInstance();
instance.use(initReactI18next).init({
...i18nConfig,
lng: defaultLocale,
resources: resources as Record<string, Record<string, Record<string, unknown>>>,
// Storybook stories run client-only — no SSR hydration concerns, so we
// can synchronously init. `react.useSuspense: false` already set in the
// shared config blocks suspending decorators.
initImmediate: false,
});
cached = instance;
return instance;
}
export function setStorybookLocale(locale: string): void {
const instance = getStorybookI18n();
const target = supportedLocales.includes(locale as SupportedLocale) ? locale : defaultLocale;
if (instance.language !== target) {
void instance.changeLanguage(target);
}
}
@@ -0,0 +1,58 @@
import path from "node:path";
import { fileURLToPath } from "node:url";
import { mergeConfig, type UserConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
import type { StorybookConfig } from "@storybook/react-vite";
const here = path.dirname(fileURLToPath(import.meta.url));
const webAppRoot = path.resolve(here, "../../../apps/web/app");
const config: StorybookConfig = {
stories: [
"../src/**/*.mdx",
"../src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui/src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui-app/src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui-subframe/src/**/*.stories.@(ts|tsx|mdx)",
"../../../packages/ui-mock/src/**/*.stories.@(ts|tsx|mdx)",
],
addons: [
"@storybook/addon-essentials",
"@storybook/addon-a11y",
"@storybook/addon-interactions",
"@storybook/addon-themes",
],
framework: {
name: "@storybook/react-vite",
options: {},
},
docs: {
autodocs: "tag",
},
typescript: {
check: false,
reactDocgen: false,
},
core: {
disableTelemetry: true,
},
// Mirror apps/web's Vite pipeline for the Tailwind-v4 surface so future
// stories can import the real components from packages/ui / apps/web
// instead of the temporary `_demo-primitives.tsx`. Today's 21 stories
// use inline-styles + CSS-variable tokens declared in `preview.css`, so
// adding the Tailwind plugin is a no-op for them but unblocks the
// migration path. See docs/improvement-plan/08-mobile-cli-storybook-sdk/storybook.md
// ("real Tailwind-v4 preview pipeline" deviation).
async viteFinal(viteConfig) {
return mergeConfig(viteConfig, {
plugins: [tailwindcss()],
resolve: {
alias: {
"~": webAppRoot,
},
},
} satisfies UserConfig);
},
};
export default config;
@@ -0,0 +1,180 @@
/*
* Storybook preview stylesheet.
*
* Layered as:
* 1. `@import "tailwindcss"` — pulls the full Tailwind v4 runtime via the
* @tailwindcss/vite plugin wired in `.storybook/main.ts`. This unlocks
* Tailwind utility classes inside stories that import real
* `packages/ui` / `apps/web` components. Today's 21 stories use inline
* styles + the CSS-variable tokens declared further down, so the
* Tailwind import is additive — no visual change to existing stories.
* 2. `@custom-variant dark` — mirrors apps/web/app/globals.css so the
* `dark:` utility flips alongside the `.dark` root class that
* `withThemeByClassName` applies from the theme toolbar global.
* 3. The CSS-variable token block below — the design-token surface the
* existing demo primitives (`_demo-primitives.tsx`) read via
* `var(--color-primary)` etc. Kept verbatim so the 21 in-flight
* stories stay visually stable while the real-component migration
* ramps up (#62 follow-up).
*
* The web app's full theme (HSL channel system, Tremor palette, typography
* scale) lives in apps/web/app/globals.css; we keep the Storybook surface
* intentionally narrow so the preview builds quickly and stays readable.
*/
@import "tailwindcss";
/*
* Subframe design-system theme + content sources.
* Storybook runs its own Tailwind-v4 pipeline rooted at apps/storybook, so it neither loads
* the Subframe theme tokens nor scans the Subframe component files in apps/web/app. Without
* these, Subframe-backed components (Button, TextInput, …) render unstyled here and in
* lostpixel visual regression. Mirror apps/web/app/globals.css's Subframe wiring.
*/
@import "../../../apps/web/app/ui/theme.css";
@source "../../../apps/web/app/ui";
@source "../../../apps/web/app/components/ui";
@custom-variant dark (&:is(.dark *));
/*
* apps/web design-token surface (#62 follow-up).
*
* Mirrors apps/web/app/globals.css so real shadcn components imported from
* apps/web/app/components/ui resolve `bg-primary`, `text-foreground`,
* `border-border`, etc. The HSL channel system + `@theme inline` mapping is
* load-bearing for the cva variants in those components.
*
* The legacy `--color-bg`/`--color-fg`/etc. block at the bottom is kept for
* backward compatibility with un-migrated demo primitives.
*/
:root {
--background: hsl(0 0% 100%);
--foreground: hsl(240 10% 3.9%);
--muted: hsl(240 4.8% 95.9%);
--muted-foreground: hsl(240 3.8% 46.1%);
--popover: hsl(0 0% 100%);
--popover-foreground: hsl(240 10% 3.9%);
--card: hsl(0 0% 100%);
--card-foreground: hsl(240 10% 3.9%);
--border: hsl(240 5.9% 90%);
--input: hsl(240 5.9% 90%);
--primary: hsl(240 5.9% 10%);
--primary-foreground: hsl(0 0% 98%);
--secondary: hsl(240 4.8% 95.9%);
--secondary-foreground: hsl(240 5.9% 10%);
--accent: hsl(240 4.8% 95.9%);
--accent-foreground: hsl(240 5.9% 10%);
--destructive: hsl(0 84.2% 60.2%);
--destructive-foreground: hsl(0 0% 98%);
--ring: hsl(240 5.9% 10%);
--radius: 0.5rem;
/* Legacy demo-primitive tokens (kept for un-migrated stories). */
--color-bg: #ffffff;
--color-fg: #0f172a;
--color-muted: #64748b;
--color-border: #e2e8f0;
--color-success: #16a34a;
--color-warning: #d97706;
color-scheme: light;
}
.dark {
--background: hsl(240 10% 3.9%);
--foreground: hsl(0 0% 98%);
--muted: hsl(240 3.7% 15.9%);
--muted-foreground: hsl(240 5% 64.9%);
--popover: hsl(240 10% 3.9%);
--popover-foreground: hsl(0 0% 98%);
--card: hsl(240 10% 3.9%);
--card-foreground: hsl(0 0% 98%);
--border: hsl(240 3.7% 15.9%);
--input: hsl(240 3.7% 15.9%);
--primary: hsl(0 0% 98%);
--primary-foreground: hsl(240 5.9% 10%);
--secondary: hsl(240 3.7% 15.9%);
--secondary-foreground: hsl(0 0% 98%);
--accent: hsl(240 3.7% 15.9%);
--accent-foreground: hsl(0 0% 98%);
--destructive: hsl(0 62.8% 30.6%);
--destructive-foreground: hsl(0 0% 98%);
--ring: hsl(240 4.9% 83.9%);
/* Legacy demo-primitive tokens (kept for un-migrated stories). */
--color-bg: #0b0b0c;
--color-fg: #f8fafc;
--color-muted: #94a3b8;
--color-border: #1f2937;
color-scheme: dark;
}
@theme inline {
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
}
html,
body {
background: var(--color-bg);
color: var(--color-fg);
font-family:
Inter,
ui-sans-serif,
system-ui,
-apple-system,
BlinkMacSystemFont,
"Segoe UI",
sans-serif;
margin: 0;
}
/*
* Coarse Tailwind-like helpers retained so the preview's `withWrapper`
* decorator works even if a story disables the Tailwind pipeline via
* `parameters.tailwind.disable` (escape hatch — none in use today). When
* the Tailwind v4 plugin is active these are shadowed by the real utility
* generation, so removing them is safe once we're confident no stories
* rely on the bespoke definitions.
*/
.font-sans {
font-family:
Inter,
ui-sans-serif,
system-ui,
sans-serif;
}
.text-sm {
font-size: 0.875rem;
}
.text-foreground {
color: var(--color-fg);
}
.bg-background {
background: var(--color-bg);
}
.min-h-\[60px\] {
min-height: 60px;
}
.p-6 {
padding: 1.5rem;
}
@@ -0,0 +1,126 @@
import type { Preview, Decorator } from "@storybook/react";
import { withThemeByClassName } from "@storybook/addon-themes";
import React from "react";
import { I18nextProvider } from "react-i18next";
import { getDirection, supportedLocales } from "@toolctrl/i18n";
import { getStorybookI18n, setStorybookLocale } from "./i18n";
import "./preview.css";
const LOCALE_TOOLBAR_DESCRIPTION = "Active language - flips Tailwind rtl: variants, <html lang/dir>, and the in-canvas i18next instance";
const RTL_PREVIEW_TITLE = "AR (RTL preview)";
// i18n decorator (#62 Task F + #72 i18n-foundation).
//
// Two responsibilities:
// 1. Sync `<html lang>` / `<html dir>` so any `rtl:` Tailwind variants
// light up exactly as they would in the running app.
// 2. Switch the in-canvas i18next instance to the picked locale and wrap
// every story in `<I18nextProvider>` so `useTranslation` calls in
// future stories (and any real `packages/ui` components we import
// once the Tailwind v4 pipeline is wired) resolve against the seeded
// `apps/web/public/locales` tree.
//
// The instance is lazy-built on first render — for the existing 21 stories
// (none of which call `useTranslation`) this is effectively a no-op beyond
// updating the html attributes.
const withLocale: Decorator = (Story, context) => {
const locale = (context.globals.locale ?? "en") as string;
const dir = getDirection(locale);
if (typeof document !== "undefined") {
document.documentElement.setAttribute("lang", locale);
document.documentElement.setAttribute("dir", dir);
}
setStorybookLocale(locale);
const i18n = getStorybookI18n();
return (
<I18nextProvider i18n={i18n}>
<Story />
</I18nextProvider>
);
};
const withWrapper: Decorator = (Story) => (
<div className="text-foreground bg-background min-h-[60px] p-6 font-sans text-sm">
<Story />
</div>
);
const preview: Preview = {
parameters: {
layout: "padded",
controls: {
matchers: {
color: /(background|color)$/i,
date: /Date$/i,
},
},
backgrounds: {
default: "light",
values: [
{ name: "light", value: "#ffffff" },
{ name: "dark", value: "#0b0b0c" },
],
},
a11y: {
// WCAG-2.2-AA target ruleset for live in-Storybook accessibility
// feedback. Mirrors packages/ui-app/test-setup/axe.ts so devs see the
// same violations during design as their unit tests will catch.
//
// Disable per-story only with `parameters.a11y.disable = true` and a
// code-comment justification. Spec:
// docs/improvement-plan/10-compliance-polish/wcag-internal.md
element: "#storybook-root",
manual: false,
config: {
rules: [
// High-signal contrast rule — Storybook can compute real CSS so we
// keep it enabled (jsdom can't, which is why vitest-axe disables it).
{ id: "color-contrast", enabled: true },
{ id: "color-contrast-enhanced", enabled: false },
// Region landmarks aren't meaningful for an isolated component
// story; verified separately by route-level audits.
{ id: "region", enabled: false },
],
},
options: {
runOnly: {
type: "tag",
values: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa", "best-practice"],
},
reporter: "v2",
},
},
},
globalTypes: {
locale: {
name: "Locale",
description: LOCALE_TOOLBAR_DESCRIPTION,
defaultValue: "en",
toolbar: {
icon: "globe",
items: [
...supportedLocales.map((code) => ({ value: code, title: code.toUpperCase() })),
// RTL preview locale. We don't ship Arabic translations yet, but
// the decorator still flips direction so we can spot layout breaks.
{ value: "ar", title: RTL_PREVIEW_TITLE },
],
showName: true,
dynamicTitle: true,
},
},
},
decorators: [
// `withThemeByClassName` registers its own `theme` global + toolbar item
// (key `theme`, values `light`/`dark`) and applies the class to <html>.
// We intentionally don't re-declare it in `globalTypes` above to avoid
// a duplicate toolbar entry — the addon owns that surface.
withThemeByClassName({
themes: { light: "light", dark: "dark" },
defaultTheme: "light",
}),
withLocale,
withWrapper,
],
};
export default preview;
@@ -0,0 +1,53 @@
/**
* Storybook test-runner configuration (Phase 08 #62).
*
* The test-runner spins up Playwright + Chromium, walks every story
* registered in `main.ts`, and applies the `postVisit` hook below to
* each one. The hook re-runs the same axe-rules ruleset the in-canvas
* `@storybook/addon-a11y` panel uses (see `.storybook/preview.tsx`)
* but in a real headless Chromium where `color-contrast` actually
* resolves CSS — failures here are real WCAG-2.2-AA regressions and
* MUST be fixed (or explicitly opted-out via `parameters.a11y.disable
* = true` with a justification comment in the story).
*
* The `getStoryContext` / `injectAxe` / `checkA11y` triple is the
* documented integration recipe; we override the axe-context to the
* Storybook root so out-of-frame chrome (toolbar etc.) is ignored.
*/
import type { TestRunnerConfig } from "@storybook/test-runner";
import { getStoryContext } from "@storybook/test-runner";
import { checkA11y, configureAxe, injectAxe } from "axe-playwright";
const config: TestRunnerConfig = {
async preVisit(page) {
await injectAxe(page);
},
async postVisit(page, context) {
const storyContext = await getStoryContext(page, context);
const a11yParameter = (storyContext.parameters as {
a11y?: { disable?: boolean; config?: unknown; options?: unknown };
}).a11y;
if (a11yParameter?.disable) {
return;
}
if (a11yParameter?.config || a11yParameter?.options) {
await configureAxe(page, {
rules: ((a11yParameter.config as { rules?: unknown[] } | undefined)?.rules ?? []) as never[],
});
}
await checkA11y(page, "#storybook-root", {
detailedReport: true,
detailedReportOptions: { html: true },
axeOptions: a11yParameter?.options as Parameters<typeof checkA11y>[2] extends infer T
? T extends { axeOptions?: infer A }
? A
: undefined
: undefined,
});
},
};
export default config;