Refactor to TypeScript, Documentation, NPM and More

[laobubu]

• 🏠 HyperMD Core
• ⚡️ HyperMD mode
• 🔌 Addons
  • InsertFile
  • Click
  • CursorDebounce
  • FoldMath
  • Fold
  • HideToken
  • Hover
  • ModeLoader
  • Paste
  • ReadLink
  • TableAlign
• ⚙️ Bundler config (with rollup.js)
• 📑 Interfaces Declaration
• 🙃 Deal with the poorly-typed @types/codemirror
• 📘 Documentation
  • CONTRIBUTING.md
  • Doc generator with TypeScript
• 📦 Pack-up script
• 🚢 First Release! Publish to npm

[laobubu]

Code goes to refactoring-with-ts branch

Rollup is good but there is still something wrong in my configuration...

Emmm... what the hell is '../../hypermd/addon/' ?!

HyperMD/dist/addon/insert-file.js

Lines 2 to 4 in f108ab1

	typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('codemirror'), require('hypermd'), require('../../hypermd/addon/readlink')) :
	typeof define === 'function' && define.amd ? define(['exports', 'codemirror', 'hypermd', '../../hypermd/addon/readlink'], factory) :
	(factory((global.HyperMD = global.HyperMD || {}, global.HyperMD.InsertFile = {}),global.CodeMirror,global.HyperMD));

@nokola

[laobubu]

Ready to TypeScript now. hover, mode-loader, read-link and insert-file are refractored. There are still lots of work to do.

[nokola]

re: '../../hypermd/addon/' -> looks like you fixed it, probably some issue with import or base folder.

"Deal with the poorly-typed @types/codemirror": I noticed for some function calls I had to replace them to use Doc instead of Editor. e.g. cm.getCursor() change to cm.getDoc().getCursor(). I think this is intentional because CodeMirror.Doc is the better location to deal with cursor/etc. The old functions are left working only for legacy purposes.

[laobubu]

A workaround is that let CodrMirror.Editor extends CodeMirror.Doc , which is now written in "src/core/type.d.ts". I'm not sure whether multi-doc feature is important. If it is, lots of add-ons will need to rewrite. So let's just put this aside for a while

[nokola]

Sounds good. I wonder about multi-doc feature too. Perhaps slowly over time can switch to using getDoc().
Personally I always use the getDoc() since I started with typescript anyway.

[nokola]

Just found something very interesting! See parcel js - a module bundler with what they say very good typescript support https://parceljs.org/transforms.html

I haven't read much about it yet.

Edit: after more reading, found out "microbundle" as another alternative.

Many places note that "rollup" that you use is a good choice for npm libs.

Anyway please ignore this comment since rollup looks like working well already for you :)

[laobubu]

(part of) BREAKING CHANGES

Powerful Fold System!

Fold addon is now much more efficient and extensible.

A developer may implement a FolderFunc to fold anything. A example can be found in FoldMath, only 60 lines(with comments).

The new Fold add-on makes it very easy to support Markdown Diagrams and render them with 3rd libraries like flowchart.js, PlantUML etc.

HyperMD/src/addon/fold.ts

Lines 17 to 29 in 25b4431

	/**
	* 1. Check if `token` is a **BEGINNING TOKEN** of fold-able text (eg. "!" for images)
	* 2. Use `stream.findNext` to find the end of the text to be folded (eg. ")" or "]" of link/URL, for images)
	* 3. Compose a range `{from, to}`
	* - `from` is always `{ line: stream.lineNo, ch: token.start }`
	* 4. Check if `stream.requestRange(from, to)` returns `RequestRangeResult.OK`
	* - if not ok, return `null` immediately.
	* 5. Use `stream.cm.markText(from, to, options)` to fold text, and return the marker
	*
	* @param token current checking token. a shortcut to `stream.lineTokens[stream.i_token]`
	* @returns a TextMarker if folded.
	*/
	export type FolderFunc = (stream: FoldStream, token: CodeMirror.Token) => CodeMirror.TextMarker;

Click Handers

hmdClick option can be a ClickHandler function, which may supress HyperMD default behaviors by returning false:

HyperMD/src/addon/click.ts

Lines 17 to 38 in 25b4431

	export type TargetType = "image" | "link" | "footref" | "url" | "todo"
	export interface ClickInfo {
	type: TargetType
	text: string
	url: string // for todo item, url is empty
	pos: CodeMirror.Position
	button: number
	clientX: number
	clientY: number
	ctrlKey: boolean
	altKey: boolean
	shiftKey: boolean
	}
	/**
	* User may define his click handler, which has higher priority than HyperMD's.
	*
	* Custom handler may return `false` to prevent HyperMD's default behavior.
	*/
	export type ClickHandler = (info: ClickInfo, cm: cm_t) => (false | void)

Addon Skeleton

Boilerplate to start a new add-on quickly. See skeleton.ts

Once a new add-on is ready-to-test:

1. Add to components in rollup.config.js
2. Edit demo/index.js and load it
3. Edit src/core/quick.ts and provide a suggested option value
4. yarn dev

---

@nasyxx interested in composing CONTRIBUTING.md? I do feel frustrated with my poor English now.

[cgestes]

Happy to unroll my custom changes to make it work in webpack and try this changeset :)

Will keep you posted.

[cgestes]

using your branch at commit 955fffe

$ yarn build                                                                                                                                                                           19:25
yarn run v1.6.0
$ npm run build_js && npm run build_css

> hypermd@0.3.0 build_js /home/cedric/src/HyperMD
> rollup -c


./src/core.ts → ./core.js...
[!] (rpt2 plugin) Error: /home/cedric/src/HyperMD/src/core.ts(5,24): semantic error TS2307 Cannot find module './core/Addon'.
src/core.ts
Error: /home/cedric/src/HyperMD/src/core.ts(5,24): semantic error TS2307 Cannot find module './core/Addon'.
    at error (/home/cedric/src/HyperMD/node_modules/rollup/dist/rollup.js:199:15)
    at Object.error (/home/cedric/src/HyperMD/node_modules/rollup/dist/rollup.js:17311:21)
    at RollupContext.error (/home/cedric/src/HyperMD/node_modules/rollup-plugin-typescript2/dist/rollup-plugin-typescript2.cjs.js:17215:30)
    at /home/cedric/src/HyperMD/node_modules/rollup-plugin-typescript2/dist/rollup-plugin-typescript2.cjs.js:19860:23
    at arrayEach (/home/cedric/src/HyperMD/node_modules/rollup-plugin-typescript2/dist/rollup-plugin-typescript2.cjs.js:546:11)
    at forEach (/home/cedric/src/HyperMD/node_modules/rollup-plugin-typescript2/dist/rollup-plugin-typescript2.cjs.js:9372:14)
    at printDiagnostics (/home/cedric/src/HyperMD/node_modules/rollup-plugin-typescript2/dist/rollup-plugin-typescript2.cjs.js:19833:5)
    at Object.transform (/home/cedric/src/HyperMD/node_modules/rollup-plugin-typescript2/dist/rollup-plugin-typescript2.cjs.js:20104:17)
    at /home/cedric/src/HyperMD/node_modules/rollup/dist/rollup.js:17316:48
    at process._tickCallback (internal/process/next_tick.js:68:7)

beside this issue that I fixed with a rename, I still have troubles getting it to work. I will investigate later, I run out of time today.

[laobubu]

@cgestes
I use Windows and filenames are case-insensitive. Thanks for reporting this bug.
The package on NPM is now tested (with parcel-bundler) and works well. See http://laobubu.net/HyperMD/#./docs/index.md

[cgestes]

Ok thank you. I'll see it seems there is some migration required. I'll keep you posted

Thanks for the great addons.

[nokola]

Will you merge the typescript branch before the documentation? I think the documentation can be a separate task - for me typescript support is an awesome thing of it's own :)

[laobubu]

@nokola TypeScript branch is already merged to master.

Note that there are still some unfinished / untested codes in master branch. You may find a stabler version in "Releases". If something abnormal occurred, feel free to post here.