diff options
Diffstat (limited to 'ext/js/templates/sandbox')
5 files changed, 462 insertions, 167 deletions
diff --git a/ext/js/templates/sandbox/anki-template-renderer-content-manager.js b/ext/js/templates/sandbox/anki-template-renderer-content-manager.js index 596fa499..4989ced3 100644 --- a/ext/js/templates/sandbox/anki-template-renderer-content-manager.js +++ b/ext/js/templates/sandbox/anki-template-renderer-content-manager.js @@ -17,30 +17,21 @@ */ /** - * A callback used when a media file has been loaded. - * @callback AnkiTemplateRendererContentManager.OnLoadCallback - * @param {string} url The URL of the media that was loaded. - */ - -/** - * A callback used when a media file should be unloaded. - * @callback AnkiTemplateRendererContentManager.OnUnloadCallback - * @param {boolean} fullyLoaded Whether or not the media was fully loaded. - */ - -/** * The content manager which is used when generating content for Anki. */ export class AnkiTemplateRendererContentManager { /** * Creates a new instance of the class. - * @param {TemplateRendererMediaProvider} mediaProvider The media provider for the object. - * @param {object} data The data object passed to the Handlebars template renderer. - * See {@link AnkiNoteDataCreator.create}'s return value for structure information. + * @param {import('./template-renderer-media-provider.js').TemplateRendererMediaProvider} mediaProvider The media provider for the object. + * @param {import('anki-templates').NoteData} data The data object passed to the Handlebars template renderer. + * See AnkiNoteDataCreator.create's return value for structure information. */ constructor(mediaProvider, data) { + /** @type {import('./template-renderer-media-provider.js').TemplateRendererMediaProvider} */ this._mediaProvider = mediaProvider; + /** @type {import('anki-templates').NoteData} */ this._data = data; + /** @type {import('anki-template-renderer-content-manager').OnUnloadCallback[]} */ this._onUnloadCallbacks = []; } @@ -48,9 +39,9 @@ export class AnkiTemplateRendererContentManager { * Attempts to load the media file from a given dictionary. * @param {string} path The path to the media file in the dictionary. * @param {string} dictionary The name of the dictionary. - * @param {AnkiTemplateRendererContentManager.OnLoadCallback} onLoad The callback that is executed if the media was loaded successfully. + * @param {import('anki-template-renderer-content-manager').OnLoadCallback} onLoad The callback that is executed if the media was loaded successfully. * No assumptions should be made about the synchronicity of this callback. - * @param {AnkiTemplateRendererContentManager.OnUnloadCallback} onUnload The callback that is executed when the media should be unloaded. + * @param {import('anki-template-renderer-content-manager').OnUnloadCallback} onUnload The callback that is executed when the media should be unloaded. */ loadMedia(path, dictionary, onLoad, onUnload) { const imageUrl = this._mediaProvider.getMedia(this._data, ['dictionaryMedia', path], {dictionary, format: 'fileName', default: null}); @@ -73,7 +64,7 @@ export class AnkiTemplateRendererContentManager { /** * Sets up attributes and events for a link element. - * @param {Element} element The link element. + * @param {HTMLAnchorElement} element The link element. * @param {string} href The URL. * @param {boolean} internal Whether or not the URL is an internal or external link. */ diff --git a/ext/js/templates/sandbox/anki-template-renderer.js b/ext/js/templates/sandbox/anki-template-renderer.js index 10f69745..dbf395e9 100644 --- a/ext/js/templates/sandbox/anki-template-renderer.js +++ b/ext/js/templates/sandbox/anki-template-renderer.js @@ -36,17 +36,29 @@ export class AnkiTemplateRenderer { * Creates a new instance of the class. */ constructor() { + /** @type {CssStyleApplier} */ this._structuredContentStyleApplier = new CssStyleApplier('/data/structured-content-style.json'); + /** @type {CssStyleApplier} */ this._pronunciationStyleApplier = new CssStyleApplier('/data/pronunciation-style.json'); + /** @type {RegExp} */ this._structuredContentDatasetKeyIgnorePattern = /^sc([^a-z]|$)/; + /** @type {JapaneseUtil} */ this._japaneseUtil = new JapaneseUtil(null); + /** @type {TemplateRenderer} */ this._templateRenderer = new TemplateRenderer(); + /** @type {AnkiNoteDataCreator} */ this._ankiNoteDataCreator = new AnkiNoteDataCreator(this._japaneseUtil); + /** @type {TemplateRendererMediaProvider} */ this._mediaProvider = new TemplateRendererMediaProvider(); + /** @type {PronunciationGenerator} */ this._pronunciationGenerator = new PronunciationGenerator(this._japaneseUtil); + /** @type {?(Map<string, unknown>[])} */ this._stateStack = null; + /** @type {?import('anki-note-builder').Requirement[]} */ this._requirements = null; - this._cleanupCallbacks = null; + /** @type {(() => void)[]} */ + this._cleanupCallbacks = []; + /** @type {?HTMLElement} */ this._temporaryElement = null; } @@ -93,7 +105,7 @@ export class AnkiTemplateRenderer { ]); this._templateRenderer.registerDataType('ankiNote', { modifier: ({marker, commonData}) => this._ankiNoteDataCreator.create(marker, commonData), - composeData: (marker, commonData) => ({marker, commonData}) + composeData: ({marker}, commonData) => ({marker, commonData}) }); this._templateRenderer.setRenderCallbacks( this._onRenderSetup.bind(this), @@ -107,40 +119,56 @@ export class AnkiTemplateRenderer { // Private + /** + * @returns {{requirements: import('anki-note-builder').Requirement[]}} + */ _onRenderSetup() { + /** @type {import('anki-note-builder').Requirement[]} */ const requirements = []; this._stateStack = [new Map()]; this._requirements = requirements; this._mediaProvider.requirements = requirements; - this._cleanupCallbacks = []; return {requirements}; } + /** + * @returns {void} + */ _onRenderCleanup() { for (const callback of this._cleanupCallbacks) { callback(); } this._stateStack = null; this._requirements = null; this._mediaProvider.requirements = null; - this._cleanupCallbacks = null; + this._cleanupCallbacks.length = 0; } + /** + * @param {string} text + * @returns {string} + */ _escape(text) { return Handlebars.Utils.escapeExpression(text); } + /** + * @param {string} text + * @returns {string} + */ _safeString(text) { return new Handlebars.SafeString(text); } // Template helpers - _dumpObject(context, object) { + /** @type {import('template-renderer').HelperFunction<string>} */ + _dumpObject(object) { const dump = JSON.stringify(object, null, 4); return this._escape(dump); } - _furigana(context, ...args) { - const {expression, reading} = this._getFuriganaExpressionAndReading(context, ...args); + /** @type {import('template-renderer').HelperFunction<string>} */ + _furigana(args, context, options) { + const {expression, reading} = this._getFuriganaExpressionAndReading(args, context, options); const segs = this._japaneseUtil.distributeFurigana(expression, reading); let result = ''; @@ -157,8 +185,9 @@ export class AnkiTemplateRenderer { return this._safeString(result); } - _furiganaPlain(context, ...args) { - const {expression, reading} = this._getFuriganaExpressionAndReading(context, ...args); + /** @type {import('template-renderer').HelperFunction<string>} */ + _furiganaPlain(args, context, options) { + const {expression, reading} = this._getFuriganaExpressionAndReading(args, context, options); const segs = this._japaneseUtil.distributeFurigana(expression, reading); let result = ''; @@ -174,43 +203,56 @@ export class AnkiTemplateRenderer { return result; } - _getFuriganaExpressionAndReading(context, ...args) { - if (args.length >= 3) { - return {expression: args[0], reading: args[1]}; - } else if (args.length === 2) { - const {expression, reading} = args[0]; - return {expression, reading}; + /** + * @type {import('template-renderer').HelperFunction<{expression: string, reading: string}>} + */ + _getFuriganaExpressionAndReading(args) { + let expression; + let reading; + if (args.length >= 2) { + [expression, reading] = /** @type {[expression?: string, reading?: string]} */ (args); } else { - return void 0; + ({expression, reading} = /** @type {import('core').SerializableObject} */ (args[0])); } + return { + expression: typeof expression === 'string' ? expression : '', + reading: typeof reading === 'string' ? reading : '' + }; } + /** + * @param {string} string + * @returns {string} + */ _stringToMultiLineHtml(string) { return string.split('\n').join('<br>'); } - _multiLine(context, options) { - return this._stringToMultiLineHtml(options.fn(context)); + /** @type {import('template-renderer').HelperFunction<string>} */ + _multiLine(_args, context, options) { + return this._stringToMultiLineHtml(this._asString(options.fn(context))); } - _regexReplace(context, ...args) { + /** @type {import('template-renderer').HelperFunction<string>} */ + _regexReplace(args, context, options) { // Usage: // {{#regexReplace regex string [flags] [content]...}}content{{/regexReplace}} // regex: regular expression string // string: string to replace // flags: optional flags for regular expression // e.g. "i" for case-insensitive, "g" for replace all - const argCount = args.length - 1; - const options = args[argCount]; - let value = typeof options.fn === 'function' ? options.fn(context) : ''; + const argCount = args.length; + let value = this._asString(options.fn(context)); if (argCount > 3) { value = `${args.slice(3, -1).join('')}${value}`; } if (argCount > 1) { try { - const flags = argCount > 2 ? args[2] : 'g'; - const regex = new RegExp(args[0], flags); - value = value.replace(regex, args[1]); + const [pattern, replacement, flags] = args; + if (typeof pattern !== 'string') { throw new Error('Invalid pattern'); } + if (typeof replacement !== 'string') { throw new Error('Invalid replacement'); } + const regex = new RegExp(pattern, typeof flags === 'string' ? flags : 'g'); + value = value.replace(regex, replacement); } catch (e) { return `${e}`; } @@ -218,24 +260,26 @@ export class AnkiTemplateRenderer { return value; } - _regexMatch(context, ...args) { + /** @type {import('template-renderer').HelperFunction<string>} */ + _regexMatch(args, context, options) { // Usage: // {{#regexMatch regex [flags] [content]...}}content{{/regexMatch}} // regex: regular expression string // flags: optional flags for regular expression // e.g. "i" for case-insensitive, "g" for match all - const argCount = args.length - 1; - const options = args[argCount]; - let value = typeof options.fn === 'function' ? options.fn(context) : ''; + const argCount = args.length; + let value = this._asString(options.fn(context)); if (argCount > 2) { value = `${args.slice(2, -1).join('')}${value}`; } if (argCount > 0) { try { - const flags = argCount > 1 ? args[1] : ''; - const regex = new RegExp(args[0], flags); + const [pattern, flags] = args; + if (typeof pattern !== 'string') { throw new Error('Invalid pattern'); } + const regex = new RegExp(pattern, typeof flags === 'string' ? flags : ''); + /** @type {string[]} */ const parts = []; - value.replace(regex, (g0) => parts.push(g0)); + value.replace(regex, (g0) => { parts.push(g0); return g0; }); value = parts.join(''); } catch (e) { return `${e}`; @@ -244,11 +288,18 @@ export class AnkiTemplateRenderer { return value; } - _mergeTags(context, object, isGroupMode, isMergeMode) { + /** + * @type {import('template-renderer').HelperFunction<string>} + */ + _mergeTags(args) { + const [object, isGroupMode, isMergeMode] = /** @type {[object: import('anki-templates').TermDictionaryEntry, isGroupMode: boolean, isMergeMode: boolean]} */ (args); const tagSources = []; if (isGroupMode || isMergeMode) { - for (const definition of object.definitions) { - tagSources.push(definition.definitionTags); + const {definitions} = object; + if (Array.isArray(definitions)) { + for (const definition of definitions) { + tagSources.push(definition.definitionTags); + } } } else { tagSources.push(object.definitionTags); @@ -265,7 +316,9 @@ export class AnkiTemplateRenderer { return [...tags].join(', '); } - _eachUpTo(context, iterable, maxCount, options) { + /** @type {import('template-renderer').HelperFunction<string>} */ + _eachUpTo(args, context, options) { + const [iterable, maxCount] = /** @type {[iterable: Iterable<unknown>, maxCount: number]} */ (args); if (iterable) { const results = []; let any = false; @@ -279,14 +332,15 @@ export class AnkiTemplateRenderer { return results.join(''); } } - return options.inverse(context); + return this._asString(options.inverse(context)); } - _spread(context, ...args) { + /** @type {import('template-renderer').HelperFunction<unknown[]>} */ + _spread(args) { const result = []; - for (let i = 0, ii = args.length - 1; i < ii; ++i) { + for (const array of /** @type {Iterable<unknown>[]} */ (args)) { try { - result.push(...args[i]); + result.push(...array); } catch (e) { // NOP } @@ -294,15 +348,22 @@ export class AnkiTemplateRenderer { return result; } - _op(context, ...args) { + /** @type {import('template-renderer').HelperFunction<unknown>} */ + _op(args) { + const [operator] = /** @type {[operator: string, operand1: import('core').SafeAny, operand2?: import('core').SafeAny, operand3?: import('core').SafeAny]} */ (args); switch (args.length) { - case 3: return this._evaluateUnaryExpression(args[0], args[1]); - case 4: return this._evaluateBinaryExpression(args[0], args[1], args[2]); - case 5: return this._evaluateTernaryExpression(args[0], args[1], args[2], args[3]); + case 2: return this._evaluateUnaryExpression(operator, args[1]); + case 3: return this._evaluateBinaryExpression(operator, args[1], args[2]); + case 4: return this._evaluateTernaryExpression(operator, args[1], args[2], args[3]); default: return void 0; } } + /** + * @param {string} operator + * @param {import('core').SafeAny} operand1 + * @returns {unknown} + */ _evaluateUnaryExpression(operator, operand1) { switch (operator) { case '+': return +operand1; @@ -313,6 +374,12 @@ export class AnkiTemplateRenderer { } } + /** + * @param {string} operator + * @param {import('core').SafeAny} operand1 + * @param {import('core').SafeAny} operand2 + * @returns {unknown} + */ _evaluateBinaryExpression(operator, operand1, operand2) { switch (operator) { case '+': return operand1 + operand2; @@ -341,6 +408,13 @@ export class AnkiTemplateRenderer { } } + /** + * @param {string} operator + * @param {import('core').SafeAny} operand1 + * @param {import('core').SafeAny} operand2 + * @param {import('core').SafeAny} operand3 + * @returns {unknown} + */ _evaluateTernaryExpression(operator, operand1, operand2, operand3) { switch (operator) { case '?:': return operand1 ? operand2 : operand3; @@ -348,8 +422,11 @@ export class AnkiTemplateRenderer { } } - _get(context, key) { + /** @type {import('template-renderer').HelperFunction<unknown>} */ + _get(args) { + const [key] = /** @type {[key: string]} */ (args); const stateStack = this._stateStack; + if (stateStack === null) { throw new Error('Invalid state'); } for (let i = stateStack.length; --i >= 0;) { const map = stateStack[i]; if (map.has(key)) { @@ -359,19 +436,21 @@ export class AnkiTemplateRenderer { return void 0; } - _set(context, ...args) { + /** @type {import('template-renderer').HelperFunction<string>} */ + _set(args, context, options) { const stateStack = this._stateStack; + if (stateStack === null) { throw new Error('Invalid state'); } switch (args.length) { - case 2: + case 1: { - const [key, options] = args; + const [key] = /** @type {[key: string]} */ (args); const value = options.fn(context); stateStack[stateStack.length - 1].set(key, value); } break; - case 3: + case 2: { - const [key, value] = args; + const [key, value] = /** @type {[key: string, value: unknown]} */ (args); stateStack[stateStack.length - 1].set(key, value); } break; @@ -379,8 +458,10 @@ export class AnkiTemplateRenderer { return ''; } - _scope(context, options) { + /** @type {import('template-renderer').HelperFunction<unknown>} */ + _scope(_args, context, options) { const stateStack = this._stateStack; + if (stateStack === null) { throw new Error('Invalid state'); } try { stateStack.push(new Map()); return options.fn(context); @@ -391,14 +472,25 @@ export class AnkiTemplateRenderer { } } - _property(context, ...args) { - const ii = args.length - 1; + /** @type {import('template-renderer').HelperFunction<unknown>} */ + _property(args) { + const ii = args.length; if (ii <= 0) { return void 0; } try { let value = args[0]; for (let i = 1; i < ii; ++i) { - value = value[args[i]]; + if (typeof value !== 'object' || value === null) { throw new Error('Invalid object'); } + const key = args[i]; + switch (typeof key) { + case 'number': + case 'string': + case 'symbol': + break; + default: + throw new Error('Invalid key'); + } + value = /** @type {import('core').UnknownObject} */ (value)[key]; } return value; } catch (e) { @@ -406,38 +498,51 @@ export class AnkiTemplateRenderer { } } - _noop(context, options) { + /** @type {import('template-renderer').HelperFunction<unknown>} */ + _noop(_args, context, options) { return options.fn(context); } - _isMoraPitchHigh(context, index, position) { + /** @type {import('template-renderer').HelperFunction<boolean>} */ + _isMoraPitchHigh(args) { + const [index, position] = /** @type {[index: number, position: number]} */ (args); return this._japaneseUtil.isMoraPitchHigh(index, position); } - _getKanaMorae(context, text) { + /** @type {import('template-renderer').HelperFunction<string[]>} */ + _getKanaMorae(args) { + const [text] = /** @type {[text: string]} */ (args); return this._japaneseUtil.getKanaMorae(`${text}`); } - _getTypeof(context, ...args) { - const ii = args.length - 1; - const value = (ii > 0 ? args[0] : args[ii].fn(context)); + /** @type {import('template-renderer').HelperFunction<import('core').TypeofResult>} */ + _getTypeof(args, context, options) { + const ii = args.length; + const value = (ii > 0 ? args[0] : options.fn(context)); return typeof value; } - _join(context, ...args) { - return args.length > 1 ? args.slice(1, args.length - 1).flat().join(args[0]) : ''; + /** @type {import('template-renderer').HelperFunction<string>} */ + _join(args) { + return args.length > 0 ? args.slice(1, args.length).flat().join(/** @type {string} */ (args[0])) : ''; } - _concat(context, ...args) { + /** @type {import('template-renderer').HelperFunction<string>} */ + _concat(args) { let result = ''; - for (let i = 0, ii = args.length - 1; i < ii; ++i) { + for (let i = 0, ii = args.length; i < ii; ++i) { result += args[i]; } return result; } - _pitchCategories(context, data) { - const {pronunciations, headwords} = data.dictionaryEntry; + /** @type {import('template-renderer').HelperFunction<string[]>} */ + _pitchCategories(args) { + const [data] = /** @type {[data: import('anki-templates').NoteData]} */ (args); + const {dictionaryEntry} = data; + if (dictionaryEntry.type !== 'term') { return []; } + const {pronunciations, headwords} = dictionaryEntry; + /** @type {Set<string>} */ const categories = new Set(); for (const {headwordIndex, pitches} of pronunciations) { const {reading, wordClasses} = headwords[headwordIndex]; @@ -452,6 +557,9 @@ export class AnkiTemplateRenderer { return [...categories]; } + /** + * @returns {HTMLElement} + */ _getTemporaryElement() { let element = this._temporaryElement; if (element === null) { @@ -461,14 +569,28 @@ export class AnkiTemplateRenderer { return element; } + /** + * @param {Element} node + * @returns {string} + */ _getStructuredContentHtml(node) { return this._getHtml(node, this._structuredContentStyleApplier, this._structuredContentDatasetKeyIgnorePattern); } + /** + * @param {Element} node + * @returns {string} + */ _getPronunciationHtml(node) { return this._getHtml(node, this._pronunciationStyleApplier, null); } + /** + * @param {Element} node + * @param {CssStyleApplier} styleApplier + * @param {?RegExp} datasetKeyIgnorePattern + * @returns {string} + */ _getHtml(node, styleApplier, datasetKeyIgnorePattern) { const container = this._getTemporaryElement(); container.appendChild(node); @@ -478,20 +600,27 @@ export class AnkiTemplateRenderer { return this._safeString(result); } + /** + * @param {Element} root + * @param {CssStyleApplier} styleApplier + * @param {?RegExp} datasetKeyIgnorePattern + */ _normalizeHtml(root, styleApplier, datasetKeyIgnorePattern) { const {ELEMENT_NODE, TEXT_NODE} = Node; const treeWalker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT); + /** @type {HTMLElement[]} */ const elements = []; + /** @type {Text[]} */ const textNodes = []; while (true) { const node = treeWalker.nextNode(); if (node === null) { break; } switch (node.nodeType) { case ELEMENT_NODE: - elements.push(node); + elements.push(/** @type {HTMLElement} */ (node)); break; case TEXT_NODE: - textNodes.push(node); + textNodes.push(/** @type {Text} */ (node)); break; } } @@ -508,8 +637,11 @@ export class AnkiTemplateRenderer { } } + /** + * @param {Text} textNode + */ _replaceNewlines(textNode) { - const parts = textNode.nodeValue.split('\n'); + const parts = /** @type {string} */ (textNode.nodeValue).split('\n'); if (parts.length <= 1) { return; } const {parentNode} = textNode; if (parentNode === null) { return; } @@ -521,6 +653,10 @@ export class AnkiTemplateRenderer { parentNode.replaceChild(fragment, textNode); } + /** + * @param {import('anki-templates').NoteData} data + * @returns {StructuredContentGenerator} + */ _createStructuredContentGenerator(data) { const contentManager = new AnkiTemplateRendererContentManager(this._mediaProvider, data); const instance = new StructuredContentGenerator(contentManager, this._japaneseUtil, document); @@ -528,44 +664,64 @@ export class AnkiTemplateRenderer { return instance; } - _formatGlossary(context, dictionary, content, options) { + /** + * @type {import('template-renderer').HelperFunction<string>} + */ + _formatGlossary(args, context, options) { + const [dictionary, content] = /** @type {[dictionary: string, content: import('dictionary-data').TermGlossary]} */ (args); const data = options.data.root; if (typeof content === 'string') { return this._stringToMultiLineHtml(this._escape(content)); } if (!(typeof content === 'object' && content !== null)) { return ''; } switch (content.type) { case 'image': return this._formatGlossaryImage(content, dictionary, data); case 'structured-content': return this._formatStructuredContent(content, dictionary, data); + case 'text': return this._stringToMultiLineHtml(this._escape(content.text)); } return ''; } + /** + * @param {import('dictionary-data').TermGlossaryImage} content + * @param {string} dictionary + * @param {import('anki-templates').NoteData} data + * @returns {string} + */ _formatGlossaryImage(content, dictionary, data) { const structuredContentGenerator = this._createStructuredContentGenerator(data); const node = structuredContentGenerator.createDefinitionImage(content, dictionary); return this._getStructuredContentHtml(node); } + /** + * @param {import('dictionary-data').TermGlossaryStructuredContent} content + * @param {string} dictionary + * @param {import('anki-templates').NoteData} data + * @returns {string} + */ _formatStructuredContent(content, dictionary, data) { const structuredContentGenerator = this._createStructuredContentGenerator(data); const node = structuredContentGenerator.createStructuredContent(content.content, dictionary); return node !== null ? this._getStructuredContentHtml(node) : ''; } - _hasMedia(context, ...args) { - const ii = args.length - 1; - const options = args[ii]; - return this._mediaProvider.hasMedia(options.data.root, args.slice(0, ii), options.hash); + /** + * @type {import('template-renderer').HelperFunction<boolean>} + */ + _hasMedia(args, _context, options) { + return this._mediaProvider.hasMedia(options.data.root, args, options.hash); } - _getMedia(context, ...args) { - const ii = args.length - 1; - const options = args[ii]; - return this._mediaProvider.getMedia(options.data.root, args.slice(0, ii), options.hash); + /** + * @type {import('template-renderer').HelperFunction<?string>} + */ + _getMedia(args, _context, options) { + return this._mediaProvider.getMedia(options.data.root, args, options.hash); } - _pronunciation(context, ...args) { - const ii = args.length - 1; - const options = args[ii]; + /** + * @type {import('template-renderer').HelperFunction<string>} + */ + _pronunciation(_args, _context, options) { let {format, reading, downstepPosition, nasalPositions, devoicePositions} = options.hash; if (typeof reading !== 'string' || reading.length === 0) { return ''; } @@ -586,18 +742,30 @@ export class AnkiTemplateRenderer { } } - _hiragana(context, ...args) { - const ii = args.length - 1; - const options = args[ii]; + /** + * @type {import('template-renderer').HelperFunction<string>} + */ + _hiragana(args, context, options) { + const ii = args.length; const {keepProlongedSoundMarks} = options.hash; const value = (ii > 0 ? args[0] : options.fn(context)); - return this._japaneseUtil.convertKatakanaToHiragana(value, keepProlongedSoundMarks === true); + return typeof value === 'string' ? this._japaneseUtil.convertKatakanaToHiragana(value, keepProlongedSoundMarks === true) : ''; } - _katakana(context, ...args) { - const ii = args.length - 1; - const options = args[ii]; + /** + * @type {import('template-renderer').HelperFunction<string>} + */ + _katakana(args, context, options) { + const ii = args.length; const value = (ii > 0 ? args[0] : options.fn(context)); - return this._japaneseUtil.convertHiraganaToKatakana(value); + return typeof value === 'string' ? this._japaneseUtil.convertHiraganaToKatakana(value) : ''; + } + + /** + * @param {unknown} value + * @returns {string} + */ + _asString(value) { + return typeof value === 'string' ? value : `${value}`; } } diff --git a/ext/js/templates/sandbox/template-renderer-frame-api.js b/ext/js/templates/sandbox/template-renderer-frame-api.js index 7ce2d909..94ebf7fe 100644 --- a/ext/js/templates/sandbox/template-renderer-frame-api.js +++ b/ext/js/templates/sandbox/template-renderer-frame-api.js @@ -16,16 +16,26 @@ * along with this program. If not, see <https://www.gnu.org/licenses/>. */ +import {ExtensionError} from '../../core/extension-error.js'; + export class TemplateRendererFrameApi { + /** + * @param {import('./template-renderer.js').TemplateRenderer} templateRenderer + */ constructor(templateRenderer) { + /** @type {import('./template-renderer.js').TemplateRenderer} */ this._templateRenderer = templateRenderer; - this._windowMessageHandlers = new Map([ + /** @type {import('core').MessageHandlerMap} */ + this._windowMessageHandlers = new Map(/** @type {import('core').MessageHandlerArray} */ ([ ['render', {async: false, handler: this._onRender.bind(this)}], ['renderMulti', {async: false, handler: this._onRenderMulti.bind(this)}], ['getModifiedData', {async: false, handler: this._onGetModifiedData.bind(this)}] - ]); + ])); } + /** + * @returns {void} + */ prepare() { window.addEventListener('message', this._onWindowMessage.bind(this), false); this._postMessage(window.parent, 'ready', {}, null); @@ -33,14 +43,24 @@ export class TemplateRendererFrameApi { // Private + /** + * @param {MessageEvent<import('template-renderer-frame-api').MessageData>} e + */ _onWindowMessage(e) { const {source, data: {action, params, id}} = e; const messageHandler = this._windowMessageHandlers.get(action); if (typeof messageHandler === 'undefined') { return; } - this._onWindowMessageInner(messageHandler, action, params, source, id); + this._onWindowMessageInner(messageHandler, action, params, /** @type {Window} */ (source), id); } + /** + * @param {import('core').MessageHandlerDetails} handlerItem + * @param {string} action + * @param {import('core').SerializableObject} params + * @param {Window} source + * @param {?string} id + */ async _onWindowMessageInner({handler, async}, action, params, source, id) { let response; try { @@ -50,64 +70,54 @@ export class TemplateRendererFrameApi { } response = {result}; } catch (error) { - response = {error: this._serializeError(error)}; + response = {error: ExtensionError.serialize(error)}; } if (typeof id === 'undefined') { return; } this._postMessage(source, `${action}.response`, response, id); } + /** + * @param {{template: string, data: import('template-renderer').PartialOrCompositeRenderData, type: import('anki-templates').RenderMode}} event + * @returns {import('template-renderer').RenderResult} + */ _onRender({template, data, type}) { return this._templateRenderer.render(template, data, type); } + /** + * @param {{items: import('template-renderer').RenderMultiItem[]}} event + * @returns {import('core').Response<import('template-renderer').RenderResult>[]} + */ _onRenderMulti({items}) { - return this._serializeMulti(this._templateRenderer.renderMulti(items)); + return this._templateRenderer.renderMulti(items); } + /** + * @param {{data: import('template-renderer').CompositeRenderData, type: import('anki-templates').RenderMode}} event + * @returns {import('anki-templates').NoteData} + */ _onGetModifiedData({data, type}) { const result = this._templateRenderer.getModifiedData(data, type); return this._clone(result); } - _serializeError(error) { - try { - if (typeof error === 'object' && error !== null) { - const result = { - name: error.name, - message: error.message, - stack: error.stack - }; - if (Object.prototype.hasOwnProperty.call(error, 'data')) { - result.data = error.data; - } - return result; - } - } catch (e) { - // NOP - } - return { - value: error, - hasValue: true - }; - } - - _serializeMulti(array) { - for (let i = 0, ii = array.length; i < ii; ++i) { - const value = array[i]; - const {error} = value; - if (typeof error !== 'undefined') { - value.error = this._serializeError(error); - } - } - return array; - } - + /** + * @template [T=unknown] + * @param {T} value + * @returns {T} + */ _clone(value) { return JSON.parse(JSON.stringify(value)); } + /** + * @param {Window} target + * @param {string} action + * @param {import('core').SerializableObject} params + * @param {?string} id + */ _postMessage(target, action, params, id) { - return target.postMessage({action, params, id}, '*'); + target.postMessage(/** @type {import('template-renderer-frame-api').MessageData} */ ({action, params, id}), '*'); } } diff --git a/ext/js/templates/sandbox/template-renderer-media-provider.js b/ext/js/templates/sandbox/template-renderer-media-provider.js index 33ddec21..d8a0a16d 100644 --- a/ext/js/templates/sandbox/template-renderer-media-provider.js +++ b/ext/js/templates/sandbox/template-renderer-media-provider.js @@ -20,9 +20,11 @@ import {Handlebars} from '../../../lib/handlebars.js'; export class TemplateRendererMediaProvider { constructor() { + /** @type {?import('anki-note-builder').Requirement[]} */ this._requirements = null; } + /** @type {?import('anki-note-builder').Requirement[]} */ get requirements() { return this._requirements; } @@ -31,12 +33,24 @@ export class TemplateRendererMediaProvider { this._requirements = value; } + /** + * @param {import('anki-templates').NoteData} root + * @param {unknown[]} args + * @param {import('core').SerializableObject} namedArgs + * @returns {boolean} + */ hasMedia(root, args, namedArgs) { const {media} = root; const data = this._getMediaData(media, args, namedArgs); return (data !== null); } + /** + * @param {import('anki-templates').NoteData} root + * @param {unknown[]} args + * @param {import('core').SerializableObject} namedArgs + * @returns {?string} + */ getMedia(root, args, namedArgs) { const {media} = root; const data = this._getMediaData(media, args, namedArgs); @@ -45,16 +59,24 @@ export class TemplateRendererMediaProvider { if (typeof result === 'string') { return result; } } const defaultValue = namedArgs.default; - return typeof defaultValue !== 'undefined' ? defaultValue : ''; + return defaultValue === null || typeof defaultValue === 'string' ? defaultValue : ''; } // Private + /** + * @param {import('anki-note-builder').Requirement} value + */ _addRequirement(value) { if (this._requirements === null) { return; } this._requirements.push(value); } + /** + * @param {import('anki-templates').MediaObject} data + * @param {import('core').SerializableObject} namedArgs + * @returns {string} + */ _getFormattedValue(data, namedArgs) { let {value} = data; const {escape=true} = namedArgs; @@ -64,6 +86,12 @@ export class TemplateRendererMediaProvider { return value; } + /** + * @param {import('anki-templates').Media} media + * @param {unknown[]} args + * @param {import('core').SerializableObject} namedArgs + * @returns {?(import('anki-templates').MediaObject)} + */ _getMediaData(media, args, namedArgs) { const type = args[0]; switch (type) { @@ -78,6 +106,11 @@ export class TemplateRendererMediaProvider { } } + /** + * @param {import('anki-templates').Media} media + * @param {import('anki-templates').MediaSimpleType} type + * @returns {?import('anki-templates').MediaObject} + */ _getSimpleMediaData(media, type) { const result = media[type]; if (typeof result === 'object' && result !== null) { return result; } @@ -85,12 +118,19 @@ export class TemplateRendererMediaProvider { return null; } + /** + * @param {import('anki-templates').Media} media + * @param {unknown} path + * @param {import('core').SerializableObject} namedArgs + * @returns {?import('anki-templates').MediaObject} + */ _getDictionaryMedia(media, path, namedArgs) { + if (typeof path !== 'string') { return null; } const {dictionaryMedia} = media; const {dictionary} = namedArgs; + if (typeof dictionary !== 'string') { return null; } if ( typeof dictionaryMedia !== 'undefined' && - typeof dictionary === 'string' && Object.prototype.hasOwnProperty.call(dictionaryMedia, dictionary) ) { const dictionaryMedia2 = dictionaryMedia[dictionary]; @@ -109,8 +149,15 @@ export class TemplateRendererMediaProvider { return null; } + /** + * @param {import('anki-templates').Media} media + * @param {unknown} text + * @param {import('core').SerializableObject} namedArgs + * @returns {?import('anki-templates').MediaObject} + */ _getTextFurigana(media, text, namedArgs) { - const {readingMode=null} = namedArgs; + if (typeof text !== 'string') { return null; } + const readingMode = this._normalizeReadingMode(namedArgs.readingMode); const {textFurigana} = media; if (Array.isArray(textFurigana)) { for (const entry of textFurigana) { @@ -125,4 +172,18 @@ export class TemplateRendererMediaProvider { }); return null; } + + /** + * @param {unknown} value + * @returns {?import('anki-templates').TextFuriganaReadingMode} + */ + _normalizeReadingMode(value) { + switch (value) { + case 'hiragana': + case 'katakana': + return value; + default: + return null; + } + } } diff --git a/ext/js/templates/sandbox/template-renderer.js b/ext/js/templates/sandbox/template-renderer.js index 8d8a2765..239240b6 100644 --- a/ext/js/templates/sandbox/template-renderer.js +++ b/ext/js/templates/sandbox/template-renderer.js @@ -17,50 +17,78 @@ */ import {Handlebars} from '../../../lib/handlebars.js'; +import {ExtensionError} from '../../core/extension-error.js'; export class TemplateRenderer { constructor() { + /** @type {Map<string, import('handlebars').TemplateDelegate<import('anki-templates').NoteData>>} */ this._cache = new Map(); + /** @type {number} */ this._cacheMaxSize = 5; + /** @type {Map<import('anki-templates').RenderMode, import('template-renderer').DataType>} */ this._dataTypes = new Map(); + /** @type {?((noteData: import('anki-templates').NoteData) => import('template-renderer').SetupCallbackResult)} */ this._renderSetup = null; + /** @type {?((noteData: import('anki-templates').NoteData) => import('template-renderer').CleanupCallbackResult)} */ this._renderCleanup = null; } + /** + * @param {import('template-renderer').HelperFunctionsDescriptor} helpers + */ registerHelpers(helpers) { for (const [name, helper] of helpers) { this._registerHelper(name, helper); } } - registerDataType(name, {modifier=null, composeData=null}) { + /** + * @param {import('anki-templates').RenderMode} name + * @param {import('template-renderer').DataType} details + */ + registerDataType(name, {modifier, composeData}) { this._dataTypes.set(name, {modifier, composeData}); } + /** + * @param {?((noteData: import('anki-templates').NoteData) => import('template-renderer').SetupCallbackResult)} setup + * @param {?((noteData: import('anki-templates').NoteData) => import('template-renderer').CleanupCallbackResult)} cleanup + */ setRenderCallbacks(setup, cleanup) { this._renderSetup = setup; this._renderCleanup = cleanup; } + /** + * @param {string} template + * @param {import('template-renderer').PartialOrCompositeRenderData} data + * @param {import('anki-templates').RenderMode} type + * @returns {import('template-renderer').RenderResult} + */ render(template, data, type) { const instance = this._getTemplateInstance(template); - data = this._getModifiedData(data, void 0, type); - return this._renderTemplate(instance, data); + const modifiedData = this._getModifiedData(data, void 0, type); + return this._renderTemplate(instance, modifiedData); } + /** + * @param {import('template-renderer').RenderMultiItem[]} items + * @returns {import('core').Response<import('template-renderer').RenderResult>[]} + */ renderMulti(items) { + /** @type {import('core').Response<import('template-renderer').RenderResult>[]} */ const results = []; for (const {template, templateItems} of items) { const instance = this._getTemplateInstance(template); for (const {type, commonData, datas} of templateItems) { - for (let data of datas) { + for (const data of datas) { let result; try { - data = this._getModifiedData(data, commonData, type); - result = this._renderTemplate(instance, data); - result = {result}; + const data2 = this._getModifiedData(data, commonData, type); + const renderResult = this._renderTemplate(instance, data2); + result = {result: renderResult}; } catch (error) { - result = {error}; + result = {error: ExtensionError.serialize(error)}; } results.push(result); } @@ -69,29 +97,46 @@ export class TemplateRenderer { return results; } + /** + * @param {import('template-renderer').CompositeRenderData} data + * @param {import('anki-templates').RenderMode} type + * @returns {import('anki-templates').NoteData} + */ getModifiedData(data, type) { return this._getModifiedData(data, void 0, type); } // Private + /** + * @param {string} template + * @returns {import('handlebars').TemplateDelegate<import('anki-templates').NoteData>} + */ _getTemplateInstance(template) { const cache = this._cache; let instance = cache.get(template); if (typeof instance === 'undefined') { this._updateCacheSize(this._cacheMaxSize - 1); - instance = Handlebars.compileAST(template); + instance = /** @type {import('handlebars').TemplateDelegate<import('anki-templates').NoteData>} */ (Handlebars.compileAST(template)); cache.set(template, instance); } return instance; } + /** + * @param {import('handlebars').TemplateDelegate<import('anki-templates').NoteData>} instance + * @param {import('anki-templates').NoteData} data + * @returns {import('template-renderer').RenderResult} + */ _renderTemplate(instance, data) { const renderSetup = this._renderSetup; const renderCleanup = this._renderCleanup; + /** @type {string} */ let result; + /** @type {?import('template-renderer').SetupCallbackResult} */ let additions1; + /** @type {?import('template-renderer').CleanupCallbackResult} */ let additions2; try { additions1 = (typeof renderSetup === 'function' ? renderSetup(data) : null); @@ -99,28 +144,36 @@ export class TemplateRenderer { } finally { additions2 = (typeof renderCleanup === 'function' ? renderCleanup(data) : null); } - return Object.assign({result}, additions1, additions2); + return /** @type {import('template-renderer').RenderResult} */ (Object.assign({result}, additions1, additions2)); } + /** + * @param {import('template-renderer').PartialOrCompositeRenderData} data + * @param {import('anki-note-builder').CommonData|undefined} commonData + * @param {import('anki-templates').RenderMode} type + * @returns {import('anki-templates').NoteData} + * @throws {Error} + */ _getModifiedData(data, commonData, type) { if (typeof type === 'string') { const typeInfo = this._dataTypes.get(type); if (typeof typeInfo !== 'undefined') { if (typeof commonData !== 'undefined') { const {composeData} = typeInfo; - if (typeof composeData === 'function') { - data = composeData(data, commonData); - } + data = composeData(data, commonData); + } else if (typeof data.commonData === 'undefined') { + throw new Error('Incomplete data'); } const {modifier} = typeInfo; - if (typeof modifier === 'function') { - data = modifier(data); - } + return modifier(/** @type {import('template-renderer').CompositeRenderData} */ (data)); } } - return data; + throw new Error(`Invalid type: ${type}`); } + /** + * @param {number} maxSize + */ _updateCacheSize(maxSize) { const cache = this._cache; let removeCount = cache.size - maxSize; @@ -132,9 +185,21 @@ export class TemplateRenderer { } } + /** + * @param {string} name + * @param {import('template-renderer').HelperFunction} helper + */ _registerHelper(name, helper) { + /** + * @this {unknown} + * @param {unknown[]} args + * @returns {unknown} + */ function wrapper(...args) { - return helper(this, ...args); + const argCountM1 = Math.max(0, args.length - 1); + const options = /** @type {import('handlebars').HelperOptions} */ (args[argCountM1]); + args.length = argCountM1; + return helper(args, this, options); } Handlebars.registerHelper(name, wrapper); } |