svedit 0.12.0 → 0.14.0

package/README.md

@@ -1,9 +1,9 @@
 # Svedit
 
-Svedit (think Svelte Edit) is a tiny library for building editable websites in Svelte. Model content in JSON, render it with custom components, and let site owners **edit directly in the layout** — no CMS needed.
+Svedit is Editing for Svelte. It offers structured, full-canvas content editing. Model content in JSON, render it with custom components, and **edit it directly in the layout**.
 
 - Try the [Svedit demo](https://svedit.dev) — watch the debug output at the bottom of the page
-- Try [Editable Website](https://editable.website) — utilizes Svedit to enable CMS-free editable websites
+- Try [Editable](https://editable.website) — build Svelte websites you can edit on the page
 
 ## Why Svedit?
 
@@ -16,13 +16,13 @@ The fastest way to get started is to clone the `hello-svedit` template and turn
 ```bash
 git clone https://github.com/michael/hello-svedit
 cd hello-svedit
-npm install
-npm run dev
+pnpm install
+pnpm dev
 ```
 
-Now make it your own. The next thing you probably want to do is define your own [node types](./src/routes/create_demo_session.js), add a [Toolbar](./src/routes/components/Toolbar.svelte), and render custom [Overlays](./src/routes/components/Overlays.svelte). For that just get inspired by the [Svedit demo code](./src/routes).
+Now make it your own. The next thing you probably want to do is define your own [node types](./src/routes/demo_schema.ts), add a [Toolbar](./src/routes/components/Toolbar.svelte), and render custom [Overlays](./src/routes/components/Overlays.svelte). For that just get inspired by the [Svedit demo code](./src/routes).
 
-You can also install Svedit into an existing SvelteKit project with `npm install svedit`, but you'll need to set up the session, schema, config, and components yourself. See the [hello-svedit repo](https://github.com/michael/hello-svedit) or this repo's [`src/routes`](./src/routes) for reference.
+You can also install Svedit into an existing SvelteKit project with `pnpm add svedit`, but you'll need to set up the session, schema, config, and components yourself. See the [hello-svedit repo](https://github.com/michael/hello-svedit) or this repo's [`src/routes`](./src/routes) for reference.
 
 ## Principles
 
@@ -117,9 +117,9 @@ flowchart TD
 
 Properties of nodes can hold values:
 
-- `string`: A good old JavaScript string
+- `string`: A good old JavaScript string. Use optional `values` to restrict it to an ordered set of allowed strings.
 - `number`: Just like a number in JavaScript
-- `integer`: A number for which Number.isInteger(number) returns true
+- `integer`: A number for which Number.isInteger(number) returns true. Optional `min` and `max` bounds are inclusive.
 - `boolean`: true or false
 - `datetime`: A date/time string parseable by `Date.parse()`
 - `string_array`: An array of strings
@@ -409,7 +409,11 @@ const document_schema = {
 	paragraph: {
 		kind: 'text',
 		properties: {
-			layout: { type: 'integer', default: 1 },
+			layout: {
+				type: 'string',
+				values: ['image-left', 'image-right', 'stacked'],
+				default: 'image-left'
+			},
 			content: {
 				type: 'text',
 				allow_newlines: true
@@ -422,7 +426,7 @@ const migrated_doc = fill_document_defaults(existing_doc, document_schema);
 const session = new Session(document_schema, migrated_doc, config);
 ```
 
-This only fills properties that are missing. Explicit schema `default` values are used when present; otherwise Svedit uses built-in defaults for value types such as strings, numbers, booleans, arrays, `node_array`, and `text`. Existing values are preserved, and the original document object is not mutated.
+This only fills properties that are missing. Explicit schema `default` values are used when present; otherwise Svedit uses built-in defaults for value types such as strings, numbers, booleans, arrays, `node_array`, and `text`. Constraints such as `values`, `min`, and `max` do not change those defaults, so declare an explicit `default` when the built-in value would be invalid. Existing values are preserved, and the original document object is not mutated.
 
 Defaults make it safe to add new defaultable properties, but they are not a replacement for real document migrations. If you rename a property, remove a property, split one property into several, change node types, or need to transform existing data, write your own migration first and use `fill_document_defaults` only as a helper where appropriate.
 
@@ -430,17 +434,17 @@ Defaults make it safe to add new defaultable properties, but they are not a repl
 
 ## Config
 
-Documents need a config object that tells Svedit how to render and manipulate your content. See the full example in [`src/routes/create_demo_session.js`](src/routes/create_demo_session.js).
+Documents need a config object that tells Svedit how to render and manipulate your content. See the full example in [`src/routes/demo_config.ts`](src/routes/demo_config.ts).
 
 Two optional hooks are especially useful when integrating custom media workflows:
 
 - `handle_media_paste(session, pasted_media)`  
   Called when media is pasted. You can upload/process files, replace an existing media property, or return a node payload to insert new content.  
-  See example implementation in [`src/routes/create_demo_session.js`](src/routes/create_demo_session.js).
+  See example implementation in [`src/routes/demo_config.ts`](src/routes/demo_config.ts).
 
 - `handle_property_deletion(session, path)`  
   Called when deleting/cutting a property selection. Use it to define app-specific reset behavior (for example clearing an image property or resetting a referenced media node).  
-  See example implementation in [`src/routes/create_demo_session.js`](src/routes/create_demo_session.js).
+  See example implementation in [`src/routes/demo_config.ts`](src/routes/demo_config.ts).
 
 ```js
 const session_config = {
@@ -477,6 +481,7 @@ const session_config = {
 - **`system_components`** - Optional overrides for internal editor components and a slot for your own overlays:
   - `overlays` — A Svelte component rendered inside `<Svedit>` but outside the content canvas. Use it to add floating UI like link editors, image toolbars, or annotation popovers that appear near the current selection. See [`src/routes/components/Overlays.svelte`](src/routes/components/Overlays.svelte) for an example.
   - `node_gap`, `node_gap_markers`, `node_selection_markers` — Override the default system components if you need custom visuals for node gaps or selection indicators.
+  - `node_gap_tools` — A component rendered inside the active node gap marker, next to the caret. Use it for gap-scoped tools like an insert button: it inherits the `--row` orientation variable from the node array, and it appears and disappears together with the caret. Receives `{ path, offset, is_first, is_last }` (see the `NodeGapToolsProps` type). The marker has `pointer-events: none`, so interactive tools must set `pointer-events: auto`. See [`src/routes/components/GapInsertTool.svelte`](src/routes/components/GapInsertTool.svelte) for an example.
 - **`inserters`** - Functions that create blank nodes of each type and set up the selection
 - **`create_commands_and_keymap`** - Factory function that creates commands and keybindings for an editor instance
 - **`handle_image_paste`** - Optional handler for image paste events
@@ -653,7 +658,11 @@ function insert_heading(tr) {
 
 	// Create and insert a heading node
 	const heading_id = tr.generate_id();
-	tr.create({ id: heading_id, type: 'heading', content: { content: '', marks: [], annotations: [] } });
+	tr.create({
+		id: heading_id,
+		type: 'heading',
+		content: { content: '', marks: [], annotations: [] }
+	});
 	tr.insert_nodes([heading_id]);
 
 	return true;
@@ -676,7 +685,11 @@ session.apply(tr); // Apply atomically
 
 ```js
 // Create a new node (must include all required properties from schema)
-tr.create({ id: 'paragraph_1', type: 'paragraph', content: { content: '', marks: [], annotations: [] } });
+tr.create({
+	id: 'paragraph_1',
+	type: 'paragraph',
+	content: { content: '', marks: [], annotations: [] }
+});
 
 // Delete a node (cascades to unreferenced child nodes)
 tr.delete('paragraph_26');
@@ -816,7 +829,7 @@ Svedit provides several [core commands](src/lib/Command.svelte.js) out of the bo
 
 #### Using document commands
 
-Commands are created by passing them a context object from the Svedit component. See a complete example in [`src/routes/create_demo_session.js`](src/routes/create_demo_session.js) in the `create_commands_and_keymap` configuration function:
+Commands are created by passing them a context object from the Svedit component. See a complete example in [`src/routes/demo_config.ts`](src/routes/demo_config.ts) in the `create_commands_and_keymap` configuration function:
 
 ```js
 create_commands_and_keymap: (context) => {
@@ -1162,7 +1175,7 @@ For styling, you usually don't need the props at all: `<Node>` adds range classe
 
 ```css
 .anno-marker {
-	background: color-mix(in oklch, var(--app-primary-fill) 13%, transparent);
+	background: color-mix(in oklch, var(--accent) 13%, transparent);
 }
 ```
 
@@ -1440,10 +1453,10 @@ The source code is compact and readable — less than 3000 LOC across a handful
 
 ## Developing Svedit
 
-Once you've cloned the Svedit repository and installed dependencies with `npm install`, start a development server:
+Once you've cloned the Svedit repository and installed dependencies with `pnpm install`, start a development server:
 
 ```bash
-npm run dev
+pnpm dev
 ```
 
 ## Building
@@ -1451,10 +1464,10 @@ npm run dev
 To create a production version of your app:
 
 ```bash
-npm run build
+pnpm build
 ```
 
-You can preview the production build with `npm run preview`.
+You can preview the production build with `pnpm preview`.
 
 ## Contributing
 
@@ -1481,4 +1494,4 @@ It's still early. Expect bugs. Expect missing features. Expect the need for more
 
 ## Credits
 
-Svedit is led by [Michael Aufreiter](https://michaelaufreiter.com) with guidance and support from [Johannes Mutter](https://mutter.co).
+Svedit is made by [Michael Aufreiter](https://michaelaufreiter.com) (maintainer) and [Johannes Mutter](https://mutter.co) (design and engineering). Illustrations and icons are hand-crafted by Johannes.

package/dist/Command.svelte.d.ts

@@ -1,3 +1,9 @@
+import type Session from './Session.svelte.js';
+type CommandSession = Session<any>;
+export type CommandContext = {
+    session: CommandSession;
+    editable: boolean;
+};
 /**
  * Base class for commands that can be executed in response to user actions
  * like keyboard shortcuts, menu items, or toolbar buttons.
@@ -21,53 +27,50 @@
  * ```
  */
 export default class Command {
-    /**
-     * Creates a new Command instance.
-     *
-     * @param {any} context - The context object providing access to application state
-     */
-    constructor(context: any);
+    context: CommandContext;
     /**
      * Derived state that indicates if the command is disabled.
      * Automatically computed from is_enabled().
      */
     disabled: boolean;
-    context: any;
+    /**
+     * Creates a new Command instance.
+     *
+     * @param context - The context object providing access to application state
+     */
+    constructor(context: CommandContext);
     /**
      * Determines if the command can currently be executed.
      * Override this method to implement command-specific logic.
-     *
-     * @returns {boolean} true if the command can be executed, false otherwise
      */
     is_enabled(): boolean;
     /**
      * Executes the command.
      * Override this method to implement the command's behavior.
      * Can be async for commands that need to perform asynchronous operations.
-     *
-     * @returns {void | Promise<void>}
      */
     execute(): void | Promise<void>;
 }
 /**
  * Command that undoes the last change to the document.
  */
-export class UndoCommand extends Command {
-    is_enabled(): any;
+export declare class UndoCommand extends Command {
+    is_enabled(): boolean;
     execute(): void;
 }
 /**
  * Command that redoes the last undone change to the document.
  */
-export class RedoCommand extends Command {
-    is_enabled(): any;
+export declare class RedoCommand extends Command {
+    is_enabled(): boolean;
     execute(): void;
 }
 /**
  * Command that selects the parent of the current selection.
  * Useful for navigating up the document hierarchy.
  */
-export class SelectParentCommand extends Command {
+export declare class SelectParentCommand extends Command {
+    is_enabled(): boolean;
     execute(): void;
 }
 /**
@@ -77,11 +80,12 @@ export class SelectParentCommand extends Command {
  * are removed, a single touched property-less mark may switch type, and mixed
  * touched types disable the command. Annotations never affect mark toggling.
  */
-export class ToggleMarkCommand extends Command {
-    constructor(node_type: any, context: any);
-    node_type: any;
-    active: any;
-    is_active(): any;
+export declare class ToggleMarkCommand extends Command {
+    node_type: string;
+    constructor(node_type: string, context: CommandContext);
+    active: boolean;
+    is_active(): boolean;
+    is_enabled(): boolean;
     execute(): void;
 }
 /**
@@ -91,19 +95,20 @@ export class ToggleMarkCommand extends Command {
  * same-type annotations are removed, otherwise a new annotation is created.
  * Marks and other annotation types never block the toggle.
  */
-export class ToggleAnnotationCommand extends Command {
-    constructor(node_type: any, context: any);
-    node_type: any;
+export declare class ToggleAnnotationCommand extends Command {
+    node_type: string;
+    constructor(node_type: string, context: CommandContext);
     active: boolean;
-    relevant_annotations(): any;
+    relevant_annotations(): import("./doc_utils.js").SelectedAttachment[];
     is_active(): boolean;
+    is_enabled(): boolean;
     execute(): void;
 }
 /**
  * Command that adds a new line character at the current caret position.
  * Only works in text selections where newlines are allowed.
  */
-export class AddNewLineCommand extends Command {
+export declare class AddNewLineCommand extends Command {
     is_enabled(): any;
     execute(): void;
 }
@@ -112,22 +117,25 @@ export class AddNewLineCommand extends Command {
  * Creates a new node and splits the content between the current and new node.
  * Only works in text selections.
  */
-export class BreakTextNodeCommand extends Command {
+export declare class BreakTextNodeCommand extends Command {
+    is_enabled(): boolean;
     execute(): void;
 }
 /**
  * Command that selects all content in the current context.
  * Progressively expands selection from text → node → parent node array.
  */
-export class SelectAllCommand extends Command {
-    is_enabled(): any;
+export declare class SelectAllCommand extends Command {
+    is_enabled(): boolean;
     execute(): void;
 }
 /**
  * Command that inserts a default node at the current caret position.
  * Only works when a collapsed node selection is active.
  */
-export class InsertDefaultNodeCommand extends Command {
+export declare class InsertDefaultNodeCommand extends Command {
+    is_enabled(): boolean;
     execute(): void;
 }
+export {};
 //# sourceMappingURL=Command.svelte.d.ts.map

package/dist/Command.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Command.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Command.svelte.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAOC;;;;OAIG;IACH,qBAFW,GAAG,EAIb;IAbD;;;OAGG;IACH,kBAAwC;IAQvC,aAAsB;IAGvB;;;;;OAKG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;OAMG;IACH,WAFa,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhC;CACD;AAED;;GAEG;AACH;IACC,kBAEC;IAED,gBAEC;CACD;AAED;;GAEG;AACH;IACC,kBAEC;IAED,gBAEC;CACD;AAED;;;GAGG;AACH;IASC,gBAEC;CACD;AAED;;;;;;GAMG;AACH;IACC,0CAGC;IADA,eAA0B;IAG3B,YAAoC;IAEpC,iBAMC;IA2BD,gBAEC;CACD;AAED;;;;;;GAMG;AACH;IACC,0CAGC;IADA,eAA0B;IAG3B,gBAAoC;IAIpC,4BAIC;IAED,qBAEC;IAmBD,gBAEC;CACD;AAED;;;GAGG;AACH;IACC,kBASC;IAED,gBAqBC;CACD;AAED;;;;GAIG;AACH;IAaC,gBAKC;CACD;AAED;;;GAGG;AACH;IACC,kBAEC;IAED,gBAwGC;CACD;AAED;;;GAGG;AACH;IAUC,gBAIC;CACD"}
+{"version":3,"file":"Command.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Command.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAI/C,KAAK,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;AAEnC,MAAM,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,OAAO,OAAO,OAAO;IAC3B,OAAO,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,QAAQ,UAAgC;IAExC;;;;OAIG;gBACS,OAAO,EAAE,cAAc;IAInC;;;OAGG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;OAIG;IACH,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,OAAO;IACvC,UAAU;IAIV,OAAO;CAGP;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,OAAO;IACvC,UAAU;IAIV,OAAO;CAGP;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,OAAO;IAC/C,UAAU;IAQV,OAAO;CAGP;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,OAAO;IAC7C,SAAS,EAAE,MAAM,CAAC;gBAEN,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;IAKtD,MAAM,UAA8B;IAEpC,SAAS;IAOT,UAAU;IAyBV,OAAO;CAGP;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,OAAO;IACnD,SAAS,EAAE,MAAM,CAAC;gBAEN,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;IAKtD,MAAM,UAA8B;IAIpC,oBAAoB;IAMpB,SAAS;IAIT,UAAU;IAiBV,OAAO;CAGP;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,OAAO;IAC7C,UAAU;IAWV,OAAO;CAuBP;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;IAChD,UAAU;IAYV,OAAO;CAMP;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,OAAO;IAC5C,UAAU;IAIV,OAAO;CAyGP;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,OAAO;IACpD,UAAU;IASV,OAAO;CAKP"}