@spec default() :: t()

The schema Coelho ships with: paragraphs, headings, lists, quotes, code blocks, images, and the usual inline marks.

@spec default_limits() :: limits()

The bounds a schema is given when it does not set its own.

@spec extend(
  t(),
  keyword()
) :: t()

Adds nodes and marks to an existing schema.

Most applications want the default schema and one thing of their own — a mention, an embed, a callout — and re-declaring the other fifteen nodes to get there would guarantee they drift.

Coelho.Schema.extend(Coelho.Schema.default(),
  nodes: [
    mention: [
      group: "inline",
      inline: true,
      void: true,
      attrs: [user_id: [required: true, validate: :integer], label: [default: nil, validate: {:nullable, :string}]],
      render: &MyApp.RichText.render_mention/2
    ]
  ]
)

Additions keep their declaration order, after what was already there. Redeclaring an existing name replaces it, which is how the default schema's rendering or attributes get adjusted without a fork.

@spec instance_of?(t(), atom(), atom()) :: boolean()

Whether a node type answers to a name used in a content expression, either because it is that node, or because it belongs to that group.

@spec mark_index(t(), atom()) :: non_neg_integer()

The position of a mark in the schema's declaration order.

Marks are a set, so the order they are written in carries no meaning — which is exactly why a canonical document has to pick one. ProseMirror ranks marks by their position in the schema, and Coelho.Document sorts them the same way, so that the same fragment hashes the same however the editor happened to add its marks.

@spec mark_spec(t(), atom()) :: Coelho.Schema.MarkSpec.t() | nil

Looks up a mark spec by name, returning nil when unknown.

@spec new(keyword()) :: t()

Builds a schema from a declaration.

Raises ArgumentError when the declaration is inconsistent: an unparsable content expression, a name no node or group answers to, an unknown mark in a node's :marks list, or a missing top node. A schema is developer authored, so an invalid one is a bug rather than a runtime condition.

@spec node_spec(t(), atom()) :: Coelho.Schema.NodeSpec.t() | nil

Looks up a node spec by name, returning nil when unknown.

@spec resolve_mark_name(t(), term()) :: {:ok, atom()} | :error

Resolves a mark type name coming from untrusted input.

@spec resolve_node_name(t(), term()) :: {:ok, atom()} | :error

Resolves a node type name coming from untrusted input.

Never converts to an atom blindly: only names the schema already knows are resolved, so a hostile document cannot grow the atom table.

@spec restrict(
  t(),
  keyword()
) :: t()

Narrows a schema to a subset of its nodes and marks.

An application with several rich text fields usually wants one vocabulary per field — a portal blurb that is paragraphs and four marks, terms and conditions that add headings and lists but only bold and links. Declaring each of them with new/1 means keeping several full schemas consistent by hand; this subtracts from one instead.

Coelho.Schema.restrict(Coelho.Schema.default(),
  nodes: [:paragraph],
  marks: [:bold, :link]
)

Only the keys given are narrowed: leaving :nodes out keeps every node. The top node and the text node are always kept, since a schema without them could not hold a document at all.

Limits are narrowed the same way — a value given here applies only if it is tighter than the parent's. That is what makes the guarantee hold in both directions: a restricted schema never accepts a document its parent would reject.

Raises ArgumentError when a name is not in the parent — asking to keep what is not there is a bug, not a narrowing — and when the narrowing leaves a surviving node referring to something that is gone, such as keeping bullet_list without list_item.

@spec to_json(t()) :: map()

Exports the schema in the shape the browser side consumes to build the matching ProseMirror schema.

Nodes and marks are emitted as ordered pairs rather than objects: node order carries meaning in ProseMirror and map key order does not survive a round trip through Elixir.