keystone-design-bootstrap 1.0.68 → 1.0.70

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`