@woodsportal/hubspot-kit 1.0.41 → 1.0.42-dev.1

package/examples/greenfield/module-hybrid-cdn/src/features/starter/components/starter-home.tsx

@@ -1,38 +1,34 @@
 import { useStarterPreview } from '../hooks/use-starter-preview'
 import { STARTER_FEATURES, WOODSCLI_ABOUT } from '../content/woodscli-guide-content'
 
-function heroClass(style: ReturnType<typeof useStarterPreview>['heroStyle']): string {
-  if (style === 'minimal') {
-    return 'bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
-  }
-  if (style === 'bold') {
-    return 'bg-[#1c1c1f] text-white'
-  }
-  return 'bg-gradient-to-br from-[var(--starter-accent,#0091ae)] to-[#ff7a59] text-white'
-}
-
 export function StarterHome() {
-  const { title, tagline, showFeatureCards, accentColor, heroStyle } = useStarterPreview()
+  const { title, tagline, showFeatureCards, heroStyle } = useStarterPreview()
 
   return (
     <>
-      <div style={{ ['--starter-accent' as string]: accentColor }}>
-        <section className={`px-6 py-14 sm:px-10 sm:py-16 ${heroClass(heroStyle)}`}>
-          <div className="mx-auto max-w-4xl">
-            <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
-              {WOODSCLI_ABOUT.package} · local dev
-            </p>
-            <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
-            <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
-            <p className="mt-6 text-sm opacity-75">
-              Module config overlay:{' '}
-              <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
-              {' · '}
-              Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
-            </p>
-          </div>
-        </section>
-      </div>
+      <section
+        className={
+          heroStyle === 'minimal'
+            ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
+            : heroStyle === 'bold'
+              ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[#1c1c1f] text-white'
+              : 'px-6 py-14 sm:px-10 sm:py-16 bg-gradient-to-br from-[var(--primary-color,#FF7A59)] to-[var(--secondary-color,#2797AF)] text-white'
+        }
+      >
+        <div className="mx-auto max-w-4xl">
+          <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
+            {WOODSCLI_ABOUT.package} · local dev
+          </p>
+          <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
+          <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
+          <p className="mt-6 text-sm opacity-75">
+            Module config overlay:{' '}
+            <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
+            {' · '}
+            Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
+          </p>
+        </div>
+      </section>
 
       {showFeatureCards ? (
         <div className="mx-auto grid max-w-4xl gap-4 px-6 py-10 sm:grid-cols-3 sm:px-10">
@@ -41,7 +37,7 @@ export function StarterHome() {
               key={feature.title}
               className="rounded-lg border border-[#cbd6e2] bg-white p-5 shadow-sm"
             >
-              <h2 className="text-sm font-semibold text-[#0091ae]">{feature.title}</h2>
+              <h2 className="text-sm font-semibold text-[var(--primary-color,#FF7A59)]">{feature.title}</h2>
               <p className="mt-2 text-sm leading-relaxed text-[#516f90]">{feature.body}</p>
             </article>
           ))}

package/examples/greenfield/module-hybrid-cdn/src/features/starter/hooks/starter-preview-values.ts

@@ -0,0 +1,60 @@
+export type StarterPreviewValues = {
+  title: string
+  tagline: string
+  showFeatureCards: boolean
+  heroStyle: 'gradient' | 'minimal' | 'bold'
+}
+
+function normalizeHeroStyle(raw: unknown): StarterPreviewValues['heroStyle'] {
+  const key = String(raw ?? 'gradient').toLowerCase()
+  if (key === 'minimal' || key === 'bold') return key
+  return 'gradient'
+}
+
+/** CONTENT-tab fields may live under a `content` group (fields.json) or flat legacy keys. */
+function readContentField(module: Record<string, unknown>, key: string): unknown {
+  const content = module.content
+  if (content && typeof content === 'object' && key in (content as Record<string, unknown>)) {
+    return (content as Record<string, unknown>)[key]
+  }
+  return module[key]
+}
+
+/** STYLE-tab fields may live under a `style` group (fields.json) or legacy `styles` / flat keys. */
+function readStyleField(module: Record<string, unknown>, key: string): unknown {
+  const style = module.style
+  if (style && typeof style === 'object' && key in (style as Record<string, unknown>)) {
+    return (style as Record<string, unknown>)[key]
+  }
+  const styles = module.styles
+  if (styles && typeof styles === 'object' && key in (styles as Record<string, unknown>)) {
+    return (styles as Record<string, unknown>)[key]
+  }
+  return module[key]
+}
+
+export function mapStarterPreviewValues(module: Record<string, unknown>): StarterPreviewValues {
+  return {
+    title: String(readContentField(module, 'title') ?? 'My HubSpot Portal'),
+    tagline: String(
+      readContentField(module, 'tagline') ??
+        'Customize this preview with Ctrl+Shift+Z, then replace this page with your portal app.',
+    ),
+    showFeatureCards: readContentField(module, 'show_feature_cards') !== false,
+    heroStyle: normalizeHeroStyle(readStyleField(module, 'hero_style')),
+  }
+}
+
+/** HubSpot module field blob on window (dev adapter + CMS runtime). */
+export function readStarterModuleFields(): Record<string, unknown> {
+  const win = window as Window & {
+    __WPHS_DATA__?: Record<string, unknown>
+    hubSpotData?: Record<string, unknown>
+  }
+  const blob = win.__WPHS_DATA__ ?? win.hubSpotData ?? {}
+  const nested = blob.module
+  if (nested && typeof nested === 'object') {
+    return nested as Record<string, unknown>
+  }
+  return blob
+}

package/examples/greenfield/module-hybrid-cdn/src/features/starter/hooks/use-starter-preview.dev.ts

@@ -0,0 +1,18 @@
+import { MODULE_CONFIG_CHANGED } from '@/dev/module-config/schema/types'
+import { getModuleFieldValues } from '@/dev/module-config/runtime/module-config-runtime'
+
+import {
+  mapStarterPreviewValues,
+  type StarterPreviewValues,
+} from './starter-preview-values'
+
+/** Dev-only: refresh when module-config overlay applies changes. */
+export function subscribeStarterPreview(
+  onChange: (values: StarterPreviewValues) => void,
+): () => void {
+  const refresh = () => onChange(mapStarterPreviewValues(getModuleFieldValues()))
+
+  refresh()
+  window.addEventListener(MODULE_CONFIG_CHANGED, refresh)
+  return () => window.removeEventListener(MODULE_CONFIG_CHANGED, refresh)
+}

package/examples/greenfield/module-hybrid-cdn/src/features/starter/hooks/use-starter-preview.ts

@@ -1,47 +1,30 @@
 import { useEffect, useState } from 'react'
 
-import { MODULE_CONFIG_CHANGED } from '@/dev/module-config/schema/types'
-import { getModuleFieldValues } from '@/dev/module-config/runtime/module-config-runtime'
-
-export type StarterPreviewValues = {
-  title: string
-  tagline: string
-  showFeatureCards: boolean
-  accentColor: string
-  heroStyle: 'gradient' | 'minimal' | 'bold'
-}
-
-function normalizeHeroStyle(raw: unknown): StarterPreviewValues['heroStyle'] {
-  const key = String(raw ?? 'gradient').toLowerCase()
-  if (key === 'minimal' || key === 'bold') return key
-  return 'gradient'
-}
-
-function readPreviewValues(): StarterPreviewValues {
-  const module = getModuleFieldValues()
-  const accent = module.accent_color as { color?: string } | undefined
-
-  return {
-    title: String(module.title ?? 'My HubSpot Portal'),
-    tagline: String(
-      module.tagline ??
-        'Customize this preview with Ctrl+Shift+Z, then replace this page with your portal app.',
-    ),
-    showFeatureCards: module.show_feature_cards !== false,
-    accentColor: accent?.color ?? '#0091ae',
-    heroStyle: normalizeHeroStyle(module.hero_style),
-  }
-}
+import {
+  mapStarterPreviewValues,
+  readStarterModuleFields,
+  type StarterPreviewValues,
+} from './starter-preview-values'
 
-/** Live module field values for the wp init starter preview. */
+/** Module field values for the starter preview (dev overlay + production window data). */
 export function useStarterPreview(): StarterPreviewValues {
-  const [values, setValues] = useState(readPreviewValues)
+  const [values, setValues] = useState(() => mapStarterPreviewValues(readStarterModuleFields()))
 
   useEffect(() => {
-    const refresh = () => setValues(readPreviewValues())
-    window.addEventListener(MODULE_CONFIG_CHANGED, refresh)
-    return () => window.removeEventListener(MODULE_CONFIG_CHANGED, refresh)
+    if (!import.meta.env.DEV) {
+      return
+    }
+
+    let unsubscribe = () => {}
+
+    void import('./use-starter-preview.dev').then(({ subscribeStarterPreview }) => {
+      unsubscribe = subscribeStarterPreview(setValues)
+    })
+
+    return () => unsubscribe()
   }, [])
 
   return values
 }
+
+export type { StarterPreviewValues } from './starter-preview-values'

package/examples/greenfield/module-hybrid-cdn-auth-full/.env.dev.example

@@ -0,0 +1,3 @@
+# Deployed dev CDN build (deploy:dev, ci:release-module:dev) — copy to .env.dev
+VITE_NODE_ENV=dev
+VITE_PUBLIC_REST_API_ENDPOINT=https://api.dev.woodsportal.com

package/examples/greenfield/module-hybrid-cdn-auth-full/.env.local.example

@@ -0,0 +1,6 @@
+# Localhost SPA (yarn local / wp local) — copy to .env.local
+VITE_NODE_ENV=local
+VITE_DEV_MODE=live
+VITE_PUBLIC_REST_API_ENDPOINT=https://api.dev.woodsportal.com
+# VITE_DEV_PORTAL_ID=1
+# VITE_LOCAL_HUB_ID=12345678

package/examples/greenfield/module-hybrid-cdn-auth-full/.env.prod.example

@@ -0,0 +1,5 @@
+# Production CDN build — copy to .env.prod (or run wp setup)
+VITE_NODE_ENV=prod
+VITE_PORTAL_EMBED_MODE=cdn
+VITE_PUBLIC_REST_API_ENDPOINT=https://api.woodsportal.com
+# PORTAL_CDN_PUBLISH_TOKEN is written to .env.local by wp init / wp setup (hybrid CDN) — gitignored

package/examples/greenfield/module-hybrid-cdn-auth-full/.env.stg.example

@@ -0,0 +1,3 @@
+# Reserved — future staging CDN (wp build --tier stg). Copy to .env.stg when a staging API exists.
+VITE_NODE_ENV=stg
+# VITE_PUBLIC_REST_API_ENDPOINT=https://api.stg.woodsportal.com

package/examples/greenfield/module-hybrid-cdn-auth-full/.wphs/README.md

@@ -0,0 +1,17 @@
+# WoodsCLI workspace (.wphs/)
+
+Local state for **WoodsCLI** (`@woodsportal/hubspot-kit`). Not shipped to HubSpot.
+
+| Path | Purpose |
+|------|---------|
+| `config/module-config.local.json` | Live Content/Styles values (gitignored) |
+| `config/module-config.example.json` | Example generated from `fields.json` |
+| `assets/branding/` | Dev-tool uploaded images (gitignored) |
+| `fixtures/` | Optional preview / hubspot-data overrides |
+| `cache/` | CLI caches (gitignored) |
+| `audit/baseline/` | Build parity snapshots (gitignored) |
+| `.kit-module-config` | Symlink to kit dev-module-config |
+| `.kit-bootstrap.tsx` | Symlink to kit dev bootstrap (full portal) |
+| `.kit-bootstrap-greenfield.tsx` | Symlink to kit greenfield dev bootstrap |
+
+Run `wp doctor` to recreate missing folders.

package/examples/greenfield/module-hybrid-cdn-auth-full/README.md

@@ -0,0 +1,60 @@
+# Getting started
+
+This project was scaffolded with **WoodsCLI** (`@woodsportal/hubspot-kit`).
+
+## Daily dev
+
+```bash
+npm install
+wp setup
+wp doctor
+wp dev
+```
+
+Open the local URL, then **Ctrl+Shift+Z** (Mac **⌃⇧Z**) to edit module fields. Click **Apply changes** to refresh the starter preview.
+
+## Routing (`wp init`)
+
+Default is **hash history** — same as `woodsportal-client-frontend` (`#/guide` URLs work in HubSpot CMS).
+
+| `wp init --router` | Behavior |
+|--------------------|----------|
+| `hash` (default) | `createHashHistory()` — production-safe in HubSpot embeds |
+| `browser` | Clean `/guide` URLs for local dev only |
+| `none` | Single-page starter, no TanStack Router |
+
+Recorded in `woodscli.json` → `scaffold.router`.
+
+## `src/` layout
+
+| Path | Purpose |
+|------|---------|
+| `main.tsx` | Dev entry — loads styles and `mountDevPreview()` |
+| `app.tsx` | `RouterProvider` shell (client-frontend pattern) |
+| `config/router.ts` | Hash vs browser history |
+| `portal/` | Dev vs production mount (`mount-dev-preview`, `mount-portal`) |
+| `routes/` | TanStack file routes — keep thin; import from `features/` |
+| `features/starter/` | Demo home + developer guide (replace with your app) |
+| `components/` | Shared layout and UI |
+| `integrations/` | Router and third-party wiring |
+| `hubspot/` | HubSpot types and dev fixtures |
+| `config/` | Route constants and app config |
+| `assets/css/` | Tailwind entry for local dev |
+
+Kit runtime expects `src/defaultData.ts` (re-exports `hubspot/default-data.ts`).
+
+## Docs (in the kit package)
+
+After `npm install`, see:
+
+- `node_modules/@woodsportal/hubspot-kit/docs/CLI-REFERENCE.md`
+- `node_modules/@woodsportal/hubspot-kit/docs/MODULES.md`
+- `node_modules/@woodsportal/hubspot-kit/docs/HUBSPOT-CLI-SETUP.md`
+
+## HubSpot upload
+
+```bash
+cp hubspot.config.yml.example hubspot.config.yml
+# add portal + personal access key
+wp upload
+```

package/examples/greenfield/module-hybrid-cdn-auth-full/hubspot.config.yml.example

@@ -0,0 +1,10 @@
+# HubSpot CLI personal access key — copy to hubspot.config.yml (gitignored).
+# Generate at: https://app.hubspot.com/l/personal-access-key
+# Docs: https://developers.hubspot.com/docs/cms/developer-reference/local-development-cli
+
+defaultPortal: your-portal-id
+portals:
+  - name: staging
+    portalId: 12345678
+    authType: personalaccesskey
+    personalAccessKey: YOUR_PAT_HERE

package/examples/greenfield/module-hybrid-cdn-auth-full/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>WoodsCLI dev</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/greenfield/module-hybrid-cdn-auth-full/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "module-hybrid-cdn-auth-full",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "local": "wp dev",
+    "doctor": "wp doctor",
+    "build:prod": "wp build --tier prod",
+    "deploy:prod": "wp deploy --tier prod --yes",
+    "dev": "wp dev",
+    "build:dev": "wp build --tier dev",
+    "deploy:dev": "wp deploy --tier dev --yes"
+  },
+  "devDependencies": {
+    "@woodsportal/hubspot-kit": "^1.0.30",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tailwindcss/vite": "^4.0.6",
+    "@tanstack/react-router": "^1.121.2",
+    "@tanstack/router-plugin": "^1.121.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.6",
+    "vite": "^6.1.0",
+    "woodsportal-client-sdk": "^4.0.7-dev.11",
+    "@tanstack/react-query": "^5.66.9",
+    "@t3-oss/env-core": "^0.12.0",
+    "zod": "^3.24.2",
+    "sonner": "^2.0.1"
+  }
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/portal.cdn.json.example

@@ -0,0 +1,8 @@
+{
+  "publishMode": "jsdelivr",
+  "github": "your-org/your-portal-cdn-mirror",
+  "gitRemote": "https://github.com/your-org/your-portal-cdn-mirror.git",
+  "cdnPathInRepo": "dist/cdn",
+  "defaultBranch": "main",
+  "_note": "Forks: point github/gitRemote at your jsDelivr mirror repo, or set cdn.mode custom in woodscli.json."
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/public/fields.json

@@ -0,0 +1,100 @@
+[
+  {
+    "type": "group",
+    "name": "content",
+    "label": "Content",
+    "tab": "CONTENT",
+    "children": [
+      {
+        "name": "title",
+        "label": "Portal title",
+        "type": "text",
+        "default": "My HubSpot Portal"
+      },
+      {
+        "name": "tagline",
+        "label": "Tagline",
+        "type": "text",
+        "display": "textarea",
+        "help_text": "Subtitle shown under the hero title.",
+        "default": "Customize this preview with Ctrl+Shift+Z, then replace StarterPage with your portal app."
+      },
+      {
+        "name": "show_feature_cards",
+        "label": "Show feature cards",
+        "type": "boolean",
+        "display": "toggle",
+        "default": true
+      }
+    ]
+  },
+  {
+    "type": "group",
+    "name": "style",
+    "label": "Style",
+    "tab": "STYLE",
+    "children": [
+      {
+        "type": "group",
+        "name": "module_global_colors",
+        "label": "Module Global Colors",
+        "tab": "STYLE",
+        "children": [
+          {
+            "name": "primary_color",
+            "label": "Primary Color",
+            "type": "color",
+            "default": {
+              "color": "#FF7A59",
+              "opacity": 100
+            }
+          },
+          {
+            "name": "secondary_color",
+            "label": "Secondary Color",
+            "type": "color",
+            "default": {
+              "color": "#2797AF",
+              "opacity": 100
+            }
+          },
+          {
+            "name": "button_text_color",
+            "label": "Button Text Color",
+            "type": "color",
+            "default": {
+              "color": "#FFFFFF",
+              "opacity": 100
+            }
+          }
+        ],
+        "default": {
+          "primary_color": {
+            "color": "#FF7A59",
+            "opacity": 100
+          },
+          "secondary_color": {
+            "color": "#2797AF",
+            "opacity": 100
+          },
+          "button_text_color": {
+            "color": "#FFFFFF",
+            "opacity": 100
+          }
+        }
+      },
+      {
+        "name": "hero_style",
+        "label": "Hero style",
+        "type": "choice",
+        "display": "select",
+        "choices": [
+          ["gradient", "Gradient"],
+          ["minimal", "Minimal"],
+          ["bold", "Bold"]
+        ],
+        "default": "gradient"
+      }
+    ]
+  }
+]

package/examples/greenfield/module-hybrid-cdn-auth-full/public/meta.json

@@ -0,0 +1,9 @@
+{
+  "label": "WoodsPortal hybrid module",
+  "css_assets": [],
+  "external_js": [],
+  "global": false,
+  "host_template_types": ["PAGE", "BLOG_POST", "BLOG_LISTING"],
+  "content_types": ["SITE_PAGE", "LANDING_PAGE", "BLOG_POST", "BLOG_LISTING"],
+  "is_available_for_new_content": true
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/public/module.html

@@ -0,0 +1,38 @@
+{# Hybrid CDN — React app loads from jsDelivr; module.js is a thin bootstrap only. #}
+{% set in_cms_editor = is_in_editor or is_in_page_editor or is_in_previewer %}
+{% require_css %}
+<style>
+{% scope_css %}
+:root {
+  --primary-color: {{ module.style.module_global_colors.primary_color.color|default('#FF7A59') }};
+  --secondary-color: {{ module.style.module_global_colors.secondary_color.color|default('#2797AF') }};
+  --button-text-color: {{ module.style.module_global_colors.button_text_color.color|default('#FFFFFF') }};
+}
+p:not([class]) {
+  margin: 0;
+}
+ul, ol {
+  margin: 0;
+}
+{% end_scope_css %}
+</style>
+{% end_require_css %}
+<script>
+  window.hsInEditor = {{ in_cms_editor|lower }};
+  window.hubSpotData = {
+    title: {{ module.content.title|default(module.title)|tojson }},
+    tagline: {{ module.content.tagline|default(module.tagline)|tojson }},
+    show_feature_cards: {{ module.content.show_feature_cards|default(module.show_feature_cards)|lower }},
+    hero_style: {{ module.style.hero_style|tojson }},
+    assetBaseUrl: "__PORTAL_CDN_BASE__",
+    buildId: "__PORTAL_BUILD_ID__",
+    isInEditor: {{ in_cms_editor|lower }}
+  };
+</script>
+{% set portal_cdn_base = "__PORTAL_CDN_BASE__" %}
+{% set portal_vendor_script = "__PORTAL_VENDOR_FILE__" %}
+{% set portal_app_script = "__PORTAL_APP_FILE__" %}
+{# App styles ship in module.css (HubSpot editor cannot rely on external CDN CSS). #}
+{{ require_js(portal_cdn_base ~ '/' ~ portal_vendor_script, { position: 'footer', defer: true }) }}
+{{ require_js(portal_cdn_base ~ '/' ~ portal_app_script, { position: 'footer', defer: true }) }}
+<div id="app"></div>