codeplay-common 4.2.3 → 4.2.5

package/.gitattributes

@@ -1,2 +1,2 @@
-# Auto detect text files and perform LF normalization
-* text=auto
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Merbin Joe
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Merbin Joe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,103 +1,119 @@
-# codeplay-common
- Everything automatted in Capacitor apps, easy to maintain many apps in capacitor. It will reduce your 40% of work, with common file code.
-
-
-Easy add splashscreen and set animation
-Admob id automatically from capacitor.config.json file
-Make three build file for different store as per our requirement
-Based on store install various IAP plugins
-Make it to ionic project
-
-Donate to get full code including many common functions
-https://ko-fi.com/codeplay
-
-
-Version 4.2.3
-  Added build warning confirmation when android.ORIENTATION is not "auto" or android.RESIZEABLE_ACTIVITY is not true.
-
-Version 4.2.2
-  Added "bannerDisabledPages" property and its default value
-  The admob configuration default value priority is updated
-
-Version 4.2.1
-  Updated AdMob nextgen file validation to match admob-emi-nextgen file names.
-
-Version 4.2.0
-  Firebase related automatic changes updated
-
-Version 4.1.9
-  Added AdMob nextgen 1.7 validation/default support for "overlappingHeight", "bannerTypeAndroidLandscape", and "bannerTypeiOSLandscape".
-
-Version 4.1.8
-  "consentDebug: false" is added
-
-Version 4.1.7
-  admob configuration automatically added.
-
-Version 4.1.6
-  "setup-baseline-profile.js" modification, duplicate validation error fixed
-
-Version 4.1.5
-  While isTesting is true it is not validated from our new configuration admob file, now it is solved
-
-Version 4.1.4
-  hardcoded version is removed for the admob-emi-nextgen
-
-
-Version 4.1.3
-"consentDebug": false automatically adds if not
-
-Version 4.1.2
-  Speedup
-
-Version 4.1.1
-  Auto admob integration updated
-
-
-version 4.0.9
-  packageJson.scripts["ionic:serve"] = "cross-env NODE_ENV=development vite"; this line updated in "sync-files.js"
-
-
-version 4.0.8
-  safearea plugin is checked and removed automatically
-  Automatically added following in capacitor.config.json file
-      "SystemBars": {
-        "insetsHandling": "css"
-      }
-  patchFile() method is removed
-
-
-
-
-Version 4.0.6
-  IAP related some automatic variable creation and validation
-   Fetch from vite.config.json file
-      'import.meta.env.VITE_APP_UNIQUE_ID': JSON.stringify(APP_UNIQUE_ID),
-      'import.meta.env.VITE_ANDROID_ANALYTICS_ENABLED': JSON.stringify(ANDROID_ANALYTICS_ENABLED),
-      'import.meta.env.VITE_IOS_ANALYTICS_ENABLED': JSON.stringify(IOS_ANALYTICS_ENABLED),
-      'import.meta.env.VITE_IAP_DESIGN': JSON.stringify(IAP_DESIGN),
-
-
-Version 4.0.5
-  In "files\buildCodeplay\packageidBaseModification-1.4.js" SCHEDULE_EXACT_ALARM permission added for the app unique id 2 (resume generator app)
-
-
-Version 4.0.4
-  patchFile(); method is disabled, Due to "@capacitor/android:8.4.2" this update. I think it is realted to  safearea issue fixed in this latest version, file in "SystemBars.java"
-
-Version 4.0.3
-  Old admob check performs through plugin location, but not it is validated from capacitor.config.json 
-
-
-Version: 4.0.2
-  After check & install/download the latest version, the re-check is cancelled now
-
-Version: 4.0.1
-    Base profile script added
-
-
-  "version": "",
-Version : 4.0.0 (Previous version 3.2.19)
-    1) In here we are completly remove the admob-emi and use "capacitor-admob-nextgen"
-    2) Removed "modify-plugin-xml.js"
-    3) 
+# codeplay-common
+ Everything automatted in Capacitor apps, easy to maintain many apps in capacitor. It will reduce your 40% of work, with common file code.
+
+
+Easy add splashscreen and set animation
+Admob id automatically from capacitor.config.json file
+Make three build file for different store as per our requirement
+Based on store install various IAP plugins
+Make it to ionic project
+
+## Agent instruction templates
+
+Agent instructions are maintained independently under `agent-templates/v<version>/`.
+The version in `agent-templates/manifest.json` is installed by default. To pin a
+project to a specific instruction version, add this to the project's `package.json`:
+
+```json
+"codeplayCommon": {
+  "agentsVersion": "1.0"
+}
+```
+
+During npm installation, the selected template's `AGENTS.md` and `AGENTS/` folder
+are copied to the project root. Project-only files with different names inside
+`AGENTS/` are preserved.
+
+Donate to get full code including many common functions
+https://ko-fi.com/codeplay
+
+
+Version 4.2.3
+  Added build warning confirmation when android.ORIENTATION is not "auto" or android.RESIZEABLE_ACTIVITY is not true.
+
+Version 4.2.2
+  Added "bannerDisabledPages" property and its default value
+  The admob configuration default value priority is updated
+
+Version 4.2.1
+  Updated AdMob nextgen file validation to match admob-emi-nextgen file names.
+
+Version 4.2.0
+  Firebase related automatic changes updated
+
+Version 4.1.9
+  Added AdMob nextgen 1.7 validation/default support for "overlappingHeight", "bannerTypeAndroidLandscape", and "bannerTypeiOSLandscape".
+
+Version 4.1.8
+  "consentDebug: false" is added
+
+Version 4.1.7
+  admob configuration automatically added.
+
+Version 4.1.6
+  "setup-baseline-profile.js" modification, duplicate validation error fixed
+
+Version 4.1.5
+  While isTesting is true it is not validated from our new configuration admob file, now it is solved
+
+Version 4.1.4
+  hardcoded version is removed for the admob-emi-nextgen
+
+
+Version 4.1.3
+"consentDebug": false automatically adds if not
+
+Version 4.1.2
+  Speedup
+
+Version 4.1.1
+  Auto admob integration updated
+
+
+version 4.0.9
+  packageJson.scripts["ionic:serve"] = "cross-env NODE_ENV=development vite"; this line updated in "sync-files.js"
+
+
+version 4.0.8
+  safearea plugin is checked and removed automatically
+  Automatically added following in capacitor.config.json file
+      "SystemBars": {
+        "insetsHandling": "css"
+      }
+  patchFile() method is removed
+
+
+
+
+Version 4.0.6
+  IAP related some automatic variable creation and validation
+   Fetch from vite.config.json file
+      'import.meta.env.VITE_APP_UNIQUE_ID': JSON.stringify(APP_UNIQUE_ID),
+      'import.meta.env.VITE_ANDROID_ANALYTICS_ENABLED': JSON.stringify(ANDROID_ANALYTICS_ENABLED),
+      'import.meta.env.VITE_IOS_ANALYTICS_ENABLED': JSON.stringify(IOS_ANALYTICS_ENABLED),
+      'import.meta.env.VITE_IAP_DESIGN': JSON.stringify(IAP_DESIGN),
+
+
+Version 4.0.5
+  In "files\buildCodeplay\packageidBaseModification-1.4.js" SCHEDULE_EXACT_ALARM permission added for the app unique id 2 (resume generator app)
+
+
+Version 4.0.4
+  patchFile(); method is disabled, Due to "@capacitor/android:8.4.2" this update. I think it is realted to  safearea issue fixed in this latest version, file in "SystemBars.java"
+
+Version 4.0.3
+  Old admob check performs through plugin location, but not it is validated from capacitor.config.json 
+
+
+Version: 4.0.2
+  After check & install/download the latest version, the re-check is cancelled now
+
+Version: 4.0.1
+    Base profile script added
+
+
+  "version": "",
+Version : 4.0.0 (Previous version 3.2.19)
+    1) In here we are completly remove the admob-emi and use "capacitor-admob-nextgen"
+    2) Removed "modify-plugin-xml.js"
+    3) 

package/agent-templates/manifest.json

@@ -0,0 +1,7 @@
+{
+  "current": "1.1",
+  "versions": [
+    "1.0"
+    ,"1.1"
+  ]
+}

package/agent-templates/v1.0/AGENTS/agent-screenshot.md

@@ -0,0 +1,12 @@
+# Screenshot Capture Rule
+
+- Always capture from the current connected/online adb device only.
+- Before running any screenshot command:
+  - Detect the first device with `device` state from `adb devices`.
+  - Do not use any key events (no power, wake, or lock/unlock commands).
+  - Do not use screen-state changes (`keyevent 26`, `keyevent 224`, etc.).
+- Capture command sequence:
+  1. `adb -s <device-id> shell screencap -p /sdcard/current_connected_screenshot.png`
+  2. `adb -s <device-id> pull /sdcard/current_connected_screenshot.png _connected_screenshot.png`
+  3. `adb -s <device-id> shell rm /sdcard/current_connected_screenshot.png`
+- If no device is in `device` state, stop and report `no_connected_device` before running any screenshot command.

package/agent-templates/v1.0/AGENTS/agent-temp.md

@@ -0,0 +1,4 @@
+# AGENT TEMP FOLDER RULE
+
+- All temporary files and folders created while executing tasks (including images, cache files, debug output, and generated artifacts) **must be written only under the project-level `agent-temp/` directory**.
+- Do not create or leave temporary artifacts in repository root, `src`, `www`, `public`, or other project folders.

package/agent-templates/v1.0/AGENTS/agents-create-new-page.md

@@ -0,0 +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.
+
+
+
+
+
+
+if you are using $$ you must import dom7