@blocknote/core 0.7.1-alpha.0 → 0.8.1

package/src/extensions/Blocks/api/blockTypes.ts

@@ -1,90 +1,177 @@
 /** Define the main block types **/
-
+import { Node, NodeConfig } from "@tiptap/core";
+import { BlockNoteEditor } from "../../../BlockNoteEditor";
 import { InlineContent, PartialInlineContent } from "./inlineContentTypes";
 
-export type BlockTemplate<
-  // Type of the block.
-  // Examples might include: "paragraph", "heading", or "bulletListItem".
-  Type extends string,
-  // Changeable props which affect the block's behaviour or appearance.
-  // An example might be: { textAlignment: "left" | "right" | "center" } for a paragraph block.
-  Props extends Record<string, string>
+// A configuration for a TipTap node, but with stricter type constraints on the
+// "name" and "group" properties. The "name" property is now always a string
+// literal type, and the "blockGroup" property cannot be configured as it should
+// always be "blockContent". Used as the parameter in `createTipTapNode`.
+export type TipTapNodeConfig<
+  Name extends string,
+  Options = any,
+  Storage = any
 > = {
-  id: string;
-  type: Type;
-  props: Props;
-  content: InlineContent[];
-  children: Block[];
+  [K in keyof NodeConfig<Options, Storage>]: K extends "name"
+    ? Name
+    : K extends "group"
+    ? never
+    : NodeConfig<Options, Storage>[K];
 };
 
-export type DefaultBlockProps = {
-  backgroundColor: string;
-  textColor: string;
-  textAlignment: "left" | "center" | "right" | "justify";
+// A TipTap node with stricter type constraints on the "name" and "group"
+// properties. The "name" property is now a string literal type, and the
+// "blockGroup" property is now "blockContent". Returned by `createTipTapNode`.
+export type TipTapNode<
+  Name extends string,
+  Options = any,
+  Storage = any
+> = Node<Options, Storage> & {
+  name: Name;
+  group: "blockContent";
 };
 
-export type NumberedListItemBlock = BlockTemplate<
-  "numberedListItem",
-  DefaultBlockProps
->;
+// Defines a single prop spec, which includes the default value the prop should
+// take and possible values it can take.
+export type PropSpec = {
+  values?: readonly string[];
+  default: string;
+};
 
-export type BulletListItemBlock = BlockTemplate<
-  "bulletListItem",
-  DefaultBlockProps
->;
+// Defines multiple block prop specs. The key of each prop is the name of the
+// prop, while the value is a corresponding prop spec. This should be included
+// in a block config or schema. From a prop schema, we can derive both the props'
+// internal implementation (as TipTap node attributes) and the type information
+// for the external API.
+export type PropSchema = Record<string, PropSpec>;
 
-export type HeadingBlock = BlockTemplate<
-  "heading",
-  DefaultBlockProps & {
-    level: "1" | "2" | "3";
-  }
->;
+// Defines Props objects for use in Block objects in the external API. Converts
+// each prop spec into a union type of its possible values, or a string if no
+// values are specified.
+export type Props<PSchema extends PropSchema> = {
+  [PType in keyof PSchema]: PSchema[PType]["values"] extends readonly string[]
+    ? PSchema[PType]["values"][number]
+    : string;
+};
 
-export type ParagraphBlock = BlockTemplate<"paragraph", DefaultBlockProps>;
+// Defines the config for a single block. Meant to be used as an argument to
+// `createBlockSpec`, which will create a new block spec from it. This is the
+// main way we expect people to create custom blocks as consumers don't need to
+// know anything about the TipTap API since the associated nodes are created
+// automatically.
+export type BlockConfig<
+  Type extends string,
+  PSchema extends PropSchema,
+  ContainsInlineContent extends boolean,
+  BSchema extends BlockSchema
+> = {
+  // Attributes to define block in the API as well as a TipTap node.
+  type: Type;
+  readonly propSchema: PSchema;
 
-export type Block =
-  | ParagraphBlock
-  | HeadingBlock
-  | BulletListItemBlock
-  | NumberedListItemBlock;
+  // Additional attributes to help define block as a TipTap node.
+  containsInlineContent: ContainsInlineContent;
+  render: (
+    /**
+     * The custom block to render
+     */
+    block: SpecificBlock<
+      BSchema & { [k in Type]: BlockSpec<Type, PSchema> },
+      Type
+    >,
+    /**
+     * The BlockNote editor instance
+     * This is typed generically. If you want an editor with your custom schema, you need to
+     * cast it manually, e.g.: `const e = editor as BlockNoteEditor<typeof mySchema>;`
+     */
+    editor: BlockNoteEditor<BSchema & { [k in Type]: BlockSpec<Type, PSchema> }>
+    // (note) if we want to fix the manual cast, we need to prevent circular references and separate block definition and render implementations
+    // or allow manually passing <BSchema>, but that's not possible without passing the other generics because Typescript doesn't support partial inferred generics
+  ) => ContainsInlineContent extends true
+    ? {
+        dom: HTMLElement;
+        contentDOM: HTMLElement;
+      }
+    : {
+        dom: HTMLElement;
+      };
+};
 
-export type BlockIdentifier = string | Block;
+// Defines a single block spec, which includes the props that the block has and
+// the TipTap node used to implement it. Usually created using `createBlockSpec`
+// though it can also be defined from scratch by providing your own TipTap node,
+// allowing for more advanced custom blocks.
+export type BlockSpec<Type extends string, PSchema extends PropSchema> = {
+  readonly propSchema: PSchema;
+  node: TipTapNode<Type>;
+};
 
-/** Define "Partial Blocks", these are for updating or creating blocks */
-export type PartialBlockTemplate<B extends Block> = B extends Block
-  ? Partial<Omit<B, "props" | "children" | "content" | "type">> & {
-      type?: B["type"];
-      props?: Partial<B["props"]>;
-      content?: string | PartialInlineContent[];
-      children?: PartialBlock[];
-    }
+// Utility type. For a given object block schema, ensures that the key of each
+// block spec matches the name of the TipTap node in it.
+export type TypesMatch<
+  Blocks extends Record<string, BlockSpec<string, PropSchema>>
+> = Blocks extends {
+  [Type in keyof Blocks]: Type extends string
+    ? Blocks[Type] extends BlockSpec<Type, PropSchema>
+      ? Blocks[Type]
+      : never
+    : never;
+}
+  ? Blocks
   : never;
 
-export type PartialBlock = PartialBlockTemplate<Block>;
+// Defines multiple block specs. Also ensures that the key of each block schema
+// is the same as name of the TipTap node in it. This should be passed in the
+// `blocks` option of the BlockNoteEditor. From a block schema, we can derive
+// both the blocks' internal implementation (as TipTap nodes) and the type
+// information for the external API.
+export type BlockSchema = TypesMatch<
+  Record<string, BlockSpec<string, PropSchema>>
+>;
 
-export type BlockPropsTemplate<Props> = Props extends Block["props"]
-  ? keyof Props
-  : never;
+// Converts each block spec into a Block object without children. We later merge
+// them into a union type and add a children property to create the Block and
+// PartialBlock objects we use in the external API.
+type BlocksWithoutChildren<BSchema extends BlockSchema> = {
+  [BType in keyof BSchema]: {
+    id: string;
+    type: BType;
+    props: Props<BSchema[BType]["propSchema"]>;
+    content: InlineContent[];
+  };
+};
 
-/**
- * Expose blockProps. This is currently not very nice, but it's expected this
- * will change anyway once we allow for custom blocks
- */
-
-export const globalProps: Array<keyof DefaultBlockProps> = [
-  "backgroundColor",
-  "textColor",
-  "textAlignment",
-];
-
-export const blockProps: Record<Block["type"], Set<string>> = {
-  paragraph: new Set<keyof ParagraphBlock["props"]>([...globalProps]),
-  heading: new Set<keyof HeadingBlock["props"]>([
-    ...globalProps,
-    "level" as const,
-  ]),
-  numberedListItem: new Set<keyof NumberedListItemBlock["props"]>([
-    ...globalProps,
-  ]),
-  bulletListItem: new Set<keyof BulletListItemBlock["props"]>([...globalProps]),
+// Converts each block spec into a Block object without children, merges them
+// into a union type, and adds a children property
+export type Block<BSchema extends BlockSchema> =
+  BlocksWithoutChildren<BSchema>[keyof BlocksWithoutChildren<BSchema>] & {
+    children: Block<BSchema>[];
+  };
+
+export type SpecificBlock<
+  BSchema extends BlockSchema,
+  BlockType extends keyof BSchema
+> = BlocksWithoutChildren<BSchema>[BlockType] & {
+  children: Block<BSchema>[];
+};
+
+// Same as BlockWithoutChildren, but as a partial type with some changes to make
+// it easier to create/update blocks in the editor.
+type PartialBlocksWithoutChildren<BSchema extends BlockSchema> = {
+  [BType in keyof BSchema]: Partial<{
+    id: string;
+    type: BType;
+    props: Partial<Props<BSchema[BType]["propSchema"]>>;
+    content: PartialInlineContent[] | string;
+  }>;
 };
+
+// Same as Block, but as a partial type with some changes to make it easier to
+// create/update blocks in the editor.
+export type PartialBlock<BSchema extends BlockSchema> =
+  PartialBlocksWithoutChildren<BSchema>[keyof PartialBlocksWithoutChildren<BSchema>] &
+    Partial<{
+      children: PartialBlock<BSchema>[];
+    }>;
+
+export type BlockIdentifier = { id: string } | string;

package/src/extensions/Blocks/api/cursorPositionTypes.ts

@@ -1,7 +1,7 @@
-import { Block } from "./blockTypes";
+import { Block, BlockSchema } from "./blockTypes";
 
-export type TextCursorPosition = {
-  block: Block;
-  prevBlock: Block | undefined;
-  nextBlock: Block | undefined;
+export type TextCursorPosition<BSchema extends BlockSchema> = {
+  block: Block<BSchema>;
+  prevBlock: Block<BSchema> | undefined;
+  nextBlock: Block<BSchema> | undefined;
 };

package/src/extensions/Blocks/api/defaultBlocks.ts

@@ -0,0 +1,44 @@
+import { HeadingBlockContent } from "../nodes/BlockContent/HeadingBlockContent/HeadingBlockContent";
+import { BulletListItemBlockContent } from "../nodes/BlockContent/ListItemBlockContent/BulletListItemBlockContent/BulletListItemBlockContent";
+import { NumberedListItemBlockContent } from "../nodes/BlockContent/ListItemBlockContent/NumberedListItemBlockContent/NumberedListItemBlockContent";
+import { ParagraphBlockContent } from "../nodes/BlockContent/ParagraphBlockContent/ParagraphBlockContent";
+import { PropSchema, TypesMatch } from "./blockTypes";
+
+export const defaultProps = {
+  backgroundColor: {
+    default: "transparent" as const,
+  },
+  textColor: {
+    default: "black" as const, // TODO
+  },
+  textAlignment: {
+    default: "left" as const,
+    values: ["left", "center", "right", "justify"] as const,
+  },
+} satisfies PropSchema;
+
+export type DefaultProps = typeof defaultProps;
+
+export const defaultBlockSchema = {
+  paragraph: {
+    propSchema: defaultProps,
+    node: ParagraphBlockContent,
+  },
+  heading: {
+    propSchema: {
+      ...defaultProps,
+      level: { default: "1", values: ["1", "2", "3"] as const },
+    },
+    node: HeadingBlockContent,
+  },
+  bulletListItem: {
+    propSchema: defaultProps,
+    node: BulletListItemBlockContent,
+  },
+  numberedListItem: {
+    propSchema: defaultProps,
+    node: NumberedListItemBlockContent,
+  },
+} as const;
+
+export type DefaultBlockSchema = TypesMatch<typeof defaultBlockSchema>;

package/src/extensions/Blocks/api/selectionTypes.ts

@@ -1,5 +1,5 @@
-import { Block } from "./blockTypes";
+import { Block, BlockSchema } from "./blockTypes";
 
-export type Selection = {
-  blocks: Block[];
+export type Selection<BSchema extends BlockSchema> = {
+  blocks: Block<BSchema>[];
 };

package/src/extensions/Blocks/api/serialization.ts

@@ -0,0 +1,29 @@
+import { Extension } from "@tiptap/core";
+import { Plugin } from "prosemirror-state";
+import { DOMSerializer, Schema } from "prosemirror-model";
+
+const customBlockSerializer = (schema: Schema) => {
+  const defaultSerializer = DOMSerializer.fromSchema(schema);
+
+  return new DOMSerializer(
+    {
+      ...defaultSerializer.nodes,
+      // TODO: If a serializer is defined in the config for a custom block, it
+      //  should be added here. We still need to figure out how the serializer
+      //  should be defined in the custom blocks API though, and implement that,
+      //  before we can do this.
+    },
+    defaultSerializer.marks
+  );
+};
+export const CustomBlockSerializerExtension = Extension.create({
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        props: {
+          clipboardSerializer: customBlockSerializer(this.editor.schema),
+        },
+      }),
+    ];
+  },
+});

package/src/extensions/Blocks/index.ts

@@ -1,16 +1,8 @@
 import { Node } from "@tiptap/core";
 import { BlockContainer } from "./nodes/BlockContainer";
 import { BlockGroup } from "./nodes/BlockGroup";
-import { ParagraphBlockContent } from "./nodes/BlockContent/ParagraphBlockContent/ParagraphBlockContent";
-import { HeadingBlockContent } from "./nodes/BlockContent/HeadingBlockContent/HeadingBlockContent";
-import { BulletListItemBlockContent } from "./nodes/BlockContent/ListItemBlockContent/BulletListItemBlockContent/BulletListItemBlockContent";
-import { NumberedListItemBlockContent } from "./nodes/BlockContent/ListItemBlockContent/NumberedListItemBlockContent/NumberedListItemBlockContent";
 
 export const blocks: any[] = [
-  ParagraphBlockContent,
-  HeadingBlockContent,
-  BulletListItemBlockContent,
-  NumberedListItemBlockContent,
   BlockContainer,
   BlockGroup,
   Node.create({

package/src/extensions/Blocks/nodes/Block.module.css

@@ -7,14 +7,26 @@ BASIC STYLES
   transition: margin 0.2s;
 }
 
+/*Ensures blocks & block content spans editor width*/
+.block {
+  display: flex;
+  flex-direction: column;
+}
+
+/*Ensures block content inside React node views spans editor width*/
+.reactNodeViewRenderer {
+  display: flex;
+  flex-grow: 1;
+}
+
 .blockContent {
   padding: 3px 0;
+  flex-grow: 1;
   transition: font-size 0.2s;
   /*
   because the content elements are display: block
   we use flex to position them next to list markers
   */
-  display: flex;
 }
 
 .blockContent::before {
@@ -48,14 +60,14 @@ NESTED BLOCKS
   .blockGroup
   .blockGroup
   > .blockOuter:not([data-prev-depth-changed])::before {
-  border-left: 1px solid #cccccc;
+  border-left: 1px solid #AFAFAF;
 }
 
 [data-theme="dark"]
   .blockGroup
   .blockGroup
   > .blockOuter:not([data-prev-depth-changed])::before {
-  border-left: 1px solid #999999;
+  border-left: 1px solid #7F7F7F;
 }
 
 .blockGroup .blockGroup > .blockOuter[data-prev-depth-change="-2"]::before {
@@ -225,8 +237,8 @@ NESTED BLOCKS
 
 /* PLACEHOLDERS*/
 
-.blockContent.isEmpty > :first-child:before,
-.blockContent.isFilter > :first-child:before {
+.isEmpty .inlineContent:before,
+.isFilter .inlineContent:before {
   /*float: left; */
   content: "";
   pointer-events: none;
@@ -236,33 +248,33 @@ NESTED BLOCKS
   font-style: italic;
 }
 
-[data-theme="light"] .blockContent.isEmpty > :first-child:before,
-.blockContent.isFilter > :first-child:before {
-  color: #cccccc;
+[data-theme="light"] .isEmpty .inlineContent:before,
+.isFilter .inlineContent:before {
+  color: #CFCFCF;
 }
 
-[data-theme="dark"] .blockContent.isEmpty > :first-child:before,
-.blockContent.isFilter > :first-child:before {
-  color: #999999;
+[data-theme="dark"] .isEmpty .inlineContent:before,
+.isFilter .inlineContent:before {
+  color: #7F7F7F;
 }
 
 /* TODO: would be nicer if defined from code */
 
-.blockContent.isEmpty.hasAnchor > :first-child:before {
+.isEmpty.hasAnchor .inlineContent:before {
   content: "Enter text or type '/' for commands";
 }
 
-.blockContent.isFilter.hasAnchor > :first-child:before {
+.blockContent.isFilter.hasAnchor .inlineContent:before {
   content: "Type to filter";
 }
 
-.blockContent[data-content-type="heading"].isEmpty > :first-child::before {
+.blockContent[data-content-type="heading"].isEmpty .inlineContent:before {
   content: "Heading";
 }
 
-.blockContent[data-content-type="bulletListItem"].isEmpty > :first-child:before,
+.blockContent[data-content-type="bulletListItem"].isEmpty .inlineContent:before,
 .blockContent[data-content-type="numberedListItem"].isEmpty
-  > :first-child:before {
+.inlineContent:before {
   content: "List";
 }
 

package/src/extensions/Blocks/nodes/BlockContainer.ts

@@ -5,11 +5,12 @@ import {
   blockToNode,
   inlineContentToNodes,
 } from "../../../api/nodeConversions/nodeConversions";
-import { PartialBlock } from "../api/blockTypes";
+
 import { getBlockInfoFromPos } from "../helpers/getBlockInfoFromPos";
 import { PreviousBlockTypePlugin } from "../PreviousBlockTypePlugin";
 import styles from "./Block.module.css";
 import BlockAttributes from "./BlockAttributes";
+import { BlockSchema, PartialBlock } from "../api/blockTypes";
 
 // TODO
 export interface IBlock {
@@ -23,10 +24,13 @@ declare module "@tiptap/core" {
       BNDeleteBlock: (posInBlock: number) => ReturnType;
       BNMergeBlocks: (posBetweenBlocks: number) => ReturnType;
       BNSplitBlock: (posInBlock: number, keepType: boolean) => ReturnType;
-      BNUpdateBlock: (posInBlock: number, block: PartialBlock) => ReturnType;
-      BNCreateOrUpdateBlock: (
+      BNUpdateBlock: <BSchema extends BlockSchema>(
+        posInBlock: number,
+        block: PartialBlock<BSchema>
+      ) => ReturnType;
+      BNCreateOrUpdateBlock: <BSchema extends BlockSchema>(
         posInBlock: number,
-        block: PartialBlock
+        block: PartialBlock<BSchema>
       ) => ReturnType;
     };
   }

package/src/extensions/Blocks/nodes/BlockContent/HeadingBlockContent/HeadingBlockContent.ts

@@ -1,9 +1,9 @@
-import { InputRule, mergeAttributes, Node } from "@tiptap/core";
+import { InputRule, mergeAttributes } from "@tiptap/core";
+import { createTipTapBlock } from "../../../api/block";
 import styles from "../../Block.module.css";
 
-export const HeadingBlockContent = Node.create({
+export const HeadingBlockContent = createTipTapBlock<"heading">({
   name: "heading",
-  group: "blockContent",
   content: "inline*",
 
   addAttributes() {
@@ -70,7 +70,7 @@ export const HeadingBlockContent = Node.create({
         class: styles.blockContent,
         "data-content-type": this.name,
       }),
-      ["h" + node.attrs.level, 0],
+      ["h" + node.attrs.level, { class: styles.inlineContent }, 0],
     ];
   },
 });

package/src/extensions/Blocks/nodes/BlockContent/ListItemBlockContent/BulletListItemBlockContent/BulletListItemBlockContent.ts

@@ -1,10 +1,10 @@
-import { InputRule, mergeAttributes, Node } from "@tiptap/core";
-import styles from "../../../Block.module.css";
+import { InputRule, mergeAttributes } from "@tiptap/core";
+import { createTipTapBlock } from "../../../../api/block";
 import { handleEnter } from "../ListItemKeyboardShortcuts";
+import styles from "../../../Block.module.css";
 
-export const BulletListItemBlockContent = Node.create({
+export const BulletListItemBlockContent = createTipTapBlock<"bulletListItem">({
   name: "bulletListItem",
-  group: "blockContent",
   content: "inline*",
 
   addInputRules() {
@@ -88,7 +88,7 @@ export const BulletListItemBlockContent = Node.create({
         class: styles.blockContent,
         "data-content-type": this.name,
       }),
-      ["p", 0],
+      ["p", { class: styles.inlineContent }, 0],
     ];
   },
 });