@cavulsqa/create 2.9.2 → 2.10.0

package/templates/m3e-app/src/app/storage.config.ts

@@ -0,0 +1,65 @@
+import {
+  capacitorSqlite,
+  isStorageId,
+  opfsSahPool,
+  waAccessHandlePool,
+  waIdbBatchAtomic,
+  waOriginPrivateFileSystem,
+  STORAGE_IDS,
+  type StorageCandidate,
+} from "@/shared/database/candidates";
+
+/**
+ * The knob. Walked in order, first candidate that opens wins, and the rest are never imported - so a
+ * chain that stops at the first entry never downloads the others' wasm.
+ *
+ * Reorder freely to trade speed for reach: the entries lower down reach older WebViews, and each
+ * one states its own `tradeoff` and whether its `evidence` came from a device or a vendor's README.
+ * Read the list rather than this comment - `@cavulsqa/create` removes the engines an app did not
+ * ask for, so what is below is what this app actually has.
+ *
+ * No in-memory entry on purpose: a chain that ends somewhere data is not kept is worse than one that
+ * fails and names every attempt.
+ */
+export const DEFAULT_ORDER: StorageCandidate[] = [
+  opfsSahPool,
+  waAccessHandlePool,
+  waOriginPrivateFileSystem,
+  waIdbBatchAtomic,
+  capacitorSqlite,
+];
+
+/**
+ * `VITE_STORAGE_ENGINE` promotes one candidate to the front and leaves the rest as fallback, so the
+ * env var reorders the chain rather than replacing it - a device that cannot open the preferred
+ * engine still gets a working app.
+ *
+ * A typo is reported and ignored rather than fatal: it should not brick the build's output, but a
+ * setting that was silently dropped looks exactly like one that was applied and did nothing.
+ */
+/**
+ * What `VITE_STORAGE_ENGINE` was at build time, or undefined.
+ *
+ * Exported so the open can report it. Vite inlines this when it bundles, so an empty value means
+ * the variable never reached the build - a `.env` written as UTF-16 by PowerShell's `>` parses as
+ * garbage and is dropped without a word.
+ */
+export const preferredEngine = import.meta.env.VITE_STORAGE_ENGINE;
+
+function preferredFirst(candidates: StorageCandidate[]): StorageCandidate[] {
+  const preferred = preferredEngine;
+  if (!preferred) return candidates;
+
+  if (!isStorageId(preferred)) {
+    console.warn(
+      `[storage] VITE_STORAGE_ENGINE="${preferred}" is not an engine this app has. ` +
+        `Expected one of: ${STORAGE_IDS.join(", ")}. Falling back to the default order.`,
+    );
+    return candidates;
+  }
+
+  const match = candidates.find((candidate) => candidate.id === preferred);
+  return match ? [match, ...candidates.filter((candidate) => candidate !== match)] : candidates;
+}
+
+export const storageChain: StorageCandidate[] = preferredFirst(DEFAULT_ORDER);

package/templates/m3e-app/src/app/tabs.ts

@@ -0,0 +1,33 @@
+import type { Component } from "vue";
+import HomeOutline from "~icons/material-symbols/home-outline-rounded";
+import HomeFilled from "~icons/material-symbols/home-rounded";
+import OrdersOutline from "~icons/material-symbols/receipt-long-outline-rounded";
+import OrdersFilled from "~icons/material-symbols/receipt-long-rounded";
+import GalleryOutline from "~icons/material-symbols/widgets-outline-rounded";
+import GalleryFilled from "~icons/material-symbols/widgets-rounded";
+import SettingsOutline from "~icons/material-symbols/settings-outline-rounded";
+import SettingsFilled from "~icons/material-symbols/settings-rounded";
+
+export interface TabDefinition {
+  /** Also the tab's DOM id (`view-<id>`) and the first segment of its route. */
+  id: string;
+  labelKey: string;
+  /** M3 marks the selected destination with a filled glyph as well as the indicator. */
+  icon: Component;
+  iconSelected: Component;
+}
+
+/** Add an entry plus a route file in the matching module; the bar and the rail follow. */
+export const tabs: readonly TabDefinition[] = [
+  { id: "home", labelKey: "tabs.home", icon: HomeOutline, iconSelected: HomeFilled },
+  { id: "demo", labelKey: "tabs.demo", icon: OrdersOutline, iconSelected: OrdersFilled },
+  { id: "gallery", labelKey: "tabs.gallery", icon: GalleryOutline, iconSelected: GalleryFilled },
+  {
+    id: "settings",
+    labelKey: "tabs.settings",
+    icon: SettingsOutline,
+    iconSelected: SettingsFilled,
+  },
+];
+
+export const START_TAB = tabs[0]!.id;

package/templates/m3e-app/src/app/theme.config.ts

@@ -0,0 +1,51 @@
+import type { SchemeVariant } from "@cavulsqa/m3e";
+
+/**
+ * The brand, as data. Every colour on screen is generated from `seed` by Material's 2025 colour
+ * system; nothing else in the app is allowed to name a hex value. Change the seed here and the
+ * whole app - light, dark, every contrast level - follows.
+ */
+export const BRAND_SEED = "#c96442";
+
+export const DEFAULT_VARIANT: SchemeVariant = "tonalSpot";
+
+/**
+ * Custom colour groups beyond the M3 roles, each published as `X`, `on-X`, `X-container` and
+ * `on-X-container`. Harmonised toward the seed so they belong to the same palette.
+ */
+export const EXTRA_COLORS = {
+  success: "#1c7a4a",
+  warning: "#c08a2e",
+} as const;
+
+export interface SeedPreset {
+  id: string;
+  seed: string;
+  labelKey: string;
+}
+
+/** The colour studio's swatches, spread around the hue wheel. The first is the brand. */
+export const SEED_PRESETS: readonly SeedPreset[] = [
+  { id: "brand", seed: BRAND_SEED, labelKey: "studio.presets.brand" },
+  { id: "red", seed: "#d32f2f", labelKey: "studio.presets.red" },
+  { id: "amber", seed: "#c08a2e", labelKey: "studio.presets.amber" },
+  { id: "green", seed: "#2e7d32", labelKey: "studio.presets.green" },
+  { id: "teal", seed: "#00796b", labelKey: "studio.presets.teal" },
+  { id: "blue", seed: "#2f6fd6", labelKey: "studio.presets.blue" },
+  { id: "indigo", seed: "#4f5bd5", labelKey: "studio.presets.indigo" },
+  { id: "violet", seed: "#7b4fd0", labelKey: "studio.presets.violet" },
+  { id: "pink", seed: "#c2185b", labelKey: "studio.presets.pink" },
+  { id: "slate", seed: "#546e7a", labelKey: "studio.presets.slate" },
+];
+
+/** The variants the studio offers, in the order M3 recommends them. */
+export const STUDIO_VARIANTS: readonly SchemeVariant[] = [
+  "tonalSpot",
+  "expressive",
+  "vibrant",
+  "brand",
+  "neutral",
+  "monochrome",
+];
+
+export const TYPEFACE = `"Google Sans Flex Variable", "Google Sans Flex", Roboto, "Noto Sans", "Noto Sans Arabic", system-ui, sans-serif`;

package/templates/m3e-app/src/assets/css/app.css

@@ -0,0 +1,18 @@
+/*
+ * Cascade layers decide every conflict here, not specificity and not `!important`. Framework7's
+ * stylesheet is the lowest layer, so nothing it ships can override a component or a utility; the
+ * M3 components sit in `components` (imported from `m3e.css`), below Tailwind's utilities, so a
+ * utility on a component wins.
+ */
+@layer framework7, theme, base, components, utilities;
+
+@import "framework7/css" layer(framework7);
+@import "framework7/components/tabs/css" layer(framework7);
+@import "tailwindcss";
+
+@import "./theme/tailwind.css";
+@import "./theme/framework7.css";
+@import "./base.css";
+@import "./layout/shell.css";
+@import "./layout/transitions.css";
+@import "./layout/container-transform.css";

package/templates/m3e-app/src/assets/css/base.css

@@ -0,0 +1,53 @@
+@layer base {
+  html,
+  body {
+    background: var(--md-sys-color-surface);
+    color: var(--md-sys-color-on-surface);
+    font-family: var(--md-ref-typeface-plain);
+    font-optical-sizing: auto;
+    -webkit-font-smoothing: antialiased;
+    -webkit-tap-highlight-color: transparent;
+    -webkit-text-size-adjust: 100%;
+  }
+
+  body {
+    user-select: none;
+    overscroll-behavior: none;
+  }
+
+  input,
+  textarea,
+  [contenteditable],
+  .selectable {
+    user-select: text;
+  }
+
+  ::selection {
+    background: var(--md-sys-color-primary-container);
+    color: var(--md-sys-color-on-primary-container);
+  }
+
+  :focus-visible {
+    outline: 3px solid var(--md-sys-color-secondary);
+    outline-offset: 2px;
+  }
+
+  /*
+   * The page under a pushed one stays in the DOM; its looping animations - a loading indicator, a
+   * wave - would keep the compositor busy for a page nobody can see.
+   */
+  .page-previous *,
+  .page-previous *::before,
+  .page-previous *::after {
+    animation-play-state: paused !important;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-iteration-count: 1 !important;
+      scroll-behavior: auto !important;
+    }
+  }
+}

package/templates/m3e-app/src/assets/css/layout/container-transform.css

@@ -0,0 +1,113 @@
+/*
+ * `m3e-container`: Material's container transform, driven by `useContainerTransform`. The opened
+ * page starts clipped to the tapped card - its box, its corner radius, its colour, written on the
+ * view as `--m3e-ct-*` - and the clip opens to the full screen while the page's own content fades
+ * in over the card's colour. Back runs it in reverse into the card, re-measured just before. The
+ * page underneath holds still: only the container moves.
+ *
+ * The clip animates on the main thread, so it stays one element for one emphasized half-second.
+ * Under reduced motion it is a cross-fade.
+ *
+ * @see https://m3.material.io/styles/motion/transitions/transition-patterns
+ */
+@layer base {
+  :root {
+    --m3e-ct-duration: var(--md-sys-motion-duration-long2, 500ms);
+    --m3e-ct-ease: var(--md-sys-motion-easing-emphasized, cubic-bezier(0.2, 0, 0, 1));
+  }
+
+  .router-transition-m3e-container-forward .page-next {
+    z-index: 1;
+    animation: m3e-ct-open var(--m3e-ct-duration) var(--m3e-ct-ease) both;
+  }
+
+  .router-transition-m3e-container-forward .page-next > * {
+    animation: m3e-ct-content-in var(--m3e-ct-duration) linear both;
+  }
+
+  .router-transition-m3e-container-backward .page-current {
+    z-index: 1;
+    animation: m3e-ct-close var(--m3e-ct-duration) var(--m3e-ct-ease) both;
+  }
+
+  .router-transition-m3e-container-backward .page-current > * {
+    animation: m3e-ct-content-out var(--m3e-ct-duration) linear both;
+  }
+
+  .router-transition-m3e-container-forward .page-current,
+  .router-transition-m3e-container-backward .page-previous {
+    animation: m3e-ct-hold var(--m3e-ct-duration) linear both;
+  }
+
+  @keyframes m3e-ct-open {
+    from {
+      clip-path: inset(
+        var(--m3e-ct-top) var(--m3e-ct-right) var(--m3e-ct-bottom) var(--m3e-ct-left) round
+          var(--m3e-ct-radius)
+      );
+      background-color: var(--m3e-ct-color);
+    }
+    to {
+      clip-path: inset(0 0 0 0 round 0);
+    }
+  }
+
+  @keyframes m3e-ct-close {
+    from {
+      clip-path: inset(0 0 0 0 round 0);
+    }
+    to {
+      clip-path: inset(
+        var(--m3e-ct-top) var(--m3e-ct-right) var(--m3e-ct-bottom) var(--m3e-ct-left) round
+          var(--m3e-ct-radius)
+      );
+      background-color: var(--m3e-ct-color);
+    }
+  }
+
+  /* The card's own content is gone at once; the page's arrives once the container has room. */
+  @keyframes m3e-ct-content-in {
+    0%,
+    35% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+
+  @keyframes m3e-ct-content-out {
+    0% {
+      opacity: 1;
+    }
+    25%,
+    100% {
+      opacity: 0;
+    }
+  }
+
+  @keyframes m3e-ct-hold {
+    from,
+    to {
+      transform: none;
+      opacity: 1;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .router-transition-m3e-container-forward .page-next,
+    .router-transition-m3e-container-backward .page-previous {
+      animation: m3e-fade-in 200ms linear both;
+    }
+
+    .router-transition-m3e-container-forward .page-current,
+    .router-transition-m3e-container-backward .page-current {
+      animation: m3e-fade-out 200ms linear both;
+    }
+
+    .router-transition-m3e-container-forward .page-next > *,
+    .router-transition-m3e-container-backward .page-current > * {
+      animation: none;
+    }
+  }
+}

package/templates/m3e-app/src/assets/css/layout/shell.css

@@ -0,0 +1,69 @@
+/*
+ * The shell: the views fill the window; the compact navigation bar floats over their bottom edge,
+ * or, from 600dp, the navigation rail sits beside them. Pages never measure either - they read
+ * `--app-nav-offset`, which the shell sets to the bar's height while it is on screen.
+ */
+@layer base {
+  :root {
+    --app-nav-offset: 0px;
+    --app-bottom-inset: calc(var(--app-nav-offset) + env(safe-area-inset-bottom));
+  }
+
+  /*
+   * The root is Framework7's own element: `F7App` renders `.framework7-root` and passes no class
+   * through, so a class on `<F7App>` styles nothing. Without the row, the rail stacks above the
+   * views and pushes every page below a landscape screen.
+   */
+  .framework7-root {
+    display: flex;
+    background: var(--md-sys-color-surface);
+  }
+
+  .app-shell__rail {
+    position: relative;
+    z-index: 5001;
+    flex: none;
+  }
+
+  .app-shell__views {
+    position: relative;
+    flex: 1 1 auto;
+    box-sizing: border-box;
+    min-width: 0;
+    padding-right: env(safe-area-inset-right);
+  }
+
+  /*
+   * Material's hide-on-scroll timing: the bar enters in 225ms decelerating and leaves in 175ms
+   * accelerating, so it gets out of the way faster than it comes back.
+   */
+  .app-shell__bar {
+    position: fixed;
+    inset: auto 0 0;
+    z-index: 5001;
+    transition: transform 225ms var(--md-sys-motion-easing-emphasized-decelerate);
+  }
+
+  .app-shell__bar--hidden {
+    transform: translateY(calc(100% + 1px));
+    transition: transform 175ms var(--md-sys-motion-easing-emphasized-accelerate);
+  }
+
+  .page-content {
+    padding-bottom: calc(var(--app-bottom-inset) + 24px);
+    scroll-padding-bottom: calc(var(--app-bottom-inset) + 24px);
+    overscroll-behavior-y: contain;
+  }
+
+  .app-page--has-fab .page-content {
+    padding-bottom: calc(var(--app-bottom-inset) + 112px);
+  }
+
+  /*
+   * Tabs pinned under a page's app bar take the bar's scrolled container with it, so the two read
+   * as one surface once content slides beneath them.
+   */
+  .m3-app-bar[data-scrolled] ~ .app-sticky-tabs {
+    --m3-tabs-container: var(--md-sys-color-surface-container);
+  }
+}

package/templates/m3e-app/src/assets/css/layout/transitions.css

@@ -0,0 +1,121 @@
+/*
+ * `m3e-axis`: Material's shared-axis X transition with an Expressive spring. Forward, the new page
+ * slides in from the end edge while the old one drifts toward the start; the two fade through each
+ * other rather than stacking, so a page never reads as a card sliding over another. Back plays the
+ * same movement mirrored. Directions flip under `dir="rtl"`.
+ *
+ * Travel runs on the slow spatial spring (full-screen moves), the fade on linear keyframes timed for
+ * a fade-through. Only transform and opacity move, both on the compositor. Under reduced motion it
+ * is a plain cross-fade: the meaning (you went somewhere) stays, the travel goes.
+ *
+ * @see https://m3.material.io/styles/motion/transitions/transition-patterns
+ */
+@layer base {
+  :root {
+    --m3e-axis-distance: 64px;
+    --m3e-axis-sign: 1;
+    --m3e-axis-duration: var(--md-sys-motion-spring-slow-spatial-duration, 650ms);
+    --m3e-axis-ease: var(--md-sys-motion-spring-slow-spatial, cubic-bezier(0.2, 0, 0, 1));
+  }
+
+  [dir="rtl"] {
+    --m3e-axis-sign: -1;
+  }
+
+  .router-transition-m3e-axis-forward .page,
+  .router-transition-m3e-axis-backward .page {
+    animation-fill-mode: both;
+  }
+
+  .router-transition-m3e-axis-forward .page-next {
+    animation:
+      m3e-axis-from-end var(--m3e-axis-duration) var(--m3e-axis-ease) both,
+      m3e-fade-in var(--m3e-axis-duration) linear both;
+  }
+
+  .router-transition-m3e-axis-forward .page-current {
+    animation:
+      m3e-axis-to-start var(--m3e-axis-duration) var(--m3e-axis-ease) both,
+      m3e-fade-out var(--m3e-axis-duration) linear both;
+  }
+
+  .router-transition-m3e-axis-backward .page-current {
+    animation:
+      m3e-axis-to-end var(--m3e-axis-duration) var(--m3e-axis-ease) both,
+      m3e-fade-out var(--m3e-axis-duration) linear both;
+  }
+
+  .router-transition-m3e-axis-backward .page-previous {
+    animation:
+      m3e-axis-from-start var(--m3e-axis-duration) var(--m3e-axis-ease) both,
+      m3e-fade-in var(--m3e-axis-duration) linear both;
+  }
+
+  @keyframes m3e-axis-from-end {
+    from {
+      transform: translateX(calc(var(--m3e-axis-distance) * var(--m3e-axis-sign)));
+    }
+    to {
+      transform: none;
+    }
+  }
+
+  @keyframes m3e-axis-to-start {
+    from {
+      transform: none;
+    }
+    to {
+      transform: translateX(calc(var(--m3e-axis-distance) * var(--m3e-axis-sign) * -1));
+    }
+  }
+
+  @keyframes m3e-axis-to-end {
+    from {
+      transform: none;
+    }
+    to {
+      transform: translateX(calc(var(--m3e-axis-distance) * var(--m3e-axis-sign)));
+    }
+  }
+
+  @keyframes m3e-axis-from-start {
+    from {
+      transform: translateX(calc(var(--m3e-axis-distance) * var(--m3e-axis-sign) * -1));
+    }
+    to {
+      transform: none;
+    }
+  }
+
+  @keyframes m3e-fade-in {
+    0%,
+    30% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+
+  @keyframes m3e-fade-out {
+    0% {
+      opacity: 1;
+    }
+    30%,
+    100% {
+      opacity: 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .router-transition-m3e-axis-forward .page-next,
+    .router-transition-m3e-axis-backward .page-previous {
+      animation: m3e-fade-in 200ms linear both;
+    }
+
+    .router-transition-m3e-axis-forward .page-current,
+    .router-transition-m3e-axis-backward .page-current {
+      animation: m3e-fade-out 200ms linear both;
+    }
+  }
+}

package/templates/m3e-app/src/assets/css/m3e.css

@@ -0,0 +1,6 @@
+/*
+ * The component stylesheet, in the `components` layer `app.css` declared. It is imported on its own,
+ * after `app.css`, so Vite's CSS pipeline - not Tailwind's - owns it: Tailwind caches its compile and
+ * never noticed a linked package rebuilding this file.
+ */
+@import "@cavulsqa/m3e-vue/style.css" layer(components);

package/templates/m3e-app/src/assets/css/theme/framework7.css

@@ -0,0 +1,18 @@
+/*
+ * Framework7 still draws the page and view containers, so its variables point at the M3 roles. It
+ * draws nothing else: no navbar, no toolbar, no list. If something here grows past the page
+ * surface, a Framework7 component has crept back in.
+ */
+@layer theme {
+  :root,
+  .md,
+  .md.dark,
+  .dark {
+    --f7-page-bg-color: var(--md-sys-color-surface);
+    --f7-text-color: var(--md-sys-color-on-surface);
+    --f7-theme-color: var(--md-sys-color-primary);
+    --f7-font-family: var(--md-ref-typeface-plain);
+    --f7-bars-bg-color: transparent;
+    --f7-page-transition-duration: var(--md-sys-motion-spring-slow-spatial-duration);
+  }
+}