Initial import of documentation

doc/attributes.md

@@ -0,0 +1,126 @@
+## Style Attributes
+
+Style attributes in Zefyr documents are simple key-value pairs, where
+keys identify the attribute and value describes the style applied, for
+instance, `{ "heading": 1 }` defines heading style for a line of
+text with value `1` (equivalent of `h1` in HTML).
+
+It is important to note
+that one attribute can describe multiple different styles depending
+on the current value. E.g. attribute with key "heading" can be set to values
+`1`, `2` or `3`, equivalents of `h1`, `h2` and `h3` in HTML. This prevents
+a line of text from being formatted as `h1` and `h2` heading at the same time,
+which is intentional.
+
+Additionally, each attribute gets assigned one of two scopes. An
+attribute can be either *inline-scoped* or *line-scoped*, but not both.
+A good example of an inline-scoped attribute is "bold" attribute. Bold
+style can be applied to any character within a line, but not the the
+line itself. Similarly "heading" style is line-scoped and has effect
+only on the line as a whole.
+
+Below table summarizes information about all currently supported
+attributes in Zefyr:
+
+| Name    | Key       | Scope    | Type     | Valid values                           |
+|---------|-----------|----------|----------|----------------------------------------|
+| Bold    | `b`       | `inline` | `bool`   | `true`                                 |
+| Italic  | `i`       | `inline` | `bool`   | `true`                                 |
+| Link    | `a`       | `inline` | `String` | Non-empty string                       |
+| Heading | `heading` | `line`   | `int`    | `1`, `2` and `3`                       |
+| Block   | `block`   | `line`   | `String` | `"ul"`, `"ol"`, `"code"` and `"quote"` |
+
+Removing a specific style is as simple as setting corresponding
+attribute to `null`.
+
+Here is an example of applying some styles to a document:
+
+```dart
+import 'package:zefyr/zefyr.dart';
+
+void makeItPretty(ZefyrDocument document) {
+  /// All attributes can be accessed through [ZefyrAttribute] class.
+
+  // Format 5 characters starting at index 0 as bold.
+  document.format(0, 5, ZefyrAttribute.bold);
+
+  // Similarly for italic.
+  document.format(0, 5, ZefyrAttribute.italic);
+
+  // Format the first line as a heading (level 1).
+  // Note that there is no need to specify character range of the whole
+  // line. Simply set index position to anywhere within the line and
+  // length to 0.
+  document.format(0, 0, ZefyrAttribute.heading.level1);
+
+  // Add a link:
+  document.format(10, 15, ZefyrAttribute.link.fromString('https://github.com'));
+
+  // Format a line as code block. Similarly to heading styles there is no need
+  // to specify the whole character range of the line. In following example:
+  // whichever line is at character index 23 in the document will get
+  // formatted as code block.
+  document.format(23, 0, ZefyrAttribute.block.code);
+
+  // Remove heading style from the first line. All attributes
+  // have `unset` property which can be used the same way.
+  document.format(0, 0, ZefyrAttribute.heading.unset);
+}
+```
+
+### How attributes are stored in Deltas
+
+As mentioned previously a document delta consists of a sequence of `insert`
+operations. Attributes (if any) are stored as metadata on each of the
+operations.
+
+One important detail here is how line and inline-scoped attributes are
+handled. Since Deltas are essentially a flat data structure there is
+nothing in the format itself to represent a line of text, which is
+required to allow storing line-scoped style attributes.
+
+To solve this issue Zefyr (similarly to Quill.js) reserves the
+**newline** character (aka `\n` and `0x0A`) as storage for line-scoped
+styles.
+
+Zefyr's document model is designed to enforce this rule and
+prevents malformed changes from being composed into a document. For
+instance, an attempt to apply "bold" style to a newline character
+will have no effect.
+
+Below is an example of Zefyr document's Delta with two lines of text.
+The first line is formatted as an `h1` heading and on the second line
+there is bold-styled word "Flutter":
+
+```dart
+var delta = new Delta();
+delta
+  ..insert('Zefyr Editor')
+  ..insert('\n', attributes: {'heading': 1})
+  ..insert('A rich text editor for ');
+  ..insert('Flutter', attributes: {'b': true});
+  ..insert('\n');
+```
+
+Note that there is no block-level scope for style attributes. Again,
+given flat structure of Deltas there is nothing that can represent a
+block of lines which share the same style, e.g. bullet list. And we
+already reserved newline character for line styles.
+
+As it turns out, this is not a big issue and it is possible to achieve
+a friendly user experience without this extra level in a document model.
+
+The `block` attribute in Zefyr is line-scoped. To change a group of
+lines from "bullet list" to "number list" we need to update block
+style on each of the lines individually. Zefyr editor abstracts away
+such details with help of [heuristic rules][heuristics].
+
+### Next up
+
+* [Heuristics][heuristics]
+
+[heuristics]: /doc/heuristics.md
+
+### Previous
+
+* [Data Format and Document Model](/doc/data_and_document.md)

doc/data_and_document.md

@@ -0,0 +1,134 @@
+## Data Format and Document Model
+
+Zefyr documents are based on Quill.js [Delta][] format. Deltas are
+simple and expressive format of describing rich text data, and is also
+suitable for [Operational transformations][ot]. The format is
+essentially JSON, and is human readable.
+
+> Official implementation of Delta format is written in
+> [JavaScript][github-delta] but it was ported to Dart and is available
+> on [Pub][pub-delta]. Examples in this document use Dart syntax.
+
+[Delta]: https://quilljs.com/docs/delta/
+[ot]: https://en.wikipedia.org/wiki/Operational_transformation
+[github-delta]: https://github.com/quilljs/delta
+[pub-delta]: https://pub.dartlang.com/packages/quill_delta
+
+### Deltas quick start
+
+All Deltas consist of three operations: `insert`, `delete` and `retain`. The
+example below describes the string "Karl the Fog" where "Karl" is bolded
+and "Fog" is italic:
+
+```dart
+var delta = new Delta();
+delta
+  ..insert('Karl', {'bold': true})
+  ..insert(' the ')
+  ..insert('Fog', {'italic': true});
+print(json.encode(delta));
+// Prints:
+// [
+//   {"insert":"Karl","attributes":{"bold":true}},
+//   {"insert":" the "},
+//   {"insert":"Fog","attributes":{"italic":true}}
+// ]
+```
+
+Above delta is usually also called "document delta" because it consists
+of only `insert` operations.
+
+Below example describes a *change* where "Fog" gets also styled as bold:
+
+```dart
+var delta = new Delta();
+delta..retain(9)..retain(3, {'bold': true});
+print(json.encode(delta));
+// Prints:
+// [{"retain":9},{"retain":3,"attributes":{"bold":true}}]
+```
+
+A simple way to visualize a change is as if it moves an imaginary cursor
+and applies modifications on the way. So with the above example, the
+first `retain` operation moves the cursor forward 9 characters. Then,
+second operation moves cursor additional 3 characters forward but also
+applies bold style to each character it passes.
+
+The Delta library provides a way of composing such changes into documents
+or transforming against each other. E.g.:
+
+```dart
+var doc = new Delta();
+doc
+  ..insert('Karl', {'bold': true})
+  ..insert(' the ')
+  ..insert('Fog', {'italic': true});
+var change = new Delta();
+change..retain(9)..retain(3, {'bold': true});
+var updatedDoc = doc.compose(change);
+print(json.encode(updatedDoc));
+// Prints:
+//  [
+//    {"insert":"Karl","attributes":{"bold":true}},
+//    {"insert":" the "},
+//    {"insert":"Fog","attributes":{"italic":true,"bold":true}}
+//  ]
+```
+
+These are the basics of Deltas. Read [official documentation][delta-docs]
+for more details.
+
+[delta-docs]: https://quilljs.com/docs/delta/
+
+### Document model
+
+Zefyr documents are represented as a tree of nodes. There are 3 main types of
+nodes:
+
+* `Text` - a leaf node which represents a segment of styled text within
+  a document.
+* `Line` - represents an individual line of text within a document.
+  Line nodes are containers for leaf nodes.
+* `Block` - represents a group of adjacent lines which share the same
+  style. Examples of blocks include lists, quotes or code blocks.
+
+Given above description, here is ASCII-style visualization of a Zefyr
+document tree:
+
+```
+root
+ ╠═ block
+ ║   ╠═ line
+ ║   ║   ╠═ text
+ ║   ║   ╚═ text
+ ║   ╚═ line
+ ║       ╚═ text
+ ╠═ line
+ ║   ╚═ text
+ ╚═ block
+     ╚═ line
+         ╠═ text
+         ╚═ text
+```
+
+It is currently not allowed to nest blocks inside other blocks but this
+may change in the future. More node types are likely to be added as well.
+For example, another leaf node for embedded content, like images.
+
+All manipulations of Zefyr documents are designed strictly to match
+semantics of underlying Delta format. As a result the model itself is
+fairly simple and predictable.
+
+To learn more about consequences of this design read about
+[attributes][] and [heuristics][].
+
+[heuristics]: /doc/heuristics.md
+[attributes]: /doc/attributes.md
+
+### Next
+
+* [Attributes](/doc/attributes.md)
+
+### Previous
+
+* [Usage](/doc/usage.md)

doc/faq.md

@@ -0,0 +1,17 @@
+## Frequently asked questions
+
+### Are Zefyr documents compatible with Quill documents?
+
+Short answer is no. Even though Zefyr uses Quill Delta as underlying
+representation for its documents there are at least differences in
+attribute declarations. For instance heading style in Quill
+editor uses "header" as the attribute key, in Zefyr it's "heading".
+
+There are also semantical differences. In Quill, both list and heading
+styles are treated as block styles. This means applying "heading"
+style to a list item removes the item from the list. In Zefyr, heading
+style is handled separately from block styles like lists and quotes.
+As a consequence you can have a heading line inside of a quote block.
+This is intentional and inspired by how Markdown handles such scenarios.
+In fact, Zefyr format tries to follow Markdown semantics as close as
+possible.

doc/heuristics.md

@@ -0,0 +1,89 @@
+## Heuristic rules
+
+As it turns out, a good rich text editor not only allows the user to
+manually apply different styles to text in a document. It can also
+automatically apply certain styles based on the context of a user
+action.
+
+Some very common examples include autoformatting of links or inserting
+a new list item.
+
+In Zefyr, such rules are called *heuristic rules*. There are two main
+purposes for heuritic rules:
+
+1. User experience: rules like above-mentioned autoformatting of links
+  are here to make editing a nice and pleasant process.
+2. Style normalizing: this is mostly invisible for the user but
+  is very important nevertheless. There is a set of rules to make sure
+  that a document change conforms to the data format and model
+  semantics.
+
+Let's cover the second item in more detail.
+
+Say, a user is editing following document (cursor position is indicated
+by pipe `|` character):
+
+> ### Document| title styled as h3 heading
+> Regular paragraph with **bold** text.
+
+User decides to change the first line style from `h3` to `h2`. If we
+were to apply this change to the document in code it would look like
+this:
+
+```dart
+var doc = getDocument();
+var cursorPosition = 8; // after the word "Document"
+var selectionLength = 0; // selection is collapsed.
+var change = doc.format(
+  cursorPosition, selectionLength, ZefyrAttribute.heading.level2);
+```
+
+If we try to apply this change as-is it would have no effect or, more
+likely, result in an `AssertionError`. This is why all methods in
+`ZefyrDocument` have an extra step which applies heuristic rules to
+the change (there is one method which skips this step, `compose`,
+read more on it later) before actually composing it.
+
+The `ZefyrDocument.format` method returns an instance of `Delta` which
+was actualy applied to the document. For the above scenario it would
+look like this:
+
+```json
+[
+  {"retain": 35},
+  {"retain": 1, "attributes": {"heading": 2} }
+]
+```
+
+The above change applies `h2` style to the 36th character in the
+document, that's the *newline* character of the first line, exactly
+what user intended to do.
+
+There are more similar scenarios which are covered by heuristic rules
+to ensure consistency with the document model and provide better UX.
+
+### `ZefyrDocument.compose()` and skipping heuristic rules.
+
+The `compose()` method is the only method which skips the step of
+applying heuristic rules and therefore **should be used with great
+care** as it can result in corrupted document state.
+
+Use this method when you sure that the change you are about to compose
+conforms to the document model and data format semantics.
+
+This method exists mostly to enable following use cases:
+
+* **Collaborative editing**, when a change came from a different site and
+  has already been normalized by heuristic rules on that site. Care must
+  be taken to ensure that this change is based on the same revision
+  of the document, and if not, transformed against any local changes
+  before composing.
+* **Change history and revisioning**, when a change came from a revision
+  history stored on a server or a database. Similarly, care must be
+  taken to transform the change against any local (uncommitted) changes
+  before composing.
+
+When composing a change which came from a different site or server make
+sure to use `ChangeSource.api` when calling `compose()`. This allows
+you to distinguish such changes from local changes made by the user
+when listening on `ZefyrDocument.changes` stream.

doc/quick_start.md

@@ -0,0 +1,71 @@
+## Quick Start
+
+### Installation
+
+Add `zefyr` package as a dependency to your `pubspec.yaml`:
+
+```yaml
+dependencies:
+  zefyr: ^0.1.0
+```
+
+And run `flutter packages get` to install.
+
+### Usage
+
+There are 3 main objects you would normally interact with in your code:
+
+* `ZefyrDocument`, represents a rich text document and provides
+  high-level methods for manipulating the document's state, like
+  inserting, deleting and formatting of text.
+  Read [documentation][data_and_docs] for more details on Zefyr's
+  document model and data format.
+* `ZefyrEditor`, a Flutter widget responsible for rendering of rich text
+  on the screen and reacting to user actions.
+* `ZefyrController`, ties the above two objects together.
+
+Normally you would need to place `ZefyrEditor` inside of a
+`StatefulWidget`. Shown below is a minimal setup required to use the
+editor:
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:zefyr/zefyr.dart';
+
+class MyWidget extends StatefulWidget {
+  @override
+  MyWidgetState createState() => MyWidgetState();
+}
+
+class MyWidgetState extends State<MyWidget> {
+  final ZefyrController _controller;
+  final FocusNode _focusNode;
+
+  @override
+  void initState() {
+    super.initState();
+    // Create an empty document or load existing if you have one.
+    // Here we create an empty document:
+    final document = new ZefyrDocument();
+    _controller = new ZefyrController(document);
+    _focusNode = new FocusNode();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return ZefyrEditor(
+      controller: _controller,
+      focusNode: _focusNode,
+    );
+  }
+}
+```
+
+In following sections you will learn more about document
+model, Deltas, attributes and other aspects of the editor.
+
+### Next
+
+* [Data Format and Document Model][data_and_docs]
+
+[data_and_docs]: /doc/data_and_document.md