@quillmark/svelte 0.12.0 → 0.13.0

package/dist/core/codec/decode.d.ts

@@ -17,3 +17,20 @@ export declare function usvLength(s: string): number;
 export declare function renderContent(rt: Content, schema: Schema): Node;
 /** Decode a `Content` to a PM document under `schema`. */
 export declare function decode(rt: Content, schema: Schema): PMNode;
+/** Whether `rt` decodes under an inline schema with nothing but whitespace dropped:
+ *  upstream's `inline` rule, or one plain line and the empty one a trailing `\n`
+ *  opens. That newline is the one a YAML `|` scalar keeps in a `plaintext` value,
+ *  which upstream refuses (`trailingNewline`) and the inline decode drops. Marks are
+ *  the schema's own business (`plaintextSchema` declares none). */
+export declare function fitsInline(rt: Content): boolean;
+/** Whether `rt` decodes under `plainSchema` losing nothing but its marks, which the
+ *  next commit heals (CODEC §Inline mode): upstream's `isPlain`, asked of the content
+ *  with them set aside. */
+export declare function fitsPlain(rt: Content): boolean;
+/** Whether `rt` decodes under the schema a leaf so declared mounts, losing nothing its
+ *  first commit would store: {@link fitsInline} narrowed, {@link fitsPlain} plain, and
+ *  anything on the block schema. What a leaf held over the rest reads. */
+export declare function fitsLeaf(rt: Content, leaf: {
+    inline: boolean;
+    plaintext: boolean;
+}): boolean;

package/dist/core/codec/decode.js

@@ -10,7 +10,8 @@
 import { DOMSerializer } from 'prosemirror-model';
 import { ISLAND_SLOT, isBlockIsland } from './islands.js';
 import { descriptorOf, markKey, pmMarkFromContent } from './marks.js';
-import { hasMarks, isInlineSchema, takesLineBreak } from './schema.js';
+import { core } from '../lifecycle.js';
+import { hasMarks, isBlockSchema, isInlineSchema, takesLineBreak } from './schema.js';
 /** Code points of `s` (USV units): the iteration granularity the content speaks. */
 export function codePoints(s) {
     return Array.from(s);
@@ -54,6 +55,9 @@ export function decode(rt, schema) {
     if (isInlineSchema(schema)) {
         return decodeInline(rt, schema, lineTexts, starts, marks, cursor);
     }
+    if (!isBlockSchema(schema)) {
+        return decodePlain(rt, schema, lineTexts, starts, marks, cursor);
+    }
     // Build leaves (fold `continues` runs), then nest by container prefix.
     const leaves = [];
     for (let i = 0; i < rt.lines.length; i++) {
@@ -69,13 +73,46 @@ export function decode(rt, schema) {
     const blocks = groupBlocks(schema, leaves, 0, marks, cursor);
     return schema.nodes.doc.create(null, blocks.length ? blocks : schema.nodes.paragraph.create());
 }
-/** Inline / plaintext decode: one paragraph, containers and islands stripped. */
+/** Whether `rt` decodes under an inline schema with nothing but whitespace dropped:
+ *  upstream's `inline` rule, or one plain line and the empty one a trailing `\n`
+ *  opens. That newline is the one a YAML `|` scalar keeps in a `plaintext` value,
+ *  which upstream refuses (`trailingNewline`) and the inline decode drops. Marks are
+ *  the schema's own business (`plaintextSchema` declares none). */
+export function fitsInline(rt) {
+    if (core().isInline(rt))
+        return true;
+    const plain = (line) => line.kind === 'para' && line.containers.length === 0;
+    return (rt.islands.length === 0 &&
+        rt.lines.length === 2 &&
+        rt.lines.every(plain) &&
+        !rt.lines[1].continues &&
+        rt.text.endsWith('\n'));
+}
+/** Whether `rt` decodes under `plainSchema` losing nothing but its marks, which the
+ *  next commit heals (CODEC §Inline mode): upstream's `isPlain`, asked of the content
+ *  with them set aside. */
+export function fitsPlain(rt) {
+    return core().isPlain({ ...rt, marks: [] });
+}
+/** Whether `rt` decodes under the schema a leaf so declared mounts, losing nothing its
+ *  first commit would store: {@link fitsInline} narrowed, {@link fitsPlain} plain, and
+ *  anything on the block schema. What a leaf held over the rest reads. */
+export function fitsLeaf(rt, leaf) {
+    if (leaf.inline)
+        return fitsInline(rt);
+    return !leaf.plaintext || fitsPlain(rt);
+}
+/** Inline decode: one paragraph, containers and islands stripped. */
 function decodeInline(rt, schema, lineTexts, starts, marks, cursor) {
     // An inline field is single-line; join any stray lines with a space (no
-    // hard_break node exists in this schema). Islands are not representable inline:
-    // the slot char is dropped and its entry skipped.
+    // hard_break node exists in this schema). The empty line a trailing `\n` opens is
+    // dropped rather than joined, so a first edit stores no space nobody typed. Islands
+    // are not representable inline: the slot char is dropped and its entry skipped.
     const inline = [];
+    const last = lineTexts.length - 1;
     for (let i = 0; i < lineTexts.length; i++) {
+        if (i > 0 && i === last && lineTexts[i] === '')
+            break;
         if (i > 0)
             inline.push(schema.text(' '));
         inline.push(...buildInline(schema, lineTexts[i], starts[i], marks, cursor, true));
@@ -83,6 +120,22 @@ function decodeInline(rt, schema, lineTexts, starts, marks, cursor) {
     const para = schema.nodes.paragraph.create(null, inline);
     return schema.nodes.doc.create(null, para);
 }
+/** Plain decode: a `continues` line is a `hard_break` in the paragraph above and every
+ *  other line opens one. A line's kind and containers and every island have no node
+ *  here and are dropped, so a content {@link fitsPlain} refuses opens flattened. */
+function decodePlain(rt, schema, lineTexts, starts, marks, cursor) {
+    const paras = [];
+    for (let i = 0; i < rt.lines.length; i++) {
+        const inline = buildInline(schema, lineTexts[i] ?? '', starts[i], marks, cursor, true);
+        const open = paras[paras.length - 1];
+        if (rt.lines[i].continues && open)
+            open.push(schema.nodes.hard_break.create(), ...inline);
+        else
+            paras.push(inline);
+    }
+    const blocks = paras.map((inline) => schema.nodes.paragraph.create(null, inline));
+    return schema.nodes.doc.create(null, blocks.length ? blocks : schema.nodes.paragraph.create());
+}
 /** Nest a run of leaves that share a `depth`-length container prefix into blocks. */
 function groupBlocks(schema, leaves, depth, marks, cursor) {
     const out = [];

package/dist/core/codec/field.d.ts

@@ -1,4 +1,4 @@
-import type { Schema } from 'prosemirror-model';
+import { type Schema } from 'prosemirror-model';
 import { Plugin } from 'prosemirror-state';
 import { EditorView } from 'prosemirror-view';
 import type { Document, Content, Addr, Quill } from '@quillmark/wasm';
@@ -14,11 +14,24 @@ export interface CreateFieldOpts {
     quill: Quill;
     addr: Addr;
     container: HTMLElement;
-    /** Constrained single-textblock schema (a `richtext(inline)` field). */
+    /** Constrained single-textblock schema (a field declaring `inline`). */
     inline?: boolean;
-    /** The mark-free inline schema (a `plaintext` field): literal text, no formatting
-     *  and no anchors. Implies `inline`. */
+    /** A mark-free schema (a `plaintext` field): literal text, no formatting and no
+     *  anchors, in paragraphs and hard breaks or, with `inline`, one textblock. */
     plaintext?: boolean;
+    /** The id of the note the caller draws inside `container` for a held leaf →
+     *  `aria-describedby` while it holds. */
+    heldNoteId?: string;
+    /**
+     * Fired when the leaf holds or releases, and at mount when it mounts held. A leaf
+     * declaring `inline`, or a `plaintext` one, is held over a value its schema cannot
+     * hold (`fitsLeaf`, upstream's `isInline` and `isPlain`): the decode would join lines
+     * and drop containers and islands for the first commit to store. A held leaf draws
+     * its content on the block schema, read-only, and commits nothing. Judged of the value
+     * each mount and re-hydrate reads, so {@link FieldController.applyExternal} is what
+     * re-evaluates it.
+     */
+    onHold?(held: boolean): void;
     /** Suppress the markdown-shorthand input rules. */
     noInputRules?: boolean;
     /** The island chrome's wording, read live (per render) so a consumer swapping
@@ -46,11 +59,28 @@ export interface CreateFieldOpts {
     labelledBy?: string;
     /** The parked `description` → `aria-describedby`; announced after the name. */
     describedBy?: string;
-    /** Ghost text shown on the empty leaf: the resolved `default:` a field ghosts,
-     * or a body's invitation. The initial value; {@link
-     * FieldController.setPlaceholder} moves it after mount. Empty/absent
-     * shows no ghost. */
+    /**
+     * The resolved `default:` where it prints: the content an unset field's leaf holds,
+     * marked `data-default` on the editable for the default rung. Nothing is written
+     * until an edit, which commits the whole leaf as authored: the default taken, with
+     * the edit in it. The initial value; {@link FieldController.setFallback} moves it
+     * after mount.
+     */
+    fallback?: Content;
+    /** Ghost text shown on the empty leaf: the `none` an unset optional field prints, or
+     * a body's invitation. The initial value; {@link FieldController.setPlaceholder}
+     * moves it after mount. Empty/absent shows no ghost. */
     placeholder?: string;
+    /** The placeholder is what the unset field prints, so it goes at the leaf's first
+     * edit: the edit answers the field, and emptied the leaf holds an empty answer, which
+     * prints empty. Absent, the placeholder is an invitation (a body's) and returns
+     * whenever the leaf is empty. */
+    placeholderUntilEdit?: boolean;
+    /** Ghost text shown on the empty leaf until its first edit: an unset field's
+     * `example:`, at rest where there is no placeholder and in the placeholder's stead
+     * while the leaf holds the focus. The initial value; {@link FieldController.setExample}
+     * moves it after mount. */
+    example?: string;
     onFocus?(addr: Addr): void;
     /** Fired with the new USV caret after an edit or a selection move. */
     onCaretMove?(addr: Addr, pos: number): void;
@@ -60,7 +90,8 @@ export interface CreateFieldOpts {
      * move, so a host driving a recompile off it recompiles on every arrow key.
      *
      * Fires for every commit regardless of which branch it took (`applyChange`, the
-     * first-edit `overwrite`, the fallback `overwrite`) and for an anchor mutation,
+     * first-edit `overwrite`, the fallback `overwrite`, a `plaintext` leaf's typed
+     * write) and for an anchor mutation,
      * which changes no text. A commit that failed outright (`commit-lost`) does not
      * fire it: nothing landed.
      */
@@ -75,7 +106,8 @@ export interface FieldController {
     readonly el: HTMLElement;
     /** Place the caret at USV `pos` (preview onPick → usvToPM → here). */
     setCaret(pos: number): void;
-    /** External content change → re-hydrate this leaf (gated by reconcile). */
+    /** External content change → re-hydrate this leaf (gated by reconcile), and
+     *  re-evaluate its hold against the value now stored. */
     applyExternal(): void;
     /**
      * Move the empty-leaf ghost after mount: a card retyped to another kind takes
@@ -86,6 +118,12 @@ export interface FieldController {
      * a transaction would fire `onCaretMove` at a moment the caret did not move.
      */
     setPlaceholder(text: string | undefined): void;
+    /** Move the example ghost after mount, the way {@link setPlaceholder} moves the
+     *  other one. */
+    setExample(text: string | undefined): void;
+    /** Move the default an unset leaf holds after mount: a retype or a quill swap
+     *  re-seats an unset leaf on the new kind's default, and leaves a written one be. */
+    setFallback(content: Content | undefined): void;
     focus(): void;
     /** The current stored content for this addr (for tests / reconcile). */
     getContent(): Content;
@@ -146,10 +184,17 @@ export declare function proseAttributes(opts: {
     labelledBy?: string;
     describedBy?: string;
 }): Record<string, string> | undefined;
+/** A held leaf's attributes, described by its note as well. A non-editable view is no
+ *  textbox to assistive tech or to Tab, so a held leaf states both itself. */
+export declare function heldAttributes(opts: {
+    label?: string;
+    labelledBy?: string;
+    describedBy?: string;
+}, noteId: string | undefined): Record<string, string>;
 export declare function createField(opts: CreateFieldOpts): FieldController;
 /**
  * The prose-leaf plugin stack (VISUAL_EDITOR §Surface): shared by
- * {@link createField} and the by-value inline editor (`ProseValue`), so the two
+ * {@link createField} and the by-value editor (`ProseValue`), so the two
  * never fork the keymap/plugin ordering. History first, then any leaf-specific
  * plugins (`afterHistory`: the addressed leaf passes its anchor-position plugin;
  * a by-value leaf passes none), then {@link linebreakPlugin}, which normalizes what
@@ -158,10 +203,10 @@ export declare function createField(opts: CreateFieldOpts): FieldController;
  * shapes: the gap cursor, {@link pastAtomPlugin}, and the island paste pass
  * (`islands.ts`).
  *
- * Every mark-shaped plugin reads the schema rather than a flag: over
- * `plaintextSchema` the shorthand rules build nothing (each is guarded on its mark
- * type) and the toggles bind no key, so a `**bold**` keeps the delimiters its author
- * typed without a second rule saying so.
+ * Every mark-shaped plugin reads the schema rather than a flag: over either plaintext
+ * schema the shorthand rules build nothing (each is guarded on its mark type) and the
+ * toggles bind no key, so a `**bold**` keeps the delimiters its author typed without
+ * a second rule saying so.
  */
 export declare function proseLeafPlugins(schema: Schema, opts: {
     inline: boolean;
@@ -173,5 +218,9 @@ export declare function proseLeafPlugins(schema: Schema, opts: {
      *  ({@link FieldController.setPlaceholder}), and a re-hydration rebuilds this
      *  stack, so the plugin must ask rather than hold. */
     placeholder?: () => string | undefined;
+    /** {@link CreateFieldOpts.placeholderUntilEdit}. */
+    placeholderUntilEdit?: boolean;
+    /** The focused leaf's ghost, read live for the same reason. */
+    example?: () => string | undefined;
     afterHistory?: Plugin[];
 }): Plugin[];