docs: add components overview (#6186)

README.md

@@ -23,13 +23,16 @@
 
 ## Overview
 
-BlockSuite is a toolkit for building diverse collaborative editors and applications. It implements a series of collaborative editing infrastructures and editors independently.
+> _People who are really serious about editor should make their own framework._
 
-With BlockSuite, you can:
+BlockSuite is a toolkit for building editors and collaborative applications. It implements a series of content editing infrastructures, UI components and editors independently.
 
-- Reuse multiple first-party BlockSuite editors right out of the box:
+You can consider BlockSuite as a [UI component library](https://blocksuite.io/components/overview.html) for building various editors, based on a minimized vanilla framework as their runtime. With BlockSuite, you can:
+
+- Reuse multiple first-party BlockSuite editors:
   - [**`DocEditor`**](https://blocksuite.io/components/doc-editor.html): A comprehensive block-based document editor, offering extensive customization and flexibility.
-  - [**`EdgelessEditor`**](https://blocksuite.io/components/edgeless-editor.html): A graphicis editor featuring canvas-based graphics rendering, but also shares the same rich-text capabilities with the `DocEditor`.
+  - [**`EdgelessEditor`**](https://blocksuite.io/components/edgeless-editor.html): A graphics editor with opt-in canvas rendering support, but also shares the same rich-text capabilities with the `DocEditor`.
+- Customize, extend and enhance these editors with a rich set of [BlockSuite components](https://blocksuite.io/components/overview.html). All BlockSuite components (including editors) are native web components, making them framework-agnostic and easy to interop with popular frameworks.
 - Or, build new editors from scratch based on the underlying vallina framework.
 
 > 🚧 BlockSuite is currently in its early stage, with components and extension capabilities still under refinement. Hope you can stay tuned, try it out, or share your feedback!
@@ -40,7 +43,7 @@ BlockSuite originated from the open-source knowledge base [AFFiNE](https://githu
 
 - **Support for Multimodal Editable Content**: When considering knowledge as a single source of truth, building its various view modes (e.g., text, slides, mind maps, tables) still requires multiple incompatible frameworks. Ideally, no matter how the presentation of content changes, there should be a consistent framework that helps.
 - **Organizing and Visualizing Complex Knowledge**: Existing editors generally focus on editing single documents, but often fall short in dealing with complex structures involving intertwined references. This requires the framework to natively manage state across multiple documents.
-- **Collaboration-Ready**: Real-time collaboration is often seen as an optional plugin, but in reality, we should natively use the underlying CRDT technology for editor state management, which helps to build a [clearer and more reliable data flow](https://blocksuite.io/blog/crdt-native-data-flow.html).
+- **Collaboration-Ready**: Real-time collaboration is often seen as an optional plugin, but in reality, we could natively use the underlying CRDT technology for editor state management, which helps to build a [clearer and more reliable data flow](https://blocksuite.io/blog/crdt-native-data-flow.html).
 
 During the development of AFFiNE, it became clear that BlockSuite was advancing beyond merely being an in-house editor and evolving into a versatile framework. That's why we chose to open source and maintain BlockSuite independently.
 
@@ -58,7 +61,7 @@ And under the hood, the vanilla BlockSuite framework supports:
 - Persistence of documents and compatibility with various third-party formats (such as markdown and HTML) based on block [snapshot](https://blocksuite.io/guide/data-synchronization.html#snapshot-api) and transformer.
 - State scheduling across multiple documents and reusing one document in multiple editors.
 
-To try out BlockSuite, refer to the [Quick Start](https://blocksuite.io/guide/quick-start.html) example and start with the preset editors in `@blocksuite/presets`.
+To try out BlockSuite, refer to the [quick start](https://blocksuite.io/guide/quick-start.html) example and start with the preset editors in `@blocksuite/presets`.
 
 ## Architecture
 

packages/docs/.vitepress/config.ts

@@ -49,8 +49,8 @@ export default defineConfig({
 
     nav: [
       {
-        text: 'Components 🚧',
-        link: '/components/doc-editor',
+        text: 'Components',
+        link: '/components/overview',
         activeMatch: '/components/*',
       },
       {

packages/docs/.vitepress/sidebar.ts

@@ -122,7 +122,16 @@ export const reference: DefaultTheme.NavItem[] = [
 ];
 
 export const components: DefaultTheme.NavItem[] = [
-  { text: 'Component Types', link: 'guide/component-types' },
+  {
+    text: 'Introduction',
+    items: [
+      { text: 'Overview', link: 'components/overview' },
+      {
+        text: 'AFFiNE Integration',
+        link: 'components/overview#affine-integration',
+      },
+    ],
+  },
   {
     text: 'Editors',
     items: [
@@ -146,7 +155,7 @@ export const components: DefaultTheme.NavItem[] = [
         ],
       },
       {
-        text: 'Special Blocks',
+        text: 'Advanced Blocks',
         items: [
           { text: 'Surface Block', link: '' },
           { text: 'Database Block', link: '' },
@@ -169,8 +178,8 @@ export const components: DefaultTheme.NavItem[] = [
     text: 'Fragments 🚧',
     items: [
       { text: 'Doc Title', link: '' },
-      { text: 'Frame Panel', link: '' },
       { text: 'Outline Panel', link: '' },
+      { text: 'Frame Panel', link: '' },
       { text: 'Copilot Panel', link: '' },
       { text: 'Bi-Directional Link Panel', link: '' },
     ],

packages/docs/components/overview.md

@@ -0,0 +1,40 @@
+# BlockSuite Components Overview
+
+BlockSuite implements the editor features for the [AFFiNE](https://affine.pro/) knowledge base. The relationship between them is similar to that between the [Monaco Editor](https://github.com/microsoft/monaco-editor) and [VSCode](https://code.visualstudio.com/), but with one major difference: BlockSuite is not automatically generated based on the AFFiNE codebase, but is maintained independently with a different tech stack — AFFiNE uses React while BlockSuite uses [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
+
+This difference has led BlockSuite to set clear boundaries based on a **component-centric** philosophy, ensuring:
+
+- Both AFFiNE and other projects should equally reuse and extend BlockSuite through components, without any privileges.
+- BlockSuite components can be easily reused regardless of whether you are using React or other frameworks.
+- How you extend BlockSuite is precisely how you extend AFFiNE.
+
+## Component Basics
+
+In a nutshell, BlockSuite categorizes components into the following types:
+
+- **Editor** - A container used to present document content in various forms. Different editors are composed of different sets of [block specs](../guide/block-spec).
+- **Block** - The atomic unit for constructing document within the editor. Once a block spec is registered, multiple corresponding block instances can be rendered in the editor.
+- **Widget** - Auxiliary components that contextually show up in the editor on demand, such as a search bar or color picker. Every block can define its own widgets.
+- **Fragment** - Independent components outside the editor. They share the document with the editor but have their own lifecycles.
+
+![showcase-fragments-2](../images/showcase-fragments-2.jpg)
+
+These BlockSuite components are all implemented based on web components. For a more detailed description of the relationships between these components, please refer to the [component types](../guide/component-types) document.
+
+## Extension and Customization
+
+Based on the components API, BlockSuite allows:
+
+- [Defining third-party blocks](../guide/working-with-block-tree#defining-new-blocks) compatible with multiple editors.
+- Configuring, extending, and replacing widgets within the editor, such as various toolbars, popups, and menus.
+- Reusing components outside of the editor, such as panels for comments, outlines, or even AI copilots.
+
+All BlockSuite components only need to be attached to the BlockSuite document model for use. For information on how to interact with this block tree, please refer to the [usage guide](../guide/working-with-block-tree) for the BlockSuite framework.
+
+## AFFiNE Integration
+
+Regarding how BlockSuite components can be used in AFFiNE (or any other product of yours), here are some quick takeaways:
+
+- The BlockSuite editor consists of various block specs, each of which can optionally include some widgets. Therefore, **when you are reusing an existing first-party BlockSuite editor, you are actually reusing a preset of blocks and widgets**. Default editors are fine-tuned presets for AFFiNE, but you are free to compose you own presets.
+- Currently, all BlockSuite components are native web components, but we plan to provide official support for multiple frameworks.
+- AFFiNE does not use a special version of BlockSuite, [we eat our own dogfood](https://gist.github.com/chitchcock/1281611).

packages/docs/guide/block-spec.md

@@ -4,15 +4,15 @@ In BlockSuite, a `BlockSpec` defines the structure and interactive elements for
 
 A block spec contains the following properties:
 
-- `schema`: Defines the structure and data types for the block's content.
-- `service`: Used for registering methods for specific actions and external invocations.
-- `view`: Represents the visual representation and layout of the block.
+- [`schema`](./block-schema): Defines the structure and data types for the block's content.
+- [`service`](./block-service): Used for registering methods for specific actions and external invocations.
+- [`view`](./block-view): Represents the visual representation and layout of the block.
   - `component`: The primary user interface element of the block.
   - `widgets`: Additional interactive elements enhancing the block's functionality.
 
 ![block-spec](../images/block-spec.png)
 
-## Lit-Based Example
+## Example
 
 Note that in block spec, the definition of `view` is related to UI frameworks. By default, we provide a `@blocksuite/lit` package to help build a lit block view. But it's still possible to use other UI frameworks. We'll introduce later about how to write custom block renderers.
 

packages/docs/guide/block-view.md

@@ -4,7 +4,7 @@ In BlockSuite, blocks can be rendered by any UI framework. A block should be ren
 
 By default, we provide a [lit](https://lit.dev/) renderer called `@blocksuite/lit`. But it's still possible to use other UI frameworks. We'll introduce later about how to write custom block renderers.
 
-## Lit Block View
+## Web Component Block View
 
 We provide a `BlockElement` class to help building a lit-based block view.
 

packages/docs/guide/component-types.md

@@ -4,13 +4,13 @@
 🌐 This documentation has a [Chinese translation](https://insider.affine.pro/share/af3478a2-9c9c-4d16-864d-bffa1eb10eb6/94-Y53OqW0NFm6l-wqDz6).
 :::
 
-After getting started, this section outlines the foundational editing components in BlockSuite, namely `Editor`, `Fragment`, `Block` and `Widget`.
+After getting started, this section outlines the foundational [editing components](../components/overview) in BlockSuite, namely `Editor`, `Fragment`, `Block` and `Widget`.
 
 ## Editors and Fragments
 
-The `@blocksuite/presets` package includes reusable editors like `DocEditor` and `EdgelessEditor`. Besides these editors, BlockSuite also defines **_fragments_** - UI components that are not editors but are dependent on the document's state. These fragments, such as sidebars, panels, and toolbars, may be independent in lifecycle from the editors, yet should work out-of-the-box when attached to the block tree.
+The `@blocksuite/presets` package includes reusable editors like `DocEditor` and `EdgelessEditor`. Besides these editors, BlockSuite also defines **_fragments_** - UI components that are **NOT** editors but are dependent on the document's state. These fragments, such as sidebars, panels, and toolbars, may be independent in lifecycle from the editors, yet should work out-of-the-box when attached to the block tree.
 
-The distinction between editors and fragments lies in their complexity and functionality. **Fragments typically offer more simplified capabilities, serving specific UI purposes, whereas editors provide comprehensive editing capabilities over the block tree**. Nevertheless, both editors and fragments shares similar tech stacks and [data flows](/blog/crdt-native-data-flow).
+The distinction between editors and fragments lies in their complexity and functionality. **Fragments typically offer more simplified capabilities, serving specific UI purposes, whereas editors provide comprehensive editing capabilities over the block tree**. Nevertheless, both editors and fragments shares similar [data flows](/blog/crdt-native-data-flow).
 
 ![showcase-fragments-2](../images/showcase-fragments-2.jpg)
 
@@ -26,7 +26,7 @@ Within each block spec, there can be [`Widget`](./block-widgets)s specific to th
 
 In BlockSuite, the `editor` is typically designed to be remarkably lightweight. The actual editable blocks are registered to the [`EditorHost`](/api/@blocksuite/lit/) component, which is a container for mounting block UI components.
 
-BlockSuite by default offers a host based on the [lit](https://lit.dev) framework. For example, this is a conceptually usable BlockSuite editor composed by [`BlockSpec`](./block-spec)s:
+BlockSuite by default offers a host based on the [lit](https://lit.dev) framework. For example, this is a conceptually usable BlockSuite editor composed of [`BlockSpec`](./block-spec)s:
 
 ```ts
 // Default BlockSuite editable blocks
@@ -80,4 +80,4 @@ This allows you to **implement various editors easily on top of the same documen
 
 ## Summary
 
-So far, we've explained the interplay between editors, fragments, blocks, and widgets. The next sections will delve into more detailed functionalities of BlockSuite, starting with block tree manipulation.
+So far, we have explored the interplay between different BlockSuite component types. The subsequent sections will delve deeper into the detailed framework functionalities, beginning with block tree manipulation. For the moment, understanding the structured outline of the [BlockSuite components](../components/overview) gallery might provide clearer insights.

packages/docs/guide/overview.md

@@ -1,12 +1,17 @@
-# BlockSuite Overview
+# BlockSuite Framework Overview
 
-BlockSuite is a toolkit for building diverse collaborative editors and applications. It implements a series of collaborative editing infrastructures and editors independently.
+> _People who are really serious about editor should make their own framework._
 
-With BlockSuite, you can:
+---
 
-- Reuse multiple first-party BlockSuite editors right out of the box:
+BlockSuite is a toolkit for building editors and collaborative applications. It implements a series of content editing infrastructures, UI components and editors independently.
+
+You can consider BlockSuite as a [UI component library](../components/overview) for building various editors, based on a minimized vanilla framework as their runtime. With BlockSuite, you can:
+
+- Reuse multiple first-party BlockSuite editors:
   - [**`DocEditor`**](../components/doc-editor): A comprehensive block-based document editor, offering extensive customization and flexibility.
-  - [**`EdgelessEditor`**](../components/edgeless-editor): A graphicis editor featuring canvas-based graphics rendering, but also shares the same rich-text capabilities with the `DocEditor`.
+  - [**`EdgelessEditor`**](../components/edgeless-editor): A graphics editor with opt-in canvas rendering support, but also shares the same rich-text capabilities with the `DocEditor`.
+- Customize, extend and enhance these editors with a rich set of [BlockSuite components](../components/overview). All BlockSuite components (including editors) are native web components, making them framework-agnostic and easy to interop with popular frameworks.
 - Or, build new editors from scratch based on the underlying vallina framework.
 
 > 🚧 BlockSuite is currently in its early stage, with components and extension capabilities still under refinement. Hope you can stay tuned, try it out, or share your feedback!
@@ -17,10 +22,12 @@ BlockSuite originated from the open-source knowledge base [AFFiNE](https://githu
 
 - **Support for Multimodal Editable Content**: When considering knowledge as a single source of truth, building its various view modes (e.g., text, slides, mind maps, tables) still requires multiple incompatible frameworks. Ideally, no matter how the presentation of content changes, there should be a consistent framework that helps.
 - **Organizing and Visualizing Complex Knowledge**: Existing editors generally focus on editing single documents, but often fall short in dealing with complex structures involving intertwined references. This requires the framework to natively manage state across multiple documents.
-- **Collaboration-Ready**: Real-time collaboration is often seen as an optional plugin, but in reality, we should natively use the underlying CRDT technology for editor state management, which helps to build a [clearer and more reliable data flow](../blog/crdt-native-data-flow).
+- **Collaboration-Ready**: Real-time collaboration is often seen as an optional plugin, but in reality, we could natively use the underlying CRDT technology for editor state management, which helps to build a [clearer and more reliable data flow](../blog/crdt-native-data-flow).
 
 During the development of AFFiNE, it became clear that BlockSuite was advancing beyond merely being an in-house editor and evolving into a versatile framework. That's why we chose to open source and maintain BlockSuite independently.
 
+<!-- ## Examples -->
+
 ## Features
 
 With BlockSuite editors, you can selectively reuse all the editing features in [AFFiNE](https://affine.pro/):
@@ -35,7 +42,7 @@ And under the hood, the vanilla BlockSuite framework supports:
 - Persistence of documents and compatibility with various third-party formats (such as markdown and HTML) based on block [snapshot](./data-synchronization#snapshot-api) and transformer.
 - State scheduling across multiple documents and reusing one document in multiple editors.
 
-To try out BlockSuite, refer to the [Quick Start](./quick-start) example and start with the preset editors in `@blocksuite/presets`.
+To try out BlockSuite, refer to the [quick start](./quick-start) example and start with the preset editors in `@blocksuite/presets`.
 
 ## Architecture
 

packages/docs/guide/quick-start.md

@@ -1,6 +1,6 @@
 # Quick Start
 
-The `@blocksuite/presets` package contains the prebuilt editors and opt-in additional UI components. Its `canary` versions are released daily based on the master branch, which is also recommended for real world usage. You may also need to install `@blocksuite/store` explicitly for working with BlockSuite documents:
+The `@blocksuite/presets` package contains the prebuilt editors and opt-in additional UI components. Its `canary` versions are released daily based on the master branch, which is also used in production in [AFFiNE](https://github.com/toeverything/AFFiNE). To work with the BlockSuite document model, You may also need to install `@blocksuite/store` explicitly:
 
 ```sh
 pnpm install \
@@ -37,3 +37,10 @@ import { Text } from '@blocksuite/store';
 The `DocEditor` here is a standard web component that can also be reused with `<doc-editor>` HTML tag. Another `EdgelessEditor` also works similarly - simply attach the `editor` with a `page` and you are all set.
 
 For the `page.getBlockByFlavour` and `page.updateBlock` APIs used here, please see the [introduction](./working-with-block-tree#block-tree-basics) about block tree basics for further details.
+
+As the next step, you can choose to:
+
+- Explore how BlockSuite break down editors into different [component types](./component-types). Taking a look at the list of [BlockSuite components](../components/overview) may also be helpful.
+- Alternatively, learn about [basic concepts](./working-with-block-tree) in BlockSuite framework that are used throughout the development of editors.
+
+Note that BlockSuite is still under rapid development. For any questions or feedback, feel free to let us know!