@internetarchive/histogram-date-range 1.2.2-alpha-webdev7377.6 → 1.2.2-alpha-webdev7377.7

package/src/histogram-date-range.ts

@@ -47,13 +47,14 @@ const tooltipFontFamily = css`var(--histogramDateRangeTooltipFontFamily, sans-se
 
 type SliderId = 'slider-min' | 'slider-max';
 
-export type BinRoundingInterval = 'month' | 'year';
+export type BinSnappingInterval = 'none' | 'month' | 'year';
 
 interface HistogramItem {
   value: number;
   height: number;
   binStart: string;
   binEnd: string;
+  tooltip: string;
 }
 
 interface BarDataset extends DOMStringMap {
@@ -74,8 +75,6 @@ export class HistogramDateRange extends LitElement {
   @property({ type: Number }) tooltipHeight = TOOLTIP_HEIGHT;
   @property({ type: Number }) updateDelay = UPDATE_DEBOUNCE_DELAY_MS;
   @property({ type: String }) dateFormat = DATE_FORMAT;
-  /** Optional; falls back to `dateFormat` if not provided */
-  @property({ type: String }) tooltipDateFormat?: string;
   @property({ type: String }) missingDataMessage = MISSING_DATA;
   @property({ type: String }) minDate = '';
   @property({ type: String }) maxDate = '';
@@ -83,13 +82,14 @@ export class HistogramDateRange extends LitElement {
   @property({ type: Array }) bins: number[] = [];
   /** If true, update events will not be canceled by the date inputs receiving focus */
   @property({ type: Boolean }) updateWhileFocused = false;
-  /** What interval bins should be rounded to for tooltip display */
-  @property({ type: String }) binRounding: BinRoundingInterval = 'year';
+  /** What interval bins should be rounded to for display */
+  @property({ type: String }) binSnapping: BinSnappingInterval = 'none';
 
   // internal reactive properties not exposed as attributes
   @state() private _tooltipOffset = 0;
   @state() private _tooltipContent?: TemplateResult;
   @state() private _tooltipVisible = false;
+  @state() private _tooltipDateFormat?: string;
   @state() private _isDragging = false;
   @state() private _isLoading = false;
 
@@ -122,7 +122,8 @@ export class HistogramDateRange extends LitElement {
       changedProps.has('minSelectedDate') ||
       changedProps.has('maxSelectedDate') ||
       changedProps.has('width') ||
-      changedProps.has('height')
+      changedProps.has('height') ||
+      changedProps.has('binSnapping')
     ) {
       this.handleDataUpdate();
     }
@@ -140,8 +141,13 @@ export class HistogramDateRange extends LitElement {
       return;
     }
     this._histWidth = this.width - this.sliderWidth * 2;
-    this._minDateMS = this.getMSFromString(this.minDate);
-    this._maxDateMS = this.getMSFromString(this.maxDate);
+    this._minDateMS = this.snapTimestamp(this.getMSFromString(this.minDate));
+    // NB: The max date string, converted as-is to ms, represents the _start_ of the final date interval; we want the _end_.
+    this._maxDateMS =
+      this.snapTimestamp(
+        this.getMSFromString(this.maxDate) + this.snapInterval
+      ) + this.snapEndOffset;
+
     this._binWidth = this._histWidth / this._numBins;
     this._previousDateRange = this.currentDateRangeString;
     this._histData = this.calculateHistData();
@@ -153,16 +159,23 @@ export class HistogramDateRange extends LitElement {
       : this.maxDate;
   }
 
+  /**
+   * Rounds the given timestamp to the next full second.
+   */
+  private snapToNextSecond(timestamp: number): number {
+    return Math.ceil(timestamp / 1000) * 1000;
+  }
+
   /**
    * Rounds the given timestamp to the (approximate) nearest start of a month,
-   * such that dates up to the 15th of the month are rounded down, while dates
-   * past the 15th are rounded up.
+   * such that dates up to and including the 15th of the month are rounded down,
+   * while dates past the 15th are rounded up.
    */
-  private roundToMonth(timestamp: number): number {
+  private snapToMonth(timestamp: number): number {
     const d = new Date(timestamp);
     const [year, month, day] = [d.getFullYear(), d.getMonth(), d.getDate()];
 
-    return day < 16 // Obviously only an approximation, but good enough
+    return day < 16 // Obviously only an approximation, but good enough for snapping
       ? new Date(year, month, 1).getTime()
       : new Date(year, month + 1, 1).getTime();
   }
@@ -172,21 +185,29 @@ export class HistogramDateRange extends LitElement {
    * such that dates up to the end of June are rounded down, while dates in
    * July or later are rounded up.
    */
-  private roundToYear(timestamp: number): number {
+  private snapToYear(timestamp: number): number {
     const d = new Date(timestamp);
     const [year, month] = [d.getFullYear(), d.getMonth()];
 
     return month < 6 // NB: months are 0-indexed, so 6 = July
-      ? new Date(year, 1, 1).getTime()
-      : new Date(year + 1, 1, 1).getTime();
+      ? new Date(year, 0, 1).getTime()
+      : new Date(year + 1, 0, 1).getTime();
   }
 
   /**
-   * Rounds the given timestamp according to the `binRounding` property.
+   * Rounds the given timestamp according to the `binSnapping` property.
+   * Default is simply to snap to the nearest full second.
    */
-  private roundBin(timestamp: number): number {
-    if (this.binRounding === 'month') return this.roundToMonth(timestamp);
-    return this.roundToYear(timestamp);
+  private snapTimestamp(timestamp: number): number {
+    switch (this.binSnapping) {
+      case 'year':
+        return this.snapToYear(timestamp);
+      case 'month':
+        return this.snapToMonth(timestamp);
+      case 'none':
+      default:
+        return this.snapToNextSecond(timestamp);
+    }
   }
 
   private calculateHistData(): HistogramItem[] {
@@ -198,16 +219,32 @@ export class HistogramDateRange extends LitElement {
     const valueRange = minValue === maxValue ? 1 : Math.log1p(maxValue);
     const valueScale = height / valueRange;
     const dateScale = dateRangeMS / _numBins;
+
     return bins.map((v: number, i: number) => {
-      const binStartMS = this.roundBin(i * dateScale + _minDateMS);
-      const binEndMS = this.roundBin((i + 1) * dateScale + _minDateMS) - 1;
+      const binStartMS = this.snapTimestamp(i * dateScale + _minDateMS);
+      const binStart = this.formatDate(binStartMS);
+
+      const binEndMS =
+        this.snapTimestamp((i + 1) * dateScale + _minDateMS) +
+        this.snapEndOffset;
+      const binEnd = this.formatDate(binEndMS);
+
+      const tooltipStart = this.formatDate(binStartMS, this.tooltipDateFormat);
+      const tooltipEnd = this.formatDate(binEndMS, this.tooltipDateFormat);
+      // If start/end are the same, just render a single value
+      const tooltip =
+        tooltipStart === tooltipEnd
+          ? tooltipStart
+          : `${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),
-        binStart: this.formatDate(binStartMS, this.resolvedTooltipDateFormat),
-        binEnd: this.formatDate(binEndMS, this.resolvedTooltipDateFormat),
+        binStart,
+        binEnd,
+        tooltip,
       };
     });
   }
@@ -232,11 +269,39 @@ export class HistogramDateRange extends LitElement {
   }
 
   /**
-   * Returns the consumer-specified tooltip date format if set, falling back to
-   * the general `dateFormat` property and then the default format if none is set.
+   * Approximate size in ms of the interval to which bins are snapped.
+   */
+  private get snapInterval(): number {
+    const yearMS = 31_536_000_000; // A 365-day approximation of ms in a year
+    const monthMS = 2_592_000_000; // A 30-day approximation of ms in a month
+    switch (this.binSnapping) {
+      case 'year':
+        return yearMS;
+      case 'month':
+        return monthMS;
+      case 'none':
+      default:
+        return 0;
+    }
+  }
+
+  /**
+   * Offset added to the end of each bin to ensure disjoin intervals, if applicable.
+   */
+  private get snapEndOffset(): number {
+    return this.binSnapping !== 'none' && this._numBins > 1 ? -1 : 0;
+  }
+
+  /**
+   * Optional date format to use for tooltips only.
+   * Falls back to `dateFormat` if not provided.
    */
-  private get resolvedTooltipDateFormat(): string {
-    return this.tooltipDateFormat ?? this.dateFormat ?? DATE_FORMAT;
+  @property({ type: String }) get tooltipDateFormat(): string {
+    return this._tooltipDateFormat ?? this.dateFormat ?? DATE_FORMAT;
+  }
+
+  set tooltipDateFormat(value: string) {
+    this._tooltipDateFormat = value;
   }
 
   /** component's loading (and disabled) state */
@@ -305,7 +370,10 @@ export class HistogramDateRange extends LitElement {
 
   /** horizontal position of max date slider */
   get maxSliderX(): number {
-    const x = this.translateDateToPosition(this.maxSelectedDate);
+    const maxSelectedDateMS = this.snapTimestamp(
+      this.getMSFromString(this.maxSelectedDate) + this.snapInterval
+    );
+    const x = this.translateDateToPosition(this.formatDate(maxSelectedDateMS));
     return this.validMaxSliderX(x);
   }
 
@@ -321,10 +389,6 @@ export class HistogramDateRange extends LitElement {
     const x = target.x.baseVal.value + this.sliderWidth / 2;
     const dataset = target.dataset as BarDataset;
     const itemsText = `item${dataset.numItems !== '1' ? 's' : ''}`;
-    const datesText =
-      dataset.binStart === dataset.binEnd
-        ? `${dataset.binStart}` // If start/end are the same, just render a single value
-        : `${dataset.binStart} - ${dataset.binEnd}`;
     const formattedNumItems = Number(dataset.numItems).toLocaleString();
 
     this._tooltipOffset =
@@ -332,7 +396,7 @@ export class HistogramDateRange extends LitElement {
 
     this._tooltipContent = html`
       ${formattedNumItems} ${itemsText}<br />
-      ${datesText}
+      ${dataset.tooltip}
     `;
     this._tooltipVisible = true;
   }
@@ -383,6 +447,9 @@ export class HistogramDateRange extends LitElement {
       this.maxSelectedDate = this.translatePositionToDate(
         this.validMaxSliderX(newX)
       );
+      if (this.getMSFromString(this.maxSelectedDate) > this._maxDateMS) {
+        this.maxSelectedDate = this.maxDate;
+      }
     }
   };
 
@@ -491,9 +558,10 @@ export class HistogramDateRange extends LitElement {
    * @returns string representation of date
    */
   private translatePositionToDate(x: number): string {
-    // use Math.ceil to round up to fix case where input like 1/1/2010 would get
-    // translated to 12/31/2009
-    const milliseconds = Math.ceil(
+    // Snap to the nearest second, fixing the case where input like 1/1/2010
+    // would get translated to 12/31/2009 due to slight discrepancies from
+    // pixel boundaries and floating point error.
+    const milliseconds = this.snapToNextSecond(
       ((x - this.sliderWidth) * this.dateRangeMS) / this._histWidth
     );
     return this.formatDate(this._minDateMS + milliseconds);
@@ -684,41 +752,60 @@ export class HistogramDateRange extends LitElement {
 
   get histogramTemplate(): SVGTemplateResult[] {
     const xScale = this._histWidth / this._numBins;
-    const barWidth = xScale - 0.5;
+    const barWidth = xScale - 1;
     let x = this.sliderWidth; // start at the left edge of the histogram
 
-    // the stroke-dasharray style below creates a transparent border around the
-    // right edge of the bar, which prevents user from encountering a gap
-    // between adjacent bars (eg when viewing the tooltips or when trying to
-    // extend the range by clicking on a bar)
     return this._histData.map(data => {
+      const { minSelectedDate, maxSelectedDate } = this;
+      const barHeight = data.height;
+
+      const binIsBeforeMin = this.isBefore(data.binEnd, minSelectedDate);
+      const binIsAfterMax = this.isAfter(data.binStart, maxSelectedDate);
+      const barFill =
+        binIsBeforeMin || binIsAfterMax ? barExcludedFill : barIncludedFill;
+
+      // the stroke-dasharray style below creates a transparent border around the
+      // right edge of the bar, which prevents user from encountering a gap
+      // 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='stroke-dasharray: 0 ${barWidth} ${data.height} ${barWidth} 0 ${
-        data.height
-      };'
-          x="${x}"
-          y="${this.height - data.height}"
-          width="${barWidth}"
-          height="${data.height}"
-          @pointerenter="${this.showTooltip}"
-          @pointerleave="${this.hideTooltip}"
-          @click="${this.handleBarClick}"
-          fill="${
-            x + barWidth >= this.minSliderX && x <= this.maxSliderX
-              ? barIncludedFill
-              : barExcludedFill
-          }"
-          data-num-items="${data.value}"
-          data-bin-start="${data.binStart}"
-          data-bin-end="${data.binEnd}"
+          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}
         />`;
       x += xScale;
       return bar;
     });
   }
 
+  /** Whether the first arg represents a date strictly before the second arg */
+  private isBefore(date1: string, date2: string): boolean {
+    const date1MS = this.getMSFromString(date1);
+    const date2MS = this.getMSFromString(date2);
+    return date1MS < date2MS;
+  }
+
+  /** Whether the first arg represents a date strictly after the second arg */
+  private isAfter(date1: string, date2: string): boolean {
+    const date1MS = this.getMSFromString(date1);
+    const date2MS = this.getMSFromString(date2);
+    return date1MS > date2MS;
+  }
+
   private formatDate(dateMS: number, format: string = this.dateFormat): string {
     if (Number.isNaN(dateMS)) {
       return '';