@internetarchive/histogram-date-range 0.0.10-beta → 0.1.1-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';
 
@@ -47,6 +52,12 @@ interface HistogramItem {
   binEnd: 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 */
@@ -93,7 +104,14 @@ export class HistogramDateRange extends LitElement {
   }
 
   updated(changedProps: PropertyValues): void {
-    if (changedProps.has('bins') || changedProps.has('Date')) {
+    // check for changes that would affect bin data calculations
+    if (
+      changedProps.has('bins') ||
+      changedProps.has('minDate') ||
+      changedProps.has('maxDate') ||
+      changedProps.has('minSelectedDate') ||
+      changedProps.has('maxSelectedDate')
+    ) {
       this.handleDataUpdate();
     }
   }
@@ -110,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();
@@ -127,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)}`,
@@ -162,56 +186,60 @@ 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);
+    let ms = this.getMSFromString(rawDate);
+    if (!Number.isNaN(ms)) {
+      ms = Math.min(ms, this.getMSFromString(this._maxSelectedDate));
+      this._minSelectedDate = this.formatDate(ms);
     }
     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);
+    let ms = this.getMSFromString(rawDate);
+    if (!Number.isNaN(ms)) {
+      ms = Math.max(this.getMSFromString(this._minSelectedDate), ms);
+      this._maxSelectedDate = this.formatDate(ms);
     }
     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
-    );
+    // default to leftmost position if missing or invalid min position
+    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
-    );
+    // default to rightmost position if missing or invalid max position
+    const x = this.translateDateToPosition(this.maxSelectedDate);
+    return this.validMaxSliderX(x);
   }
 
   private get dateRangeMS(): number {
@@ -224,14 +252,15 @@ export class HistogramDateRange extends LitElement {
     }
     const target = e.currentTarget as SVGRectElement;
     const x = target.x.baseVal.value + this.sliderWidth / 2;
-    const dataset = target.dataset;
+    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;
@@ -274,11 +303,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)
+      );
     }
   };
 
@@ -291,8 +323,14 @@ export class HistogramDateRange extends LitElement {
    * 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);
+    if (Number.isNaN(newX)) {
+      return this.sliderWidth;
+    }
+    return this.clamp(
+      newX,
+      this.sliderWidth,
+      this.translateDateToPosition(this.maxSelectedDate)
+    );
   }
 
   /**
@@ -304,8 +342,14 @@ export class HistogramDateRange extends LitElement {
    * 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);
+    if (Number.isNaN(newX)) {
+      return this.width - this.sliderWidth;
+    }
+    return this.clamp(
+      newX,
+      this.translateDateToPosition(this.minSelectedDate),
+      this.width - this.sliderWidth
+    );
   }
 
   private addListeners(): void {
@@ -393,12 +437,17 @@ export class HistogramDateRange extends LitElement {
    * @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
+    );
+  }
+
+  /** 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: InputEvent): void {
@@ -413,29 +462,41 @@ export class HistogramDateRange extends LitElement {
     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();
+    }
   }
 
-  /** 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 (=> 0099-01-01) = 99 CE
+      return dateObj.getTime(); // get time in milliseconds
+    }
+    return dayjs(date, [this.dateFormat, DATE_FORMAT]).valueOf();
   }
 
   private handleBarClick(e: InputEvent): void {
-    const dataset = (e.currentTarget as SVGRectElement).dataset as DOMStringMap;
-    const binStartDateMS = dayjs(dataset.binStart).valueOf();
-    if (binStartDateMS < this.minSelectedDateMS) {
-      this.minSelectedDate = dataset.binStart ?? '';
-    }
-    const binEndDateMS = dayjs(dataset.binEnd).valueOf();
-    if (binEndDateMS > this.maxSelectedDateMS) {
-      this.maxSelectedDate = dataset.binEnd ?? '';
+    const dataset = (e.currentTarget as SVGRectElement).dataset as BarDataset;
+    const distanceFromMinSlider =
+      this.getMSFromString(dataset.binStart) -
+      this.getMSFromString(this.minSelectedDate);
+    const distanceFromMaxSlider =
+      this.getMSFromString(this.maxSelectedDate) -
+      this.getMSFromString(dataset.binEnd);
+    // update the selection by moving the nearer slider
+    if (distanceFromMinSlider < distanceFromMaxSlider) {
+      this.minSelectedDate = dataset.binStart;
+    } else {
+      this.maxSelectedDate = dataset.binEnd;
     }
     this.beginEmitUpdateProcess();
   }
@@ -482,9 +543,12 @@ export class HistogramDateRange extends LitElement {
     return svg`
     <svg
       id="${id}"
+      class="
+      ${this.disabled ? '' : 'draggable'} 
+      ${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
@@ -514,7 +578,7 @@ export class HistogramDateRange extends LitElement {
         y="0"
         width="${this.maxSliderX - this.minSliderX}"
         height="${this.height}"
-        fill="${selectedRangeFill}"
+        fill="${selectedRangeColor}"
       />`;
   }
 
@@ -542,7 +606,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
           }"
@@ -555,9 +619,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);
   }
 
   /**
@@ -574,6 +646,7 @@ export class HistogramDateRange extends LitElement {
         type="text"
         @focus="${this.cancelPendingUpdateEvent}"
         @blur="${this.handleMinDateInput}"
+        @keyup="${this.handleKeyUp}"
         .value="${live(this.minSelectedDate)}"
         ?disabled="${this.disabled}"
       />
@@ -588,6 +661,7 @@ export class HistogramDateRange extends LitElement {
         type="text"
         @focus="${this.cancelPendingUpdateEvent}"
         @blur="${this.handleMaxDateInput}"
+        @keyup="${this.handleKeyUp}"
         .value="${live(this.maxSelectedDate)}"
         ?disabled="${this.disabled}"
       />
@@ -618,9 +692,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>
@@ -664,11 +738,17 @@ export class HistogramDateRange extends LitElement {
       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;
@@ -678,7 +758,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;
     }
@@ -715,6 +795,7 @@ export class HistogramDateRange extends LitElement {
       border-radius: 2px !important;
       text-align: center;
       font-size: ${inputFontSize};
+      font-family: ${inputFontFamily};
     }
   `;
 
@@ -755,6 +836,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;