Track HiveGrid Cloud planning reference
No files matched your search
@@ -0,0 +1,7 @@
|
||||
storybook-static/
|
||||
*.log
|
||||
|
||||
# Lost-Pixel generated comparison output. Only the baseline/ tree is
|
||||
# committed — current/ and difference/ are per-run artifacts.
|
||||
.lostpixel/current/
|
||||
.lostpixel/difference/
|
||||
@@ -0,0 +1,2 @@
|
||||
current
|
||||
difference
|
||||
|
After Width: | Height: | Size: 6.2 KiB |
|
After Width: | Height: | Size: 5.9 KiB |
|
After Width: | Height: | Size: 5.5 KiB |
|
After Width: | Height: | Size: 6.3 KiB |
|
After Width: | Height: | Size: 5.4 KiB |
|
After Width: | Height: | Size: 5.8 KiB |
|
After Width: | Height: | Size: 6.3 KiB |
|
After Width: | Height: | Size: 6.5 KiB |
|
After Width: | Height: | Size: 7.4 KiB |
|
After Width: | Height: | Size: 5.2 KiB |
|
After Width: | Height: | Size: 5.4 KiB |
|
After Width: | Height: | Size: 5.3 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 7.8 KiB |
|
After Width: | Height: | Size: 5.3 KiB |
|
After Width: | Height: | Size: 9.8 KiB |
|
After Width: | Height: | Size: 7.7 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 7.1 KiB |
|
After Width: | Height: | Size: 5.3 KiB |
|
After Width: | Height: | Size: 6.0 KiB |
|
After Width: | Height: | Size: 8.5 KiB |
|
After Width: | Height: | Size: 8.3 KiB |
|
After Width: | Height: | Size: 9.6 KiB |
|
After Width: | Height: | Size: 7.4 KiB |
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 6.7 KiB |
|
After Width: | Height: | Size: 6.7 KiB |
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 6.6 KiB |
|
After Width: | Height: | Size: 7.4 KiB |
|
After Width: | Height: | Size: 7.5 KiB |
|
After Width: | Height: | Size: 5.7 KiB |
|
After Width: | Height: | Size: 9.3 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 6.3 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 6.6 KiB |
|
After Width: | Height: | Size: 7.3 KiB |
|
After Width: | Height: | Size: 7.3 KiB |
|
After Width: | Height: | Size: 7.3 KiB |
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 8.1 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 9.7 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 9.7 KiB |
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 6.0 KiB |
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 6.4 KiB |
|
After Width: | Height: | Size: 6.5 KiB |
|
After Width: | Height: | Size: 5.5 KiB |
|
After Width: | Height: | Size: 6.3 KiB |
|
After Width: | Height: | Size: 6.6 KiB |
|
After Width: | Height: | Size: 4.6 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 28 KiB |
|
After Width: | Height: | Size: 6.3 KiB |
|
After Width: | Height: | Size: 20 KiB |
@@ -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;
|
||||
@@ -0,0 +1,35 @@
|
||||
# `@toolctrl/storybook`
|
||||
|
||||
Aggregated Storybook for the boilerplate UI packages (`@toolctrl/ui`,
|
||||
`@toolctrl/ui-app`, `@toolctrl/ui-subframe`, `@toolctrl/ui-mock`).
|
||||
|
||||
## Run locally
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm --filter @toolctrl/storybook storybook
|
||||
# -> http://localhost:6006
|
||||
```
|
||||
|
||||
## Build static site
|
||||
|
||||
```bash
|
||||
pnpm --filter @toolctrl/storybook build-storybook
|
||||
# -> apps/storybook/storybook-static
|
||||
```
|
||||
|
||||
## Where do stories live?
|
||||
|
||||
Stories are **co-located** in each UI package:
|
||||
|
||||
```
|
||||
packages/ui/src/stories/*.stories.tsx
|
||||
packages/ui-app/src/stories/*.stories.tsx
|
||||
packages/ui-subframe/src/stories/*.stories.tsx
|
||||
packages/ui-mock/src/stories/*.stories.tsx
|
||||
```
|
||||
|
||||
`apps/storybook/.storybook/main.ts` aggregates them via globs — adding a new
|
||||
story file is enough, no manual registration.
|
||||
|
||||
See `docs/architecture/storybook.md` for the full guide.
|
||||
@@ -0,0 +1,50 @@
|
||||
/**
|
||||
* Lost-Pixel visual-regression config (Phase 08 #62).
|
||||
*
|
||||
* Lost-Pixel walks the built static Storybook, screenshots every story,
|
||||
* and diffs each shot against a committed baseline under
|
||||
* `.lostpixel/baseline/`. A pixel-diff above `threshold` fails CI and
|
||||
* uploads the diff image as an artifact.
|
||||
*
|
||||
* NOT enabled in CI yet — the `visual-regression` job in
|
||||
* `.github/workflows/storybook.yml` / `.gitea/workflows/storybook.yml`
|
||||
* is gated on the baseline directory being populated. An operator runs
|
||||
* `pnpm --filter @toolctrl/storybook visual-regression:update` once
|
||||
* against a known-good build and commits the generated baseline PNGs;
|
||||
* from then on the job blocks PRs on unintended visual drift.
|
||||
*
|
||||
* See docs/architecture/storybook.md § Visual-regression for the
|
||||
* bootstrap runbook.
|
||||
*/
|
||||
import type { CustomProjectConfig } from "lost-pixel";
|
||||
|
||||
export const config: CustomProjectConfig = {
|
||||
// Point at the static build produced by `build-storybook`. Lost-Pixel
|
||||
// serves it itself, so this is a path, not a URL.
|
||||
storybookShots: {
|
||||
storybookUrl: "./storybook-static",
|
||||
},
|
||||
|
||||
// Baseline PNGs live in-repo so a diff is reviewable in the PR.
|
||||
imagePathBaseline: "./.lostpixel/baseline",
|
||||
imagePathCurrent: "./.lostpixel/current",
|
||||
imagePathDifference: "./.lostpixel/difference",
|
||||
|
||||
// 0.1 % pixel-diff tolerance — absorbs sub-pixel font AA jitter
|
||||
// between CI runners without masking real layout regressions.
|
||||
threshold: 0.001,
|
||||
|
||||
// Lower than the default so CI doesn't stall on a cold cache; the
|
||||
// story set is small (~21 stories).
|
||||
waitBeforeScreenshot: 500,
|
||||
|
||||
// Generate the comparison even when there is no baseline yet so the
|
||||
// first operator run produces a full baseline set.
|
||||
generateOnly: false,
|
||||
|
||||
// CI integration is opt-in; left unset so a local run never tries to
|
||||
// post to an external service.
|
||||
// apiKey / setPendingStatusCheck deliberately omitted.
|
||||
};
|
||||
|
||||
export default config;
|
||||
@@ -0,0 +1,50 @@
|
||||
{
|
||||
"name": "@toolctrl/storybook",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"storybook": "storybook dev -p 6006 --no-open",
|
||||
"build-storybook": "storybook build -o storybook-static",
|
||||
"test:storybook": "test-storybook --config-dir .storybook --url ${TARGET_URL:-http://127.0.0.1:6006}",
|
||||
"visual-regression": "lost-pixel",
|
||||
"visual-regression:update": "lost-pixel update",
|
||||
"typecheck": "tsc -p tsconfig.json --noEmit"
|
||||
},
|
||||
"dependencies": {
|
||||
"@radix-ui/react-avatar": "^1.1.11",
|
||||
"@radix-ui/react-slot": "^1.2.4",
|
||||
"@toolctrl/i18n": "workspace:*",
|
||||
"class-variance-authority": "^0.7.1",
|
||||
"clsx": "^2.1.1",
|
||||
"tailwind-merge": "^3.5.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@storybook/addon-a11y": "^8.6.14",
|
||||
"@storybook/addon-essentials": "^8.6.14",
|
||||
"@storybook/addon-interactions": "^8.6.14",
|
||||
"@storybook/addon-themes": "^8.6.14",
|
||||
"@storybook/blocks": "^8.6.14",
|
||||
"@storybook/react": "^8.6.14",
|
||||
"@storybook/react-vite": "^8.6.14",
|
||||
"@storybook/test": "^8.6.14",
|
||||
"@storybook/test-runner": "^0.22.1",
|
||||
"@tailwindcss/vite": "4.2.4",
|
||||
"@types/react": "^19.0.8",
|
||||
"@types/react-dom": "^19.0.0",
|
||||
"axe-playwright": "^2.1.0",
|
||||
"http-server": "^14.1.1",
|
||||
"i18next": "^23.16.3",
|
||||
"lost-pixel": "^3.22.0",
|
||||
"react-i18next": "^15.7.4",
|
||||
"storybook": "^8.6.14",
|
||||
"tailwindcss": "^4.1.12",
|
||||
"typescript": "^5.3.2",
|
||||
"vite": "7.3.0",
|
||||
"wait-on": "^9.0.0"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"react": "19.2.3",
|
||||
"react-dom": "19.2.3"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
import { Meta } from "@storybook/blocks";
|
||||
|
||||
<Meta title="welcome/introduction" />
|
||||
|
||||
# Toolctrl UI — Storybook
|
||||
|
||||
This Storybook aggregates components from the four UI packages of the
|
||||
boilerplate:
|
||||
|
||||
| Package | Layer | Notes |
|
||||
| --- | --- | --- |
|
||||
| `@toolctrl/ui` | base primitives | shadcn / radix wrappers |
|
||||
| `@toolctrl/ui-app` | composites | tenant-app shell pieces |
|
||||
| `@toolctrl/ui-subframe` | designer output | Subframe-generated components |
|
||||
| `@toolctrl/ui-mock` | fixtures | mock pages + sample data for hot-swap drills |
|
||||
|
||||
Use the sidebar to browse component stories. Each story exposes its props as
|
||||
Controls and runs an **a11y check** via `@storybook/addon-a11y`.
|
||||
|
||||
## Conventions
|
||||
|
||||
- **CSF-3** — every story file exports a default `Meta` plus named story
|
||||
objects.
|
||||
- **Co-located** — stories live next to the source in
|
||||
`packages/<pkg>/src/stories/`.
|
||||
- **Pure renders** — stories should not depend on the running web app; pull
|
||||
fixtures from `@toolctrl/ui-mock` when needed.
|
||||
- **A11y** — violations fail the story; opt-out with
|
||||
`parameters: { a11y: { disable: true } }` plus a code comment explaining
|
||||
why.
|
||||
|
||||
See `docs/architecture/storybook.md` for the full author guide.
|
||||
@@ -0,0 +1,44 @@
|
||||
import { Meta } from "@storybook/blocks";
|
||||
|
||||
<Meta title="welcome/theme-guide" />
|
||||
|
||||
# Theme Guide
|
||||
|
||||
The Storybook preview ships a minimal token surface in
|
||||
`apps/storybook/.storybook/preview.css` so stories can render with theme
|
||||
parity to the web app without compiling Tailwind v4 at story-build time.
|
||||
|
||||
## Available CSS variables
|
||||
|
||||
| Token | Light | Dark |
|
||||
| --- | --- | --- |
|
||||
| `--color-bg` | `#ffffff` | `#0b0b0c` |
|
||||
| `--color-fg` | `#0f172a` | `#f8fafc` |
|
||||
| `--color-muted` | `#64748b` | `#94a3b8` |
|
||||
| `--color-border` | `#e2e8f0` | `#1f2937` |
|
||||
| `--color-primary` | `#2563eb` | `#60a5fa` |
|
||||
| `--color-primary-foreground` | `#ffffff` | `#0b0b0c` |
|
||||
| `--color-destructive` | `#dc2626` | `#f87171` |
|
||||
| `--color-destructive-foreground` | `#ffffff` | `#0b0b0c` |
|
||||
| `--color-accent` | `#f1f5f9` | `#1e293b` |
|
||||
| `--color-accent-foreground` | `#0f172a` | `#f8fafc` |
|
||||
| `--color-card` | `#ffffff` | `#111827` |
|
||||
| `--color-card-foreground` | `#0f172a` | `#f8fafc` |
|
||||
| `--color-success` | `#16a34a` | `#16a34a` |
|
||||
| `--color-warning` | `#d97706` | `#d97706` |
|
||||
|
||||
## Light / Dark toggle
|
||||
|
||||
The toolbar exposes a theme switcher (powered by
|
||||
`@storybook/addon-themes`) that toggles the `dark` class on the preview
|
||||
root. Stories using the variables above flip automatically.
|
||||
|
||||
## Roadmap
|
||||
|
||||
- Wire the real `apps/web/app/globals.css` (Tailwind v4) into the preview
|
||||
once the v4 + Storybook 8 builder integration is verified for our React
|
||||
Router runtime.
|
||||
- Add brand-tenant toolbar globals so stories can preview against the
|
||||
`packages/brand/themes/` palettes.
|
||||
|
||||
See `docs/architecture/storybook.md` for the author guide.
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ESNext",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "Bundler",
|
||||
"lib": ["DOM", "DOM.Iterable", "ES2022"],
|
||||
"jsx": "react-jsx",
|
||||
"strict": true,
|
||||
"skipLibCheck": true,
|
||||
"isolatedModules": true,
|
||||
"esModuleInterop": true,
|
||||
"resolveJsonModule": true,
|
||||
"allowImportingTsExtensions": false,
|
||||
"noEmit": true,
|
||||
"types": ["vite/client"],
|
||||
"baseUrl": "."
|
||||
},
|
||||
"include": [".storybook/**/*.ts", ".storybook/**/*.tsx", "src/**/*.ts", "src/**/*.tsx", "src/**/*.mdx", "lostpixel.config.ts"]
|
||||
}
|
||||