panelui-native 0.66.1 → 0.71.0

package/lib/module/components/meter/meter-scale.js

@@ -0,0 +1,142 @@
+"use strict";
+
+/**
+ * Where a reading sits on a meter's scale, and what colour it has earned.
+ *
+ * Kept apart from the component because it is the part that can be wrong
+ * without looking wrong: a threshold picked in the wrong order, or a segment
+ * count that rounds a real reading down to nothing, is a meter that lies
+ * quietly. None of it touches React, so it can be tested on its own.
+ */
+
+/** The token a meter can be painted with. */
+
+/**
+ * A point on the scale, and the colour the meter takes from there upwards.
+ *
+ * `from` is in the same units as `value` — not a percentage of the range — so
+ * a threshold on a 0–8 GB meter is written in gigabytes.
+ */
+
+/** A bounded block count keeps malformed input from allocating without limit. */
+export const MAX_METER_SEGMENTS = 100;
+/**
+ * Make a public scale safe for layout, animation and native accessibility.
+ * Invalid bounds fall back to their documented defaults; if those still do
+ * not produce a positive span, the scale honestly collapses at its floor.
+ */
+export function normalizeScale(value, min, max) {
+  const floor = Number.isFinite(min) ? min : 0;
+  const candidateMax = Number.isFinite(max) ? max : 100;
+  const ceiling = candidateMax > floor ? candidateMax : floor;
+  const held = Number.isNaN(value) ? floor : value === Number.POSITIVE_INFINITY ? ceiling : value === Number.NEGATIVE_INFINITY ? floor : Math.min(Math.max(value, floor), ceiling);
+  const magnitude = Math.max(Math.abs(floor), Math.abs(ceiling), 1);
+  const position = ceiling > floor ? (held / magnitude - floor / magnitude) / (ceiling / magnitude - floor / magnitude) : 0;
+  return {
+    min: floor,
+    max: ceiling,
+    value: held,
+    fraction: Math.min(Math.max(position, 0), 1)
+  };
+}
+
+/** Positive counts are whole and bounded; zero means the continuous meter. */
+export function normalizeSegments(segments) {
+  if (segments == null || !Number.isFinite(segments) || !(segments > 0)) return 0;
+  return Math.min(Math.floor(segments), MAX_METER_SEGMENTS);
+}
+
+/** `value` held inside the scale, so a stray number cannot escape the track. */
+export function clamp(value, min, max) {
+  return normalizeScale(value, min, max).value;
+}
+
+/**
+ * How far up the scale the value sits, 0–1. An empty or inverted range has no
+ * meaningful position in it, so it reads as empty rather than dividing by zero.
+ */
+export function fractionOf(value, min, max) {
+  return normalizeScale(value, min, max).fraction;
+}
+
+/**
+ * The colour the reading has earned: the highest threshold at or below the
+ * value, or the base colour when it has reached none of them.
+ *
+ * Highest-wins rather than first-wins, so the caller can list thresholds in
+ * any order and get the same answer. A rule that depended on the order would
+ * make a reordered array a silent behaviour change.
+ */
+export function colorFor(value, base, thresholds) {
+  if (!thresholds?.length) return base;
+  let winner;
+  for (const threshold of thresholds) {
+    if (!Number.isFinite(threshold.from)) continue;
+    if (value < threshold.from) continue;
+    if (!winner || threshold.from > winner.from) winner = threshold;
+  }
+  return winner?.color ?? base;
+}
+
+/**
+ * How many blocks of a segmented meter are lit.
+ *
+ * Rounded up, so any reading above the floor lights at least one. Rounding
+ * down would leave the whole first block of a four-block meter dark, and "a
+ * little" looking like "none" is the reading a meter can least afford to get
+ * wrong.
+ */
+export function litSegments(fraction, segments) {
+  const count = normalizeSegments(segments);
+  if (count === 0 || Number.isNaN(fraction) || fraction <= 0) return 0;
+  if (!Number.isFinite(fraction) || fraction >= 1) return count;
+  return Math.min(Math.ceil(fraction * count), count);
+}
+
+/**
+ * The value caption: an explicit override, an `Intl` rendering, or a rounded
+ * percent.
+ *
+ * A `percent` style is given the fraction, because that is what a percentage
+ * of the scale means; every other style is given the value, because a byte
+ * count or a score is a quantity and not a proportion.
+ */
+export function formatValue(value, fraction, valueLabel, formatOptions) {
+  if (valueLabel != null) return valueLabel;
+  if (formatOptions) {
+    try {
+      return new Intl.NumberFormat(undefined, formatOptions).format(formatOptions.style === 'percent' ? fraction : value);
+    } catch {
+      // Some engines ship a partial Intl; fall through to the plain percent.
+    }
+  }
+  return `${Math.round(fraction * 100)}%`;
+}
+
+/**
+ * The meter's single spoken contract. Visual treatments such as segments,
+ * thresholds and motion do not belong here: they do not change the reading.
+ */
+export function meterSemantics({
+  value,
+  fraction,
+  minValue,
+  maxValue,
+  label,
+  accessibilityLabel,
+  valueLabel,
+  formatOptions
+}) {
+  const text = formatValue(value, fraction, valueLabel, formatOptions);
+  return {
+    label: accessibilityLabel ?? label,
+    text,
+    value: {
+      min: minValue,
+      max: maxValue,
+      now: value,
+      text
+    }
+  };
+}
+//# sourceMappingURL=meter-scale.js.map

package/lib/module/components/meter/meter-scale.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["MAX_METER_SEGMENTS","normalizeScale","value","min","max","floor","Number","isFinite","candidateMax","ceiling","held","isNaN","POSITIVE_INFINITY","NEGATIVE_INFINITY","Math","magnitude","abs","position","fraction","normalizeSegments","segments","clamp","fractionOf","colorFor","base","thresholds","length","winner","threshold","from","color","litSegments","count","ceil","formatValue","valueLabel","formatOptions","Intl","NumberFormat","undefined","format","style","round","meterSemantics","minValue","maxValue","label","accessibilityLabel","text","now"],"sourceRoot":"../../../../src","sources":["components/meter/meter-scale.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AASA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA,OAAO,MAAMA,kBAAkB,GAAG,GAAG;AASrC;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAACC,KAAa,EAAEC,GAAW,EAAEC,GAAW,EAAc;EAClF,MAAMC,KAAK,GAAGC,MAAM,CAACC,QAAQ,CAACJ,GAAG,CAAC,GAAGA,GAAG,GAAG,CAAC;EAC5C,MAAMK,YAAY,GAAGF,MAAM,CAACC,QAAQ,CAACH,GAAG,CAAC,GAAGA,GAAG,GAAG,GAAG;EACrD,MAAMK,OAAO,GAAGD,YAAY,GAAGH,KAAK,GAAGG,YAAY,GAAGH,KAAK;EAC3D,MAAMK,IAAI,GAAGJ,MAAM,CAACK,KAAK,CAACT,KAAK,CAAC,GAC5BG,KAAK,GACLH,KAAK,KAAKI,MAAM,CAACM,iBAAiB,GAChCH,OAAO,GACPP,KAAK,KAAKI,MAAM,CAACO,iBAAiB,GAChCR,KAAK,GACLS,IAAI,CAACX,GAAG,CAACW,IAAI,CAACV,GAAG,CAACF,KAAK,EAAEG,KAAK,CAAC,EAAEI,OAAO,CAAC;EACjD,MAAMM,SAAS,GAAGD,IAAI,CAACV,GAAG,CAACU,IAAI,CAACE,GAAG,CAACX,KAAK,CAAC,EAAES,IAAI,CAACE,GAAG,CAACP,OAAO,CAAC,EAAE,CAAC,CAAC;EACjE,MAAMQ,QAAQ,GACZR,OAAO,GAAGJ,KAAK,GACX,CAACK,IAAI,GAAGK,SAAS,GAAGV,KAAK,GAAGU,SAAS,KACpCN,OAAO,GAAGM,SAAS,GAAGV,KAAK,GAAGU,SAAS,CAAC,GACzC,CAAC;EACP,OAAO;IACLZ,GAAG,EAAEE,KAAK;IACVD,GAAG,EAAEK,OAAO;IACZP,KAAK,EAAEQ,IAAI;IACXQ,QAAQ,EAAEJ,IAAI,CAACX,GAAG,CAACW,IAAI,CAACV,GAAG,CAACa,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;EAC7C,CAAC;AACH;;AAEA;AACA,OAAO,SAASE,iBAAiBA,CAACC,QAA4B,EAAE;EAC9D,IAAIA,QAAQ,IAAI,IAAI,IAAI,CAACd,MAAM,CAACC,QAAQ,CAACa,QAAQ,CAAC,IAAI,EAAEA,QAAQ,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC;EAC/E,OAAON,IAAI,CAACX,GAAG,CAACW,IAAI,CAACT,KAAK,CAACe,QAAQ,CAAC,EAAEpB,kBAAkB,CAAC;AAC3D;;AAEA;AACA,OAAO,SAASqB,KAAKA,CAACnB,KAAa,EAAEC,GAAW,EAAEC,GAAW,EAAE;EAC7D,OAAOH,cAAc,CAACC,KAAK,EAAEC,GAAG,EAAEC,GAAG,CAAC,CAACF,KAAK;AAC9C;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASoB,UAAUA,CAACpB,KAAa,EAAEC,GAAW,EAAEC,GAAW,EAAE;EAClE,OAAOH,cAAc,CAACC,KAAK,EAAEC,GAAG,EAAEC,GAAG,CAAC,CAACc,QAAQ;AACjD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASK,QAAQA,CACtBrB,KAAa,EACbsB,IAA4B,EAC5BC,UAAwC,EACxC;EACA,IAAI,CAACA,UAAU,EAAEC,MAAM,EAAE,OAAOF,IAAI;EACpC,IAAIG,MAAkC;EACtC,KAAK,MAAMC,SAAS,IAAIH,UAAU,EAAE;IAClC,IAAI,CAACnB,MAAM,CAACC,QAAQ,CAACqB,SAAS,CAACC,IAAI,CAAC,EAAE;IACtC,IAAI3B,KAAK,GAAG0B,SAAS,CAACC,IAAI,EAAE;IAC5B,IAAI,CAACF,MAAM,IAAIC,SAAS,CAACC,IAAI,GAAGF,MAAM,CAACE,IAAI,EAAEF,MAAM,GAAGC,SAAS;EACjE;EACA,OAAOD,MAAM,EAAEG,KAAK,IAAIN,IAAI;AAC9B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASO,WAAWA,CAACb,QAAgB,EAAEE,QAAgB,EAAE;EAC9D,MAAMY,KAAK,GAAGb,iBAAiB,CAACC,QAAQ,CAAC;EACzC,IAAIY,KAAK,KAAK,CAAC,IAAI1B,MAAM,CAACK,KAAK,CAACO,QAAQ,CAAC,IAAIA,QAAQ,IAAI,CAAC,EAAE,OAAO,CAAC;EACpE,IAAI,CAACZ,MAAM,CAACC,QAAQ,CAACW,QAAQ,CAAC,IAAIA,QAAQ,IAAI,CAAC,EAAE,OAAOc,KAAK;EAC7D,OAAOlB,IAAI,CAACX,GAAG,CAACW,IAAI,CAACmB,IAAI,CAACf,QAAQ,GAAGc,KAAK,CAAC,EAAEA,KAAK,CAAC;AACrD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,WAAWA,CACzBhC,KAAa,EACbgB,QAAgB,EAChBiB,UAAmB,EACnBC,aAAwC,EACxC;EACA,IAAID,UAAU,IAAI,IAAI,EAAE,OAAOA,UAAU;EACzC,IAAIC,aAAa,EAAE;IACjB,IAAI;MACF,OAAO,IAAIC,IAAI,CAACC,YAAY,CAACC,SAAS,EAAEH,aAAa,CAAC,CAACI,MAAM,CAC3DJ,aAAa,CAACK,KAAK,KAAK,SAAS,GAAGvB,QAAQ,GAAGhB,KACjD,CAAC;IACH,CAAC,CAAC,MAAM;MACN;IAAA;EAEJ;EACA,OAAO,GAAGY,IAAI,CAAC4B,KAAK,CAACxB,QAAQ,GAAG,GAAG,CAAC,GAAG;AACzC;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASyB,cAAcA,CAAC;EAC7BzC,KAAK;EACLgB,QAAQ;EACR0B,QAAQ;EACRC,QAAQ;EACRC,KAAK;EACLC,kBAAkB;EAClBZ,UAAU;EACVC;AAUF,CAAC,EAAE;EACD,MAAMY,IAAI,GAAGd,WAAW,CAAChC,KAAK,EAAEgB,QAAQ,EAAEiB,UAAU,EAAEC,aAAa,CAAC;EACpE,OAAO;IACLU,KAAK,EAAEC,kBAAkB,IAAID,KAAK;IAClCE,IAAI;IACJ9C,KAAK,EAAE;MAAEC,GAAG,EAAEyC,QAAQ;MAAExC,GAAG,EAAEyC,QAAQ;MAAEI,GAAG,EAAE/C,KAAK;MAAE8C;IAAK;EAC1D,CAAC;AACH","ignoreList":[]}