airport-one-widgets 0.2.95 → 0.2.97

package/README.md

@@ -5,6 +5,35 @@
 
 **Fly My Airport FAB local demos:** with the widgets dev server running, open [`/demo/fly-my-airport-fab.html`](http://localhost:3001/demo/fly-my-airport-fab.html) (see root [`index.html`](./index.html) for the full demo menu).
 
+**Demo site:** `npm run build:demo` builds the demo pages into `demo-dist/` as a static site against the dev APIs (`https://dev-api.airportonellc.com`), so instance embeds load instances saved in the dev portal. [`vercel.json`](./vercel.json) deploys it: create a Vercel project with root directory `apps/airport-one-widgets` and set `FONTAWESOME_NPM_AUTH_TOKEN` and `VITE_FMA_API_DOMAIN` (the dev FMA site); `VITE_WIDGET_PUBLIC_CONFIG_API_BASE_URL` and `VITE_FIDS_WIDGET_API_BASE_URL` override the dev API. Open the airfare search demo with `?instance=<id>` to show a dev-portal instance; the site's domain must be in that airport's allowed embed domains.
+
+## Releases and channels
+
+Airports load the bundle through `widgets.flymyairport.com`, which serves one
+of two npm dist-tags ([ADR 0017](../../docs/decisions/0017-widget-release-channels.md)):
+
+- **`latest`**: every airport.
+- **`next`**: the pilot airports chosen in the portal under Platform Settings →
+  Release Management → Widget Releases, plus portal previews when that page
+  says so.
+
+A merge that changes this package bumps `version` in `package.json` and
+publishes through `CI | npm-widget | Publish`. The `WIDGET_NPM_DIST_TAG`
+repository variable picks the channel: unset or `latest` reaches everyone,
+`next` reaches only the pilot.
+
+To pilot a release:
+
+1. Set `WIDGET_NPM_DIST_TAG` to `next`, then merge the version bump.
+2. Choose the pilot airports in the portal and save.
+3. When it looks right, run `CI | npm-widget | Promote` with that version and
+   channel `latest`.
+4. Clear the pilot list, and set `WIDGET_NPM_DIST_TAG` back to `latest` unless
+   another pilot is coming.
+
+To roll back, run `CI | npm-widget | Promote` with the previous version and
+channel `latest`. CDN caches take a few minutes to pick up either change.
+
 ## Airfare Search (v2)
 
 The v2 airfare-search widget is an explicit opt-in contract and does not alias from
@@ -29,10 +58,43 @@ Required for managed instances:
 - `data-widget-instance-id`
 
 `origin` and `destination` are resolved per field: a host attribute overrides the saved
-instance config for that field only, and whichever value survives renders as a locked
-(read-only) input. Adding a `destination` attribute to an instance whose config sets an
-origin leaves that origin locked; the origin field only stays editable when no layer
-supplies one.
+instance config for that field only. The card is about one airport, named in its header
+with a Fly Out / Fly In toggle: the `origin` when set (a `destination` alongside it renders
+as a locked field), otherwise a lone `destination` (the card opens on Fly In), otherwise
+the subscribing airport.
+
+### Design and behavior (FMA Search 2.0, AIR-1722)
+
+- **Destination**: empty, it lists every nonstop from the airport's published schedule
+  (`GET /v1/iata-auto-complete` on widget-api). Typing matches city, airport code, state
+  and country, nonstops first, then "search everywhere" KAYAK places with their nearby
+  airports. `autocomplete-type="schedule_data"` and airline-restricted embeds keep typed
+  results to the airport's own network.
+- **Dates**: one field and a two-month calendar (one on narrow cards). With a destination
+  chosen, each day carries a nonstop bar or a one-stop bar with a dot, per day from
+  `GET /v1/route-calendar-month`, and months without the nonstop say so. The calendar stays
+  open with the range on wide cards and closes after the last date on narrow ones.
+- **Trip type**, **travelers** (one count, 1–9, booked as adults) and **cabin** are menus above
+  the fields, as on the earlier widget; the Search button turns the accent color once the
+  form is complete and validates inline otherwise.
+- **Search** opens the redirect worker link, which attributes the click-out and builds the
+  KAYAK results URL (cabin, travelers, nearby dates).
+  **Car** links FlyMyAirport's car rental page for the airport in a new tab, as the earlier
+  widget did.
+
+| Attribute         | Default                                       | Description                                                                                                                                           |
+| ----------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `skin`            | `site` when `theme="dark"`, otherwise `light` | `site` (flymyairport.com dark glass), `light` (white card), `dark`, `brand` (tinted by `primary-color`), `none` (no card; the host supplies contrast) |
+| `labels`          | `inside`                                      | `outside` renders a visible label above each field for airports that need them                                                                        |
+| `market-name`     | `{City} ({IATA})`                             | The airport's display name in the header (AIR-1585)                                                                                                   |
+| `primary-color`   | `#0745A2`                                     | Calendar route bar, destination tiles                                                                                                                 |
+| `secondary-color` | `#FC6322`                                     | One-stop dot, nonstop dots and badge, Search once complete, focus ring                                                                                |
+| `hide-branding`   | `false`                                       | Hides the FlyMyAirport wordmark and Powered by KAYAK                                                                                                  |
+| `hide-fma-logo`   | `false`                                       | Hides only the FlyMyAirport wordmark; Powered by KAYAK stays. In the portal only Airport One administrators can set it                                |
+| `hide-car-button` | `false`                                       | Hides the Flights / Car links                                                                                                                         |
+
+Styling hooks: the `airfare-search-card` and `airfare-search-button` parts, and an
+`--afs-font-family` custom property (the card otherwise inherits the host page's font).
 
 ## Airfare Content