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

package/demo/index.html

@@ -79,6 +79,33 @@
       </histogram-date-range>
     </div>
 
+    <div class="container">
+      <div class="description">bins rounded to nearest month</div>
+      <histogram-date-range
+        width="175"
+        tooltipwidth="120"
+        dateFormat="YYYY-MM"
+        tooltipDateFormat="MMM YYYY"
+        binSnapping="month"
+        minDate="2009-05"
+        maxDate="2014-08"
+        bins="[100,5000,2000,100,5000,2000,100,5000,2000,100,5000,2000,100,5000,2000,100]"
+        style="--histogramDateRangeInputWidth: 50px;"
+      ></histogram-date-range>
+    </div>
+
+    <div class="container">
+      <div class="description">bins rounded to nearest year</div>
+      <histogram-date-range
+        width="175"
+        dateFormat="YYYY"
+        binSnapping="year"
+        minDate="2009"
+        maxDate="2014"
+        bins="[100,5000,2000,100,5000,2000]"
+      ></histogram-date-range>
+    </div>
+
     <div class="container">
       <div class="description">
         default range with custom styling and date format

package/dist/index.d.ts

@@ -1 +1 @@
-export { HistogramDateRange } from './src/histogram-date-range';
+export { HistogramDateRange, BinSnappingInterval as BinRoundingInterval, } from './src/histogram-date-range';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { HistogramDateRange } from './src/histogram-date-range';
+export { HistogramDateRange, } from './src/histogram-date-range';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC","sourcesContent":["export { HistogramDateRange } from './src/histogram-date-range';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAEnB,MAAM,4BAA4B,CAAC","sourcesContent":["export {\n  HistogramDateRange,\n  BinSnappingInterval as BinRoundingInterval,\n} from './src/histogram-date-range';\n"]}

package/dist/src/histogram-date-range.d.ts

@@ -1,5 +1,6 @@
 import '@internetarchive/ia-activity-indicator';
 import { LitElement, PropertyValues, SVGTemplateResult, TemplateResult } from 'lit';
+export declare type BinSnappingInterval = 'none' | 'month' | 'year';
 export declare class HistogramDateRange extends LitElement {
     width: number;
     height: number;
@@ -8,8 +9,6 @@ export declare class HistogramDateRange extends LitElement {
     tooltipHeight: number;
     updateDelay: number;
     dateFormat: string;
-    /** Optional; falls back to `dateFormat` if not provided */
-    tooltipDateFormat?: string;
     missingDataMessage: string;
     minDate: string;
     maxDate: string;
@@ -17,9 +16,12 @@ export declare class HistogramDateRange extends LitElement {
     bins: number[];
     /** If true, update events will not be canceled by the date inputs receiving focus */
     updateWhileFocused: boolean;
+    /** What interval bins should be rounded to for display */
+    binSnapping: BinSnappingInterval;
     private _tooltipOffset;
     private _tooltipContent?;
     private _tooltipVisible;
+    private _tooltipDateFormat?;
     private _isDragging;
     private _isLoading;
     private _minSelectedDate;
@@ -44,19 +46,45 @@ export declare class HistogramDateRange extends LitElement {
      */
     private handleDataUpdate;
     /**
-     * Rounds the given timestamp to the nearest start of a new month
+     * Rounds the given timestamp to the next full second.
      */
-    private roundToMonth;
+    private snapToNextSecond;
+    /**
+     * Rounds the given timestamp to the (approximate) nearest start of a month,
+     * such that dates up to and including the 15th of the month are rounded down,
+     * while dates past the 15th are rounded up.
+     */
+    private snapToMonth;
+    /**
+     * Rounds the given timestamp to the (approximate) nearest start of a year,
+     * such that dates up to the end of June are rounded down, while dates in
+     * July or later are rounded up.
+     */
+    private snapToYear;
+    /**
+     * Rounds the given timestamp according to the `binSnapping` property.
+     * Default is simply to snap to the nearest full second.
+     */
+    private snapTimestamp;
     private calculateHistData;
     private get hasBinData();
     private get _numBins();
     private get histogramLeftEdgeX();
     private get histogramRightEdgeX();
     /**
-     * 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();
+    /**
+     * Offset added to the end of each bin to ensure disjoin intervals, if applicable.
+     */
+    private get snapEndOffset();
+    /**
+     * Optional date format to use for tooltips only.
+     * Falls back to `dateFormat` if not provided.
      */
-    private get resolvedTooltipDateFormat();
+    get tooltipDateFormat(): string;
+    set tooltipDateFormat(value: string);
     /** component's loading (and disabled) state */
     get loading(): boolean;
     set loading(value: boolean);
@@ -146,6 +174,10 @@ export declare class HistogramDateRange extends LitElement {
     private generateSliderSVG;
     get selectedRangeTemplate(): SVGTemplateResult;
     get histogramTemplate(): SVGTemplateResult[];
+    /** Whether the first arg represents a date strictly before the second arg */
+    private isBefore;
+    /** Whether the first arg represents a date strictly after the second arg */
+    private isAfter;
     private formatDate;
     /**
      * NOTE: we are relying on the lit `live` directive in the template to

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

@@ -51,6 +51,8 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
         this.bins = [];
         /** If true, update events will not be canceled by the date inputs receiving focus */
         this.updateWhileFocused = false;
+        /** What interval bins should be rounded to for display */
+        this.binSnapping = 'none';
         // internal reactive properties not exposed as attributes
         this._tooltipOffset = 0;
         this._tooltipVisible = false;
@@ -102,6 +104,9 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
             }
             else {
                 this.maxSelectedDate = this.translatePositionToDate(this.validMaxSliderX(newX));
+                if (this.getMSFromString(this.maxSelectedDate) > this._maxDateMS) {
+                    this.maxSelectedDate = this.maxDate;
+                }
             }
         };
     }
@@ -118,7 +123,8 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
             changedProps.has('minSelectedDate') ||
             changedProps.has('maxSelectedDate') ||
             changedProps.has('width') ||
-            changedProps.has('height')) {
+            changedProps.has('height') ||
+            changedProps.has('binSnapping')) {
             this.handleDataUpdate();
         }
     }
@@ -134,8 +140,10 @@ let HistogramDateRange = 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();
@@ -147,14 +155,49 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
             : this.maxDate;
     }
     /**
-     * Rounds the given timestamp to the nearest start of a new month
+     * Rounds the given timestamp to the next full second.
      */
-    roundToMonth(timestamp) {
-        const date = new Date(timestamp);
-        const [y, m, d] = [date.getFullYear(), date.getMonth(), date.getDate()];
-        return d < 15
-            ? new Date(y, m, 1).getTime()
-            : new Date(y, m + 1, 1).getTime();
+    snapToNextSecond(timestamp) {
+        return Math.ceil(timestamp / 1000) * 1000;
+    }
+    /**
+     * Rounds the given timestamp to the (approximate) nearest start of a month,
+     * such that dates up to and including the 15th of the month are rounded down,
+     * while dates past the 15th are rounded up.
+     */
+    snapToMonth(timestamp) {
+        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();
+    }
+    /**
+     * Rounds the given timestamp to the (approximate) nearest start of a year,
+     * such that dates up to the end of June are rounded down, while dates in
+     * July or later are rounded up.
+     */
+    snapToYear(timestamp) {
+        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();
+    }
+    /**
+     * Rounds the given timestamp according to the `binSnapping` property.
+     * Default is simply to snap to the nearest full second.
+     */
+    snapTimestamp(timestamp) {
+        switch (this.binSnapping) {
+            case 'year':
+                return this.snapToYear(timestamp);
+            case 'month':
+                return this.snapToMonth(timestamp);
+            case 'none':
+            default:
+                return this.snapToNextSecond(timestamp);
+        }
     }
     calculateHistData() {
         const { bins, height, dateRangeMS, _numBins, _minDateMS } = this;
@@ -166,15 +209,25 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
         const valueScale = height / valueRange;
         const dateScale = dateRangeMS / _numBins;
         return bins.map((v, i) => {
-            const binStartMS = this.roundToMonth(i * dateScale + _minDateMS);
-            const binEndMS = this.roundToMonth((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,
             };
         });
     }
@@ -194,12 +247,37 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
         return this.width - this.sliderWidth;
     }
     /**
-     * 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.
+     */
+    get snapInterval() {
+        const yearMS = 31536000000; // A 365-day approximation of ms in a year
+        const monthMS = 2592000000; // 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.
      */
-    get resolvedTooltipDateFormat() {
+    get snapEndOffset() {
+        return this.binSnapping !== 'none' && this._numBins > 1 ? -1 : 0;
+    }
+    /**
+     * Optional date format to use for tooltips only.
+     * Falls back to `dateFormat` if not provided.
+     */
+    get tooltipDateFormat() {
         var _a, _b;
-        return (_b = (_a = this.tooltipDateFormat) !== null && _a !== void 0 ? _a : this.dateFormat) !== null && _b !== void 0 ? _b : DATE_FORMAT;
+        return (_b = (_a = this._tooltipDateFormat) !== null && _a !== void 0 ? _a : this.dateFormat) !== null && _b !== void 0 ? _b : DATE_FORMAT;
+    }
+    set tooltipDateFormat(value) {
+        this._tooltipDateFormat = value;
     }
     /** component's loading (and disabled) state */
     get loading() {
@@ -232,7 +310,7 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
     }
     /** formatted maximum date of selected date range */
     get maxSelectedDate() {
-        return this.formatDate(this.getMSFromString(this._maxSelectedDate) - 1);
+        return this.formatDate(this.getMSFromString(this._maxSelectedDate));
     }
     /** updates maxSelectedDate if new date is valid */
     set maxSelectedDate(rawDate) {
@@ -258,7 +336,8 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
     }
     /** horizontal position of max date slider */
     get maxSliderX() {
-        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);
     }
     get dateRangeMS() {
@@ -272,15 +351,12 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
         const x = target.x.baseVal.value + this.sliderWidth / 2;
         const dataset = target.dataset;
         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 =
             x + (this._binWidth - this.sliderWidth - this.tooltipWidth) / 2;
         this._tooltipContent = html `
       ${formattedNumItems} ${itemsText}<br />
-      ${datesText}
+      ${dataset.tooltip}
     `;
         this._tooltipVisible = true;
     }
@@ -377,9 +453,10 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
      * @returns string representation of date
      */
     translatePositionToDate(x) {
-        // 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(((x - this.sliderWidth) * this.dateRangeMS) / this._histWidth);
+        // 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);
     }
     /**
@@ -539,35 +616,52 @@ let HistogramDateRange = class HistogramDateRange extends LitElement {
     }
     get histogramTemplate() {
         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 */
+    isBefore(date1, date2) {
+        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 */
+    isAfter(date1, date2) {
+        const date1MS = this.getMSFromString(date1);
+        const date2MS = this.getMSFromString(date2);
+        return date1MS > date2MS;
+    }
     formatDate(dateMS, format = this.dateFormat) {
         if (Number.isNaN(dateMS)) {
             return '';
@@ -821,9 +915,6 @@ __decorate([
 __decorate([
     property({ type: String })
 ], HistogramDateRange.prototype, "dateFormat", void 0);
-__decorate([
-    property({ type: String })
-], HistogramDateRange.prototype, "tooltipDateFormat", void 0);
 __decorate([
     property({ type: String })
 ], HistogramDateRange.prototype, "missingDataMessage", void 0);
@@ -842,6 +933,9 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], HistogramDateRange.prototype, "updateWhileFocused", void 0);
+__decorate([
+    property({ type: String })
+], HistogramDateRange.prototype, "binSnapping", void 0);
 __decorate([
     state()
 ], HistogramDateRange.prototype, "_tooltipOffset", void 0);
@@ -851,12 +945,18 @@ __decorate([
 __decorate([
     state()
 ], HistogramDateRange.prototype, "_tooltipVisible", void 0);
+__decorate([
+    state()
+], HistogramDateRange.prototype, "_tooltipDateFormat", void 0);
 __decorate([
     state()
 ], HistogramDateRange.prototype, "_isDragging", void 0);
 __decorate([
     state()
 ], HistogramDateRange.prototype, "_isLoading", void 0);
+__decorate([
+    property({ type: String })
+], HistogramDateRange.prototype, "tooltipDateFormat", null);
 __decorate([
     property({ type: Boolean })
 ], HistogramDateRange.prototype, "loading", null);