@internetarchive/histogram-date-range 1.4.0-alpha-webdev7756.0 → 1.4.0-alpha-webdev7756.1

package/src/histogram-date-range.ts

@@ -20,6 +20,28 @@ import { styleMap } from 'lit/directives/style-map.js';
 dayjs.extend(customParseFormat);
 dayjs.extend(fixFirstCenturyYears);
 
+type SliderId = 'slider-min' | 'slider-max';
+
+export type BinSnappingInterval = 'none' | 'month' | 'year';
+
+export type BarScalingPreset = 'linear' | 'logarithmic';
+export type BarScalingFunction = (binValue: number) => number;
+export type BarScalingOption = BarScalingPreset | BarScalingFunction;
+
+interface HistogramItem {
+  value: number;
+  height: number;
+  binStart: string;
+  binEnd: string;
+  tooltip: string;
+}
+
+interface BarDataset extends DOMStringMap {
+  numItems: string;
+  binStart: string;
+  binEnd: string;
+}
+
 // these values can be overridden via the component's HTML (camelCased) attributes
 const WIDTH = 180;
 const HEIGHT = 40;
@@ -31,12 +53,17 @@ const MISSING_DATA = 'no data';
 const UPDATE_DEBOUNCE_DELAY_MS = 0;
 const TOOLTIP_LABEL = 'item';
 
-// this function may be overridden only via Lit property expression or direct assignment
-const LOG_BAR_SCALING_FN = (binValue: number) => Math.log1p(binValue);
-
 // this constant is not set up to be overridden
 const SLIDER_CORNER_SIZE = 4;
 
+/**
+ * Map from bar scaling preset options to the corresponding function they represent
+ */
+const BAR_SCALING_PRESET_FNS: Record<BarScalingPreset, BarScalingFunction> = {
+  linear: (binValue: number) => binValue,
+  logarithmic: (binValue: number) => Math.log1p(binValue),
+};
+
 // these CSS custom props can be overridden from the HTML that is invoking this component
 const sliderColor = css`var(--histogramDateRangeSliderColor, #4B65FE)`;
 const selectedRangeColor = css`var(--histogramDateRangeSelectedRangeColor, #DBE0FF)`;
@@ -53,24 +80,6 @@ const tooltipTextColor = css`var(--histogramDateRangeTooltipTextColor, #FFFFFF)`
 const tooltipFontSize = css`var(--histogramDateRangeTooltipFontSize, 1.1rem)`;
 const tooltipFontFamily = css`var(--histogramDateRangeTooltipFontFamily, sans-serif)`;
 
-type SliderId = 'slider-min' | 'slider-max';
-
-export type BinSnappingInterval = 'none' | 'month' | 'year';
-
-interface HistogramItem {
-  value: number;
-  height: number;
-  binStart: string;
-  binEnd: string;
-  tooltip: string;
-}
-
-interface BarDataset extends DOMStringMap {
-  numItems: string;
-  binStart: string;
-  binEnd: string;
-}
-
 @customElement('histogram-date-range')
 export class HistogramDateRange extends LitElement {
   /* eslint-disable lines-between-class-members */
@@ -111,20 +120,20 @@ export class HistogramDateRange extends LitElement {
   @property({ type: String }) tooltipLabel = TOOLTIP_LABEL;
 
   /**
-   * A function mapping bin values to a new value that determines how tall each bar will
-   * be in relation to the others.
+   * A function or preset value indicating how the height of each bar relates to its
+   * corresponding bin value. Current presets available are 'logarithmic' and 'linear',
+   * but a custom function may be provided instead if other behavior is desired.
    *
-   * Default sizing function is the logarithm of the bin value, yielding more prominent
-   * bars for smaller values, at the cost of bars not being directly proportional to their
-   * values and having relatively smooth variation among values of a similar magnitude.
-   * This ensures that when the difference between the min and max values is large, small
-   * values are not as liable to completely disappear visually.
+   * The default scaling (`'logarithmic'`) uses the logarithm of each bin value, yielding
+   * more prominent bars for smaller values. This ensures that even when the difference
+   * between the min & max values is large, small values are unlikely to completely disappear
+   * visually. However, the cost is that bars have less noticeable variation among values of
+   * a similar magnitude, and their heights are not a direct representation of the bin values.
    *
-   * For linearly-scaled bars, set this to the identity function.
+   * The `'linear'` preset option instead sizes the bars in linear proportion to their bin
+   * values.
    */
-  @property({ attribute: false }) barScalingFunction: (
-    binValue: number
-  ) => number = LOG_BAR_SCALING_FN;
+  @property({ type: String }) barScaling: BarScalingOption = 'logarithmic';
 
   // internal reactive properties not exposed as attributes
   @state() private _tooltipOffsetX = 0;
@@ -166,7 +175,8 @@ export class HistogramDateRange extends LitElement {
       changedProps.has('maxSelectedDate') ||
       changedProps.has('width') ||
       changedProps.has('height') ||
-      changedProps.has('binSnapping')
+      changedProps.has('binSnapping') ||
+      changedProps.has('barScaling')
     ) {
       this.handleDataUpdate();
     }
@@ -265,6 +275,17 @@ export class HistogramDateRange extends LitElement {
     }
   }
 
+  /**
+   * Function to scale bin values, whether from a preset or a provided custom function.
+   */
+  private get barScalingFunction(): BarScalingFunction {
+    if (typeof this.barScaling === 'string') {
+      return BAR_SCALING_PRESET_FNS[this.barScaling];
+    }
+
+    return this.barScaling;
+  }
+
   private calculateHistData(): HistogramItem[] {
     const { bins, height, dateRangeMS, _numBins, _minDateMS } = this;
     const minValue = Math.min(...this.bins);
@@ -295,8 +316,7 @@ export class HistogramDateRange extends LitElement {
 
       return {
         value: v,
-        // use log scaling for the height of the bar to prevent tall bars from
-        // making the smaller ones too small to see
+        // apply the configured scaling function to the bin value before determining bar height
         height: Math.floor(this.barScalingFunction(v) * valueScale),
         binStart,
         binEnd,

package/test/histogram-date-range.test.ts

@@ -44,7 +44,7 @@ async function createCustomElementInHTMLContainer(): Promise<HistogramDateRange>
 }
 
 describe('HistogramDateRange', () => {
-  it('shows scaled histogram bars when provided with data', async () => {
+  it('shows log-scaled histogram bars when provided with data', async () => {
     const el = await createCustomElementInHTMLContainer();
     const bars = el.shadowRoot?.querySelectorAll(
       '.bar'
@@ -54,6 +54,32 @@ describe('HistogramDateRange', () => {
     expect(heights).to.eql([38, 7, 50]);
   });
 
+  it('uses linear bar height scaling when specified', async () => {
+    const el = await createCustomElementInHTMLContainer();
+    el.barScaling = 'linear';
+    await el.updateComplete;
+
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    const heights = Array.from(bars, b => b.height.baseVal.value);
+
+    expect(heights).to.eql([16, 0, 50]);
+  });
+
+  it('uses custom bar height scaling when specified', async () => {
+    const el = await createCustomElementInHTMLContainer();
+    el.barScaling = (x: number) => Math.sqrt(x);
+    await el.updateComplete;
+
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    const heights = Array.from(bars, b => b.height.baseVal.value);
+
+    expect(heights).to.eql([28, 5, 50]);
+  });
+
   it('changes the position of the sliders and standardizes date format when dates are entered', async () => {
     const el = await createCustomElementInHTMLContainer();