@cavulsqa/create 2.9.2 → 2.10.0

package/templates/m3e-app/src/shared/components/page/AppPage.vue

@@ -0,0 +1,104 @@
+<template>
+  <F7Page
+    ref="page"
+    :name="props.name"
+    class="app-page"
+    @page:beforeout="leave"
+    :class="{ 'app-page--has-fab': $slots.fab }"
+  >
+    <M3TopAppBar
+      :title="props.title"
+      :subtitle="props.subtitle"
+      :variant="props.variant ?? (props.back ? 'small' : 'large')"
+      :scroll-behavior="props.scrollBehavior ?? SCROLL_BEHAVIOR.topAppBar"
+    >
+      <template v-if="props.back" #navigation>
+        <M3IconButton :label="t('shell.back')" @click="goBack">
+          <i-ms-arrow-back-rounded class="rtl:-scale-x-100" />
+        </M3IconButton>
+      </template>
+      <template v-if="$slots.actions" #actions><slot name="actions" /></template>
+      <template v-if="$slots.bottom" #bottom><slot name="bottom" /></template>
+    </M3TopAppBar>
+
+    <slot />
+
+    <template #fixed>
+      <div v-if="$slots.fab" class="app-page__fab"><slot name="fab" /></div>
+      <slot name="fixed" />
+    </template>
+  </F7Page>
+</template>
+
+<script setup lang="ts">
+import type { ComponentPublicInstance } from "vue";
+import { useHideOnScroll } from "@cavulsqa/m3e-vue";
+import { SCROLL_BEHAVIOR, type ScrollBehaviorConfig } from "@/app/scroll.config";
+
+/**
+ * Every routed screen is an `AppPage`: the Framework7 page (lifecycle, transitions, the scroller)
+ * with an M3 top app bar pinned in it and the right bottom padding for whatever floats above the
+ * content. A tab root gets the large flexible bar; a pushed page (`back`) gets the small bar with a
+ * back button and hides the navigation bar for as long as it is mounted.
+ *
+ * Slots: `actions` (trailing icon buttons in the bar), `bottom` (tabs or a filter pinned under the
+ * bar - Framework7's subnavbar), default (the content), `fab` (positioned
+ * above the navigation bar and the gesture area), `fixed` (anything else outside the scroller).
+ *
+ * The bars follow `SCROLL_BEHAVIOR`: a small bar slides away with the content (`scrollBehavior`
+ * overrides it per page), and a tab root's scrolling hides the navigation bar - only while that
+ * page is the one on screen, and never past the page leaving.
+ */
+const props = defineProps<{
+  title: string;
+  subtitle?: string;
+  variant?: "small" | "medium" | "large";
+  back?: boolean;
+  name?: string;
+  scrollBehavior?: ScrollBehaviorConfig["topAppBar"];
+}>();
+
+const { t } = useI18n();
+const page = useTemplateRef<ComponentPublicInstance>("page");
+const pageElement = computed(() => (page.value?.$el as HTMLElement | undefined) ?? null);
+const router = useViewRouter(pageElement);
+
+if (props.back) useHiddenNavigation();
+
+const content = shallowRef<HTMLElement | null>(null);
+const { setScrollHidden } = useNavigationVisibility();
+const onScreen = () =>
+  !!pageElement.value?.classList.contains("page-current") &&
+  !!pageElement.value.closest(".view.tab-active");
+const navigationHide = useHideOnScroll(content, {
+  enabled: () => SCROLL_BEHAVIOR.navigationBar === "hideOnScroll" && !props.back && onScreen(),
+});
+
+watch(navigationHide.hidden, (hidden) => {
+  if (onScreen()) setScrollHidden(hidden);
+});
+
+onMounted(() => {
+  content.value = pageElement.value?.querySelector<HTMLElement>(":scope > .page-content") ?? null;
+});
+
+function leave() {
+  navigationHide.reset();
+  setScrollHidden(false);
+}
+
+function goBack() {
+  router.back();
+}
+</script>
+
+<style scoped>
+.app-page__fab {
+  position: absolute;
+  inset-inline-end: 16px;
+  bottom: calc(16px + var(--app-bottom-inset));
+  z-index: 10;
+  transition: bottom var(--md-sys-motion-spring-default-spatial-duration)
+    var(--md-sys-motion-spring-default-spatial);
+}
+</style>

package/templates/m3e-app/src/shared/composables/navigation/useActiveTab.ts

@@ -0,0 +1,39 @@
+import { shallowRef, type ShallowRef } from "vue";
+import { START_TAB, tabs } from "@/app/tabs";
+
+const active = shallowRef(START_TAB);
+
+export interface ActiveTab {
+  active: Readonly<ShallowRef<string>>;
+  show: (id: string) => void;
+  /** Switches destination, then pushes `path` onto that destination's own history. */
+  open: (id: string, path: string) => void;
+  /** Back from the top of any other destination returns to the start one, as M3 navigation does. */
+  isStart: () => boolean;
+}
+
+/**
+ * The selected destination, shared by the shell's bar or rail and the Android back handler.
+ * Switching happens through Framework7's tab API so each view keeps its own history and the
+ * reactive queries see the `page:tabshow` / `page:tabhide` events they pause on.
+ */
+export function useActiveTab(): ActiveTab {
+  const show = (id: string) => {
+    if (!tabs.some((tab) => tab.id === id)) return;
+    active.value = id;
+    f7ready((app) => {
+      app.tab.show(`#view-${id}`);
+    });
+  };
+  return {
+    active,
+    show,
+    open(id, path) {
+      show(id);
+      f7ready((app) => {
+        app.views.get(`#view-${id}`)?.router.navigate(path);
+      });
+    },
+    isStart: () => active.value === START_TAB,
+  };
+}

package/templates/m3e-app/src/shared/composables/navigation/useContainerTransform.ts

@@ -0,0 +1,117 @@
+import type { Router } from "framework7/types";
+
+/** The Framework7 transition name; its CSS is `m3e-container` in `assets/css/layout/transitions.css`. */
+export const CONTAINER_TRANSITION = "m3e-container";
+
+const PENDING_FOR_MS = 1500;
+
+/** Which element each detail page grew out of, so going back can shrink it into the same place. */
+const origins = new WeakMap<HTMLElement, HTMLElement>();
+let pending: { source: HTMLElement; at: number } | null = null;
+let listening = false;
+
+const CONTAINERS = ".m3-list-item, .m3-card";
+
+function containerOf(event: Event): HTMLElement | null {
+  const target = (event.currentTarget ?? event.target) as Element | null;
+  return target instanceof Element ? target.closest<HTMLElement>(CONTAINERS) : null;
+}
+
+function viewOf(element: HTMLElement): HTMLElement | null {
+  return element.closest<HTMLElement>(".view");
+}
+
+/**
+ * Writes where the container starts (or ends) on the view: the source's box as insets from the
+ * view's edges, its corner radius and its colour. Physical insets, so right-to-left needs nothing.
+ */
+const isClear = (color: string) => color === "transparent" || color === "rgba(0, 0, 0, 0)";
+
+/**
+ * The element that draws the container: the source when it has a background, else the first
+ * element inside it of the same size that does - a list item paints its shape on an inner surface.
+ */
+function surfaceOf(source: HTMLElement): HTMLElement {
+  if (!isClear(getComputedStyle(source).backgroundColor)) return source;
+  const outer = source.getBoundingClientRect();
+  for (const element of source.querySelectorAll<HTMLElement>("*")) {
+    const rect = element.getBoundingClientRect();
+    if (Math.abs(rect.width - outer.width) > 2 || Math.abs(rect.height - outer.height) > 2)
+      continue;
+    if (!isClear(getComputedStyle(element).backgroundColor)) return element;
+  }
+  return source;
+}
+
+function frame(view: HTMLElement, source: HTMLElement) {
+  const surface = surfaceOf(source);
+  const box = view.getBoundingClientRect();
+  const rect = surface.getBoundingClientRect();
+  const style = getComputedStyle(surface);
+  const color = style.backgroundColor;
+  const transparent = isClear(color);
+  const set = (name: string, value: string) => view.style.setProperty(`--m3e-ct-${name}`, value);
+  set("top", `${Math.max(0, rect.top - box.top)}px`);
+  set("left", `${Math.max(0, rect.left - box.left)}px`);
+  set("right", `${Math.max(0, box.right - rect.right)}px`);
+  set("bottom", `${Math.max(0, box.bottom - rect.bottom)}px`);
+  set("radius", style.borderTopLeftRadius || "0px");
+  set("color", transparent ? "var(--md-sys-color-surface-container-low)" : color);
+}
+
+function listen() {
+  if (listening || typeof document === "undefined") return;
+  listening = true;
+  document.addEventListener(
+    "page:mounted",
+    (event) => {
+      const page = event.target;
+      if (!pending || !(page instanceof HTMLElement)) return;
+      if (performance.now() - pending.at < PENDING_FOR_MS) origins.set(page, pending.source);
+      pending = null;
+    },
+    true,
+  );
+  document.addEventListener(
+    "page:beforeout",
+    (event) => {
+      const page = event.target;
+      if (!(page instanceof HTMLElement)) return;
+      const source = origins.get(page);
+      const view = viewOf(page);
+      if (source?.isConnected && view) frame(view, source);
+    },
+    true,
+  );
+}
+
+/**
+ * Material's container transform on Framework7's router: the tapped card grows into the page it
+ * opens - its box, corners and colour morph to the full screen while the page's content fades in -
+ * and going back, by the app bar, Android back or anything else that calls `router.back()`, shrinks
+ * the page into the card again, re-measured in case the list moved. Framework7 replays the
+ * transition a page was opened with, which is what makes every way back reverse it.
+ *
+ * @see https://m3.material.io/styles/motion/transitions/transition-patterns#b67cba74-6240-4663-a423-d537b6d21187
+ */
+export function useContainerTransform() {
+  listen();
+
+  /**
+   * Opens `url` out of `from`: the element itself, or the event of a tap on it, whose closest list
+   * item or card becomes the container.
+   */
+  function open(router: Router.Router, from: Event | HTMLElement | null, url: string) {
+    const source = from instanceof Event ? containerOf(from) : from;
+    const view = source ? viewOf(source) : null;
+    if (!source || !view) {
+      router.navigate(url);
+      return;
+    }
+    frame(view, source);
+    pending = { source, at: performance.now() };
+    router.navigate(url, { transition: CONTAINER_TRANSITION });
+  }
+
+  return { open };
+}

package/templates/m3e-app/src/shared/composables/navigation/useNavigationGuard.ts

@@ -0,0 +1,48 @@
+import { f7 } from "framework7-vue";
+
+interface GuardableRouter {
+  allowPageChange: boolean;
+  navigate: (...args: never[]) => unknown;
+  back: (...args: never[]) => unknown;
+  __navigationGuarded?: boolean;
+}
+
+/**
+ * Framework7 only enforces `allowPageChange` for synchronous routes. Routes here are async, and
+ * `asyncResolve` calls the internal `load()` with `ignorePageChange: true`, so a navigate issued
+ * while a transition is still animating runs a forward on top of an in-flight backward. That
+ * destroys the previous page element and leaves the router holding two copies of the same page;
+ * from there `loadBack` takes its same-url early return and back() can never move again, which
+ * reads to the user as a frozen screen.
+ *
+ * Dropping the losing call is a single boolean read - no queueing, no deferral - so the navigation
+ * that does win runs at exactly the same speed as before.
+ */
+export function installNavigationGuard(router: GuardableRouter): void {
+  if (router.__navigationGuarded) return;
+  router.__navigationGuarded = true;
+
+  let depth = 0;
+
+  const guard = (method: (...args: never[]) => unknown) => {
+    return (...args: never[]) => {
+      if (depth === 0 && !router.allowPageChange) return router;
+      depth += 1;
+      try {
+        return method(...args);
+      } finally {
+        depth -= 1;
+      }
+    };
+  };
+
+  router.navigate = guard(router.navigate.bind(router));
+  router.back = guard(router.back.bind(router));
+}
+
+export function useNavigationGuard(): void {
+  const views = f7.views as unknown as Array<{ router?: GuardableRouter }>;
+  for (const view of views ?? []) {
+    if (view?.router) installNavigationGuard(view.router);
+  }
+}

package/templates/m3e-app/src/shared/composables/navigation/useNavigationVisibility.ts

@@ -0,0 +1,64 @@
+import { computed, onMounted, onUnmounted, shallowRef, type ComputedRef } from "vue";
+
+const keyboardOpen = shallowRef(false);
+const scrollHidden = shallowRef(false);
+const hiddenRequests = shallowRef(0);
+
+export interface NavigationVisibility {
+  isVisible: ComputedRef<boolean>;
+  /**
+   * Whether the bar keeps its row in the layout. Hiding on scroll only slides it away: taking the
+   * row back would change the content's height under the finger, and near the end of a page that
+   * moves the scroll position, which shows the bar again, which moves it back.
+   */
+  isReserved: ComputedRef<boolean>;
+  setKeyboardOpen: (open: boolean) => void;
+  /** Hide-on-scroll: the page on screen is scrolling its content down. */
+  setScrollHidden: (hidden: boolean) => void;
+  /** Hides the bar until the returned function is called. Calls are counted, not toggled. */
+  hide: () => () => void;
+}
+
+/**
+ * Whether the compact navigation bar is on screen. The bar is the shell's, but what hides it - the
+ * keyboard, a pushed page - happens deep in the tree, so the state is shared rather than local.
+ */
+export function useNavigationVisibility(): NavigationVisibility {
+  return {
+    isVisible: computed(
+      () => !keyboardOpen.value && !scrollHidden.value && hiddenRequests.value === 0,
+    ),
+    isReserved: computed(() => !keyboardOpen.value && hiddenRequests.value === 0),
+    setKeyboardOpen: (open) => {
+      keyboardOpen.value = open;
+    },
+    setScrollHidden: (hidden) => {
+      if (scrollHidden.value !== hidden) scrollHidden.value = hidden;
+    },
+    hide: () => {
+      hiddenRequests.value += 1;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        hiddenRequests.value -= 1;
+      };
+    },
+  };
+}
+
+/**
+ * For a pushed page: the bar leaves while it is mounted. The bar navigates between top-level
+ * destinations; on a detail screen it points somewhere you are not and steals a row from content.
+ */
+export function useHiddenNavigation(): void {
+  const { hide } = useNavigationVisibility();
+  let release: (() => void) | null = null;
+  onMounted(() => {
+    release = hide();
+  });
+  onUnmounted(() => {
+    release?.();
+    release = null;
+  });
+}

package/templates/m3e-app/src/shared/composables/navigation/useViewRouter.ts

@@ -0,0 +1,25 @@
+import type { Router } from "framework7/types";
+import type { Ref } from "vue";
+
+interface ViewElement extends HTMLElement {
+  f7View?: { router?: Router.Router };
+}
+
+/**
+ * The router of the view an element sits in, found through the DOM: framework7-vue hands a router
+ * to route components as a prop but provides nothing to their children, so a shared component
+ * would otherwise need it threaded through every screen.
+ */
+export function useViewRouter(element: Ref<HTMLElement | null | undefined>) {
+  const router = (): Router.Router | undefined =>
+    (element.value?.closest(".view") as ViewElement | null)?.f7View?.router;
+
+  return {
+    router,
+    back: () => {
+      const current = router();
+      if (current && current.history.length > 1) current.back();
+    },
+    navigate: (url: string) => router()?.navigate(url),
+  };
+}

package/templates/m3e-app/src/shared/composables/navigation/useWindowClass.ts

@@ -0,0 +1,22 @@
+import { useMediaQuery } from "@vueuse/core";
+import { computed, type ComputedRef } from "vue";
+
+export type WindowClass = "compact" | "medium" | "expanded" | "large";
+
+/**
+ * M3's window size classes by width: compact under 600dp, medium to 839, expanded to 1199, large
+ * from 1200. Layout decisions key on these, never on device type - a phone in landscape is medium.
+ *
+ * @see https://m3.material.io/foundations/layout/applying-layout
+ */
+export function useWindowClass(): ComputedRef<WindowClass> {
+  const medium = useMediaQuery("(min-width: 600px)");
+  const expanded = useMediaQuery("(min-width: 840px)");
+  const large = useMediaQuery("(min-width: 1200px)");
+  return computed(() => {
+    if (large.value) return "large";
+    if (expanded.value) return "expanded";
+    if (medium.value) return "medium";
+    return "compact";
+  });
+}

package/templates/m3e-app/src/shared/composables/theme/useThemeSettings.ts

@@ -0,0 +1,155 @@
+import { applyColorScheme, applySystemTokens, setDarkMode } from "@cavulsqa/m3e-vue";
+import { Capacitor } from "@capacitor/core";
+import { StatusBar, Style } from "@capacitor/status-bar";
+import { usePreferredDark, useStorage } from "@vueuse/core";
+import {
+  computed,
+  effectScope,
+  readonly,
+  watch,
+  type ComputedRef,
+  type DeepReadonly,
+  type Ref,
+} from "vue";
+import { EXTRA_COLORS, TYPEFACE } from "@/app/theme.config";
+import { m3e } from "@/plugins/m3e.plugin";
+import {
+  CONTRAST_LEVELS,
+  DEFAULT_THEME,
+  parseThemeSettings,
+  reducedMotionOverride,
+  type ThemeSettings,
+} from "@/shared/utils/theme/themeSettings";
+
+const STORAGE_KEY = "app-theme";
+
+interface ThemeState {
+  settings: Ref<ThemeSettings>;
+  isDark: ComputedRef<boolean>;
+}
+
+let state: ThemeState | null = null;
+
+function readJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function paintColors(settings: ThemeSettings): void {
+  try {
+    applyColorScheme({
+      seed: settings.seed,
+      variant: settings.variant,
+      contrast: CONTRAST_LEVELS[settings.contrast],
+      extras: EXTRA_COLORS,
+    });
+  } catch (error) {
+    console.error("[theme] colour generation failed; falling back to the brand seed", error);
+    applyColorScheme({ seed: DEFAULT_THEME.seed, extras: EXTRA_COLORS });
+  }
+}
+
+async function paintStatusBar(isDark: boolean): Promise<void> {
+  if (!Capacitor.isNativePlatform()) return;
+  try {
+    await StatusBar.setStyle({ style: isDark ? Style.Dark : Style.Light });
+  } catch (error) {
+    console.warn("[theme] status bar style not applied", error);
+  }
+}
+
+/**
+ * Starts the theme once, before the app mounts: tokens and both colour modes are in the document
+ * before the first paint, so there is no flash of an unthemed or wrong-mode screen. Colour changes
+ * from the studio coalesce to one regeneration per frame however fast a slider moves.
+ */
+export function startTheme(): ThemeState {
+  if (state) return state;
+  const scope = effectScope(true);
+  state = scope.run(() => {
+    const settings = useStorage<ThemeSettings>(STORAGE_KEY, { ...DEFAULT_THEME }, undefined, {
+      serializer: {
+        read: (raw) => parseThemeSettings(readJson(raw)),
+        write: (value) => JSON.stringify(value),
+      },
+      writeDefaults: false,
+      mergeDefaults: false,
+    });
+    const prefersDark = usePreferredDark();
+    const isDark = computed(
+      () =>
+        settings.value.mode === "dark" || (settings.value.mode === "system" && prefersDark.value),
+    );
+
+    applySystemTokens({ brandTypeface: TYPEFACE, plainTypeface: TYPEFACE });
+    paintColors(settings.value);
+    setDarkMode(isDark.value);
+
+    let frame = 0;
+    watch(
+      () => [settings.value.seed, settings.value.variant, settings.value.contrast] as const,
+      () => {
+        if (frame) return;
+        frame = requestAnimationFrame(() => {
+          frame = 0;
+          paintColors(settings.value);
+        });
+      },
+    );
+
+    watch(
+      isDark,
+      (dark) => {
+        setDarkMode(dark);
+        void paintStatusBar(dark);
+      },
+      { immediate: true },
+    );
+
+    watch(
+      () => settings.value.motion,
+      (motion) => (m3e.config.reducedMotion.value = reducedMotionOverride(motion)),
+      { immediate: true },
+    );
+
+    return { settings, isDark };
+  })!;
+  return state;
+}
+
+export interface ThemeControls {
+  settings: DeepReadonly<Ref<ThemeSettings>>;
+  isDark: ComputedRef<boolean>;
+  update: (patch: Partial<ThemeSettings>) => void;
+  reset: () => void;
+}
+
+/** The persisted theme: read it anywhere, change it from the colour studio. */
+export function useThemeSettings(): ThemeControls {
+  const { settings, isDark } = startTheme();
+  return {
+    settings: readonly(settings),
+    isDark,
+    update: (patch) => {
+      settings.value = parseThemeSettings({ ...settings.value, ...patch });
+    },
+    reset: () => {
+      settings.value = { ...DEFAULT_THEME };
+    },
+  };
+}
+
+/**
+ * Light status-bar icons while `active` holds - for a surface drawn on black, such as the photo
+ * browser - and the theme's own style back once it ends or the caller unmounts.
+ */
+export function useDarkStatusBar(active: () => boolean): void {
+  const { isDark } = startTheme();
+  watch(active, (on) => void paintStatusBar(on || isDark.value));
+  onScopeDispose(() => {
+    if (active()) void paintStatusBar(isDark.value);
+  });
+}

package/templates/m3e-app/src/shared/database/candidates/capacitorSqlite.ts

@@ -0,0 +1,36 @@
+import { Capacitor } from "@capacitor/core";
+import type { StorageCandidate, StorageProbe } from "./types";
+
+/**
+ * `@capacitor-community/sqlite`: a real file behind a native bridge.
+ *
+ * Slower than the OPFS engine on every axis measured on a device - batched writes about 2.4x, the
+ * app's own screen queries about 1.3x - and it needs the plugin in the APK. It is here for the one
+ * thing the worker cannot do: the worker is serial, so a read waits behind an in-flight write,
+ * where this dialect keeps reads outside the write lock. Choose it for an app that writes
+ * continuously while the UI reads, or that needs SQLCipher or native access to the file.
+ */
+function probeNativePlatform(): StorageProbe {
+  if (!Capacitor.isNativePlatform()) {
+    return {
+      supported: false,
+      reason: "the SQLite plugin is native-only; on web it needs jeep-sqlite and a separate store",
+    };
+  }
+  return { supported: true };
+}
+
+export const capacitorSqlite: StorageCandidate = {
+  id: "capacitor-sqlite",
+  label: "Capacitor SQLite · native plugin",
+  tradeoff:
+    "Needs the native plugin in the APK, and every statement crosses the bridge. Slower than the " +
+    "worker engines, but reads are not blocked by an in-flight write.",
+  durable: true,
+  evidence: "measured",
+  probe: probeNativePlatform,
+  createDialect: async () => {
+    const { createCapacitorDialect } = await import("@cavulsqa/mobile-db/capacitor");
+    return await createCapacitorDialect({ name: "app.sqlite3" });
+  },
+};

package/templates/m3e-app/src/shared/database/candidates/index.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export { opfsSahPool } from "./opfsSahPool";
+export { waAccessHandlePool, waIdbBatchAtomic, waOriginPrivateFileSystem } from "./waSqlite";
+export { capacitorSqlite } from "./capacitorSqlite";

package/templates/m3e-app/src/shared/database/candidates/opfsSahPool.ts

@@ -0,0 +1,25 @@
+import { createOpfsDialect } from "@cavulsqa/mobile-db/opfs";
+import OpfsWorker from "../opfs.worker?worker";
+import { probeOpfsCapable } from "../storage";
+import type { StorageCandidate } from "./types";
+
+/**
+ * Official `@sqlite.org/sqlite-wasm`, `opfs-sahpool` VFS, in a worker.
+ *
+ * The fastest thing measured on a real phone: reads 2.5-5.5x and batched writes ~9x against the
+ * Capacitor bridge, with much tighter worst cases. The SAH pool is chosen over the plain `opfs` VFS
+ * because it needs neither SharedArrayBuffer nor cross-origin isolation, and a Capacitor WebView
+ * cannot easily be given COOP/COEP headers.
+ */
+export const opfsSahPool: StorageCandidate = {
+  id: "sqlite-wasm-opfs-sahpool",
+  label: "SQLite WASM · OPFS sync access handle pool",
+  tradeoff:
+    "One connection per directory, taken exclusively - a stale handle blocks the open. The worker " +
+    "is serial, so a read waits behind an in-flight write.",
+  durable: true,
+  evidence: "measured",
+  probe: probeOpfsCapable,
+  createDialect: () =>
+    Promise.resolve(createOpfsDialect({ worker: new OpfsWorker(), name: "app.sqlite3" })),
+};