# Component contracts This is the implementation contract for the reference-matched construction ERP library. The searchable inventory is the coverage source of truth. “Live example” means an implemented UI example, not a production service. “Specification” means that workflow still requires implementation. The count is a count of components and patterns, not distinct production-ready packages. ## Core contract - Use Roboto, shared colours, 24/32 page headings, 14/20 working text, 12/18 metadata, 6 px controls and 12 px cards. Do not introduce a new theme per module. - Inputs always have labels. Required fields validate on submit; invalid entries retain their value. Identify the affected field and explain the recovery action. - Money is right aligned with explicit currency and consistent precision. Quantities retain their unit. Missing is not zero. Do not sum different units. - A component reports intent and displays application state. It must not invent permission, posting, tax or approval rules. - Async components need idle, pending, success and error; disable duplicate requests. The demo timers illustrate transitions, not network guarantees. - Native controls handle basic semantics. Custom tabs, combobox and menu implement their stated keyboard contract. Do not add ARIA roles without implementing their behaviour. ## Class and behaviour API | Component | Markup/classes | State hooks | |---|---|---| | Button | `button.button`, `.primary`, `.small`, `.danger-button` | `disabled`, `aria-busy`; actual result reported by owner | | Field | `label.field` + native input/select/textarea | `required`, `aria-invalid`, `aria-describedby` | | Badge | `.badge`, `.success`, `.warning`, `.danger`, `.blue-badge` | Visible text carries meaning | | Card | `section.card.pad` | Heading required for independently labelled section | | Alert | `.alert` + semantic modifier | `role=alert` only when dynamically urgent | | Dialog | `dialog.dialog`, optional `.drawer` | `openDialog(id)` / `closeDialog(element)` | | Toast | existing toast host | `toast(message)`; persistent dismiss control | | Table | semantic table inside `.table-scroll` | `aria-sort`, checkboxes, explicit action buttons | | Tabs | `.system-tabs [role=tab]` + labelled panels | `tab(id, focus)`; arrow/Home/End | | Combobox | `.combobox-wrap` with input/listbox | expanded, active descendant, selected option | | Resizer | `.resize-handle` separator | pointer capture, keyboard arrows, min/max/current | | Pattern navigation | `[data-page]` | `page(id)` selects known demo screen | The functions above are the present demo API, not a published framework library. Domain data is local JavaScript. Extract stateful adapters into the chosen production framework before connecting services. ## Source examples ```html Enter a whole number of bags. ``` ```html

Review changes

 ``` ## Composition and data contracts - Register input: stable record ID, displayed fields, selected IDs, filters, sorting, page and page size. Grouping is explicitly within the current page. Export scope is filtered or selected, never ambiguous. - Editable line input: stable row ID, material ID, unit, quantity and rate. Output: edits and validation state. Demo arithmetic rounds each line to cents; production precision is a business decision. - Measurement input: length, width, depth, repetition count; all positive. Output: illustrative volume. Certification and measurement methods are external. - Receipt input: received/rejected. Accepted cannot be negative. Passing validation does not post stock. - Transfer input: source store, target store, quantity; stores must differ. Real availability is checked by the service at commit time. - Bill input: current value and retention percentage 0–100. Other taxes/deductions/advances are not inferred. - Permission matrix: Create/Approve implies View; removing View clears dependants in the demo. Real authorisation is server enforced. - Schedule input: task start/end; finish on or after start. Demo is September 2026 only. Dependency scheduling is not simulated. - Payment allocation: each amount within bill balance, total within available payment. The demo does not execute a payment. - Import map: one source column per destination field, preview before commit. Example validates a fixed sheet; actual import needs server parsing and duplicate policy. ## Component/state index ### 001 · Typography Category: Foundations. Delivery: **Live example**. States: page, section, body, data, metadata. Example: `foundations` tab/page in `index.html`. ### 002 · Semantic colours Category: Foundations. Delivery: **Live example**. States: light, dark, success, warning, danger. Example: `foundations` tab/page in `index.html`. ### 003 · Spacing & sizing Category: Foundations. Delivery: **Live example**. States: 4 px scale, desktop, narrow. Example: `foundations` tab/page in `index.html`. ### 004 · Radii & surfaces Category: Foundations. Delivery: **Live example**. States: controls, cards, dialogs. Example: `foundations` tab/page in `index.html`. ### 005 · Motion Category: Foundations. Delivery: **Live example**. States: standard, reduced. Example: `foundations` tab/page in `index.html`. ### 006 · Iconography Category: Foundations. Delivery: **Live example**. States: decorative, labelled action. Example: `foundations` tab/page in `index.html`. ### 007 · Data formatting Category: Foundations. Delivery: **Live example**. States: INR grouping, unit, local date. Example: `foundations` tab/page in `index.html`. ### 008 · App shell Category: Navigation. Delivery: **Live example**. States: expanded, collapsed, narrow. Example: `overview` tab/page in `index.html`. ### 009 · Sidebar search Category: Navigation. Delivery: **Live example**. States: query, filtered. Example: `overview` tab/page in `index.html`. ### 010 · Breadcrumb Category: Navigation. Delivery: **Live example**. States: current location. Example: `overview` tab/page in `index.html`. ### 011 · Command search Category: Navigation. Delivery: **Live example**. States: open, query, empty, keyboard. Example: `overview` tab/page in `index.html`. ### 012 · Tabs Category: Navigation. Delivery: **Live example**. States: selected, arrow keys, Home/End. Example: `foundations` tab/page in `index.html`. ### 013 · Notification drawer Category: Navigation. Delivery: **Live example**. States: unread, read. Example: `overview` tab/page in `index.html`. ### 014 · Project context Category: Navigation. Delivery: **Live example**. States: project, dependent store. Example: `patterns` tab/page in `index.html`. ### 015 · Pagination Category: Navigation. Delivery: **Live example**. States: first, middle, last, disabled. Example: `orders` tab/page in `index.html`. ### 016 · Wizard Category: Navigation. Delivery: **Live example**. States: step, invalid, back, finish. Example: `advanced` tab/page in `index.html`. ### 017 · Action menu Category: Navigation. Delivery: **Live example**. States: closed, open, keyboard, escape. Example: `advanced` tab/page in `index.html`. ### 018 · Button Category: Inputs. Delivery: **Live example**. States: primary, secondary, quiet, danger, disabled, busy. Example: `controls` tab/page in `index.html`. ### 019 · Text input Category: Inputs. Delivery: **Live example**. States: default, filled, required, invalid. Example: `controls` tab/page in `index.html`. ### 020 · Textarea Category: Inputs. Delivery: **Live example**. States: empty, filled, required. Example: `controls` tab/page in `index.html`. ### 021 · Number Category: Inputs. Delivery: **Live example**. States: positive, zero, invalid precision. Example: `patterns` tab/page in `index.html`. ### 022 · Currency Category: Inputs. Delivery: **Live example**. States: rate, subtotal, invalid. Example: `patterns` tab/page in `index.html`. ### 023 · Date Category: Inputs. Delivery: **Live example**. States: empty, selected, required. Example: `controls` tab/page in `index.html`. ### 024 · Date range Category: Inputs. Delivery: **Live example**. States: valid, reverse range. Example: `patterns` tab/page in `index.html`. ### 025 · Select Category: Inputs. Delivery: **Live example**. States: empty, required, chosen. Example: `controls` tab/page in `index.html`. ### 026 · Checkbox Category: Inputs. Delivery: **Live example**. States: checked, unchecked. Example: `controls` tab/page in `index.html`. ### 027 · Radio Category: Inputs. Delivery: **Live example**. States: group, selected. Example: `controls` tab/page in `index.html`. ### 028 · Switch Category: Inputs. Delivery: **Live example**. States: on, off. Example: `controls` tab/page in `index.html`. ### 029 · Searchable combobox Category: Inputs. Delivery: **Live example**. States: query, empty, arrows, selection, escape. Example: `advanced` tab/page in `index.html`. ### 030 · Multi-select Category: Inputs. Delivery: **Live example**. States: search, checked, tags, remove. Example: `patterns` tab/page in `index.html`. ### 031 · Password Category: Inputs. Delivery: **Live example**. States: masked, revealed. Example: `advanced` tab/page in `index.html`. ### 032 · Input addons Category: Inputs. Delivery: **Live example**. States: prefix, suffix. Example: `advanced` tab/page in `index.html`. ### 033 · Read-only & disabled Category: Inputs. Delivery: **Live example**. States: locked value, dependency explanation. Example: `advanced` tab/page in `index.html`. ### 034 · Range slider Category: Inputs. Delivery: **Live example**. States: pointer, keyboard, output. Example: `advanced` tab/page in `index.html`. ### 035 · Tooltip Category: Inputs. Delivery: **Live example**. States: hover, focus, Escape. Example: `advanced` tab/page in `index.html`. ### 036 · File selection Category: Inputs. Delivery: **Live example**. States: selected, invalid type/size, removal. Example: `patterns` tab/page in `index.html`. ### 037 · Form validation Category: Inputs. Delivery: **Live example**. States: summary, invalid focus, corrected. Example: `controls` tab/page in `index.html`. ### 038 · Inline editing Category: Inputs. Delivery: **Live example**. States: view, edit, save, cancel. Example: `advanced` tab/page in `index.html`. ### 039 · Table Category: Data display. Delivery: **Live example**. States: normal, hover, compact. Example: `orders` tab/page in `index.html`. ### 040 · Sorting Category: Data display. Delivery: **Live example**. States: ascending, descending. Example: `orders` tab/page in `index.html`. ### 041 · Quick filters Category: Data display. Delivery: **Live example**. States: all, status, count. Example: `orders` tab/page in `index.html`. ### 042 · Advanced filters Category: Data display. Delivery: **Live example**. States: supplier, date, reset. Example: `orders` tab/page in `index.html`. ### 043 · Column visibility Category: Data display. Delivery: **Live example**. States: visible, hidden. Example: `orders` tab/page in `index.html`. ### 044 · Column resizing Category: Data display. Delivery: **Live example**. States: drag, keyboard resize, min width. Example: `advanced` tab/page in `index.html`. ### 045 · Column ordering Category: Data display. Delivery: **Live example**. States: move, boundary. Example: `advanced` tab/page in `index.html`. ### 046 · Grouping Category: Data display. Delivery: **Live example**. States: none, status on page. Example: `orders` tab/page in `index.html`. ### 047 · Saved view Category: Data display. Delivery: **Live example**. States: save, restore. Example: `orders` tab/page in `index.html`. ### 048 · Bulk selection Category: Data display. Delivery: **Live example**. States: none, page, cross-page, indeterminate. Example: `orders` tab/page in `index.html`. ### 049 · CSV export Category: Data display. Delivery: **Live example**. States: filtered, selected, no data. Example: `orders` tab/page in `index.html`. ### 050 · Expandable row Category: Data display. Delivery: **Live example**. States: collapsed, related items. Example: `advanced` tab/page in `index.html`. ### 051 · Badge Category: Data display. Delivery: **Live example**. States: draft, approved, rejected, pending. Example: `foundations` tab/page in `index.html`. ### 052 · Avatar Category: Data display. Delivery: **Live example**. States: initials, context. Example: `overview` tab/page in `index.html`. ### 053 · Progress Category: Data display. Delivery: **Live example**. States: labelled determinate. Example: `construction` tab/page in `index.html`. ### 054 · Chart Category: Data display. Delivery: **Live example**. States: 3/6 months, description. Example: `overview` tab/page in `index.html`. ### 055 · Dashboard widgets Category: Data display. Delivery: **Live example**. States: shown, hidden, reordered. Example: `advanced` tab/page in `index.html`. ### 056 · Empty state Category: Data display. Delivery: **Live example**. States: no records, next action. Example: `feedback` tab/page in `index.html`. ### 057 · Timeline Category: Data display. Delivery: **Live example**. States: done, pending. Example: `patterns` tab/page in `index.html`. ### 058 · Revision comparison Category: Data display. Delivery: **Live example**. States: before, after. Example: `construction` tab/page in `index.html`. ### 059 · Alert Category: Feedback & overlays. Delivery: **Live example**. States: success, warning, error. Example: `feedback` tab/page in `index.html`. ### 060 · Toast Category: Feedback & overlays. Delivery: **Live example**. States: announced, persistent, dismiss. Example: `feedback` tab/page in `index.html`. ### 061 · Loading Category: Feedback & overlays. Delivery: **Live example**. States: busy, resolved. Example: `controls` tab/page in `index.html`. ### 062 · Skeleton Category: Feedback & overlays. Delivery: **Live example**. States: loading, resolved, reduced motion. Example: `advanced` tab/page in `index.html`. ### 063 · Retry Category: Feedback & overlays. Delivery: **Live example**. States: failure, retry, restored. Example: `construction` tab/page in `index.html`. ### 064 · Modal Category: Feedback & overlays. Delivery: **Live example**. States: open, confirm, cancel, focus return. Example: `feedback` tab/page in `index.html`. ### 065 · Drawer Category: Feedback & overlays. Delivery: **Live example**. States: context, close, escape. Example: `feedback` tab/page in `index.html`. ### 066 · Popover Category: Feedback & overlays. Delivery: **Live example**. States: open, outside click, escape. Example: `orders` tab/page in `index.html`. ### 067 · Disclosure Category: Feedback & overlays. Delivery: **Live example**. States: open, closed. Example: `patterns` tab/page in `index.html`. ### 068 · Unsaved guard Category: Feedback & overlays. Delivery: **Live example**. States: dirty, stay, discard. Example: `advanced` tab/page in `index.html`. ### 069 · Permission matrix Category: Feedback & overlays. Delivery: **Live example**. States: view, create, approve dependencies. Example: `advanced` tab/page in `index.html`. ### 070 · Access denied Category: Feedback & overlays. Delivery: **Live example**. States: disabled, reason. Example: `construction` tab/page in `index.html`. ### 071 · Offline banner Category: Feedback & overlays. Delivery: **Live example**. States: preserved entry guidance. Example: `construction` tab/page in `index.html`. ### 072 · BOQ hierarchy Category: Construction patterns. Delivery: **Live example**. States: group, item, units, budget. Example: `construction` tab/page in `index.html`. ### 073 · Measurement Category: Construction patterns. Delivery: **Live example**. States: L/W/D/count, valid/invalid. Example: `construction` tab/page in `index.html`. ### 074 · Material line items Category: Construction patterns. Delivery: **Live example**. States: add/remove, select, quantity, rate, total. Example: `patterns` tab/page in `index.html`. ### 075 · Goods receipt Category: Construction patterns. Delivery: **Live example**. States: received, rejected, accepted. Example: `construction` tab/page in `index.html`. ### 076 · Retention summary Category: Construction patterns. Delivery: **Live example**. States: prior/current, percentage, net. Example: `construction` tab/page in `index.html`. ### 077 · Stock transfer Category: Construction patterns. Delivery: **Live example**. States: source/destination, same-store error. Example: `construction` tab/page in `index.html`. ### 078 · Allocation Category: Construction patterns. Delivery: **Live example**. States: issued, remaining. Example: `patterns` tab/page in `index.html`. ### 079 · Approval decision Category: Construction patterns. Delivery: **Live example**. States: pending, reason-required, returned, approved. Example: `patterns` tab/page in `index.html`. ### 080 · Attachment Category: Construction patterns. Delivery: **Live example**. States: local validation. Example: `patterns` tab/page in `index.html`. ### 081 · Activity comment Category: Construction patterns. Delivery: **Live example**. States: append, text-safe. Example: `patterns` tab/page in `index.html`. ### 082 · Import mapping Category: Construction patterns. Delivery: **Live example**. States: column map, preview, row errors. Example: `advanced` tab/page in `index.html`. ### 083 · Schedule / Gantt Category: Construction patterns. Delivery: **Live example**. States: task dates, duration, bars. Example: `advanced` tab/page in `index.html`. ### 084 · Supplier comparison Category: Construction patterns. Delivery: **Live example**. States: quotes, lowest rate, selection. Example: `advanced` tab/page in `index.html`. ### 085 · Payment allocation Category: Construction patterns. Delivery: **Live example**. States: bill, amount, balance, over-allocation. Example: `advanced` tab/page in `index.html`. ### 086 · Equipment log Category: Construction patterns. Delivery: **Live example**. States: hours, fuel, validated entry. Example: `advanced` tab/page in `index.html`. ### 087 · Digital signing Category: Application specifications. Delivery: **Specification**. States: identity, consent, signature provider, audit. This application workflow is specified but not implemented; do not present it as available functionality. ### 088 · Remote asynchronous lookup Category: Application specifications. Delivery: **Specification**. States: loading, cancellation, stale results, pagination. This application workflow is specified but not implemented; do not present it as available functionality. ### 089 · Financial reconciliation Category: Application specifications. Delivery: **Specification**. States: matching, unresolved difference, authorised posting. This application workflow is specified but not implemented; do not present it as available functionality. ### 090 · Configurable approval engine Category: Application specifications. Delivery: **Specification**. States: rules, delegation, escalation, audit. This application workflow is specified but not implemented; do not present it as available functionality. ### 091 · Import execution Category: Application specifications. Delivery: **Specification**. States: server validation, duplicate resolution, atomic commit. This application workflow is specified but not implemented; do not present it as available functionality. ### 092 · Full spreadsheet grid Category: Application specifications. Delivery: **Specification**. States: range selection, paste validation, undo, formulas. This application workflow is specified but not implemented; do not present it as available functionality. ### 093 · Schedule dependencies Category: Application specifications. Delivery: **Specification**. States: critical path, dependency constraints, conflicts. This application workflow is specified but not implemented; do not present it as available functionality.