Document stock visual decisions and operational UI examples
This commit is contained in:
1 parent
714447aa06
commit
08ff987edb
14 files changed
+532
-7
No files matched your search
@@ -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 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.
|
||||
Reference in new issue
Block a user