Document stock visual decisions and operational UI examples

This commit is contained in:
mchus committed 2026-10-03 09:15:31 +03:00
1 parent 714447aa06
commit 08ff987edb
14 files changed
+532 -7

No files matched your search

+2
View File
@@ -49,6 +49,8 @@ Read additional contracts by task type:
`table-management`, `controls-selection` `table-management`, `controls-selection`
- Visual style for server-rendered web apps: - Visual style for server-rendered web apps:
`web-visual-baseline`, `table-management`, `controls-selection` `web-visual-baseline`, `table-management`, `controls-selection`
- Week-based planning and Gantt views:
`timeline-views`, `web-visual-baseline`, `table-management`
- Forms, validation, modals: - Forms, validation, modals:
`forms-validation`, `modal-workflows` `forms-validation`, `modal-workflows`
- Import/export, CSV, upload batching: - Import/export, CSV, upload batching:
+10 -2
View File
@@ -1,6 +1,6 @@
# Contract: Controls + Selection # Contract: Controls + Selection
Version: 1.4 Version: 1.5
## Shared Base ## Shared Base
@@ -17,7 +17,8 @@ Version: 1.4
- Inside a data-table row action column, buttons are icon-only. Each one must have a - Inside a data-table row action column, buttons are icon-only. Each one must have a
deterministic `title` and `aria-label`; text labels belong in toolbars, forms and deterministic `title` and `aria-label`; text labels belong in toolbars, forms and
confirmation dialogs, not repeated in every row. confirmation dialogs, not repeated in every row.
- Buttons are text-first; icons are optional and must not replace labels on primary/danger actions. - Outside the documented icon-only row/toolbar controls, buttons are text-first; primary and
destructive form/confirmation actions retain visible labels.
- Base examples must show both `disabled` and `loading` states. - Base examples must show both `disabled` and `loading` states.
- Any control that triggers a network or database call must show a visible busy state for the whole - Any control that triggers a network or database call must show a visible busy state for the whole
duration of that call (spinner on the control, disabled control, or an equivalent indicator), and duration of that call (spinner on the control, disabled control, or an equivalent indicator), and
@@ -41,6 +42,10 @@ selects, multiselect filters, menus, date pickers.
- A panel must not be clipped by an ancestor's `overflow` (modal body, table wrapper). Position it - A panel must not be clipped by an ancestor's `overflow` (modal body, table wrapper). Position it
against the viewport (`position: fixed` or a body-level layer), not inside the clipping container. against the viewport (`position: fixed` or a body-level layer), not inside the clipping container.
- Implement placement once in the shared dropdown code; do not re-derive it per control. - Implement placement once in the shared dropdown code; do not re-derive it per control.
- A narrow table input may open a wider, content-sized suggestion panel. Clamp both horizontal
position and width to the viewport, as well as vertical height. Keep option labels useful:
identity, relevant status, quantity and price can share one compact line. Decorative price
tiers must not replace the actual amount or imply a stock/risk status.
## Checkbox Selection ## Checkbox Selection
@@ -61,6 +66,9 @@ selects, multiselect filters, menus, date pickers.
- straight internal separators between middle segments. - straight internal separators between middle segments.
- Active segment color may vary by context (for example blue preset selector vs dark status scope tabs), but geometry must remain consistent. - Active segment color may vary by context (for example blue preset selector vs dark status scope tabs), but geometry must remain consistent.
- Segment changes should preserve other active filters where possible. - Segment changes should preserve other active filters where possible.
- A view switcher uses the same joined geometry; expose the selected view with `aria-pressed`.
A single-choice form value uses radio semantics and keyboard behavior (native radios are
preferred), not just a colored active button. Concrete options remain product-specific.
## Bulk Action Safety ## Bulk Action Safety
+7 -2
View File
@@ -1,6 +1,6 @@
# Contract: Forms + Validation + Suggestions # Contract: Forms + Validation + Suggestions
Version: 1.1 Version: 1.2
This contract owns validation UX and multi-step flow rules for all form surfaces, This contract owns validation UX and multi-step flow rules for all form surfaces,
including modals (`modal-workflows` adds only modal-specific mechanics). including modals (`modal-workflows` adds only modal-specific mechanics).
@@ -10,6 +10,12 @@ including modals (`modal-workflows` adds only modal-specific mechanics).
- Group fields semantically and keep labels explicit. - Group fields semantically and keep labels explicit.
- Inputs requiring suggestions may use `datalist` or equivalent autocomplete UI. - Inputs requiring suggestions may use `datalist` or equivalent autocomplete UI.
- Suggestion sources must represent the full relevant scope (not only visible rows from paginated tables). - Suggestion sources must represent the full relevant scope (not only visible rows from paginated tables).
- Size fields by expected content: a short identifier/date beside a flexible name field is
preferable to equal-width columns. Align read-only metadata with adjacent editable values.
- Group editable child rows under the requirement/parent they satisfy, with indentation or
light connector lines. Label row controls even when repeated visible labels are omitted.
- Collapse field groups on narrow screens; retain horizontal scrolling for genuinely tabular
child editors. A fixed desktop width must not make the Save action unreachable.
## Validation ## Validation
@@ -39,4 +45,3 @@ Rules:
- If a workflow includes upload, the file control should be clearly labeled and the supported formats explicit. - If a workflow includes upload, the file control should be clearly labeled and the supported formats explicit.
- Import parsing/preview may be delegated to a dedicated import/export pattern, but the form contract must remain clear. - Import parsing/preview may be delegated to a dedicated import/export pattern, but the form contract must remain clear.
+20 -1
View File
@@ -1,6 +1,6 @@
# Contract: Modal Workflows # Contract: Modal Workflows
Version: 1.3 Version: 1.4
## State Machine ## State Machine
@@ -37,6 +37,25 @@ closed → open → submitting → success | error
move the dialog only, and reaching the dialog's end must not chain to the page. Reserve the move the dialog only, and reaching the dialog's end must not chain to the page. Reserve the
scrollbar gutter so locking the page does not shift the layout under the backdrop. scrollbar gutter so locking the page does not shift the layout under the backdrop.
## Explicit Save and Unsaved Changes
- Edit modals persist only on the labeled Save action. Field changes, autofill, child additions,
removals and state toggles remain draft state; no hidden writes on `change` or `blur`.
- Visually mark staged toggles (for example a dashed outline) and explain that Save applies
them. Do not present a draft state as already persisted.
- Track dirty state against a snapshot taken after initial asynchronous loading. Include state
outside inputs, such as pending deletions and toggle maps. Reset the snapshot only after
loading or successful save, never after an unrelated rerender of the edited content.
- Route Escape, backdrop and close buttons through one shared close guard. For dirty forms,
show an in-page choice: Continue editing / Close without saving. Escape on that confirmation
keeps the edits; Escape elsewhere acts on only the topmost modal.
- While submitting, block closing as well as double submission. On failure retain entered
values and show the error inline. If saving requires multiple requests, remember applied
operations so retry does not duplicate them; do not imply that partial success was rolled back.
- Removing a draft child may be staged without an immediate confirmation. Before committing
destructive deletion of persisted data, the separate confirmation required above must still
name the affected records and any cascade. A Save label alone is not that confirmation.
## Validation ## Validation
Validation UX follows the `forms-validation` contract (server-side on submit, inline field Validation UX follows the `forms-validation` contract (server-side on submit, inline field
@@ -15,3 +15,8 @@ Pattern-specific contracts should only define additions or exceptions.
Visual styling (colors, typography, surfaces) comes from `../web-visual-baseline/`. Visual styling (colors, typography, surfaces) comes from `../web-visual-baseline/`.
The behavior/layout contract is `contract.md`. The behavior/layout contract is `contract.md`.
For the dense parent/child variant, sticky scrolling surface, active filters and change-history
rows, see the [operational component sheet](../web-visual-baseline/assets/operations.html)
and [integration recipes](../web-visual-baseline/recipes.md). The extension deliberately keeps
horizontal scrolling; a sticky header is not a reason to clip columns.
+35 -1
View File
@@ -1,6 +1,6 @@
# Contract: Table Management (Shared) # Contract: Table Management (Shared)
Version: 1.1 Version: 1.2
## Scope ## Scope
@@ -87,6 +87,40 @@ Canonical mapping:
- Server-side filtering only — do not filter an already-loaded JS array client-side unless the full - Server-side filtering only — do not filter an already-loaded JS array client-side unless the full
dataset is guaranteed small (< 500 rows) and never grows. dataset is guaranteed small (< 500 rows) and never grows.
- Filter inputs debounce text input (300–500 ms) before triggering a server request. - Filter inputs debounce text input (300–500 ms) before triggering a server request.
- A shared collapsible filter panel may show the active-filter count and result count while
closed. Mark active fields inside it; collapsing it does not clear filters. Own URL state,
debounce and reset behavior in one shared module, with page-specific field declarations.
- Filter popups follow `controls-selection` placement rules, including in Gantt views;
raising z-index alone does not solve ancestor clipping or viewport overflow.
## Dense and Hierarchical Tables
- An operator-table density override may use `3px 14px` cell padding and middle alignment;
subordinate rows may use `1px` vertical padding and `18px` line height. Scope the override
to dense tables rather than changing key-value detail tables.
- Keep parents visually stronger than children. Indent children and align their columns;
omit redundant repeated parent fields. Expand only when there is meaningful detail.
- Expansion and editing are different actions. Use a keyboard-operable expand button with
`aria-expanded`; clicking a row action must not also toggle expansion.
- Sticky headers may use `border-collapse: separate; border-spacing: 0` to avoid collapsed
border rendering artifacts. Choose the scrolling owner explicitly. For a bounded table,
stick headers inside its scroll container and preserve horizontal scrolling.
Do not substitute `overflow-x: clip` for access to wide columns.
- Sorting uses one shared state cycle: ascending, descending, original order. Show the
direction and expose `aria-sort` on the header; use a button for keyboard activation.
Keep child groups attached to their parents. With server pagination, sort the query on
the server rather than just the loaded page.
## Change History Tables
- Use a dense event row with timestamp, actor, object and action, and expand multi-field
changes into labeled Before/After columns. Show a single meaningful change inline.
- A creation has an after value; a deletion has a before value. Do not render a misleading
empty-to-value arrow when there is no comparison.
- Combine a line item's name and quantity when they describe one change. Exclude technical
bookkeeping from the presentation, without deleting it from the underlying audit record.
- Event timestamps retain date/time precision. Formatting business dates as weeks must not
erase exact-date changes from the source audit data.
## Pagination Rules ## Pagination Rules
+49
View File
@@ -0,0 +1,49 @@
# Week-based Gantt example
The [contract](contract.md) captures the active List/Gantt workflow in stok's
`web/static/timeline-views.js` at `f589919`. The calendar implementation is dormant and is
not a default in this pattern. The [source audit](../web-visual-baseline/stock-review-2026-10-03.md)
distinguishes adopted decisions from outstanding implementation gaps.
## Shared geometry
Load canonical `view.css` first. This four-week example demonstrates geometry only; the server
or application computes week columns, bar positions, dates and status from the same records
as the list. Production ranges may contain more weeks and scroll horizontally.
```css
.gantt { max-height: 68vh; overflow: auto; border: 1px solid var(--border); border-radius: 4px; }
.gantt-row { display: grid; grid-template-columns: 260px minmax(224px, 1fr); min-width: 484px; border-bottom: 1px solid var(--border-lite); }
.gantt-header { position: sticky; top: 0; z-index: 3; background: var(--surface-2); }
.gantt-name { position: sticky; left: 0; z-index: 2; padding: 6px 9px; background: var(--surface); border-right: 1px solid var(--border); }
.gantt-weeks { display: grid; grid-template-columns: repeat(4, minmax(56px, 1fr)); }
.gantt-track { position: relative; min-height: 34px; }
.gantt-bar { position: absolute; top: 2px; bottom: 2px; border: 1px solid var(--border); border-radius: 4px; background: var(--accent-bg); color: var(--ink); white-space: nowrap; cursor: pointer; }
.gantt-bar:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
.gantt-fact { position: absolute; top: -1px; bottom: -1px; width: 3px; background: currentColor; }
```
```html
<p>2026 · W40–43</p>
<div class="gantt" tabindex="0" role="region" aria-label="Planning timeline">
<div class="gantt-row gantt-header">
<div class="gantt-name">Record</div>
<div class="gantt-weeks"><span>W40</span><span>W41</span><span>W42</span><span>W43</span></div>
</div>
<div class="gantt-row">
<div class="gantt-name">Order DEMO-01</div>
<div class="gantt-track">
<button type="button" class="gantt-bar" style="left:0;width:50%"
aria-label="Edit DEMO-01, 10 units, planned W40–41 of 2026, in transit">
10 units · In transit
</button>
</div>
</div>
</div>
```
For a parent with meaningful children, place a dedicated native button with `aria-expanded`
inside the name cell and wire it to child visibility. Keep that handler separate from the bar's
edit handler. Do not add an expand affordance for a leaf or a child identical to its parent.
An actual-date marker can use `.gantt-fact` with an accessible date in the bar label. Provide
a visible legend for markers and open-ended spans. Never rely on their color alone.
+30
View File
@@ -0,0 +1,30 @@
# Contract: Timeline Views
Version: 1.0
## Scope
An optional Gantt view for dates and parent/child records already represented by an operator
table. Visual styling inherits `web-visual-baseline`; filters inherit `table-management`.
This pattern comes from stok's active List/Gantt workflow. It does not require a calendar view.
## Rules
- Keep the list as the default view. Use a compact joined List/Gantt switcher and retain the
active filters when switching. Persist view/range in URL state when the page is shareable.
- Use ISO weeks for planning, with a visible range title and previous/current/next controls.
Mark the current week; include the ISO year wherever week numbers would be ambiguous.
- Use a bounded scrolling surface, a sticky week header and a sticky name column. Keep
filter popups above it and outside clipping ancestors using the shared dropdown mechanism.
- Parent names expand/collapse meaningful child detail. Timeline bars open the corresponding
record editor. These actions must not trigger each other; both work with the keyboard.
- Keep bar labels concise (identity/quantity), with complete dates/status available on
inspection and through an accessible name. Short bars must not make their labels unreadable;
labels may overflow within a lane if they do not cover another control.
- Display server-supplied status with text/shape as well as color. Distinguish actual-date
markers from planned spans and open-ended spans from completed ones.
- Reuse the same records and filters as the list; do not create separate business calculations
for the chart. Missing dates must not silently become today's date or disappear without an
unscheduled indication or an explicit count/link back to the list.
See [examples](README.md) for geometry and the source decisions.
@@ -7,6 +7,18 @@ Canonical reference files (full, production version of the style) are in `assets
- `assets/view.css` — copy this as the starting stylesheet and adapt tokens - `assets/view.css` — copy this as the starting stylesheet and adapt tokens
- `assets/view.html` — reference page structure (header, panels, tables) - `assets/view.html` — reference page structure (header, panels, tables)
- `assets/upload.html` — reference upload/open panel - `assets/upload.html` — reference upload/open panel
- [assets/operations.html](assets/operations.html) — static component sheet for dense tables,
nested rows, active filters, draft controls, history, disabled/loading states and privacy masking
- [assets/operations.css](assets/operations.css) — optional operational extension, loaded after
`view.css`; no duplicate palette or base theme
- [recipes.md](recipes.md) — integration examples for formatting, forms, drafts and privacy
- [stock-review-2026-10-03.md](stock-review-2026-10-03.md) — source audit, accepted decisions
and implementation gaps that must not become shared defaults
Do not maintain a separate "starter" copy of the CSS anywhere; `assets/view.css` is the Do not maintain a separate "starter" copy of the CSS anywhere; `assets/view.css` is the
single source. For a new app, copy it and delete unused rules. single source. For a new app, copy it and delete unused rules.
Open `assets/operations.html` locally to inspect the sample geometry; it needs no server,
external fonts or vendor libraries. It is a static state reference, not a working CRUD screen.
Wire application behavior according to the linked contracts and recipes. The existing `view.css`
is unchanged: optional density, sticky scrolling and operational controls live in the extension.
@@ -0,0 +1,67 @@
/* Optional operational layer; load after view.css. */
.operations .page-title-row, .operations .table-toolbar, .operations .form-actions {
display: flex; align-items: center; flex-wrap: wrap; gap: 8px;
}
.operations .page-title-row { justify-content: space-between; margin-bottom: 16px; }
.operations .page-title-row h2 { margin: 0; font-size: 22px; }
.operations .table-toolbar {
justify-content: space-between; padding: 9px 12px; background: var(--surface-2);
border: 1px solid var(--border); border-bottom: 0; border-radius: 4px 4px 0 0;
}
.operations .table-toolbar + .table-wrap { border-radius: 0 0 4px 4px; }
.operations .table-wrap { max-height: 60vh; overflow: auto; }
.operations .data-table { border-collapse: separate; border-spacing: 0; min-width: 680px; }
.operations .data-table th, .operations .data-table td { padding: 3px 14px; vertical-align: middle; }
.operations .data-table thead th { position: sticky; top: 0; z-index: 1; background: var(--surface-2); }
.operations .data-table .child-row td { padding-top: 1px; padding-bottom: 1px; line-height: 18px; }
.operations .data-table .child-name { padding-left: 32px; }
.operations .number { text-align: right; font-variant-numeric: tabular-nums; }
.operations .identifier { white-space: nowrap; }
.operations .actions-column { width: 1%; text-align: right; white-space: nowrap; }
.operations .row-status-warning { background: var(--warn-bg); }
.operations .btn-primary, .operations .btn-secondary, .operations .btn-danger {
min-height: 32px; padding: 6px 12px; border: 1px solid var(--border);
border-radius: 4px; font: inherit; font-size: 13px; font-weight: 700; cursor: pointer;
}
.operations .btn-primary { background: var(--accent); color: white; border-color: var(--accent); }
.operations .btn-secondary { background: var(--surface); color: var(--ink); }
.operations .btn-danger { background: var(--surface); color: var(--crit-fg); border-color: var(--crit-border); }
.operations button:disabled { opacity: .55; cursor: not-allowed; }
.operations button[aria-busy="true"] { cursor: wait; }
.operations .icon-button {
display: inline-grid; place-items: center; width: 24px; min-height: 24px;
padding: 0; border: 1px solid transparent; border-radius: 4px;
background: transparent; color: var(--muted); cursor: pointer;
}
.operations .icon-button svg { width: 14px; height: 14px; fill: none; stroke: currentColor; stroke-width: 2; }
.operations :is(button, a, input, select, summary):focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
.operations .quiet-link { color: inherit; text-decoration: none; }
.operations .quiet-link:hover { text-decoration: underline; }
.operations .table-filters { margin-bottom: 12px; border: 1px solid var(--border); border-radius: 4px; }
.operations .table-filters summary { padding: 6px 10px; background: var(--surface-2); cursor: pointer; }
.operations .table-filter-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; padding: 10px; }
.operations .active-filter { padding: 4px; border-left: 3px solid var(--accent); background: var(--accent-bg); }
.operations .field { display: flex; flex-direction: column; gap: 4px; }
.operations .field label { color: var(--muted); font-size: 12px; font-weight: 700; }
.operations .field input, .operations .field select {
min-width: 0; width: 100%; border: 1px solid var(--border); border-radius: 4px;
padding: 6px 8px; font: inherit; background: var(--surface); color: var(--ink);
}
.operations .record-head { display: flex; flex-wrap: wrap; gap: 12px; margin: 12px 0; }
.operations .field-short { flex: 0 1 130px; }
.operations .field-grow { flex: 1 1 240px; }
.operations .segmented { display: inline-flex; padding: 0; border: 1px solid var(--border); border-radius: 4px; overflow: hidden; }
.operations .segmented label { padding: 6px 10px; border-right: 1px solid var(--border); cursor: pointer; }
.operations .segmented label:last-child { border-right: 0; }
.operations .segmented label:has(input:checked) { background: var(--accent); color: white; }
.operations .is-pending { outline: 1px dashed currentColor; outline-offset: 2px; }
.operations .form-note { color: var(--muted); font-size: 12px; }
.operations .form-actions { margin: 16px 0; }
.operations .audit-before del { color: var(--crit-fg); }
.operations .audit-after ins { color: var(--ok-fg); text-decoration: none; }
.operations .prices-hidden [data-sensitive] { background: black; color: transparent; border-radius: 2px; user-select: none; }
@media (max-width: 720px) {
.operations .table-filter-grid { grid-template-columns: 1fr; }
.operations .record-head { flex-direction: column; }
.operations .field-short, .operations .field-grow { flex: auto; }
}
@@ -0,0 +1,64 @@
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Операционные компоненты</title>
<link rel="stylesheet" href="view.css">
<link rel="stylesheet" href="operations.css">
</head>
<body class="operations">
<header class="page-header"><h1>Операционные компоненты</h1></header>
<main class="page-main">
<p>Статические примеры состояний. Кнопки действий показаны без подключения к данным.</p>
<section class="section-card" aria-labelledby="records-title">
<div class="page-title-row"><h2 id="records-title">Закупки</h2><button type="button" class="btn-primary">Создать закупку</button></div>
<details class="table-filters" open>
<summary>Фильтры · 1 активный · найдено 2 записи</summary>
<div class="table-filter-grid">
<div class="field active-filter"><label for="status">Статус</label><select id="status"><option selected>В пути</option><option>Все</option></select></div>
<div class="field"><label for="query">Номер закупки</label><input id="query" type="search" placeholder="Содержит..."></div>
</div>
</details>
<div class="table-toolbar"><span>Показано 1–2 из 2</span><button type="button" class="btn-secondary" disabled>Экспорт выбранного</button></div>
<div class="table-wrap" tabindex="0" role="region" aria-label="Закупки, прокручиваемая таблица">
<table class="data-table">
<thead><tr><th scope="col">Закупка / позиция</th><th scope="col">Неделя</th><th scope="col" class="number">Количество</th><th scope="col">Статус</th><th scope="col" class="number">Сумма</th><th scope="col" class="actions-column" aria-label="Действия"></th></tr></thead>
<tbody>
<tr class="row-status-warning"><th scope="row" class="identifier">PO-DEMO-01</th><td>2026 · W40</td><td class="number">10</td><td><span class="status-badge status-warning">В пути</span></td><td class="number">$13&nbsp;320</td><td class="actions-column"><button type="button" class="icon-button" title="Изменить PO-DEMO-01" aria-label="Изменить PO-DEMO-01"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="m4 16 9-9 3 3-9 9H4zm11-9 2-2 3 3-2 2"/></svg></button></td></tr>
<tr class="child-row"><th scope="row" class="child-name">Устройство A</th><td>2026 · W40</td><td class="number">10</td><td>Ожидается</td><td class="number">$13&nbsp;320</td><td></td></tr>
<tr><th scope="row" class="identifier">PO-DEMO-02</th><td>2026 · W41</td><td class="number">0</td><td><span class="status-badge status-unknown">Дата уточняется</span></td><td class="number">$0</td><td></td></tr>
</tbody>
</table>
</div>
</section>
<section class="section-card" aria-labelledby="edit-title">
<h2 id="edit-title">Поля редактора и состояния сохранения</h2>
<div class="record-head">
<div class="field field-short"><label for="code">Код</label><input id="code" value="DEMO-01" readonly></div>
<div class="field field-grow"><label for="name">Название</label><input id="name" value="Пример проекта"></div>
<div class="field field-short"><label for="date">Дата поставки</label><input id="date" type="date" value="2026-10-01"></div>
</div>
<p id="probability-label">Вероятность реализации (уровни этого примера)</p>
<div class="segmented" role="group" aria-labelledby="probability-label">
<label><input type="radio" name="probability" value="0"> 0%</label><label><input type="radio" name="probability" value="25"> 25%</label><label><input type="radio" name="probability" value="50" checked> 50%</label><label><input type="radio" name="probability" value="75"> 75%</label><label><input type="radio" name="probability" value="100"> 100%</label>
</div>
<p><span class="is-pending">На складе</span> <span class="form-note">Изменение применится при сохранении.</span></p>
<div class="form-actions"><button type="button" class="btn-primary">Сохранить</button><button type="button" class="btn-primary" disabled aria-busy="true">Сохранение...</button><button type="button" class="btn-secondary" disabled>Нет изменений</button></div>
<p>Пример выбора при закрытии с несохранёнными изменениями:</p>
<div class="form-actions"><button type="button" class="btn-secondary">Продолжить редактирование</button><button type="button" class="btn-danger">Закрыть без сохранения</button></div>
</section>
<section class="section-card" aria-labelledby="history-title">
<h2 id="history-title">История</h2>
<p><time datetime="2026-10-03T10:30:00+03:00">03.10.2026 10:30</time> · operator · изменено количество: <del>8</del> → <ins>10</ins></p>
<details><summary>Изменены 2 поля</summary><div class="table-wrap" tabindex="0" role="region" aria-label="Изменения полей"><table class="data-table"><thead><tr><th scope="col">Поле</th><th scope="col">Было</th><th scope="col">Стало</th></tr></thead><tbody><tr><th scope="row">Позиция и количество</th><td class="audit-before"><del>Устройство A — 8 шт.</del></td><td class="audit-after"><ins>Устройство A — 10 шт.</ins></td></tr><tr><th scope="row">Статус</th><td class="audit-before">В пути</td><td class="audit-after">На складе</td></tr></tbody></table></div></details>
</section>
<section class="section-card" aria-labelledby="privacy-title">
<h2 id="privacy-title">Маскирование для демонстрации экрана</h2>
<p>Обычное состояние: <span data-sensitive>$13&nbsp;320</span></p>
<p class="prices-hidden">Маскирование включено: <span data-sensitive>$13&nbsp;320</span></p>
<p class="form-note">Значение остаётся в DOM. Это не редактирование экспортов и не ограничение доступа.</p>
</section>
</main>
</body>
</html>
+36 -1
View File
@@ -1,6 +1,6 @@
# Contract: Web Visual Baseline # Contract: Web Visual Baseline
Version: 1.1 Version: 1.2
## Scope ## Scope
@@ -16,6 +16,11 @@ in this pattern:
When a project does not already have an established design system, use this baseline by default. When a project does not already have an established design system, use this baseline by default.
Copy `assets/view.css` as the starting stylesheet and adapt tokens; do not rewrite it from prose. Copy `assets/view.css` as the starting stylesheet and adapt tokens; do not rewrite it from prose.
Keep shared operational components in one application stylesheet loaded after the baseline.
Keep page-only rules local to that page. If a project promises a byte-for-byte baseline copy,
put all overrides in the extension stylesheet; record deliberate deviations in its local bible.
The optional `assets/operations.css` example extends `view.css`; it is not a second baseline.
## Core Direction ## Core Direction
- Prefer a clean, data-first interface over decorative marketing UI. - Prefer a clean, data-first interface over decorative marketing UI.
@@ -75,6 +80,35 @@ Copy `assets/view.css` as the starting stylesheet and adapt tokens; do not rewri
`W32-34`. Audit-trail timestamps (created/updated-at) are exempt — show `W32-34`. Audit-trail timestamps (created/updated-at) are exempt — show
those as ordinary dates, since collapsing them to a week would hide the those as ordinary dates, since collapsing them to a week would hide the
information they exist to convey. information they exist to convey.
- Week formatting is a display convention, not a storage format: preserve the exact date in
form values and API payloads. Date inputs may display `2026 · W40` while submitting
`2026-10-01`. Exact-date filters may retain a normal date input.
- Include the ISO week-year when a range crosses years or the year would be ambiguous.
Do not compute a cross-year range from the minimum/maximum week numbers alone.
- Compact amounts (for example `$1,2 млн`) are allowed in summary metrics. Keep full rounded
amounts in tables so values remain comparable. Distinguish a known zero from a missing value.
- Align numeric columns right and use tabular numerals. Keep short identifiers on one line;
truncate long descriptions only when the complete value is available on inspection.
## Operational Extensions
- A compact header may include build version, current ISO week, sync state and a display
privacy toggle. Keep these in normal flex flow so they cannot overlap navigation.
- Navigation uses links with `aria-current="page"`; in-page actions use buttons.
Quiet text-colored links are allowed in dense data cells, with visible hover and keyboard
focus treatment. Do not apply the quiet treatment indiscriminately to every link.
- Summary metrics may sit above tables; they supplement the records rather than replace them.
Use the baseline's small radii, surfaces and spacing.
- If row backgrounds communicate status, use opaque `--ok-bg`, `--warn-bg`, `--crit-bg`
tokens and retain an explicit status indicator. Do not stack translucent status tints.
- Optional screen-sharing privacy mode masks sensitive values in place, preserves column
geometry and headings, and uses a labeled toggle with `aria-pressed`. Persist the preference
locally and apply it to newly rendered values. This is display masking only: DOM values,
API responses and exports are not redacted or access-controlled by it.
- A discrete probability/level indicator may use filled bars plus its exact numeric value
and accessible name. This is a defined quantitative encoding, not permission for arbitrary
per-field colors. Risk status remains a separate concept; product-specific levels and
thresholds stay in the project's local bible.
## Status Rules ## Status Rules
@@ -107,4 +141,5 @@ Show text or another explicit indicator together with the color treatment.
- Use this contract as the visual baseline. - Use this contract as the visual baseline.
- Use `table-management` for shared table geometry and interaction seams. - Use `table-management` for shared table geometry and interaction seams.
- Use `controls-selection` for button hierarchy, filters, and bulk selection semantics. - Use `controls-selection` for button hierarchy, filters, and bulk selection semantics.
- Use `timeline-views` for optional week-based Gantt views of the same records.
- Pattern-specific contracts may override details only when they document the reason. - Pattern-specific contracts may override details only when they document the reason.
@@ -0,0 +1,145 @@
# Operational UI recipes
Adapted from stok at `f589919`. See the [audit](stock-review-2026-10-03.md) for limitations
in the original implementations and [component sheet](assets/operations.html) for visual states.
These examples use server-rendered HTML, CSS and vanilla JavaScript; no framework is required.
## Load the extension after the baseline
```html
<link rel="stylesheet" href="/static/view.css">
<link rel="stylesheet" href="/static/operations.css">
<body class="operations">
<!-- Application content. -->
</body>
```
Copy only the needed extension rules into the application's shared stylesheet. Keep `view.css`
as the canonical starting point; do not copy all of stok's product-specific CSS or JavaScript.
The sample uses a bounded table scroller so sticky headers and horizontal overflow coexist.
## Whole-unit amounts and missing values
This USD example follows stok's display convention. Currency is a product choice, not a shared
hardcoded default. Do not use `value || ''`: a known zero must remain visible.
```js
function displayUSD(value) {
if (value === null || value === undefined || value === '') return '';
const amount = Number(value);
if (!Number.isFinite(amount)) return '';
const rounded = Math.round(amount);
return `${rounded < 0 ? '-' : ''}$${Math.abs(rounded).toLocaleString('ru-RU')}`;
}
```
`displayUSD(13320.4)` renders `$13 320`; `displayUSD(0)` renders `$0`.
Table cells use `text-align: right; font-variant-numeric: tabular-nums`.
For compact metrics, use a shared formatter rather than deriving an abbreviated value per page.
## Week display keeps the date intact
An enhanced date picker may show the week label in an alternate input while its original
field retains the date. A native input and a server-supplied label are also sufficient:
```html
<label for="delivery-date">Delivery date</label>
<input id="delivery-date" name="delivery_date" type="date"
value="2026-10-01" aria-describedby="delivery-week">
<span id="delivery-week">2026 · W40</span>
```
Recompute the label after selection, programmatic value changes and reset. Submit the original
`YYYY-MM-DD` value. Parse date-only strings as calendar dates, not timestamps that shift with
timezone conversion. Cross-year example: `2026 · W53 – 2027 · W01`, never `W1-53`.
The current-week header uses the operator's local date; audit event timestamps retain time.
## Sortable header with header semantics
```html
<th scope="col" aria-sort="ascending">
<button type="button" data-sort-key="quantity">
Quantity <span aria-hidden="true">↑</span>
</button>
</th>
```
On each activation cycle ascending → descending → original order; update the arrow and
`aria-sort`, remove sort state from other columns, and request the sorted query. Do not replace
the `th` role with `button`. Native button semantics provide Enter/Space activation.
## Draft state belongs to the editor
The following snapshot function illustrates the inputs and extra state the close guard must
consider. It is not a complete modal controller. The application owns loading, submit state,
focus management, topmost-modal selection and the in-page discard confirmation.
```js
function draftSnapshot(form, pendingDeletes, pendingToggles) {
const fields = [...form.querySelectorAll('input, select, textarea')].map(field => {
if (field.type === 'checkbox' || field.type === 'radio') {
return [field.name || field.id, field.value, field.checked];
}
if (field instanceof HTMLSelectElement && field.multiple) {
return [field.name || field.id, [...field.selectedOptions].map(option => option.value)];
}
return [field.name || field.id, field.value];
});
return JSON.stringify([fields, [...pendingDeletes].sort(),
[...pendingToggles].sort(([a], [b]) => a.localeCompare(b))]);
}
```
Take the clean snapshot after async initialization. Include new/deleted child rows and every
draft field, even if it has no form input. File editors additionally track selected files.
Do not silently write on input change or reset the clean snapshot after each render.
Before a user close request, reject it while submitting; otherwise compare the current snapshot
and ask to discard only if dirty. Programmatic close after a successful save is a separate path.
Use [modal-workflows](../modal-workflows/contract.md) for the full behavior contract. Do not
copy stok's `modal-guard.js` wholesale: its submission close gap is recorded in the audit.
## Screen-sharing mask with explicit markers
Mark sensitive text when rendering, including partial updates; this avoids recognizing money
with regexes or guessing columns from translated captions. Keep headings outside the mask.
The mask preserves dimensions. Use text-only spans for this minimal example.
```html
<button id="privacy-toggle" type="button" aria-pressed="false">Hide amounts</button>
<span data-sensitive>$13&nbsp;320</span>
```
```css
body.prices-hidden [data-sensitive] {
color: transparent;
background: black;
border-radius: 2px;
user-select: none;
}
```
Load the following script after the button. Existing and future marked spans follow the body
class, so no DOM-walking observer is needed. The example falls back to the current page if
the browser does not allow local storage.
```js
const privacyButton = document.getElementById('privacy-toggle');
const privacyKey = 'example.ui.hide-amounts';
function setPrivacy(hidden) {
document.body.classList.toggle('prices-hidden', hidden);
privacyButton.setAttribute('aria-pressed', String(hidden));
privacyButton.textContent = hidden ? 'Show amounts' : 'Hide amounts';
try { localStorage.setItem(privacyKey, String(hidden)); } catch { /* Page-only preference. */ }
}
let initiallyHidden = false;
try { initiallyHidden = localStorage.getItem(privacyKey) === 'true'; } catch { /* Use default. */ }
setPrivacy(initiallyHidden);
privacyButton.addEventListener('click', () => {
setPrivacy(!document.body.classList.contains('prices-hidden'));
});
```
This is cosmetic masking for a display, not security or export redaction. The underlying text
remains available in the DOM and to assistive technology. Applications choose which values to
mark; stok additionally masks selected project and purchase identifiers.
@@ -0,0 +1,50 @@
# stok visual review, 2026-10-03
Static source review of a Go server-rendered application with vanilla JavaScript and CSS.
No running application/browser verification was performed for this audit.
## Revisions and scope
- Source: `stok` commit `f589919` (repository directory `stock`).
- Checked-out `stock/bible`: `577aa20`; the parent repository records `714447a`.
This pre-existing submodule discrepancy was not changed by the review.
- Target shared library: `bible` at `714447a`, before this update. It already includes
backdrop press-origin, modal scroll locking and dropdown placement requirements missing
from the checked-out `stock/bible`.
- Source references below are paths relative to `stock`, not files copied into this library.
Business thresholds, probability levels, stock arithmetic, identifiers and endpoints stay
in the project's local bible. The untracked `bible/ui-design-code/` directory is out of scope.
## Accepted reusable decisions
| Decision | Source evidence | Shared destination |
| --- | --- | --- |
| Dark header, white surfaces, blue accent, Lato stack, quiet navigation and build version | `web/templates/header.html`, `web/static/stok.css` | Existing baseline retained; operational header guidance added |
| Dense aligned parent/child rows; smaller row icons; opaque status backgrounds | `web/static/stok.css`, purchase/project templates | `table-management`; optional `operations.css` |
| Sticky headers with separate table borders | `web/static/view.css` | `table-management`, with a scrollable bounded container |
| Shared collapsible filters with badge, highlighted fields, URL state and debounce | `web/static/table-filters.js` | `table-management` |
| Joined view/value controls; content-sized autocomplete labels | `web/static/stok.css`, `web/static/lot-picker.js` | `controls-selection`; exact probability choices stay local |
| Week-date display, whole-unit money, compact metric amounts | `web/static/format.js`, `web/static/date-picker.js` | Baseline formatting and recipes |
| Explicit modal Save, draft child edits and dashed pending toggles, dirty-close choice | `bible-local/decisions/2026-09-25-modals-save-only-on-button.md`, `web/static/modal-guard.js` | `modal-workflows`; destructive confirmation remains required |
| Short identifier/date fields, growing name field, read-only author, grouped allocations | `web/templates/projects.html`, `web/static/stok.css` | `forms-validation` |
| Browser-local in-place masking for screen sharing | `web/static/price-privacy.js` | Baseline privacy guidance; explicit-marker recipe |
| List/Gantt, week axis, sticky names, separate expand/edit actions, actual-date marker | `web/static/timeline-views.js`; commits `4f014e8`, `5cb8ffa`, `d0b9534` | New `timeline-views` contract |
| Dense history with inline single changes and expandable Before/After detail | `web/static/audit-view.js`, `web/templates/audit_log.html` | `table-management` history guidance |
## Gaps not promoted to shared rules
| Finding | Evidence and implication | Disposition |
| --- | --- | --- |
| The promised byte-for-byte baseline copy has drifted | Local decision `2026-09-12-web-ui-follows-bible-baseline.md` promises an unchanged copy; `diff` shows sticky headers, separate borders and `overflow-x: clip` in `web/static/view.css` | Adopt sticky geometry in the extension; keep horizontal scrolling. Do not bless clipping wide columns. |
| Dropdown placement is only partly shared/compliant | `lot-picker.js` handles vertical placement but does not clamp the right edge; `table-filters.js` uses an absolute popup and chooses direction only on open | Preserve the target library's viewport/scroll/resize rules; do not copy these helpers as complete reference implementations. |
| Color-only risk and sync indicators | `reports.html` and `projects.html` render some empty colored badges with only `title`/`aria-label`; `.table-sync .status-label` is hidden | Keep the visible text/shape requirement. A tooltip and accessible name do not provide a visible non-color distinction. |
| Modal close is not blocked during submission in all paths | Purchase edit disables the submit button, but `requestCloseModal`/`ModalGuard.requestClose` do not check submitting state | Retain the no-close-during-submit rule; do not vendor the guard unchanged. |
| Staged persisted child deletion has no separate confirmation | Purchase-order edit queues deletions and Save executes them, including cascades | Allow draft staging, but keep explicit destructive confirmation before commit. This is a conflict with the shared contract, not a new general exception. |
| Week ranges lose year information | `fmtWeekRange` takes min/max week numbers only; `date-picker.js` already preserves ISO year | Require week-year-aware cross-year labels; do not copy the range helper unchanged. |
| Sort interaction lacks semantic sort state | `sortable.js` adds `role="button"` to `th` and only changes `data-sort-dir` | Preserve header semantics and use `aria-sort` plus a button inside `th`. |
| Several secondary details drift | Metric cards use `8px` radii; project-head fixed flex fields lack a narrow-screen override; anchor reset is global | Keep `4px` default radii, responsive fields and scoped quiet links in shared examples. |
| Calendar source remains but the view is disabled | `timeline-views.js` allows only `list`/`gantt`; commit `877aaa6` disables calendar | Do not document the calendar/arrival heatmap as the active accepted interface. |
This update changes the shared library only. The findings above are outstanding application
issues, not claims that `stock` has been repaired or fully conforms. Accepted patterns are
generalized examples; they do not certify every source implementation.