@cavulsqa/create 2.9.3 → 2.10.0

package/templates/m3e-app/src/modules/demo/components/DemoStatCards.vue

@@ -0,0 +1,71 @@
+<template>
+  <div class="grid grid-cols-2 gap-2 px-4">
+    <div
+      v-for="tile in tiles"
+      :key="tile.labelKey"
+      class="flex flex-col gap-2 rounded-lg p-4"
+      :class="tile.surface"
+    >
+      <div class="flex items-center gap-2">
+        <M3Shape :shape="tile.shape" class="size-8" :class="tile.badge">
+          <component :is="tile.icon" class="size-4" />
+        </M3Shape>
+        <span class="type-label-large opacity-80">{{ t(tile.labelKey) }}</span>
+      </div>
+      <span class="type-headline-small-emphasized tabular-nums">{{ tile.value }}</span>
+      <span v-if="tile.hint" class="type-body-small opacity-70">{{ tile.hint }}</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { DashboardStats } from "@/domains/sales/sales.repository";
+import { STATUS_LOOK, formatMoney } from "@/modules/demo/composables/useOrderStatus";
+import PaymentsIcon from "~icons/material-symbols/monitoring-rounded";
+
+const props = defineProps<{ stats: DashboardStats }>();
+const { t } = useI18n();
+
+/**
+ * Status counts rather than plain totals, because they are what moves when you use the screen:
+ * confirm one order and three of these four change at once, without anything telling them to.
+ */
+const tiles = computed(() => [
+  {
+    icon: STATUS_LOOK.draft.icon,
+    shape: STATUS_LOOK.draft.shape,
+    labelKey: "demo.tiles.draft",
+    surface: "bg-surface-container-low text-on-surface",
+    badge: STATUS_LOOK.draft.classes,
+    value: String(props.stats.draft),
+    hint: t("demo.tiles.ofOrders", { count: props.stats.orders }, props.stats.orders),
+  },
+  {
+    icon: STATUS_LOOK.confirmed.icon,
+    shape: STATUS_LOOK.confirmed.shape,
+    labelKey: "demo.tiles.confirmed",
+    surface: "bg-surface-container-low text-on-surface",
+    badge: STATUS_LOOK.confirmed.classes,
+    value: String(props.stats.confirmed),
+    hint: "",
+  },
+  {
+    icon: STATUS_LOOK.delivered.icon,
+    shape: STATUS_LOOK.delivered.shape,
+    labelKey: "demo.tiles.delivered",
+    surface: "bg-surface-container-low text-on-surface",
+    badge: STATUS_LOOK.delivered.classes,
+    value: String(props.stats.delivered),
+    hint: "",
+  },
+  {
+    labelKey: "demo.tiles.committed",
+    icon: PaymentsIcon,
+    shape: "sunny" as const,
+    surface: "bg-primary-container text-on-primary-container",
+    badge: "bg-primary text-on-primary",
+    value: formatMoney(props.stats.committedCents),
+    hint: t("demo.tiles.ofTotal", { total: formatMoney(props.stats.revenueCents) }),
+  },
+]);
+</script>

package/templates/m3e-app/src/modules/demo/composables/useBenchmark.ts

@@ -0,0 +1,139 @@
+import {
+  runBenchmark,
+  type CaseResult,
+  type SuiteResult,
+} from "@/domains/benchmark/benchmark.suite";
+import { activePragmas, activeStorage, activeStorageLabel, rdb } from "@/shared/database/database";
+import type { StorageId } from "@/shared/database/candidates";
+
+const STORAGE_KEY = "app.benchmark.results";
+
+export interface CaseComparison {
+  name: string;
+  group: CaseResult["group"];
+  note?: string;
+  current: CaseResult;
+  other?: CaseResult;
+  /** How many times faster the current engine is at this case. Below 1 means slower. */
+  speedup?: number;
+}
+
+/**
+ * Results are kept per engine in localStorage, because the comparison is the point and an engine
+ * switch needs a restart - so the two halves can never be in memory at the same time.
+ */
+function readStored(): Partial<Record<StorageId, SuiteResult>> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as Partial<Record<StorageId, SuiteResult>>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeStored(all: Partial<Record<StorageId, SuiteResult>>): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // Out of quota or storage disabled: the run still displayed, it just will not be remembered.
+  }
+}
+
+export function useBenchmark() {
+  const engine = activeStorage().id;
+  const stored = ref(readStored());
+  const running = ref(false);
+  const progress = ref("");
+  const failure = ref<string | null>(null);
+
+  const result = computed<SuiteResult | null>(() => stored.value[engine] ?? null);
+
+  /** The most recent run on any other engine, which is what the current one is measured against. */
+  const baseline = computed<SuiteResult | null>(() => {
+    const others = Object.entries(stored.value)
+      .filter(([key]) => key !== engine)
+      .map(([, value]) => value)
+      .filter((value): value is SuiteResult => Boolean(value));
+    return others.sort((a, b) => b.at - a.at)[0] ?? null;
+  });
+
+  const comparison = computed<CaseComparison[]>(() => {
+    const current = result.value;
+    if (!current) return [];
+
+    return current.cases.map((entry) => {
+      const other = baseline.value?.cases.find((candidate) => candidate.name === entry.name);
+      const speedup =
+        other && entry.msPerOperation > 0
+          ? Number((other.msPerOperation / entry.msPerOperation).toFixed(2))
+          : undefined;
+      return {
+        name: entry.name,
+        group: entry.group,
+        note: entry.note,
+        current: entry,
+        other,
+        speedup,
+      };
+    });
+  });
+
+  async function run(): Promise<void> {
+    if (running.value) return;
+    running.value = true;
+    failure.value = null;
+    progress.value = "";
+
+    try {
+      /**
+       * Reads take the raw Kysely instance and writes go through `rdb`, exactly as the app does -
+       * measuring a write that skipped the change bus would measure something the app never runs.
+       * The suite's own tables are not watched by any query, so nothing refetches while it runs.
+       */
+      const finished = await runBenchmark(rdb, (name) => {
+        progress.value = name;
+      });
+
+      const next = {
+        ...stored.value,
+        [engine]: {
+          ...finished,
+          engine: activeStorageLabel(),
+          pragmas: activePragmas(),
+          at: Date.now(),
+        },
+      };
+      stored.value = next;
+      writeStored(next);
+    } catch (error) {
+      failure.value = error instanceof Error ? error.message : String(error);
+    } finally {
+      running.value = false;
+      progress.value = "";
+    }
+  }
+
+  function clear(): void {
+    stored.value = {};
+    writeStored({});
+  }
+
+  /** For pasting a run into an issue or a commit message rather than retyping numbers. */
+  function asJson(): string {
+    return JSON.stringify(stored.value, null, 2);
+  }
+
+  return {
+    engine,
+    engineName: activeStorageLabel(),
+    running,
+    progress,
+    failure,
+    result,
+    baseline,
+    comparison,
+    run,
+    clear,
+    asJson,
+  };
+}

package/templates/m3e-app/src/modules/demo/composables/useOrderStatus.ts

@@ -0,0 +1,64 @@
+import type { MaterialShapeName } from "@cavulsqa/m3e";
+import type { Component } from "vue";
+import DraftIcon from "~icons/material-symbols/draft-outline-rounded";
+import ShippingIcon from "~icons/material-symbols/local-shipping-outline-rounded";
+import VerifiedIcon from "~icons/material-symbols/verified-outline-rounded";
+
+export const ORDER_STATUSES = ["draft", "confirmed", "delivered"] as const;
+export type OrderStatus = (typeof ORDER_STATUSES)[number];
+
+export interface StatusLook {
+  labelKey: string;
+  icon: Component;
+  shape: MaterialShapeName;
+  /** Container and content roles; delivered uses the harmonised `success` custom colour. */
+  classes: string;
+  /** The container role as a text colour, for an SVG shape that fills with `currentColor`. */
+  fill: string;
+  /** The content role on that container. */
+  ink: string;
+}
+
+/**
+ * How a status reads at a glance: a role pair, a glyph and a shape, so three statuses stay apart for
+ * someone who cannot tell the colours apart - the shape and glyph carry it alone.
+ */
+export const STATUS_LOOK: Readonly<Record<OrderStatus, StatusLook>> = {
+  draft: {
+    labelKey: "demo.statusDraft",
+    icon: DraftIcon,
+    shape: "square",
+    classes: "bg-surface-container-highest text-on-surface-variant",
+    fill: "text-surface-container-highest",
+    ink: "text-on-surface-variant",
+  },
+  confirmed: {
+    labelKey: "demo.statusConfirmed",
+    icon: ShippingIcon,
+    shape: "cookie4Sided",
+    classes: "bg-tertiary-container text-on-tertiary-container",
+    fill: "text-tertiary-container",
+    ink: "text-on-tertiary-container",
+  },
+  delivered: {
+    labelKey: "demo.statusDelivered",
+    icon: VerifiedIcon,
+    shape: "cookie9Sided",
+    classes: "bg-success-container text-on-success-container",
+    fill: "text-success-container",
+    ink: "text-on-success-container",
+  },
+};
+
+export function statusLook(status: string): StatusLook {
+  return STATUS_LOOK[
+    (ORDER_STATUSES as readonly string[]).includes(status) ? (status as OrderStatus) : "draft"
+  ];
+}
+
+const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 });
+
+/** Money is integer cents everywhere; this is the only place it becomes a display string. */
+export function formatMoney(cents: number): string {
+  return formatter.format(cents / 100);
+}

package/templates/m3e-app/src/modules/demo/composables/useReactiveDemo.ts

@@ -0,0 +1,171 @@
+import { Capacitor } from "@capacitor/core";
+import type { TableChangeEvent } from "@cavulsqa/reactive-db";
+import {
+  advanceOrderStatus,
+  clearAll,
+  deleteOrder,
+  ensureReferenceData,
+  loadDashboardStats,
+  saveOrder,
+  searchOrders,
+  seedSampleData,
+  setOrderStatus,
+  type DashboardStats,
+  type DraftLine,
+  type OrderRow,
+} from "@/domains/sales/sales.repository";
+import { activeStorageLabel, changeBus, getDatabase, rdb } from "@/shared/database/database";
+import { useReactiveQuery } from "@/shared/database/queries";
+
+export interface BusEntry {
+  /** Monotonic, because a millisecond timestamp is not unique - several events share one. */
+  id: number;
+  at: number;
+  table: string;
+  type: string;
+}
+
+export interface PipelineResult {
+  parallelMs: number;
+  sequentialMs: number;
+  ratio: number;
+  /** Recorded with the numbers, because a measurement without its engine is not comparable. */
+  engine: string;
+}
+
+const EVENT_LOG_LIMIT = 20;
+const READS_PER_RUN = 5;
+const EMPTY_STATS: DashboardStats = {
+  customers: 0,
+  products: 0,
+  orders: 0,
+  draft: 0,
+  confirmed: 0,
+  delivered: 0,
+  revenueCents: 0,
+  committedCents: 0,
+};
+
+/**
+ * Everything the Reactive screen shows, so the view stays presentational.
+ *
+ * Nothing here tells a query to refresh. Writes go through `rdb`, which announces the tables they
+ * touched, and both queries below watch those tables - which is why creating one order moves the
+ * revenue tile, the order count and the list at the same time.
+ */
+export function useReactiveDemo() {
+  const busy = ref(false);
+  const busLog = ref<BusEntry[]>([]);
+  const pipeline = ref<PipelineResult | null>(null);
+  const measuring = ref(false);
+
+  const statsQuery = useReactiveQuery(() => loadDashboardStats(getDatabase().db), {
+    // Four tables, because the tiles aggregate across all of them.
+    tables: ["customer", "product", "sales_order", "order_line"],
+    queryKey: ["demo:stats"],
+    debounce: 250,
+  });
+
+  const ordersQuery = useReactiveQuery(() => searchOrders(getDatabase().db, ""), {
+    tables: ["sales_order", "order_line", "customer"],
+    queryKey: ["demo:orders"],
+    debounce: 250,
+  });
+
+  let busSequence = 0;
+  const stopWatching = changeBus.on(["*"], (event: TableChangeEvent) => {
+    busSequence += 1;
+    busLog.value = [
+      { id: busSequence, at: Date.now(), table: event.table, type: event.type },
+      ...busLog.value,
+    ].slice(0, EVENT_LOG_LIMIT);
+  });
+  onUnmounted(stopWatching);
+
+  const stats = computed<DashboardStats>(() => statsQuery.data.value ?? EMPTY_STATS);
+  const orders = computed<OrderRow[]>(() => ordersQuery.data.value ?? []);
+
+  async function withBusy(work: () => Promise<void>): Promise<void> {
+    busy.value = true;
+    try {
+      await work();
+    } finally {
+      busy.value = false;
+    }
+  }
+
+  const seed = () => withBusy(() => seedSampleData(rdb));
+
+  const advance = (orderId: number) => withBusy(() => advanceOrderStatus(rdb, orderId));
+
+  const setStatus = (orderId: number, status: "draft" | "confirmed" | "delivered") =>
+    withBusy(() => setOrderStatus(rdb, orderId, status));
+
+  const remove = (orderId: number) => withBusy(() => deleteOrder(rdb, orderId));
+
+  const save = (input: { customerId: number; reference: string; lines: DraftLine[] }) =>
+    withBusy(() => saveOrder(rdb, input));
+  /**
+   * Wipe the demo data, then put the catalogue back. Deleting the products and customers too would
+   * leave the app in a state where no order can be written and the only way out is a restart.
+   */
+  const clear = () =>
+    withBusy(async () => {
+      await clearAll(rdb);
+      await ensureReferenceData(rdb);
+    });
+
+  /**
+   * Reads issued together against reads awaited one by one.
+   *
+   * The worker executes statements one at a time, so this measures how much of a read is the message
+   * round trip rather than the query - it cannot show queries overlapping, and a ratio near 1x is
+   * the expected result rather than a regression.
+   */
+  async function measurePipelining(): Promise<void> {
+    measuring.value = true;
+    try {
+      const db = getDatabase().db;
+      const read = () => db.selectFrom("sales_order").select("id").limit(5).execute();
+      await read();
+
+      const parallelStart = performance.now();
+      await Promise.all(Array.from({ length: READS_PER_RUN }, read));
+      const parallelMs = performance.now() - parallelStart;
+
+      const sequentialStart = performance.now();
+      for (let index = 0; index < READS_PER_RUN; index++) await read();
+      const sequentialMs = performance.now() - sequentialStart;
+
+      pipeline.value = {
+        parallelMs: Number(parallelMs.toFixed(1)),
+        sequentialMs: Number(sequentialMs.toFixed(1)),
+        ratio: Number((sequentialMs / Math.max(parallelMs, 0.01)).toFixed(2)),
+        engine: activeStorageLabel(),
+      };
+    } finally {
+      measuring.value = false;
+    }
+  }
+
+  return {
+    stats,
+    orders,
+    loading: ordersQuery.loading,
+    busy,
+    busLog,
+    pipeline,
+    measuring,
+    readsPerRun: READS_PER_RUN,
+    isNative: Capacitor.isNativePlatform(),
+    engineName: activeStorageLabel(),
+    platform: Capacitor.getPlatform(),
+    seed,
+    advance,
+    setStatus,
+    remove,
+    save,
+    clear,
+    measurePipelining,
+  };
+}

package/templates/m3e-app/src/modules/demo/router/routes/demo.routes.ts

@@ -0,0 +1,22 @@
+import type { Router } from "framework7/types";
+import { lazyRoute } from "@/shared/utils/lazyRoute";
+
+const demoRoutes: Router.RouteParameters[] = [
+  {
+    name: "demo",
+    path: "/demo/",
+    async: lazyRoute(() => import("@/modules/demo/views/DemoView.vue")),
+  },
+  {
+    name: "demo-search",
+    path: "/demo/search/",
+    async: lazyRoute(() => import("@/modules/demo/views/OrderSearchView.vue")),
+  },
+  {
+    name: "demo-order",
+    path: "/demo/order/:id/",
+    async: lazyRoute(() => import("@/modules/demo/views/OrderDetailView.vue")),
+  },
+];
+
+export default demoRoutes;

package/templates/m3e-app/src/modules/demo/views/DemoView.vue

@@ -0,0 +1,210 @@
+<template>
+  <AppPage :title="t('demo.title')" name="demo">
+    <template #actions>
+      <M3IconButton :label="t('demo.searchTitle')" @click="f7router.navigate('/demo/search/')">
+        <i-ms-search-rounded />
+      </M3IconButton>
+      <M3IconButton :label="t('metrics.title')" @click="metricsOpen = true">
+        <i-ms-monitoring-rounded />
+      </M3IconButton>
+    </template>
+
+    <M3Tabs
+      v-model="pane"
+      class="app-sticky-tabs sticky top-[calc(env(safe-area-inset-top)+64px)] z-[2] mb-3"
+      :label="t('demo.title')"
+    >
+      <M3Tab value="data" :label="t('demo.data')" />
+      <M3Tab value="diagnostics" :label="t('demo.diagnostics')" />
+    </M3Tabs>
+
+    <div v-show="pane === 'data'">
+      <DemoStatCards :stats="stats" />
+
+      <SectionHeader>
+        <span class="flex items-center gap-2">
+          {{ t("demo.orders") }}
+          <M3LoadingIndicator v-if="loading" :size="24" :label="t('demo.refetching')" />
+        </span>
+      </SectionHeader>
+
+      <DemoOrderList
+        v-if="orders.length"
+        :orders="orders"
+        @open="openOrder"
+        @more="orderActions"
+        @advance="(order) => run(() => advance(order.id))"
+        @delete="deleteOrder"
+      />
+      <EmptyState
+        v-else
+        shape="cookie6Sided"
+        :headline="t('demo.emptyTitle')"
+        :text="t('demo.empty')"
+      >
+        <template #icon><i-ms-receipt-long-outline-rounded class="size-10" /></template>
+        <M3Button variant="tonal" :disabled="busy" @click="run(seed)">
+          <template #icon><i-ms-wand-stars-rounded /></template>
+          {{ t("demo.seed") }}
+        </M3Button>
+      </EmptyState>
+    </div>
+
+    <div v-show="pane === 'diagnostics'" class="flex flex-col gap-3">
+      <DemoBusLog :entries="busLog" />
+      <DemoPipelineBenchmark
+        :result="pipeline"
+        :measuring="measuring"
+        :reads-per-run="readsPerRun"
+        :is-native="isNative"
+        :platform="platform"
+        :engine-name="engineName"
+        @measure="measurePipelining"
+      />
+      <DemoBenchmark />
+    </div>
+
+    <template v-if="pane === 'data'" #fab>
+      <M3FabMenu
+        v-model:open="fabOpen"
+        :label="t('demo.actions')"
+        :close-label="t('shell.dismiss')"
+      >
+        <template #icon><i-ms-add-rounded /></template>
+        <M3FabMenuItem :index="2" :label="t('demo.newOrder')" @click="createOpen = true">
+          <i-ms-edit-outline-rounded />
+        </M3FabMenuItem>
+        <M3FabMenuItem :index="1" :label="t('demo.seed')" @click="run(seed)">
+          <i-ms-wand-stars-rounded />
+        </M3FabMenuItem>
+        <M3FabMenuItem :index="0" :label="t('demo.clear')" @click="resetData">
+          <i-ms-delete-outline-rounded />
+        </M3FabMenuItem>
+      </M3FabMenu>
+    </template>
+
+    <template #fixed>
+      <DemoCreateOrderSheet v-model:open="createOpen" :save="saveOrder" />
+      <DemoMetricsSheet v-model:open="metricsOpen" />
+    </template>
+  </AppPage>
+</template>
+
+<script setup lang="ts">
+import { markRaw } from "vue";
+import type { ActionSheetGroup } from "@cavulsqa/m3e-vue";
+import type { Router } from "framework7/types";
+import DeleteIcon from "~icons/material-symbols/delete-outline-rounded";
+import ShippingIcon from "~icons/material-symbols/local-shipping-outline-rounded";
+import VerifiedIcon from "~icons/material-symbols/verified-outline-rounded";
+import type { DraftLine, OrderRow } from "@/domains/sales/sales.repository";
+import DemoBenchmark from "@/modules/demo/components/DemoBenchmark.vue";
+import DemoBusLog from "@/modules/demo/components/DemoBusLog.vue";
+import DemoCreateOrderSheet from "@/modules/demo/components/DemoCreateOrderSheet.vue";
+import DemoMetricsSheet from "@/modules/demo/components/DemoMetricsSheet.vue";
+import DemoOrderList from "@/modules/demo/components/DemoOrderList.vue";
+import DemoPipelineBenchmark from "@/modules/demo/components/DemoPipelineBenchmark.vue";
+import DemoStatCards from "@/modules/demo/components/DemoStatCards.vue";
+import { useReactiveDemo } from "@/modules/demo/composables/useReactiveDemo";
+
+const { t } = useI18n();
+const props = defineProps<{ f7router: Router.Router }>();
+const snackbar = useSnackbar();
+const { open } = useContainerTransform();
+const dialog = useDialog();
+const actionSheet = useActionSheet();
+
+const pane = ref<"data" | "diagnostics">("data");
+const createOpen = ref(false);
+const metricsOpen = ref(false);
+const fabOpen = ref(false);
+
+const {
+  stats,
+  orders,
+  loading,
+  busy,
+  busLog,
+  pipeline,
+  measuring,
+  readsPerRun,
+  isNative,
+  platform,
+  engineName,
+  seed,
+  advance,
+  remove,
+  save,
+  clear,
+  measurePipelining,
+} = useReactiveDemo();
+
+/** Every action reports failure the same way, so a broken write is never silent. */
+async function run(action: () => Promise<void>): Promise<boolean> {
+  if (busy.value) return false;
+  try {
+    await action();
+    return true;
+  } catch (error) {
+    console.error("[demo] action failed", error);
+    void snackbar.show({ message: t("demo.actionFailed"), duration: "long" });
+    return false;
+  }
+}
+
+function openOrder(order: OrderRow, event: MouseEvent) {
+  open(props.f7router, event, `/demo/order/${String(order.id)}/`);
+}
+
+async function saveOrder(draft: { customerId: number; reference: string; lines: DraftLine[] }) {
+  await save(draft);
+  void snackbar.show(t("demo.saved", { reference: draft.reference }));
+}
+
+async function orderActions(order: OrderRow) {
+  const next =
+    order.status === "draft" ? "confirm" : order.status === "confirmed" ? "deliver" : null;
+  const groups: ActionSheetGroup[] = [
+    {
+      items: [
+        { id: "delete", label: t("demo.delete"), icon: markRaw(DeleteIcon), tone: "destructive" },
+      ],
+    },
+  ];
+  if (next) {
+    groups.unshift({
+      items: [
+        {
+          id: "advance",
+          label: next === "confirm" ? t("demo.confirm") : t("demo.deliver"),
+          icon: markRaw(next === "confirm" ? ShippingIcon : VerifiedIcon),
+        },
+      ],
+    });
+  }
+  const choice = await actionSheet.open({
+    title: order.reference,
+    supporting: order.customerName,
+    groups,
+  });
+  if (choice === "advance") await run(() => advance(order.id));
+  if (choice === "delete") await deleteOrder(order);
+}
+
+async function deleteOrder(order: OrderRow) {
+  if (await run(() => remove(order.id))) {
+    void snackbar.show(t("demo.deleted", { reference: order.reference }));
+  }
+}
+
+async function resetData() {
+  const confirmed = await dialog.confirm({
+    headline: t("demo.clearTitle"),
+    text: t("demo.clearText"),
+    confirmLabel: t("demo.clear"),
+    dismissLabel: t("demo.cancel"),
+    destructive: true,
+  });
+  if (confirmed) await run(clear);
+}
+</script>