refactor: migrating legacy tools

[doouding]

Continue #8438

There're some depended modules that need to be refactor also during migration. I'll list them here.

GfxExtension

Used to extend the GfxController. The GfxExtension can perform tasks during the life cycle of GfxController.

import { GfxExtension } from '@blocksuite/std/gfx';

export class ExampleExtension extends GfxExtension {
  // the key is required
  static override key = 'example';

  // you can access this.gfx inside the class context

  mounted() {
    // called when gfx has mounted
  }

  unmounted() {
    // called when gfx has unmounted
  }
}

// edgeless-spec.ts
export const edgelessSpec = [
  // append it on the spec list
  ExampleExtension
]

KeyboardController

KeyboardController provide the pressing status of common key such as shift, space. So that you don't have to maintain thoese status everywhere. Now you can access it through gfx.keyboard.

EdgelessSelectionManager

The legacy EdgelessSelectionManager has move to block-std/gfx and become a first-party supported module. Now you can access it through gfx.selection.

OverlayExtension

The legacy overlay has to be instantiated and added manually, which is a bit of a hassle. The newly refactored overlay utilizes the new Extension infra to automatically instantiate and add itself to the overlay renderer.

import { Overlay } from './renderer/overlay.js';
 
export class ExampleOverlay extends Overlay {
  static override overlayName = 'example';

  // the methods remain the same
}

// edgeless-spec.ts
import { ExampleOverlay } from './example-overlay.js'

export const edgelessSpec = [
  // append it on the spec list
 ExampleOverlay
]

When you need to get the instance of that overlay, just use the std.get(OverlayIdentifier(theOverlayName).

import { OverlayIdentifier } from './renderer/overlay.js';

const exampleOverlayInst = std.get(OverlayIdentifier('example');

Note that you don’t have to use the OverlayExtension if you only need a local overlay. You can still create and add it to the renderer manually.

SurfaceMiddlewareExtesion

The new surface middleware is aimed to extend the functionality of addElement, deleteElement and updateElement. It's a pure local infra which is helpful when you need to do something when the previously mentioned methods are called.

You can load the middleware manually using surfaceModel.applyMiddlewares method. But we provide a more common way to extend the middleware using the Extension infra.

import { type SurfaceMiddlewareBuilder } from '@blocksuite/block-std/gfx';

export const ExampleMiddlewareBuilder: SurfaceMiddlewareBuilder = (std: BlockStdScope) => {
  /**
   * you can access std here
   * the builder must return a middleware function which will be apply to surface model
   **/
  return (ctx: MiddlewareCtx) => {
    // this middleware function will be executed every time when the surface methods get called.
  } 
}


// edgeless-spec.ts
import { SurfaceMiddlewareExtension } from '@blocksuite/block-std/gfx';
import { ExampleMiddlewareBuilder } from './middlewares.js'

export const edgelessSpec = [
  // ...
  // the surface builder should be wrapped in the `SurfaceMiddlewareExtension` function to get injected
  SurfaceMiddlewareExtension([ExampleMiddlewareBuilder])
]

Review guide

This PR is a bit huge, but most of changes are just migration from legacy implementation. Here the list that worth attention.

• Every change under block-std package
• New extendable overlay under block-surface/src/renderer/overlay.ts

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
blocksuite	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 22, 2024 7:24am

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
blocksuite-docs	⬜️ Ignored (Inspect)	Visit Preview		Oct 22, 2024 7:24am

[changeset-bot]

⚠️ No Changeset found

Latest commit: 65fbde6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[graphite-app]

Your org has enabled the Graphite merge queue for merging into master

Add the label “merge” to the PR and Graphite will automatically add it to the merge queue when it’s ready to merge.

You must have a Graphite account and log in to Graphite in order to use the merge queue. Sign up using this link.

[doouding]

• refactor: migrating legacy tools #8471 : 2 dependent PRs (#8536 , #8563 ) 👈
• refactor: edgeless tool manager #8438
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

Join @doouding and the rest of your teammates on Graphite

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 65fbde6. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx vite:build @blocksuite/playground

---

Sent with 💌 from NxCloud.

[doouding]

Merge activity

• Oct 21, 11:25 PM EDT: Graphite disabled "merge when ready" on this PR due to: a merge conflict with the target branch; resolve the conflict and try again..
• Oct 22, 3:23 AM EDT: A user added this pull request to the Graphite merge queue.
• Oct 22, 3:28 AM EDT: A user merged this pull request with the Graphite merge queue.

[github-actions]

size-limit report 📦

Path	Size
@blocksuite/affine	13 B (0%)
@blocksuite/affine/effects	2.06 MB (-0.01% 🔽)
@blocksuite/affine/block-std	156.97 KB (+1.06% 🔺)
@blocksuite/affine/block-std/gfx	80.1 KB (+2.56% 🔺)
@blocksuite/affine/global	13 B (0%)
@blocksuite/affine/global/utils	13.83 KB (+0.06% 🔺)
@blocksuite/affine/global/env	210 B (0%)
@blocksuite/affine/global/exceptions	552 B (0%)
@blocksuite/affine/global/di	1.65 KB (0%)
@blocksuite/affine/global/types	13 B (0%)
@blocksuite/affine/store	78.54 KB (0%)
@blocksuite/affine/inline	32.03 KB (0%)
@blocksuite/affine/inline/consts	51 B (0%)
@blocksuite/affine/inline/types	13 B (0%)
@blocksuite/affine/presets	1.86 MB (-0.06% 🔽)
@blocksuite/affine/blocks	1.95 MB (-0.05% 🔽)
@blocksuite/affine/blocks/schemas	88.72 KB (+1.06% 🔺)