codeplay-common 4.2.4 → 4.2.6

package/agent-templates/{v1.0 → v1.1}/AGENTS/agents-create-new-page.md

@@ -1,242 +1,242 @@
-# Framework7 `.f7` New Page Standard (Cross-App)
-
-## Source-of-truth and project scope
-Use these files as mandatory baseline before creating any new page:
-`AGENTS.md`, `AGENTS\agents.md`, existing pages under `src\pages`, `src\js\routes.js`, and theme files under `src\theme`.
-Use the matching project’s actual files for any app where you are implementing this standard.
-
-## Required page shape
-Every new page file must use `.f7` with exactly one `<template>` and one `<script>`.
-The root DOM must be one `.page` element with `data-name`.
-
-Minimum skeleton:
-```html
-<template>
-  <div class="page" data-name="newPage">
-    <!-- optional navbar -->
-    <!-- page content -->
-  </div>
-</template>
-<script>
-export default (props, { $f7, $el, $on }) => {
-  // lifecycle + handlers
-  return $render;
-};
-</script>
-```
-
-## Route integration rule
-After creating any new `.f7` page, add it to `src\js\routes.js` with lazy async loading and route names ending in `/`, matching existing app routes.
-Use this style:
-```js
-{
-  path: '/NewPageName/',
-  //component: newPageImport
-  async async({ resolve }) {
-    const page = await import('../pages/newpage.f7');
-    resolve({ component: page.default });
-  },
-},
-```
-
-Match the existing conventions exactly:
-- path names use PascalCase and trailing slash.
-- import path should point to `../pages/<file>.f7`.
-- component is resolved from `page.default`.
-
-## Back button rule (required)
-All new pages must use the shared back handler from `src/js/back.js`.
-
-Add this import:
-```js
-import { backButtonPress } from './../js/back.js';
-```
-
-Use `backButtonPress` for every page back action in navbars, back links, and custom back controls.
-
-```html
-<div class="left">
-  <div class="link" @click="${backButtonPress}">
-    <img src="${backImage}" class="backIconImg"></img>
-  </div>
-</div>
-```
-
-Do not use custom `router.back()` or manual `window.history.back()` in new pages.
-If a page requires a custom close/exit confirmation, keep it inside `backButtonPress` central flow or `common` helpers, then wire the same handler.
-
-The central `backButtonPress` flow must preserve the actual navigation source:
-- Home keeps the app's existing exit-confirmation behavior.
-- Pages with explicit product behavior may keep a named destination in `src/js/back.js`.
-- All other pages must use the main Framework7 router history to return to the previous page.
-- If no previous route exists, the central handler must return to Home.
-- Do not add page-local back methods or hardcode Home in ordinary secondary pages.
-
-When a page has popups/sheets/dialogs open, verify the shared handler’s behavior for overlays before adding extra back logic.
-
-## Template structure (strict)
-Use Framework7 layout components before any custom markup.
-For pages with header actions use `.navbar` with `.navbar-bg`.
-If theme color is needed, include `.theme-navbarBackColor`.
-For content use `.page-content`.
-For tab rows use `.subnavbar` + `.toolbar.toolbar-top.tabbar`.
-For bottom action bars use `.toolbar.toolbar-bottom.tabbar`.
-
-Examples:
-`<div class="navbar"> <div class="navbar-bg theme-navbarBackColor"></div> <div class="navbar-inner">...</div> </div>`
-
-`<div class="subnavbar theme-navbarBackColor"><div class="subnavbar-inner"><div class="toolbar toolbar-top tabbar">...</div></div></div>`
-
-`<div class="toolbar toolbar-bottom tabbar theme-navbarBackColor"><div class="toolbar-inner">...</div></div>`
-
-## Framework7 custom component enable/disable rule
-If a new page uses a component beyond the currently enabled baseline, update these files first:
-- `src/js/framework7-custom.js`
-- `src/assets/css/framework7-custom.less`
-
-Enable a component by uncommenting both:
-- JS import and registration in `src/js/framework7-custom.js`
-- matching LESS import in `src/assets/css/framework7-custom.less`
-
-Disable a component by commenting both import/registration and LESS import.
-Keep JS and LESS changes synchronized for each enabled component.
-
-Keep this section app-agnostic.
-For each app, enable only components that are required by that app and keep JS/LESS toggles synchronized in that app's own `framework7-custom` files.
-
-## Grid and list policy
-Use Framework7 utilities for columns:
-`grid`, `grid-cols-*`, `grid-gap`, `display-flex`, and standard alignment classes.
-Use framework list classes:
-`list`, `list media-list`, `item-content`, `item-inner`, `item-title`.
-Do not create new custom grid/list styles unless existing utilities are impossible.
-
-## Navbar and status-bar behavior
-If page has a header, add theme activation in lifecycle:
-```js
-$on("pageBeforeIn", () => {
-  ThemeController.activateForPage({
-    navColor: 'white',
-    statusColor: 'white',
-    navIsAutoMode: false,
-    statusIsAutoMode: false,
-    navCanChangeInNavScroll: false,
-    statusCanChangeInNavScroll: true
-  });
-});
-```
-
-If page needs translation updates, listen to app theme event in `pageInit`.
-
-## Sheet / popup / popover / dialog usage
-Use Framework7 APIs to create these controls.
-Do not hand-style internals as ad-hoc floating containers.
-For sheets use `sheet` element + `$f7.sheet.create`.
-For popups use `$f7.popup.create`.
-For popovers use `$f7.popover.create`.
-For completion dialogs always set back behavior using dialog options, for example `dialogClass: 'namepopup-dialog dialog-back-no-close'`.
-
-For non-dismissible bottom sheet/popups, use proper F7 class + safe-area aware spacing from shared styles.
-
-## FAB policy
-Use `.fab` and `.fab-button` classes only.
-Avoid building custom floating action components with fixed positioned custom HTML.
-If using FAB for mobile actions, set `right`, `bottom`, and alignment with F7 classes and existing utilities.
-
-## Styling policy for new pages
-Avoid inline style attributes in new pages.
-Do not add custom CSS classes directly inside `.f7` unless truly unavoidable.
-Also follow all theme rules in this app’s theme notes file (for example `src\theme\<theme-folder>\Notes.txt`) when designing page visuals.
-If style is needed, define it in:
-`src\theme\theme-x.x\theme.less`, `src\theme\theme-x.x\theme-dialog.less`, or `src\assets\css\common-x.x.less`.
-All theme helper classes should be prefixed with `t-`.
-Prefer theme classes like `theme-navbarBackColor`, `t-fade-img`, existing ripple utility classes, and shared page-level helper classes.
-
-Theme file musts / reminders from `<theme-folder>\Notes.txt` (for example `theme-x.x\Notes.txt`):
-- Prefer Framework7 classes first; only fallback to theme css when not possible.
-- Use `theme-navbarBackColor` for navbar color consistency.
-- Reuse existing utility variables like `--bg-main1`, `--bg-main2`, `--bg-main2-text`, `--tab-active-bg`, `--tab-inactive-text`, etc.
-- Use shared theme class prefix `t-*` for all new custom theme classes.
-- For images that must change by theme, use `data-image-light` / `data-image-dark` and call `ThemeController.activateForPage()` when needed.
-- Theme-related changes should go to `src/theme/css/custom.less`, `src/theme/css/light.less`, or `src/theme/css/dark.less` only.
-- For light/dark and system behavior checks, use existing `ThemeController` helpers.
-- Do not change protected shared styles directly on a page with inline or per-page overrides unless explicitly required.
-
-Do not modify `www` and do not edit protected shared files unless user explicitly grants permission.
-Protected list is in `AGENTS.md`.
-
-If you notice a missing instruction between this file and `Notes.txt`, update this instruction file first and follow the stricter one.
-
-## Handler and event rules
-Keep template event bindings minimal and avoid large inline arrow expressions in markup.
-Define handlers as named functions and bind directly.
-Keep DOM queries inside lifecycle events only.
-
-Good pattern:
-`@click="${onOpenMenu}"`, `@click="${openTemplatePopup}"`, `@click="${goBack}"`
-Avoid repeating heavy anonymous callbacks inside markup.
-
-## Reuse over duplication
-Before creating helpers, check existing exported helpers in project js folders.
-Prefer reuse of common functions in shared modules.
-Do not introduce duplicate utilities for back navigation, theme switching, popover/popup creation, dialogs, toasts, or storage.
-
-## Shared method first (required)
-Before adding new helper methods, always search and reuse existing common methods in the project.
-If a shared method already exists, do not create a new one.
-
-Important shared method source for new pages:
-- `./../js/common-x.x.js`
-- theme/controller helpers already imported in existing pages (for example `ThemeController`)
-
-From the project update notes:
-- For back handling in app shell, `capacitor-app.js` must import:
-  `import { backButtonCheckAndExit } from './common-x.x.js';`
-  and call `backButtonCheckAndExit();` inside `handleAndroidBackButton`.
-- If a new page needs spinner stop, import:
-  `import { stopSpinner } from './../js/common-x.x.js';`
-
-Commonly available methods to prefer (examples):
-- `hideForMethod`
-- `shareApp` (with `noAppOpenShowUntilResume`)
-- `shareContent` (with `noAppOpenShowUntilResume`)
-- `rateUs` (with `noAppOpenShowUntilResume`)
-- `gotoPrivacypolicy` (with `noAppOpenShowUntilResume`)
-- `openDeveloperApps` (with `noAppOpenShowUntilResume`)
-- `bugReportPopup`
-- `showToast`
-- `showSpinner`, `stopSpinner`
-- `showAlertBox`
-- `setLocalStorage`, `getLocalStorage`, `removeLocalStorage`
-- `getExactContentHeight`
-- `confirmDialog`
-- `setNavBarColor`, `setStatusBarColor` (order note: call `setNavBarColor` first)
-- `manageStorage(key).setState/getState/removeState`
-- `initTouchableImages` for touch feedback animations
-- `activateLogTracker`, `getConsoleData` (testing only)
-
-Notes:
-- `showPage`, `backButtonPress`, and theme-related helpers should remain consistent with existing patterns.
-- Deprecated / removed methods from older notes should not be reintroduced.
-
-## Required quality checklist before returning page code
-Page file name and `data-name` are unique.
-Navbar, page-content, and footer toolbar structure use Framework7 classes.
-No new inline style blocks are used unless the exception is explicitly justified.
-No hardcoded `background-color` at page element level unless required by theme variant.
-No direct edits to protected files were made.
-New route is added in `src\js\routes.js`.
-At least one existing Framework7 component is used for each required UI area.
-Theme activation and lifecycle usage is present when page has a header.
-If dialog cannot close on back press, `dialogClass` rule is set at call site.
-
-## Response rule for this repo
-When codegen is requested from this file, follow this instruction order first:
-structure, route, template layout, theme integration, handlers, then script wiring.
-
-
-
-
-
-
+# Framework7 `.f7` New Page Standard (Cross-App)
+
+## Source-of-truth and project scope
+Use these files as mandatory baseline before creating any new page:
+`AGENTS.md`, `AGENTS\agents.md`, existing pages under `src\pages`, `src\js\routes.js`, and theme files under `src\theme`.
+Use the matching project’s actual files for any app where you are implementing this standard.
+
+## Required page shape
+Every new page file must use `.f7` with exactly one `<template>` and one `<script>`.
+The root DOM must be one `.page` element with `data-name`.
+
+Minimum skeleton:
+```html
+<template>
+  <div class="page" data-name="newPage">
+    <!-- optional navbar -->
+    <!-- page content -->
+  </div>
+</template>
+<script>
+export default (props, { $f7, $el, $on }) => {
+  // lifecycle + handlers
+  return $render;
+};
+</script>
+```
+
+## Route integration rule
+After creating any new `.f7` page, add it to `src\js\routes.js` with lazy async loading and route names ending in `/`, matching existing app routes.
+Use this style:
+```js
+{
+  path: '/NewPageName/',
+  //component: newPageImport
+  async async({ resolve }) {
+    const page = await import('../pages/newpage.f7');
+    resolve({ component: page.default });
+  },
+},
+```
+
+Match the existing conventions exactly:
+- path names use PascalCase and trailing slash.
+- import path should point to `../pages/<file>.f7`.
+- component is resolved from `page.default`.
+
+## Back button rule (required)
+All new pages must use the shared back handler from `src/js/back.js`.
+
+Add this import:
+```js
+import { backButtonPress } from './../js/back.js';
+```
+
+Use `backButtonPress` for every page back action in navbars, back links, and custom back controls.
+
+```html
+<div class="left">
+  <div class="link" @click="${backButtonPress}">
+    <img src="${backImage}" class="backIconImg"></img>
+  </div>
+</div>
+```
+
+Do not use custom `router.back()` or manual `window.history.back()` in new pages.
+If a page requires a custom close/exit confirmation, keep it inside `backButtonPress` central flow or `common` helpers, then wire the same handler.
+
+The central `backButtonPress` flow must preserve the actual navigation source:
+- Home keeps the app's existing exit-confirmation behavior.
+- Pages with explicit product behavior may keep a named destination in `src/js/back.js`.
+- All other pages must use the main Framework7 router history to return to the previous page.
+- If no previous route exists, the central handler must return to Home.
+- Do not add page-local back methods or hardcode Home in ordinary secondary pages.
+
+When a page has popups/sheets/dialogs open, verify the shared handler’s behavior for overlays before adding extra back logic.
+
+## Template structure (strict)
+Use Framework7 layout components before any custom markup.
+For pages with header actions use `.navbar` with `.navbar-bg`.
+If theme color is needed, include `.theme-navbarBackColor`.
+For content use `.page-content`.
+For tab rows use `.subnavbar` + `.toolbar.toolbar-top.tabbar`.
+For bottom action bars use `.toolbar.toolbar-bottom.tabbar`.
+
+Examples:
+`<div class="navbar"> <div class="navbar-bg theme-navbarBackColor"></div> <div class="navbar-inner">...</div> </div>`
+
+`<div class="subnavbar theme-navbarBackColor"><div class="subnavbar-inner"><div class="toolbar toolbar-top tabbar">...</div></div></div>`
+
+`<div class="toolbar toolbar-bottom tabbar theme-navbarBackColor"><div class="toolbar-inner">...</div></div>`
+
+## Framework7 custom component enable/disable rule
+If a new page uses a component beyond the currently enabled baseline, update these files first:
+- `src/js/framework7-custom.js`
+- `src/assets/css/framework7-custom.less`
+
+Enable a component by uncommenting both:
+- JS import and registration in `src/js/framework7-custom.js`
+- matching LESS import in `src/assets/css/framework7-custom.less`
+
+Disable a component by commenting both import/registration and LESS import.
+Keep JS and LESS changes synchronized for each enabled component.
+
+Keep this section app-agnostic.
+For each app, enable only components that are required by that app and keep JS/LESS toggles synchronized in that app's own `framework7-custom` files.
+
+## Grid and list policy
+Use Framework7 utilities for columns:
+`grid`, `grid-cols-*`, `grid-gap`, `display-flex`, and standard alignment classes.
+Use framework list classes:
+`list`, `list media-list`, `item-content`, `item-inner`, `item-title`.
+Do not create new custom grid/list styles unless existing utilities are impossible.
+
+## Navbar and status-bar behavior
+If page has a header, add theme activation in lifecycle:
+```js
+$on("pageBeforeIn", () => {
+  ThemeController.activateForPage({
+    navColor: 'white',
+    statusColor: 'white',
+    navIsAutoMode: false,
+    statusIsAutoMode: false,
+    navCanChangeInNavScroll: false,
+    statusCanChangeInNavScroll: true
+  });
+});
+```
+
+If page needs translation updates, listen to app theme event in `pageInit`.
+
+## Sheet / popup / popover / dialog usage
+Use Framework7 APIs to create these controls.
+Do not hand-style internals as ad-hoc floating containers.
+For sheets use `sheet` element + `$f7.sheet.create`.
+For popups use `$f7.popup.create`.
+For popovers use `$f7.popover.create`.
+For completion dialogs always set back behavior using dialog options, for example `dialogClass: 'namepopup-dialog dialog-back-no-close'`.
+
+For non-dismissible bottom sheet/popups, use proper F7 class + safe-area aware spacing from shared styles.
+
+## FAB policy
+Use `.fab` and `.fab-button` classes only.
+Avoid building custom floating action components with fixed positioned custom HTML.
+If using FAB for mobile actions, set `right`, `bottom`, and alignment with F7 classes and existing utilities.
+
+## Styling policy for new pages
+Avoid inline style attributes in new pages.
+Do not add custom CSS classes directly inside `.f7` unless truly unavoidable.
+Also follow all theme rules in this app’s theme notes file (for example `src\theme\<theme-folder>\Notes.txt`) when designing page visuals.
+If style is needed, define it in:
+`src\theme\theme-x.x\theme.less`, `src\theme\theme-x.x\theme-dialog.less`, or `src\assets\css\common-x.x.less`.
+All theme helper classes should be prefixed with `t-`.
+Prefer theme classes like `theme-navbarBackColor`, `t-fade-img`, existing ripple utility classes, and shared page-level helper classes.
+
+Theme file musts / reminders from `<theme-folder>\Notes.txt` (for example `theme-x.x\Notes.txt`):
+- Prefer Framework7 classes first; only fallback to theme css when not possible.
+- Use `theme-navbarBackColor` for navbar color consistency.
+- Reuse existing utility variables like `--bg-main1`, `--bg-main2`, `--bg-main2-text`, `--tab-active-bg`, `--tab-inactive-text`, etc.
+- Use shared theme class prefix `t-*` for all new custom theme classes.
+- For images that must change by theme, use `data-image-light` / `data-image-dark` and call `ThemeController.activateForPage()` when needed.
+- Theme-related changes should go to `src/theme/css/custom.less`, `src/theme/css/light.less`, or `src/theme/css/dark.less` only.
+- For light/dark and system behavior checks, use existing `ThemeController` helpers.
+- Do not change protected shared styles directly on a page with inline or per-page overrides unless explicitly required.
+
+Do not modify `www` and do not edit protected shared files unless user explicitly grants permission.
+Protected list is in `AGENTS.md`.
+
+If you notice a missing instruction between this file and `Notes.txt`, update this instruction file first and follow the stricter one.
+
+## Handler and event rules
+Keep template event bindings minimal and avoid large inline arrow expressions in markup.
+Define handlers as named functions and bind directly.
+Keep DOM queries inside lifecycle events only.
+
+Good pattern:
+`@click="${onOpenMenu}"`, `@click="${openTemplatePopup}"`, `@click="${goBack}"`
+Avoid repeating heavy anonymous callbacks inside markup.
+
+## Reuse over duplication
+Before creating helpers, check existing exported helpers in project js folders.
+Prefer reuse of common functions in shared modules.
+Do not introduce duplicate utilities for back navigation, theme switching, popover/popup creation, dialogs, toasts, or storage.
+
+## Shared method first (required)
+Before adding new helper methods, always search and reuse existing common methods in the project.
+If a shared method already exists, do not create a new one.
+
+Important shared method source for new pages:
+- `./../js/common-x.x.js`
+- theme/controller helpers already imported in existing pages (for example `ThemeController`)
+
+From the project update notes:
+- For back handling in app shell, `capacitor-app.js` must import:
+  `import { backButtonCheckAndExit } from './common-x.x.js';`
+  and call `backButtonCheckAndExit();` inside `handleAndroidBackButton`.
+- If a new page needs spinner stop, import:
+  `import { stopSpinner } from './../js/common-x.x.js';`
+
+Commonly available methods to prefer (examples):
+- `hideForMethod`
+- `shareApp` (with `noAppOpenShowUntilResume`)
+- `shareContent` (with `noAppOpenShowUntilResume`)
+- `rateUs` (with `noAppOpenShowUntilResume`)
+- `gotoPrivacypolicy` (with `noAppOpenShowUntilResume`)
+- `openDeveloperApps` (with `noAppOpenShowUntilResume`)
+- `bugReportPopup`
+- `showToast`
+- `showSpinner`, `stopSpinner`
+- `showAlertBox`
+- `setLocalStorage`, `getLocalStorage`, `removeLocalStorage`
+- `getExactContentHeight`
+- `confirmDialog`
+- `setNavBarColor`, `setStatusBarColor` (order note: call `setNavBarColor` first)
+- `manageStorage(key).setState/getState/removeState`
+- `initTouchableImages` for touch feedback animations
+- `activateLogTracker`, `getConsoleData` (testing only)
+
+Notes:
+- `showPage`, `backButtonPress`, and theme-related helpers should remain consistent with existing patterns.
+- Deprecated / removed methods from older notes should not be reintroduced.
+
+## Required quality checklist before returning page code
+Page file name and `data-name` are unique.
+Navbar, page-content, and footer toolbar structure use Framework7 classes.
+No new inline style blocks are used unless the exception is explicitly justified.
+No hardcoded `background-color` at page element level unless required by theme variant.
+No direct edits to protected files were made.
+New route is added in `src\js\routes.js`.
+At least one existing Framework7 component is used for each required UI area.
+Theme activation and lifecycle usage is present when page has a header.
+If dialog cannot close on back press, `dialogClass` rule is set at call site.
+
+## Response rule for this repo
+When codegen is requested from this file, follow this instruction order first:
+structure, route, template layout, theme integration, handlers, then script wiring.
+
+
+
+
+
+
 if you are using $$ you must import dom7