docs: clarify container detached/attached states and text methods (#20)

Author: zxch3n

pages/docs/advanced/cid.mdx

@@ -44,6 +44,17 @@ export type ContainerID =
      containers
    - Contains the Operation ID of its creation within its Container ID
 
+## Container States and IDs
+
+The ContainerID is not a random UUID but is deterministically generated based on the container's context. To understand how ContainerIDs work, it's important to first understand container states.
+
+> For a comprehensive guide on containers, including attached vs detached states, see [Container Concepts](/docs/concepts/container).
+
+Key points about ContainerID generation:
+- **Root containers**: Derive their ID from their name (e.g., "text" in `doc.getText("text")`)
+- **Normal containers**: Derive their ID from the operation (OpID) that created them
+- **Detached containers**: Have a default placeholder ID until they're inserted into a document
+
 ## Container Overwrites
 
 When initializing child containers in parallel, overwrites can occur instead of

pages/docs/concepts/_meta.js

@@ -1,5 +1,6 @@
 export default {
   crdt: "What are CRDTs",
+  container: "Container",
   choose_crdt_type: "How to Choose the Right CRDT Types",
   when_not_crdt: "When Not to Rely on CRDTs"
 }

pages/docs/concepts/container.mdx

@@ -0,0 +1,170 @@
+# Container
+
+Containers are the fundamental building blocks in Loro for organizing and structuring collaborative data. They provide typed data structures that automatically merge when concurrent edits occur.
+
+## Container Types
+
+Loro provides several container types, each optimized for different use cases:
+
+- **LoroMap**: Key-value pairs with Last-Write-Wins semantics
+- **LoroList**: Ordered sequences that merge concurrent insertions
+- **LoroText**: Text with character-level merging and rich text support
+- **LoroTree**: Hierarchical tree structures with move operations
+- **LoroMovableList**: Lists with reordering capabilities
+- **LoroCounter**: Numerical values with increment/decrement operations
+
+## Container States: Attached vs Detached
+
+Containers in Loro exist in two distinct states that affect their behavior and identity.
+
+### Detached Containers
+
+A container is **detached** when created directly using constructors:
+
+```ts twoslash
+import { LoroMap, LoroText, LoroList } from "loro-crdt";
+// ---cut---
+// These containers are all detached
+const map = new LoroMap();
+const text = new LoroText();
+const list = new LoroList();
+```
+
+Characteristics of detached containers:
+- Not yet part of any document
+- Have a default placeholder ContainerID
+- Can be used as templates or temporary data structures
+- Will get a proper ContainerID when inserted into a document
+
+### Attached Containers
+
+A container becomes **attached** when it's part of a document hierarchy:
+
+```ts twoslash
+import { LoroDoc, LoroMap, LoroText } from "loro-crdt";
+// ---cut---
+const doc = new LoroDoc();
+
+// Root containers are immediately attached
+const rootMap = doc.getMap("myMap");
+const rootText = doc.getText("myText");
+
+// Child containers: the returned value is attached
+const detachedChild = new LoroText();
+const attachedChild = rootMap.setContainer("child", detachedChild);
+// Note: detachedChild remains detached
+// attachedChild is the attached version with proper ContainerID
+```
+
+Characteristics of attached containers:
+- Belong to a specific document
+- Have a proper ContainerID that uniquely identifies them
+- Changes are tracked in the document's history
+- Can be synchronized across peers
+
+## Container IDs
+
+Every attached container has a unique ContainerID that identifies it within the distributed system. The ID generation depends on the container type:
+
+- **Root containers**: ID derived from their name (e.g., "myMap" in `doc.getMap("myMap")`)
+- **Child containers**: ID based on the operation that created them (OpID)
+
+This deterministic ID generation ensures that:
+- The same container can be identified across all peers
+- Container IDs are not random but contextually determined
+- A detached container cannot have its final ID until insertion
+
+## Working with Containers
+
+### Creating Root Containers
+
+Root containers are created through the document API and are immediately attached:
+
+```ts twoslash
+import { LoroDoc } from "loro-crdt";
+// ---cut---
+const doc = new LoroDoc();
+
+// These methods create or get root containers
+const map = doc.getMap("settings");
+const text = doc.getText("content");
+const list = doc.getList("items");
+const tree = doc.getTree("hierarchy");
+```
+
+### Nesting Containers
+
+Containers can be nested to create complex data structures:
+
+```ts twoslash
+import { LoroDoc, LoroMap, LoroList, LoroText } from "loro-crdt";
+// ---cut---
+const doc = new LoroDoc();
+const rootMap = doc.getMap("root");
+
+// Method 1: Using setContainer (returns attached container)
+const childText = rootMap.setContainer("description", new LoroText());
+
+// Method 2: Using insertContainer for lists
+const list = doc.getList("items");
+const childMap = list.insertContainer(0, new LoroMap());
+```
+
+## Container Overwrites
+
+When initializing child containers in parallel, overwrites can occur instead of
+automatic merging. For example:
+
+```ts twoslash
+import { LoroDoc, LoroText } from "loro-crdt";
+// ---cut---
+const a: string = "hello";
+const doc = new LoroDoc();
+const map = doc.getMap("map");
+
+// Parallel initialization of child containers
+const docB = doc.fork();
+const textA = doc.getMap("map").setContainer("text", new LoroText());
+textA.insert(0, "A");
+const textB = docB.getMap("map").setContainer("text", new LoroText());
+textB.insert(0, "B");
+
+doc.import(docB.export({ mode: "update" }));
+// Result: Either { "meta": { "text": "A" } } or { "meta": { "text": "B" } }
+```
+
+This behavior poses a significant risk of data loss if the editing history is
+not preserved. Even when the complete history is available and allows for data
+recovery, the recovery process can be complex.
+
+<aside>
+By default, Loro and Automerge preserve the whole editing history in a directed
+acyclic graph like Git.
+</aside>
+
+When a container holds substantial data or serves as the primary storage for
+document content, overwriting it can lead to the unintended hiding/loss of
+critical information. For this reason, it is essential to implement careful and
+systematic container initialization practices to prevent such issues.
+
+### Best Practices
+
+1. When containers might be initialized concurrently, prefer initializing them
+   at the root level rather than as nested containers
+
+2. When using map containers:
+   - If possible, initialize all child containers during the map container's
+     initialization
+   - Avoid concurrent creation of child containers with the same key in the map
+     container to prevent overwrites
+
+The overwrite behavior occurs because parallel creation of child containers
+results in different container IDs, preventing automatic merging of their
+contents.
+
+
+## Related Concepts
+
+- [Container ID](/docs/advanced/cid): Deep dive into how Container IDs work
+- [Choosing CRDT Types](/docs/concepts/choose_crdt_type): Guide for selecting the right container type
+- [Composition](/docs/tutorial/composition): How to compose containers into complex structures

pages/docs/index.mdx

@@ -1,4 +1,4 @@
-# Introduction to Loro
+## Introduction to Loro
 
 It is well-known that syncing data/building realtime collaborative apps is
 challenging, especially when devices can be offline or part of a peer-to-peer
@@ -92,7 +92,7 @@ import { Cards } from "nextra/components";
   </Cards.Card>
 </Cards>
 
-# Is Loro Right for You?
+## Is Loro Right for You?
 
 ### ✅ Use Loro when you need:
 
@@ -111,7 +111,7 @@ import { Cards } from "nextra/components";
 
 [Learn more about when not to use CRDTs →](/docs/concepts/when_not_crdt)
 
-# Differences from other CRDT libraries
+## Differences from other CRDT libraries
 
 The table below summarizes Loro's features, which may not be present in other
 CRDT libraries.

pages/docs/tutorial/text.mdx

@@ -34,7 +34,7 @@ The [loro-prosemirror](https://github.com/loro-dev/loro-prosemirror) package pro
 
 The ProseMirror binding can also be used with [Tiptap](https://tiptap.dev/), a popular rich text editor built on top of ProseMirror. This means you can easily add collaborative editing capabilities to your Tiptap-based applications.
 
-```ts no_run twoslash
+```ts no_run
 import {
   CursorAwareness,
   LoroCursorPlugin,
@@ -47,9 +47,7 @@ import { LoroDoc } from "loro-crdt";
 import { EditorView } from "prosemirror-view";
 import { EditorState } from "prosemirror-state";
 import { keymap } from "prosemirror-keymap";
-declare const pmPlugins: any[];
-declare const editorDom: HTMLElement;
-// ---cut---
+
 const doc = new LoroDoc();
 const awareness = new CursorAwareness(doc.peerIdStr);
 const plugins = [
@@ -76,12 +74,12 @@ The [loro-codemirror](https://github.com/loro-dev/loro-codemirror) package provi
 - Cursor awareness
 - Undo/Redo functionality
 
-```ts no_run twoslash
+```ts no_run
 import { EditorState } from "@codemirror/state";
 import { EditorView } from "@codemirror/view";
 import { LoroExtensions } from "loro-codemirror";
 import { Awareness, LoroDoc, UndoManager } from "loro-crdt";
-// ---cut---
+
 const doc = new LoroDoc();
 const awareness = new Awareness(doc.peerIdStr);
 const undoManager = new UndoManager(doc, {});
@@ -316,11 +314,44 @@ const restored = Cursor.decode(bytes);
 const pos = doc.getCursorPos(restored);
 ```
 
+### `toJSON(): string`
+
+Returns the plain text content as a string. This method:
+- Returns only the text content without any formatting marks
+- Is not affected by any rich text attributes (bold, italic, links, etc.)
+- Is equivalent to `toString()` for text containers
+
+If you need rich text information including formatting, use `toDelta()` instead.
+
 ### `toDelta(): Delta<string>[]`
 
-Get the rich text value. It's in
+Get the rich text value with all formatting information. It's in
 [Quill's Delta format](https://quilljs.com/docs/delta/).
 
+Unlike `toJSON()` which returns plain text, `toDelta()` preserves all rich text attributes like bold, italic, links, and custom marks.
+
+Example comparing `toJSON()` vs `toDelta()`:
+
+```ts twoslash
+import { LoroDoc } from "loro-crdt";
+// ---cut---
+const doc = new LoroDoc();
+doc.configTextStyle({ bold: { expand: "after" } });
+const text = doc.getText("text");
+text.insert(0, "Hello World!");
+text.mark({ start: 0, end: 5 }, "bold", true);
+
+// toJSON returns plain string without marks
+console.log(text.toJSON()); // "Hello World!"
+
+// toDelta returns rich text with formatting
+console.log(text.toDelta());
+// [
+//   { insert: "Hello", attributes: { bold: true } },
+//   { insert: " World!" }
+// ]
+```
+
 ### `mark(range: {start: number, end: number}, key: string, value: any): void`
 
 Mark the given range with a key-value pair.