The search island
View .mdSet the stay’s dates and guests once. The search-island contract is the
floating island custom sites share with the Elements ActionBar: it collapses
into an Add dates · 2 guests pill on a phone, docks as a bar on a desktop,
reads and writes the page’s one stay store (mirrored in
the canonical stay URL), and once dated it re-runs
availability for whatever page it is on.
For the shared field, popover, counter, and draft-value rules used by a full search bar, see Stay search-bar conventions.
Take it, restyle it
Section titled “Take it, restyle it”The behavior ships as one headless hook from @kismet-tech/sdk/react. You
render everything — pill, fields, sheet, bar — and the hook reads and writes
the one stay store and gives you the summary line and the scoped availability
request:
'use client';import { useSearchIsland } from '@kismet-tech/sdk/react';
function GroupIsland({ groupSlug }: { groupSlug: string }) { const island = useSearchIsland({ scope: { kind: 'group', groupSlug }, });
if (!island.isEditorOpen) { return ( <button data-kismet-island-pill aria-expanded="false" onClick={island.openEditor}> {island.summaryLabel} </button> ); } return ( <form data-island-editor onSubmit={(event) => event.preventDefault()}> <label htmlFor="check-in">Check-in</label> <input id="check-in" type="date" onChange={(event) => island.applyStaySettings({ checkIn: event.target.value || undefined })} /> {/* check-out and guests likewise */} </form> );}summaryLabelis the collapsed line —Add dates · 2 guestsundated,12–15 Oct · 4 guestsdated — produced byformatStaySelectionSummary, so every site reads the same.applyStaySettings({ checkIn, checkOut, guests })writes the canonical stay URL throughuseStayQuery. Dates travel as a pair; a reload, a shared link, or the move to a property page keeps them.availabilityRequestisundefinedwhile undated, then{ checkIn, checkOut, guests, group? }— the exact options forvacationRental.availability.get. Thegroupkey is present only when the scope is a group, so a group page re-runs availability for that group and a results page re-runs it for the current set.
Pass the scope the page is on:
| Page | Scope | Availability request |
|---|---|---|
| Group landing | { kind: 'group', groupSlug } |
carries group: groupSlug |
| Results | { kind: 'results' } |
no group key |
What changes once dates are set
Section titled “What changes once dates are set”When the stay is dated, cards show the before-tax stay total from
vacationRental.availability.get — totalBeforeTaxMinor per vacation
rental — never a final quote. Confirmed-unavailable vacation rentals are
marked (Not available for your dates) or sink to the bottom of the list
through sortVacationRentals; a rental whose
availability is unknown stays in place and is never treated as
unavailable. Those rendered-results rules are owned by the
browse channel, property-card, and results-page
contracts — the island contract governs where the stay lives, not how
results react.
The contract
Section titled “The contract”search-island@1 builds on the stay-query contract. State ownership is
the MUST, enforced statically on every site that runs
kismet recipes check — both starters do — and on rendered pages by the
two must-severity criteria of the search-island recipe scenario:
| Requirement | Level | Check |
|---|---|---|
| Stay settings live in the canonical stay URL (static) | MUST | recipes/stay-query-source |
| Never hold the stay dates or guest count in local component state | MUST NOT | recipes/search-island-source |
| Applied settings reach the canonical URL (rendered) | MUST | conformance/search-island-stay-url |
| Stay survives a reload (rendered) | MUST | conformance/search-island-persistence |
| Collapsed summary pill reflects the observed stay | SHOULD | conformance/search-island-pill |
| Fields labelled and keyboard-enterable | SHOULD | conformance/search-island-fields |
| Availability rebinds to the active scope | SHOULD | conformance/search-island-scope |
| Every date surface shows one stay: dates picked in the quick-view calendar reach the island, the URL and the availability request | MUST | conformance/search-island-stay-store-sync |
| A lone check-in stays in its calendar until check-out | MUST | conformance/search-island-lone-check-in |
| Every stay calendar opens on the selected check-in’s month | MUST | conformance/search-island-calendar-first-month |
The recipe scenario grades a page that declares search-island: the runner
fills the canonical stay form with the keyboard, reads the URL keys the
page writes, reloads, and correlates the availability requests in that
window. The pill SHOULD is scoped to pages that render the optional
data-kismet-island-pill hook. A MUST miss fails the site; a SHOULD miss
warns and never blocks a declaration.
The one-stay-store criteria then open the quick-view sheet from the first
visible data-kismet-open join. The sheet calendar must mark the island’s
nights with data-kismet-calendar-night-selected="true". When its
data-kismet-calendar-night cells are buttons, the runner clicks a check-in
night (the URL must not change yet), then a check-out night, and checks that
the island fields and pill, the URL and a new availability request all carry
the picked stay. A page with no open join, or a display-only sheet calendar,
is scoped out with a detail line.
The calendar-first-month criterion then applies a stay two or more months out
and checks that the sheet calendar’s first visible month is the check-in’s
month — that month carries a data-kismet-calendar-night-selected="true"
night on screen when the calendar opens. A calendar that opens on today’s
month with the stay months ahead hides the dates the guest already picked, so
it fails. Pages whose calendar never opens, or where the probe cannot apply
its stay, scope out with a detail line. The shared answer is
stayCalendarFirstMonth({ checkIn }) from @kismet-tech/sdk/react: the
check-in’s month, today’s month when the stay is undated, and never a month
before today.
Placement is free space: dock the bar, float the pill, restyle the sheet.