@apliteni/apliteni-ui 0.113.0 → 0.115.0

package/src/components/dropdown.js

@@ -384,6 +384,45 @@ function ddResetSearch(dd, panel, search) {
  * fails when one drifts. why: src/styles/dropdown.css */
 export const DD_MENU_FLOOR = 240;
 
+/** The floor a panel asks for in the sheet, or null. A separate name from the
+ *  floor this fit writes back: one that read its own output would pin a menu at
+ *  whatever a narrow row once allowed. why: src/styles/filter-bar.css */
+function ddPanelAsk(panel) {
+  const view = panel?.ownerDocument?.defaultView;
+  if (!panel || typeof view?.getComputedStyle !== 'function') return null;
+  const asked = Number.parseFloat(view.getComputedStyle(panel).getPropertyValue('--ui-filter-panel-ask'));
+  return Number.isFinite(asked) && asked > 0 ? asked : null;
+}
+
+/** The `.ui-dropdown__panel` inside a dropdown, by class rather than by data
+ *  attribute: the fit's subjects are the panels the stylesheet's rules match, and
+ *  filter-panel-fit.test.js hands this function hand-made elements. */
+const ddFitPanelOf = (dd) => (typeof dd?.querySelector === 'function'
+  ? dd.querySelector('.ui-dropdown__panel') : null);
+
+/**
+ * The filter row an anchored menu is measured inside, or null outside one.
+ *
+ * Two panels in a row are anchored at a trigger of their own: a chip's values, and
+ * the add control's catalogue, which says so by asking for a width. The slide
+ * filterPanelFit() computes is measured from that trigger's offset along the row,
+ * which is arithmetic for either. A panel anchored to the row itself is neither,
+ * and sizes itself.
+ *
+ * Published because `<Dropdown>` asks the same question — the same row to observe,
+ * the same panels to hold through a close — and a second copy of this rule would
+ * drift from the stylesheet. why: src/styles/filter-bar.css
+ *
+ * @param {Element} dd a `.ui-dropdown` that may be inside a filter row
+ * @returns {Element|null} the `.ui-filter-bar` this menu's fit is measured in
+ */
+export function filterPanelRow(dd) {
+  if (typeof dd?.closest !== 'function') return null;
+  const chip = dd.closest('.ui-filter-bar__chip');
+  if (chip) return chip.closest('.ui-filter-bar');
+  return ddPanelAsk(ddFitPanelOf(dd)) ? dd.closest('.ui-filter-bar') : null;
+}
+
 /**
  * Where a filter chip's menu may sit. #484 bounds the panel to its trigger, so a
  * chip printing its value alone (#536) left a 48px menu breaking words
@@ -396,23 +435,23 @@ export const DD_MENU_FLOOR = 240;
  * other way. Measuring an end-anchored panel forwards put one off the page.
  * why: docs/components.md#a-filter-row-holds-its-panels
  *
+ * A menu that is not a chip's takes this arithmetic by asking, on its own panel,
+ * for a width: `--ui-filter-panel-ask`. why: src/styles/filter-bar.css
+ *
  * @param {Element} dd a `.ui-dropdown` that may be inside a filter row
- * @param {number} [floor] the width to reach for
+ * @param {number} [floor] the width to reach for; the panel's own ask, else the kit's
  * @returns {{room: number, shift: number, floor: number, end: boolean}|null}
  */
-export function filterPanelFit(dd, floor = DD_MENU_FLOOR) {
-  /* A chip's menu, not any menu in a filter row: the slide below is measured from
-   * the trigger's offset along the row, so a panel anchored to the row itself is
-   * not this function's subject and must size itself. why: src/styles/filter-bar.css */
-  const chip = typeof dd?.closest === 'function' ? dd.closest('.ui-filter-bar__chip') : null;
-  const bar = chip ? chip.closest('.ui-filter-bar') : null;
+export function filterPanelFit(dd, floor) {
+  const panel = ddFitPanelOf(dd);
+  // Which menus are this function's subjects is filterPanelRow()'s question.
+  const bar = filterPanelRow(dd);
   if (!bar || typeof bar.getBoundingClientRect !== 'function') return null;
   const row = bar.getBoundingClientRect();
   const box = dd.getBoundingClientRect();
-  const panel = typeof dd.querySelector === 'function' ? dd.querySelector('.ui-dropdown__panel') : null;
   const end = !!panel?.classList?.contains('is-end');
   // A row narrower than the floor decides the width; nothing may leave the row.
-  const want = Math.min(floor, row.width);
+  const want = Math.min(floor ?? ddPanelAsk(panel) ?? DD_MENU_FLOOR, row.width);
   const ahead = end
     ? Math.max(0, box.right - row.left)    // an end-anchored panel grows backwards
     : Math.max(0, row.right - box.left);
@@ -466,11 +505,6 @@ function ddRefitFilterPanel(dd, panel) {
   if (panel.offsetWidth) panel.style.minWidth = `${panel.offsetWidth}px`;
 }
 
-/** The row this chip's menu is fitted to, or null outside one. */
-function ddRowOf(dd) {
-  return dd?.closest?.('.ui-filter-bar__chip')?.closest('.ui-filter-bar') || null;
-}
-
 /** Is this node inside some dropdown panel? Both fits write to a panel and to
  *  nothing else, so a change inside one is never news — and a panel is
  *  `position: absolute`, so nothing in it can move a chip along its row. Any
@@ -501,7 +535,7 @@ function ddOurs(node) {
  */
 function ddWatchRow(dd, panel) {
   ddUnwatchRow(dd);
-  const row = ddRowOf(dd);
+  const row = filterPanelRow(dd);
   const view = dd.ownerDocument?.defaultView;
   if (!row) return;
   const refit = () => { if (dd.classList.contains('open')) ddRefitFilterPanel(dd, panel); };
@@ -619,7 +653,7 @@ const DD_EXIT_SLACK_MS = 50;
 const DD_SETTLE_MS = 450;
 
 /**
- * Hold a closing chip menu's open geometry until its fade has finished.
+ * Hold a closing anchored menu's open geometry until its fade has finished.
  *
  * `.open` stops matching in the frame the menu closes; the fade does not — the
  * panel transitions opacity over --dur-med. Dropping the width there left a 240px
@@ -823,10 +857,10 @@ function closeDropdown(dd) {
   /* A search panel carries the width it was opened at as an inline `min-width`,
    * and inline beats any sheet. Inside a filter row that leaves a SHUT panel wider
    * than its trigger, which is #467. Cleared here, and ddResetSearch() writes it
-   * again on the next open — except for a chip's menu, which gives the pin and the
-   * fit back at the END of its fade, both being its open geometry. A portalled
+   * again on the next open — except for an anchored menu, which gives the pin and
+   * the fit back at the END of its fade, both being its open geometry. A portalled
    * panel is never fitted, so it has none to hold. why: ddHoldClose() */
-  if (panel?.style && !dd.__ddPanel && ddRowOf(dd)) ddHoldClose(dd, panel);
+  if (panel?.style && !dd.__ddPanel && filterPanelRow(dd)) ddHoldClose(dd, panel);
   else if (panel?.style && dd.closest?.('.ui-filter-bar')) panel.style.minWidth = '';
   dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'false');
   /* The anchor may have moved while the panel was open, and a shut panel is laid

package/src/components/filter-bar.js

@@ -2,7 +2,7 @@ import { button, esc } from './index.js';
 import { dropdown, wireDropdown } from './dropdown.js';
 import { filterChipText, filterChipName, filterChipUnset, filterChipItems, focusNextStop } from '../logic/filter-bar.js';
 
-export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear all filters', disabled = false, busy = false } = {}) {
+export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear all', disabled = false, busy = false } = {}) {
   return `<fieldset class="ui-filter-bar" data-filter-bar${disabled || busy ? ' disabled' : ''}${busy ? ' aria-busy="true"' : ''}>`
     + `<legend class="ui-filter-bar__legend">${esc(label)}</legend>`
     + filters.map(filter => `<fieldset class="ui-filter-bar__chip" data-filter-id="${esc(filter.id)}"${filter.disabled ? ' disabled' : ''}>`
@@ -21,7 +21,7 @@ export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear
     // live action beside two chips has to read as live.
     // why: docs/components.md#a-filter-row-holds-its-panels
     + (filters.length
-      ? `<span data-filter-clear>${button({ label: clearLabel, size: 'sm' })}</span>`
+      ? `<span data-filter-clear>${button({ label: clearLabel, size: 'sm', variant: 'ghost' })}</span>`
       : '')
     + '</fieldset>';
 }
@@ -58,7 +58,10 @@ export function initFilterBar(host, options = {}) {
     const chip = e.target.closest('[data-filter-id]');
     if (e.target.closest('[data-filter-remove]')) emit('ui-filter-remove', { id: chip.dataset.filterId });
     else if (e.target.closest('[data-filter-clear] button')) emit('ui-filter-clear', {});
-    else if (e.target.closest('[data-dd-item]')) {
+    // A chip's menu only. The catalogue a vanilla page draws under `data-filter-add` is the
+    // page's own, and a pick in it names no chip: reported as a change, it had a consumer
+    // mapping over its filters and writing the catalogue's value into every one of them. #518
+    else if (e.target.closest('[data-dd-item]') && !e.target.closest('[data-filter-add]')) {
       const item = e.target.closest('[data-dd-item]');
       if (item.getAttribute('aria-disabled') !== 'true') {
         const id = chip?.dataset.filterId, value = item.dataset.value;

package/src/index.css

@@ -36,6 +36,7 @@
 @import "./styles/filter-bar.css";
 @import "./styles/pagination.css";
 @import "./styles/stat.css";
+@import "./styles/chart.css";
 @import "./styles/empty.css";
 @import "./styles/callout.css";
 @import "./styles/code.css";

package/src/index.d.ts

@@ -43,12 +43,18 @@ export declare function dropdownAvail(opts: {
 }): number;
 /** The kit's menu floor, the width `.ui-dropdown__panel` writes. */
 export declare const DD_MENU_FLOOR: number;
-/** Where a filter chip's open menu can sit: the room from the edge it is
- *  anchored at to the far side of its row once slid, how far it had to slide,
- *  the width it reached for, and whether it is anchored at its inline end.
- *  `null` unless the dropdown is inside a `.ui-filter-bar__chip`: the slide is a
- *  chip's offset along its row, so a panel anchored to the row itself is not this
- *  function's subject and sizes itself. why: docs/components.md */
+/** The `.ui-filter-bar` an anchored menu's fit is measured inside, or `null`.
+ *  A chip's menu, and a menu that asks for a width with `--ui-filter-panel-ask` on
+ *  its own panel: the slide is that trigger's offset along the row, so those two
+ *  are the subjects and a panel anchored to the row itself sizes itself.
+ *  why: docs/components.md */
+export declare function filterPanelRow(dd: Element | null | undefined): Element | null;
+/** Where an anchored filter menu can sit: the room from the edge it is anchored
+ *  at to the far side of its row once slid, how far it had to slide, the width it
+ *  reached for, and whether it is anchored at its inline end. `null` for a
+ *  dropdown `filterPanelRow()` does not answer for. The width reached for is
+ *  `floor`, else the panel's own `--ui-filter-panel-ask`, else `DD_MENU_FLOOR`.
+ *  why: docs/components.md */
 export declare function filterPanelFit(
   dd: Element | null | undefined,
   floor?: number,
@@ -86,6 +92,24 @@ export type NumericValueOptions = { value?: string | number | null; unit?: strin
 export type DeltaValueOptions = { value?: string | null; tone?: 'success' | 'danger' | 'neutral'; basisId?: string; missing?: string };
 export declare function formatNumericValue(options?: NumericValueOptions): { text: string; unit: string; missing: string | undefined };
 export declare function formatDeltaValue(options?: DeltaValueOptions): { text: string; className: string; basisId: string | undefined };
+
+/** The smallest band a series is drawn in, as a share of its own reach. */
+export declare const CHART_FLOOR: number;
+export type ChartScaleOptions = { ticks?: number; zero?: boolean; floor?: number; nice?: boolean };
+export type ChartScale = { min: number; max: number; step: number; ticks: number[] };
+export declare function chartScale(values: Iterable<number>, options?: ChartScaleOptions): ChartScale;
+export type BridgeStepInput = { label: string; value?: number; kind?: 'total' | 'change' };
+export type BridgeBar<S> = S & { kind: 'total' | 'change'; value: number; from: number; to: number };
+export declare function bridgeWalk<S extends BridgeStepInput>(steps: Iterable<S>): BridgeBar<S>[];
+export type ChartBox = { left: number; right: number; top: number; bottom: number };
+export type PointTargetLimits = {
+  floor: number; min?: number; box: ChartBox;
+  column: [number, number]; apart?: Iterable<number>;
+};
+export type ChartTarget = { x: number; y: number; w: number; h: number };
+export declare function pointTarget(
+  point: { x: number; y: number }, limits: PointTargetLimits,
+): ChartTarget;
 export declare const SCORE: Record<'exact' | 'prefix' | 'wordStart' | 'contains' | 'keyword' | 'description' | 'subsequence', number>;
 export declare const iconNames: string[];
 export declare const iconCategories: { name: string; names: string[] }[];

package/src/index.js

@@ -35,3 +35,4 @@ export { PAGE_SIZES, DEFAULT_PAGE_SIZE } from './logic/pagination.js';
 export { calloutIcons } from './logic/callout.js';
 export { formatNumericValue, formatDeltaValue } from './logic/table-values.js';
 export { accentSwatchStyle } from './logic/accents.js';
+export { CHART_FLOOR, chartScale, bridgeWalk, pointTarget } from './logic/chart.js';

package/src/inline.js

@@ -50,6 +50,7 @@ export const styles = {
   filterBar: read('styles/filter-bar.css'),
   pagination: read('styles/pagination.css'),
   stat: read('styles/stat.css'),
+  chart: read('styles/chart.css'),
   empty: read('styles/empty.css'),
   callout: read('styles/callout.css'),
   code: read('styles/code.css'),
@@ -86,6 +87,7 @@ export const cssText = [
   styles.filterBar,
   styles.pagination,
   styles.stat,
+  styles.chart,
   styles.empty,
   styles.callout,
   styles.code,

package/src/logic/chart.js

@@ -0,0 +1,143 @@
+// Chart arithmetic, shared by the React Chart and by anything that draws the
+// same shapes without it. No DOM, no pixels: a scale and a walk, both pure.
+// why: docs/components.md#react-charts
+
+/** The steps a whole-unit axis may take, per decade, smallest first. 2.5 is
+ *  among them — 25000 is a whole step and the one that turns a four-tick axis
+ *  into four ticks — but it is taken only where it lands on a whole number, so
+ *  nothing below the units decade can put 2.5 on an axis. */
+const STEPS = [1, 2, 2.5, 5, 10];
+
+/** The smallest band a series is drawn in, as a share of its own reach. Below
+ *  this, a series that barely moves would be stretched into a cliff. */
+export const CHART_FLOOR = 0.25;
+
+const round = (n) => Math.round(n * 1e6) / 1e6;
+
+/** The smallest nice step at or above `raw` that is a whole unit. */
+function niceStep(raw) {
+  if (!(raw > 0)) return 1;
+  const decade = 10 ** Math.floor(Math.log10(raw));
+  for (const s of STEPS) {
+    const step = round(s * decade);
+    if (step >= raw - 1e-9 && step >= 1 && Number.isInteger(step)) return step;
+  }
+  return Math.max(1, Math.ceil(raw));
+}
+
+/**
+ * The band a series is drawn in, and the ticks written beside it.
+ *
+ * @param {Iterable<number>} values every number that has to fit
+ * @param {object} [options]
+ * @param {number} [options.ticks] how many steps to aim for
+ * @param {boolean} [options.zero] keep the zero line inside the band — true for
+ *   bars, which are read from zero, false for a line read against itself
+ * @param {number} [options.floor] the smallest band, as a share of the series'
+ *   own reach; `CHART_FLOOR` for a sparkline
+ * @param {boolean} [options.nice] round the band out to whole steps and return
+ *   them; false for a chart with no axis
+ * @returns {{min: number, max: number, step: number, ticks: number[]}}
+ */
+export function chartScale(values, { ticks = 4, zero = true, floor = 0, nice = true } = {}) {
+  const finite = [...values].filter((v) => Number.isFinite(v));
+  if (finite.length === 0) return { min: 0, max: 1, step: 1, ticks: [0, 1] };
+
+  let min = Math.min(...finite);
+  let max = Math.max(...finite);
+  if (zero) { min = Math.min(min, 0); max = Math.max(max, 0); }
+
+  const reach = Math.max(Math.abs(min), Math.abs(max)) || 1;
+  const want = reach * floor;
+  if (max - min < want) {
+    const pad = (want - (max - min)) / 2;
+    min -= pad;
+    max += pad;
+    if (zero) { min = Math.min(min, 0); max = Math.max(max, 0); }
+  }
+  if (min === max) { min -= 0.5; max += 0.5; }
+
+  if (!nice) return { min: round(min), max: round(max), step: 0, ticks: [] };
+
+  const step = niceStep((max - min) / Math.max(ticks, 1));
+  min = Math.floor(round(min / step)) * step;
+  max = Math.ceil(round(max / step)) * step;
+  const out = [];
+  for (let t = min; t <= max + 1e-9; t += step) out.push(round(t));
+  return { min: round(min), max: round(max), step, ticks: out };
+}
+
+/**
+ * One period walked from a starting total through its components to a result.
+ *
+ * The first step is a total unless it says otherwise; every later step is a
+ * component added to the running total. A step marked `total` with no value of
+ * its own takes the running total, which is how the closing column is written
+ * without repeating a sum the caller already gave piece by piece.
+ *
+ * @param {Iterable<{label: string, value?: number, kind?: 'total'|'change'}>} steps
+ * @returns {Array<{label: string, kind: 'total'|'change', value: number, from: number, to: number}>}
+ *   each column's own amount and the two ends of the bar that draws it
+ */
+export function bridgeWalk(steps) {
+  let running = 0;
+  return [...steps].map((step, index) => {
+    const kind = step.kind || (index === 0 ? 'total' : 'change');
+    if (kind === 'total') {
+      const value = Number.isFinite(step.value) ? step.value : running;
+      running = value;
+      return { ...step, kind, value: round(value), from: 0, to: round(value) };
+    }
+    const value = Number.isFinite(step.value) ? step.value : 0;
+    const from = running;
+    running += value;
+    return { ...step, kind, value: round(value), from: round(from), to: round(running) };
+  });
+}
+
+const clamp = (v, lo, hi) => Math.min(Math.max(v, lo), hi);
+
+/**
+ * The pointer target over one drawn point, as a rectangle.
+ *
+ * A point is a mark a pointer has to reach rather than a control, so its target
+ * is a transparent box laid over it. The box grows to the floor this pointer
+ * asks for, stops at half the clear space to the nearest point on each side,
+ * and is then held inside the box the chart draws in — a target that reached
+ * past the chart's edge would be clipped there, and a nominal 44 that a
+ * drawing clips to 19 is not a target. `min` is the floor it keeps where the
+ * column has room. A narrower column owns the whole column instead, so no point
+ * answers for the period beside it.
+ * why: guidelines/accessibility-floor.md#tap-target-on-a-phone
+ *
+ * @param {{x: number, y: number}} point the point's centre
+ * @param {object} limits
+ * @param {number} limits.floor the target this pointer asks for, each way
+ * @param {number} [limits.min] the smallest target, where the column has room
+ * @param {{left: number, right: number, top: number, bottom: number}} limits.box
+ *   the chart's own drawn box, which nothing may reach past
+ * @param {[number, number]} limits.column the point's own column, left and right
+ * @param {Iterable<number>} [limits.apart] the centre, down, of every other
+ *   point in the same column
+ * @returns {{x: number, y: number, w: number, h: number}}
+ */
+export function pointTarget({ x, y }, { floor, min = floor, box, column, apart = [] }) {
+  const fit = (centre, [outerLo, outerHi], [spaceLo, spaceHi], neighbours) => {
+    let lo = spaceLo;
+    let hi = spaceHi;
+    for (const n of neighbours) {
+      const mid = (centre + n) / 2;
+      if (n < centre) lo = Math.max(lo, mid);
+      if (n > centre) hi = Math.min(hi, mid);
+    }
+    const size = Math.min(floor, Math.max(0, hi - lo));
+    // Centred on the point, then held inside the space it may own, then inside
+    // the chart's box. The box is last so the point on the chart's own edge
+    // keeps a whole target instead of half of one.
+    const owned = clamp(centre - size / 2, lo, Math.max(lo, hi - size));
+    return { at: clamp(owned, outerLo, Math.max(outerLo, outerHi - size)), size };
+  };
+  const across = fit(x, [box.left, box.right], column, []);
+  const down = fit(y, [box.top, box.bottom], [box.top, box.bottom], apart);
+  return { x: across.at, y: down.at, w: across.size, h: down.size };
+}

package/src/logic/filter-bar.js

@@ -67,37 +67,55 @@ function stopsAround(host) {
     ...order.filter(el => host.compareDocumentPosition(el) & PRECEDING).reverse()];
 }
 
-/** The control a reader's next Tab would reach from `host`: forward in document
- *  order, else the nearest one behind it. A filter bar that has just dropped its
- *  last control keeps no box the focus ring can sit on, so the focus has to
- *  leave the bar rather than land on a line with no height.
+/** The bar `host` is, or the one inside it. */
+function barIn(host) {
+  if (!host || typeof host.matches !== 'function') return null;
+  return host.matches('[data-filter-bar]') ? host : host.querySelector('[data-filter-bar]');
+}
+
+/** Where an emptied bar hands the focus, in the order it tries: the way to add one
+ *  still drawn on the row, which outlives the chips and so is nearer than anything
+ *  outside, then the controls around the bar. The answer a consumer reads and the
+ *  move the bar makes both come from here, so the two cannot disagree. A control
+ *  the reader cannot reach is left out of the list. #518 */
+function focusStops(host) {
+  const bar = barIn(host);
+  const add = bar && !bar.querySelector('[data-filter-id]')
+    && bar.querySelector('[data-filter-add] [data-dropdown-trigger]');
+  const around = stopsAround(host);
+  return add && !unreachable(add) ? [add, ...around] : around;
+}
+
+/** Where an emptied bar sends the focus, without moving it: the way to add one
+ *  still on its row, else the control a reader's next Tab would reach — forward in
+ *  document order, else the nearest one behind. A bar that has just dropped its
+ *  last chip keeps no box the focus ring can sit on, so with no control of its own
+ *  left the focus has to leave rather than land on a line with no height.
+ *  `focusNextStop()` acts on this same list.
  *  why: docs/components.md#a-filter-row-holds-its-panels */
 export function nextFocusStop(host) {
-  return stopsAround(host)[0] || null;
+  return focusStops(host)[0] || null;
 }
 
 /** Puts the focus where an emptied bar hands it on, and answers with the element
  *  it ended on, or null if nothing took it.
  *
- *  A bar that still holds chips draws a box around them, so it takes the focus
- *  itself, made focusable for that moment. Emptied, it has only an out-of-flow
- *  legend left and measures 0 high, so the focus goes to the first control
- *  outside it that will have it — on the Stock screener the caller's own
- *  `Add filter`, in the React Finance composition the view strip's chosen tab.
- *
- *  Being reachable is not the same as taking the focus: a control can be visible
- *  and enabled and still refuse, so each candidate is asked and then checked, and
- *  the next one tried.
+ *  A bar that still holds chips draws a box around them and takes the focus
+ *  itself. Emptied of them it has only an out-of-flow legend and measures 0 high,
+ *  so the focus goes where `nextFocusStop()` names — the way to add one still on
+ *  the row, which is what the Stock screener draws, else outside the bar.
+ *  Being reachable is not taking the focus: each candidate is asked and then
+ *  checked. #518
  *  why: docs/components.md#a-filter-row-holds-its-panels */
 export function focusNextStop(host) {
   const doc = host && host.ownerDocument;
   if (!doc) return null;
-  const bar = host.matches('[data-filter-bar]') ? host : host.querySelector('[data-filter-bar]');
+  const bar = barIn(host);
   if (bar && bar.querySelector('[data-filter-id]')) {
     bar.tabIndex = -1; bar.focus();
     return doc.activeElement === bar ? bar : null;
   }
-  for (const stop of stopsAround(host)) {
+  for (const stop of focusStops(host)) {
     stop.focus();
     if (doc.activeElement === stop) return stop;
   }