@cavulsqa/create 0.1.0

package/templates/f7-app/src/shared/components/metrics/MetricsPanel.vue

@@ -0,0 +1,79 @@
+<template>
+  <F7Page>
+    <F7Navbar :title="t('metrics.title')">
+      <F7NavRight>
+        <F7Link panel-close icon-f7="xmark" />
+      </F7NavRight>
+    </F7Navbar>
+
+    <F7BlockTitle>{{ t("metrics.summary") }}</F7BlockTitle>
+    <F7List strong inset dividers class="rounded-2xl!">
+      <F7ListItem :title="t('metrics.totalQueries')" :after="String(totalQueries)">
+        <template #media><F7Icon f7="number_circle_fill" color="blue" /></template>
+      </F7ListItem>
+      <F7ListItem :title="t('metrics.avgQueryTime')" :after="`${avgQueryTime.toFixed(1)} ms`">
+        <template #media><F7Icon f7="timer_fill" color="orange" /></template>
+      </F7ListItem>
+      <F7ListItem :title="t('metrics.cacheHitRate')" :after="`${cacheHitRate.toFixed(0)} %`">
+        <template #media><F7Icon f7="bolt_circle_fill" color="green" /></template>
+      </F7ListItem>
+      <F7ListItem :title="t('metrics.activeListeners')" :after="String(activeListeners)">
+        <template #media><F7Icon f7="antenna_radiowaves_left_right" color="purple" /></template>
+      </F7ListItem>
+    </F7List>
+
+    <F7BlockTitle>{{ t("metrics.refetchesTitle") }}</F7BlockTitle>
+    <F7List v-if="refetches.length" strong inset dividers class="rounded-2xl!">
+      <F7ListItem
+        v-for="[table, count] in refetches"
+        :key="table"
+        :title="table"
+        :after="String(count)"
+      >
+        <template #media><F7Icon f7="arrow_2_circlepath" color="teal" /></template>
+      </F7ListItem>
+    </F7List>
+    <F7Block v-else strong inset class="rounded-2xl!">
+      <p class="m-0 text-sm">{{ t("metrics.noRefetches") }}</p>
+    </F7Block>
+
+    <F7BlockTitle>{{ t("metrics.slowest") }}</F7BlockTitle>
+    <!-- media-list, because a query key is long and the panel is narrow. -->
+    <F7List v-if="slowestQueries.length" media-list strong inset dividers class="rounded-2xl!">
+      <F7ListItem
+        v-for="entry in slowestQueries"
+        :key="entry.key"
+        :title="`${entry.avgTime.toFixed(1)} ms`"
+        :subtitle="t('metrics.calls', { count: entry.count })"
+      >
+        <template #media><F7Icon f7="speedometer" color="red" /></template>
+        <template #text>{{ entry.key }}</template>
+      </F7ListItem>
+    </F7List>
+    <F7Block v-else strong inset class="rounded-2xl!">
+      <p class="m-0 text-sm">{{ t("metrics.noQueries") }}</p>
+    </F7Block>
+
+    <F7Block>
+      <F7Button large outline @click="reset">{{ t("metrics.reset") }}</F7Button>
+    </F7Block>
+  </F7Page>
+</template>
+
+<script setup lang="ts">
+import { useQueryMetrics } from "@/shared/database/queries";
+
+const { t } = useI18n();
+
+const {
+  totalQueries,
+  avgQueryTime,
+  cacheHitRate,
+  activeListeners,
+  refetchesByTable,
+  slowestQueries,
+  reset,
+} = useQueryMetrics();
+
+const refetches = computed(() => Object.entries(refetchesByTable.value));
+</script>

package/templates/f7-app/src/shared/composables/theme/useAppTheme.ts

@@ -0,0 +1,68 @@
+import { Capacitor } from "@capacitor/core";
+import { StatusBar, Style } from "@capacitor/status-bar";
+import type { ComputedRef, InjectionKey } from "vue";
+
+export type AppTheme = "ios" | "md" | "auto";
+export type AppMode = "light" | "dark";
+
+export interface AppContext {
+  theme: AppTheme;
+  darkMode: AppMode;
+  setTheme: (theme: AppTheme) => void;
+  setDarkMode: (mode: AppMode) => Promise<void>;
+}
+
+export const AppContextKey: InjectionKey<ComputedRef<AppContext>> = Symbol("AppContext");
+
+/**
+ * Called once, by the shell. Both choices persist to local storage so the app opens the way it was
+ * left.
+ *
+ * Switching iOS/Material reloads the page on purpose: Framework7 resolves theme-specific components
+ * and CSS variables when it initialises, so flipping `f7.theme` afterwards leaves a half-converted
+ * UI. Dark mode needs no reload - it is a class on the root plus the native status bar style.
+ */
+export const useAppThemeProvider = (): ComputedRef<AppContext> => {
+  const theme = useLocalStorage<AppTheme>("app-theme", "auto");
+  const darkMode = useLocalStorage<AppMode>(
+    "app-dark-mode",
+    window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light",
+  );
+
+  const setTheme = (next: AppTheme) => {
+    theme.value = next;
+    window.location.reload();
+  };
+
+  const setDarkMode = async (next: AppMode) => {
+    darkMode.value = next;
+    f7.setDarkMode(next === "dark");
+
+    if (Capacitor.isNativePlatform()) {
+      await StatusBar.setStyle({ style: next === "dark" ? Style.Dark : Style.Light });
+    }
+  };
+
+  const appContext = computed<AppContext>(() => ({
+    theme: theme.value,
+    darkMode: darkMode.value,
+    setTheme,
+    setDarkMode,
+  }));
+
+  provide(AppContextKey, appContext);
+
+  onMounted(() => {
+    void setDarkMode(darkMode.value);
+  });
+
+  return appContext;
+};
+
+export const useAppTheme = (): ComputedRef<AppContext> => {
+  const context = inject(AppContextKey);
+  if (!context) {
+    throw new Error("useAppTheme needs useAppThemeProvider() called in a parent component");
+  }
+  return context;
+};

package/templates/f7-app/src/shared/composables/useTabbarVisibility.ts

@@ -0,0 +1,50 @@
+import type { ComputedRef } from "vue";
+
+// Shell-level state: the tab bar is rendered by the shell, but what hides it - a keyboard, a pushed
+// page - happens elsewhere in the tree.
+const keyboardOpen = ref(false);
+const hiddenRequests = ref(0);
+
+export interface TabbarVisibility {
+  isVisible: ComputedRef<boolean>;
+  setKeyboardOpen: (open: boolean) => void;
+  hideTabbar: () => () => void;
+}
+
+export function useTabbarVisibility(): TabbarVisibility {
+  return {
+    isVisible: computed(() => !keyboardOpen.value && hiddenRequests.value === 0),
+    setKeyboardOpen: (open: boolean) => {
+      keyboardOpen.value = open;
+    },
+    /** Hide the bar for as long as the caller needs it; the returned function restores it. */
+    hideTabbar: () => {
+      hiddenRequests.value += 1;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        hiddenRequests.value -= 1;
+      };
+    },
+  };
+}
+
+/**
+ * Drop this into any pushed page and the tab bar gets out of the way for as long as that page is
+ * mounted. The bar belongs to the tab roots: on a detail or a search screen it is navigation to
+ * somewhere you are not, and it steals a row from content.
+ */
+export function useHiddenTabbar(): void {
+  const { hideTabbar } = useTabbarVisibility();
+  let release: (() => void) | null = null;
+
+  onMounted(() => {
+    release = hideTabbar();
+  });
+
+  onUnmounted(() => {
+    release?.();
+    release = null;
+  });
+}

package/templates/f7-app/src/shared/database/database.ts

@@ -0,0 +1,86 @@
+import { Capacitor } from "@capacitor/core";
+import { Kysely } from "kysely";
+import { Migrator } from "kysely/migration";
+import { createMobileDatabase, runWrite, type MobileDatabase } from "@cavulsqa/mobile-db";
+import { createChangeBus, createReactiveDb } from "@cavulsqa/reactive-db";
+import { migrations } from "./migrations";
+import type { Database } from "./schema";
+
+/**
+ * One bus for the whole app. Writes announce the tables they touched on it and reactive queries
+ * listen to it, so both sides have to be the same instance - which is why it is created here and
+ * passed outward rather than constructed wherever it is needed.
+ */
+export const changeBus = createChangeBus();
+
+let database: MobileDatabase<Database> | null = null;
+
+/**
+ * On a device the database is a real SQLite file behind the Capacitor plugin.
+ *
+ * In a browser it is sql.js in memory, via the dialect `@cavulsqa/mobile-db` already ships for its
+ * own tests. That is deliberate: the plugin's web mode needs a `jeep-sqlite` element plus a
+ * `sql-wasm.wasm` whose build must match the glue jeep-sqlite bundles - a pairing outside this
+ * template's control that breaks on any upstream bump. This path has no assets to serve and no
+ * version to keep in step; the cost is that browser data does not survive a reload, which for a
+ * template running `vp dev` is the honest trade.
+ */
+async function openWebDatabase(): Promise<MobileDatabase<Database>> {
+  const { createSqlJsDialect } = await import("@cavulsqa/mobile-db/testing");
+  const db = new Kysely<Database>({ dialect: await createSqlJsDialect() });
+
+  await new Migrator({
+    db,
+    provider: { getMigrations: () => Promise.resolve(migrations) },
+  }).migrateToLatest();
+
+  return {
+    db,
+    write: (ctx, work) =>
+      runWrite(ctx, () => db.transaction().execute((trx) => work(trx)), {
+        runInTransaction: <R>(task: () => Promise<R>) => task(),
+        emitTableChange: (table) => changeBus.emit(table, "bulk"),
+      }),
+    getRawConnection: () => {
+      throw new Error("no native connection in a browser");
+    },
+    close: () => db.destroy(),
+  };
+}
+
+export async function openDatabase(): Promise<MobileDatabase<Database>> {
+  if (database) return database;
+
+  database =
+    Capacitor.getPlatform() === "web"
+      ? await openWebDatabase()
+      : await createMobileDatabase<Database>({
+          name: "app",
+          migrations,
+          emitTableChange: (table) => changeBus.emit(table, "bulk"),
+          /**
+           * One native connection cannot serve two writers. This serialises writes and transactions
+           * while leaving reads parallel, because the native bridge pipelines concurrent calls and
+           * queueing reads costs several times the latency on a screen loading with `Promise.all`.
+           */
+          serializeAccess: true,
+        });
+
+  return database;
+}
+
+export function getDatabase(): MobileDatabase<Database> {
+  if (!database) throw new Error("openDatabase() must be awaited before the database is used");
+  return database;
+}
+
+/** Writes go through this so every mutation announces its tables without the caller remembering. */
+export const rdb = createReactiveDb<Database>({
+  getDb: () => getDatabase().db,
+  emitChange: changeBus.emit,
+});
+
+export async function closeDatabase(): Promise<void> {
+  await database?.close();
+  database = null;
+}

package/templates/f7-app/src/shared/database/index.ts

@@ -0,0 +1,3 @@
+export * from "./database";
+export * from "./queries";
+export type { Database } from "./schema";

package/templates/f7-app/src/shared/database/migrations.ts

@@ -0,0 +1,81 @@
+import { createTableWithDefaults, type MigrationSet } from "@cavulsqa/mobile-db";
+import { sql } from "kysely";
+
+/**
+ * Keys are ordered lexically and recorded once applied, so they are numbered and never renamed:
+ * renaming one makes it run again on a database that already has it.
+ *
+ * Foreign keys are declared for the shape, and indexed on the columns the screens actually filter
+ * and join by - without them every dashboard aggregate is a full scan.
+ */
+export const migrations: MigrationSet = {
+  "001_sales": {
+    up: async (db) => {
+      await createTableWithDefaults(db, "customer")
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("city", "text", (col) => col.notNull().defaultTo(""))
+        .execute();
+
+      await createTableWithDefaults(db, "product")
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await createTableWithDefaults(db, "sales_order")
+        .addColumn("customer_id", "integer", (col) =>
+          col.notNull().references("customer.id").onDelete("cascade"),
+        )
+        .addColumn("reference", "text", (col) => col.notNull())
+        .addColumn("status", "text", (col) => col.notNull().defaultTo("draft"))
+        .execute();
+
+      await db.schema
+        .createTable("order_line")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("order_id", "integer", (col) =>
+          col.notNull().references("sales_order.id").onDelete("cascade"),
+        )
+        .addColumn("product_id", "integer", (col) => col.notNull().references("product.id"))
+        .addColumn("quantity", "integer", (col) => col.notNull().defaultTo(1))
+        .addColumn("unit_price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("tag")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("label", "text", (col) => col.notNull().unique())
+        .execute();
+
+      await db.schema
+        .createTable("customer_tag")
+        .addColumn("customer_id", "integer", (col) =>
+          col.notNull().references("customer.id").onDelete("cascade"),
+        )
+        .addColumn("tag_id", "integer", (col) =>
+          col.notNull().references("tag.id").onDelete("cascade"),
+        )
+        .addPrimaryKeyConstraint("customer_tag_pk", ["customer_id", "tag_id"])
+        .execute();
+
+      await db.schema
+        .createIndex("idx_sales_order_customer")
+        .on("sales_order")
+        .column("customer_id")
+        .execute();
+      await db.schema
+        .createIndex("idx_order_line_order")
+        .on("order_line")
+        .column("order_id")
+        .execute();
+      await db.schema
+        .createIndex("idx_order_line_product")
+        .on("order_line")
+        .column("product_id")
+        .execute();
+      await db.schema.createIndex("idx_customer_city").on("customer").column("city").execute();
+
+      // SQLite ignores foreign keys unless asked, and the plugin opens with them off.
+      await sql`PRAGMA foreign_keys = ON`.execute(db);
+    },
+  },
+};

package/templates/f7-app/src/shared/database/queries.ts

@@ -0,0 +1,22 @@
+import { createReactiveQuery, createVueQueryMetrics } from "@cavulsqa/reactive-vue";
+import { usePageVisibility } from "@cavulsqa/reactive-vue/framework7";
+import { changeBus } from "./database";
+
+const metrics = createVueQueryMetrics({
+  exposeOnWindowAs: import.meta.env.DEV ? "__appMetrics" : undefined,
+});
+
+/**
+ * The composables every screen uses. They are built once, here, because the change bus and the
+ * metrics recorder are app-wide singletons - a query created with a different bus would never hear
+ * about a write.
+ */
+export const { useReactiveQuery, useStructuralQuery, useStaticQuery } = createReactiveQuery({
+  onTableChange: changeBus.on,
+  metrics: metrics.recorder,
+  // Without this a tab the user cannot see keeps refetching in the background.
+  useVisibility: usePageVisibility,
+});
+
+export const { useQueryMetrics } = metrics;
+export { uniqueQueryKey } from "@cavulsqa/reactive-vue";

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

@@ -0,0 +1,59 @@
+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;
+}

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

@@ -0,0 +1,152 @@
+import type { ComponentResolver } from "unplugin-vue-components/types";
+
+export function Framework7VueResolver(): ComponentResolver {
+  const framework7Components = [
+    "f7-app",
+    "f7-view",
+    "f7-views",
+    "f7-page",
+    "f7-page-content",
+
+    "f7-navbar",
+    "f7-nav-left",
+    "f7-nav-right",
+    "f7-nav-title",
+    "f7-nav-title-large",
+    "f7-toolbar",
+    // No "f7-toolbar-pane": Framework7 9 ships the CSS class but framework7-vue 8 exports no
+    // such component, and resolving it fails at runtime instead of warning. Use the class.
+    "f7-subnavbar",
+    "f7-searchbar",
+
+    "f7-row",
+    "f7-col",
+
+    "f7-list",
+    "f7-list-group",
+    "f7-list-item",
+    "f7-list-item-row",
+    "f7-list-item-cell",
+    "f7-list-item-content",
+    "f7-list-button",
+    "f7-list-input",
+
+    "f7-checkbox",
+    "f7-toggle",
+    "f7-stepper",
+
+    "f7-button",
+    "f7-segmented",
+    "f7-fab",
+    "f7-fab-button",
+    "f7-fab-buttons",
+
+    "f7-card",
+    "f7-card-header",
+    "f7-card-content",
+    "f7-card-footer",
+
+    "f7-popup",
+    "f7-popover",
+    "f7-actions",
+    "f7-actions-group",
+    "f7-actions-button",
+    "f7-actions-label",
+    "f7-sheet",
+
+    "f7-login-screen",
+    "f7-login-screen-title",
+
+    "f7-panel",
+    "f7-tabs",
+    "f7-tab",
+    "f7-link",
+
+    "f7-photo-browser",
+
+    "f7-swipeout",
+    "f7-swipeout-actions",
+    "f7-swipeout-button",
+    "f7-swipeout-content",
+
+    "f7-accordion",
+    "f7-accordion-item",
+    "f7-accordion-toggle",
+    "f7-accordion-content",
+    "f7-contacts-list",
+    "f7-virtual-list",
+    "f7-list-index",
+
+    "f7-chip",
+    "f7-badge",
+
+    "f7-preloader",
+    "f7-progressbar",
+    "f7-skeleton-block",
+    "f7-skeleton-text",
+
+    "f7-messages",
+    "f7-messages-title",
+    "f7-message",
+    "f7-messagebar",
+    "f7-messagebar-attachment",
+    "f7-messagebar-attachments",
+
+    "f7-icon",
+
+    "f7-block",
+    "f7-block-title",
+    "f7-block-header",
+    "f7-block-footer",
+  ];
+
+  const toCamelCase = (str: string) => {
+    return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+  };
+
+  return {
+    type: "component",
+    resolve: (name: string) => {
+      if (name.startsWith("F7") && name.length > 2) {
+        const kebabName = name
+          .replace(/^F7/, "f7-")
+          .replace(/([a-z])([A-Z])/g, "$1-$2")
+          .toLowerCase();
+
+        if (framework7Components.includes(kebabName)) {
+          return {
+            name: toCamelCase(kebabName),
+            from: "framework7-vue",
+          };
+        }
+      }
+
+      if (name.startsWith("f7-") && framework7Components.includes(name)) {
+        return {
+          name: toCamelCase(name),
+          from: "framework7-vue",
+        };
+      }
+
+      if (name.match(/^f7[A-Z]/)) {
+        const kebabName = name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+
+        if (framework7Components.includes(kebabName)) {
+          return {
+            name: toCamelCase(kebabName),
+            from: "framework7-vue",
+          };
+        }
+      }
+    },
+  };
+}
+
+export function getFramework7AutoImports() {
+  return {
+    "framework7/lite": ["utils", "getDevice", "createStore", "Dom7", "request"],
+    // Only what framework7-vue actually exports. `f7route` and `f7router` are passed to a
+    // route component as props - see FeatureDetailView - and importing them fails at runtime.
+    "framework7-vue": ["f7ready", "f7", "theme"],
+  };
+}

package/templates/f7-app/tests/icons.test.ts

@@ -0,0 +1,81 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { expect, test } from "vite-plus/test";
+
+/**
+ * framework7-icons is a ligature font: an unknown name renders nothing at all - no warning, no
+ * fallback, just empty space where an icon should be. This template shipped seven wrong names
+ * before anyone noticed, and then a "fix" derived from the package's React component filenames
+ * broke four that had been correct, because those files are SVG wrappers and say nothing about the
+ * font's ligatures.
+ *
+ * So the font itself is the authority. Ligature names appear as plain ASCII in the ttf, which is
+ * enough to tell a real name from an invented one.
+ */
+const require = createRequire(import.meta.url);
+
+function iconFontText(): string {
+  const cssPath = require.resolve("framework7-icons/css/framework7-icons.css");
+  const ttf = join(dirname(dirname(cssPath)), "fonts", "Framework7Icons-Regular.ttf");
+  return readFileSync(ttf, "latin1");
+}
+
+function sourceFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) sourceFiles(full, out);
+    else if (/\.(vue|ts)$/.test(entry)) out.push(full);
+  }
+  return out;
+}
+
+/** Matches `f7="name"`, `icon-f7="name"` and the `f7:name` form used for per-theme icons. */
+function usedIconNames(): string[] {
+  const names = new Set<string>();
+  for (const file of sourceFiles(join(import.meta.dirname, "..", "src"))) {
+    const source = readFileSync(file, "utf8");
+    for (const match of source.matchAll(/(?:icon-)?f7="([a-z][a-z0-9_]*)"/g)) names.add(match[1]!);
+    for (const match of source.matchAll(/f7:([a-z][a-z0-9_]*)/g)) names.add(match[1]!);
+  }
+  return [...names].sort();
+}
+
+test("every Framework7 icon name used in the app exists in the font", () => {
+  const font = iconFontText();
+  const used = usedIconNames();
+
+  // A guard that never looks at anything is worse than no guard.
+  expect(used.length).toBeGreaterThan(10);
+
+  const missing = used.filter((name) => !font.includes(name));
+  expect(missing, `not ligatures in Framework7Icons-Regular.ttf: ${missing.join(", ")}`).toEqual(
+    [],
+  );
+});
+
+test("the names this template previously got wrong stay caught", () => {
+  const font = iconFontText();
+
+  // Underscores before digits are part of the name; dropping them was the regression.
+  for (const wrong of [
+    "arrow2_circlepath",
+    "square_grid2x2_fill",
+    "square_stack3d_down_right_fill",
+    "rectangle3_offgrid_fill",
+    // An SF Symbols name this font does not carry - the search icon was invisible because of it.
+    "magnifyingglass",
+  ]) {
+    expect(font.includes(wrong), `${wrong} should not resolve`).toBe(false);
+  }
+
+  for (const right of [
+    "arrow_2_circlepath",
+    "square_grid_2x2_fill",
+    "square_stack_3d_down_right_fill",
+    "rectangle_3_offgrid_fill",
+    "search",
+  ]) {
+    expect(font.includes(right), `${right} should resolve`).toBe(true);
+  }
+});