md / trips / fh / fh-widget-editor-plan.md
Molino⺢Pro

fh-widget-editor-plan

Master Codebase Guidebook
Markdown + HTML Dev-Docs Renderer - Frontend Client Module

Default Index
Open README.md
Root: README.mdfh
Milestones
⬆ Parent folder📝 fh-docs.skill📝 fh-widget-editor-plan📝 html-booking-pages-simple📝 link-audit📝 README
H1FareHarbor Widget Editor Plan

Status: draft plan before implementation.

H2Goal

Build a reusable Trip/FareHarbor component that lets me:

  • keep the current working test page intact,
  • preview or paste FareHarbor widgets in edit mode,
  • render the widget cleanly in view mode,
  • reuse the same pattern across booking sections or cards,
  • avoid hydration problems with FareHarbor embeds.
H2Known working result

The current proof of concept shows:

  • the Lightframe button works in the Next.js app route,
  • direct React rendering is not reliable for calendar/grid widgets,
  • a parsed HTML island or isolated HTML shell is the stable way to render FareHarbor widgets.
H2Options to evaluate
H3Option A: Generic editor component with paste-in HTML

Use a component with an editor textarea or content field where I paste FareHarbor widget HTML.

Pros:

  • simplest authoring experience,
  • easy to inspect and update,
  • can support buttons, calendars, grids, and custom widget snippets.

Risks:

  • raw HTML editing can be messy,
  • needs sanitizing or strict isolation,
  • direct rendering in React may reintroduce hydration issues.

Best use:

  • internal admin/edit mode,
  • quick widget testing,
  • page-specific booking cards.
H3Option B: JSON-driven widget registry

Store widget snippets in JSON and select them from a chooser.

Pros:

  • structured,
  • easy to reuse,
  • can map labels to widget types, item ids, and flow ids.

Risks:

  • less flexible for one-off snippets,
  • more setup before it becomes useful,
  • still needs a safe rendering container.

Best use:

  • repeatable booking sections,
  • curated widgets for items/flows,
  • long-term maintainable configuration.
H3Option C: Hollow iframe component

Make a generic iframe shell and inject FareHarbor widget HTML into it.

Pros:

  • safest for FareHarbor rendering,
  • avoids React hydration issues,
  • matches the behavior that already works.

Risks:

  • editing experience is less direct unless paired with an editor,
  • iframe content is harder to inspect from the outer page,
  • may need a preview/edit toggle and persistence layer.

Best use:

  • production-safe widget rendering,
  • reusable booking cards,
  • any widget that must behave exactly like the static HTML test.
H2Recommended direction

Start with a hybrid:

  1. Use a generic editor panel for authoring.
  2. Store widget definitions in JSON or local draft state.
  3. Render the final widget inside a hollow iframe.

This gives:

  • edit mode for pasting or selecting widgets,
  • view mode for stable rendering,
  • a clean path to reuse the component across booking sections.
H2Suggested widget model

Each widget entry should store:

  • id
  • label
  • type (button, calendar, grid, custom)
  • shortname
  • flowId
  • itemId
  • html
  • description
  • enabled
H2Suggested UX
H3Edit mode
  • textarea or code editor for widget HTML,
  • dropdown for widget type,
  • optional selectors for item or flow ids,
  • save/update button,
  • preview toggle.
H3View mode
  • render the widget inside an iframe,
  • show a compact label and meta chips above it,
  • keep the outer booking card clean and reusable.
H2Implementation phases
H3Phase 1: Confirm the container shape
  • Decide whether the source of truth is JSON, local state, or both.
  • Decide whether the editor is inline or in a modal/drawer.
  • Decide whether the iframe content is generated from a template or stored as full HTML.
H3Phase 2: Build the reusable component
  • Create a generic FareHarborWidgetCard or FareHarborWidgetFrame.
  • Add edit/view toggle.
  • Add textarea or widget selector.
  • Preserve the current fh-test page unchanged.
H3Phase 3: Add persistence
  • Start with local JSON or temporary state.
  • Later wire it to the existing data layer if needed.
  • Keep the widget schema small and explicit.
H3Phase 4: Reuse across booking sections
  • Add the component to booking cards.
  • Support one component per item or flow.
  • Keep Lightframe/button widgets separate from calendar/grid widgets if needed.
H2Acceptance criteria
  • Existing test page still works.
  • Calendar and grid widgets render reliably.
  • Edit mode lets me paste or select widgets without breaking the view.
  • View mode is stable and reusable across multiple booking sections.
  • The implementation does not depend on direct React rendering of FareHarbor widgets.
H2Open questions
  • Should the editor accept raw HTML only, or also structured widget fields?
  • Should the data live in JSON first, or in a small database/model later?
  • Should the iframe be full-width per card, or a compact inline preview?
  • Do we want one generic component for all widget types, or separate components for button vs calendar vs grid?
H2Current decision

Use the iframe approach as the rendering primitive, and layer an editor/selector on top of it.

That keeps the current working test stable and gives a practical path to a reusable booking UI.