@slash-editor/core 0.0.5 → 0.0.7

package/dist/index.d.mts

@@ -22,6 +22,12 @@ interface SlashItem {
   aliases?: string[];
   /** Lower-weight search terms that are never displayed. */
   keywords?: string[];
+  /**
+   * Markdown input-rule shorthand shown as a hint in the menu (`#`, `---`).
+   * Display only — ranking never reads it, and it must mirror a rule the
+   * editor actually registers.
+   */
+  shortcut?: string;
   /** Icon key resolved by the UI layer; the core ships no components. */
   icon?: string;
   /** Hides the item when the current editor cannot run it. */
@@ -913,6 +919,54 @@ declare const Mention: Node<MentionOptions, MentionStorage>;
 /** Configures the mention node. `items` is required — there is no default provider. */
 declare function mention(options: Partial<MentionOptions> & Pick<MentionOptions, "items">): Node<MentionOptions, MentionStorage>;
 //#endregion
+//#region src/placeholder.d.ts
+/**
+ * Slot a placeholder string is looked up under. Slots are resolved from the
+ * empty node *and its parent*: the empty node inside a list item, a task item,
+ * a quote or a callout is a plain `paragraph`, so node type alone cannot tell
+ * those cases apart.
+ */
+type PlaceholderKey = "paragraph" | "heading1" | "heading2" | "heading3" | "listItem" | "taskItem" | "blockquote" | "callout" | "details";
+interface PlaceholderContext {
+  editor: Editor;
+  /** The empty block holding the caret. */
+  node: Node$1;
+  /** Its parent, which distinguishes a bare paragraph from a list/quote child. */
+  parent: Node$1 | null;
+  /** Position directly before `node`. */
+  pos: number;
+}
+interface PlaceholderOptions {
+  /** Per-slot overrides; unset slots keep the default string. */
+  text?: Partial<Record<PlaceholderKey, string>>;
+  /**
+   * Full override. Wins over `text`; returning `null` suppresses the
+   * placeholder for that block.
+   */
+  resolve?: (context: PlaceholderContext) => string | null;
+}
+declare const defaultPlaceholderText: Record<PlaceholderKey, string>;
+/**
+ * Maps an empty block to its placeholder slot, or `null` when it should stay
+ * blank. Code blocks are excluded: their content is literal, and a hint would
+ * read as source.
+ */
+declare function placeholderKeyFor(node: Node$1, parent: Node$1 | null): PlaceholderKey | null;
+declare const placeholderPluginKey: PluginKey<any>;
+/**
+ * Empty-block hints, Notion style: only the block holding the caret shows one.
+ *
+ * Renders `data-placeholder` and no class names — the UI layer styles
+ * `[data-placeholder]::before`, matching how every other core node is styled.
+ *
+ * The decoration is derived from the state it is drawn against rather than
+ * from `editor.state`: during a transaction those are different documents, and
+ * resolving a parent in the stale one mislabels every nested block.
+ */
+declare const Placeholder: Extension<PlaceholderOptions, any>;
+/** Configures empty-block placeholders. */
+declare function placeholder(options?: PlaceholderOptions): Extension<PlaceholderOptions, any>;
+//#endregion
 //#region src/slash-command.d.ts
 interface SlashMenuState {
   open: boolean;
@@ -947,6 +1001,12 @@ interface SlashCommandOptions {
   char: string;
   /** Item registry, or a resolver called with the live editor. */
   items: SlashItem[] | ((editor: Editor) => SlashItem[]);
+  /**
+   * Inline hint rendered next to the trigger character while the query is
+   * still empty, the way Notion prompts after `/`. Set to `""` to drop it.
+   * The UI layer renders it from `data-decoration-content`.
+   */
+  hint: string;
   /**
    * Called when an item's `run` throws. The failing transaction is never
    * applied, so the document keeps the state it had before the item ran.
@@ -1045,6 +1105,13 @@ interface BlockKitOptions {
    * @default { char: "/", items: defaultSlashItems }
    */
   slash?: Partial<SlashCommandOptions> | false;
+  /**
+   * Empty-block placeholder hints, or `false` to render none. Only the block
+   * holding the caret shows one.
+   *
+   * @default {}
+   */
+  placeholder?: PlaceholderOptions | false;
   /**
    * Stable per-block id configuration, or `false` to opt out. Drag
    * targeting and the future comment/collaboration surfaces depend on it.
@@ -1188,4 +1255,4 @@ declare const Callout: Node<CalloutOptions, any>;
 /** Configures the callout node. */
 declare function callout(options?: Partial<CalloutOptions>): Node<CalloutOptions, any>;
 //#endregion
-export { type AiActionStatus, AiBlock, type AiBlockOptions, type AiBlockStorage, type AiKitOptions, type AiRequest, type AiSlashAction, BLOCK_ID_REMOTE_META, BlockDrag, type BlockDragOptions, type BlockDragState, type BlockDragStorage, BlockId, type BlockIdOptions, type BlockKitOptions, type BlockLocation, type BlockRect, type BlockTarget, BubbleToolbar, type BubbleToolbarItem, type BubbleToolbarOptions, type BubbleToolbarState, type BubbleToolbarStorage, Callout, type CalloutOptions, type CollaborationOptions, type CollaborationProvider, type CollaborationUser, Column, type ColumnOptions, Columns, type ColumnsOptions, Comment, type CommentMessage, type CommentOptions, type CommentState, type CommentStorage, type CommentThread, type CommentThreadStore, type DropMode, type DropTarget, Embed, type EmbedMode, type EmbedOptions, File$1 as File, type FileOptions, type FileStorage, type HeadingLevel, Image, type ImageOptions, type ImageStorage, LinkEditor, type LinkEditorOptions, type LinkEditorState, type LinkEditorStorage, Mention, type MentionItem, type MentionOptions, type MentionState, type MentionStorage, PendingAiRegistry, PendingUploadRegistry, type RetryUploadOptions, type RunAiActionOptions, type RunUploadOptions, type SetEmbedOptions, type SetFileFromFile, type SetFileFromSrc, type SetFileOptions, type SetImageFromFile, type SetImageFromSrc, type SetImageOptions, type SetVideoFromFile, type SetVideoFromSrc, type SetVideoOptions, SlashCommand, type SlashCommandOptions, type SlashCommandStorage, type SlashContext, type SlashItem, type SlashMenuState, type StreamAdapter, type StreamContext, TableKit, type TableKitOptions, type UploadAdapter, type UploadContext, type UploadResult, type UploadStatus, Video, type VideoOptions, type VideoStorage, activeThreadIds, aiBlock, blockDrag, blockDragPluginKey, blockId, blockIdPluginKey, bubbleToolbar, callout, canAppendChild, canOpenLinkEditor, collaboration, column, columns, comment, createAiSlashItems, createBlockKit, defaultAiSlashActions, defaultBubbleToolbarItems, defaultSlashItems, embed, file, filterBubbleToolbarItems, filterSlashItems, findNodeById, image, linkEditor, mention, mentionPluginKey, resolveDropTarget, retryUpload, runUpload, slashCommand, slashCommandPluginKey, table, video };
+export { type AiActionStatus, AiBlock, type AiBlockOptions, type AiBlockStorage, type AiKitOptions, type AiRequest, type AiSlashAction, BLOCK_ID_REMOTE_META, BlockDrag, type BlockDragOptions, type BlockDragState, type BlockDragStorage, BlockId, type BlockIdOptions, type BlockKitOptions, type BlockLocation, type BlockRect, type BlockTarget, BubbleToolbar, type BubbleToolbarItem, type BubbleToolbarOptions, type BubbleToolbarState, type BubbleToolbarStorage, Callout, type CalloutOptions, type CollaborationOptions, type CollaborationProvider, type CollaborationUser, Column, type ColumnOptions, Columns, type ColumnsOptions, Comment, type CommentMessage, type CommentOptions, type CommentState, type CommentStorage, type CommentThread, type CommentThreadStore, type DropMode, type DropTarget, Embed, type EmbedMode, type EmbedOptions, File$1 as File, type FileOptions, type FileStorage, type HeadingLevel, Image, type ImageOptions, type ImageStorage, LinkEditor, type LinkEditorOptions, type LinkEditorState, type LinkEditorStorage, Mention, type MentionItem, type MentionOptions, type MentionState, type MentionStorage, PendingAiRegistry, PendingUploadRegistry, Placeholder, type PlaceholderContext, type PlaceholderKey, type PlaceholderOptions, type RetryUploadOptions, type RunAiActionOptions, type RunUploadOptions, type SetEmbedOptions, type SetFileFromFile, type SetFileFromSrc, type SetFileOptions, type SetImageFromFile, type SetImageFromSrc, type SetImageOptions, type SetVideoFromFile, type SetVideoFromSrc, type SetVideoOptions, SlashCommand, type SlashCommandOptions, type SlashCommandStorage, type SlashContext, type SlashItem, type SlashMenuState, type StreamAdapter, type StreamContext, TableKit, type TableKitOptions, type UploadAdapter, type UploadContext, type UploadResult, type UploadStatus, Video, type VideoOptions, type VideoStorage, activeThreadIds, aiBlock, blockDrag, blockDragPluginKey, blockId, blockIdPluginKey, bubbleToolbar, callout, canAppendChild, canOpenLinkEditor, collaboration, column, columns, comment, createAiSlashItems, createBlockKit, defaultAiSlashActions, defaultBubbleToolbarItems, defaultPlaceholderText, defaultSlashItems, embed, file, filterBubbleToolbarItems, filterSlashItems, findNodeById, image, linkEditor, mention, mentionPluginKey, placeholder, placeholderKeyFor, placeholderPluginKey, resolveDropTarget, retryUpload, runUpload, slashCommand, slashCommandPluginKey, table, video };

package/dist/index.mjs

@@ -293,28 +293,28 @@ const defaultAiSlashActions = [
 		id: "continue-writing",
 		title: "Continue writing",
 		description: "AI extends the text above the cursor",
-		icon: "sparkles",
+		icon: "pencil-sparkles",
 		prompt: "Continue writing the document naturally, matching its tone and style. Write only the continuation, with no preamble."
 	},
 	{
 		id: "summarize",
 		title: "Summarize",
 		description: "AI summarizes the text above the cursor",
-		icon: "sparkles",
+		icon: "broom-sparkles",
 		prompt: "Summarize the following text in a few concise sentences."
 	},
 	{
 		id: "brainstorm-ideas",
 		title: "Brainstorm ideas",
 		description: "AI lists ideas related to the text above the cursor",
-		icon: "sparkles",
+		icon: "brain",
 		prompt: "Brainstorm a short bullet list of ideas related to the following text."
 	},
 	{
 		id: "fix-spelling-grammar",
 		title: "Fix spelling & grammar",
 		description: "AI rewrites the text above the cursor, correcting mistakes",
-		icon: "sparkles",
+		icon: "spell-check",
 		prompt: "Rewrite the following text, correcting spelling and grammar mistakes only, and preserve its meaning and tone."
 	}
 ];
@@ -1904,6 +1904,92 @@ function mention(options) {
 	return Mention.configure(options);
 }
 //#endregion
+//#region src/placeholder.ts
+const defaultPlaceholderText = {
+	paragraph: "Press '/' for commands…",
+	heading1: "Heading 1",
+	heading2: "Heading 2",
+	heading3: "Heading 3",
+	listItem: "List",
+	taskItem: "To-do",
+	blockquote: "Quote",
+	callout: "Callout",
+	details: "Toggle"
+};
+const PARENT_KEYS = {
+	listItem: "listItem",
+	taskItem: "taskItem",
+	blockquote: "blockquote",
+	callout: "callout",
+	detailsContent: "details"
+};
+/**
+* Maps an empty block to its placeholder slot, or `null` when it should stay
+* blank. Code blocks are excluded: their content is literal, and a hint would
+* read as source.
+*/
+function placeholderKeyFor(node, parent) {
+	const name = node.type.name;
+	if (name === "heading") {
+		const { level } = node.attrs;
+		return level === 1 || level === 2 || level === 3 ? `heading${level}` : null;
+	}
+	if (name === "detailsSummary") return "details";
+	if (name !== "paragraph") return null;
+	return parent ? PARENT_KEYS[parent.type.name] ?? "paragraph" : "paragraph";
+}
+const placeholderPluginKey = new PluginKey("placeholder");
+/**
+* Empty-block hints, Notion style: only the block holding the caret shows one.
+*
+* Renders `data-placeholder` and no class names — the UI layer styles
+* `[data-placeholder]::before`, matching how every other core node is styled.
+*
+* The decoration is derived from the state it is drawn against rather than
+* from `editor.state`: during a transaction those are different documents, and
+* resolving a parent in the stale one mislabels every nested block.
+*/
+const Placeholder = Extension.create({
+	name: "placeholder",
+	addOptions() {
+		return {};
+	},
+	addProseMirrorPlugins() {
+		const { editor } = this;
+		const text = {
+			...defaultPlaceholderText,
+			...this.options.text
+		};
+		const { resolve } = this.options;
+		return [new Plugin({
+			key: placeholderPluginKey,
+			props: { decorations: (state) => {
+				if (!editor.isEditable) return null;
+				const { doc, selection } = state;
+				const $anchor = doc.resolve(selection.anchor);
+				const node = $anchor.parent;
+				if (!node.type.isTextblock || node.content.size > 0) return null;
+				const parent = $anchor.depth > 0 ? $anchor.node($anchor.depth - 1) : null;
+				const pos = $anchor.before($anchor.depth);
+				const context = {
+					editor,
+					node,
+					parent,
+					pos
+				};
+				const key = placeholderKeyFor(node, parent);
+				const value = resolve ? resolve(context) : key && text[key];
+				if (!value) return null;
+				return DecorationSet.create(doc, [Decoration.node(pos, pos + node.nodeSize, { "data-placeholder": value })]);
+			} }
+		})];
+	}
+});
+/** Configures empty-block placeholders. */
+function placeholder(options = {}) {
+	return Placeholder.configure(options);
+}
+//#endregion
 //#region src/slash-items.ts
 const TITLE_PREFIX = 100;
 const TITLE_WORD_PREFIX = 80;
@@ -1959,6 +2045,7 @@ const defaultSlashItems = [
 		description: "Large section title",
 		aliases: ["h1", "title"],
 		keywords: ["#"],
+		shortcut: "#",
 		icon: "heading-1",
 		when: (editor) => hasNode(editor, "heading"),
 		run: ({ editor, range }) => {
@@ -1972,6 +2059,7 @@ const defaultSlashItems = [
 		description: "Medium section title",
 		aliases: ["h2", "subtitle"],
 		keywords: ["##"],
+		shortcut: "##",
 		icon: "heading-2",
 		when: (editor) => hasNode(editor, "heading"),
 		run: ({ editor, range }) => {
@@ -1985,6 +2073,7 @@ const defaultSlashItems = [
 		description: "Small section title",
 		aliases: ["h3"],
 		keywords: ["###"],
+		shortcut: "###",
 		icon: "heading-3",
 		when: (editor) => hasNode(editor, "heading"),
 		run: ({ editor, range }) => {
@@ -1998,6 +2087,7 @@ const defaultSlashItems = [
 		description: "Unordered list",
 		aliases: ["ul", "bullet"],
 		keywords: ["-", "*"],
+		shortcut: "-",
 		icon: "list",
 		when: (editor) => hasNode(editor, "bulletList"),
 		run: ({ editor, range }) => {
@@ -2011,6 +2101,7 @@ const defaultSlashItems = [
 		description: "Ordered list",
 		aliases: ["ol", "numbered"],
 		keywords: ["1."],
+		shortcut: "1.",
 		icon: "list-ordered",
 		when: (editor) => hasNode(editor, "orderedList"),
 		run: ({ editor, range }) => {
@@ -2028,6 +2119,7 @@ const defaultSlashItems = [
 			"checkbox"
 		],
 		keywords: ["[]", "[ ]"],
+		shortcut: "[]",
 		icon: "list-checks",
 		when: (editor) => hasNode(editor, "taskList"),
 		run: ({ editor, range }) => {
@@ -2041,6 +2133,7 @@ const defaultSlashItems = [
 		description: "Capture a quotation",
 		aliases: ["quote", "citation"],
 		keywords: [">"],
+		shortcut: ">",
 		icon: "quote",
 		when: (editor) => hasNode(editor, "blockquote"),
 		run: ({ editor, range }) => {
@@ -2088,6 +2181,7 @@ const defaultSlashItems = [
 		description: "Monospaced code",
 		aliases: ["code", "snippet"],
 		keywords: ["```"],
+		shortcut: "```",
 		icon: "code",
 		when: (editor) => hasNode(editor, "codeBlock"),
 		run: ({ editor, range }) => {
@@ -2105,6 +2199,7 @@ const defaultSlashItems = [
 			"rule"
 		],
 		keywords: ["---"],
+		shortcut: "---",
 		icon: "minus",
 		when: (editor) => hasNode(editor, "horizontalRule"),
 		run: ({ editor, range }) => {
@@ -2222,6 +2317,7 @@ const SlashCommand = Extension.create({
 	addOptions() {
 		return {
 			char: "/",
+			hint: "Type to search",
 			items: defaultSlashItems
 		};
 	},
@@ -2283,6 +2379,7 @@ const SlashCommand = Extension.create({
 		return [Suggestion({
 			editor,
 			char: this.options.char,
+			decorationContent: this.options.hint,
 			pluginKey: slashCommandPluginKey,
 			allowSpaces: false,
 			allow: ({ state, range }) => !state.doc.resolve(range.from).parent.type.spec.code,
@@ -2467,7 +2564,7 @@ const DEFAULT_HEADING_LEVELS = [
 * the `data-*` attributes rendered by slash-editor nodes.
 */
 function createBlockKit(options = {}) {
-	const { headingLevels = DEFAULT_HEADING_LEVELS, history = true, slash, blockId: blockIdOptions, drag, bubbleToolbar: bubbleToolbarOptions, image: imageOptions, file: fileOptions, video: videoOptions, embed: embedOptions, table: tableOptions, columns: columnsOptions, linkEditor: linkEditorOptions, mention: mentionOptions, ai: aiOptions, collaboration: collaborationOptions, comment: commentOptions, extend = [] } = options;
+	const { headingLevels = DEFAULT_HEADING_LEVELS, history = true, slash, placeholder: placeholderOptions, blockId: blockIdOptions, drag, bubbleToolbar: bubbleToolbarOptions, image: imageOptions, file: fileOptions, video: videoOptions, embed: embedOptions, table: tableOptions, columns: columnsOptions, linkEditor: linkEditorOptions, mention: mentionOptions, ai: aiOptions, collaboration: collaborationOptions, comment: commentOptions, extend = [] } = options;
 	const resolvedAi = aiOptions ? {
 		actions: defaultAiSlashActions,
 		node: true,
@@ -2501,6 +2598,7 @@ function createBlockKit(options = {}) {
 			...slash,
 			items: slash?.items ?? (() => [...defaultSlashItems, ...resolvedAi ? createAiSlashItems(resolvedAi) : []])()
 		})],
+		...placeholderOptions === false ? [] : [placeholder(placeholderOptions)],
 		...blockIdOptions === false ? [] : [blockId(blockIdOptions)],
 		...drag === false ? [] : [blockDrag(drag)],
 		...bubbleToolbarOptions === false ? [] : [bubbleToolbar(bubbleToolbarOptions)],
@@ -2511,4 +2609,4 @@ function createBlockKit(options = {}) {
 	];
 }
 //#endregion
-export { AiBlock, BLOCK_ID_REMOTE_META, BlockDrag, BlockId, BubbleToolbar, Callout, Column, Columns, Comment, Embed, File, Image, LinkEditor, Mention, PendingAiRegistry, PendingUploadRegistry, SlashCommand, TableKit, Video, activeThreadIds, aiBlock, blockDrag, blockDragPluginKey, blockId, blockIdPluginKey, bubbleToolbar, callout, canAppendChild, canOpenLinkEditor, collaboration, column, columns, comment, createAiSlashItems, createBlockKit, defaultAiSlashActions, defaultBubbleToolbarItems, defaultSlashItems, embed, file, filterBubbleToolbarItems, filterSlashItems, findNodeById, image, linkEditor, mention, mentionPluginKey, resolveDropTarget, retryUpload, runUpload, slashCommand, slashCommandPluginKey, table, video };
+export { AiBlock, BLOCK_ID_REMOTE_META, BlockDrag, BlockId, BubbleToolbar, Callout, Column, Columns, Comment, Embed, File, Image, LinkEditor, Mention, PendingAiRegistry, PendingUploadRegistry, Placeholder, SlashCommand, TableKit, Video, activeThreadIds, aiBlock, blockDrag, blockDragPluginKey, blockId, blockIdPluginKey, bubbleToolbar, callout, canAppendChild, canOpenLinkEditor, collaboration, column, columns, comment, createAiSlashItems, createBlockKit, defaultAiSlashActions, defaultBubbleToolbarItems, defaultPlaceholderText, defaultSlashItems, embed, file, filterBubbleToolbarItems, filterSlashItems, findNodeById, image, linkEditor, mention, mentionPluginKey, placeholder, placeholderKeyFor, placeholderPluginKey, resolveDropTarget, retryUpload, runUpload, slashCommand, slashCommandPluginKey, table, video };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slash-editor/core",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Headless block-editor core: ProseMirror/Tiptap extensions, schema, commands.",
   "license": "MIT",
   "repository": {