@postxl/generators 0.2.2

package/dist/e2e/template/e2e/support/checkbox-click.ts

@@ -0,0 +1,20 @@
+import { Page } from '@playwright/test'
+
+/**
+ * Clicks a checkbox element by its name attribute.
+ *
+ * This function uses page.evaluate() to execute the click in the browser context,
+ * which can be more reliable than using Playwright's click() method for certain
+ * checkbox implementations or when dealing with custom styled checkboxes.
+ *
+ */
+export const clickCheckboxByName = async (page: Page, name: string): Promise<void> => {
+  await page.evaluate((name) => {
+    // Find the checkbox element by its name attribute
+    const checkbox = document.querySelector(`input[name="${name}"]`) as HTMLElement
+    if (checkbox) {
+      // Use native DOM click() method for reliable interaction
+      checkbox.click()
+    }
+  }, name)
+}

package/dist/e2e/template/e2e/support/get-backend-mode.ts

@@ -0,0 +1,10 @@
+import { TEST_CONFIG } from 'playwright.config'
+
+export async function getBackendMode(): Promise<string> {
+  const response = await fetch(`${TEST_CONFIG.apiURL}/test/mode`)
+  if (!response.ok) {
+    throw new Error('Failed to fetch backend mode')
+  }
+  const data = await response.json()
+  return data.mode // Backend returns { mode: "stateful" | "stateless" }
+}

package/dist/e2e/template/e2e/support/map.utils.ts

@@ -0,0 +1,98 @@
+import { Page } from '@playwright/test'
+
+/**
+ * Waits for a map instance to become idle (not moving or zooming).
+ *
+ * This function first attempts to wait for a test marker element with data-testid="map-idle"
+ * for up to 1 second, then polls the global map instance to check if it's in an idle state.
+ * The function will timeout after 4 seconds if the map doesn't become idle.
+ *
+ */
+export async function waitForMapIdle(page: Page): Promise<void> {
+  const timeout = 4000
+  const start = Date.now()
+
+  try {
+    await page.getByTestId('map-idle').waitFor({ timeout: 1000 })
+  } catch {
+    // Ignore errors if the marker is not present
+  }
+
+  while (Date.now() - start < timeout) {
+    const isIdle = await page.evaluate(() => {
+      // SONAR suggest 'Prefer `globalThis` over `window`'
+      const map = (globalThis as any).mapInstance
+      if (!map) {
+        console.warn('map instance not found on globalThis')
+        return true
+      }
+      return !(map.isMoving() || map.isZooming())
+    })
+
+    if (isIdle) {
+      await page.evaluate(() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))))
+      return
+    }
+
+    await page.waitForTimeout(100)
+  }
+
+  console.warn('Timed out waiting for the map to become idle')
+}
+
+/**
+ * Additional stronger wait that checks Mapbox tile images are loaded.
+ */
+export async function waitForMapFullyRendered(page: Page, timeout = 4000): Promise<void> {
+  const start = Date.now()
+  // first wait for the simple idle marker if present
+  try {
+    await page.getByTestId('map-idle').waitFor({ timeout: 1000 })
+  } catch {
+    // ignore - we'll still poll below
+  }
+
+  // wait until any <img> tiles are complete (or there are none)
+  await page.waitForFunction(
+    () => {
+      const imgs = Array.from(document.querySelectorAll('.mapboxgl-tiles img')) as HTMLImageElement[]
+      if (imgs.length === 0) {
+        return true
+      }
+      return imgs.every((i) => i.complete && (i.naturalWidth ?? 0) > 0)
+    },
+    { timeout: timeout / 2 },
+  )
+
+  // Wait for MapboxGL to finish moving/zooming
+  await page
+    .waitForFunction(
+      () => {
+        // @ts-expect-error - exposed in our app
+        // SONAR suggest 'Prefer `globalThis` over `window`'
+        const map = globalThis.mapInstance
+        if (!map) {
+          console.warn('map instance not found on globalThis')
+          return true
+        } // fallback if not exposed
+        return !(map.isMoving() || map.isZooming())
+      },
+      { timeout: timeout / 2 },
+    )
+    .catch(() => {
+      /* ignore if not exposed */
+    })
+
+  // give one final animation frame for the canvas to settle
+  await page.evaluate(
+    () =>
+      new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(resolve))
+      }),
+  )
+
+  // guard: if we took too long, still return (test should fail elsewhere)
+  if (Date.now() - start > timeout) {
+    return
+  }
+}

package/dist/e2e/template/e2e/support/mask-toast.ts

@@ -0,0 +1,20 @@
+import type { Page } from '@playwright/test'
+
+/**
+ * Masks toast messages at the bottom right of the page
+ * Useful for preventing toast messages from appearing in screenshots
+ */
+export async function maskToast(page: Page) {
+  await page.evaluate(() => {
+    const mask = document.createElement('div')
+    mask.style.position = 'fixed'
+    mask.style.right = '0'
+    mask.style.bottom = '0'
+    mask.style.width = '420px'
+    mask.style.height = '260px'
+    mask.style.background = '#fff'
+    mask.style.zIndex = '9999'
+    mask.style.pointerEvents = 'none'
+    document.body.appendChild(mask)
+  })
+}

package/dist/e2e/template/e2e/support/model-test-ids.ts

@@ -0,0 +1,4 @@
+/**
+ * Object with all generated test ids.
+ */
+export const MODEL_TEST_IDS = {}

package/dist/e2e/template/e2e/support/mouse-annotations.ts

@@ -0,0 +1,162 @@
+import { Locator, Page } from '@playwright/test'
+
+type Coordinate = {
+  top: number
+  left: number
+}
+
+/**
+ * Checks if an element with id ` playwright-mousepointer` exists in the page and returns it.
+ * If it does not exist, it creates a new element in the center of the page and returns it.
+ */
+async function getFakeMousePointerElement(page: Page) {
+  const fakeMousePointerElement = await page.$('#playwright-mousepointer')
+  if (fakeMousePointerElement) {
+    return fakeMousePointerElement
+  }
+  return page.evaluateHandle(() => {
+    const div = document.createElement('div')
+    div.id = 'playwright-mousepointer'
+    div.style.position = 'fixed'
+    div.style.top = '0px'
+    div.style.left = '0px'
+    div.style.width = '15px'
+    div.style.height = '15px'
+    div.style.borderRadius = '50%'
+    div.style.backgroundColor = 'blue'
+    div.style.border = '2px solid white'
+    div.style.boxShadow = '0 0 5px rgba(0, 0, 0, 0.5)'
+    div.style.zIndex = '999999'
+    div.style.pointerEvents = 'none' // Ensures the fake pointer doesn't interfere with real pointer events
+    document.body.appendChild(div)
+    return div
+  })
+}
+
+/**
+ * Moves a fake mouse pointer to the specified item with an offset and adds scaling animations.
+ *
+ * @example
+ * const item = page.locator('.some-class');
+ * await moveMouse(item, { top: 10, left: 30 });
+ */
+export async function moveMouse(item: Locator, offset: Coordinate = { top: 0, left: 20 }) {
+  const firstItem = item.nth(0)
+  if (!firstItem) {
+    return
+  }
+  const boundingBox = await firstItem.boundingBox()
+  if (!boundingBox) {
+    return
+  }
+
+  const targetPostion = { left: boundingBox.x + offset.left, top: boundingBox.y + boundingBox.height / 2 + offset.top }
+
+  const page = item.page()
+  const mousePointer = await getFakeMousePointerElement(page)
+
+  //add animation that moves the mousepointer to the new position
+  await mousePointer.evaluate((element: HTMLElement, { left, top }) => {
+    element.style.transition = 'transform 1.0s'
+    element.style.transform = `translate(${left}px, ${top}px)`
+  }, targetPostion)
+
+  await page.waitForTimeout(1200)
+
+  await mousePointer.evaluate((element: HTMLElement) => {
+    const scaleTransform = `scale(0.2)`
+    let transform = element.style.transform
+    if (transform.includes('scale')) {
+      transform = transform.replace(/scale\([0-9.]+\)/, scaleTransform)
+    }
+    transform = `${transform} ${scaleTransform}`
+
+    element.style.transition = 'transform 0.2s'
+    element.style.transform = transform
+  })
+  await page.waitForTimeout(200)
+
+  await mousePointer.evaluate((element: HTMLElement) => {
+    const scaleTransform = `scale(1.0)`
+    let transform = element.style.transform
+    if (transform.includes('scale')) {
+      transform = transform.replace(/scale\([0-9.]+\)/, scaleTransform)
+    }
+    transform = `${transform} ${scaleTransform}`
+
+    element.style.transition = 'transform 0.2s'
+    element.style.transform = transform
+  })
+  await page.waitForTimeout(200)
+}
+
+/**
+ * Displays an annotation message on the given page.
+ *
+ * @example
+ * const page = await browser.newPage();
+ * await annotate(page, 'This is an annotation message.');
+ */
+export async function annotate(page: Page, message: string) {
+  const annotationElement = await getAnnotationElement(page)
+
+  return annotationElement.evaluate((element, message) => {
+    element.style.display = 'block'
+    element.textContent = message
+  }, message)
+}
+
+// AnnotationElement is a div at the bottom of the screen that displays the message
+// The messsage is on top of everyhting else and a box with white background, gray border and black text
+// The text is centered and the height of the div changes based on the length of the message - while the width is constant 1000px
+// The method checks if an element with the id "annotation" exists and returns it - else it creates it
+
+/**
+ * Retrieves the annotation element from the page. If it doesn't exist, creates and returns a new annotation element.
+ *
+ * @example
+ * const page = await browser.newPage();
+ * const annotationElement = await getAnnotationElement(page);
+ */
+
+async function getAnnotationElement(page: Page) {
+  const annotationElement = await page.$('#playwright-annotation')
+  if (annotationElement) {
+    return annotationElement
+  }
+  return page.evaluateHandle(() => {
+    const annotationElement = document.createElement('div')
+    annotationElement.id = 'playwright-annotation'
+    annotationElement.style.position = 'fixed'
+    annotationElement.style.bottom = '5%'
+    annotationElement.style.left = '20%'
+    annotationElement.style.width = '60%'
+    annotationElement.style.height = 'auto'
+    annotationElement.style.backgroundColor = 'rgba(250, 220, 217, 0.9)'
+    annotationElement.style.border = '1px solid gray'
+    annotationElement.style.color = 'black'
+    annotationElement.style.textAlign = 'center'
+    annotationElement.style.zIndex = '999999'
+    annotationElement.style.pointerEvents = 'none'
+    annotationElement.style.fontSize = '24px'
+    annotationElement.style.fontWeight = 'bold'
+    annotationElement.style.padding = '20px'
+    document.body.appendChild(annotationElement)
+    return annotationElement
+  })
+}
+
+/**
+ * Hides the annotation element on the given page.
+ *
+ * @example
+ * const page = await browser.newPage();
+ * await hideAnnotation(page);
+ */
+
+export async function hideAnnotation(page: Page) {
+  const annotationElement = await getAnnotationElement(page)
+  return annotationElement.evaluate((element) => {
+    element.style.display = 'none'
+  })
+}

package/dist/e2e/template/e2e/support/page-stability.ts

@@ -0,0 +1,86 @@
+import { BrowserContext, Page, Request } from '@playwright/test'
+
+const pendingRequests = new WeakMap<Page, Set<Request>>()
+
+function isApiRequest(request: Request, apiOrigin: string, apiPort: string): boolean {
+  try {
+    const url = new URL(request.url())
+    return url.origin === apiOrigin || url.port === apiPort || url.pathname.includes('/trpc')
+  } catch {
+    return false
+  }
+}
+
+function trackPage(page: Page, apiOrigin: string, apiPort: string) {
+  if (pendingRequests.has(page)) {
+    return
+  }
+
+  const trackedRequests = new Set<Request>()
+  pendingRequests.set(page, trackedRequests)
+
+  const markCompleted = (request: Request) => {
+    if (trackedRequests.has(request)) {
+      trackedRequests.delete(request)
+    }
+  }
+
+  page.on('request', (request) => {
+    if (isApiRequest(request, apiOrigin, apiPort)) {
+      trackedRequests.add(request)
+    }
+  })
+  page.on('requestfinished', markCompleted)
+  page.on('requestfailed', markCompleted)
+  page.on('close', () => {
+    pendingRequests.delete(page)
+  })
+}
+
+/**
+ * Registers a browser context to track API request stability across all pages.
+ *
+ * This function sets up request tracking for all current and future pages in the given
+ * browser context. It monitors API requests to determine when the application becomes
+ * "idle" (no pending API requests). The tracking includes requests to the specified
+ * API origin, port, or any tRPC endpoints.
+ *
+ */
+export function registerContextForStability(context: BrowserContext, apiUrl: URL) {
+  const apiOrigin = apiUrl.origin
+  const apiPort = apiUrl.port || '80'
+
+  context.on('page', (page) => {
+    trackPage(page, apiOrigin, apiPort)
+  })
+
+  for (const page of context.pages()) {
+    trackPage(page, apiOrigin, apiPort)
+  }
+}
+
+/**
+ * Waits for a page to become "idle" by ensuring all tracked API requests have completed.
+ *
+ * This function polls the page's pending request tracker and waits until no API requests
+ * are in-flight. It's useful for ensuring the application has finished loading data
+ * before proceeding with test assertions or interactions.
+ *
+ */
+export async function waitForAppIdle(page: Page, timeout = 10_000) {
+  const start = Date.now()
+  while (Date.now() - start < timeout) {
+    if (page.isClosed()) {
+      return
+    }
+
+    const tracked = pendingRequests.get(page)
+    if (!tracked || tracked.size === 0) {
+      return
+    }
+
+    await page.waitForTimeout(50)
+  }
+
+  throw new Error(`Timed out waiting for app to become idle after ${timeout}ms`)
+}

package/dist/e2e/template/e2e/support/reset-data.ts

@@ -0,0 +1,38 @@
+import { TEST_CONFIG } from 'playwright.config'
+
+import { getBackendMode } from './get-backend-mode'
+
+export async function resetData(): Promise<{ status: number; message: string }> {
+  // Check the backend mode
+  const backendMode = await getBackendMode()
+  if (backendMode !== 'stateful') {
+    console.warn('Backend is in stateless mode. Skipping data reset.')
+    // Return a 204 status code to indicate that the request was understood and accepted,
+    // but no action was taken (e.g., skipping the reset operation in stateless mode).
+    return { status: 204, message: 'Backend is in stateless mode. Skipping data reset.' }
+  }
+
+  if (!TEST_CONFIG.apiURL) {
+    throw new Error('API_URL environment variable not set')
+  }
+
+  // Use the reset endpoint to reset the test data
+  const response = await fetch(`${TEST_CONFIG.apiURL}/test/reset`, { method: 'PUT' })
+
+  // Handle different status codes
+  switch (response.status) {
+    case 200: // Success
+      console.log('Reset data successfully')
+      return { status: 200, message: 'Reset data successfully' }
+
+    case 404: // Not Found
+      console.log('Reset endpoint not available: 404 Not Found')
+      return { status: 404, message: 'Reset endpoint not available: 404 Not Found' }
+
+    default: // Other errors
+      return {
+        status: response.status,
+        message: `Reset data failed with status ${response.status}: ${response.statusText}`,
+      }
+  }
+}

package/dist/e2e/template/e2e/support/set-data.ts

@@ -0,0 +1,44 @@
+import { TEST_CONFIG } from 'playwright.config'
+
+import { getBackendMode } from './get-backend-mode'
+
+export async function setData(data: any): Promise<{ status: number; message: string }> {
+  // Check the backend mode
+  const backendMode = await getBackendMode()
+  if (backendMode !== 'stateful') {
+    console.warn('Backend is in stateless mode. Skipping data reset.')
+    // Return a 204 status code to indicate that the request was understood and accepted,
+    // but no action was taken (e.g., skipping the reset operation in stateless mode).
+    return { status: 204, message: 'Backend is in stateless mode. Skipping data reset.' }
+  }
+
+  if (!TEST_CONFIG.apiURL) {
+    throw new Error('API_URL environment variable not set')
+  }
+
+  // Use the reset endpoint to reset the test data
+  const response = await fetch(`${TEST_CONFIG.apiURL}/test/reset`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(data),
+  })
+
+  // Handle different status codes
+  switch (response.status) {
+    case 200: // Success
+      console.log('Reset data successfully')
+      return { status: 200, message: 'Reset data successfully' }
+
+    case 404: // Not Found
+      console.log('Reset endpoint not available: 404 Not Found')
+      return { status: 404, message: 'Reset endpoint not available: 404 Not Found' }
+
+    default: // Other errors
+      return {
+        status: response.status,
+        message: `Reset data failed with status ${response.status}: ${response.statusText}`,
+      }
+  }
+}

package/dist/e2e/template/e2e/support/wait-for-page-loaded.ts

@@ -0,0 +1,28 @@
+import { Page } from '@playwright/test'
+
+/**
+ * Waits for the page to be fully loaded, including all DOM content and images.
+ *
+ * This function first waits for the 'domcontentloaded' event, ensuring that the
+ * HTML document has been completely loaded and parsed. It then evaluates the
+ * page's DOM and waits for all images on the page to load, resolving when all
+ * images have either loaded successfully or encountered an error.
+ */
+export async function waitForPageLoaded(page: Page) {
+  // use domcontentloaded to wait for the page to be fully loaded
+  await page.waitForLoadState('domcontentloaded')
+
+  // evaluate the page's DOM and wait for all images to be loaded
+  await page.evaluate(() => {
+    return Promise.all(
+      Array.from(document.images).map((img) => {
+        if (img.complete) {
+          return
+        }
+        return new Promise((resolve) => {
+          img.onload = img.onerror = resolve
+        })
+      }),
+    )
+  })
+}

package/dist/e2e/template/e2e/tsconfig.json

@@ -0,0 +1,51 @@
+{
+  "ts-node": {
+    "require": ["tsconfig-paths/register"]
+  },
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2019",
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "lib": ["ESNext", "dom"],
+    "types": ["node"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "strictBindCallApply": true,
+    "strictFunctionTypes": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "resolveJsonModule": true,
+    "useUnknownInCatchVariables": true,
+    "paths": {
+      "@actions/*": ["../backend/libs/actions/src/*"],
+      "@authentication/*": ["../backend/libs/authentication/src/*"],
+      "@database/*": ["../backend/libs/database/src/*"],
+      "@decoders/*": ["../backend/libs/decoders/src/*"],
+      "@e2e/*": ["../backend/libs/e2e/src/*"],
+      "@import/*": ["../backend/libs/import/src/*"],
+      "@repositories/*": ["../backend/libs/repositories/src/*"],
+      "@router-trpc/*": ["../backend/libs/router-trpc/src/*"],
+      "@seed/*": ["../backend/libs/seed/src/*"],
+      "@seedData/*": ["../backend/libs/seedData/src/*"],
+      "@types": ["../backend/libs/types/src"],
+      "@types/*": ["../backend/libs/types/src/*"],
+      "@update/*": ["../backend/libs/update/src/*"],
+      "@mock-data/*": ["../backend/libs/mock-data/src/*"],
+      "@view/*": ["../backend/libs/view/src/*"],
+      "@xlport/*": ["../backend/libs/xlport/src/*"]
+    }
+  },
+  "include": ["./**/*.ts"]
+}

package/dist/e2e/template/scripts/docker.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Define a name for the image
+IMAGE_NAME="e2e-pxl-env"
+
+# Build the image from the Dockerfile in the current directory
+docker build -t $IMAGE_NAME ./e2e/
+
+# Run a container from the built image
+# Add user mapping only on Linux/WSL to avoid permission issues with mounted volumes
+USER_FLAG=""
+if [[ "$(uname)" = "Linux" ]]; then
+    USER_FLAG="-u $(id -u):$(id -g)"
+fi
+
+docker run -p 3030:3030 $USER_FLAG -v ${PWD}/../..:/pxl -w /pxl/projects/<%schema.slug%>/e2e --rm -it $IMAGE_NAME /bin/bash
+

package/dist/frontend-admin/admin.generator.d.ts

@@ -0,0 +1,75 @@
+import * as Generator from '@postxl/generator';
+import { WithBackendTrpcRouter } from '../backend-router-trpc';
+import { WithBase } from '../base';
+import { WithFrontend } from '../frontend-core';
+import { WithForms } from '../frontend-forms';
+import { WithTables } from '../frontend-tables';
+import { WithTrpcClient } from '../frontend-trpc-client/trpc-client.generator';
+import { WithTypes } from '../types';
+type ContextRequirements = WithTables<WithFrontend<WithForms<WithTrpcClient<WithBackendTrpcRouter<WithTypes<WithBase<Generator.Context>>>>>>>;
+export type ModelContextRequirements = Generator.InferModelContext<ContextRequirements>;
+export type EnumContextRequirements = Generator.InferEnumContext<ContextRequirements>;
+export type ContextResult = WithAdmin<ContextRequirements>;
+export type ModelContextResult = Generator.InferModelContext<ContextResult>;
+export type WithAdmin<Context> = Generator.ExtendContextAndModel<Context, {
+    /**
+     * Admin module configuration
+     */
+    admin: ContextAdmin;
+}, {
+    /**
+     * Admin module configuration for the model
+     */
+    admin: ModelContextAdmin;
+}>;
+export type Page = {
+    /**
+     * The component for the page
+     */
+    pageComponent: Generator.ImportableFunction;
+    /**
+     * The route path for the page, e.g. `/admin/user`
+     */
+    route: string;
+    /**
+     * Optional aliases for the page route, e.g. `/admin/users`
+     */
+    aliases?: string[];
+    /**
+     * If true, the page is an outlet route and an index page will be created in addition to the outlet
+     */
+    isOutlet?: boolean;
+};
+type ContextAdmin = {
+    components: {
+        /**
+         * Sidebar component for the Admin UI
+         */
+        sidebar: Generator.ImportableFunction;
+        /**
+         * Audit Log Sidebar component for the Admin UI
+         */
+        auditLogSidebar: Generator.ImportableFunction;
+    };
+    pages: {
+        /**
+         * Admin Overview Page
+         */
+        overview: Page;
+        dataManagement: Page;
+    };
+};
+type ModelContextAdmin = {
+    /**
+     * Admin Page for the model
+     */
+    page: Page;
+};
+export type PagePaths = {
+    pages: string;
+    routes: string;
+    components: string;
+};
+export declare const generatorId: string & import("zod").BRAND<"PXL.GeneratorInterfaceId">;
+export declare const generator: Generator.GeneratorInterface;
+export {};