@relyio/sdk 0.10.0 → 0.12.0

package/dist/rich-text.d-rKmpgdGd.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Rich text's stored and served value: a tree we define (ADR 0013, REL-1803).
+ *
+ * A `richText` field holds one {@link RichTextValue} per locale — a documented, **versioned** JSON
+ * tree shaped like the editor's document: a quote and a list item hold blocks, lists nest, a text
+ * run names its marks. Every node carries `_type`; every node but a text run carries `_key`, unique
+ * within the field. It is not Portable Text (flat: a quote of two paragraphs becomes two quotes,
+ * nested lists become levels) and not TipTap's JSON (TipTap's node names and attributes would be
+ * our public API, and a TipTap upgrade a breaking change for customers). The vocabulary is written
+ * down for readers in `devtools/docs/guide/schema/field-types/rich-text-format.md`; this module is
+ * its one definition in code.
+ *
+ * **The version grows by addition.** {@link RICH_TEXT_VERSION} changes only when a node, a mark or
+ * an attribute is renamed, removed or reshaped. A new node type, a new mark, a new `list` style or a
+ * new optional attribute is not a version change — the docs set's built-ins (REL-1805: tables, task
+ * lists, code groups with tabs, highlight, sub- and superscript) arrived inside version 1, and P3b's
+ * entry links and declared blocks will, so a reader must treat a `_type` it does not know as content
+ * it cannot draw rather than as an error.
+ *
+ * **A field narrows the docs set** (REL-1805): its config's `structure`, `marks` and `multiline` are
+ * read by {@link richTextNarrowingOf}, held to on every write by {@link richTextNarrowingProblems}
+ * (the validation document's `x-richTextNarrowing` keyword), enforced in the editor by
+ * `@relyio/studio-core`'s `RichTextPolicy`, and applied by schema adaptation through
+ * {@link narrowRichText} when a field is narrowed over content it no longer allows.
+ *
+ * Who uses it: the projection writes and reads a live document by it (`@relyio/entry-projection`'s
+ * `./blocks`), the validation document holds a written value to it ({@link richTextProblems}), the
+ * write core keys a written value ({@link keyRichText}), the index embeds its text
+ * ({@link richTextPlainText}), and `@relyio/sdk` types a read by it (the types only, build-inlined
+ * through the package root).
+ *
+ * Dependency-free like `./declaration` (`__tests__/dependency-free.test.ts`): no import at all.
+ */
+/** The format's version. The stored value carries it, so a reader knows which vocabulary it holds. */
+declare const RICH_TEXT_VERSION = 1;
+/** The root's `_type`: what a value of a `richText` field is. */
+declare const RICH_TEXT_TYPE = "richText";
+/** A rich-text field's value: the root of the tree. The root is the field, so it has no `_key`. */
+interface RichTextValue {
+    readonly _type: typeof RICH_TEXT_TYPE;
+    readonly version: typeof RICH_TEXT_VERSION;
+    readonly children: readonly RichTextBlock[];
+}
+/** What every node but a text run carries: its identity within the field (design decision 10). */
+interface RichTextKeyed {
+    readonly _key: string;
+}
+/** A paragraph: inline content. */
+interface RichTextParagraph extends RichTextKeyed {
+    readonly _type: 'paragraph';
+    readonly children: readonly RichTextInline[];
+}
+/** The heading levels, as numbers. */
+declare const RICH_TEXT_HEADING_LEVELS: readonly [1, 2, 3, 4, 5, 6];
+/** A heading of `level` 1 to 6: inline content. */
+interface RichTextHeading extends RichTextKeyed {
+    readonly _type: 'heading';
+    readonly level: (typeof RICH_TEXT_HEADING_LEVELS)[number];
+    readonly children: readonly RichTextInline[];
+}
+/** A quote: one block or more — a quote of two paragraphs is one quote. */
+interface RichTextQuote extends RichTextKeyed {
+    readonly _type: 'quote';
+    readonly children: readonly RichTextBlock[];
+}
+/**
+ * The list styles. Version 1 held `bullet` and `numbered`; REL-1805 added `task`, whose items each
+ * carry `checked`, without a version change.
+ */
+declare const RICH_TEXT_LIST_STYLES: readonly ['bullet', 'numbered', 'task'];
+type RichTextListStyle = (typeof RICH_TEXT_LIST_STYLES)[number];
+/**
+ * A list: one item or more. `start` is a numbered list's first number, present only when it is not
+ * `1`. Lists nest: an item holds blocks, and a list is a block.
+ */
+interface RichTextList extends RichTextKeyed {
+    readonly _type: 'list';
+    readonly style: RichTextListStyle;
+    readonly start?: number;
+    readonly children: readonly RichTextListItem[];
+}
+/**
+ * A list's item: blocks, the first of them a paragraph (the editor's model, `paragraph block*`).
+ * `checked` is a task list's item's, and present on every one of them: whether its task is done.
+ * An item of a bullet or a numbered list carries none.
+ */
+interface RichTextListItem extends RichTextKeyed {
+    readonly _type: 'listItem';
+    readonly checked?: boolean;
+    readonly children: readonly RichTextBlock[];
+}
+/** The lines of a file a code block is, 1-based and inclusive: the docs' code citations. */
+interface RichTextCodeLines {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * A block of code: its text exactly, newlines included, with no marks, and the `language` it is
+ * written in when one is named. Standing in a code group it is one of the group's tabs, and `label`
+ * is the tab's name; `filename` is the file it shows and `lines` which of that file's lines. All
+ * three are optional, alone or in a group (REL-1805).
+ */
+interface RichTextCodeBlock extends RichTextKeyed {
+    readonly _type: 'codeBlock';
+    readonly language?: string;
+    readonly label?: string;
+    readonly filename?: string;
+    readonly lines?: RichTextCodeLines;
+    readonly text: string;
+}
+/**
+ * Code with tabs: one code block or more, each a tab — the same snippet for another language,
+ * package manager or client (REL-1805). Each tab's text is its own, so two people typing in two tabs
+ * keep both. A `code` field holds this node as its value (REL-1806).
+ */
+interface RichTextCodeGroup extends RichTextKeyed {
+    readonly _type: 'codeGroup';
+    readonly children: readonly RichTextCodeBlock[];
+}
+/** How a table cell's text is aligned. Absent is the reader's default. */
+declare const RICH_TEXT_CELL_ALIGNMENTS: readonly ['left', 'center', 'right'];
+type RichTextCellAlignment = (typeof RICH_TEXT_CELL_ALIGNMENTS)[number];
+/**
+ * A table: one row or more, every row holding the same number of cells (REL-1805). `headerRow` is
+ * present, `true`, when the first row is the table's header. Cells hold formatted text, and nothing
+ * merges cells. A `table` field holds this node as its value (REL-1806).
+ */
+interface RichTextTable extends RichTextKeyed {
+    readonly _type: 'table';
+    readonly headerRow?: true;
+    readonly children: readonly RichTextTableRow[];
+}
+/** A table's row: one cell or more. */
+interface RichTextTableRow extends RichTextKeyed {
+    readonly _type: 'tableRow';
+    readonly children: readonly RichTextTableCell[];
+}
+/** A table's cell: one paragraph or more of formatted text, and its alignment when one is set. */
+interface RichTextTableCell extends RichTextKeyed {
+    readonly _type: 'tableCell';
+    readonly align?: RichTextCellAlignment;
+    readonly children: readonly RichTextParagraph[];
+}
+/** A horizontal rule between blocks. */
+interface RichTextDivider extends RichTextKeyed {
+    readonly _type: 'divider';
+}
+/** A block: what a field, a quote and a list item hold. */
+type RichTextBlock = RichTextParagraph | RichTextHeading | RichTextQuote | RichTextList | RichTextCodeBlock | RichTextCodeGroup | RichTextTable | RichTextDivider;
+/**
+ * A run of text: its characters and the marks on all of them. `marks` is absent when there are
+ * none, and in {@link RICH_TEXT_MARK_TYPES}' order when there are, each type at most once. A text
+ * run has no `_key`: it is not addressable apart from the block that holds it, and the live document
+ * gives it no identity to keep.
+ */
+interface RichTextSpan {
+    readonly _type: 'text';
+    readonly text: string;
+    readonly marks?: readonly RichTextMark[];
+}
+/** A line break inside a paragraph or a heading. */
+interface RichTextLineBreak extends RichTextKeyed {
+    readonly _type: 'lineBreak';
+}
+/** Inline content: what a paragraph and a heading hold. */
+type RichTextInline = RichTextSpan | RichTextLineBreak;
+/**
+ * The marks, in the order a run holds them: the link first, so a renderer that nests marks in this
+ * order wraps the formatting in the anchor. REL-1805 added highlight, subscript and superscript
+ * after the first six, and P3b adds the entry link, without a version change.
+ */
+declare const RICH_TEXT_MARK_TYPES: readonly ['link', 'bold', 'italic', 'underline', 'strike', 'code', 'highlight', 'subscript', 'superscript'];
+type RichTextMarkType = (typeof RICH_TEXT_MARK_TYPES)[number];
+/**
+ * A link to a URL. `href` is all a reader is given: whether it opens a new tab and which `rel` it
+ * carries are the site's rendering decisions, not content (the editor's defaults for them are not
+ * stored), and a link's title was dropped before the tree existed (REL-1942).
+ */
+interface RichTextLinkMark {
+    readonly _type: 'link';
+    readonly href: string;
+}
+/**
+ * A mark: formatting by name, or a link. `code` holds no other mark beside it, and `subscript` and
+ * `superscript` are never on one run together.
+ */
+type RichTextMark = RichTextLinkMark | {
+    readonly _type: Exclude<RichTextMarkType, 'link'>;
+};
+/** Any node of the tree below the root. */
+type RichTextNode = RichTextBlock | RichTextListItem | RichTextTableRow | RichTextTableCell | RichTextInline;
+/**
+ * The built-in blocks a field's `structure` names (REL-1805): every block but the paragraph, which
+ * every field holds. A list is named by its style, since a field may want bullets and no tasks; a
+ * code group's tabs come with the group, whether or not `codeBlock` is named.
+ */
+declare const RICH_TEXT_STRUCTURES: readonly ['heading', 'quote', 'bulletList', 'numberedList', 'taskList', 'codeBlock', 'codeGroup', 'table', 'divider'];
+type RichTextStructure = (typeof RICH_TEXT_STRUCTURES)[number];
+
+export type { RichTextBlock as R, RichTextCellAlignment as a, RichTextCodeBlock as b, RichTextCodeGroup as c, RichTextCodeLines as d, RichTextDivider as e, RichTextHeading as f, RichTextInline as g, RichTextLineBreak as h, RichTextLinkMark as i, RichTextList as j, RichTextListItem as k, RichTextListStyle as l, RichTextMark as m, RichTextMarkType as n, RichTextNode as o, RichTextParagraph as p, RichTextQuote as q, RichTextSpan as r, RichTextStructure as s, RichTextTable as t, RichTextTableCell as u, RichTextTableRow as v, RichTextValue as w };

package/dist/schema/index.cjs

@@ -1,145 +1,141 @@
 'use strict';
 
-var chunk2HP566NI_cjs = require('../chunk-2HP566NI.cjs');
+var chunk3MSFWXQL_cjs = require('../chunk-3MSFWXQL.cjs');
 require('../chunk-MWMSFIWN.cjs');
 
 
 
 Object.defineProperty(exports, "BUILT_IN_ROLES", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.BUILT_IN_ROLES; }
+  get: function () { return chunk3MSFWXQL_cjs.BUILT_IN_ROLES; }
 });
 Object.defineProperty(exports, "BUILT_IN_ROLE_ACTIONS", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.BUILT_IN_ROLE_ACTIONS; }
+  get: function () { return chunk3MSFWXQL_cjs.BUILT_IN_ROLE_ACTIONS; }
 });
 Object.defineProperty(exports, "ROLE_ACTIONS", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.ROLE_ACTIONS; }
+  get: function () { return chunk3MSFWXQL_cjs.ROLE_ACTIONS; }
 });
 Object.defineProperty(exports, "buildFallbackChain", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.buildFallbackChain; }
+  get: function () { return chunk3MSFWXQL_cjs.buildFallbackChain; }
 });
 Object.defineProperty(exports, "defineAssetType", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineAssetType; }
-});
-Object.defineProperty(exports, "defineComponent", {
-  enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineComponent; }
+  get: function () { return chunk3MSFWXQL_cjs.defineAssetType; }
 });
 Object.defineProperty(exports, "defineContentType", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineContentType; }
+  get: function () { return chunk3MSFWXQL_cjs.defineContentType; }
 });
 Object.defineProperty(exports, "defineContentTypeWorkflow", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineContentTypeWorkflow; }
+  get: function () { return chunk3MSFWXQL_cjs.defineContentTypeWorkflow; }
 });
 Object.defineProperty(exports, "defineLocale", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineLocale; }
+  get: function () { return chunk3MSFWXQL_cjs.defineLocale; }
 });
 Object.defineProperty(exports, "defineQuery", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineQuery; }
+  get: function () { return chunk3MSFWXQL_cjs.defineQuery; }
 });
 Object.defineProperty(exports, "defineRole", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineRole; }
+  get: function () { return chunk3MSFWXQL_cjs.defineRole; }
 });
 Object.defineProperty(exports, "defineSchema", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineSchema; }
+  get: function () { return chunk3MSFWXQL_cjs.defineSchema; }
 });
 Object.defineProperty(exports, "defineSettingsGroup", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineSettingsGroup; }
+  get: function () { return chunk3MSFWXQL_cjs.defineSettingsGroup; }
 });
 Object.defineProperty(exports, "defineSingleton", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineSingleton; }
+  get: function () { return chunk3MSFWXQL_cjs.defineSingleton; }
 });
 Object.defineProperty(exports, "defineSingletonContentType", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineSingletonContentType; }
+  get: function () { return chunk3MSFWXQL_cjs.defineSingletonContentType; }
 });
 Object.defineProperty(exports, "defineView", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineView; }
+  get: function () { return chunk3MSFWXQL_cjs.defineView; }
 });
 Object.defineProperty(exports, "defineWorkflow", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineWorkflow; }
+  get: function () { return chunk3MSFWXQL_cjs.defineWorkflow; }
 });
 Object.defineProperty(exports, "defineWorkflowStage", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.defineWorkflowStage; }
+  get: function () { return chunk3MSFWXQL_cjs.defineWorkflowStage; }
 });
 Object.defineProperty(exports, "fields", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.fields; }
+  get: function () { return chunk3MSFWXQL_cjs.fields; }
 });
 Object.defineProperty(exports, "fieldset", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.fieldset; }
+  get: function () { return chunk3MSFWXQL_cjs.fieldset; }
 });
 Object.defineProperty(exports, "findDefaultLocale", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.findDefaultLocale; }
+  get: function () { return chunk3MSFWXQL_cjs.findDefaultLocale; }
 });
 Object.defineProperty(exports, "findWorkflowStage", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.findWorkflowStage; }
+  get: function () { return chunk3MSFWXQL_cjs.findWorkflowStage; }
 });
 Object.defineProperty(exports, "getActiveLocales", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.getActiveLocales; }
+  get: function () { return chunk3MSFWXQL_cjs.getActiveLocales; }
 });
 Object.defineProperty(exports, "getBuiltInRoleActions", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.getBuiltInRoleActions; }
+  get: function () { return chunk3MSFWXQL_cjs.getBuiltInRoleActions; }
 });
 Object.defineProperty(exports, "getFirstWorkflowStage", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.getFirstWorkflowStage; }
+  get: function () { return chunk3MSFWXQL_cjs.getFirstWorkflowStage; }
 });
 Object.defineProperty(exports, "getLocaleCodes", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.getLocaleCodes; }
+  get: function () { return chunk3MSFWXQL_cjs.getLocaleCodes; }
 });
 Object.defineProperty(exports, "getNextWorkflowStage", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.getNextWorkflowStage; }
+  get: function () { return chunk3MSFWXQL_cjs.getNextWorkflowStage; }
 });
 Object.defineProperty(exports, "getWorkflowStageIds", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.getWorkflowStageIds; }
+  get: function () { return chunk3MSFWXQL_cjs.getWorkflowStageIds; }
 });
 Object.defineProperty(exports, "isBuiltInRole", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.isBuiltInRole; }
+  get: function () { return chunk3MSFWXQL_cjs.isBuiltInRole; }
 });
 Object.defineProperty(exports, "isFinalWorkflowStage", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.isFinalWorkflowStage; }
+  get: function () { return chunk3MSFWXQL_cjs.isFinalWorkflowStage; }
 });
 Object.defineProperty(exports, "isLocaleDefinition", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.isLocaleDefinition; }
+  get: function () { return chunk3MSFWXQL_cjs.isLocaleDefinition; }
 });
 Object.defineProperty(exports, "isRoleDefinition", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.isRoleDefinition; }
+  get: function () { return chunk3MSFWXQL_cjs.isRoleDefinition; }
 });
 Object.defineProperty(exports, "isWorkflowDefinition", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.isWorkflowDefinition; }
+  get: function () { return chunk3MSFWXQL_cjs.isWorkflowDefinition; }
 });
 Object.defineProperty(exports, "isWorkflowStageDefinition", {
   enumerable: true,
-  get: function () { return chunk2HP566NI_cjs.isWorkflowStageDefinition; }
+  get: function () { return chunk3MSFWXQL_cjs.isWorkflowStageDefinition; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map