@idkwebsites/components 0.1.16 → 0.1.18

package/BOOKING-WIDGET.md

@@ -0,0 +1,340 @@
+# Booking Widget — Porting Guide
+
+Reusable booking component built on `@idkwebsites/components`. This doc covers everything needed to port the widget to another project or extract it into the package.
+
+---
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `app/components/booking-widget-panel.tsx` | The widget component (all logic + render) |
+| `app/globals.css` (`.bw-*` section) | All widget styles, starting at the `/* ── Booking Widget ──` comment |
+| `app/booking/page.tsx` | Example booking page (site-specific layout wrapper) |
+
+## Dependencies
+
+```json
+{
+  "@idkwebsites/components": "useBookingWidget, useServices, useTeam hooks",
+  "framer-motion": "AnimatePresence + motion for staff trigger animation, chevron rotation",
+  "smooth-scrollbar": "Smooth scrollbar with bounce overscroll on services list + mobile body",
+  "lucide-react": "Scissors, Sparkles, Heart, Palette, CircleDot, User, ChevronLeft/Right/Down, Check, ArrowRight/Left, Globe, Menu, X",
+  "next": "next/link for mobile nav links"
+}
+```
+
+---
+
+## Props
+
+```tsx
+interface BookingWidgetProps {
+  /** Navigation links for the mobile menu overlay. Omit to hide the hamburger entirely. */
+  navLinks?: { label: string; href: string }[];
+  /** Custom icon for the mobile menu open button (default: lucide Menu 20px) */
+  menuIcon?: React.ReactNode;
+  /** Custom icon for the mobile menu close button (default: lucide X 20px) */
+  closeIcon?: React.ReactNode;
+  /** Override the category → icon mapping (keyword → lucide component) */
+  categoryIcons?: Record<string, LucideIcon>;
+  /** Override step titles for the mobile 4-step flow */
+  stepTitles?: [string, string, string, string];
+}
+```
+
+### Usage example
+
+```tsx
+import { BookingWidgetPanel } from "@/app/components/booking-widget-panel";
+import { primaryNavLinks } from "@/app/lib/site-config";
+import { Flower2 } from "lucide-react";
+
+<BookingWidgetPanel
+  navLinks={primaryNavLinks}
+  menuIcon={<Flower2 size={20} />}
+  categoryIcons={{ botanical: Flower2 }}
+  stepTitles={[
+    "Choose your treatment",
+    "Select a service",
+    "Pick a date & time",
+    "Your information",
+  ]}
+/>
+```
+
+---
+
+## Page Layout
+
+The booking page should fill the entire viewport (navbar + widget, nothing else). **No footer. No floating elements (phone button, chat, etc.).**
+
+Do NOT use your site shell component (e.g. `SiteShell`). Site shells typically include footers, floating phone buttons, and other chrome that shouldn't appear on the booking page. Import only the site header directly.
+
+### Recommended: Flex wrapper (handles any navbar height automatically)
+
+```tsx
+// app/booking/page.tsx
+import { SiteHeader } from "@/app/components/site-header";
+import { BookingWidgetPanel } from "@/app/components/booking-widget-panel";
+import { primaryNavLinks } from "@/app/lib/site-config";
+
+export default function BookingPage() {
+  return (
+    <div className="booking-page">
+      <SiteHeader />
+      <BookingWidgetPanel navLinks={primaryNavLinks} />
+    </div>
+  );
+}
+```
+
+```css
+/* Site-specific CSS */
+.booking-page {
+  height: 100vh;
+  height: 100dvh;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.booking-page > .bw {
+  flex: 1;
+  min-height: 0;
+  height: auto;
+}
+
+/* Hide site header on mobile — the widget has its own topbar with hamburger */
+@media (max-width: 1024px) {
+  .booking-page > .site-header { display: none; }
+}
+```
+
+**Key points:**
+- The wrapper div uses `overflow: hidden` — no scrolling on this page, ever (desktop). Mobile uses smooth-scrollbar on the body for bounce overscroll.
+- `.bw` uses `flex: 1` to fill remaining space — no hardcoded navbar heights needed.
+- On mobile (≤1024px), the site header is hidden. The widget's own topbar shows progress dots + a hamburger menu that opens a nav overlay. Pass `navLinks` to populate it.
+
+### Alternative: Offset variable (when you can't control the page layout)
+
+If you must use a shell/layout you can't modify, set `--bw-offset-top` instead:
+
+```css
+.bw {
+  --bw-offset-top: 73px; /* navbar height including borders */
+}
+
+@media (max-width: 1024px) {
+  .bw {
+    --bw-offset-top: 61px;
+  }
+}
+```
+
+The base `.bw` styles use `height: calc(100dvh - var(--bw-offset-top))`. Default is `0px`.
+
+---
+
+## Theming
+
+Override these CSS custom properties on `.bw` or a parent to re-skin the widget:
+
+```css
+.bw {
+  --bw-font: "Inter", sans-serif;
+  --bw-bg: #FFFFFF;
+  --bw-text: #1A1A1A;
+  --bw-text-secondary: #6B6B6B;
+  --bw-text-muted: #999999;
+  --bw-border: #E8E8E8;
+  --bw-border-light: #F0F0F0;
+  --bw-radius: 8px;
+  --bw-radius-lg: 12px;
+  --bw-primary: #1A1A1A;        /* buttons, selected states, active borders */
+  --bw-primary-text: #FFFFFF;
+  --bw-hover: #F8F8F8;
+  --bw-error-bg: #fef2f2;
+  --bw-error-text: #b91c1c;
+  --bw-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);       /* dropdowns */
+  --bw-shadow-badge: 0 1px 4px rgba(0, 0, 0, 0.12);   /* price badge on image */
+  --bw-offset-top: 0px;         /* see Page Layout section */
+}
+```
+
+All visual styling uses these tokens. Change them per-site and the widget adapts.
+
+---
+
+## Component Structure
+
+### Desktop (>1024px): 3-column grid
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Schedule your visit                                     │
+├────────────┬─────────────────────────┬───────────────────┤
+│ LEFT       │ CENTER                  │ RIGHT             │
+│            │                         │                   │
+│ [Dropdown] │  February 2026    ˅  < >│ Full name         │
+│ Specialist │                         │ Email             │
+│ ─────────  │  Calendar grid          │ Phone             │
+│ ✂ Hair   ˅ │                         │ Notes             │
+│  ☐ Cut     │  ─────────────          │                   │
+│  ☑ Color   │  Time slots             │ Booking Summary   │
+│  ☐ Style   │  (4-per-row grid)       │  · Specialist     │
+│ ✦ Skin   › │                         │ [Confirm Booking] │
+│ ♥ Spa    › │  🌐 Timezone            │                   │
+│            │                         │                   │
+└────────────┴─────────────────────────┴───────────────────┘
+```
+
+- **Left column (22%):** Specialist custom dropdown → divider → category accordion cards with services nested under the expanded category
+- **Center column (flexible):** Calendar card with custom month dropdown + time slots (4 per row)
+- **Right column (22%):** Form fields, booking summary (with specialist), confirm button
+
+### Mobile (≤1024px): 4-step flow
+
+```
+┌─────────────────────────┐
+│ ●● ○ ○              ≡   │  ← progress dots + hamburger
+├─────────────────────────┤
+│ Schedule your visit      │  ← step title
+│                         │
+│ [content for step]      │  ← scrollable body with bounce overscroll
+│                         │
+├─────────────────────────┤
+│        Next →           │  ← footer (back + next/confirm)
+└─────────────────────────┘
+```
+
+Step 1: Specialist dropdown + category accordion
+Step 2: Service list (with images + price badges when available)
+Step 3: Calendar + time slots
+Step 4: Form fields (scrollable) + booking summary (in footer)
+
+---
+
+## Key Behaviors
+
+### Specialist selection
+- Custom dropdown (NOT a native `<select>`). Comes FIRST because services/categories may depend on which specialist is chosen.
+- **Always visible** — shows "Any Available" by default.
+- **Staff list comes from `useTeam()` hook** — NOT from `bw.staffOptions`. The hook's built-in `staffOptions` filters by selected service, which is the opposite of what we want.
+- **Staff selection filters services** — services are client-side filtered by `assignedStaff`.
+- **Dropdown is portaled** to `.bw-portal` (inside `.bw` but outside `.bw-body`) to escape smooth-scrollbar's `transform` context. Uses `position: fixed` + `z-index: 10000`.
+- **Booking summary** includes specialist name (or "Any Available") on both desktop and mobile.
+
+### Category selection (accordion)
+- Categories render as accordion cards with auto-mapped icons.
+- **Animated with CSS grid:** `grid-template-rows: 0fr → 1fr` transition (250ms). No framer-motion for the accordion — pure CSS for smooth, jitter-free animation.
+- **Each accordion section filters its own services** from the full service list by category. This prevents the closing section from showing the wrong services during the collapse animation.
+- Icon mapping (override via `categoryIcons` prop): `hair/cut/barber/styling → Scissors`, `skin/facial/beauty → Sparkles`, `massage/wellness/spa → Heart`, `nail/color/manicure/pedicure → Palette`, default → `CircleDot`.
+
+### Services list — varied content
+Services adapt their layout based on available data:
+
+**Desktop (inline, inside accordion):**
+- Checkbox (18px) + name (12px) + meta "dur · price" (11px) + optional description (11px, truncated) + optional thumbnail (36×36px, 6px radius)
+
+**Mobile step 2 (full):**
+- **With image:** Checkbox (20px) + name (14px) + duration (12px) + description (11px) + 120×120px image (14px radius) with price badge overlay (white bg, 8px radius, 13px bold, shadow)
+- **Without image:** Checkbox (20px) + name + duration + description + price text on right (14px, 600 weight)
+- No dividers between rows
+
+### Mobile topbar
+- **Progress dots** on the left (28px wide, 3px tall, 8px gap)
+- **Hamburger menu** on the right (customizable via `menuIcon` / `closeIcon` props)
+- Opens a full-screen nav overlay with links from `navLinks` prop
+- Topbar sits above the overlay (`z-index: 101` vs `100`) so the toggle button is always clickable
+- If `navLinks` is empty/omitted, the hamburger is hidden entirely
+
+### Step 1 validation
+- "Next" button is disabled until a category is selected (`categoryFilter !== "all"`)
+
+### Mobile scrolling
+- Body uses `smooth-scrollbar` with `OverscrollPlugin` (bounce effect)
+- Scroll position resets instantly on step change (`scrollTo(0, 0, 0)`)
+- Scrollbar tracks are hidden
+
+### Booking summary
+- Shows: Service, Specialist, Date, Time, Duration, Estimated total
+- No dividers between rows (clean stacked layout)
+- On mobile step 4, summary is rendered in the footer (attached to the confirm button), not in the scrollable body
+
+---
+
+## Smooth Scrollbar Setup
+
+```ts
+import Scrollbar from "smooth-scrollbar";
+import OverscrollPlugin from "smooth-scrollbar/plugins/overscroll";
+
+Scrollbar.use(OverscrollPlugin);
+
+const opts = {
+  damping: 0.08,
+  continuousScrolling: false,
+  alwaysShowTracks: false,
+  plugins: {
+    overscroll: { effect: "bounce", damping: 0.15, maxOverscroll: 80 },
+  },
+};
+```
+
+Applied to:
+- `.bw-svc-scroll-wrap` (services list) — desktop only (≥1025px)
+- `.bw-body` (mobile body) — mobile only (≤1024px), bounce overscroll
+
+Scrollbar is re-initialized on media query changes and when category filter changes.
+
+---
+
+## CSS Architecture
+
+All widget classes use the `bw-` prefix. No Tailwind classes — pure CSS for portability.
+
+### Critical layout chain (prevents viewport overflow)
+
+```
+.bw                    → height from flex or offset, overflow: hidden, flex column, position: relative
+  .bw-topbar           → hidden on desktop, flex row on mobile (dots + hamburger)
+  .bw-nav-overlay      → mobile nav (position: absolute, z-index: 100)
+  .bw-header           → natural height
+  .bw-body             → flex: 1, grid on desktop, flex column on mobile
+    .bw-body-inner     → display: contents on desktop, flex column on mobile
+      .bw-col--left    → specialist + categories + services
+      .bw-col--center  → calendar + time slots
+      .bw-col--right   → form + summary
+  .bw-footer           → mobile only (next/back buttons, step 4 summary)
+  .bw-portal           → portal target for staff dropdown (outside .bw-body)
+```
+
+### Responsive breakpoints
+
+| Breakpoint | Layout |
+|------------|--------|
+| >1024px | 3-column grid: 22% / 1fr / 22%, site header visible |
+| ≤1024px | Single column, 4-step mobile flow, site header hidden, widget topbar with hamburger |
+| ≤480px | Tighter padding, smaller fonts and touch targets |
+
+---
+
+## Porting Checklist
+
+1. Copy `booking-widget-panel.tsx` and the `.bw-*` CSS block (from `/* ── Booking Widget ──` to the end of the responsive blocks)
+2. Install deps: `@idkwebsites/components`, `smooth-scrollbar`, `lucide-react`, `framer-motion`
+3. Set up the booking page:
+   - Use a flex wrapper div (`.booking-page`) — NOT your site shell
+   - Import only the site header, no footer or floating elements
+   - Set `overflow: hidden` on the wrapper
+   - Add `.booking-page > .bw { flex: 1; min-height: 0; height: auto; }` to your CSS
+   - Hide the site header on mobile: `.booking-page > .site-header { display: none; }` at ≤1024px
+4. Pass props:
+   - `navLinks` — your site's navigation links for the mobile hamburger menu
+   - `menuIcon` / `closeIcon` — custom icons if you don't want the default lucide Menu/X
+   - `categoryIcons` — override category-to-icon mapping if your categories don't match the defaults
+   - `stepTitles` — override the 4 step titles if needed
+5. Override `--bw-*` CSS tokens to match your brand
+6. The widget handles booking logic via `useBookingWidget`, `useServices`, and `useTeam` hooks
+7. If your site has a floating phone/chat button, hide it on the booking page