@umriss-ui/alarms 0.0.0-stage → 0.47.1

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changes to `@umriss-ui/alarms`
+
+This document describes what changes for **callers** of the package: exports,
+props, behaviour.
+
+**The numbers.** The middle digit rises when something is added; the last one
+when something is repaired. The seven packages are released in step, and a rename
+keeps its old name for one further minor, with a warning, before the minor after
+it removes the name ([the upgrade promise, ADR-0066](../../docs/adr/0066-one-number-peers-over-the-minor-a-rename-lives-one-minor.md)).
+**Whatever changes existing behaviour stands under a heading "Changed" of its
+own**, no matter which digit rose, with a `Migration:` line.
+
+Alarms joins the other six packages' one number at its first version.
+
+## 0.47.1 – Released in step with the table (Oct. 2026)
+
+No change of its own; the number moves with the table's repaired exports.
+
+## 0.47.0 – Alarm management: a model, a list and a banner (Oct. 2026)
+
+### Added
+
+- **`alarmModel`**, the lifecycle of the application's alarms as a pure view: four priorities (`critical`, `high`, `medium`, `low`), acknowledgement, shelving with the plant's reasons, suppression by design and out of service, flood and chatter. `Alarm.group` and `Alarm.sequence` give the first-out alarm of each group (`AlarmRow.firstOut`), `Flood.first` the earliest of a flood, `AlarmProjection.rate` the alarms raised in the ten minutes before the as-of time and `unacknowledgedByPriority` the count per priority. `acknowledge`, `lifecycleAt` and `countAcknowledgeable` are the transitions and counts the application applies; the package generates no alarm.
+- **`AlarmList`**, a grid with one tab stop, worst first: `PriorityMark`, "First out" and "First in flood" badges, the Raised column to the second, `maxHeight` for a scroll area, a ref on its root, and `snoozeReasons` (with `snoozeReason="required"` one reason must be given). A acknowledges the focused alarm, Shift+A asks to acknowledge the selection or, without one, the rows in view, S opens the shelve panel. A shelved alarm still in alarm shows "Shelved until 14:05". The live region changes at most once per two seconds of the view's as-of time and says a count of 0 when no row is shown. The flood mark reads "Alarm flood: 40 in 10 min".
+- **`AlarmBanner`**: the worst active, unacknowledged alarm in service with its mark, label and time, the count per priority, "n more", the flood and the freshness; `onAcknowledge`, `onOpen` and `onAnnunciate` (`new` with the highest priority, `cleared`), the cue for the application's horn. Its alert text carries the alarm's raised time, so a second arrival of the same type is spoken again; a consumer's `aria-label` is kept.
+- **The demo** on port 4179: example pages and the scenario "Work through the alerts". What the package follows of ISA-18.2 and where it departs stands in `docs/standards.md`; no conformance is claimed.

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Roman Händler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @umriss-ui/alarms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Alarm management for a control room: what happens to an alarm after the
+application has raised it. `alarmModel` turns the application's alarms into a
+view - lifecycle, acknowledgement, snoozing, flood and chatter - and
+`AlarmList` shows it, worst first. The application generates the alarms and
+applies every transition; the package reports what the operator asked for.
+
+`AlarmBanner` shows the worst unacknowledged alarm on every screen, from an
+unfiltered `alarmModel` view; keep it on screen with one line of the host's CSS,
+`position: sticky; top: 0`. Its `onAnnunciate` is the cue for the application's
+horn.
+
+## Install
+
+```bash
+pnpm add @umriss-ui/alarms @umriss-ui/core @umriss-ui/table
+```
+
+`@umriss-ui/core` and `@umriss-ui/table` are **peer dependencies**, and React 19
+or newer as well; TypeScript 5.4 or newer.
+
+The package ships ES2022 syntax; an application that serves older browsers
+transpiles it itself.
+
+The entry begins with `"use client"`, the directive a framework with Server
+Components reads to treat a module as client code. The list and the banner
+are used from a Client Component file; both render to a string on the server and
+in a test.
+
+## The boundary
+
+The application generates its alarms, applies every transition and keeps the
+result; the package derives a view from them and reports what the operator asked
+for. It raises no alarm, sounds no horn - `onAnnunciate` is the cue - and keeps no
+record. What it follows of ISA-18.2 and where it departs is in
+[`docs/standards.md`](../../docs/standards.md#isa-182---alarm-management).
+
+## Documentation
+
+The demo is the documentation; in a checkout, `pnpm dev:alarms` (port 4179)
+opens it. Every export is listed in [API.md](API.md).

package/dist/alarms.css

@@ -0,0 +1 @@
+@layer umriss.tokens,umriss.base,umriss.components;@layer umriss.base{}@layer umriss.components{}@layer umriss.components{._mark_1l90g_7,._mark_1l90g_7:before,._mark_1l90g_7:after{box-sizing:border-box}._mark_1l90g_7{--_alarms-fill: var(--u-color-priority-low);display:inline-flex;flex:none;vertical-align:middle;border-radius:var(--u-radius-sm);corner-shape:squircle}._mark_1l90g_7[data-priority=critical]{--_alarms-fill: var(--u-color-priority-critical)}._mark_1l90g_7[data-priority=high]{--_alarms-fill: var(--u-color-priority-high)}._mark_1l90g_7[data-priority=medium]{--_alarms-fill: var(--u-color-priority-medium)}._mark_1l90g_7[data-neutral]{--_alarms-fill: var(--u-color-text-secondary)}._shape_1l90g_33{display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;width:1.25rem;height:1.25rem;background:var(--_alarms-fill);color:var(--u-color-on-priority);font-size:var(--u-text-xs);font-weight:var(--u-weight-semibold);font-variant-numeric:tabular-nums;line-height:var(--u-leading-none)}._mark_1l90g_7[data-priority=critical] ._shape_1l90g_33{clip-path:polygon(50% 0,100% 50%,50% 100%,0 50%)}._mark_1l90g_7[data-priority=high] ._shape_1l90g_33{clip-path:polygon(50% 4%,100% 94%,0 94%);align-items:flex-end;padding-block-end:.05rem}._mark_1l90g_7[data-priority=medium] ._shape_1l90g_33{clip-path:inset(.125rem)}._mark_1l90g_7[data-priority=low] ._shape_1l90g_33{clip-path:circle(50%)}._mark_1l90g_7[data-flashing] ._shape_1l90g_33{animation:_flash_1l90g_1 var(--u-duration-alarm-flash) steps(1,end) infinite}@keyframes _flash_1l90g_1{50%{opacity:.2}}@media(prefers-reduced-motion:reduce){._mark_1l90g_7[data-flashing] ._shape_1l90g_33{animation:none}._mark_1l90g_7[data-flashing]{outline:2px solid var(--_alarms-fill);outline-offset:1px}}@media(forced-colors:active){._shape_1l90g_33{forced-color-adjust:none;background:CanvasText;color:Canvas}._mark_1l90g_7[data-neutral] ._shape_1l90g_33{background:GrayText}}}@layer umriss.base{}@layer umriss.components{}@layer umriss.components{._list_17n9u_4,._list_17n9u_4:before,._list_17n9u_4:after{box-sizing:border-box}._bar_17n9u_12,._bar_17n9u_12:before,._bar_17n9u_12:after{box-sizing:border-box}._heading_17n9u_19,._heading_17n9u_19:before,._heading_17n9u_19:after{box-sizing:border-box}._filler_17n9u_25,._filler_17n9u_25:before,._filler_17n9u_25:after{box-sizing:border-box}._asOf_17n9u_29,._asOf_17n9u_29:before,._asOf_17n9u_29:after{box-sizing:border-box}._live_17n9u_46,._live_17n9u_46:before,._live_17n9u_46:after{box-sizing:border-box}._alarm_17n9u_54,._alarm_17n9u_54:before,._alarm_17n9u_54:after{box-sizing:border-box}._label_17n9u_59,._label_17n9u_59:before,._label_17n9u_59:after{box-sizing:border-box}._counter_17n9u_63,._counter_17n9u_63:before,._counter_17n9u_63:after{box-sizing:border-box}._state_17n9u_70,._state_17n9u_70:before,._state_17n9u_70:after{box-sizing:border-box}._lifecycle_17n9u_74,._lifecycle_17n9u_74:before,._lifecycle_17n9u_74:after{box-sizing:border-box}._hidden_17n9u_80,._hidden_17n9u_80:before,._hidden_17n9u_80:after{box-sizing:border-box}._hiddenLabel_17n9u_87,._hiddenLabel_17n9u_87:before,._hiddenLabel_17n9u_87:after{box-sizing:border-box}._availability_17n9u_93,._availability_17n9u_93:before,._availability_17n9u_93:after{box-sizing:border-box}._priority_17n9u_98,._priority_17n9u_98:before,._priority_17n9u_98:after{box-sizing:border-box}._empty_17n9u_104,._empty_17n9u_104:before,._empty_17n9u_104:after{box-sizing:border-box}._row_17n9u_112,._row_17n9u_112:before,._row_17n9u_112:after{box-sizing:border-box}._snoozePanel_17n9u_132,._snoozePanel_17n9u_132:before,._snoozePanel_17n9u_132:after{box-sizing:border-box}._snoozeForm_17n9u_143,._snoozeForm_17n9u_143:before,._snoozeForm_17n9u_143:after{box-sizing:border-box}._list_17n9u_4{display:flex;flex-direction:column;gap:var(--u-space-3);min-width:0}._bar_17n9u_12{display:flex;align-items:center;gap:var(--u-space-3);flex-wrap:wrap}._heading_17n9u_19{font-size:var(--u-text-sm);font-weight:var(--u-weight-semibold);color:var(--u-color-text)}._filler_17n9u_25{flex:1 1 auto}._asOf_17n9u_29{font-size:var(--u-text-xs);color:var(--u-color-text-secondary)}._asOf_17n9u_29[data-freshness=stale]{color:var(--u-color-warning)}._asOf_17n9u_29[data-freshness=lost]{color:var(--u-color-danger-text);font-weight:var(--u-weight-medium)}._live_17n9u_46{font-size:var(--u-text-xs);color:var(--u-color-text-secondary)}._alarm_17n9u_54{display:block;min-width:10rem}._label_17n9u_59{font-weight:var(--u-weight-medium)}._counter_17n9u_63{margin-left:var(--u-space-2)}._state_17n9u_70{white-space:nowrap}._lifecycle_17n9u_74{font-size:var(--u-text-xs)}._hidden_17n9u_80{font-size:var(--u-text-xs);color:var(--u-color-text-secondary)}._hiddenLabel_17n9u_87{font-size:var(--u-text-xs)}._availability_17n9u_93{margin-right:var(--u-space-2)}._priority_17n9u_98{display:inline-flex;align-items:center;gap:var(--u-space-2)}._empty_17n9u_104{color:var(--u-color-text-secondary)}._row_17n9u_112[data-availability=in-service][data-lifecycle=active-unacknowledged] td:first-child{box-sizing:border-box}._row_17n9u_112[data-availability=in-service][data-lifecycle=active-unacknowledged] td:first-child{box-shadow:inset 3px 0 0 var(--u-color-danger)}._row_17n9u_112[data-availability=in-service][data-lifecycle=resolved-unacknowledged] td:first-child{box-sizing:border-box}._row_17n9u_112[data-availability=in-service][data-lifecycle=resolved-unacknowledged] td:first-child{box-shadow:inset 3px 0 0 var(--u-color-warning)}._row_17n9u_112[data-lifecycle=resolved-acknowledged] :is(td,th),._row_17n9u_112:not([data-availability=in-service]) :is(td,th){color:var(--u-color-text-secondary)}._snoozePanel_17n9u_132{min-width:240px;max-width:320px;background:var(--u-color-surface);border-radius:var(--u-radius-md);corner-shape:squircle;outline:1px solid transparent;box-shadow:var(--u-shadow-overlay);padding:var(--u-space-3)}._snoozeForm_17n9u_143{display:flex;flex-direction:column;gap:var(--u-space-3)}}@layer umriss.base{._text_18806_22{font-family:var(--u-font-sans);font-size:var(--u-text-md);line-height:var(--u-leading-normal);color:var(--u-color-text);-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}@media(pointer:fine){._dense_18806_38{--u-control-height-sm: var(--u-control-height-xs)}}._ink_18806_49{--u-color-text: var(--u-color-bg);--u-color-text-secondary: color-mix(in srgb, var(--u-color-bg) 75%, transparent);--u-color-text-muted: color-mix(in srgb, var(--u-color-bg) 60%, transparent)}._extent_18806_75{--_chars: 20;--_extra: 0;--_tracking: 0px;--_chrome: 0px;min-inline-size:0;max-inline-size:100%;contain:inline-size;contain-intrinsic-inline-size:calc((var(--_chars) + var(--_extra)) * (1ch + var(--_tracking)) + var(--_chrome))}._field_18806_90{caret-color:var(--u-color-accent)}._scroll_18806_96{scrollbar-width:thin;scrollbar-color:color-mix(in srgb,var(--u-color-text) 25%,transparent) transparent}._scroll_18806_96::-webkit-scrollbar{width:10px;height:10px}._scroll_18806_96::-webkit-scrollbar-thumb{background:color-mix(in srgb,var(--u-color-text) 22%,transparent);border-radius:var(--u-radius-full);border:3px solid transparent;background-clip:content-box}._scroll_18806_96::-webkit-scrollbar-track{background:transparent}}@layer umriss.components{._ring_18806_125:focus-visible{outline:2px solid transparent;box-shadow:var(--u-focus-ring)}@media(pointer:coarse){._field_18806_90._field_18806_90,._fieldRoot_18806_145._fieldRoot_18806_145{font-size:16px}}._field_18806_90:-webkit-autofill,._field_18806_90:-webkit-autofill:hover,._field_18806_90:-webkit-autofill:focus{-webkit-box-shadow:inset 0 0 0 1000px var(--u-color-surface),0 0 0 1px var(--u-edge-color-strong);-webkit-text-fill-color:var(--u-color-text);caret-color:var(--u-color-accent)}}@layer umriss.components{._banner_13ro2_4,._banner_13ro2_4:before,._banner_13ro2_4:after{box-sizing:border-box}._worst_13ro2_18,._worst_13ro2_18:before,._worst_13ro2_18:after{box-sizing:border-box}._time_13ro2_25,._time_13ro2_25:before,._time_13ro2_25:after{box-sizing:border-box}._more_13ro2_26,._more_13ro2_26:before,._more_13ro2_26:after{box-sizing:border-box}._asOf_13ro2_27,._asOf_13ro2_27:before,._asOf_13ro2_27:after{box-sizing:border-box}._counts_13ro2_41,._counts_13ro2_41:before,._counts_13ro2_41:after{box-sizing:border-box}._count_13ro2_41,._count_13ro2_41:before,._count_13ro2_41:after{box-sizing:border-box}._none_13ro2_55,._none_13ro2_55:before,._none_13ro2_55:after{box-sizing:border-box}._banner_13ro2_4{display:flex;align-items:center;flex-wrap:wrap;gap:var(--u-space-2) var(--u-space-3);min-width:0;padding:var(--u-space-2) var(--u-space-3);border:1px solid var(--u-color-border);border-radius:var(--u-radius-md);corner-shape:squircle;background:var(--u-color-surface);color:var(--u-color-text)}._worst_13ro2_18{display:inline-flex;align-items:center;gap:var(--u-space-2);font-weight:var(--u-weight-semibold)}._time_13ro2_25,._more_13ro2_26,._asOf_13ro2_27{font-size:var(--u-text-xs);color:var(--u-color-text-secondary)}._asOf_13ro2_27[data-freshness=stale]{color:var(--u-color-warning)}._asOf_13ro2_27[data-freshness=lost]{color:var(--u-color-danger-text);font-weight:var(--u-weight-medium)}._counts_13ro2_41{display:inline-flex;align-items:center;gap:var(--u-space-2)}._count_13ro2_41{display:inline-flex;align-items:center;gap:var(--u-space-1);font-size:var(--u-text-xs);font-variant-numeric:tabular-nums}._none_13ro2_55{color:var(--u-color-text-secondary)}._none_13ro2_55[data-lost]{color:var(--u-color-danger-text);font-weight:var(--u-weight-medium)}}