@marvalt/digivalt-core 0.2.28 → 0.2.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/GLOBAL-SHORTCODES.md +99 -0
  3. package/README.md +1 -1
  4. package/dist/utils/wpRegistry.d.ts +1 -1
  5. package/docs/LOVABLE-MASTER-PROMPT.md +1 -1
  6. package/docs/README.md +4 -2
  7. package/docs/SHORTCODES.md +40 -0
  8. package/package.json +5 -4
package/CHANGELOG.md CHANGED
@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.2.30] - 2026-08-26
9
+
10
+ ### Added
11
+ - `createAppRegistry` merges **`getMauticShortcodeHandlers()`** (`[mautic_form]`) and **`getPhplistShortcodeHandlers()`** (`[phplist_subscribe]`). Gravity Forms and popup shortcodes stay in core.
12
+
13
+ ### Changed
14
+ - Depends on **`@marvalt/madapter@^2.3.11`** and **`@marvalt/plister@^0.3.0`**.
15
+ - **`docs/SHORTCODES.md`** — how shortcodes are parsed and merged; points at adapter `docs/SHORTCODES.md` after install.
16
+ - `GLOBAL-SHORTCODES.md` catalog (do not register as WordPress PHP shortcodes). Included in the npm tarball.
17
+ - Apps with a local `wpRegistry.tsx` (from `digivalt-init`) need to merge the new handlers after upgrading.
18
+
19
+ ## [0.2.29] - 2026-08-12
20
+
21
+ ### Changed
22
+ - Depends on **`@digivalt/tracker@^0.1.1`** so SPA pageviews include Vite `base` / Router `basename` in Matomo and GA paths.
23
+
8
24
  ## [0.2.28] - 2026-08-03
9
25
 
10
26
  ### Added
package/GLOBAL-SHORTCODES.md ADDED
@@ -0,0 +1,99 @@
1
+ # Global Shortcodes (DigiValt Core)
2
+
3
+ How shortcodes are wired (and adapter-specific guides after npm install):
4
+
5
+ - `node_modules/@marvalt/digivalt-core/docs/SHORTCODES.md`
6
+ - `node_modules/@marvalt/madapter/docs/SHORTCODES.md` — `[mautic_form]`
7
+ - `node_modules/@marvalt/plister/docs/SHORTCODES.md` — `[phplist_subscribe]`
8
+ - `node_modules/@marvalt/wparser/docs/SHORTCODES.md` — parser / registry merge
9
+
10
+ This document lists the shortcodes supported by `@marvalt/digivalt-core` in `src/utils/wpRegistry.tsx`.
11
+
12
+ **Do not register these as WordPress PHP shortcodes.** They must remain literal text in REST/HTML so `@marvalt/wparser` can replace them with React components. Content editors type them into WordPress; the headless app renders them.
13
+
14
+ Merge order in `createAppRegistry`: adapter handlers (`@marvalt/madapter`, `@marvalt/plister`) first, then Gravity Forms, popups, and `@marvalt/shcoder` CPT shortcodes.
15
+
16
+ ## Gravity Forms (core)
17
+
18
+ - `[gf_embed id="1"]` — Render Gravity Form inline.
19
+ - `[gform form_id="1"]` — Alias of `gf_embed`.
20
+ - `[popupbtn_gf id="1" text="Submit"]` — Button that opens Gravity Form in a popup.
21
+ - `[popupgform form_id="1"]` — Alias of `popupbtn_gf`.
22
+
23
+ ## Mautic (`@marvalt/madapter`)
24
+
25
+ Handlers: `getMauticShortcodeHandlers()`. DigiValt core passes `renderForm` so the app `MauticForm` (static JSON + integration config) is used.
26
+
27
+ - `[mautic_form id="1"]` — Render Mautic form inline. Optional `title`, `description`. `formId` is accepted as an alias of `id`.
28
+ - `[popupbtn_mautic id="1" text="Contact Us"]` — Button that opens Mautic form in a popup (core-level; uses app Dialog/Button). Optional `title` for the popup heading.
29
+
30
+ Standalone apps (no DigiValt core) can merge the same handlers:
31
+
32
+ ```ts
33
+ import { getMauticShortcodeHandlers } from '@marvalt/madapter';
34
+ Object.assign(registry.shortcodes, getMauticShortcodeHandlers());
35
+ ```
36
+
37
+ Requires generated `mautic-data.json` (or a custom `resolveForm`) and `QueryClientProvider`.
38
+
39
+ ## PHPList (`@marvalt/plister`)
40
+
41
+ Handlers: `getPhplistShortcodeHandlers()`. Renders `PhpListSubscribeEmbed` (loads `phplist-data.json`, posts through the PHPList proxy). Requires `QueryClientProvider`.
42
+
43
+ - `[phplist_subscribe list="1" attrs="firstname,lastname"]` — Inline subscribe form (email plus nominated visible attributes).
44
+
45
+ | Attribute | Required | Meaning |
46
+ |-----------|----------|---------|
47
+ | `list` | Usually | List id, or slug/name from static data. If omitted, uses static `list.id` then `VITE_PHPLIST_LIST_ID`. |
48
+ | `attrs` | No | Comma-separated **visible** attribute names to collect (plus email). Omit for email only. Unknown names are skipped. Hidden/preset attributes are not supported yet. |
49
+ | `page` | No | PHPList subscribe page id (public API + confirmation emails). If omitted: first static page that includes the list, else first subscribe page, else `VITE_PHPLIST_SUBSCRIBE_PAGE_IDS`. |
50
+ | `title` | No | Override subscribe-page title. |
51
+ | `intro` | No | Override subscribe-page intro. |
52
+
53
+ PHPList has no public “subscribe to list X” API; signups go through a subscribe page. Editors can omit `page` when the site has one default page.
54
+
55
+ Dedicated subscribe routes (e.g. `/subscribe`) are unchanged; the shortcode is for embedding in WordPress content.
56
+
57
+ Standalone:
58
+
59
+ ```ts
60
+ import { getPhplistShortcodeHandlers } from '@marvalt/plister';
61
+ Object.assign(registry.shortcodes, getPhplistShortcodeHandlers());
62
+ ```
63
+
64
+ ## Member Shortcodes (`@marvalt/shcoder`)
65
+
66
+ These are mapped in DigiValt core and rendered using `@marvalt/shcoder` components/hooks.
67
+
68
+ - `[member_card id="123"]` — Single member profile.
69
+ - `[member_cards tax="leadership" cols="3" image="true"]` — Member grid.
70
+ - `[member_slideshow category="leadership" interval="5000" show_bio="true"]` — Member slideshow.
71
+
72
+ ## Testimonial Shortcodes (`@marvalt/shcoder`)
73
+
74
+ - `[testimonial_card id="123"]` — Single testimonial.
75
+ - `[testimonial_cards category="external" cols="2"]` — Testimonial grid.
76
+ - `[testimonial_slideshow category="external" interval="5000"]` — Testimonial slideshow.
77
+
78
+ ## Event Shortcodes (`@marvalt/shcoder`)
79
+
80
+ Preferred platform-agnostic names:
81
+
82
+ - `[event_card id="123"]` — Single event card.
83
+ - `[events_cards category="..." cols="3"]` — Event cards grid.
84
+ - `[events_slideshow category="..." interval="5000"]` — Event slideshow.
85
+
86
+ Legacy aliases still supported:
87
+
88
+ - `[eventbrite_event_card ...]` → alias of `event_card`
89
+ - `[eventbrite-events_cards ...]` → alias of `events_cards`
90
+ - `[eventbriteevents_cards ...]` → alias of `events_cards`
91
+ - `[eventbrite-events_slideshow ...]` → alias of `events_slideshow`
92
+ - `[eventbriteevents_slideshow ...]` → alias of `events_slideshow`
93
+
94
+ ## Notes
95
+
96
+ - Popup button shortcodes (`popupbtn_mautic`, `popupbtn_gf`) are app/core-level mappings, not adapter-package shortcodes.
97
+ - CPT dashboard widgets in `wp-custom-api-endpoints` list member/testimonial/event shortcodes only. Form shortcodes are documented here and in adapter package docs.
98
+ - Attribute support can evolve with registry/component updates; treat `wpRegistry.tsx` as source of truth.
99
+ - Apps that copied `wpRegistry.tsx` locally (via `digivalt-init`) must merge the adapter handlers (or recopy from this package) after upgrading madapter/plister/core.
package/README.md CHANGED
@@ -8,7 +8,7 @@ Core DigiVAlt package for static data generation, runtime service wiring, and Cl
8
8
  npm install @marvalt/digivalt-core
9
9
  ```
10
10
 
11
- Full handover docs: **[docs/README.md](./docs/README.md)** and **[docs/ENVIRONMENT.md](./docs/ENVIRONMENT.md)**. After install: `node_modules/@marvalt/digivalt-core/docs/README.md`.
11
+ Full handover docs: **[docs/README.md](./docs/README.md)** and **[docs/ENVIRONMENT.md](./docs/ENVIRONMENT.md)**. After install: `node_modules/@marvalt/digivalt-core/docs/README.md`. WordPress shortcodes: **[docs/SHORTCODES.md](./docs/SHORTCODES.md)** (catalog also in **[GLOBAL-SHORTCODES.md](./GLOBAL-SHORTCODES.md)**).
12
12
 
13
13
  In the **DigiVAlt monorepo**, **`digivalt-landing`** is the reference Vite app used to test this package with WordPress plugins and Cloudflare Pages.
14
14
 
package/dist/utils/wpRegistry.d.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * This registry:
5
5
  * - Maps Gutenberg blocks to React components (atomic design)
6
- * - Handles shortcodes for integrations (Gravity Forms, Mautic, etc.)
6
+ * - Handles shortcodes for integrations (Gravity Forms, Mautic via madapter, PHPList via plister)
7
7
  * - Extracts block data and passes as props to components
8
8
  * - Provides color mapping from WordPress theme colors to app CSS classes
9
9
  * - Configures spacing system for consistent element spacing
package/docs/LOVABLE-MASTER-PROMPT.md CHANGED
@@ -109,7 +109,7 @@ For forms, support Gravity Forms and Mautic via `@marvalt/digivalt-core/services
109
109
  - Static data: template starter fixtures for WordPress, Gravity Forms, Mautic
110
110
  - SEO: ON
111
111
  - Cloudflare Functions + `wrangler.toml`: ON
112
- - Form/page mapping: derive from WordPress content and shortcodes first
112
+ - Form/page mapping: derive from WordPress content and shortcodes first (`gf_embed`, `mautic_form`, `phplist_subscribe`; see `GLOBAL-SHORTCODES.md`)
113
113
 
114
114
  ---
115
115
 
package/docs/README.md CHANGED
@@ -10,6 +10,8 @@ Read these in order for DigiValt app setup, deploy, and SEO.
10
10
  | [SEO-PERFORMANCE.md](./SEO-PERFORMANCE.md) | Devs | `DigiValtSeoHead`, sitemap, `VITE_SEO_*`, performance |
11
11
  | [PATH-MOUNT.md](./PATH-MOUNT.md) | Devs | Path mounts via digivalt-uworker + Vite `base` + `withBasePath` |
12
12
  | [CLOUDFLARE-STREAM.md](./CLOUDFLARE-STREAM.md) | Devs | Stream helpers + `CloudflareStreamPlayer` (`/media`) |
13
+ | [SHORTCODES.md](./SHORTCODES.md) | Devs + editors | How WP shortcodes are parsed and merged; links to adapter docs |
14
+ | [../GLOBAL-SHORTCODES.md](../GLOBAL-SHORTCODES.md) | Devs + editors | Full shortcode catalog (same topic, package-root copy) |
13
15
 
14
16
  Package root [README.md](../README.md) covers `digivalt-init`, generators, and entry points.
15
17
 
@@ -31,7 +33,7 @@ Shadcn-heavy UI in package **source** (forms, `wpRegistry`, etc.) is **not** in
31
33
  Each ships its own `docs/README.md` under `node_modules/@marvalt/<package>/docs/`:
32
34
 
33
35
  - `@marvalt/wadapter` — WordPress + Gravity Forms
34
- - `@marvalt/madapter` — Mautic
36
+ - `@marvalt/madapter` — Mautic (including `getMauticShortcodeHandlers()` for `[mautic_form]`)
35
37
  - `@marvalt/wparser` — Gutenberg block rendering
36
38
  - `@marvalt/dstyler` — Theme / section styling
37
39
  - `@marvalt/shcoder` — CPT shortcode components
@@ -39,4 +41,4 @@ Each ships its own `docs/README.md` under `node_modules/@marvalt/<package>/docs/
39
41
  - `@marvalt/sadapter` — SuiteCRM
40
42
  - `@marvalt/cadapter` — Calendly embeds
41
43
  - `@digivalt/tracker` — Google Analytics + Matomo (required dependency; import via **`@marvalt/digivalt-core/integrations`**)
42
- - `@marvalt/plister` — PHPList newsletters, subscribe, preferences, forward
44
+ - `@marvalt/plister` — PHPList newsletters, subscribe, preferences, forward (including `getPhplistShortcodeHandlers()` for `[phplist_subscribe]`)
package/docs/SHORTCODES.md ADDED
@@ -0,0 +1,40 @@
1
+ # WordPress shortcodes — `@marvalt/digivalt-core`
2
+
3
+ After install: `node_modules/@marvalt/digivalt-core/docs/SHORTCODES.md`.
4
+
5
+ The same list lives at the package root as `GLOBAL-SHORTCODES.md`.
6
+
7
+ Content editors type shortcodes into WordPress. `@marvalt/wparser` finds `[name attr="value"]` in block HTML. `createAppRegistry` (in package **source** `src/utils/wpRegistry.tsx`, copied into apps by `digivalt-init`) maps names to React components.
8
+
9
+ **Do not register these as WordPress PHP shortcodes.** They must stay literal in REST content.
10
+
11
+ ## What the app already merges
12
+
13
+ | Shortcode | Package | Notes |
14
+ |-----------|---------|--------|
15
+ | `[mautic_form id="1"]` | `@marvalt/madapter` `getMauticShortcodeHandlers()` | Optional `title`, `description`. See `node_modules/@marvalt/madapter/docs/SHORTCODES.md`. |
16
+ | `[phplist_subscribe list="1" attrs="firstname,lastname"]` | `@marvalt/plister` `getPhplistShortcodeHandlers()` | Visible fields only. Optional `page`, `title`, `intro`. See `node_modules/@marvalt/plister/docs/SHORTCODES.md`. |
17
+ | `[gf_embed id="1"]` / `[gform …]` | core | Gravity Forms inline. |
18
+ | `[popupbtn_gf …]` / `[popupbtn_mautic …]` | core | App Dialog/Button popups. |
19
+ | `[member_*]` / `[testimonial_*]` / `[event_*]` | `@marvalt/shcoder` | CPT cards, grids, slideshows. |
20
+
21
+ Full attribute list: package root [GLOBAL-SHORTCODES.md](../GLOBAL-SHORTCODES.md).
22
+
23
+ ## If shortcodes stay as raw text
24
+
25
+ 1. The shortcode is not in `registry.shortcodes` — merge adapter handlers, or recopy `wpRegistry.tsx` after upgrading.
26
+ 2. Someone registered a PHP shortcode in WordPress — undo that so the token remains in the API response.
27
+ 3. Mautic/PHPList JSON was not generated, or `QueryClientProvider` is missing.
28
+
29
+ ## Standalone (no DigiValt `createAppRegistry`)
30
+
31
+ ```tsx
32
+ import { getMauticShortcodeHandlers } from '@marvalt/madapter';
33
+ import { getPhplistShortcodeHandlers } from '@marvalt/plister';
34
+
35
+ Object.assign(
36
+ registry.shortcodes,
37
+ getMauticShortcodeHandlers(),
38
+ getPhplistShortcodeHandlers()
39
+ );
40
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marvalt/digivalt-core",
3
- "version": "0.2.28",
3
+ "version": "0.2.30",
4
4
  "description": "Core glue logic and shared context for DigiVAlt frontend applications",
5
5
  "license": "GPL-3.0-or-later",
6
6
  "main": "dist/index.cjs",
@@ -62,6 +62,7 @@
62
62
  "README.md",
63
63
  "LICENSE",
64
64
  "CHANGELOG.md",
65
+ "GLOBAL-SHORTCODES.md",
65
66
  "bin",
66
67
  "template"
67
68
  ],
@@ -109,10 +110,10 @@
109
110
  "npm": ">=8.0.0"
110
111
  },
111
112
  "dependencies": {
112
- "@digivalt/tracker": "^0.1.0",
113
+ "@digivalt/tracker": "^0.1.1",
113
114
  "@marvalt/dstyler": "^0.1.51",
114
- "@marvalt/madapter": "^2.3.7",
115
- "@marvalt/plister": "^0.2.0",
115
+ "@marvalt/madapter": "^2.3.11",
116
+ "@marvalt/plister": "^0.3.0",
116
117
  "@marvalt/sadapter": "^0.1.5",
117
118
  "@marvalt/shcoder": "^0.1.35",
118
119
  "@marvalt/tadapter": "^1.0.12",