Skip to main content

Recipe: Garage sale

A sale page over one board: each item with its photo, a price tag, and a Reserve button. A visitor gives their name and email the first time they reserve, with no Playbook account, holds up to three items, and can cancel. Of two visitors reserving one item at once, exactly one gets it. The buyer's name and email go into members-only fields: the seller sees them in Playbook, and no visitor, the app included, ever reads them. Light and dark themes follow the visitor's system, with a toggle.

When to use it​

  • Anyone with the link claims something: a garage or moving sale, free stuff to give away, sign-up slots, spare tickets. Access is public and sign-up is open.
  • The same shape fits any "first one gets it" list. For a closed group, deploy with password.
  • Open sign-up has no captcha: someone determined can sign up many times. active_per_guest limits what one sign-up holds, not one person.

How the board drives it​

Create the fields once, before the first deploy (Playbook checks every field and option the actions name, and refuses the deploy with the reason). Fields belong to the whole workspace: check list_custom_fields first, because create_custom_field on a select that already exists replaces its options and clears the missing ones from every asset. If a name is taken by another use, pick another and change it in app.js and playbook.json.

  • Sale, a select with the options Available, Reserved and Sold. An item with no value counts as available.
  • Price, a text field: the tag on the photo (€40, Free, €60 for the box).
  • Buyer, Buyer email and Buyer note, text fields made with create_custom_field and members_only: true. A guest's email may only go into a members-only field: deploying an action that writes it anywhere else is refused.

Text fields are not yet in every workspace. Where create_custom_field refuses field_type: "text", put the price in the item's description, drop input from reserve and the buyer fields from release, and ask for no email at sign-up. The seller then knows who signed up and how many items each holds (the Guests panel), but not who holds which: keep such a sale to people who come to the door.

  • An item's title and description are its name and details. The board's title and description are the page's heading and introduction.
  • reserve runs only while Sale is Available or empty, sets it to Reserved, and writes the guest's name and email into the buyer fields. release undoes it: only the guest who reserved may run it, and only while nobody has changed the item since.

For the seller​

There is no confirm step: a reservation holds at once. With notify: true, the app's creator gets an email when items are reserved, at most every 10 minutes, with guest names but no contacts.

  1. In Playbook, filter the board by Sale = Reserved. Each item shows Buyer and Buyer email.
  2. Write to the buyer to arrange the pick-up. The page tells them to expect it.
  3. When it's sold, set Sale to Sold. The guest can no longer cancel, and the page shows it as sold.
  4. To turn a reservation down, set Sale back to Available and clear the buyer fields.

Developer → Custom apps → Guests lists everyone who signed up, with their email; Remove with "Also withdraw their answers and take back their changes" frees every item they still hold.

The files​

playbook.json:

{
"guests": { "signup": "open" },
"guest_actions": {
"reserve": {
"label": "Reserve",
"when": { "Sale": ["Available", null] },
"set": { "Sale": "Reserved" },
"input": { "name": "Buyer", "email": "Buyer email", "note?": "Buyer note" },
"limit": { "active_per_guest": 3 },
"notify": true
},
"release": {
"label": "Cancel my reservation",
"undoes": "reserve",
"set": { "Sale": "Available", "Buyer": "", "Buyer email": "", "Buyer note": "" }
}
}
}

index.html:

<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Sale</title>
<script>
// The visitor's theme, set before the page paints.
try { const theme = localStorage.getItem(`theme:${location.pathname}`); if (theme) document.documentElement.dataset.theme = theme } catch {}
</script>
<link rel="icon" href="data:," />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo:wdth,[email protected],400;62..125,600;62..125,800&display=swap" />
<link rel="stylesheet" href="styles.css" />
</head>
<body>
<header class="top">
<p class="who" id="who"></p>
<button type="button" class="theme" id="theme" aria-label="Switch between light and dark"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="8" fill="none" stroke="currentColor" stroke-width="1.8" /><path d="M12 4a8 8 0 0 1 0 16z" fill="currentColor" /></svg></button>
</header>

<section class="hero">
<h1 id="title">Loading…</h1>
<p class="subtitle" id="subtitle"></p>
<nav class="filters" id="filters" aria-label="Show"></nav>
</section>

<main class="items" id="items" aria-live="polite"></main>
<p class="notice" id="notice" hidden>The sale did not load. Reload the page to try again.</p>

<dialog class="sheet" id="signup">
<form method="dialog" id="signup-form">
<h2>Reserve it</h2>
<p>The seller gets your name and email to arrange the pick-up. Nobody else sees them.</p>
<label for="signup-name">Your name</label>
<input id="signup-name" maxlength="80" autocomplete="name" required />
<label for="signup-email">Email</label>
<input id="signup-email" type="email" autocomplete="email" required />
<p class="error" id="signup-error" role="alert"></p>
<div class="sheet-actions">
<button type="button" class="ghost" id="signup-cancel">Cancel</button>
<button type="submit" class="solid" id="signup-send">Continue</button>
</div>
</form>
</dialog>

<p class="toast" id="toast" role="status" hidden></p>

<script type="module" src="app.js"></script>
</body>
</html>

styles.css:

/* Light by default, dark when the system asks for it, and either one when the
visitor picks it (data-theme on <html>, set by the toggle). */
:root {
color-scheme: light;
--bg: #ffffff;
--ink: #141414;
--soft: #4b4b4b;
--muted: #7a7a7a;
--line: rgba(20, 20, 20, 0.12);
--field: #f4f4f4;
--tag: #ffd84d;
--on-tag: #141414;
--mine: #1f5eff;
--on-mine: #ffffff;
--gone: #8a8a8a;
--error: #c62f22;
--shadow: rgba(20, 20, 20, 0.16);
--focus: rgba(31, 94, 255, 0.55);
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light']) {
color-scheme: dark;
--bg: #111111; --ink: #f2f2f2; --soft: #c4c4c4; --muted: #8f8f8f; --line: rgba(255, 255, 255, 0.12);
--field: #1c1c1c; --tag: #ffd84d; --on-tag: #141414; --mine: #6f97ff; --on-mine: #0b1330; --gone: #7a7a7a;
--error: #ff7d70; --shadow: rgba(0, 0, 0, 0.5); --focus: rgba(111, 151, 255, 0.6);
}
}
:root[data-theme='dark'] {
color-scheme: dark;
--bg: #111111; --ink: #f2f2f2; --soft: #c4c4c4; --muted: #8f8f8f; --line: rgba(255, 255, 255, 0.12);
--field: #1c1c1c; --tag: #ffd84d; --on-tag: #141414; --mine: #6f97ff; --on-mine: #0b1330; --gone: #7a7a7a;
--error: #ff7d70; --shadow: rgba(0, 0, 0, 0.5); --focus: rgba(111, 151, 255, 0.6);
}

* { box-sizing: border-box; }
[hidden] { display: none !important; }
body { margin: 0; min-height: 100vh; background: var(--bg); color: var(--ink); font: 16px/1.45 'Archivo', system-ui, sans-serif; -webkit-font-smoothing: antialiased; }
button, input { font: inherit; color: inherit; }
button { cursor: pointer; }
:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }

.solid, .ghost { min-height: 44px; padding: 0 18px; border-radius: 8px; font-weight: 600; white-space: nowrap; }
.solid { border: 0; background: var(--ink); color: var(--bg); }
.ghost { border: 1px solid var(--line); background: none; }
.solid:disabled, .ghost:disabled { opacity: 0.5; cursor: default; }
.link { padding: 0; border: 0; background: none; color: inherit; text-decoration: underline; text-underline-offset: 3px; }
.theme { display: grid; place-items: center; width: 36px; height: 36px; padding: 0; border: 1px solid var(--line); border-radius: 50%; background: none; color: var(--soft); }
.theme svg { width: 16px; height: 16px; }

.top { display: flex; justify-content: flex-end; align-items: center; gap: 14px; padding: 18px 28px 0; }
.who { margin: 0; color: var(--muted); font-size: 14px; }
.who b { color: var(--ink); font-weight: 600; }

.hero { padding: 40px 28px 24px; }
h1 { margin: 0; font-size: clamp(44px, 9vw, 112px); font-weight: 800; font-stretch: 70%; line-height: 0.9; letter-spacing: -0.02em; text-transform: uppercase; }
.subtitle { max-width: 60ch; margin: 16px 0 0; color: var(--soft); font-size: 18px; white-space: pre-line; }
.subtitle:empty { display: none; }
.filters { display: flex; gap: 6px; margin-top: 24px; overflow-x: auto; scrollbar-width: none; }
.filters button { min-height: 36px; padding: 0 14px; border: 1px solid var(--line); border-radius: 99px; background: none; font-size: 14px; white-space: nowrap; }
.filters button[aria-pressed='true'] { border-color: var(--ink); background: var(--ink); color: var(--bg); }

.items { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 28px 18px; padding: 0 28px 72px; }
.item { display: flex; flex-direction: column; gap: 10px; }
.photo { position: relative; aspect-ratio: 1; overflow: hidden; border-radius: 10px; background: var(--field); }
.photo img { display: block; width: 100%; height: 100%; object-fit: cover; }
.price { position: absolute; top: 10px; left: 10px; padding: 4px 10px 3px; border-radius: 4px; background: var(--tag); color: var(--on-tag); font-weight: 800; font-size: 18px; font-stretch: 80%; transform: rotate(-3deg); box-shadow: 0 2px 6px var(--shadow); }
.state { position: absolute; inset: auto 10px 10px auto; padding: 3px 10px; border-radius: 99px; background: rgba(0, 0, 0, 0.66); color: #fff; font-size: 13px; font-weight: 600; }
.item.is-taken img, .item.is-sold img { filter: grayscale(1); opacity: 0.55; }
.item.is-mine .state { background: var(--mine); color: var(--on-mine); }
.item h2 { margin: 0; font-size: 18px; font-weight: 600; line-height: 1.2; }
.details { margin: 0; color: var(--soft); font-size: 15px; white-space: pre-line; }
.details:empty { display: none; }
.item .solid { margin-top: auto; }
.mine { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 6px; margin: auto 0 0; color: var(--mine); font-size: 14px; font-weight: 600; }
.mine .link { color: var(--muted); font-weight: 400; }
.gone { margin: auto 0 0; color: var(--gone); font-size: 14px; }
.error { margin: 0; color: var(--error); font-size: 14px; }
.error:empty { display: none; }
.empty, .notice { color: var(--muted); }
.notice { padding: 0 28px; }

.sheet { width: min(420px, calc(100% - 32px)); padding: 24px; border: 1px solid var(--line); border-radius: 14px; background: var(--bg); color: var(--ink); box-shadow: 0 30px 80px var(--shadow); }
.sheet::backdrop { background: rgba(0, 0, 0, 0.5); }
.sheet h2 { margin: 0; font-size: 28px; font-weight: 800; font-stretch: 75%; text-transform: uppercase; }
.sheet p { margin: 6px 0 18px; color: var(--soft); }
.sheet label { display: block; margin: 12px 0 6px; font-size: 14px; font-weight: 600; }
.sheet input { width: 100%; min-height: 48px; padding: 0 14px; border: 1px solid var(--line); border-radius: 8px; background: var(--field); outline: none; }
.sheet input:focus { border-color: var(--focus); }
.sheet .error { margin-top: 12px; }
.sheet-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 20px; }

.toast { position: fixed; z-index: 20; bottom: 24px; left: 50%; margin: 0; padding: 10px 18px; transform: translateX(-50%); border-radius: 8px; background: var(--ink); color: var(--bg); font-weight: 600; }

@media (max-width: 640px) {
.top { padding: 14px 16px 0; }
.hero { padding: 24px 16px 20px; }
.filters { margin: 20px -16px 0; padding: 0 16px; }
.items { grid-template-columns: repeat(2, 1fr); gap: 22px 10px; padding: 0 16px 48px; }
.price { font-size: 15px; }
.item h2 { font-size: 16px; }
.details { font-size: 14px; }
}

app.js:

// A sale of things on one board, open to anyone with the link (access `public`).
// A select field holds each item's state. A visitor signs up with their name and
// email and reserves up to three items: the state action `reserve` in
// playbook.json. Their contacts go into members-only fields the page never reads.

const FIELD = 'Sale'
const AVAILABLE = 'Available'
const RESERVED = 'Reserved'
const SOLD = 'Sold'
const PRICE = 'Price'
const ACTION = 'reserve'
const UNDO = 'release'
const MOST = 3 // limit.active_per_guest in playbook.json

const $ = (id) => document.getElementById(id)
const plain = (html) => new DOMParser().parseFromString(html || '', 'text/html').body.textContent.trim()
const el = (tag, className, text) => {
const node = document.createElement(tag)
if (className) node.className = className
if (text) node.textContent = text
return node
}

// Every call goes to the app's own address. Busy or cold reads (429, 5xx) are
// retried twice. A refusal throws its message, with its code and status.
async function call(path, { method = 'GET', body, tries = 3 } = {}) {
const response = await fetch(path, {
method,
headers: body ? { 'Content-Type': 'application/json' } : {},
body: body && JSON.stringify(body),
}).catch(() => null)
const status = response?.status ?? 0
if (method === 'GET' && tries > 1 && (status === 0 || status === 429 || status >= 500)) {
const wait = Number(response?.headers.get('Retry-After')) || 2
await new Promise((resolve) => setTimeout(resolve, wait * 1000))
return call(path, { method, body, tries: tries - 1 })
}
const answer = response ? await response.json().catch(() => ({})) : {}
if (response?.ok) return answer
throw Object.assign(new Error(answer.error || 'That did not go through. Try again.'), { code: answer.code, status })
}

const REFUSALS = {
condition_failed: 'Someone was quicker: it is taken.',
limit_reached: `You can hold ${MOST} items at a time. Cancel one to reserve this.`,
}

let items = []
let me = null // the guest: { name, runs }, or null for a visitor who has not signed up
let filter = 'all'
const mine = new Set() // tokens the guest holds
const errors = {}

// The guest's current reservation is still on the item (a run stops being
// current once anyone changes what it wrote), so it wins over a cached read.
function stateOf(item) {
if (mine.has(item.token)) return 'mine'
const value = item.fields?.[FIELD]
if (value === SOLD) return 'sold'
if (value === RESERVED) return 'taken'
return 'available'
}

function toast(text) {
$('toast').textContent = text
$('toast').hidden = false
clearTimeout(toast.timer)
toast.timer = setTimeout(() => ($('toast').hidden = true), 2400)
}

// `runs` lists the guest's current runs of every action, the undo action's
// included: an item they reserved and released shows a `release` run. Keep the
// runs of `reserve` only.
function setGuest(guest) {
me = guest
mine.clear()
for (const run of guest?.runs || []) if (run.action === ACTION) mine.add(run.asset)
renderWho()
}

function renderWho() {
$('who').replaceChildren()
if (!me) return
const out = el('button', 'link', 'Not you?')
out.type = 'button'
out.addEventListener('click', signOut)
$('who').append(el('b', '', me.name), ` · ${mine.size} of ${MOST} reserved · `, out)
}

function card(item) {
const state = stateOf(item)
const node = el('article', `item is-${state}`)
node.dataset.token = item.token
const photo = el('div', 'photo')
photo.style.backgroundColor = item.average_color || ''
if (item.thumbnails?.length) {
const image = el('img')
const thumbs = [...item.thumbnails].sort((a, b) => a.width - b.width)
image.src = (thumbs.find((t) => t.width >= 480) || thumbs.at(-1)).url
image.alt = item.title || ''
image.loading = 'lazy'
photo.append(image)
}
if (item.fields?.[PRICE]) photo.append(el('span', 'price', item.fields[PRICE]))
const label = { mine: 'Reserved for you', taken: 'Reserved', sold: 'Sold' }[state]
if (label) photo.append(el('span', 'state', label))
node.append(photo, el('h2', '', item.title), el('p', 'details', plain(item.description)))

if (state === 'available') {
const reserve = el('button', 'solid', 'Reserve')
reserve.type = 'button'
reserve.addEventListener('click', () => act(item, ACTION))
node.append(reserve)
} else if (state === 'mine') {
const line = el('p', 'mine', 'Yours. The seller will email you.')
const cancel = el('button', 'link', 'Cancel')
cancel.type = 'button'
cancel.addEventListener('click', () => act(item, UNDO))
line.append(cancel)
node.append(line)
} else {
node.append(el('p', 'gone', state === 'sold' ? 'Sold.' : 'Someone reserved it.'))
}
node.append(el('p', 'error', errors[item.token] || ''))
return node
}

function render() {
const left = items.filter((item) => stateOf(item) === 'available').length
$('filters').replaceChildren(
...[['all', `All ${items.length}`], ['available', `Available ${left}`], ...(me ? [['mine', `Yours ${mine.size}`]] : [])].map(
([key, label]) => {
const button = el('button', '', label)
button.type = 'button'
button.setAttribute('aria-pressed', String(filter === key))
button.addEventListener('click', () => {
filter = key
render()
})
return button
}
)
)
const shown = items.filter((item) => filter === 'all' || stateOf(item) === filter)
$('items').replaceChildren(...(shown.length ? shown.map(card) : [el('p', 'empty', 'Nothing here.')]))
}

// The sign-up sheet resolves with the guest, or null when the visitor closes it.
function signUp() {
return new Promise((resolve) => {
$('signup-error').textContent = ''
$('signup').onclose = () => resolve(me)
$('signup').showModal()
$('signup-name').focus()
})
}

$('signup-form').addEventListener('submit', async (event) => {
event.preventDefault()
$('signup-send').disabled = true
$('signup-error').textContent = ''
try {
await call('playbook/guest', { method: 'POST', body: { name: $('signup-name').value.trim(), email: $('signup-email').value.trim() } })
setGuest(await call('playbook/guest/me'))
$('signup').close()
} catch (error) {
$('signup-error').textContent = error.message
} finally {
$('signup-send').disabled = false
}
})
$('signup-cancel').addEventListener('click', () => $('signup').close())

async function signOut() {
await call('playbook/guest/signout', { method: 'POST', body: {} }).catch(() => {})
setGuest(null)
render()
}

async function act(item, action) {
if (!me && !(await signUp())) return
delete errors[item.token]
document.querySelector(`[data-token="${item.token}"]`)?.querySelectorAll('button').forEach((b) => (b.disabled = true))
try {
const result = await call(`playbook/guest/actions/${action}`, { method: 'POST', body: { asset: item.token } })
// The answer is the item as it is now: reads stay cached for minutes, so
// keep it instead of reading the board again.
Object.assign(item, result.asset)
if (action === ACTION) mine.add(item.token)
else mine.delete(item.token)
toast(action === ACTION ? 'Reserved for you' : 'Reservation cancelled')
} catch (error) {
if (error.status === 401) setGuest(null) // the pass ended: the next tap signs up again
else errors[item.token] = REFUSALS[error.code] || error.message
// Taken by someone else: show it as taken until the next read.
if (error.code === 'condition_failed') item.fields = { ...item.fields, [FIELD]: RESERVED }
}
renderWho()
render()
}

// Light or dark: the visitor's pick, kept per app, else the system's.
$('theme').addEventListener('click', () => {
const root = document.documentElement
const dark = root.dataset.theme ? root.dataset.theme === 'dark' : matchMedia('(prefers-color-scheme: dark)').matches
root.dataset.theme = dark ? 'light' : 'dark'
try {
localStorage.setItem(`theme:${location.pathname}`, root.dataset.theme)
} catch {}
})

try {
const app = await call('playbook/app')
const [{ data: board }, assets, guest] = await Promise.all([
call(`playbook/api/boards/${app.board}`),
(async () => {
const all = []
for (let page = 1; ; page++) {
const { data, pagy } = await call(`playbook/api/assets?per_page=100&page=${page}`)
all.push(...data)
if (!pagy || pagy.current_page >= pagy.total_pages) return all
}
})(),
call('playbook/guest/me').catch(() => null), // 401: not signed up yet
])
items = assets.filter((asset) => !asset.is_group)
document.title = board.title
$('title').textContent = board.title
$('subtitle').textContent = plain(board.description)
setGuest(guest)
render()
} catch {
$('title').textContent = ''
$('notice').hidden = false
}

Make it yours​

Change:

  • FIELD, RESERVED, SOLD and PRICE in app.js, and the same names in playbook.json: they must match the fields and options exactly, as list_custom_fields spells them.
  • MOST and limit.active_per_guest together, 1 to 50: an app anyone can sign up to needs that limit on every state action that undoes nothing.
  • The sign-up sheet's words in index.html: say who gets the contact and why. Add a phone field, and "phone" to input with a members-only field for it, if the seller calls rather than writes.
  • Colours. The tokens at the top of styles.css: the light set on :root, the dark set twice below it. Change both together.
  • Type. The Google Fonts link in index.html and the font on body.

Keep:

  • The sign-up sheet asking for every contact reserve writes. Sign-up doesn't check them, and a guest can't add one later: signing up again makes a new guest.
  • runs from guests/me filtered to reserve. It lists the guest's current runs of every action, the undo's included: an item the guest reserved and released shows a release run.
  • The guest's own current runs trusted over the board's state. A run stays current only while nobody changes what it wrote, so it is always right, while a read can be up to five minutes old.
  • The item from each action's answer kept on the page instead of reading the board again.
  • condition_failed shown as "someone was quicker", and limit_reached as the limit, in the visitor's words.
  • Names shown with textContent, never innerHTML.

Check it​

Open the app in two browsers, one 390 px wide and one 1280 px wide, in different themes. Reserve the same item in both: one gets it, the other is told someone was quicker. Reserve until the limit and check the message. Cancel one and reload: the page still shows what you hold. In Playbook, the item you hold has Buyer and Buyer email; set its Sale back to Available and clear them when you are done.