@internetarchive/histogram-date-range 1.2.2-alpha-webdev7377.8 → 1.3.1-alpha-webdev7745.0

package/src/histogram-date-range.ts

@@ -1,6 +1,7 @@
 import '@internetarchive/ia-activity-indicator';
 import dayjs from 'dayjs/esm';
 import customParseFormat from 'dayjs/esm/plugin/customParseFormat';
+import fixFirstCenturyYears from './plugins/fix-first-century-years';
 import {
   css,
   html,
@@ -13,8 +14,10 @@ import {
 } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { live } from 'lit/directives/live.js';
+import { classMap } from 'lit/directives/class-map.js';
 
 dayjs.extend(customParseFormat);
+dayjs.extend(fixFirstCenturyYears);
 
 // these values can be overridden via the component's HTML (camelCased) attributes
 const WIDTH = 180;
@@ -82,7 +85,18 @@ 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 display */
+
+  /**
+   * What interval bins should be snapped to for determining their time ranges.
+   *  - `none` (default): Bins should each represent an identical duration of time,
+   *     without regard for the actual dates represented.
+   *  - `month`: Bins should each represent one or more full, non-overlapping months.
+   *     The bin ranges will be "snapped" to the nearest month boundaries, which can
+   *     result in bins that represent different amounts of time, particularly if the
+   *     provided bins do not evenly divide the provided date range, or if the months
+   *     represented are of different lengths.
+   *  - `year`: Same as `month`, but snapping to year boundaries instead of months.
+   */
   @property({ type: String }) binSnapping: BinSnappingInterval = 'none';
 
   // internal reactive properties not exposed as attributes
@@ -141,8 +155,10 @@ export class HistogramDateRange extends LitElement {
       return;
     }
     this._histWidth = this.width - this.sliderWidth * 2;
+
     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_.
+    // NB: The max date string, converted as-is to ms, represents the *start* of the
+    // final date interval; we want the *end*, so we add any snap interval/offset.
     this._maxDateMS =
       this.snapTimestamp(
         this.getMSFromString(this.maxDate) + this.snapInterval
@@ -172,12 +188,16 @@ export class HistogramDateRange extends LitElement {
    * while dates past the 15th are rounded up.
    */
   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 for snapping
-      ? new Date(year, month, 1).getTime()
-      : new Date(year, month + 1, 1).getTime();
+    const d = dayjs(timestamp);
+    const monthsToAdd = d.date() < 16 ? 0 : 1;
+    const snapped = d
+      .add(monthsToAdd, 'month')
+      .date(1)
+      .hour(0)
+      .minute(0)
+      .second(0)
+      .millisecond(0); // First millisecond of the month
+    return snapped.valueOf();
   }
 
   /**
@@ -186,12 +206,17 @@ export class HistogramDateRange extends LitElement {
    * July or later are rounded up.
    */
   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, 0, 1).getTime()
-      : new Date(year + 1, 0, 1).getTime();
+    const d = dayjs(timestamp);
+    const yearsToAdd = d.month() < 6 ? 0 : 1;
+    const snapped = d
+      .add(yearsToAdd, 'year')
+      .month(0)
+      .date(1)
+      .hour(0)
+      .minute(0)
+      .second(0)
+      .millisecond(0); // First millisecond of the year
+    return snapped.valueOf();
   }
 
   /**
@@ -206,6 +231,7 @@ export class HistogramDateRange extends LitElement {
         return this.snapToMonth(timestamp);
       case 'none':
       default:
+        // We still align it to second boundaries to resolve minor discrepancies
         return this.snapToNextSecond(timestamp);
     }
   }
@@ -286,7 +312,8 @@ export class HistogramDateRange extends LitElement {
   }
 
   /**
-   * Offset added to the end of each bin to ensure disjoin intervals, if applicable.
+   * Offset added to the end of each bin to ensure disjoint intervals,
+   * depending on whether snapping is enabled and there are multiple bins.
    */
   private get snapEndOffset(): number {
     return this.binSnapping !== 'none' && this._numBins > 1 ? -1 : 0;
@@ -297,7 +324,7 @@ export class HistogramDateRange extends LitElement {
    * Falls back to `dateFormat` if not provided.
    */
   @property({ type: String }) get tooltipDateFormat(): string {
-    return this._tooltipDateFormat ?? this.dateFormat ?? DATE_FORMAT;
+    return this._tooltipDateFormat ?? this.dateFormat;
   }
 
   set tooltipDateFormat(value: string) {
@@ -708,13 +735,17 @@ export class HistogramDateRange extends LitElement {
     // minimum, or facing towards the right (-1), ie maximum
     const k = id === 'slider-min' ? 1 : -1;
 
+    const sliderClasses = classMap({
+      slider: true,
+      draggable: !this.disabled,
+      dragging: this._isDragging,
+    });
+
     return svg`
     <svg
-      id="${id}"
-      class="
-      ${this.disabled ? '' : 'draggable'}
-      ${this._isDragging ? 'dragging' : ''}"
-      @pointerdown="${this.drag}"
+      id=${id}
+      class=${sliderClasses}
+      @pointerdown=${this.drag}
     >
       <path d="${sliderShape} z" fill="${sliderColor}" />
       <rect
@@ -812,9 +843,12 @@ export class HistogramDateRange extends LitElement {
     }
     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());
+      // years before 1000 don't play well with dayjs custom formatting, so work around dayjs
+      // by setting the year to a sentinel value and then replacing it instead.
+      // this is a bit hacky but it does the trick for essentially all reasonable cases
+      // until such time as we replace dayjs.
+      const tmpDate = date.year(199999);
+      return tmpDate.format(format).replace(/199999/g, date.year().toString());
     }
     return date.format(format);
   }
@@ -829,13 +863,13 @@ export class HistogramDateRange extends LitElement {
     return html`
       <input
         id="date-min"
-        placeholder="${this.dateFormat}"
+        placeholder=${this.dateFormat}
         type="text"
-        @focus="${this.handleInputFocus}"
-        @blur="${this.handleMinDateInput}"
-        @keyup="${this.handleKeyUp}"
-        .value="${live(this.minSelectedDate)}"
-        ?disabled="${this.disabled}"
+        @focus=${this.handleInputFocus}
+        @blur=${this.handleMinDateInput}
+        @keyup=${this.handleKeyUp}
+        .value=${live(this.minSelectedDate)}
+        ?disabled=${this.disabled}
       />
     `;
   }
@@ -844,13 +878,13 @@ export class HistogramDateRange extends LitElement {
     return html`
       <input
         id="date-max"
-        placeholder="${this.dateFormat}"
+        placeholder=${this.dateFormat}
         type="text"
-        @focus="${this.handleInputFocus}"
-        @blur="${this.handleMaxDateInput}"
-        @keyup="${this.handleKeyUp}"
-        .value="${live(this.maxSelectedDate)}"
-        ?disabled="${this.disabled}"
+        @focus=${this.handleInputFocus}
+        @blur=${this.handleMaxDateInput}
+        @keyup=${this.handleKeyUp}
+        .value=${live(this.maxSelectedDate)}
+        ?disabled=${this.disabled}
       />
     `;
   }
@@ -968,6 +1002,9 @@ export class HistogramDateRange extends LitElement {
         transparent;
     }
     /****** slider ********/
+    .slider {
+      shape-rendering: crispEdges; /* So the slider doesn't get blurry if dragged between pixels */
+    }
     .draggable:hover {
       cursor: grab;
     }

package/src/plugins/fix-first-century-years.ts

@@ -0,0 +1,52 @@
+import type dayjs from 'dayjs/esm';
+
+/**
+ * As with the Date(y, m, ...) constructor, dayjs interprets years 0-99 as offsets
+ * from the year 1900 instead of the actual first-century years.
+ * We don't want that weird legacy behavior; we want years parsed literally.
+ *
+ * The maintainer of dayjs apparently refuses to address this:
+ *  - https://github.com/iamkun/dayjs/pull/548#issuecomment-477660947
+ *  - https://github.com/iamkun/dayjs/issues/1237
+ *
+ * So this plugin tries to detect the anomalous cases where the date format
+ * contains a YYYY block and the parsed date has a year in the 1900-1999 range,
+ * by checking whether the parsed year actually occurred in the original string.
+ * If not, then we assume it was parsed incorrectly as an offset, and adjust.
+ *
+ * In practice this assumption could fail if the input date is invalid in some
+ * way (e.g. having overflow, like a YYYY-MM-DD of "1950-22-33", which might be
+ * converted to 1951-11-02 and produce a false positive). Essentially, we trade away
+ * leniency for overflow dates to ensure that we handle all valid ones correctly.
+ * This seems a reasonable tradeoff for our present use cases. But realistically we
+ * should probably explore moving to a date lib that handles these cases properly.
+ */
+export default function fixFirstCenturyYears(
+  _: unknown,
+  dayjsClass: typeof dayjs.Dayjs
+) {
+  const proto = dayjsClass.prototype;
+  const oldParse = proto.parse;
+  proto.parse = function (cfg) {
+    const inputDate = cfg.date;
+    const format = cfg.args[1];
+    oldParse.call(this, cfg);
+
+    const year = this.year();
+    const isProblemDateRange = year >= 1900 && year < 2000;
+    const isProblemStringFormat =
+      typeof format === 'string' && format.includes('YYYY');
+    const isProblemArrayFormat =
+      Array.isArray(format) &&
+      typeof format[0] === 'string' &&
+      format[0].includes('YYYY');
+    const isProblemFormat = isProblemStringFormat || isProblemArrayFormat;
+    const missingParsedYear =
+      typeof inputDate === 'string' && !inputDate.includes(`${year}`);
+
+    if (isProblemDateRange && isProblemFormat && missingParsedYear) {
+      this.$d.setFullYear(year - 1900);
+      this.init(); // Re-initialize with the new date
+    }
+  };
+}

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

@@ -248,7 +248,7 @@ describe('HistogramDateRange', () => {
 
     // initial state
     expect(minSlider.getBoundingClientRect().x).to.eq(108);
-    expect(Array.from(minSlider.classList).join(' ')).to.eq('draggable');
+    expect(minSlider.classList.contains('draggable')).to.be.true;
 
     // pointer down
     minSlider.dispatchEvent(new PointerEvent('pointerdown'));
@@ -308,6 +308,55 @@ describe('HistogramDateRange', () => {
     window.dispatchEvent(new PointerEvent('pointermove', { clientX: 50 }));
     await el.updateComplete;
     expect(Math.round(maxSlider.getBoundingClientRect().x)).to.eq(268); // max slider didn't move
+
+    // try to slide max slider off the right edge
+    maxSlider.dispatchEvent(new PointerEvent('pointerdown', { clientX: 120 }));
+    window.dispatchEvent(new PointerEvent('pointermove', { clientX: 300 }));
+    await el.updateComplete;
+    expect(maxSlider.getBoundingClientRect().x).to.eq(298); // back to its initial position
+    expect(el.maxSelectedDate).to.equal('12/4/2020');
+  });
+
+  it('does not permit sliders to select dates outside the allowed range', async () => {
+    const el = await createCustomElementInHTMLContainer();
+    el.binSnapping = 'month';
+    el.dateFormat = 'YYYY-MM';
+    el.minDate = '2020-01';
+    el.maxDate = '2021-12';
+    el.minSelectedDate = '2020-01';
+    el.maxSelectedDate = '2021-12';
+    el.bins = [10, 20, 30, 40, 50, 60, 70, 80];
+    await el.updateComplete;
+
+    const minSlider = el.shadowRoot?.querySelector('#slider-min') as SVGElement;
+    const maxSlider = el.shadowRoot?.querySelector('#slider-max') as SVGElement;
+
+    const minDateInput = el.shadowRoot?.querySelector(
+      '#date-min'
+    ) as HTMLInputElement;
+    const maxDateInput = el.shadowRoot?.querySelector(
+      '#date-max'
+    ) as HTMLInputElement;
+
+    // initial state
+    expect(minSlider.getBoundingClientRect().x).to.eq(108, 'initial');
+    expect(maxSlider.getBoundingClientRect().x).to.eq(298, 'initial');
+    expect(minDateInput.value).to.eq('2020-01', 'initial');
+    expect(maxDateInput.value).to.eq('2021-12', 'initial');
+
+    // try dragging the min slider too far to the left
+    minSlider.dispatchEvent(new PointerEvent('pointerdown', { clientX: 0 }));
+    window.dispatchEvent(new PointerEvent('pointermove', { clientX: -50 }));
+    await el.updateComplete;
+    expect(minSlider.getBoundingClientRect().x).to.eq(108); // slider didn't move
+    expect(minDateInput.value).to.eq('2020-01'); // value unchanged
+
+    // try dragging the max slider too far to the right
+    maxSlider.dispatchEvent(new PointerEvent('pointerdown', { clientX: 195 }));
+    window.dispatchEvent(new PointerEvent('pointermove', { clientX: 250 }));
+    await el.updateComplete;
+    expect(maxSlider.getBoundingClientRect().x).to.eq(298); // slider didn't move
+    expect(maxDateInput.value).to.eq('2021-12'); // value unchanged
   });
 
   it("emits a custom event when the element's date range changes", async () => {
@@ -531,7 +580,7 @@ describe('HistogramDateRange', () => {
     expect(maxDateInput.value).to.eq('5000');
   });
 
-  it('handles year values less than 1000 by overriding date format to just display year', async () => {
+  it('handles year values less than 1000 correctly', async () => {
     const el = await fixture<HistogramDateRange>(
       html`
         <histogram-date-range
@@ -548,12 +597,12 @@ describe('HistogramDateRange', () => {
     const minDateInput = el.shadowRoot?.querySelector(
       '#date-min'
     ) as HTMLInputElement;
-    expect(minDateInput.value).to.eq('-500');
+    expect(minDateInput.value).to.eq('1/1/-500');
 
     const maxDateInput = el.shadowRoot?.querySelector(
       '#date-max'
     ) as HTMLInputElement;
-    expect(maxDateInput.value).to.eq('500');
+    expect(maxDateInput.value).to.eq('1/1/500');
   });
 
   it('handles missing data', async () => {
@@ -602,6 +651,207 @@ describe('HistogramDateRange', () => {
     expect(heights).to.eql([37, 40, 38, 38, 37, 36]);
   });
 
+  it('correctly aligns bins to exact month boundaries when binSnapping=month', async () => {
+    const el = await fixture<HistogramDateRange>(
+      html`
+        <histogram-date-range
+          binSnapping="month"
+          dateFormat="YYYY-MM"
+          tooltipDateFormat="MMM YYYY"
+          minDate="2020-01"
+          maxDate="2021-12"
+          bins="[10,20,30,40,50,60,70,80]"
+        ></histogram-date-range>
+      `
+    );
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    const tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql([
+      'Jan 2020 - Mar 2020',
+      'Apr 2020 - Jun 2020',
+      'Jul 2020 - Sep 2020',
+      'Oct 2020 - Dec 2020',
+      'Jan 2021 - Mar 2021',
+      'Apr 2021 - Jun 2021',
+      'Jul 2021 - Sep 2021',
+      'Oct 2021 - Dec 2021',
+    ]);
+  });
+
+  it('correctly handles month snapping for years 0-99', async () => {
+    const el = await fixture<HistogramDateRange>(
+      html`
+        <histogram-date-range
+          binSnapping="month"
+          dateFormat="YYYY-MM"
+          tooltipDateFormat="MMM YYYY"
+          minDate="0050-01"
+          maxDate="0065-12"
+          bins="[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32]"
+        ></histogram-date-range>
+      `
+    );
+
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    const tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql([
+      'Jan 50 - Jun 50',
+      'Jul 50 - Dec 50',
+      'Jan 51 - Jun 51',
+      'Jul 51 - Dec 51',
+      'Jan 52 - Jun 52',
+      'Jul 52 - Dec 52',
+      'Jan 53 - Jun 53',
+      'Jul 53 - Dec 53',
+      'Jan 54 - Jun 54',
+      'Jul 54 - Dec 54',
+      'Jan 55 - Jun 55',
+      'Jul 55 - Dec 55',
+      'Jan 56 - Jun 56',
+      'Jul 56 - Dec 56',
+      'Jan 57 - Jun 57',
+      'Jul 57 - Dec 57',
+      'Jan 58 - Jun 58',
+      'Jul 58 - Dec 58',
+      'Jan 59 - Jun 59',
+      'Jul 59 - Dec 59',
+      'Jan 60 - Jun 60',
+      'Jul 60 - Dec 60',
+      'Jan 61 - Jun 61',
+      'Jul 61 - Dec 61',
+      'Jan 62 - Jun 62',
+      'Jul 62 - Dec 62',
+      'Jan 63 - Jun 63',
+      'Jul 63 - Dec 63',
+      'Jan 64 - Jun 64',
+      'Jul 64 - Dec 64',
+      'Jan 65 - Jun 65',
+      'Jul 65 - Dec 65',
+    ]);
+  });
+
+  it('correctly aligns bins to exact year boundaries when binSnapping=year', async () => {
+    const el = await fixture<HistogramDateRange>(
+      html`
+        <histogram-date-range
+          binSnapping="year"
+          minDate="2000"
+          maxDate="2019"
+          bins="[10,20,30,40,50,60,70,80,90,100]"
+        ></histogram-date-range>
+      `
+    );
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    const tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql([
+      '2000 - 2001',
+      '2002 - 2003',
+      '2004 - 2005',
+      '2006 - 2007',
+      '2008 - 2009',
+      '2010 - 2011',
+      '2012 - 2013',
+      '2014 - 2015',
+      '2016 - 2017',
+      '2018 - 2019',
+    ]);
+  });
+
+  it('correctly handles year snapping for years 0-99', async () => {
+    const el = await fixture<HistogramDateRange>(
+      html`
+        <histogram-date-range
+          binSnapping="year"
+          dateFormat="YYYY"
+          minDate="0020"
+          maxDate="0025"
+          bins="[1,2,3,4,5,6]"
+        ></histogram-date-range>
+      `
+    );
+
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    const tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql(['20', '21', '22', '23', '24', '25']);
+  });
+
+  it('does not duplicate start/end date in tooltips when representing a single year', async () => {
+    const el = await fixture<HistogramDateRange>(
+      html`
+        <histogram-date-range
+          binSnapping="year"
+          dateFormat="YYYY"
+          minDate="2001"
+          maxDate="2005"
+          bins="[10,20,30,40,50]"
+        ></histogram-date-range>
+      `
+    );
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    const tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql(['2001', '2002', '2003', '2004', '2005']);
+  });
+
+  it('falls back to default date format for tooltips if no tooltip date format provided', async () => {
+    const el = await fixture<HistogramDateRange>(
+      html`
+        <histogram-date-range
+          binSnapping="year"
+          minDate="2001"
+          maxDate="2005"
+          bins="[10,20,30,40,50]"
+        ></histogram-date-range>
+      `
+    );
+
+    const bars = el.shadowRoot?.querySelectorAll(
+      '.bar'
+    ) as unknown as SVGRectElement[];
+    let tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql(['2001', '2002', '2003', '2004', '2005']); // default YYYY date format
+
+    el.dateFormat = 'YYYY/MM';
+    el.minDate = '2001/01';
+    el.maxDate = '2005/01';
+    await el.updateComplete;
+
+    // Should use dateFormat fallback for tooltips
+    tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql([
+      '2001/01 - 2001/12',
+      '2002/01 - 2002/12',
+      '2003/01 - 2003/12',
+      '2004/01 - 2004/12',
+      '2005/01 - 2005/12',
+    ]);
+
+    el.dateFormat = 'YYYY';
+    el.tooltipDateFormat = 'MMMM YYYY';
+    el.minDate = '2001';
+    el.maxDate = '2005';
+    await el.updateComplete;
+
+    // Should use defined tooltipDateFormat for tooltips
+    tooltips = Array.from(bars).map(b => b.dataset.tooltip);
+    expect(tooltips).to.eql([
+      'January 2001 - December 2001',
+      'January 2002 - December 2002',
+      'January 2003 - December 2003',
+      'January 2004 - December 2004',
+      'January 2005 - December 2005',
+    ]);
+  });
+
   it('has a disabled state', async () => {
     const el = await fixture<HistogramDateRange>(
       html`
@@ -629,7 +879,7 @@ describe('HistogramDateRange', () => {
     await el.updateComplete;
 
     // cursor is not draggable if disabled
-    expect(Array.from(minSlider.classList).join(' ')).to.eq('');
+    expect(minSlider.classList.contains('draggable')).to.be.false;
 
     // attempt to slide to right
     window.dispatchEvent(new PointerEvent('pointermove', { clientX: 70 }));

package/types/dayjs.d.ts

@@ -0,0 +1,10 @@
+export { default } from 'dayjs/esm';
+
+declare module 'dayjs/esm' {
+  // Widening the Dayjs interface so that we can properly extend it via plugin
+  interface Dayjs {
+    $d: Date;
+    parse(cfg: { date: unknown; args: unknown[] }): void;
+    init(): void;
+  }
+}