From 9df679c2c7ca5186445cfd383a32249d1a5c8064 Mon Sep 17 00:00:00 2001 From: Nicolas CARPi Date: Tue, 12 Mar 2024 16:39:22 +0100 Subject: [PATCH] add typedoc for api doc --- .github/workflows/push_demo.yml | 2 + .gitignore | 2 + package-lock.json | 100 ++++++++++++++++++++++++++++++++ package.json | 6 +- src/main.ts | 49 ++++++++++++++-- 5 files changed, 154 insertions(+), 5 deletions(-) diff --git a/.github/workflows/push_demo.yml b/.github/workflows/push_demo.yml index 8d580f2..9cf0ee5 100644 --- a/.github/workflows/push_demo.yml +++ b/.github/workflows/push_demo.yml @@ -38,6 +38,8 @@ jobs: run: npm ci - name: Build dist files run: npm run build + - name: Build api doc + run: npm run build-docs-demo - name: Fix lib load path run: sed -i -e 's:./dist::' demo/demo.js - name: Copy lib diff --git a/.gitignore b/.gitignore index e571afb..a41c8de 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ dist/* node_modules/ demo/malle.js +docs/ +demo/api/ diff --git a/package-lock.json b/package-lock.json index 585ecec..c3fae91 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,6 +19,7 @@ "eslint-plugin-promise": "^6.0.0", "jest": "^27.5.1", "ts-jest": "^27.1.3", + "typedoc": "^0.25.8", "typescript": "^4.0.2" } }, @@ -1679,6 +1680,12 @@ "node": ">=8" } }, + "node_modules/ansi-sequence-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz", + "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==", + "dev": true + }, "node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -4767,6 +4774,12 @@ "node": ">=6" } }, + "node_modules/jsonc-parser": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.1.tgz", + "integrity": "sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==", + "dev": true + }, "node_modules/keyv": { "version": "4.5.4", "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz", @@ -4855,6 +4868,12 @@ "yallist": "^3.0.2" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/make-dir": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz", @@ -4885,6 +4904,18 @@ "tmpl": "1.0.5" } }, + "node_modules/marked": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz", + "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==", + "dev": true, + "bin": { + "marked": "bin/marked.js" + }, + "engines": { + "node": ">= 12" + } + }, "node_modules/merge-stream": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", @@ -5728,6 +5759,18 @@ "node": ">=8" } }, + "node_modules/shiki": { + "version": "0.14.7", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.7.tgz", + "integrity": "sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==", + "dev": true, + "dependencies": { + "ansi-sequence-parser": "^1.1.0", + "jsonc-parser": "^3.2.0", + "vscode-oniguruma": "^1.7.0", + "vscode-textmate": "^8.0.0" + } + }, "node_modules/side-channel": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz", @@ -6266,6 +6309,51 @@ "is-typedarray": "^1.0.0" } }, + "node_modules/typedoc": { + "version": "0.25.8", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.8.tgz", + "integrity": "sha512-mh8oLW66nwmeB9uTa0Bdcjfis+48bAjSH3uqdzSuSawfduROQLlXw//WSNZLYDdhmMVB7YcYZicq6e8T0d271A==", + "dev": true, + "dependencies": { + "lunr": "^2.3.9", + "marked": "^4.3.0", + "minimatch": "^9.0.3", + "shiki": "^0.14.7" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 16" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x" + } + }, + "node_modules/typedoc/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/typedoc/node_modules/minimatch": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", + "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "dev": true, + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/typescript": { "version": "4.9.5", "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz", @@ -6381,6 +6469,18 @@ "node": ">= 8" } }, + "node_modules/vscode-oniguruma": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz", + "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==", + "dev": true + }, + "node_modules/vscode-textmate": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz", + "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==", + "dev": true + }, "node_modules/w3c-hr-time": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/w3c-hr-time/-/w3c-hr-time-1.0.2.tgz", diff --git a/package.json b/package.json index 3c017d3..b432854 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,7 @@ "version": "2.5.2", "description": "Make text elements malleable, without dependencies.", "main": "dist/main.js", - "typings": "dist/main.d.ts", + "typings": "dist/main.d.ts", "repository": "https://github.com/deltablot/malle", "author": "Nicolas CARPi @ Deltablot>", "license": "MIT", @@ -15,6 +15,9 @@ ], "scripts": { "build": "tsc && cp -v dist/main.js demo/malle.js", + "watch-docs": "typedoc --commentStyle All --watch src/main.ts", + "build-docs": "typedoc --commentStyle All src/main.ts", + "build-docs-demo": "typedoc --commentStyle All --out demo/api src/main.ts", "lint": "eslint src", "dev-server": "docker run --rm -it --name malle-dev -p 4813:80 -v $(pwd):/usr/share/nginx/html:ro -d nginx:stable-alpine", "pre-commit": "npm run lint && npm run test", @@ -33,6 +36,7 @@ "eslint-plugin-promise": "^6.0.0", "jest": "^27.5.1", "ts-jest": "^27.1.3", + "typedoc": "^0.25.8", "typescript": "^4.0.2" } } diff --git a/src/main.ts b/src/main.ts index 642db74..71330ed 100644 --- a/src/main.ts +++ b/src/main.ts @@ -5,6 +5,7 @@ * https://github.com/deltablot/malle */ +// The `InputType` will set the `type` attribute of the generated input element. export enum InputType { Color = 'color', Date = 'date', @@ -18,51 +19,94 @@ export enum InputType { Url = 'url', } +// List of possible trigger events export enum EventType { + // A mouse click triggers the event (default) Click = 'click', + // Trigger malle when the mouse starts hovering the element Mouseenter = 'mouseenter', + // Trigger malle when the mouse stops hovering the element Mouseover = 'mouseover', } +// List of possible action that can be defined at different moments export enum Action { + // Submit the form Submit = 'submit', + // Cancel change and revert to initial element Cancel = 'cancel', + // Do nothing Ignore = 'ignore', } +// Structure for the select element options export interface SelectOptions { + // Value of the option. value?: string; + // Displayed text of the option. text?: string; + // Is this option selected? selected?: boolean; } +// Configuration object for the Malle class. export interface Options { + // Function to execute after all the other events. after?(original: HTMLElement, event:Event, value: string): boolean; + /** + * This function will be called before anything else is done, once the trigger event has been fired. + * If it returns something else than `true`, the edition will be canceled. + */ before?(original: HTMLElement, event:Event): boolean; + // The text displayed on Cancel button. cancel?: string; + // The classes added to Cancel button. cancelClasses?: Array; + // The classes added to the form element. formClasses?: Array; + // The classes added to the input element. inputClasses?: Array, + // Enabling debug mode will produce verbose output in the console. debug?: boolean; + // This is where you define the type of event that will trigger malle. event?: EventType; + // Should the newly created input grab focus? inputType?: InputType; + // This is the user function that is called on submit. focus?: boolean; + // Define the type of the input element. fun(value: string, original: HTMLElement, event:Event, input: HTMLInputElement|HTMLSelectElement): Promise; + // Start listening immediatly or not. listenNow?: boolean; + // HTML selector to target malleable elements on the page. listenOn?: string; + // What Action should be taken when focus of the input is lost. onBlur?: Action; + // This function runs right after the form is created. onEdit?(original: HTMLElement, event:Event, input: HTMLInputElement|HTMLSelectElement): boolean | Promise; + // What Action should be taken when the Enter key is pressed? onEnter?: Action; + // What Action should be taken when the Escape key is pressed? onEscape?: Action; + // A text that is shown on empty input. placeholder?: string; + // Do nothing if new value is the same as the old value. requireDiff?: boolean; + // Use innerHTML instead of innerText (only use if the return value is trusted HTML). returnedValueIsTrustedHtml?: boolean; + // An array of options for InputType.Select. Can also be a Promise and fetched asynchronously. selectOptions?: Array | Promise>; + // What is the name of the key to use to lookup the values in the selectOptions array? selectOptionsValueKey?: string; + // What is the name of the key to use to lookup the option text in the selectOptions array? selectOptionsTextKey?: string; + // The text on the Submit button. submit?: string; + // The classes added to the submit button. submitClasses?: Array; + // The text added on hover of the malleable element. Uses the `title` attribute. tooltip?: string; + // Allow setting a different value than the current element content. inputValue?: string; } @@ -84,9 +128,7 @@ export class Malle { this.innerFun = this.opt.returnedValueIsTrustedHtml ? 'innerHTML' : 'innerText'; } - /** - * Assign defaults to options - */ + // Assign defaults to options normalizeOptions(options: Options): Options { const defaultOptions = { after: undefined, @@ -100,7 +142,6 @@ export class Malle { focus: true, fun: () => new Error('No user function defined!'), inputType: InputType.Text, - // don't listen for events on instanciation unless requested listenNow: false, listenOn: '[data-malleable="true"]', onBlur: Action.Submit,