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

package/dist/src/histogram-date-range.js

@@ -19,8 +19,16 @@ const TOOLTIP_HEIGHT = 30;
 const DATE_FORMAT = 'YYYY';
 const MISSING_DATA = 'no data';
 const UPDATE_DEBOUNCE_DELAY_MS = 0;
+const TOOLTIP_LABEL = 'item';
 // 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 = {
+    linear: (binValue) => binValue,
+    logarithmic: (binValue) => 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)`;
@@ -67,6 +75,26 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
          *  - `year`: Same as `month`, but snapping to year boundaries instead of months.
          */
         this.binSnapping = 'none';
+        /**
+         * What label to use on tooltips to identify the type of data being represented.
+         * Defaults to `'item(s)'`.
+         */
+        this.tooltipLabel = TOOLTIP_LABEL;
+        /**
+         * 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.
+         *
+         * 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.
+         *
+         * The `'linear'` preset option instead sizes the bars in linear proportion to their bin
+         * values.
+         */
+        this.barScaling = 'logarithmic';
         // internal reactive properties not exposed as attributes
         this._tooltipOffsetX = 0;
         this._tooltipOffsetY = 0;
@@ -138,7 +166,8 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
             changedProps.has('maxSelectedDate') ||
             changedProps.has('width') ||
             changedProps.has('height') ||
-            changedProps.has('binSnapping')) {
+            changedProps.has('binSnapping') ||
+            changedProps.has('barScaling')) {
             this.handleDataUpdate();
         }
     }
@@ -226,13 +255,22 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
                 return this.snapToNextSecond(timestamp);
         }
     }
+    /**
+     * Function to scale bin values, whether from a preset or a provided custom function.
+     */
+    get barScalingFunction() {
+        if (typeof this.barScaling === 'string') {
+            return BAR_SCALING_PRESET_FNS[this.barScaling];
+        }
+        return this.barScaling;
+    }
     calculateHistData() {
         const { bins, height, dateRangeMS, _numBins, _minDateMS } = this;
         const minValue = Math.min(...this.bins);
         const maxValue = Math.max(...this.bins);
         // if there is no difference between the min and max values, use a range of
         // 1 because log scaling will fail if the range is 0
-        const valueRange = minValue === maxValue ? 1 : Math.log1p(maxValue);
+        const valueRange = minValue === maxValue ? 1 : this.barScalingFunction(maxValue);
         const valueScale = height / valueRange;
         const dateScale = dateRangeMS / _numBins;
         return bins.map((v, i) => {
@@ -249,9 +287,8 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
                 : `${tooltipStart} - ${tooltipEnd}`;
             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
-                height: Math.floor(Math.log1p(v) * valueScale),
+                // apply the configured scaling function to the bin value before determining bar height
+                height: Math.floor(this.barScalingFunction(v) * valueScale),
                 binStart,
                 binEnd,
                 tooltip,
@@ -379,7 +416,7 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
         const target = e.currentTarget;
         const x = target.x.baseVal.value + this.sliderWidth / 2;
         const dataset = target.dataset;
-        const itemsText = `item${dataset.numItems !== '1' ? 's' : ''}`;
+        const itemsText = `${this.tooltipLabel}${dataset.numItems !== '1' ? 's' : ''}`;
         const formattedNumItems = Number(dataset.numItems).toLocaleString();
         const tooltipPadding = 2;
         const bufferHeight = 9;
@@ -395,9 +432,9 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
                 window.scrollX;
         // Place the tooltip (with arrow) just above the top of the histogram bars
         this._tooltipOffsetY = histogramY - heightAboveHistogram + window.scrollY;
-        this._tooltipContent = html `
-      ${formattedNumItems} ${itemsText}<br />
-      ${dataset.tooltip}
+        this._tooltipContent = html `
+      ${formattedNumItems} ${itemsText}<br />
+      ${dataset.tooltip}
     `;
         (_b = (_a = this._tooltip).showPopover) === null || _b === void 0 ? void 0 : _b.call(_a);
     }
@@ -594,25 +631,25 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
         // border-radius); used as part of a SVG quadratic curve. see
         // https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#curve_commands
         const cs = SLIDER_CORNER_SIZE;
-        const sliderShape = `
-            M${this.minSliderX},0
-            h-${this.sliderWidth - cs}
-            q-${cs},0 -${cs},${cs}
-            v${this.height - cs * 2}
-            q0,${cs} ${cs},${cs}
-            h${this.sliderWidth - cs}
+        const sliderShape = `
+            M${this.minSliderX},0
+            h-${this.sliderWidth - cs}
+            q-${cs},0 -${cs},${cs}
+            v${this.height - cs * 2}
+            q0,${cs} ${cs},${cs}
+            h${this.sliderWidth - cs}
           `;
         return this.generateSliderSVG(this.minSliderX, 'slider-min', sliderShape);
     }
     get maxSliderTemplate() {
         const cs = SLIDER_CORNER_SIZE;
-        const sliderShape = `
-            M${this.maxSliderX},0
-            h${this.sliderWidth - cs}
-            q${cs},0 ${cs},${cs}
-            v${this.height - cs * 2}
-            q0,${cs} -${cs},${cs}
-            h-${this.sliderWidth - cs}
+        const sliderShape = `
+            M${this.maxSliderX},0
+            h${this.sliderWidth - cs}
+            q${cs},0 ${cs},${cs}
+            v${this.height - cs * 2}
+            q0,${cs} -${cs},${cs}
+            h-${this.sliderWidth - cs}
           `;
         return this.generateSliderSVG(this.maxSliderX, 'slider-max', sliderShape);
     }
@@ -625,38 +662,38 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
             draggable: !this.disabled,
             dragging: this._isDragging,
         });
-        return svg `
-    <svg
-      id=${id}
-      class=${sliderClasses}
-      @pointerdown=${this.drag}
-    >
-      <path d="${sliderShape} z" fill="${sliderColor}" />
-      <rect
-        x="${sliderPositionX - this.sliderWidth * k + this.sliderWidth * 0.4 * k}"
-        y="${this.height / 3}"
-        width="1"
-        height="${this.height / 3}"
-        fill="white"
-      />
-      <rect
-        x="${sliderPositionX - this.sliderWidth * k + this.sliderWidth * 0.6 * k}"
-        y="${this.height / 3}"
-        width="1"
-        height="${this.height / 3}"
-        fill="white"
-      />
-    </svg>
+        return svg `
+    <svg
+      id=${id}
+      class=${sliderClasses}
+      @pointerdown=${this.drag}
+    >
+      <path d="${sliderShape} z" fill="${sliderColor}" />
+      <rect
+        x="${sliderPositionX - this.sliderWidth * k + this.sliderWidth * 0.4 * k}"
+        y="${this.height / 3}"
+        width="1"
+        height="${this.height / 3}"
+        fill="white"
+      />
+      <rect
+        x="${sliderPositionX - this.sliderWidth * k + this.sliderWidth * 0.6 * k}"
+        y="${this.height / 3}"
+        width="1"
+        height="${this.height / 3}"
+        fill="white"
+      />
+    </svg>
     `;
     }
     get selectedRangeTemplate() {
-        return svg `
-      <rect
-        x="${this.minSliderX}"
-        y="0"
-        width="${this.maxSliderX - this.minSliderX}"
-        height="${this.height}"
-        fill="${selectedRangeColor}"
+        return svg `
+      <rect
+        x="${this.minSliderX}"
+        y="0"
+        width="${this.maxSliderX - this.minSliderX}"
+        height="${this.height}"
+        fill="${selectedRangeColor}"
       />`;
     }
     get histogramTemplate() {
@@ -674,22 +711,30 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
             // between adjacent bars (eg when viewing the tooltips or when trying to
             // extend the range by clicking on a bar)
             const barStyle = `stroke-dasharray: 0 ${barWidth} ${barHeight} ${barWidth} 0 ${barHeight}`;
-            const bar = svg `
-        <rect
-          class="bar"
-          style=${barStyle}
-          x=${x}
-          y=${this.height - barHeight}
-          width=${barWidth}
-          height=${barHeight}
-          @pointerenter=${this.showTooltip}
-          @pointerleave=${this.hideTooltip}
-          @click=${this.handleBarClick}
-          fill=${barFill}
-          data-num-items=${data.value}
-          data-bin-start=${data.binStart}
-          data-bin-end=${data.binEnd}
-          data-tooltip=${data.tooltip}
+            const bar = svg `
+        <rect
+          class="bar-pointer-target"
+          x=${x}
+          y="0"
+          width=${barWidth}
+          height=${this.height}
+          @pointerenter=${this.showTooltip}
+          @pointerleave=${this.hideTooltip}
+          @click=${this.handleBarClick}
+          fill="transparent"
+          data-num-items=${data.value}
+          data-bin-start=${data.binStart}
+          data-bin-end=${data.binEnd}
+          data-tooltip=${data.tooltip}
+        />
+        <rect
+          class="bar"
+          style=${barStyle}
+          x=${x}
+          y=${this.height - barHeight}
+          width=${barWidth}
+          height=${barHeight}
+          fill=${barFill}
         />`;
             x += xScale;
             return bar;
@@ -729,31 +774,31 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
      * https://lit.dev/docs/templates/directives/#live
      */
     get minInputTemplate() {
-        return html `
-      <input
-        id="date-min"
-        placeholder=${this.dateFormat}
-        type="text"
-        @focus=${this.handleInputFocus}
-        @blur=${this.handleMinDateInput}
-        @keyup=${this.handleKeyUp}
-        .value=${live(this.minSelectedDate)}
-        ?disabled=${this.disabled}
-      />
+        return html `
+      <input
+        id="date-min"
+        placeholder=${this.dateFormat}
+        type="text"
+        @focus=${this.handleInputFocus}
+        @blur=${this.handleMinDateInput}
+        @keyup=${this.handleKeyUp}
+        .value=${live(this.minSelectedDate)}
+        ?disabled=${this.disabled}
+      />
     `;
     }
     get maxInputTemplate() {
-        return html `
-      <input
-        id="date-max"
-        placeholder=${this.dateFormat}
-        type="text"
-        @focus=${this.handleInputFocus}
-        @blur=${this.handleMaxDateInput}
-        @keyup=${this.handleKeyUp}
-        .value=${live(this.maxSelectedDate)}
-        ?disabled=${this.disabled}
-      />
+        return html `
+      <input
+        id="date-max"
+        placeholder=${this.dateFormat}
+        type="text"
+        @focus=${this.handleInputFocus}
+        @blur=${this.handleMaxDateInput}
+        @keyup=${this.handleKeyUp}
+        .value=${live(this.maxSelectedDate)}
+        ?disabled=${this.disabled}
+      />
     `;
     }
     get minLabelTemplate() {
@@ -769,179 +814,184 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
             top: `${this._tooltipOffsetY}px`,
             left: `${this._tooltipOffsetX}px`,
         });
-        return html `
-      <div id="tooltip" style=${styles} popover>${this._tooltipContent}</div>
+        return html `
+      <div id="tooltip" style=${styles} popover>${this._tooltipContent}</div>
     `;
     }
     get noDataTemplate() {
-        return html `
-      <div class="missing-data-message">${this.missingDataMessage}</div>
+        return html `
+      <div class="missing-data-message">${this.missingDataMessage}</div>
     `;
     }
     get activityIndicatorTemplate() {
         if (!this.loading) {
             return nothing;
         }
-        return html `
-      <ia-activity-indicator mode="processing"> </ia-activity-indicator>
+        return html `
+      <ia-activity-indicator mode="processing"> </ia-activity-indicator>
     `;
     }
     render() {
         if (!this.hasBinData) {
             return this.noDataTemplate;
         }
-        return html `
-      <div
-        id="container"
-        class="
-          noselect
-          ${this._isDragging ? 'dragging' : ''}
-        "
-        style="width: ${this.width}px"
-      >
-        ${this.activityIndicatorTemplate} ${this.tooltipTemplate}
-        <div
-          class="inner-container
-          ${this.disabled ? 'disabled' : ''}"
-        >
-          <svg
-            width="${this.width}"
-            height="${this.height}"
-            @pointerleave="${this.drop}"
-          >
-            ${this.selectedRangeTemplate}
-            <svg id="histogram">${this.histogramTemplate}</svg>
-            ${this.minSliderTemplate} ${this.maxSliderTemplate}
-          </svg>
-          <div id="inputs">
-            ${this.minLabelTemplate} ${this.minInputTemplate}
-            <div class="dash">-</div>
-            ${this.maxLabelTemplate} ${this.maxInputTemplate}
-            <slot name="inputs-right-side"></slot>
-          </div>
-        </div>
-      </div>
+        return html `
+      <div
+        id="container"
+        class="
+          noselect
+          ${this._isDragging ? 'dragging' : ''}
+        "
+        style="width: ${this.width}px"
+      >
+        ${this.activityIndicatorTemplate} ${this.tooltipTemplate}
+        <div
+          class="inner-container
+          ${this.disabled ? 'disabled' : ''}"
+        >
+          <svg
+            width="${this.width}"
+            height="${this.height}"
+            @pointerleave="${this.drop}"
+          >
+            ${this.selectedRangeTemplate}
+            <svg id="histogram">${this.histogramTemplate}</svg>
+            ${this.minSliderTemplate} ${this.maxSliderTemplate}
+          </svg>
+          <div id="inputs">
+            ${this.minLabelTemplate} ${this.minInputTemplate}
+            <div class="dash">-</div>
+            ${this.maxLabelTemplate} ${this.maxInputTemplate}
+            <slot name="inputs-right-side"></slot>
+          </div>
+        </div>
+      </div>
     `;
     }
 };
-HistogramDateRange.styles = css `
-    .missing-data-message {
-      text-align: center;
-    }
-    #container {
-      margin: 0;
-      touch-action: none;
-      position: relative;
-    }
-    .disabled {
-      opacity: 0.3;
-    }
-    ia-activity-indicator {
-      position: absolute;
-      left: calc(50% - 10px);
-      top: 10px;
-      width: 20px;
-      height: 20px;
-      --activityIndicatorLoadingDotColor: rgba(0, 0, 0, 0);
-      --activityIndicatorLoadingRingColor: ${activityIndicatorColor};
-    }
-
-    /* prevent selection from interfering with tooltip, especially on mobile */
-    /* https://stackoverflow.com/a/4407335/1163042 */
-    .noselect {
-      -webkit-touch-callout: none; /* iOS Safari */
-      -webkit-user-select: none; /* Safari */
-      -moz-user-select: none; /* Old versions of Firefox */
-      -ms-user-select: none; /* Internet Explorer/Edge */
-      user-select: none; /* current Chrome, Edge, Opera and Firefox */
-    }
-    .bar {
-      /* create a transparent border around the hist bars to prevent "gaps" and
-      flickering when moving around between bars. this also helps with handling
-      clicks on the bars, preventing users from being able to click in between
-      bars */
-      stroke: rgba(0, 0, 0, 0);
-      /* ensure transparent stroke wide enough to cover gap between bars */
-      stroke-width: 2px;
-    }
-    .bar:hover {
-      /* highlight currently hovered bar */
-      fill-opacity: 0.7;
-    }
-    .disabled .bar:hover {
-      /* ensure no visual hover interaction when disabled */
-      fill-opacity: 1;
-    }
-    /****** histogram ********/
-    #tooltip {
-      position: absolute;
-      background: ${tooltipBackgroundColor};
-      margin: 0;
-      border: 0;
-      color: ${tooltipTextColor};
-      text-align: center;
-      border-radius: 3px;
-      padding: 2px;
-      font-size: ${tooltipFontSize};
-      font-family: ${tooltipFontFamily};
-      touch-action: none;
-      pointer-events: none;
-      overflow: visible;
-    }
-    #tooltip:after {
-      content: '';
-      position: absolute;
-      margin-left: -5px;
-      top: 100%;
-      left: 50%;
-      /* arrow */
-      border: 5px solid ${tooltipTextColor};
-      border-color: ${tooltipBackgroundColor} transparent transparent
-        transparent;
-    }
-    /****** slider ********/
-    .slider {
-      shape-rendering: crispEdges; /* So the slider doesn't get blurry if dragged between pixels */
-    }
-    .draggable:hover {
-      cursor: grab;
-    }
-    .dragging {
-      cursor: grabbing !important;
-    }
-    /****** inputs ********/
-    #inputs {
-      display: flex;
-      justify-content: center;
-      margin: ${inputRowMargin};
-    }
-    #inputs .dash {
-      position: relative;
-      bottom: -1px;
-      align-self: center; /* Otherwise the dash sticks to the top while the inputs grow */
-    }
-    input {
-      width: ${inputWidth};
-      margin: 0 3px;
-      border: ${inputBorder};
-      border-radius: 2px !important;
-      text-align: center;
-      font-size: ${inputFontSize};
-      font-family: ${inputFontFamily};
-    }
-    .sr-only {
-      position: absolute !important;
-      width: 1px !important;
-      height: 1px !important;
-      margin: 0 !important;
-      padding: 0 !important;
-      border: 0 !important;
-      overflow: hidden !important;
-      white-space: nowrap !important;
-      clip: rect(1px, 1px, 1px, 1px) !important;
-      -webkit-clip-path: inset(50%) !important;
-      clip-path: inset(50%) !important;
-    }
+HistogramDateRange.styles = css `
+    .missing-data-message {
+      text-align: center;
+    }
+    #container {
+      margin: 0;
+      touch-action: none;
+      position: relative;
+    }
+    .disabled {
+      opacity: 0.3;
+    }
+    ia-activity-indicator {
+      position: absolute;
+      left: calc(50% - 10px);
+      top: 10px;
+      width: 20px;
+      height: 20px;
+      --activityIndicatorLoadingDotColor: rgba(0, 0, 0, 0);
+      --activityIndicatorLoadingRingColor: ${activityIndicatorColor};
+    }
+
+    /* prevent selection from interfering with tooltip, especially on mobile */
+    /* https://stackoverflow.com/a/4407335/1163042 */
+    .noselect {
+      -webkit-touch-callout: none; /* iOS Safari */
+      -webkit-user-select: none; /* Safari */
+      -moz-user-select: none; /* Old versions of Firefox */
+      -ms-user-select: none; /* Internet Explorer/Edge */
+      user-select: none; /* current Chrome, Edge, Opera and Firefox */
+    }
+    .bar,
+    .bar-pointer-target {
+      /* create a transparent border around the hist bars to prevent "gaps" and
+      flickering when moving around between bars. this also helps with handling
+      clicks on the bars, preventing users from being able to click in between
+      bars */
+      stroke: rgba(0, 0, 0, 0);
+      /* ensure transparent stroke wide enough to cover gap between bars */
+      stroke-width: 2px;
+    }
+    .bar {
+      /* ensure the bar's pointer target receives events, not the bar itself */
+      pointer-events: none;
+    }
+    .bar-pointer-target:hover + .bar {
+      /* highlight currently hovered bar */
+      fill-opacity: 0.7;
+    }
+    .disabled .bar-pointer-target:hover + .bar {
+      /* ensure no visual hover interaction when disabled */
+      fill-opacity: 1;
+    }
+    /****** histogram ********/
+    #tooltip {
+      position: absolute;
+      background: ${tooltipBackgroundColor};
+      margin: 0;
+      border: 0;
+      color: ${tooltipTextColor};
+      text-align: center;
+      border-radius: 3px;
+      padding: 2px;
+      font-size: ${tooltipFontSize};
+      font-family: ${tooltipFontFamily};
+      touch-action: none;
+      pointer-events: none;
+      overflow: visible;
+    }
+    #tooltip:after {
+      content: '';
+      position: absolute;
+      margin-left: -5px;
+      top: 100%;
+      left: 50%;
+      /* arrow */
+      border: 5px solid ${tooltipTextColor};
+      border-color: ${tooltipBackgroundColor} transparent transparent
+        transparent;
+    }
+    /****** slider ********/
+    .slider {
+      shape-rendering: crispEdges; /* So the slider doesn't get blurry if dragged between pixels */
+    }
+    .draggable:hover {
+      cursor: grab;
+    }
+    .dragging {
+      cursor: grabbing !important;
+    }
+    /****** inputs ********/
+    #inputs {
+      display: flex;
+      justify-content: center;
+      margin: ${inputRowMargin};
+    }
+    #inputs .dash {
+      position: relative;
+      bottom: -1px;
+      align-self: center; /* Otherwise the dash sticks to the top while the inputs grow */
+    }
+    input {
+      width: ${inputWidth};
+      margin: 0 3px;
+      border: ${inputBorder};
+      border-radius: 2px !important;
+      text-align: center;
+      font-size: ${inputFontSize};
+      font-family: ${inputFontFamily};
+    }
+    .sr-only {
+      position: absolute !important;
+      width: 1px !important;
+      height: 1px !important;
+      margin: 0 !important;
+      padding: 0 !important;
+      border: 0 !important;
+      overflow: hidden !important;
+      white-space: nowrap !important;
+      clip: rect(1px, 1px, 1px, 1px) !important;
+      -webkit-clip-path: inset(50%) !important;
+      clip-path: inset(50%) !important;
+    }
   `;
 __decorate([
     property({ type: Number })
@@ -985,6 +1035,12 @@ __decorate([
 __decorate([
     property({ type: String })
 ], HistogramDateRange.prototype, "binSnapping", void 0);
+__decorate([
+    property({ type: String })
+], HistogramDateRange.prototype, "tooltipLabel", void 0);
+__decorate([
+    property({ type: String })
+], HistogramDateRange.prototype, "barScaling", void 0);
 __decorate([
     state()
 ], HistogramDateRange.prototype, "_tooltipOffsetX", void 0);