`. ##### Keyboard Not interactive: the block takes no focus; the buttons in `#actions` are the tab stops. ##### Screen reader - Role: a `status`; `tone="danger"` is an `alert`, read at once. The block appears with its words, and a status that appears with its words is often not read out: that a list is empty is said by a region that was on the page before (UiTable has one), and a page of your own keeps one. - Order: the title, then the description. - Glyph: the glyph on its plate is hidden. ##### States Nothing yet, with a `primary` button to create the first one; nothing matches, with a `secondary` button to reset the filters; the load failed, `danger`, a red plate with a warning glyph and Retry. `sm` in a drawer or a card, `md` on a page. A dashed frame on a page, none inside a card, a drawer or a window. A neutral one without a glyph draws no plate. ##### When to use another component - Content on its way: UiSkeleton. - An action in flight: UiSpinner. - A notice over content that is there: UiListItem in a `tone`. - A failed request: a toast through UiToaster. #### Examples ##### Nothing matches ```vue ``` ##### The load failed ```vue ``` ##### Section in a drawer ```vue ``` ##### In a card ```vue ``` ##### Without a glyph ```vue ``` #### API Props: - `title`: `string` (default `""`) — One short line of what happened: "No invoices yet", "The record did not load". - `description`: `string` (required) — Why it is empty and what to do next. - `tone`: `"neutral" | "danger"` = `neutral | danger` (default `"neutral"`) — `danger` for a load that failed: a red plate and an alert; its Retry is a `secondary` UiButton in `#actions`. - `size`: `"sm" | "md"` = `sm | md` (default `"md"`) — `md` for a page, `sm` for a section inside a drawer or a card. Anything else lands on the root element: native attributes, aria-*, data-testid. Slots: - `media` with `Record` — The glyph on the plate, as a row's `#media`; `danger` draws a warning sign when it is empty. - `actions` with `Record` — The next step, a UiButton of your own or two: `primary` to create the first one, `secondary` to reset the filters or retry, with `loading` when it sends. #### How it behaves ##### Way forward - When: a list, a table or a section has nothing to show. - Props: `title` and `description` for the cause, the step in `#actions`; `tone="danger"` for a failed load. - Guarantee: The message explains the cause through `title` and `description`, with the actions from `#actions` below it. With `tone="danger"`, it shows a warning icon on a red background and is announced immediately by a screen reader. - Without it: A blank area or “No data” message gives no explanation or next step. - Code: `` - Your part: Explain the cause and offer a useful action: Create when there are no records, Reset when filters hide them, or Retry with `tone="danger"` when loading fails. UiTable, UiDataTable and UiLog include this message component in their own states. - Not covered: It does not tell the causes apart by itself; only the app knows why the list is empty. - Proof, in the repository's tests (UiNoData.spec.ts, not in the package): "It holds the next step: a button of your own, with its own weight.", "the next step comes after the title and the description", "A failed load is said at once, on a red plate with a warning glyph." - Pattern for all components: https://grani.arseni.work/patterns/finding#empty-next-step The patterns: https://grani.arseni.work/patterns ### Pagination (`UiPagination`) > Move between pages with Previous, Next and page numbers below a list or table. A component of grani 0.1.0. Data, stable, since 0.1.0. Page: https://grani.arseni.work/components/pagination Also called pager, page navigation. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Ignore extra presses while a request runs. - Start a new search on the first page. - Land on a page with records after a delete. - Keep the page arrows under the pointer. - Keep turning pages from the keyboard. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass the list’s loading flag as `loading`, from the moment the page is requested until it has arrived. - Set `v-model:page` to 1 when the search or the sort changes; UiDataTable does it for you. - Set the page to the last one when the total drops below it; UiDataTable does this for you. - Set `loading` from the page request until it finishes. Use `disabled` when paging is unavailable altogether; it disables the arrows. #### Why it works this way Page numbers with previous and next arrows. Take it under a list that pages, beside the count. What it owns. It knows the total and the page size and asks for a page, nothing else; the list owns the data and the page size. **Placement.** In the footer of a UiDataTable, in the corner beside the count ("1–25 of 57"). **Count.** The page count is max(1, ceil(total / pageSize)); one page renders nothing. Out of range. A page that is out of range or unreadable is drawn as the nearest one, and a click is clamped to the range. The pager draws; it does not ask: on a list that shrank (a delete, a filter), the app sets the page to the last one, as UiDataTable does. **Loading.** While a page is on its way the app passes `loading`: the arrow that asked shows a spinner and keeps the focus, the other arrow is off, the numbers are held but keep the focus, and a press asks nothing. A number that asked shows the spinner in place of its digits, in a slot of the same width. A click on the current page asks nothing either. `disabled` is a row that cannot page at all, not a load. **Steady row.** The row holds still. Once the pages do not fit, it always shows the same number of slots (a gap never hides a single page), and every number is as wide as the widest, so the arrows stay under the pointer. **Narrow box.** It fills the box it is given, as wide as its parent or the rest of a row, and draws its row at the start of it: `text-center` or `text-end` on it moves the row. Where that box is too narrow for the numbers (20rem at `xs`, 24rem at `sm`, 28rem at `md`, a container query, not the screen; wider as the last page gains digits past two), they give way to "3 / 20" between the arrows. A number that had the focus hands it to "3 / 20". ##### Keyboard - `Tab`: walks the previous arrow, each page number and the next arrow; an arrow at its end is disabled and skipped. - `Enter` `Space`: press the arrow or the number, which are buttons. While `loading` the pressed arrow keeps the focus with its spinner, and the numbers stay in the Tab order (`aria-disabled`), so a press that starts a load keeps the focus in the row. An arrow that turns off at its end once the page has come hands the focus to the current page, or to "3 / 20" in the compact row; so does an arrow under the focus when the row turns `disabled`. ##### Screen reader - Landmark: a navigation landmark named "Pagination", or by the caller's `aria-label`; a second pager on the page takes one of its own, so the two landmarks are told apart. - Arrows: "Previous page" and "Next page". - Numbers: every number is "Page N", the current one is `aria-current="page"`, and held numbers are `aria-disabled`. - Page change: a status region, always there, says "Page N of M" when the page changes, in the wide row and the compact one alike; the numbers are grouped as the app's language does. - Compact label: "3 / 20" is read as "Page 3 of 20" when it takes the focus. - Loading: the pressed arrow or number says busy (`aria-busy`). ##### States Every page while they fit, the ends with a window and gaps, the first and the last page with an arrow inert, `loading` with a spinner on the pressed arrow, `disabled`, `compact` and the narrow row with "N / M", a stale page past the range drawn as the last; three steps of the ladder. One page draws nothing. ##### When to use another component - A list that loads and owns its page: UiDataTable around the table. - Older events at the end of a timeline: UiLog with `hasMore`. - Views of one page: UiTabs. #### Examples ##### Many pages ```vue ``` ##### Compact ```vue ``` ##### Loading ```vue ``` ##### Sizes ```vue ``` ##### Stale page ```vue ``` ##### One page ```vue ``` #### API Props: - `page`: `number` (required) — Current page, from 1 (`v-model:page`). - `pageSize`: `number` (required) — Records per page; the page count is derived from it and `total`. Changing it is not this component's job. - `total`: `number` (required) — Total records. - `compact`: `boolean` (default `false`) — "N / M" instead of page numbers, for a narrow row. - `siblings`: `number` (default `1`) — Pages shown on each side of the current one. - `boundary`: `number` (default `1`) — Pages always shown at each end. - `loading`: `boolean` (default `false`) — A page is on its way: the pressed arrow shows a spinner and keeps the focus, the numbers are held, and a press asks nothing. Pass the list's loading flag. - `disabled`: `boolean` (default `false`) — The row cannot page at all: the arrows are off, the numbers are held. A load is `loading`. - `size`: `ControlSize` = `xs | sm | md` — Control size shared by every button in the row. Unset, the app's size (`createGrani({ size })`), `sm` by default. Anything else lands on the root element: native attributes, aria-*, data-testid. Events: - `update:page` (`page: number`) — Asks the parent for this page, clamped to the range; the parent applies it. #### How it behaves ##### One press, one request - When: a page is loading. - Props: `loading`. - Guarantee: The arrow or page number you pressed shows a spinner and keeps keyboard focus while the page loads. Further presses are ignored until loading finishes, and the page numbers stay where they were. - Without it: Next takes every press: a double press asks twice and skips a page. - Code: `` - Your part: Pass the list’s loading flag as `loading`, from the moment the page is requested until it has arrived. - Not covered: Without `loading`, nothing holds a second press: two presses a moment apart ask for two pages. - Proof, in the repository's tests (UiPagination.spec.ts, not in the package): "disabled holds the whole row: arrows off, numbers held but focusable, nothing asked", "while loading, the pressed arrow keeps the focus with a spinner, the other is off, and a press asks nothing", "a number pressed while its page loads shows a spinner in place of its digits and says busy" - Pattern for all components: https://grani.arseni.work/patterns/waiting#one-press ##### From page one - When: the list moves the page back to one. - Props: none. - Guarantee: Page one is marked as the current page, Previous is off, and a screen reader hears “Page 1 of 6”. - Without it: The pager still marks page 4 while the list starts over. - Code: `` - Your part: Set `v-model:page` to 1 when the search or the sort changes; UiDataTable does it for you. - Not covered: The pager does not know the search: it shows the page it is given. - Proof, in the repository's tests (UiPagination.spec.ts, not in the package): "a page set back to one from outside is marked current, Previous is off, and the change is said" - Pattern for all components: https://grani.arseni.work/patterns/finding#search-from-page-one ##### Last page lands - When: the list has shrunk below the current page. - Props: none. - Guarantee: The pager shows the last page that exists as the current one, so a page number is always marked and Next is off at the end. - Without it: The pager shows page 3 of 2 as requested: no page number is marked as current, and Next leads nowhere. - Code: `` - Your part: Set the page to the last one when the total drops below it; UiDataTable does this for you. - Not covered: The pager adjusts its display only. It does not change `v-model:page` or load records; the app must update the page value and data. - Proof, in the repository's tests (UiPagination.spec.ts, not in the package): "a stale page beyond the range renders as the last page" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#last-page-lands ##### Arrows hold still - When: there are more pages than fit. - Props: none. - Guarantee: The Previous and Next arrows stay in place as you change pages. The page slots keep a constant count and are wide enough for the largest page number, such as four digits for 1,200 pages. The compact label, such as “3 / 20”, also reserves the width of its widest value. - Without it: Each number is as wide as its digits and the window of pages grows and shrinks, so the Next arrow moves out from under the pointer between clicks. - Code: `` - Your part: Nothing. - Not covered: When the pager’s container is too narrow, the page numbers are replaced by a compact label between the arrows. This depends on the space given to the pager, not the screen size. Larger page numbers need more space. - Proof, in the repository's tests (UiPagination.spec.ts, not in the package): "the row holds the same number of slots on every page", "every number is as wide as the widest, and a four-digit total holds the arrows", "the compact label holds the width of its widest "N / M", and the gap the numbers' text size" - Pattern for all components: https://grani.arseni.work/patterns/finding#pager-holds-still ##### Focus kept - When: you page with the keyboard through a list that loads. - Props: `loading`. - Guarantee: The arrow or page number you pressed keeps keyboard focus while the page loads. When an arrow becomes disabled at the end, focus moves to the current page number or the compact label, such as “3 / 20”; it also moves there when a narrow container replaces the page numbers with that label. If the whole pager becomes `disabled`, focus moves from the disabled arrow to the current page. - Without it: The arrow turns off while the page loads, keyboard focus is lost, and you have to find the page controls again. - Code: `` - Your part: Set `loading` from the page request until it finishes. Use `disabled` when paging is unavailable altogether; it disables the arrows. - Proof, in the repository's tests (UiPagination.spec.ts, not in the package): "keyboard paging on a loading list keeps the focus inside the pager", "while loading, the pressed arrow keeps the focus with a spinner, the other is off, and a press asks nothing", "compact: an arrow that goes inert hands the focus to the label, also while disabled" - Pattern for all components: https://grani.arseni.work/patterns/waiting#pager-keeps-focus The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useControlSize`, `useUiT`. ### Popover (`UiPopover`) > Open a small panel of options beside a button while keeping the rest of the page available. A component of grani 0.1.0. Overlays, stable, since 0.1.0. Page: https://grani.arseni.work/components/popover Also called dropdown panel, flyout, popup. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Open with keyboard focus where the task begins. Implemented by the app: - Data fetching, saving, permissions and business rules. - Put the field to start on first, or mark another one with the `data-autofocus` attribute. #### Why it works this way A small panel under a button, with the page still live. Take it for a few controls about the page (a note, a currency, a date); a filter is UiFilter and the columns of a table UiTableColumns, both on this panel, as UiMenu is for its list of commands. **Trigger.** The trigger is your own button in `#trigger`; the popover gives it `aria-haspopup`, `aria-expanded` and the toggle. The panel has no heading: the button names it, or `labelledby` does (a field's label). **Dialog.** The panel is a non-modal dialog, and the page stays live: no backdrop, no scroll lock. **Open state.** `v-model:open` lets the host open it, at mount too, and hear every close. When it is closed from outside, a focus that was inside goes back to the button. **Kept pages.** In a page that a `KeepAlive` keeps, a panel left open stays in the body when the page is deactivated, and Escape closes it there. Close it (`open` false) when the route changes. **Footer.** Actions (Apply, Reset) go in `#footer`, under a line at the end, never among the controls; both slots get `close`. Sections are flat UiCard components with a separator between neighbors, as in every overlay. **Nesting.** A select, a menu or a date picker inside works: a press in its list does not count as outside, and anything opened from the panel paints above it. A list at the top or the bottom of the panel (a UiFilterList) reaches that edge, as a select's list does. The panel is never taller than the room beside its button, so it never covers the button; a longer panel scrolls inside itself. **Attributes.** `class` and other attributes land on the panel. Its `id` stays its own, because the button points at it. **Placement.** It sits in a table toolbar (UiFilter, UiDateRange, UiTableColumns), under a date field (UiDatePicker); a menu's panel (UiMenu) is the same panel, holding commands. ##### Keyboard - `Enter` `Space`: on the button, open it, as a click does. The focus goes to the first field (a drawn select, date, switch, scale, drop zone or date range too, or what is marked `data-autofocus`), else to the first control; a panel of buttons opens on its first button. - `Tab`: goes round inside. - `Escape`: closes it and returns the focus to the button, only while the panel is the top layer. `close` from a slot does the same, unless the focus has already moved into a layer opened from the panel (a drawer an item opened), which keeps it. A click outside closes it and leaves the focus where the click went. ##### Screen reader - Button: says it opens a dialog (`aria-haspopup`), whether it is open (`aria-expanded`) and what it controls (`aria-controls`). - Panel: a non-modal `dialog` named by the button (`aria-labelledby`), or by `labelledby` (a field's label), with no heading of its own. ##### States Closed, or open under the button on its start, center or end edge (`align`), above it when there is no room below. It is never taller than the room beside the button; a longer panel scrolls inside itself with the `#footer` in view. While its button is scrolled out of the window, the panel waits hidden, still open, and the focus it held comes back with it. Opened from outside with `v-model:open`, at mount too. A select, a menu or a date picker open inside it. Opened from a drawer, where Escape closes only the panel. ##### When to use another component - Commands: UiMenu. - A task that needs the whole attention: UiModal. - A record to edit: UiCrudDrawer. - A hint of text alone: UiTooltip. #### Examples ##### Nested ```vue ``` ##### Open ```vue ``` ##### Drawer ```vue ``` #### API Props: - `align`: `"start" | "center" | "end"` = `start | center | end` (default `"start"`) — Which edge of the button the panel lines up with; start and end follow the reading direction. - `anchor`: `HTMLElement | null` (default `null`) — The element the panel lines up with, when the button sits inside a wider one (a field's capsule). - `labelledby`: `string` (default `""`) — The id of what names the panel, when the button's text is not its name (a field's label). - `open`: `boolean` (default `false`) — Whether the panel is open (`v-model:open`): the host learns of every close and can open it from outside. Attributes are placed by the component itself: its description says where. Events: - `update:open` (`value: boolean`) — The new value of `open`, for `v-model:open`. Slots: - `trigger` with `Record` — The button that opens the panel: one element or component, it keeps its own look and name. - `default` with `{ close: () => void; }` — The controls. `close` closes the panel and returns focus to the button. - `footer` with `{ close: () => void; }` — The actions under a line at the end of the panel, `xs` buttons 8px in (a gray Reset first with `me-auto`, Apply last); it stays in view while the controls scroll. Gets `close`. One that draws nothing draws no line. #### How it behaves ##### Focus starts inside - When: the panel opens, from the keyboard or a click. - Props: none: every UiPopover; `data-autofocus` names another place. - Guarantee: Start typing or choosing as soon as the panel opens. Focus goes to its first field or list, including a select or switch. If there are none, it goes to the first button. - Without it: The panel opens with keyboard focus left on the button that opened it, so what you type does not reach the panel’s field. - Code: ` ` - Your part: Put the field to start on first, or mark another one with the `data-autofocus` attribute. - Proof, in the repository's tests (UiPopover.spec.ts, not in the package): "focus goes to the first control and Tab goes round inside", "focus goes to the first list, not to a search further down" - Pattern for all components: https://grani.arseni.work/patterns/opening#focus-start The patterns: https://grani.arseni.work/patterns #### Built on it - [Menu](https://grani.arseni.work/components/menu): Open a menu of available actions, such as exporting records, changing a row or managing your account. ### Progress (`UiProgress`) > See how much of a task or target is complete when its progress can be measured. A component of grani 0.1.0. Status, stable, since 0.1.0. Page: https://grani.arseni.work/components/progress Also called progress bar, loading bar. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See upload progress and when it ends. - See where the app is working. - Reduce motion without hiding loading. Implemented by the app: - Data fetching, saving, permissions and business rules. - Update `value` with the upload’s measured progress. Inside UiDropzone, its `busy` and `progress` values drive the bar for you. - Update `value` with the measured progress and name the bar with `aria-label`. Use `indeterminate` when the amount completed is unknown. #### Why it works this way How far work or a target has come, `value` of `max`. Take it when the share is known: an upload, a quota, a goal; for work of unknown length set `indeterminate`. **Steps.** With `step` it shows one segment per step, filled by whole steps reached; an empty segment is a step still to go. **Color.** `tone` colors the fill. `variant="thermometer"` colors it by how full it is, from danger to success, and `invert` flips that for "less is better". **Unknown length.** `indeterminate` is work of unknown length: a band runs along the track, with no number. **Size.** The host's classes set the size; without them the bar is 8px tall. **Value.** It is a progressbar with `aria-valuenow`, absent while the value is unknown. `valueText` gives words, and it is what says a value past `max` ("14 of 10, over"), since the number stops at `max`. Name each bar (`aria-label`); unnamed, it is "Progress". **Marks.** A mark already given is this bar with `:step="1"`; a mark to give is UiScaleInput. **Placement.** It sits in a table's progress column, as UiDropzone's upload bar, and in a card, under its figure or as its `#divider`. ##### Keyboard Not interactive: it takes no focus. A mark to give is UiScaleInput. ##### Screen reader - Name: a `progressbar` named by the `aria-label` the host gives it, else "Progress"; a host that names it with `aria-labelledby` gets no second name. - Value: `aria-valuenow` runs from `0` to `max`, and is absent while `indeterminate` or while the value is not a number. - Value text: `valueText` is read in place of the number and carries a value past `max`. - Hidden: the fill and the segments. ##### States Empty, part, full and past `max`, where the number stops at `max`. `step` segments, filled by whole steps reached, and a continuous bar again above `maxSegments` or with no step filled. `tone` on the fill. `thermometer` from danger through warning to success, `invert` reversed. `indeterminate`, a band running along the track, which keeps running, slower, under reduced motion. 8px tall without a height class, else the host's height. In forced colors the track is outlined and the fill takes the highlight. ##### When to use another component - A wait in place: UiSpinner. - Content on its way: UiSkeleton. - A number: UiCount. - A change: UiDelta. - A mark to give: UiScaleInput. #### Examples ##### Segments ```vue ``` ##### Thermometer ```vue ``` ##### Tones ```vue ``` ##### Empty to over ```vue ``` ##### Unknown length ```vue ``` #### API Props: - `value`: `number` (default `Number.NaN`) — The current value, in the units of `max`. Not read while `indeterminate`. - `max`: `number` (default `100`) — The value at which the bar is full. - `indeterminate`: `boolean` (default `false`) — Work of unknown length: a band runs along the track, no value is said. - `step`: `number` — Size of one segment; turns the bar into segments, an empty one reads as one step still to go. - `maxSegments`: `number` (default `24`) — Above this many segments the bar is continuous again: a finger cannot tell them apart. - `tone`: `Tone` = `brand | neutral | success | warning | danger | info` (default `"brand"`) — Color of the fill; `brand` by default. - `variant`: `"plain" | "thermometer"` = `plain | thermometer` (default `"plain"`) — `plain` fills with `tone`; `thermometer` colors the fill by how full it is, danger through warning to success (`utils/scaleRamp`). - `invert`: `boolean` (default `false`) — Reverses the thermometer: less is better (load, pain, cost). - `valueText`: `string` — Words for the value instead of a number: "3 of 10 payments". Past `max` they carry the overage, the number stops at `max`. Anything else lands on the root element: native attributes, aria-*, data-testid. #### How it behaves ##### Upload shown - When: it is the bar of an upload. - Props: `value` of `max` bound to the upload's share. - Guarantee: The bar fills as the file uploads, and its number never goes past the end. The announcement that the upload is done comes from UiDropzone, not from the bar. - Without it: Nothing moves while the file uploads, and you cannot tell how much is left. - Code: `` - Your part: Update `value` with the upload’s measured progress. Inside UiDropzone, its `busy` and `progress` values drive the bar for you. - Proof, in the repository's tests (UiProgress.spec.ts, not in the package): "The bar says how far it is, and its fill follows value of max.", "beyond max the number stays at max and valueText carries the real value" - Pattern for all components: https://grani.arseni.work/patterns/waiting#upload-shown ##### Visible work - When: the amount of work completed is known. - Props: `value` of `max`, moved as the work goes; `indeterminate` when the length is unknown. - Guarantee: The bar fills with the measured progress, and a screen reader can read its current value. When progress cannot be measured, an animated band shows ongoing work without implying a percentage. - Without it: A spinner shows that work is ongoing but cannot tell you how much has finished. - Code: `` - Your part: Update `value` with the measured progress and name the bar with `aria-label`. Use `indeterminate` when the amount completed is unknown. - Not covered: It does not estimate progress: the bar is only as accurate as the `value` it receives. - Proof, in the repository's tests (UiProgress.spec.ts, not in the package): "The bar says how far it is, and its fill follows value of max.", "Work of unknown length runs a band along the track and says no number." - Pattern for all components: https://grani.arseni.work/patterns/waiting#visible-work ##### Calm motion - When: the work has an unknown length and reduced motion is on. - Props: `indeterminate`, and the system setting `prefers-reduced-motion: reduce`. - Guarantee: The band keeps running along the track, once every 1.6 seconds instead of 1.2. - Without it: The band stops partway along the track, and the work looks stuck. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiProgress.spec.ts, not in the package): "The running band keeps running, slower, when the system asks for reduced motion." - Pattern for all components: https://grani.arseni.work/patterns/waiting#calm-motion The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useUiT`. ### Radio group (`UiRadioGroup`) > Choose one answer from a short list, cards or a segmented bar; the whole row or card is the click target. A component of grani 0.1.0. Form, stable, since 0.1.0. Page: https://grani.arseni.work/components/radio-group Also called radio buttons, segmented control, option cards. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See the value the app actually accepted. - Toggle or pick by clicking the words. - Keep nearby buttons and fields in place. - Pass a group with one press of Tab. - Submit the values shown in the form. - Go straight to the field that needs fixing. - Name each field once for screen readers. - Announce required fields in words. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass the answer the app holds as `modelValue`. - Put the words in the slot and the details in `description`, `#media` or `#meta`, not beside the component. - Give each group in a form its own `name`. - Pass the error to its `UiField group`, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Put the name in the slot, and the rest in `description` or `#meta`. - Set `required` on the group, or on the UiField around it, and check for `null` before you save. #### Why it works this way One answer out of a few, shown as rows, cards or a segmented bar. The group owns the value, the name and the states; its `UiRadio` children are thin options drawn from it. **Empty.** No answer is `null`; a pick sends the option's value. A person cannot take an answer back: where none is an answer too, give it a radio of its own. A value no radio stands for shows nothing chosen and sends nothing; in development the console names it once, an empty string excepted: it is read as no answer yet, as in UiSelect. **Required.** It does not force a selection. `required` says one is needed, to a screen reader and to a form. **Variants.** `variant` changes only the look: rows, cards, or a `segmented` bar with one segment pressed. The bar stands on the control ladder (the app's step, `sm` at least), `block` makes it fill the row, and it reddens its frame when invalid. A press on the bar's frame picks the segment beside it. A bar wider than its row scrolls sideways inside its frame, its edges fading where more segments wait: keep its words short, two to four of them. The segmented bar is also the library's state switcher. **Model.** The radios follow the model after a refused pick and after a form reset. **Names.** Two groups in one form need two names: the browser joins radios that share a name. Two Vue apps on one page each need their own `app.config.idPrefix`, or their generated names meet. **Field.** Inside UiField, use `group`. **Attributes.** Attributes land on the root (`data-*`); ours apply where we set one, and the caller's description is joined to ours. **Placement.** In a form column beside UiCheckbox and UiSwitch. A segmented bar switches what a card or a list shows (a period, a view, the kind of event in UiLog), over it or in its toolbar. ##### Keyboard Native radios: the keys are the browser's, and the radios are native inputs under the marks, the cards and the segments, so a bar is walked the same way as rows. - `ArrowUp` `ArrowDown` `ArrowLeft` `ArrowRight`: move the selection. - `Space`: selects. There is one tab stop, on the checked radio, or on the first while none is. A click anywhere on a row, a card or a segment selects it. Safari passes over a group whose checked radio is disabled: turn the whole group off, not its chosen radio. ##### Screen reader - Group: a radiogroup named by the field's legend (`aria-labelledby`) or by the caller's `ariaLabel`. - Description: the field's description and error, and the caller's own, are read with it. - Invalid: `invalid` is `aria-invalid` on the group once, never on a radio. - Required: `required` is `aria-required` on the group and native `required` on the radios for a form; inside a UiField `group` it is silent, since the legend says it once. - Disabled: `disabled` is `aria-disabled`. - Radio: each radio is named by its own text, as UiRadio says. ##### States Nothing chosen, one chosen, hover, focus, disabled (the whole group, or one radio that stays disabled whatever the group says), invalid (red empty marks; a `segmented` bar reddens its frame), required, and the variants `plain`, `card`, `card-check` and `segmented`, with or without `block`. ##### When to use another component - Several answers: UiCheckbox in a UiField `group`. - A mark from 1 to N: UiScaleInput. - A pick from a long list: UiSelect. - On or off: UiSwitch. - Sections of a page, each with its own content: UiTabs. - Actions side by side: UiButtonGroup. #### Examples ##### Card ```vue ``` ##### Check ```vue ``` ##### Segmented ```vue ``` ##### Sizes ```vue ``` ##### Long ```vue ``` ##### States ```vue ``` ##### Refused ```vue ``` ##### Form ```vue ``` #### API Props: - `modelValue`: `SelectValue | null` (required) — The selected value (`v-model`). `null` when nothing is selected. - `name`: `string` — Native name shared by every radio, for forms. Generated when omitted, stable across server and client; two apps on one page need their own `app.config.idPrefix`. - `disabled`: `boolean` (default `false`) — Prevents selecting in every radio. - `invalid`: `boolean` (default `false`) — Marks the group as invalid: red marks. Inside UiField, the error state sets this automatically. - `variant`: `RadioGroupVariant` = `plain | card | card-check | segmented` (default `"plain"`) — `plain` rows with the mark first; `card` a card per radio with the mark at the end; `card-check` cards that show a check and a tint on the selected one only; `segmented` a bar with one segment pressed. - `size`: `ControlSize` = `xs | sm | md` — Step of the control ladder. A `segmented` bar is 36 or 44 px (`xs` is read as `sm`: a 24px segment is too small to hit); a `plain` mark is 16, 18 or 20 px. Unset, the app's size (`createGrani({ size })`). - `id`: `string` — Own id of the group, for a reference from elsewhere (`aria-controls`, a link); a field names it by its legend. - `ariaLabel`: `string` — Accessible name of the group when there is no visible legend. Inside a UiField group the legend names it. - `required`: `boolean` (default `false`) — One answer is needed: said to a reader on the group, and `required` on the radios for a form. Inside UiField group the legend says it instead. - `block`: `boolean` (default `false`) — A segmented bar as wide as its row, segments sharing the width. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Events: - `update:modelValue` (`value: SelectValue`) — The selected value changed. Slots: - `default` with `Record` — The radios. ##### Radio (`UiRadio`) Props: - `value`: `SelectValue` (required) — The value this radio stands for; the group's model takes it when selected. - `description`: `string` — A second line under the label. Read with the radio as its description. Not drawn in a segment. - `disabled`: `boolean` (default `false`) — Prevents selecting this radio; the group's `disabled` covers all of them. - `id`: `string` — Own id, for a label elsewhere. - `ariaLabel`: `string` — Accessible name when the slot has no text: a glyph segment, a label outside the row. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Slots: - `default` with `Record` — Label text displayed next to the mark. Clicking it selects the radio. - `media` with `Record` — A glyph or a small image before the text. Cards only. - `meta` with `Record` — A value at the end, before the mark: a price, a count. Cards only. #### How it behaves ##### Back to the value - When: the app refuses a choice, or the form is reset. - Props: `v-model`, or `modelValue` with `@update:model-value`. - Guarantee: If the app refuses your choice, the previous answer is selected again. A form reset brings back the app’s answer. - Without it: An answer looks selected that the app did not accept. - Code: `…` - Your part: Pass the answer the app holds as `modelValue`. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "a vetoed change puts the DOM back on the model" - Pattern for all components: https://grani.arseni.work/patterns/waiting#refused-goes-back ##### Click the label - When: its options are rows or cards. - Props: the default slot of each UiRadio; `variant="card"` or `"card-check"` for cards. - Guarantee: The whole row is the label of its radio: a click on the words picks it, and a long label wraps beside the mark. A card is picked by a click anywhere on it, its words, `#media` and `#meta` included. - Without it: A radio in a corner of the card: a click on the words or the price picks nothing. - Code: `…` - Your part: Put the words in the slot and the details in `description`, `#media` or `#meta`, not beside the component. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "the row is the label: a click on the text selects", "a click anywhere on a card picks it, its media and its meta included" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#label-is-target ##### Steady width - When: it is a segmented bar. - Props: `variant="segmented"`. - Guarantee: Each segment keeps the same font weight and width whether selected or not, so choosing one does not push the next option sideways. - Without it: The picked segment turns bold, its word grows wider, and the segments after it shift sideways. - Code: `…` - Your part: Nothing. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "segments keep one weight whether chosen or not, so none changes width on a pick" - Pattern for all components: https://grani.arseni.work/patterns/finding#steady-width ##### One Tab per group - When: you choose one answer from a group. - Props: none. - Guarantee: The group takes one press of Tab, on the chosen answer or on the first. The arrow keys change the answer, the same way whether the options are drawn as rows, cards or segments. - Without it: Segments built as separate buttons take a press of Tab each. - Code: `…` - Your part: Nothing. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "is a radiogroup whose radios share one name and reflect the value" - Pattern for all components: https://grani.arseni.work/patterns/opening#one-stop ##### Sent with the form - When: it sits inside a native form. - Props: `name`. - Guarantee: The chosen radio sends its value under the group's `name`, and nothing is sent while none is chosen. After a form reset, the radios show the app's value again. - Without it: Radios on screen that the form never sends, or two groups merged under one name. - Code: `…` - Your part: Give each group in a form its own `name`. - Not covered: A disabled group sends nothing, as a disabled radio does: the form leaves it out. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "in a form the checked radio sends its value under the group name, and none sends nothing", "a form reset leaves the radios on the model, mark and DOM agreeing" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#sends-like-native ##### Focus on the error - When: a form is sent with no option chosen. - Props: `invalid`, or the error of its `UiField group`. - Guarantee: When the group is the first field with an error, keyboard focus lands on the chosen radio, or on the first one when none is chosen, so you can move through the options with the arrow keys. - Without it: The form does not send, keyboard focus stays on Save, and you have to find the field with an error yourself. - Code: `…` - Your part: Pass the error to its `UiField group`, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "focusInvalid on an invalid radiogroup focuses the chosen radio, else the first" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-invalid ##### One name - When: its options have descriptions. - Props: `description`, `#meta`. - Guarantee: Each radio is named by its own words alone; its `description` and `#meta` are announced once, after the name. - Without it: A radio whose announced name runs on into its description. - Code: `Team` - Your part: Put the name in the slot, and the rest in `description` or `#meta`. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "the name is the label text; the description and meta are read once after it" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice ##### Required in words - When: an answer is needed. - Props: `required`, or a required `UiField group`. - Guarantee: The group is announced as required. With its own `required`, each radio carries native `required` too, so a native form checks that an answer was chosen; inside a required `UiField group`, the legend says it once instead. - Without it: An asterisk that a screen reader skips. - Code: `…` - Your part: Set `required` on the group, or on the UiField around it, and check for `null` before you save. - Not covered: A required `UiField group` only says it: the browser checks the group’s own `required`, not the field’s. - Proof, in the repository's tests (UiRadioGroup.spec.ts, not in the package): "required on the group says aria-required and puts required on each input; inside a group field it stays silent" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#required-in-words The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useControlSize`. ### Reveal (`UiReveal`) > Open details where you need them and collapse them again without leaving the page. A component of grani 0.1.0. Layout, stable, since 0.1.0. Page: https://grani.arseni.work/components/reveal Also called accordion, collapsible, disclosure, expandable section. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Keep keyboard focus where you are working. - Reduce motion without hiding loading. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass `controls` from the `#trigger` slot to the trigger as `aria-controls`. A control placed elsewhere points at the block through the block's `id`. #### Why it works this way A block that opens and closes in place, under the control that names it. Take it for settings behind a switch or more options behind a button. **Content.** The block goes in the default slot. With `v-model:open`, a `#trigger` (`{ open, toggle, controls }`), such as a UiSwitch in a UiListItem, stands above it; or `:open` alone follows a control elsewhere, which points at the block by its `id`. **Spacing.** In a card of rows, the block continues the row: it sits on the row's inset, 16 below it. On a padded surface, or on no surface, it stands 16 under what is above it. A nested block keeps that gutter. ##### Keyboard Nothing of its own: the control in `#trigger` keeps its keys (a UiSwitch, a button). - `Tab`: reaches the fields of an open block in their order. When the block closes with the focus inside, the focus goes to the control that names the block in `aria-controls`, else to the element above. Opening leaves the focus on the trigger, as a disclosure does; with `autofocus` it goes to the block's first field, for a block opened to be typed in. ##### Screen reader - Trigger: says the block's state: a button takes `open` as `aria-expanded`, and a switch says it through `aria-checked`. `controls` points the trigger at the block only while the block is shown. - Closed block: its fields leave the page and are not submitted. - Height: the change of height is not announced. ##### States Open and closed, with the height following the content: `ui-reveal` animates a grid row from `0fr` to `1fr`, with the opacity, over `--ui-dur-fast`; under reduced motion the change is instant. With a `#trigger` and `open` unset, it starts closed and keeps its own state. ##### When to use another component - A panel floating beside its trigger: UiPopover. - A record inside a record: a step of UiCrudDrawer. - Panes switched among others: UiTabs. #### Examples ##### Behind a switch ```vue ``` ##### Nested ```vue ``` ##### Own state ```vue ``` #### API Props: - `open`: `boolean` — The block is shown (`v-model:open`); the parent owns it, the trigger only asks. Unset, the block starts closed and keeps its own state, which a `#trigger` toggles. - `autofocus`: `boolean` (default `false`) — When the block opens, the focus goes to its first field: a block opened to be typed in, such as a note. A block shown at mount takes no focus. Attributes are placed by the component itself: its description says where. Events: - `update:open` (`open: boolean`) — The trigger asked for the other state. Slots: - `trigger` with `{ open: boolean; toggle: () => void; controls: string | undefined; }` — The control that opens the block: `controls` is its `aria-controls` while the block is shown; a button also takes `open` as `aria-expanded`, a switch does not (its `aria-checked` says it). - `default` with `Record` — The block shown under the trigger; it stands on the gutter the host gives (16 under what is above, or the row's inset in a card of rows). #### How it behaves ##### Focus stays near - When: The block closes while keyboard focus is inside it. - Props: `v-model:open` with a `#trigger`, or `:open` and an `id` a control points at. - Guarantee: Focus returns to the control that opens the section, or to the nearest button or field above it if no linked control is found. The next Tab continues from there. - Without it: Keyboard focus is lost with the closed block, and you have to find the control again. - Code: ` … ` - Your part: Pass `controls` from the `#trigger` slot to the trigger as `aria-controls`. A control placed elsewhere points at the block through the block's `id`. - Not covered: A control that does not name the block in `aria-controls` and does not stand right above it is not found, so focus is not moved there. - Proof, in the repository's tests (UiReveal.spec.ts, not in the package): "returns focus to the trigger when the block collapses with focus inside it", "closing a block no control names, with focus inside, returns focus to the element above" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-stays ##### Calm motion - When: the block opens or closes, with reduced motion on. - Props: the system setting `prefers-reduced-motion: reduce`. - Guarantee: With reduced motion enabled, the section appears or disappears immediately, without sliding. - Without it: Sections keep sliding open and shut although you asked for less movement. - Code: `…` - Your part: Nothing. - Proof, in the repository's tests (UiReveal.spec.ts, not in the package): "It opens and closes at once when the system asks for reduced motion." - Pattern for all components: https://grani.arseni.work/patterns/waiting#calm-motion The patterns: https://grani.arseni.work/patterns ### Scale input (`UiScaleInput`) > Give a rating on a short labeled scale and, where clearing is allowed, take it back by choosing the same value again. A component of grani 0.1.0. Form, stable, since 0.1.0. Page: https://grani.arseni.work/components/scale-input Also called rating, nps scale, likert scale, score input. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See the value the app actually accepted. - Submit the values shown in the form. - Go straight to the field that needs fixing. - Name states in words, not color alone. - Take back a scale answer. - Change a number with the arrow keys. - Pass a group with one press of Tab. - Name each field once for screen readers. - Announce required fields in words. - Announce scale steps with their meaning. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass the mark the app holds as `modelValue`, and explain why a mark was refused. - Give it a `name`, and check `required` yourself: the hidden input does not. - Pass the error to its `UiField group`, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Keep the numbers or the readout visible. - Treat `null` as no answer. - Put it in a UiField with `group`, or give it `ariaLabel`. - Set `required`, and check for `null` before you save. - Write the end words in `lowLabel` and `highLabel`. #### Why it works this way One mark on a scale of a few steps, 1 to 10 by default. Take it for how hard, how good or how much. **Layout.** A bar of segments is filled up to the mark, with the number in each segment. A readout shows "mark / max" with a unit at its end; the name is the field's, a UiField `group` label over it, or `ariaLabel` alone. Words at the two ends say what low and high mean, and a screen reader hears them with the first and last step. **Empty.** No mark is `null`, as a choice is: a clear sends `null`. **Thermometer.** `variant="thermometer"` colors the fill by the mark in five stops, from danger through warning to success, each with an ink that reads on it. `invert` is for scales where more is worse. **Field.** Standalone it takes `ariaLabel`, `invalid` and `required`. Required is only announced, not enforced, because a hidden input takes no validation. Inside UiField `group` the legend names it, and the description or the error describes it. Invalid tints the empty segments and the frame with the danger tone. **Form.** `name` sends the mark with a form through a hidden input; nothing is sent while there is no answer or the scale is disabled. **Stray values.** A value off the scale shows as no answer. It is dropped only when the scale itself shrinks below it. **Attributes.** Attributes land on the radiogroup, ours where we set one; `class` and `style` on the root. **Steps.** Twelve steps at most, because a narrower segment cannot be hit with a finger. For a free number take UiInput with `numeric`. **Placement.** Beside UiRadioGroup `segmented` and UiInput in a form column. **Loading.** The scale has no loading of its own: while its mark is on its way, its owner draws a UiSkeleton in its shape, a short line where the readout stands over a bar of the control's height for its size (`h-7`, `h-9`, `h-11`), and the field's words at the ends stay, with a `role="status"` of its own that says the load. The demo's Loading tab has it. ##### Keyboard A radiogroup underneath. There is one tab stop: on the mark, or on the first step while there is no answer. - `ArrowLeft` `ArrowRight` `ArrowUp` `ArrowDown`: move the mark from the step in focus; `ArrowUp` at `max` and `ArrowDown` at `min` send nothing. - `Home` `End`: jump to the ends. - `Delete` `Backspace`: clear it; a click on the mark clears it too, and `clearable` off stops both. - `Space` `Enter`: pick the step in focus and never clear. - `Alt` `Ctrl` `Meta`: keys with them go to the browser. After a clear or a refused move, the focus returns to the tab stop. ##### Screen reader - Group: a radiogroup named by the field's legend, or by `ariaLabel`; the field's description or error is read with it. - Step: a radio named by its number out of `max`, the first and the last with their end words; the chosen one is `aria-checked`. - States: `invalid` is `aria-invalid`; `required` is `aria-required` standalone and silent inside a UiField `group`; `disabled` is `aria-disabled`. ##### States No answer (a dash in the readout), a mark with the bar filled to it, hover, focus, disabled (the disabled tokens; it wins over invalid), invalid (the empty segments and the frame in the danger tone, the frame alone on a full bar), required, `thermometer` colored by the mark, inverted, with or without numbers, and a unit in the readout. ##### When to use another component - A free number: UiInput `numeric`. - A count of things: UiStepper. - One answer in words: UiRadioGroup `segmented`. - A mark shown without editing: UiProgress with `:step="1"`, in a table or on a card. #### Examples ##### Thermometer ```vue ``` ##### Unit ```vue ``` ##### Loading ```vue ``` ##### Sizes ```vue ``` ##### States ```vue ``` ##### Refused ```vue ``` ##### Form ```vue ``` #### API Props: - `modelValue`: `number | null` (required) — The mark (`v-model`); `null` while there is no answer. - `min`: `number` (default `1`) — First step of the scale. - `max`: `number` (default `10`) — Last step. Twelve steps at most. - `clearable`: `boolean` (default `true`) — A click on the mark, Delete or Backspace clears the answer; off, an answer once given stays. - `disabled`: `boolean` (default `false`) — Nothing can be picked. - `invalid`: `boolean` (default `false`) — Marks the control invalid: the empty segments and the frame take the danger tone. Inside UiField the error sets this. - `required`: `boolean` (default `false`) — An answer is needed: said to a reader on the group. Not enforced by a form: the hidden input takes no validation. Inside UiField group the legend says it instead. - `unit`: `string` (default `""`) — Shown after the readout: "7 / 10 km". - `readout`: `boolean` (default `true`) — The line "mark / max" above the bar. - `id`: `string` — Own id of the group, for a reference from elsewhere (`aria-controls`, a link); a field names it by its legend. - `name`: `string` — Form field name: a hidden input sends the mark; nothing is sent while there is no answer or the scale is disabled. - `showNumbers`: `boolean` (default `true`) — Numbers in the segments; off for a dense row. - `variant`: `"brand" | "thermometer"` = `brand | thermometer` (default `"brand"`) — `brand` fills with the brand; `thermometer` colors the fill by the mark, danger through warning to success. - `invert`: `boolean` (default `false`) — Reverses the thermometer: more is worse (difficulty, pain, load). - `lowLabel`: `string` (default `""`) — What the low end means: "easy". - `highLabel`: `string` (default `""`) — What the high end means: "hard". - `ariaLabel`: `string` — Accessible name of the scale when there is no UiField around. - `size`: `"sm" | "xs"` = `xs | sm` — Height of the bar on the control ladder: `xs` 28, `sm` 36. Unset, the app's size (`createGrani({ size })`); `md` is read as `sm`: the scale has no `md`. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Events: - `update:modelValue` (`value: number | null`) — The mark changed; `null` after a clear. #### How it behaves ##### Back to the value - When: the app refuses a mark, or the form is reset. - Props: `v-model`, or `modelValue` with `@update:model-value`. - Guarantee: If the app rejects a rating, the scale returns to the accepted value. When you Tab into it again, focus starts on that value. - Without it: The bar is filled to a mark the app did not accept. - Code: `` - Your part: Pass the mark the app holds as `modelValue`, and explain why a mark was refused. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "a refused pick leaves the bar and the tab stop on the model" - Pattern for all components: https://grani.arseni.work/patterns/waiting#refused-goes-back ##### Sent with the form - When: it sits inside a native form. - Props: `name`. - Guarantee: A hidden input sends the chosen step under its `name`; with no answer, or while disabled, nothing is sent. - Without it: A scale on screen that the form never sends. - Code: `` - Your part: Give it a `name`, and check `required` yourself: the hidden input does not. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "in a form the mark sends under the name, none and disabled send nothing" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#sends-like-native ##### Focus on the error - When: a form is sent with no step chosen. - Props: `invalid`, or the error of its `UiField group`. - Guarantee: When the scale is the first field with an error, keyboard focus lands on the chosen step, or on the first step when none is chosen, so you can pick an answer from the keyboard. - Without it: The form does not send, keyboard focus stays on Save, and you have to find the field with an error yourself. - Code: `` - Your part: Pass the error to its `UiField group`, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "focusInvalid on an invalid scale focuses the chosen segment, else the first" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-invalid ##### Words, not only color - When: the fill is colored by the answer. - Props: `variant="thermometer"`, `invert`. - Guarantee: The color comes with the number on each segment and with the readout, such as “7 / 10”; each number takes a text color that stays readable on its segment, filled or empty. - Without it: A bar that turns red with no number to say how far. - Code: `` - Your part: Keep the numbers or the readout visible. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "thermometer numerals take the ink that reads on their stop", "empty numerals read in the body ink on their track" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#level-not-by-colour ##### Answer cleared - When: an answer may be withdrawn. - Props: `clearable`, on by default. - Guarantee: A click on the chosen step, Delete or Backspace clears the answer to `null`; Space and Enter never clear. With `clearable` off, an answer once given stays. - Without it: As with native radios, once a step is checked, the answer cannot be taken back. - Code: `` - Your part: Treat `null` as no answer. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "a click picks; a click on the mark clears unless clearable is off", "Delete and Backspace obey clearable=false", "Space on the mark keeps it" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#mark-taken-back ##### Arrows step - When: you set the answer from the keyboard. - Props: none. - Guarantee: The arrow keys move the answer from the step that has keyboard focus, Home and End jump to the ends, and an arrow key past an end changes nothing. - Without it: A row of buttons that the arrow keys do not move. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "one tab stop, on the mark; arrows, Home, End move it and Delete clears", "ArrowUp at max and ArrowDown at min emit nothing" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#number-by-arrows ##### One Tab per group - When: a question is answered on a scale. - Props: none. - Guarantee: The scale takes one press of Tab, on the chosen step, or on the first step while there is no answer. The arrow keys move the mark, and Home and End take it to the ends. - Without it: Each step is its own button, so a scale of ten steps takes ten presses of Tab to pass one question. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "one tab stop, on the mark; arrows, Home, End move it and Delete clears" - Pattern for all components: https://grani.arseni.work/patterns/opening#one-stop ##### One name - When: it sits in a field. - Props: a `UiField group` around it, or `ariaLabel`. - Guarantee: The field's label names the scale as a whole, and the description or the error is announced with it, once; each step keeps its own short name. - Without it: A scale announced with two names, or with none. - Code: `` - Your part: Put it in a UiField with `group`, or give it `ariaLabel`. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "inside UiField the label names the group and the description describes it" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice ##### Required in words - When: an answer is needed. - Props: `required`, or a required `UiField group`. - Guarantee: On its own, the scale is announced as required (`aria-required`); inside a required `UiField group`, the legend says it once instead. The requirement is only announced: the browser does not check it when the form is sent. - Without it: An asterisk that a screen reader skips. - Code: `` - Your part: Set `required`, and check for `null` before you save. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "required on the scale says aria-required standalone and stays silent inside a group field" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#required-in-words ##### Ends named - When: its ends mean something. - Props: `lowLabel`, `highLabel`. - Guarantee: Each step is named by its number out of the total, “7 of 10”, and the first and last add their end words: “1 of 10, easy”, “10 of 10, hard”. - Without it: Steps named by their number alone: the words under the ends are printed, but never announced with the step. - Code: `` - Your part: Write the end words in `lowLabel` and `highLabel`. - Proof, in the repository's tests (UiScaleInput.spec.ts, not in the package): "the first and last radio name their end words" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#mark-says-its-word The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useControlSize`, `useUiT`. ### Select (`UiSelect`) > Search for and choose one or more options. Enter selects an option without also submitting the form. A component of grani 0.1.0. Form, stable, since 0.1.0. Page: https://grani.arseni.work/components/select Also called dropdown, combobox, autocomplete, searchable select. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Results match the current search. - See the value the app actually accepted. - Submit the values shown in the form. - Finish a word in any script before it is sent. - Clear a search in one step. - Keep nearby buttons and fields in place. - Keep nearby content in place while loading. - Open a panel on the side where it fits. - Close only the top layer with Escape. - Close a popup without closing the form behind it. - Go straight to the field that needs fixing. - Close an open picker when its field is disabled. - Read the full text when a label is shortened. - Notice when there are more options below. - Clear a field and enter its replacement immediately. - Search once typing pauses. - Jump to an option by letter. - Pick with Enter without sending the form. - Keep your browser’s keyboard shortcuts. - Remove selected tags with the keyboard. - Open with keyboard focus where the task begins. - Continue from where you opened the panel. - Name each field once for screen readers. Implemented by the app: - Data fetching, saving, permissions and business rules. - Return the options for the query you are given. When you prefill a value, also pass its option in `items`, such as `{ value: 7, label: 'Anna Petrova' }`. - Pass the value the app holds as `modelValue`, and explain why a choice was refused. - Give it a `name`. - Give the field a width where the row needs one; without it, the field is as wide as its longest option. - Pass `loading` while the options load; a `fetcher` reports its own loading. - Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Treat `null` as no answer. - Return the options for the query you are given. - Put it in a UiField with a `label`, or give it `ariaLabel`. #### Why it works this way A form control for picking one value from a list of options, or several with `multiple`. It sits in the input capsule on the control ladder. **Placement.** In a form, under a UiField label beside UiInput and UiDatePicker on the same step, or joined with a UiInput in a UiButtonGroup (an amount and its currency); as the kind filter of UiLog past three kinds. **Panel.** The trigger is a button with the combobox role. The list is a listbox in a panel anchored under it; the panel flips above when there is no room below and follows scrolling. **Options.** Items are options or groups of options. A disabled option is shown but cannot be picked. While the app's options are on their way it passes `loading`: with none yet the list draws rows in their shape, never "No matches"; with options in view they stay, dimmed, still to be picked, and the highlight keeps to its option as they change. A picked value whose option has not come yet reads as a load in the field and is sent as it is; once the load is over, a value no option knows shows as its own text and is sent, so the field never looks empty while the form holds a value, and in development the console names it once per app. An empty string no option has is nothing picked, as `null` is. With `fetcher` the select says its own load and `loading` does nothing. A list that loads holds the height it reached while open, until a filter narrows options already in. **Types.** The model's shape follows `multiple`: one value or `null` without it, an array with it, and the props reject the other. A `multiple` decided at run time is two branches (`v-if` with the array model, `v-else` with the single one). `update:modelValue` carries either shape: an explicit handler casts what it receives, `v-model` needs nothing. **Search.** `searchable` puts a filter at the top of the list; an option's `keywords` are matched too. The filter leaves the accents of Latin and Cyrillic letters out, so a name typed without them is found ("munchen" finds München) and the Cyrillic yo reads as ie; the Cyrillic short i stays a letter of its own. `fetcher` asks a server for the options as the filter is typed. The picked options are remembered, so their labels survive a new search. While the first answer is on its way the list draws rows of the options' shape, and while it is open it never shrinks, so nothing under the pointer moves as answers come. A failed search offers Try again, which asks once more; a search that matches nothing offers Clear search. **Clear.** `clearable` adds a button that resets the value to `null`, or `[]` with `multiple`: a choice is a value or `null`. A required field never gets it, since there empty is an error, not a state. Its place is kept while there is nothing to clear. **Width.** A single pick from a local list keeps the field's width: the text is sized to the longest labels, counted in letters, so a label of wide letters outside the three longest can still widen it. A chosen label longer than the field is cut, and shows whole in a tooltip on hover while the list is closed. **Multiple.** `multiple` turns the rows into check marks and the model into an array, and a pick keeps the list open. The trigger shows the count of picks, and each pick stands below the field as a tag with a cross. **Picks.** With `multiple`, the `#picks` slot draws the picks under the field the app's way, in place of tags: a row with what the app keeps for each, a quantity, a price. The field becomes a search that adds; it keeps its placeholder, since the picks are in view below. The value stays the list of picked values in the order they were picked; what a row holds besides is the app's. A disabled select takes no pick back, and hands `disabled` to the rows, so the app can hold its own controls too. **Field.** Standalone it takes `invalid` and `ariaLabel`; inside UiField it reads id, error and required from the field. **Attributes.** `class` and `style` land on the select's outer box: the capsule, or with tags or the app's picks the box that holds the capsule and them; every other attribute and listener lands on the trigger, the combobox. ##### Keyboard On the closed field: - `ArrowDown` `ArrowUp` `Enter` `Space` `Home`: open the list, and so do `Alt+ArrowDown` `Alt+ArrowUp`; `Ctrl` or `Meta` with a key stays the browser's. - `End`: opens the list on the last option. - `A–Z`: opens it on the first label that starts with the letter, or starts the filter when there is one. - `Backspace`: with `multiple`, removes the last pick. In the open list: - `ArrowDown` `ArrowUp`: move over the enabled options. - `Home` `End`: jump to the first and the last option; in the filter they move the caret. - `Enter`: picks; never submits the form around it. While the answer to the typed text is on its way it picks nothing. After a failed search it asks again. A pick closes a single list and returns the focus to the field; a `multiple` list stays open. - `Space`: picks, outside the filter; after letters typed over the list it belongs to the word. - `A–Z`: jumps to the first match; letters typed together find a word. - `Escape`: closes the list and returns the focus to the field; inside a window it closes only the list, and in a filter with text it clears the text first. - `Tab`: closes the list and moves on to the next field. A pointer press outside closes it too. On a tag: - `Enter` `Space`: on its cross, removes that pick and moves the focus to the next tag, or to the field. ##### Screen reader - Field: a combobox named by `ariaLabel` or the field's label. It says the chosen label, the count of picks or the placeholder, whether it is expanded, and that it opens a listbox. - List: a listbox with the same name, `aria-multiselectable` with `multiple`. A group's heading is shown but is not an option. - Options: each says selected and disabled. The highlighted one is tracked through `aria-activedescendant` on the field, or on the filter, a named text box with `aria-autocomplete`. - Status: a region that stays in the DOM says what the list is doing: "Searching…" for a `fetcher`, "Loading options…" and "Updating…" for the app's load, then "No matches" to a search, "No options" to none, or the failure, once nothing is on its way. - Errors: `invalid` is `aria-invalid`, `required` is `aria-required`, and the field's description and error are read with the field. - Tags: they stand in a named list, each cross is named with its label, and the clear button has a name. ##### States Empty with the placeholder, a pick, open with the chosen option highlighted, a disabled option, groups, the app's options on their way (`loading`: rows of their shape, then dimmed), `searchable` with its filter, a server search (rows of the options' shape while the first answer is on its way, the previous options dimmed while a new query waits, no matches with Clear search, failed with Try again, the list holding the height it reached while open; a late answer is dropped), `multiple` with check marks and a count, with tags below the field, or with the app's rows below it, `clearable` with the cross and its place kept, disabled (the plate, an inert trigger, nothing sent), invalid (a red border; disabled wins over it), and required, with no cross. ##### When to use another component - A few answers in view: UiRadioGroup. - Several answers in view: UiCheckbox in a UiField `group`. - A time of day: UiTimePicker. - A day: UiDatePicker. - Commands: UiMenu. - A list that adds what is typed: UiListField. #### Examples ##### Search ```vue ``` ##### Multiple ```vue ``` ##### Order ```vue ``` ##### Sizes ```vue ``` ##### Loading ```vue ``` ##### States ```vue ``` ##### Refused ```vue ``` ##### Form ```vue ``` ##### Long ```vue ``` ##### Russian ```vue ``` #### API Props: - `items`: `SelectItem[]` (default `[]`) — Options or groups of options with labels. With `fetcher` they are the known labels: a prefilled value shows its label before the server answers. - `fetcher`: `((query: string) => Promise)` — Asks a server for the options: called with the filter text on open and as it is typed (250 ms after the last key); a late answer to an older query is dropped. Implies `searchable`. - `loading`: `boolean` (default `false`) — The options the app passes in `items` are on their way: with none yet, rows in their shape; with options in view, they stay, dimmed. A `fetcher` says this by itself. - `placeholder`: `string` — Shown when nothing is selected. - `name`: `string` — Native name for forms. The value is submitted through a hidden input. - `id`: `string` — Own id when standalone. Inside UiField, the field's id takes precedence. - `disabled`: `boolean` (default `false`) — Prevents opening and clearing. - `invalid`: `boolean` (default `false`) — Marks the control as invalid. Shows the invalid border and focus ring. Inside UiField, the error state sets this automatically. - `ariaLabel`: `string` — Accessible name when there is no visible label. - `size`: `ControlSize` = `xs | sm | md` — Step of the control ladder. Unset, the app's size (`createGrani({ size })`), `sm` by default. - `searchable`: `boolean` (default `false`) — Adds a filter to the option list. Typing narrows options by label. - `clearable`: `boolean` (default `false`) — Adds a button that resets the value to `null`, or to `[]` with `multiple`; never shown on a required field. - `required`: `boolean` (default `false`) — Standalone only: empty is an error, said to a reader, and no cross. Inside UiField the field's `required` says so. - `tags`: `boolean` (default `false`) — With `multiple`: every pick as a tag with a cross below the field, the trigger counting them. Without it the picks are listed in the trigger, which fits a narrow place such as a toolbar. - `tagSize`: `"sm" | "md"` = `sm | md` (default `"md"`) — Size of the tags, as a UiBadge's. - `modelValue`: `SelectValue | SelectValue[] | null` (required) — The selected value (`v-model`): `null` when nothing is selected; with `multiple`, the picked values in the order they were picked, `[]` when none is. - `multiple`: `boolean` (default `false`) — Several values: check marks in the rows, an array in the model, the list stays open after a pick. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Events: - `update:modelValue` (`value: SelectValue | SelectValue[] | null`) — The selected value changed; `null` (or `[]` with `multiple`) after clearing. Slots: - `start` with `Record` — Before the value, inside the trigger: a glyph that says what is chosen (a clock, a flag). Decoration. - `picks` with `{ options: SelectOption[]; remove: (option: SelectOption, event?: MouseEvent | undefined) => void; disabled: boolean; }` — With `multiple`: the picks drawn by the app under the field, in place of tags, the field a search that adds to them. `options` are the picked options as given in `items` or by the `fetcher`; `remove` takes one back and puts the focus on the field (pass the click, `remove(option, $event)`, and a double click's second click on the row sliding under the pointer is held back); `disabled` is the field's, and while it holds `remove` does nothing. #### How it behaves ##### Late answer dropped - When: the options come from a server. - Props: `fetcher`, `items` for a value given in advance. - Guarantee: A search response is shown only if it still belongs to the current query; a response to an older one is ignored instead of replacing newer results. The option you chose keeps its name in the field when a new search no longer returns it, and a value set in advance shows the label given in `items` before the first search answers. - Without it: Every answer is shown as it arrives, so a slow answer to an old query covers the newer one, and the choice turns into its raw value once the results change. - Code: `` - Your part: Return the options for the query you are given. When you prefill a value, also pass its option in `items`, such as `{ value: 7, label: 'Anna Petrova' }`. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "a late answer to an older query is dropped", "a picked option keeps its label after the server answers another query", "items seeds the label of a prefilled value before the first fetcher search resolves" - Pattern for all components: https://grani.arseni.work/patterns/finding#late-dropped ##### Back to the value - When: the app refuses a choice, or the form is reset. - Props: `v-model`, or `modelValue` with `@update:model-value`. - Guarantee: If the app refuses your choice, the field shows the previous option again, and the form still sends that option. A form reset brings back the app’s value. - Without it: The field shows an option the app did not accept. - Code: `` - Your part: Pass the value the app holds as `modelValue`, and explain why a choice was refused. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "a change the parent refuses puts the select back on the model" - Pattern for all components: https://grani.arseni.work/patterns/waiting#refused-goes-back ##### Sent with the form - When: it sits inside a native form. - Props: `name`. - Guarantee: The chosen value is included under its `name` through a hidden input. An empty or disabled select sends nothing. After a form reset, the visible choice and the submitted value both match the app’s current value. - Without it: A list on screen that the form never sends. - Code: `` - Your part: Give it a `name`. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "an empty select sends nothing under its name", "a form reset leaves the select on its model, hidden input and trigger agreeing" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#sends-like-native ##### Words in the making - When: its search is typed through an input method. - Props: `searchable`. - Guarantee: The Enter that picks the word picks no option. - Without it: An option chosen by the key that only meant to finish a word. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "an Enter that confirms an IME composition in the search picks nothing" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#word-as-composed ##### Search clears - When: the filter has text. - Props: `searchable` or `fetcher`. - Guarantee: A cross clears the filter and keeps keyboard focus in it. Escape clears it first and keeps the list open; a second Escape closes the list. - Without it: A filter you can clear only by selecting its text and deleting it. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "the search clears its own text on Escape and keeps the panel open; a second Escape closes it" - Pattern for all components: https://grani.arseni.work/patterns/finding#search-clears ##### Steady width - When: one option is picked from a list it holds. - Props: `items`, without `fetcher` or `multiple`. - Guarantee: Picking an option, or clearing it, does not move the fields beside it: the field reserves the width of its longest option or its placeholder, and keeps the place of the clear button while it is hidden. - Without it: A field as wide as its text: a longer option widens it at the pick and pushes the field beside it. - Code: `` - Your part: Give the field a width where the row needs one; without it, the field is as wide as its longest option. - Not covered: Options from a server (`fetcher`) and several picks (`multiple`) are not known in advance, so their field does not reserve the longest one. The longest labels are counted in letters: one of wide letters outside the three longest can still widen the field. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "the field keeps its width: the text stands over the longest labels, the cross keeps its place", "the clear cross pulls to the capsule edge and, at xs, fits inside the capsule; its kept place matches it" - Pattern for all components: https://grani.arseni.work/patterns/finding#steady-width ##### Stable dimensions - When: the app loads the options itself. - Props: `loading`. - Guarantee: While the list has no results, it shows placeholders shaped like options, with checkboxes when `multiple` is enabled. Once open, it keeps the height it has reached as options arrive. A selected value whose option is still loading shows a loading state in the field. - Without it: An empty list says nothing matches, then grows under the pointer when the options arrive. - Code: `` - Your part: Pass `loading` while the options load; a `fetcher` reports its own loading. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "options the app is loading show rows in their shape and say so, never "No matches"" - Pattern for all components: https://grani.arseni.work/patterns/waiting#no-jolt ##### Opens where it fits - When: its field stands near the bottom of the window. - Props: none. - Guarantee: The list opens above the field when the room below is too short for it and the room above is longer, and under it otherwise. It never covers the field and never leaves the window. - Without it: A list under a field at the end of a long form runs off the screen. - Code: `` - Your part: Nothing. - Not covered: The room is measured in the window, not in a scrolling box inside the page. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "near the bottom of the window the list opens above the field; near the top, below it" - Pattern for all components: https://grani.arseni.work/patterns/opening#opens-where-fits ##### Escape, top first - When: its list is open inside a window or a drawer. - Props: none. - Guarantee: Escape closes the list only, and keyboard focus goes back to the field; the window stays open. With text in its search, the first Escape clears the text and the list stays. - Without it: One Escape closes the list and the form behind it at once. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "Escape on the trigger of an open select inside a modal closes the list only", "Home and End jump, Escape closes and returns focus to the trigger", "the search clears its own text on Escape and keeps the panel open; a second Escape closes it" - Pattern for all components: https://grani.arseni.work/patterns/closing#escape-top ##### Outside, top first - When: its list is open inside a window or a drawer. - Props: none. - Guarantee: A press outside the list, on the backdrop too, closes the list alone, and the window stays open; the next press there closes the window. - Without it: A press beside the list closes the window under it as well, with the form in it. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "a press outside its list inside a modal closes the list and keeps the modal" - Pattern for all components: https://grani.arseni.work/patterns/closing#press-top ##### Focus on the error - When: a form is sent with no choice made. - Props: `invalid`, or the error of its UiField. - Guarantee: When the select is the first field with an error, keyboard focus lands on its button, so you can open the list and choose straight away. - Without it: The form does not send, keyboard focus stays on Save, and you have to find the field with an error yourself. - Code: `` - Your part: Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "focusInvalid on an invalid select focuses the trigger" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-invalid ##### Off closes - When: it is disabled while its list is open. - Props: `disabled`. - Guarantee: The list closes and keyboard focus stays on the field. - Without it: The list stays open over a field that no longer accepts a choice. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "disabling while open closes the list and keeps the focus on the field" - Pattern for all components: https://grani.arseni.work/patterns/closing#off-closes ##### Whole text - When: the chosen option is longer than its field. - Props: none. - Guarantee: The field shows the chosen label on one line, cut with an ellipsis, and its whole text shows in a tooltip on hover while the cut is real. The chevron and the clear button stay in view. - Without it: A long client name cut at the end of a narrow field, with no way to read the rest but opening the list. - Code: `` - Your part: Nothing; give the field the width its row allows. - Not covered: Only the mouse shows it: a tap opens the list, keyboard focus opens no tooltip, and while the list is open there is none, since it would stand over the rows; the rows of the list are cut too. A screen reader hears the whole label. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "a chosen label stands in a UiTruncate, its whole text in the tooltip while cut", "the whole-label tooltip stays away while the list is open, where it would stand over the rows" - Pattern for all components: https://grani.arseni.work/patterns/finding#whole-text ##### Five and a half rows - When: the list is long. - Props: none. - Guarantee: The list is cut at five and a half rows, so the half row shows there is more below. - Without it: A list cut at a row edge that looks finished. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "a long list is cut at five rows and a half" - Pattern for all components: https://grani.arseni.work/patterns/finding#five-rows ##### Cleared in place - When: An answer may be left empty. - Props: `clearable`. - Guarantee: The × sets the value to `null`, or to `[]` with `multiple`, and keyboard focus moves to the field. A required field has no ×. - Without it: The × empties the field and keyboard focus is lost, so you have to find the field again. - Code: `` - Your part: Treat `null` as no answer. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "the clear button keeps the focus on the field" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#cleared-in-place ##### Asks once - When: the options come from a server. - Props: `fetcher`. - Guarantee: Opening the list calls `fetcher` with an empty query. Typing calls it after a 250 ms pause. Reopening after a search requests the empty query again. While results are loading, the visible options remain in place and are dimmed. A list closed within the pause asks nothing, and the closed field shows its value, not a load. - Without it: A request on every key. - Code: `` - Your part: Return the options for the query you are given. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "asks the server on open with an empty query, then 250 ms after the last key", "reopening after a search asks once for the empty query", "a press outside while a search waits asks the server for nothing", "a search dropped before it was asked leaves the closed field showing its value, not a load", "an answer on its way when the list closes changes nothing: the field shows its value" - Pattern for all components: https://grani.arseni.work/patterns/finding#typing-asks-once ##### Letter jumps - When: the list has no filter field. - Props: none. - Guarantee: On the closed field, a letter opens the list with the first option that starts with it highlighted; in the open list, it moves the highlight there. The same letter again goes on to the next option that starts with it. Letters typed together find a word, its spaces too: "new j" reaches New Jersey. - Without it: A long list that you walk one row at a time with the arrow keys. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "a letter jumps to the first label with that prefix", "a letter on the closed field opens on the first label that starts with it, the chosen one too", "a Space after letters typed over the list belongs to the word: New J reaches New Jersey" - Pattern for all components: https://grani.arseni.work/patterns/finding#letter-jumps ##### Enter picks - When: The select is inside a form. - Props: `searchable`, `fetcher`, or none. - Guarantee: On the closed select, Enter opens the list. In the open list or its search box, Enter picks the highlighted option. In both cases the form around it is not submitted. While the answer to the text typed in a server search is on its way, Enter picks nothing: the rows in view answer an older word. - Without it: With a plain text field and a list under it, Enter submits the form before anything is picked. - Code: `

` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "inside a form Enter picks and the form is not submitted", "Enter while the answer to the typed text is on its way picks nothing; once it comes, Enter picks from it" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#enter-picks ##### Shortcuts kept - When: the field or its open list has keyboard focus. - Props: none: every UiSelect. - Guarantee: Alt+Down opens the list, as on a native select. With Ctrl or Cmd held an arrow opens nothing and moves no highlight, so the browser’s own shortcut runs. - Without it: Ctrl+Down, meant for the page, opens the list or moves its highlight instead. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "Alt with ArrowDown opens the list, as a select does; Ctrl or Meta leave the key", "in the open list Ctrl or Meta with an arrow moves no highlight and leaves the key" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#shortcuts-kept ##### Tag taken back - When: Selections show as tags. - Props: `multiple`, `tags`. - Guarantee: A tag's × removes that selection and moves keyboard focus to the next tag, or back to the field after the last tag. With the list closed, Backspace on the field removes the last selection shown. A value missing from `items` shows as its own text, so it is one of them. - Without it: A tag’s cross takes the keyboard focus away with the tag: it falls to the page, and a screen reader loses its place. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "the cross of a tag drops that pick and moves the focus to the next tag", "removing the last tag puts the focus back on the field", "Backspace takes back the last pick in view, a value outside items shown as its text too" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#tag-taken-back ##### Focus starts inside - When: its list has a search field. - Props: `searchable` or `fetcher`. - Guarantee: Opening the list puts keyboard focus in its search field, so typing narrows the options at once. When nothing matches, the list says so in words instead of showing an empty box. - Without it: The list opens with keyboard focus left on the field, and you press Tab or click before you can search. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "focuses the filter, narrows by label, and says when nothing matches" - Pattern for all components: https://grani.arseni.work/patterns/opening#focus-start ##### Focus comes back - When: the list closes. - Props: none. - Guarantee: After choosing an option, pressing Escape, or pressing Tab from the list’s search field, focus returns to the select field. Clicking outside closes the list and leaves focus where you clicked. - Without it: The list closes and keyboard focus falls to the page: a screen reader loses its place, and you look for the field again. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "Home and End jump, Escape closes and returns focus to the trigger", "Tab from the filter closes and puts focus back on the trigger", "after a pick from a searchable list the focus is back on the field; a press outside leaves it where it was" - Pattern for all components: https://grani.arseni.work/patterns/opening#focus-back ##### One name - When: it needs a name. - Props: a UiField around it, or `ariaLabel`. - Guarantee: The select and its open list are announced once, by the field's label or by `ariaLabel`; the description and the error are announced with it. - Without it: A list announced with two names, or a select named only by its placeholder. - Code: `` - Your part: Put it in a UiField with a `label`, or give it `ariaLabel`. - Proof, in the repository's tests (UiSelect.spec.ts, not in the package): "takes id, required, error and description from the field", "a standalone listbox takes the ariaLabel" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useControlSize`, `useUiT`. ### Separator (`UiSeparator`) > Separate groups in a menu, toolbar or card with a simple dividing line. A component of grani 0.1.0. Layout, stable, since 0.1.0. Page: https://grani.arseni.work/components/separator Also called divider, horizontal rule. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. Implemented by the app: - Data fetching, saving, permissions and business rules. #### Why it works this way A line between groups of content. Take it between menu items, parts of a toolbar or groups of a UiButtonGroup. **Spacing.** It has no margin of its own: the parent's gap spaces it. On a padded surface, a horizontal line runs through the gutter to the edges by itself; your own `-mx-*` is only for a place with no gutter. A vertical line stretches to the height of its flex row; in a UiButtonGroup it stands across the group. **Border.** It is a border, not a fill, because forced colors keep borders. ##### Keyboard Not interactive: it takes no focus and no tab stop. ##### Screen reader - Line: a `separator` with its `aria-orientation`: a break between groups and nothing more. ##### States None: one line, horizontal or vertical, through a surface's gutter or across a row; a border, so forced colors keep it. ##### When to use another component - The line under a section title: UiHeader `legend`; where a legend opens a section, the legend is the line. - The line between rows of a list: UiList draws it. - Lines under a card's header and above its footer: UiCard draws them. - The lines between the flat sections of an overlay: the overlay places them, as UiDrawer does. #### Examples ##### In a row ```vue ``` ##### In a button group ```vue ``` ##### In a menu ```vue ``` #### API Props: - `orientation`: `"horizontal" | "vertical"` = `horizontal | vertical` — `horizontal` spans the width between stacked blocks; `vertical` stands between items of a row. Default: across the enclosing UiButtonGroup, else horizontal. Anything else lands on the root element: native attributes, aria-*, data-testid. ### Skeleton (`UiSkeleton`) > Show where content will appear while it loads, holding its space so the page around it moves less. A component of grani 0.1.0. Status, stable, since 0.1.0. Page: https://grani.arseni.work/components/skeleton Also called loading placeholder, shimmer, content placeholder. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See where the app is working. - Keep nearby content in place while loading. - Reduce motion without hiding loading. Implemented by the app: - Data fetching, saving, permissions and business rules. - Show it from the start of the request until the answer, and never next to a spinner for the same wait. - Give it the size and shape of the content to come, and remove it when the data arrives. Inside a card, a table, a drawer or a chart card, set their `loading` instead. #### Why it works this way The shape of content on its way. Take it in a block of your own while its first load runs; a card, a table, a drawer and a chart card draw their own under `loading`. **Size.** Size and shape come from the classes the host passes (`h-4 w-32`, `h-64 w-full`, `rounded-pill` for an avatar); without them it has no size. A line of text is an `inline-block h-3 align-middle` inside a block of the text's size, which keeps the line's height. A page skeleton is several of these, mirroring the real layout. **Decoration.** It is decoration, and its shimmer is the sign that the first load runs: under reduced motion it keeps shimmering, slower, since a still gray block reads as a broken page. The host's live region announces the loading state. **By hand.** UiCard, UiTable, UiDataTable, UiCrudDrawer and UiChartCard (with its charts) draw it themselves under `loading`. Place it by hand only in blocks of your own, which bring their own `role="status"` and drop it when the data comes. ##### Keyboard Not interactive: it takes no focus and holds no control. ##### Screen reader - Hidden: `aria-hidden`; the loading state is announced by the host's live region, a `role="status"` the host brings and drops when the data comes. ##### States One: a shimmering block, slower under reduced motion, in the size and shape the host's classes give it; without them it has no size. ##### When to use another component - An action in flight: UiSpinner. - Work measured or of unknown length: UiProgress. - Nothing there or a failed load: UiNoData. - Loading a card, a table, a drawer or a chart card: UiCard, UiTable, UiCrudDrawer and UiChartCard draw it themselves under `loading`. #### Examples ##### By hand ```vue ``` ##### Blocks ```vue ``` #### API No props, events or slots of its own. Anything else lands on the root element: native attributes, aria-*, data-testid. #### How it behaves ##### Visible work - When: on a first load whose layout is known. - Props: shown from the request to its answer. - Guarantee: Placeholders show that content is still loading and where it will appear; their shimmer shows that loading is in progress. - Without it: A blank space that looks empty rather than loading. - Code: `` - Your part: Show it from the start of the request until the answer, and never next to a spinner for the same wait. - Proof, in the repository's tests (UiSkeleton.spec.ts, not in the package): "A hidden block in the shape its host gives it." - Pattern for all components: https://grani.arseni.work/patterns/waiting#visible-work ##### Stable dimensions - When: on a first load. - Props: the host gives it the size and shape of what comes. - Guarantee: The placeholder reserves space in the shape of the expected content, so when the content replaces it nothing nearby moves, as long as the dimensions match. - Without it: The space stays empty, and when the content arrives everything below it jumps down. - Code: `` - Your part: Give it the size and shape of the content to come, and remove it when the data arrives. Inside a card, a table, a drawer or a chart card, set their `loading` instead. - Not covered: It does not announce that the page is loading; the surrounding component’s `role="status"` does. - Proof, in the repository's tests (UiSkeleton.spec.ts, not in the package): "A hidden block in the shape its host gives it." - Pattern for all components: https://grani.arseni.work/patterns/waiting#no-jolt ##### Calm motion - When: reduced motion is on. - Props: the system setting `prefers-reduced-motion: reduce`. - Guarantee: The placeholder animation slows from one pulse every 2 seconds to one every 3 seconds. - Without it: The placeholders stand still and gray, and the page looks stalled rather than loading. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiSkeleton.spec.ts, not in the package): "It keeps shimmering, slower, when the system asks for reduced motion." - Pattern for all components: https://grani.arseni.work/patterns/waiting#calm-motion The patterns: https://grani.arseni.work/patterns ### Sparkline (`UiSparkline`) > See a value's recent trend beside the number, with gaps where data is missing. A component of grani 0.1.0. Charts, stable, since 0.1.0. Page: https://grani.arseni.work/components/sparkline Also called mini chart, trend line, inline chart. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Show missing data as a gap. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass `null` where there is no data, and `0` only for a real zero. #### Why it works this way A small trend with no axes, beside the number it belongs to. Take it in a table cell, in a strip's actions beside a UiDelta, or under a headline in a UiChartCard. **Shapes.** `line` and `area` stretch in one viewBox, with a dot on the newest value kept inside the box; a flat run stands at mid-height. `bar` draws HTML boxes from zero: the newest one (or `highlight`) is full, and the rest are pale with a line at their height, so each still reads. Bars stand 4px apart while there is room; a long run in a narrow host closes the gaps. **Gaps.** A `null` is no data: the line breaks (a single value between two gaps is a dot), and a bar's place stays empty. A zero is a stub on the zero line. Size and tone. The host sets the width, and `height` sets the height. Set `tone` to agree with the verdict beside it. `mark` draws one reference line, an average or a plan, named at its end. In a card. In a UiChartCard it draws its shape pale on the first load and holds it still when there is nothing to draw. ##### Keyboard Not interactive: no tab stop, no keys; the number beside it carries the value. ##### Screen reader - Name: without `ariaLabel` it is hidden (`aria-hidden`), and the number beside it says the value; with one it is an image with that name, followed by the mark's label ("Average receipt, the last 12 months, 12-month average 43.06"). - Values: not read; a chart a reader can walk is UiAreaChart or UiBarChart. - Hidden: on a card's first load, when the card has nothing to draw, and when no value is a number, whatever its name. ##### States `line`, `area` and `bar`, a dot on the newest value or on `highlight`, a gap (`null`) that breaks the line or leaves a bar's place empty, a loss below the zero line, a flat run at mid-height, a `mark` with its name, six tones. In a UiChartCard: its first load as a pale shape, nothing to draw held still, a refresh dimmed by the card. No hover or focus state of its own. ##### When to use another component - A chart with axes, a legend and a tooltip: UiAreaChart or UiBarChart. - A share of a whole: UiProgress. - The verdict beside it: UiDelta. - A single figure with a trend as a card: UiChartCard with `bleed="full"`. #### Examples ##### Tones ```vue ``` ##### Mark ```vue ``` ##### Beside a number ```vue ``` ##### In a table ```vue ``` ##### Gaps ```vue ``` ##### In a card ```vue ``` #### API Props: - `values`: `(number | null)[]` (required) — The values in order, the newest last; `null` is no data, a gap. - `variant`: `"line" | "area" | "bar"` = `line | area | bar` (default `"line"`) — `line` a trend, `area` the same filled below, `bar` one box per value from zero. - `tone`: `Tone` = `brand | neutral | success | warning | danger | info` (default `"brand"`) — What the trend means: `brand` for a figure of the product, `success` or `danger` for a verdict, `neutral` for a quiet one. - `endpoint`: `boolean` (default `true`) — A dot on the newest value of a line or an area. - `height`: `number` (default `28`) — The height in pixels; the host sets the width. - `highlight`: `number` — The index of the value in light: the full bar, or the dot on a line; the newest value when unset. - `mark`: `{ at: number; label: string; }` — A line of reference across the trend, named at its end: `{ at: 43.06, label: '12-month average 43.06' }`. - `ariaLabel`: `string` (default `""`) — What the trend shows, for a screen reader: "Average receipt, the last 12 months". Unset, it is decoration. Anything else lands on the root element: native attributes, aria-*, data-testid. #### How it behaves ##### A gap, not a zero - When: a value is missing. - Props: `values` with `null` where there is no data. - Guarantee: A `null` breaks the line, which resumes at the next available value. An isolated value is shown as a dot so it remains visible, and the endpoint dot marks the latest available value. In a bar sparkline, missing data leaves an empty space. - Without it: A missing day is drawn as a dive to zero: a fall that never happened. - Code: `` - Your part: Pass `null` where there is no data, and `0` only for a real zero. - Proof, in the repository's tests (UiSparkline.spec.ts, not in the package): "a missing value breaks the line, and the dot stands on the newest value there is", "a bar with no value leaves its place empty rather than drawing a stub", "a value alone between two gaps is drawn as a dot, not a speck of line" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#gap-not-zero The patterns: https://grani.arseni.work/patterns ### Spinner (`UiSpinner`) > Show that work is in progress where the surrounding component has no loading state of its own. A component of grani 0.1.0. Status, stable, since 0.1.0. Page: https://grani.arseni.work/components/spinner Also called loader, loading indicator, activity indicator. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See where the app is working. - Reduce motion without hiding loading. Implemented by the app: - Data fetching, saving, permissions and business rules. - Show it when the request starts and remove it when the request ends. A spinner that mounts with its name is often not read out, so say the wait in a live region that was on the page before the request starts (UiCard `loading` has one). Inside a button, a badge, a switch or a row, set their `loading` instead of placing a spinner yourself. #### Why it works this way The sign that work is under way. Take it where a request runs and nothing draws one for you; a button, a badge, a switch and a row draw their own under `loading`. **Size.** It is 16px unless the host sets `h-*` or `size-*`. It has no props. **Placement.** It is the loading state of buttons, badges, switches, rows, selects, list fields, uploads, toasts and chart cards. ##### Keyboard Not interactive: it takes no focus. A button that spins is UiButton `loading`, which handles the keys. ##### Screen reader - Name: with an `aria-label` or `aria-labelledby` it is a `status` with that name; without a name it is decoration, hidden. A `role` or `aria-hidden` you set never overrides this. - Status: one that mounts with its name already in place is often not read out. Say the wait in a live region that was on the page before the request starts (UiCard `loading` has one), and let the spinner be its picture. ##### States One: turning, slower under reduced motion, never still; 16px unless the host sets `h-*` or `size-*`. ##### When to use another component - Content on its way: UiSkeleton. - Work of unknown length on a track: UiProgress `indeterminate`. - A button, a badge, a switch or a row at work: UiButton, UiBadge, UiSwitch and UiListItem draw it themselves under `loading`. #### Examples ##### Named or not ```vue ``` ##### Color ```vue ``` ##### Where it turns ```vue ``` #### API No props, events or slots of its own. Attributes are placed by the component itself: its description says where. #### How it behaves ##### Visible work - When: a request is running. - Props: it is mounted while the request runs; `aria-label` is set when no words beside it say what is loading. - Guarantee: A spinning ring shows that work is in progress. With an accessible name it is exposed as a status with that name; without a name it is hidden from a screen reader. - Without it: Nothing changes after the click, so you click again and the same request goes twice. - Code: `Save` - Your part: Show it when the request starts and remove it when the request ends. A spinner that mounts with its name is often not read out, so say the wait in a live region that was on the page before the request starts (UiCard `loading` has one). Inside a button, a badge, a switch or a row, set their `loading` instead of placing a spinner yourself. - Not covered: It does not stop a second click; the button’s `loading` does. - Proof, in the repository's tests (UiSpinner.spec.ts, not in the package): "The ring turns, at the size its host gives it.", "With a name it is a status with that name; without one it is hidden from a screen reader." - Pattern for all components: https://grani.arseni.work/patterns/waiting#visible-work ##### Calm motion - When: reduced motion is on. - Props: the system setting `prefers-reduced-motion: reduce`. - Guarantee: The spinner continues turning, slowed to one rotation every 1.6 seconds. - Without it: The ring stops with every other animation, and the screen looks frozen. - Code: `` - Your part: Nothing. A loading indicator of your own keeps moving only with the `animate-spin` class or the `data-motion-keep` attribute; otherwise it stops with every other animation. - Proof, in the repository's tests (UiSpinner.spec.ts, not in the package): "It keeps turning, slower, when the system asks for reduced motion." - Pattern for all components: https://grani.arseni.work/patterns/waiting#calm-motion The patterns: https://grani.arseni.work/patterns ### Stack (`UiStack`) > Arrange related content vertically or horizontally with consistent spacing between groups, headings and sections. A component of grani 0.1.0. Layout, stable, since 0.1.0. Page: https://grani.arseni.work/components/stack Also called vertical stack, vstack, spacing scale. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. Implemented by the app: - Data fetching, saving, permissions and business rules. #### Why it works this way Things one under another or side by side, spaced by what they are to each other. Take it for the blocks of a page or a form; text on the left and a thing on the right is UiListItem. **Gaps.** You name the relation, never a number. `tight` is 8, for the lines of one thing (a label and its control, a name and its count). `group` is 16, the default, for the things of one group (the fields of a form, a search over its list). `title` is 24, for a title and the text or the fields it names. `block` is 48, for the blocks of one page, and `section` is 96, for its sections. Importance is shown by size and color, not distance: a wider gap says "another thing", never "a bigger thing". **Margins.** It is a gap, not a margin, so the children carry no space of their own. A UiSeparator among them keeps the rhythm, and a UiHeader legend after other content adds its own 32 to the gap: in the default stack that lands at `block` (48), in another it is that gap plus 32. The stack pads nothing: in a UiCard it is the body, and the card's gutter goes round it. **Rows.** `row` is for things that share one line and nothing else (a badge beside a name, two buttons); they align on its vertical center. Text on the left and a thing on the right is UiListItem, not a `row`. ##### Keyboard Not interactive: the children keep their own tab stops, in the order they are stacked. ##### Screen reader - Element: nothing of its own; a `div`, or the element `as` names (`section`, `ul`, `form`, `li`), with the children read in order. ##### States None: the gap is one step of the scale and does not change with the content. ##### When to use another component - Text on the left and a thing on the right: UiListItem. - A table: UiTable. - The toolbar row: UiTableToolbar owns it. - Buttons joined into one capsule: UiButtonGroup. - A grid of columns: the page lays it out itself. #### Examples ##### Nested ```vue ``` ##### A row ```vue ``` #### API Props: - `gap`: `"block" | "title" | "group" | "section" | "tight"` = `block | title | group | section | tight` (default `"group"`) — The relation between the children, a step of the scale: `tight` 8, `group` 16, `title` 24, `block` 48, `section` 96 px. - `direction`: `"column" | "row"` = `column | row` (default `"column"`) — `column` stacks the children; `row` lines them up on one line. - `align`: `"start" | "center" | "end" | "stretch"` = `start | center | end | stretch` — Where the children stand across the stack. Unset, a column stretches them to its width and a row centers them on the line. - `as`: `"div" | "form" | "section" | "ul" | "li"` = `div | form | section | ul | li` (default `"div"`) — The element: `div` by default; `section`, `ul`, `form` or `li` when the stack is one. Anything else lands on the root element: native attributes, aria-*, data-testid. Slots: - `default` with `Record` — The things stacked, in order, each without a margin of its own. ### Stepper (`UiStepper`) > Count things with minus and plus, such as pieces in a cart or guests on a booking, or type the number when it is far from the current one. A component of grani 0.1.0. Form, stable, since 0.1.0. Page: https://grani.arseni.work/components/stepper Also called quantity input, counter, plus minus input, numeric stepper. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Change a number with the arrow keys. - See the value the app actually accepted. - Submit the values shown in the form. - Enter numbers in the app’s local format. - Keep nearby buttons and fields in place. - Go straight to the field that needs fixing. - Name each field once for screen readers. - Announce required fields in words. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass `min` and `max` where the count has bounds, and `step` if it is not 1. - Pass the count the app holds as `modelValue`, and say why a count was refused. - Listen to `unsure` if the count is saved: a count the locale cannot read for sure, such as 1.200 in Russian, reaches the model as written, and `unsure` is `true` while the count holds it. #### Why it works this way A count of things with minus and plus at its edges, the count between them. Take it for pieces, people, nights: a whole number a person changes by one more often than types. **Count.** It is a number field, the one UiInput draws with `numeric`: the value is text, empty is `null`, a number pasted or typed is read in the app's locale, and one it cannot read for sure is marked and told through `unsure`, as in UiInput; a press on it moves nothing and marks it at once. The step is `1` unless set; the buttons and ArrowUp and ArrowDown move by it and stop at `min` and `max`, which bound the buttons, not the typing. A count of things takes `min` (`0` or `1`): without it minus goes below zero. A fraction typed into it is carried as written, as a count past `max` is: the form checks it (`Number.isInteger`). The app takes or refuses a count in the same tick it is sent; a count confirmed later is a draft of the app's own. A unit stands after the count in `#end`, its short form (`pcs`, `kg`); an addon before it in `#start`. **Width.** The count is 3em wide, room for four digits, and the stepper keeps that width in a field rather than stretching across it; given a width, the count takes the room between the buttons, so they stand at the edges and never move. A longer count is cut at its end. **Field.** Standalone it takes `invalid` and `ariaLabel`; inside UiField it reads id, error and required from the field. **Attributes.** Attributes and listeners land on the input (`@blur`, `data-testid`); `class` and `style` on the capsule. **Placement.** In a form column under a UiField label; in a row of a list or a cart, beside the name of what is counted; joined with other controls in a UiButtonGroup. ##### Keyboard - `Tab`: reaches the count; the buttons are out of the tab order. - `ArrowUp` `ArrowDown`: move the count by the step without moving the caret, and stop at `min` and `max`. The buttons keep the focus and the caret in the count; `disabled` or `readonly` turns them off. ##### Screen reader - Count: a spinbutton named by `ariaLabel` or the field's label; it says its value and its bounds, and no value while the count is unsure. The unit in `#end` is not part of it. - Buttons: named by what they change, "Decrease Guests" and "Increase Guests", disabled at a bound; out of the tab order. - Errors: `invalid` sets `aria-invalid`; inside UiField the description and the error are read with it. ##### States Rest, focus, a button resting at a bound, disabled, readonly, invalid, with a unit, at `xs`, `sm` and `md`. ##### When to use another component - A number with decimals or money: UiInput `numeric`. - A mark from 1 to N: UiScaleInput. #### Examples ##### States ```vue ``` ##### Sizes ```vue ``` ##### Field ```vue ``` ##### Russian ```vue ``` #### API Props: - `modelValue`: `string | null` (required) — The count as text (`v-model`): `null` when emptied. A number is plain text (`12`) parsed by its owner on use. - `step`: `number` (default `1`) — How much a button or an arrow key moves the count. - `min`: `number` — The lowest count the buttons and the arrows reach. Typing is not clamped: the form validates. - `max`: `number` — The highest count the buttons and the arrows reach. - `name`: `string` — Native name for forms. - `id`: `string` — Own id when standalone. Inside UiField the field's id takes precedence. - `placeholder`: `string` — Hint shown while empty. Not a replacement for a label. - `readonly`: `boolean` (default `false`) — Prevents editing while keeping the count focusable: something else sets it. - `disabled`: `boolean` (default `false`) — Prevents input and interaction. - `invalid`: `boolean` (default `false`) — Marks the control invalid: red border and halo. Inside UiField the error sets this. - `required`: `boolean` (default `false`) — Standalone only: a count is needed, said to a reader and to a form. Inside UiField the field's `required` says so. - `ariaLabel`: `string` — Accessible name when there is no visible label. - `size`: `ControlSize` = `xs | sm | md` — Step of the control ladder. Unset, the app's size (`createGrani({ size })`), `sm` by default. Attributes are placed by the component itself: its description says where. Events: - `update:modelValue` (`value: string | null`) — The count changed: the number as text, `null` when emptied. - `unsure` (`unsure: boolean`) — `true` while the count holds text the locale cannot read for sure (`1.200` in Russian), which the model carries as written; `false` when it does not. Said on mount, then on every change. Slots: - `start` with `Record` — An addon before the count: a currency sign, an icon. - `end` with `Record` — A unit after the count, its short form: `pcs`, `kg`. #### How it behaves ##### Arrows step - When: always: its minus and plus, and ArrowUp and ArrowDown in the count. - Props: `step`, `min`, `max`. - Guarantee: Minus, plus and the arrow keys move the count by the step and stop at `min` and `max`. A press leaves the focus in the count, so the arrow keys go on from there. - Without it: Buttons beside a field that take the focus, so the next arrow key goes nowhere, and a count that runs past its bounds. - Code: `` - Your part: Pass `min` and `max` where the count has bounds, and `step` if it is not 1. - Not covered: Typing is not clamped: a count typed past `max` stays as typed, and the form checks it. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "the buttons rest at the bounds and while disabled; the keyboard steps too", "pressing minus or plus with a pointer keeps the focus and the caret in the count", "minus and plus at the edges, the count centered in monospace, step 1 by default" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#number-by-arrows ##### Back to the value - When: the app refuses a count, more than it has, or the form is reset. - Props: `modelValue` with `@update:model-value`. - Guarantee: If the app refuses the count a press or a key asked for, the stepper shows the count the app holds again. A form reset brings it back too. - Without it: The stepper shows 6 while the app, with 5 in stock, still holds 5. - Code: `` - Your part: Pass the count the app holds as `modelValue`, and say why a count was refused. - Not covered: The app takes or refuses a count in the same tick it is sent: a count it answers later is overtaken by the next press or key, so a count confirmed by a server is a draft the app keeps. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "a press of plus the parent refuses leaves the count on the model" - Pattern for all components: https://grani.arseni.work/patterns/waiting#refused-goes-back ##### Sent with the form - When: it sits inside a native form. - Props: `name`. - Guarantee: The count is sent under its `name`, and after a form reset it shows the app’s count again. - Without it: A count on screen the form never sends. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "in a form it sends its count under its name, and a reset puts the app's count back" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#sends-like-native ##### Number as written - When: a count is typed or pasted as people write it. - Props: none. - Guarantee: The count is read in the app’s locale: a pasted 1 200 is 1200 in Russian. - Without it: A pasted 1 200 the field cannot read. - Code: `` - Your part: Listen to `unsure` if the count is saved: a count the locale cannot read for sure, such as 1.200 in Russian, reaches the model as written, and `unsure` is `true` while the count holds it. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "a count pasted as people write it is read in the app locale", "a count the locale cannot read for sure tells the app, as its number field does" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#number-as-written ##### Steady width - When: the count grows past a digit, 9 to 10. - Props: none. - Guarantee: Minus and plus stand at the edges of a count of one width, so a count that grows from 9 to 10 to 100 moves neither of them: pressing plus again lands on plus. - Without it: A field as wide as its number: at 10 it widens, and the plus moves from under the pointer pressing it. - Code: `` - Your part: Nothing; give the stepper a width where the row needs a wider count. - Not covered: A count longer than its width is cut at its end, not widened: give the stepper a width for counts that large. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "the count keeps its 3em whatever its digits, minus and plus at the edges, so neither moves" - Pattern for all components: https://grani.arseni.work/patterns/finding#steady-width ##### Focus on the error - When: a form is sent with this field in error. - Props: `error` on UiField. - Guarantee: When this is the first field with an error, the focus moves into the count. - Without it: Keyboard focus stays on Save, and you look for the count yourself. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "in a field in error, focusInvalid lands on the count" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-invalid ##### One name - When: it stands in a UiField, or takes `ariaLabel`. - Props: none. - Guarantee: The count is named once, by its label, and each button says what it changes: Decrease Guests. - Without it: Two buttons with no name, and a count read with none. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "inside UiField the label points at the count, and the error and required reach it", "the buttons are named by what they change: Decrease Guests, Increase Guests" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice ##### Required in words - When: it must be filled. - Props: `required` on UiField. - Guarantee: Inside a required UiField, the count is announced as required, and the field draws the asterisk. - Without it: An asterisk that a screen reader skips. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiStepper.spec.ts, not in the package): "inside UiField the label points at the count, and the error and required reach it" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#required-in-words The patterns: https://grani.arseni.work/patterns ### Switch (`UiSwitch`) > Change an on/off setting immediately, returning to the previous position if the app rejects the change. A component of grani 0.1.0. Form, stable, since 0.1.0. Page: https://grani.arseni.work/components/switch Also called toggle, toggle switch, on off switch. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See the value the app actually accepted. - Submit the values shown in the form. - Go straight to the field that needs fixing. - Toggle or pick by clicking the words. - Name each field once for screen readers. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass the value the app holds as `modelValue`, set `loading` while the change is saved, and explain why a change was refused. - Give it a `name`, and a `value` where the server expects something other than `on`. - Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Put the words in the default slot; in a setting row, use UiListItem with `as="label"`. - Give it words in the default slot, or `ariaLabel`; a switch with no name warns in development. #### Why it works this way An on or off setting that applies at once. Take it where a change takes effect without saving a form. **Element.** It is a `button` with `role="switch"`, so a screen reader says "switch, on". **Form.** With a `name`, an on switch sends `value` (`on` by default) under that name with the form, and an off switch sends nothing, as a checkbox does. **Label.** Label text goes in the default slot, toggles the switch on click, and is then its only name; without it, `ariaLabel` names the switch. Inside UiField it takes the field's label and description. The label starts at the middle of the track (2px down beside the 24px `md` track), so a long label wraps below. **Model.** When the parent does not apply a change, the switch stays as the model says. **Loading.** `loading` keeps the focus on the switch while the change is saved. **Invalid.** An invalid switch that is off tints its track with the danger tone. **Attributes.** Attributes land on the button, `class` and `style` on the root. **Size.** Its `size` is a track, not a box, so it stays `sm` by default and does not follow the app's size (`createGrani({ size })`). **Placement.** Beside UiCheckbox and UiRadio in a form column. A setting row is UiListItem `as="label"` with the switch in `#actions`. It also works as a `UiReveal` trigger. ##### Keyboard A native button. - `Tab`: reaches it. - `Enter` `Space`: toggle it. `disabled` blocks it. `loading` blocks it too while the focus stays, the caller's own click included. A label in the slot toggles it on click, except while disabled. ##### Screen reader - Switch: `role="switch"`; it says on or off (`aria-checked`). - Name: the slot text, else `ariaLabel`, else the field's label: one name only. A switch with no name warns in dev. - Loading: `loading` says busy (`aria-busy`, `aria-disabled`). - Errors: `invalid` sets `aria-invalid`, and the field's words are read with it. - Required: `aria-required` says it is required, except in a group, whose legend says it once. ##### States Off, on, hover, focus, disabled (the plate, and the thumb in the disabled ink so on and off still look different), loading (a spinner in the thumb), invalid (the track in the danger tone while off; disabled wins over it), and the two tracks, `sm` and `md`. ##### When to use another component - Saved with the form, not applied at once: UiCheckbox. - One answer out of a few: UiRadioGroup. - A toggle that is a button: UiButton `pressed`. #### Examples ##### Sizes ```vue ``` ##### States ```vue ``` ##### Loading ```vue ``` ##### Setting row ```vue ``` ##### Refused ```vue ``` ##### Form ```vue ``` #### API Props: - `modelValue`: `boolean` (required) — On or off (`v-model`). - `disabled`: `boolean` (default `false`) — Prevents toggling. - `size`: `"sm" | "md"` = `sm | md` (default `"sm"`) — Track size: `sm` 20px, `md` 24px. - `name`: `string` — Native name for forms: an on switch sends `value` under it, an off one nothing. - `value`: `string` (default `"on"`) — Sent under `name` while on. - `ariaLabel`: `string` — Accessible name when the slot is empty and there is no field label; slot text wins over it. - `loading`: `boolean` (default `false`) — The change is being saved: a spinner in the thumb, `aria-busy`, no toggling; focus stays. - `id`: `string` — Own id when standalone. Inside UiField the field's id takes precedence. - `invalid`: `boolean` (default `false`) — Marks the switch invalid: the track takes the danger tone while off. Inside UiField the error sets this. - `required`: `boolean` (default `false`) — Standalone only: the switch must be on, said to a reader, with a star after its text. Inside UiField the field's `required` says so. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Events: - `update:modelValue` (`value: boolean`) — The state changed. Slots: - `default` with `Record` — The visible label, to the right of the track; clicking it toggles. #### How it behaves ##### Back to the value - When: the app saves the change and may refuse it. - Props: `modelValue` with `@update:model-value`, `loading`. - Guarantee: You can see whether a setting changed. The switch follows the app’s value, so a rejected change leaves it in its previous position. While the app marks the update as loading, it shows progress, keeps focus and ignores further presses. - Without it: The switch flips on the press and stays on, while the setting is still off. - Code: `` - Your part: Pass the value the app holds as `modelValue`, set `loading` while the change is saved, and explain why a change was refused. - Proof, in the repository's tests (UiSwitch.spec.ts, not in the package): "a change the parent refuses leaves the switch on the model" - Pattern for all components: https://grani.arseni.work/patterns/waiting#refused-goes-back ##### Sent with the form - When: it sits inside a native form. - Props: `name`, `value`. - Guarantee: When on, it sends `value` (`on` by default) under its `name`; when off or disabled, it sends nothing. After a form reset it shows the app's value again. - Without it: A switch on screen that the form never sends. - Code: `Weekly digest` - Your part: Give it a `name`, and a `value` where the server expects something other than `on`. - Proof, in the repository's tests (UiSwitch.spec.ts, not in the package): "in a form an on switch sends its value under its name and an off one sends nothing", "a form reset leaves the switch on its model" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#sends-like-native ##### Focus on the error - When: a form is sent with the switch in error. - Props: `invalid`, or the error of its UiField. - Guarantee: When the switch is the first field with an error, keyboard focus lands on it, so you can turn it on from the keyboard straight away. - Without it: The form does not send, keyboard focus stays on Save, and you have to find the field with an error yourself. - Code: `I accept the terms` - Your part: Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Proof, in the repository's tests (UiSwitch.spec.ts, not in the package): "a switch marked invalid is what focusInvalid lands on" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-invalid ##### Click the label - When: the switch has words. - Props: the default slot. - Guarantee: The words sit inside the label around the switch, so a click on them toggles it, as a click on the track does; while the switch is disabled, they do not. - Without it: Words beside the switch that only name it: a click on them does nothing. - Code: `Weekly summary` - Your part: Put the words in the default slot; in a setting row, use UiListItem with `as="label"`. - Proof, in the repository's tests (UiSwitch.spec.ts, not in the package): "a label in the slot wraps the control, so clicking the text toggles too" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#label-is-target ##### One name - When: it needs a name. - Props: the default slot, `ariaLabel`, or a UiField around it. - Guarantee: A screen reader gets one name: the switch’s text, then `ariaLabel` if there is no text, then the surrounding UiField’s label if neither is provided. The field’s description and error are announced with it. - Without it: A switch announced with two names, or with none. - Code: `Weekly summary` - Your part: Give it words in the default slot, or `ariaLabel`; a switch with no name warns in development. - Proof, in the repository's tests (UiSwitch.spec.ts, not in the package): "with its own text inside UiField it is named by that text, as UiCheckbox", "slot text and ariaLabel together emit one name" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice The patterns: https://grani.arseni.work/patterns ### Table (`UiTable`) > Compare records in columns, sort and select rows and act on a row, with clear states for loading, empty results and errors. A component of grani 0.1.0. Data, stable, since 0.1.0. Page: https://grani.arseni.work/components/table Also called simple table, grid, rows and columns. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Show missing data as a gap. - See that a row goes on past its edge. - Select or clear a range of rows. - Show when only some are selected. - Keep nearby content in place while loading. - Keep keyboard focus where you are working. - See whether an action worked. - Ignore extra presses while a request runs. - Give every empty list a way forward. - See how the rows are sorted. - Compare numbers in aligned columns. - Read the full text when a label is shortened. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass `null` where there is no value, and `0` only for a real zero. - Keep `v-model:selection` to rows that still exist: drop the keys of rows that were deleted. - Set `skeletonRows` to the page size. - Pass the error message in words as `error`, and load again on `@retry`. - Set `loading` from the moment you ask for rows until they arrive. - Use `#empty` to supply a UiNoData message with an action such as Create or Reset. For a failed load, pass an explanation in `error` and load again on `retry`. - Order the rows by `sort` yourself: the table reports the choice and does not reorder the rows. - Format the numbers alike down a column, with the same number of decimals, so their digits line up. - Set `truncate` on a column of long names, and a `width` where it should not take the room left. #### Why it works this way Records as rows under column headers, with sorting, selection and loading states. Take it inside UiDataTable, or alone for a list with no toolbar and no pages. **Data.** It draws the page it is given and owns none of the data. A header click asks for a sort (`v-model:sort`). A checkbox marks a row (`v-model:selection`, a set of row keys); with Shift, by pointer or Shift+Space, it marks the range from the last row marked. The parent loads, filters and orders the rows, and keeps the selection to rows that still exist. **Look.** One presentation: a hairline between rows, space between columns, a tint on the row under the pointer. The table draws no shell; the card around it does (`UiCard :padded="false"`). Its focus rings are drawn inside, since the card clips what sticks out. **Wide tables.** A wide table scrolls sideways in its own box, with `#row-actions` kept at the end. Once it overflows, the box takes focus and the arrow keys scroll it, a side with more columns past it is shaded, and on a desktop pointer an arrow in the header's band pages the table toward it, so a narrow screen shows the table goes on and how to reach the rest. The arrow stands over the edge of the header cell under it, which is pressed beside it. An empty or a failed table shows its plate with neither. Once it scrolls, a column of short values (24 characters or fewer) keeps them on one line: the table has the room to the side. **Loading.** The first load shows skeleton rows, as many as the page will hold; a refresh keeps the rows in view, dimmed and busy, and says it updates. In UiDataTable, a list that searches, the table stands on a floor: its empty and failed states fill it, and a skeleton holds as many rows as were in view, never fewer than fill it. A skeleton cell draws the lines its column holds (`lines`, 2 for a UiMoneyCell or UiDateCell), so the rows arrive at their height. With `#row-actions`, it holds the square of one icon button at the app's size, so the actions column keeps its width and the row its height. The other columns take their width from their content, which a skeleton does not have: those without a `width` settle when the rows arrive. Empty and failed. An empty page is UiNoData: "no records yet", or, with `filtered`, "nothing matches"; `#empty` puts one with its own action in its place. A failed load is UiNoData `danger` with the message and Retry. A failed refresh shows the same plate in place of the rows, and Retry brings the skeleton back. **Rows.** A row without a key keeps its DOM node for the life of the page, so a sort moves the row with its record. The totals row shows only when there are rows. A cell of an object needs `format`, `accessor` or its slot; without one it draws a dash. **Focus.** It stays where the person is when the rows change under it: a sort leaves it on the same control of the same row, a row deleted hands it to the same control of the row now in its place (the row above when it was the last), and a page left without rows gives it to the table's box. A focus that went elsewhere, into a window opened from a row, is not pulled back; that window gives it back to its own trigger. A row's own control turned off for a moment keeps it. A row deleted from its UiMenu is handed on the same way: the menu gives the focus back to its button first. A row removed while a window opened from it holds the focus (a question's `action`) is handed on too: the window gives the focus to the same control of the row now in its place. **Attributes.** They reach the ``, so `aria-label` names it and its page checkbox; `class` and `style` stay on the root. **Placement.** In UiDataTable, under UiTableToolbar and over UiPagination, with UiMoneyCell and UiDateCell as its cells. Alone in a `UiCard :padded="false"` when a list needs no toolbar and no pages. ##### Keyboard - `Tab`: once the table overflows, reaches its scroll box first; then the page checkbox, a sortable header, each row's checkbox and the controls in `#row-actions`, and the Retry of a failed load. - `ArrowLeft` `ArrowRight` `ArrowUp` `ArrowDown`: on the scroll box, scroll it. - `Enter` `Space`: on a sortable header, a button, turn it. - `Space`: on a checkbox, marks the row. - `Shift+Space`: on a checkbox, marks the range from the last row marked. A row is reached through a control in `#row-actions`, never by a click on the row alone. A header pressed while rows load asks for nothing and keeps the focus; Retry is held the same way and leaves the focus in the table. ##### Screen reader - Table: named by the `aria-label` the page gives it, and so are its page checkbox ("Select all on this page of Orders") and its scroll box. - Sortable header: says its direction (`aria-sort`); a sort a press asked for is said once the app sends it back ("Sorted by Name, ascending"). - Row checkbox: "Select row", or "Select Anna" with `rowLabel`, and says its shortcut. - Columns: the selection column and the actions column have hidden names. - Row: says whether it is selected (`aria-selected`). - Status: one region, present from the start and drawn empty, says "Loading…", the empty words, from a moment after the table mounts. The plate of an empty page is no second live region; a UiNoData of your own in `#empty` takes `role="none"` for the same. - Failed load: announced by its plate. - Refresh: `aria-busy` on the rows. ##### States A first load (skeleton rows, as many as the page holds), rows, a refresh (the rows kept, dimmed to 60% and busy), empty with nothing yet, empty because of a filter (`filtered`), a failed load (UiNoData `danger` with Retry), a failed refresh (the same plate in place of the rows), a sort, a selection with the page checkbox mixed, a totals row shown only with rows, and a wide table that scrolls in its box. ##### When to use another component - A list screen: UiDataTable, with its toolbar, pages and selection strip. - Rows of settings or facts: UiListItem rows in a UiList. - A list of names that grows from its last row: UiListField. - The changes of one event: UiLog's own table. #### Examples ##### Sortable ```vue ``` ##### Selectable ```vue ``` ##### Row actions ```vue ``` ##### Totals ```vue ``` ##### States ```vue ``` ##### Wide ```vue ``` ##### Money ```vue ``` ##### Date ```vue ``` #### API Props: - `columns`: `TableColumn[]` (required) — The columns in order; each names its `#cell.` slot. A column is `{ key, label }` and may add `accessor(row)` (the value when it is not `row[key]`), `format(value, row)` (the text), `sortable` with `defaultSortDir` (`asc` or `desc`, the first press), `align: 'end'` (numbers, digit under digit), `width` (one CSS value, `120px` or `calc(…)`), `truncate` (one line, cut with a tooltip; cut columns with no width share the room left evenly). - `items`: `T[]` (required) — Rows of the current page. The table does not load, filter or sort them. - `rowKey`: `RowKey` — What tells rows apart: a field name or a function; `id` when unset, so rows without an `id` need it. A row without a key cannot be selected, and is known by its object: a parent that rebuilds its rows on every render remounts them all. - `loading`: `boolean` (default `false`) — Rows are on their way: skeleton rows on the first load, the rows in view dimmed on a refresh. - `skeletonRows`: `number` (default `5`) — Skeleton rows on the first load: the page size, so nothing moves when the rows arrive. - `rowLabel`: `((row: T) => string)` — Names a row for its checkbox: "Select Anna" instead of "Select row". - `error`: `string | null` (default `null`) — Why the rows could not be loaded, in words for the reader, shown with a retry. A failed refresh shows the same plate in place of the rows. - `selectable`: `boolean` (default `false`) — A checkbox on every row and one for the page in the header. - `selection`: `Set` (default `new Set()`) — Keys of the selected rows (`v-model:selection`); the page checkbox adds or removes the page, Shift with a row's checkbox the rows from the last one marked. The parent drops the keys of rows it deletes. - `isRowSelectable`: `((row: T) => boolean)` — Which rows can be selected; the others show a disabled checkbox and stay out of the page checkbox. - `sort`: `TableSort` (default `null`) — The current sort (`v-model:sort`); a header click cycles the column's first direction, the other one, then none. - `clickable`: `boolean` (default `false`) — Rows answer a click with `row-click` and show a pointer cursor. A pointer shortcut: the keyboard path to a row is a control in it (`#row-actions`), the row itself takes no tab stop. - `filtered`: `boolean` (default `false`) — The page is empty because of a filter or a search: the empty text says so. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Events: - `retry` — The retry of a failed load was pressed. - `update:sort` (`sort: TableSort`) — A header was clicked: the column and direction to sort by, `null` to drop the sort. - `update:selection` (`selection: Set`) — The selection changed; a new set, the one passed in is not mutated. - `row-click` (`row: T, event: MouseEvent`) — A row was clicked with `clickable` on. Not for a click on a control inside the row, with a modifier key, or over selected text. Slots: - `row-actions` with `{ row: T; rowIndex: number; }` — Controls of a row, in a column kept at the end when the table scrolls: ghost icon buttons. - `empty` with `{ filtered: boolean; }` — Instead of the empty-page text; `filtered` says which wording it replaces. ##### Date cell (`UiDateCell`) Props: - `value`: `DateValue | null` (required) — An ISO string with a time or a day alone, a Date, or a timestamp. A time with no zone is read in the app's zone. Empty or unreadable prints a dash. - `variant`: `DateCellVariant` = `day | time` (default `"day"`) — Which fact leads: `time` on top for a list within a day, `day` on top for a list across months. - `context`: `DateCellContext` = `weekday | relative` (default `"relative"`) — What the lower line answers: how long ago (`relative`), or which day of the week (`weekday`). Attributes are placed by the component itself: its description says where. ##### Money cell (`UiMoneyCell`) Props: - `value`: `string | number | null` (required) — The amount in major units: a number or the decimal string an API sends. Empty or unreadable prints a dash. - `currency`: `string` — ISO 4217 code for this cell; unset, the app's currency (`createGrani({ currency })`). - `unit`: `string` — What the amount is per, `kg` or `pc`; shown after the currency as "EUR / kg". - `tone`: `MoneyTone` = `success | danger | info` — Meaning of the amount: `success`, `danger`, `info`. Unset is the normal ink. Anything else lands on the root element: native attributes, aria-*, data-testid. #### How it behaves ##### A gap, not a zero - When: a cell has no value. - Props: `items` with `null` where there is no value. - Guarantee: A cell with no value shows a dash, and so does one whose `format` returns an empty or blank string. A real `0` is printed as 0. - Without it: A missing amount is printed as 0 and read as nothing owed, or the cell is left empty and reads as a value still loading. - Code: `` - Your part: Pass `null` where there is no value, and `0` only for a real zero. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "renders headers and values: format, accessor, a dash for an empty value", "a format that returns an empty string still shows the table's dash" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#gap-not-zero ##### More past the edge - When: its columns are wider than its box. - Props: none: every UiTable; `#row-actions` for the actions of a row. - Guarantee: A shade marks the edge with more columns past it: the end at first, at the row actions, where the columns slide under them, and the start once scrolled. On a desktop pointer an arrow in the header’s band pages the table toward that edge; the scroll box takes the focus and the arrow keys scroll it. The actions of each row stay at the end, in view. - Without it: A table cut at the screen’s edge that looks complete, with the actions of its rows out of sight. - Code: `` - Your part: Nothing. Give a column of long names `truncate`, and a `width` where a column should not grow. - Not covered: The arrows are for a desktop pointer: on a touch screen the table is swiped. An arrow stands over the edge of the header cell under it, which is pressed beside it. The header row does not stick to the top of the page as the page scrolls. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "fades at the end while more columns wait there", "fades at the start once scrolled, and not at the end when the end is reached", "a table that fits draws no fade", "the horizontal scroll box is keyboard-focusable and named once the table overflows", "row actions add a sticky last column with a named header; a footer cell adds the footer row", "the end's shade stands at the row actions, where the columns slide under them", "an edge with more columns past it grows an arrow that pages the table, for the pointer", "at the end the arrow stands at the start and pages back", "an empty or a failed wide table draws no shade and no arrow over its plate" - Pattern for all components: https://grani.arseni.work/patterns/finding#edge-says-more ##### Range select - When: a row checkbox is pressed with Shift, with the pointer or with Shift+Space. - Props: `selectable`, `v-model:selection`. - Guarantee: Every selectable row between the checkbox you activate and the previous one takes its new state: checking selects the range, unchecking clears it. - Without it: Ten rows take ten presses. - Code: `` - Your part: Keep `v-model:selection` to rows that still exist: drop the keys of rows that were deleted. - Not covered: A range stays within the page in view and skips rows that cannot be selected. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "Shift with a second checkbox marks every row between", "Shift over marked rows clears the range, as the pressed row goes", "Shift+Space from the keyboard marks the range too" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#range-select ##### Some selected - When: some, but not all, selectable rows of the page are selected. - Props: `selectable`. - Guarantee: The page checkbox shows the dash and is announced as mixed. A press selects every selectable row of the page and leaves out rows that cannot be selected; a press when all of them are selected clears them. - Without it: The page checkbox looks empty while some rows are selected, as if nothing were. - Code: `` - Your part: Nothing. - Not covered: It counts only the page in view: rows selected on other pages do not count toward it. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "the page checkbox selects the selectable rows, shows mixed for a part, clears when all are in" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#mixed-says-some ##### Stable dimensions - When: rows load: the first page, or a refresh with rows in view. - Props: `loading`, `skeletonRows`. - Guarantee: The first load shows placeholder rows sized like text rows, as many as the page size. A refresh keeps the existing rows visible, dimmed and marked busy, so the table does not collapse while waiting. - Without it: The rows disappear for the refresh, and everything below the table jumps up, then down. - Code: `` - Your part: Set `skeletonRows` to the page size. - Not covered: A page that comes back shorter or longer still changes the height once. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "a skeleton row has the height of a text row and its bar follows the column alignment", "a refresh in flight keeps the existing rows instead of skeleton rows, and says it is busy" - Pattern for all components: https://grani.arseni.work/patterns/waiting#no-jolt ##### Focus stays near - When: Rows are deleted or sorted while keyboard focus is on a button in a row. - Props: none: every UiTable. - Guarantee: After you delete a row, keyboard focus moves to the same button in the row that takes its place, or in the previous row if you deleted the last one, so the next delete is one Enter away. A row deleted while a window opened from it holds the focus (a confirmation’s `action`) is handed on the same way when the window closes. If the page becomes empty, focus moves to the table container. After sorting, focus stays on the same button in the same record, wherever that record moves. - Without it: Every delete loses keyboard focus, and you tab through the page again to reach the next row's Delete button. - Code: ` ` - Your part: Nothing. Remove or reorder the rows in `items` as usual; the table moves keyboard focus itself. - Not covered: This applies to buttons in a row and to a row’s UiMenu, which gives the focus back to its button before the command runs, so Delete from the ⋯ menu lands on the ⋯ of the next row. A menu of your own that keeps the focus until the row is gone loses it with the row. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "a row deleted under the focus hands it to the same control of the row now in its place", "the page checkbox turned off with the last row gives the focus to the table box" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-stays ##### Outcome shown - When: loading rows fails. - Props: `error`, `@retry`. - Guarantee: When a load fails, whether first or refresh, a message with Retry replaces the rows, and a screen reader announces it once; no old rows are left on screen. Pressing Retry brings the placeholder rows back. - Without it: An empty table, with no sign of whether there are no records or the request failed. - Code: `` - Your part: Pass the error message in words as `error`, and load again on `@retry`. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "a failed load shows the message with a retry; a failed refresh shows the same plate in place of the rows" - Pattern for all components: https://grani.arseni.work/patterns/waiting#answered ##### One press, one request - When: you press a column header or Retry while rows load. - Props: `loading`. - Guarantee: While rows load, a column heading keeps keyboard focus, but pressing it does not request another sort. When the app starts loading after Retry, placeholder rows replace the Retry button, so it cannot be pressed again while the request runs. - Without it: Two presses send two requests, and the answer that arrives last may be the older one. - Code: `` - Your part: Set `loading` from the moment you ask for rows until they arrive. - Not covered: Row checkboxes and `#row-actions` stay active during a refresh, because the selection holds row keys, not the rows themselves. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "a retry in flight after a failure draws the skeleton: no retry is left to press twice", "a header pressed while rows load asks for no second sort and keeps the focus" - Pattern for all components: https://grani.arseni.work/patterns/waiting#one-press ##### Way forward - When: a page has no rows, or the first load failed. - Props: `filtered`, `error`, `#empty`. - Guarantee: An empty page says why: “No records yet”, or “No matching records” with `filtered`. A failed load says “Could not load records” with the message you pass in `error`, offers Retry, and a screen reader announces it at once. - Without it: A blank table, which reads as a failed load. - Code: ` ` - Your part: Use `#empty` to supply a UiNoData message with an action such as Create or Reset. For a failed load, pass an explanation in `error` and load again on `retry`. - Not covered: Without `#empty`, an empty page says why but offers no button. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "an empty page and a failed load say why; #empty puts the next step of your own in place" - Pattern for all components: https://grani.arseni.work/patterns/finding#empty-next-step ##### Sort said - When: a column is `sortable`. - Props: `sortable` and `defaultSortDir` on a column, `v-model:sort`. - Guarantee: A press on its header asks for the column’s first direction (`defaultSortDir`, ascending unless set), then the other direction, then no sort. An arrow icon shows the direction, and `aria-sort` lets a screen reader announce it. - Without it: Nothing shows how the rows are sorted, so you have to compare values to work out their order. - Code: `` - Your part: Order the rows by `sort` yourself: the table reports the choice and does not reorder the rows. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "a sortable header cycles first direction, the other one, then none; aria-sort follows" - Pattern for all components: https://grani.arseni.work/patterns/finding#sort-says ##### Digits line up - When: a column has `align: 'end'`. - Props: `align: 'end'` on a column. - Guarantee: The column aligns numbers to the end and uses equal-width digits, so with consistent decimal formatting the digits line up and values are easy to compare down the column. - Without it: 1,111 and 8,888 have different widths, so the eye compares lengths, not values. - Code: `` - Your part: Format the numbers alike down a column, with the same number of decimals, so their digits line up. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "an end-aligned column sets tabular figures" - Pattern for all components: https://grani.arseni.work/patterns/finding#digits-line ##### Whole text - When: a column is set to `truncate`. - Props: `columns[].truncate`. - Guarantee: The cell keeps one line, cut with an ellipsis, and the whole text stands in a tooltip while the cut is real. - Without it: A row that grows to three lines for one long name, or a name cut with no way to read the rest. - Code: `` - Your part: Set `truncate` on a column of long names, and a `width` where it should not take the room left. - Proof, in the repository's tests (UiTable.spec.ts, not in the package): "stands in a UiTruncate, not under a title" - Pattern for all components: https://grani.arseni.work/patterns/finding#whole-text The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useUiT`, `announce`, `useControlSize`. ### Table columns (`UiTableColumns`) > Choose which columns to show and keep that choice for later visits in the same browser. A component of grani 0.1.0. Data, stable, since 0.1.0. Page: https://grani.arseni.work/components/table-columns Also called column picker, column visibility, show hide columns. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Keep at least one column visible. - Remember hidden columns in this browser. - Keep one option and clear the rest in one press. - Find what you chose at the top of a long filter. - Clear a search in one step. - Notice when there are more options below. - Jump to an option by letter. - Keep Reset in one place. - Open with keyboard focus where the task begins. - Continue from where you opened the panel. - Pass a group with one press of Tab. Implemented by the app: - Data fetching, saving, permissions and business rules. - Put an identifying column, such as a name or record number, in `required` to keep it visible. The component prevents hiding the last visible column automatically. - Name the kind of table in `key` (for example `invoices`), and pass the signed-in user as `scope` when two people share a browser. #### Why it works this way A button with a panel where a person picks which columns a table shows. The table toolbar draws it from its `columns` prop; it is not placed by hand. **Panel.** The panel is a UiPopover with a checkbox per column, applied at once. A required column is ticked, held and marked "Required". The last column shown cannot be hidden and is marked "Last one". The marks are one word, so the one that comes with the last tick does not widen the panel under the pointer, and the column's own name keeps its room. Reset in the footer returns to the default; it is held while nothing differs, so the list never moves under the pointer. From six columns the shown stand first under "Shown" and the hidden under "Hidden", a line between, so the list says why its order is not the table's. A view, not a filter. The choice is a personal view, so the button shows no count. `useTableColumns` keeps the choice per kind of table; this component is the view of that state, and the page draws the table from the state's `visible`. A stored choice arrives once the page runs in the browser, so a page rendered on the server shows the default columns for a moment. **Placement.** The toolbar draws it first in the right cluster, across the row from UiFilter and UiDateRange. UiDataTable takes the same state as its `columns`. **Button.** The button names itself in a tooltip. Attributes land on the button, not on the panel. ##### Keyboard On the button: - `Tab`: reaches it. - `Enter` `Space`: open the panel; the focus goes to the list, or to its search when there are six columns or more. In the panel, where the list is one tab stop and Reset the next; from six columns up the search takes the list's tab stop, and its cross is one more once it holds text: - `ArrowDown` `ArrowUp`: in the list, move the highlight. - `Home` `End`: jump. - `Enter` `Space`: tick. - `A–Z`: jumps to the column that starts with the letter. - `Escape`: closes the panel and returns the focus to the button. - `Tab`: cycles inside the panel. ##### Screen reader - Button: named "Columns" (`aria-label`, and the tooltip), with `aria-haspopup` and `aria-expanded`. - Panel: a dialog with the same name. - List: a multi-select listbox named "Columns", each column an option that says whether it is ticked. - Held column: says "Required" or "Last one" after its name. - Count: under the list, a status region, read as it changes: "2 hidden" or "All columns shown". ##### States Rest, open, a column ticked, a required column held with "Required", the last column shown held with "Last one", Reset held while nothing differs; the choice kept across a remount, and the default columns for a moment on a page rendered on the server. No count on the button: the choice is a view, not a filter. ##### When to use another component - Narrowing the rows: UiFilter. - A period: UiDateRange. - One choice among a few: UiSelect. - A second menu beside a toolbar: never; the toolbar draws it from `columns`. #### Examples ##### No column required ```vue ``` #### API Props: - `columns`: `TableColumns` (required) — The columns state from `useTableColumns`: every column, the hidden ones, which may be hidden. The table draws its `visible`. - `size`: `ControlSize` = `xs | sm | md` — Step of the control ladder for the button: the toolbar row's, the app's size (`createGrani({ size })`) when unset. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. #### How it behaves ##### Last column stays - When: no column is required and all but one are hidden. - Props: `useTableColumns(key, columns)` with no `required`. - Guarantee: The last column shown cannot be unticked and is marked “Last one”, so the table always shows at least one column. - Without it: A menu that unticks the last column, leaving empty rows that read as a failed load. - Code: `const cols = useTableColumns('invoices', COLUMNS)` - Your part: Put an identifying column, such as a name or record number, in `required` to keep it visible. The component prevents hiding the last visible column automatically. - Not covered: A stored choice that hides every column, for example one saved for an older set of columns, shows the first column. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "the last column shown is held and marked Last one" - Pattern for all components: https://grani.arseni.work/patterns/finding#last-column-stays ##### Columns remembered - When: the table is opened again in this browser. - Props: `useTableColumns(key, columns)`. - Guarantee: The column choice is stored as soon as it changes and restored on the next visit. With the default browser storage, changes made in another tab are also applied to this one. - Without it: A choice kept only in the page: the hidden columns are back on every visit. - Code: `const cols = useTableColumns('invoices', COLUMNS)` - Your part: Name the kind of table in `key` (for example `invoices`), and pass the signed-in user as `scope` when two people share a browser. - Not covered: Preferences belong to this browser and are not shared through a URL. A server-rendered page may briefly show default columns before the stored choice applies. With `createGrani({ storage })`, automatic updates from other tabs are unavailable; the last tab to save a choice wins. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "a choice made in the menu is there after a remount" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#columns-remembered ##### Only this - When: a table of three columns or more. - Props: none: every UiTableColumns. - Guarantee: The highlighted row offers Only, which shows that column alone and hides the others in one press; a required column stays beside it, and Reset brings the default back. - Without it: Unticking every other column, one by one, to look at a single one. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "Only keeps the highlighted column alone, and a required column stays beside it", "Only on a hidden column leaves that column alone in view" - Pattern for all components: https://grani.arseni.work/patterns/finding#only-this ##### Chosen first - When: a table of six columns or more. - Props: none: every UiTableColumns. - Guarantee: The columns the table shows open at the top of the list under Shown, in the table’s order, and the hidden ones below a line under Hidden, so you see why the list runs in another order than the table; the order holds while the panel is open, so a tick never moves a row under the pointer. - Without it: The columns in view scattered down a long list, some below its fold. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "from six columns the ones shown open at the top, in the order of the table", "from six columns the shown and the hidden stand under their names, a line between" - Pattern for all components: https://grani.arseni.work/patterns/finding#chosen-first ##### Search clears - When: a table of six columns or more. - Props: none: every UiTableColumns. - Guarantee: A search stands over the list of columns and narrows it as you type. Its cross or Escape empties it and keeps the focus in the field; an Escape with no text closes the panel. - Without it: An Escape meant for the text that closes the whole panel, so the search starts over. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "from six columns a search narrows the list, and Escape empties it with the panel still open" - Pattern for all components: https://grani.arseni.work/patterns/finding#search-clears ##### Five and a half rows - When: a table of more than five columns. - Props: none: every UiTableColumns. - Guarantee: The list shows five columns and half of the sixth, so the cut says more wait below; the keys bring a column past the cut into view. - Without it: A list cut on a row’s edge that looks finished while columns wait below it. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "a long list of columns is cut at five rows and a half" - Pattern for all components: https://grani.arseni.work/patterns/finding#five-rows ##### Letter jumps - When: a table of five columns or fewer, where no search takes the letters. - Props: none: every UiTableColumns. - Guarantee: A letter goes to the first column that starts with it, and the same letter again to the next. - Without it: Arrowing down the list one column at a time to reach the one you know by name. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "a letter goes to the column that starts with it, and the same letter again to the next" - Pattern for all components: https://grani.arseni.work/patterns/finding#letter-jumps ##### Reset held - When: the panel is open and you hide or show the first column. - Props: none. - Guarantee: Reset and the hidden-column count, such as “2 hidden”, have a fixed place in the footer. Reset becomes available when column visibility differs from the default, without changing the panel’s layout. - Without it: A Reset that appears only once a column is hidden, so the footer changes under the pointer. - Code: `` - Your part: Nothing. - Not covered: Reset returns to the columns hidden by default (`hiddenByDefault`), not to every column shown. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "a tick applies at once; the summary counts the hidden; Reset is held until something differs" - Pattern for all components: https://grani.arseni.work/patterns/finding#reset-held ##### Focus starts inside - When: you open the columns panel. - Props: none. - Guarantee: Use the arrow keys to move between columns and Space to show or hide one. With six or more columns, focus starts in the search field instead, so you can find a column by name. - Without it: The panel opens with keyboard focus left on its button, and you press Tab before you can turn a column on or off. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "opened, the focus goes to the list of columns", "opened on six columns or more, the focus goes to the search" - Pattern for all components: https://grani.arseni.work/patterns/opening#focus-start ##### Focus comes back - When: you close the columns panel with Escape. - Props: none. - Guarantee: Focus returns to the columns button at the end of the toolbar, so you can continue through the toolbar with Tab. - Without it: After Escape, keyboard focus drops to the start of the page, and you tab through the page again to reach the table. - Code: `` - Your part: Nothing. - Not covered: If the panel is closed by a click outside it, keyboard focus stays where the click put it. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "Escape closes the panel and returns the focus to the button" - Pattern for all components: https://grani.arseni.work/patterns/opening#focus-back ##### One Tab per group - When: the columns panel is open. - Props: none. - Guarantee: Tab reaches the column list as one group, so you do not have to visit every column. Reset is the next available stop when the view differs from the default. - Without it: Each column is its own checkbox, so a wide table costs a press of Tab per column. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableColumns.spec.ts, not in the package): "the list is one tab stop, and Reset the next once something differs" - Pattern for all components: https://grani.arseni.work/patterns/opening#one-stop The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useTableColumns`, `useControlSize`, `useUiT`. ### Table toolbar (`UiTableToolbar`) > Keep search, filters and actions together above the table they affect. A component of grani 0.1.0. Data, stable, since 0.1.0. Page: https://grani.arseni.work/components/table-toolbar Also called list toolbar, search and filters bar, table header bar. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Results match the current search. - Keep a reset from restoring the old search. - Search once typing pauses. - Finish a word in any script before it is sent. - Reach frequent actions from the keyboard. - Clear a search in one step. Implemented by the app: - Data fetching, saving, permissions and business rules. - Apply the values in the order they arrive. - Set `search` to the new value; there is no pending send for you to cancel. - Load the list on `update:search`, not on every key. #### Why it works this way The row above a list, with a built-in search, what narrows the list on the left and what acts on it on the right. UiDataTable builds it from its own props and slots. **Clusters.** `#start` holds what narrows the list (a period in UiDateRange, filters). `#end` holds what acts on it: catalog buttons, then the main action last. The columns menu is built in too; when the toolbar is given its state, it stands first on the right. **Search.** The search is built in and always present (`v-model:search`). The field takes every key; the value goes out after a 250 ms pause, and Enter sends it at once. A value set from outside (a reset, the URL) replaces what was being typed. When a host applies the model late, the toolbar's own sent values coming back are not taken for an outside value, so what was typed since stays, and a clear or a step back made while a value is on its way is sent too. A host that drops a value it was sent without a word keeps it counted as on its way, and takes one outside value equal to it for its answer. **Size.** Controls in the row share one step, `size`: the app's size (`createGrani({ size })`), or `sm` (36 px) if unset; `xs` for a dense row, `md` for a comfortable one. The slots get it as `{ size }` to bind on their controls. **Layout.** On a narrow screen the search takes a line of its own and the rest share the line under it. The row is padded 16 px, so it lines up with the table's cells under it and with its footer; the card around them is the shell. **Placement.** In UiDataTable's card, above the table; UiDataTable builds it from its search, `#filters`, `#actions` and `columns`. UiFilter and UiDateRange stand in `#start`, UiTableColumns first in the right cluster. A host may make it `inert` while a selection strip covers it. ##### Keyboard - `Tab`: reaches the search first (its cross next, while it holds text), then the controls in `#start`, the columns button and the controls in `#end`, in the order they stand. - `/`: from anywhere outside a field, goes to the search of the first list in view, in the window open over the page when there is one. An app that takes the key itself calls `preventDefault` on it first. In the search, where every key narrows the list after a 250 ms pause: - `Enter`: sends at once and does not submit a form around it. - `Escape`: empties it and keeps the focus, as the cross does. Leaving the field sends what was typed. The Enter that confirms an IME candidate sends nothing. ##### Screen reader - Search: a landmark (`role="search"`) named like its field, by `searchPlaceholder`, "Search" by default; UiDataTable adds its own name ("Search Invoices"), so two lists on one page keep their searches apart. The field says its shortcut, `/` (`aria-keyshortcuts`). - Row: has no name and no role. - Slots: what they hold is read as the controls they are. ##### States Rest, text in the search (the cross shows), a pending send, a value set from outside that replaces the typing, `inert` under a selection strip; the row at `xs`, `sm` and `md`, and on a narrow screen the search on a line of its own. ##### When to use another component - One block of table, toolbar, pages and states: UiDataTable. - A search outside a list: UiInput `type="search"`. - A second columns menu: never in `#end`; the toolbar draws it from `columns`. #### Examples ##### Status ```vue ``` ##### Columns ```vue ``` ##### Set from outside ```vue ``` ##### Under a selection strip ```vue ``` ##### Sizes ```vue ``` #### API Props: - `search`: `string` (required) — The search text (`v-model:search`); the field is always there. Sent as typed, spaces included, after a 250 ms pause or at Enter. - `searchPlaceholder`: `string` — What the search looks in; the field's placeholder and its name. - `columns`: `TableColumns` — The columns menu: the state from `useTableColumns`. The button stands first in the right cluster; without it the columns are fixed. - `size`: `ControlSize` = `xs | sm | md` — Step of the control ladder for the row: `xs` for a dense row, `sm` (36 px), `md` for a comfortable one; unset, the app's size (`createGrani({ size })`). The slots get it as `{ size }`. Anything else lands on the root element: native attributes, aria-*, data-testid. Events: - `update:search` (`value: string`) — The search text, after the pause or at Enter. Slots: - `start` with `{ size: ControlSize; }` — What narrows the list, after the search: a period, filters; bind `size` on them. - `end` with `{ size: ControlSize; }` — What acts on the list, after the columns menu: catalog buttons, then the main action last; bind `size`. Not another columns menu. #### How it behaves ##### Late answer dropped - When: the app applies the search late, as a router query does. - Props: `v-model:search`. - Guarantee: When the app applies a search value the toolbar sent earlier, the toolbar recognizes it as a delayed update: it keeps the text you typed since then and sends that newer value when ready, including an empty value if you cleared the search. - Without it: The late value writes the old text back into the field, and a clear you made is undone. - Code: `` - Your part: Apply the values in the order they arrive. - Not covered: The toolbar expects each value it sends to be applied to `search`. If the app drops one, the toolbar still treats it as pending. A later external update with that same value can then be mistaken for the delayed response instead of a new reset. - Proof, in the repository's tests (UiTableToolbar.spec.ts, not in the package): "the host echoing an older sent value does not erase what was typed since", "a clear made while a value is on its way is sent, and the late echo does not undo it" - Pattern for all components: https://grani.arseni.work/patterns/finding#late-dropped ##### Reset wins - When: the app sets the search itself: a reset, a saved view, a step back. - Props: `v-model:search`. - Guarantee: The field shows the search value the app set and discards any earlier text still waiting for the typing delay, so the old search is never sent afterward. - Without it: The list is reset while the field still shows the old text, and the pending send can filter the list by it again. - Code: ` Reset filters` - Your part: Set `search` to the new value; there is no pending send for you to cancel. - Proof, in the repository's tests (UiTableToolbar.spec.ts, not in the package): "a value set from outside replaces the typing and drops the pending send" - Pattern for all components: https://grani.arseni.work/patterns/finding#outside-wins ##### Asks once - When: you type in the search. - Props: none: every UiTableToolbar. - Guarantee: The text is sent once, 250 ms after the last key, with the latest value. Enter sends it at once and does not submit a form around the toolbar. Nothing is sent while an input method, for example for Japanese, is still composing a word. - Without it: A request on every key: five letters, five requests. - Code: `` - Your part: Load the list on `update:search`, not on every key. - Proof, in the repository's tests (UiTableToolbar.spec.ts, not in the package): "sends the text once after the pause, with the last value", "Enter sends at once and does not submit a form around the toolbar", "no emit happens while a word is being composed" - Pattern for all components: https://grani.arseni.work/patterns/finding#typing-asks-once ##### Words in the making - When: a search is typed through an input method. - Props: none: every UiTableToolbar. - Guarantee: Nothing is sent while the word is being composed, and the Enter that picks it sends nothing; the whole word goes out once the typing pauses. - Without it: A search sent for every reading of the word, and one more for the Enter that picks it. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTableToolbar.spec.ts, not in the package): "no emit happens while a word is being composed", "the Enter that confirms an IME candidate sends nothing", "the Enter Safari sends after it ends a composition sends nothing at once" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#word-as-composed ##### Shortcut keys - When: a page with a list on it. - Props: none: every UiTableToolbar, and so every UiDataTable. - Guarantee: Pressing `/` anywhere outside a field moves keyboard focus to the search of the first list in view, or to the list in the window open over the page when there is one. The field names the key to a screen reader. - Without it: A trip to the mouse, or a run of Tab presses, to start a search you meant to type. - Code: `` - Your part: Nothing. An app that takes `/` for itself calls `preventDefault` on it first, and the list leaves it. - Not covered: Only the first list in view takes the key; a list hidden in a closed tab or panel is passed over. - Proof, in the repository's tests (UiTableToolbar.spec.ts, not in the package): "/ from the page goes to the search, and the field says its shortcut", "typed in a field, / stays a slash", "the first list on the page takes /", "a / the app took first, a window open over the list, or a list held inert keep it" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#keyboard-actions ##### Search clears - When: the search has text. - Props: none: every UiTableToolbar. - Guarantee: × or Escape clears the search, and you can type the next term without leaving the field. The empty value reaches the app immediately, bypassing the usual 250 ms delay, even when earlier typing was still waiting to be sent. - Without it: The field looks empty while the list is still filtered by text the field no longer shows. - Code: `` - Your part: Nothing. Do not add a clear button of your own: the field already has one. - Proof, in the repository's tests (UiTableToolbar.spec.ts, not in the package): "the cross and Escape each send the empty value once, at once, and keep the focus" - Pattern for all components: https://grani.arseni.work/patterns/finding#search-clears The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `debounce`, `useTableColumns`, `useControlSize`, `useUiT`. ### Tabs (`UiTabs`) > Switch between sections of the same screen without showing them all at once. A component of grani 0.1.0. Layout, stable, since 0.1.0. Page: https://grani.arseni.work/components/tabs Also called tab bar, tab strip, tabbed navigation. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See that a row goes on past its edge. - Keep counts short and in place. - Keep your browser’s keyboard shortcuts. - Pass a group with one press of Tab. Implemented by the app: - Data fetching, saving, permissions and business rules. - Give `badgeLabel` the count in words, such as “3 unread”; a bare number triggers a warning in development. - Share a link to the open tab. - Name the strip with `ariaLabel`, and put each pane in the slot named after its tab. #### Why it works this way Panes of one screen, one at a time. Take it when a page or a record splits into parts a person moves between; a choice with no panes is UiRadioGroup `segmented`. **Panes.** The root is a `

`. The active tab's pane is the slot named after its value (`#overview`); a tab without a slot renders no pane. A pane that is not shown is unmounted, so a form in it must keep its values in the parent, not in the DOM. The pane follows `modelValue`, not the tabs: a value whose tab is gone (taken away with a permission) still shows its slot, named by no tab, so set `modelValue` to a tab that stays when the tabs change. **Variants.** `underline` is a strip on its own. `panel` puts the strip inside the card shell as the header of a block, with `#header` above it; inside a UiCard's `#header`, the card is the shell and the panel draws none of its own. A tab stands on the control ladder (`size`, else the app's step). **Focus.** A focused tab rings inward with its underline kept, so no scroll edge or card clips the ring. In forced colors the selected tab is highlighted. **Direction.** The strip follows the reading direction: on a right-to-left page it starts at the right, and its paging arrow and faded edge stand on the side where tabs wait. **Routing.** The active tab is not synced to the URL; the consumer does that around `v-model`. ##### Keyboard The WAI-ARIA tab pattern: the strip has one tab stop, the active tab, and a move activates the tab and focuses it. - `ArrowLeft` `ArrowRight`: the tab to the left and the tab to the right, round the ends; a disabled tab is passed over. On a right-to-left page the strip starts at the right, so `ArrowRight` is the tab before and `ArrowLeft` the tab after. - `Home` `End`: the first and the last tab. - `Tab`: on to the pane's first control, or to the pane when it holds none. - `ArrowUp` `ArrowDown`: stay the page's: the strip is horizontal. - `Alt` `Ctrl` `Meta`: a chord with them stays the browser's. The paging arrows of a wide set are for the pointer, outside the tab order. ##### Screen reader - Strip: a `tablist` named by `ariaLabel`. - Tab: says whether it is selected (`aria-selected`) and controls its pane (`aria-controls`) only while the pane is there; a disabled tab says so (`aria-disabled`). - Pane: a `tabpanel` named by its tab. - Badge: read in the words of `badgeLabel`, with the number hidden; a bare number warns in dev, since the reader would hear the label and the number as one. ##### States Active, with the brand ink and underline; rest; hover, only when enabled; disabled, in the disabled ink, not chosen by a click or a key; focus, ringing inward with the underline kept. `panel` in the card shell, with `#header` and a rule above the strip, and inside a UiCard's `#header` with no shell of its own; `underline` on its own. A set wider than the strip scrolls, with faded edges and arrows on desktop. In forced colors the selected tab is highlighted. `sm` is 36px, `md` 44px. ##### When to use another component - A choice with no panes: UiRadioGroup `segmented`. - Pages of one set: UiPagination. - The places of the app: UiAppShell. - A block shown or hidden in place: UiReveal. #### Examples ##### Underline ```vue ``` ##### Many tabs ```vue ``` ##### Medium ```vue ``` ##### Disabled ```vue ``` #### API Props: - `modelValue`: `TabValue` (required) — Value of the active tab (`v-model`). - `tabs`: `TabItem[]` (required) — Tabs in order: `value`, `label`, `disabled`, and a `badge` with its `badgeTone` and `badgeLabel` (what it means, in words). - `variant`: `"panel" | "underline"` = `panel | underline` (default `"panel"`) — `panel` (the default) is the header of a block inside the card shell; `underline` is a strip on its own. - `ariaLabel`: `string` (required) — Accessible name of the tab set. - `size`: `"sm" | "xs" | "md"` = `xs | sm | md` — Step of a tab on the control ladder: `sm` 36px, `md` 44px. Unset, the app's size (`createGrani({ size })`); `xs` is read as `sm`. Anything else lands on the root element: native attributes, aria-*, data-testid. Events: - `update:modelValue` (`value: TabValue`) — The new value, for `v-model`. Slots: - `header` with `Record` — Above the strip, inside the shell; `panel` only. What the tabs do not switch. #### How it behaves ##### More past the edge - When: its tabs are wider than their strip. - Props: none: every UiTabs. - Guarantee: The strip scrolls sideways without a bar and never wraps; an edge that hides tabs fades, and with a mouse an arrow there pages to the rest. - Without it: Tabs past the edge that nobody knows are there, or a strip that breaks onto a second line. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTabs.spec.ts, not in the package): "a long set scrolls sideways without a bar and never wraps", "edges that hide tabs fade and grow arrows; a set that fits has neither", "the arrows are for a mouse: drawn only on a device whose pointer hovers and is fine, never on touch" - Pattern for all components: https://grani.arseni.work/patterns/finding#edge-says-more ##### Compact counts - When: a tab has a count. - Props: `badge` and `badgeLabel` on the tab. - Guarantee: The count shows only above zero and reads 99+ past its limit. A screen reader announces the words you give, such as “3 unread”, instead of a bare number. - Without it: A 0 sits on every quiet tab, and a screen reader announces “Inbox 3” without saying what the 3 counts. - Code: `` - Your part: Give `badgeLabel` the count in words, such as “3 unread”; a bare number triggers a warning in development. - Proof, in the repository's tests (UiTabs.spec.ts, not in the package): "a count of zero draws no badge", "a count past its limit reads 99+ and keeps the badge short", "a badge with badgeLabel is read in words: the number hidden, the meaning said", "a bare number badge warns in dev" - Pattern for all components: https://grani.arseni.work/patterns/waiting#compact-counts ##### Share a link to the open tab - When: a tab should be shared as a link. - Props: `v-model`. - Guarantee: It shows the tab named by `v-model` and reports every change through it; it does not read or write the page address itself. - Without it: A link that always opens on the first tab, whatever tab was open when it was sent. - Code: `` - Your part: Bind `v-model` to a query parameter of the route and read it back when the page opens. If the address names a tab that no longer exists, fall back to the first one. ##### Shortcuts kept - When: keyboard focus is on a tab. - Props: none: every UiTabs. - Guarantee: The arrows move between tabs; with Alt or Cmd held the tab stays and the browser takes the key, so Alt+Left still goes back a page. - Without it: Going back a page from the row of tabs switches the tab instead. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTabs.spec.ts, not in the package): "a browser chord on a tab is not swallowed: Alt+ArrowLeft and Cmd+ArrowRight emit nothing" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#shortcuts-kept ##### One Tab per group - When: a screen is split into tabs. - Props: `tabs`, `v-model` and `ariaLabel`. - Guarantee: The tab strip takes one press of Tab and enters on the open tab. The arrow keys move to the next or previous tab and open it, wrapping round at the ends; Home and End go to the first and last tab, and the next Tab goes into the open pane. - Without it: Tabs built as a row of buttons take a press of Tab each before you reach the content below them. - Code: `` - Your part: Name the strip with `ariaLabel`, and put each pane in the slot named after its tab. - Not covered: A pane that is not shown is unmounted, so a form inside it keeps what was typed only if the parent holds the values. - Proof, in the repository's tests (UiTabs.spec.ts, not in the package): "marks the active tab and gives only it a tab stop", "arrows wrap round the ends; Home and End jump to the ends", "a pane with a focusable child adds no tab stop of its own; a pane of words does" - Pattern for all components: https://grani.arseni.work/patterns/opening#one-stop The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useControlSize`. ### Textarea (`UiTextarea`) > Write several lines, such as a note, address or biography, in a field that can grow with the text. A component of grani 0.1.0. Form, stable, since 0.1.0. Page: https://grani.arseni.work/components/textarea Also called multiline input, text area. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See the value the app actually accepted. - Submit the values shown in the form. - Go straight to the field that needs fixing. - Name each field once for screen readers. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass the text the app holds as `modelValue`, and explain why a change was refused. - Give it a `name`. - Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Put it in a UiField with a `label`, or give it `ariaLabel`. #### Why it works this way A multi-line text field in the input capsule. Take it for a note, an address or a bio. **Height.** The height comes from `rows`, from the resize handle, or from `resize="auto"`, which grows from `rows` up to 24rem and then scrolls. One row stands on the control ladder (`size`, else the app's step), so it lines up with UiInput. **Field.** It reads the field context; standalone, the name goes through `ariaLabel`. **Attributes.** Attributes and listeners land on the textarea, `class` and `style` on the capsule. **Model.** The field shows the model: when the owner refuses a change, or a form resets, it goes back to the model and the caret stays where it was. **Empty.** The value is text, and empty is `''`, never `null`. **Length.** `maxlength` cuts off text past the limit and shows no counter; the caller writes one into UiField's `#meta`. **Placement.** In a form column beside UiInput, inside UiField, or in a UiModal or a UiCrudDrawer that sends on Cmd+Enter from it. ##### Keyboard A native textarea. - `Tab`: reaches it. - `Enter`: adds a line. - `Meta+Enter` `Ctrl+Enter`: send from it in a UiModal or a UiCrudDrawer; that key belongs to the surface, not to the textarea. Nothing is sent while an IME composes. `readonly` keeps it focusable and blocks typing; `disabled` blocks the focus too. The handle resizes with the pointer. ##### Screen reader - Field: a text box named by `ariaLabel` or the field's label, never by the placeholder. A textarea with no name warns in dev. - Errors: `invalid` sets `aria-invalid`. Inside UiField the description and the error are read with it once, and `aria-required` says it is required. - Caller attributes: a caller's `aria-invalid` and `aria-required` reach it when the field sets none. ##### States Rest, hover, focus (the capsule draws the ring), disabled (its plate, nothing sent), readonly, invalid (red border and halo; disabled wins over it), with a handle, a fixed height, `auto` growing to 24rem and then scrolling, and one row on each step of the ladder. ##### When to use another component - One line: UiInput. - Names added one by one: UiListField. - A counter under it: the caller's text in UiField `#meta`. #### Examples ##### Field ```vue ``` ##### Resize ```vue ``` ##### Sizes ```vue ``` ##### States ```vue ``` ##### Refused ```vue ``` ##### Form ```vue ``` #### API Props: - `modelValue`: `string` (required) — The text (`v-model`); empty is `''`. - `rows`: `number` (default `3`) — Visible lines before the user resizes the control. - `name`: `string` — Native name for forms. - `id`: `string` — Own id when standalone. Inside UiField the field's id takes precedence. - `placeholder`: `string` — Hint shown while empty. Not a replacement for a label. - `maxlength`: `number` — Maximum number of characters. - `readonly`: `boolean` (default `false`) — Prevents editing while keeping the control focusable. - `disabled`: `boolean` (default `false`) — Prevents input and interaction. - `invalid`: `boolean` (default `false`) — Marks the control invalid: red border and halo. Inside UiField the error sets this. - `required`: `boolean` (default `false`) — Standalone only: a value is needed, said to a reader and to a form (native `required`). Inside UiField the field's `required` says so. - `ariaLabel`: `string` — Accessible name when there is no visible label. A prop, not `aria-label`: the root is the capsule, the name belongs to the control. - `size`: `ControlSize` = `xs | sm | md` — Height of one row on the control ladder; defaults to the app's step. - `resize`: `"none" | "vertical" | "auto"` = `none | vertical | auto` (default `"vertical"`) — `vertical` gives the user a handle; `none` fixes the height at `rows`; `auto` grows with the text. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Events: - `update:modelValue` (`value: string`) — The value changed. #### How it behaves ##### Back to the value - When: the app refuses a change, or the form is reset. - Props: `v-model`, or `modelValue` with `@update:model-value`. - Guarantee: A refused change is undone and the text cursor stays where you were typing, so you can go on. This also holds for text composed with an input method (IME), as for Chinese or Japanese. A form reset brings back the app’s text. - Without it: The refused words stay on the screen, although the app did not accept them. - Code: `` - Your part: Pass the text the app holds as `modelValue`, and explain why a change was refused. - Proof, in the repository's tests (UiTextarea.spec.ts, not in the package): "a change the parent refuses puts the textarea back on the model", "a refused composition goes back to the model too" - Pattern for all components: https://grani.arseni.work/patterns/waiting#refused-goes-back ##### Sent with the form - When: it sits inside a native form. - Props: `name`. - Guarantee: It sends its text under its `name`, nothing while disabled, and after a form reset it shows the app's value again. - Without it: A text field on screen that the form never sends. - Code: `` - Your part: Give it a `name`. - Proof, in the repository's tests (UiTextarea.spec.ts, not in the package): "in a form it sends its value under its name, nothing when disabled", "a form reset leaves the textarea on its model" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#sends-like-native ##### Focus on the error - When: a form is sent with the text in error. - Props: `invalid`, or the error of its UiField. - Guarantee: When the textarea is the first field with an error, keyboard focus lands in it, so you can type the fix straight away. - Without it: The form does not send, keyboard focus stays on Save, and you have to find the field with an error yourself. - Code: `` - Your part: Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Proof, in the repository's tests (UiTextarea.spec.ts, not in the package): "a textarea marked invalid is what focusInvalid lands on" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-invalid ##### One name - When: it needs a name. - Props: a UiField around it, or `ariaLabel`. - Guarantee: A screen reader announces the field’s label or `ariaLabel`, followed by its description and error, each once. The placeholder is never used as its name, and a missing name triggers a development warning. - Without it: A textarea named only by its placeholder, which disappears as soon as you type. - Code: `` - Your part: Put it in a UiField with a `label`, or give it `ariaLabel`. - Proof, in the repository's tests (UiTextarea.spec.ts, not in the package): "inside UiField with a description it is named once and described once", "warns in dev when it has no name" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useControlSize`. ### Time picker (`UiTimePicker`) > Choose hours and minutes or type a time such as 2:30p or 1430. A valid time is kept even if it is not among the listed options. A component of grani 0.1.0. Dates, stable, since 0.1.0. Page: https://grani.arseni.work/components/time-picker Also called time input, time field. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See the value the app actually accepted. - Submit the values shown in the form. - Respect date limits without losing a value. - Type a date or a time as your language writes it. - Close only the top layer with Escape. - Go straight to the field that needs fixing. - Clear a field and enter its replacement immediately. - Name each field once for screen readers. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass the time the app holds as `modelValue`, and explain why a time was refused. - Give it a `name`. - State the allowed window in the field's description, since the list alone does not say why some times cannot be picked. - Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Treat `null` as no time. - Put it in a UiField with a `label`, or give it `ariaLabel`. #### Why it works this way A form field for a time of day, in the input capsule on the control ladder. Take it beside a UiDatePicker or a UiCalendar for a day and its hours. **Value.** The value is `HH:mm` (`10:30`); one with seconds (`14:30:00`) is read to the minute, and a change sends `HH:mm`. It is shown as the app's language writes a time: `14:30` in Russian, `2:30 PM` in American English. **Panel.** The button opens a UiPopover with two listboxes side by side, Hour and Minute (a third, Period, in a 12-hour locale); each shows five rows and a half and scrolls the rest (`useVisibleRows`), scrolled on open to the chosen row. A press on an hour sets the value at once, the current minute clamped to the nearest one the window still allows (the first allowed minute with no value yet), keeps the panel open and moves the focus to Minute; a press on a minute sets it and closes the panel, the focus back on the field. A press on a period keeps the hour's number and flips its half of the day, and stays open. **Typing.** Digits build a time without the search row UiSelect has: one or two are the hour (`9` lights 9, `14` lights 14), three are `H:mm` (`930`, `230`) while the minute fits (`183` stays 18:3_), four `HH:mm` (`0930`, `1437`). A mark after the hour (`9:30`, `9.30`, `9 30`) ends the hour where it is, and a lone digit after it is the minute's tens. Digits of other scripts count as theirs. The hour reads on the 24-hour clock unless `a` or `p` sets its half of the day, and a 12-hour field says the half it reads as it is typed (`2:30 AM`); `a` or `p` with nothing typed moves the time held to that half. A time that does not exist (`9:75`, `2400`) is no time, never one nearby. The field shows what was typed until Enter takes it to the minute, off the step too, and closes; a time that is not one, or one outside the window, is not taken: the field is marked invalid until the text changes, and a reader hears why. A press away takes it too when it is written in full: the hour and two digits of the minute, and in a 12-hour language its half of the day or an hour past 12 (where the half cannot be typed as `a` or `p`, Korean or Arabic, the minute is enough); anything else is dropped there, and a reader hears why. While it is typed the columns show it chosen, the minute once both of its digits are in, off the step too. Backspace takes back the last key, the half of the day too; Escape, the cross, a press on a row and an arrow drop it and give the time held back. Typing opens the panel from the closed field too, and the keys typed while it opens go on with the time, so the pointer picks on the step and the keys reach any minute. **Hours.** The app's language decides: a 24-hour one draws 00…23 in two columns and writes `14:30`; a 12-hour one draws 12, 1…11 and a Period column of the language's AM/PM words and writes `2:30 PM`. `hourCycle` sets it for every language. **Window.** `min` and `max` are `HH:mm`. `min` after `max` is read as a window that wraps past midnight (a night shift, 22:00–06:00), not an empty one. An hour with no allowed minute in the window, and a minute outside it, are shown but disabled; a value outside the window is kept and reads invalid. **Step.** Minutes in a column are multiples of `step` (1..60, a bad step falls back to 1); the default is 5. A value off the step is kept and listed in its own place. **Empty.** No time is `null`: the cross sends `null`, and `null` or an empty string reads as none. With `name` a form gets the field's name with an empty value, as a native time input sends it. **Odd values.** `9:30` is read as `09:30`. A value that is not a time (`25:99`) counts as none. **Width.** The field keeps its width when a time is picked or cleared; cut in a narrow column, the whole time shows in a tooltip on hover. A required field shows no cross. **Field.** Inside UiField it reads id, error and required. `focus()` puts the focus on it. ##### Keyboard - `Tab`: reaches the combobox. - `ArrowDown` `Alt+ArrowDown` `Enter` `Space`: open the panel, on the closed field. - `0–9`: a digit opens the panel and starts the typed time; a mark after the hour (`:` `.` `-` `,` or a space) ends it; in a 12-hour language `a`/`p` set its half of the day. - `Alt` `Ctrl` `Meta`: a chord with them stays the browser's, on the field and in the panel; only `Alt+ArrowDown` on the closed field is its own. In the open panel: - `ArrowUp` `ArrowDown`: move within a column, over the enabled rows; `Home`/`End` to its ends. - `ArrowLeft` `ArrowRight`: move to the next or the previous column. - `Enter` `Space`: picks the row, as a press does; on Minute (or Period with no Minute column left to fill) it closes the panel too. With a time typed, Enter takes it and Space is a mark. - `Backspace`: takes back the last typed key. - `Escape`: closes the panel; inside a window it closes only the panel. - `Tab`: moves to the next column and goes round inside, as in UiDatePicker's calendar; `Escape` leaves. The cross clears the value and keeps the focus on the field. ##### Screen reader - Field: a combobox named by `ariaLabel` or the field's label and says the time as the locale prints it, or the placeholder. - Panel: Hour, Minute and, in a 12-hour locale, Period are listboxes named in words, the chosen row marked, the focus moving with the rows (roving, not `aria-activedescendant`: three listboxes side by side read better as one tab stop each). - Icon: the clock icon is hidden from a screen reader. - Errors: a time outside `min` and `max`, a typed time refused, or a field error, sets `aria-invalid`; `required` sets `aria-required`; the field's description and error are read with it once. - Typed time: a time not taken is said in words, "Not a time", "Time outside the allowed range" or "Time not kept: type it in full". ##### States Empty, a time picked, open with the chosen hour and minute (and period) highlighted, a time off the step (listed in its place), a time outside the window (kept, reads invalid), a value that is not a time (shown as empty, nothing sent), disabled (nothing sent, the panel closes), invalid, required (no cross), `clearable` with the cross, and joined in a UiButtonGroup. The width holds in all of them. ##### When to use another component - A day: UiDatePicker. - A duration in minutes: UiInput `numeric`. - Any other pick from a list: UiSelect itself. #### Examples ##### Odd values ```vue ``` ##### States ```vue ``` ##### Sizes ```vue ``` ##### Modal ```vue ``` ##### Refused ```vue ``` ##### Form ```vue ``` ##### Russian ```vue ``` #### API Props: - `modelValue`: `string | null` (default `null`) — The time, `HH:mm` (`v-model`); `null` for none. - `step`: `number` (default `5`) — Minutes between two rows of the Minute column. - `min`: `string` (default `"00:00"`) — The first time the window allows, `HH:mm`. - `max`: `string` (default `"23:59"`) — The last time the window allows, `HH:mm`; a `min` after it wraps the window past midnight. - `clearable`: `boolean` (default `false`) — A cross that empties the field. - `placeholder`: `string` (default `""`) — Shown while empty; defaults to "Pick a time". - `disabled`: `boolean` (default `false`) — The field cannot be changed. - `required`: `boolean` (default `false`) — Standalone only: empty is an error, said to a reader, and no cross. Inside UiField the field's `required` says so. - `invalid`: `boolean` (default `false`) — Standalone only: the value is wrong. Inside UiField the field's error says so. - `name`: `string` — Sends the time with a form, under this name. - `id`: `string` — Id of the trigger, standalone; inside UiField the field's id wins. - `ariaLabel`: `string` — Standalone only: the accessible name. Inside UiField the label names it. - `hourCycle`: `12 | 24` — 12 hours with an AM/PM column, or 24; unset, the app's language decides (`2:30 PM` in American English, `14:30` in Russian). The field writes the time the same way. - `size`: `ControlSize` = `xs | sm | md` — Step of the control ladder. Unset, the app's size (`createGrani({ size })`), `sm` by default. Attributes: `class` and `style` stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it. Events: - `update:modelValue` (`value: string | null`) — A time was picked (`HH:mm`), or `null` when cleared. #### How it behaves ##### Back to the value - When: the app refuses a time. - Props: `modelValue` with `@update:model-value`. - Guarantee: If the app refuses the time you pick, the field shows the previous time again. - Without it: The field shows a time the app is not using. - Code: `` - Your part: Pass the time the app holds as `modelValue`, and explain why a time was refused. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "a change the parent refuses puts the picker back on the model" - Pattern for all components: https://grani.arseni.work/patterns/waiting#refused-goes-back ##### Sent with the form - When: it sits inside a native form. - Props: `name`. - Guarantee: It sends the time as `HH:mm` under its `name`, the time the field shows, an empty value while it has none, and nothing while disabled. - Without it: A time field on screen that the form never sends. - Code: `` - Your part: Give it a `name`. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "in a form it sends HH:mm under its name, and an empty value while empty", "a disabled picker sends nothing with a form" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#sends-like-native ##### Limits shown - When: The times are limited by `min` and `max`. - Props: `min`, `max`. - Guarantee: You can see hours and minutes outside the allowed range, but cannot select them. The range can cross midnight. A previously stored time outside it remains visible and is marked invalid, so you can correct it. - Without it: A list of only the allowed times: a saved time outside them shows as an empty field, and saving the form sends no time. - Code: `` - Your part: State the allowed window in the field's description, since the list alone does not say why some times cannot be picked. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "a value outside min and max is kept and reads invalid" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#limit-shown ##### Typed as written - When: a digit is typed on the field. - Props: none; 12 or 24 hours come from the app’s `locale`, or `hourCycle`. - Guarantee: The field shows what is typed, the Hour column moves to the hour it reads, and Enter takes the time to the minute, off the step too. Three digits are `H:mm` and four `HH:mm`; a mark (`:`, `.`, a space) ends the hour. A 12-hour field says the half of the day it reads (`2:30 AM`) until `a` or `p` sets another. A press away takes the time when it is written in full, and in a 12-hour language with its half of the day; Escape drops it. A time that does not exist, or one outside `min` and `max`, is not taken: the field is marked invalid and a screen reader announces why. - Without it: A time is scrolled to in a list of minutes, or typed into a plain text field that reads `230` as 23:0 and sends a time nobody meant. - Code: `` - Your part: Nothing; `createGrani({ locale })` sets 12 or 24 hours. - Not covered: Words are not read: “noon” or “half past two” is the columns’ to give. Where the half of the day is not written with a and p (Korean, Arabic), a press away takes a time written to the minute on the 24-hour clock. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "three digits are H:mm: 230 and Enter is 02:30, not 23:00", "a space after the hour ends it, as a colon does: 9 30 is 09:30, and nothing is emitted before", "Enter on a time that does not exist takes nothing, says so and marks the field invalid", "a time that does not exist is not taken: 2400 is not 02:40", "a press away takes a time typed in full, and drops a shorter one, said", "in a 12-hour language a press away wants the period, or an hour only the 24-hour clock has", "in a 12-hour language the typed text names the half of the day it will be read in", "a time outside the window is not taken by Enter nor by a press away, and said", "Escape drops the typed time wherever the focus is in the panel" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#date-as-written ##### Escape, top first - When: its list is open inside a window. - Props: none. - Guarantee: Escape closes the list of times only, and keyboard focus goes back to the field; the window stays open. - Without it: One Escape closes the list and the window behind it at once. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "Escape in a window closes the list only" - Pattern for all components: https://grani.arseni.work/patterns/closing#escape-top ##### Focus on the error - When: a form is sent with no time. - Props: `invalid`, or the error of its UiField. - Guarantee: When the time field is the first one in error, keyboard focus lands on it, so you can enter the time straight away. - Without it: The form does not send, keyboard focus stays on Save, and you have to find the field with an error yourself. - Code: `` - Your part: Pass the error to its UiField, or set `invalid`. UiModal with `form` and UiCrudDrawer move the focus themselves; in a form of your own, call `focusInvalid(form)` after your check. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "a picker marked invalid is what focusInvalid lands on" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-invalid ##### Cleared in place - When: A time may be left empty. - Props: `clearable`. - Guarantee: The × sets the value to `null`, and keyboard focus stays on the field. A required field has no ×, because empty is not allowed there. - Without it: The × disappears together with the time it cleared, and keyboard focus is lost with it. - Code: `` - Your part: Treat `null` as no time. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "the cross clears it and the focus stays on the field" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#cleared-in-place ##### One name - When: it needs a name. - Props: a UiField around it, or `ariaLabel`. - Guarantee: A screen reader announces it once, by the field's label or by `ariaLabel`, with the time as the locale writes it; the description and the error are announced with it, once. - Without it: A time field announced only by its placeholder. - Code: `` - Your part: Put it in a UiField with a `label`, or give it `ariaLabel`. - Proof, in the repository's tests (UiTimePicker.spec.ts, not in the package): "inside UiField with a description it is named once and described once" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useControlSize`, `useUiT`, `announce`. ### Toaster (`UiToaster`) > See a short message about an action's progress or result, with an action such as Undo when available. A component of grani 0.1.0. Overlays, stable, since 0.1.0. Page: https://grani.arseni.work/components/toaster Also called toast, notifications, snackbar. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - See whether an action worked. - Ignore extra presses while a request runs. - Confirm only what cannot be undone. - Reach frequent actions from the keyboard. - Keep keyboard focus where you are working. Implemented by the app: - Data fetching, saving, permissions and business rules. - Keep the button in `loading` until the request answers, then report the outcome with `toast.success` or `toast.error`; an error says what to do next. Where the button leaves the screen once pressed, as a menu row does, `toast.promise` shows the wait in a message instead. - Make the change, retain the information needed to reverse it, and connect the toast’s Undo action to that reversal. - List F8 wherever your app lists its keys; the notification region already names it to a screen reader as “Notifications (F8)”. #### Why it works this way The place where toasts appear. Put it once at the app root (its root component or a layout), beside UiConfirm. **Root.** Never put it in a page or a component: every `useToast()` call anywhere lands in this one stack, and a second toaster in the same app warns in dev. Without a toaster, a toast is queued and never seen, and dev says so once. It stands at the end of the `body`, or where `createGrani({ teleport })` says. **Placement.** By default it stands at the bottom start of the screen (`placement`: `bottom-start`, `bottom`, `bottom-end`; start and end follow the reading direction), clear of the safe area. On a phone it stands at the top, where it covers no pinned footer and no Save button. The newest toast is in front, and up to three are shown; older ones peek behind it, smaller and as tall as it, so a short one never hides behind a long one nor a long one stands over a short one as an empty frame, and wait with their timers paused until there is room. Under the pointer or the focus, the pile opens into a column and every timer stops until both have left. Over a drawer. The stack stands above every layer and leaves no room for the one under it. On a phone, at the top, it covers the drawer's header (its cross and title) while it stays; on a screen under 850px wide, at the bottom start, it covers the end of a drawer's footer, its Cancel. It goes by itself, by a swipe or with its close button. In a UiAppShell the stack at the bottom start stands over the sidebar's `#footer` while it shows: with a control there that is used often (a theme switch), set `placement="bottom-end"`. **Toast.** A toast is a row on a card: the glyph of its tone (or its own `icon`; `neutral` has none), a title, a detail line, one action and a close button. It closes when its `duration` runs out (5 s, 7 s for an error, 13 s with an action, time to reach it by `F8`), on the close button, on Escape while focused, or on a swipe away from the screen edge it stands at (down, or up on a phone) or toward its side. Its action runs once. A long line wraps; a long detail is cut at three lines. A toast never holds what the page needs to go on: that is a dialog or inline text. **Again.** The same toast shown again while one stands, shown or waiting (the same title, detail, tone, glyph and `announce`, no action), is that one card: it comes to the front with its whole time again, and its id is returned. Five presses of Copy are one "Copied", not a pile of five. A toast with an action is always new: two Undo buttons undo two things. **The key.** F8 is a function key no browser uses for itself, and the key a toast region is commonly reached by. F6 is the browser's own walk between its panes, and a letter with Alt or Ctrl+Alt types text on some keyboards. The region's name includes the key, so a screen reader user hears how to get in. The toaster stands above every layer, and an open window's focus trap lets the focus into it. ##### Keyboard - `F8`: from anywhere on the page, with a window open or not, moves the focus to the newest toast's action (its close button when it has none); `F8` again goes back. - `Tab`: reaches a toast's action and its close button. - `Escape`: on a focused toast, closes it. When a toast closes with the focus in it (Escape, its close button, its action), the focus goes back to where it came from. Focus in the stack opens the pile and pauses every timer until it leaves; a toast beyond the three shown is `inert` until it moves up. The swipe is for a pointer; the keyboard closes a toast with the button or Escape. ##### Screen reader - Live regions: two stand on the page before any toast arrives. - Error: with `priority: 'high'`, an alert, read at once. - Other toasts: a status, read at a pause. - Content: each is read with its title and detail. - Several: toasts that come together are read one after another in the order they came. - Again: the same toast shown again while it stands is read once more. - Silent: `announce: false` is not read (for a control that has already said it). - Stack: a region named "Notifications (F8)". - Close button: each is named "Close" and the toast's title. - Action: its label, described by the toast's title, so F8 landing on it says what it acts on. - Glyph: hidden. ##### States One toast per tone (`neutral` without a glyph, `success`, `danger`, `warning`, `info`); a glyph of its own; loading from `promise`, then a new toast with its outcome; with an action; open until closed (`persistent`); the same toast again, one card; long text wrapping and a detail cut at three lines; a pile of three with older ones peeking behind, opened under the pointer or the focus; placed at the start, the center or the end of the bottom edge, and at the top on a phone. ##### When to use another component - What the page needs to go on: UiModal or inline text. - A question: UiConfirm. - A field's validation: stays by the field in UiField. - A load that failed: UiNoData `tone="danger"` with Retry, inline. #### Examples ##### Undo ```vue ``` ##### Request ```vue ``` ##### Pile ```vue ``` ##### Persistent ```vue ``` #### API Props: - `placement`: `"bottom" | "bottom-end" | "bottom-start"` = `bottom | bottom-end | bottom-start` (default `"bottom-start"`) — Where the stack stands on the bottom edge; `start` and `end` follow the reading direction. Anything else lands on the root element: native attributes, aria-*, data-testid. ##### `useToast()` The queue behind UiToaster. Components call `toast.success(...)` and the toaster at the app root shows it. Feedback on an action goes here: a save that failed, a copy that worked; a field's validation stays by the field and a load error stays inline with its retry. The same toast again while one stands, with no action, is that one card, back at the front with its id. Returns: - `toasts`: `Readonly>` — Every toast in order of arrival, read-only. - `stack`: `ComputedRef` — The toasts in the stack, newest first; beyond the limit they wait, their clocks held. - `show`: `(options: ToastOptions) => number` — Shows a toast from full options and returns its id. - `update`: `(id: number, patch: Partial) => void` — Changes a toast by id in place; a new tone or duration restarts its clock. - `close`: `(id?: number | undefined) => void` — Closes one toast by id, or all of them with no argument; an id that is `undefined` closes none. - `promise`: `(p: Promise, messages: ToastPromiseMessages) => Promise` — A request as toasts: `loading` while it runs, then a new one with `success` or `error`; a message that throws gives way to "Done" or "Could not complete the action". - `success`: `(title: string, options?: Omit) => number` — `success(title, options?)`: a done action, "Invoice sent". - `error`: `(title: string, options?: Omit) => number` — `error(title, options?)`: a failed action, read out at once, a little longer on screen. - `warning`: `(title: string, options?: Omit) => number` — `warning(title, options?)`: done, with something to look at. - `info`: `(title: string, options?: Omit) => number` — `info(title, options?)`: a fact worth a glance. `ToastAction` - `label`: `string` — The button's text: "Undo", "Open". - `onClick`: `() => void` — Runs once, as the toast closes. `ToastOptions` - `title`: `string` — One line, the fact: "Invoice sent". - `description`: `string` — A second line with the detail, optional. - `tone`: `"neutral" | "success" | "warning" | "danger" | "info"` — Meaning, and with it the glyph and its color: `neutral` (default), `success`, `danger`, `warning`, `info`. - `icon`: `Component` — A Lucide glyph in place of the tone's own; the tone still colors it. - `loading`: `boolean` — A request in flight: a spinner instead of the glyph; `promise` sets it. - `duration`: `number | "persistent"` — How long it stays once shown: 5 s by default, 7 s for `danger`, 13 s with an `action`. - `priority`: `"low" | "high"` — How a screen reader hears it: `high` at once, `low` at a pause; `danger` is `high` by default. - `action`: `ToastAction` — One button in the toast, "Undo" or "Open"; it never holds what the page needs to work. - `announce`: `boolean` — `false` shows it unread: for an outcome the control has already announced where the focus is (a copy button's own live region). `Toast` - `id`: `number` - `duration`: `number | "persistent"` — How long it stays once shown: 5 s by default, 7 s for `danger`, 13 s with an `action`. - `priority`: `"low" | "high"` — How a screen reader hears it: `high` at once, `low` at a pause; `danger` is `high` by default. - `again`: `number` — How many times the same toast came again while it stood; each time it is read again. - `title`: `string` — One line, the fact: "Invoice sent". - `description`: `string` — A second line with the detail, optional. - `tone`: `"neutral" | "success" | "warning" | "danger" | "info"` — Meaning, and with it the glyph and its color: `neutral` (default), `success`, `danger`, `warning`, `info`. - `icon`: `Component` — A Lucide glyph in place of the tone's own; the tone still colors it. - `loading`: `boolean` — A request in flight: a spinner instead of the glyph; `promise` sets it. - `action`: `ToastAction` — One button in the toast, "Undo" or "Open"; it never holds what the page needs to work. - `announce`: `boolean` — `false` shows it unread: for an outcome the control has already announced where the focus is (a copy button's own live region). `ToastPromiseMessages`: The three faces of `promise`: a title or full options, the last two maybe from the outcome. - `loading`: `string | ToastOptions` - `success`: `string | ToastOptions | ((value: T) => string | ToastOptions)` - `error`: `string | ToastOptions | ((error: unknown) => string | ToastOptions)` #### How it behaves ##### Outcome shown - When: a request started by a button, such as a send or a save. - Props: the button's `loading` while the request runs, then `toast.success` or `toast.error`. - Guarantee: While the request runs, its button shows a spinner and ignores a second press. When the request completes, a message states the outcome, and a screen reader announces an error immediately. - Without it: The button is pressed, and nothing says whether the request went or how it ended. - Code: `sending.value = true try { await send(invoice) toast.success('INV-0042 sent') } catch { toast.error('Could not send', { description: 'Check the connection and send it again.' }) } finally { sending.value = false }` - Your part: Keep the button in `loading` until the request answers, then report the outcome with `toast.success` or `toast.error`; an error says what to do next. Where the button leaves the screen once pressed, as a menu row does, `toast.promise` shows the wait in a message instead. - Proof, in the repository's tests (UiToaster.spec.ts, not in the package): "an error is an alert, the rest are status; the glyph follows the tone" - Pattern for all components: https://grani.arseni.work/patterns/waiting#answered ##### One press, one request - When: a message with an action, such as Undo or Open. - Props: `action: { label, onClick }`. - Guarantee: The action closes its notification and runs once for that notification. Another press during the fade-out does not run it again. - Without it: A double press on Undo restores the invoice twice. - Code: `toast.show({ title: 'Invoice deleted', action: { label: 'Undo', onClick: restore } })` - Your part: Nothing: `onClick` is called once. - Proof, in the repository's tests (UiToaster.spec.ts, not in the package): "the action runs once and closes its toast", "a second click on the action during the leave fade does not run it twice" - Pattern for all components: https://grani.arseni.work/patterns/waiting#one-press ##### Undo, not a question - When: a change that can be reversed: a delete, an archive, a move. - Props: `action: { label: 'Undo', onClick }` on the toast. - Guarantee: A notification with Undo stays visible longer than one without an action. Its background fades to show the time remaining, and the timer pauses while the pointer is over the notifications or keyboard focus is inside them. Undo runs once for that notification. - Without it: Either a delete is gone for good, or every delete first asks “Are you sure?”. - Code: `toast.show({ title: 'Invoice deleted', action: { label: 'Undo', onClick: restore }, })` - Your part: Make the change, retain the information needed to reverse it, and connect the toast’s Undo action to that reversal. - Proof, in the repository's tests (UiToaster.spec.ts, not in the package): "a toast with an action stays longer than one without", "A toast with an action shows its time as a haze over its whole stay; a plain one has none.", "the close button and Escape on a focused toast close it; the pointer on the stack holds the clocks", "the action runs once and closes its toast" - Pattern for all components: https://grani.arseni.work/patterns/waiting#ask-what-stays ##### Shortcut keys - When: a notification is shown, with a window open or not. - Props: none: every UiToaster. - Guarantee: F8 from anywhere on the page moves keyboard focus to the newest notification's action, or to its close button when it has none, and F8 again returns focus to where it was. With no notification on screen, the key is left to the page. - Without it: A notification only the mouse can reach, gone before keyboard focus gets there. - Code: `` - Your part: List F8 wherever your app lists its keys; the notification region already names it to a screen reader as “Notifications (F8)”. - Proof, in the repository's tests (UiToaster.spec.ts, not in the package): "F8 moves the focus to the newest toast action; the region names the key", "F8 with no toast does nothing and leaves the key to the page" - Pattern for all components: https://grani.arseni.work/patterns/working-the-list#keyboard-actions ##### Focus stays near - When: A message closes while keyboard focus is in it: by Escape, its close button or its action. - Props: none: every UiToaster. - Guarantee: Keyboard focus goes back to where it was before it moved into the message, for example the field you were typing in, not to the start of the page. - Without it: The message closes with keyboard focus inside it, focus is lost, and you have to find the field you were in again. - Code: `` - Your part: Nothing. - Proof, in the repository's tests (UiToaster.spec.ts, not in the package): "running the action from the keyboard gives the focus back where it came from" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#focus-stays The patterns: https://grani.arseni.work/patterns Built with what `grani` exports: `useToast`, `useUiT`, `announce`. ### Tooltip (`UiTooltip`) > Get a short hint on hover, keyboard focus or tap; anything essential stays on the page outside the tooltip. A component of grani 0.1.0. Overlays, stable, since 0.1.0. Page: https://grani.arseni.work/components/tooltip Also called hint, hover hint. #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Close only the top layer with Escape. - Name each field once for screen readers. Implemented by the app: - Data fetching, saving, permissions and business rules. - Name an icon button with `ariaLabel`, and use the hint to add what the name does not say. #### Why it works this way A short text hint beside its trigger. Take it for detail a dense row has no room for. **Showing.** It shows on hover and on keyboard focus, but not when a script gives the focus back after a click. When the pointer moves from one trigger to the next, the next hint opens at once. A tap shows it on a trigger that only shows something (a cut text, a date); a tap on a button that opens something only opens it. A press outside hides the hint and still reaches the window under it. A long word wraps inside it. **Content.** Text only. It is never the only place for what must be read by a person who cannot reach it: a natively disabled button takes no focus, so its reason is visible text beside it; UiButton and UiIconButton with `disabledReason` keep the focus and say their reason in one. **Trigger.** Attributes and listeners set on the tooltip reach the trigger along with the trigger's own, so it can stand inside a popover's or a menu's `#trigger`. The trigger is one element or a single-root component (not a fragment, not another tooltip) and should be focusable (a static badge takes `tabindex="0"`). When the panel is pushed aside, its tail stays on the trigger; a trigger that goes away takes the hint with it. The pointer may cross onto the tooltip (WCAG 1.4.13). **Placement.** UiTruncate and UiDateCell stand on it; UiButton and UiIconButton draw the same hint for the reason they are off. It names an icon button where a sighted user needs the name (the sidebar's toggle, a table's columns). ##### Keyboard Keyboard focus on the trigger shows it at once, and blur hides it; a focus a script gives back after a click does not show it. - `Escape`: hides it first and goes no further, so a window under it stays until the next `Escape`. The hint itself takes no focus and holds nothing focusable. ##### Screen reader - Role: a `tooltip`. - Description: while shown, it describes the trigger (`aria-describedby`), next to any description you set; with no `content` there is none. - Repeated words: a hint that repeats the trigger's own name (an icon button's `ariaLabel`) or a description it already has (a disabled button's reason) is not wired, so the words are read once. - Tail: hidden. ##### States Hidden; shown after a short delay on hover, at once on keyboard focus, on a tap on a touch screen, and at once when the pointer moves from one trigger to the next. On one of four sides (`side`), flipped when that side has no room, and pushed aside at the screen edge with the tail kept on the trigger; a `left` or `right` hint with room on neither side goes below or above, never over its trigger. Long text and a long word wrap. One hint on the page at a time. ##### When to use another component - A hint with a link or a control: UiPopover. - The reason a button is off: UiButton or UiIconButton `disabledReason`, which keeps the focus and says it; for a button natively `disabled`, visible text beside it. - A cut value in a cell: UiTruncate, built on it. - A date: UiDateCell, built on it. #### Examples ##### Dense ```vue ``` ##### Long ```vue ``` ##### Popover ```vue ``` ##### Disabled ```vue ``` ##### Edge ```vue ``` ##### Window ```vue ``` #### API Props: - `content`: `string` (default `""`) — The hint. Empty or absent means no tooltip. - `side`: `"top" | "bottom" | "left" | "right"` = `top | bottom | left | right` (default `"top"`) — Preferred side; it flips when that side has no room, and a side hint with room on neither side goes below or above. Attributes are placed by the component itself: its description says where. Slots: - `default` with `Record` — The trigger: one element or a single-root component the hint describes. It should be focusable. #### How it behaves ##### Escape, top first - When: a hint is shown inside a window, a drawer or a panel. - Props: none: every UiTooltip. - Guarantee: The first Escape hides the hint and goes no further; the window under it closes only with the next Escape. - Without it: Escape meant for a hint closes the whole window, and what you typed in it is lost. - Code: ` Reset ` - Your part: Nothing. - Proof, in the repository's tests (UiTooltip.spec.ts, not in the package): "Escape on a shown tooltip inside a modal hides the hint and leaves the modal open" - Pattern for all components: https://grani.arseni.work/patterns/closing#escape-top ##### One name - When: its hint repeats the name of its trigger, as on an icon button. - Props: `content` equal to the trigger's `ariaLabel`. - Guarantee: When the hint matches the trigger's `aria-label` letter for letter, it is not connected as a description, so a screen reader announces the name once; a hint that adds something is announced as the trigger's description. - Without it: A screen reader announces “Columns, Columns”: the name, then the same word as its description. - Code: ` ` - Your part: Name an icon button with `ariaLabel`, and use the hint to add what the name does not say. - Proof, in the repository's tests (UiTooltip.spec.ts, not in the package): "a hint equal to the trigger name is not wired as its description" - Pattern for all components: https://grani.arseni.work/patterns/filling-in#one-name-one-voice The patterns: https://grani.arseni.work/patterns #### Built on it - [Truncate](https://grani.arseni.work/components/truncate): Keep a long value on one line with an ellipsis, and reveal the full text on hover or tap when it does not fit. ### Truncate (`UiTruncate`) > Keep a long value on one line with an ellipsis, and reveal the full text on hover or tap when it does not fit. A component of grani 0.1.0. Layout, stable, since 0.1.0. Page: https://grani.arseni.work/components/truncate Also called ellipsis, text overflow, truncated text. It works on top of [Tooltip](https://grani.arseni.work/components/tooltip). #### Use ```vue ``` #### Who does what Provided by grani: - Rendering, keyboard and screen reader behavior, and the states this page names. - Read the full text when a label is shortened. Implemented by the app: - Data fetching, saving, permissions and business rules. - Pass the full text in `text` and give the component the width it has. Do not cut text by hand with the `truncate` class and a `title`. #### Why it works this way One line of text cut with an ellipsis, its whole text in a UiTooltip while it is cut. Take it for a name or a title in a narrow place: a table cell, a list row, a file name. **Tooltip.** While the text is really cut, the whole text shows in the tooltip on hover and tap, as UiDateCell shows the full date; text that fits has no tooltip. The cut is measured, not assumed: when a column widens or the text changes, it is measured again, and the tooltip follows. **Props.** `text` is the only prop; markup in a slot handles its own cut. The root is a block `` with no tab stop, and attributes land on it. ##### Keyboard No tab stop: the span is not focusable, so the tooltip opens on hover and on tap, not from the keyboard; for the keyboard, put a control beside it that leads to the whole text. ##### Screen reader - Text: the whole text, always: the cut is CSS, and the span holds every character. - Tooltip: while shown, it describes the span (`aria-describedby`) with the same words again. ##### States Fits, with no tooltip and no native `title`; cut, with the whole text in the tooltip on hover and tap. The cut is measured on mount, on resize, when a web font arrives and when `text` changes, with one pixel of slack; an empty text is a cut of nothing. ##### When to use another component - Markup in a slot: it handles its own cut (`truncate` on the element). - A date: UiDateCell. - The label of a badge: UiBadge cuts it itself. - Text that may wrap: plain text. #### Examples ##### Fits or cut ```vue ``` #### API Props: - `text`: `string` (required) — The text; the whole of it goes to the tooltip while it is cut. Attributes are placed by the component itself: its description says where. #### How it behaves ##### Whole text - When: one line of text in a narrow place. - Props: `text`. - Guarantee: Hover or tap a shortened label to read its full text. The component measures whether it fits and checks again when the text or available space changes. Text that fits has no tooltip or native `title`. - Without it: An ellipsis and nothing more: the end of the name is gone, and the only way to read it is to widen the window. - Code: `` - Your part: Pass the full text in `text` and give the component the width it has. Do not cut text by hand with the `truncate` class and a `title`. - Not covered: The text is not a Tab stop, so a keyboard cannot open this tooltip. If people need the full value to complete a task, provide a nearby button or link that opens it. - Proof, in the repository's tests (UiTruncate.spec.ts, not in the package): "A cut text keeps its whole in a tooltip, while the cut is real.", "Text that fits gets no tooltip, and no native title either.", "The cut is measured again when the text changes." - Pattern for all components: https://grani.arseni.work/patterns/finding#whole-text The patterns: https://grani.arseni.work/patterns ## How admin screens behave: the patterns of grani > 126 interaction patterns, by what the person is doing, with explanations, who implements them and test references where available (111 of them have tests). Page: https://grani.arseni.work/patterns One chapter alone: - https://grani.arseni.work/patterns/opening.md - https://grani.arseni.work/patterns/closing.md - https://grani.arseni.work/patterns/filling-in.md - https://grani.arseni.work/patterns/finding.md - https://grani.arseni.work/patterns/waiting.md - https://grani.arseni.work/patterns/working-the-list.md ### Focus and navigation Where keyboard focus starts, how it moves, and where it returns. Page: https://grani.arseni.work/patterns/opening #### Mark today in the app’s time zone The calendar marks today in the app’s time zone, or in the browser’s time zone if the app has not set one. On a page rendered by a server, the marker appears only after the calendar runs in the browser. A screen reader identifies it as the current date. Why: Near midnight, the server’s date may differ from the date in the calendar’s time zone. Waiting for the browser avoids marking the wrong day as today, even briefly. Held by the library by itself. Where: [Calendar](https://grani.arseni.work/components/calendar). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/opening#readers-today #### Open a panel on the side where it fits A field near the top of the window opens its calendar under it; a field near the bottom opens it above, so the calendar stays inside the window and the page needs no scrolling. The panel is never taller than the room it has, scrolling inside itself when the room is short, and never covers its field. Why: You pick a day at the end of a long form without the calendar running off the screen, and the field you are filling stays in sight. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker), [Select](https://grani.arseni.work/components/select). Tests: 6, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/opening#opens-where-fits #### Know when a link opens a new tab Before opening a link, you can tell whether it will use a new tab: an arrow follows the text, and a screen reader announces “opens in a new tab”. Links to another site use this behavior by default. Mail and phone links can open another app, so they do not carry the new-tab notice. Why: You know that the original page will remain open and that you can return to it by switching tabs. Held by the library by itself. Where: [Link](https://grani.arseni.work/components/link), [Button](https://grani.arseni.work/components/button), [List item](https://grani.arseni.work/components/list-item). Tests: 7, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/opening#new-tab-said #### Open with keyboard focus where the task begins Open a form and start typing in its first field, or open a list and start choosing with the arrow keys. Searchable lists start in their search field, and a calendar starts on the selected day. In a confirmation dialog, focus starts on Cancel, so pressing Enter by habit does not approve the action. Why: You can begin the task without first clicking a field or pressing Tab to find it. Confirmation dialogs give you time to read the question before approving it. Held by the library by itself. Where: [Filter list](https://grani.arseni.work/components/filter-list), [Popover](https://grani.arseni.work/components/popover), [Confirm](https://grani.arseni.work/components/confirm), [Table columns](https://grani.arseni.work/components/table-columns), [Filter](https://grani.arseni.work/components/filter), [Select](https://grani.arseni.work/components/select), [Date picker](https://grani.arseni.work/components/date-picker), [Calendar](https://grani.arseni.work/components/calendar), [Drawer](https://grani.arseni.work/components/drawer), [Modal](https://grani.arseni.work/components/modal), [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 16, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/opening#focus-start #### Continue from where you opened the panel After closing a dialog or side panel, continue from the button or row that opened it. Closing a popup with Escape or by choosing an option also returns focus to its opener, provided it is still on the page. Clicking outside a popup leaves focus where you clicked. Why: You can open and close one record after another from the keyboard without looking for your place again each time. Held by the library by itself. Where: [Drawer](https://grani.arseni.work/components/drawer), [App shell](https://grani.arseni.work/components/app-shell), [Filter](https://grani.arseni.work/components/filter), [Table columns](https://grani.arseni.work/components/table-columns), [Date range](https://grani.arseni.work/components/date-range), [Select](https://grani.arseni.work/components/select), [Date picker](https://grani.arseni.work/components/date-picker), [Popover](https://grani.arseni.work/components/popover), [Modal](https://grani.arseni.work/components/modal), [Menu](https://grani.arseni.work/components/menu), [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 18, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/opening#focus-back #### Pass a group with one press of Tab Use Tab to reach a group of options, then the arrow keys to move within it. The next Tab leaves the group. This works for tabs, radio options, scale values, filter options and calendar days, so you do not have to Tab through each option separately. Separate controls, such as search and Reset buttons, have their own Tab stops. Why: You can get past a group of twelve options without pressing Tab twelve times, while still reaching every option with the arrow keys. Held by the library by itself. Where: [Tabs](https://grani.arseni.work/components/tabs), [Filter list](https://grani.arseni.work/components/filter-list), [Calendar](https://grani.arseni.work/components/calendar), [Radio group](https://grani.arseni.work/components/radio-group), [Table columns](https://grani.arseni.work/components/table-columns), [Filter](https://grani.arseni.work/components/filter), [Scale input](https://grani.arseni.work/components/scale-input). Tests: 10, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/opening#one-stop ### Closing panels Dismiss nested panels in order, the top one first, and leave the form behind them as it was. Page: https://grani.arseni.work/patterns/closing #### Keep the current period until both days are picked Your current period stays in effect until you select both ends of a new range. If you close the panel before selecting both dates, the unfinished range is discarded, and the panel next opens on its list of periods. If the app sets another period while you are selecting, the unfinished range is discarded too. Why: You can explore dates and cancel without changing the records shown by the current filter. Held by the library by itself. Where: [Date range](https://grani.arseni.work/components/date-range). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/closing#half-pick-dropped #### Close only the top layer with Escape Press Escape to step back from the last thing you opened. A list or calendar closes while the form behind it stays open. In a drawer with nested views, Escape goes back one level before closing the drawer. A search containing text uses the first Escape to clear it; a calendar’s month view uses it to return to the days. Why: You can dismiss a temporary choice without accidentally closing the form you are still filling in. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker), [Select](https://grani.arseni.work/components/select), [Time picker](https://grani.arseni.work/components/time-picker), [Drawer](https://grani.arseni.work/components/drawer), [Tooltip](https://grani.arseni.work/components/tooltip), [Popover](https://grani.arseni.work/components/popover), [Crud drawer](https://grani.arseni.work/components/crud-drawer), [Modal](https://grani.arseni.work/components/modal). Tests: 11, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/closing#escape-top #### Close a popup without closing the form behind it If a select’s list or a calendar is open inside a window or drawer, a click outside it closes only that list or calendar, and the form stays open. In a window this holds even for a click on the backdrop; the next click there closes the window. Why: Clicking away is the usual way to dismiss a list you opened by mistake, and it should not cost you the form you were filling in. Held by the library by itself. Where: [Select](https://grani.arseni.work/components/select), [Date picker](https://grani.arseni.work/components/date-picker), [Crud drawer](https://grani.arseni.work/components/crud-drawer), [Modal](https://grani.arseni.work/components/modal). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/closing#press-top #### See one window at a time If a dialog opens another dialog, the first one closes and the new one takes its place. If an edit dialog asks a question (a confirmation), the edit dialog is hidden until you answer, then returns as you left it, with focus on the button that asked. A side drawer remains visible beneath a dialog. Why: You can tell which question needs an answer, and the keyboard cannot move into a hidden dialog by mistake. Held by the library by itself. Where: [Modal](https://grani.arseni.work/components/modal), [Confirm](https://grani.arseni.work/components/confirm). Tests: 9, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/closing#one-window #### Close an open picker when its field is disabled If a select or date field becomes disabled while its list or calendar is open, the popup closes. Focus returns to the field, so you keep your place in the form even though that field cannot currently accept a choice. Why: An open list should not offer choices the field no longer accepts, and with focus on the field you do not have to find your place again. Held by the library by itself. Where: [Select](https://grani.arseni.work/components/select), [Date picker](https://grani.arseni.work/components/date-picker). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/closing#off-closes ### Forms and input Enter values, correct validation errors and submit a form. Page: https://grani.arseni.work/patterns/filling-in #### Get your text back when adding fails While an entry is being added, the field shows a spinner. You can keep typing, but pressing Enter again sends nothing. If adding fails, your text returns with a message such as “Could not add Meat. Press Enter to try again.” Why: A failed request does not cost you the text you typed; one Enter tries again. Held by the library by itself. Where: [List field](https://grani.arseni.work/components/list-field). Tests: 6, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#text-back #### Know why an action is unavailable A button that cannot be pressed yet says what it waits for: “Add the client’s email first”. It keeps its place in the Tab order and shows the reason when you point at it, reach it with Tab, press it or tap it, and a screen reader reads the reason with it. A press does nothing until the reason is gone. Why: A grey Save with no word sends a person hunting through the form for what is missing, or to support; the reason turns a dead end into the next step. Held by the library by itself. Where: [Button](https://grani.arseni.work/components/button), [Icon button](https://grani.arseni.work/components/icon-button), [Copy button](https://grani.arseni.work/components/copy-button). Tests: 18, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#off-says-why #### Know what was refused and why If something cannot be added, a message names it and says why, and a screen reader announces it at once. A dropzone names up to three files for each reason and counts the rest, for example “a.png, b.png, c.png and 2 more: unsupported file type.”, a sentence per reason. A list field keeps the refused text in the field to be corrected, and adds the valid entries typed or pasted with it. Why: You know what to fix or leave out before you try again, and you correct a refused entry instead of typing it again. Held by the library by itself. Where: [Dropzone](https://grani.arseni.work/components/dropzone), [List field](https://grani.arseni.work/components/list-field). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#refused-by-name #### Submit the values shown in the form The form sends the values you can see and review. Give each control a `name` to include it in a native form submission or `FormData`. Unchecked boxes, off switches, an empty select and disabled controls send nothing. An empty text field, a date picker with no day and a time picker with no time send an empty value. Resetting the form restores the app’s current values, so the app must clear those values to empty the form. Why: The submitted values agree with the visible fields, and developers do not have to maintain a second set of hidden inputs themselves. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker), [Input](https://grani.arseni.work/components/input), [Time picker](https://grani.arseni.work/components/time-picker), [Textarea](https://grani.arseni.work/components/textarea), [Switch](https://grani.arseni.work/components/switch), [Select](https://grani.arseni.work/components/select), [Scale input](https://grani.arseni.work/components/scale-input), [Radio group](https://grani.arseni.work/components/radio-group), [Password field](https://grani.arseni.work/components/password-field), [Dropzone](https://grani.arseni.work/components/dropzone), [Code input](https://grani.arseni.work/components/code-input), [Checkbox](https://grani.arseni.work/components/checkbox), [Stepper](https://grani.arseni.work/components/stepper). Tests: 27, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#sends-like-native #### Finish a word in any script before it is sent Japanese, Chinese and Korean are typed through an input method: the reading first, then the word picked with Enter. Until the word is picked nothing is sent or chosen, and the Enter that picks it does not search, tick a row or add an entry. Why: A search for half a word, or an entry added halfway through typing it, is a wrong answer for anyone who writes these languages every day. Held by the library by itself. Where: [Table toolbar](https://grani.arseni.work/components/table-toolbar), [Input](https://grani.arseni.work/components/input), [Select](https://grani.arseni.work/components/select), [Filter list](https://grani.arseni.work/components/filter-list), [List field](https://grani.arseni.work/components/list-field). Tests: 10, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#word-as-composed #### Avoid adding the same entry twice If you add something already in the list, the list keeps one copy and says so, for example “a.pdf: already in the list.” A file is the same when its name, size and date match; a typed or pasted name when it matches a whole name in the list in any capitalization, repeats within one paste included. Why: Nobody gets a second copy by accident, and you see why nothing new was added instead of wondering or finding it twice later. Held by the library by itself. Where: [Dropzone](https://grani.arseni.work/components/dropzone), [List field](https://grani.arseni.work/components/list-field). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#no-twice #### Show the error where the hint was The hint below a field and its error share the same place: when the value has an error, the explanation replaces the hint, and when the error clears, the hint returns. A screen reader announces the error and identifies the field as invalid. Why: You find the correction where you were already reading the instructions, and the fields below do not move to make room for a second message. A longer error can still increase the field’s height. Held by the library by itself. Where: [Field](https://grani.arseni.work/components/field), [List item](https://grani.arseni.work/components/list-item). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#error-takes-the-hints-place #### Leave invalid date values empty instead of guessing If the app supplies an impossible date, such as 2026-13-40, the field shows its placeholder instead of converting it into another date. It has no clear button, and the form sends an empty value for it. Why: An invalid value never silently becomes a day nobody selected. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#unreadable-is-none #### Respect date limits without losing a value You can see which dates and times are available before choosing: values outside the allowed range stay visible but cannot be picked. A previously saved value outside the range is kept and marked invalid, so you can review and correct it. Calendar navigation respects the allowed range, but still lets you navigate back if the selected date is outside it. Why: A previously saved value is not silently erased or replaced when the range changes: you can see what needs correcting and navigate back to an available date or time. Held by the library by itself. Where: [Time picker](https://grani.arseni.work/components/time-picker), [Calendar](https://grani.arseni.work/components/calendar), [Date picker](https://grani.arseni.work/components/date-picker). Tests: 10, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#limit-shown #### Keep the end of a period after its start Two date fields, from and to: the days before the start cannot be picked as the end. If the start is moved past an end already chosen, the end keeps its day and shows an error instead of changing by itself. Why: A period that ends before it starts never reaches the report, and a day you chose is never changed behind your back. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#end-after-start #### See a date range before you pick its end After the first day of a range, the calendar draws the range to the day under the pointer or the keyboard focus and says how many days it covers, such as “7 days”. Nothing is applied until you pick the last day. Why: A week that came out eight days long, or a period one day short, is caught while you are still choosing it, not after the report has changed. Held by the library by itself. Where: [Calendar](https://grani.arseni.work/components/calendar), [Date range](https://grani.arseni.work/components/date-range). Tests: 6, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#span-seen-first #### See which days are the weekend The calendar names the days of rest in bold in its header, as the app’s language and region count them: Saturday and Sunday in most places, Friday and Saturday in Israel or Saudi Arabia. A due date put on a day off is seen by its column before it is picked. Why: A deadline or a delivery set on a day when nobody works is caught while you choose it, not on the day itself. Held by the library by itself. Where: [Calendar](https://grani.arseni.work/components/calendar), [Date picker](https://grani.arseni.work/components/date-picker), [Date range](https://grani.arseni.work/components/date-range). Tests: 7, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#weekend-shown #### See the day of the week beside a date A date field shows the day of the week with the date, “Thu, Sep 24”, the year added when it is not this one, and a column of dates can carry it under each date. A due date put on a Saturday, or a day picked one off, is seen at a glance. Why: People plan by days of the week: a meeting on the wrong Thursday or a deadline on a Sunday is caught before it is kept. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker), `UiDateCell`. Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#weekday-said #### Save the day you picked, in any time zone A date field holds and sends the day itself, `2026-10-24`, not a moment at midnight. A server or a colleague in another time zone reads the same 24th, so a date of birth or a due date never slips to the day before. Why: A day kept as midnight in Moscow is already the 23rd on a server that runs in UTC: a birthday or a deadline moves by a day, and nobody notices until it matters. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker), [Calendar](https://grani.arseni.work/components/calendar), [Date range](https://grani.arseni.work/components/date-range), `UiDateCell`. Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#day-stays-day #### Make small changes without losing decimal precision The arrows adjust a price or measurement at the precision you entered. With a step of 0.1, 10.44 changes to 10.45 or 10.43, because its last decimal place is finer than the step. Results are rounded to that precision, so 0.2 plus 0.1 becomes 0.3 rather than a long string of digits. Why: A small adjustment preserves the decimal places you entered without adding rounding digits to the result. Held by the library by itself. Where: [Input](https://grani.arseni.work/components/input). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#cent-stays-cent #### Enter numbers in the app’s local format You type or paste a number the way your language writes it: “1 234,50” in Russian and “1,234.50” in English are both 1234.50. If the field cannot interpret a value unambiguously, it keeps the text as written for you to correct, and marks it invalid when you leave the field. Why: You can enter numbers in the format you are used to, without removing separators by hand. An ambiguous number waits for your correction instead of being saved as the wrong amount. Held by the library by itself. Where: [Input](https://grani.arseni.work/components/input), [Stepper](https://grani.arseni.work/components/stepper). Tests: 11, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#number-as-written #### Type a date or a time as your language writes it Type `12.03.1987` in Russian or `03/12/1987` in American English, or the digits alone, and the date field reads the parts in the order your language writes them. Type `14:30`, `1430` or `2:30p`, and the time field reads it the same way. As you type, the calendar or the column jumps to what was read, and Enter takes it. A day or a time that does not exist is not taken, and never guessed. Why: A date from a passport or a time from an invoice goes in at typing speed, instead of twelve years of paging back or scrolling through the hours, and you see how the field read it before it is kept. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker), [Time picker](https://grani.arseni.work/components/time-picker). Tests: 21, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#date-as-written #### Let the app check a code as soon as it is complete When you type, paste or autofill the last character, the field tells the app that the code is complete, so the app can check it without a separate button. A code the app puts in the field itself, such as a restored draft, is not reported as completed, and input that leaves the code unchanged is not reported again. Why: You can finish entering the code and the app can check it immediately, with no separate button to press. A restored draft is not sent for checking automatically. Held by the library by itself. Where: [Code input](https://grani.arseni.work/components/code-input). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#complete-once #### Go straight to the field that needs fixing If a form cannot be submitted because a field has an error, focus moves to the first field you can correct, and the page scrolls enough to show it. UiModal with `form` and UiCrudDrawer do this by themselves when the app marks the field as the submit is checked, and again when `submitting` falls on an answer that marked one, unless you are typing in another field. Any error in a custom form is focused by the app calling `focusInvalid`. Why: You can correct the problem immediately, even in a long form where the error was off screen, instead of pressing Save again or searching for the highlighted field. Held by the library by itself. Where: [Modal](https://grani.arseni.work/components/modal), [Checkbox](https://grani.arseni.work/components/checkbox), [Time picker](https://grani.arseni.work/components/time-picker), [Textarea](https://grani.arseni.work/components/textarea), [Switch](https://grani.arseni.work/components/switch), [Select](https://grani.arseni.work/components/select), [Scale input](https://grani.arseni.work/components/scale-input), [Radio group](https://grani.arseni.work/components/radio-group), [List field](https://grani.arseni.work/components/list-field), [Input](https://grani.arseni.work/components/input), [Field](https://grani.arseni.work/components/field), [Dropzone](https://grani.arseni.work/components/dropzone), [Code input](https://grani.arseni.work/components/code-input), [Stepper](https://grani.arseni.work/components/stepper), [List item](https://grani.arseni.work/components/list-item), [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 20, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#focus-invalid #### Name states in words, not color alone You can identify a status without its color: a badge says “Paid” or “Overdue”, a scale shows its numbers, and a screen reader announces whether a change is better or worse. Color reinforces the meaning. A badge without text triggers a development warning. Why: The state stays readable for people who do not tell colors apart, in grayscale, and with a screen reader. Held by the library by itself. Where: [Badge](https://grani.arseni.work/components/badge), [Delta](https://grani.arseni.work/components/delta), [Scale input](https://grani.arseni.work/components/scale-input), [Link](https://grani.arseni.work/components/link), [List item](https://grani.arseni.work/components/list-item). Tests: 8, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#level-not-by-colour #### Know what fits when a list has a limit When a list allows only so many entries, what fits is added and a message says what was left out, for example “c.pdf: up to 2 files.” A list field that is full replaces its field with a message that explains the limit, and if the field had focus, focus moves to that message. Why: You can tell why adding stopped and how much of a pasted list or a drop was accepted. Held by the library by itself. Where: [List field](https://grani.arseni.work/components/list-field), [Dropzone](https://grani.arseni.work/components/dropzone). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#nearly-full #### Toggle or pick by clicking the words A click on the text of a checkbox, a switch or a radio works as a click on its box does. In a setting row, a click anywhere on the row, its title and description included, toggles its switch. Options shown as cards are picked by a click anywhere on the card: on its words, its image or its details, such as a price. Why: The words give a much larger target than the small box, switch or radio. Held by the library by itself. Where: [Switch](https://grani.arseni.work/components/switch), [List item](https://grani.arseni.work/components/list-item), [Radio group](https://grani.arseni.work/components/radio-group), [Checkbox](https://grani.arseni.work/components/checkbox). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#label-is-target #### Drop files anywhere on the upload card You can drop files anywhere on the upload card, including over files already listed. While the dropzone is on the page, a file dropped outside any drop target does not open in the browser tab. Other file inputs and drop targets still handle their own drops. Why: A drop that misses by a few pixels does not replace the page and the form you were filling in. Held by the library by itself. Where: [Dropzone](https://grani.arseni.work/components/dropzone). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#whole-zone-is-target #### Clear a field and enter its replacement immediately Press a field’s × and enter the replacement immediately, without clicking back into the field: clearing moves keyboard focus to the field, whether you use the mouse or the keyboard. Why: The × disappears once the field is empty; without this, keyboard focus would be lost with it, and you would have to find the field again. Held by the library by itself. Where: [Time picker](https://grani.arseni.work/components/time-picker), [Select](https://grani.arseni.work/components/select), [List field](https://grani.arseni.work/components/list-field), [Input](https://grani.arseni.work/components/input), [Date picker](https://grani.arseni.work/components/date-picker). Tests: 6, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#cleared-in-place #### See the password you generate Generate a password to see it in plain text and copy it before saving. Clearing the field turns password hiding back on, so the next password you type is hidden. Why: You never save a password you have not seen and could not type again on another device. Held by the library by itself. Where: [Password field](https://grani.arseni.work/components/password-field). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#made-is-seen #### Generate a password instead of inventing one Press Generate to get a random password, 16 characters long by default, with an uppercase letter, a lowercase letter, a digit and a symbol. The app must still check any other requirements of its password policy. Why: You get a ready-made password without inventing one or assembling the required character types yourself. Held by the library by itself. Where: [Password field](https://grani.arseni.work/components/password-field). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#strong-on-offer #### Show a password without leaving the field Click the password visibility button to check what you typed, then continue editing immediately. Showing or hiding the characters keeps focus in the field and preserves the text cursor’s position. Why: You can check what you typed and correct it at once, without clicking back into the field and finding your place. Held by the library by itself. Where: [Input](https://grani.arseni.work/components/input). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#eye-keeps-field #### Take back a scale answer Click the selected value again, or press Delete or Backspace, to clear the answer to `null`. Space and Enter select an answer and never clear it. With `clearable` turned off, an answer cannot be cleared once given. Why: You can withdraw an answer given by mistake, or one that no longer applies, instead of being forced to leave some value. Held by the library by itself. Where: [Scale input](https://grani.arseni.work/components/scale-input). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#mark-taken-back #### Know how to add files from a folder If you drop a folder, a message tells you how to continue: “photos: folders are not accepted; drop the files inside.” Files dropped alongside the folder are processed separately and are added if they meet the file requirements. Why: You get a next step you can take, instead of a refusal with no reason or an empty file in the list. Held by the library by itself. Where: [Dropzone](https://grani.arseni.work/components/dropzone). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#folder-refused #### Type, paste or autofill a code Enter a code whichever way you have it: type it, paste it, or accept the browser’s autofill from a message where available. The cells share one input, so a complete code fills them at once. Pasted text keeps only the allowed characters and is cut to the code’s length. Why: You use the code you already have without copying it one character at a time. Held by the library by itself. Where: [Code input](https://grani.arseni.work/components/code-input). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#code-any-way #### Show where the next code character goes As you type a code, the cell for the next character is highlighted; on a full code, the last cell is. Backspace removes the last character, and the highlight moves back. Why: You see where the next character goes and can enter the whole code without clicking between cells. Held by the library by itself. Where: [Code input](https://grani.arseni.work/components/code-input). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#code-moves-on #### Keep only the characters a code allows Whatever you type or paste, the field keeps the allowed characters, removes the rest and cuts the result to the code’s length. A value supplied by the app, such as a restored draft, follows the same rules. Why: A stray space or letter never remains in a numeric code. The app still needs to check whether the code itself is correct. Held by the library by itself. Where: [Code input](https://grani.arseni.work/components/code-input). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#code-refuses-wrong-kind #### Pick with Enter without sending the form In a select, a filter or a calendar inside a form, Enter chooses the highlighted option or day and does not submit the form. The form is submitted only when you choose to submit it. Why: Choosing a value from the keyboard does not send a half-filled form. Held by the library by itself. Where: [Select](https://grani.arseni.work/components/select), [List field](https://grani.arseni.work/components/list-field), [Filter list](https://grani.arseni.work/components/filter-list), [Filter](https://grani.arseni.work/components/filter), [Calendar](https://grani.arseni.work/components/calendar). Tests: 8, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#enter-picks #### Submit a form with Enter Enter in a single-line field submits a modal or drawer form, when submission is available. A quick second Enter, or one pressed while the app marks the save as running, does not submit again. The app validates and saves the submitted values. Why: You can submit a completed form without moving to Save, and repeated presses while it is busy do not start another submission. Held by the library by itself. Where: [Modal](https://grani.arseni.work/components/modal), [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#enter-saves #### Submit from a text box with Ctrl or Cmd+Enter Send a modal or drawer form from a multiline text field with Ctrl+Enter or Cmd+Enter. Enter on its own still inserts a line break. The shortcut activates the submit button, so it is unavailable while that button is disabled or loading. Why: You can write several lines and send them without reaching for the mouse. Held by the library by itself. Where: [Modal](https://grani.arseni.work/components/modal), [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#meta-enter-saves #### Change a number with the arrow keys ArrowUp increases a number and ArrowDown decreases it, without retyping and without moving the text cursor. Changes follow the configured step while preserving finer decimal precision when the value has it. The arrows stop at the minimum and maximum, but typed values still need validation. On a scale, the arrow keys change the answer, and Home and End reach the endpoints. Why: You can make small changes without the mouse and without typing the number again. Held by the library by itself. Where: [Input](https://grani.arseni.work/components/input), [Stepper](https://grani.arseni.work/components/stepper), [Scale input](https://grani.arseni.work/components/scale-input). Tests: 10, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#number-by-arrows #### Move by month or year from the keyboard Page Up and Page Down move the calendar by a month, and with Shift by a year, so a distant date is a few key presses away. The day number is preserved where possible: moving back from May 31 goes to April 30, then March 31. Why: A date months or years away is reached in a few key presses instead of one day at a time. Held by the library by itself. Where: [Calendar](https://grani.arseni.work/components/calendar). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#page-by-key #### Jump to a month from the heading Press the calendar’s month heading to show all twelve months, change the year with the header arrows, and choose a month, without paging through every month in between. Escape returns to the day view. Why: You can go directly to a month such as next September instead of pressing the next-month arrow repeatedly. Held by the library by itself. Where: [Calendar](https://grani.arseni.work/components/calendar). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#months-jump #### Remove selected tags with the keyboard You can remove selected tags without the mouse: Tab reaches each tag’s remove button, and Enter or Space activates it. In a closed multi-select, Backspace removes the last visible tag. After a removal, keyboard focus moves to the next tag, or back to the field when no tag remains. Why: You can correct a selection without switching to the mouse, and Backspace never removes a value you cannot see. Held by the library by itself. Where: [Select](https://grani.arseni.work/components/select), [Badge](https://grani.arseni.work/components/badge). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#tag-taken-back #### Pick a common date in one press Choose a common date without opening the calendar. Buttons below the field can set Today, Yesterday, Tomorrow or another date relative to today, and the field shows the date a press set. Why: When most entries fall on the same few days, you do not have to open the calendar for each one. Held by the library by itself. Where: [Date picker](https://grani.arseni.work/components/date-picker). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#common-days #### Pick range ends in either order Choose the two ends of a date range in either order. The earlier date becomes the start and the later date the end. Your existing filter stays in effect until you have chosen both. Why: You do not have to start over because you happened to press the later date first. Held by the library by itself. Where: [Date range](https://grani.arseni.work/components/date-range). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#either-order #### Paste a list to add several entries Paste a column of values, such as email addresses, to add several entries at once. Each line goes the way a typed entry goes: spaces at the ends removed, the app’s cleanup applied, such as one capitalization for tags, then its check. Accepted lines are added together; duplicates are identified instead of being added again. Why: You can reuse a list prepared elsewhere without entering each value on its own, and typed and pasted entries come out alike, so the list does not collect several spellings of one entry. Held by the library by itself. Where: [List field](https://grani.arseni.work/components/list-field). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#paste-many #### Keep keyboard focus where you are working You can delete several rows without finding the Delete button after each one: when a row is removed, keyboard focus moves to the same button in the row that takes its place, so Enter deletes the next one. When a message, field or panel disappears while you are using it, focus moves to a control that remains. Why: You can continue a sequence of actions from the keyboard without tabbing back into the list each time or switching to the mouse. Held by the library by itself. Where: [App shell](https://grani.arseni.work/components/app-shell), [Dropzone](https://grani.arseni.work/components/dropzone), [Reveal](https://grani.arseni.work/components/reveal), [Table](https://grani.arseni.work/components/table), [Copy button](https://grani.arseni.work/components/copy-button), [Filter list](https://grani.arseni.work/components/filter-list), [Toaster](https://grani.arseni.work/components/toaster), [List field](https://grani.arseni.work/components/list-field), [Input](https://grani.arseni.work/components/input). Tests: 18, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#focus-stays #### Open a field from its label Clicking a field’s label works as it does for a text field, where it puts the cursor in: it presses the control. A select opens its list and a dropzone its file dialog, so the label is as good a target as the field itself. Why: The label is a larger target right above the field. A click on it reaches the field instead of doing nothing. Held by the library by itself. Where: [Field](https://grani.arseni.work/components/field). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#label-opens #### Name each field once for screen readers A screen reader announces each field’s name once, followed by its hint or error. UiField connects those messages to the control they describe. Repeated text, such as a tooltip that matches an icon button’s name, is not announced twice. Why: You can understand what a field asks for and how to correct it without guessing from a placeholder or listening to the same label twice. Held by the library by itself. Where: [Field](https://grani.arseni.work/components/field), [Time picker](https://grani.arseni.work/components/time-picker), [Textarea](https://grani.arseni.work/components/textarea), [Switch](https://grani.arseni.work/components/switch), [Select](https://grani.arseni.work/components/select), [Scale input](https://grani.arseni.work/components/scale-input), [Radio group](https://grani.arseni.work/components/radio-group), [List field](https://grani.arseni.work/components/list-field), [Password field](https://grani.arseni.work/components/password-field), [Button group](https://grani.arseni.work/components/button-group), [Icon button](https://grani.arseni.work/components/icon-button), [Tooltip](https://grani.arseni.work/components/tooltip), [Stepper](https://grani.arseni.work/components/stepper), [List item](https://grani.arseni.work/components/list-item). Tests: 25, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#one-name-one-voice #### Announce required fields in words A required field shows an asterisk and is announced as required, so you can identify it visually and with a screen reader. For a group, such as radio options or a scale, the requirement is announced once with the group’s label. The app still checks that an answer has been given. Why: People who cannot see the asterisk still learn which answers they must give before they send the form. Held by the library by itself. Where: [Field](https://grani.arseni.work/components/field), [Scale input](https://grani.arseni.work/components/scale-input), [Radio group](https://grani.arseni.work/components/radio-group), [Input](https://grani.arseni.work/components/input), [Stepper](https://grani.arseni.work/components/stepper), [List item](https://grani.arseni.work/components/list-item). Tests: 8, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#required-in-words #### Describe calendar marks in words A screen reader announces each day’s full date and the meaning of its marks, such as “overdue” or “unavailable”, as well as which day is today and which days are outside the allowed range. The calendar’s colors and symbols are not the only way to learn a day’s state. Why: Someone who cannot see the dots, the strike-through or the colors still learns that a day is overdue, taken or out of range before choosing it. Held by the library by itself. Where: [Calendar](https://grani.arseni.work/components/calendar). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#state-in-words #### Announce scale steps with their meaning A screen reader announces both the position on a scale and what its endpoints mean. For example, a middle value is “7 of 10”, while the endpoints can be “1 of 10, easy” and “10 of 10, hard”. Why: You can choose an answer knowing which end means easy or hard, even when you cannot see the labels below the scale. Held by the library by itself. Where: [Scale input](https://grani.arseni.work/components/scale-input). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/filling-in#mark-says-its-word ### Search and selection Find options, filter rows and navigate long lists. Page: https://grani.arseni.work/patterns/finding #### Results match the current search In a select, a slow response to an older query cannot replace the results for newer text, and the option you chose keeps its name while the results change. In a table toolbar, a search value the app applies late cannot overwrite newer typing or undo a clear. Either way, an old response never changes what you are currently searching for. Why: You can keep searching without a slow response restoring text or results from a question you have already moved past. Held by the library by itself. Where: [Select](https://grani.arseni.work/components/select), [Table toolbar](https://grani.arseni.work/components/table-toolbar). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#late-dropped #### Start a new search on the first page When you type a new search, sort by another column or change a filter, the table asks for page one, so the new results are read from their start. The pager marks page one as the current page. Why: Staying on page 4 of a new search shows the middle of its results, or an empty page that reads as no results, while the first matches wait on page one. Held by the library by itself. Where: [Data table](https://grani.arseni.work/components/data-table), [Pagination](https://grani.arseni.work/components/pagination). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#search-from-page-one #### Give every empty list a way forward An empty area explains what happened: there are no records yet, nothing matches the current search or filters, or loading failed, and it never leaves you at a dead end. It offers the next step it can, such as Clear search, Reset filters, Retry or Show all, and beside it a step of the app, such as creating what you searched for or adding the first record. Why: You can decide what to do next instead of guessing whether to wait, change a filter or reload the page. Held by the library by itself. Where: [No data](https://grani.arseni.work/components/no-data), [Data table](https://grani.arseni.work/components/data-table), [List field](https://grani.arseni.work/components/list-field), [Chart card](https://grani.arseni.work/components/chart-card), [Table](https://grani.arseni.work/components/table), [Log](https://grani.arseni.work/components/log). Tests: 14, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#empty-next-step #### Count the last day of a period whole A period from the 1st to the 31st takes in everything on the 31st, up to midnight by the app’s clock. The filter hands the app the moments its period covers, from midnight of the first day to midnight after the last, so a query never stops where the last day begins or at the server’s midnight. Why: A report for October that quietly leaves out the invoices of the 31st, or moves its edges by the server’s time zone, gives a wrong total that nobody checks. Held by the library by itself. Where: [Date range](https://grani.arseni.work/components/date-range). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#last-day-whole #### Keep “Last month” and “Today” up to date A saved period keeps the meaning of its name: opening a Last month link in October shows September. Named periods are recalculated when the page opens and when the day changes. Date-picker presets such as Today update within a minute of midnight. A custom range keeps the exact dates you chose. Why: A saved view or a shared link keeps meaning what its name says, so you do not read an old month’s figures as the latest ones. Held by the library by itself. Where: [Date range](https://grani.arseni.work/components/date-range), [Date picker](https://grani.arseni.work/components/date-picker). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#named-period-rolls #### Keep a reset from restoring the old search After Reset filters, a saved view or Back changes the search, the field shows that new value immediately. Any earlier typing still waiting for the search delay is discarded, so it cannot reapply the old filter a moment later. Why: You can trust that a reset or saved view will stay in effect instead of changing again because of text entered before it. Held by the library by itself. Where: [Table toolbar](https://grani.arseni.work/components/table-toolbar). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#outside-wins #### Keep Reset in one place Reset stays in the footer of filter and column panels. It becomes available when there is something to reset, without appearing as a new row or moving the options you are selecting. Why: You can tick several boxes in a row without a click landing on a row that was pushed into its place. Held by the library by itself. Where: [Filter](https://grani.arseni.work/components/filter), [Table columns](https://grani.arseni.work/components/table-columns). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#reset-held #### Clear a search in one step Clear a search with × or Escape and start typing another term immediately. Focus stays in the field. Inside a panel, the first Escape clears nonempty text without closing the panel; another Escape can then close it. Why: You can try one term after another without selecting and deleting the old text, or reopening a panel that Escape closed. Held by the library by itself. Where: [Filter](https://grani.arseni.work/components/filter), [Table columns](https://grani.arseni.work/components/table-columns), [List field](https://grani.arseni.work/components/list-field), [Table toolbar](https://grani.arseni.work/components/table-toolbar), [Filter list](https://grani.arseni.work/components/filter-list), [Select](https://grani.arseni.work/components/select), [Input](https://grani.arseni.work/components/input). Tests: 13, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#search-clears #### Find what you chose at the top of a long filter From six options, a filter opens with the options you already chose at the top, in their own order. The order stays while the panel is open, so a tick never moves a row under the pointer. Why: In a long list you see and change your choice at once, instead of scrolling to find the ticks. Held by the library by itself. Where: [Filter](https://grani.arseni.work/components/filter), [Table columns](https://grani.arseni.work/components/table-columns), [Filter list](https://grani.arseni.work/components/filter-list). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#chosen-first #### Keep nearby buttons and fields in place Controls keep their width as their values change, so nearby controls stay in place. Filters, date fields, selects, steppers and period buttons reserve room for their widest content, and the segments of a switcher such as Day, Week, Month keep one width whichever is selected. A custom date range may still widen its button if it is wider than every named period. Why: When you make several choices in a row, the next button stays where you expect it, so a click meant for it does not land on another one. Held by the library by itself. Where: [Filter](https://grani.arseni.work/components/filter), [Date picker](https://grani.arseni.work/components/date-picker), [Radio group](https://grani.arseni.work/components/radio-group), [Stepper](https://grani.arseni.work/components/stepper), [Select](https://grani.arseni.work/components/select), [Date range](https://grani.arseni.work/components/date-range). Tests: 9, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#steady-width #### Keep the page arrows under the pointer You can click Next repeatedly without moving the mouse. When there are more pages than fit, the number of page slots stays constant, and each slot is as wide as the largest page number. The compact label, such as “3 / 20”, also keeps a steady width. Why: Without it, a quick second click can land on a page number that moved into the arrow’s place and open a page you did not ask for. Held by the library by itself. Where: [Pagination](https://grani.arseni.work/components/pagination). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#pager-holds-still #### Keep at least one column visible The column menu keeps at least one column visible. Once only one remains, its checkbox is disabled and marked “Last one”. If an older saved preference would hide every column, the first column is shown instead. Why: You can still identify the records in the table instead of seeing empty rows that look like a loading failure. Held by the library by itself. Where: [Table columns](https://grani.arseni.work/components/table-columns). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#last-column-stays #### See that a row goes on past its edge When columns or tabs do not fit, the side with more past it is marked, and with a mouse an arrow there pages to the rest: a table shades the edge where its columns slide under the row actions, tabs fade theirs. A wide table scrolls from the keyboard too, and keeps the actions of its rows in view at the end. Why: A table cut at the screen’s edge reads as complete, and the column you need, or the actions of a row, stay out of sight. Held by the library by itself. Where: [Table](https://grani.arseni.work/components/table), [Tabs](https://grani.arseni.work/components/tabs). Tests: 12, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#edge-says-more #### See how the rows are sorted Press a sortable column heading to sort by it, press again for the opposite direction, and a third time to clear the sort. An arrow shows the current direction, and a screen reader can announce it. The app applies the requested order to the rows. Why: You know which column orders the rows, and which way, before you read them, instead of comparing rows to guess. Held by the library by itself. Where: [Table](https://grani.arseni.work/components/table). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#sort-says #### Compare numbers in aligned columns You can compare amounts or counts by scanning down the column: the numbers are right-aligned in equal-width digits, so matching decimal places line up when the values share the same format and precision. Why: You can spot the largest amount or an odd one out by scanning the column, without reading each number. Held by the library by itself. Where: [Table](https://grani.arseni.work/components/table), [Data table](https://grani.arseni.work/components/data-table). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#digits-line #### Read old and new values in full See exactly what changed in a record, with the old and new values shown together. Long values wrap onto more lines so the differing characters remain visible. A single change appears on one line; several changes use a table. Why: You can review the change without opening an older version, even when two long values differ only at the end. Held by the library by itself. Where: [Log](https://grani.arseni.work/components/log). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#was-and-became #### See when each event happened Read a record’s history by day, with each event’s time shown beside it. When events use Date values, headings identify Today, Yesterday or a date, including the year for older events. Hover over a time to see the complete date and time in the app’s time zone. Why: You can distinguish recent activity from older events and find out exactly when a change happened. Held by the library by itself. Where: [Log](https://grani.arseni.work/components/log). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#exact-time #### Read the full text when a label is shortened When a name is too long for its place, it is cut to one line with an ellipsis, and hovering over it or tapping it shows the full text in a tooltip. The tooltip appears only while the text is really cut, and a screen reader always reads the full text. A number that must fit, such as the total in the middle of a donut chart, is shortened instead, and its full value stands in the legend and in the table a screen reader reads. Why: You can distinguish names that begin alike without guessing what is hidden at the end. Held by the library by itself. Where: [Truncate](https://grani.arseni.work/components/truncate), [Select](https://grani.arseni.work/components/select), [Table](https://grani.arseni.work/components/table), [Bar chart](https://grani.arseni.work/components/bar-chart), [Donut chart](https://grani.arseni.work/components/donut-chart), [Copy button](https://grani.arseni.work/components/copy-button), [Badge](https://grani.arseni.work/components/badge). Tests: 11, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#whole-text #### Notice when there are more options below A long list shows five options and part of the sixth, so you can see there is more to scroll to. You scroll inside the list to reach the rest. The list is never taller than the available screen space. Why: The partially visible row shows that the list continues, so you are less likely to miss an option below the edge. Held by the library by itself. Where: [Filter list](https://grani.arseni.work/components/filter-list), [Table columns](https://grani.arseni.work/components/table-columns), [Date range](https://grani.arseni.work/components/date-range), [Select](https://grani.arseni.work/components/select). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#five-rows #### Search once typing pauses A search is sent after a 250 ms pause in typing, not on every letter. In the table toolbar, Enter sends it immediately. Text still being composed with an input method, such as Japanese input, is not sent until composition finishes. When the response arrives, a screen reader announces how many results were found. Why: A word typed quickly produces one request instead of a request and a redraw for every letter. Held by the library by itself. Where: [Table toolbar](https://grani.arseni.work/components/table-toolbar), [Data table](https://grani.arseni.work/components/data-table), [Select](https://grani.arseni.work/components/select). Tests: 9, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#typing-asks-once #### Jump to an option by letter Find a known option by typing its first letter while the list has focus: G can take you to Germany. Repeat the letter to move to the next matching option. In a list with a search field, typing searches instead. Why: When you already know the name, you do not have to press the Down arrow once for every option above it. Held by the library by itself. Where: [Menu](https://grani.arseni.work/components/menu), [Filter](https://grani.arseni.work/components/filter), [Filter list](https://grani.arseni.work/components/filter-list), [Table columns](https://grani.arseni.work/components/table-columns), [Select](https://grani.arseni.work/components/select). Tests: 9, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#letter-jumps #### Keep one option and clear the rest in one press The highlighted option of a filter offers Only, which keeps that option chosen and clears the others. From the keyboard, Alt+Enter does the same. Why: Narrowing a list to one value takes one press instead of unticking every other box. Held by the library by itself. Where: [Filter](https://grani.arseni.work/components/filter), [Table columns](https://grani.arseni.work/components/table-columns), [Filter list](https://grani.arseni.work/components/filter-list). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/finding#only-this ### Loading and feedback Show progress, explain failures and confirm actions when needed. Page: https://grani.arseni.work/patterns/waiting #### See whether an action worked When an action ends, you can tell how it went: the content changes, a short message confirms it, or an error says what went wrong and what to do next. Messages and errors are announced by a screen reader too. Why: You do not have to repeat an action, or check somewhere else, to find out whether it went through. Held by the library by itself. Where: [Toaster](https://grani.arseni.work/components/toaster), [Table](https://grani.arseni.work/components/table), [Log](https://grani.arseni.work/components/log), [List field](https://grani.arseni.work/components/list-field), [Password field](https://grani.arseni.work/components/password-field), [Dropzone](https://grani.arseni.work/components/dropzone), [Copy button](https://grani.arseni.work/components/copy-button), [Confirm](https://grani.arseni.work/components/confirm). Tests: 13, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#answered #### Ignore extra presses while a request runs After you press Send, a loading indicator shows that the request is running and further presses are ignored until it finishes. This prevents another click from starting the same action through that control. The app supplies the loading state unless the component manages the request itself. Why: You do not need to press again to check whether the first click registered, and an impatient second press does not start an extra request through the busy control. Held by the library by itself. Where: [Button](https://grani.arseni.work/components/button), [Icon button](https://grani.arseni.work/components/icon-button), [Pagination](https://grani.arseni.work/components/pagination), [Table](https://grani.arseni.work/components/table), [Log](https://grani.arseni.work/components/log), [List field](https://grani.arseni.work/components/list-field), [Dropzone](https://grani.arseni.work/components/dropzone), [Confirm](https://grani.arseni.work/components/confirm), [Menu](https://grani.arseni.work/components/menu), [Toaster](https://grani.arseni.work/components/toaster), [List item](https://grani.arseni.work/components/list-item), [Badge](https://grani.arseni.work/components/badge). Tests: 24, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#one-press #### Confirm only what cannot be undone Ask for confirmation only before an action that cannot be undone, and name the action on its button. A change the app can reverse happens immediately, with Undo offered for a limited time in a notification. The app handles the reversal; the notification provides the action that triggers it. Why: A question asked rarely gets read, so the one that matters is noticed. A reversible change is corrected with Undo instead of a question before every routine action. Held by the library by itself. Where: [Toaster](https://grani.arseni.work/components/toaster), [Confirm](https://grani.arseni.work/components/confirm). Tests: 9, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#ask-what-stays #### See the value the app actually accepted A field always shows the value the app holds, so you can tell whether an edit took effect. If the app rejects a change, the field returns to that value: a switch cannot stay on while its setting is still off. A form reset also restores the app’s current value, which is not necessarily the value saved on the server. Why: You see at once that a change did not take effect, instead of finding out later that the screen and the app disagree. Held by the library by itself. Where: [Textarea](https://grani.arseni.work/components/textarea), [Switch](https://grani.arseni.work/components/switch), [Checkbox](https://grani.arseni.work/components/checkbox), [Radio group](https://grani.arseni.work/components/radio-group), [Stepper](https://grani.arseni.work/components/stepper), [Time picker](https://grani.arseni.work/components/time-picker), [Select](https://grani.arseni.work/components/select), [Scale input](https://grani.arseni.work/components/scale-input), [List field](https://grani.arseni.work/components/list-field), [Password field](https://grani.arseni.work/components/password-field), [Input](https://grani.arseni.work/components/input), [Dropzone](https://grani.arseni.work/components/dropzone), [Code input](https://grani.arseni.work/components/code-input). Tests: 14, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#refused-goes-back #### Keep the chart when a refresh fails If a chart refresh fails, the previous chart stays on screen, and “Not updated” with Retry makes clear that new data did not arrive. A table behaves differently: a failed load replaces its rows with the error and Retry. Why: The figures you were reading stay available, with a clear sign that they are not current. Held by the library by itself. Where: [Chart card](https://grani.arseni.work/components/chart-card). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#kept-on-fail #### See upload progress and when it ends While files upload, you can see how far the upload has gone and when it is done. The file list cannot be changed during the upload. When the upload ends at 100%, each file gets a check mark and a screen reader announces the result, such as “2 files uploaded”. If it fails, the files left behind say why and offer Retry. The app supplies the progress and any failure; the dropzone shows them. Why: You can tell that the upload has started, which files are still on their way and when you can move on, instead of guessing from a single spinner. Held by the library by itself. Where: [Dropzone](https://grani.arseni.work/components/dropzone), [Progress](https://grani.arseni.work/components/progress). Tests: 8, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#upload-shown #### See where the app is working Progress appears where you expect the result. A busy button shows a spinner. A first load shows placeholders shaped like the coming content. A refresh keeps the existing content visible and dimmed, announces “Updating…”, and in a card adds one spinner over the content. A page whose layout is not yet known may show a single spinner in its center. Why: You can distinguish loading from an empty result or an ignored click, without pressing again to find out. Held by the library by itself. Where: [Spinner](https://grani.arseni.work/components/spinner), [Progress](https://grani.arseni.work/components/progress), [Card](https://grani.arseni.work/components/card), [Filter list](https://grani.arseni.work/components/filter-list), [Filter](https://grani.arseni.work/components/filter), [Badge](https://grani.arseni.work/components/badge), [Skeleton](https://grani.arseni.work/components/skeleton). Tests: 12, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#visible-work #### Keep nearby content in place while loading You can keep reading, or reach for a button, while nearby content loads. Placeholders reserve space for the expected content, media keeps its space before it arrives, and a refresh keeps the existing content in place. The final result can still shift the layout once if its size differs from the reserved space. Why: A button that shifts under the pointer is easy to miss, and a page that keeps changing shape makes you look for your reading position again. Held by the library by itself. Where: [App shell](https://grani.arseni.work/components/app-shell), [Button](https://grani.arseni.work/components/button), [Aspect ratio](https://grani.arseni.work/components/aspect-ratio), [Card](https://grani.arseni.work/components/card), [Skeleton](https://grani.arseni.work/components/skeleton), [Table](https://grani.arseni.work/components/table), [Avatar](https://grani.arseni.work/components/avatar), [Chart card](https://grani.arseni.work/components/chart-card), [Data table](https://grani.arseni.work/components/data-table), [Select](https://grani.arseni.work/components/select), [Log](https://grani.arseni.work/components/log), [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 21, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#no-jolt #### Search while the table stays in place You can keep typing while the table loads your search. Placeholder rows immediately replace the previous results, preserving their space and at least the height of an empty or error message. Sorting or paging within the same search keeps the existing rows visible and dimmed. Keyboard focus and your text stay in the search field throughout. Why: The table does not collapse with every letter, and old results are not mistaken for the answer to the new query. Its height may change once, when the new result arrives. Held by the library by itself. Where: [Data table](https://grani.arseni.work/components/data-table), [Table](https://grani.arseni.work/components/table). Tests: 8, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#still-list #### Keep reading as older events load Older events are appended below the ones already shown, so loading more history does not send you back to the top. If “Load older events” had keyboard focus and disappears because no older events remain, focus moves to the first new event, and a screen reader announces how many arrived. Why: You can continue from the newly loaded events instead of finding where you left off after the loading button disappears. Held by the library by itself. Where: [Log](https://grani.arseni.work/components/log). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#keep-place #### Keep counts short and in place A count stays short: above the configured maximum, it is shortened to a value such as 99+, so it never grows past that. A value that is not a number is hidden, and a negative one counts as 0. An attention indicator disappears at zero; a total beside a label can still show 0. Why: You can tell what needs attention without oversized counts, meaningless “NaN” values or a notification marker showing zero. Held by the library by itself. Where: [Indicator](https://grani.arseni.work/components/indicator), [Count](https://grani.arseni.work/components/count), [Tabs](https://grani.arseni.work/components/tabs). Tests: 12, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#compact-counts #### Keep turning pages from the keyboard You can keep paging from the keyboard without finding Next again after every load: the arrow you pressed keeps keyboard focus while the page loads. When that arrow reaches the end and becomes disabled, focus moves to the current page number or the compact page label. In a calendar, a month arrow that reaches its limit passes focus to the month heading, and a period’s arrow to the period button. Why: You can read a long list, or step through months, without returning to the mouse after every step. Held by the library by itself. Where: [Pagination](https://grani.arseni.work/components/pagination), [Calendar](https://grani.arseni.work/components/calendar), [Date range](https://grani.arseni.work/components/date-range). Tests: 6, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#pager-keeps-focus #### Announce a new password without reading it When a generated password is accepted by the app, a screen reader confirms “New password generated” without reading the password itself. Generate another one and the confirmation is announced again. Why: You get confirmation that generation worked without the password being read out where others can hear it. Held by the library by itself. Where: [Password field](https://grani.arseni.work/components/password-field). Tests: 1, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#made-is-not-spoken #### Reduce motion without hiding loading With the system’s reduced-motion setting enabled, sections open without sliding and attention indicators stop pulsing. Loading indicators keep moving, more slowly: spinners still turn and placeholders still shimmer. Why: Decorative movement is removed, but you can still see that loading is in progress. Held by the library by itself. Where: [Reveal](https://grani.arseni.work/components/reveal), [Spinner](https://grani.arseni.work/components/spinner), [Indicator](https://grani.arseni.work/components/indicator), [Progress](https://grani.arseni.work/components/progress), [Skeleton](https://grani.arseni.work/components/skeleton). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/waiting#calm-motion ### Working with records Select rows, apply actions and move between records. Page: https://grani.arseni.work/patterns/working-the-list #### Land on a page with records after a delete When you delete the last record on the last page and other pages remain, the table requests the previous page, so you continue with the remaining records instead of an empty page. If the current page no longer exists for another reason, the table waits for loading to finish and then requests the new last page. The app loads the page the table requests. Why: You can go on through the remaining records without meeting an empty page that looks like an empty list. Held by the library by itself. Where: [Data table](https://grani.arseni.work/components/data-table), [Pagination](https://grani.arseni.work/components/pagination). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#last-page-lands #### Show missing data as a gap A missing value appears as a gap in a chart and a dash in a table, never as zero. A line breaks where data is missing and resumes at the next value, a bar leaves a gap or a gray stub, and a cell shows “—”. A real zero keeps its own representation, so the two look different. Why: A day with no data does not read as a day when nothing sold, so the chart does not show a fall that never happened. Held by the library by itself. Where: [Sparkline](https://grani.arseni.work/components/sparkline), [Table](https://grani.arseni.work/components/table), [Data table](https://grani.arseni.work/components/data-table), [Area chart](https://grani.arseni.work/components/area-chart), [Bar chart](https://grani.arseni.work/components/bar-chart). Tests: 11, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#gap-not-zero #### Show when a reporting period is still incomplete A month still in progress is marked as a partial result: its bar is hatched or its line segment dashed, and the chart labels it “in progress”. This lets you tell the figures collected so far from a completed month before comparing them. Why: Half a month’s total looks much lower than a full month’s. The marker keeps that difference from being read as a decline. Held by the library by itself. Where: [Bar chart](https://grani.arseni.work/components/bar-chart), [Area chart](https://grani.arseni.work/components/area-chart). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#partial-not-drop #### Show a shrinking loss as an improvement A balance that goes from −100 to −50 has improved, and it is shown that way: +50%, better. The percentage is calculated against the absolute value of the previous figure, so moving toward zero from a loss is shown as an increase. Why: The sign and the assessment agree: a smaller loss reads as an improvement, not as a decline. Held by the library by itself. Where: [Delta](https://grani.arseni.work/components/delta). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#loss-shrinks #### Act on several selected rows at once Select several records to reveal actions for the whole selection. A strip replaces the toolbar, states the count, such as “2 selected”, and offers the actions supplied by the app plus a way to clear the selection. Why: You can apply one change to many records in one step, instead of repeating it row by row. Held by the library by itself. Where: [Data table](https://grani.arseni.work/components/data-table). Tests: 2, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#bulk-action #### Edit a value in its row Offer an editor within a table row for small changes such as a status or amount. Make Save, Cancel and any correction needed after an error clear, so the task can be completed without opening a separate form. Why: You can correct one value and continue down the list without navigating into a full form and back. Not built yet: until it is, the app does it. #### Show when only some are selected See whether a selection is partial before acting on it. The select-all checkbox shows a dash when some items are selected, and a screen reader announces a mixed state. In a table, activating it selects all selectable rows on the current page; activating it when all are selected clears them. Why: You can tell a partial selection from a full one, or from none, before you act on the selected rows. Held by the library by itself. Where: [Checkbox](https://grani.arseni.work/components/checkbox), [Table](https://grani.arseni.work/components/table). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#mixed-says-some #### Copy a whole value in one press Copy an entire id or link with one press, even when only a shortened version is displayed. A brief check mark confirms a successful copy. Why: You get the exact value without selecting it by hand, so no character is missed and no ellipsis is copied with it. Held by the library by itself. Where: [Copy button](https://grani.arseni.work/components/copy-button). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#copy-value #### Remember hidden columns in this browser Hide unnecessary columns once and return to the same table layout on later visits in this browser. With the default browser storage, a change in another tab is also reflected here. Why: You set a table up for your work once, instead of hiding the same columns on every visit. Held by the library by itself. Where: [Table columns](https://grani.arseni.work/components/table-columns). Tests: 3, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#columns-remembered #### Return to the list where you were Return from a record to the same part of the list. The app should restore the filters, page and scroll position so you can continue reviewing the rows you left. Why: You can go through a list record by record without finding your place again after each one. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Find records by the details you remember Search using a detail you remember, such as a phone number, email address, invoice number or client’s company. The app should search the relevant fields and related records, and explain which details its search accepts. Why: You can find a record without remembering its exact title, and understand when a different search is needed. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Reload or share a list as you see it The search, the filters, the sort and the page are written into the page’s address, so a reload, a link sent to a colleague or the browser’s Back opens the list as you saw it. Why: A colleague can open the same query, and you can return to it later without setting the filters again. The matching records may change as the underlying data changes. Held by the library by itself. Where: [Data table](https://grani.arseni.work/components/data-table). Tests: 8, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#list-link #### Share a link to the open tab A link should open the same tab you were viewing and preserve that choice after a reload. The app enables this by storing the active tab in the page address and restoring it when the page opens. Why: Someone who opens your link lands on the section you meant, not on the first tab. Held by the app that uses it. Where: [Tabs](https://grani.arseni.work/components/tabs). #### Open a record from a link Give each record a direct link so someone with access can open it without searching. The app provides the address and loads the corresponding record. Why: A link points to exactly one record, so nobody has to search for it or guess which of two similar records was meant. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Open the records behind a number Make a count such as “12 overdue invoices” open the records it represents. The app applies the corresponding filters so you can inspect the records or act on them. Why: You can check a number, or act on the records behind it, without rebuilding its filters by hand. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Open a related record inside the drawer Explore related information without leaving the record you started from. A row with a chevron leads to the related view, which the app shows inside the same drawer as a level of its own. Back names the previous level and returns to it, with focus on the row that opened the related view. Why: You can inspect related records and return to the original task without reopening its drawer or re-entering the draft kept at the previous level. Held by the library by itself. Where: [Crud drawer](https://grani.arseni.work/components/crud-drawer), [List item](https://grani.arseni.work/components/list-item). Tests: 5, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#open-related #### Save filters you use often Save a frequently used set of filters under a name, then choose that name to apply them again. The app stores and restores the view; the records it returns can change over time. Why: A weekly query becomes one choice instead of several filters to rebuild, while preserving the same selection criteria. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Choose which records to export Before exporting, offer a clear choice between the selected rows and all records matching the current search and filters, including records on other pages. Why: The file holds the set you meant, and you do not have to delete stray records from it afterwards. Not built yet: until it is, the app does it. #### Create a related record from the form If a required related record is missing, offer a way to create it from the current form. For example, add a new client while preparing an invoice, then return to the invoice with its draft intact. Why: You finish the record you started, instead of leaving the form, creating the missing record elsewhere and typing everything again. Not built yet: until it is, the app does it. #### Start a new record with known values When the current task already identifies a value, prefill it in the new record. For example, an invoice created from a client’s page can start with that client selected. The app supplies the known values and lets you review them before saving. Why: You can review information the app already knows instead of re-entering it, reducing typing and accidental mistakes. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Start a record from a copy For a record similar to an existing one, let the app copy reusable values into a new draft. Review and change that draft before saving it as a separate record. Why: A record much like an existing one takes a few edits instead of every value typed again. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Keep your browser’s keyboard shortcuts Shortcuts you know from the browser and the system keep working inside the controls. The arrow keys move through a calendar, a list, tabs or a number, but with Ctrl, Cmd or Alt held the key goes to the browser: Alt+Left still goes back a page, and Cmd+Up still moves the text cursor to the start of a field. Alt+Down opens a list, as it does on a native select. Why: People who work from the keyboard use these shortcuts without thinking; a control that takes one over changes a number or a date instead, and the shortcut seems broken in that one place. Held by the library by itself. Where: [Input](https://grani.arseni.work/components/input), [List field](https://grani.arseni.work/components/list-field), [Calendar](https://grani.arseni.work/components/calendar), [Select](https://grani.arseni.work/components/select), [Tabs](https://grani.arseni.work/components/tabs), [Code input](https://grani.arseni.work/components/code-input), [Date picker](https://grani.arseni.work/components/date-picker), [Time picker](https://grani.arseni.work/components/time-picker), [Menu](https://grani.arseni.work/components/menu), [Scale input](https://grani.arseni.work/components/scale-input), [Area chart](https://grani.arseni.work/components/area-chart). Tests: 16, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#shortcuts-kept #### Select or clear a range of rows Select a group of neighboring rows without checking each one: check row 3, then hold Shift and check row 10, and rows 3 through 10 are selected. From the keyboard, Shift+Space on the checkbox does the same. Clearing a checkbox the same way clears the range. Why: Two checkbox actions select a whole range, so preparing a bulk action does not take a click per row. Held by the library by itself. Where: [Table](https://grani.arseni.work/components/table), [Data table](https://grani.arseni.work/components/data-table). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#range-select #### Search by a pasted list of values Provide a way to paste several values, such as order numbers from a spreadsheet, and use the accepted entries together as search or filter criteria. Why: You can work with a prepared set of records without entering and checking each search value separately. Not built yet: until it is, the app does it. #### Filter by a value in a cell Use a value already visible in a table as the next filter. For example, offer an action on a client’s name to show that client’s records without retyping the name. The application must connect the action to its filtering behavior. Why: The value in front of you is often the next thing to search by, and retyping it costs time and invites typos. Not built yet: until it is, the app does it. #### Reach frequent actions from the keyboard Use Ctrl+B or Cmd+B to collapse or expand the sidebar. Use F8 to reach the newest notification’s action, or its close button if it has no action; press F8 again to return. Press / to start a search in the list on the page. The shortcuts do not run while you are typing in a field or editor. Why: You can reach a notification’s Undo before it disappears and use common navigation actions without moving to the mouse. Held by the library by itself. Where: [App shell](https://grani.arseni.work/components/app-shell), [Table toolbar](https://grani.arseni.work/components/table-toolbar), [Toaster](https://grani.arseni.work/components/toaster). Tests: 15, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#keyboard-actions #### Reopen a recent record Keep recently opened records easy to return to. The app should provide a short recent-records list so you can reopen one directly instead of searching again. Why: You can pick up interrupted work without repeating the search that found the record. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Pin the records you use often Let people pin records they use regularly and reopen them from a persistent list. The app manages the pins and the list they appear in. Why: Records you come back to every day stay one step away, however long the lists around them grow. Held by the app that uses it. Where: in the app's own screens; no component of the library holds it by itself. #### Step through records in one drawer Review successive records without closing the drawer. Previous record and Next record ask for the neighboring record of the current list while the drawer stays open. While there is unsaved input or a save is running, they refuse with a shake instead of leaving your input behind. Why: You can go through a run of records, such as checking each new order, without closing and reopening the drawer for each one. Held by the library by itself. Where: [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#walk-records #### Save and start the next record Choose Save and add another to continue entering records in the same drawer. After a successful save, the app clears the form and keeps the drawer open. Focus moves to the first field, ready for the next entry. A failed save keeps the current input for correction or retry. Why: You can enter a batch without reopening the form after every successful save. Held by the library by itself. Where: [Crud drawer](https://grani.arseni.work/components/crud-drawer). Tests: 4, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#save-and-new #### Read every chart value from the keyboard Tab to a chart, then use the arrow keys, Home and End to explore its values. A screen reader announces the selected point and its data. A separate data table is also available to screen readers, including values that would otherwise appear only in a hover tooltip. Why: Someone on a keyboard or a screen reader gets the same numbers as someone with a mouse, not only the shape of the line. Held by the library by itself. Where: [Area chart](https://grani.arseni.work/components/area-chart), [Bar chart](https://grani.arseni.work/components/bar-chart), [Donut chart](https://grani.arseni.work/components/donut-chart). Tests: 6, named in patterns/tests.md beside this chapter Link: https://grani.arseni.work/patterns/working-the-list#values-by-keys

Account

Address