@abyss-project/commons-front-core 6.1.0 → 7.1.0

package/catalog/parts.tsx

@@ -0,0 +1,427 @@
+import type { ReactNode } from 'react';
+import Avatar from '@mui/material/Avatar';
+import ButtonBase from '@mui/material/ButtonBase';
+import IconButton from '@mui/material/IconButton';
+import { styled } from '@mui/material/styles';
+import ArchiveOutlined from '@mui/icons-material/ArchiveOutlined';
+import ArticleOutlined from '@mui/icons-material/ArticleOutlined';
+import FamilyRestroomOutlined from '@mui/icons-material/FamilyRestroomOutlined';
+import FolderOutlined from '@mui/icons-material/FolderOutlined';
+import HelpOutlineRounded from '@mui/icons-material/HelpOutlineRounded';
+import ImageOutlined from '@mui/icons-material/ImageOutlined';
+import MovieOutlined from '@mui/icons-material/MovieOutlined';
+import NotificationsNoneOutlined from '@mui/icons-material/NotificationsNoneOutlined';
+import PhotoCameraOutlined from '@mui/icons-material/PhotoCameraOutlined';
+import PictureAsPdfOutlined from '@mui/icons-material/PictureAsPdfOutlined';
+import TableChartOutlined from '@mui/icons-material/TableChartOutlined';
+import { focusRing, hairline, px } from '../src/theme/components/shared';
+import type { SemanticToken } from '../src/theme/tokens/semantic';
+import { fontWeights } from '../src/theme/tokens/primitives';
+import { Surface } from '../src/components/structure/Surface/Surface';
+import { Sparkline } from '../src/components/data/Sparkline/Sparkline';
+import { StatusBadge } from '../src/components/meaning/StatusBadge/StatusBadge';
+import type { AppShellFooterItem } from '../src/components/structure/AppShell/app-shell.types';
+import type { BankAccount, CloudFile, FileKind } from './fixtures';
+import { formatEuro, formatSignedEuro } from './fixtures';
+
+// Small host-side pieces the fixtures need around the components: what an application would
+// write itself (an amount cell, a file glyph, the top bar slots, the sidebar footer).
+
+const AmountText = styled('span', {
+  shouldForwardProp: (prop) => prop !== 'credit',
+})<{ credit: boolean }>(({ theme, credit }) => ({
+  fontFamily: theme.design.fonts.mono,
+  fontWeight: fontWeights.medium,
+  whiteSpace: 'nowrap',
+  color: credit
+    ? theme.design.tokens['status.success']
+    : theme.design.tokens['text.primary'],
+}));
+
+/** A signed amount: credits in `status.success`, debits in the text color. */
+export const Amount = ({ value }: { value: number }) => (
+  <AmountText credit={value > 0}>{formatSignedEuro(value)}</AmountText>
+);
+
+// A file type is no meaning: its glyph stays neutral, color is kept for the state (scan verdict).
+const FILE_GLYPHS: Record<FileKind, ReactNode> = {
+  folder: <FolderOutlined />,
+  pdf: <PictureAsPdfOutlined />,
+  sheet: <TableChartOutlined />,
+  image: <ImageOutlined />,
+  doc: <ArticleOutlined />,
+  archive: <ArchiveOutlined />,
+  video: <MovieOutlined />,
+};
+
+const GlyphBox = styled('span', {
+  shouldForwardProp: (prop) => prop !== 'tone',
+})<{ tone: SemanticToken }>(({ theme, tone }) => {
+  const { space, radii, tokens } = theme.design;
+  return {
+    display: 'grid',
+    placeItems: 'center',
+    flex: 'none',
+    width: px(space[8]),
+    height: px(space[8]),
+    borderRadius: px(radii.md),
+    backgroundColor: tokens['bg.raised'],
+    color: tokens[tone],
+    '& > svg': { width: px(space[5]), height: px(space[5]) },
+  };
+});
+
+/** An icon on a raised square, colored by a token. */
+export const Glyph = ({
+  icon,
+  tone,
+}: {
+  icon: ReactNode;
+  tone: SemanticToken;
+}) => (
+  <GlyphBox tone={tone} aria-hidden="true">
+    {icon}
+  </GlyphBox>
+);
+
+export const FileGlyph = ({ kind }: { kind: FileKind }) => (
+  <Glyph icon={FILE_GLYPHS[kind]} tone="text.secondary" />
+);
+
+const NameCell = styled('span')(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: px(theme.design.space[3]),
+  minWidth: 0,
+}));
+
+const NameText = styled('span')({
+  display: 'flex',
+  flexDirection: 'column',
+  minWidth: 0,
+  overflowWrap: 'anywhere',
+  // On one line (a table cell), each line ends with an ellipsis rather than a clipped letter.
+  '& > span': { overflow: 'hidden', textOverflow: 'ellipsis' },
+});
+
+const Muted = styled('span')(({ theme }) => ({
+  color: theme.design.tokens['text.muted'],
+  fontSize: px(theme.design.typeScale.small),
+}));
+
+/** A file name with its glyph and its detail line. */
+export const FileName = ({ file }: { file: CloudFile }) => (
+  <NameCell>
+    <FileGlyph kind={file.kind} />
+    <NameText>
+      <span>{file.name}</span>
+      <Muted>{file.detail}</Muted>
+    </NameText>
+  </NameCell>
+);
+
+const MutedLine = styled('span', {
+  shouldForwardProp: (prop) => prop !== 'mono',
+})<{ mono: boolean }>(({ theme, mono }) => ({
+  color: theme.design.tokens['text.muted'],
+  fontSize: px(theme.design.typeScale.small),
+  fontFamily: mono ? theme.design.fonts.mono : undefined,
+}));
+
+/** Two lines in one cell: the value and a muted detail under it. */
+export const TwoLines = ({
+  first,
+  second,
+  mono = false,
+}: {
+  first: ReactNode;
+  second: ReactNode;
+  mono?: boolean;
+}) => (
+  <NameText>
+    <span>{first}</span>
+    <MutedLine mono={mono}>{second}</MutedLine>
+  </NameText>
+);
+
+const MonoSmall = styled('span')(({ theme }) => ({
+  fontFamily: theme.design.fonts.mono,
+  fontSize: px(theme.design.typeScale.small),
+  color: theme.design.tokens['text.secondary'],
+  overflowWrap: 'anywhere',
+}));
+
+export const Mono = ({ children }: { children: ReactNode }) => (
+  <MonoSmall>{children}</MonoSmall>
+);
+
+const StatusCode = styled('span', {
+  shouldForwardProp: (prop) => prop !== 'tone',
+})<{ tone: SemanticToken }>(({ theme, tone }) => ({
+  fontFamily: theme.design.fonts.mono,
+  fontWeight: fontWeights.medium,
+  color: theme.design.tokens[tone],
+}));
+
+/** An HTTP status code colored by its class, as in the Monitor mock-up. */
+export const HttpStatus = ({ code }: { code: number }) => (
+  <StatusCode
+    tone={
+      code >= 500
+        ? 'status.danger'
+        : code >= 400
+        ? 'status.warning'
+        : 'status.success'
+    }
+  >
+    {code}
+  </StatusCode>
+);
+
+const AccountAvatar = styled(Avatar)(({ theme }) => {
+  const { space, tokens, typeScale } = theme.design;
+  return {
+    width: px(space[7]),
+    height: px(space[7]),
+    fontSize: px(typeScale.small),
+    fontWeight: fontWeights.semibold,
+    backgroundColor: tokens['bg.raised'],
+    color: tokens['text.primary'],
+    border: hairline(tokens['border.subtle']),
+  };
+});
+
+/** Right side of the top bar: help, notifications, account. */
+export const TopbarActions = () => (
+  <>
+    <IconButton aria-label="Aide">
+      <HelpOutlineRounded />
+    </IconButton>
+    <IconButton aria-label="Notifications">
+      <NotificationsNoneOutlined />
+    </IconButton>
+    <AccountAvatar alt="Mehdi A.">MA</AccountAvatar>
+  </>
+);
+
+const FooterAvatar = styled('span')(({ theme }) => {
+  const { tokens, typeScale, radii } = theme.design;
+  return {
+    display: 'grid',
+    placeItems: 'center',
+    width: '100%',
+    height: '100%',
+    borderRadius: px(radii.lg),
+    fontSize: px(typeScale.caption),
+    fontWeight: fontWeights.semibold,
+    backgroundColor: tokens['bg.raised'],
+    color: tokens['text.primary'],
+    border: hairline(tokens['border.subtle']),
+    boxSizing: 'border-box',
+  };
+});
+
+/** Bottom of the navigation: the family and the account (the canonical sidebar footer). */
+export const SHELL_FOOTER: AppShellFooterItem[] = [
+  {
+    id: 'family',
+    label: 'Ma famille · 4',
+    icon: <FamilyRestroomOutlined />,
+    href: '#famille',
+  },
+  {
+    id: 'account',
+    label: 'Mon compte',
+    icon: <FooterAvatar>MA</FooterAvatar>,
+    href: '#compte',
+  },
+];
+
+const PhotoFrame = styled('div', {
+  shouldForwardProp: (prop) => prop !== 'from' && prop !== 'to',
+})<{ from: SemanticToken; to: SemanticToken }>(({ theme, from, to }) => {
+  const { tokens, space } = theme.design;
+  return {
+    position: 'relative',
+    display: 'grid',
+    placeItems: 'center',
+    width: '100%',
+    height: '100%',
+    minHeight: px(space[10]),
+    backgroundImage: `linear-gradient(160deg, ${tokens[from]}, ${tokens[to]})`,
+    color: tokens['accent.on'],
+    '& > svg': { width: px(space[9]), height: px(space[9]), opacity: 0.55 },
+  };
+});
+
+const PHOTO_TONES: Array<[SemanticToken, SemanticToken]> = [
+  ['status.info', 'brand.gradientTo'],
+  ['status.highlight', 'accent'],
+  ['brand.gradientFrom', 'status.success'],
+  ['status.warning', 'status.highlight'],
+  ['accent', 'status.info'],
+  ['status.success', 'brand.gradientFrom'],
+];
+
+/** Stand-in for a photo: a token gradient (the catalog ships no image). */
+export const PhotoPlaceholder = ({ index }: { index: number }) => {
+  const [from, to] = PHOTO_TONES[index % PHOTO_TONES.length];
+  return (
+    <PhotoFrame from={from} to={to} aria-hidden="true">
+      <PhotoCameraOutlined />
+    </PhotoFrame>
+  );
+};
+
+const AccountHead = styled('div')(({ theme }) => ({
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'flex-start',
+  gap: px(theme.design.space[2]),
+  minWidth: 0,
+}));
+
+const AccountBalance = styled('span', {
+  shouldForwardProp: (prop) => prop !== 'negative',
+})<{ negative: boolean }>(({ theme, negative }) => ({
+  fontFamily: theme.design.fonts.mono,
+  fontSize: px(theme.design.typeScale.sectionTitle),
+  fontWeight: fontWeights.medium,
+  color: negative
+    ? theme.design.tokens['status.danger']
+    : theme.design.tokens['text.primary'],
+}));
+
+const AccountBody = styled('div')(({ theme }) => ({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: px(theme.design.space[3]),
+  minWidth: 0,
+}));
+
+/** A bank account card: name, IBAN, status, balance and its twelve-month trend. */
+export const AccountCard = ({
+  account,
+  interactive = false,
+  onOpen,
+}: {
+  account: BankAccount;
+  interactive?: boolean;
+  onOpen?(): void;
+}) => (
+  <Surface
+    padding={4}
+    interactive={interactive}
+    onClick={onOpen}
+    aria-label={interactive ? account.name : undefined}
+  >
+    <AccountBody>
+      <AccountHead>
+        <TwoLines
+          first={account.name}
+          second={`${account.bank} · ${account.iban}`}
+          mono
+        />
+        <StatusBadge
+          tone={account.status.tone}
+          label={account.status.label}
+          dot
+        />
+      </AccountHead>
+      <AccountBalance negative={account.balance < 0}>
+        {formatEuro(account.balance)}
+      </AccountBalance>
+      <Sparkline
+        values={account.trend}
+        label={`Solde de ${account.name} sur 12 mois`}
+      />
+      <Muted>{account.type}</Muted>
+    </AccountBody>
+  </Surface>
+);
+
+const ListRoot = styled('ul')(({ theme }) => ({
+  margin: 0,
+  padding: 0,
+  listStyle: 'none',
+  display: 'flex',
+  flexDirection: 'column',
+  minWidth: 0,
+  backgroundColor: theme.design.tokens['bg.surface'],
+  border: hairline(theme.design.tokens['border.subtle']),
+  borderRadius: px(theme.design.radii.lg),
+  overflow: 'hidden',
+  '& > li + li': { borderTop: hairline(theme.design.tokens['border.subtle']) },
+}));
+
+const RowButton = styled(ButtonBase)(({ theme }) => {
+  const { space, tokens, densityValues, typeScale, fonts } = theme.design;
+  return {
+    width: '100%',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'flex-start',
+    gap: px(space[3]),
+    minHeight: px(densityValues.touchTarget + space[4]),
+    padding: `${px(space[2])} ${px(space[4])}`,
+    textAlign: 'left',
+    fontFamily: fonts.sans,
+    fontSize: px(typeScale.bodyMobile),
+    color: tokens['text.primary'],
+    '&:hover': { backgroundColor: tokens['bg.hover'] },
+    '&.Mui-focusVisible': { ...focusRing(theme), outlineOffset: '-2px' },
+  };
+});
+
+const RowText = styled('span')({
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 auto',
+  minWidth: 0,
+  '& > span': {
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+});
+
+const RowTrailing = styled('span')(({ theme }) => ({
+  flex: 'none',
+  display: 'flex',
+  alignItems: 'center',
+  gap: px(theme.design.space[2]),
+}));
+
+export interface TouchListItem {
+  id: string;
+  leading?: ReactNode;
+  title: string;
+  subtitle: string;
+  trailing?: ReactNode;
+}
+
+/** A touch list of two-line rows, as in the mobile mock-ups (`.mli`). */
+export const TouchList = ({
+  items,
+  onOpen,
+}: {
+  items: TouchListItem[];
+  onOpen(id: string): void;
+}) => (
+  <ListRoot>
+    {items.map((item) => (
+      <li key={item.id}>
+        <RowButton onClick={() => onOpen(item.id)}>
+          {item.leading}
+          <RowText>
+            <span>{item.title}</span>
+            <Muted>{item.subtitle}</Muted>
+          </RowText>
+          {item.trailing !== undefined && (
+            <RowTrailing>{item.trailing}</RowTrailing>
+          )}
+        </RowButton>
+      </li>
+    ))}
+  </ListRoot>
+);

package/catalog/playwright.ci.config.ts

@@ -0,0 +1,29 @@
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { defineConfig } from '@playwright/test';
+import baseConfig from './playwright.config';
+import { catalogPort } from './catalog-port';
+
+// CI run of the catalog checks (`catalog:test:ci`, job `front-core-catalog`): the built catalog
+// (`catalog-dist/`, built by the script just before) served by `vite preview`, instead of the dev
+// server, which transforms every module on demand and makes a shared runner miss its timeouts.
+// Only the specs that carry criteria 15 and 16 run (responsive, mobile-shell): the captures are a
+// human review, produced locally by `catalog:test`, so neither their spec nor the teardown that
+// indexes them runs here.
+const port = catalogPort();
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+export default defineConfig({
+  ...baseConfig,
+  testIgnore: ['**/captures.spec.ts'],
+  globalTeardown: undefined,
+  workers: 4,
+  webServer: {
+    command: 'pnpm exec vite preview --config catalog/vite.config.ts',
+    cwd: packageRoot,
+    url: `http://127.0.0.1:${port}`,
+    reuseExistingServer: false,
+    timeout: 60_000,
+    env: { CATALOG_PORT: String(port) },
+  },
+});

package/catalog/playwright.config.ts

@@ -0,0 +1,36 @@
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { defineConfig, devices } from '@playwright/test';
+import { catalogPort } from './catalog-port';
+
+// The package is an ES module: no `__dirname`.
+const catalogDir = dirname(fileURLToPath(import.meta.url));
+
+// Browser checks of the component catalog: overflow and touch targets (responsive), the mobile
+// frame (mobile-shell) and the screenshots of every page (captures). The catalog dev server is
+// started on `CATALOG_PORT` and never reused: an already listening port belongs to someone else.
+const port = catalogPort();
+const packageRoot = resolve(catalogDir, '..');
+
+export default defineConfig({
+  testDir: resolve(catalogDir, 'specs'),
+  outputDir: resolve(packageRoot, 'test-results/catalog'),
+  fullyParallel: true,
+  forbidOnly: true,
+  retries: 0,
+  reporter: [['list']],
+  globalTeardown: resolve(catalogDir, 'specs/write-capture-index.ts'),
+  use: {
+    ...devices['Desktop Chrome'],
+    baseURL: `http://127.0.0.1:${port}`,
+    trace: 'retain-on-failure',
+  },
+  webServer: {
+    command: 'pnpm exec vite --config catalog/vite.config.ts',
+    cwd: packageRoot,
+    url: `http://127.0.0.1:${port}`,
+    reuseExistingServer: false,
+    timeout: 120_000,
+    env: { CATALOG_PORT: String(port) },
+  },
+});

package/catalog/specs/captures.spec.ts

@@ -0,0 +1,67 @@
+import { resolve } from 'path';
+import { expect, test } from '@playwright/test';
+import type { Page } from '@playwright/test';
+import { CAPTURES, CAPTURES_DIR, VIEWPORT_HEIGHT } from '../captures-plan';
+import type { CaptureState } from '../captures-plan';
+import { openCatalogPage, settle } from './catalog-page';
+
+// Criterion 13: one PNG per component in light and dark at 1440 px, plus 390 px for the
+// components that change form below 768 px, and the two composed scenes at 1440 and 390 px.
+
+/** How each state beyond arrival is reached, and what proves it is shown. */
+const REACH: Record<
+  Exclude<CaptureState, 'arrival'>,
+  (page: Page) => Promise<void>
+> = {
+  'sheet-open': async (page) => {
+    await page
+      .getByRole('button', { name: /avis-imposition-2026\.pdf/ })
+      .click();
+    await expect(
+      page.getByRole('dialog', { name: 'avis-imposition-2026.pdf' }),
+    ).toBeVisible();
+  },
+  'list-open': async (page) => {
+    await page.getByRole('combobox').first().click();
+    await expect(page.getByRole('listbox')).toBeVisible();
+  },
+  'calendar-open': async (page) => {
+    await page
+      .getByRole('button', { name: /Choisir une date/ })
+      .first()
+      .click();
+    await expect(page.getByRole('dialog')).toBeVisible();
+  },
+};
+
+for (const capture of CAPTURES) {
+  test(`capture ${capture.file}`, async ({ page }) => {
+    await openCatalogPage(page, capture.entry.name, capture.theme, {
+      width: capture.width,
+      height: VIEWPORT_HEIGHT[capture.width],
+    });
+
+    if (capture.state !== 'arrival') {
+      await REACH[capture.state](page);
+      await settle(page);
+    }
+
+    // A taller window rather than `fullPage`: the sticky sidebar (`100vh`) then spans the whole
+    // page, as it does on screen while scrolling. A mobile frame (`100dvh`) is never taller.
+    const documentHeight = await page.evaluate(
+      () => document.documentElement.scrollHeight,
+    );
+    if (documentHeight > VIEWPORT_HEIGHT[capture.width]) {
+      await page.setViewportSize({
+        width: capture.width,
+        height: documentHeight,
+      });
+      await settle(page);
+    }
+
+    await page.screenshot({
+      path: resolve(CAPTURES_DIR, capture.file),
+      animations: 'disabled',
+    });
+  });
+}

package/catalog/specs/catalog-page.ts

@@ -0,0 +1,42 @@
+import type { Page } from '@playwright/test';
+import { catalogPath } from '../catalog-entries';
+import type { CatalogTheme } from '../catalog-entries';
+
+/** Longest enter transition of the design system (`durations.slow`, 260 ms), with margin. */
+const SETTLE_MS = 400;
+
+/**
+ * Opens a catalog page at `width` × `height` and waits until it is drawn: fonts loaded, enter
+ * transitions over. Any uncaught page error fails the calling test.
+ */
+export const openCatalogPage = async (
+  page: Page,
+  name: string,
+  theme: CatalogTheme,
+  viewport: { width: number; height: number },
+): Promise<void> => {
+  const errors: string[] = [];
+  page.on('pageerror', (error) => errors.push(error.message));
+  await page.setViewportSize(viewport);
+  await page.goto(catalogPath(name, theme));
+  await page.waitForLoadState('networkidle');
+  await page.evaluate(() => document.fonts.ready.then(() => undefined));
+  await page.waitForTimeout(SETTLE_MS);
+  if (errors.length > 0) {
+    throw new Error(
+      `The catalog page ${name} (${theme}) threw: ${errors.join(' | ')}`,
+    );
+  }
+  const dataTheme = await page.evaluate(
+    () => document.documentElement.dataset.theme,
+  );
+  if (dataTheme !== theme) {
+    throw new Error(
+      `The catalog page ${name} rendered data-theme="${dataTheme}", expected ${theme}.`,
+    );
+  }
+};
+
+/** Waits for enter and exit transitions after an interaction. */
+export const settle = (page: Page): Promise<void> =>
+  page.waitForTimeout(SETTLE_MS);