@internetarchive/histogram-date-range 0.1.0-beta → 0.1.3-alpha

package/src/histogram-date-range.ts

@@ -1,6 +1,7 @@
 import {
   css,
   html,
+  nothing,
   LitElement,
   PropertyValues,
   svg,
@@ -10,6 +11,8 @@ import {
 import { property, state, customElement } from 'lit/decorators.js';
 import { live } from 'lit/directives/live.js';
 import dayjs from 'dayjs/esm/index.js';
+import customParseFormat from 'dayjs/esm/plugin/customParseFormat';
+dayjs.extend(customParseFormat);
 import '@internetarchive/ia-activity-indicator/ia-activity-indicator';
 
 // these values can be overridden via the component's HTML (camelCased) attributes
@@ -20,23 +23,25 @@ const TOOLTIP_WIDTH = 125;
 const TOOLTIP_HEIGHT = 30;
 const DATE_FORMAT = 'YYYY';
 const MISSING_DATA = 'no data';
-const UPDATE_DEBOUNCE_DELAY_MS = 1000;
+const UPDATE_DEBOUNCE_DELAY_MS = 0;
 
 // this constant is not set up to be overridden
 const SLIDER_CORNER_SIZE = 4;
 
 // these CSS custom props can be overridden from the HTML that is invoking this component
-const sliderFill = css`var(--histogramDateRangeSliderFill, #4B65FE)`;
-const selectedRangeFill = css`var(--histogramDateRangeSelectedRangeFill, #DBE0FF)`;
+const sliderColor = css`var(--histogramDateRangeSliderColor, #4B65FE)`;
+const selectedRangeColor = css`var(--histogramDateRangeSelectedRangeColor, #DBE0FF)`;
 const barIncludedFill = css`var(--histogramDateRangeBarIncludedFill, #2C2C2C)`;
 const activityIndicatorColor = css`var(--histogramDateRangeActivityIndicator, #2C2C2C)`;
 const barExcludedFill = css`var(--histogramDateRangeBarExcludedFill, #CCCCCC)`;
 const inputBorder = css`var(--histogramDateRangeInputBorder, 0.5px solid #2C2C2C)`;
 const inputWidth = css`var(--histogramDateRangeInputWidth, 35px)`;
 const inputFontSize = css`var(--histogramDateRangeInputFontSize, 1.2rem)`;
+const inputFontFamily = css`var(--histogramDateRangeInputFontFamily, sans-serif)`;
 const tooltipBackgroundColor = css`var(--histogramDateRangeTooltipBackgroundColor, #2C2C2C)`;
 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';
 
@@ -123,8 +128,8 @@ export class HistogramDateRange extends LitElement {
       return;
     }
     this._histWidth = this.width - this.sliderWidth * 2;
-    this._minDateMS = dayjs(this.minDate).valueOf();
-    this._maxDateMS = dayjs(this.maxDate).valueOf();
+    this._minDateMS = this.getMSFromString(this.minDate);
+    this._maxDateMS = this.getMSFromString(this.maxDate);
     this._binWidth = this._histWidth / this._numBins;
     this._previousDateRange = this.currentDateRangeString;
     this._histData = this.calculateHistData();
@@ -140,11 +145,17 @@ export class HistogramDateRange extends LitElement {
   private calculateHistData(): HistogramItem[] {
     const minValue = Math.min(...this.bins);
     const maxValue = Math.max(...this.bins);
-    const valueScale = this.height / Math.log1p(maxValue - minValue);
+    // 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 - minValue);
+    const valueScale = this.height / valueRange;
     const dateScale = this.dateRangeMS / this._numBins;
     return this.bins.map((v: number, i: number) => {
       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(i * dateScale + this._minDateMS)}`,
         binEnd: `${this.formatDate((i + 1) * dateScale + this._minDateMS)}`,
@@ -163,6 +174,14 @@ export class HistogramDateRange extends LitElement {
     return this.bins.length;
   }
 
+  private get histogramLeftEdgeX(): number {
+    return this.sliderWidth;
+  }
+
+  private get histogramRightEdgeX(): number {
+    return this.width - this.sliderWidth;
+  }
+
   /** component's loading (and disabled) state */
   @property({ type: Boolean }) get loading(): boolean {
     return this._isLoading;
@@ -175,56 +194,62 @@ export class HistogramDateRange extends LitElement {
 
   /** formatted minimum date of selected date range */
   @property() get minSelectedDate(): string {
-    return this.formatDate(this._minSelectedDate);
+    return this.formatDate(this.getMSFromString(this._minSelectedDate));
   }
 
+  /** updates minSelectedDate if new date is valid */
   set minSelectedDate(rawDate: string) {
     if (!this._minSelectedDate) {
       // because the values needed to calculate valid max/min values are not
       // available during the lit init when it's populating properties from
       // attributes, fall back to just the raw date if nothing is already set
       this._minSelectedDate = rawDate;
+      return;
     }
-    const x = this.translateDateToPosition(rawDate);
-    if (x) {
-      const validX = this.validMinSliderX(x);
-      this._minSelectedDate = this.translatePositionToDate(validX);
+    const proposedDateMS = this.getMSFromString(rawDate);
+    const isValidDate = !Number.isNaN(proposedDateMS);
+    const isNotTooRecent =
+      proposedDateMS <= this.getMSFromString(this.maxSelectedDate);
+    if (isValidDate && isNotTooRecent) {
+      this._minSelectedDate = this.formatDate(proposedDateMS);
     }
     this.requestUpdate();
   }
 
   /** formatted maximum date of selected date range */
   @property() get maxSelectedDate(): string {
-    return this.formatDate(this._maxSelectedDate);
+    return this.formatDate(this.getMSFromString(this._maxSelectedDate));
   }
 
+  /** updates maxSelectedDate if new date is valid */
   set maxSelectedDate(rawDate: string) {
     if (!this._maxSelectedDate) {
-      // see comment above in the minSelectedDate setter
+      // because the values needed to calculate valid max/min values are not
+      // available during the lit init when it's populating properties from
+      // attributes, fall back to just the raw date if nothing is already set
       this._maxSelectedDate = rawDate;
+      return;
     }
-    const x = this.translateDateToPosition(rawDate);
-    if (x) {
-      const validX = this.validMaxSliderX(x);
-      this._maxSelectedDate = this.translatePositionToDate(validX);
+    const proposedDateMS = this.getMSFromString(rawDate);
+    const isValidDate = !Number.isNaN(proposedDateMS);
+    const isNotTooOld =
+      proposedDateMS >= this.getMSFromString(this.minSelectedDate);
+    if (isValidDate && isNotTooOld) {
+      this._maxSelectedDate = this.formatDate(proposedDateMS);
     }
     this.requestUpdate();
   }
+
   /** horizontal position of min date slider */
   get minSliderX(): number {
-    return (
-      // default to leftmost position if missing or invalid min position
-      this.translateDateToPosition(this.minSelectedDate) ?? this.sliderWidth
-    );
+    const x = this.translateDateToPosition(this.minSelectedDate);
+    return this.validMinSliderX(x);
   }
 
   /** horizontal position of max date slider */
   get maxSliderX(): number {
-    return (
-      // default to rightmost position if missing or invalid max position
-      this.translateDateToPosition(this.maxSelectedDate) ??
-      this.width - this.sliderWidth
-    );
+    const x = this.translateDateToPosition(this.maxSelectedDate);
+    return this.validMaxSliderX(x);
   }
 
   private get dateRangeMS(): number {
@@ -239,12 +264,13 @@ 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 formattedNumItems = Number(dataset.numItems).toLocaleString();
 
     this._tooltipOffset =
       x + (this._binWidth - this.sliderWidth - this.tooltipWidth) / 2;
 
     this._tooltipContent = html`
-      ${dataset.numItems} ${itemsText}<br />
+      ${formattedNumItems} ${itemsText}<br />
       ${dataset.binStart} - ${dataset.binEnd}
     `;
     this._tooltipVisible = true;
@@ -287,11 +313,14 @@ export class HistogramDateRange extends LitElement {
   private move = (e: PointerEvent): void => {
     const newX = e.offsetX - this._dragOffset;
     const slider = this._currentSlider as SVGRectElement;
-    const date = this.translatePositionToDate(newX);
     if ((slider.id as SliderId) === 'slider-min') {
-      this.minSelectedDate = date;
+      this.minSelectedDate = this.translatePositionToDate(
+        this.validMinSliderX(newX)
+      );
     } else {
-      this.maxSelectedDate = date;
+      this.maxSelectedDate = this.translatePositionToDate(
+        this.validMaxSliderX(newX)
+      );
     }
   };
 
@@ -299,26 +328,42 @@ export class HistogramDateRange extends LitElement {
    * Constrain a proposed value for the minimum (left) slider
    *
    * If the value is less than the leftmost valid position, then set it to the
-   * left edge of the widget (ie the slider width). If the value is greater than
-   * the rightmost valid position (the position of the max slider), then set it
-   * to the position of the max slider
+   * left edge of the histogram (ie the slider width). If the value is greater
+   * than the rightmost valid position (the position of the max slider), then
+   * set it to the position of the max slider
    */
   private validMinSliderX(newX: number): number {
-    const validX = Math.max(newX, this.sliderWidth);
-    return Math.min(validX, this.maxSliderX);
+    // allow the left slider to go right only to the right slider, even if the
+    // max selected date is out of range
+    const rightLimit = Math.min(
+      this.translateDateToPosition(this.maxSelectedDate),
+      this.histogramRightEdgeX
+    );
+    newX = this.clamp(newX, this.histogramLeftEdgeX, rightLimit);
+    const isInvalid =
+      Number.isNaN(newX) || rightLimit < this.histogramLeftEdgeX;
+    return isInvalid ? this.histogramLeftEdgeX : newX;
   }
 
   /**
    * Constrain a proposed value for the maximum (right) slider
    *
    * If the value is greater than the rightmost valid position, then set it to
-   * the right edge of the widget (ie widget width - slider width). If the value
-   * is less than the leftmost valid position (the position of the min slider),
-   * then set it to the position of the min slider
+   * the right edge of the histogram (ie histogram width - slider width). If the
+   * value is less than the leftmost valid position (the position of the min
+   * slider), then set it to the position of the min slider
    */
   private validMaxSliderX(newX: number): number {
-    const validX = Math.max(newX, this.minSliderX);
-    return Math.min(validX, this.width - this.sliderWidth);
+    // allow the right slider to go left only to the left slider, even if the
+    // min selected date is out of range
+    const leftLimit = Math.max(
+      this.histogramLeftEdgeX,
+      this.translateDateToPosition(this.minSelectedDate)
+    );
+    newX = this.clamp(newX, leftLimit, this.histogramRightEdgeX);
+    const isInvalid =
+      Number.isNaN(newX) || leftLimit > this.histogramRightEdgeX;
+    return isInvalid ? this.histogramRightEdgeX : newX;
   }
 
   private addListeners(): void {
@@ -400,54 +445,87 @@ export class HistogramDateRange extends LitElement {
   }
 
   /**
-   * Returns slider x-position corresponding to given date (or null if invalid
-   * date)
+   * Returns slider x-position corresponding to given date
    *
    * @param date
    * @returns x-position of slider
    */
-  private translateDateToPosition(date: string): number | null {
-    const milliseconds = dayjs(date).valueOf();
-    const xPosition =
+  private translateDateToPosition(date: string): number {
+    const milliseconds = this.getMSFromString(date);
+    return (
       this.sliderWidth +
-      ((milliseconds - this._minDateMS) * this._histWidth) / this.dateRangeMS;
-    return isNaN(milliseconds) || isNaN(xPosition) ? null : xPosition;
+      ((milliseconds - this._minDateMS) * this._histWidth) / this.dateRangeMS
+    );
   }
 
-  private handleMinDateInput(e: InputEvent): void {
+  /** ensure that the returned value is between minValue and maxValue */
+  private clamp(x: number, minValue: number, maxValue: number): number {
+    return Math.min(Math.max(x, minValue), maxValue);
+  }
+
+  private handleMinDateInput(e: Event): void {
     const target = e.currentTarget as HTMLInputElement;
     this.minSelectedDate = target.value;
     this.beginEmitUpdateProcess();
   }
 
-  private handleMaxDateInput(e: InputEvent): void {
+  private handleMaxDateInput(e: Event): void {
     const target = e.currentTarget as HTMLInputElement;
     this.maxSelectedDate = target.value;
     this.beginEmitUpdateProcess();
   }
 
-  private get currentDateRangeString(): string {
-    return `${this.minSelectedDate}:${this.maxSelectedDate}`;
+  private handleKeyUp(e: KeyboardEvent): void {
+    if (e.key === 'Enter') {
+      const target = e.currentTarget as HTMLInputElement;
+      target.blur();
+      if (target.id === 'date-min') {
+        this.handleMinDateInput(e);
+      } else if (target.id === 'date-max') {
+        this.handleMaxDateInput(e);
+      }
+    }
   }
 
-  /** minimum selected date in milliseconds */
-  private get minSelectedDateMS(): number {
-    return dayjs(this.minSelectedDate).valueOf();
+  private get currentDateRangeString(): string {
+    return `${this.minSelectedDate}:${this.maxSelectedDate}`;
   }
 
-  /** maximum selected date in milliseconds */
-  private get maxSelectedDateMS(): number {
-    return dayjs(this.maxSelectedDate).valueOf();
+  private getMSFromString(date: string): number {
+    const digitGroupCount = (date.split(/(\d+)/).length - 1) / 2;
+    if (digitGroupCount === 1) {
+      // if there's just a single set of digits, assume it's a year
+      const dateObj = new Date(0, 0); // start at January 1, 1900
+      dateObj.setFullYear(Number(date)); // override year
+      return dateObj.getTime(); // get time in milliseconds
+    }
+    return dayjs(date, [this.dateFormat, DATE_FORMAT]).valueOf();
   }
 
-  private handleBarClick(e: InputEvent): void {
+  /**
+   * expand or narrow the selected range by moving the slider nearest the
+   * clicked bar to the outer edge of the clicked bar
+   *
+   * @param e Event click event from a histogram bar
+   */
+  private handleBarClick(e: Event): void {
     const dataset = (e.currentTarget as SVGRectElement).dataset as BarDataset;
-    const binStartDateMS = dayjs(dataset.binStart).valueOf();
-    if (binStartDateMS < this.minSelectedDateMS) {
+    // use the midpoint of the width of the clicked bar to determine which is
+    // the nearest slider
+    const clickPosition =
+      (this.getMSFromString(dataset.binStart) +
+        this.getMSFromString(dataset.binEnd)) /
+      2;
+    const distanceFromMinSlider = Math.abs(
+      clickPosition - this.getMSFromString(this.minSelectedDate)
+    );
+    const distanceFromMaxSlider = Math.abs(
+      clickPosition - this.getMSFromString(this.maxSelectedDate)
+    );
+    // update the selected range by moving the nearer slider
+    if (distanceFromMinSlider < distanceFromMaxSlider) {
       this.minSelectedDate = dataset.binStart;
-    }
-    const binEndDateMS = dayjs(dataset.binEnd).valueOf();
-    if (binEndDateMS > this.maxSelectedDateMS) {
+    } else {
       this.maxSelectedDate = dataset.binEnd;
     }
     this.beginEmitUpdateProcess();
@@ -500,7 +578,7 @@ export class HistogramDateRange extends LitElement {
       ${this._isDragging ? 'dragging' : ''}"
       @pointerdown="${this.drag}"
     >
-      <path d="${sliderShape} z" fill="${sliderFill}" />
+      <path d="${sliderShape} z" fill="${sliderColor}" />
       <rect
         x="${
           sliderPositionX - this.sliderWidth * k + this.sliderWidth * 0.4 * k
@@ -530,7 +608,7 @@ export class HistogramDateRange extends LitElement {
         y="0"
         width="${this.maxSliderX - this.minSliderX}"
         height="${this.height}"
-        fill="${selectedRangeFill}"
+        fill="${selectedRangeColor}"
       />`;
   }
 
@@ -558,7 +636,7 @@ export class HistogramDateRange extends LitElement {
           @pointerleave="${this.hideTooltip}"
           @click="${this.handleBarClick}"
           fill="${
-            x >= this.minSliderX && x <= this.maxSliderX
+            x + barWidth >= this.minSliderX && x <= this.maxSliderX
               ? barIncludedFill
               : barExcludedFill
           }"
@@ -571,9 +649,17 @@ export class HistogramDateRange extends LitElement {
     });
   }
 
-  private formatDate(rawDate: string | number): string {
-    const date = dayjs(rawDate);
-    return date.isValid() ? date.format(this.dateFormat) : '';
+  private formatDate(dateMS: number): string {
+    if (Number.isNaN(dateMS)) {
+      return '';
+    }
+    const date = dayjs(dateMS);
+    if (date.year() < 1000) {
+      // years before 1000 don't play well with dayjs custom formatting, so fall
+      // back to displaying only the year
+      return String(date.year());
+    }
+    return date.format(this.dateFormat);
   }
 
   /**
@@ -590,6 +676,7 @@ export class HistogramDateRange extends LitElement {
         type="text"
         @focus="${this.cancelPendingUpdateEvent}"
         @blur="${this.handleMinDateInput}"
+        @keyup="${this.handleKeyUp}"
         .value="${live(this.minSelectedDate)}"
         ?disabled="${this.disabled}"
       />
@@ -604,6 +691,7 @@ export class HistogramDateRange extends LitElement {
         type="text"
         @focus="${this.cancelPendingUpdateEvent}"
         @blur="${this.handleMaxDateInput}"
+        @keyup="${this.handleKeyUp}"
         .value="${live(this.maxSelectedDate)}"
         ?disabled="${this.disabled}"
       />
@@ -634,9 +722,9 @@ export class HistogramDateRange extends LitElement {
     `;
   }
 
-  private get activityIndicatorTemplate(): TemplateResult {
+  private get activityIndicatorTemplate(): TemplateResult | typeof nothing {
     if (!this.loading) {
-      return html``;
+      return nothing;
     }
     return html`
       <ia-activity-indicator mode="processing"> </ia-activity-indicator>
@@ -700,7 +788,7 @@ export class HistogramDateRange extends LitElement {
       border-radius: 3px;
       padding: 2px;
       font-size: ${tooltipFontSize};
-      font-family: sans-serif;
+      font-family: ${tooltipFontFamily};
       touch-action: none;
       pointer-events: none;
     }
@@ -737,6 +825,7 @@ export class HistogramDateRange extends LitElement {
       border-radius: 2px !important;
       text-align: center;
       font-size: ${inputFontSize};
+      font-family: ${inputFontFamily};
     }
   `;
 
@@ -777,6 +866,9 @@ export class HistogramDateRange extends LitElement {
     `;
   }
 }
+
+// help TypeScript provide strong typing when interacting with DOM APIs
+// https://stackoverflow.com/questions/65148695/lit-element-typescript-project-global-interface-declaration-necessary
 declare global {
   interface HTMLElementTagNameMap {
     'histogram-date-range': HistogramDateRange;