noecosystem-design 0.1.0

package/apps/showcase/src/catalog/catalog-shell.browser.test.tsx

@@ -0,0 +1,73 @@
+import { expect, test } from 'vitest';
+import { render } from 'vitest-browser-react';
+import type { CatalogEntry } from './catalog-index';
+import { CatalogShell } from './catalog-shell';
+
+const entries: CatalogEntry[] = [
+  {
+    id: 'dialog',
+    category: 'Overlays',
+    status: 'available',
+    name: 'Dialog',
+    description: 'Direction-preserving modal primitive.',
+    package: '@noe/ui',
+    registryItem: 'dialog',
+    preview: () => <span>Dialog preview</span>,
+  },
+  {
+    id: 'button',
+    category: 'Primitives / Actions',
+    status: 'available',
+    name: 'Button',
+    description: 'Primary action primitive.',
+    package: '@noe/ui',
+    registryItem: 'button',
+    preview: () => <span>Button preview</span>,
+  },
+  {
+    id: 'select',
+    category: 'Primitives / Forms',
+    status: 'planned',
+    name: 'Select',
+    description: 'Not yet adopted.',
+    package: '@noe/ui',
+    registryItem: null,
+    preview: () => <span>Select preview</span>,
+  },
+];
+
+test('filters the component inventory and exposes the selected audit state', async () => {
+  const screen = await render(<CatalogShell initialEntries={entries} />);
+
+  await expect.element(screen.getByRole('heading', { name: 'Dialog' })).toBeVisible();
+  await expect.element(screen.getByRole('heading', { name: 'Button' })).toBeVisible();
+
+  const search = screen.getByRole('searchbox', { name: /search components/i });
+  await search.fill('dialog');
+
+  await expect.element(screen.getByRole('heading', { name: 'Dialog' })).toBeVisible();
+  await expect.element(screen.getByRole('heading', { name: 'Button' })).not.toBeInTheDocument();
+});
+
+test('opens a component detail view and returns to the grid', async () => {
+  const screen = await render(<CatalogShell initialEntries={entries} />);
+
+  await screen
+    .getByRole('button', { name: /view details/i })
+    .first()
+    .click();
+  await expect.element(screen.getByRole('heading', { level: 2 })).toBeVisible();
+
+  await screen.getByRole('button', { name: /back to catalog/i }).click();
+  await expect.element(screen.getByRole('heading', { name: 'Dialog' })).toBeVisible();
+});
+
+test('switching locale to Persian updates document direction to rtl', async () => {
+  const screen = await render(<CatalogShell initialEntries={entries} />);
+
+  const localeSelect = screen.getByRole('combobox').nth(1);
+  await localeSelect.selectOptions('fa');
+
+  await expect.poll(() => document.documentElement.dir).toBe('rtl');
+  await expect.poll(() => document.documentElement.lang).toBe('fa');
+});

package/apps/showcase/src/catalog/catalog-shell.tsx

@@ -0,0 +1,506 @@
+import * as React from 'react';
+
+import { DirectionProvider } from '@noe/ui';
+import type { Direction, DirectionOverride, LocaleCode } from '@noe/i18n';
+import { applyDocumentLocale, getLocaleMetadata, pseudoLocalize } from '@noe/i18n';
+
+import {
+  catalogCategories,
+  catalogEntries,
+  type CatalogEntry,
+  type CatalogStatus,
+} from './catalog-index';
+import { getMessages } from '@noe/i18n';
+
+const statusLabelKey: Record<CatalogStatus, string> = {
+  available: 'catalog.status.available',
+  'in-progress': 'catalog.status.inProgress',
+  planned: 'catalog.status.planned',
+  partial: 'catalog.status.planned',
+  experimental: 'catalog.status.inProgress',
+};
+
+const statusBadgeClassName: Record<CatalogStatus, string> = {
+  available: 'border-success/30 bg-success/10 text-success',
+  'in-progress': 'border-warning/40 bg-warning/15 text-warning-foreground',
+  planned: 'border-border bg-muted text-muted-foreground',
+  partial: 'border-warning/40 bg-warning/15 text-warning-foreground',
+  experimental: 'border-border bg-muted text-muted-foreground',
+};
+
+function readParam(name: string): string | null {
+  if (typeof window === 'undefined') return null;
+  return new URLSearchParams(window.location.search).get(name);
+}
+
+function writeParams(next: Record<string, string | null>) {
+  if (typeof window === 'undefined') return;
+  const params = new URLSearchParams(window.location.search);
+  for (const [key, value] of Object.entries(next)) {
+    if (value === null || value === '') params.delete(key);
+    else params.set(key, value);
+  }
+  const query = params.toString();
+  window.history.replaceState(null, '', query ? `?${query}` : window.location.pathname);
+}
+
+export interface CatalogShellProps {
+  initialEntries?: readonly CatalogEntry[];
+}
+
+export function CatalogShell({ initialEntries = catalogEntries }: CatalogShellProps) {
+  const [locale, setLocale] = React.useState<LocaleCode>(
+    () => (readParam('locale') as LocaleCode | null) ?? 'en',
+  );
+  const [directionOverride, setDirectionOverride] = React.useState<DirectionOverride>(
+    () => (readParam('direction') as DirectionOverride | null) ?? 'auto',
+  );
+  const [effectiveLocale, setEffectiveLocale] = React.useState<LocaleCode>(() => {
+    const initial = (readParam('locale') as LocaleCode | null) ?? 'en';
+    return initial === 'fa' ? 'en' : initial;
+  });
+  const [theme, setTheme] = React.useState<'light' | 'dark'>(
+    () => (readParam('theme') as 'light' | 'dark' | null) ?? 'light',
+  );
+  const [search, setSearch] = React.useState(() => readParam('q') ?? '');
+  const [category, setCategory] = React.useState<string>(() => readParam('category') ?? 'all');
+  const [statusFilter, setStatusFilter] = React.useState<CatalogStatus | 'all'>('all');
+  const [selectedId, setSelectedId] = React.useState<string | null>(() => readParam('component'));
+
+  const localeMeta = getLocaleMetadata(effectiveLocale);
+  const direction: Direction =
+    directionOverride === 'auto' ? localeMeta.direction : directionOverride;
+  const baseMessages: Record<string, string> = getMessages(effectiveLocale) as unknown as Record<
+    string,
+    string
+  >;
+
+  const t = React.useCallback(
+    (key: string) => {
+      const raw = baseMessages[key] ?? key;
+      return localeMeta.pseudo ? pseudoLocalize(raw, localeMeta.pseudo) : raw;
+    },
+    [baseMessages, localeMeta.pseudo],
+  );
+
+  React.useEffect(() => {
+    if (locale !== 'fa') {
+      setEffectiveLocale(locale);
+      return;
+    }
+    if (effectiveLocale === 'fa') return;
+    let cancelled = false;
+    const fontSpec = '16px IRANYekanX';
+    const FONT_TIMEOUT_MS = 3000;
+    const check = () => {
+      try {
+        return (
+          typeof document !== 'undefined' &&
+          (document as unknown as { fonts?: { check: (s: string) => boolean } }).fonts?.check(fontSpec) === true
+        );
+      } catch {
+        return false;
+      }
+    };
+    const markReady = () => {
+      if (!cancelled) setEffectiveLocale('fa');
+    };
+    if (check()) {
+      markReady();
+      return;
+    }
+    const hasLoad = typeof document !== 'undefined' && typeof (document as unknown as { fonts?: { load: (s: string) => Promise<unknown> } }).fonts?.load === 'function';
+    if (hasLoad) {
+      let timedOut = false;
+      const timeoutId = setTimeout(() => {
+        timedOut = true;
+        // keep English on timeout — do not activate Persian without confirmed font
+      }, FONT_TIMEOUT_MS);
+      (document as unknown as { fonts: { load: (s: string) => Promise<unknown> } }).fonts
+        .load(fontSpec)
+        .then(() => {
+          clearTimeout(timeoutId);
+          if (timedOut || cancelled) return;
+          if (check()) markReady();
+        })
+        .catch(() => {
+          clearTimeout(timeoutId);
+        });
+      return () => {
+        cancelled = true;
+        clearTimeout(timeoutId);
+      };
+    } else {
+      // Unsupported Font Loading API — keep English, do not switch to Persian
+      return () => {
+        cancelled = true;
+      };
+    }
+  }, [locale, effectiveLocale]);
+
+  React.useLayoutEffect(() => {
+    applyDocumentLocale(document.documentElement, effectiveLocale, directionOverride);
+    document.documentElement.dataset.theme = theme;
+  }, [effectiveLocale, directionOverride, theme]);
+
+  React.useEffect(() => {
+    writeParams({
+      locale,
+      direction: directionOverride === 'auto' ? null : directionOverride,
+      theme: theme === 'light' ? null : theme,
+      q: search || null,
+      category: category === 'all' ? null : category,
+      component: selectedId,
+    });
+  }, [locale, directionOverride, theme, search, category, selectedId]);
+
+  const filtered = React.useMemo(() => {
+    const needle = search.trim().toLowerCase();
+    return initialEntries.filter((entry) => {
+      if (category !== 'all' && entry.category !== category) return false;
+      if (statusFilter !== 'all' && entry.status !== statusFilter) return false;
+      if (!needle) return true;
+      return (
+        entry.name.toLowerCase().includes(needle) ||
+        entry.description.toLowerCase().includes(needle) ||
+        entry.category.toLowerCase().includes(needle) ||
+        entry.id.includes(needle)
+      );
+    });
+  }, [initialEntries, search, category, statusFilter]);
+
+  const selectedEntry = selectedId ? initialEntries.find((entry) => entry.id === selectedId) : null;
+
+  const counts = React.useMemo(() => {
+    const result: Record<CatalogStatus, number> = {
+      available: 0,
+      'in-progress': 0,
+      planned: 0,
+      partial: 0,
+      experimental: 0,
+    };
+    for (const entry of initialEntries) result[entry.status] += 1;
+    return result;
+  }, [initialEntries]);
+
+  return (
+    <DirectionProvider direction={direction}>
+      <div className="min-h-dvh bg-background text-foreground" data-noe-app-root data-theme={theme}>
+        <header className="bg-surface-raised">
+          <div className="mx-auto flex max-w-7xl flex-col gap-4 px-6 py-8">
+            <div className="flex flex-wrap items-start justify-between gap-4">
+              <div className="flex flex-col gap-1.5">
+                <p
+                  className="m-0 font-mono text-xs uppercase tracking-wide text-muted-foreground"
+                  dir="ltr"
+                >
+                  NOECOSYSTEM / DESIGN SYSTEM
+                </p>
+                <h1 className="m-0 font-heading text-2xl font-semibold tracking-tight sm:text-3xl">
+                  {t('catalog.title')}
+                </h1>
+                <p className="m-0 max-w-2xl text-sm leading-normal text-muted-foreground">
+                  {t('catalog.subtitle')}
+                </p>
+              </div>
+              <div className="flex flex-wrap items-center gap-2">
+                <label className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                  <span className="sr-only">Theme</span>
+                  <select
+                    className="h-(--noe-control-height-sm) rounded-md border border-border bg-background px-2 text-sm text-foreground"
+                    onChange={(event) => setTheme(event.target.value as 'light' | 'dark')}
+                    value={theme}
+                  >
+                    <option value="light">Light</option>
+                    <option value="dark">Dark</option>
+                  </select>
+                </label>
+                <label className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                  <span className="sr-only">Locale</span>
+                  <select
+                    className="h-(--noe-control-height-sm) rounded-md border border-border bg-background px-2 text-sm text-foreground"
+                    onChange={(event) => setLocale(event.target.value as LocaleCode)}
+                    value={locale}
+                  >
+                    <option value="en">{t('catalog.locale.en')}</option>
+                    <option value="fa">{t('catalog.locale.fa')}</option>
+                    <option value="en-XA">{t('catalog.locale.pseudoLTR')}</option>
+                    <option value="ar-XB">{t('catalog.locale.pseudoRTL')}</option>
+                  </select>
+                </label>
+                <label className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                  <span className="sr-only">Direction</span>
+                  <select
+                    className="h-(--noe-control-height-sm) rounded-md border border-border bg-background px-2 text-sm text-foreground"
+                    onChange={(event) =>
+                      setDirectionOverride(event.target.value as DirectionOverride)
+                    }
+                    value={directionOverride}
+                  >
+                    <option value="auto">Auto</option>
+                    <option value="ltr">LTR</option>
+                    <option value="rtl">RTL</option>
+                  </select>
+                </label>
+              </div>
+            </div>
+          </div>
+        </header>
+
+        {selectedEntry ? (
+          <CatalogDetail
+            entry={selectedEntry}
+            onBack={() => setSelectedId(null)}
+            t={t}
+            locale={effectiveLocale}
+            direction={direction}
+          />
+        ) : (
+          <main className="mx-auto max-w-7xl px-6 py-8">
+            <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+              <input
+                aria-label={t('catalog.searchPlaceholder')}
+                className="h-(--noe-control-height-md) w-full max-w-sm rounded-md border border-border bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground focus-visible:border-accent focus-visible:ring-2 focus-visible:ring-focus-ring"
+                onChange={(event) => setSearch(event.target.value)}
+                placeholder={t('catalog.searchPlaceholder')}
+                type="search"
+                value={search}
+              />
+              <fieldset className="flex flex-wrap gap-1.5 border-0 p-0 m-0">
+                <legend className="sr-only">{t('catalog.allCategories')}</legend>
+                <CategoryPill active={category === 'all'} onClick={() => setCategory('all')}>
+                  {t('catalog.allCategories')}
+                </CategoryPill>
+                {catalogCategories.map((cat) => (
+                  <CategoryPill
+                    active={category === cat}
+                    key={cat}
+                    onClick={() => setCategory(cat)}
+                  >
+                    {cat}
+                  </CategoryPill>
+                ))}
+              </fieldset>
+            </div>
+
+            <div className="mt-4 flex flex-wrap items-center gap-2">
+              {(['available', 'in-progress', 'planned'] as const).map((status) => (
+                <button
+                  aria-pressed={statusFilter === status}
+                  className={`inline-flex items-center gap-1.5 rounded-pill border px-2.5 py-1 text-xs font-medium transition-colors ${statusBadgeClassName[status]} ${statusFilter === status ? 'ring-2 ring-focus-ring' : ''}`}
+                  key={status}
+                  onClick={() =>
+                    setStatusFilter((current) => (current === status ? 'all' : status))
+                  }
+                  type="button"
+                >
+                  {t(statusLabelKey[status])} · {counts[status]}
+                </button>
+              ))}
+            </div>
+
+            {filtered.length === 0 ? (
+              <p className="mt-10 text-sm text-muted-foreground">{t('catalog.resultsEmpty')}</p>
+            ) : (
+              <div className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+                {filtered.map((entry) => (
+                  <CatalogCard
+                    entry={entry}
+                    key={entry.id}
+                    onSelect={() => setSelectedId(entry.id)}
+                    t={t}
+                    locale={effectiveLocale}
+                    direction={direction}
+                  />
+                ))}
+              </div>
+            )}
+          </main>
+        )}
+      </div>
+    </DirectionProvider>
+  );
+}
+
+function CategoryPill({
+  active,
+  children,
+  onClick,
+}: {
+  active: boolean;
+  children: React.ReactNode;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      aria-pressed={active}
+      className={`h-(--noe-control-height-sm) rounded-md border px-3 text-xs font-medium transition-colors ${
+        active
+          ? 'border-accent bg-accent/10 text-accent'
+          : 'border-border bg-transparent text-muted-foreground hover:text-foreground'
+      }`}
+      onClick={onClick}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+function CatalogCard({
+  entry,
+  onSelect,
+  t,
+  locale,
+  direction,
+}: {
+  entry: CatalogEntry;
+  onSelect: () => void;
+  t: (key: string) => string;
+  locale: LocaleCode;
+  direction: Direction;
+}) {
+  const isPlanned = entry.status === 'planned';
+  const isPartial = entry.status === 'partial';
+  const previewCtx = { locale, direction, t, status: entry.status } as const;
+  return (
+    <article className="flex flex-col gap-4 rounded-lg bg-surface-raised p-5 shadow-raised">
+      <div className="flex items-start justify-between gap-3">
+        <div className="flex flex-col gap-1">
+          <h3 className="m-0 font-heading text-sm font-semibold leading-snug text-foreground">
+            {entry.name}
+          </h3>
+          <p className="m-0 text-xs text-muted-foreground">{entry.category}</p>
+        </div>
+        <span
+          className={`shrink-0 rounded-pill border px-2 py-0.5 text-[0.6875rem] font-medium ${statusBadgeClassName[entry.status]}`}
+          lang={locale}
+        >
+          {t(statusLabelKey[entry.status])}
+        </span>
+      </div>
+      <p className="m-0 text-xs leading-normal text-muted-foreground" lang={locale}>
+        {entry.description}
+      </p>
+      {isPlanned ? (
+        <div className="flex flex-col gap-2 rounded-md bg-surface-sunken/60 p-4">
+          <p className="m-0 text-sm font-medium text-foreground" lang={locale}>
+            {t('catalog.preview.planned.title')}
+          </p>
+          <p className="m-0 text-xs leading-normal text-muted-foreground" lang={locale}>
+            {t('catalog.preview.planned.description')}
+          </p>
+          <span className="text-xs text-muted-foreground" lang={locale}>
+            {t('catalog.preview.planned.notAvailable')}
+          </span>
+        </div>
+      ) : (
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center justify-center overflow-hidden rounded-md bg-surface-sunken/60 p-4">
+            {entry.preview(previewCtx)}
+          </div>
+          {isPartial && (
+            <p className="m-0 text-xs text-warning-foreground" lang={locale}>
+              {t('catalog.preview.partial.limitation')}
+            </p>
+          )}
+        </div>
+      )}
+      <div className="flex justify-end">
+        <button
+          className="text-xs font-medium text-accent hover:underline focus-visible:underline"
+          onClick={onSelect}
+          type="button"
+        >
+          {isPlanned ? t('catalog.preview.planned.readSpec') : t('catalog.viewDetail')}
+        </button>
+      </div>
+    </article>
+  );
+}
+
+function CatalogDetail({
+  entry,
+  onBack,
+  t,
+  locale,
+  direction,
+}: {
+  entry: CatalogEntry;
+  onBack: () => void;
+  t: (key: string) => string;
+  locale: LocaleCode;
+  direction: Direction;
+}) {
+  const isPlanned = entry.status === 'planned';
+  const isPartial = entry.status === 'partial';
+  const previewCtx = { locale, direction, t, status: entry.status } as const;
+  return (
+    <main className="mx-auto max-w-4xl px-6 py-8">
+      <button
+        className="mb-6 text-sm font-medium text-accent hover:underline"
+        onClick={onBack}
+        type="button"
+      >
+        ← {t('catalog.backToGrid')}
+      </button>
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div className="flex flex-col gap-1">
+          <h2 className="m-0 font-heading text-2xl font-semibold tracking-tight" lang={locale}>
+            {entry.name}
+          </h2>
+          <p className="m-0 text-sm text-muted-foreground" lang={locale}>
+            {entry.category}
+          </p>
+        </div>
+        <span
+          className={`shrink-0 rounded-pill border px-2.5 py-1 text-xs font-medium ${statusBadgeClassName[entry.status]}`}
+          lang={locale}
+        >
+          {t(statusLabelKey[entry.status])}
+        </span>
+      </div>
+      <p className="mt-3 max-w-2xl text-sm leading-normal text-muted-foreground" lang={locale}>
+        {entry.description}
+      </p>
+      <dl className="mt-4 grid grid-cols-2 gap-4 text-sm sm:max-w-md">
+        <div>
+          <dt className="text-xs text-muted-foreground">Package</dt>
+          <dd className="m-0 font-mono text-xs" dir="ltr">
+            {entry.package}
+          </dd>
+        </div>
+        <div>
+          <dt className="text-xs text-muted-foreground">Registry item</dt>
+          <dd className="m-0 font-mono text-xs" dir="ltr">
+            {entry.registryItem ?? '—'}
+          </dd>
+        </div>
+      </dl>
+      {isPlanned ? (
+        <div className="mt-6 flex flex-col gap-3 rounded-lg bg-surface-sunken/60 p-8">
+          <p className="m-0 text-sm font-medium text-foreground" lang={locale}>
+            {t('catalog.preview.planned.title')}
+          </p>
+          <p className="m-0 text-sm leading-normal text-muted-foreground" lang={locale}>
+            {t('catalog.preview.planned.description')}
+          </p>
+          <span className="text-xs text-muted-foreground" lang={locale}>
+            {t('catalog.preview.planned.notAvailable')}
+          </span>
+        </div>
+      ) : (
+        <div className="mt-6 flex flex-col gap-3">
+          <div className="flex items-center justify-center overflow-hidden rounded-lg bg-surface-sunken/60 p-8">
+            {entry.preview(previewCtx)}
+          </div>
+          {isPartial && (
+            <p className="m-0 text-xs text-warning-foreground" lang={locale}>
+              {t('catalog.preview.partial.limitation')}
+            </p>
+          )}
+        </div>
+      )}
+    </main>
+  );
+}

package/apps/showcase/src/main.tsx

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { App } from './app';
+import './app.css';
+
+const root = document.getElementById('root');
+
+if (!root) {
+  throw new Error('NOE showcase root element was not found.');
+}
+
+createRoot(root).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/apps/showcase/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/apps/showcase/vite.config.ts

@@ -0,0 +1,15 @@
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  build: {
+    // Showcase bundles the full catalog (47 previews) including heavy cinematic canvases.
+    // Initial JS is ~560k (gzip ~173k) largely due to inlined cinematic demos that are
+    // not needed for consumer installs. Phase 1 keeps them inline for visual parity;
+    // Phase 2 will lazy-load cinematic/showcase code into separate chunks.
+    // Raising limit avoids noisy warning without hiding real regressions (ADR pending).
+    chunkSizeWarningLimit: 650,
+  },
+});

package/apps/storybook/.storybook/main.ts

@@ -0,0 +1,21 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+import tailwindcss from '@tailwindcss/vite';
+
+const config: StorybookConfig = {
+  stories: ['../stories/**/*.stories.@(ts|tsx|mdx)'],
+  addons: ['@storybook/addon-docs', '@storybook/addon-a11y', '@storybook/addon-vitest'],
+  framework: { name: '@storybook/react-vite', options: {} },
+  docs: { autodocs: 'tag' },
+  staticDirs: ['../../../packages/design-tokens/src'],
+  typescript: { check: true },
+  // Storybook's react-vite framework does not read a root vite.config.ts and this
+  // workspace has none; without this hook Tailwind's `@import "tailwindcss"` in
+  // tailwind.css never expands, so every story renders with the right class names
+  // but no generated utility CSS at all.
+  async viteFinal(viteConfig) {
+    viteConfig.plugins = [...(viteConfig.plugins ?? []), tailwindcss()];
+    return viteConfig;
+  },
+};
+
+export default config;