@slotted/react 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/docs/guidelines/browsing.md

@@ -0,0 +1,74 @@
+---
+topic: browsing
+prefix: BR
+triggers:
+  [
+    tree,
+    category,
+    categories,
+    hierarchy,
+    branch,
+    leaf,
+    taxonomy,
+    browse,
+    facet,
+    drill,
+    place,
+    scope,
+    breadcrumb,
+    count,
+    grain,
+    catalogue,
+  ]
+families: [tree, breadcrumb, page-header, filter-bar, data-grid]
+---
+
+# Browsing
+
+How a reader moves through a set that is arranged rather than listed: a tree
+of categories over a list of records, and one concept a backend answers for at
+two grains. The library gives `tree` a hierarchy with a keyboard and a query,
+`breadcrumb` a trail and `filter-bar` a tree of conditions; it does not say
+whether a branch is a filter or a place, which of a node's two counts a row
+draws, or how a list that reads products and a list that reads stock lead to
+each other.
+
+### BR-01 · A branch is the list's place, not one of its pills
+
+Level: SHOULD
+Applies to: a list reached by choosing a node in a `tree`, and the `filter-bar` above that list
+Rule: The branch a reader chose is the list's heading and its `breadcrumb`; the filter bar keeps the facets and holds no pill for it.
+Why: A place is where the reader is and a facet is what they asked for; a branch drawn as a pill reads as one condition among many, and the way back out of it becomes a chip to delete rather than a trail to walk.
+Do: Name the list after the branch, put the trail from the catalogue's root in the header's breadcrumb with every ancestor a link, and narrow the query from the place rather than from the bar. The way out is the trail's first crumb, which names the whole set.
+Don't: Write the branch into the bar's tree, or leave the list titled after the resource while its rows come from one branch.
+Check: Open a branch from the tree: the heading is the branch's name, the trail stands above it, and the bar's pill count is unchanged.
+
+### BR-02 · A place holds what is under it, and says how much of it there is
+
+Level: MUST
+Applies to: a list narrowed to a branch of a hierarchy
+Rule: The query covers the branch and every node beneath it, and the page states how many nodes that is beside how many records they hold.
+Why: A backend that files a record on a leaf answers nothing for the branch above it; a list that asked for the branch alone would tell a reader a whole department is empty, and a list that asks for the subtree without saying so leaves a count nobody can reconcile with the tree.
+Do: Read the hierarchy before the rows, send the branch and its descendants as one condition, and write the sentence under the title: how many records the place holds, how many nodes it covers, and how many the whole set holds.
+Don't: Narrow to the chosen node alone, or state a count without saying what it is counted over.
+Check: Open a branch whose own records are none: the list is not empty and the sentence names the nodes it covers.
+
+### BR-03 · A node's own count and its branch's count are two numbers
+
+Level: MUST
+Applies to: a count drawn on a `tree` node
+Rule: The number on a row is one of the two and the screen says which; where a node holds records of its own and has nodes under it, the second number is said apart from the first.
+Why: The two answer different questions — how big this branch is, and how much is filed at this level — and a tree that prints one of them without saying which is read as the other.
+Do: Put the branch's whole count in the row's trailing cell, the one the family keeps at its intrinsic width, and say in the region's own words what that number counts. Where a node also holds records directly, say how many on the row's second line, which the family already draws in the muted step.
+Don't: Draw the backend's own field without adding the descendants, or print two bare numbers on one row.
+Check: A branch whose records are all on its leaves shows the leaves' total, not nought.
+
+### BR-04 · One concept at two grains is two lists that name each other
+
+Level: SHOULD
+Applies to: a resource the backend answers for at two grains — a family header and the item that is counted, ordered and priced
+Rule: Each grain is its own route with its own columns and its own filters, and each page names the other above its rows.
+Why: The two grains are asked different questions and filtered by different fields; one bar cannot hold both sets of conditions, and a reader looking for what is below its reorder point is not looking for a family header.
+Do: Give each list the filters its own resource offers, say in one sentence what the grain is and what the other one is for, and carry the reader's place from one to the other so a branch survives the move.
+Don't: Put a view switch over one filter bar whose fields belong to one of the two, or leave the second grain reachable only through a record of the first.
+Check: The two routes are in the navigation, each header links to the other, and a place chosen on one is still the place on the other.

package/dist/docs/guidelines/builders.md

@@ -0,0 +1,97 @@
+---
+topic: builders
+prefix: BD
+triggers:
+  [
+    builder,
+    rule,
+    rule builder,
+    condition,
+    condition tree,
+    nested group,
+    workflow,
+    automation,
+    designer,
+    definition,
+    and,
+    or,
+    drag,
+    reorder,
+    move,
+    limit,
+    depth,
+    flow,
+    trace,
+    run history,
+  ]
+families: [segmented-control, select, multi-select, menu, inline-message, typography]
+---
+
+# Builders
+
+How a screen lets a person write a rule the system runs later — a trigger, a
+tree of conditions, the actions — and how that rule is read by someone who
+cannot change it. The library gives `filter-bar` a builder for a filter
+applied to a list, `menu` a place for a node's commands and the field families
+an operand; it does not say how a stored rule reads aloud, where a limit the
+backend enforces is said, or how a tree narrows to a phone.
+
+### BD-01 · A definition reads as a rule before a form
+
+Level: SHOULD
+Applies to: a stored rule — a workflow's trigger, conditions and actions — on its record
+Rule: The record shows the rule as it reads — When, If, Then, Otherwise — every later line of the condition tree led by its join in words and every nested group opened by its own ("any of:", "all of:"); the editor opens from that reading in the section it is read in; a reader without the permission to edit reads the rule and is not shown an editor.
+Why: A rule shown only as a form makes a reader who cannot edit it decode disabled controls, and makes one who can open an editor to learn what the rule does.
+Do: Set the trigger beside "When", the conditions the way a query is set — the join in a column of its own at the start of each later line, a group's children stepped in one step under the line that opens it, a guide down every level — and the actions numbered under "Then". The editor is a query parameter of the record (FM-12) and stands in the same section (FM-07).
+Don't: Draw the editor in a read-only state for a reader, or join the conditions by colour, a border or indentation alone.
+Check: Open a stored rule as a reader who may edit it and as one who may not: both read When, If, Then, Otherwise with every later line led by its join in words, and only the first is offered the editor.
+
+### BD-02 · A structural limit is said before it is reached
+
+Level: SHOULD
+Applies to: a builder whose backend limits the tree — conditions per rule, levels of nesting
+Rule: Under the tree the builder states what it holds and what remains of each limit, and a control that would cross a limit is disabled with the limit as its stated reason.
+Why: A limit met only as a refusal after the save is a tree written past what the backend accepts, and a control that silently does nothing at the limit reads as a broken control.
+Do: Write one line under the root: the conditions and levels used of their maxima, and how many more of each can be added. At a limit, the add control in the group's foot is disabled and the same item in the group's `menu` carries the limit in its `description`.
+Don't: Let the add control stay live at the limit and answer with the backend's refusal.
+Check: Fill a tree to one of its limits: the line under the tree says nothing remains of it, and each control that would cross it is disabled with the limit as its reason.
+
+### BD-03 · A refusal that names no node is marked at the node before the request
+
+Level: MUST
+Applies to: a tree the backend validates and refuses under one field, with no path to the node
+Rule: The builder runs the backend's own check on every change and, once a save is tried, marks each node it would refuse with its message before any request is sent; a group with nothing in it is marked from the moment it is empty.
+Why: After the request the screen knows only that the conditions were refused, not which of fifty; before it, the same check knows the node.
+Do: Run the backend's validation code in the browser rather than writing a second one, key its issues by the node's path, outline the node and put the message under it, and keep the form's summary for the same messages (FM-03).
+Don't: Send the tree and translate the backend's list of messages back onto nodes, or mark every node as invalid while the reader is still writing.
+Check: Save a tree that holds an empty group and a node past a limit: each is marked at its node with its message, and the network log holds no request.
+
+### BD-04 · The keyboard and the pointer make the same moves
+
+Level: SHOULD
+Applies to: moving the nodes of a tree — up, down, into the group above, out of the group
+Rule: Every node's menu carries its moves and its removal, the grip's drag makes the same moves, and both refuse the same places — a group into itself, a level past the limit — with the reason said.
+Why: A drag with no menu shuts out the keyboard and a phone's scrolling finger, and two code paths with two sets of boundaries let one of them build a tree the other refuses.
+Do: Compute every move from one function over the tree and its limits; disable a menu move that would be refused, with the reason as the item's `description`; outline the place a drag is over when it is refused and announce the reason politely; keep the focus on the moved node's menu after a keyboard move.
+Don't: Offer dragging alone, or let the drop answer with a backend refusal.
+Check: Move one node with the keyboard from its menu and the same node by its grip: both reach the same places, both refuse a group dropped into itself with the reason said, and after the keyboard move the focus is on the node's menu.
+
+### BD-05 · A tree narrows by stepping in, never by scrolling
+
+Level: SHOULD
+Applies to: a nested builder below the width its rows' three controls need, at 570 pixels and on a phone
+Rule: Each level steps in by one space step behind a rule, and below the width a condition's field, operator and value fit on one line the field takes its own line and the operator and the value share the next; the tree never scrolls sideways.
+Why: A tree five levels deep that indents by a column, or keeps three controls on one line, is wider than a phone, and a builder that scrolls sideways hides the join of the level the reader is in.
+Do: Make the builder a container and switch the row's grid on its own width (OE-09), keep the grip and the node's menu at the row's two ends with the words between them wrapping, and leave the operator's popup to the family, which keeps it inside the viewport.
+Don't: Indent by more than one space step per level, or give the tree a horizontal scroller.
+Check: At 390 and 360 pixels open a tree five levels deep: nothing scrolls sideways, each level steps in by one space step, and a condition's field stands on its own line.
+
+### BD-06 · A rule's record shows what flowed through it, and the rule carries its own figures
+
+Level: SHOULD
+Applies to: a stored rule's record, its run history and its editor — a trigger, a decision over a condition tree, the actions in order
+Rule: The record opens on how the rule runs — every event of a stated period split where the conditions decide, the events let through split again by how their run ended, each band as thick as the events in it, the three totals over its columns — and then the rule itself, with each step's own figure at the end of its line. A run opens on the same rule as its trace, the rail lit as far as the run went; the editor, where the container has room, sets the draft the same way beside the form.
+Why: Read as text, the rule says what it does and not how often; read as rows, the history says what happened and not where in the rule. The split by volume answers the first question a reader of a rule brings — how much of what arrives does it act on — in one look, and the figure at the end of each line answers where.
+Do: Draw the split as an element of the screen's own (OE-01) from the measured width, with the figures in words over it. Set the rule as a sheet of four lines — When, If, Then, Otherwise — down a rail, the figures in an end column aligned across the lines, and no card, tile or badge around a step. Narrow, stand each label over its step and the end column under it.
+Don't: Build the flow from stat cards, tiles and tags; give a figure only by a band's thickness or a tone; keep a second rendering of the rule for the trace and the preview.
+Check: Open a rule's record: the split of its period's events comes before the rule with its totals in words, each line of the rule ends in its own figure, a run opens on the same rule lit as far as it went, and at 390 pixels nothing scrolls sideways.

package/dist/docs/guidelines/composition.md

@@ -0,0 +1,143 @@
+---
+topic: composition
+prefix: CP
+triggers:
+  [
+    slot,
+    part,
+    anatomy,
+    where,
+    place,
+    compose,
+    wrap,
+    body,
+    header,
+    inside,
+    beside,
+    own element,
+    custom,
+    creative,
+    bespoke,
+    no family,
+    token,
+    literal,
+    hard-coded,
+  ]
+families:
+  [
+    page-header,
+    app-shell,
+    top-navigation,
+    popover,
+    drawer,
+    dialog,
+    tabs,
+    toolbar,
+    inline,
+    stack,
+    grid,
+    typography,
+  ]
+---
+
+# Composition
+
+Where a consumer's element goes in relation to a family: in a slot the family
+names, or beside the family as a block of the consumer's own. Every family
+publishes its anatomy — the parts it draws and the slots it leaves for the
+consumer — and a screen that improvises a block where a slot exists loses what
+the slot carries: a position, a sticky edge, a fold, a keyboard order.
+
+### CP-01 · A slot the family names before a block of your own
+
+Level: MUST
+Applies to: any element a page places inside or beside a family — a tab strip, a toolbar, a search field, a workspace row, a footer link
+Rule: Before writing an element next to a family, the family's anatomy is read; when it names a slot for that element, the element stands in the slot.
+Why: The slot is where the family's promises hold — the header's tabs stay pinned, the bar's search folds, the column's header takes the row inset; a block written beside the family carries none of them and reads as a defect of the family.
+Do: Open the reference page's anatomy table and match the element to a part described as "the slot a … sits in". Compose with the family's own members; wrap a family's part in a component of the page's own only when the host has no box.
+Don't: Place a family's content as the first block of a body, a sibling of the family or a child of the wrong part because the markup is shorter that way.
+Check: For every element of the page's own inside a family's root, the family's anatomy names the part it stands in; every "slot a … sits in" the page needs is used rather than imitated.
+
+### CP-02 · Siblings of the page's own stand in a layout family
+
+Level: MUST
+Applies to: two or more elements a page writes beside each other with no family between them — a name and a badge, a run of tags, the lines of an address, a figure and its caption
+Rule: Sibling elements of the page's own stand in `inline` (one row) or `stack` (one column) with a gap from the space scale, and text of the page's own takes its size from the typography family; bare inline siblings and bare text are not written.
+Why: Two inline elements with nothing between them touch, and a badge beside a word sits on the text baseline rather than the row's centre; bare text takes the document's 16-pixel body size inside a region whose families set 13.
+Do: Wrap the run in `inline` (centre-aligned by default, a two-step gap for marks beside a word) and each line of a block in `stack`; give every span of the page's own the typography family's `size`. The families' own parts — a list item's label, a cell's value, a description — already carry their size and gap and need none of this.
+Don't: Write a name and a `badge` run together as text in a cell, a `description-list` value holding three tags with nothing between them, or address lines as plain spans.
+Check: Every element of the page's own that has a sibling is a child of `inline` or `stack`; no bare span inside a family's part carries the body size.
+
+### CP-03 · A track that holds a family states a zero minimum
+
+Level: MUST
+Applies to: a `grid` or a flex line of the page's own holding a family that scrolls its own content — `table`, `data-grid`, `scroll-area`
+Rule: The track the family stands in is written with a zero minimum (`minmax(0, 1fr)`, or `min-inline-size: 0` on a flex child), so the family's scroller is what scrolls.
+Why: A track is `auto` by default and a grid item's minimum is its content, so a table wider than the page stretches the track and pushes every sibling — the figures, the header — out of the frame, instead of scrolling inside the scroller the family already draws.
+Do: State the single column as `minmax(0, 1fr)` on the region that holds the listing, and let the family's `scroll` part take the overflow.
+Don't: Rely on the family to constrain itself: it cannot measure a parent that grows with it.
+Check: At 1280 with the widest tab open, the page's scroll width equals the viewport and the family's own scroller is the only thing wider than its box.
+
+### CP-04 · Where no family answers the problem, the screen composes its own
+
+Level: MAY
+Applies to: a problem no published family covers — two versions of one value side by side, a step of a lifecycle drawn on a row, a figure with its own shape, a summary that is neither a list nor a table
+Rule: When the families' anatomies have been read and none of them answers the problem, the screen writes an element of its own rather than bending a family into a shape it does not have.
+Why: A family used against its anatomy reads as a defect of the library — a `list-item` made to hold a chart, a `badge` made to hold a sentence — and the screen still does not answer the problem; a screen that draws only what a family draws cannot answer anything the library has not met yet.
+Do: Read the anatomies first, and name the one that came closest and what it does not carry (CP-01 is the earlier question, not a veto). Then compose: the layout families for the arrangement (`inline`, `stack`, `grid`), the families that do fit for the parts they own, the typography family for every word, and the theme's tokens for every value the element paints (CP-05). The element takes one of three shapes, and each is legitimate — a block in the screen's template, a component of the screen's own named after what it shows, or a component the module's screens share — and it carries the state attributes the vocabulary already has, so it reads as part of the system. A screen whose problem is dense is expected to reach this rule: a flagship screen composed only of untouched families is usually a screen that gave up on its problem. Add a ledger row when a family would plausibly have covered the case: that row is what grows the library.
+Don't: Reach for the nearest family and override its stylesheet; copy a family's parts into markup of your own; or leave the problem half-answered because no family draws it.
+Check: For every element of the page's own, the family that came closest is named in a comment or a ledger row, and what it does not carry is named as a **part of its anatomy** — not as an impression of its examples. A claim that a family "does not do this" which its anatomy table contradicts is the defect; the approval chain was written by hand beside `timeline`, whose `rail`, `marker` and `connector` are exactly that shape, and the hand-drawn thread broke on the first step that carried a comment.
+
+### CP-05 · An element of the page's own is built from the theme's tokens
+
+Level: MUST
+Applies to: any CSS a screen writes for an element of its own, under CP-04 or beside a family
+Rule: Every value the element paints comes from the theme — space, type, ink, border, radius, elevation and motion — where the theme has a token for it; a literal is written only beside a comment that says what decided it and why no token covers it.
+Why: A literal is what makes a screen look adjacent to the product rather than part of it: it ignores the scheme switch, the three densities and the theme's own retuning, and it is the first thing that drifts when the theme moves.
+Do: Read `--slotted-space-*` for every gap and inset, `--slotted-text-*` and `--slotted-surface-*` for ink and ground, the typography family's `size` for every word, and the published measures of the family the element stands in — `--slotted-app-shell-row-inset` inside the navigation column, the control heights beside a control. Some values have no token and never will: a measure a column is capped at, a container query's step, an optical nudge of a pixel, the geometry of a shape the screen draws. Write those, in rem where the value scales with the type and in pixels where it does not, and put the reason beside them — the check reads that comment and passes. The escape is for a value the theme does not hold, not for a value it does.
+Don't: Write a hex colour, a font size or a gap the theme already holds a token for, and do not read another family's private custom property. A literal with no reason beside it is the defect this rule is about; a reasoned one is a decision the next reader can weigh.
+Check: Read every stylesheet of the screen, skipping media and container queries, hairlines and any line whose comment gives its reason: no colour, type size or gap remains that a theme token covers.
+
+### CP-06 · A state the family already draws is not drawn again
+
+Level: SHOULD
+Applies to: the axes a screen passes to a family — `variant`, `tone`, `size`, `current`, `complete` — and any mark a screen adds beside a part the family fills
+Rule: A screen states a state once. Where the family has a state for it, the screen sets that state and adds nothing louder beside it.
+Why: The second statement is never the same size as the first: `current` on a `timeline` item draws a target, and the `solid` `variant` over it adds a halo two rules wide that crowds the title; a `badge` beside a description that already says "Waiting on this role" says it twice at two weights.
+Do: Set the state the family names, read what it draws, and stop. Where an axis is passed as well, the screen can say what that axis adds which the state does not already carry.
+Don't: Reach for the loudest variant to make a state visible, or add a mark beside a part that already carries the words.
+Check: For every axis a screen passes to a family, the screen can name what it adds beyond the family's own state.
+
+### CP-07 · A page's width is its type's
+
+Status: retired · rewritten as CP-10, which gives every destination one width
+
+### CP-08 · A control that changes mode keeps every box where it was
+
+Level: MUST
+Applies to: a segmented control, a tab or a toggle that switches what one region holds — a reply or an internal note, one view or another — and the text beside it
+Rule: Switching the mode changes the words and the values in the region, never the size, the line count or the position of any box in it or around it; text whose length differs between modes stands on one line, cut with an ellipsis and read whole from its title.
+Why: The line beside Reply and Internal note was longer in one mode and wrapped under the control at narrow widths, so every switch moved the composer and the conversation above it under the reader's eyes and pointer.
+Do: Give the varying text `flex: 1 1 0`, `min-inline-size: 0` and a one-line cut, write the two texts to similar lengths, and keep a control's label set fixed across modes.
+Don't: Let a mode add or remove a line, a hint or a control that changes the region's height, or let a row wrap differently in one mode than in the other.
+Check: At 1280, 570 and 390 pixels, switch the mode and read the bounding box of each box in the region: every top and height is the same in both modes.
+
+### CP-09 · A control that switches a region does not render the region in its own frame
+
+Level: MUST
+Applies to: tabs, a segmented control, a route link or a filter whose change mounts a region holding tables, grids, charts or forms
+Rule: The control's own state — the selected tab, the pressed segment — updates in the interaction's frame; the region renders from a deferred value (in React, useDeferredValue or startTransition) and states aria-busy while the shown value lags the selected one.
+Why: Mounting a region of families in the click's task blocks the next paint, and Interaction to Next Paint above 200 ms is "needs improvement" and above 500 ms "poor": a table of a hundred rows of twenty cells measured 160 ms in one task in a development build, and a 4× CPU throttle takes its 93 ms in a production build past the first threshold.
+Do: Keep the selection state urgent and hand the region the deferred value; mount only the selected panel, with mount active.
+Don't: Set the selection and the region from one state update inside the click handler, or mount every panel to make switching look instant.
+Check: Switch the control with the CPU throttled 4× in Chrome: the selection marker moves in the next frame, and the Performance panel shows no long task between the click and that paint.
+
+### CP-10 · Every destination has one width
+
+Level: SHOULD
+Applies to: every `page`
+Rule: Every destination of the navigation — a list, a record, a dashboard, an overview — is `full`, so moving between destinations never moves the column's edges; a create or edit form is `wide` and lays its fields out in a grid of the form's own; a page of preferences read as prose is `measure`.
+Why: A list at `bleed`, a record at `wide` and a form at `content` moved the column's edges on every move between destinations, and a form 56rem wide stood narrow in a desktop frame; the owner read the pages as squeezed and without a pattern.
+Do: Set `full` on every destination and `wide` on every form, on the page and nowhere else; a list keeps `fill` (LP-12); a form arranges its fields in a `grid` within that width.
+Don't: Give each page type a measure of its own, or cap a form's body with a width of the screen's own.
+Check: Move between two destinations of the navigation: the header's and the body's start and end edges stay on the same lines.

package/dist/docs/guidelines/conversations.md

@@ -0,0 +1,59 @@
+---
+topic: conversations
+prefix: CV
+triggers:
+  [
+    conversation,
+    thread,
+    message,
+    reply,
+    composer,
+    internal note,
+    ticket,
+    inbox,
+    sla,
+    clock,
+    business hours,
+    queue,
+  ]
+families: [message, message-scroller, prompt-composer, filter-bar, tabs, page-header]
+---
+
+# Conversations
+
+How a record that is a conversation with a clock is read and answered: a
+support ticket, and anything else whose body is messages. The library gives
+`message` a thread row, `message-scroller` a log that follows new rows and
+`prompt-composer` a field that sends; it does not say where the composer
+stands when the thread is long, how a service-level clock is said, or how an
+inbox's queues and its filters stay one thing.
+
+### CV-01 · The composer stays in reach of a scrolled conversation
+
+Level: MUST
+Applies to: a record whose body is a conversation the reader answers
+Rule: From 600 pixels the conversation fills its region and scrolls on its own with the composer under it, and the record's context scrolls on its own beside it or behind a tab of the header; below 600 pixels the page scrolls, the composer is stuck to the bottom of the screen, and the record opens on its last message.
+Why: A thread of 120 messages scrolled with the page put the composer 120 messages away from the line it answers, and a context that scrolled with the thread left the customer and the clocks behind.
+Do: Give the thread a `message-scroller` that opens at its `end`, keep the composer in the row under it, and draw the context as its own scrolling column; on a phone, make the composer's row sticky on the page's ground.
+Don't: Put the composer at the end of the page's flow, or let the context scroll away with the thread.
+Check: Open a conversation of more than one screen of messages at 1280 and at 390 pixels: it opens on its last message, and the composer is on screen without a scroll at both widths.
+
+### CV-02 · A service-level clock is said in business time, with the hour it falls due
+
+Level: SHOULD
+Applies to: a clock counted in business hours — a first response, a resolution
+Rule: A running clock says the business time left and the hour it falls due in the organization's zone, a passed one by how much and when it was due, a paused one that it is stopped and why; a queue's row says the span alone, and no clock is ever said in raw minutes.
+Why: "1 h 20 min left" read at 19:00 is tomorrow morning: the span alone hides that the time outside business hours does not count, and the hour alone hides how much work time is left.
+Do: Take the remaining minutes from the backend, say them in minutes, hours and business days of the organization's own length, and add the due hour; state the policy once beside the clocks, with the business hours.
+Don't: Recompute a clock in the client, or let a colour alone say that a clock is at risk or passed.
+Check: Read a running, a passed and a paused clock: the first names its due hour, the second how much it passed by, the third that it is stopped and why; none is a count of minutes above 59.
+
+### CV-03 · A queue is a view of the bar, never a second filter
+
+Level: SHOULD
+Applies to: a list worked as named queues — mine, unassigned, at risk, escalated
+Rule: Each queue is a view of the list's `filter-bar`, a tree of the bar's own fields, labelled with the count of the rows it opens on; choosing it writes its pills, and editing a pill leaves a view the bar marks as changed.
+Why: A queue picker beside the bar's pills is two answers to "what am I looking at", and they disagree the moment the reader edits a pill.
+Do: Hand the queues to the bar as its `preset` views, count each with the list's own total for its tree, and let a door open a queue by naming it in the address.
+Don't: Keep the chosen queue in a state of its own, or count a queue with a figure the list does not reproduce.
+Check: Choose each queue: the bar shows its pills and the list's total equals the queue's count; remove one pill: the bar marks the view as changed.

package/dist/docs/guidelines/errors-and-conflicts.md

@@ -0,0 +1,71 @@
+---
+topic: errors and conflicts
+prefix: ER
+triggers:
+  [
+    error,
+    conflict,
+    refusal,
+    failed,
+    retry,
+    stale,
+    version,
+    409,
+    503,
+    transport,
+    degraded,
+    permission,
+    forbidden,
+    state,
+    transition,
+  ]
+families: [inline-message, toast, result-state, button, dialog]
+---
+
+# Errors and conflicts
+
+What a screen does with an answer that is not the one it asked for. The
+library gives `inline-message` six tones, `result-state` four statuses and
+`toast` a place for what is passing; it does not say which of them a refusal
+belongs in, or that two refusals a reader must answer differently should not
+look the same.
+
+### ER-01 · A refusal is classed before it is shown
+
+Level: MUST
+Applies to: every command a screen sends
+Rule: The screen sorts the backend's answer into the class the reader must act on — a conflict (the record moved), a transport failure (nothing was written), a permission (this persona never will) or a state (the record cannot do this now) — and says the class, not the code.
+Why: "Request failed" makes the reader guess whether to try again, to read the page again, or to ask someone else; those are three different next steps and the answer already knows which one it is.
+Do: Keep one map from code to class in the module's store — the conflicts, the unavailable answer, the refusal of a permission and the state transitions — and one sentence per class beside the message: what happened, and what the reader does now. The words are the product's where the module knows the code, and the server's sentence where it does not.
+Don't: Show the code, show "Something went wrong", or answer every failure with the same toast.
+Check: Refuse a command for each class — a stale version, a failed request, a missing permission, a record in the wrong state: each message names its class in the product's words, and none shows a code.
+
+### ER-02 · A conflict is answered by reading the record again
+
+Level: MUST
+Applies to: every conflict the backend answers — a stale version, a record already moved to another state, a decision already taken, a quantity that changed
+Rule: The screen re-reads the record before it shows the message, so what the reader sees under the message is what the backend now holds; the message says that it has done so.
+Why: A conflict means the reader's picture is out of date. Leaving the old picture under a warning invites the same command again, and the second refusal teaches nothing.
+Do: Re-read on the conflict codes and on those alone — a transport failure changed nothing, so the picture is still true — and word the message as what happened elsewhere ("Another approver decided this one a moment ago"), not as what the reader did wrong.
+Don't: Ask the reader to refresh, or clear the screen and start over.
+Check: Change a record from a second session, then send a command from the first: the record on screen is re-read before the message, and the message says it was.
+
+### ER-03 · The version a command carries is the version the page read
+
+Level: MUST
+Applies to: every command that carries the version it read
+Rule: The screen holds the version as a number at the moment it read the record, and sends that; it never reads the version out of an answer it is still holding at the moment it sends.
+Why: A client that keeps the answers it read shares them with its store, so an object read minutes ago carries whoever wrote last — and a command built from it is never refused for being stale, which silently overwrites the other writer.
+Do: Copy the number when the record loads, and again after every command that succeeds. Where a screen holds many records — a queue — keep the number per row.
+Don't: Read the version from the held record inside the call that sends the command.
+Check: Change a record from a second session after the first read it, then send a command from the first: the backend refuses it as stale.
+
+### ER-04 · Two failures that read alike are two failures the reader cannot tell apart
+
+Level: SHOULD
+Applies to: a screen that can meet both a conflict and a transport failure — every screen with a command, on a slow or failing network
+Rule: A conflict and a transport failure carry different tones and different second lines: the conflict is a warning that the page has been read again, the transport failure is a danger that nothing was written and the same action can be tried again.
+Why: On a slow or failing network both arrive within a minute of each other, and a reader who cannot tell them apart either retries a command that already ran or abandons one that never did.
+Do: Reserve the danger tone for what did not happen, and the warning tone for what happened somewhere else.
+Don't: Give every refusal the danger tone because it is a failure.
+Check: With the network failing, a failed command says nothing was changed and offers the same action again; a conflict says the page has been read again. The two carry different tones.