diff --git a/.babelrc b/.babelrc deleted file mode 100644 index b2c668c74..000000000 --- a/.babelrc +++ /dev/null @@ -1,64 +0,0 @@ -{ - "presets": [ - [ - "env", - { - "modules": false - } - ], - "react", - "stage-0" - ], - "plugins": ["external-helpers"], - "env": { - "webpack": { - "presets": [ - [ - "env", - { - "modules": false - } - ], - "react", - "stage-0" - ], - "plugins": ["transform-runtime", "react-hot-loader/babel"] - }, - "test": { - "presets": [ - [ - "env", - { - "exclude": ["transform-regenerator"] - } - ], - "react", - "stage-0" - ], - "plugins": [ - "transform-runtime", - [ - "module-resolver", - { - "alias": { - "^(slate.*)": "./packages/\\1/src" - } - } - ] - ] - }, - "benchmark": { - "presets": [ - [ - "env", - { - "exclude": ["transform-regenerator"] - } - ], - "react", - "stage-0" - ], - "plugins": ["transform-runtime"] - } - } -} diff --git a/.eslintignore b/.eslintignore index dd449725e..78e9f9743 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1 +1,8 @@ *.md +.github/ +.next/ +build/ +dist/ +lib/ +node_modules/ +tmp/ \ No newline at end of file diff --git a/.eslintrc b/.eslintrc index e322094fe..928636ec6 100644 --- a/.eslintrc +++ b/.eslintrc @@ -1,15 +1,25 @@ { - "extends": ["prettier", "prettier/react"], - "plugins": ["import", "react", "prettier"], - "settings": { - "import/extensions": [".js"] - }, - "parser": "babel-eslint", + "extends": [ + "plugin:import/typescript", + "prettier", + "prettier/@typescript-eslint", + "prettier/react" + ], + "plugins": ["@typescript-eslint", "import", "react", "prettier"], + "parser": "@typescript-eslint/parser", "parserOptions": { + "sourceType": "module", + "ecmaVersion": 2020, "ecmaFeatures": { "jsx": true } }, + "settings": { + "import/extensions": [".js", ".ts"], + "react": { + "version": "detect" + } + }, "env": { "browser": true, "es6": true, @@ -36,16 +46,6 @@ "import/no-named-as-default-member": "error", "import/no-unresolved": "error", "linebreak-style": "error", - "lines-around-comment": [ - "error", - { - "beforeBlockComment": true, - "afterBlockComment": true, - "allowBlockStart": true, - "allowObjectStart": true, - "allowArrayStart": true - } - ], "no-array-constructor": "error", "no-class-assign": "error", "no-console": "error", @@ -63,7 +63,6 @@ "no-extra-boolean-cast": "error", "no-func-assign": "error", "no-invalid-regexp": "error", - "no-lonely-if": "error", "no-native-reassign": "error", "no-negated-in-lhs": "error", "no-new-object": "error", @@ -71,36 +70,14 @@ "no-path-concat": "error", "no-redeclare": "error", "no-regex-spaces": "error", - "no-restricted-globals": [ - "error", - "Debug", - "document", - "Document", - "event", - "history", - "History", - "length", - "Map", - "Node", - "parent", - "Range", - "Selection", - "Set", - "Text" - ], "no-sequences": "error", - "no-shadow": "error", - "no-shadow-restricted-names": "error", "no-tabs": "error", "no-this-before-super": "error", "no-throw-literal": "error", - "no-undef": "error", "no-unneeded-ternary": "error", "no-unreachable": "error", "no-unsafe-finally": "error", "no-unsafe-negation": "error", - "no-unused-expressions": "error", - "no-unused-vars": ["error", { "vars": "all", "args": "none" }], "no-useless-call": "error", "no-useless-computed-key": "error", "no-useless-constructor": "error", @@ -120,7 +97,6 @@ "prettier/prettier": "error", "radix": "error", "react/jsx-boolean-value": ["error", "never"], - "react/jsx-key": "error", "react/jsx-no-duplicate-props": "error", "react/jsx-no-target-blank": "error", "react/jsx-no-undef": "error", @@ -143,26 +119,14 @@ ], "valid-typeof": "error", "yield-star-spacing": ["error", "after"], - "yoda": ["error", "never"], - "padding-line-between-statements": [ - "error", - { "blankLine": "always", "prev": "multiline-expression", "next": "*" }, - { "blankLine": "any", "prev": "multiline-expression", "next": "return" }, - { "blankLine": "always", "prev": "*", "next": "multiline-expression" }, - { "blankLine": "always", "prev": "*", "next": "multiline-expression" }, - { "blankLine": "any", "prev": "empty", "next": "multiline-expression" }, - { "blankLine": "always", "prev": "multiline-block-like", "next": "*" }, - { "blankLine": "any", "prev": "multiline-block-like", "next": "return" }, - { "blankLine": "always", "prev": "*", "next": "multiline-block-like" }, - { "blankLine": "always", "prev": "*", "next": "multiline-block-like" }, - { "blankLine": "any", "prev": "case", "next": "case" } - ] + "yoda": ["error", "never"] }, "overrides": [ { "files": "**/test/**/*.js", "rules": { - "import/no-extraneous-dependencies": false + "import/no-extraneous-dependencies": "off", + "import/no-unresolved": "off" } } ] diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 4427af19b..ce8b6c40d 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,6 +1,6 @@ #### Do you want to request a _feature_ or report a _bug_? - #### Have you checked that...? - -* [ ] The new code matches the existing patterns and styles. -* [ ] The tests pass with `yarn test`. -* [ ] The linter passes with `yarn lint`. (Fix errors with `yarn prettier`.) -* [ ] The relevant examples still work. (Run examples with `yarn watch`.) +- [ ] The new code matches the existing patterns and styles. +- [ ] The tests pass with `yarn test`. +- [ ] The linter passes with `yarn lint`. (Fix errors with `yarn fix`.) +- [ ] The relevant examples still work. (Run examples with `yarn watch`.) #### Does this fix any issues or need any specific reviewers? diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d96595cc8..983d9b845 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,10 +4,10 @@ jobs: ci: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - uses: actions/setup-node@v1 - with: - node-version: 12 - - run: yarn && yarn build && yarn lint && yarn test - env: - CI: true + - uses: actions/checkout@v1 + - uses: actions/setup-node@v1 + with: + node-version: 12 + - run: yarn && yarn build:rollup && yarn test && yarn lint + env: + CI: true diff --git a/.gitignore b/.gitignore index 94b19ed8a..e2ba75075 100644 --- a/.gitignore +++ b/.gitignore @@ -1,26 +1,10 @@ -# Build files. -*.js.map +*.log +.next/ +.vscode/ build/ dist/ lib/ - -# Temporary files. -tmp/ - -# Gitbook files. -_book/ - -# Package files. -lerna-debug.log node_modules/ -npm-debug.log -yarn-error.log packages/*/yarn.lock - -# OS files. -.DS_Store -.idea/ -.vscode/ - -# Editor files -.tern-port +site/out/ +tmp/ \ No newline at end of file diff --git a/.prettierignore b/.prettierignore index a24a71a6a..e768e3356 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,6 +1,8 @@ +.babelrc +.next/ build/ +dist/ +lib/ node_modules/ package.json -packages/*/dist/ -packages/*/lib/ -tmp/ +tmp/ \ No newline at end of file diff --git a/Changelog.md b/Changelog.md index a39f71959..89887f215 100644 --- a/Changelog.md +++ b/Changelog.md @@ -2,10 +2,8 @@ Since Slate is a monorepo with many packages that are versioned separately, we maintain a changelog for each individual package: -* [`slate`](./packages/slate/Changelog.md) -* [`slate-base64-serializer`](./packages/slate-base64-serializer/Changelog.md) -* [`slate-html-serializer`](./packages/slate-html-serializer/Changelog.md) -* [`slate-hyperscript`](./packages/slate-hyperscript/Changelog.md) -* [`slate-plain-serializer`](./packages/slate-plain-serializer/Changelog.md) -* [`slate-prop-types`](./packages/slate-prop-types/Changelog.md) -* [`slate-react`](./packages/slate-react/Changelog.md) +- [`slate`](./packages/slate/Changelog.md) +- [`slate-history`](./packages/slate-history/Changelog.md) +- [`slate-hyperscript`](./packages/slate-hyperscript/Changelog.md) +- [`slate-react`](./packages/slate-react/Changelog.md) +- [`slate-schema`](./packages/slate-schema/Changelog.md) diff --git a/Contributing.md b/Contributing.md index 6ca47e5dc..113232896 100644 --- a/Contributing.md +++ b/Contributing.md @@ -2,16 +2,13 @@ Want to contribute to Slate? That would be awesome! -* [Reporting Bugs](#reporting-bugs) -* [Asking Questions](#asking-questions) -* [Submitting Pull Requests](#submitting-pull-requests) -* [Running Examples](#running-examples) -* [Running Tests](#running-tests) -* [Running Benchmarks](#running-benchmarks) -* [Adding Browser Support](#adding-browser-support) -* [Testing Input Methods](#testing-input-methods) -* [Debugging Slate Methods](#debugging-slate-methods) -* [Publishing Releases](#publishing-releases) +- [Reporting Bugs](#reporting-bugs) +- [Asking Questions](#asking-questions) +- [Submitting Pull Requests](#submitting-pull-requests) +- [Running Examples](#running-examples) +- [Running Tests](#running-tests) +- [Testing Input Methods](#testing-input-methods) +- [Publishing Releases](#publishing-releases) ## Reporting Bugs @@ -19,9 +16,9 @@ If you run into any weird behavior while using Slate, feel free to open a new is Any issue you open must include: -* A [JSFiddle](https://jsfiddle.net/fj9dvhom/1/) that reproduces the bug with a minimal setup. -* A GIF showing the issue in action. (Using something like [RecordIt](http://recordit.co/).) -* A clear explanation of what the issue is. +- A [JSFiddle](https://jsfiddle.net/fj9dvhom/1/) that reproduces the bug with a minimal setup. +- A GIF showing the issue in action. (Using something like [RecordIt](http://recordit.co/).) +- A clear explanation of what the issue is. Here's a [JSFiddle template for Slate](https://jsfiddle.net/fj9dvhom/1/) to get you started: @@ -70,54 +67,16 @@ If you need to debug something, you can add a `debugger` line to the source, and If you only want to run a specific test or tests, you can run `yarn test --fgrep="slate-react rendering"` flag which will filter the tests being run by grepping for the string in each test. -## Running Benchmarks - -To run the benchmarks, first make some changes to the source that you want to benchmark. Now that you're ready, you need to save a "baseline" for what the performance was before you made you change. - -To do that, stash your changes and save the benchmarks: - -``` -git stash -yarn benchmark:save -``` - -Then once the reference has been saved, unstash your changes and run the benchmarks to see a comparison: - -``` -git stash pop -yarn benchmark -``` - -There will be some subtle changes in iteration speed always, but the comparison reporter will highlight any changes that seem meaningful. You can run `benchmark` multiple times to ensure the speed up persists. - -### Run Selected Benchmarks - -To run selected benchmarks, create `tmp/benchmark-config.js` with `module.exports.include`. For example, to run slate-core benchmarks only with `get-*`, we can create a `tmp/benchmark-config.js` as - -``` -module.exports.include = { - slate: /^get/ -} -``` - -## Adding Browser Support - -Slate aims to targeted all of the modern browsers, and eventually the modern mobile platforms. Right now browser support is limited to the latest versions of [Chrome](https://www.google.com/chrome/browser/desktop/), [Firefox](https://www.mozilla.org/en-US/firefox/new/), and [Safari](http://www.apple.com/safari/), but if you are interested in adding support for another modern platform, that is welcomed! - ## Testing Input Methods [Here's a helpful page](https://github.com/Microsoft/vscode/wiki/IME-Test) detailing how to test various input scenarios on Windows, Mac and Linux. -## Debugging Slate Methods - -Slate makes use of [debug](https://github.com/visionmedia/debug) to log information about various methods. You can [enable the logger in the browser](https://github.com/visionmedia/debug#browser-support) by setting `localStorage.debug = "*"` (to log methods on all modules) or to a single namespace (e.g. `slate:editor`). Look for `const debug = Debug('')` to get the namespace of various modules. - ## Publishing Releases -Since we use [Lerna](https://lernajs.io) to manage the Slate packages this is fairly easy, **but** you must make sure you are using `npm` to run the release script, because using `yarn` results in failures. So just run: +Since we use [Lerna](https://lernajs.io) to manage the Slate packages this is fairly easy, just run: ```js -npm run release +yarn release ``` And follow the prompts Lerna gives you. diff --git a/Readme.md b/Readme.md index 3970492f5..da720a8b9 100644 --- a/Readme.md +++ b/Readme.md @@ -13,7 +13,6 @@ Principles · Demo · Examples · - Plugins · Documentation · Contributing!

@@ -38,7 +37,7 @@ Slate lets you build rich, intuitive editors like those in [Medium](https://medium.com/), [Dropbox Paper](https://www.dropbox.com/paper) or [Google Docs](https://www.google.com/docs/about/)—which are becoming table stakes for applications on the web—without your codebase getting mired in complexity. -It can do this because all of its logic is implemented with a series of plugins, so you aren't ever constrained by what _is_ or _isn't_ in "core". You can think of it like a pluggable implementation of `contenteditable` built on top of [React](https://facebook.github.io/react/) and [Immutable](https://immutable-js.github.io/immutable-js/). It was inspired by libraries like [Draft.js](https://facebook.github.io/draft-js/), [Prosemirror](http://prosemirror.net/) and [Quill](http://quilljs.com/). +It can do this because all of its logic is implemented with a series of plugins, so you aren't ever constrained by what _is_ or _isn't_ in "core". You can think of it like a pluggable implementation of `contenteditable` built on top of [React](https://facebook.github.io/react/). It was inspired by libraries like [Draft.js](https://facebook.github.io/draft-js/), [Prosemirror](http://prosemirror.net/) and [Quill](http://quilljs.com/). > 🤖 **Slate is currently in beta**. Its core API is useable now, but you might need to pull request a fix or two for advanced use cases. Some of its APIs are not "finalized" and will (breaking) change over time as we discover better solutions. @@ -50,19 +49,19 @@ Why create Slate? Well... _(Beware: this section has a few of [my](https://githu Before creating Slate, I tried a lot of the other rich text libraries out there—[**Draft.js**](https://facebook.github.io/draft-js/), [**Prosemirror**](http://prosemirror.net/), [**Quill**](http://quilljs.com/), etc. What I found was that while getting simple examples to work was easy enough, once you started trying to build something like [Medium](https://medium.com/), [Dropbox Paper](https://www.dropbox.com/paper) or [Google Docs](https://www.google.com/docs/about/), you ran into deeper issues... -* **The editor's "schema" was hardcoded and hard to customize.** Things like bold and italic were supported out of the box, but what about comments, or embeds, or even more domain-specific needs? +- **The editor's "schema" was hardcoded and hard to customize.** Things like bold and italic were supported out of the box, but what about comments, or embeds, or even more domain-specific needs? -* **Transforming the documents programmatically was very convoluted.** Writing as a user may have worked, but making programmatic changes, which is critical for building advanced behaviors, was needlessly complex. +- **Transforming the documents programmatically was very convoluted.** Writing as a user may have worked, but making programmatic changes, which is critical for building advanced behaviors, was needlessly complex. -* **Serializing to HTML, Markdown, etc. seemed like an afterthought.** Simple things like transforming a document to HTML or Markdown involved writing lots of boilerplate code, for what seemed like very common use cases. +- **Serializing to HTML, Markdown, etc. seemed like an afterthought.** Simple things like transforming a document to HTML or Markdown involved writing lots of boilerplate code, for what seemed like very common use cases. -* **Re-inventing the view layer seemed inefficient and limiting.** Most editors rolled their own views, instead of using existing technologies like React, so you have to learn a whole new system with new "gotchas". +- **Re-inventing the view layer seemed inefficient and limiting.** Most editors rolled their own views, instead of using existing technologies like React, so you have to learn a whole new system with new "gotchas". -* **Collaborative editing wasn't designed for in advance.** Often the editor's internal representation of data made it impossible to use to for a realtime, collaborative editing use case without basically rewriting the editor. +- **Collaborative editing wasn't designed for in advance.** Often the editor's internal representation of data made it impossible to use to for a realtime, collaborative editing use case without basically rewriting the editor. -* **The repositories were monolithic, not small and reusable.** The code bases for many of the editors often didn't expose the internal tooling that could have been re-used by developers, leading to having to reinvent the wheel. +- **The repositories were monolithic, not small and reusable.** The code bases for many of the editors often didn't expose the internal tooling that could have been re-used by developers, leading to having to reinvent the wheel. -* **Building complex, nested documents was impossible.** Many editors were designed around simplistic "flat" documents, making things like tables, embeds and captions difficult to reason about and sometimes impossible. +- **Building complex, nested documents was impossible.** Many editors were designed around simplistic "flat" documents, making things like tables, embeds and captions difficult to reason about and sometimes impossible. Of course not every editor exhibits all of these issues, but if you've tried using another editor you might have run into similar problems. To get around the limitations of their API's and achieve the user experience you're after, you have to resort to very hacky things. And some experiences are just plain impossible to achieve. @@ -76,21 +75,19 @@ Which brings me to how Slate solves all of that... Slate tries to solve the question of "[Why?](#why)" with a few principles: -1. **First-class plugins.** The most important part of Slate is that plugins are first-class entities—the core editor logic is even implemented as its own plugin. That means you can _completely_ customize the editing experience, to build complex editors like Medium's or Dropbox's, without having to fight against the library's assumptions. +1. **First-class plugins.** The most important part of Slate is that plugins are first-class entities. That means you can _completely_ customize the editing experience, to build complex editors like Medium's or Dropbox's, without having to fight against the library's assumptions. -2. **Schema-less core.** Slate's core logic doesn't assume anything about the schema of the data you'll be editing, which means that there are no assumptions baked into the library that'll trip you up when you need to go beyond the most basic use cases. +2. **Schema-less core.** Slate's core logic assumes very little about the schema of the data you'll be editing, which means that there are no assumptions baked into the library that'll trip you up when you need to go beyond the most basic use cases. 3. **Nested document model.** The document model used for Slate is a nested, recursive tree, just like the DOM itself. This means that creating complex components like tables or nested block quotes are possible for advanced use cases. But it's also easy to keep it simple by only using a single level of hierarchy. 4. **Parallel to the DOM.** Slate's data model is based on the DOM—the document is a nested tree, it uses selections and ranges, and it exposes all the standard event handlers. This means that advanced behaviors like tables or nested block quotes are possible. Pretty much anything you can do in the DOM, you can do in Slate. -5. **Stateless views and immutable data.** By using React and Immutable.js, the Slate editor is built in a stateless fashion using immutable data structures, which leads to much easier to reason about code, and a much easier time writing plugins. +5. **Intuitive commands.** Slate documents are edited using "commands", that are designed to be high-level and extremely intuitive to write and read, so that custom functionality is as expressive as possible. This greatly increases your ability to reason about your code. -6. **Intuitive changes.** Slate documents are edited using "changes", that are designed to be high-level and extremely intuitive to write and read, so that custom functionality is as expressive as possible. This greatly increases your ability to reason about your code. +6. **Collaboration-ready data model.** The data model Slate uses—specifically how operations are applied to the document—has been designed to allow for collaborative editing to be layered on top, so you won't need to rethink everything if you decide to make your editor collaborative. -7. **Collaboration-ready data model.** The data model Slate uses—specifically how changes are applied to the document—has been designed to allow for collaborative editing to be layered on top, so you won't need to rethink everything if you decide to make your editor collaborative. - -8. **Clear "core" boundaries.** With a plugin-first architecture, and a schema-less core, it becomes a lot clearer where the boundary is between "core" and "custom", which means that the core experience doesn't get bogged down in edge cases. +7. **Clear "core" boundaries.** With a plugin-first architecture, and a schema-less core, it becomes a lot clearer where the boundary is between "core" and "custom", which means that the core experience doesn't get bogged down in edge cases.
@@ -102,55 +99,39 @@ Check out the [**live demo**](http://slatejs.org) of all of the examples! ### Examples +## Examples + To get a sense for how you might use Slate, check out a few of the examples: -* [**Plain text**](./examples/plain-text) — showing the most basic case: a glorified `