@knight-lab/timelinejs 3.8.21 → 3.9.1

package/src/js/core/TimelineConfig.js

@@ -177,7 +177,6 @@ export class TimelineConfig {
             trace("Missing start date, skipping event")
             console.log(data)
             return null
-                // throw new TLError("missing_start_date_err", event_id);
         }
 
         this._processDates(data);

package/src/js/date/TLDate.js

@@ -178,13 +178,24 @@ export const TLDate = TLClass.extend({
             this._createDateObj();
         }
 
+        if (data.format && !format) {
+            format = data.format
+        }
         this._setFormat(format, format_short);
     },
 
     setDateFormat: function(format) {
         this.data.format = format;
     },
-
+    /**
+     * Return a string representation of this date. If this date has been created with a `display_date` property,
+     * that value is always returned, regardless of arguments to the method invocation. Otherwise,
+     * the given `Language` is asked to create a string representation based on this Date's data, passing through the provided
+     * `format` String, or, if that is undefined, this date's default format string.
+     * @param {Language} language
+     * @param {String} format
+     * @returns {String} formattedDate
+     */
     getDisplayDate: function(language, format) {
         if (this.data.display_date) {
             return this.data.display_date;
@@ -345,6 +356,14 @@ export const TLDate = TLClass.extend({
         } else if (!this.data.format_short) {
             this.data.format_short = this.findBestFormat(true);
         }
+    },
+    /**
+     * Get the year-only representation of this date. Ticks need this to layout
+     * the time axis, and this needs to work isomorphically for TLDate and BigDate 
+     * @returns {Number}
+     */
+    getFullYear: function() {
+        return this.data.date_obj.getFullYear()
     }
 });
 
@@ -477,6 +496,10 @@ export const BigDate = TLDate.extend({
             this._createDateObj();
         }
 
+        if (data.format && !format) {
+            format = data.format
+        }
+
         this._setFormat(format, format_short);
     },
 
@@ -497,5 +520,13 @@ export const BigDate = TLDate.extend({
         }
 
         throw new TLError("invalid_scale_err", scale);
+    },
+    /**
+     * Get the year-only representation of this date. Ticks need this to layout
+     * the time axis, and this needs to work isomorphically for TLDate and BigDate 
+     * @returns {Number}
+     */
+    getFullYear: function() {
+        return this.data.date_obj.getTime()
     }
 });

package/src/js/date/__tests__/TLDate.test.js

@@ -55,6 +55,16 @@ test("display_text overrides other formatting", () => {
 
 })
 
+test("date constructor format overrides other formatting", () => {
+    var cdate = new TLDate({ year: 2014, month: 12 }, 'yyyy')
+    expect(cdate.getDisplayDate()).toBe('2014')
+})
+
+test("format in constructor data param overrides other formatting", () => {
+    var cdate = new TLDate({ year: 2014, month: 12, format: 'yyyy' })
+    expect(cdate.getDisplayDate()).toBe('2014')
+})
+
 test("handle years in the first century CE correctly", () => {
     var date = makeDate({ year: 75 });
     expect(date.getDisplayDate()).toBe("75")

package/src/js/dom/DOMUtil.js

@@ -5,21 +5,21 @@
 ================================================== */
 
 function hasClass(el, name) {
-	return (el.className.length > 0) &&
-			new RegExp("(^|\\s)" + name + "(\\s|$)").test(el.className);
+    return (el.className.length > 0) &&
+        new RegExp("(^|\\s)" + name + "(\\s|$)").test(el.className);
 }
 
 export function addClass(el, name) {
-	if (!hasClass(el, name)) {
-		el.className += (el.className ? ' ' : '') + name;
-	}
+    if (!hasClass(el, name)) {
+        el.className += (el.className ? ' ' : '') + name;
+    }
 }
 
 export function removeClass(el, name) {
-	el.className = el.className.replace(/(\S+)\s*/g, function (w, match) {
-		if (match === name) {
-			return '';
-		}
-		return w;
-	}).replace(/^\s+/, '');
-}
+    el.className = el.className.replace(/(\S+)\s*/g, function(w, match) {
+        if (match === name) {
+            return '';
+        }
+        return w;
+    }).replace(/^\s+/, '');
+}

package/src/js/language/I18NMixins.js

@@ -1,5 +1,5 @@
 /*  I18NMixins
-    assumes that its class has an options object with a Language instance    
+    assumes that its class has an attribute `language` with a Language instance    
 ================================================== */
 import { trace } from "../core/Util"
 import { fallback } from "../language/Language"
@@ -24,8 +24,18 @@ class I18NMixins {
         return fallback;
     }
 
-    _(msg) {
-        return this.getLanguage()._(msg);
+    /**
+     * Look up a localized version of a standard message using the Language instance
+     * that was previously set with {@link setLanguage}.
+     * 
+     * @see {@link Language#_}
+     * @param {string} msg - a message key 
+     * @param {Object} [context] - a dictionary with string keys appropriate to message `k` 
+     *      and string values which will be interpolated into the message.
+     * @returns {string} - a localized string appropriate to the message key
+     */
+    _(msg, context) {
+        return this.getLanguage()._(msg, context);
     }
 }
 

package/src/js/language/Language.js

@@ -1,19 +1,21 @@
 import { mergeData, pad, trace } from "../core/Util"
 import { fetchJSON } from "../net/Net"
 import { BigYear } from "../date/TLDate"
+import TLError from "../core/TLError";
 
-/**
- * Instantiate a Language object to manage I18N. 
- * WARNING: In general, this should not be called directly, because it doesn't block while
- * the language file is loaded, which can lead to race conditions in some cases. In most
- * cases, language objects other than the fallback should be gotten by calling the 
- * async function loadLanguage defined elsewhere in this file.
- * 
- * @param {String} [language=en] - a language code or a URL to a 
- *     translation file
- * @param {string} [script_path] - if `language` is not a URL, this is used
- *     to construct a fully-qualified URL to load a translation file.
- */
+const MESSAGE_VARIABLE_PATTERN = new RegExp(/\$\{(.+?)\}/g)
+    /**
+     * Instantiate a Language object to manage I18N. 
+     * WARNING: In general, this should not be called directly, because it doesn't block while
+     * the language file is loaded, which can lead to race conditions in some cases. In most
+     * cases, language objects other than the fallback should be gotten by calling the 
+     * async function loadLanguage defined elsewhere in this file.
+     * 
+     * @param {String} [language=en] - a language code or a URL to a 
+     *     translation file
+     * @param {string} [script_path] - if `language` is not a URL, this is used
+     *     to construct a fully-qualified URL to load a translation file.
+     */
 class Language {
     constructor(language, script_path) {
         // borrowed from http://stackoverflow.com/a/14446414/102476
@@ -73,8 +75,28 @@ class Language {
         }
     }
 
-    _(k) {
-        return this.messages[k] || Language.fallback.messages[k] || k;
+    /**
+     * Look up a localized version of a standard message. While using `_` for the
+     * method name is not exactly idiomatic javascript, it was inspired by Python's
+     * {@link https://docs.python.org/3/library/gettext.html|gettext} module, with
+     * the intention of reducing clutter in places where, in a non-I18N'd app, you'd 
+     * simply have a quoted string.
+     * 
+     * @param {string} k - a message key 
+     * @param {Object} [context] - a dictionary with string keys appropriate to message `k` 
+     *      and string values which will be interpolated into the message.
+     * @returns {string} - a localized string appropriate to the message key
+     */
+    _(k, context) {
+        let msg = this.messages[k] || Language.fallback.messages[k] || k;
+        if (msg.match(MESSAGE_VARIABLE_PATTERN)) {
+            if (!context) throw new TLError("template_message_without_context")
+            for (let match of msg.matchAll(MESSAGE_VARIABLE_PATTERN)) {
+                if (!(match[1] in context)) throw new TLError("template_message_without_context")
+                msg = msg.replace(match[0], context[match[1]])
+            }
+        }
+        return msg
     }
 
     formatDate(date, format_name) {
@@ -267,19 +289,17 @@ var LANGUAGES = {
             loading: "Loading",
             wikipedia: "From Wikipedia, the free encyclopedia",
             error: "Error",
-            contract_timeline: "Contract Timeline",
             return_to_title: "Return to Title",
+            go_to_end: "Go to the last slide",
             loading_content: "Loading Content",
-            expand_timeline: "Expand Timeline",
             loading_timeline: "Loading Timeline... ",
             swipe_to_navigate: "Swipe to Navigate<br><span class='tl-button'>OK</span>",
+            zoom_in: "Zoom in",
+            zoom_out: "Zoom out",
             unknown_read_err: "An unexpected error occurred trying to read your spreadsheet data",
             invalid_url_err: "Unable to read Timeline data. Make sure your URL is for a Google Spreadsheet or a Timeline JSON file.",
-            invalid_url_share_required: "Because of unexpected changes to Google's data access API, the creator of this timeline must enable 'anyone with the url can read' access for this spreadsheet. See timeline.knightlab.com for more information.",
             network_err: "Unable to read your Google Spreadsheet. Make sure you have published it to the web.",
-            empty_feed_err: "No data entries found",
             missing_start_date_err: "Missing start_date",
-            invalid_data_format_err: "Header row has been modified.",
             invalid_start_time_without_date: "Invalid configuration: time cannot be used without date.",
             invalid_end_time_without_date: "Invalid configuration: end time cannot be used without end date.",
             date_compare_err: "Can't compare timeline date objects on different scales",
@@ -295,19 +315,26 @@ var LANGUAGES = {
             flickr_notfound_err: "Photo not found or private",
             flickr_invalidurl_err: "Invalid Flickr URL",
             imgur_invalidurl_err: "Invalid Imgur URL",
-            twitter_invalidurl_err: "Invalid Twitter URL",
             twitter_load_err: "Unable to load Tweet",
             twitterembed_invalidurl_err: "Invalid Twitter Embed url",
             wikipedia_load_err: "Unable to load Wikipedia entry",
-            youtube_invalidurl_err: "Invalid YouTube URL",
             spotify_invalid_url: "Invalid Spotify URL",
-            template_value_err: "No value provided for variable",
             invalid_rgb_err: "Invalid RGB argument",
             time_scale_scale_err: "Don't know how to get date from time for scale",
             axis_helper_no_options_err: "Axis helper must be configured with options",
             axis_helper_scale_err: "No AxisHelper available for scale",
             invalid_integer_option: "Invalid option value—must be a whole number.",
-            instagram_bad_request: "Invalid or private Instagram URL"
+            instagram_bad_request: "Invalid or private Instagram URL",
+            template_message_without_context: "Required variables not provided for template translation message",
+            aria_label_timeline: "Timeline",
+            aria_label_timeline_navigation: "Timeline navigation",
+            aria_label_timeline_content: "Timeline content",
+            // The following message keys are pseudo-template literal. 
+            // Do not surround with backticks (`) since evaluation is deferred 
+            // (and backticks wouldn't be allowed in JSON localization files)
+            // for each, document typical values for variable components
+            aria_label_zoomin: "Show less than ${start} to ${end}", // 'start' and 'end' should be numeric years 
+            aria_label_zoomout: "Show more than ${start} to ${end}" // 'start' and 'end' should be numeric years 
         },
         date: {
             month: [

package/src/js/language/__tests__/Language.test.js

@@ -0,0 +1,32 @@
+import { fallback } from "../Language"
+import { classMixin } from "../../core/Util"
+import { I18NMixins } from "../I18NMixins"
+class MixinTest {
+
+}
+
+classMixin(MixinTest, I18NMixins)
+
+test("Test variable interpolation", () => {
+    let msg = fallback._("aria_label_zoomin", { start: 1900, end: 2000 })
+    expect(msg).toBe('Show less than 1900 to 2000')
+})
+
+test("Test variable interpolation error checking with no context", () => {
+    expect(() => {
+        let msg = fallback._("aria_label_zoomin")
+    }).toThrow()
+})
+
+test("Test variable interpolation error checking with partial context", () => {
+    expect(() => {
+        let msg = fallback._("aria_label_zoomin", { start: 1900 })
+    }).toThrow()
+})
+
+test("Test interpolation through a mixin", () => {
+    let mixin = new MixinTest()
+    mixin.setLanguage(fallback)
+    let msg = mixin._("aria_label_zoomin", { start: 1900, end: 2000 })
+    expect(msg).toBe('Show less than 1900 to 2000')
+})

package/src/js/language/locale/af.json

@@ -1,75 +1,73 @@
 {
-    "lang": "af", 
+    "lang": "af",
     "date": {
         "month_abbr": [
-            "Jan.", 
-            "Feb.", 
-            "Maart", 
-            "April", 
-            "Mei", 
-            "Junei", 
-            "Julie", 
-            "Aug.", 
-            "Sept.", 
-            "Okt.", 
-            "Nov.", 
+            "Jan.",
+            "Feb.",
+            "Maart",
+            "April",
+            "Mei",
+            "Junei",
+            "Julie",
+            "Aug.",
+            "Sept.",
+            "Okt.",
+            "Nov.",
             "Des."
-        ], 
+        ],
         "day_abbr": [
-            "Son.", 
-            "Maan.", 
-            "Dins.", 
-            "Woen.", 
-            "Don.", 
-            "Vry.", 
+            "Son.",
+            "Maan.",
+            "Dins.",
+            "Woen.",
+            "Don.",
+            "Vry.",
             "Sat."
-        ], 
+        ],
         "day": [
-            "Sondag", 
-            "Maandag", 
-            "Dinsdag", 
-            "Woensdag", 
-            "Donderdag", 
-            "Vrydag", 
+            "Sondag",
+            "Maandag",
+            "Dinsdag",
+            "Woensdag",
+            "Donderdag",
+            "Vrydag",
             "Saterdag"
-        ], 
+        ],
         "month": [
-            "Januarie", 
-            "Februarie", 
-            "Maart", 
-            "April", 
-            "Mei", 
-            "Junie", 
-            "Julie", 
-            "Augustus", 
-            "September", 
-            "Oktober", 
-            "November", 
+            "Januarie",
+            "Februarie",
+            "Maart",
+            "April",
+            "Mei",
+            "Junie",
+            "Julie",
+            "Augustus",
+            "September",
+            "Oktober",
+            "November",
             "Desember"
         ]
-    }, 
+    },
     "api": {
         "wikipedia": "af"
-    }, 
+    },
     "messages": {
-        "loading": "Aan't laai", 
-        "contract_timeline": "Krimp die tydlyn", 
-        "return_to_title": "Begin voor", 
-        "wikipedia": "Van Wikipedia, die gratis ensiklopedie", 
-        "loading_content": "Die inhoud laai", 
-        "expand_timeline": "Rek die tydlyn", 
+        "loading": "Aan't laai",
+        "return_to_title": "Begin voor",
+        "wikipedia": "Van Wikipedia, die gratis ensiklopedie",
+        "loading_content": "Die inhoud laai",
         "loading_timeline": "Die tydlyn laai... "
-    }, 
+    },
     "dateformats": {
-        "full_long": "d mmm',' yyyy 'om' HH:MM", 
-        "full_short": "d mmm", 
-        "full": "d mmmm yyyy", 
-        "month_short": "mmm", 
-        "time_no_seconds_small_date": "HH:MM'<br/><small>'d mmmm yyyy'</small>'", 
-        "month": "mmmm yyyy", 
-        "time_no_seconds_short": "HH:MM", 
-        "time_short": "HH:MM:ss", 
-        "year": "yyyy", 
+        "full_long": "d mmm',' yyyy 'om' HH:MM",
+        "full_short": "d mmm",
+        "full": "d mmmm yyyy",
+        "month_short": "mmm",
+        "time_no_seconds_small_date": "HH:MM'<br/><small>'d mmmm yyyy'</small>'",
+        "month": "mmmm yyyy",
+        "time_no_seconds_short": "HH:MM",
+        "time_short": "HH:MM:ss",
+        "year": "yyyy",
         "full_long_small_date": "HH:MM'<br/><small>d mmm yyyy'</small>'"
     }
 }

package/src/js/language/locale/ar.json

@@ -1,76 +1,74 @@
 {
-    "lang": "ar", 
+    "lang": "ar",
     "direction": "rtl",
     "messages": {
-        "loading": "تحميل", 
-        "contract_timeline": "الاتفاقية", 
-        "return_to_title": "العودة", 
-        "wikipedia": "من ويكيبيديا, الموسوعة الحرة", 
-        "loading_content": "تحميل المحتوى", 
-        "expand_timeline": "تكبير العرض", 
+        "loading": "تحميل",
+        "return_to_title": "العودة",
+        "wikipedia": "من ويكيبيديا, الموسوعة الحرة",
+        "loading_content": "تحميل المحتوى",
         "loading_timeline": "جاري التحميل... "
-    }, 
+    },
     "api": {
         "wikipedia": "ar"
-    }, 
+    },
     "date": {
         "month_abbr": [
-            "كانون الثاني", 
-            "شباط", 
-            "آذار", 
-            "نيسان", 
-            "أيار", 
-            "حزيران", 
-            "تموز", 
-            "آب", 
-            "أيلول", 
-            "تشرين الأول", 
-            "تشرين الثاني", 
+            "كانون الثاني",
+            "شباط",
+            "آذار",
+            "نيسان",
+            "أيار",
+            "حزيران",
+            "تموز",
+            "آب",
+            "أيلول",
+            "تشرين الأول",
+            "تشرين الثاني",
             "كانون الأول"
-        ], 
+        ],
         "day_abbr": [
-            "الأحد", 
-            "الإثنين", 
-            "الثلاثاء", 
-            "الأربعاء", 
-            "الخميس", 
-            "الجمعة", 
+            "الأحد",
+            "الإثنين",
+            "الثلاثاء",
+            "الأربعاء",
+            "الخميس",
+            "الجمعة",
             "السبت"
-        ], 
+        ],
         "day": [
-            "الأحد", 
-            "الإثنين", 
-            "الثلاثاء", 
-            "الأربعاء", 
-            "الخميس", 
-            "الجمعة", 
+            "الأحد",
+            "الإثنين",
+            "الثلاثاء",
+            "الأربعاء",
+            "الخميس",
+            "الجمعة",
             "السبت"
-        ], 
+        ],
         "month": [
-            "كانون الثاني", 
-            "شباط", 
-            "آذار", 
-            "نيسان", 
-            "أيار", 
-            "حزيران", 
-            "تموز", 
-            "آب", 
-            "أيلول", 
-            "تشرين الأول", 
-            "تشرين الثاني", 
+            "كانون الثاني",
+            "شباط",
+            "آذار",
+            "نيسان",
+            "أيار",
+            "حزيران",
+            "تموز",
+            "آب",
+            "أيلول",
+            "تشرين الأول",
+            "تشرين الثاني",
             "كانون الأول"
         ]
-    }, 
+    },
     "dateformats": {
-        "full_long": "mmm d',' yyyy 'at' hh:MM TT", 
-        "full_short": "mmm d", 
-        "full": "mmmm d',' yyyy", 
-        "month_short": "mmm", 
-        "time_no_seconds_small_date": "h:MM TT'<br/><small>'mmmm d',' yyyy'</small>'", 
-        "month": "mmmm yyyy", 
-        "time_no_seconds_short": "h:MM TT", 
-        "time_short": "h:MM:ss TT", 
-        "year": "yyyy", 
+        "full_long": "mmm d',' yyyy 'at' hh:MM TT",
+        "full_short": "mmm d",
+        "full": "mmmm d',' yyyy",
+        "month_short": "mmm",
+        "time_no_seconds_small_date": "h:MM TT'<br/><small>'mmmm d',' yyyy'</small>'",
+        "month": "mmmm yyyy",
+        "time_no_seconds_short": "h:MM TT",
+        "time_short": "h:MM:ss TT",
+        "year": "yyyy",
         "full_long_small_date": "hh:MM TT'<br/><small>mmm d',' yyyy'</small>'"
     }
 }