@carto/ps-react-ui 4.18.0 → 4.20.0

package/src/widgets-v2/spread/band.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { getSpreadBand } from './band'
+
+describe('getSpreadBand', () => {
+  it('reads `spread` as a percentage of the centre value by default', () => {
+    expect(getSpreadBand({ value: 1000, spread: 5 })).toEqual({
+      min: 950,
+      max: 1050,
+    })
+  })
+
+  it('reads `spread` as a percentage when asked explicitly', () => {
+    expect(
+      getSpreadBand({ value: 204_113, spread: 5, variant: 'percentage' }),
+    ).toEqual({ min: 193_907.35, max: 214_318.65 })
+  })
+
+  it('reads `spread` as raw units when the caller opts into `absolute`', () => {
+    expect(
+      getSpreadBand({ value: 204_113, spread: 5, variant: 'absolute' }),
+    ).toEqual({ min: 204_108, max: 204_118 })
+  })
+
+  it('collapses to the centre value when `spread` is 0', () => {
+    expect(getSpreadBand({ value: 42, spread: 0 })).toEqual({
+      min: 42,
+      max: 42,
+    })
+  })
+
+  // A percentage of a negative centre value is a negative offset, which would
+  // otherwise invert the band into `min: -180, max: -220`.
+  it('keeps `min <= max` for a negative centre value', () => {
+    expect(getSpreadBand({ value: -200, spread: 10 })).toEqual({
+      min: -220,
+      max: -180,
+    })
+  })
+
+  it('keeps `min <= max` for a negative `spread`', () => {
+    expect(getSpreadBand({ value: 1000, spread: -5 })).toEqual({
+      min: 950,
+      max: 1050,
+    })
+  })
+})

package/src/widgets-v2/spread/band.ts

@@ -0,0 +1,47 @@
+/**
+ * How a `spread` amount is applied to a centre value.
+ *
+ * - `percentage` — `spread` is a whole-number percentage of the centre
+ *   value, so `5` means +/-5%.
+ * - `absolute` — `spread` is a raw offset in the value's own units.
+ */
+export type SpreadVariant = 'percentage' | 'absolute'
+
+export interface GetSpreadBandOptions {
+  /** The centre value the band is drawn around. */
+  value: number
+  /** Half-width of the band, read according to `variant`. */
+  spread: number
+  /** Defaults to `percentage`. */
+  variant?: SpreadVariant
+}
+
+/**
+ * Derives the `min` / `max` band around a centre value, for feeding a
+ * {@link SpreadDataItem} from a single aggregated number (a prediction, a
+ * target) plus a tolerance — rather than from a real column range.
+ *
+ * `spread` is read as a percentage by default, which is what a tolerance
+ * almost always is: an absolute offset is meaningless without knowing the
+ * value's magnitude, and gets visually lost on large values (+/-5 on a
+ * prediction of 204,113 renders as a range indistinguishable from a single
+ * number).
+ *
+ * @example
+ * getSpreadBand({ value: 1000, spread: 5 })
+ * // -> { min: 950, max: 1050 }
+ * getSpreadBand({ value: 1000, spread: 5, variant: 'absolute' })
+ * // -> { min: 995, max: 1005 }
+ */
+export function getSpreadBand({
+  value,
+  spread,
+  variant = 'percentage',
+}: GetSpreadBandOptions): { min: number; max: number } {
+  const offset = variant === 'absolute' ? spread : (spread / 100) * value
+  // Keep `min <= max`: a percentage of a negative centre value (or a negative
+  // `spread`) yields a negative offset, which would invert the band.
+  const width = Math.abs(offset)
+
+  return { min: value - width, max: value + width }
+}

package/src/widgets-v2/spread/index.ts

@@ -3,4 +3,5 @@ export { SpreadUI, type SpreadUIProps } from './spread-ui'
 export { Separator } from './separator'
 export { SpreadSkeleton, type SpreadSkeletonProps } from './skeleton'
 export { createSpreadDownloadConfig } from './download'
+export { getSpreadBand, type SpreadVariant, type GetSpreadBandOptions } from './band'
 export type { SpreadDataItem, SpreadWidgetData } from './types'