{"bugs":{"url":"https://github.com/toeverything/blocksuite/issues"},"dist":{"shasum":"88b0c94d700aa20d23ad2f224b89a32026fbab3a","tarball":"https://registry.npmjs.org/@blocksuite/virgo/-/virgo-0.0.0-20231206051647-ab555738-nightly.tgz","fileCount":178,"integrity":"sha512-RWjmY2XwSm3tQDBsOSdermuCMhR8InxapllTrmdiagyt4XRtBPQbZa84YzhRJH6Qo0hiu72pP3/0hHJPpnj/BA==","signatures":[{"sig":"MEUCIDAJI7xxjodXwJutETuELUE8Cq2l3j6tYpCvca3tPFtDAiEAu3jOgtm6r79z5sXYtRcoPSHUZnj7DI0f8hnz08yysQ8=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@blocksuite%2fvirgo@0.0.0-20231206051647-ab555738-nightly","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":533367},"main":"dist/index.js","name":"@blocksuite/virgo","type":"module","_from":"file:blocksuite-virgo-0.0.0-20231206051647-ab555738-nightly.tgz","types":"dist/index.d.ts","author":{"name":"toeverything"},"readme":"# `@blocksuite/virgo`\n\n## Introduction\n\nVirgo is a streamlined rich-text editing core that seamlessly synchronizes the state between DOM and [Y.Text](https://docs.yjs.dev/api/shared-types/y.text). What sets it apart from other rich-text editing frameworks is its natively CRDT data model. For comparison, if you want collaborative editing in Slate.js, you'd typically use a plugin like slate-yjs, which acts as a bridge between [Yjs](https://github.com/yjs/yjs) and Slate.js. Within these plugins, all text operations must be translated between Yjs and Slate.js operations, potentially complicating undo/redo functionalities and code maintenance. With Virgo, the synchronization between Yjs and DOM is direct. This means Yjs's state is the singular source of truth, allowing for direct manipulation of the DOM state via the `Y.Text` API, which considerably reduces the editor's complexity.\n\nIn BlockSuite, we initially employed Quill for in-block rich-text editing, leveraging only a limited subset of its APIs. Each paragraph in BlockSuite was managed by an individual Quill instance, linked to a `Y.Text` instance for collaborative purposes. Virgo further simplifies this, performing the same function as our usage of the Quill subset. It essentially offers a straightforward rich-text synchronization process, with block-tree-level state management being taken care of by BlockSuite's data store.\n\nThe Virgo editor's state is compatible with `Y.Text`, simplifying the conversion between them. Virgo uses the Delta format, similar to Yjs, allowing Yjs to manage all text states, including formatting.\n\n## Usage\n\nTo use Virgo in your project, all you need to do is to create a `Y.Text` instance from `Y.Doc`, bind it to the virgo editor, then mount it to the DOM:\n\n```ts\nconst doc = new Y.Doc();\nconst yText = doc.getText('text');\nconst vEditor = new VEditor(yText);\n\nconst editorContainer = document.getElementById('editor');\nvEditor.mount(editorContainer);\n```\n\nYou can go to [virgo playground](https://try-blocksuite.vercel.app/examples/virgo/)\nfor online testing and check out the code in its [repository](https://github.com/toeverything/blocksuite/tree/master/packages/playground/examples/virgo).\n\n### Attributes\n\nAttributes is a property of a delta structure, which is used to store formatting information.\nA delta expressing a bold text node would look like this:\n\n```json\n{\n  \"insert\": \"Hello World\",\n  \"attributes\": {\n    \"bold\": true\n  }\n}\n```\n\nVirgo use zod to validate attributes, you can use `setAttributesSchema` to set the schema:\n\n```ts\n// you don't have to extend baseTextAttributes\nconst customSchema = baseTextAttributes.extend({\n  reference: z\n    .object({\n      type: type: z.enum([\n        // @deprecated Subpage is deprecated, use LinkedPage instead\n        'Subpage',\n        'LinkedPage',\n      ]),\n      pageId: z.string(),\n    })\n    .optional()\n    .nullable()\n    .catch(undefined),\n  background: z.string().optional().nullable().catch(undefined),\n  color: z.string().optional().nullable().catch(undefined),\n});\n\nconst doc = new Y.Doc();\nconst yText = doc.getText('text');\nconst vEditor = new VEditor(yText);\nvEditor.setAttributesSchema(customSchema);\n\nconst editorContainer = document.getElementById('editor');\nvEditor.mount(editorContainer);\n```\n\nVirgo has default attributes schema, so you can skip this step if you think it is enough.\n\n```ts\n// default attributes schema\nconst baseTextAttributes = z.object({\n  bold: z.literal(true).optional().nullable().catch(undefined),\n  italic: z.literal(true).optional().nullable().catch(undefined),\n  underline: z.literal(true).optional().nullable().catch(undefined),\n  strike: z.literal(true).optional().nullable().catch(undefined),\n  code: z.literal(true).optional().nullable().catch(undefined),\n  link: z.string().optional().nullable().catch(undefined),\n});\n```\n\n### Attributes Renderer\n\nAttributes Renderer is a function that takes a delta and returns `TemplateResult<1>`, which is a valid [lit-html](https://github.com/lit/lit/tree/main/packages/lit-html) template result.\nVirgo use this function to render text with custom format and it is also the way to customize the text render.\n\n```ts\ntype AffineTextAttributes = {\n  // your custom attributes\n};\n\nconst attributeRenderer: AttributeRenderer<AffineTextAttributes> = (\n  delta,\n  // you can use `selected` to check if the text node is selected\n  selected\n) => {\n  // generate style from delta\n  return html`<span style=${style}\n    ><v-text .str=${delta.insert}></v-text\n  ></span>`;\n};\n\nconst doc = new Y.Doc();\nconst yText = doc.getText('text');\nconst vEditor = new VEditor(yText);\nvEditor.setAttributeRenderer(attributeRenderer);\n\nconst editorContainer = document.getElementById('editor');\nvEditor.mount(editorContainer);\n```\n\nYou will see there is a `v-text` in the template, it is a custom element that render text node.\nVirgo use them to calculate range so you have to use them to render text content from delta.\n\n### Rich Text\n\nIf you find Virgo's features too limited or difficult to use, you can refer to or directly use the [rich-text](https://github.com/toeverything/blocksuite/blob/f71df00ce18e3f300caad914aaedf63267158885/packages/blocks/src/components/rich-text/rich-text.ts) encapsulated in the blocks package. It contains basic editing features like copy/cut/paste, undo/redo (including range restore).\n","exports":{".":"./dist/index.js","./*":"./dist/*.js"},"license":"MPL-2.0","scripts":{"test":"pnpm test:unit && pnpm test:e2e","build":"tsc","test:e2e":"playwright test","test:unit":"vitest --run","test:unit:ui":"vitest --ui","test:unit:coverage":"vitest run --coverage"},"_npmUser":{"name":"doodlewind","email":"doodlewind@gmail.com"},"homepage":"https://github.com/toeverything/blocksuite#readme","keywords":[],"_resolved":"/tmp/035d25ae6bb7f20cbce2dc95b0c68a35/blocksuite-virgo-0.0.0-20231206051647-ab555738-nightly.tgz","_integrity":"sha512-RWjmY2XwSm3tQDBsOSdermuCMhR8InxapllTrmdiagyt4XRtBPQbZa84YzhRJH6Qo0hiu72pP3/0hHJPpnj/BA==","repository":{"url":"git+https://github.com/toeverything/blocksuite.git","type":"git"},"_npmVersion":"9.8.1","description":"A micro editor.","directories":{},"maintainers":[{"name":"lawvs","email":"litusq@gmail.com"},{"name":"doodlewind","email":"doodlewind@gmail.com"}],"_nodeVersion":"18.18.2","dependencies":{"zod":"^3.22.4","@blocksuite/global":"0.0.0-20231206051647-ab555738-nightly"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"lit":"^3.1.0","yjs":"^13.6.10"},"peerDependencies":{"lit":"^3.0.2","yjs":"^13"},"_npmOperationalInternal":{"tmp":"tmp/virgo_0.0.0-20231206051647-ab555738-nightly_1701850590485_0.8485992095318964","host":"s3://npm-registry-packages"},"_id":"@blocksuite/virgo@0.0.0-20231206051647-ab555738-nightly","version":"0.0.0-20231206051647-ab555738-nightly"}