From 1d044380498ef90ac0e7193c4d4e9b541fb5d393 Mon Sep 17 00:00:00 2001 From: Saul-Mirone Date: Mon, 17 Mar 2025 12:51:08 +0000 Subject: [PATCH] docs(editor): scaffolding docs generator (#10925) --- .github/workflows/build-test.yml | 9 + .prettierignore | 1 + blocksuite/docs/README.md | 12 ++ .../docs/api/@blocksuite/block-std/README.md | 12 ++ .../api/@blocksuite/block-std/gfx/README.md | 46 +++++ .../gfx/classes/GfxBlockElementModel.md | 147 ++++++++++++++ .../gfx/classes/GfxSelectionManager.md | 50 +++++ .../block-std/gfx/functions/GfxCompatible.md | 35 ++++ .../gfx/functions/canSafeAddToContainer.md | 25 +++ .../block-std/gfx/functions/compareLayer.md | 26 +++ .../block-std/gfx/functions/convert.md | 49 +++++ .../block-std/gfx/functions/derive.md | 54 +++++ .../gfx/functions/generateKeyBetween.md | 27 +++ .../gfx/functions/generateKeyBetweenV2.md | 28 +++ .../gfx/functions/generateNKeysBetween.md | 39 ++++ .../block-std/gfx/functions/getTopElements.md | 36 ++++ .../functions/isGfxGroupCompatibleModel.md | 21 ++ .../block-std/gfx/functions/local.md | 42 ++++ .../block-std/gfx/functions/observe.md | 53 +++++ .../block-std/gfx/functions/watch.md | 46 +++++ .../gfx/interfaces/GfxCompatibleInterface.md | 75 +++++++ .../gfx/interfaces/GfxElementGeometry.md | 14 ++ .../interfaces/GfxGroupCompatibleInterface.md | 110 +++++++++++ .../gfx/interfaces/PointTestOptions.md | 54 +++++ .../gfx/type-aliases/GfxCommonBlockProps.md | 22 +++ .../gfx/type-aliases/GfxCompatibleProps.md | 11 ++ .../variables/SURFACE_TEXT_UNIQ_IDENTIFIER.md | 11 ++ .../variables/SURFACE_YMAP_UNIQ_IDENTIFIER.md | 11 ++ .../gfx/variables/gfxGroupCompatibleSymbol.md | 11 ++ .../api/@blocksuite/block-std/index/README.md | 28 +++ .../block-std/index/classes/BlockService.md | 19 ++ .../block-std/index/classes/CommandManager.md | 186 ++++++++++++++++++ .../index/classes/LifeCycleWatcher.md | 82 ++++++++ .../block-std/index/classes/RangeBinding.md | 9 + .../block-std/index/classes/RangeManager.md | 121 ++++++++++++ .../index/functions/BlockViewExtension.md | 42 ++++ .../index/functions/ConfigExtensionFactory.md | 45 +++++ .../index/functions/FlavourExtension.md | 31 +++ .../index/functions/KeymapExtension.md | 49 +++++ .../index/functions/WidgetViewExtension.md | 45 +++++ .../variables/RANGE_QUERY_EXCLUDE_ATTR.md | 11 ++ .../variables/RANGE_SYNC_EXCLUDE_ATTR.md | 11 ++ .../docs/api/@blocksuite/store/README.md | 12 ++ .../@blocksuite/store/classes/Extension.md | 133 +++++++++++++ .../store/classes/StoreExtension.md | 47 +++++ blocksuite/docs/api/README.md | 10 + blocksuite/docs/package.json | 21 ++ blocksuite/docs/tsconfig.json | 11 ++ blocksuite/docs/typedoc.json | 26 +++ blocksuite/framework/block-std/typedoc.json | 3 + .../store/src/extension/extension.ts | 7 +- .../store/src/extension/store-extension.ts | 16 ++ .../store/src/test/test-workspace.ts | 1 + blocksuite/framework/store/typedoc.json | 3 + oxlint.json | 3 +- tools/cli/src/run.ts | 1 + tools/utils/src/workspace.gen.ts | 6 + tsconfig.json | 1 + yarn.lock | 53 ++++- 59 files changed, 2101 insertions(+), 9 deletions(-) create mode 100644 blocksuite/docs/README.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/README.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/README.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxBlockElementModel.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxSelectionManager.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/GfxCompatible.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/canSafeAddToContainer.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/compareLayer.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/convert.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/derive.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetween.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetweenV2.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateNKeysBetween.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/getTopElements.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/isGfxGroupCompatibleModel.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/local.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/observe.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/functions/watch.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxCompatibleInterface.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxElementGeometry.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxGroupCompatibleInterface.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/PointTestOptions.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCommonBlockProps.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCompatibleProps.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_TEXT_UNIQ_IDENTIFIER.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_YMAP_UNIQ_IDENTIFIER.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/gfx/variables/gfxGroupCompatibleSymbol.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/README.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/classes/BlockService.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/classes/CommandManager.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/classes/LifeCycleWatcher.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeBinding.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeManager.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/functions/BlockViewExtension.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/functions/ConfigExtensionFactory.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/functions/FlavourExtension.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/functions/KeymapExtension.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/functions/WidgetViewExtension.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_QUERY_EXCLUDE_ATTR.md create mode 100644 blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_SYNC_EXCLUDE_ATTR.md create mode 100644 blocksuite/docs/api/@blocksuite/store/README.md create mode 100644 blocksuite/docs/api/@blocksuite/store/classes/Extension.md create mode 100644 blocksuite/docs/api/@blocksuite/store/classes/StoreExtension.md create mode 100644 blocksuite/docs/api/README.md create mode 100644 blocksuite/docs/package.json create mode 100644 blocksuite/docs/tsconfig.json create mode 100644 blocksuite/docs/typedoc.json create mode 100644 blocksuite/framework/block-std/typedoc.json create mode 100644 blocksuite/framework/store/typedoc.json diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml index 53821ec4fd..73689e07b1 100644 --- a/.github/workflows/build-test.yml +++ b/.github/workflows/build-test.yml @@ -117,6 +117,15 @@ jobs: run: yarn dedupe --check - name: Run Type Check run: yarn typecheck + - name: Run BS Docs Build + run: | + yarn affine bs-docs build + git status --porcelain | grep . && { + echo "Run 'yarn typecheck && yarn affine bs-docs build' and make sure all changes are submitted" + exit 1 + } || { + echo "All changes are submitted" + } lint-rust: name: Lint Rust diff --git a/.prettierignore b/.prettierignore index e5e7a06eda..b0e1d1209e 100644 --- a/.prettierignore +++ b/.prettierignore @@ -35,3 +35,4 @@ packages/frontend/native/index.d.ts packages/frontend/native/index.js packages/frontend/apps/android/App/app/build/** tests/blocksuite/snapshots +blocksuite/docs/api/** diff --git a/blocksuite/docs/README.md b/blocksuite/docs/README.md new file mode 100644 index 0000000000..5dd69e59a5 --- /dev/null +++ b/blocksuite/docs/README.md @@ -0,0 +1,12 @@ +# BlockSuite Docs + +API docs for BlockSuite. + +Generated by [typedoc](https://typedoc.org/). + +## Build Docs + +```bash +yarn typecheck +yarn af bs-docs build +``` diff --git a/blocksuite/docs/api/@blocksuite/block-std/README.md b/blocksuite/docs/api/@blocksuite/block-std/README.md new file mode 100644 index 0000000000..6ce2dfc001 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/README.md @@ -0,0 +1,12 @@ +**@blocksuite/block-std** + +*** + +[BlockSuite API Documentation](../../README.md) / @blocksuite/block-std + +# @blocksuite/block-std + +## Modules + +- [gfx](gfx/README.md) +- [index](index/README.md) diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/README.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/README.md new file mode 100644 index 0000000000..b4b2b3a8e6 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/README.md @@ -0,0 +1,46 @@ +[**@blocksuite/block-std**](../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../README.md) / [@blocksuite/block-std](../README.md) / gfx + +# gfx + +## Classes + +- [GfxBlockElementModel](classes/GfxBlockElementModel.md) +- [GfxSelectionManager](classes/GfxSelectionManager.md) + +## Interfaces + +- [GfxCompatibleInterface](interfaces/GfxCompatibleInterface.md) +- [GfxElementGeometry](interfaces/GfxElementGeometry.md) +- [GfxGroupCompatibleInterface](interfaces/GfxGroupCompatibleInterface.md) +- [PointTestOptions](interfaces/PointTestOptions.md) + +## Type Aliases + +- [GfxCommonBlockProps](type-aliases/GfxCommonBlockProps.md) +- [GfxCompatibleProps](type-aliases/GfxCompatibleProps.md) + +## Variables + +- [gfxGroupCompatibleSymbol](variables/gfxGroupCompatibleSymbol.md) +- [SURFACE\_TEXT\_UNIQ\_IDENTIFIER](variables/SURFACE_TEXT_UNIQ_IDENTIFIER.md) +- [SURFACE\_YMAP\_UNIQ\_IDENTIFIER](variables/SURFACE_YMAP_UNIQ_IDENTIFIER.md) + +## Functions + +- [canSafeAddToContainer](functions/canSafeAddToContainer.md) +- [compareLayer](functions/compareLayer.md) +- [convert](functions/convert.md) +- [derive](functions/derive.md) +- [generateKeyBetween](functions/generateKeyBetween.md) +- [generateKeyBetweenV2](functions/generateKeyBetweenV2.md) +- [generateNKeysBetween](functions/generateNKeysBetween.md) +- [getTopElements](functions/getTopElements.md) +- [GfxCompatible](functions/GfxCompatible.md) +- [isGfxGroupCompatibleModel](functions/isGfxGroupCompatibleModel.md) +- [local](functions/local.md) +- [observe](functions/observe.md) +- [watch](functions/watch.md) diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxBlockElementModel.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxBlockElementModel.md new file mode 100644 index 0000000000..c70ff1c3be --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxBlockElementModel.md @@ -0,0 +1,147 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxBlockElementModel + +# Class: GfxBlockElementModel\ + +The graphic block model that can be rendered in the graphics mode. +All the graphic block model should extend this class. +You can use `GfxCompatibleBlockModel` to convert a BlockModel to a subclass that extends it. + +## Extends + +- `BlockModel`\<`Props`\> + +## Type Parameters + +### Props + +`Props` *extends* [`GfxCompatibleProps`](../type-aliases/GfxCompatibleProps.md) = [`GfxCompatibleProps`](../type-aliases/GfxCompatibleProps.md) + +## Implements + +- [`GfxCompatibleInterface`](../interfaces/GfxCompatibleInterface.md) + +## Properties + +### responseExtension + +> **responseExtension**: \[`number`, `number`\] + +Defines the extension of the response area beyond the element's bounding box. +This tuple specifies the horizontal and vertical margins to be added to the element's [x, y, width, height]. + +The first value represents the horizontal extension (added to both left and right sides), +and the second value represents the vertical extension (added to both top and bottom sides). + +The response area is computed as: +`[x - horizontal, y - vertical, width + 2 * horizontal, height + 2 * vertical]`. + +Example: +- Bounding box: `[0, 0, 100, 100]`, `responseExtension: [10, 20]` + Resulting response area: `[-10, -20, 120, 140]`. +- `responseExtension: [0, 0]` keeps the response area equal to the bounding box. + +#### Implementation of + +[`GfxCompatibleInterface`](../interfaces/GfxCompatibleInterface.md).[`responseExtension`](../interfaces/GfxCompatibleInterface.md#responseextension) + +## Accessors + +### elementBound + +#### Get Signature + +> **get** **elementBound**(): `Bound` + +The bound of the element without considering the response extension. + +##### Returns + +`Bound` + +The bound of the element without considering the response extension. + +#### Implementation of + +[`GfxCompatibleInterface`](../interfaces/GfxCompatibleInterface.md).[`elementBound`](../interfaces/GfxCompatibleInterface.md#elementbound) + +*** + +### lockedBySelf + +#### Get Signature + +> **get** **lockedBySelf**(): `undefined` \| `boolean` + +Indicates whether the current block is explicitly locked by self. +For checking the lock status of the element, use `isLocked` instead. +For (un)locking the element, use `(un)lock` instead. + +##### Returns + +`undefined` \| `boolean` + +#### Set Signature + +> **set** **lockedBySelf**(`lockedBySelf`): `void` + +Indicates whether the current block is explicitly locked by self. +For checking the lock status of the element, use `isLocked` instead. +For (un)locking the element, use `(un)lock` instead. + +##### Parameters + +###### lockedBySelf + +`undefined` | `boolean` + +##### Returns + +`void` + +Indicates whether the current block is explicitly locked by self. +For checking the lock status of the element, use `isLocked` instead. +For (un)locking the element, use `(un)lock` instead. + +#### Implementation of + +[`GfxCompatibleInterface`](../interfaces/GfxCompatibleInterface.md).[`lockedBySelf`](../interfaces/GfxCompatibleInterface.md#lockedbyself) + +*** + +### responseBound + +#### Get Signature + +> **get** **responseBound**(): `Bound` + +The bound of the element considering the response extension. + +##### Returns + +`Bound` + +The bound of the element considering the response extension. + +#### Implementation of + +[`GfxCompatibleInterface`](../interfaces/GfxCompatibleInterface.md).[`responseBound`](../interfaces/GfxCompatibleInterface.md#responsebound) + +## Methods + +### isLocked() + +> **isLocked**(): `boolean` + +Check if the element is locked. It will check the lock status of the element and its ancestors. + +#### Returns + +`boolean` + +#### Implementation of + +[`GfxCompatibleInterface`](../interfaces/GfxCompatibleInterface.md).[`isLocked`](../interfaces/GfxCompatibleInterface.md#islocked) diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxSelectionManager.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxSelectionManager.md new file mode 100644 index 0000000000..2a225a67e0 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/classes/GfxSelectionManager.md @@ -0,0 +1,50 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxSelectionManager + +# Class: GfxSelectionManager + +GfxSelectionManager is just a wrapper of std selection providing +convenient method and states in gfx + +## Extends + +- `GfxExtension` + +## Methods + +### has() + +> **has**(`element`): `boolean` + +check if the element is selected in local + +#### Parameters + +##### element + +`string` + +#### Returns + +`boolean` + +*** + +### hasRemote() + +> **hasRemote**(`element`): `boolean` + +check if element is selected by remote peers + +#### Parameters + +##### element + +`string` + +#### Returns + +`boolean` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/GfxCompatible.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/GfxCompatible.md new file mode 100644 index 0000000000..ec7c5ca731 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/GfxCompatible.md @@ -0,0 +1,35 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxCompatible + +# Function: GfxCompatible() + +> **GfxCompatible**\<`Props`, `T`\>(`BlockModelSuperClass`): *typeof* [`GfxBlockElementModel`](../classes/GfxBlockElementModel.md) + +Convert a BlockModel to a GfxBlockElementModel. + +## Type Parameters + +### Props + +`Props` *extends* [`GfxCompatibleProps`](../type-aliases/GfxCompatibleProps.md) + +### T + +`T` *extends* `Constructor`\<`BlockModel`\<`Props`\>\> = `Constructor`\<`BlockModel`\<`Props`\>\> + +## Parameters + +### BlockModelSuperClass + +`T` + +The BlockModel class to be converted. + +## Returns + +*typeof* [`GfxBlockElementModel`](../classes/GfxBlockElementModel.md) + +The returned class is a subclass of the GfxBlockElementModel class and the given BlockModelSuperClass. diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/canSafeAddToContainer.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/canSafeAddToContainer.md new file mode 100644 index 0000000000..7fd3369932 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/canSafeAddToContainer.md @@ -0,0 +1,25 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / canSafeAddToContainer + +# Function: canSafeAddToContainer() + +> **canSafeAddToContainer**(`container`, `element`): `boolean` + +This checker is used to prevent circular reference, when adding a child element to a container. + +## Parameters + +### container + +`GfxGroupModel` + +### element + +[`GfxCompatibleInterface`](../interfaces/GfxCompatibleInterface.md) + +## Returns + +`boolean` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/compareLayer.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/compareLayer.md new file mode 100644 index 0000000000..36a451ee30 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/compareLayer.md @@ -0,0 +1,26 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / compareLayer + +# Function: compareLayer() + +> **compareLayer**(`a`, `b`): `SortOrder` + +A comparator function for sorting elements in the surface. +SortOrder.AFTER means a should be rendered after b and so on. + +## Parameters + +### a + +`GfxModel` | `GfxLocalElementModel` + +### b + +`GfxModel` | `GfxLocalElementModel` + +## Returns + +`SortOrder` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/convert.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/convert.md new file mode 100644 index 0000000000..f34527f2ed --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/convert.md @@ -0,0 +1,49 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / convert + +# Function: convert() + +> **convert**\<`V`, `T`\>(`fn`): (`_`, `context`) => `ClassAccessorDecoratorResult`\<`T`, `V`\> + +The convert decorator is used to convert the property value before it's +set to the Y map. + +Note: +1. This decorator function will not execute in model initialization. + +## Type Parameters + +### V + +`V` + +### T + +`T` *extends* `GfxPrimitiveElementModel`\<`BaseElementProps`\> + +## Parameters + +### fn + +(`propValue`, `instance`) => `unknown` + +## Returns + +`Function` + +### Parameters + +#### \_ + +`unknown` + +#### context + +`ClassAccessorDecoratorContext` + +### Returns + +`ClassAccessorDecoratorResult`\<`T`, `V`\> diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/derive.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/derive.md new file mode 100644 index 0000000000..280a80398a --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/derive.md @@ -0,0 +1,54 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / derive + +# Function: derive() + +> **derive**\<`V`, `T`\>(`fn`): (`_`, `context`) => `ClassAccessorDecoratorResult`\<`GfxPrimitiveElementModel`\<`BaseElementProps`\>, `V`\> + +The derive decorator is used to derive other properties' update when the +decorated property is updated through assignment in the local. + +Note: +1. The first argument of the function is the new value of the decorated property + before the `convert` decorator is called. +2. The decorator function will execute after the decorated property has been updated. +3. The decorator function will not execute during model creation. +4. The decorator function will not execute if the decorated property is updated through + the Y map. That is to say, if other peers update the property will not trigger this decorator + +## Type Parameters + +### V + +`V` + +### T + +`T` *extends* `GfxPrimitiveElementModel`\<`BaseElementProps`\> + +## Parameters + +### fn + +(`propValue`, `instance`) => `Record`\<`string`, `unknown`\> + +## Returns + +`Function` + +### Parameters + +#### \_ + +`unknown` + +#### context + +`ClassAccessorDecoratorContext` + +### Returns + +`ClassAccessorDecoratorResult`\<`GfxPrimitiveElementModel`\<`BaseElementProps`\>, `V`\> diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetween.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetween.md new file mode 100644 index 0000000000..5fb1e3fbc0 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetween.md @@ -0,0 +1,27 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / generateKeyBetween + +# Function: generateKeyBetween() + +> **generateKeyBetween**(`a`, `b`, `digits`?): `string` + +## Parameters + +### a + +`undefined` | `null` | `string` + +### b + +`undefined` | `null` | `string` + +### digits? + +`string` + +## Returns + +`string` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetweenV2.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetweenV2.md new file mode 100644 index 0000000000..fb04551c6f --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateKeyBetweenV2.md @@ -0,0 +1,28 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / generateKeyBetweenV2 + +# Function: generateKeyBetweenV2() + +> **generateKeyBetweenV2**(`a`, `b`): `string` + +generate a key between a and b, the result key is always satisfied with a < result < b. +the key always has a random suffix, so there is no need to worry about collision. + +make sure a and b are generated by this function. + +## Parameters + +### a + +`null` | `string` + +### b + +`null` | `string` + +## Returns + +`string` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateNKeysBetween.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateNKeysBetween.md new file mode 100644 index 0000000000..86c5b98bc2 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/generateNKeysBetween.md @@ -0,0 +1,39 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / generateNKeysBetween + +# Function: generateNKeysBetween() + +> **generateNKeysBetween**(`a`, `b`, `n`, `digits`?): `string`[] + +same preconditions as generateKeysBetween. +n >= 0. +Returns an array of n distinct keys in sorted order. +If a and b are both null, returns [a0, a1, ...] +If one or the other is null, returns consecutive "integer" +keys. Otherwise, returns relatively short keys between +a and b. + +## Parameters + +### a + +`undefined` | `null` | `string` + +### b + +`undefined` | `null` | `string` + +### n + +`number` + +### digits? + +`string` + +## Returns + +`string`[] diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/getTopElements.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/getTopElements.md new file mode 100644 index 0000000000..74a25ee11e --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/getTopElements.md @@ -0,0 +1,36 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / getTopElements + +# Function: getTopElements() + +> **getTopElements**(`elements`): `GfxModel`[] + +Get the top elements from the list of elements, which are in some tree structures. + +For example: a list `[G1, E1, G2, E2, E3, E4, G4, E5, E6]`, +and they are in the elements tree like: +``` + G1 G4 E6 + / \ | + E1 G2 E5 + / \ + E2 G3* + / \ + E3 E4 +``` +where the star symbol `*` denote it is not in the list. + +The result should be `[G1, G4, E6]` + +## Parameters + +### elements + +`GfxModel`[] + +## Returns + +`GfxModel`[] diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/isGfxGroupCompatibleModel.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/isGfxGroupCompatibleModel.md new file mode 100644 index 0000000000..ad8bd75a71 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/isGfxGroupCompatibleModel.md @@ -0,0 +1,21 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / isGfxGroupCompatibleModel + +# Function: isGfxGroupCompatibleModel() + +> **isGfxGroupCompatibleModel**(`elm`): `elm is GfxGroupModel` + +Check if the element is a container element. + +## Parameters + +### elm + +`unknown` + +## Returns + +`elm is GfxGroupModel` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/local.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/local.md new file mode 100644 index 0000000000..9a108e190c --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/local.md @@ -0,0 +1,42 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / local + +# Function: local() + +> **local**\<`V`, `T`\>(): (`_target`, `context`) => `ClassAccessorDecoratorResult`\<`T`, `V`\> + +A decorator to mark the property as a local property. + +The local property act like it is a field property, but it's not synced to the Y map. +Updating local property will also trigger the `elementUpdated` slot of the surface model + +## Type Parameters + +### V + +`V` + +### T + +`T` *extends* `GfxPrimitiveElementModel`\<`BaseElementProps`\> + +## Returns + +`Function` + +### Parameters + +#### \_target + +`ClassAccessorDecoratorTarget`\<`T`, `V`\> + +#### context + +`ClassAccessorDecoratorContext` + +### Returns + +`ClassAccessorDecoratorResult`\<`T`, `V`\> diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/observe.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/observe.md new file mode 100644 index 0000000000..c668736ac7 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/observe.md @@ -0,0 +1,53 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / observe + +# Function: observe() + +> **observe**\<`V`, `E`, `T`\>(`fn`): (`_`, `context`) => `ClassAccessorDecoratorResult`\<`GfxPrimitiveElementModel`\<`BaseElementProps`\>, `V`\> + +A decorator to observe the y type property. +You can think of it is just a decorator version of 'observe' method of Y.Array and Y.Map. + +The observer function start to observe the property when the model is mounted. And it will +re-observe the property automatically when the value is altered. + +## Type Parameters + +### V + +`V` + +### E + +`E` *extends* `YEvent`\<`any`\> + +### T + +`T` *extends* `GfxPrimitiveElementModel`\<`BaseElementProps`\> + +## Parameters + +### fn + +`ObserveFn`\<`E`, `T`\> + +## Returns + +`Function` + +### Parameters + +#### \_ + +`unknown` + +#### context + +`ClassAccessorDecoratorContext` + +### Returns + +`ClassAccessorDecoratorResult`\<`GfxPrimitiveElementModel`\<`BaseElementProps`\>, `V`\> diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/watch.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/watch.md new file mode 100644 index 0000000000..551740887b --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/functions/watch.md @@ -0,0 +1,46 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / watch + +# Function: watch() + +> **watch**\<`V`, `T`\>(`fn`): (`_`, `context`) => `ClassAccessorDecoratorResult`\<`GfxPrimitiveElementModel`\<`BaseElementProps`\>, `V`\> + +The watch decorator is used to watch the property change of the element. +You can thinks of it as a decorator version of `elementUpdated` slot of the surface model. + +## Type Parameters + +### V + +`V` + +### T + +`T` *extends* `GfxPrimitiveElementModel`\<`BaseElementProps`\> + +## Parameters + +### fn + +`WatchFn`\<`T`\> + +## Returns + +`Function` + +### Parameters + +#### \_ + +`unknown` + +#### context + +`ClassAccessorDecoratorContext` + +### Returns + +`ClassAccessorDecoratorResult`\<`GfxPrimitiveElementModel`\<`BaseElementProps`\>, `V`\> diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxCompatibleInterface.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxCompatibleInterface.md new file mode 100644 index 0000000000..5920b464cf --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxCompatibleInterface.md @@ -0,0 +1,75 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxCompatibleInterface + +# Interface: GfxCompatibleInterface + +All the model that can be rendered in graphics mode should implement this interface. + +## Extends + +- `IBound`.[`GfxElementGeometry`](GfxElementGeometry.md) + +## Extended by + +- [`GfxGroupCompatibleInterface`](GfxGroupCompatibleInterface.md) + +## Properties + +### elementBound + +> `readonly` **elementBound**: `Bound` + +The bound of the element without considering the response extension. + +*** + +### lockedBySelf? + +> `optional` **lockedBySelf**: `boolean` + +Indicates whether the current block is explicitly locked by self. +For checking the lock status of the element, use `isLocked` instead. +For (un)locking the element, use `(un)lock` instead. + +*** + +### responseBound + +> `readonly` **responseBound**: `Bound` + +The bound of the element considering the response extension. + +*** + +### responseExtension + +> **responseExtension**: \[`number`, `number`\] + +Defines the extension of the response area beyond the element's bounding box. +This tuple specifies the horizontal and vertical margins to be added to the element's bound. + +The first value represents the horizontal extension (added to both left and right sides), +and the second value represents the vertical extension (added to both top and bottom sides). + +The response area is computed as: +`[x - horizontal, y - vertical, w + 2 * horizontal, h + 2 * vertical]`. + +Example: +- xywh: `[0, 0, 100, 100]`, `responseExtension: [10, 20]` + Resulting response area: `[-10, -20, 120, 140]`. +- `responseExtension: [0, 0]` keeps the response area equal to the bounding box. + +## Methods + +### isLocked() + +> **isLocked**(): `boolean` + +Check if the element is locked. It will check the lock status of the element and its ancestors. + +#### Returns + +`boolean` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxElementGeometry.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxElementGeometry.md new file mode 100644 index 0000000000..1f5c6dc25e --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxElementGeometry.md @@ -0,0 +1,14 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxElementGeometry + +# Interface: GfxElementGeometry + +The methods that a graphic element should implement. +It is already included in the `GfxCompatibleInterface` interface. + +## Extended by + +- [`GfxCompatibleInterface`](GfxCompatibleInterface.md) diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxGroupCompatibleInterface.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxGroupCompatibleInterface.md new file mode 100644 index 0000000000..87a9fb67fa --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/GfxGroupCompatibleInterface.md @@ -0,0 +1,110 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxGroupCompatibleInterface + +# Interface: GfxGroupCompatibleInterface + +GfxGroupCompatibleElement is a model that can contain other models. +It just like a group that in common graphic software. + +## Extends + +- [`GfxCompatibleInterface`](GfxCompatibleInterface.md) + +## Properties + +### childElements + +> **childElements**: `GfxModel`[] + +All child element models of this container. +Note that the `childElements` may not contains all the children in `childIds`, +because some children may not be loaded. + +*** + +### childIds + +> **childIds**: `string`[] + +All child ids of this container. + +*** + +### elementBound + +> `readonly` **elementBound**: `Bound` + +The bound of the element without considering the response extension. + +#### Inherited from + +[`GfxCompatibleInterface`](GfxCompatibleInterface.md).[`elementBound`](GfxCompatibleInterface.md#elementbound) + +*** + +### lockedBySelf? + +> `optional` **lockedBySelf**: `boolean` + +Indicates whether the current block is explicitly locked by self. +For checking the lock status of the element, use `isLocked` instead. +For (un)locking the element, use `(un)lock` instead. + +#### Inherited from + +[`GfxCompatibleInterface`](GfxCompatibleInterface.md).[`lockedBySelf`](GfxCompatibleInterface.md#lockedbyself) + +*** + +### responseBound + +> `readonly` **responseBound**: `Bound` + +The bound of the element considering the response extension. + +#### Inherited from + +[`GfxCompatibleInterface`](GfxCompatibleInterface.md).[`responseBound`](GfxCompatibleInterface.md#responsebound) + +*** + +### responseExtension + +> **responseExtension**: \[`number`, `number`\] + +Defines the extension of the response area beyond the element's bounding box. +This tuple specifies the horizontal and vertical margins to be added to the element's bound. + +The first value represents the horizontal extension (added to both left and right sides), +and the second value represents the vertical extension (added to both top and bottom sides). + +The response area is computed as: +`[x - horizontal, y - vertical, w + 2 * horizontal, h + 2 * vertical]`. + +Example: +- xywh: `[0, 0, 100, 100]`, `responseExtension: [10, 20]` + Resulting response area: `[-10, -20, 120, 140]`. +- `responseExtension: [0, 0]` keeps the response area equal to the bounding box. + +#### Inherited from + +[`GfxCompatibleInterface`](GfxCompatibleInterface.md).[`responseExtension`](GfxCompatibleInterface.md#responseextension) + +## Methods + +### isLocked() + +> **isLocked**(): `boolean` + +Check if the element is locked. It will check the lock status of the element and its ancestors. + +#### Returns + +`boolean` + +#### Inherited from + +[`GfxCompatibleInterface`](GfxCompatibleInterface.md).[`isLocked`](GfxCompatibleInterface.md#islocked) diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/PointTestOptions.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/PointTestOptions.md new file mode 100644 index 0000000000..8752c1c62f --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/interfaces/PointTestOptions.md @@ -0,0 +1,54 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / PointTestOptions + +# Interface: PointTestOptions + +The options for the hit testing of a point. + +## Properties + +### hitThreshold? + +> `optional` **hitThreshold**: `number` + +The threshold of the hit test. The unit is pixel. + +*** + +### ignoreTransparent? + +> `optional` **ignoreTransparent**: `boolean` + +If true, the transparent area of the element will be ignored during the point inclusion test. +Otherwise, the transparent area will be considered as filled area. + +Default is true. + +*** + +### responsePadding? + +> `optional` **responsePadding**: \[`number`, `number`\] + +The padding of the response area for each element when do the hit testing. The unit is pixel. +The first value is the padding for the x-axis, and the second value is the padding for the y-axis. + +*** + +### useElementBound? + +> `optional` **useElementBound**: `boolean` + +If true, the element bound will be used for the hit testing. +By default, the response bound will be used. + +*** + +### zoom? + +> `optional` **zoom**: `number` + +The zoom level of current view when do the hit testing. diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCommonBlockProps.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCommonBlockProps.md new file mode 100644 index 0000000000..0f38ca3c2d --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCommonBlockProps.md @@ -0,0 +1,22 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxCommonBlockProps + +# Type Alias: GfxCommonBlockProps + +> **GfxCommonBlockProps** = [`GfxCompatibleProps`](GfxCompatibleProps.md) & `object` + +This type include the common props for the graphic block model. +You can use this type with Omit to define the props of a graphic block model. + +## Type declaration + +### rotate + +> **rotate**: `number` + +### scale + +> **scale**: `number` diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCompatibleProps.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCompatibleProps.md new file mode 100644 index 0000000000..524935cddd --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/type-aliases/GfxCompatibleProps.md @@ -0,0 +1,11 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / GfxCompatibleProps + +# Type Alias: GfxCompatibleProps + +> **GfxCompatibleProps** = `object` + +The props that a graphics block model should have. diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_TEXT_UNIQ_IDENTIFIER.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_TEXT_UNIQ_IDENTIFIER.md new file mode 100644 index 0000000000..01285ab4d6 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_TEXT_UNIQ_IDENTIFIER.md @@ -0,0 +1,11 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / SURFACE\_TEXT\_UNIQ\_IDENTIFIER + +# Variable: SURFACE\_TEXT\_UNIQ\_IDENTIFIER + +> `const` **SURFACE\_TEXT\_UNIQ\_IDENTIFIER**: `"affine:surface:text"` = `'affine:surface:text'` + +Used for text field diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_YMAP_UNIQ_IDENTIFIER.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_YMAP_UNIQ_IDENTIFIER.md new file mode 100644 index 0000000000..2674564eef --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/SURFACE_YMAP_UNIQ_IDENTIFIER.md @@ -0,0 +1,11 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / SURFACE\_YMAP\_UNIQ\_IDENTIFIER + +# Variable: SURFACE\_YMAP\_UNIQ\_IDENTIFIER + +> `const` **SURFACE\_YMAP\_UNIQ\_IDENTIFIER**: `"affine:surface:ymap"` = `'affine:surface:ymap'` + +Used for field that use Y.Map. E.g. group children field diff --git a/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/gfxGroupCompatibleSymbol.md b/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/gfxGroupCompatibleSymbol.md new file mode 100644 index 0000000000..fe1c93316f --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/gfx/variables/gfxGroupCompatibleSymbol.md @@ -0,0 +1,11 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [gfx](../README.md) / gfxGroupCompatibleSymbol + +# Variable: gfxGroupCompatibleSymbol + +> `const` **gfxGroupCompatibleSymbol**: *typeof* `gfxGroupCompatibleSymbol` + +The symbol to mark a model as a container. diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/README.md b/blocksuite/docs/api/@blocksuite/block-std/index/README.md new file mode 100644 index 0000000000..6fa0af4fbe --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/README.md @@ -0,0 +1,28 @@ +[**@blocksuite/block-std**](../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../README.md) / [@blocksuite/block-std](../README.md) / index + +# index + +## Classes + +- [~~BlockService~~](classes/BlockService.md) +- [CommandManager](classes/CommandManager.md) +- [LifeCycleWatcher](classes/LifeCycleWatcher.md) +- [RangeBinding](classes/RangeBinding.md) +- [RangeManager](classes/RangeManager.md) + +## Variables + +- [RANGE\_QUERY\_EXCLUDE\_ATTR](variables/RANGE_QUERY_EXCLUDE_ATTR.md) +- [RANGE\_SYNC\_EXCLUDE\_ATTR](variables/RANGE_SYNC_EXCLUDE_ATTR.md) + +## Functions + +- [BlockViewExtension](functions/BlockViewExtension.md) +- [ConfigExtensionFactory](functions/ConfigExtensionFactory.md) +- [FlavourExtension](functions/FlavourExtension.md) +- [KeymapExtension](functions/KeymapExtension.md) +- [WidgetViewExtension](functions/WidgetViewExtension.md) diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/classes/BlockService.md b/blocksuite/docs/api/@blocksuite/block-std/index/classes/BlockService.md new file mode 100644 index 0000000000..9db498a77e --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/classes/BlockService.md @@ -0,0 +1,19 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / BlockService + +# Class: ~~`abstract` BlockService~~ + +## Deprecated + +BlockService is deprecated. You should reconsider where to put your feature. + +BlockService is a legacy extension that is used to provide services to the block. +In the previous version of BlockSuite, block service provides a way to extend the block. +However, in the new version, we recommend using the new extension system. + +## Extends + +- [`Extension`](../../../store/classes/Extension.md) diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/classes/CommandManager.md b/blocksuite/docs/api/@blocksuite/block-std/index/classes/CommandManager.md new file mode 100644 index 0000000000..17dc31dd9e --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/classes/CommandManager.md @@ -0,0 +1,186 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / CommandManager + +# Class: CommandManager + +Command manager to manage all commands + +Commands are functions that take a context and a next function as arguments + +```ts +const myCommand: Command = (ctx, next) => { + const count = ctx.count || 0; + + const success = someOperation(); + if (success) { + return next({ count: count + 1 }); + } + // if the command is not successful, you can return without calling next + return; +``` + +Command input and output data can be defined in the `Command` type + +```ts +// input: ctx.firstName, ctx.lastName +// output: ctx.fullName +const myCommand: Command<{ firstName: string; lastName: string }, { fullName: string }> = (ctx, next) => { + const { firstName, lastName } = ctx; + const fullName = `${firstName} ${lastName}`; + return next({ fullName }); +} + +``` + +--- + +Commands can be run in two ways: + +1. Using `exec` method +`exec` is used to run a single command +```ts +const [result, data] = commandManager.exec(myCommand, payload); +``` + +2. Using `chain` method +`chain` is used to run a series of commands +```ts +const chain = commandManager.chain(); +const [result, data] = chain + .pipe(myCommand1) + .pipe(myCommand2, payload) + .run(); +``` + +--- + +Command chains will stop running if a command is not successful + +```ts +const chain = commandManager.chain(); +const [result, data] = chain + .chain(myCommand1) <-- if this fail + .chain(myCommand2, payload) <- this won't run + .run(); + +result <- result will be `false` +``` + +You can use `try` to run a series of commands and if one of them is successful, it will continue to the next command +```ts +const chain = commandManager.chain(); +const [result, data] = chain + .try(chain => [ + chain.pipe(myCommand1), <- if this fail + chain.pipe(myCommand2, payload), <- this will run, if this success + chain.pipe(myCommand3), <- this won't run + ]) + .run(); +``` + +The `tryAll` method is similar to `try`, but it will run all commands even if one of them is successful +```ts +const chain = commandManager.chain(); +const [result, data] = chain + .try(chain => [ + chain.pipe(myCommand1), <- if this success + chain.pipe(myCommand2), <- this will also run + chain.pipe(myCommand3), <- so will this + ]) + .run(); +``` + +## Extends + +- [`LifeCycleWatcher`](LifeCycleWatcher.md) + +## Methods + +### chain() + +> **chain**(): `Chain`\<`InitCommandCtx`\> + +Create a chain to run a series of commands +```ts +const chain = commandManager.chain(); +const [result, data] = chain + .myCommand1() + .myCommand2(payload) + .run(); +``` + +#### Returns + +`Chain`\<`InitCommandCtx`\> + +[success, data] - success is a boolean to indicate if the chain is successful, + data is the final context after running the chain + +*** + +### created() + +> **created**(): `void` + +Called when std is created. + +#### Returns + +`void` + +#### Inherited from + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`created`](LifeCycleWatcher.md#created) + +*** + +### mounted() + +> **mounted**(): `void` + +Called when editor host is mounted. +Which means the editor host emit the `connectedCallback` lifecycle event. + +#### Returns + +`void` + +#### Inherited from + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`mounted`](LifeCycleWatcher.md#mounted) + +*** + +### rendered() + +> **rendered**(): `void` + +Called when `std.render` is called. + +#### Returns + +`void` + +#### Inherited from + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`rendered`](LifeCycleWatcher.md#rendered) + +*** + +### unmounted() + +> **unmounted**(): `void` + +Called when editor host is unmounted. +Which means the editor host emit the `disconnectedCallback` lifecycle event. + +#### Returns + +`void` + +#### Inherited from + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`unmounted`](LifeCycleWatcher.md#unmounted) diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/classes/LifeCycleWatcher.md b/blocksuite/docs/api/@blocksuite/block-std/index/classes/LifeCycleWatcher.md new file mode 100644 index 0000000000..94e9609670 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/classes/LifeCycleWatcher.md @@ -0,0 +1,82 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / LifeCycleWatcher + +# Class: `abstract` LifeCycleWatcher + +A life cycle watcher is an extension that watches the life cycle of the editor. +It is used to perform actions when the editor is created, mounted, rendered, or unmounted. + +When creating a life cycle watcher, you must define a key that is unique to the watcher. +The key is used to identify the watcher in the dependency injection container. +```ts +class MyLifeCycleWatcher extends LifeCycleWatcher { + static override readonly key = 'my-life-cycle-watcher'; +``` + +In the life cycle watcher, the methods will be called in the following order: +1. `created`: Called when the std is created. +2. `rendered`: Called when `std.render` is called. +3. `mounted`: Called when the editor host is mounted. +4. `unmounted`: Called when the editor host is unmounted. + +## Extends + +- [`Extension`](../../../store/classes/Extension.md) + +## Extended by + +- [`CommandManager`](CommandManager.md) +- [`RangeManager`](RangeManager.md) + +## Methods + +### created() + +> **created**(): `void` + +Called when std is created. + +#### Returns + +`void` + +*** + +### mounted() + +> **mounted**(): `void` + +Called when editor host is mounted. +Which means the editor host emit the `connectedCallback` lifecycle event. + +#### Returns + +`void` + +*** + +### rendered() + +> **rendered**(): `void` + +Called when `std.render` is called. + +#### Returns + +`void` + +*** + +### unmounted() + +> **unmounted**(): `void` + +Called when editor host is unmounted. +Which means the editor host emit the `disconnectedCallback` lifecycle event. + +#### Returns + +`void` diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeBinding.md b/blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeBinding.md new file mode 100644 index 0000000000..2f542da4b3 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeBinding.md @@ -0,0 +1,9 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / RangeBinding + +# Class: RangeBinding + +Two-way binding between native range and text selection diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeManager.md b/blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeManager.md new file mode 100644 index 0000000000..b8deca704e --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/classes/RangeManager.md @@ -0,0 +1,121 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / RangeManager + +# Class: RangeManager + +CRUD for Range and TextSelection + +## Extends + +- [`LifeCycleWatcher`](LifeCycleWatcher.md) + +## Methods + +### created() + +> **created**(): `void` + +Called when std is created. + +#### Returns + +`void` + +#### Inherited from + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`created`](LifeCycleWatcher.md#created) + +*** + +### getSelectedBlockComponentsByRange() + +> **getSelectedBlockComponentsByRange**(`range`, `options`): `BlockComponent`\<`BlockModel`\<`object`\>, [`BlockService`](BlockService.md), `string`\>[] + +#### Parameters + +##### range + +`Range` + +##### options + +###### match? + +(`el`) => `boolean` + +###### mode? + +`"flat"` \| `"all"` \| `"highest"` + +#### Returns + +`BlockComponent`\<`BlockModel`\<`object`\>, [`BlockService`](BlockService.md), `string`\>[] + +#### Example + +```ts +aaa + b[bb + ccc +ddd + ee]e + +all mode: [aaa, bbb, ccc, ddd, eee] +flat mode: [bbb, ccc, ddd, eee] +highest mode: [bbb, ddd] + +match function will be evaluated before filtering using mode +``` + +*** + +### mounted() + +> **mounted**(): `void` + +Called when editor host is mounted. +Which means the editor host emit the `connectedCallback` lifecycle event. + +#### Returns + +`void` + +#### Overrides + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`mounted`](LifeCycleWatcher.md#mounted) + +*** + +### rendered() + +> **rendered**(): `void` + +Called when `std.render` is called. + +#### Returns + +`void` + +#### Inherited from + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`rendered`](LifeCycleWatcher.md#rendered) + +*** + +### unmounted() + +> **unmounted**(): `void` + +Called when editor host is unmounted. +Which means the editor host emit the `disconnectedCallback` lifecycle event. + +#### Returns + +`void` + +#### Inherited from + +[`LifeCycleWatcher`](LifeCycleWatcher.md).[`unmounted`](LifeCycleWatcher.md#unmounted) diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/functions/BlockViewExtension.md b/blocksuite/docs/api/@blocksuite/block-std/index/functions/BlockViewExtension.md new file mode 100644 index 0000000000..2b5c2af8f6 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/functions/BlockViewExtension.md @@ -0,0 +1,42 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / BlockViewExtension + +# Function: BlockViewExtension() + +> **BlockViewExtension**(`flavour`, `view`): `ExtensionType` + +Create a block view extension. + +## Parameters + +### flavour + +`string` + +The flavour of the block that the view is for. + +### view + +`BlockViewType` + +Lit literal template for the view. Example: `my-list-block` + +The view is a lit template that is used to render the block. + +## Returns + +`ExtensionType` + +## Example + +```ts +import { BlockViewExtension } from '@blocksuite/block-std'; + +const MyListBlockViewExtension = BlockViewExtension( + 'affine:list', + literal`my-list-block` +); +``` diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/functions/ConfigExtensionFactory.md b/blocksuite/docs/api/@blocksuite/block-std/index/functions/ConfigExtensionFactory.md new file mode 100644 index 0000000000..65c5e45f7d --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/functions/ConfigExtensionFactory.md @@ -0,0 +1,45 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / ConfigExtensionFactory + +# Function: ConfigExtensionFactory() + +> **ConfigExtensionFactory**\<`Config`\>(`flavor`): (`config`) => `ExtensionType` & `object` + +Create a config extension. +A config extension provides a configuration object for a block flavour. +The configuration object can be used like: +```ts +const config = std.provider.get(ConfigIdentifier('my-flavour')); +``` + +## Type Parameters + +### Config + +`Config` *extends* `Record`\<`string`, `any`\> + +## Parameters + +### flavor + +`string` + +The flavour of the block that the config is for. + +## Returns + +(`config`) => `ExtensionType` & `object` + +## Example + +```ts +import { ConfigExtensionFactory } from '@blocksuite/block-std'; +const MyConfigExtensionFactory = ConfigExtensionFactory('my-flavour'); +const MyConfigExtension = MyConfigExtensionFactory({ + option1: 'value1', + option2: 'value2', +}); +``` diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/functions/FlavourExtension.md b/blocksuite/docs/api/@blocksuite/block-std/index/functions/FlavourExtension.md new file mode 100644 index 0000000000..ed6a39e6eb --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/functions/FlavourExtension.md @@ -0,0 +1,31 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / FlavourExtension + +# Function: FlavourExtension() + +> **FlavourExtension**(`flavour`): `ExtensionType` + +Create a flavour extension. + +## Parameters + +### flavour + +`string` + +The flavour of the block that the extension is for. + +## Returns + +`ExtensionType` + +## Example + +```ts +import { FlavourExtension } from '@blocksuite/block-std'; + +const MyFlavourExtension = FlavourExtension('my-flavour'); +``` diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/functions/KeymapExtension.md b/blocksuite/docs/api/@blocksuite/block-std/index/functions/KeymapExtension.md new file mode 100644 index 0000000000..c30e9e958e --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/functions/KeymapExtension.md @@ -0,0 +1,49 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / KeymapExtension + +# Function: KeymapExtension() + +> **KeymapExtension**(`keymapFactory`, `options`?): `ExtensionType` + +Create a keymap extension. + +## Parameters + +### keymapFactory + +(`std`) => `Record`\<`string`, `UIEventHandler`\> + +Create keymap of the extension. +It should return an object with `keymap` and `options`. + +`keymap` is a record of keymap. + +### options? + +`EventOptions` + +`options` is an optional object that restricts the event to be handled. + +## Returns + +`ExtensionType` + +## Example + +```ts +import { KeymapExtension } from '@blocksuite/block-std'; + +const MyKeymapExtension = KeymapExtension(std => { + return { + keymap: { + 'mod-a': SelectAll + } + options: { + flavour: 'affine:paragraph' + } + } +}); +``` diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/functions/WidgetViewExtension.md b/blocksuite/docs/api/@blocksuite/block-std/index/functions/WidgetViewExtension.md new file mode 100644 index 0000000000..350816ff8c --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/functions/WidgetViewExtension.md @@ -0,0 +1,45 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / WidgetViewExtension + +# Function: WidgetViewExtension() + +> **WidgetViewExtension**(`flavour`, `id`, `view`): `ExtensionType` + +Create a widget view extension. + +## Parameters + +### flavour + +`string` + +The flavour of the block that the widget view is for. + +### id + +`string` + +The id of the widget view. + +### view + +`StaticValue` + +The widget view lit literal. + +A widget view is to provide a widget view for a block. +For every target block, it's view will be rendered with the widget view. + +## Returns + +`ExtensionType` + +## Example + +```ts +import { WidgetViewExtension } from '@blocksuite/block-std'; + +const MyWidgetViewExtension = WidgetViewExtension('my-flavour', 'my-widget', literal`my-widget-view`); diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_QUERY_EXCLUDE_ATTR.md b/blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_QUERY_EXCLUDE_ATTR.md new file mode 100644 index 0000000000..9e8576ea1b --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_QUERY_EXCLUDE_ATTR.md @@ -0,0 +1,11 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / RANGE\_QUERY\_EXCLUDE\_ATTR + +# Variable: RANGE\_QUERY\_EXCLUDE\_ATTR + +> `const` **RANGE\_QUERY\_EXCLUDE\_ATTR**: `"data-range-query-exclude"` = `'data-range-query-exclude'` + +Used to exclude certain elements when using `getSelectedBlockComponentsByRange`. diff --git a/blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_SYNC_EXCLUDE_ATTR.md b/blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_SYNC_EXCLUDE_ATTR.md new file mode 100644 index 0000000000..d6babf5a22 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/block-std/index/variables/RANGE_SYNC_EXCLUDE_ATTR.md @@ -0,0 +1,11 @@ +[**@blocksuite/block-std**](../../../../@blocksuite/block-std/README.md) + +*** + +[BlockSuite API Documentation](../../../../README.md) / [@blocksuite/block-std](../../README.md) / [index](../README.md) / RANGE\_SYNC\_EXCLUDE\_ATTR + +# Variable: RANGE\_SYNC\_EXCLUDE\_ATTR + +> `const` **RANGE\_SYNC\_EXCLUDE\_ATTR**: `"data-range-sync-exclude"` = `'data-range-sync-exclude'` + +Used to mark certain elements so that they are excluded when synchronizing the native range and text selection (such as database block). diff --git a/blocksuite/docs/api/@blocksuite/store/README.md b/blocksuite/docs/api/@blocksuite/store/README.md new file mode 100644 index 0000000000..af37499c34 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/store/README.md @@ -0,0 +1,12 @@ +**@blocksuite/store** + +*** + +[BlockSuite API Documentation](../../README.md) / @blocksuite/store + +# @blocksuite/store + +## Extension + +- [Extension](classes/Extension.md) +- [StoreExtension](classes/StoreExtension.md) diff --git a/blocksuite/docs/api/@blocksuite/store/classes/Extension.md b/blocksuite/docs/api/@blocksuite/store/classes/Extension.md new file mode 100644 index 0000000000..df60fbdfe0 --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/store/classes/Extension.md @@ -0,0 +1,133 @@ +[**@blocksuite/store**](../../../@blocksuite/store/README.md) + +*** + +[BlockSuite API Documentation](../../../README.md) / [@blocksuite/store](../README.md) / Extension + +# Class: `abstract` Extension + +# Understanding Extensions + +Extensions provide a way to extend the functionality of a system using dependency injection. +They allow you to register services, implementations, and factories in the DI container, +which can then be retrieved and used by different parts of the application. + +Extensions are particularly useful for: +- Registering different implementations for different types +- Creating pluggable architecture where components can be added or removed +- Managing dependencies between different parts of the application + +# Usage Example: Fruit Processing System + +Let's consider a fruit processing system where different types of fruits need +different processing methods. We'll show how to implement this using extensions. + +## Step 1: Define the interfaces + +```ts +interface FruitProcessor { + process(fruit: Fruit): void; +} + +interface Fruit { + type: string; + // other properties +} +``` + +## Step 2: Create a service identifier + +```ts +import { createIdentifier } from '@blocksuite/global/di'; + +const FruitProcessorProvider = createIdentifier('fruit-processor-provider'); +``` + +## Step 3: Create implementations + +```ts +class AppleProcessor implements FruitProcessor { + process(fruit: Fruit): void { + console.log('Slicing apple'); + // Apple-specific processing + } +} + +class BananaProcessor implements FruitProcessor { + process(fruit: Fruit): void { + console.log('Peeling banana'); + // Banana-specific processing + } +} +``` + +## Step 4: Create an extension factory + +```ts +const FruitProcessorExtension = ( + fruitType: string, + implementation: new () => FruitProcessor +): ExtensionType => { + return { + setup: di => { + di.addImpl(FruitProcessorProvider(fruitType), implementation); + } + }; +}; +``` + +## Step 5: Create concrete extensions + +```ts +export const AppleProcessorExtension = FruitProcessorExtension('apple', AppleProcessor); +export const BananaProcessorExtension = FruitProcessorExtension('banana', BananaProcessor); +``` + +## Step 6: Use the extensions + +```ts +import { Container } from '@blocksuite/global/di'; + +class FruitProcessingSystem { + provider: ServiceProvider; + + constructor(extensions: ExtensionType[]) { + const container = new Container(); + + // Set up all extensions + extensions.forEach(ext => ext.setup(container)); + + // Create a provider from the container + this.provider = container.provider(); + } + + processFruit(fruit: Fruit) { + // Get the appropriate processor based on fruit type + const processor = this.provider.get(FruitProcessorProvider(fruit.type)); + + // Process the fruit + processor.process(fruit); + } +} + +// Initialize the system with extensions +const system = new FruitProcessingSystem([ + AppleProcessorExtension, + BananaProcessorExtension +]); + +// Use the system +system.processFruit({ type: 'apple' }); // Output: Slicing apple +system.processFruit({ type: 'banana' }); // Output: Peeling banana +``` + +Note: We deliberately used a non-block specific example here. In BlockSuite, the extension +pattern can be applied to any entity that can be configured by third parties, not just blocks. +This includes different tools in the whiteboard, different column types in database blocks, +and many other extensible components. The pattern remains the same regardless of what you're extending. + +## Extended by + +- [`StoreExtension`](StoreExtension.md) +- [`BlockService`](../../block-std/index/classes/BlockService.md) +- [`LifeCycleWatcher`](../../block-std/index/classes/LifeCycleWatcher.md) diff --git a/blocksuite/docs/api/@blocksuite/store/classes/StoreExtension.md b/blocksuite/docs/api/@blocksuite/store/classes/StoreExtension.md new file mode 100644 index 0000000000..8e2d3c76fc --- /dev/null +++ b/blocksuite/docs/api/@blocksuite/store/classes/StoreExtension.md @@ -0,0 +1,47 @@ +[**@blocksuite/store**](../../../@blocksuite/store/README.md) + +*** + +[BlockSuite API Documentation](../../../README.md) / [@blocksuite/store](../README.md) / StoreExtension + +# Class: StoreExtension + +Store extensions are used to extend the store. +They should be registered to the store. And they should be able to run in a none-dom environment. + +## Extends + +- [`Extension`](Extension.md) + +## Properties + +### key + +> `readonly` `static` **key**: `string` + +The key of the store extension. +**You must override this property with a unique string.** + +## Methods + +### disposed() + +> **disposed**(): `void` + +Lifecycle hook when the yjs document is disposed. + +#### Returns + +`void` + +*** + +### loaded() + +> **loaded**(): `void` + +Lifecycle hook when the yjs document is loaded. + +#### Returns + +`void` diff --git a/blocksuite/docs/api/README.md b/blocksuite/docs/api/README.md new file mode 100644 index 0000000000..6a61e0a1fa --- /dev/null +++ b/blocksuite/docs/api/README.md @@ -0,0 +1,10 @@ +**BlockSuite API Documentation** + +*** + +# BlockSuite API Documentation + +## Packages + +- [@blocksuite/store](@blocksuite/store/README.md) +- [@blocksuite/block-std](@blocksuite/block-std/README.md) diff --git a/blocksuite/docs/package.json b/blocksuite/docs/package.json new file mode 100644 index 0000000000..f72142bb94 --- /dev/null +++ b/blocksuite/docs/package.json @@ -0,0 +1,21 @@ +{ + "name": "@blocksuite/bs-docs", + "description": "BlockSuite documentation", + "private": true, + "keywords": [], + "author": "toeverything", + "repository": "toeverything/blocksuite", + "license": "MPL-2.0", + "type": "module", + "devDependencies": { + "typedoc": "^0.28.0", + "typedoc-plugin-markdown": "^4.5.0" + }, + "scripts": { + "build": "typedoc" + }, + "dependencies": { + "@blocksuite/affine": "workspace:*" + }, + "version": "0.20.0" +} diff --git a/blocksuite/docs/tsconfig.json b/blocksuite/docs/tsconfig.json new file mode 100644 index 0000000000..3bcce54b19 --- /dev/null +++ b/blocksuite/docs/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../tsconfig.json", + "compilerOptions": { + "target": "ES2024", + "rootDir": ".", + "outDir": "./dist", + "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo" + }, + "include": ["./.vitepress"], + "references": [{ "path": "../affine/all" }] +} diff --git a/blocksuite/docs/typedoc.json b/blocksuite/docs/typedoc.json new file mode 100644 index 0000000000..0e19e105b9 --- /dev/null +++ b/blocksuite/docs/typedoc.json @@ -0,0 +1,26 @@ +{ + "entryPoints": ["../framework/store", "../framework/block-std"], + "packageOptions": { + "readme": "none", + "categorizeByGroup": false, + "includeVersion": false, + "excludeNotDocumented": true, + "excludeInternal": true, + "excludePrivate": true, + "excludeProtected": true, + "excludeExternals": true, + "externalPattern": ["node_modules/**/*"], + "disableSources": true + }, + "readme": "none", + "plugin": ["typedoc-plugin-markdown"], + "out": "./api", + "entryPointStrategy": "packages", + "includeVersion": false, + "logLevel": "Error", + "name": "BlockSuite API Documentation", + "navigation": { + "includeCategories": true + }, + "sort": ["source-order"] +} diff --git a/blocksuite/framework/block-std/typedoc.json b/blocksuite/framework/block-std/typedoc.json new file mode 100644 index 0000000000..4096e97f01 --- /dev/null +++ b/blocksuite/framework/block-std/typedoc.json @@ -0,0 +1,3 @@ +{ + "entryPoints": ["src/index.ts", "src/gfx/index.ts", "src/effects.ts"] +} diff --git a/blocksuite/framework/store/src/extension/extension.ts b/blocksuite/framework/store/src/extension/extension.ts index 6357d993b2..2762c82c67 100644 --- a/blocksuite/framework/store/src/extension/extension.ts +++ b/blocksuite/framework/store/src/extension/extension.ts @@ -1,11 +1,6 @@ import type { Container } from '@blocksuite/global/di'; /** - * Generic extension. - * Extensions are used to set up the dependency injection container. - * In most cases, you won't need to use this class directly. - * We provide helper classes like `CommandExtension` and `BlockViewExtension` to make it easier to create extensions. - * * # Understanding Extensions * * Extensions provide a way to extend the functionality of a system using dependency injection. @@ -125,6 +120,8 @@ import type { Container } from '@blocksuite/global/di'; * pattern can be applied to any entity that can be configured by third parties, not just blocks. * This includes different tools in the whiteboard, different column types in database blocks, * and many other extensible components. The pattern remains the same regardless of what you're extending. + * + * @category Extension */ export abstract class Extension { static setup(_di: Container): void { diff --git a/blocksuite/framework/store/src/extension/store-extension.ts b/blocksuite/framework/store/src/extension/store-extension.ts index 77b4676576..46eba36dab 100644 --- a/blocksuite/framework/store/src/extension/store-extension.ts +++ b/blocksuite/framework/store/src/extension/store-extension.ts @@ -10,15 +10,31 @@ export const StoreExtensionIdentifier = export const storeExtensionSymbol = Symbol('StoreExtension'); +/** + * Store extensions are used to extend the store. + * They should be registered to the store. And they should be able to run in a none-dom environment. + * + * @category Extension + */ export class StoreExtension extends Extension { + /** + * The key of the store extension. + * **You must override this property with a unique string.** + */ static readonly key: string; constructor(readonly store: Store) { super(); } + /** + * Lifecycle hook when the yjs document is loaded. + */ loaded() {} + /** + * Lifecycle hook when the yjs document is disposed. + */ disposed() {} static readonly [storeExtensionSymbol] = true; diff --git a/blocksuite/framework/store/src/test/test-workspace.ts b/blocksuite/framework/store/src/test/test-workspace.ts index 82b25c7923..f9f7e06965 100644 --- a/blocksuite/framework/store/src/test/test-workspace.ts +++ b/blocksuite/framework/store/src/test/test-workspace.ts @@ -42,6 +42,7 @@ export type DocCollectionOptions = { }; /** + * @internal * Test only * Do not use this in production */ diff --git a/blocksuite/framework/store/typedoc.json b/blocksuite/framework/store/typedoc.json new file mode 100644 index 0000000000..35fed2c958 --- /dev/null +++ b/blocksuite/framework/store/typedoc.json @@ -0,0 +1,3 @@ +{ + "entryPoints": ["src/index.ts"] +} diff --git a/oxlint.json b/oxlint.json index dca3ccb7ae..cdee1d161b 100644 --- a/oxlint.json +++ b/oxlint.json @@ -35,7 +35,8 @@ "packages/frontend/native/index.d.ts", "packages/frontend/native/index.js", "packages/frontend/apps/android/App/app/build/**", - "tests/blocksuite/snapshots" + "tests/blocksuite/snapshots", + "blocksuite/docs/api/**" ], "rules": { "import/named": "error", diff --git a/tools/cli/src/run.ts b/tools/cli/src/run.ts index 720dfaff7d..cab5bd1b84 100644 --- a/tools/cli/src/run.ts +++ b/tools/cli/src/run.ts @@ -19,6 +19,7 @@ const ignoreLoaderScripts = [ 'prisma', 'cap', 'tsc', + 'typedoc', /^r$/, /electron(?!-)/, ]; diff --git a/tools/utils/src/workspace.gen.ts b/tools/utils/src/workspace.gen.ts index a7c7b93216..443d9eeb74 100644 --- a/tools/utils/src/workspace.gen.ts +++ b/tools/utils/src/workspace.gen.ts @@ -583,6 +583,11 @@ export const PackageList = [ 'blocksuite/framework/global', ], }, + { + location: 'blocksuite/docs', + name: '@blocksuite/bs-docs', + workspaceDependencies: ['blocksuite/affine/all'], + }, { location: 'blocksuite/framework/block-std', name: '@blocksuite/block-std', @@ -966,6 +971,7 @@ export type PackageName = | '@blocksuite/affine-widget-scroll-anchoring' | '@blocksuite/affine-widget-slash-menu' | '@blocksuite/affine-widget-toolbar' + | '@blocksuite/bs-docs' | '@blocksuite/block-std' | '@blocksuite/global' | '@blocksuite/inline' diff --git a/tsconfig.json b/tsconfig.json index a99782ade6..c7816b55c0 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -87,6 +87,7 @@ { "path": "./blocksuite/affine/widgets/widget-scroll-anchoring" }, { "path": "./blocksuite/affine/widgets/widget-slash-menu" }, { "path": "./blocksuite/affine/widgets/widget-toolbar" }, + { "path": "./blocksuite/docs" }, { "path": "./blocksuite/framework/block-std" }, { "path": "./blocksuite/framework/global" }, { "path": "./blocksuite/framework/inline" }, diff --git a/yarn.lock b/yarn.lock index 3252fa336b..4ae42262d5 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3256,6 +3256,16 @@ __metadata: languageName: unknown linkType: soft +"@blocksuite/bs-docs@workspace:blocksuite/docs": + version: 0.0.0-use.local + resolution: "@blocksuite/bs-docs@workspace:blocksuite/docs" + dependencies: + "@blocksuite/affine": "workspace:*" + typedoc: "npm:^0.28.0" + typedoc-plugin-markdown: "npm:^4.5.0" + languageName: unknown + linkType: soft + "@blocksuite/data-view@workspace:*, @blocksuite/data-view@workspace:blocksuite/affine/data-view": version: 0.0.0-use.local resolution: "@blocksuite/data-view@workspace:blocksuite/affine/data-view" @@ -5192,6 +5202,17 @@ __metadata: languageName: node linkType: hard +"@gerrit0/mini-shiki@npm:^3.2.1": + version: 3.2.1 + resolution: "@gerrit0/mini-shiki@npm:3.2.1" + dependencies: + "@shikijs/engine-oniguruma": "npm:^3.2.1" + "@shikijs/types": "npm:^3.2.1" + "@shikijs/vscode-textmate": "npm:^10.0.2" + checksum: 10/7f366cf09b682e1aeef0ebeb32e548f209b4c0b8695efde65e07451634677baf790942ba78ae78a8eca20d8b92ce8251411d0ebc5319a8d9d01c28d9d1368140 + languageName: node + linkType: hard + "@golevelup/nestjs-discovery@npm:4.0.3": version: 4.0.3 resolution: "@golevelup/nestjs-discovery@npm:4.0.3" @@ -12055,7 +12076,7 @@ __metadata: languageName: node linkType: hard -"@shikijs/engine-oniguruma@npm:3.2.1": +"@shikijs/engine-oniguruma@npm:3.2.1, @shikijs/engine-oniguruma@npm:^3.2.1": version: 3.2.1 resolution: "@shikijs/engine-oniguruma@npm:3.2.1" dependencies: @@ -12103,7 +12124,7 @@ __metadata: languageName: node linkType: hard -"@shikijs/types@npm:3.2.1": +"@shikijs/types@npm:3.2.1, @shikijs/types@npm:^3.2.1": version: 3.2.1 resolution: "@shikijs/types@npm:3.2.1" dependencies: @@ -32342,6 +32363,15 @@ __metadata: languageName: node linkType: hard +"typedoc-plugin-markdown@npm:^4.5.0": + version: 4.5.0 + resolution: "typedoc-plugin-markdown@npm:4.5.0" + peerDependencies: + typedoc: 0.28.x + checksum: 10/292bd854c2eeaf1321d5df3b50e4d47f80e5ad8a0ec53c8485a1e22b5d8c3130642c6214699a3f2fde3886de4ff2574456012caf132ca0480fdec5961c7835f2 + languageName: node + linkType: hard + "typedoc@npm:^0.27.4": version: 0.27.9 resolution: "typedoc@npm:0.27.9" @@ -32359,6 +32389,23 @@ __metadata: languageName: node linkType: hard +"typedoc@npm:^0.28.0": + version: 0.28.0 + resolution: "typedoc@npm:0.28.0" + dependencies: + "@gerrit0/mini-shiki": "npm:^3.2.1" + lunr: "npm:^2.3.9" + markdown-it: "npm:^14.1.0" + minimatch: "npm:^9.0.5" + yaml: "npm:^2.7.0 " + peerDependencies: + typescript: 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x + bin: + typedoc: bin/typedoc + checksum: 10/41f5f871d314c5a9166e3e449ec01c916d3516c5fcb198304bfeb2bbcab8139f9f090c41035c52556a4b549f55e39822f345e0472641cea24c04b344f6dd34fa + languageName: node + linkType: hard + "typescript-eslint@npm:^8.18.0": version: 8.26.1 resolution: "typescript-eslint@npm:8.26.1" @@ -33808,7 +33855,7 @@ __metadata: languageName: node linkType: hard -"yaml@npm:^2.3.1, yaml@npm:^2.5.1, yaml@npm:^2.6.1, yaml@npm:^2.7.0": +"yaml@npm:^2.3.1, yaml@npm:^2.5.1, yaml@npm:^2.6.1, yaml@npm:^2.7.0, yaml@npm:^2.7.0 ": version: 2.7.0 resolution: "yaml@npm:2.7.0" bin: