web-manager 4.3.1 → 4.3.2

package/CHANGELOG.md

@@ -14,6 +14,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+---
+## [4.3.2] - 2026-06-11
+
+### Added
+- **`docs/bindings.md`**: full `data-wm-bind` deep reference migrated from the `omega:ujm` skill into the repo (the module that implements the feature) — actions table, comma-separated multi-binding syntax + parser caveat, condition operators, auth/usage/custom state paths, JS API, skeleton-loader lifecycle (`wm-binding-skeleton` → `wm-bound`), multi-phase binding, composite-text pattern, and root-key update filtering. Linked from CLAUDE.md and `docs/modules.md`. Part of the skills-as-routers refactor: framework facts live in repo docs (version-matched via `node_modules`).
+
+### Changed
+- **Dependency bumps**: `@sentry/browser` `^10.54.0` → `^10.57.0`, `firebase` `^12.13.0` → `^12.14.0`.
+
 ---
 ## [4.2.0] - 2026-05-21
 ### Added

package/CLAUDE.md

@@ -76,6 +76,7 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 - [docs/architecture.md](docs/architecture.md) — singleton pattern, directory structure, module dependency graph
 - [docs/code-patterns.md](docs/code-patterns.md) — early returns, `$`-prefixed DOM vars, logical operator placement, Firestore path syntax, dynamic imports, config deep-merge, event delegation
 - [docs/modules.md](docs/modules.md) — full module quick reference (Storage, Auth + `resolveSubscription` + Settler Pattern, Bindings, Firestore, Notifications, ServiceWorker, Sentry, DOM, Utilities)
+- [docs/bindings.md](docs/bindings.md) — `data-wm-bind` deep reference: actions, comma syntax, condition operators, state paths, skeleton loaders, root-key update filtering
 - [docs/build-system.md](docs/build-system.md) — `prepare-package` ES5 transpile, build commands, package exports
 - [docs/testing.md](docs/testing.md) — Mocha test setup
 - [docs/common-tasks.md](docs/common-tasks.md) — adding a utility, adding a module, modifying config defaults, payment config (OMEGA SSOT shape), adding a binding action

package/TODO.md

@@ -1,5 +1,10 @@
-BRING BACK THESE THINGS FROM LEGACY:
-- Add back build.json fetch
+RADOM
+Remove this remove this eventually once we test the VAPDI push notificationx issue
+
+
+      const tokenOptions = { serviceWorkerRegistration: swRegistration };
+      if (this._vapidKey) { tokenOptions.vapidKey = this._vapidKey; }
+      return await getToken(messaging, tokenOptions);
 
 Do we need to use polyfill? the project that consumes this  is using webpack and compiles to es5. we need to ensure we have
 - fetch api

package/docs/bindings.md

@@ -0,0 +1,223 @@
+# Bindings (`data-wm-bind`)
+
+The `data-wm-bind` attribute declaratively binds DOM elements to state data (auth, plan, roles, usage, custom state) managed by `webManager.bindings()`. **Always prefer wm-bindings over manual JS class toggling** for anything based on user/auth state — if an element's visibility or content depends on the user object, use `data-wm-bind` in HTML, not `classList.toggle('d-none', ...)` or `.hidden` from JS.
+
+## HTML Syntax
+
+```html
+<element data-wm-bind="@action path.to.data"></element>
+```
+
+### Multiple Bindings: MUST Use Commas
+
+Multiple bindings are **comma-separated**. The parser splits by comma first, then parses each part as `@action expression`.
+
+```html
+<!-- CORRECT: comma-separated -->
+<element data-wm-bind="@show auth.user, @attr src auth.user.photoURL"></element>
+
+<!-- WRONG: space-separated — gets parsed as ONE binding with action=@show, expression="auth.user @attr src auth.user.photoURL" -->
+<element data-wm-bind="@show auth.user @attr src auth.user.photoURL"></element>
+```
+
+**Why this matters:** The parser splits on `,` then finds the first space within each part to separate `@action` from `expression`. Without commas, everything after the first `@action` is treated as a single expression string, producing broken behavior with no error.
+
+## Supported Actions
+
+| Action | Syntax | Description |
+|--------|--------|-------------|
+| `@text` | `@text path` | Set text content |
+| `@value` | `@value path` | Set input/textarea value |
+| `@show` | `@show condition` | Show element if truthy |
+| `@hide` | `@hide condition` | Hide element if truthy |
+| `@attr` | `@attr name path` | Set HTML attribute value |
+| `@style` | `@style property path` | Set CSS property or CSS variable |
+
+## Condition Operators
+
+```html
+<!-- Truthy check -->
+<div data-wm-bind="@show auth.user">Visible when logged in</div>
+
+<!-- Negation (!) -->
+<div data-wm-bind="@show !auth.user">Visible when NOT logged in</div>
+
+<!-- Comparisons (===, !==, ==, !=, >, <, >=, <=) -->
+<div data-wm-bind="@show auth.account.plan.id === 'premium'">Premium only</div>
+<div data-wm-bind="@show checkout.errorCount > 0">Has errors</div>
+```
+
+No logic operators (`&&`, `||`) in conditions — keep conditions simple. Right-side comparison values are auto-parsed: quoted strings, numbers, booleans, null.
+
+## Common Auth Patterns
+
+```html
+<!-- Show for anonymous users -->
+<div data-wm-bind="@show !auth.user">
+  <a href="/signup">Create free account</a>
+</div>
+
+<!-- Show for signed-in users -->
+<div data-wm-bind="@show auth.user">
+  <a href="/pricing">Upgrade your plan</a>
+</div>
+
+<!-- Admin-only elements -->
+<div data-wm-bind="@show auth.account.roles.admin">Admin panel</div>
+
+<!-- User data binding -->
+<img data-wm-bind="@show auth.user, @attr src auth.user.photoURL, @attr alt auth.user.displayName">
+<span data-wm-bind="@text auth.user.displayName">Loading...</span>
+<input data-wm-bind="@value auth.user.email">
+```
+
+## Available State Paths
+
+### Auth paths (automatically populated by web-manager)
+
+```
+auth.user                        # Firebase user object (truthy = signed in)
+auth.user.uid                    # User ID
+auth.user.email                  # Email
+auth.user.displayName            # Display name
+auth.user.photoURL               # Avatar URL
+auth.user.emailVerified          # Boolean
+auth.account.plan.id             # Plan ID (e.g. 'basic', 'premium')
+auth.account.roles.admin         # Boolean
+auth.account.roles.betaTester    # Boolean
+```
+
+### Usage paths (auto-populated by web-manager + authorized-fetch)
+
+```
+usage.{feature}.monthly              # Current monthly usage count
+usage.{feature}.daily                # Current daily usage count
+usage.{feature}.limit                # Plan limit for this feature
+```
+
+Example: `usage.credits.monthly`, `usage.credits.limit`
+
+Seeded on auth settle from `account.usage` + the site's payment plan config. Refreshed after every `authorizedFetch` call from `bm-properties` response headers.
+
+### Custom state (set via JS)
+
+Any custom paths set via `webManager.bindings().update(stateObject)`.
+
+## JavaScript API
+
+```javascript
+// Update bindings with state data
+webManager.bindings().update({
+  checkout: {
+    product: { name: 'Pro Plan' },
+    error: { show: false, message: '' },
+  },
+});
+
+// Get current binding context
+const context = webManager.bindings().getContext();
+
+// Clear all bindings
+webManager.bindings().clear();
+```
+
+## Skeleton Loaders
+
+### How Skeletons Work
+
+The `wm-binding-skeleton` class shows a shimmer animation until data loads. Skeletons resolve **only when at least one of the element's bindings is actually processed** — meaning the binding's root key must be in the `updatedKeys` for that `update()` call.
+
+When `_updateBindings` processes an element:
+
+1. Executes each binding action (`@text`, `@show`, `@attr`, etc.)
+2. Each action returns `true` (processed) or `false` (skipped because root key wasn't updated)
+3. **Only if at least one action was processed:** adds `wm-bound` class (triggers CSS fade-out transition)
+4. After 300ms, removes `wm-binding-skeleton` class (shimmer disappears)
+
+**Root key scoping matters for skeletons.** If an element is bound to `checkout.pricing.total` and `update({ auth: ... })` fires, that element's skeleton is NOT resolved — the binding is skipped entirely because `checkout` is not in `updatedKeys`.
+
+```html
+<!-- Skeleton resolves when 'auth' key is updated -->
+<span class="wm-binding-skeleton" data-wm-bind="@text auth.user.displayName">&nbsp;</span>
+
+<!-- Skeleton resolves when 'checkout' key is updated (NOT when 'auth' updates) -->
+<span class="wm-binding-skeleton" data-wm-bind="@text checkout.pricing.total">&nbsp;</span>
+```
+
+### Multi-phase binding example (e.g., checkout page)
+
+When bindings fire in phases, skeletons resolve independently per root key:
+
+```javascript
+// Phase 1: Global auth bindings fire
+webManager.bindings().update({ auth: { user: {...} } });
+// → Only elements bound to 'auth.*' resolve their skeletons
+// → Elements bound to 'checkout.*' keep their skeletons
+
+// Phase 2: After API fetches complete
+webManager.bindings().update({ checkout: { pricing: {...} } });
+// → Now elements bound to 'checkout.*' resolve their skeletons
+```
+
+This prevents checkout skeletons from disappearing prematurely when global auth bindings fire before checkout data is available.
+
+### Skeleton Pattern
+
+Use `&nbsp;` as placeholder content (prevents zero-width collapse so the shimmer is visible):
+
+```html
+<span class="wm-binding-skeleton" data-wm-bind="@text auth.user.displayName">&nbsp;</span>
+```
+
+**Do NOT use text like "Loading..." as placeholder** — it flashes visible text before the shimmer kicks in. Use `&nbsp;` for a clean shimmer-only experience.
+
+### Composite Text in Skeletons
+
+For composite text (e.g., "$0.00 due today"), do NOT mix static text with a binding span inside a skeleton div. Instead, create a dedicated pre-formatted value in the state and bind with a single `@text`:
+
+```javascript
+// CORRECT: compose the text in JS, bind as single value
+webManager.bindings().update({
+  checkout: {
+    totalDueText: `${formatCurrency(prices.total)} due today`,
+  },
+});
+```
+
+```html
+<!-- CORRECT: single binding for composite text -->
+<span class="wm-binding-skeleton" data-wm-bind="@text checkout.totalDueText">&nbsp;</span>
+
+<!-- WRONG: mixing static text with binding inside skeleton -->
+<span class="wm-binding-skeleton">
+  <span data-wm-bind="@text checkout.pricing.total"></span> due today
+</span>
+```
+
+## Implementation Notes
+
+- Uses the `hidden` attribute for show/hide (`[hidden] { display: none !important; }`)
+- Queries `[data-wm-bind]` on each `update()` call — handles dynamic elements
+- Auth bindings are auto-populated when `webManager.auth().listen()` fires
+- When `updatedKeys` is `null` (e.g., from `clear()`), ALL bindings fire
+
+### Root Key Update Filtering
+
+`_shouldUpdatePath` checks the **root key** (first segment before `.`) of each binding's expression path against the `updatedKeys` from the `update()` call. A binding only fires when its root key was updated.
+
+```javascript
+// This update ONLY triggers bindings whose expression starts with 'checkout'
+webManager.bindings().update({
+  checkout: { pricing: { total: 9.99 } },
+});
+// Fires: @text checkout.pricing.total, @show checkout.active
+// Skips: @text auth.user.displayName (root key is 'auth', not updated)
+```
+
+Negation (`!`) is stripped before root-key checking, so `@show !auth.user` fires when `auth` is updated.
+
+## See also
+
+- [modules.md](modules.md) — quick reference for all nine modules
+- [architecture.md](architecture.md) — module dependency graph
+- `src/modules/bindings.js` — the implementation

package/docs/modules.md

@@ -45,6 +45,7 @@ Auth uses a promise-based settler (`_authReady`) that resolves once Firebase's f
 - **Key Methods**: `update(data)`, `getContext()`, `clear()`
 - **HTML Attr**: `data-wm-bind`
 - **Actions**: `@text`, `@value`, `@show`, `@hide`, `@attr`, `@style`
+- **Deep reference**: [bindings.md](bindings.md) — comma syntax, condition operators, state paths, skeleton loaders, root-key filtering
 
 ## Firestore (`firestore.js`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-manager",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "description": "Easily access important variables such as the query string, current domain, and current page in a single object.",
   "main": "dist/index.js",
   "module": "src/index.js",
@@ -43,9 +43,9 @@
     "@sentry/browser": "Resolved by using OVERRIDES in web-manager (lighthouse is the issue"
   },
   "dependencies": {
-    "@sentry/browser": "^10.54.0",
+    "@sentry/browser": "^10.57.0",
     "chatsy": "^2.0.14",
-    "firebase": "^12.13.0",
+    "firebase": "^12.14.0",
     "itwcw-package-analytics": "^1.0.8",
     "lodash": "^4.18.1"
   },