@ponchia/ui 0.6.0 → 0.6.4

package/css/textref.css

@@ -0,0 +1,63 @@
+/* ==========================================================================
+   textref — opt-in deep-link-to-the-cited-sentence provenance primitive.
+
+   A citation that jumps to the EXACT quoted text. The link's href is a URL
+   Text Fragment (`#…:~:text=`); the browser scrolls to the match and highlights
+   it for free, and Bronto owns the on-brand `::target-text` paint. The inline
+   counterpart to the static `ui-src` / `ui-citation` trust layer (sources.css),
+   which can label a source but not point inside it. Pure CSS + a host-built URL,
+   no kernel, SSR-static. Not imported by core.css.
+
+   Boundary: the HOST builds the fragment URL and sets it as the link's href.
+   The encoder is a three-line pure function (see docs/textref.md) — Bronto does
+   not ship runtime here, it owns the affordance class + the highlight paint.
+   `::target-text` is global by design: any text-fragment landing on the page
+   gets the brand highlight once this leaf is imported. On engines without Text
+   Fragments the link still navigates to the section; the highlight is additive.
+   ========================================================================== */
+
+.ui-textref {
+  --textref-highlight: var(--accent-soft);
+
+  color: var(--accent-text);
+  text-decoration: underline;
+  text-decoration-style: dotted;
+  text-underline-offset: 0.2em;
+}
+
+/* A small leading caret signals "this jumps to the quoted text", distinct from
+   a plain external link. currentColor only — no raw paint. */
+.ui-textref::before {
+  content: '\201F'; /* double high-reversed-9 quote — a quote-jump cue */
+  margin-inline-end: 0.15em;
+}
+
+@media (hover: hover) {
+  .ui-textref:hover {
+    text-decoration-style: solid;
+  }
+}
+
+.ui-textref:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+
+/* The browser-painted highlight on the matched fragment. Scoped to the page
+   the link lands on; the accent-soft wash is the same rationed-accent surface
+   the rest of the trust layer uses. `--textref-highlight` lets a host retune it
+   per-surface. */
+::target-text {
+  background-color: var(--textref-highlight, var(--accent-soft));
+  color: var(--text);
+}
+
+/* Forced colours: the accent wash collapses to the system surface and the match
+   would be invisible — repaint with the system selection colours so the jump
+   target still reads. */
+@media (forced-colors: active) {
+  ::target-text {
+    background-color: Highlight;
+    color: HighlightText;
+  }
+}

package/css/toc.css

@@ -0,0 +1,91 @@
+/* ==========================================================================
+   toc — opt-in scrollspy table-of-contents rail for long reports.
+
+   A sticky contents list whose entry for the section currently in view is
+   highlighted, so a reader of a long generated report always knows where they
+   are. Long-document orientation, on the generated-reports pillar. Degrades to a
+   plain anchored list with zero JS. Not imported by core.css.
+
+   Boundary: the HOST owns the section IDs and the anchor list; Bronto owns the
+   rail's classes + the active treatment. The active state keys on the standard
+   `aria-current="true"` hook. CSS alone cannot know which section is in view, so
+   the host mirrors the in-view section onto its link's `aria-current` — either
+   statically (server-rendered "current page") or with a small IntersectionObserver
+   (~15 lines, copy-paste recipe in docs/toc.md). No Bronto kernel ships for it;
+   the rail is fully useful as a static sticky list without the observer.
+   ========================================================================== */
+
+.ui-toc {
+  --toc-top: var(--space-md);
+
+  align-self: start;
+  font-family: var(--mono);
+  font-size: var(--text-xs);
+  inset-block-start: var(--toc-top);
+  letter-spacing: var(--tracking-wide);
+  position: sticky;
+}
+
+/* An optional eyebrow heading for the rail. */
+.ui-toc__title {
+  color: var(--text-dim);
+  font-size: var(--text-2xs);
+  margin-block-end: var(--space-xs);
+  text-transform: uppercase;
+}
+
+.ui-toc__list {
+  display: grid;
+  gap: 1px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+/* Nested lists indent for sub-sections. */
+.ui-toc__list .ui-toc__list {
+  margin-inline-start: var(--space-sm);
+}
+
+.ui-toc__link {
+  border-inline-start: 2px solid var(--line);
+  color: var(--text-dim);
+  display: block;
+  padding: 0.3rem var(--space-sm);
+  text-decoration: none;
+  transition: color var(--duration-fast) var(--ease-standard);
+}
+
+/* The section in view. Keys on `aria-current` (the framework rule every other
+   nav surface here uses) so a host that sets only aria-current still lights up. */
+.ui-toc__link[aria-current]:not([aria-current='false']) {
+  border-inline-start-color: var(--accent);
+  color: var(--accent-text);
+}
+
+.ui-toc__link:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: -2px;
+}
+
+@media (hover: hover) {
+  .ui-toc__link:hover:not([aria-current]:not([aria-current='false'])) {
+    color: var(--text);
+  }
+}
+
+/* Forced colours: the accent border + text collapse to the system surface and
+   the active entry loses its only cue — re-assert with the system highlight. */
+@media (forced-colors: active) {
+  .ui-toc__link[aria-current]:not([aria-current='false']) {
+    border-inline-start-color: Highlight;
+    color: Highlight;
+  }
+}
+
+/* Reduced motion: drop the colour transition. */
+@media (prefers-reduced-motion: reduce) {
+  .ui-toc__link {
+    transition: none;
+  }
+}

package/css/tokens.css

@@ -327,15 +327,28 @@
    prints dark-on-white instead of light-grey text or a dark panel on white.
    Lives here, in the exempt tier-definition file, because it is a token-value
    override (ADR-0001), not component styling. CSS-only, like the presets above.
+
+   Selector is `:root:root:root` (specificity 0,3,0), not a bare `:root`: a media
+   query adds NO specificity, so a bare `:root` (0,1,0) loses the cascade to the
+   on-screen dark palette at `:root[data-theme='dark']` (0,2,0) and the OLED
+   surface at `:root[data-theme='dark'][data-surface='oled']` (0,3,0) — i.e. a
+   dark-mode user would print a near-black `.ui-card` on white paper, the exact
+   opposite of what this block promises. Tripling `:root` matches the OLED rule's
+   specificity and wins on source order (this block is last), so the remap also
+   beats the `prefers-color-scheme: dark` blocks. Neutralise the OLED-only dark
+   surfaces (--bg / --bg-elevated / --panel-strong) too, or they'd leak through.
    -------------------------------------------------------------------------- */
 @media print {
-  :root {
+  :root:root:root {
     color-scheme: light;
 
     --text: #111;
     --text-soft: #2a2a2a;
     --text-dim: #555;
+    --bg: #fff;
+    --bg-elevated: #fff;
     --panel: #fff;
+    --panel-strong: #fff;
     --panel-soft: #f7f7f7;
     --line: #d9d9d9;
     --line-strong: #b3b3b3;

package/css/tree.css

@@ -0,0 +1,134 @@
+/* ==========================================================================
+   tree — opt-in hierarchy outline on nested native <details name> disclosures.
+
+   A depth-indented outline for hierarchies: file trees, report contents, nested
+   generated-content provenance, object graphs. Built on nested native
+   `<details>` (optionally `name` exclusive-accordion groups) so open/close,
+   keyboard toggling and animation come from the platform — this leaf is the
+   hierarchy LAYER (rails, indent, chevron), it does NOT reinvent the disclosure
+   grammar that `ui-accordion` already owns. Pure CSS, SSR-static. Not imported
+   by core.css.
+
+   Boundary: the HOST owns the nesting and the labels. A11y honesty — a native
+   `<details>` group is a disclosure group, NOT an ARIA `tree`; do not bolt on
+   `role="tree"`/`treeitem` without the roving-focus keyboard model it implies.
+   That kernel is intentionally NOT shipped here; it lands behind a real consumer
+   (see docs/tree.md). The visuals below work on the full browser floor with zero
+   JS.
+   ========================================================================== */
+
+.ui-tree {
+  color: var(--text);
+  font-family: var(--mono);
+  font-size: var(--text-sm);
+  line-height: 1.5;
+}
+
+/* A branch is a <details>; a leaf is a plain row with no disclosure. Both are
+   rows in the outline. */
+.ui-tree__branch,
+.ui-tree__leaf {
+  display: block;
+}
+
+/* Nested rows indent and carry a hairline guide rail back to their parent. */
+.ui-tree__branch .ui-tree__branch,
+.ui-tree__branch .ui-tree__leaf {
+  border-inline-start: 1px solid var(--line);
+  margin-inline-start: 0.5rem;
+  padding-inline-start: var(--space-sm);
+}
+
+/* The summary is the clickable branch row; reset the native marker, lay it out
+   as label + twist. */
+.ui-tree__summary {
+  align-items: center;
+  cursor: pointer;
+  display: flex;
+  gap: var(--space-2xs);
+  list-style: none;
+  padding-block: var(--space-2xs);
+}
+
+.ui-tree__summary::-webkit-details-marker {
+  display: none;
+}
+
+/* Twist chevron — a currentColor caret that rotates open. */
+.ui-tree__summary::before {
+  block-size: 0.4rem;
+  border-block-end: 1.5px solid var(--text-dim);
+  border-inline-end: 1.5px solid var(--text-dim);
+  content: '';
+  flex: 0 0 auto;
+  inline-size: 0.4rem;
+  transform: rotate(-45deg);
+  transition: transform var(--duration-fast) var(--ease-spring);
+}
+
+.ui-tree__branch[open] > .ui-tree__summary::before {
+  border-color: var(--accent);
+  transform: rotate(45deg);
+}
+
+.ui-tree__branch[open] > .ui-tree__summary {
+  color: var(--accent-text);
+}
+
+/* A leaf has no chevron; align its label with branch labels via a spacer the
+   width of the chevron + gap. */
+.ui-tree__leaf {
+  align-items: center;
+  display: flex;
+  gap: var(--space-2xs);
+  padding-block: var(--space-2xs);
+}
+
+.ui-tree__leaf::before {
+  content: '';
+  flex: 0 0 auto;
+  inline-size: 0.4rem;
+}
+
+.ui-tree__label {
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Auto-height open/close, gated exactly like ui-accordion (Chrome 131+/Safari
+   18.4+; Firefox snaps). Strict progressive enhancement + reduced-motion. */
+@supports selector(::details-content) {
+  @media (prefers-reduced-motion: no-preference) {
+    .ui-tree {
+      interpolate-size: allow-keywords;
+    }
+
+    .ui-tree__branch::details-content {
+      block-size: 0;
+      overflow: hidden;
+      transition:
+        block-size var(--duration-base) var(--ease-out),
+        content-visibility var(--duration-base) allow-discrete;
+    }
+
+    .ui-tree__branch[open]::details-content {
+      block-size: auto;
+    }
+  }
+}
+
+/* Reduced motion: no chevron spin. */
+@media (prefers-reduced-motion: reduce) {
+  .ui-tree__summary::before {
+    transition: none;
+  }
+}
+
+/* Forced colours: keep the open branch distinguishable when accent flattens. */
+@media (forced-colors: active) {
+  .ui-tree__branch[open] > .ui-tree__summary::before {
+    border-color: Highlight;
+  }
+}