From 2ad72bbf61848c76650fe874d1c39dda988fd48e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20B=C3=A4dorf?= Date: Mon, 5 Sep 2022 21:46:55 +0200 Subject: [PATCH] Small docs improvements --- docs/.vitepress/config.ts | 7 ++-- docs/creating-blocks/examples.md | 3 ++ docs/creating-blocks/index.md | 22 ++++++++++++ docs/installation.md | 2 ++ .../core/lib/components/TreeBlockSelect.tsx | 2 +- packages/core/lib/types.ts | 34 +++++++++---------- packages/heading/lib/index.ts | 3 +- packages/paragraph/lib/edit.tsx | 12 +++---- 8 files changed, 56 insertions(+), 29 deletions(-) create mode 100644 docs/creating-blocks/examples.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index b090fec..f8a30db 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -18,11 +18,10 @@ export default defineConfig({ ] }, { - text: 'Development', + text: 'Creating Blocks', items: [ - { text: 'Introduction', link: '/' }, - { text: 'Installation and usage', link: '/installation' }, - { text: 'Getting Started', link: '/getting-started' }, + { text: 'Basics', link: '/creating-blocks/' }, + { text: 'Examples', link: '/creating-blocks/examples' }, ] } ] diff --git a/docs/creating-blocks/examples.md b/docs/creating-blocks/examples.md new file mode 100644 index 0000000..896aac1 --- /dev/null +++ b/docs/creating-blocks/examples.md @@ -0,0 +1,3 @@ +# Example blocks + +As Schlechtenburg is still in active development, it's good to check out the official blocks to see what they look like. diff --git a/docs/creating-blocks/index.md b/docs/creating-blocks/index.md index 2964fd4..002105d 100644 --- a/docs/creating-blocks/index.md +++ b/docs/creating-blocks/index.md @@ -1 +1,23 @@ # Creating blocks + +After you've been using Schlechtenburg for a short while, you'll probably end up wanting to create your own blocks. + +## The anatomy of a block + +In general, a block is a javascript object that implements the `IBlockDefinition` interface. + +A functional block contains all of the following: + +1. A unique name. This will be used to assign JSON data to your specific block. It's good practice to prefix these so you don't run into conflicts with other blocks. Official Schlechtenburg block names are prefixed with `sb-`. +2. A function that returns a JSON structure representing an "empty" or "default" instance of your block. +3. A component for the edit mode. +4. A component for the view mode. + +```ts +export default { + name, + getDefaultData, + edit: defineAsyncComponent(() => import('./edit')), + view: defineAsyncComponent(() => import('./view')), +} as IBlockDefinition; +``` diff --git a/docs/installation.md b/docs/installation.md index ac8f68f..5e65498 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -6,6 +6,8 @@ meaning that v2.0.3 of one package is guaranteed to work with v2.0.3 of another Schlechtenburg is basically one Vue component, so if you're already using Vue you can import and use it directly. Otherwise, there's the standalone version that comes prepackaged with Vue. +[Projects without Vue 3](#your-project-does-not-use-vue-3) | [Projects with Vue 3](#your-project-uses-vue-3) + ## Your project does not use Vue 3 ### Install npm packages diff --git a/packages/core/lib/components/TreeBlockSelect.tsx b/packages/core/lib/components/TreeBlockSelect.tsx index 1fe5a46..85a1e81 100644 --- a/packages/core/lib/components/TreeBlockSelect.tsx +++ b/packages/core/lib/components/TreeBlockSelect.tsx @@ -42,7 +42,7 @@ export const SbTreeBlockSelect = defineComponent({ return () => ( - console.log(blockTree.value) || blockTree.value + blockTree.value ? { * Callback type for sending full block updates. SbBlock takes this as a prop. * * ``` - * + * * ``` * * @see SbBlock @@ -42,7 +42,7 @@ export type OnUpdateBlockCb = (updated: IBlockData) => void; * * ``` * props: { - * onUpdate: { + * eventUpdate: { * type: (null as unknown) as PropType>, * default: () => {}, * }, @@ -58,7 +58,7 @@ export type OnUpdateSelfCb = (updated: Partial) => void; * * ``` * props: { - * onPrependBlock: { + * eventPrependBlock: { * type: (null as unknown) as PropType>, * default: () => {}, * }, @@ -74,7 +74,7 @@ export type OnPrependBlockCb = (block: IBlockData) => void; * * ``` * props: { - * onAppendBlock: { + * eventAppendBlock: { * type: (null as unknown) as PropType>, * default: () => {}, * }, @@ -90,7 +90,7 @@ export type OnAppendBlockCb = (block: IBlockData) => void; * * ``` * props: { - * onRemoveSelf: { + * eventRemoveSelf: { * type: (null as unknown) as PropType, * default: () => {}, * }, @@ -106,32 +106,32 @@ export type OnRemoveSelfCb = () => void; * * ``` * props: { - * onActivatePrevious: { + * eventActivatePrevious: { * type: (null as unknown) as PropType, - * default: () => {}, + * default: (_i:number) => {}, * }, * } * ``` * * @see SbBlock */ -export type OnActivatePreviousCb = () => void; +export type OnActivatePreviousCb = (_i:number) => void; /** * Callback type for activating the next block. * * ``` * props: { - * onActivateNext: { + * eventActivateNext: { * type: (null as unknown) as PropType, - * default: () => {}, + * default: (_i:number) => {}, * }, * } * ``` * * @see SbBlock */ -export type OnActivateNextCb = () => void; +export type OnActivateNextCb = (_i:number) => void; /** * Any Block that you create @@ -141,12 +141,12 @@ export type OnActivateNextCb = () => void; export interface IBlockProps { blockId?: string; data?: T, - onUpdate?: OnUpdateSelfCb; - onPrependBlock?: OnPrependBlockCb; - onAppendBlock?: OnAppendBlockCb; - onRemoveSelf?: OnRemoveSelfCb; - onActivateNext?: OnActivateNextCb; - onActivatePrevious?: OnActivatePreviousCb; + eventUpdate?: OnUpdateSelfCb; + eventPrependBlock?: OnPrependBlockCb; + eventAppendBlock?: OnAppendBlockCb; + eventRemoveSelf?: OnRemoveSelfCb; + eventActivateNext?: OnActivateNextCb; + eventActivatePrevious?: OnActivatePreviousCb; } /** diff --git a/packages/heading/lib/index.ts b/packages/heading/lib/index.ts index 36abf80..8677be4 100644 --- a/packages/heading/lib/index.ts +++ b/packages/heading/lib/index.ts @@ -1,4 +1,5 @@ import { defineAsyncComponent } from 'vue'; +import { IBlockDefinition } from '@schlechtenburg/core'; import { getDefaultData } from './util'; export * from './util'; @@ -9,4 +10,4 @@ export default { getDefaultData, edit: defineAsyncComponent(() => import('./edit')), view: defineAsyncComponent(() => import('./view')), -}; +} as IBlockDefinition; diff --git a/packages/paragraph/lib/edit.tsx b/packages/paragraph/lib/edit.tsx index a6c7066..06487c2 100644 --- a/packages/paragraph/lib/edit.tsx +++ b/packages/paragraph/lib/edit.tsx @@ -47,12 +47,12 @@ export default defineComponent({ default: () => {}, }, eventActivateNext: { - type: (null as unknown) as PropType<() => void>, - default: () => {}, + type: (null as unknown) as PropType<(_i:number) => void>, + default: (_i:number) => {}, }, eventActivatePrevious: { - type: (null as unknown) as PropType<() => void>, - default: () => {}, + type: (null as unknown) as PropType<(_i:number) => void>, + default: (_i:number) => {}, }, }, @@ -151,10 +151,10 @@ export default defineComponent({ if (node === inputEl.value || index === 0 || index === childNodes.length -1) { switch ($event.key) { case 'ArrowDown': - props.eventActivateNext(); + props.eventActivateNext(index); break; case 'ArrowUp': - props.eventActivatePrevious(); + props.eventActivatePrevious(index); break; } }