Skip to content

Instantly share code, notes, and snippets.

@doolin
Created September 25, 2026 12:24
Show Gist options
  • Select an option

  • Save doolin/05e2188e2bfd594acfbda26784f78688 to your computer and use it in GitHub Desktop.

Select an option

Save doolin/05e2188e2bfd594acfbda26784f78688 to your computer and use it in GitHub Desktop.
Quickbar: a fixed-grid sidebar launcher for hand-curated links. Portable, framework-neutral specification.

Quickbar — a fixed-grid sidebar launcher for hand-curated links

A portable specification, version 1.0, 2026-09-24. Written from a widget in daily use since March 2026, so that it can be built in any web application on any framework, by a reader with no access to the original.

How to read this document

  • §1 to Appendix F is the product: behaviour, data, interface, and the reasons behind each. It names no framework, library, or file. A build that meets these sections is the Quickbar.
  • The last section, "Lessons learned building it in Rails", is for a build on Rails and Hotwire, the stack of the reference implementation. It records what cost the most to learn there. Readers on other stacks can skip it, though several lessons (7, 13, 14) apply anywhere.

Requirements FR-001 to FR-021 describe what the reference implementation already does and define the product. FR-022 to FR-028 are improvements a new build should make; the reference does not have them yet (§9.2 explains both).


1. Executive Summary

1.1 Overview

The Quickbar is a persistent sidebar widget holding up to 100 links entered by hand, arranged as 10 pages of 10 numbered slots. It renders on every page of the application, so the links are one click away wherever the user is.

1.2 Problem Statement

Some links have to be opened by a person. The host refuses automated fetches, or needs a login, or the page is only useful in a browser. Those links cannot go into a bookmark manager that fetches, summarises and tags what it stores, because every step of that pipeline fails for them. Kept in browser bookmarks instead, they live outside the application the user works in, unordered and unlabelled at the group level, and they do not follow the user between machines or browsers.

1.3 Proposed Solution

A sidebar launcher with a fixed grid of numbered slots, filled by hand and grouped into ten titled pages. Deliberately manual: no fetching, no title scraping, no favicon lookup. The links are here because fetching them fails.

1.4 Expected Outcome

The user's hand-opened links live inside the application, survive a change of browser or machine, and are reachable from any page in at most two clicks.

1.5 Decision Request

Approve this document as the Quickbar specification, including the adding and editing improvements in §9.2 (FR-022 to FR-028).


2. Background and Context

2.1 Current State

One implementation exists, in a single-user personal dashboard, in daily use since March 2026. It is built on Rails and Hotwire with SQLite, and the last section of this document records what building it there taught.

2.2 Historical Context

The widget was built in five small changes over eleven days, then left alone for six months. After that, three improvements came from daily use: tooltips on the page tabs, editors that open at the link being edited, and move controls for reordering.

One early decision shaped everything after it: the sidebar hosts independent boxes, and the Quickbar is one of them, not the owner of the sidebar. A quote box and a separate links strip were later added to the same application without touching the Quickbar.

2.3 Trigger for This Work

A second application needs a Quickbar. Earlier versions of this document described the widget as its first application builds it, including that framework's classes, routes and templates. This version describes what the widget is, so it can be built from the document alone.

2.4 Related Work

  • A top-of-page links strip (the Thinbar, in the reference application): a flat, always-visible row of the handful of links needed constantly. The boundary between the two is capacity. The Quickbar holds up to a hundred links in titled pages, addressed by slot, which is worth having for a curated working set and worth nothing for six links. The strip holds as many as fit on one line, in order, with no grouping.
  • A bookmark manager: the automated counterpart, which fetches, summarises, tags and searches. Anything a bookmark manager can ingest does not belong in the Quickbar.

2.5 Relevant Research and Evidence

No formal research. The design rests on one observation and one measurement:

  • A fixed grid makes each link's place memorable in a way a growing list never is. A link at page 3, slot 2 stays there until the user moves it, so the hand learns where it is. The cap on the grid is what makes that possible: a list that grows without bound keeps shifting.
  • A sizeable share of the original user's daily reading sits behind hosts that refuse automated fetches. That, not a preference for manual entry, is why the widget refuses to fetch.

Six months of daily use by its author is the rest of the evidence. That is strong evidence of fit for one user and weak evidence about anyone else.


3. Goals and Non-Goals

3.1 Goals

  • Keep the user's hand-opened links inside the application, durably.
  • Reach any of them in at most two clicks, page tab then link, from any page.
  • Keep links and page titles across browsers and machines.
  • Stay small enough that a change takes an afternoon.

3.2 Non-Goals

  • No fetching of any kind. No title scraping, favicon lookup, dead-link checking, or preview generation.
  • No tagging, search or ranking. Position in the grid is the whole organising scheme.
  • No drag-and-drop. Reordering is in scope, by move controls (FR-018). The drag gesture is not: a drop target here is a narrow row in a narrow column, and a keyboard path has to exist anyway.
  • No growth past 10 by 10. The cap forces curation and keeps positions memorable.

Multi-user support is not a non-goal. The reference is single-user because its application is; nothing in the design depends on that. §10.6 sets out what a multi-user build must do.

3.3 Success Definition

The user stops keeping a parallel set of browser bookmarks for these links.

3.4 Future Work

  • Moving a link to another page. The move controls answer "which way"; a cross-page move has to answer "which page, which slot". Not yet asked for.
  • A "recently used" hint, if fixed positions stop being memorable at full capacity.
  • Visible page labels on the tabs, if tooltips turn out not to be enough (Q-01).

4. Stakeholders

In the reference, one person is product owner, engineer and only user. A new build should name its own owner and decide whether its users need the multi-user work in §10.6 before the first release.


5. Users and Personas

5.1 Primary Persona

  • Role: the application's user, at a desk, mid-session.
  • Context: working in the application; needs a site that has to be opened by hand.
  • Goals: get to it in one or two clicks without leaving the application.
  • Pain points: browser bookmarks are unordered, unlabelled at the group level, and invisible from inside the application.
  • Frequency of use: several times a session.

5.2 Secondary Persona

  • Role: an engineer, or a coding agent, asked to change the widget.
  • Needs: the two rules that no single file makes obvious. A slot holds at most one link, enforced by the store, so a write into a taken slot fails. And content (links, titles) lives on the server while view state (the selected tab) lives in the browser, so moving titles into browser storage would lose them across machines.

5.3 Accessibility Considerations

  • Page tabs show a bare digit, so each tab's accessible name must include both the number and the title (FR-014).
  • The row's actions must be reachable without a pointer (FR-027).
  • Form fields must have labels, not only placeholders (FR-026).
  • The page-title field is edited in place; it must have an accessible name and announce itself as editable (FR-008).

6. User Needs and Jobs to Be Done

6.1 User Needs

  • Somewhere inside the application for links only a person can open.
  • Groups with readable names, not just numbers.
  • A stable address for each link, so muscle memory works.

6.2 Jobs to Be Done

  • When I hit a site I will need again and it cannot be fetched, I want to park it inside the application, so I stop losing it in my browser's bookmarks.
  • When I come back to a page of links after a week, I want to see what each page is for without opening all ten.
  • When I reload, I want the page I was using to still be selected.
  • When the order of a page has drifted, I want to fix it without retyping links.

6.3 Pain Points in Current Workflow

The page titles are only visible for the selected page; the tabs show a digit. Tooltips (FR-012) are the cheap fix. Whether they are enough is Q-01.


7. Scope

7.1 In Scope

The widget: the slot grid, page tabs and their tooltips, page titles, adding, editing, removing and reordering links, remembering the selected tab, and the visual contract.

7.2 Out of Scope

The layout that hosts the sidebar, and any other widget in it.

7.3 Assumptions

Listed with their consequences in Appendix F. The three that matter most: one writer at a time; 100 slots is enough; a sidebar region already exists.

7.4 Constraints

  • The store must enforce uniqueness of (page, slot). Validation in application code alone turns concurrent writes into a race (A-08).
  • Moves that exchange two links must be atomic (FR-020), which interacts with how the store checks unique constraints (§10.5).

8. Use Cases and User Stories

8.1 Primary Use Cases

  1. Add a link: click an empty slot, or the header +; enter the URL and the link text; save.
  2. Open a link: select a page tab; click the link.
  3. Retitle a page: click the title under the tabs; type; press Enter or click away.
  4. Edit a link: use the row's edit control; change the text or URL; save.
  5. Remove a link: use the row's remove control; confirm.
  6. Reorder: use the row's up or down control until the link is where it belongs.

8.2 User Stories

  • As a user, I want to add a link by hand, so a site that cannot be fetched still has a home.
  • As a user, I want to name each page, so ten pages stay navigable.
  • As a user, I want my selected page remembered, so a reload costs nothing.
  • As a user, I want to move a link a slot at a time, so a drifted order can be fixed without editing two links.

8.3 Edge Cases

  • Full page: the header + on a page with all ten slots filled declines with a message. Clicking an empty slot cannot reach this case.
  • Taken slot: a write into an occupied slot fails at the store, never overwrites.
  • Blank title: clearing a title stores no title, and the page shows its placeholder, Page N.
  • Stale stored tab: a remembered tab outside 1 to 10, or unreadable, falls back to page 1.
  • Empty grid: every slot shows a placeholder that is itself the add control, so the empty state is the entry point.
  • Move at an end: the control pointing out of the grid is disabled, and the server refuses the move too, so a hand-made request cannot push a link out of the grid.
  • Move into a gap: the link takes the empty slot and leaves a gap behind. Repeated presses carry a link toward where it is going.
  • Unsafe URL scheme: a URL whose scheme could run script is refused (FR-025).

8.4 Failure Scenarios

Every write must either succeed and show its result, or fail and say so where the user is looking: inside the form or field that made it (FR-022, FR-024). The reference falls short here (§9.2).


9. Functional Requirements

9.1 Requirements

FR-001 to FR-021 describe the widget as it exists and define the product. FR-022 to FR-028 are improvements a new build should make. The reference does not have them yet.

Grid, pages and links

  • FR-001: The widget renders in the application's sidebar on every page, without each page opting in.
  • FR-002: Links are organised as 10 pages numbered 1 to 10, each with 10 slots numbered 1 to 10. Exactly one page is shown at a time.
  • FR-003: At most one link occupies a given (page, slot). The store enforces this.
  • FR-004: A link has a name (its visible text, at most 100 characters) and a URL (at most 2048 characters). Both are required and both are entered by the user; neither is derived from the target.
  • FR-005: An empty slot shows a placeholder. Clicking it opens the add form for that exact page and slot.
  • FR-006: The header + opens the add form at the first empty slot of the current page, positioned at that slot. On a full page it declines with a message.
  • FR-007: A link can be edited (name and URL) and removed. Removal asks for confirmation and names the link.
  • FR-008: Each page has an optional title of at most 40 characters, shown under the tabs for the selected page and edited in place. It saves on Enter and when the field loses focus.
  • FR-009: A page without a title shows the placeholder Page N.
  • FR-010: The selected page survives a reload, per browser.
  • FR-011: The widget is a self-contained box, so the sidebar can hold other widgets beside it.

Tab tooltips

  • FR-012: Each tab has a tooltip giving its page's title, so titles can be read without selecting each tab.
  • FR-013: A page with no title, a blank one, or one of only spaces, gets the tooltip Page N. A tab never has an empty tooltip.
  • FR-014: A tab's accessible name is Page N: <title>, or Page N when untitled. It is not the bare title: the visible label is the digit, and an accessible name must contain the visible label (WCAG 2.5.3, Label in Name).
  • FR-015: Renaming a page updates its tab's tooltip and accessible name without a reload.

Adding and editing

  • FR-016: The add form and the editor open at the slot they act on, not at a fixed place in the widget. A panel near the edge of the window stays fully on screen. Only one panel is open at a time. Escape closes it and returns focus to the control that opened it.
  • FR-017: Form text meets a 7:1 contrast ratio against its background. Typed values are darkest, then titles, then labels. Placeholders are the one exception: they may be lighter, at no less than 4.5:1, because they are replaced as soon as the user types. Each input sets its own text colour rather than inheriting it from where it is placed.

Reordering

  • FR-018: A link moves to the adjacent slot from its own row, without opening the editor. The move steps to the adjacent slot number, not the next link: empty slots are visible, so stepping into a gap is what the user sees and expects. If the adjacent slot holds a link, the two exchange places.
  • FR-019: An exchange leaves both links in the grid. This is the case an edit cannot do, because the uniqueness rule refuses the first half of a two-step swap.
  • FR-020: A move is atomic. A failure part-way leaves both links where they started, and no link is ever visible outside slots 1 to 10.
  • FR-021: A move updates the widget without a full page load and returns focus to the moved link's control, so the same control can be pressed again. At an end of the grid that control is disabled and focus goes to the opposite one.

Improvements for a new build

  • FR-022: A failed add or edit keeps the form open, keeps what the user typed, and shows the error inside the form.
  • FR-023: A successful add or edit updates the affected row in place and closes the form, without a full page load. The row shows the new name and URL immediately.
  • FR-024: A failed page-title save puts the previous title back and says so at the field. The field refuses input past 40 characters, rather than letting the save fail on the server.
  • FR-025: A URL must be absolute http or https, or a path within the application (starting with /). Any other scheme, javascript: in particular, is refused on save.
  • FR-026: Every field in the add and edit forms has a visible label, not only a placeholder. The URL field comes first and takes focus when the form opens, because pasting a URL is how most links arrive.
  • FR-027: Each row's actions (move, edit, remove) are reachable by keyboard, in a documented order, and visible whenever one of them or the row's link has focus.
  • FR-028: The server decides which slot the header + fills, or checks the slot the browser proposes, so the browser's view of free slots cannot be stale between rendering and saving.

9.2 Adding and editing: what the reference does, and what to do better

This is where six months of use taught the most.

Improvements already in the reference, to keep:

  1. The form opens where the user is looking (FR-016). The first version put the editor at the foot of the sidebar whichever of the hundred slots was clicked, so the user's eye had to leave the link to find its form.
  2. The header + opens at the slot it will fill (FR-006). Before, it opened detached from any slot, and in one version off screen.
  3. Clicking an empty slot opens the form for that slot (FR-005). The empty placeholder is the add control, so the empty state is the entry point.
  4. Escape closes, focus returns (FR-016). Escape is claimed only when a panel is open, so a confirmation dialog above it gets the key first, and a composing input method's Escape is ignored.
  5. Reordering replaced "edit it to move it" (FR-018 to FR-021). Moving a link by editing its slot number fails whenever the target is taken, which is exactly when the user wants to move it.
  6. Focus survives a move (FR-021), so a link can be walked several slots by pressing the same key.
  7. Legible forms (FR-017), after the labels measured below the contrast target and the inputs inherited their colour from wherever they were placed.
  8. The edit form changes name and URL only. A link's page and slot change through the move controls, never by typing a number.

Improvements a new build should make (FR-022 to FR-028):

  1. Errors inside the form (FR-022). The reference reloads the page and shows a validation error as a page-level message, and the typed input is lost.
  2. Update in place (FR-023). The reference reloads the page after every add, edit and remove. Only reordering updates in place.
  3. Honest title saves (FR-024). The reference sends the title and ignores the answer. A title longer than 40 characters is refused by the server, while the screen, and the tooltip, show the new text until the next reload.
  4. Safe URLs (FR-025). The reference accepts any text as a URL. That is tolerable when the only person who can enter a link is the only person who can see it, and not otherwise.
  5. Labelled fields (FR-026). The reference's add form has placeholders and no labels; its edit form has labels.
  6. Keyboard reach, stated (FR-027). In the reference the actions appear when the row's link has keyboard focus, so Tab from the link reaches them. That works by accident of the styling, not by design, and nothing tests it.
  7. One owner for "the next free slot" (FR-028). In the reference the browser works it out from a map rendered with the page. The server has its own helper that answers a different question (one past the highest slot) and is not used.
  8. One panel at a time, in both directions (FR-016). The reference closes an open editor when the add form opens, but opening an editor closes nothing, so the add form and several editors can be open together.

9.3 Data Entry and Validation

Field Required Rule On failure
Link name yes 1 to 100 characters Error in the form (FR-022)
Link URL yes at most 2048 characters; http, https or /path (FR-025) Error in the form
Page yes integer 1 to 10 Refused; not user-entered
Slot yes integer 1 to 10; free on that page Refused; the form says the slot was taken
Page title no at most 40 characters; blank or spaces stored as no title Field keeps the old title and says so (FR-024)

9.4 Permissions

Single-user in the reference: whoever can use the application can change the widget. A multi-user build scopes every read and write to the owner (§10.6).

9.5 States

Thing States
Slot empty, filled
Page title untitled (no record, or blank), titled
Panel closed, add form open at a slot, editor open at a link
Move control enabled, disabled (at an end of the grid)
Row actions hidden, shown (hover, or focus within the row)

At most one panel is open at a time. Opening one closes any other.


10. Detailed Requirements by Surface

10.1 User Interface

The box sits in the sidebar with a header (the word "Quickbar" and a + control), a tab strip, the selected page's title, and the selected page's ten slots. The reference lays the ten tabs out as two rows of five.

Tabs are small numbered buttons. The selected tab is the only saturated element in the widget. Each carries the tooltip and accessible name of FR-012 to FR-014.

The page title sits under the tabs, centred, edited in place. When empty it shows Page N in a muted, italic style.

A filled slot shows the link text, truncated with an ellipsis. Its actions are two move controls (up, down), an edit control and a remove control, shown on hover and on keyboard focus. Removal is muted, not red: in a tool used by its owner, a red button is noise rather than a warning.

An empty slot shows a faint dash. It highlights on hover and opens the add form when clicked.

Panels (the add form and the editor) open directly below the slot, over the page content, flipped to align right when they would leave the window. The add form has URL and name fields, Add and Cancel. The editor has a title, name and URL fields, Save and Cancel.

Empty, error and loading states:

  • Empty grid: ten dashes per page; the dashes are the add controls.
  • Error: inside the form or field that caused it (FR-022, FR-024).
  • Loading: none needed; every operation is small. A control should not accept a second press while its first request is in flight.

10.2 Interface

Five operations. How they are exposed (REST routes, RPC, form posts) is the builder's choice; the reference uses REST-style routes.

Operation Input Success Failure
Create link name, URL, page, slot the new row, or an updated widget validation errors, form kept open
Update link id; name, URL the updated row validation errors, form kept open
Remove link id the emptied slot not found
Move link id; direction earlier or later the updated widget, and which control to focus refused for any other direction, and at an end of the grid
Set page title page number; title the stored title validation error, e.g. too long

Notes:

  • Direction words are axis-neutral: earlier and later, not up and down, so the same operation serves a vertical list and a horizontal strip.
  • Set page title is keyed by page number, not by a record id. A page has no record until it is first titled, so the operation creates or updates.
  • Move returns enough to restore focus: the moved link and the direction pressed. The control that was pressed no longer exists once the widget is re-rendered.
  • An edit form for one link is fetched when the editor opens, or rendered in the browser from data already on the page. Either works.

10.3 Data Model

Two record types, with no relation declared between them. They meet on the page number.

Link

Attribute Type Rule
id identifier
name text required, at most 100 characters
url text required, at most 2048 characters, scheme rule of FR-025
page integer required, 1 to 10
slot integer required, 1 to 10
created, updated timestamps

Unique: (page, slot), enforced by the store.

Page title

Attribute Type Rule
page integer required, 1 to 10, unique
title text optional, at most 40 characters; blank stored as none
created, updated timestamps

A page-title record is created the first time its page is titled. Clearing the title keeps the record with no title.

View state (the selected tab) lives in browser storage, per browser, and is never sent to the server.

10.4 Rendering and Behaviour

  • The widget needs all links and all titles to render: at most 110 records. Load them once per page.
  • The browser shows one page at a time and switches pages without a request.
  • Opening a panel closes any other. Closing a panel returns focus to the control that opened it, if that control still exists.
  • After a move, the widget is re-rendered and focus goes to the moved link's control for the same direction, or the opposite one if that is now disabled. A control hidden until hover cannot take focus, so the row has to be shown before focus is placed.
  • If one add form is shared between all slots and moved into the slot that was clicked, clicks inside the form will reach the slot's own click handler. Those clicks must not reopen or reset the form. This is a consequence of the shared-form approach and will appear in any build that takes it.

10.5 Moving and Exchanging Under a Unique Constraint

An exchange writes two slots that are each other's. Many stores check a unique constraint on every row write, so the obvious two writes fail on the first:

set A.slot = B.slot   -- collides: B still holds that slot
set B.slot = A.slot

Two ways to do it:

  1. Deferred constraint. If the store can defer the unique check to the end of the transaction (PostgreSQL can, for a constraint declared deferrable), write both slots in one transaction in either order.
  2. Parking value. If it cannot (SQLite cannot; it defers only foreign keys), move one row to a value no real row can hold, such as the negation of its slot, then write the other row, then land the first. All three writes run in one transaction, so the parked value is never visible. The parking write skips validation, since the value is invalid on purpose; the two final writes validate.

Either way, a test that stays green with the parking step removed is not testing the exchange (§20).

10.6 Multi-User

The reference has never done this. It is a design sketch, not a tested path.

  • Every link and every page title belongs to a user.
  • Both uniqueness rules become per-user: (user, page, slot) for links and (user, page) for titles. As global rules, the second user to fill page 1 slot 1 is refused, and the second user cannot title page 3 at all. Add the user to both rules before a second user exists; afterwards it is data repair.
  • Page-title records are created lazily, so the create-or-update must be scoped to the user. Unscoped, one user's first title silently claims the record another user then edits. Nothing fails loudly when this is wrong.
  • The 100-link cap becomes per user.
  • Every read and write is scoped, including the free-slot calculation and the occupant lookup inside a move, which otherwise could exchange a link with another user's.
  • FR-025 becomes mandatory before release, and so does FR-027.

11. Non-Functional Requirements

  • Performance: at most 110 small records read per page render, on every page. Cheap at this size, and the widget's one global cost. Cache the rendered widget, or load it after the page, if the application's pages are otherwise very fast.
  • Reliability: no background work and no retries. Every write reports its result (FR-022 to FR-024).
  • Security: request forgery protection on every write; the URL rule of FR-025; link text escaped when rendered.
  • Accessibility: §5.3, FR-014, FR-026, FR-027. Target WCAG 2.2 AA.
  • Observability: none required.
  • Internationalisation: the reference is English-only. Page N and the control labels are the strings to translate.

12. Experience Requirements

Dense, quiet and subordinate to the page: small type, muted greys, controls revealed on hover and focus, no animation. The selected tab is the only saturated element. The widget must not compete with the page it sits beside.


13. Data Requirements

  • Inputs: hand entry only.
  • Outputs: none. Nothing else reads these records.
  • Retention: until the user removes them.
  • Migration: none. A new build starts empty.

14. Analytics and Measurement

None. Success (§3.3) is the user's judgement.


15. Dependencies

A new build needs four things from its platform:

  1. HTML rendered for every page, with a sidebar region the widget can occupy.
  2. A way to update part of a page without a full load (FR-021, FR-023).
  3. A store that enforces a composite unique constraint.
  4. Browser storage for the selected tab.

Nothing else. No JavaScript bundler, drag library or CSS framework is needed.


16. Risks, Issues, and Mitigations

16.1 Risks

Risk Likelihood Impact Mitigation
The browser's view of free slots is stale when the form is saved Low for one user; real for several Low FR-028; the store's uniqueness rule refuses the write regardless
Silent save failures leave the screen and the store disagreeing Medium in the reference Low FR-022 to FR-024
100 slots fill up Medium Low Curate; growing the grid is a non-goal
An unsafe URL scheme is stored and clicked Low for one user; high otherwise High FR-025
Row actions hidden until hover are unreachable by keyboard Depends on build Medium FR-027, with a test

16.2 Open Issues

None beyond the open questions in §24.

16.3 Known Unknowns

Whether tooltips are enough for finding a page, or whether the tabs need visible labels (Q-01).


17. Alternatives Considered

17.1 Browser bookmarks

No build at all, but invisible from inside the application, no group labels, and not durable across machines without a sync account.

17.2 Fold into the bookmark manager

One model and search for free, but a bookmark manager is built around fetching and summarising, which these links refuse. They would be permanent second-class rows.

17.3 Browser storage for everything

No schema, but lost with the browser profile. Rejected for links and titles, chosen for the selected tab, where per-browser is the right scope.


18. Tradeoffs

The four decisions a new build keeps, or knowingly breaks:

  • Fixed 10 by 10 over unbounded: forces curation, costs flexibility.
  • Hand entry over enrichment: the only option that works for these links.
  • Split storage: content on the server, view state in the browser; each value in the store whose scope matches it.
  • On every page over an on-demand panel: always one click away, at the cost of a small read on every page.

A build that keeps these four is the Quickbar. One that drops any of them is a different product.


19. Rollout Plan

Ship FR-001 to FR-011 first; the rest are additive. No flags or migrations of existing data are needed. For a multi-user application, §10.6 comes before the first release, not after.


20. Testing and Validation

20.1 Test Strategy

  • Store level: the uniqueness rule refuses a write into a taken slot; an exchange succeeds and leaves both links in the grid; a failed exchange leaves both where they were.
  • Server level: every operation in §10.2, including a refused direction and a move at each end of the grid.
  • Browser level: page switching and the remembered tab; opening each panel at its slot; Escape and focus return; the shared add form not reopening on clicks inside it; focus after a move; keyboard reach of the row actions.

Three lessons from the reference's tests, each learned by breaking the code on purpose:

  • Remove the exchange's parking step and the exchange tests must go red with the collision it prevents. If they stay green, they are not testing the exchange.
  • A test that the row's actions close when focus leaves passed with the feature removed, because "closed" is also the state of a row nobody touched. Assert the open state first.
  • Browser tests built from hand-made event objects hid two real defects: they had the shape the code expected, not the shape a browser sends. Use real events.

20.2 Acceptance Criteria

Tooltips

  • AC-001: Given page 3 is titled "Vietnam refs", when I hover tab 3, then the tooltip reads "Vietnam refs".
  • AC-002: Given page 7 has no title, when I hover tab 7, then the tooltip reads "Page 7".
  • AC-003: Given I rename page 3, when I hover tab 3 without reloading, then the tooltip reads the new title.
  • AC-004: Given a screen reader reaches tab 3, then its accessible name is "Page 3: Vietnam refs".

Reordering

  • AC-005: Given a link at slot 6 and an empty slot 5, when I press up, then the link is at slot 5 and slot 6 is empty.
  • AC-006: Given links at slots 5 and 6, when I press up on the one at 6, then they have exchanged places and both are still in the grid.
  • AC-007: Given a link at slot 1, then its up control is disabled, and a request to move it earlier is refused.
  • AC-008: Given I press up, when the widget re-renders, then focus is on the same link's up control, or on its down control if the link reached slot 1.

Adding and editing

  • AC-009: Given I click empty slot 4 on page 2, then the add form opens directly below slot 4 with the URL field focused, and saving puts the link at page 2, slot 4.
  • AC-010: Given page 2 has slots 1 to 3 filled, when I press +, then the add form opens below slot 4.
  • AC-011: Given I submit the add form with a blank name, then the form stays open, my URL is still in it, and the error is shown in the form.
  • AC-012: Given I edit a link's name and save, then the row shows the new name without a page reload and the editor closes.
  • AC-013: Given I enter javascript:alert(1) as a URL, then the save is refused with an error in the form.
  • AC-014: Given the editor is open, when I press Escape, then it closes and focus is on the edit control that opened it.
  • AC-015: Given I type a 41st character in a page title, then the field does not accept it.
  • AC-016: Given keyboard focus is on a link, when I press Tab, then focus moves to that row's first enabled action, and the actions are visible.
  • AC-017: Given the add form is open, when I open a link's editor, then the add form closes; and given one editor is open, opening another closes the first.

21. Operational Readiness

No background work, no external calls, nothing to alert on.


22. Legal, Policy, and Compliance Review

The links are the user's own. A multi-user build stores personal data (each user's links) and should treat it like any other user content.


23. Resourcing and Delivery

The reference took five small changes for the core widget and about an afternoon each for tooltips, editor placement and reordering. A new build of FR-001 to FR-028 is a few days for one engineer.


24. Open Questions

ID Question Resolution
Q-01 Are tooltips enough for finding a page, or do the tabs need visible labels? Open
Q-02 Where should the free-slot calculation live? Answered for a new build by FR-028: the server decides or checks
Q-03 Should a failed title save be reported? Answered by FR-024: yes

25. Final Recommendation

Build FR-001 to FR-021 as the product and FR-022 to FR-028 as the lessons of its first six months. Treat §18 as what must not change, §10.5 as the part that is harder than it looks, and §10.6 as work that comes before a second user, not after.


Appendix A: User Journeys

A-1: Parking a link that cannot be fetched

The user hits a site they will want again. The sidebar is already in view.

  1. They hover the tabs to find the page whose title fits.
  2. They click an empty slot. The add form opens at that slot, URL field focused.
  3. They paste the URL, type a short name, save. The link is in the slot they clicked.

Alternative: the header + picks the first empty slot on the page and opens there. On a full page it says so and does nothing.

Exception: the save fails validation. The form stays open with the input kept and the error shown (FR-022).

A-2: Fixing a drifted order

A link added months ago is now the most used, at slot 7.

  1. The user hovers the row, or tabs to it. Its actions appear.
  2. They press up. The link moves to slot 6, exchanging with whatever was there, and the widget updates without a page load.
  3. Focus is still on the up control, so they press it again. At slot 1 the control is disabled and focus moves to the down control, which is how they know they have arrived.

A-3: Correcting a link

  1. The user opens the row's editor. It opens at the row.
  2. They fix the URL and save. The row updates and the editor closes (FR-023).
  3. Or they press Escape, the editor closes, and focus is back on the edit control.

Appendix B: Business Rules

  • BR-001: Page and slot are integers from 1 to 10.
  • BR-002: At most one link per (page, slot), enforced by the store.
  • BR-003: A link needs a name and a URL, both entered by the user.
  • BR-004: A URL is http, https, or a path within the application.
  • BR-005: A page title is optional, at most 40 characters, and blank is stored as none.
  • BR-006: A page-title record exists only once its page has been titled.
  • BR-007: Exactly one page is shown at a time.
  • BR-008: The selected page is per-browser state, not account state.
  • BR-009: Nothing about a link is ever fetched from its target.
  • BR-010: A link's page and slot change only by moving it, never by typing.

Appendix C: Glossary

Term Definition
Quickbar This widget
Page One of ten groups of ten slots, optionally titled
Slot One of ten numbered positions on a page, empty or filled
Panel The add form or the editor, opened at a slot
Exchange A move into a filled slot: the two links swap slots
Parking value A value no real slot can hold, used mid-exchange (§10.5)

Appendix D: Requirements Map

Requirement Section Acceptance
FR-001 to FR-011 §9.1, §10.1, §10.3 §20.1
FR-012 to FR-015 §9.1, §5.3 AC-001 to AC-004
FR-016, FR-017 §9.1, §9.2, §10.4 AC-009, AC-010, AC-014, AC-017
FR-018 to FR-021 §9.1, §10.4, §10.5 AC-005 to AC-008
FR-022 §9.2 AC-011
FR-023 §9.2 AC-012
FR-024 §9.2 AC-015
FR-025 §9.2, §10.6 AC-013
FR-026 §9.2, §5.3 AC-009
FR-027 §9.2, §5.3 AC-016
FR-028 §9.2 AC-010

Appendix E: Decision Log

ID Decision Reason
D-01 Fixed 10 by 10 grid Forces curation; positions stay memorable
D-02 Hand entry, no fetching The target hosts refuse automated access
D-03 The sidebar hosts independent boxes Later widgets join without touching this one
D-04 Selected tab in browser storage View state is correctly per-browser
D-05 Page titles on the server Content must survive a change of browser
D-06 Editors open at their slot The user's eye stays on the link being changed
D-07 Move controls, not drag-and-drop A narrow drop target; a keyboard path is needed regardless
D-08 A move steps to the adjacent slot, not the adjacent link Gaps are visible, so stepping into one is what the user expects
D-09 Axis-neutral directions, earlier and later One vocabulary for a vertical list and a horizontal strip
D-10 Exchanges are atomic, by deferred constraint or parking value The uniqueness rule refuses the obvious two writes

Appendix F: Assumption Log

ID Assumption If false
A-01 One writer at a time Two writers need conflict handling on links, and FR-028 becomes required
A-02 100 slots is enough The answer is curation. A build that disagrees is building a different product (D-01)
A-03 The links cannot be enriched by fetching Then they belong in a bookmark manager
A-04 Slot positions are memorable The case for a fixed grid rests on this. The "recently used" hint (§3.4) is the hedge
A-05 A sidebar region exists on every page Decide where the box goes before anything else here applies
A-06 Losing the selected tab is cheap It stays view state only; nothing else may be kept in browser storage
A-07 Nothing else reads these records A second reader would see the lazy page-title records (§10.3)
A-08 The store enforces the composite uniqueness rule Without it, FR-019 becomes a race rather than a transaction problem

Lessons learned building it in Rails

The reference implementation is Rails 8.1, SQLite, Turbo and Stimulus loaded through an import map with no JavaScript bundler, and Tailwind CSS compiled to a build file. These lessons are specific to that stack unless noted.

  1. One Turbo frame per row, inside the row. A single frame for the whole widget can only be positioned against the widget, which put every editor at the foot of the sidebar. A frame inside each <li>, with the <li> position: relative and the panel position: absolute; top: 100%, lets the browser place it with no computed coordinates.
  2. Closing a frame's editor means emptying the frame. The single-frame version closed its editor by navigating the frame to root_path. With a frame per row, Cancel sets the frame's content to empty instead.
  3. A shared add form moved into the clicked slot inherits the slot's click handler. Every click inside the form, Cancel and both fields, bubbled to the slot's click->quickbar#fillSlot and reopened the form, wiping the input. The handler ignores clicks that start inside the form.
  4. An element with no positioned ancestor escapes. The header + once opened its form parked on the <aside>, which had no position, so top: 100% resolved against a distant ancestor and the form left the screen. The box is now position: relative, and + opens at the slot it chose.
  5. Stream-replace for anything pressed repeatedly. A move that redirects reloads the page and drops focus after every press. A turbo_stream replacing the widget, carrying which link moved and which control was pressed, lets the controller put focus back on connect.
  6. display: none cannot take focus. The row's actions are hidden until hover, so restoring focus after a move adds an actions-open class to the row first, and :focus-within keeps the group open after that.
  7. SQLite cannot defer a unique index. Only foreign keys are deferrable, so the exchange parks one row at -position with update_column (skipping the validation that would reject it) and lands both real values with update!, all in one transaction. On PostgreSQL, a unique constraint declared DEFERRABLE INITIALLY DEFERRED removes the need for the parking step. Put the exchange in a concern if another widget reorders under a similar index; the reference's links strip does.
  8. Keep generic controllers generic. The inline title editor dispatches an inline-edit:saved event; the Quickbar listens and retitles its tab. The editor knows nothing about tabs, which kept it reusable.
  9. A shell partial in an engine layout needs main_app route helpers. The widget also renders inside a mounted engine's layout, where bare route helpers resolve against the engine. Every route in the partial is main_app.-prefixed.
  10. Classes set only from JavaScript must be visible to the CSS build. The controller toggles the tab colours (bg-indigo-600, text-white, bg-slate-200, text-slate-600). A class the build does not see is silently dropped. The inactive pair is also in the template; the active bg-indigo-600 survives only because an unrelated view happens to use it. Either list such classes where the build scans, or keep them in the stylesheet as named rules.
  11. Inputs must set their own colour. Form text inherited its colour from wherever the panel was mounted and measured below the contrast target in one host. Each input now declares color explicitly.
  12. Partials that read instance variables are hard to reuse. The partial defaults @quickbar_pages ||= ... so it works on any page. That works, but it hides a query in the view, and ERB linters such as Herb flag it. A helper or component that loads and passes locals is the cleaner shape.
  13. Test with real events. The Stimulus tests for fillSlot passed a hand-made { currentTarget } object with no target, which is why lesson 3's defect reached daily use. Tests now build real DOM events.
  14. Break the code to prove the test. Removing the parking step turned the exchange specs red with the exact collision; removing the disabled computation turned the end-of-grid view specs red. The focus-out test passed with the feature removed until it was rewritten to assert the open state first.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment