keystone-design-bootstrap 1.0.66 → 1.0.69

package/README.md

@@ -1,175 +1,117 @@
 # Keystone Design Bootstrap
 
-A comprehensive design system for Keystone customer websites. Provides themed sections, elements, and utilities for building consistent, server-rendered Next.js sites.
+The shared design system and runtime package powering all Keystone customer websites. Provides themed sections, UI elements, the member portal, server-side API helpers, form handling, Meta Pixel tracking, and the Next.js app shell.
 
-## Quick Start
+---
 
-1. **Set your theme** in `config/index.ts`:
-```typescript
-export const config = {
-  site: { theme: "barelux" } // or "aman", "classic"
-}
-```
+## Documentation
 
-2. **Import theme CSS** in your `app/globals.css`:
-```css
-@import "keystone-design-bootstrap/styles/fonts.css";
-@import "keystone-design-bootstrap/styles/theme.css";
-@import "keystone-design-bootstrap/styles/typography.css";
-@import "keystone-design-bootstrap/styles/style-overrides.barelux.css"; /* Change to match your theme */
-```
+| Doc | Description |
+|---|---|
+| [`docs/architecture.md`](./docs/architecture.md) | Package structure, rendering model, theme system, publishing workflow |
+| [`docs/server-api.md`](./docs/server-api.md) | All data-fetching functions, caching strategy, environment variables |
+| [`docs/navigation-and-layout.md`](./docs/navigation-and-layout.md) | `KeystoneRootLayout`, `SiteConfig`, CTA URL resolution, dynamic nav, mobile sticky footer |
+| [`docs/member-portal.md`](./docs/member-portal.md) | Member portal setup, tabs, auth flow, iframe booking, messaging |
+| [`docs/forms.md`](./docs/forms.md) | Dynamic forms, `ContactSection`, form route, custom form pattern |
+| [`docs/meta-tracking.md`](./docs/meta-tracking.md) | Meta Pixel initialization, automatic events, custom form tracking |
+| [`docs/site-customization.md`](./docs/site-customization.md) | Per-site config, style overrides, component customization hierarchy |
+| [`docs/theme-system.md`](./docs/theme-system.md) | Creating and registering themes, CSS tokens, component variants |
 
-3. **Run** `npm run dev` and you're ready!
+---
 
-## Installation
+## Quick start (new customer site)
+
+### 1. Environment variables
 
 ```bash
-npm install @keystone-pzjr/design-bootstrap
+# .env.local
+API_URL=http://localhost:3000/api/v1
+API_KEY=your-api-key-here
 ```
 
-## Using the Design System
-
-### Elements
-Reusable UI components:
+### 2. Config
 
 ```typescript
-import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'
+// config/index.ts
+import type { SiteConfig } from 'keystone-design-bootstrap/types';
 
-<Button color="primary" size="md">Click Me</Button>
-<Input label="Email" type="email" />
-<Carousel items={photos} />
+export const config: SiteConfig = {
+  site: { title: "Business Name", description: "…", theme: "aman" },
+  navigation: { header: […], footer: [[…], […], […], […]] },
+};
 ```
 
-### Server API
-Async functions for fetching data server-side:
+### 3. Root layout
 
 ```typescript
-import { getServices, getTestimonials, getBlogPosts } from '@keystone-pzjr/design-bootstrap/lib/server-api'
+// app/layout.tsx
+import { KeystoneRootLayout } from 'keystone-design-bootstrap/next/layouts/root-layout';
+import { config } from '@/config';
 
-const services = await getServices()
-const testimonials = await getTestimonials()
-```
-
-### Sections
-Pre-built page components that accept data via props:
-
-```typescript
-import { HeroHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'
-import { getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'
-
-export default async function HomePage() {
-  const testimonials = await getTestimonials()
-  return (
-    <main>
-      <HeroHome />
-      <TestimonialsHome testimonials={testimonials} />
-    </main>
-  )
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <KeystoneRootLayout config={config}>{children}</KeystoneRootLayout>;
 }
 ```
 
-**Available:** `HeroHome`, `ServicesHome`, `TestimonialsHome`, `BlogSection`, `ContactSection`, `HeaderNavigation`, `FooterHome`, and more.
-
-## Package Exports
-
-```typescript
-// Sections (hero, footer, header, testimonials, etc.)
-import { HeroHome, FooterHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'
-
-// Elements (buttons, inputs, carousels, etc.)
-import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'
-
-// Hooks
-import { useBreakpoint } from '@keystone-pzjr/design-bootstrap/hooks'
-
-// Theme context
-import { ThemeProvider } from '@keystone-pzjr/design-bootstrap/contexts'
+### 4. CSS imports
 
-// Server API utilities
-import { getServices, getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'
-
-// Types
-import type { Service, Testimonial } from '@keystone-pzjr/design-bootstrap/types'
-
-// Themes
-import { themes } from '@keystone-pzjr/design-bootstrap/themes'
+```css
+/* app/globals.css */
+@import "keystone-design-bootstrap/styles/fonts.css";
+@import "keystone-design-bootstrap/styles/theme.css";
+@import "keystone-design-bootstrap/styles/typography.css";
+@import "keystone-design-bootstrap/styles/style-overrides.aman.css"; /* match your theme */
+@import "../styles/custom-overrides.css";
 ```
 
-## Meta Pixel Tracking
+---
 
-Meta Pixel is initialised automatically in `KeystoneRootLayout` when the account has a connected Meta integration with a pixel configured. Most events fire without any extra work. The one place you need to add tracking manually is **custom form submissions**.
+## Package exports reference
 
-### What fires automatically
-
-| Event | Trigger |
+| Import path | Contents |
 |---|---|
-| `PageView` | Every page load |
-| `ViewContent` | Route changes to `/services`, `/services/:slug`, `/locations`, `/locations/:slug`, `/portal`, `/service-menu`, `/faq`, `/contact` |
-| `InitiateCheckout` | Click on any link to the account's external booking URL |
-| Portal tab events | Opening Services, Packages, Specials, or Booking tabs in the member portal |
-
-### Adding tracking to a custom form
-
-On successful submission, add two calls:
+| `keystone-design-bootstrap/sections` | All section components |
+| `keystone-design-bootstrap/elements` | UI element components |
+| `keystone-design-bootstrap/portal` | `PortalPage` and portal sub-components |
+| `keystone-design-bootstrap/next/layouts/root-layout` | `KeystoneRootLayout` |
+| `keystone-design-bootstrap/next/routes/consumer-auth` | `createConsumerAuthHandlers` |
+| `keystone-design-bootstrap/next/routes/form` | `createFormRouteHandlers` (re-exported as `POST`) |
+| `keystone-design-bootstrap/lib/server-api` | Server-side data fetching functions |
+| `keystone-design-bootstrap/lib/cta-urls` | `resolveCtaUrls`, `resolvePortalPath`, `isExternalCtaUrl` |
+| `keystone-design-bootstrap/tracking` | `firePixelEvent`, `setPixelUserData` |
+| `keystone-design-bootstrap/types` | TypeScript types |
+| `keystone-design-bootstrap/hooks` | Client-side hooks |
+| `keystone-design-bootstrap/styles/*` | CSS files |
 
-```tsx
-import { firePixelEvent, setPixelUserData } from 'keystone-design-bootstrap/tracking';
-
-// inside your success handler, after a confirmed API response:
-await setPixelUserData({ email: data.email, phone: data.phone });
-firePixelEvent('Lead');
-```
+---
 
-Also submit with `formType: 'lead'` in the POST body — this triggers the server-side CAPI `Lead` event automatically with no extra backend work.
+## Local development
 
-Both calls are silent no-ops when no Meta Pixel is configured for the site.
+Use `yalc` to test local builds in a customer site:
 
-See `components/sections/VipReferralForm.tsx` in any customer site for a complete working example.
-
-## Architecture
-
-- **Server-first**: Data fetching happens server-side, components render as Server Components where possible
-- **Theme variants**: Components automatically select variants based on active theme
-- **Tailwind-first**: Use semantic utility classes (`bg-primary`, `text-fg-primary`, `font-display`)
-- **Type-safe**: Full TypeScript support throughout
-- **CSS variables**: Themes customize via CSS custom properties
-- **Self-hosted fonts**: Uses Fontsource for optimized, bundled font loading
-
-## Theme System
-
-**Available themes:** `classic`, `aman`, `barelux`
-
-### Themes
+```bash
+# In this package
+npm run build && yalc publish
 
-- **classic**: Default professional theme, Inter font, neutral colors
-- **aman**: Luxury theme with Playfair Display serifs, warm beige, bronze accents
-- **barelux**: Modern minimal theme with Poppins, clean lines
+# In the customer site
+yalc update keystone-design-bootstrap
 
-### Creating a Theme
+# To restore the published npm version
+yalc remove keystone-design-bootstrap && npm install
+```
 
-See [`docs/theme-system.md`](./docs/theme-system.md) for complete instructions.
+---
 
-**With AI assistance:**
-```
-I am creating a new theme. Here is a link to an example: https://www.example.com
-[Attach screenshots of various pages]
+## Creating a new theme
 
-Please follow the prompt in /docs/ai-prompt-template.md
-```
+See [`docs/theme-system.md`](./docs/theme-system.md) for the full guide.
 
-**Manual steps:**
+Quick checklist:
 1. Register in `src/themes/index.ts`
 2. Install fonts via Fontsource
 3. Create `src/styles/style-overrides.{theme}.css`
 4. Create component variants (optional)
-5. Add to design gallery app
-6. Pass lint, typecheck, and build
-
-**Critical rules:**
-- Never modify base components or foundation CSS
-- Use semantic variables/classes only
-- Set BOTH `--color-*` and `--background-*` prefixes
-- Match base component props exactly
-- Ensure `npm run lint`, `npm run typecheck`, `npm run build` pass with zero errors/warnings
+5. Add to design gallery
+6. `npm run lint && npm run typecheck && npm run build` — must all pass
 
-See [`.cursor/rules/theme-creation.mdc`](./.cursor/rules/theme-creation.mdc) for detailed rules
+**Available themes:** `classic`, `aman`, `barelux`, `balance`

package/dist/design_system/sections/index.js

@@ -6261,7 +6261,7 @@ async function setPixelUserData(userData) {
     getRegisteredPixelIds().forEach((id3) => fbq("init", id3, hashed));
   }
 }
-function firePixelEvent(event, params) {
+function firePixelEvent(event, params, eventId) {
   const fbq = getFbq();
   if (!fbq) {
     console.debug("[MetaPixel] skipped \u2014 fbq not loaded", { event });
@@ -6271,8 +6271,10 @@ function firePixelEvent(event, params) {
   const normalized = {};
   if (params == null ? void 0 : params.contentName) normalized.content_name = params.contentName;
   if (params == null ? void 0 : params.contentCategory) normalized.content_category = params.contentCategory;
-  console.debug("[MetaPixel]", event, normalized);
-  fbq("track", event, Object.keys(normalized).length > 0 ? normalized : void 0);
+  const customData = Object.keys(normalized).length > 0 ? normalized : void 0;
+  const eventData = eventId ? { eventID: eventId } : void 0;
+  console.debug("[MetaPixel]", event, normalized, eventId ? { eventID: eventId } : "");
+  fbq("track", event, customData, eventData);
 }
 
 // src/next/contexts/form-definitions.tsx
@@ -6330,7 +6332,7 @@ var ContactSectionForm = ({
         (_a = formRef.current) == null ? void 0 : _a.reset();
         onSuccess == null ? void 0 : onSuccess();
         await setPixelUserData({ email: data.email, phone: data.phone });
-        firePixelEvent("Lead");
+        firePixelEvent("Lead", void 0, result.eventId);
         setTimeout(() => setSubmitStatus("idle"), 5e3);
       } else {
         setSubmitStatus("error");
@@ -6496,6 +6498,7 @@ var FooterHome = ({
 // src/design_system/sections/header-navigation.tsx
 import React22, { useRef as useRef7, useState as useState10 } from "react";
 import Link4 from "next/link";
+import { usePathname } from "next/navigation";
 import Image8 from "next/image";
 import { ChevronDown as ChevronDown4 } from "@untitledui/icons";
 import { Button as AriaButton8, Dialog as AriaDialog, DialogTrigger as AriaDialogTrigger, Popover as AriaPopover3 } from "react-aria-components";
@@ -6547,6 +6550,19 @@ var CONTACT_PATH = "/contact";
 function isExternalCtaUrl(href) {
   return href.startsWith("http://") || href.startsWith("https://");
 }
+function resolvePortalPath(companyInformation) {
+  var _a;
+  const url = (_a = companyInformation == null ? void 0 : companyInformation.portal_url) == null ? void 0 : _a.trim();
+  if (!url) return null;
+  let pathname = null;
+  try {
+    pathname = new URL(url).pathname;
+  } catch (e) {
+    pathname = url.startsWith("/") ? url : null;
+  }
+  if (!pathname || pathname === "/") return null;
+  return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+}
 function resolveCtaUrls(companyInformation) {
   var _a, _b, _c;
   const portalUrl = ((_a = companyInformation == null ? void 0 : companyInformation.portal_url) == null ? void 0 : _a.trim()) || null;
@@ -6610,6 +6626,9 @@ function HeaderNavigation({
     image: logoImage
   };
   const dynamicNavigation = navigation;
+  const pathname = usePathname();
+  const portalPath = resolvePortalPath(companyInformation);
+  const isPortalPage = portalPath ? pathname == null ? void 0 : pathname.startsWith(portalPath) : false;
   const getVariantClasses = () => {
     switch (variant) {
       case "minimal":
@@ -6817,7 +6836,7 @@ function HeaderNavigation({
         (cta_button == null ? void 0 : cta_button.secondary_label) && ctaUrls.hasSecondary ? cta_button.secondary_label : (cta_button == null ? void 0 : cta_button.label) || "Get Started"
       ))))
     ))))
-  ), /* @__PURE__ */ React22.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary" }, /* @__PURE__ */ React22.createElement("div", { className: "flex gap-0" }, (cta_button == null ? void 0 : cta_button.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React22.createElement(
+  ), !isPortalPage && /* @__PURE__ */ React22.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary" }, /* @__PURE__ */ React22.createElement("div", { className: "flex gap-0" }, (cta_button == null ? void 0 : cta_button.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React22.createElement(
     Button2,
     {
       href: ctaUrls.secondaryHref,
@@ -8591,6 +8610,7 @@ registerThemeVariant("hero-home", "aman", HeroHome2);
 import React36, { useState as useState16, useRef as useRef9, useCallback as useCallback5 } from "react";
 import Link6 from "next/link";
 import Image11 from "next/image";
+import { usePathname as usePathname2 } from "next/navigation";
 var MAX_DROPDOWN_ITEMS = 3;
 function HeaderNavigation2({
   props,
@@ -8626,6 +8646,9 @@ function HeaderNavigation2({
   const companyName = logoTextOverride || (companyInformation == null ? void 0 : companyInformation.company_name) || ((_b = props == null ? void 0 : props.logo) == null ? void 0 : _b.text) || "";
   const navigation = navigationOverride || ((_c = config == null ? void 0 : config.navigation) == null ? void 0 : _c.header) || [];
   const ctaUrls = resolveCtaUrls(companyInformation);
+  const pathname = usePathname2();
+  const portalPath = resolvePortalPath(companyInformation);
+  const isPortalPage = portalPath ? pathname == null ? void 0 : pathname.startsWith(portalPath) : false;
   const cancelCloseTimeout = useCallback5(() => {
     if (closeTimeoutRef.current) {
       clearTimeout(closeTimeoutRef.current);
@@ -8843,7 +8866,7 @@ function HeaderNavigation2({
       onClick: () => setIsMobileMenuOpen(false)
     },
     ((_q = props == null ? void 0 : props.cta_button) == null ? void 0 : _q.secondary_label) && ctaUrls.hasSecondary ? props.cta_button.secondary_label : ((_r = props == null ? void 0 : props.cta_button) == null ? void 0 : _r.label) || "Contact"
-  ))))), /* @__PURE__ */ React36.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary" }, /* @__PURE__ */ React36.createElement("div", { className: "flex gap-0" }, ((_s = props == null ? void 0 : props.cta_button) == null ? void 0 : _s.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React36.createElement(
+  ))))), !isPortalPage && /* @__PURE__ */ React36.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary" }, /* @__PURE__ */ React36.createElement("div", { className: "flex gap-0" }, ((_s = props == null ? void 0 : props.cta_button) == null ? void 0 : _s.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React36.createElement(
     Button2,
     {
       href: ctaUrls.secondaryHref,
@@ -9092,7 +9115,7 @@ var ContactSectionForm2 = ({
         (_a = formRef.current) == null ? void 0 : _a.reset();
         onSuccess == null ? void 0 : onSuccess();
         await setPixelUserData({ email: data.email, phone: data.phone });
-        firePixelEvent("Lead");
+        firePixelEvent("Lead", void 0, result.eventId);
         setTimeout(() => setSubmitStatus("idle"), 5e3);
       } else {
         setSubmitStatus("error");
@@ -17683,6 +17706,7 @@ registerThemeVariant("hero-home", "barelux", HeroHome3);
 import React45, { useState as useState23, useRef as useRef14, useCallback as useCallback8 } from "react";
 import Link8 from "next/link";
 import Image12 from "next/image";
+import { usePathname as usePathname3 } from "next/navigation";
 var MAX_DROPDOWN_ITEMS2 = 6;
 function HeaderNavigation3({
   props,
@@ -17708,6 +17732,9 @@ function HeaderNavigation3({
   const companyName = logoTextOverride || (companyInformation == null ? void 0 : companyInformation.company_name) || ((_b = props == null ? void 0 : props.logo) == null ? void 0 : _b.text) || "";
   const navigation = navigationOverride || ((_c = config == null ? void 0 : config.navigation) == null ? void 0 : _c.header) || [];
   const ctaUrls = resolveCtaUrls(companyInformation);
+  const pathname = usePathname3();
+  const portalPath = resolvePortalPath(companyInformation);
+  const isPortalPage = portalPath ? pathname == null ? void 0 : pathname.startsWith(portalPath) : false;
   const cancelCloseTimeout = useCallback8(() => {
     if (closeTimeoutRef.current) {
       clearTimeout(closeTimeoutRef.current);
@@ -17899,7 +17926,7 @@ function HeaderNavigation3({
       onClick: () => setIsMobileMenuOpen(false)
     },
     ((_m = props == null ? void 0 : props.cta_button) == null ? void 0 : _m.label) || ""
-  ))))), /* @__PURE__ */ React45.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary" }, /* @__PURE__ */ React45.createElement("div", { className: "flex gap-0" }, ((_n = props == null ? void 0 : props.cta_button) == null ? void 0 : _n.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React45.createElement(
+  ))))), !isPortalPage && /* @__PURE__ */ React45.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary" }, /* @__PURE__ */ React45.createElement("div", { className: "flex gap-0" }, ((_n = props == null ? void 0 : props.cta_button) == null ? void 0 : _n.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React45.createElement(
     Button2,
     {
       href: ctaUrls.secondaryHref,
@@ -18294,7 +18321,7 @@ var ContactSectionForm3 = ({
         (_a = formRef.current) == null ? void 0 : _a.reset();
         onSuccess == null ? void 0 : onSuccess();
         await setPixelUserData({ email: data.email, phone: data.phone });
-        firePixelEvent("Lead");
+        firePixelEvent("Lead", void 0, result.eventId);
         setTimeout(() => setSubmitStatus("idle"), 5e3);
       } else {
         setSubmitStatus("error");
@@ -18474,6 +18501,7 @@ registerThemeVariant("hero-home", "balance", HeroHome4);
 import React53, { useState as useState27, useRef as useRef16, useCallback as useCallback9 } from "react";
 import Link10 from "next/link";
 import Image13 from "next/image";
+import { usePathname as usePathname4 } from "next/navigation";
 function HeaderNavigation4({
   props,
   navigation: navigationOverride,
@@ -18498,6 +18526,9 @@ function HeaderNavigation4({
   const companyName = logoTextOverride || (companyInformation == null ? void 0 : companyInformation.company_name) || ((_b = props == null ? void 0 : props.logo) == null ? void 0 : _b.text) || "";
   const navigation = navigationOverride || ((_c = config == null ? void 0 : config.navigation) == null ? void 0 : _c.header) || [];
   const ctaUrls = resolveCtaUrls(companyInformation);
+  const pathname = usePathname4();
+  const portalPath = resolvePortalPath(companyInformation);
+  const isPortalPage = portalPath ? pathname == null ? void 0 : pathname.startsWith(portalPath) : false;
   const cancelCloseTimeout = useCallback9(() => {
     if (closeTimeoutRef.current) {
       clearTimeout(closeTimeoutRef.current);
@@ -18659,7 +18690,7 @@ function HeaderNavigation4({
       onClick: () => setIsMobileMenuOpen(false)
     },
     ((_m = props == null ? void 0 : props.cta_button) == null ? void 0 : _m.label) || ""
-  ))))), /* @__PURE__ */ React53.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden", style: { backgroundColor: "rgb(148, 133, 84)" } }, /* @__PURE__ */ React53.createElement("div", { className: "flex gap-0" }, ((_n = props == null ? void 0 : props.cta_button) == null ? void 0 : _n.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React53.createElement(
+  ))))), !isPortalPage && /* @__PURE__ */ React53.createElement("div", { className: "fixed bottom-0 left-0 right-0 z-40 md:hidden", style: { backgroundColor: "rgb(148, 133, 84)" } }, /* @__PURE__ */ React53.createElement("div", { className: "flex gap-0" }, ((_n = props == null ? void 0 : props.cta_button) == null ? void 0 : _n.secondary_label) && ctaUrls.hasSecondary && /* @__PURE__ */ React53.createElement(
     Button2,
     {
       href: ctaUrls.secondaryHref,
@@ -18788,7 +18819,7 @@ var ContactSectionForm4 = ({
         (_a = formRef.current) == null ? void 0 : _a.reset();
         onSuccess == null ? void 0 : onSuccess();
         await setPixelUserData({ email: data.email, phone: data.phone });
-        firePixelEvent("Lead");
+        firePixelEvent("Lead", void 0, result.eventId);
         setTimeout(() => setSubmitStatus("idle"), 5e3);
       } else {
         setSubmitStatus("error");