@sonordev/site-kit 7.0.1 → 7.1.0

package/src/commerce/README.md

@@ -0,0 +1,109 @@
+# Commerce — `@sonordev/site-kit/commerce`
+
+Products, services, classes, events, and checkout flows — all managed from the Sonor dashboard.
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `OfferingCard` | Card display for any offering type |
+| `OfferingList` | Grid/list of offerings with filtering |
+| `ProductPage` / `ProductDetail` | Full product page with gallery, sizes, variants |
+| `ProductGrid` / `ProductEmbed` | Product showcase widgets |
+| `SizeChart` | Clothing size chart display |
+| `EventTile` / `UpcomingEvents` | Event display widgets |
+| `EventCalendar` / `EventModal` | Calendar view + detail modal |
+| `EventEmbed` / `EventsWidget` | Embeddable event components |
+| `CheckoutForm` | Payment checkout flow |
+| `RegistrationForm` | Event/class registration |
+| `CalendarView` | Date-based calendar component |
+
+## Usage
+
+```tsx
+import { OfferingList, ProductPage } from '@sonordev/site-kit/commerce'
+
+// List all offerings
+export default function ShopPage() {
+  return <OfferingList type="product" />
+}
+
+// Single product page
+export default function Product({ params }) {
+  return <ProductPage slug={params.slug} />
+}
+```
+
+## API Functions
+
+```ts
+import {
+  fetchOfferings, fetchOffering,
+  fetchProducts, fetchProductBySlug,
+  fetchUpcomingEvents, fetchNextEvent,
+  fetchCategories, fetchServices,
+  createCheckoutSession, createPaymentIntent,
+  validateDiscountCode, registerForEvent,
+  fetchShippingRates, validateAddress,
+} from '@sonordev/site-kit/commerce'
+```
+
+## Offering Types
+
+```ts
+type OfferingType = 'product' | 'service' | 'class' | 'event' | 'subscription'
+
+interface CommerceOffering {
+  name: string; slug: string; type: OfferingType;
+  description?: string; featured_image_url?: string;
+  price_type: 'fixed' | 'variable' | 'quote' | 'free';
+  price?: number; compare_at_price?: number; currency: string;
+  track_inventory?: boolean; inventory_count?: number;
+  is_clothing?: boolean; size_chart?: SizeChart;
+  duration_minutes?: number; capacity?: number;
+  location?: string; is_virtual?: boolean;
+  schedules?: CommerceSchedule[]; variants?: CommerceVariant[];
+}
+```
+
+## Per-category styling (`data-category` / `data-offering-type`)
+
+Event and offering surfaces expose the offering's category slug and type as
+data attributes, so sites can theme categories with plain CSS — no custom
+components needed. `data-category` is only present when the offering has a
+category; `data-offering-type` is always present.
+
+Elements carrying the attributes:
+
+- `CalendarView` / `EventCalendar` — `.site-kit-calendar-event` chips (both
+  `title` and `image` display modes) and the image-mode wrapper
+- `EventTile` (both variants — also covers `UpcomingEvents` and `EventEmbed`)
+- `EventsWidget` — `.site-kit-event-card` in list and grid views
+- `OfferingCard` (all variants — also covers `OfferingList` / `ProductGrid`)
+
+```css
+/* e.g. two color schemes on one calendar: PTO vs school district */
+.site-kit-calendar-event[data-category="pto"] {
+  background: rgba(16, 185, 129, 0.15);
+  color: #059669;
+}
+.site-kit-calendar-event[data-category="school-district"] {
+  background: rgba(59, 130, 246, 0.15);
+  color: #2563eb;
+}
+```
+
+## Size Charts (clothing products)
+
+```ts
+interface SizeChart {
+  unit: 'inches' | 'cm'
+  fit_note?: string                // e.g., "Runs small. Order one size up."
+  measurements: string[]           // ['Chest', 'Length', 'Sleeve']
+  rows: Array<{
+    size: string                   // 'S', 'M', 'L', 'XL'
+    values: number[]               // Primary unit values
+    values_alt?: number[]          // Auto-converted alternate unit
+  }>
+}
+```

package/src/cta-bar/README.md

@@ -0,0 +1,154 @@
+# @sonordev/site-kit/cta-bar
+
+The Liquid Glass mobile CTA bar (6.1.0). A floating frosted capsule that
+keeps a site's one or two highest-intent actions a thumb away on phones.
+
+It replaces every hand-rolled sticky mobile bar in the fleet. Those eleven
+copies had each solved part of the same problem set; this one does all of it:
+
+| Behaviour | Before | Here |
+|---|---|---|
+| Hide while the form it points at is on screen | two sites, hand-built | `hideOver` |
+| Stay off the hero until the hero CTA scrolls away | one site | `showAfter` |
+| Get out from under the Echo launcher | two sites (`body:has`, a 72px dead corner) | automatic |
+| Ride out the iOS toolbar collapsing | one site (a GSAP tween) | `--sk-vv-layout-gap` |
+| Get out of the way of the keyboard | nobody | `hideWhileTyping` |
+| Tell Sonor which action converts | one site (hand-wired) | `cta_click` event |
+
+## Use it
+
+```tsx
+// app/layout.tsx (a server component)
+import Link from 'next/link'
+import { Phone, ClipboardCheck } from 'lucide-react'
+import { CtaBar, CtaBarAction } from '@sonordev/site-kit/cta-bar'
+
+<SiteKitLayout>
+  <Header />
+  <main>{children}</main>
+  <Footer />
+  <CtaBar label="Call or request a quote" hideOver="#quote">
+    <CtaBarAction href="tel:+15135550100" variant="secondary" icon={<Phone />}>
+      Call now
+    </CtaBarAction>
+    <CtaBarAction as={Link} href="/quote" icon={<ClipboardCheck />}>
+      Free quote
+    </CtaBarAction>
+  </CtaBar>
+</SiteKitLayout>
+```
+
+Rules:
+
+- **Render it once per page:** at the layout root for a site-wide bar, or
+  inside the page for a page-specific one. It's a labelled `<aside>`, valid
+  at either depth; the kit's axe gate covers both placements.
+- **Never inside a blurred header.** `backdrop-filter` on an ancestor becomes
+  the containing block for this fixed bar and clips it.
+- **Delete the site's own bar and its compensating `padding-bottom`.** The
+  kit renders a spacer that reserves the bar's height at the end of the page.
+- **Better: pad the footer instead of adding a strip after it.** A spacer
+  after a dark footer is a blank band in the page colour. Pass
+  `spacer={false}` and let the footer's own background run under the bar:
+
+  ```css
+  footer { padding-bottom: calc(2rem + var(--sk-cta-bar-space, 0px)); }
+  ```
+
+  `--sk-cta-bar-space` is set on `<html>` only while a bar is present and
+  below its breakpoint, so desktop and bar-less pages get `0px`.
+- **Delete any `--sk-echo-offset-bottom` rule written for the old bar.** The
+  kit sets it while the bar is on screen.
+
+`CtaBar` and `CtaBarAction` are plain components with no hooks, so a server
+layout can pass `as={Link}` and Link children without crossing a client
+boundary. The only client code is a childless behaviour island the bar
+mounts itself (about 4.4 KB gzipped for the whole module, glass and
+analytics included).
+
+## `<CtaBar>`
+
+| Prop | Default | |
+|---|---|---|
+| `label` | `"Quick actions"` | Accessible name of the landmark. |
+| `breakpoint` | `"lg"` | Hidden at this width and up: `sm` 640, `md` 768, `lg` 1024, `xl` 1280, `none` = every width. |
+| `layout` | `"fill"` | `fill` stretches actions across the capsule. `fit` hugs a single action in a centred capsule (the old floating "Request a quote" button). |
+| `showAfter` | | Selector. Hidden until that element scrolls off the top (the hero CTA). Server-rendered hidden, so it never slides in over the hero during hydration. No match = shown. |
+| `hideOver` | | Selector or selectors. Steps aside while any match is on screen: the form it points at, the footer. |
+| `hideWhileTyping` | `true` | Hidden while a text field has focus, so it never sits on the keyboard. |
+| `compactOnScroll` | `true` | Tightens while scrolling down; an icon-bearing secondary action folds to its icon. Scrolling up restores it. |
+| `echoClearance` | `true` | Lifts the Echo launcher above the bar while the bar is on screen, below the breakpoint only. |
+| `spacer` | `true` | Reserves the bar's height at the end of the page. |
+| `track` | `true` | Sends `cta_click` (`category: engagement`, `label`, `properties.href`, `properties.variant`, `properties.location = "cta_bar"`) through the standalone analytics dispatch. |
+
+Client navigation re-finds `showAfter` and `hideOver` targets on each route.
+
+## `<CtaBarAction>`
+
+| Prop | Default | |
+|---|---|---|
+| `as` | `a` with an `href`, else `button` | Any element or component, e.g. Next's `Link`. Polymorphic since 6.1.3: the action then takes that component's own props (required ones included), so `<CtaBarAction as={ScheduleTourButton} values={unit}>` type-checks and a missing required prop doesn't. |
+| `variant` | `"primary"` | `primary`: solid brand. `secondary`: tinted glass. `plain`: layout only, bring your own classes. |
+| `icon` | | Leading icon, hidden from assistive tech. Lucide icons are sized to 18px. |
+| `collapse` | secondary + icon | Fold to icon-only while compact. The label stays in the accessible name. |
+
+Everything else (`href`, `onClick`, `target`, `aria-*`, `data-*`) passes
+through. A `button` without an explicit `type` gets `type="button"`.
+
+## Theme it
+
+Colours and geometry are custom properties. Set them on `:root` so the bar,
+its spacer and the Echo clearance all read the same values.
+
+```css
+:root {
+  --sk-cta-primary-bg: var(--brand-primary);   /* default: --sk-primary, then #2563eb */
+  --sk-cta-primary-text: #fff;
+  --sk-cta-bar-text: var(--ink-900);           /* secondary label colour */
+}
+```
+
+**A dark bar: scope the tint to the bar, not `:root`.** The Echo window
+reads the same `--sk-glass-tint`, and its text follows `--sk-text-primary`
+(dark by default). A dark tint on `:root` puts that dark text on dark glass.
+Either scope the bar's colours to the bar:
+
+```css
+.sk-cta-bar {
+  --sk-glass-tint: #0b0a09;
+  --sk-cta-bar-text: #fff;
+  --sk-cta-primary-bg: #fff;
+  --sk-cta-primary-text: #0b0a09;
+}
+```
+
+or theme the whole kit dark with `--sk-bg` and `--sk-text-primary` on
+`:root`, which both surfaces (and site-kit forms) read.
+
+| Token | Default |
+|---|---|
+| `--sk-cta-bar-inset` | `12px` from the screen edges |
+| `--sk-cta-bar-padding` | `6px` between glass and buttons |
+| `--sk-cta-bar-action-height` | `48px` (44px tap target minimum; don't go lower) |
+| `--sk-cta-bar-max-width` | `520px` |
+| `--sk-cta-bar-z` | `40` |
+| `--sk-cta-bar-text` | `--sk-text-primary`, then `#111827` |
+| `--sk-cta-primary-bg` / `--sk-cta-primary-text` | `--sk-primary` / `#fff` |
+| `--sk-cta-secondary-bg` / `--sk-cta-secondary-text` | 8% of the text colour / the text colour |
+| `--sk-glass-*` | the shared glass recipe (`--sk-glass-tint`, `--sk-glass-opacity`, `--sk-glass-blur`, `--sk-glass-saturate`) |
+
+## The glass
+
+The surface is the kit's one Liquid Glass recipe (`src/shared/glass.tsx`),
+the same material as the Echo launcher and chat window, so the bar and the
+chat always match. The tint is mostly opaque (72%): the tint carries the
+contrast, and the blur only softens what shows through. Browsers without
+`backdrop-filter`, and visitors who ask their OS for reduced transparency
+or more contrast, get the same surface solid. Reduced motion turns the
+transitions off. JS-off visitors get the bar, visible, through
+`@media (scripting: none)`.
+
+On phones where the layout viewport runs taller than the visible one
+(in-app browsers, toolbar animations), mount `VisualViewportGap` from
+`@sonordev/site-kit/client`; the bar already adds `--sk-vv-layout-gap` to
+its `bottom`.

package/src/engage/README.md

@@ -0,0 +1,241 @@
+# Engage — `@sonordev/site-kit/engage`
+
+Popups, nudges, bars, slide-ins, and chat widgets — all configured from the Sonor dashboard.
+
+## Usage
+
+Auto-included by `SiteKitLayout`. For standalone use:
+
+```tsx
+'use client'
+import { EngageWidget } from '@sonordev/site-kit/engage'
+
+export default function Layout({ children }) {
+  return (
+    <>
+      {children}
+      <EngageWidget />
+    </>
+  )
+}
+```
+
+## Props
+
+```ts
+interface EngageWidgetProps {
+  apiUrl?: string             // Default: https://api.sonor.io
+  apiKey?: string             // From SiteKitLayout or env
+  projectId?: string          // For chat routing
+  position?: 'bottom-right' | 'bottom-left'  // Default: 'bottom-right'
+  offsetBottom?: string | number             // Default: '20px'. See "Launcher placement"
+  zIndex?: number             // Default: 9999. Popups, nudges, bars and the chat. See "Stacking"
+  chatEnabled?: boolean       // Default: true. See "The chat switch"
+  debug?: boolean
+}
+```
+
+Through `SiteKitLayout`, the same options go in `engage={{ ... }}`.
+
+## The chat switch
+
+Echo follows the project's **Enable Chat Widget** switch in Sonor (Engage,
+Chat settings). A project that has never saved chat settings counts as on, so
+Echo is on by default and only an owner who switches it off hides it. It also
+needs the project's **Engage** module on (Project Settings); without it Sonor
+answers off, since the chat has nowhere to take a visitor's message.
+
+- The launcher appears once `GET /engage/widget/config` answers. Nothing
+  renders before that, so a switched-off site never flashes a launcher, and
+  it never starts Echo's availability polling.
+- If the config can't be fetched, the launcher stays hidden. The chat can't
+  run without the API anyway.
+- `chatEnabled: false` (or `engage={false}`) in code still turns chat off
+  whatever the switch says. Code can turn Echo off; it can't force it on over
+  the owner's switch.
+
+## Liquid Glass (6.1.0)
+
+Echo's launcher and chat window are made of the kit's shared Liquid Glass
+recipe (`src/shared/glass.tsx`), the same material as the mobile CTA bar
+(`@sonordev/site-kit/cta-bar`), so the two always match.
+
+- **Launcher:** brand-tinted glass (86% brand over a blurred backdrop) with a
+  specular rim. The icon turns dark on a light brand colour; it used to stay
+  white and disappear.
+- **Chat window:** a glass panel (86% tint, 28px blur) that grows out of the
+  launcher's corner. The header is part of the sheet, washed with the brand
+  at the top, and the brand sits on the avatar tile, the visitor's bubbles,
+  the send button and the launcher.
+- **Bubbles and the composer stay near-opaque** (94%). The glass is depth,
+  never the surface text reads against.
+- **Brand text always reads (6.1.2).** Where the brand is text on the panel
+  (quick-action chips, the phone link, link buttons, suggestion chips, "Talk
+  to a person"), Echo uses the brand as-is when it clears WCAG AA against the
+  panel, and otherwise pulls it toward black (light panel) or white (dark
+  panel) just far enough to clear it: `#d4af37` gold becomes `#887023`. Fills
+  (launcher, avatar, the visitor's bubbles, buttons) keep the raw brand. One
+  helper decides this, `src/engage/brand-color.ts`; route any new brand
+  foreground through it. `--sk-primary` can be hex, `rgb()` or `hsl()`.
+- **Fields are 16px.** iOS Safari zooms the whole page into any focused field
+  under 16px; the chat input and the inline Echo forms were 13.5-14px.
+- **Fallbacks:** no `backdrop-filter`, reduced transparency, or more contrast
+  all get the same surfaces solid. Reduced motion skips the open animation.
+
+Tune it with the shared tokens, from your own stylesheet:
+
+```css
+:root {
+  --sk-glass-panel-opacity: 92%;   /* denser chat window (default 86%) */
+  --sk-glass-brand-opacity: 100%;  /* solid brand launcher (default 86%) */
+  --sk-glass-tint: #0b0b0c;        /* dark glass; pair with --sk-text-primary */
+}
+```
+
+`--sk-glass-panel-opacity: 100%` gives the pre-6.1 solid window back, with the
+glass header.
+
+## Launcher placement
+
+The Echo launcher is a 60px circle, fixed 20px from the side and 20px above
+the bottom edge. Its placement is an inline style, so a stylesheet can't move
+it without `!important`. Don't write that override; declare the offset instead.
+
+**A fixed offset, every page:** pass `offsetBottom`.
+
+```tsx
+<SiteKitLayout engage={{ offsetBottom: '88px' }}>{children}</SiteKitLayout>
+```
+
+Any CSS length works (`'5.5rem'`, `'calc(4rem + 8px)'`); a number is pixels.
+The device's safe-area inset is added on top, so pass the clearance you want
+above your own UI, not the inset.
+
+**An offset that depends on the page or the breakpoint:** set the
+`--sk-echo-offset-bottom` custom property from your stylesheet. The launcher
+is portalled to `<body>`, so a declaration on `body` or `:root` reaches it,
+and the property wins over `offsetBottom`. This clears a sticky mobile bar
+only on the pages that render one:
+
+```css
+@media (max-width: 1023.98px) {
+  body:has(.sticky-cta) {
+    --sk-echo-offset-bottom: 5.5rem;
+  }
+}
+```
+
+Pages without the bar, desktop, and any browser without `:has()` keep the
+default. No `!important`, no selector on the kit's markup.
+
+**Using the kit's `<CtaBar>`?** Write nothing. It sets
+`--sk-echo-offset-bottom` itself while it's on screen, below its breakpoint,
+and the launcher glides up and back down as the bar shows and hides. Delete
+any rule like the one above that was written for a hand-rolled bar.
+
+**The popup follows.** It opens 10px above the launcher and keeps 30px clear
+of the top edge, wherever the offset puts the launcher. (An override that
+moved only the `<button>` left the popup behind, with the launcher over its
+input row.)
+
+The resolved position is:
+
+```
+launcher bottom = offset + env(safe-area-inset-bottom) + var(--sk-vv-layout-gap, 0px)
+popup bottom    = launcher bottom + 70px
+popup maxHeight = 100dvh - launcher bottom - 100px
+```
+
+### Stacking
+
+`zIndex` is the one layer everything Engage renders sits on: popups, nudges,
+bars and the chat launcher. The chat popup sits one layer beneath the
+launcher. The default is 9999, above almost anything a site draws, so lower it
+when your own fixed UI (a mobile menu, a cookie banner) has to cover the chat:
+
+```tsx
+<SiteKitLayout engage={{ zIndex: 40 }}>{children}</SiteKitLayout>
+```
+
+```
+launcher z-index = zIndex (default 9999)
+popup z-index    = zIndex - 1
+```
+
+At `zIndex` 0 or below the popup shares the launcher's layer instead, because
+-1 would put it behind the page's own content. The launcher still paints on
+top.
+
+### Layout vs visual viewport on phones
+
+On a phone the layout viewport can be taller than what the visitor can see
+(browser chrome, in-app browsers, pinch zoom), and `position: fixed` is
+measured against the layout viewport, so a bottom-fixed launcher can sit
+below the fold. Mount `VisualViewportGap` to publish the difference as
+`--sk-vv-layout-gap` on `<html>`. The launcher and popup already read it, and
+your own fixed bottom UI can too:
+
+```tsx
+import { VisualViewportGap } from '@sonordev/site-kit/client'
+
+<SiteKitLayout>
+  <VisualViewportGap />
+  {children}
+</SiteKitLayout>
+```
+
+```css
+.mobile-cta {
+  bottom: calc(24px + env(safe-area-inset-bottom, 0px) + var(--sk-vv-layout-gap, 0px));
+}
+```
+
+It's opt-in: while a field has focus the gap grows to the keyboard's height,
+so everything that reads it rides above the keyboard. `useVisualViewportGap()`
+is the hook form for an existing client component.
+
+## Element Types
+
+| Type | Description |
+|------|-------------|
+| `popup` | Modal overlay with CTA |
+| `nudge` | Small corner notification |
+| `bar` | Top/bottom sticky bar |
+| `slide-in` | Side panel |
+| `chat` | AI/live chat widget |
+
+## Targeting & Triggers
+
+All configured in the Sonor dashboard — no code changes needed:
+
+- **Page targeting** — include/exclude paths with wildcard support
+- **Device targeting** — desktop, mobile, tablet
+- **Visitor targeting** — new vs returning visitors
+- **Triggers** — immediate, delay (seconds), scroll (%), exit-intent, click, custom
+- **Frequency capping** — once, once-per-session, every N days
+
+## Chat Widget
+
+Supports AI mode (Echo), live mode, and hybrid (AI + human handoff):
+
+```ts
+interface ChatConfig {
+  position: 'bottom-right' | 'bottom-left'
+  offsetBottom?: string | number   // See "Launcher placement"
+  zIndex?: number                  // Default: 9999. See "Stacking"
+  mode: 'ai' | 'live' | 'hybrid'
+  buttonColor?: string
+  aiSettings?: {
+    skillId?: string
+    handoffToLive?: boolean
+    handoffKeywords?: string[]
+  }
+  operatingHours?: { ... }
+  offlineMode?: 'form' | 'ai' | 'message'
+  offlineFormSlug?: string
+}
+```
+
+## Tracking
+
+Impressions and clicks are automatically tracked via the Sonor API. Shares visitor ID (`_sk_vid`) with Analytics for cross-module attribution.