@abyss-project/commons-front-core 6.0.0 → 7.0.0

package/catalog/captures-plan.ts

@@ -0,0 +1,91 @@
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { CATALOG_ENTRIES, CATALOG_THEMES } from './catalog-entries';
+import type { CatalogEntry, CatalogTheme } from './catalog-entries';
+
+// The package is an ES module: no `__dirname`.
+const catalogDir = dirname(fileURLToPath(import.meta.url));
+
+// Which screenshots the catalog produces, shared by `specs/captures.spec.ts` (takes them) and
+// `specs/write-capture-index.ts` (lists them in `index.md`).
+
+export const CAPTURES_DIR = resolve(
+  catalogDir,
+  '../../../e2e/screenshots/286/core',
+);
+
+export const DESKTOP_WIDTH = 1440;
+export const TABLET_WIDTH = 768;
+export const PHONE_WIDTH = 390;
+
+/** Viewport height per width: a laptop screen, a tablet held in portrait, a phone. */
+export const VIEWPORT_HEIGHT: Record<number, number> = {
+  [DESKTOP_WIDTH]: 900,
+  [TABLET_WIDTH]: 1024,
+  [PHONE_WIDTH]: 844,
+};
+
+/** The pages also shown at tablet width: the shell turns into an icon rail there. */
+const TABLET_CAPTURES = new Set(['SceneDesktop', 'AppShell']);
+
+/** A state reached after arrival, captured under its own name. */
+export type CaptureState =
+  | 'arrival'
+  | 'sheet-open'
+  | 'list-open'
+  | 'calendar-open';
+
+/** File name suffix of each state. */
+const STATE_SUFFIX: Record<CaptureState, string> = {
+  arrival: '',
+  'sheet-open': '-feuille',
+  'list-open': '-liste',
+  'calendar-open': '-calendrier',
+};
+
+/** The states shown beyond arrival: what a closed control hides (options, calendar, sheet). */
+const EXTRA_STATES: Record<string, CaptureState> = {
+  SceneMobile: 'sheet-open',
+  RichSelect: 'list-open',
+  DateField: 'calendar-open',
+};
+
+export interface Capture {
+  entry: CatalogEntry;
+  theme: CatalogTheme;
+  width: number;
+  state: CaptureState;
+  file: string;
+}
+
+const widthsOf = (entry: CatalogEntry): number[] => [
+  DESKTOP_WIDTH,
+  ...(TABLET_CAPTURES.has(entry.name) ? [TABLET_WIDTH] : []),
+  ...(entry.mobileCapture ? [PHONE_WIDTH] : []),
+];
+
+const statesOf = (entry: CatalogEntry): CaptureState[] => {
+  const extra = EXTRA_STATES[entry.name];
+  return extra === undefined ? ['arrival'] : ['arrival', extra];
+};
+
+const fileName = (
+  entry: CatalogEntry,
+  theme: CatalogTheme,
+  width: number,
+  state: CaptureState,
+) => `${entry.slug}${STATE_SUFFIX[state]}-${theme}-${width}.png`;
+
+export const CAPTURES: Capture[] = CATALOG_ENTRIES.flatMap((entry) =>
+  statesOf(entry).flatMap((state) =>
+    CATALOG_THEMES.flatMap((theme) =>
+      widthsOf(entry).map((width) => ({
+        entry,
+        theme,
+        width,
+        state,
+        file: fileName(entry, theme, width, state),
+      })),
+    ),
+  ),
+);

package/catalog/catalog-entries.ts

@@ -0,0 +1,89 @@
+import { ThemeMode } from '../src/theme/tokens/primitives';
+
+// The catalog pages, as plain data: read by the browser entry (`main.tsx`) and by the Playwright
+// specs, which run in Node and must not load React or MUI.
+
+export type CatalogFamily =
+  | 'scenes'
+  | 'structure'
+  | 'mobile'
+  | 'states'
+  | 'data'
+  | 'meaning'
+  | 'business'
+  | 'layers'
+  | 'inputs';
+
+export interface CatalogEntry {
+  /** Value of the `component` URL parameter. */
+  name: string;
+  family: CatalogFamily;
+  /** Base name of the screenshots: `<slug>-<theme>-<width>.png`. */
+  slug: string;
+  /** Checked by `responsive.spec.ts` at 360, 768 and 1440 px (structure, mobile, `DataTable`). */
+  responsive: boolean;
+  /** Also captured at 390 px: the page changes form below 768 px. */
+  mobileCapture: boolean;
+}
+
+const entry = (
+  name: string,
+  family: CatalogFamily,
+  slug: string,
+  options: { responsive?: boolean; mobileCapture?: boolean } = {},
+): CatalogEntry => ({
+  name,
+  family,
+  slug,
+  responsive: options.responsive ?? false,
+  mobileCapture: options.mobileCapture ?? false,
+});
+
+const RESPONSIVE = { responsive: true, mobileCapture: true };
+
+export const CATALOG_ENTRIES: CatalogEntry[] = [
+  entry('SceneDesktop', 'scenes', 'scene-bureau', RESPONSIVE),
+  entry('SceneMobile', 'scenes', 'scene-mobile', RESPONSIVE),
+  entry('AppShell', 'structure', 'app-shell', RESPONSIVE),
+  entry('PageHeader', 'structure', 'page-header', RESPONSIVE),
+  entry('Section', 'structure', 'section', RESPONSIVE),
+  entry('Surface', 'structure', 'surface', RESPONSIVE),
+  entry('Toolbar', 'structure', 'toolbar', RESPONSIVE),
+  entry('FilterBar', 'structure', 'filter-bar', RESPONSIVE),
+  entry('SplitView', 'structure', 'split-view', RESPONSIVE),
+  entry('MobileShell', 'mobile', 'mobile-shell', RESPONSIVE),
+  entry('BottomSheet', 'mobile', 'bottom-sheet', RESPONSIVE),
+  entry('ActionBar', 'mobile', 'action-bar', RESPONSIVE),
+  entry('SwipeDeck', 'mobile', 'swipe-deck', RESPONSIVE),
+  entry('PageState', 'states', 'page-state'),
+  entry('DataTable', 'data', 'data-table', RESPONSIVE),
+  entry('KeyValueList', 'data', 'key-value-list'),
+  entry('StatTile', 'data', 'stat-tile'),
+  entry('Sparkline', 'data', 'sparkline'),
+  entry('ChartTheme', 'data', 'chart-theme'),
+  entry('StatusBadge', 'meaning', 'status-badge'),
+  entry('MethodBadge', 'meaning', 'method-badge'),
+  entry('SeverityBadge', 'meaning', 'severity-badge'),
+  entry('ScanBadge', 'meaning', 'scan-badge'),
+  entry('RoleBadge', 'meaning', 'role-badge'),
+  entry('ToolIcon', 'meaning', 'tool-icon'),
+  entry('InfectedDownloadModal', 'business', 'infected-download-modal'),
+  entry('Modal', 'layers', 'modal', { mobileCapture: true }),
+  entry('ConfirmDialog', 'layers', 'confirm-dialog'),
+  entry('Drawer', 'layers', 'drawer'),
+  entry('Menu', 'layers', 'menu'),
+  entry('Toast', 'layers', 'toast'),
+  entry('CommandPalette', 'layers', 'command-palette'),
+  entry('RichSelect', 'inputs', 'rich-select'),
+  entry('DateField', 'inputs', 'date-field'),
+  entry('DateRangeField', 'inputs', 'date-range-field'),
+  entry('ColorField', 'inputs', 'color-field'),
+  entry('SegmentedControl', 'inputs', 'segmented-control'),
+];
+
+export const CATALOG_THEMES = [ThemeMode.Dark, ThemeMode.Light] as const;
+export type CatalogTheme = (typeof CATALOG_THEMES)[number];
+
+/** Path of a catalog page, relative to the catalog server. */
+export const catalogPath = (name: string, theme: CatalogTheme): string =>
+  `/?component=${encodeURIComponent(name)}&theme=${theme}`;

package/catalog/catalog-port.ts

@@ -0,0 +1,19 @@
+/**
+ * Port of the catalog server, read from `CATALOG_PORT`. There is no default: every session (lane)
+ * owns its own block of ports, and a default would silently squat another session's port.
+ */
+export const catalogPort = (): number => {
+  const raw = process.env.CATALOG_PORT;
+  if (raw === undefined || raw.trim() === '') {
+    throw new Error(
+      'CATALOG_PORT is not set: the catalog does not start without an explicit port (the lane slot port, e.g. 21788).',
+    );
+  }
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new Error(
+      `CATALOG_PORT must be an integer between 1024 and 65535, got "${raw}".`,
+    );
+  }
+  return port;
+};