@ohhwells/bridge 0.1.29-next.20 → 0.1.29-next.24

package/README.md

@@ -184,6 +184,64 @@ Add `data-ohw-editable` and `data-ohw-key` to any element the studio owner shoul
 
 ---
 
+## SchedulingWidget (vibe-coder placement)
+
+`SchedulingWidget` lets a template builder embed a scheduling/booking section directly in their template JSX, without going through the "Add Section" flow. The canvas editor treats it exactly like a dynamically-inserted scheduling widget — the studio owner can connect a schedule, switch it, and clear it.
+
+### Basic usage
+
+```tsx
+import { SchedulingWidget } from '@ohhwells/bridge'
+
+export default function ClassesPage() {
+  return (
+    <>
+      <PageHeader ... />
+      <ClassLibrary ... />
+      <SchedulingWidget />
+      <WordmarkBand ... />
+    </>
+  )
+}
+```
+
+No props are required. The widget auto-generates a stable identity via React's `useId()` so the bridge can track which schedule is connected to it across saves.
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `insertAfter` | `string` | auto | Stable identifier used as the tracker key. Only set this manually if you need two `SchedulingWidget`s on the same page. |
+| `initialScheduleId` | `string \| null` | `undefined` | Set by the bridge internally after hydration. Do not pass this yourself. |
+| `notifyOnConnect` | `boolean` | `false` | Set by the bridge internally. Do not pass this yourself. |
+
+### How it works
+
+1. The widget renders immediately with a loading skeleton.
+2. It sends `ow:request-schedule-config` to the bridge (running in the same window).
+3. The bridge looks up the tracker for a saved `scheduleId` for this widget:
+   - **Found** → responds with `ow:schedule-config { scheduleId }` → widget loads that schedule.
+   - **Not found (first time)** → bridge adopts the widget (adds it to the tracker, notifies the canvas editor), responds with `scheduleId: null` → widget shows empty state with an "Add Schedule" button.
+4. In the canvas editor, the studio owner clicks "Add Schedule" → selects a schedule → the widget updates and the connection is saved.
+5. On the live site, the widget fetches the saved schedule by ID and renders it.
+
+### Multiple widgets on one page
+
+Each `SchedulingWidget` must have a unique `insertAfter` to be tracked independently:
+
+```tsx
+<SchedulingWidget insertAfter="classes-morning" />
+<SchedulingWidget insertAfter="classes-evening" />
+```
+
+If you omit `insertAfter` on both, `useId()` auto-generates different stable IDs for each, so they are tracked separately anyway.
+
+### Empty state on live site
+
+If the studio owner has never connected a schedule to this widget, it renders nothing on the live site (no empty placeholder is shown to visitors).
+
+---
+
 ## Editable states (advanced)
 
 For elements with multiple display states (e.g. a contact form with default/success/error views), wrap each state in a `data-ohw-state-view` and mark the container with `data-ohw-editable-state`: