@neuravision/construct 2.0.3 → 2.1.2

package/components/status.css

@@ -0,0 +1,107 @@
+/* ── Live / Connection Status ──────────────────────────────────── */
+
+.ct-status {
+  --ct-status-gap: var(--component-status-gap);
+  --ct-status-font-size: var(--component-status-font-size);
+  --ct-status-icon-size: var(--component-status-icon-size);
+  --ct-status-color: var(--color-text-secondary);
+  --ct-status-indicator-color: var(--color-border-strong);
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ct-status-gap);
+  color: var(--ct-status-color);
+  font-size: var(--ct-status-font-size);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--line-height-sm);
+}
+
+.ct-status__indicator,
+.ct-status__icon {
+  width: var(--ct-status-icon-size);
+  height: var(--ct-status-icon-size);
+  flex: none;
+}
+
+.ct-status__indicator {
+  border: var(--border-thin) solid currentColor;
+  border-radius: var(--radius-round);
+  background: var(--ct-status-indicator-color);
+  color: var(--ct-status-indicator-color);
+}
+
+.ct-status__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--ct-status-indicator-color);
+}
+
+.ct-status__label {
+  min-width: 0;
+}
+
+.ct-status__detail {
+  color: var(--color-text-muted);
+  font-weight: var(--font-weight-regular);
+}
+
+/* Labels use surface-safe neutral text because status can appear on any
+   surface. Semantic colour is reserved for the non-text indicator, while
+   the required visible wording carries meaning without colour. */
+
+.ct-status:is([data-status='online'], [data-status='success']) {
+  --ct-status-color: var(--color-text-primary);
+  --ct-status-indicator-color: var(--color-state-success);
+}
+
+.ct-status:is([data-status='connecting'], [data-status='info'], [data-state='loading']) {
+  --ct-status-color: var(--color-text-primary);
+  --ct-status-indicator-color: var(--color-state-info);
+}
+
+.ct-status:is([data-status='degraded'], [data-status='warning']) {
+  --ct-status-color: var(--color-text-primary);
+  --ct-status-indicator-color: var(--color-state-warning);
+}
+
+.ct-status:is([data-status='offline'], [data-status='neutral']) {
+  --ct-status-color: var(--color-text-secondary);
+  --ct-status-indicator-color: var(--color-border-strong);
+}
+
+.ct-status:is([data-status='error'], [data-status='danger'], [data-state='error']) {
+  --ct-status-color: var(--color-text-primary);
+  --ct-status-indicator-color: var(--color-state-danger);
+}
+
+.ct-status:is([aria-busy='true'], [data-status='connecting'], [data-state='loading']) {
+  cursor: wait;
+}
+
+.ct-status:is([aria-busy='true'], [data-status='connecting'], [data-state='loading']) .ct-status__indicator {
+  background: transparent;
+  border: var(--border-medium) solid currentColor;
+  border-inline-end-color: transparent;
+  animation: ct-spin var(--ct-spinner-duration) linear infinite;
+}
+
+.ct-status:is([aria-disabled='true'], [data-state='disabled']) {
+  opacity: var(--opacity-disabled);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ct-status__indicator {
+    animation: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .ct-status__indicator {
+    border: var(--border-medium) solid currentColor;
+  }
+
+  .ct-status:is([aria-busy='true'], [data-status='connecting'], [data-state='loading']) .ct-status__indicator {
+    border-inline-end-style: dotted;
+  }
+}

package/components/switch.css

@@ -43,7 +43,7 @@
 
 @media (hover: hover) {
   .ct-switch__input:not(:disabled):hover {
-    background: color-mix(in srgb, var(--color-border-strong) 85%, black);
+    background: color-mix(in srgb, var(--color-border-strong) 85%, var(--color-text-primary));
   }
 
   .ct-switch__input:checked:not(:disabled):hover {
@@ -54,6 +54,9 @@
 .ct-switch__input:disabled {
   background: var(--color-border-subtle);
   cursor: not-allowed;
+  /* disabled is encoded via the muted track color; opting out of the global
+     :disabled opacity avoids double dimming (same pattern as the slider) */
+  opacity: 1;
 }
 
 .ct-switch__input:focus-visible {
@@ -61,13 +64,21 @@
   outline-offset: 2px;
 }
 
-/* Invisible touch-target expansion (WCAG 2.5.8: 44×44px minimum) */
+/* WCAG 2.2 SC 2.5.8: the small track is only 20px tall, so every pointer
+   context gets at least a 24px-tall hit area. */
+.ct-switch__input::before {
+  content: '';
+  position: absolute;
+  inset-block: calc((var(--ct-switch-height) - 24px) / 2);
+  inset-inline: 0;
+}
+
+/* Construct 44×44 target policy: meets the size in WCAG 2.2 SC 2.5.5
+   (AAA) and exceeds the AA minimum in SC 2.5.8. */
 @media (pointer: coarse) {
   .ct-switch__input::before {
-    content: '';
-    position: absolute;
     inset-block: calc((var(--ct-switch-height) - 44px) / 2);
-    inset-inline: 0;
+    inset-inline: calc((var(--ct-switch-width) - 44px) / 2);
   }
 }
 
@@ -80,3 +91,53 @@
   --ct-switch-width: 52px;
   --ct-switch-height: 28px;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .ct-switch__input,
+  .ct-switch__input::after {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  /* Track and thumb are shadow/background-drawn; redraw both with
+     system-palette borders so on/off state survives without shadows. */
+  .ct-switch__input {
+    border: 1px solid ButtonText;
+    background: Canvas;
+  }
+
+  .ct-switch__input::after {
+    border: 1px solid ButtonText;
+    background: Canvas;
+    box-shadow: none;
+  }
+
+  /* The checked fill must survive forced backgrounds; the extra hover
+     selector matches the specificity of the base hover rule. */
+  .ct-switch__input:checked,
+  .ct-switch__input:checked:not(:disabled):hover {
+    background: SelectedItem;
+    border-color: ButtonText;
+    forced-color-adjust: none;
+  }
+
+  .ct-switch__input:checked::after {
+    background: SelectedItemText;
+    border-color: SelectedItemText;
+  }
+
+  .ct-switch__input:disabled,
+  .ct-switch__input:disabled::after {
+    border-color: GrayText;
+  }
+
+  .ct-switch__input:checked:disabled {
+    background: GrayText;
+  }
+
+  .ct-switch__input:checked:disabled::after {
+    background: Canvas;
+    border-color: GrayText;
+  }
+}

package/components/table.css

@@ -97,14 +97,18 @@
   mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 5'%3E%3Cpath d='M4 5L0 0h8z'/%3E%3C/svg%3E");
 }
 
-th[aria-sort='ascending'] .ct-table__sort-indicator::before {
+th[aria-sort='ascending'] .ct-table__sort-indicator::before,
+th[aria-sort='descending'] .ct-table__sort-indicator::after {
   background-color: var(--color-text-secondary);
   opacity: 1;
 }
 
-th[aria-sort='descending'] .ct-table__sort-indicator::after {
-  background-color: var(--color-text-secondary);
-  opacity: 1;
+/* Direction is shape-encoded: the unsorted state keeps the dimmed
+   both-ways glyph, while a sorted column shows only its own arrow so the
+   state never relies on colour or opacity alone. */
+th[aria-sort='ascending'] .ct-table__sort-indicator::after,
+th[aria-sort='descending'] .ct-table__sort-indicator::before {
+  display: none;
 }
 
 .ct-table__cell--numeric .ct-table__sort {
@@ -137,3 +141,48 @@ th[aria-sort='descending'] .ct-table__sort-indicator::after {
   font-size: var(--font-size-xs);
   color: var(--color-text-muted);
 }
+
+/* ── Selected / current rows ──
+   The datum: an orange leading edge marks the selected or current row,
+   consistent with list, sidebar, and card active states. The edge sits
+   on the row's first cell — box-shadow on <tr> is unreliable with
+   collapsed borders. Row text stays neutral; only the edge is orange. */
+.ct-table tbody tr > :first-child {
+  transition: box-shadow var(--duration-fast) var(--easing-standard);
+}
+
+.ct-table tbody tr:is([aria-selected='true'], [aria-current='true'], [data-state='selected']) {
+  background: var(--color-bg-muted);
+}
+
+.ct-table tbody tr:is([aria-selected='true'], [aria-current='true'], [data-state='selected']) > :first-child {
+  box-shadow: inset var(--component-datum-edge-width) 0 0 0 var(--color-brand-accent);
+}
+
+/* ── Sorted column ──
+   The datum underlines the actively sorted column header, like the tab
+   indicator. Direction stays shape-encoded via the arrow glyphs. */
+.ct-table thead th:is([aria-sort='ascending'], [aria-sort='descending']) {
+  box-shadow: inset 0 calc(-1 * var(--component-datum-edge-width)) 0 0 var(--color-brand-accent);
+}
+
+@media (forced-colors: active) {
+  /* Mask-drawn arrows paint via background-color; the sorted selectors
+     match the specificity of the full-strength rules above. */
+  .ct-table__sort-indicator::before,
+  .ct-table__sort-indicator::after,
+  th[aria-sort='ascending'] .ct-table__sort-indicator::before,
+  th[aria-sort='descending'] .ct-table__sort-indicator::after {
+    background-color: CanvasText;
+  }
+
+  /* The datum edges are inset box-shadows, which forced colors drops —
+     re-encode them as borders. */
+  .ct-table tbody tr:is([aria-selected='true'], [aria-current='true'], [data-state='selected']) > :first-child {
+    border-inline-start: var(--component-datum-edge-width) solid SelectedItem;
+  }
+
+  .ct-table thead th:is([aria-sort='ascending'], [aria-sort='descending']) {
+    border-block-end: var(--component-datum-edge-width) solid SelectedItem;
+  }
+}

package/components/tabs.css

@@ -30,19 +30,39 @@
   font-size: var(--ct-tabs-trigger-font-size);
   line-height: var(--ct-tabs-trigger-line-height);
   font-weight: var(--font-weight-medium);
+  text-decoration: none;
   cursor: pointer;
   transition: color var(--duration-fast) var(--easing-standard),
     background var(--duration-fast) var(--easing-standard);
 }
 
+/* Triggers may be rendered as <a> for router-driven tabs. Neutralize the
+   global link styling (underline + link colors) so anchor triggers read
+   identically to buttons — the active-tab signal is the indicator, never
+   an underline. Deliberately excludes :hover so the shared trigger hover
+   rule above keeps winning. */
+a.ct-tabs__trigger,
+a.ct-tabs__trigger:active {
+  color: var(--color-text-secondary);
+  text-decoration: none;
+}
+
 .ct-tabs__trigger::after {
   content: '';
   position: absolute;
   inset-inline: 0;
   inset-block-end: 0;
   height: var(--ct-tabs-indicator-size);
-  background: transparent;
-  transition: background var(--duration-fast) var(--easing-standard);
+  background: var(--ct-tabs-indicator-color);
+  /* The datum draws itself: the indicator grows from its origin on
+     activation instead of popping in. Collapsed to zero at rest. */
+  transform: scaleX(0);
+  transform-origin: 0 50%;
+  transition: transform var(--duration-fast) var(--easing-standard);
+}
+
+.ct-tabs__trigger:is(:dir(rtl))::after {
+  transform-origin: 100% 50%;
 }
 
 @media (hover: hover) {
@@ -65,7 +85,7 @@
 
 .ct-tabs__trigger[aria-selected='true']::after,
 .ct-tabs__trigger[data-state='active']::after {
-  background: var(--ct-tabs-indicator-color);
+  transform: scale(1);
 }
 
 .ct-tabs__trigger:disabled,
@@ -114,6 +134,13 @@
   inset-block: 0;
   width: var(--ct-tabs-indicator-size);
   height: auto;
+  /* Vertical tabs draw the indicator from the block start. */
+  transform: scaleY(0);
+  transform-origin: 50% 0;
+}
+
+.ct-tabs--vertical .ct-tabs__trigger:is([aria-selected='true'], [data-state='active'])::after {
+  transform: scale(1);
 }
 
 /* Pill variant */
@@ -139,9 +166,34 @@
   box-shadow: var(--shadow-sm);
 }
 
+/* Construct 44×44 target policy (WCAG 2.2 SC 2.5.5 is AAA) */
+
+@media (pointer: coarse) {
+  .ct-tabs__trigger {
+    min-block-size: 44px;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .ct-tabs__trigger,
   .ct-tabs__trigger::after {
     transition: none;
   }
 }
+
+@media (forced-colors: active) {
+  /* The active indicator is background-drawn and must survive forced
+     backgrounds. */
+  .ct-tabs__trigger[aria-selected='true']::after,
+  .ct-tabs__trigger[data-state='active']::after {
+    background: SelectedItem;
+    forced-color-adjust: none;
+  }
+
+  .ct-tabs--pill .ct-tabs__trigger[aria-selected='true'],
+  .ct-tabs--pill .ct-tabs__trigger[data-state='active'] {
+    background: SelectedItem;
+    color: SelectedItemText;
+    forced-color-adjust: none;
+  }
+}

package/components/toast.css

@@ -23,12 +23,21 @@
   box-shadow: var(--shadow-md);
   color: var(--color-text-primary);
   transition: opacity var(--duration-fast) var(--easing-standard),
-    transform var(--duration-fast) var(--easing-standard);
+    transform var(--duration-fast) var(--easing-standard),
+    visibility 0s linear 0s;
 }
 
+/* Delayed visibility (drawer.css pattern) removes the faded-out toast
+   from the accessibility tree and tab order once the fade completes;
+   reopening restores it instantly via the base transition. */
 .ct-toast[data-state='closed'] {
   opacity: 0;
   transform: translateY(8px);
+  visibility: hidden;
+  pointer-events: none;
+  transition: opacity var(--duration-fast) var(--easing-standard),
+    transform var(--duration-fast) var(--easing-standard),
+    visibility 0s linear var(--duration-fast);
 }
 
 .ct-toast__title {

package/components/toggle-group.css

@@ -24,11 +24,7 @@
   overflow-x: auto;
   overflow-y: hidden;
   -webkit-overflow-scrolling: touch;
-  scrollbar-width: none;
-}
-
-.ct-toggle-group::-webkit-scrollbar {
-  display: none;
+  scrollbar-width: thin;
 }
 
 /* ── Item ── */
@@ -194,3 +190,18 @@
     transition: none;
   }
 }
+
+/* ── Forced colors ── */
+
+@media (forced-colors: active) {
+  /* The pressed fill must survive forced backgrounds; the outlined
+     selectors match the specificity of that variant's override. */
+  .ct-toggle-group__item[aria-pressed='true'],
+  .ct-toggle-group__item[aria-checked='true'],
+  .ct-toggle-group--outlined .ct-toggle-group__item[aria-pressed='true'],
+  .ct-toggle-group--outlined .ct-toggle-group__item[aria-checked='true'] {
+    background: SelectedItem;
+    color: SelectedItemText;
+    forced-color-adjust: none;
+  }
+}

package/components/toolbar.css

@@ -15,7 +15,8 @@
   display: flex;
   align-items: center;
   gap: var(--ct-toolbar-gap);
-  height: var(--ct-toolbar-height);
+  /* min-height, not height: the bar must grow with text scaling. */
+  min-height: var(--ct-toolbar-height);
   padding: 0 var(--ct-toolbar-padding-x);
   background: var(--color-bg-elevated);
   border-bottom: var(--border-thin) solid var(--color-border-subtle);
@@ -153,8 +154,15 @@
   --ct-toolbar-actions-gap: var(--space-2);
 }
 
+/* WCAG 2.2 SC 2.5.8: dense padding alone cannot guarantee 24px links. */
+.ct-toolbar--dense .ct-toolbar__nav-link {
+  min-height: 24px;
+}
+
 /* ── Sticky ── */
 
+/* Consumers: set --ct-scroll-offset-top on :root (see foundations.css) so
+   scrolled-to content is not obscured behind the bar (WCAG 2.4.11). */
 .ct-toolbar--sticky {
   position: sticky;
   inset-block-start: 0;
@@ -213,6 +221,14 @@
   }
 }
 
+/* ── Construct 44×44 target policy (WCAG 2.2 SC 2.5.5 is AAA) ── */
+
+@media (pointer: coarse) {
+  .ct-toolbar__nav-link {
+    min-height: 44px;
+  }
+}
+
 /* ── Reduced Motion ── */
 
 @media (prefers-reduced-motion: reduce) {

package/components/tooltip.css

@@ -41,16 +41,20 @@
   --_tt-open: 1;
   opacity: 1;
   visibility: visible;
+  pointer-events: auto;
   transition: opacity var(--duration-fast) var(--easing-standard),
     transform var(--duration-fast) var(--easing-standard),
     visibility 0s linear 0s;
 }
 
 @media (hover: hover) {
+  .ct-tooltip[data-state='open'] .ct-tooltip__content,
+  .ct-tooltip:focus-within .ct-tooltip__content,
   .ct-tooltip:hover .ct-tooltip__content {
     --_tt-open: 1;
     opacity: 1;
     visibility: visible;
+    pointer-events: auto;
     transition: opacity var(--duration-fast) var(--easing-standard),
       transform var(--duration-fast) var(--easing-standard),
       visibility 0s linear 0s;

package/components/tree.css

@@ -118,10 +118,25 @@
   border-radius: var(--ct-tree-toggle-radius);
   color: var(--ct-tree-toggle-color);
   cursor: pointer;
+  position: relative;
   transition: color var(--duration-fast) var(--easing-standard),
     background var(--duration-fast) var(--easing-standard);
 }
 
+/* WCAG 2.2 SC 2.5.8: the visual chevron stays 1rem; the pointer target
+   does not. The hit area overlaps the row, mirroring checkbox.css. */
+.ct-tree__toggle::before {
+  content: '';
+  position: absolute;
+  inset: calc((var(--ct-tree-toggle-size) - 24px) / 2);
+}
+
+@media (pointer: coarse) {
+  .ct-tree__toggle::before {
+    inset: calc((var(--ct-tree-toggle-size) - 44px) / 2);
+  }
+}
+
 @media (hover: hover) {
   .ct-tree__toggle:hover {
     color: var(--ct-tree-toggle-color-hover);
@@ -194,6 +209,13 @@
   --ct-tree-actions-opacity: 1;
 }
 
+/* Touch surfaces have no hover to reveal row actions — keep them visible. */
+@media (hover: none) {
+  .ct-tree {
+    --ct-tree-actions-opacity: 1;
+  }
+}
+
 /* ── Selection ── */
 
 .ct-tree__node[aria-selected='true'] > .ct-tree__row,
@@ -277,6 +299,14 @@
   background: var(--color-bg-elevated);
 }
 
+/* ── Construct 44×44 target policy (WCAG 2.2 SC 2.5.5 is AAA) ── */
+
+@media (pointer: coarse) {
+  .ct-tree__row {
+    min-height: 44px;
+  }
+}
+
 /* ── Reduced motion ── */
 
 @media (prefers-reduced-motion: reduce) {

package/docs/architecture.md

@@ -0,0 +1,79 @@
+# Construct Architecture
+
+Construct separates reusable design decisions, visual component contracts, interaction behavior, and product integration. That separation lets a vanilla page and a framework application share the same public contract without coupling Construct to either runtime.
+
+```text
+primitive tokens
+      │
+      ▼
+semantic tokens ─── built-in/custom theme scopes
+      │
+      ▼
+component tokens ── stable component decisions
+      │
+      ├──────────────► component CSS ──► DOM + ARIA/data state
+      │                                      ▲
+      └──────────────► JS/TS token exports   │
+                                             │
+optional headless behaviors ─────────────────┘
+                                             │
+framework adapter / application data ───────┘
+```
+
+## Token layers
+
+1. **Primitives** are raw, context-free scales such as palette steps, spacing, type sizes, and motion durations.
+2. **Semantic tokens** express intent such as canvas, primary text, danger surface, or focus ring. Themes override this layer.
+3. **Component tokens** express stable component decisions such as button height or control border. They reference semantic or primitive tokens and are re-declared in theme scopes so nested container themes resolve correctly.
+
+Source files live in `tokens/*.json`; `tokens/tokens.css`, `.json`, `.js`, and `.ts` are generated. Schemas in `schemas/` define the accepted source and product-theme contracts.
+
+## CSS layers and entry points
+
+| Entry point | Purpose |
+| --- | --- |
+| `@neuravision/construct/tokens/tokens.css` | Tokens only |
+| `@neuravision/construct/foundations.css` | Network-free reset, typography, and layout utilities |
+| `@neuravision/construct/fonts.css` | Optional hosted-font request; import only with explicit privacy/CSP approval |
+| `@neuravision/construct/components/components.css` | Complete component bundle |
+| `@neuravision/construct/components/<name>.css` | Generated standalone component entry with tokens and shared component contracts |
+| `@neuravision/construct/components/core.css` | Tokens and shared component contracts without a concrete component |
+
+Files under `standalone/` are generated package adapters. Authored component CSS remains in `components/`; it is never copied into a second implementation. This keeps full-bundle and selective-import behavior on one source.
+
+## Behavior layer
+
+Construct CSS styles ARIA and `data-*` state; it cannot implement a focus trap, roving tabindex, typeahead, Escape handling, or focus restoration. The optional `@neuravision/construct/behaviors` ESM entry provides dependency-free controllers for those state machines.
+
+Controllers enhance caller-owned DOM. They synchronize semantics, emit cancellable `ct:before*` and post-change `ct:*` events where relevant, expose programmatic methods, and return a `destroy()` lifecycle. Rendering and product data stay in the application or framework adapter.
+
+Importing the behavior entry has no side effect. A controller starts only when its factory is called, and destroying it restores the attributes it owned.
+
+## Product themes
+
+A product theme is a validated override, not a copy of the generated stylesheet. It names a built-in base, supplies known semantic and/or component paths, and declares any product-specific contrast pairs.
+
+```bash
+npx construct-theme \
+  --theme ./brand.theme.json \
+  --out-dir ./src/generated/construct
+```
+
+The compiler validates schemas, unknown paths, references, complete resolved shapes, selector/value safety, duplicate selectors, typed CSS values, and contrast before writing the same CSS/JSON/JS/TS formats as the built-in build. Keep the theme input under product source control and treat its output as generated.
+
+The consuming stylesheet must load the generated `tokens.css` after foundations and all full or standalone Construct component entries. Those entries include the built-in token sheet; putting the generated theme last gives its root and scoped declarations deterministic precedence. Product-specific overrides may follow it.
+
+## Framework boundary
+
+Framework adapters own references, mount/unmount lifecycle, controlled application state, and rendering. They should initialize a controller after the relevant DOM exists and call `destroy()` during cleanup. They must not reproduce the controller's keyboard or focus logic in parallel.
+
+Construct does not own routing, remote data, authorization, analytics, localization, or product-specific responsive decisions. Components expose explicit slots, attributes, tokens, and controller callbacks so those concerns can remain at the product layer.
+
+## Generated and compatibility files
+
+- Edit token source JSON and run the build; never hand-edit `tokens/tokens.*`.
+- Edit `components/index.css` and authored component files; regenerate `standalone/`.
+- A compatibility entry may import a canonical implementation, but duplicated component implementations are not maintained.
+- Public exports are checked against real files before packaging.
+
+See [Governance and Definition of Done](governance.md) for change ownership, review requirements, and release gates.