# Stay search-bar conventions

> Shared interaction rules for stay search bars, fields, counters, popovers, and canonical search values.


Use one interaction model for every stay search bar. Each selection field opens
a popover from the field: dates, guests, bedrooms, destination or group,
accommodation type, and pets. Do not replace a field with a native `select` or
a bare checkbox.

## Shared rules

1. Every selection opens a popover from its field. The popover is the same
   pattern on desktop and phone; keep the field value on one line on a phone.
2. There is no **Done** button. Clicking outside the open field and its popover,
   or pressing Escape, closes it. A click inside the popover, such as a counter
   button, keeps it open. Choosing an option in a choice popover closes it. The
   dates popover has **Clear dates** only.

   A search action is the only submit action in the bar; closing a popover must
   never require a second confirmation button.
3. Counts use minus and plus controls. Guests is a number. Bedrooms shows
   `Any` at zero and `N+` for a minimum greater than zero.
4. Hide a field when it has no real choices. For example, hide an
   accommodation-type field when its only value is `All types`; do not show a
   popover with one choice.
5. Keep edits as a draft until **Search**. On submit, write through the one
   stay store and the canonical stay keys using [`useStayQuery`](https://developers.kismet.travel/sdk/stay-query.md)
   and `stayQueryToSearchParams`. Without JavaScript, the form still submits
   those same keys as named inputs.
6. Share one field layout and popover style across the bar. On narrow screens,
   values stay on one line and the popover remains usable without horizontal
   scrolling.

## Counter popover

Counters stay open while the user adjusts a value. The display is derived from
the draft, and the canonical stay store is updated only by the form submit.

```tsx
<FieldPopover label="Guests" value={`${draft.guests} guests`}>
  <Counter
    label="Guests"
    value={draft.guests}
    min={1}
    onChange={(guests) => setDraft({ ...draft, guests })}
  />
</FieldPopover>
```

## Choice popover

Choice fields close after a selection. Omit the whole field when there is no
choice beyond its no-filter value.

```tsx
{types.length > 1 && (
  <FieldPopover label="Type" value={draft.type ?? 'Any type'}>
    {types.map((type) => (
      <button
        type="button"
        key={type.value}
        onClick={() => {
          setDraft({ ...draft, type: type.value });
          closePopover();
        }}
      >
        {type.label}
      </button>
    ))}
  </FieldPopover>
)}
```

The [stay-search-form](https://developers.kismet.travel/sdk/recipes.md) and [stay-search-bar](https://developers.kismet.travel/sdk/recipes.md)
recipes use these conventions. The [canonical stay URL](https://developers.kismet.travel/sdk/stay-query.md)
page explains the shared store and parameter contract.
