@blocknote/core 0.9.6 → 0.10.0

package/src/schema/blocks/types.ts

@@ -0,0 +1,252 @@
+/** Define the main block types **/
+import { Extension, Node } from "@tiptap/core";
+
+import type { BlockNoteEditor } from "../../editor/BlockNoteEditor";
+import {
+  InlineContent,
+  InlineContentSchema,
+  PartialInlineContent,
+} from "../inlineContent/types";
+import { PropSchema, Props } from "../propTypes";
+import { StyleSchema } from "../styles/types";
+
+export type BlockNoteDOMElement =
+  | "editor"
+  | "blockContainer"
+  | "blockGroup"
+  | "blockContent"
+  | "inlineContent";
+
+export type BlockNoteDOMAttributes = Partial<{
+  [DOMElement in BlockNoteDOMElement]: Record<string, string>;
+}>;
+
+// BlockConfig contains the "schema" info about a Block type
+// i.e. what props it supports, what content it supports, etc.
+export type BlockConfig = {
+  type: string;
+  readonly propSchema: PropSchema;
+  content: "inline" | "none" | "table";
+};
+
+// Block implementation contains the "implementation" info about a Block
+// such as the functions / Nodes required to render and / or serialize it
+export type TiptapBlockImplementation<
+  T extends BlockConfig,
+  B extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  requiredExtensions?: Array<Extension | Node>;
+  node: Node;
+  toInternalHTML: (
+    block: BlockFromConfigNoChildren<T, I, S> & {
+      children: Block<B, I, S>[];
+    },
+    editor: BlockNoteEditor<B, I, S>
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  };
+  toExternalHTML: (
+    block: BlockFromConfigNoChildren<T, I, S> & {
+      children: Block<B, I, S>[];
+    },
+    editor: BlockNoteEditor<B, I, S>
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  };
+};
+
+// A Spec contains both the Config and Implementation
+export type BlockSpec<
+  T extends BlockConfig,
+  B extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  config: T;
+  implementation: TiptapBlockImplementation<T, B, I, S>;
+};
+
+// 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.
+type NamesMatch<Blocks extends Record<string, BlockConfig>> = Blocks extends {
+  [Type in keyof Blocks]: Type extends string
+    ? Blocks[Type] extends { type: Type }
+      ? Blocks[Type]
+      : never
+    : never;
+}
+  ? Blocks
+  : never;
+
+// A Schema contains all the types (Configs) supported in an editor
+// The keys are the "type" of a block
+export type BlockSchema = NamesMatch<Record<string, BlockConfig>>;
+
+export type BlockSpecs = Record<
+  string,
+  BlockSpec<any, any, InlineContentSchema, StyleSchema>
+>;
+
+export type BlockImplementations = Record<
+  string,
+  TiptapBlockImplementation<any, any, any, any>
+>;
+
+export type BlockSchemaFromSpecs<T extends BlockSpecs> = {
+  [K in keyof T]: T[K]["config"];
+};
+
+export type BlockSchemaWithBlock<
+  BType extends string,
+  C extends BlockConfig
+> = {
+  [k in BType]: C;
+};
+
+export type TableContent<
+  I extends InlineContentSchema,
+  S extends StyleSchema = StyleSchema
+> = {
+  type: "tableContent";
+  rows: {
+    cells: InlineContent<I, S>[][];
+  }[];
+};
+
+// A BlockConfig has all the information to get the type of a Block (which is a specific instance of the BlockConfig.
+// i.e.: paragraphConfig: BlockConfig defines what a "paragraph" is / supports, and BlockFromConfigNoChildren<paragraphConfig> is the shape of a specific paragraph block.
+// (for internal use)
+export type BlockFromConfigNoChildren<
+  B extends BlockConfig,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  id: string;
+  type: B["type"];
+  props: Props<B["propSchema"]>;
+  content: B["content"] extends "inline"
+    ? InlineContent<I, S>[]
+    : B["content"] extends "table"
+    ? TableContent<I, S>
+    : B["content"] extends "none"
+    ? undefined
+    : never;
+};
+
+export type BlockFromConfig<
+  B extends BlockConfig,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = BlockFromConfigNoChildren<B, I, S> & {
+  children: Block<BlockSchema, I, S>[];
+};
+
+// 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,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  [BType in keyof BSchema]: BlockFromConfigNoChildren<BSchema[BType], I, S>;
+};
+
+// 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,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = BlocksWithoutChildren<BSchema, I, S>[keyof BSchema] & {
+  children: Block<BSchema, I, S>[];
+};
+
+export type SpecificBlock<
+  BSchema extends BlockSchema,
+  BType extends keyof BSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = BlocksWithoutChildren<BSchema, I, S>[BType] & {
+  children: Block<BSchema, I, S>[];
+};
+
+/** CODE FOR PARTIAL BLOCKS, analogous to above
+ *
+ * Partial blocks are convenience-wrappers to make it easier to
+ *create/update blocks in the editor.
+ *
+ */
+
+export type PartialTableContent<
+  I extends InlineContentSchema,
+  S extends StyleSchema = StyleSchema
+> = {
+  type: "tableContent";
+  rows: {
+    cells: PartialInlineContent<I, S>[];
+  }[];
+};
+
+type PartialBlockFromConfigNoChildren<
+  B extends BlockConfig,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  id?: string;
+  type?: B["type"];
+  props?: Partial<Props<B["propSchema"]>>;
+  content?: B["content"] extends "inline"
+    ? PartialInlineContent<I, S>
+    : B["content"] extends "table"
+    ? PartialTableContent<I, S>
+    : undefined;
+};
+
+type PartialBlocksWithoutChildren<
+  BSchema extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  [BType in keyof BSchema]: PartialBlockFromConfigNoChildren<
+    BSchema[BType],
+    I,
+    S
+  >;
+};
+
+export type PartialBlock<
+  BSchema extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = PartialBlocksWithoutChildren<
+  BSchema,
+  I,
+  S
+>[keyof PartialBlocksWithoutChildren<BSchema, I, S>] &
+  Partial<{
+    children: PartialBlock<BSchema, I, S>[];
+  }>;
+
+export type SpecificPartialBlock<
+  BSchema extends BlockSchema,
+  I extends InlineContentSchema,
+  BType extends keyof BSchema,
+  S extends StyleSchema
+> = PartialBlocksWithoutChildren<BSchema, I, S>[BType] & {
+  children?: Block<BSchema, I, S>[];
+};
+
+export type PartialBlockFromConfig<
+  B extends BlockConfig,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = PartialBlockFromConfigNoChildren<B, I, S> & {
+  children?: Block<BlockSchema, I, S>[];
+};
+
+export type BlockIdentifier = { id: string } | string;

package/src/schema/index.ts

@@ -0,0 +1,10 @@
+export * from "./blocks/createSpec";
+export * from "./blocks/internal";
+export * from "./blocks/types";
+export * from "./inlineContent/createSpec";
+export * from "./inlineContent/internal";
+export * from "./inlineContent/types";
+export * from "./propTypes";
+export * from "./styles/createSpec";
+export * from "./styles/internal";
+export * from "./styles/types";

package/src/schema/inlineContent/createSpec.ts

@@ -0,0 +1,119 @@
+import { Node } from "@tiptap/core";
+import { ParseRule } from "@tiptap/pm/model";
+import { nodeToCustomInlineContent } from "../../api/nodeConversions/nodeConversions";
+import { propsToAttributes } from "../blocks/internal";
+import { Props } from "../propTypes";
+import { StyleSchema } from "../styles/types";
+import {
+  addInlineContentAttributes,
+  addInlineContentKeyboardShortcuts,
+  createInlineContentSpecFromTipTapNode,
+} from "./internal";
+import {
+  CustomInlineContentConfig,
+  InlineContentConfig,
+  InlineContentFromConfig,
+  InlineContentSpec,
+} from "./types";
+
+// TODO: support serialization
+
+export type CustomInlineContentImplementation<
+  T extends InlineContentConfig,
+  // B extends BlockSchema,
+  // I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  render: (
+    /**
+     * The custom inline content to render
+     */
+    inlineContent: InlineContentFromConfig<T, S>
+    /**
+     * 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<B, I, S>
+    // (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
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+    // destroy?: () => void;
+  };
+};
+
+export function getInlineContentParseRules(
+  config: CustomInlineContentConfig
+): ParseRule[] {
+  return [
+    {
+      tag: `[data-inline-content-type="${config.type}"]`,
+      contentElement: (element) => {
+        const htmlElement = element as HTMLElement;
+
+        if (htmlElement.matches("[data-editable]")) {
+          return htmlElement;
+        }
+
+        return htmlElement.querySelector("[data-editable]") || htmlElement;
+      },
+    },
+  ];
+}
+
+export function createInlineContentSpec<
+  T extends CustomInlineContentConfig,
+  S extends StyleSchema
+>(
+  inlineContentConfig: T,
+  inlineContentImplementation: CustomInlineContentImplementation<T, S>
+): InlineContentSpec<T> {
+  const node = Node.create({
+    name: inlineContentConfig.type,
+    inline: true,
+    group: "inline",
+    selectable: inlineContentConfig.content === "styled",
+    atom: inlineContentConfig.content === "none",
+    content: (inlineContentConfig.content === "styled"
+      ? "inline*"
+      : "") as T["content"] extends "styled" ? "inline*" : "",
+
+    addAttributes() {
+      return propsToAttributes(inlineContentConfig.propSchema);
+    },
+
+    addKeyboardShortcuts() {
+      return addInlineContentKeyboardShortcuts(inlineContentConfig);
+    },
+
+    parseHTML() {
+      return getInlineContentParseRules(inlineContentConfig);
+    },
+
+    renderHTML({ node }) {
+      const editor = this.options.editor;
+
+      const output = inlineContentImplementation.render(
+        nodeToCustomInlineContent(
+          node,
+          editor.inlineContentSchema,
+          editor.styleSchema
+        ) as any as InlineContentFromConfig<T, S> // TODO: fix cast
+      );
+
+      return addInlineContentAttributes(
+        output,
+        inlineContentConfig.type,
+        node.attrs as Props<T["propSchema"]>,
+        inlineContentConfig.propSchema
+      );
+    },
+  });
+
+  return createInlineContentSpecFromTipTapNode(
+    node,
+    inlineContentConfig.propSchema
+  ) as InlineContentSpec<T>; // TODO: fix cast
+}

package/src/schema/inlineContent/internal.ts

@@ -0,0 +1,105 @@
+import { KeyboardShortcutCommand, Node } from "@tiptap/core";
+
+import { camelToDataKebab } from "../../util/string";
+import { PropSchema, Props } from "../propTypes";
+import {
+  CustomInlineContentConfig,
+  InlineContentConfig,
+  InlineContentImplementation,
+  InlineContentSchemaFromSpecs,
+  InlineContentSpec,
+  InlineContentSpecs,
+} from "./types";
+
+// Function that adds necessary classes and attributes to the `dom` element
+// returned from a custom inline content's 'render' function, to ensure no data
+// is lost on internal copy & paste.
+export function addInlineContentAttributes<
+  IType extends string,
+  PSchema extends PropSchema
+>(
+  element: {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  },
+  inlineContentType: IType,
+  inlineContentProps: Props<PSchema>,
+  propSchema: PSchema
+): {
+  dom: HTMLElement;
+  contentDOM?: HTMLElement;
+} {
+  // Sets content type attribute
+  element.dom.setAttribute("data-inline-content-type", inlineContentType);
+  // Adds props as HTML attributes in kebab-case with "data-" prefix. Skips props
+  // set to their default values.
+  Object.entries(inlineContentProps)
+    .filter(([prop, value]) => value !== propSchema[prop].default)
+    .map(([prop, value]) => {
+      return [camelToDataKebab(prop), value];
+    })
+    .forEach(([prop, value]) => element.dom.setAttribute(prop, value));
+
+  if (element.contentDOM !== undefined) {
+    element.contentDOM.setAttribute("data-editable", "");
+  }
+
+  return element;
+}
+
+// see https://github.com/TypeCellOS/BlockNote/pull/435
+export function addInlineContentKeyboardShortcuts<
+  T extends CustomInlineContentConfig
+>(
+  config: T
+): {
+  [p: string]: KeyboardShortcutCommand;
+} {
+  return {
+    Backspace: ({ editor }) => {
+      const resolvedPos = editor.state.selection.$from;
+
+      return (
+        editor.state.selection.empty &&
+        resolvedPos.node().type.name === config.type &&
+        resolvedPos.parentOffset === 0
+      );
+    },
+  };
+}
+
+// This helper function helps to instantiate a InlineContentSpec with a
+// config and implementation that conform to the type of Config
+export function createInternalInlineContentSpec<T extends InlineContentConfig>(
+  config: T,
+  implementation: InlineContentImplementation<T>
+) {
+  return {
+    config,
+    implementation,
+  } satisfies InlineContentSpec<T>;
+}
+
+export function createInlineContentSpecFromTipTapNode<
+  T extends Node,
+  P extends PropSchema
+>(node: T, propSchema: P) {
+  return createInternalInlineContentSpec(
+    {
+      type: node.name as T["name"],
+      propSchema,
+      content: node.config.content === "inline*" ? "styled" : "none",
+    },
+    {
+      node,
+    }
+  );
+}
+
+export function getInlineContentSchemaFromSpecs<T extends InlineContentSpecs>(
+  specs: T
+) {
+  return Object.fromEntries(
+    Object.entries(specs).map(([key, value]) => [key, value.config])
+  ) as InlineContentSchemaFromSpecs<T>;
+}

package/src/schema/inlineContent/types.ts

@@ -0,0 +1,144 @@
+import { Node } from "@tiptap/core";
+import { PropSchema, Props } from "../propTypes";
+import { StyleSchema, Styles } from "../styles/types";
+
+export type CustomInlineContentConfig = {
+  type: string;
+  content: "styled" | "none"; // | "plain"
+  readonly propSchema: PropSchema;
+  // content: "inline" | "none" | "table";
+};
+// InlineContentConfig contains the "schema" info about an InlineContent type
+// i.e. what props it supports, what content it supports, etc.
+export type InlineContentConfig = CustomInlineContentConfig | "text" | "link";
+
+// InlineContentImplementation contains the "implementation" info about an InlineContent element
+// such as the functions / Nodes required to render and / or serialize it
+// @ts-ignore
+export type InlineContentImplementation<T extends InlineContentConfig> =
+  T extends "link" | "text"
+    ? undefined
+    : {
+        node: Node;
+      };
+
+// Container for both the config and implementation of InlineContent,
+// and the type of `implementation` is based on that of the config
+export type InlineContentSpec<T extends InlineContentConfig> = {
+  config: T;
+  implementation: InlineContentImplementation<T>;
+};
+
+// A Schema contains all the types (Configs) supported in an editor
+// The keys are the "type" of InlineContent elements
+export type InlineContentSchema = Record<string, InlineContentConfig>;
+
+export type InlineContentSpecs = {
+  text: { config: "text"; implementation: undefined };
+  link: { config: "link"; implementation: undefined };
+} & Record<string, InlineContentSpec<InlineContentConfig>>;
+
+export type InlineContentSchemaFromSpecs<T extends InlineContentSpecs> = {
+  [K in keyof T]: T[K]["config"];
+};
+
+export type CustomInlineContentFromConfig<
+  I extends CustomInlineContentConfig,
+  S extends StyleSchema
+> = {
+  type: I["type"];
+  props: Props<I["propSchema"]>;
+  content: I["content"] extends "styled"
+    ? StyledText<S>[]
+    : I["content"] extends "plain"
+    ? string
+    : I["content"] extends "none"
+    ? undefined
+    : never;
+};
+
+export type InlineContentFromConfig<
+  I extends InlineContentConfig,
+  S extends StyleSchema
+> = I extends "text"
+  ? StyledText<S>
+  : I extends "link"
+  ? Link<S>
+  : I extends CustomInlineContentConfig
+  ? CustomInlineContentFromConfig<I, S>
+  : never;
+
+export type PartialCustomInlineContentFromConfig<
+  I extends CustomInlineContentConfig,
+  S extends StyleSchema
+> = {
+  type: I["type"];
+  props?: Props<I["propSchema"]>;
+  content: I["content"] extends "styled"
+    ? StyledText<S>[] | string
+    : I["content"] extends "plain"
+    ? string
+    : I["content"] extends "none"
+    ? undefined
+    : never;
+};
+
+export type PartialInlineContentFromConfig<
+  I extends InlineContentConfig,
+  S extends StyleSchema
+> = I extends "text"
+  ? string | StyledText<S>
+  : I extends "link"
+  ? PartialLink<S>
+  : I extends CustomInlineContentConfig
+  ? PartialCustomInlineContentFromConfig<I, S>
+  : never;
+
+export type StyledText<T extends StyleSchema> = {
+  type: "text";
+  text: string;
+  styles: Styles<T>;
+};
+
+export type Link<T extends StyleSchema> = {
+  type: "link";
+  href: string;
+  content: StyledText<T>[];
+};
+
+export type PartialLink<T extends StyleSchema> = Omit<Link<T>, "content"> & {
+  content: string | Link<T>["content"];
+};
+
+export type InlineContent<
+  I extends InlineContentSchema,
+  T extends StyleSchema
+> = InlineContentFromConfig<I[keyof I], T>;
+
+type PartialInlineContentElement<
+  I extends InlineContentSchema,
+  T extends StyleSchema
+> = PartialInlineContentFromConfig<I[keyof I], T>;
+
+export type PartialInlineContent<
+  I extends InlineContentSchema,
+  T extends StyleSchema
+> = PartialInlineContentElement<I, T>[] | string;
+
+export function isLinkInlineContent<T extends StyleSchema>(
+  content: InlineContent<any, T>
+): content is Link<T> {
+  return content.type === "link";
+}
+
+export function isPartialLinkInlineContent<T extends StyleSchema>(
+  content: PartialInlineContentElement<any, T>
+): content is PartialLink<T> {
+  return typeof content !== "string" && content.type === "link";
+}
+
+export function isStyledTextInlineContent<T extends StyleSchema>(
+  content: PartialInlineContentElement<any, T>
+): content is StyledText<T> {
+  return typeof content !== "string" && content.type === "text";
+}

package/src/schema/propTypes.ts

@@ -0,0 +1,32 @@
+// Defines a single prop spec, which includes the default value the prop should
+// take and possible values it can take.
+export type PropSpec<PType extends boolean | number | string> = {
+  values?: readonly PType[];
+  default: PType;
+};
+
+// 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<boolean | number | string>>;
+
+// 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> = {
+  [PName in keyof PSchema]: PSchema[PName]["default"] extends boolean
+    ? PSchema[PName]["values"] extends readonly boolean[]
+      ? PSchema[PName]["values"][number]
+      : boolean
+    : PSchema[PName]["default"] extends number
+    ? PSchema[PName]["values"] extends readonly number[]
+      ? PSchema[PName]["values"][number]
+      : number
+    : PSchema[PName]["default"] extends string
+    ? PSchema[PName]["values"] extends readonly string[]
+      ? PSchema[PName]["values"][number]
+      : string
+    : never;
+};