rcf-lite 0.28.4 → 0.29.0

package/src/view/components/doc-row.js

@@ -0,0 +1,62 @@
+// Shared DocRow collapsible (viewer UI refresh PR 2, decision 2 / w-
+// 2026-10-02-dave-010): one markup shape for every per-document row on
+// every list tab (REQ, US, TAC, ADR, FBS). Closed by default, hidden-
+// by-filter via `[hidden]`, deep-link-navigable via `data-doc-id` and
+// the raw document id as the anchor.
+//
+// Shape:
+//   <details class="rcf-row doc-row {className}" data-doc-id="{id}" [open]>
+//     <summary>
+//       <span class="id">{id}</span>
+//       <span class="title">{title}</span>
+//       <span class="meta">{meta badges / pill}</span>
+//     </summary>
+//     <div class="rcf-row-body body">
+//       {body}
+//     </div>
+//   </details>
+//
+// The .doc-row prefix lets later tab-side migrations (PR 3-6) swap
+// `detailsWrap` for `renderDocRow` while leaving the existing CSS
+// selectors (`details.doc-details`) alone until each tab lands. PR 2
+// ships the markup and the matching .rcf-row stylesheet rules; no tab
+// is cut over here. The fixture page (/_fixtures/components) is where
+// the component is exercised in isolation.
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+
+/**
+ * @param {object} args
+ * @param {string} args.id                    display doc id (e.g. "REQ-002")
+ * @param {string} args.title                 one-line label (right of the id)
+ * @param {string} [args.body]                rendered body HTML (empty for a header-only row)
+ * @param {string} [args.className]           extra class applied to the <details>
+ * @param {boolean} [args.open]               initial open state (default: closed)
+ * @param {string} [args.dataDocId]           override the id used for `data-doc-id` (defaults to args.id)
+ * @param {string} [args.meta]                pre-rendered meta HTML (badges + pill) shown right of the title
+ * @returns {string}
+ */
+export function renderDocRow({
+  id,
+  title,
+  body = '',
+  className = '',
+  open = false,
+  dataDocId,
+  meta = '',
+}) {
+  const classes = ['rcf-row', 'doc-row'];
+  if (className) classes.push(String(className));
+  const openAttr = open ? ' open' : '';
+  const anchorId = dataDocId ?? id;
+  return `<details class="${classes.join(' ')}" data-doc-id="${escapeHtml(anchorId)}"${openAttr}>
+  <summary>
+    <span class="id">${escapeHtml(id)}</span>
+    <span class="title">${escapeHtml(title ?? '')}</span>
+    ${meta ? `<span class="meta">${meta}</span>` : ''}
+  </summary>
+  <div class="rcf-row-body body">
+    ${body}
+  </div>
+</details>`;
+}

package/src/view/components/empty-state.js

@@ -0,0 +1,35 @@
+// Shared EmptyState (viewer UI refresh PR 2, design doc section 4):
+// one dashed-outline, muted-text block for "nothing here yet" cases
+// across every tab (Architecture section without content, a Needs-work
+// table with no rows, a filter that excludes every item, etc).
+//
+// Shape:
+//   <div class="rcf-empty-state empty" role="status">
+//     <p class="rcf-empty-state-title">{title}</p>
+//     [<p class="rcf-empty-state-hint">{hint}</p>]
+//     [<p class="rcf-empty-state-action">{actionHtml}</p>]
+//   </div>
+//
+// `hint` is plain text; `actionHtml` is an escape hatch for the one
+// case the design calls out (an authoring CLI call under a missing TAD
+// section) and must already be safe HTML - callers that pass raw user
+// text should use `hint` instead.
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+
+/**
+ * @param {object} args
+ * @param {string} args.title
+ * @param {string} [args.hint]
+ * @param {string} [args.actionHtml]
+ * @returns {string}
+ */
+export function renderEmptyState({ title, hint, actionHtml }) {
+  const hintBlock = hint ? `<p class="rcf-empty-state-hint">${escapeHtml(hint)}</p>` : '';
+  const actionBlock = actionHtml ? `<p class="rcf-empty-state-action">${actionHtml}</p>` : '';
+  return `<div class="rcf-empty-state empty" role="status">
+    <p class="rcf-empty-state-title">${escapeHtml(title)}</p>
+    ${hintBlock}
+    ${actionBlock}
+  </div>`;
+}

package/src/view/components/entity-selector.js

@@ -0,0 +1,137 @@
+// Shared EntitySelector (viewer UI refresh PR 3, decision 4): replaces
+// the PRD's 109 inline requirement links with a compact header showing
+// the total, a type-ahead jump input, and a row of area chips with
+// counts that deep-link into the Requirements tab filtered by domain.
+// Pure HTML string helper; the type-ahead behaviour (filter the list,
+// Enter to jump) is wired by page-init.js.
+//
+// Markup shape:
+//
+//   <div class="rcf-entity-selector" data-rcf-entity-selector="requirements"
+//        data-tab="requirements">
+//     <div class="rcf-entity-selector-head">
+//       <span class="rcf-entity-selector-total">109 requirements in 21 areas</span>
+//     </div>
+//     <div class="rcf-entity-selector-jump">
+//       <input class="rcf-entity-selector-input" type="search"
+//              placeholder="..." autocomplete="off"
+//              aria-label="Jump to a requirement by id or title">
+//       <div class="rcf-entity-selector-results" hidden></div>
+//     </div>
+//     <div class="rcf-entity-selector-facets" aria-label="Areas">
+//       <a class="rcf-entity-selector-chip" href="#tab=requirements&domain=platform"
+//          data-facet-key="domain" data-facet-value="platform">
+//         platform <span class="rcf-badge rcf-badge--count"><span class="rcf-badge-value">17</span></span>
+//       </a>
+//       ...
+//     </div>
+//   </div>
+//
+// The payload (every entity's id, title, facet value) is serialised
+// onto the root `<div>` as a `data-items` attribute (JSON, HTML-escaped)
+// so the jump input can filter without a network call. The container
+// carries all state so the shell page has no inline `<script>` body
+// (PR 1 contract, decision 10).
+// Decision 11 names `#entity=<id>` as the deep link target so a jump
+// writes `#tab=<targetTab>&entity=<id>` (preserving the host query via
+// the existing urlWithHash helper).
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+import { renderBadge } from './badge.js';
+
+/**
+ * @typedef {object} EntitySelectorItem
+ * @property {string} id              document id (e.g. "REQ-002")
+ * @property {string} title           display title
+ * @property {string} [facet]         facet value (e.g. "platform")
+ */
+
+/**
+ * @typedef {object} EntitySelectorFacet
+ * @property {string} value           facet value (e.g. "platform")
+ * @property {number} count           count of items in this facet
+ * @property {string} [label]         optional display label (defaults to value)
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.hashKey                            selector slot name (e.g. "requirements")
+ * @param {string} args.targetTab                          tab name used in hash writes (e.g. "requirements")
+ * @param {string} args.facetKey                           hash key for area chips (e.g. "domain")
+ * @param {EntitySelectorItem[]} args.items                every entity (for the jump input)
+ * @param {EntitySelectorFacet[]} [args.facets]            ordered facet chips (if omitted, derived from items)
+ * @param {string} [args.totalLabel]                       pre-rendered total line (e.g. "109 requirements in 21 areas")
+ * @param {string} [args.placeholder]                      input placeholder
+ * @param {string} [args.chipsLabel]                       muted lead-in above the chip row
+ * @returns {string}
+ */
+export function renderEntitySelector({
+  hashKey,
+  targetTab,
+  facetKey,
+  items,
+  facets,
+  totalLabel,
+  placeholder = 'Jump to an entity by id or title',
+  chipsLabel = 'By area (click to open the tab filtered):',
+}) {
+  const safeItems = Array.isArray(items) ? items : [];
+  const resolvedFacets = Array.isArray(facets) && facets.length > 0
+    ? facets
+    : deriveFacets(safeItems);
+  const total = totalLabel
+    ?? `${safeItems.length} ${safeItems.length === 1 ? 'item' : 'items'} in ${resolvedFacets.length} ${resolvedFacets.length === 1 ? 'area' : 'areas'}`;
+
+  const chipBlocks = resolvedFacets.map((f) => {
+    const label = f.label ?? f.value;
+    const hash = `#tab=${encodeURIComponent(targetTab)}&${encodeURIComponent(facetKey)}=${encodeURIComponent(f.value)}`;
+    const count = renderBadge({ value: f.count, variant: 'count' });
+    return `<a class="rcf-entity-selector-chip" href="${escapeHtml(hash)}" data-facet-key="${escapeHtml(facetKey)}" data-facet-value="${escapeHtml(f.value)}"><span class="rcf-entity-selector-chip-label">${escapeHtml(label)}</span> ${count}</a>`;
+  }).join('\n        ');
+
+  const payload = JSON.stringify(safeItems.map((it) => ({
+    id: it.id,
+    title: it.title ?? '',
+    facet: it.facet ?? '',
+  })));
+  // The payload rides on the container as a `data-items` attribute.
+  // escapeHtml encodes `&`, `<`, `>`, `"` and `'` so the attribute
+  // boundary cannot be broken by any id, title or facet value, and
+  // no `<script>` element is emitted (PR 1 "no inline script body").
+  const itemsAttr = escapeHtml(payload);
+
+  return `<div class="rcf-entity-selector" data-rcf-entity-selector="${escapeHtml(hashKey)}" data-target-tab="${escapeHtml(targetTab)}" data-facet-key="${escapeHtml(facetKey)}" data-items="${itemsAttr}">
+      <div class="rcf-entity-selector-head">
+        <span class="rcf-entity-selector-total">${escapeHtml(total)}</span>
+      </div>
+      <div class="rcf-entity-selector-jump">
+        <input class="rcf-entity-selector-input" type="search" placeholder="${escapeHtml(placeholder)}" autocomplete="off" aria-label="${escapeHtml(placeholder)}">
+        <div class="rcf-entity-selector-results" hidden role="listbox"></div>
+      </div>
+      <div class="rcf-entity-selector-facets-lead muted small">${escapeHtml(chipsLabel)}</div>
+      <div class="rcf-entity-selector-facets" aria-label="Areas">
+        ${chipBlocks}
+      </div>
+    </div>`;
+}
+
+/**
+ * Derive facet chips (value + count) from the item list when the caller
+ * does not pass an explicit facet order. Facets sort by count desc,
+ * then by value asc. Items with an empty facet are dropped.
+ *
+ * @param {EntitySelectorItem[]} items
+ * @returns {EntitySelectorFacet[]}
+ */
+function deriveFacets(items) {
+  const counts = new Map();
+  for (const it of items) {
+    const v = it.facet;
+    if (typeof v !== 'string' || v.length === 0) continue;
+    counts.set(v, (counts.get(v) ?? 0) + 1);
+  }
+  const out = [];
+  for (const [value, count] of counts.entries()) out.push({ value, count });
+  out.sort((a, b) => (b.count - a.count) || a.value.localeCompare(b.value));
+  return out;
+}

package/src/view/components/filter-bar.js

@@ -0,0 +1,97 @@
+// Shared FilterBar (viewer UI refresh PR 2, decision 3): sticky bar
+// under the tabstrip with a text query, facet selects, toggles, a live
+// row count and an Expand / Collapse all control. Filter state lives
+// in the hash so a filtered view is a link; the hashKey argument lets
+// each tab own its own slice of the hash namespace (e.g. "requirements"
+// writes #tab=requirements&q=...&area=...).
+//
+// Markup shape:
+//
+//   <div class="rcf-filterbar filterbar" data-rcf-filterbar="{hashKey}">
+//     <input type="search" class="rcf-filter-text" placeholder="...">
+//     <select class="rcf-filter-select" data-filter-key="area">...</select>
+//     <label class="rcf-filter-toggle">
+//       <input type="checkbox" data-filter-key="needsWork"> Needs work
+//     </label>
+//     <span class="rcf-filter-count count">N of M visible</span>
+//     <button type="button" class="rcf-filter-expand linkish">Expand all</button>
+//   </div>
+//
+// PR 2 ships the markup helper only; the hash-sync + list-filter wiring
+// lives in page-init.js and ships with the first list tab that adopts
+// FilterBar (PR 3, Requirements). The helper is pure HTML and has no
+// behaviour of its own, so a later tab can mount it without a Router
+// handshake.
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+
+/**
+ * @typedef {object} FilterSelectSpec
+ * @property {string} key                   facet key (e.g. "area", "status")
+ * @property {string} label                 visible label
+ * @property {Array<{ value: string, label: string }>} options
+ * @property {string} [value]               initial selected value
+ */
+
+/**
+ * @typedef {object} FilterToggleSpec
+ * @property {string} key                   toggle key (e.g. "needsWork")
+ * @property {string} label                 visible label
+ * @property {boolean} [checked]            initial state
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.hashKey                              owning tab, used as the hash namespace
+ * @param {string} [args.placeholder]                        text input placeholder
+ * @param {string} [args.text]                               initial text value
+ * @param {FilterSelectSpec[]} [args.selects]
+ * @param {FilterToggleSpec[]} [args.toggles]
+ * @param {{ visible: number, total: number }} [args.count]  initial count readout
+ * @param {boolean} [args.showExpandAll]                     render the Expand / Collapse control
+ * @returns {string}
+ */
+export function renderFilterBar({
+  hashKey,
+  placeholder = 'Search this list',
+  text = '',
+  selects = [],
+  toggles = [],
+  count,
+  showExpandAll = true,
+}) {
+  const selectBlocks = selects.map((s) => {
+    const options = (s.options ?? []).map((o) => {
+      const selected = o.value === s.value ? ' selected' : '';
+      return `<option value="${escapeHtml(o.value)}"${selected}>${escapeHtml(o.label)}</option>`;
+    }).join('');
+    return `<label class="rcf-filter-label">
+      <span>${escapeHtml(s.label)}</span>
+      <select class="rcf-filter-select" data-filter-key="${escapeHtml(s.key)}">${options}</select>
+    </label>`;
+  }).join('\n    ');
+
+  const toggleBlocks = toggles.map((t) => {
+    const checked = t.checked ? ' checked' : '';
+    return `<label class="rcf-filter-toggle">
+      <input type="checkbox" data-filter-key="${escapeHtml(t.key)}"${checked}>
+      <span>${escapeHtml(t.label)}</span>
+    </label>`;
+  }).join('\n    ');
+
+  const countBlock = count
+    ? `<span class="rcf-filter-count count">${escapeHtml(String(count.visible))} of ${escapeHtml(String(count.total))} visible</span>`
+    : '';
+
+  const expandBlock = showExpandAll
+    ? `<button type="button" class="rcf-filter-expand linkish" data-expand-state="collapsed">Expand all</button>`
+    : '';
+
+  return `<div class="rcf-filterbar filterbar" data-rcf-filterbar="${escapeHtml(hashKey)}">
+    <input type="search" class="rcf-filter-text" value="${escapeHtml(text)}" placeholder="${escapeHtml(placeholder)}">
+    ${selectBlocks}
+    ${toggleBlocks}
+    ${countBlock}
+    ${expandBlock}
+  </div>`;
+}

package/src/view/components/findings-list.js

@@ -0,0 +1,49 @@
+// Shared findings-list component (REQ-181, TAC-4127-readiness-view).
+// Renders a heading with a count badge plus an unordered list of
+// `{ id, why, href? }` items. Ids are capped at 20, and the tail
+// becomes a `... N more suppressed` line so a huge failing list stays
+// legible. Pure; no I/O. (AC-18101-2.)
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+
+/**
+ * @typedef {object} FindingsListItem
+ * @property {string} id - document id (also the anchor label)
+ * @property {string} [why] - one-line reason
+ * @property {string} [href] - override anchor target; defaults to `#<id>`
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.heading - section heading text (plain)
+ * @param {number} args.count - the total count to show in the badge
+ *   (may exceed `items.length`; the component renders the suppressed
+ *   tail from the delta)
+ * @param {FindingsListItem[]} args.items - items to render (will be
+ *   capped at the display limit)
+ * @returns {string}
+ */
+export function findingsList({ heading, count, items }) {
+  const cap = 20;
+  const list = Array.isArray(items) ? items : [];
+  const total = typeof count === 'number' && Number.isFinite(count) ? count : list.length;
+  const shown = list.slice(0, cap);
+  const liHtml = shown.map((item) => {
+    const id = String(item?.id ?? '');
+    const anchorHref = typeof item?.href === 'string' && item.href.length > 0
+      ? item.href
+      : `#${id}`;
+    const why = typeof item?.why === 'string' && item.why.length > 0
+      ? `: ${escapeHtml(item.why)}`
+      : '';
+    return `<li><a href="${escapeHtml(anchorHref)}">${escapeHtml(id)}</a>${why}</li>`;
+  }).join('');
+  const suppressedCount = Math.max(0, total - shown.length);
+  const suppressedLi = suppressedCount > 0
+    ? `<li class="rcf-findings-list__suppressed"><em>... ${suppressedCount} more suppressed</em></li>`
+    : '';
+  return `<div class="rcf-findings-list">`
+    + `<h4>${escapeHtml(heading)} <span class="rcf-findings-list__count">${total}</span></h4>`
+    + `<ul>${liHtml}${suppressedLi}</ul>`
+    + `</div>`;
+}

package/src/view/components/index.js

@@ -0,0 +1,12 @@
+// Shared component barrel (viewer UI refresh PR 2). Re-exports every
+// per-component string helper so downstream tabs can import a single
+// well-known path. New components added in later PRs land here too.
+
+export { pill } from './pill.js';
+export { renderDocRow } from './doc-row.js';
+export { renderBadge } from './badge.js';
+export { renderFilterBar } from './filter-bar.js';
+export { renderEmptyState } from './empty-state.js';
+export { renderToastContainer } from './toast.js';
+export { renderSubTabStrip } from './sub-tab-strip.js';
+export { renderEntitySelector } from './entity-selector.js';

package/src/view/components/pill.js

@@ -0,0 +1,46 @@
+// Shared pill component (REQ-181, TAC-4127-readiness-view). One module,
+// one markup shape: `<span class="rcf-pill rcf-pill--<variant>
+// rcf-pill--<normalisedValue>" [title?]>{value}</span>`, or an `<a>`
+// with the same classes when `href` is passed. The vocabulary families
+// (gate state / level verdict / persona / AC class) all ride the same
+// shape so a status reads the same on every tab (AC-18101-1).
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+
+/**
+ * Normalise a value into a kebab-cased class suffix: lowercased with
+ * `/`, whitespace and `_` collapsed to `-`. Everything outside
+ * `[a-z0-9-]` is stripped. The caller controls what the display label
+ * reads; this only touches the class suffix.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normaliseValue(raw) {
+  const s = String(raw ?? '').toLowerCase().replace(/[\s/_]+/g, '-');
+  return s.replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.value - display label (also drives the class suffix)
+ * @param {string} args.variant - vocabulary family (e.g. `gate-state`,
+ *   `level-verdict`, `persona`, `ac-class`). Also normalised into the
+ *   class suffix for the family.
+ * @param {string} [args.title] - optional tooltip text
+ * @param {string} [args.href] - optional href; when set, renders an `<a>`
+ * @returns {string}
+ */
+export function pill({ value, variant, title, href }) {
+  const valueText = String(value ?? '');
+  const variantClass = `rcf-pill--${normaliseValue(variant)}`;
+  const valueClass = `rcf-pill--${normaliseValue(valueText)}`;
+  const classes = `rcf-pill ${variantClass} ${valueClass}`.trim();
+  const titleAttr = typeof title === 'string' && title.length > 0
+    ? ` title="${escapeHtml(title)}"`
+    : '';
+  if (typeof href === 'string' && href.length > 0) {
+    return `<a class="${classes}" href="${escapeHtml(href)}"${titleAttr}>${escapeHtml(valueText)}</a>`;
+  }
+  return `<span class="${classes}"${titleAttr}>${escapeHtml(valueText)}</span>`;
+}

package/src/view/components/sub-tab-strip.js

@@ -0,0 +1,43 @@
+// Shared SubTabStrip (viewer UI refresh PR 2, design doc section 4):
+// the one-row chip strip that sits inside a tab panel and switches
+// sub-views (Build tab's Specs | DAG in PR 5-6). Writes `sub=` into
+// the owning tab's hash slot via the `hashKey` argument; the Router
+// in page-init.js owns the read.
+//
+// Markup shape:
+//   <nav class="rcf-subtabs subtabs" aria-label="Sub-sections"
+//        data-rcf-subtabstrip="{hashKey}">
+//     <button type="button" role="tab" data-sub="{item.key}"
+//             aria-selected="true|false">{item.label}</button>
+//     ...
+//   </nav>
+
+import { escapeHtml } from '../doc-renderers/helpers.js';
+
+/**
+ * @typedef {object} SubTabItem
+ * @property {string} key                   value written into `sub=`
+ * @property {string} label
+ * @property {string} [controls]            optional id of the panel this item controls
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.hashKey             owning tab (e.g. "build")
+ * @param {SubTabItem[]} args.items
+ * @param {string} [args.active]            key of the item to mark as active
+ * @returns {string}
+ */
+export function renderSubTabStrip({ hashKey, items, active }) {
+  const effectiveActive = active ?? (items[0]?.key ?? '');
+  const buttons = items.map((item) => {
+    const isActive = item.key === effectiveActive;
+    const controlsAttr = item.controls
+      ? ` aria-controls="${escapeHtml(item.controls)}"`
+      : '';
+    return `<button type="button" role="tab" data-sub="${escapeHtml(item.key)}"${controlsAttr} aria-selected="${isActive ? 'true' : 'false'}">${escapeHtml(item.label)}</button>`;
+  }).join('\n    ');
+  return `<nav class="rcf-subtabs subtabs" role="tablist" aria-label="Sub-sections" data-rcf-subtabstrip="${escapeHtml(hashKey)}">
+    ${buttons}
+  </nav>`;
+}

package/src/view/components/toast.js

@@ -0,0 +1,25 @@
+// Shared Toast container (viewer UI refresh PR 2, design doc section 4):
+// a single bottom-centred transient message block that lives in the
+// AppShell. PR 2 ships the container markup and a tiny vanilla showToast
+// helper on `window.rcfView`. The container is empty on first paint;
+// the helper writes the text, flips the `.show` class, auto-hides after
+// a brief delay and clears the content.
+//
+// Shape (uses <output> rather than <div> so the Phase 3.8 D13a
+// `lastIndexOf("</div>")` live-content wrapper check in
+// test/view/html-page.test.js stays unambiguous; <output> carries the
+// implicit role="status" we need anyway):
+//
+//   <output class="rcf-toast toast" aria-live="polite" aria-atomic="true"
+//           data-toast></output>
+//
+// Idempotent client wiring is in page-init.js; the container is
+// rendered once by the AppShell so the SSE innerHTML swap (which
+// replaces #rcf-live-content only) does not blow it away.
+
+/**
+ * @returns {string}
+ */
+export function renderToastContainer() {
+  return '<output class="rcf-toast toast" aria-live="polite" aria-atomic="true" data-toast></output>';
+}