# Fastlane shop SDK

SDK v1

Put "add to cart" on your own product pages and let our checkout take over
from there. Your blocks, your copy, your layout; our quantity control, our
cart button, our basket and our checkout, in your shop's own theme, or in
your site's own look with nothing but CSS.

**A whole site, no JavaScript.** One script tag, a few HTML attributes on your
own markup and your own CSS give you a header count, "add" buttons on your
product pages, a basket drawer, a bottom bar and the full shop in your style.
A Lago-style example is at the end, and running at
`https://<embed-host>/v1/sdk/lago/`.

This file is the whole reference, at `https://<embed-host>/v1/sdk.md`. In
production `<embed-host>` is `embed-shop.fastlane.events`; it is written as a
placeholder so the snippets stay right when you read this from staging. The
`/v1/` is the major version: within it changes are compatible, and a breaking
change would be `/v2/`. The developer page a shop shares from our backoffice
shows the same reference, filled in with that shop.

## Get started

### The script tag

Once per page:

```html
<script src="https://<embed-host>/v1/sdk.js"
        data-shop="<shop-slug>" data-event="<event-slug>"></script>
```

A classic script, never `type="module"`. There is no key: the shop slug says
which shop.

| attribute | |
|---|---|
| `data-shop` | your shop's slug (required) |
| `data-event` | the event to sell |
| `data-theme` | `theme` (default), `light`, `dark`, `auto`, or a JSON theme, as on `<fl-shop>` |
| `data-language` | `nl`, `en` or `de`; absent, the visitor's own choice, then their browser |
| `data-demo` | the bundled demo catalog: the controls draw, nothing is reserved |

Then put a buy control on your product (`<fl-qty>` or your own button with
`data-fl-add`) and the basket somewhere in your layout (`<fl-cart>` and a way
to open it). Product ids come from `fl.catalog()`, or from the backoffice.

### The npm package

The script tag sets `window.Fastlane`. `@fastlane/shop` is a typed loader for
the same script and resolves to the same object:

```js
import { loadFastlane } from "@fastlane/shop";

const fl = await loadFastlane({ shop: "<shop-slug>", event: "<event-slug>" });
```

### Testing

`data-demo` (or `demo: true`) draws the elements on our demo catalog without
reserving anything. A test shop with test payments is planned.

## Elements

Every element renders into its own shadow root: your CSS reaches it only
through the custom properties and parts under Styling. Each takes
`theme="…"` to override the page's theme for that element.

### `<fl-qty>`

```html
<!-- in your product block, next to your own copy and price -->
<fl-qty product="<product-id>"></fl-qty>
```

Our stepper on its own small card. `+` is "add to cart": each press reserves
the ticket. Sold out, not for sale or not on sale yet, it shows why in the
same box, so your layout never jumps. It sells products by count; a product
sold per time slot or by amount is chosen in our shop. Reserve a lane at
least 128px wide and 46px tall for it.

| attribute | |
|---|---|
| `product` | the product id (required) |
| `theme` | this element's theme |

### `<fl-cart-button>`

```html
<fl-cart-button></fl-cart-button>                <!-- floats in the bottom-left corner -->
<fl-cart-button inline></fl-cart-button>         <!-- in place, in your own header -->
<fl-cart-button variant="bar"></fl-cart-button>  <!-- the bottom bar -->
```

Our launcher pill: "Tickets" while the cart is empty, "Afrekenen · 3" once it
is not. A click opens the basket when the page has a `<fl-cart>`, and our
checkout otherwise.

Floating, it sits 16px from the corner (8px on a phone). **On phones, keep
72px free at the bottom of your page** so it never covers your own content.

`variant="bar"` is the bottom bar: "Je mandje · 2 items" with the total, and
**Afrekenen**. A full-width band on a phone, a 468px card centred at the
bottom on a desktop. Hidden while the basket is empty. Its left half opens the
basket.

| attribute | |
|---|---|
| `inline` | draw the pill where the element is, not in the corner |
| `variant` | `bar`: the bottom bar instead of the pill |
| `theme` | this element's theme |

### `<fl-cart>`

```html
<fl-cart></fl-cart>                      <!-- once, anywhere in your layout -->
<fl-cart variant="panel"></fl-cart>      <!-- or: in our popup panel's box -->
```

The basket, "Je mandje": a line per product with its photo, section and our
`−` / `+`, a bundle's contents, the total including service fees,
**Afrekenen** (our checkout on this cart) and **Verder winkelen**. By default
it is a sheet at the right edge; `variant="panel"` opens it in our popup
panel's box, in the corner of the cart button. On a phone it is the whole
screen. Escape, the ✕ and a click beside it close it.

With `<fl-cart>` on the page, `<fl-cart-button>`, `data-fl-cart-open` and the
bottom bar open the basket instead of going straight to checkout.

| attribute | |
|---|---|
| `variant` | `panel`: our popup panel's box instead of the edge sheet |
| `theme` | this element's theme |

### `<fl-shop>`

```html
<script type="module" src="https://<embed-host>/v1/inline.js"></script>

<fl-shop shop="<shop-slug>" event="<event-slug>"></fl-shop>
```

The full shop, in place (the Inline Embed). On the same page as `sdk.js` it
shares the cart: a ticket picked in the shop shows in your header count, and
an "In mandje" on your own button shows in the shop. Its options (`shop`,
`event`, `theme`, `language`, `demo`) are in `https://<embed-host>/llms.txt`.

## Your markup

Put these attributes on any element of your own. We do the clicking and keep
the state on the element as classes, so your CSS draws it. Markup that
arrives later (a CMS block, a client-side route) works without telling us.

```html
<button data-fl-add="<product-id>">
  In mandje <span data-fl-add-state></span>
</button>

<a href="/tickets" data-fl-cart-open>Tickets <span data-fl-count></span></a>
```

### `data-fl-add`

`data-fl-add="<product-id>"`: a click adds 1 (it reserves). A bundle (a tent
with two weekend tickets) works the same.

The classes a `data-fl-add` element gets:

| class | when |
|---|---|
| `is-added` | the basket holds this product |
| `is-busy` | a press is being reserved (also `aria-busy="true"`) |
| `is-sold-out` | none left; a click does nothing (also `aria-disabled="true"`) |
| `is-unavailable` | not for sale now: closed, not on sale yet, or chosen in our shop (a time slot, an amount); a click does nothing |

`data-fl-add-state` inside a `data-fl-add` element says "1 in je mandje"
while the basket holds the product, and is empty and `hidden` otherwise.
Beside the button instead, name the product:

```html
<span data-fl-add-state="<product-id>"></span>
```

A refused add is `cart:error`, as for `<fl-qty>`: we never show a message on
your page.

### `data-fl-count`

The basket's count as the element's text; `hidden` while the basket is empty.

```css
.count[hidden] { display: none; }
```

### `data-fl-cart-open`

A click opens the basket (`<fl-cart>`), or our checkout when the page has no
basket. A link with it does not navigate.

## Styling

Unset, everything looks exactly as it does today (Inter, our radii, the
shop's theme). Your values win over the shop's theme on your page, and only
there.

### Custom properties `--fl-*`

Set them on the elements (they inherit into our shadow root), or on `:root`
to style everything:

```css
fl-shop, fl-cart, fl-qty, fl-cart-button {
  --fl-font: "PP Neue Montreal", sans-serif;   /* body text */
  --fl-font-display: Voyage, serif;             /* headings */
  --fl-font-display-weight: 400;                /* a display face often has one weight */
  --fl-radius: 0;                               /* boxes: 0 is square */
  --fl-radius-control: 0;                       /* buttons, steppers, chips, inputs */
  --fl-primary: #720000;
  --fl-primary-foreground: #ffe2e1;
}
```

Load your fonts with your own `@font-face` on your page.

| property | what it styles | default |
|---|---|---|
| `--fl-font` | all text | Inter |
| `--fl-font-display` | headings | `--fl-font` |
| `--fl-font-display-weight` | heading weight | 600 |
| `--fl-radius` | cards and boxes; the scale is ⅔ / 1 / 1⅔ of it | 12px (8 / 12 / 20) |
| `--fl-radius-control` | buttons, steppers, chips, inputs, the cart button | pill (inputs: `--fl-radius`) |
| `--fl-foreground` | text on your page's ground | the shop's theme |
| `--fl-card`, `--fl-card-foreground`, `--fl-card-muted-foreground`, `--fl-card-border` | every card, row and panel, and its text | the shop's theme |
| `--fl-card-backdrop` | the blur behind a card (`none` for flat) | the shop's theme |
| `--fl-primary`, `--fl-primary-foreground`, `--fl-primary-border` | the one button to press (Afrekenen, Verder) | the shop's theme |
| `--fl-secondary`, `--fl-secondary-foreground`, `--fl-secondary-border` | the second button | the shop's theme |
| `--fl-control`, `--fl-control-foreground`, `--fl-control-border`, `--fl-control-selected`, `--fl-control-selected-foreground` | what you pick: stepper discs, chips, selects | the shop's theme |
| `--fl-input-background`, `--fl-input-foreground`, `--fl-input-muted-foreground`, `--fl-input-border`, `--fl-input-focus` | the fields you type in | the shop's theme |
| `--fl-overlay` | the dim behind the basket and our panels | the shop's theme |
| `--fl-destructive`, `--fl-destructive-foreground` | errors | the shop's theme |
| `--fl-success`, `--fl-success-foreground` | done | the shop's theme |
| `--fl-warning`, `--fl-warning-foreground` | needs you | the shop's theme |

**Our checkout takes them too.** When it opens over your page it uses the
values set on your `<fl-cart>` (or `<fl-cart-button>`, `<fl-shop>`, `<fl-qty>`,
then `:root`) and the `@font-face` rules of the fonts they name. A font file
must allow our origin (CORS); otherwise our checkout uses Inter.

### Parts `::part()`

For what a variable cannot say:

```css
fl-shop::part(cta) { text-transform: uppercase; }
fl-cart::part(cart-line) { border-bottom: 1px solid #720000; }
```

| part | element |
|---|---|
| `cta` | the one button to press (Verder, Afrekenen) |
| `section` | a section card of the shop |
| `product-row` | a product's row |
| `product-title` | a product's name |
| `price` | a product's price |
| `stepper` | the `−` count `+` |
| `step-bar` | the shop's step bar |
| `input` | a field you type in |
| `drawer` | the basket's box |
| `cart-line` | a line in the basket |
| `cart-button` | the cart button's pill |
| `cart-bar` | the bottom bar |

## JavaScript

You need none of this for the elements and attributes above. It is there for
a site that builds its own product pages or listens to the cart.

### `fl.catalog()`

The event's sections and products in the order our shop shows them, from the
call the SDK already makes. The shape is versioned (`version: 1`) and only
grows; build your own product pages from it.

```js
const fl = window.Fastlane;
const { version, event, sections } = await fl.catalog();
// event: { id, slug, name, startDate, endDate }
// sections: [{ id, name, description, page, products: [
//   { id, name, description, photo, price: { amountMinor, currency },
//     fees: [{ name, amountMinor }], maxPerOrder, status, addable,
//     bundle?: { items: [{ id, name, quantity }] } } ] }]
```

| field | |
|---|---|
| `id` | the id `<fl-qty product>`, `data-fl-add` and `fl.cart.*` take |
| `photo` | the product's own photo URL, or `null` |
| `price` | one unit, before fees, in cents |
| `fees` | the fees on one unit; `price` plus these is what one unit costs |
| `maxPerOrder` | the most one order may hold |
| `status` | `available`, `soldOut`, `notYetOnSale` or `unavailable` |
| `addable` | whether a count on your page can buy it (`false`: a time slot or an amount, chosen in our shop) |
| `bundle` | a bundle's contents; absent on anything else |
| `page` | the shop page (step) the section is on |

To list every product id of the event in the browser console:

```js
(await Fastlane.catalog()).sections.flatMap((s) => s.products.map((p) => [p.id, p.name]));
```

### Cart and checkout

```js
await fl.cart.add("<product-id>", 2);     // reserves; rejects with { code }
await fl.cart.remove("<product-id>");     // one back
await fl.cart.set("<product-id>", 0);     // exactly this many
fl.cart.get();                            // { cartId, count, total, lines }
fl.checkout.open();                       // our checkout, on this cart
await fl.ready;                           // resolves once the products are known
```

`checkout.open()` opens our checkout over your page on the cart you built. It
starts at the visitor's details (or at the extras first, when the event has
them); "Wijzigen" goes back to our catalog with the same cart. Closing it
keeps the cart. Payment happens with us and comes back to your page.

With nothing in the cart yet, it opens our catalog, still on your page's
cart, so whatever is picked there shows on your page when it closes.

A cart is held for 5 minutes and every change restarts that. Your page never
shows a clock; `checkout.open()` asks for an expired hold back first.
`total.amountMinor` is in cents, service fees included.

An Inline Embed (`<fl-shop>`) on the same page uses the same cart, and keeps
in step with it while the page is open.

### Events and errors

```js
fl.on("cart:updated", ({ count, total, lines }) => { badge.textContent = count; });
fl.on("cart:error", ({ code, productId }) => { /* SoldOut, MaxPerOrder, … */ });
fl.on("cart:expired", (cart) => { /* the 5-minute hold ran out */ });
fl.on("purchase", ({ orderId, value, currency, items }) => { /* paid */ });
window.addEventListener("fastlane:ready", (e) => { /* e.detail is window.Fastlane */ });
```

`on` returns a function that removes the listener; `off` does the same.

| `cart:error` code | means |
|---|---|
| `SoldOut` | none left; the control shows "Uitverkocht" |
| `MaxPerOrder` | past the most one order may hold |
| `Unavailable` | not for sale now, or chosen in our shop (time slot, amount) |
| `UnknownProduct` | no such product on this event |
| `Offline` | no answer at all |
| `Failed` | anything else; the cart is unchanged |

We never show a message on your page: the count goes back by itself, and
`cart:error` is how you hear about it. `purchase` is the same detail as the
embeds' `fl-shop:purchase`.

## Examples

### Lago-style site

A festival site in its own look (square boxes, its own fonts, its own
colours) with a header count, "In mandje" on a product page, the basket, the
bottom bar and the full shop. No JavaScript of its own. It runs at
`https://<embed-host>/v1/sdk/lago/`.

```html
<head>
  <style>
    @font-face { font-family: "PP Neue Montreal"; src: url("/fonts/PPNeueMontreal-Light.woff2") format("woff2"); font-weight: 300; }
    @font-face { font-family: Voyage; src: url("/fonts/Voyage-Regular.woff2") format("woff2"); }

    fl-shop, fl-cart, fl-qty, fl-cart-button {
      --fl-font: "PP Neue Montreal", sans-serif;
      --fl-font-display: Voyage, serif;
      --fl-font-display-weight: 400;
      --fl-radius: 0;
      --fl-radius-control: 0;
      --fl-card: rgb(255 226 225 / 0.72);
      --fl-card-foreground: #720000;
      --fl-card-muted-foreground: #8f3b3b;
      --fl-card-border: #e3a9a7;
      --fl-card-backdrop: none;
      --fl-primary: #720000;
      --fl-primary-foreground: #ffe2e1;
      --fl-control: #ffe2e1;
      --fl-control-foreground: #720000;
      --fl-control-border: #720000;
    }
    fl-shop::part(cta), fl-cart::part(cta) { text-transform: uppercase; }

    .add.is-busy { opacity: 0.6; }
    .add.is-sold-out { opacity: 0.4; }
    .count[hidden] { display: none; }
  </style>
  <script src="https://<embed-host>/v1/sdk.js" data-shop="<shop-slug>" data-event="<event-slug>"></script>
  <script type="module" src="https://<embed-host>/v1/inline.js"></script>
</head>
<body>
  <header>
    <a href="#" data-fl-cart-open>Mandje <span class="count" data-fl-count></span></a>
  </header>

  <!-- a product page -->
  <button class="add" data-fl-add="<tent-bundle-id>">In mandje</button>
  <span data-fl-add-state="<tent-bundle-id>"></span>

  <!-- the tickets page -->
  <fl-shop shop="<shop-slug>" event="<event-slug>"></fl-shop>

  <!-- once, in the layout -->
  <fl-cart></fl-cart>
  <fl-cart-button variant="bar"></fl-cart-button>
</body>
```
