Simple Pwa Organiser

I have a bunch of boxes storing a lot of small stuff. I’ve labelled them, but the labels are hard to read across the room and a pain to keep up to date when the contents shift. A photo of each box, plus a list of what’s inside, searchable from the phone in my pocket, would be enough to find anything I own without opening a single lid.

Let’s write a local-first PWA for that. Just photos, items, and a search — no framework on top, sync optional.

Live: https://sam.konubinix.eu/organiser/.

A note on reading the code blocks below. This is a literate document — prose and code interleaved, tangled into the running app at build time. Each block carries a #+name: line that gives it an identity; where you see <<some-name>> inside a block, it’s a slot — a hole left for one or more other blocks (named or referenced under some-name) to fill. The tangling step splices everything together; the export you’re reading keeps the slots visible on purpose, so the composition is part of what the code shows you.

choice of technology

Two prior attempts ground the choice.

The first was score counter tally, built on alpine + yjs (yjs is a CRDT library — a data structure that lets multiple devices edit the same document concurrently and merge the result without losing writes). The friction came from two reactivity systems competing: alpine drives the DOM from its own reactive store, yjs drives everything from its document, and the wiring between the two is where the bugs lived.

The second was scrutin de Condorcet randomisé entre amis, on petite-vue + automerge (another CRDT, different lineage from yjs). Slightly better — petite-vue is more forgiving than alpine — but the same fault line was there: the framework’s reactivity and the CRDT’s reactivity are not the same animal, and keeping them in step needed hacky magick at every seam.

The lesson I keep relearning is the same one: one reactive engine, no more. If the rendering layer wants to drive the DOM from its own model while the CRDT also wants to, the seam between them is where the bugs live and where I burn my evenings. I’ll accept a pure render function called from the store’s listener — declarative output that doesn’t pretend to own state — but I won’t accept a second engine.

The second thing I want is just as hard. This is a line-of-business app — lists, forms, CRUD on labelled boxes — and I want to read a card’s markup top to bottom in one piece, the way I read HTML on any real LoB codebase. Hand-rolled createElement chains and setAttribute calls are how I’d have done this in 2005, and they drown the reading every time I come back to the file.

So two picks, one per constraint.

The store is TinyBase. I need persistence (the boxes have to survive a tab close) and mergeable sync (the phone and the laptop have to agree), and TinyBase ships both. The thing I cared most about: its job ends at “a cell changed, here’s the new value.” It doesn’t try to render anything. That leaves me free to plug a renderer of my choosing.

The renderer is lit-html — and only its bare html + render primitives, not the full Lit component model with its own reactive controllers. The whole appeal is that render isn’t reactive: I call it, it patches the DOM, it goes away. My TinyBase listener rebuilds the template and calls render once; nothing else fires on its own. One loop, top to bottom. And because lit-html uses tagged template literals as ESM, “no JSX, no bundler” survives — the markup is HTML I can read, not a sequence of constructor calls.

React was the other obvious candidate. At this scale — forms, lists, CRUD on labelled boxes — the components + hooks + effect dependencies + build pipeline tax buys nothing.

The price of the TinyBase pick lands on the other side: it’s JS-only. If I later want a Python importer or a backend that reads the inventory, it’ll either parse the JSON the sync server writes to disk, or drive a JS runtime as a subprocess. Yjs and Automerge would have given me a real cross-language peer, but only by bringing back the reactivity duality I just walked away from. I’d rather take the language lock-in than pay that bug bill again.

Setting up the store

I want the first feature chapter to read like a feature, not like setup. So before any user-facing thing lands on screen, three foundation pieces have to be in place: I need both libraries loaded the way I said I’d load them, I need to agree with myself on the shape of a box and an item, and I need a boot sequence I can stop thinking about. Every later chapter will read and write through whatever I lay down here.

External libraries

I want TinyBase and lit-html on the page, and I committed to no build step. The browser can resolve bare specifiers (import {…} from 'tinybase') if I declare an import map, so that’s the smallest thing that gets me there.

<script type="importmap">
  {
    "imports": {
      "tinybase": "https://esm.sh/tinybase@5",
      "tinybase/persisters/persister-indexed-db": "https://esm.sh/tinybase@5/persisters/persister-indexed-db",
      "tinybase/synchronizers/synchronizer-ws-client": "https://esm.sh/tinybase@5/synchronizers/synchronizer-ws-client",
      "lit-html": "https://esm.sh/lit-html@3"
    }
  }
</script>

Store schema

What I want to remember is small: a box I can recognise on sight (so a photo, because the labels I’ve been using are unreadable across the room), and an item that names the thing I was looking for. An item has to know which box it lives in so the search can answer “where did I put that?”, and it has to allow no box at all so I can dump items into the system before I’ve decided where they go.

That gives me two TinyBase tables, both keyed by id. A box carries the photo, the basename of the file I picked (which I’ll need as the accessible label and as a hook the tests can grab), and an integer I’ll use to keep the boxes in the order I want — table iteration order doesn’t survive an edit-and-recreate, so I’d rather be explicit (see Reorder boxes). An item carries its name, its current boxId (empty when unassigned — see Drop an item into a box), optionally its own thumbnail for the chip (see Items with photos), and optionally a background colour I can use to group it visually (see Items with background colour).

Initial load

The store holds the things I want to remember after I close the tab. But the app has a second kind of state that has no business landing in IndexedDB: which form is open at the moment, the draft inside it, what I’ve typed in the search box, what the sync indicator is showing. Tomorrow’s “is the box form open?” answer should always be “no” regardless of what I did yesterday. I carry this ephemeral stuff in a plain object alongside the store, and I funnel every mutation through a single helper so I never forget to re-render after I touched it.

const ui = {
    formOpen: null,
    boxForm: {photo: '', photoName: '', editingId: ''},
    itemForm: {name: '', image: '', bgColor: '', editingId: '', nameError: false, boxId: ''},
    searchQuery: '',
    syncStatus: 'off',
    dragEnabled: false,
    contextMenu: null,
    catalogOpen: false,
};

function setUI(updates){
    Object.assign(ui, updates);
    renderApp();
}

Now the rendering. I want one entry point — one function that produces the whole dynamic body, top to bottom — because the moment I have two render functions racing each other I’m back in the bug zone the choice of TinyBase was supposed to walk me out of. Every feature chapter will plug into this entry point.

What I’ll plug into, exactly, is a set of named slots. The top bar has three: a status indicator on the left for the sync state, a row of action buttons in the middle, a search input on the right. The body has two: an overlay layer where the open form lives, and a content layer for the lists and the empty-state hint. Each later chapter pours its contribution into the slot it earns and nobody else’s.

And there’s exactly one place in the whole app where I let myself look up a DOM element by hand: at boot, to find the <main> the app will render into. After that, every element travels with the template that owns it.

const appRoot = document.getElementById('app');

function appTemplate(){
    return html`
      <<app-template-markup>>
    `;
}

function renderApp(){
    renderLit(appTemplate(), appRoot);
}

<header class="app-bar">
  <<app-bar-status>>
  <div class="app-bar-actions">
    <<app-bar-actions>>
  </div>
  <<app-bar-search>>
</header>
<<app-body-overlays>>
<<app-body-content>>
<<app-floating-controls>>

The boot sequence has one ordering trap, one type pick, and one small wrinkle for the test suite worth stating before the code.

The trap: if I wire the store listener before the persister has replayed yesterday’s state, renderApp fires on every replayed write and the first paint flashes through partial states. So I replay first, then wire the listener, then call renderApp once on the loaded state, then start saving forward mutations. The last thing I do is set data-app-ready on the body, which is the single signal my tests wait on before they start driving the page.

The wrinkle: TinyBase’s startAutoSave debounces writes by a tick or two, which is fine for production but means the persistence test would race the disk if I asked it to reload immediately after Save. Rather than dropping startAutoSave (it’s doing real work — handling the IndexedDB connection, coalescing burst writes), I add a parallel listener alongside it that calls persister.save() and bumps a data-persist-seq counter on the body once the write returns. The persistence test waits on that counter incrementing — a deterministic signal that the row is on disk — rather than guessing how long the debounce takes.

The type pick: MergeableStore, not the plain Store. The plain one wouldn’t survive the moment a second device starts writing — I need the hybrid-logical-clock stamps the WebSocket synchronizer reads (HLCs are a way to give every edit a total order across devices that have never spoken to each other, so the merge can decide who wins without a coordinator; see Sync across devices). Paying for the stamps now is cheaper than retrofitting them later.

import { createMergeableStore } from 'tinybase';
import { createIndexedDbPersister } from 'tinybase/persisters/persister-indexed-db';
import { createWsSynchronizer } from 'tinybase/synchronizers/synchronizer-ws-client';
import { html, render as renderLit } from 'lit-html';

const store = createMergeableStore();
const persister = createIndexedDbPersister(store, 'organiser');

await persister.startAutoLoad();
store.addTablesListener(renderApp);
renderApp();
await persister.startAutoSave();
let _persistSeq = 0;
store.addTablesListener(async () => {
    await persister.save();
    document.body.setAttribute('data-persist-seq', String(++_persistSeq));
});
document.body.setAttribute('data-app-ready', '1');
startSync();

Visual basics

I want a dark theme — phones are mostly dark these days and the app spends its time in workshop and storeroom lighting — and I want every later chapter that needs the muted grey for a label or the accent orange for a button to reach for the same names. So I pin the palette to CSS custom properties once, here, and the feature chapters can use var(--muted) without me having to remember which shade I picked.

:root{
    --bg:#1b1d2e; --card:#262a40; --fg:#e8e8f0; --muted:#8a8ea5;
    --accent:#f9a826;
}
*{box-sizing:border-box}
body{margin:0;background:var(--bg);color:var(--fg);font-family:system-ui,sans-serif;line-height:1.4;min-height:100vh}
[hidden]{display:none !important}

Open the app

The first time I open the app on a fresh phone there’s nothing in the store yet, and an empty page would leave me wondering whether the thing failed to load. So I want a small landing message: an emoji big enough to read across the room, the app’s name, a single line saying “no boxes yet.” It should disappear the second I add anything, no matter what — a box or just an unassigned item.

The test I want to pin first is the trivial one: open the app, see the hint. (clear_state, used here and in every later test, resets IndexedDB and localStorage between cases — defined in Playwright tests.)

@testcase
def test_empty_state(page):
    """No box recorded yet → the empty-state line is visible."""
    clear_state(page)
    assert page.get_by_text("No boxes yet").is_visible(), \
        "empty-state line not visible after fresh load"
    print("  PASS: empty state")

“Disappear the second I add anything” tells me what to compute: whether both tables are empty. Because the renderer runs on every store change, I don’t need any kind of show/hide gymnastics — the template returns the hint when both tables are empty, and returns nothing the next time the user has actually written something. The empty state lives in the document the same way a paragraph does when it has content to display, and is simply absent otherwise.

function emptyStateTemplate(){
    const empty = !Object.keys(store.getTable('boxes')).length
               && !Object.keys(store.getTable('items')).length;
    if(!empty) return '';
    return html`
      <<empty-state-markup>>
    `;
}

The wording of the hint matters: the test reaches for the literal string “No boxes yet”, so if I change the copy later I’ll have to update the test in the same edit.

<div class="empty-state">
  <div class="emoji">&#x1f4e6;</div>
  <h1>Organiser</h1>
  <p>No boxes yet.</p>
</div>

The thing I most want to avoid visually is the user mistaking the hint for a stuck loading screen. Centering the block, muting the text colour, and pushing the emoji to font-size 3 buys that — at a glance it reads “this is what the app looks like when it’s empty”, not “the thing is still spinning.”

.empty-state{text-align:center;padding:60px 20px;color:var(--muted)}
.empty-state .emoji{font-size:3rem;margin-bottom:12px}
.empty-state h1{font-size:1.4rem;margin:0 0 8px 0;color:var(--fg)}
.empty-state p{font-size:.95rem;line-height:1.5}

Add a box

This is the feature the whole app is in service of. The single thing I’ll remember about a box is what it looks like, and that’s literally what the camera in my pocket gives me. So recording a box is: tap a button, pick (or take) a photo, save. No name to type, no colour to fiddle with, no field that doesn’t earn its place — the photo is the box, from the moment it lands.

The test pins down what “added” feels like end to end: the thumbnail appears in the list, the empty-state hint goes away.

@testcase
def test_add_first_box(page):
    """Adding a first box puts its photo thumbnail in the list and
    dissolves the empty-state hint."""
    clear_state(page)
    page.get_by_role("button", name="Add a box").click()
    page.get_by_label("Photo").set_input_files(files=[{
        "name": "workshop.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Photo preview").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    assert page.get_by_role("button", name="Box workshop").is_visible(), \
        "new box thumbnail not listed"
    assert not page.get_by_text("No boxes yet").is_visible(), \
        "empty-state still visible after add"
    print("  PASS: add first box")

The entry point lives in the top bar. I want the bar to host more than just this button later — at minimum a search field, and eventually a sync indicator — so the action takes its place alongside the others rather than dominating the screen.

<button type="button" @click=${openBoxForm}>Add a box</button>

Now that the bar has its first occupant, it earns its styling. A horizontal flex row with the actions pushed to the right end is what I want — the status indicator and the search field are what will sit on the left and centre once they arrive. Whatever button lands in the bar wears the accent orange so it stands out as a primary action.

.app-bar{display:flex;gap:8px;align-items:center;flex-wrap:wrap;padding:12px 16px;border-bottom:1px solid #2a2d44}
.app-bar button{background:var(--accent);color:#111;padding:8px 14px;border:0;border-radius:6px;font:inherit;font-weight:600;cursor:pointer}
.app-bar-actions{display:flex;gap:8px;margin-left:auto}

Tapping the button opens a form, and I want every later form (the item form is the next one) to feel identical: same width, same spacing, same submit/cancel pair at the bottom. I codify that once now — under the add-form class — so each later chapter just inherits the look by carrying the same class.

.add-form{display:grid;gap:10px;padding:16px;max-width:420px;margin:0 auto}
.add-form label{display:block;font-size:.9rem;color:var(--muted)}
.add-form input[type=text]{width:100%;background:var(--card);color:var(--fg);border:1px solid #333;border-radius:6px;padding:8px;font:inherit;margin-top:4px}
.add-form input[type=color]{width:48px;height:32px;border:0;background:transparent;margin-top:4px;padding:0;cursor:pointer}
.add-form-actions{display:flex;gap:8px}
.add-form-actions button{flex:1;padding:10px;border:0;border-radius:6px;font:inherit;font-weight:600;cursor:pointer}
.add-form-actions button[type=submit]{background:var(--accent);color:#111}
.add-form-actions button[type=button]{background:var(--card);color:var(--fg)}

Same goes for the list of boxes I’m about to create. I want the list itself to flow — boxes arranged left-to-right and wrapping to a new row when they run out of width, the way a contact-sheet of photos would. One-box-per-line wastes the horizontal space on anything wider than a phone, and even on a phone two compact cards fit comfortably side by side. Each card has a flex basis of 160 pixels so cards stretch a little to fill an even row, and the list itself caps at 840 pixels so it stays centred and readable on a wide screen.

One small thing the rule does explicitly that looks redundant is set flex-direction:row. The list also wears the .reorder-list class so the shared reorder engine picks it up, and that engine sets flex-direction:column on its lists by default (a sensible default for the column-shaped lists most callers want to reorder). I want a row layout instead, so I state it. Same with placing this rule after the shared reorder CSS in the export, so the cascade resolves my way.

Inside each card, a 48×48 thumbnail carries the photo. The earlier version cropped to fill the square (object-fit:cover), which threw away the edges of every non-square photo — useless if the bit that identifies the box is at the top of the shot. I use object-fit:contain instead: the whole photo is visible inside the square, letterboxed when the aspect ratio doesn’t match. To make the letterboxing read as deliberate rather than as a glitch, I give the button a background that matches the page, not the card. The same contain rule applies to the bigger preview <img> inside the edit form, where the photo gets to fill the form’s width for a proper look before saving. The item form reuses that preview, which is why both rules live here rather than in Items with photos.

.boxes-list{list-style:none;padding:0 16px;margin:0 auto;max-width:840px;display:flex;flex-direction:row;flex-wrap:wrap;gap:8px}
.box{padding:8px 14px;background:var(--card);border-radius:8px;flex:1 1 160px}
.box-photo{
    appearance:none;border:1px solid #00000033;padding:0;
    width:48px;height:48px;border-radius:8px;
    overflow:hidden;flex-shrink:0;cursor:pointer;
    background:var(--bg);
}
.box-photo-thumb{display:block;width:100%;height:100%;object-fit:contain}
.item-image-preview,.box-photo-preview{display:block;width:100%;max-height:60vh;border-radius:6px;margin-top:4px;object-fit:contain}

Now the form itself. The story of the form is: I pick a file, I see what I picked, I save. So the markup needs a file input, a preview that’s only there once a photo has actually landed, and the submit/cancel pair. The same form will serve the edit case later (cf. Edit a box), at which point a Delete button slots into the action row — but that arrives with its own chapter, so for now there’s an opening for it and nothing else.

The preview’s alt text deserves a word. I want the test to wait on something deterministic when a new photo lands, not a guess-the-delay sleep. The cheapest signal I can hand it is the alt text itself, set on the same render that puts the preview on screen — so I embed the file’s basename in there. The edit test in Edit a box is what really exercises this, but the contract is established here.

<form class="add-form" @submit=${onBoxFormSubmit}>
  <label>Photo
    <input type="file" accept="image/*" capture="environment"
           @change=${onBoxPhotoChange}>
  </label>
  ${photo ? html`
    <img class="box-photo-preview"
         src=${photo}
         alt=${photoName ? `Photo preview ${photoName}` : 'Photo preview'}>
  ` : ''}
  <div class="add-form-actions">
    <button type="submit">Save</button>
    <button type="button" @click=${closeForm}>Cancel</button>
    <<box-form-action-extras>>
  </div>
</form>

The form sits in front of the rest of the page when it’s open and is otherwise absent. It opens centred in the viewport — a stable spot the eye always lands on, that survives a phone rotation without any geometry to recompute — and a modal backdrop holds the rest of the page until I commit one way or the other. One piece of ephemeral state drives it: ui.formOpen names which form is showing, and the renderer picks the right template. The same flag will gate the item form too (cf. Add an item), which is what guarantees only one form is ever on screen.

modalShellTemplate wraps any form in the backdrop + the shell. The backdrop has no click handler — there’s no escape route except Save or Cancel — and the shell sits one z-index above it. No inline geometry: the centring is pure CSS, which re-resolves automatically on a viewport change.

function modalShellTemplate(form){
    return html`
      <div class="modal-backdrop"></div>
      <div class="modal-shell">
        ${form}
      </div>
    `;
}

The centring, backdrop, sizing and overflow live in the shared modal-shell block — same pattern any future modal in this app would want. All this chapter has to add locally is the reset that lets the form’s grid sit flush against the shell’s rounded edges.

.modal-shell .add-form{margin:0}

Opening the form is a single state mutation: seed an empty draft, flip the flag, and stash the click target’s rect so the shell can place itself next to it. Closing it does the reverse and wipes both form drafts and the anchor, since I don’t want yesterday’s half-typed item name to reappear when I next open that form either. closeForm lives here because it’s symmetrical with openBoxForm, but Add an item and the delete buttons share it.

function openBoxForm(){
    setUI({
        formOpen: 'box',
        boxForm: {photo: '', photoName: '', editingId: ''},
    });
}

function closeForm(){
    setUI({
        formOpen: null,
        boxForm: {photo: '', photoName: '', editingId: ''},
        itemForm: {name: '', image: '', bgColor: '', editingId: '', nameError: false},
    });
}

The picked file is the next problem. A modern phone camera hands me a JPEG of several megapixels — more than enough to balloon IndexedDB after a few dozen boxes, and obscene for what’s going to be a 48-pixel thumbnail. So I downscale before storing. I do it through a <canvas> because that’s the one place in the browser where I can decode an image, resize it, and re-encode it without leaving the page. 200 pixels on the long side is enough for the thumbnail and for me to still recognise the box; JPEG 0.85 keeps the file small without artefacts at this size. The function lives at module scope because the item form (cf. Items with photos) will reuse exactly the same pipeline.

async function fileToThumbnail(file){
    const url = URL.createObjectURL(file);
    try {
        const img = await new Promise((res, rej) => {
            const i = new Image();
            i.onload = () => res(i);
            i.onerror = rej;
            i.src = url;
        });
        const max = 200;
        const scale = Math.min(max / img.width, max / img.height, 1);
        const canvas = document.createElement('canvas');
        canvas.width = Math.max(1, Math.round(img.width * scale));
        canvas.height = Math.max(1, Math.round(img.height * scale));
        canvas.getContext('2d').drawImage(img, 0, 0, canvas.width, canvas.height);
        return canvas.toDataURL('image/jpeg', 0.85);
    } finally {
        URL.revokeObjectURL(url);
    }
}

When the file input changes, I run it through the pipeline and put the result into ui.boxForm. There is no separate show/hide toggle for the preview — the form template re-renders with the new state, and the conditional in the markup is what flips it on. If the user clears the input, the same state mutation drops the preview by the same path.

async function onBoxPhotoChange(e){
    const file = e.target.files[0];
    if(!file){
        setUI({boxForm: {...ui.boxForm, photo: '', photoName: ''}});
        return;
    }
    const photo = await fileToThumbnail(file);
    const photoName = file.name.replace(/\.[^.]+$/, '');
    setUI({boxForm: {...ui.boxForm, photo, photoName}});
}

Save is the moment the draft becomes a real row. A brand-new box needs to land at the end of the list so the user sees it appear where they expect, which means giving it an order one past the current maximum; an edit, on the other hand, must keep the existing order or the box would jump around mid-edit. The editingId bit of the draft is what tells the two cases apart.

function onBoxFormSubmit(e){
    e.preventDefault();
    const {photo, photoName, editingId} = ui.boxForm;
    if(!photo) return;
    const id = editingId || crypto.randomUUID();
    const existing = store.getRow('boxes', id);
    const orders = Object.values(store.getTable('boxes')).map(r => r.order ?? 0);
    const order = existing?.order ?? (orders.length ? Math.max(...orders) + 1 : 0);
    store.setRow('boxes', id, {photo, photoName, order});
    closeForm();
}

Once boxes exist, they need to appear in a list. The list is ordered by the order cell — not by table iteration, which is what makes Reorder boxes possible later. I also bake in the search-filter branch right now even though Find a box by searching for an item is what populates ui.searchQuery later; until that chapter the query is empty (the initial UI state seeds it that way) and the filter is a no-op. Putting it here saves me from having to revisit this template once searching arrives.

function boxesListTemplate(){
    const rows = store.getTable('boxes');
    const itemsById = store.getTable('items');
    const queryB = ui.searchQuery.trim().toLowerCase();
    const itemMatchesB = name => !queryB || name.toLowerCase().includes(queryB);
    const sortedIds = Object.keys(rows).sort((a, b) =>
        (rows[a].order ?? 0) - (rows[b].order ?? 0));
    const ids = sortedIds.filter(id => {
        if(!queryB) return true;
        return Object.keys(itemsById).some(iid =>
            itemsById[iid].boxId === id && itemMatchesB(itemsById[iid].name));
    });
    if(!ids.length) return '';
    return html`
      <<boxes-list-markup>>
    `;
}

<ul class="boxes-list reorder-list" data-reorder="boxes" aria-label="Boxes">
  ${ids.map((id, idx) =>
      boxTemplate(id, idx, rows[id], itemsById, itemMatchesB))}
</ul>

Each card in the list is, again, just the photo — wrapped in a <button> because tapping it does something (it opens the edit form, as Edit a box sets up). The button carries the accessible label Box <photoName> so the same word is what a screen reader hears, what the test reaches for, and what the edit-click reads.

Three later chapters extend this card: Drop an item into a box needs to mark the <li> as a drop target, Add an item needs to add a chip row inside it for the contained items, and Reorder boxes needs to add a grip and a data-idx. I open four slots now — three for additions to the body, one for additions to the <li>’s attributes — and let each chapter pour into the slot it owns.

<li
  class="box reorder-item"
  data-box-id=${id}
  <<render-box-attrs>>
>
  <<render-box-base>>
  <<render-box-items>>
  <<render-box-grip>>
</li>

The first slot is mine to fill: the photo button itself, with the click that opens the edit form. openBoxEdit is defined over in Edit a box, but the gesture lives on the photo button, and I want the handler attached to the element that owns the gesture rather than fished out by event delegation somewhere far away.

<button type="button" class="box-photo"
        aria-label="Box ${row.photoName}"
        @click=${() => openBoxEdit(id, row)}>
  <img class="box-photo-thumb" src=${row.photo} alt="">
</button>

Edit a box

Sooner or later I’ll take a bad photo, or the box’s contents will drift enough that the current photo no longer represents it. I want the fix to be cheap: tap the box, retake the photo, save. No separate edit screen. The form I already built for adding is the natural place — it has the same single field (a photo), and the difference between adding and editing is just “do I have an id to overwrite, or do I mint a new one.” That’s already the shape of the editingId switch in the submit handler.

The test does add → tap → re-photo → save, and asserts that the old thumbnail is gone (otherwise the edit would have created a duplicate row instead of overwriting). The wait on Photo preview garage rather than a plain “Photo preview” is on purpose: the thumbnail pipeline is async, so the only way the preview’s alt text reads Photo preview garage is after the new photo has landed in ui.boxForm.photoName — which is precisely the state Save needs to read. Waiting on the alt text is therefore the same as waiting on the state.

@testcase
def test_edit_box(page):
    """Tapping a box opens the form; uploading a new photo overwrites it."""
    clear_state(page)
    page.get_by_role("button", name="Add a box").click()
    page.get_by_label("Photo").set_input_files(files=[{
        "name": "workshop.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Photo preview workshop").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    page.get_by_role("button", name="Box workshop").click()
    page.get_by_label("Photo").set_input_files(files=[{
        "name": "garage.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Photo preview garage").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    assert not page.get_by_role("button", name="Box workshop").is_visible(), \
        "old thumbnail still visible — edit may have created a duplicate"
    assert page.get_by_role("button", name="Box garage").is_visible()
    print("  PASS: edit box")

A modal backdrop holds the rest of the page until I commit — clicking another box behind the form does nothing.

@testcase
def test_edit_form_is_modal(page):
    """The modal backdrop blocks clicks on items behind the form
    — only Save or Cancel can close it."""
    clear_state(page)
    for name in ["alpha", "bravo"]:
        page.get_by_role("button", name="Add a box").click()
        page.get_by_label("Photo").set_input_files(files=[{
            "name": f"{name}.png", "mimeType": "image/png", "buffer": MINIMAL_PNG}])
        page.get_by_role("img", name="Photo preview").wait_for(state="visible")
        page.get_by_role("button", name="Save").click()
    page.get_by_role("button", name="Box alpha").click()
    page.get_by_role("img", name="Photo preview alpha").wait_for(state="visible")
    bravo_rect = page.get_by_role("button", name="Box bravo").bounding_box()
    page.mouse.click(
        bravo_rect["x"] + bravo_rect["width"] / 2,
        bravo_rect["y"] + bravo_rect["height"] / 2,
    )
    assert page.get_by_role("img", name="Photo preview alpha").is_visible(), \
        "form switched source after a click on another box — backdrop didn't block"
    print("  PASS: edit form is modal")

The form sits centred in the viewport — both axes, regardless of where on the page the user tapped. A modal that jumps next to the click target was a clever idea that played badly in practice: it left the form pinned to the corner the photo happened to occupy, made the rotation case (the viewport shifts but the placement stays frozen at the old coordinates) a constant source of off-screen forms, and gave the eye no stable place to look. Centred in the viewport, the form is always where the user expects it to be, and a phone rotation redraws into the new shape with nothing further to do.

@testcase
def test_edit_form_centered_in_viewport(page):
    """The edit form is centred in the viewport, before and after rotation."""
    clear_state(page)
    page.get_by_role("button", name="Add a box").click()
    page.get_by_label("Photo").set_input_files(files=[{
        "name": "workshop.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Photo preview workshop").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    page.get_by_role("button", name="Box workshop").click()
    page.locator("form.add-form").wait_for(state="visible")
    def assert_centered(vw, vh, slack=2):
        rect = page.locator(".modal-shell").bounding_box()
        cx = rect["x"] + rect["width"] / 2
        cy = rect["y"] + rect["height"] / 2
        assert abs(cx - vw / 2) < slack, \
            f"shell not horizontally centred: cx={cx}, vp_w={vw}"
        assert abs(cy - vh / 2) < slack, \
            f"shell not vertically centred: cy={cy}, vp_h={vh}"
        assert rect["x"] >= 0 and rect["x"] + rect["width"] <= vw, \
            f"shell off-screen horizontally: {rect}"
        assert rect["y"] >= 0 and rect["y"] + rect["height"] <= vh, \
            f"shell off-screen vertically: {rect}"
    assert_centered(*PHONE_VIEWPORT.values())
    try:
        page.set_viewport_size({"width": 800, "height": 400})
        page.wait_for_function(
            """() => {
              const s = document.querySelector('.modal-shell');
              if (!s) return false;
              const r = s.getBoundingClientRect();
              return Math.abs((r.left + r.width / 2)  - window.innerWidth / 2) < 2
                  && Math.abs((r.top  + r.height / 2) - window.innerHeight / 2) < 2;
            }""",
            timeout=1500,
        )
        assert_centered(800, 400)
    finally:
        page.set_viewport_size(PHONE_VIEWPORT)
    print("  PASS: edit form centered in viewport")

All this chapter has to add is the gesture: tap a box, open the form pre-filled with that box’s state. editingId tells the submit handler to overwrite rather than mint. The form opens centred in the viewport, same as the add case — there’s no separate edit screen and no per-box positioning to compute.

function openBoxEdit(id, row){
    setUI({
        formOpen: 'box',
        boxForm: {
            photo: row.photo || '',
            photoName: row.photoName || '',
            editingId: id,
        },
    });
}

Delete a box

At some point a box stops being useful — the shelf it lived on is gone, the things it held are scattered. I want to be able to drop it from the inventory without it being so easy that an accidental tap costs me a row. So: a Delete button on the edit form (not anywhere on the box card itself, where I might brush it by mistake), and a browser confirm() behind it. The test does the simple case — add, edit, delete, gone — and the harder case (what happens to items inside a deleted box) waits for Drop an item into a box, because until then no item can be inside a box.

@testcase
def test_delete_box(page):
    """Deleting an empty box removes its thumbnail from the list."""
    clear_state(page)
    page.get_by_role("button", name="Add a box").click()
    page.get_by_label("Photo").set_input_files(files=[{
        "name": "workshop.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Photo preview").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    page.get_by_role("button", name="Box workshop").click()
    page.once("dialog", lambda d: d.accept())
    page.get_by_role("button", name="Delete").click()
    assert not page.get_by_role("button", name="Box workshop").is_visible(), \
        "thumbnail still listed"
    print("  PASS: delete box")

The button slots into the action row I already left open in the form template (Add a box’s box-form-action-extras). It appears only when the form is in edit mode — i.e. when ui.boxForm.editingId is set — because in add mode there is literally no row to delete.

${ui.boxForm.editingId ? html`
  <button type="button" class="danger" @click=${onBoxFormDelete}>Delete</button>
` : ''}

This is also the first destructive button in the app, so it earns the danger colour. Delete an item later wears the same class.

.add-form-actions button.danger{background:#e94560;color:#fff}

The handler itself does one thing that isn’t obvious: before removing the box’s row it sweeps every item that points at this box and flips its boxId back to empty, so the items return to Unassigned rather than becoming orphans pointing at a row that no longer exists. The order matters — items first, then the box — because the renderer fires once at the end of the transaction and I don’t want it ever seeing the intermediate state. The confirm message reflects this so the user knows their items aren’t going to disappear with the box.

function onBoxFormDelete(){
    const {editingId} = ui.boxForm;
    if(!editingId) return;
    if(!confirm('Delete this box? Items inside go back to Unassigned.')) return;
    const items = store.getTable('items');
    for(const id of Object.keys(items)){
        if(items[id].boxId === editingId){
            store.setCell('items', id, 'boxId', '');
        }
    }
    store.delRow('boxes', editingId);
    closeForm();
}

Reorder boxes

Once I have more than three boxes, creation order stops matching the physical layout in my workshop. I want my “shelf above the workbench” box near the top because that’s where I look first, and I want to be able to put it there by hand. A drag-to-reorder gesture with a small grip on the right edge of each card is the obvious affordance: it tells me the row is movable without shouting at me, and it keeps the bulk of the card free for tap gestures.

Two design choices I want to commit to before the code lands.

First, the order has to live in the store, not in the table’s iteration sequence. TinyBase iteration is stable across reloads, but it’s not stable across an edit or a delete-and-recreate. If I rely on it, the order will randomise itself behind my back the first time I edit a box. So every box gets an explicit order integer and the renderer sorts by it.

Second, the reorder gesture rewrites every box’s order cell in one pass — index 0, 1, 2, … all the way through — because keeping the integers dense is cheaper to reason about than juggling fractions or sparse indices. I wrap the whole rewrite in a store.transaction so the listener fires once at the end rather than once per cell, which matters during the drag because the pointer-engine’s geometry queries would otherwise be chasing a list that’s re-rendering under its feet.

I’m not writing the drag engine itself in this doc — it lives in shared blocks because Condorcet needs the same thing. The contract it expects is: a .reorder-list on the <ul>, a .reorder-item class plus a data-idx attribute on each <li>, and a .reorder-grip element to grab. When a drag finishes the engine fires a reorder:move event with from and to indices. My job is to listen for it and rewrite the order cells.

@testcase
def test_reorder_boxes(page):
    """Dragging a box's grip up changes its position in the list."""
    clear_state(page)
    for name in ["alpha", "bravo", "charlie"]:
        page.get_by_role("button", name="Add a box").click()
        page.get_by_label("Photo").set_input_files(files=[{
            "name": f"{name}.png",
            "mimeType": "image/png",
            "buffer": MINIMAL_PNG,
        }])
        page.get_by_role("img", name="Photo preview").wait_for(state="visible")
        page.get_by_role("button", name="Save").click()
    enable_drag(page)
    page.get_by_role("button", name="Reorder charlie").drag_to(
        page.get_by_role("button", name="Reorder alpha"))
    first_label = page.get_by_role(
        "button", name=re.compile(r"^Box ")).first.get_attribute("aria-label")
    assert first_label == "Box charlie", \
        f"reorder didn't take effect: first is {first_label!r}"
    print("  PASS: reorder boxes")

The floating clone the engine shows during the drag has the same outer dimensions as the box being dragged — no visible size jump when the gesture begins.

@testcase
def test_reorder_drag_clone_matches_source(page):
    """The floating drag clone matches the dragged box's
    width and height (no scale-up, no padding mismatch)."""
    clear_state(page)
    for name in ["alpha", "bravo"]:
        page.get_by_role("button", name="Add a box").click()
        page.get_by_label("Photo").set_input_files(files=[{
            "name": f"{name}.png", "mimeType": "image/png",
            "buffer": MINIMAL_PNG}])
        page.get_by_role("img", name="Photo preview").wait_for(state="visible")
        page.get_by_role("button", name="Save").click()
    enable_drag(page)
    src = page.locator("li.box").nth(0)
    src_rect = src.bounding_box()
    grip = page.get_by_role("button", name="Reorder alpha")
    grip_rect = grip.bounding_box()
    cx = grip_rect["x"] + grip_rect["width"] / 2
    cy = grip_rect["y"] + grip_rect["height"] / 2
    page.mouse.move(cx, cy)
    page.mouse.down()
    page.mouse.move(cx + 5, cy + 5)
    clone_rect = page.locator(".drag-clone").bounding_box()
    page.mouse.up()
    wd = abs(clone_rect["width"] - src_rect["width"])
    hd = abs(clone_rect["height"] - src_rect["height"])
    assert wd < 4, \
        f"clone width {clone_rect['width']} != source {src_rect['width']}"
    assert hd < 4, \
        f"clone height {clone_rect['height']} != source {src_rect['height']}"
    print("  PASS: reorder drag clone matches source")

document.addEventListener('reorder:move', e => {
    if(e.target.dataset?.reorder !== 'boxes') return;
    const { from, to } = e.detail;
    const rows = store.getTable('boxes');
    const ordered = Object.keys(rows).sort((a, b) =>
        (rows[a].order ?? 0) - (rows[b].order ?? 0));
    const [moved] = ordered.splice(from, 1);
    ordered.splice(to, 0, moved);
    store.transaction(() => {
        ordered.forEach((id, idx) => store.setCell('boxes', id, 'order', idx));
    });
});

Two contributions to the box card complete the engine’s contract.

The grip itself goes into Add a box’s render-box-grip slot — six dots on the right edge, recognisable as “grab me.” Its aria-label is Reorder <photoName>, which lets the test grab the right handle by name rather than by position, and lets a screen reader name it usefully too.

${ui.dragEnabled ? html`
  <button type="button" class="reorder-grip" aria-label="Reorder ${row.photoName}">
    <svg width="10" height="16" viewBox="0 0 10 16" aria-hidden="true">
      <circle cx="2" cy="3" r="1.3"/><circle cx="8" cy="3" r="1.3"/>
      <circle cx="2" cy="8" r="1.3"/><circle cx="8" cy="8" r="1.3"/>
      <circle cx="2" cy="13" r="1.3"/><circle cx="8" cy="13" r="1.3"/>
    </svg>
  </button>
` : ''}

The data-idx the engine reads belongs on the <li> itself, not on the grip, so it goes into the attributes slot rather than the body slot.

data-idx=${idx}

The grip’s styling lives here too — small and muted by default, brightening on hover — because the feature that owns the gesture is also the feature that owns its visual weight. The opacity ramp-on-hover is what tells the user the grip is interactive without it dominating the card when they’re not interacting.

.reorder-grip{
    appearance:none;border:0;padding:0;
    width:28px;height:28px;
    margin-right:-6px;
    background:transparent;color:var(--muted);
    opacity:.55;border-radius:6px;
    transition:opacity .15s, background-color .15s;
}
.reorder-grip:hover{opacity:1;background:rgba(255,255,255,.06)}
.reorder-grip svg{fill:currentColor;display:block;margin:auto;pointer-events:none}

One more visual the gesture owns: the floating clone shown during the drag. The shared engine builds it as a positioned <div class“drag-clone”>= and the engine’s default CSS paints it in the accent colour and scales it up 4% — visually distinct, but a poor match for a box card. The override below makes the clone wear the box’s own padding, background and border-radius, and drops the scale so the box doesn’t visibly jump on grab. :not(.item) keeps the rule off the chip-drag clone (cf. Drop an item into a box), where the engine’s default look is fine.

.drag-clone:not(.item){
    padding:8px 14px;
    background:var(--card);
    color:var(--fg);
    border-radius:8px;
    transform:none;
}

Add an item

Boxes are scaffolding. Items are the point — every screw, charger, allen key I want to find again next month. Two things drive the shape of this feature.

First, I almost never know which box a thing belongs in at the moment I record it. I find a loose USB cable on my desk; I want to add it to the inventory now and decide its box later, when I’m next standing in front of the shelves. So the item starts unassigned, and adding it requires no decision about placement. The boxId cell starts empty and stays empty until I drag the chip onto a box (cf. Drop an item into a box).

Second, unassigned items can’t be invisible — if they were, I’d forget I had them. I gather them in their own Unassigned section at the bottom of the page where they’re impossible to miss.

@testcase
def test_add_first_item(page):
    """Adding an item lands it in the Unassigned section."""
    clear_state(page)
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("3mm screw")
    page.get_by_role("button", name="Save").click()
    assert page.get_by_text("3mm screw").is_visible(), \
        "new item not in Unassigned"
    assert page.get_by_role("heading", name="Unassigned").is_visible(), \
        "Unassigned section header not visible"
    print("  PASS: add first item")

The form

Same entry pattern as the box form: a second button in the app-bar’s actions row, next to the existing one.

<button type="button" @click=${() => openItemForm()}>Add an item</button>

The form itself reuses everything I built for the box form — same add-form class, same ui.formOpen flag, same upload pipeline. What’s different: there’s a name field, the image is optional, and there’s a duplicate-name guard (Unique item names). The draft sits in ui.itemForm.

Three slots in the markup left for later chapters to fill: item-form-name-extras just below the name field (where Unique item names pours the duplicate-name alert), item-form-color between the image preview and the action row (where Items with background colour pours its picker and recent-colour swatches), and item-form-action-extras alongside Save and Cancel (where Delete an item pours its Delete button when the form is in edit mode).

<form class="add-form" @submit=${onItemFormSubmit}>
  <label>Item name
    <input type="text" placeholder="e.g. 3mm screw" required
           .value=${name}
           @input=${onItemNameInput}>
  </label>
  <<item-form-name-extras>>
  <label>Image
    <input type="file" accept="image/*" capture="environment"
           @change=${onItemImageChange}>
  </label>
  ${image ? html`
    <img class="item-image-preview" src=${image} alt="Image preview">
  ` : ''}
  <<item-form-color>>
  <div class="add-form-actions">
    <button type="submit">Save</button>
    <button type="button" @click=${closeForm}>Cancel</button>
    <<item-form-action-extras>>
  </div>
</form>

Opening this form follows the same pattern as the box form — seed an empty draft, flip ui.formOpen — and closeForm (in Add a box) already handles both. Edit an item will be the variant that pre-fills the draft instead of clearing it.

function openItemForm(opts = {}){
    setUI({
        formOpen: 'item',
        itemForm: {name: '', image: '', bgColor: '', editingId: '', nameError: false,
                   boxId: opts.boxId || ''},
        contextMenu: null,
    });
}

Submit is going to need to refuse a duplicate name, so the check is what I write first. The full reasoning for why duplicates are forbidden lives in Unique item names; for now the bit that matters is that the comparison is case-insensitive and trimmed, and that an item being edited has to be allowed to “duplicate” itself — otherwise I couldn’t even change its capitalisation.

function itemNameExists(name, exceptId){
    const items = store.getTable('items');
    const lower = name.toLowerCase();
    return Object.entries(items).some(([id, item]) =>
        id !== exceptId && item.name.toLowerCase() === lower);
}

Two input handlers feed the draft. The name field is bound two-way — what I type lands in ui.itemForm.name immediately — and the same keystroke also clears the duplicate-name alert so the next submit attempt starts fresh.

function onItemNameInput(e){
    setUI({itemForm: {...ui.itemForm, name: e.target.value, nameError: false}});
}

The image input runs through the same fileToThumbnail I wrote for the box photos — no point duplicating that pipeline — and writes the result into ui.itemForm.image.

async function onItemImageChange(e){
    const file = e.target.files[0];
    if(!file){
        setUI({itemForm: {...ui.itemForm, image: ''}});
        return;
    }
    const image = await fileToThumbnail(file);
    setUI({itemForm: {...ui.itemForm, image}});
}

Save commits the draft. Two cases I want to keep apart in my head: a new item must start unassigned (boxId empty), while an edit must preserve whatever box the item was already in — I don’t want renaming a screw to yank it out of its drawer. If the name’s a duplicate, the form stays open and the alert lights up.

function onItemFormSubmit(e){
    e.preventDefault();
    const {name: raw, image, bgColor, editingId, boxId} = ui.itemForm;
    const name = raw.trim();
    if(!name) return;
    if(itemNameExists(name, editingId)){
        setUI({itemForm: {...ui.itemForm, nameError: true}});
        return;
    }
    if(editingId){
        const existing = store.getRow('items', editingId);
        store.setRow('items', editingId, {
            name, image, bgColor, boxId: existing?.boxId || '',
        });
    } else {
        store.setRow('items', crypto.randomUUID(), {
            name, image, bgColor, boxId: boxId || '',
        });
    }
    closeForm();
}

The chip

Now the chip the item renders as. It has to work in two places — on its own in the Unassigned section, and crammed into a box card alongside its siblings — but I want it to be the same template in both, so that any future change (a delete X, a long-press menu) lands in one place. The chip itself is a tap target for editing (Edit an item defines what that means), and it carries data-draggable so the drag engine picks it up as a source later.

<li class="item" data-item-id=${id} ?data-draggable=${ui.dragEnabled}
    style=${item.bgColor ? `background:${item.bgColor};color:${readableForeground(item.bgColor)}` : ''}
    @click=${() => openItemEdit(id, item)}>
  ${item.image ? html`<img class="item-thumb" src=${item.image} alt=${item.name}>` : ''}
  <span class="item-name">${item.name}</span>
</li>

The Unassigned section

The Unassigned section holds the unboxed chips at the bottom of the page. It only appears when at least one item is unassigned (an empty inventory shouldn’t waste vertical space on an empty heading), and it carries data-drop-target itself so that I can later drag an item back out of a box and into Unassigned — the same drop engine that handles dragging into a box handles dragging out.

This is also the only place this layout appears, so the styling for it earns its place here. A small uppercased heading reads as a section header rather than as content, and the chips stack vertically as full-width pills.

.unassigned{padding:0 16px;margin:8px auto 0;max-width:420px}
.unassigned h2{font-size:.85rem;color:var(--muted);font-weight:600;margin:8px 0;text-transform:uppercase;letter-spacing:.05em}
.items-list{list-style:none;padding:0;margin:0;display:flex;flex-direction:column;gap:6px}
.items-list .item{display:flex;align-items:center;gap:8px;padding:10px 14px;background:var(--card);border-radius:8px;color:var(--fg)}

The ids that survive the filter are sorted alphabetically by name before they hit the template. The store doesn’t preserve a meaningful order on its own — insertion order is whatever I happened to type — and seeing the same item land in a different slot every time I open the app would be its own small kind of “where is it?” Sorting by name gives me a stable index.

function unassignedSectionTemplate(){
    const itemsTable = store.getTable('items');
    const queryU = ui.searchQuery.trim().toLowerCase();
    const unassignedIds = Object.keys(itemsTable)
        .filter(id => {
            if(itemsTable[id].boxId) return false;
            return !queryU || itemsTable[id].name.toLowerCase().includes(queryU);
        })
        .sort((a, b) => itemsTable[a].name.localeCompare(itemsTable[b].name));
    if(!unassignedIds.length) return '';
    return html`
      <<unassigned-section-markup>>
    `;
}

<section class="unassigned" ?data-drop-target=${ui.dragEnabled}>
  <h2>Unassigned</h2>
  <ul class="items-list">
    ${unassignedIds.map(id => itemTemplate(id, itemsTable[id]))}
  </ul>
</section>

Chips inside a box

Once an item lands in a box, the same chip appears again — but this time crammed in alongside its siblings inside a box card. I want it smaller and flowing horizontally rather than stacking, because a box might hold a dozen of them and I don’t want the card growing taller for each one. So I override the Unassigned styling whenever a chip is rendered inside the boxes-list: same element, two contexts, two looks.

.items-in-box{
    flex:1;
    list-style:none;margin:0;padding:0;
    display:flex;flex-wrap:wrap;gap:4px;
}
.items-in-box .item{display:flex;align-items:center;gap:6px;padding:6px 10px;background:var(--bg);border-radius:6px;color:var(--fg);font-size:.9rem}

And the slot that puts the chips there — the render-box-items slot the box card (Add a box) left open for me. The itemMatches callback the box loop passes in is what makes search work later — it filters out the chips that don’t survive the current query, so a search for “screw” shows only screws even inside a box that also holds other things. The chips are sorted by name for the same reason the unassigned ones are: I want the same item to be in the same spot every time I look into the box.

<ul class="items-in-box">
  ${Object.keys(itemsById)
    .filter(iid => itemsById[iid].boxId === id && itemMatches(itemsById[iid].name))
    .sort((a, b) => itemsById[a].name.localeCompare(itemsById[b].name))
    .map(iid => itemTemplate(iid, itemsById[iid]))}
</ul>

The test for this drops two items into a box in reverse alphabetical order and asserts they render the right way round.

@testcase
def test_items_sorted_alphabetically_in_box(page):
    """Items inside a box appear in alphabetical order regardless
    of the order they were added."""
    clear_state(page)
    page.get_by_role("button", name="Add a box").click()
    page.get_by_label("Photo").set_input_files(files=[{
        "name": "workshop.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Photo preview").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    enable_drag(page)
    for item_name in ["Saw", "Hammer"]:
        page.get_by_role("button", name="Add an item").click()
        page.get_by_label("Item name").fill(item_name)
        page.get_by_role("button", name="Save").click()
        page.get_by_text(item_name).drag_to(
            page.get_by_role("button", name="Box workshop"))
    chips_in_box = page.locator(".boxes-list .items-in-box .item-name").all_inner_texts()
    assert chips_in_box == ["Hammer", "Saw"], \
        f"items not alphabetical in box: {chips_in_box}"
    print("  PASS: items sorted alphabetically in box")

Edit an item

Same gesture as for boxes — tap the chip, the form opens pre-filled, save overwrites. The mental model is “you tap a thing to change it” everywhere in the app; there’s no separate edit affordance to learn.

One subtlety the gesture would otherwise trip on: the chip is also the source of a drag-to-box gesture (cf. Drop an item into a box). The browser suppresses click when pointerdown and pointerup happen far enough apart, which is exactly the same threshold the drop engine uses to recognise a drag — so a real grab-and-drop never accidentally fires the edit click. The two gestures can share the element without a custom guard.

The fields the form lets me edit are name, image, and bgColor. Crucially not boxId — placement is set by dragging the chip into a box, not by typing into a field. So the submit handler is careful to read the existing row’s boxId and write it back unchanged. If I rename a screw, it stays in whatever drawer I put it in.

@testcase
def test_edit_item(page):
    """Tapping an item opens the form prefilled; saving overwrites the name."""
    clear_state(page)
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("Hammer")
    page.get_by_role("button", name="Save").click()
    page.get_by_text("Hammer").click()
    assert page.get_by_label("Item name").input_value() == "Hammer", \
        "form not prefilled with the item's current name"
    page.get_by_label("Item name").fill("Mallet")
    page.get_by_role("button", name="Save").click()
    assert not page.get_by_text("Hammer").is_visible(), \
        "old name still visible — edit may have created a duplicate"
    assert page.get_by_text("Mallet").is_visible()
    print("  PASS: edit item")

function openItemEdit(id, item){
    setUI({
        formOpen: 'item',
        itemForm: {
            name: item.name || '',
            image: item.image || '',
            bgColor: item.bgColor || '',
            editingId: id,
            nameError: false,
        },
    });
}

Delete an item

Mechanically identical to Delete a box: a danger-coloured button on the edit form, behind a confirm(). The only thing that’s simpler here is the cleanup — an item has no children to reparent, so it just goes. No transaction, no sweep.

${ui.itemForm.editingId ? html`
  <button type="button" class="danger" @click=${onItemFormDelete}>Delete</button>
` : ''}

@testcase
def test_delete_item(page):
    """Deleting an item removes it from the list."""
    clear_state(page)
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("Hammer")
    page.get_by_role("button", name="Save").click()
    page.get_by_text("Hammer").click()
    page.once("dialog", lambda d: d.accept())
    page.get_by_role("button", name="Delete").click()
    assert not page.get_by_text("Hammer").is_visible(), "item still listed"
    print("  PASS: delete item")

function onItemFormDelete(){
    const {editingId} = ui.itemForm;
    if(!editingId) return;
    if(!confirm('Delete this item?')) return;
    store.delRow('items', editingId);
    closeForm();
}

Items with photos

Standing in the workshop with a screw in my hand, I want to be able to glance at the chip and see “yes, that’s the one” — and for some items, the name doesn’t get me there fast enough. “3mm screw” looks like every other screw I own. But a tiny photo next to the name closes the gap immediately: I see the head, the thread, the rough size; I match it to what I’m holding.

This is the same image-upload story as for boxes, with one important difference: for an item, the photo is optional. Some things (“hammer”) really are findable by name alone, and forcing a photo for every USB cable would be tedious. So the chip renders the thumbnail when there is one, and just the name when there isn’t.

Nearly everything I need for this is already in place. The file input, the change handler, the fileToThumbnail pipeline, the preview, the conditional render of the chip’s <img> — all that was wired in Add an item. What this chapter actually adds is small: the test that exercises the pipeline end-to-end, and the CSS rule that sizes the chip thumbnail.

The test uses a 1×1 PNG as the fixture: small enough that I can embed it inline as hex in the test runner, real enough to ride the load-resize-store-render path all the way through. The rendered <img> carries alt={item.name} so the test can find it by accessible name, no inspection of the data-URL itself.

@testcase
def test_add_item_with_image(page):
    """An item saved with an image renders that image in its chip."""
    clear_state(page)
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("Hammer")
    page.get_by_label("Image").set_input_files(files=[{
        "name": "hammer.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Image preview").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    assert page.get_by_role("img", name="Hammer").is_visible(), \
        "image not rendered for the item"
    print("  PASS: add item with image")

The thumbnail has to be small enough to fit in a chip without pushing the name off the line — 24 pixels is about the size of the surrounding text. Cropped to a square so all chips line up visually, even if my source photo was portrait.

.item-thumb{width:24px;height:24px;border-radius:4px;object-fit:cover;flex-shrink:0}

Items with background colour

Photos work for the items that earn one, but I want a second axis to scan by — and one that costs nothing to apply. A solid background tint on a chip lets me paint everything electrical the same blue, every workshop fastener the same red, and the page reads like a colour-coded legend before I’ve focused on any single word.

Two things shape the feature. One: the colour is optional — most items don’t need one, and the chip should look unchanged until I deliberately tint it. Two: once I’ve used a colour, I want it back with a single tap. Pulling a precise hex out of the browser’s colour picker every time I add a screw would defeat the point; the second screw should match the first by recognition, not by retyping.

@testcase
def test_item_background_colour(page):
    """A chosen colour paints the chip, and the colour is offered
    as a one-tap shortcut on the next item."""
    clear_state(page)
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("Hammer")
    page.get_by_label("Background colour").fill("#ff0000")
    page.get_by_role("button", name="Save").click()
    bg = page.get_by_text("Hammer").evaluate(
        "el => getComputedStyle(el.closest('li.item')).backgroundColor")
    assert bg == "rgb(255, 0, 0)", \
        f"chip not painted with the chosen colour: {bg}"
    page.get_by_role("button", name="Add an item").click()
    page.get_by_role("button", name="Use colour #ff0000").click()
    assert page.get_by_label("Background colour").input_value() == "#ff0000", \
        "shortcut didn't apply the colour to the picker"
    print("  PASS: item background colour")

A third concern lands on the chip itself. The dark theme’s near-white default foreground would disappear against any pale tint, and the eye’s outsized sensitivity to green means even a mid-bright green is light enough to drown out a near-white text on top. So the chip render picks a contrasting foreground from whatever I chose, and the rest of the app keeps treating its foregrounds as the theme says.

@testcase
def test_chip_text_adapts_to_tint(page):
    """The chip text picks a contrasting colour against
    whatever tint sits behind it — pale, mid-bright
    chromatic, or near-black."""
    clear_state(page)
    cases = [
        ("Snow", "#ffffff", "rgb(17, 17, 17)"),
        ("Cordelettes", "#22aa22", "rgb(17, 17, 17)"),
        ("Inkwell", "#111122", "rgb(255, 255, 255)"),
    ]
    for name, bg, expected_fg in cases:
        page.get_by_role("button", name="Add an item").click()
        page.get_by_label("Item name").fill(name)
        page.get_by_label("Background colour").fill(bg)
        page.get_by_role("button", name="Save").click()
        actual = page.get_by_text(name).evaluate(
            "el => getComputedStyle(el.closest('li.item')).color")
        assert actual == expected_fg, \
            f"{name} on {bg}: expected text {expected_fg}, got {actual}"
    print("  PASS: chip text adapts to tint")

The plumbing under the colour was wired ahead of time. The schema reserves a bgColor cell on every item row (Store schema), the submit handler in the form reads and writes it, Edit an item pre-fills it, and the chip render in the chip applies it as inline background and color styles — the latter computed by readableForeground below. What this chapter adds is the part the user touches: the picker, the swatch shortcuts, the readability rule, and the styling to match.

The WCAG relative-luminance formula does the work. Convert each sRGB channel out of gamma encoding, weight by the eye’s sensitivity (green carries the bulk of the luminance), and threshold at the crossover point where contrast against black equals contrast against white — about 0.179 on the 0…1 scale. Below that, a light foreground wins; above, a dark one. The two tones the rest of the app already uses — #111 and #fff — slot straight in.

function readableForeground(hex){
    const h = hex.replace('#', '');
    const channel = i => {
        const c = parseInt(h.substr(i, 2), 16) / 255;
        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
    };
    const L = 0.2126 * channel(0) + 0.7152 * channel(2) + 0.0722 * channel(4);
    return L > 0.179 ? '#111' : '#fff';
}

The shortcuts come straight from the store — every distinct bgColor cell currently in use, lowercased and deduplicated. I don’t bother caching this across renders: the items table is small, the set operation is cheap, and “what colours have I used so far” is exactly the live answer the user wants.

function usedItemColours(){
    const items = store.getTable('items');
    const seen = new Set();
    for(const id of Object.keys(items)){
        const c = (items[id].bgColor || '').toLowerCase();
        if(c) seen.add(c);
    }
    return [...seen].sort();
}

Both the picker’s @input and a swatch’s @click route the chosen colour through the same setter so the form state has a single ingress — and the “no colour” exit at the head of the swatch row routes through it too, with the empty string.

function setItemFormColour(value){
    setUI({itemForm: {...ui.itemForm, bgColor: value || ''}});
}

The markup pours into the slot the form reserved for it. The picker falls back to the browser’s neutral default when no colour has been chosen yet, so an unpainted item never shows a meaningful colour in the input until the user picks one.

<label>Background colour
  <input type="color" .value=${ui.itemForm.bgColor || '#000000'}
         @input=${e => setItemFormColour(e.target.value)}>
</label>
<div class="colour-swatches" role="group" aria-label="Recently used colours">
  <button type="button" class="colour-swatch colour-none"
          aria-label="No colour"
          @click=${() => setItemFormColour('')}></button>
  ${usedItemColours().map(c => html`
    <button type="button" class="colour-swatch"
            style=${`background:${c}`}
            aria-label="Use colour ${c}"
            @click=${() => setItemFormColour(c)}></button>
  `)}
</div>

The swatches are circles big enough to read as taps on a phone. The “no colour” head wears a diagonal slash so it doesn’t blur into another dark shade in the row.

.colour-swatches{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}
.colour-swatch{
    width:28px;height:28px;border-radius:50%;
    border:2px solid #00000033;cursor:pointer;padding:0;
}
.colour-swatch.colour-none{
    background:transparent;border:2px solid var(--muted);
    background-image:linear-gradient(45deg,transparent 45%,var(--muted) 45%,var(--muted) 55%,transparent 55%);
}

Unique item names

An item’s name is its identity to me. It’s what I type when I’m looking for it later, and it’s the answer the app gives back when I find it (“the 3mm screws are in the workshop box”). If I accidentally let two items end up called “hammer”, then searching for “hammer” returns two answers, neither obviously preferable to the other, and the search becomes useless for that name. So the app needs to actively prevent duplicates rather than let me blunder into them.

My instinct is to be lenient about what counts as “the same name”: “hammer”, “Hammer”, and “Hammer " (with a trailing space I didn’t notice) should all collide. And the user-facing message has to actually appear — silently dropping the save would leave me staring at the form wondering why nothing happened.

There’s one edge case the comparison has to allow for: an item being edited has to be allowed to “duplicate” its own current name. If I’m just changing a photo and leave the name alone, the form is technically asking “is there an item called X?” and the answer would be “yes, this one” — but that’s me, not a conflict. So the duplicate check excludes the row being edited.

The check itself was already written ahead in Add an item, because the submit handler that lives there is what calls it. All I add here is the visible side: an alert that drops into the form when ui.itemForm.nameError is set, and the styling that makes it look like an error rather than a regular caption.

${ui.itemForm.nameError ? html`
  <p class="form-error" role="alert">An item with this name already exists.</p>
` : ''}

.form-error{margin:0;color:#e94560;font-size:.85rem}

@testcase
def test_duplicate_item_name_rejected(page):
    """Saving an item with a name that already exists shows an error
    and does not create a duplicate row."""
    clear_state(page)
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("Hammer")
    page.get_by_role("button", name="Save").click()
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("Hammer")
    page.get_by_role("button", name="Save").click()
    assert page.get_by_role("alert").is_visible(), \
        "duplicate-name error not shown"
    # Form is still open (Save did not commit)
    assert page.get_by_label("Item name").is_visible()
    # Only the original Hammer chip exists
    assert page.get_by_text("Hammer", exact=True).count() == 1
    print("  PASS: duplicate name rejected")

Drop an item into a box

Now that I have boxes on one side and unboxed items on the other, I need a way to put one inside the other. The gesture I want is the one any user would guess: grab the item, drop it on the box. This is also the moment the app stops being “two lists side by side” and starts being an inventory.

The first thing the gesture has to deal with is that I want it to work on a phone. Native HTML5 drag-and-drop is a non-starter here — it doesn’t fire on touch devices, which is half my target use. So instead of native drag I use pointer events, which behave identically whether the pointer is a mouse, a stylus, or a finger. The geometry work — detecting which target the pointer is over, deciding whether the gesture counts as a drag or a tap — is identical to what Condorcet needed, so it lives in a shared engine rather than in this doc.

What I do supply is the wiring: I tell the engine which elements are sources (the item chips, marked with data-draggable) and which are targets (the box cards and the Unassigned section, both marked with data-drop-target), and I listen for the dropzone:drop event the engine fires when a drag lands. The handler reads the dropped chip’s item id off the source element, the destination box id off the target, and writes the new boxId cell. TinyBase’s listener does the rest — the chip re-renders inside its new container on the next tick.

@testcase
def test_drop_item_into_box(page):
    """Drag an unassigned item onto a box → the item leaves the Unassigned area."""
    clear_state(page)
    page.get_by_role("button", name="Add a box").click()
    page.get_by_label("Photo").set_input_files(files=[{
        "name": "workshop.png",
        "mimeType": "image/png",
        "buffer": MINIMAL_PNG,
    }])
    page.get_by_role("img", name="Photo preview").wait_for(state="visible")
    page.get_by_role("button", name="Save").click()
    page.get_by_role("button", name="Add an item").click()
    page.get_by_label("Item name").fill("Hammer")
    page.get_by_role("button", name="Save").click()
    enable_drag(page)
    page.get_by_text("Hammer").drag_to(
        page.get_by_role("button", name="Box workshop"))
    assert page.get_by_text("Hammer").is_visible(), "Hammer disappeared after drop"
    assert not page.get_by_role("heading", name="Unassigned").is_visible(), \
        "Unassigned heading still visible — Hammer didn't move into the box"
    print("  PASS: drop item into box")