@apliteni/apliteni-ui 0.81.0 → 0.84.0

package/guidelines/component-choice.md

@@ -54,6 +54,20 @@
 
 **Don't:** Give those same list filters tab roles when they have no separate panels.
 
+## Group one category at a time
+
+<!-- rule: one-category -->
+
+**Rule:** Give views, filters, sorting and actions separate groups and styles.
+
+**Why:** Identical controls in one bar hide that one of them re-draws every row while its neighbour only narrows them.
+
+**Do:** Keep the filter chips in one bar, the views in a strip of their own, and the action at the right-hand end.
+
+**Don't:** Put three saved views and a filter control in one bar as four buttons of the same size and style.
+
+**Except:** Saved views that re-draw one table take a segmented strip; views that swap panels take tabs.
+
 ## Match confirmation scale
 
 <!-- rule: scale -->

package/guidelines/dense-tables.md

@@ -56,7 +56,7 @@
 
 **Rule:** Keep units smaller and in body ink.
 
-**Do:** Keep units smaller and in body ink, and explain abbreviations in reachable text.
+**Do:** Keep units smaller and in body ink, and explain abbreviations in reachable text. A short value in a stacked row carries its own unit or count word, because the header that named it is no longer on screen.
 
 **Don't:** Hide units in muted text or make readers guess what an abbreviation means.
 
@@ -72,6 +72,8 @@
 
 **Don't:** Squeeze columns until values are unreadable or silently remove data.
 
+**Except:** On a phone, a row whose long column is a paragraph stacks instead of scrolling: the short values on one line, the paragraph under them, and the header kept for screen readers. No column is dropped.
+
 ## Keep updates stable
 
 <!-- rule: states -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.81.0",
+  "version": "0.84.0",
   "workspaces": [
     "react"
   ],

package/react/dist/index.d.ts

@@ -97,11 +97,14 @@ interface StatDelta {
     basis?: string;
     tooltip?: string;
     direction?: 'up' | 'down' | 'flat';
-    none?: string;
 }
 interface StatFigure {
     label: string;
     value: ReactNode;
+    /** Context that is not a change, such as "of revenue": no arrow, no tone. It
+     *  takes the row a change would take, and leads that row beside one. A short
+     *  phrase: the row is one line, and a longer caption is clipped. */
+    caption?: string;
     delta?: StatDelta;
     trend?: ReactNode;
 }

package/react/dist/index.js

@@ -379,17 +379,21 @@ var directionOf = (text2) => {
   return /^[-−–(]/.test(t) ? "down" : /^\+/.test(t) ? "up" : "flat";
 };
 var hasChange = (d) => !!d && d.value != null && d.value !== "";
-function Delta({ delta, basisId }) {
-  if (!hasChange(delta)) {
-    return /* @__PURE__ */ jsx11("dd", { className: "ui-stat__delta ui-stat__delta--none", children: delta.none || "No earlier figure" });
-  }
+function ContextRow({ caption, delta, basisId }) {
+  if (!hasChange(delta)) return caption ? /* @__PURE__ */ jsx11("dd", { className: "ui-stat__caption", children: caption }) : null;
+  const lead = caption ? /* @__PURE__ */ jsxs7(Fragment, { children: [
+    /* @__PURE__ */ jsx11("span", { className: "ui-stat__caption", children: caption }),
+    " "
+  ] }) : null;
   const dir = delta.direction && GLYPH[delta.direction] ? delta.direction : directionOf(delta.value);
-  return /* @__PURE__ */ jsxs7("dd", { className: "ui-stat__delta", "aria-describedby": !delta.basis && basisId ? basisId : void 0, children: [
+  const own = delta.basis || "";
+  return /* @__PURE__ */ jsxs7("dd", { className: "ui-stat__delta", "aria-describedby": !own && basisId ? basisId : void 0, children: [
+    lead,
     /* @__PURE__ */ jsx11(Icon, { name: GLYPH[dir] }),
     delta.tooltip ? /* @__PURE__ */ jsx11(Tooltip, { text: delta.tooltip, children: /* @__PURE__ */ jsx11("span", { className: "ui-stat__change", children: delta.value }) }) : /* @__PURE__ */ jsx11("span", { className: "ui-stat__change", children: delta.value }),
-    delta.basis ? /* @__PURE__ */ jsxs7(Fragment, { children: [
+    own ? /* @__PURE__ */ jsxs7(Fragment, { children: [
       " ",
-      /* @__PURE__ */ jsx11("span", { className: "ui-stat__basis", children: delta.basis })
+      /* @__PURE__ */ jsx11("span", { className: "ui-stat__basis", children: own })
     ] }) : null
   ] });
 }
@@ -406,7 +410,7 @@ function StatBand({ stats, variant = "tiles", basis, basisId: sharedBasisId, lab
       return /* @__PURE__ */ jsxs7("div", { className: cls, children: [
         /* @__PURE__ */ jsx11("dt", { className: "ui-stat__label", children: s.label }),
         /* @__PURE__ */ jsx11("dd", { className: "ui-stat__value", children: s.value }),
-        s.delta ? /* @__PURE__ */ jsx11(Delta, { delta: s.delta, basisId }) : null,
+        /* @__PURE__ */ jsx11(ContextRow, { caption: s.caption, delta: s.delta, basisId }),
         s.trend ? /* @__PURE__ */ jsx11("dd", { className: "ui-stat__trend", children: s.trend }) : null
       ] }, `${s.label}-${i}`);
     }) })

package/src/components/stat.js

@@ -23,23 +23,26 @@ const directionOf = (text) => {
 const GLYPH = { up: 'arrowUp', down: 'arrowDown', flat: 'minus' };
 const hasChange = (delta) => delta && delta.value != null && delta.value !== '';
 
-const deltaHtml = (delta, basisId) => {
-  if (!delta) return '';
-  if (!hasChange(delta)) {
-    return `<dd class="ui-stat__delta ui-stat__delta--none">${esc(delta.none || 'No earlier figure')}</dd>`;
-  }
+// One row and one line: the caption, the change, then what it is measured
+// against. Nothing to compare draws no row. why: docs/specification.md#stat-bands
+const contextRow = (caption, delta, basisId) => {
+  if (!hasChange(delta)) return caption ? `<dd class="ui-stat__caption">${esc(caption)}</dd>` : '';
+  // The space is read where the CSS gap is only drawn: "of income+1.2 pts" else.
+  const lead = caption ? `<span class="ui-stat__caption">${esc(caption)}</span> ` : '';
   const text = String(delta.value);
   const dir = GLYPH[delta.direction] ? delta.direction : directionOf(text);
+  // Never dropped: a basis is passed when the band's caption does not cover this figure.
   const own = delta.basis ? ` <span class="ui-stat__basis">${esc(delta.basis)}</span>` : '';
-  const describedby = !delta.basis && basisId ? ` aria-describedby="${basisId}"` : '';
-  return `<dd class="ui-stat__delta"${describedby}>${icon(GLYPH[dir])}<span class="ui-stat__change">${esc(text)}</span>${own}</dd>`;
+  const describedby = !own && basisId ? ` aria-describedby="${basisId}"` : '';
+  return `<dd class="ui-stat__delta"${describedby}>${lead}${icon(GLYPH[dir])}`
+    + `<span class="ui-stat__change">${esc(text)}</span>${own}</dd>`;
 };
 
 // `tone` says whether the change is good news, and nothing else. It is never
 // inferred from the direction: costs going up and unclassified rows going down
 // are both real, and a band that paints every rise green is editorialising.
 // A figure with no change has no news to colour.
-const figure = ({ label = '', value = '', delta, trend = '' }, tile, basisId) => {
+const figure = ({ label = '', value = '', caption = '', delta, trend = '' }, tile, basisId) => {
   const tone = hasChange(delta) && STAT_TONES.includes(delta.tone) && delta.tone !== 'neutral' ? delta.tone : '';
   const cls = cx('ui-stat', tone && `ui-stat--${tone}`, tile && 'ui-card ui-card--pad-sm');
   // `trend` is trusted markup — an <svg> the caller drew. The kit sizes and
@@ -47,20 +50,15 @@ const figure = ({ label = '', value = '', delta, trend = '' }, tile, basisId) =>
   return `<div class="${cls}">`
     + `<dt class="ui-stat__label">${esc(label)}</dt>`
     + `<dd class="ui-stat__value">${esc(value)}</dd>`
-    + deltaHtml(delta, basisId)
+    + contextRow(caption, delta, basisId)
     + (trend ? `<dd class="ui-stat__trend">${trend}</dd>` : '')
     + '</div>';
 };
 
-// `basis` is the band's caption, said once above the figures: what every change
-// is measured against, or on a band with no changes, what the figures cover. A
-// figure measured against something else carries its own `delta.basis`, printed
-// beside the change.
-//
-// The caption comes before the list, the way a table's <caption> does, in every
-// layout. It is one statement about all the figures, so it is read before them
-// and it sits outside every one of them — under a row of tiles it would read as
-// a note on the last card. why: docs/specification.md#stat-bands
+// `basis` is the band's caption: what every change is measured against, said
+// once before the list the way a table's <caption> is, in every layout — under
+// a row of tiles it would read as a note on the last card.
+// why: docs/specification.md#stat-bands
 export function statBand({ stats = [], variant = 'tiles', basis = '', label, id } = {}) {
   const v = STAT_VARIANTS.includes(variant) ? variant : 'tiles';
   const base = id ? esc(id) : `ui-stats-${++seq}`;

package/src/styles/card.css

@@ -82,7 +82,8 @@
   display: flex;
   align-items: center;
   gap: 10px;
-  margin: 0 0 5px;
+  /* Title to description: the step, not the 5px it was. why: docs/specification.md#spacing-and-rhythm */
+  margin: 0 0 var(--space-2);
 }
 .ui-card__sub {
   color: var(--text);

package/src/styles/stat.css

@@ -49,9 +49,25 @@
   white-space: nowrap;
 }
 
+/* A figure's own words about its value, in the caption rank's size and weight
+   with the band's tighter leading, as the label takes, so it claims no rank.
+   Body ink on no fill; no tone reaches it, having no change to colour. */
+.ui-stat__caption {
+  color: var(--text);
+  font-size: var(--text-sm);
+  font-weight: var(--weight-normal);
+  line-height: var(--leading-snug);
+}
+
+/* Alone it is the row a change would have taken — the same step down and line
+   box — which holds a band of unlike figures on one line. Leading a change it is
+   a span in that row, spaced off what follows. */
+dd.ui-stat__caption { margin-top: var(--space-2); }
+.ui-stat__delta .ui-stat__caption { margin-inline-end: var(--space-1); }
+
 .ui-stat__delta {
   display: flex;
-  flex-wrap: wrap;
+  flex-wrap: nowrap;
   align-items: center;
   gap: 2px var(--space-1);
   margin-top: var(--space-2);
@@ -61,9 +77,21 @@
   line-height: var(--leading-snug);
 }
 .ui-stat__delta svg { width: 14px; height: 14px; flex: none; stroke-width: 2.7; } /* 2.7 of a 24 box drawn at 14px = 1.58 CSS px. docs/specification.md#icons-and-glyphs */
-.ui-stat__change { font-variant-numeric: tabular-nums; white-space: nowrap; }
+.ui-stat__change { font-variant-numeric: tabular-nums; white-space: nowrap; flex: none; }
 .ui-stat__basis { color: var(--text); font-weight: var(--weight-normal); }
-.ui-stat__delta--none { color: var(--text); font-weight: var(--weight-normal); }
+
+/* The change above does not wrap: wrapped, its arrow ends one line and its number
+   starts the next, and a long caption drops its own change below the ones beside
+   it. The arrow and the number cannot give way, so the words clip — the whole
+   string stays in the markup. Only in that row: a caption standing alone has
+   nothing to orphan, so it takes a second line rather than lose words. */
+.ui-stat__delta .ui-stat__caption,
+.ui-stat__basis { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* A figure is never narrower than its content: without these a long line widens it. */
+dd.ui-stat__caption { contain: inline-size; }
+.ui-stat__delta .ui-stat__caption,
+.ui-stat__basis { width: 0; flex-grow: 1; max-width: max-content; }
 
 /* Tone is set by the caller and says good or bad news. Direction is the arrow's
    job, so an unset tone keeps the change neutral whichever way it points. */
@@ -77,14 +105,15 @@
 .ui-stat--good .ui-stat__trend { color: var(--chip-success-ink); }
 .ui-stat--bad .ui-stat__trend { color: var(--chip-danger-ink); }
 
-/* The band's caption, above the figures rather than in one: it is what every
-   change points at, so it sits outside the ranks and takes none of them. The
-   margin is under it because it leads the row. */
+/* The band's caption, above the figures rather than in one: what every change
+   points at. It governs the row, so it takes the caption rank itself and is
+   never set under a caption inside one figure, and its margin is below it. */
 .ui-stats__basis {
   margin: 0 0 var(--space-5);
   color: var(--text);
-  font-size: var(--text-xs);
-  line-height: var(--leading-snug);
+  /* rank: caption */
+  font-size: var(--text-sm);
+  font-weight: var(--weight-normal);
 }
 
 .ui-stats--tiles .ui-stats__list { gap: var(--space-4); }

package/src/styles/table.css

@@ -241,3 +241,68 @@ a.ui-identity:hover { text-decoration: underline; }
 .ui-table--pinned { --ui-table-selection-width: var(--space-12); }
 .ui-table--pinned .ui-table__selection { box-sizing: border-box; width: var(--ui-table-selection-width); min-width: var(--ui-table-selection-width); max-width: var(--ui-table-selection-width); padding-inline: 0; text-align: center; }
 .ui-table--pinned .ui-table__selection + .ui-table__identity { left: var(--ui-table-selection-width); }
+
+/* ============================================================================
+ * Stacked rows at phone width — .ui-table--stack, .ui-table__long
+ *
+ * The cell rules name both .ui-table and the modifier on purpose: --dense, --compact and
+ * __title reach a cell with two classes, and one class would lose to them and leave
+ * `nowrap` on a paragraph.
+ *
+ * The consumer's half — the roles a changed `display` drops — is in the specification.
+ * why: docs/specification.md#dense-financial-tables
+ * held by: src/styles/table-stack.test.js (layout), stories/table-stack.test.js (roles)
+ * ========================================================================== */
+
+/* The marked column holds running text at any width. What the modifier adds below the
+   phone step is the line of its own. */
+.ui-table td.ui-table__long { white-space: normal; }
+
+@media (max-width: 560px) {
+  .ui-table.ui-table--stack { display: block; width: 100%; min-width: 0; padding: 0; }
+  .ui-table.ui-table--stack > thead {
+    position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%);
+  }
+  .ui-table.ui-table--stack > tbody { display: block; }
+  .ui-table.ui-table--stack > tbody > tr {
+    display: flex; flex-wrap: wrap; align-items: baseline;
+    column-gap: var(--space-3); row-gap: var(--space-1);
+    /* The inset is on the row, not the table: the hover outline draws at the row's own
+       edge, so a pad on the table would put the outline back against the text (#71). It is
+       the step a dense cell already pays sideways, so the outline and the row separator keep
+       the clearance they had at the width above this one. */
+    padding: var(--space-3); border-bottom: 1px solid var(--border);
+  }
+  .ui-table.ui-table--stack > tbody > tr:last-child { border-bottom: 0; }
+  /* `height` is in this list for the same reason `white-space` is: --compact sets a row
+     height for a one-line cell, and a block cell takes it as a fixed height rather than a
+     floor, so a wrapped paragraph spills through the separator into the next row. A stacked
+     cell is as tall as its text. */
+  .ui-table.ui-table--stack > tbody > tr > td {
+    display: block; width: auto; min-width: 0; max-width: 100%; height: auto;
+    padding: 0; border-bottom: 0; white-space: normal; overflow-wrap: break-word;
+  }
+  .ui-table.ui-table--stack > tbody > tr > td.ui-table__long { flex: 0 0 100%; text-align: left; }
+  /* A stacked row has no columns left to pin, stick or inset, and the identity's name is
+     what the row is about — the fold hides it only because a pinned column is narrow. */
+  .ui-table.ui-table--stack.ui-table--pinned > :where(thead, tbody) > tr > :where(.ui-table__identity, .ui-table__selection) {
+    position: static; width: auto; min-width: 0; max-width: none;
+    padding-inline: 0; border-right: 0; text-align: left;
+  }
+  .ui-table.ui-table--stack.ui-table--pinned .ui-identity__name {
+    position: static; width: auto; height: auto; max-width: none;
+    overflow: visible; clip-path: none;
+  }
+  /* The bleed now pays for the row's inset instead of the end cells', so the cells still
+     start on the card's own text edge and the outline keeps its room on both sides. Same
+     step, so the arithmetic is the one the sheet already does for a dense table above; these
+     rules exist because a stacked table that is not dense gets no bleed from that one. A
+     scroll wrapper owns the bleed when it is the card's child, and owes one step more than
+     the table does because the wrapper keeps its own --space-1 of focus clearance. */
+  .ui-card > .ui-table--stack {
+    width: calc(100% + 2 * var(--space-3)); margin-inline: calc(-1 * var(--space-3));
+  }
+  .ui-card > .ui-table-scroll:has(> .ui-table--stack) {
+    margin-inline: calc(-1 * var(--space-4));
+  }
+}