@cavulsqa/create 2.9.3 → 2.10.0

package/templates/m3e-app/src/shared/database/schema.ts

@@ -0,0 +1,153 @@
+import type { Generated } from "kysely";
+
+/**
+ * A small relational schema rather than one flat table, so the demo can show what the reactive
+ * layer is actually for: a write to one table refreshing a screen that reads three others through
+ * joins and aggregates.
+ *
+ * customer 1-N sales_order 1-N order_line N-1 product, plus customer N-N tag through customer_tag.
+ */
+export interface CustomerTable {
+  id: Generated<number>;
+  created_at: string;
+  name: string;
+  city: string;
+}
+
+export interface ProductTable {
+  id: Generated<number>;
+  created_at: string;
+  name: string;
+  /** Integer cents. Money in a float is a rounding bug waiting for a total. */
+  price_cents: number;
+}
+
+export interface SalesOrderTable {
+  id: Generated<number>;
+  created_at: string;
+  customer_id: number;
+  reference: string;
+  status: "draft" | "confirmed" | "delivered";
+}
+
+export interface OrderLineTable {
+  id: Generated<number>;
+  order_id: number;
+  product_id: number;
+  quantity: number;
+  /** Copied from the product at the time of sale, so later price changes do not rewrite history. */
+  unit_price_cents: number;
+}
+
+export interface TagTable {
+  id: Generated<number>;
+  label: string;
+}
+
+export interface CustomerTagTable {
+  customer_id: number;
+  tag_id: number;
+}
+
+export interface Database {
+  customer: CustomerTable;
+  product: ProductTable;
+  sales_order: SalesOrderTable;
+  order_line: OrderLineTable;
+  tag: TagTable;
+  customer_tag: CustomerTagTable;
+  bench_region: BenchRegionTable;
+  bench_city: BenchCityTable;
+  bench_customer: BenchCustomerTable;
+  bench_category: BenchCategoryTable;
+  bench_product: BenchProductTable;
+  bench_warehouse: BenchWarehouseTable;
+  bench_stock: BenchStockTable;
+  bench_order: BenchOrderTable;
+  bench_order_line: BenchOrderLineTable;
+  bench_payment: BenchPaymentTable;
+}
+
+/**
+ * The benchmark's own tables, deliberately separate from the app's.
+ *
+ * Ten tables at roughly 100k rows, shaped like a distribution domain - regions down to order lines,
+ * plus stock and payments - because the questions worth answering are about joins across a real
+ * cardinality spread, not about two tables with a foreign key. A five-level join here touches a
+ * 10-row table and a 40k-row table in the same query, which is where planners and indexes start to
+ * matter.
+ *
+ * Measuring against the app's own tables would either corrupt them or force a rollback, and a
+ * rolled-back transaction never pays the commit - most of what a write costs on a phone.
+ */
+export interface BenchRegionTable {
+  id: Generated<number>;
+  name: string;
+}
+
+export interface BenchCityTable {
+  id: Generated<number>;
+  region_id: number;
+  name: string;
+}
+
+export interface BenchCustomerTable {
+  id: Generated<number>;
+  city_id: number;
+  code: string;
+  name: string;
+  /** Unindexed on purpose: the LIKE case needs a genuine full scan over 5k rows. */
+  notes: string;
+  credit_cents: number;
+  created_at: string;
+}
+
+export interface BenchCategoryTable {
+  id: Generated<number>;
+  name: string;
+}
+
+export interface BenchProductTable {
+  id: Generated<number>;
+  category_id: number;
+  sku: string;
+  name: string;
+  price_cents: number;
+}
+
+export interface BenchWarehouseTable {
+  id: Generated<number>;
+  name: string;
+}
+
+export interface BenchStockTable {
+  id: Generated<number>;
+  warehouse_id: number;
+  product_id: number;
+  quantity: number;
+}
+
+export interface BenchOrderTable {
+  id: Generated<number>;
+  customer_id: number;
+  reference: string;
+  status: string;
+  created_at: string;
+  total_cents: number;
+}
+
+export interface BenchOrderLineTable {
+  id: Generated<number>;
+  order_id: number;
+  product_id: number;
+  quantity: number;
+  unit_price_cents: number;
+}
+
+export interface BenchPaymentTable {
+  id: Generated<number>;
+  order_id: number;
+  amount_cents: number;
+  method: string;
+  created_at: string;
+}

package/templates/m3e-app/src/shared/database/storage.ts

@@ -0,0 +1,64 @@
+import type { StorageProbe } from "./candidates/types";
+
+export type { StorageProbe };
+
+/**
+ * `navigator.storage.getDirectory` is the whole of what a main-thread probe can see. Synchronous
+ * access handles are Worker-only in Chromium, so checking `createSyncAccessHandle` on
+ * `FileSystemFileHandle.prototype` is false on *every* device - it rejected a phone that had been
+ * running OPFS for hours. Anything finer belongs to the engine, via `describeOpenFailure`.
+ */
+export function probeOpfsCapable(): StorageProbe {
+  if (typeof navigator === "undefined" || !navigator.storage?.getDirectory) {
+    return {
+      supported: false,
+      reason:
+        "This WebView has no Origin Private File System, so the database cannot be stored. Update " +
+        "Android System WebView from the Play Store - it updates separately from Android itself.",
+    };
+  }
+
+  return { supported: true };
+}
+
+export function probeIndexedDb(): StorageProbe {
+  if (typeof indexedDB === "undefined") {
+    return {
+      supported: false,
+      reason: "This WebView has no IndexedDB, which leaves nowhere to keep the database.",
+    };
+  }
+  return { supported: true };
+}
+
+export function describeOpenFailure(error: unknown): string {
+  const detail = error instanceof Error ? error.message : String(error);
+
+  if (/SyncAccessHandle|createSyncAccessHandle|sahpool|SAH/i.test(detail)) {
+    return (
+      "SQLite could not take a synchronous file handle. Either this WebView is too old - update " +
+      "Android System WebView from the Play Store, it updates separately from Android - or another " +
+      `copy of the app still holds the database open. (${detail})`
+    );
+  }
+
+  return `The database could not be opened: ${detail}`;
+}
+
+/**
+ * Android System WebView updates from the Play Store independently of Android itself, so the OS
+ * version says nothing useful here - a phone on Android 7 can be current and one on Android 14 old.
+ */
+export function webviewVersion(): number | null {
+  if (typeof navigator === "undefined") return null;
+  const match = /Chrome\/(\d+)/.exec(navigator.userAgent);
+  return match ? Number(match[1]) : null;
+}
+
+/** Advice, never a gate: a vendor WebView build can differ either way, so the engine decides. */
+export const MINIMUM_CHROMIUM_FOR_OPFS = 109;
+
+export function webviewLikelyTooOld(): boolean {
+  const version = webviewVersion();
+  return version !== null && version < MINIMUM_CHROMIUM_FOR_OPFS;
+}

package/templates/m3e-app/src/shared/database/wa.worker.ts

@@ -0,0 +1,5 @@
+import { runWaWorker } from "@cavulsqa/mobile-db/wa";
+
+// The whole worker. It lives in the app because only the app's bundler can emit a worker and the
+// wa-sqlite wasm it loads; the logic is all in @cavulsqa/mobile-db.
+runWaWorker();

package/templates/m3e-app/src/shared/utils/lazyRoute.ts

@@ -0,0 +1,41 @@
+import type { Router } from "framework7/types";
+import { i18n } from "@/plugins/i18n.plugin";
+import { m3e } from "@/plugins/m3e.plugin";
+
+type RouteComponentModule = { default: unknown };
+
+/**
+ * Framework7 sets `allowPageChange = false` before calling a route's async hook and only restores
+ * it from `resolve` or `reject`. A hook that settles neither - a chunk that fails to download, or a
+ * module that throws while evaluating - leaves that view's router locked for the rest of the
+ * session, so every later navigation and back press is silently ignored. Routing the import
+ * through here guarantees the router is always released.
+ *
+ * A failed tap must not look like a dead button, so the failure also says so, with a reload: the
+ * browser can keep a failed module import for the life of the document, which makes a plain retry
+ * fail the same way.
+ */
+export function lazyRoute(
+  load: () => Promise<RouteComponentModule>,
+): Router.RouteParameters["async"] {
+  return function routeAsync({ resolve, reject }) {
+    load()
+      .then((module) => {
+        resolve({ component: module.default });
+      })
+      .catch((error: unknown) => {
+        console.error("[router] Unable to load route component", error);
+        reject();
+        void reportFailure();
+      });
+  };
+}
+
+async function reportFailure(): Promise<void> {
+  const { t } = i18n.global;
+  const result = await m3e.config.snackbar.show({
+    message: t("shell.routeFailed"),
+    action: t("shell.reload"),
+  });
+  if (result === "action") window.location.reload();
+}

package/templates/m3e-app/src/shared/utils/resolvers/resolvers.ts

@@ -0,0 +1,42 @@
+import type { ComponentResolver } from "unplugin-vue-components/types";
+
+/**
+ * Framework7 is this template's navigation engine and nothing else: the app root, the tab views,
+ * each view's router and the page lifecycle the reactive queries pause on. Everything you see is a
+ * Material 3 Expressive component from @cavulsqa/m3e-vue. The allowlist is the boundary - adding a
+ * visual `f7-*` component here brings Framework7's styling back, which is what this flavour exists
+ * to avoid.
+ */
+const ENGINE_COMPONENTS = new Set(["f7-app", "f7-views", "f7-view", "f7-page", "f7-page-content"]);
+
+const toCamelCase = (value: string) =>
+  value.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+
+function kebabOf(name: string): string | null {
+  if (/^F7[A-Z]/.test(name))
+    return name
+      .replace(/^F7/, "f7-")
+      .replace(/([a-z])([A-Z])/g, "$1-$2")
+      .toLowerCase();
+  if (name.startsWith("f7-")) return name;
+  return null;
+}
+
+export function Framework7VueResolver(): ComponentResolver {
+  return {
+    type: "component",
+    resolve: (name: string) => {
+      const kebab = kebabOf(name);
+      if (kebab && ENGINE_COMPONENTS.has(kebab))
+        return { name: toCamelCase(kebab), from: "framework7-vue" };
+      return undefined;
+    },
+  };
+}
+
+export function getFramework7AutoImports() {
+  return {
+    "framework7/lite": ["utils", "getDevice", "Dom7"],
+    "framework7-vue": ["f7ready", "f7"],
+  };
+}

package/templates/m3e-app/src/shared/utils/textDirection.ts

@@ -0,0 +1,22 @@
+const RIGHT_TO_LEFT = new Set(["ar", "arc", "ckb", "dv", "fa", "he", "ps", "sd", "ug", "ur", "yi"]);
+
+interface TextInfoLocale {
+  getTextInfo?: () => { direction?: string };
+  textInfo?: { direction?: string };
+}
+
+/**
+ * Which way a language is written. Asks the engine first (`Intl.Locale` text info), then a list of
+ * the right-to-left scripts' languages, so Arabic lays out mirrored even on a WebView that predates
+ * the API.
+ */
+export function textDirection(locale: string): "ltr" | "rtl" {
+  try {
+    const info = new Intl.Locale(locale) as Intl.Locale & TextInfoLocale;
+    const direction = (info.getTextInfo?.() ?? info.textInfo)?.direction;
+    if (direction === "rtl" || direction === "ltr") return direction;
+  } catch {
+    return "ltr";
+  }
+  return RIGHT_TO_LEFT.has(locale.split(/[-_]/)[0]!.toLowerCase()) ? "rtl" : "ltr";
+}

package/templates/m3e-app/src/shared/utils/theme/themeSettings.ts

@@ -0,0 +1,59 @@
+import { CONTRAST, SCHEME_VARIANTS, isHexColor, type SchemeVariant } from "@cavulsqa/m3e";
+import { BRAND_SEED, DEFAULT_VARIANT } from "@/app/theme.config";
+
+export type ContrastChoice = "standard" | "medium" | "high";
+export type ModeChoice = "system" | "light" | "dark";
+export type MotionChoice = "system" | "reduced" | "full";
+
+export interface ThemeSettings {
+  seed: string;
+  variant: SchemeVariant;
+  contrast: ContrastChoice;
+  mode: ModeChoice;
+  motion: MotionChoice;
+}
+
+export const DEFAULT_THEME: Readonly<ThemeSettings> = {
+  seed: BRAND_SEED,
+  variant: DEFAULT_VARIANT,
+  contrast: "standard",
+  mode: "system",
+  motion: "system",
+};
+
+export const CONTRAST_LEVELS: Readonly<Record<ContrastChoice, number>> = {
+  standard: CONTRAST.standard,
+  medium: CONTRAST.medium,
+  high: CONTRAST.high,
+};
+
+const oneOf = <T extends string>(value: unknown, options: readonly T[], fallback: T): T =>
+  typeof value === "string" && (options as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback;
+
+/**
+ * Settings read back from storage are untrusted text: an older build, a hand-edited value, a
+ * variant this build no longer offers. Every field is checked and falls back on its own, so one
+ * bad value never costs the user the rest of their choices.
+ */
+export function parseThemeSettings(raw: unknown): ThemeSettings {
+  const value = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
+  return {
+    seed:
+      typeof value.seed === "string" && isHexColor(value.seed) ? value.seed : DEFAULT_THEME.seed,
+    variant: oneOf(value.variant, SCHEME_VARIANTS, DEFAULT_THEME.variant),
+    contrast: oneOf(
+      value.contrast,
+      ["standard", "medium", "high"] as const,
+      DEFAULT_THEME.contrast,
+    ),
+    mode: oneOf(value.mode, ["system", "light", "dark"] as const, DEFAULT_THEME.mode),
+    motion: oneOf(value.motion, ["system", "reduced", "full"] as const, DEFAULT_THEME.motion),
+  };
+}
+
+export function reducedMotionOverride(motion: MotionChoice): boolean | null {
+  if (motion === "system") return null;
+  return motion === "reduced";
+}

package/templates/m3e-app/src/shared/utils/tone.ts

@@ -0,0 +1,8 @@
+export type Tone = "primary" | "secondary" | "tertiary";
+
+/** A container and its content colour, for decorative shapes that need a hue but carry no state. */
+export const TONE_CLASSES: Readonly<Record<Tone, string>> = {
+  primary: "bg-primary-container text-on-primary-container",
+  secondary: "bg-secondary-container text-on-secondary-container",
+  tertiary: "bg-tertiary-container text-on-tertiary-container",
+};

package/templates/m3e-app/tests/benchmark.suite.test.ts

@@ -0,0 +1,104 @@
+import { expect, test } from "vite-plus/test";
+import { Kysely } from "kysely";
+import { Migrator } from "kysely/migration";
+import { createSqlJsDialect } from "@cavulsqa/mobile-db/testing";
+import { runBenchmark } from "../src/domains/benchmark/benchmark.suite.js";
+import { datasetRowCount, SCALE, TOTAL_ROWS } from "../src/domains/benchmark/benchmark.dataset.js";
+import { migrations } from "../src/shared/database/migrations.js";
+import type { Database } from "../src/shared/database/schema.js";
+
+async function open(): Promise<Kysely<Database>> {
+  const db = new Kysely<Database>({ dialect: await createSqlJsDialect() });
+  await new Migrator({
+    db,
+    provider: { getMigrations: () => Promise.resolve(migrations) },
+  }).migrateToLatest();
+  return db;
+}
+
+/**
+ * The suite seeds roughly 100k rows across ten tables and runs 24 cases, several of them six-table
+ * joins. A broken case would otherwise surface halfway through a run on a phone, as a number nobody
+ * could interpret - so it executes here against real SQLite first.
+ *
+ * Slow by design: this is the only place the whole thing runs without a device.
+ */
+test("the whole suite runs at scale and every case reports a timing", async () => {
+  const db = await open();
+
+  const seen: string[] = [];
+  const result = await runBenchmark(db, (name) => seen.push(name));
+
+  expect(result.cases.length).toBeGreaterThanOrEqual(27);
+  expect(result.seedMs, "the first run builds the dataset").toBeGreaterThan(0);
+  expect(result.rowsSeeded).toBeGreaterThanOrEqual(SCALE.orderLines + SCALE.stock);
+
+  for (const entry of result.cases) {
+    expect(entry.operations, entry.name).toBeGreaterThan(0);
+    expect(entry.msPerOperation, entry.name).toBeGreaterThanOrEqual(0);
+    expect(entry.worstMs, entry.name).toBeGreaterThanOrEqual(entry.medianMs);
+  }
+
+  // All six groups represented, or the suite is not covering what it claims to.
+  expect([...new Set(result.cases.map((entry) => entry.group))].sort()).toEqual([
+    "concurrency",
+    "join",
+    "read",
+    "schema",
+    "sync",
+    "transaction",
+    "write",
+  ]);
+
+  /**
+   * The sync cases measure how long a read waits, so a zero would mean the read never queued behind
+   * the write and the case proved nothing.
+   */
+  for (const entry of result.cases.filter((c) => c.group === "sync")) {
+    expect(entry.medianMs, entry.name).toBeGreaterThan(0);
+  }
+
+  // Read and join cases must actually return rows; a fast case that returns none proves nothing.
+  for (const entry of result.cases.filter((c) => c.group === "join")) {
+    expect(entry.rows, `${entry.name} returned no rows`).toBeGreaterThan(0);
+  }
+}, 600_000);
+
+/**
+ * The dataset has to survive a run untouched, or every subsequent run measures a different database
+ * and two runs cannot be compared.
+ */
+test("a run leaves the dataset exactly as it found it", async () => {
+  const db = await open();
+  await runBenchmark(db);
+  const after = await datasetRowCount(db);
+
+  await runBenchmark(db);
+  expect(await datasetRowCount(db)).toBe(after);
+
+  // And nothing the write cases created is left behind.
+  const strays = await db
+    .selectFrom("bench_payment")
+    .select(({ fn }) => fn.countAll<number>().as("n"))
+    .where("method", "like", "bench-%")
+    .executeTakeFirstOrThrow();
+  expect(Number(strays.n)).toBe(0);
+}, 600_000);
+
+test("the scale constants add up to about 100k rows", () => {
+  expect(TOTAL_ROWS).toBeGreaterThan(100_000);
+  expect(SCALE.orderLines).toBe(40_000);
+});
+
+test("the benchmark never touches the app's tables", async () => {
+  const db = await open();
+  await db
+    .insertInto("customer")
+    .values({ created_at: "2026-01-01T00:00:00.000Z", name: "Untouched", city: "Algiers" })
+    .execute();
+
+  await runBenchmark(db);
+
+  const customers = await db.selectFrom("customer").select("name").execute();
+  expect(customers.map((row) => row.name)).toEqual(["Untouched"]);
+}, 600_000);

package/templates/m3e-app/tests/containerTransform.test.ts

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+import { expect, test, vi } from "vite-plus/test";
+import {
+  CONTAINER_TRANSITION,
+  useContainerTransform,
+} from "../src/shared/composables/navigation/useContainerTransform.js";
+
+function rect(left: number, top: number, width: number, height: number) {
+  return {
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+  } as DOMRect;
+}
+
+test("a card inside a view opens its page with the container transform, from its own box", () => {
+  const view = document.createElement("div");
+  view.className = "view";
+  const card = document.createElement("div");
+  card.className = "m3-card";
+  card.style.backgroundColor = "rgb(1, 2, 3)";
+  card.style.borderTopLeftRadius = "12px";
+  const label = document.createElement("span");
+  card.append(label);
+  view.append(card);
+  document.body.append(view);
+  vi.spyOn(view, "getBoundingClientRect").mockReturnValue(rect(0, 0, 360, 800));
+  vi.spyOn(card, "getBoundingClientRect").mockReturnValue(rect(16, 200, 328, 80));
+
+  const navigate = vi.fn();
+  const { open } = useContainerTransform();
+  label.addEventListener("click", (event) => open({ navigate } as never, event, "/x/"));
+  label.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+
+  expect(navigate).toHaveBeenCalledWith("/x/", { transition: CONTAINER_TRANSITION });
+  const value = (name: string) => view.style.getPropertyValue(`--m3e-ct-${name}`);
+  expect([value("top"), value("left"), value("right"), value("bottom")]).toEqual([
+    "200px",
+    "16px",
+    "16px",
+    "520px",
+  ]);
+  expect(value("radius")).toBe("12px");
+  expect(value("color")).toBe("rgb(1, 2, 3)");
+  view.remove();
+});
+
+test("without a view to grow in, it navigates the ordinary way", () => {
+  const navigate = vi.fn();
+  const { open } = useContainerTransform();
+  open({ navigate } as never, document.createElement("div"), "/y/");
+  expect(navigate).toHaveBeenCalledWith("/y/");
+});

package/templates/m3e-app/tests/fieldFormats.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "vite-plus/test";
+import {
+  formatMobile,
+  isMobile,
+  mobileDigits,
+  passwordScore,
+} from "../src/modules/gallery/composables/fieldFormats.js";
+
+test("a password scores by length and by the kinds of character in it", () => {
+  expect(passwordScore("abc")).toBe(0);
+  expect(passwordScore("abcdefgh")).toBe(1);
+  expect(passwordScore("abcdefghijklmn")).toBe(1);
+  expect(passwordScore("Abcdefg1")).toBe(3);
+  expect(passwordScore("Abcdefgh1!xyz")).toBe(4);
+});
+
+test("a mobile number reads the same however its prefix was typed", () => {
+  expect(mobileDigits("0555 12 34 56")).toBe("555123456");
+  expect(mobileDigits("+213 555-123-456")).toBe("555123456");
+  expect(mobileDigits("5551234567")).toBe("555123456");
+  expect(formatMobile("555123456")).toBe("5 55 12 34 56");
+  expect(formatMobile("5551")).toBe("5 55 1");
+  expect(isMobile("555123456")).toBe(true);
+  expect(isMobile("212345678")).toBe(false);
+});

package/templates/m3e-app/tests/lazyRoute.test.ts

@@ -0,0 +1,30 @@
+import { expect, test, vi } from "vite-plus/test";
+import { lazyRoute } from "../src/shared/utils/lazyRoute.js";
+
+function callRoute(handler: ReturnType<typeof lazyRoute>) {
+  const resolve = vi.fn();
+  const reject = vi.fn();
+  (handler as (ctx: unknown) => void)({ resolve, reject });
+  return { resolve, reject };
+}
+
+test("resolves the route with the module's default export", async () => {
+  const component = { name: "HomeView" };
+  const { resolve, reject } = callRoute(lazyRoute(() => Promise.resolve({ default: component })));
+
+  await vi.waitFor(() => expect(resolve).toHaveBeenCalledOnce());
+  expect(resolve).toHaveBeenCalledWith({ component });
+  expect(reject).not.toHaveBeenCalled();
+});
+
+test("rejects the route when the chunk fails to load, releasing the router", async () => {
+  // Without this the router keeps allowPageChange === false forever and the view freezes.
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  const { resolve, reject } = callRoute(
+    lazyRoute(() => Promise.reject(new Error("chunk load failed"))),
+  );
+
+  await vi.waitFor(() => expect(reject).toHaveBeenCalledOnce());
+  expect(resolve).not.toHaveBeenCalled();
+  consoleError.mockRestore();
+});