@djangocfg/widget-editor 0.1.1

package/src/markdown/markdown-editor.stories.tsx

@@ -0,0 +1,500 @@
+import { useRef, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  MarkdownEditor,
+  mentionPresets,
+  FilePathChip,
+  type MarkdownEditorHandle,
+  type MarkdownEditorProps,
+  type MentionConfig,
+  type MentionMarkdownRenderer,
+} from './lazy';
+
+// ── Fixtures ──
+
+const SAMPLE = `# Hello, Markdown!
+
+Type **bold**, *italic*, or \`inline code\`.
+
+- Lists work too
+- And [links](https://djangocfg.com)
+`;
+
+const LONG_CONTENT = `# Long Document
+
+## Introduction
+
+This is a longer document used to verify scrolling, sticky toolbar behaviour, and
+overall density of the editor surface.
+
+## Features
+
+- Headings (H1–H3)
+- **Bold**, *italic*, ~~strikethrough~~, \`inline code\`
+- Ordered and unordered lists
+- Blockquotes
+- Links — [djangocfg](https://djangocfg.com)
+- Horizontal rules
+
+---
+
+## Code
+
+\`\`\`ts
+export function greet(name: string) {
+  return \`hello, \${name}\`;
+}
+\`\`\`
+
+## Quote
+
+> "The best way to predict the future is to invent it." — Alan Kay
+
+## Checklist
+
+1. Draft
+2. Review
+3. Ship
+
+## Filler
+
+${Array.from({ length: 12 }, (_, i) => `Paragraph ${i + 1}. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`).join('\n\n')}
+`;
+
+const MENTION_ITEMS: MentionConfig = {
+  items: [
+    { id: '1', label: 'Alice', description: 'Protagonist', thumbnail: 'https://i.pravatar.cc/48?u=alice' },
+    { id: '2', label: 'Bob', description: 'Antagonist', thumbnail: 'https://i.pravatar.cc/48?u=bob' },
+    { id: '3', label: 'Charlie', description: 'Side character', thumbnail: 'https://i.pravatar.cc/48?u=charlie' },
+    { id: '4', label: 'Diana', description: 'Narrator' },
+    { id: '5', label: 'Eve', description: 'Mystery character' },
+  ],
+};
+
+// ── Meta ──
+
+// ── Host (Controls-driven) ──
+
+interface HostProps extends Omit<MarkdownEditorProps, 'value' | 'onChange'> {
+  initialContent?: string;
+  mentions?: MentionConfig;
+}
+
+function Host({ initialContent = '', mentions, ...rest }: HostProps) {
+  const [value, setValue] = useState(initialContent);
+  return (
+    <div className="w-[680px]">
+      <MarkdownEditor {...rest} mentions={mentions} value={value} onChange={setValue} />
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Widgets/Editor/Editor',
+  component: Host,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'TipTap-based markdown editor. Supports headings, lists, marks, blockquotes, code, ' +
+          'links, and an optional `@`-mention popover. The component is controlled — pass `value` ' +
+          'and `onChange`. Use the `ref` (`MarkdownEditorHandle`) to focus or move the caret.',
+      },
+    },
+  },
+  argTypes: {
+    placeholder: {
+      control: 'text',
+      table: { category: 'Content' },
+    },
+    minHeight: {
+      control: { type: 'number', min: 40, max: 800, step: 20 },
+      table: { category: 'Layout' },
+    },
+    disabled: {
+      control: 'boolean',
+      table: { category: 'Behaviour' },
+    },
+    showToolbar: {
+      control: 'boolean',
+      table: { category: 'Behaviour' },
+    },
+    className: { table: { disable: true } },
+    mentions: { table: { disable: true } },
+    onMentionIdsChange: { table: { disable: true } },
+    onSubmit: { table: { disable: true } },
+    initialContent: {
+      control: 'text',
+      table: { category: 'Content' },
+    },
+  },
+} satisfies Meta<typeof Host>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ── Playground ──
+
+export const Playground: Story = {
+  args: {
+    placeholder: 'Write markdown…',
+    minHeight: 240,
+    disabled: false,
+    showToolbar: true,
+  },
+  render: ({ initialContent, ...args }) => (
+    <Host initialContent={initialContent ?? SAMPLE} {...args} />
+  ),
+};
+
+// ── Curated presets ──
+
+export const Empty: Story = {
+  render: () => <Host initialContent="" placeholder="Start typing…" />,
+};
+
+export const WithContent: Story = {
+  render: () => <Host initialContent={SAMPLE} />,
+};
+
+export const ReadOnly: Story = {
+  render: () => (
+    <div className="w-[680px]">
+      <MarkdownEditor value={SAMPLE} onChange={() => {}} disabled />
+    </div>
+  ),
+};
+
+export const NoToolbar: Story = {
+  render: () => (
+    <Host
+      initialContent={'Plain text without toolbar.\n\nStill supports **markdown** shortcuts.'}
+      showToolbar={false}
+    />
+  ),
+};
+
+export const Compact: Story = {
+  render: () => (
+    <div className="w-[420px]">
+      <Host initialContent="Short note" minHeight={60} placeholder="Quick note…" />
+    </div>
+  ),
+};
+
+export const LongContent: Story = {
+  render: () => (
+    <div className="h-[520px] w-[680px] overflow-auto rounded-md border">
+      <Host initialContent={LONG_CONTENT} minHeight={480} />
+    </div>
+  ),
+};
+
+// ── Mentions ──
+
+function MentionsHost({
+  initial,
+  renderMarkdown,
+}: {
+  initial: string;
+  renderMarkdown?: MentionMarkdownRenderer;
+}) {
+  const [value, setValue] = useState(initial);
+  const [ids, setIds] = useState<string[]>([]);
+  const mentions: MentionConfig = renderMarkdown
+    ? { ...MENTION_ITEMS, renderMarkdown }
+    : MENTION_ITEMS;
+
+  return (
+    <div className="grid w-[820px] gap-3" style={{ gridTemplateColumns: '1fr 1fr' }}>
+      <div>
+        <MarkdownEditor
+          value={value}
+          onChange={setValue}
+          mentions={mentions}
+          onMentionIdsChange={setIds}
+          placeholder="Type @ to mention…"
+          minHeight={200}
+        />
+        {ids.length > 0 && (
+          <div className="mt-2 text-xs opacity-60">Mentioned IDs: {ids.join(', ')}</div>
+        )}
+      </div>
+      <div>
+        <div className="mb-1 text-[10px] uppercase tracking-wide opacity-50">
+          Serialized markdown
+        </div>
+        <pre className="max-h-[260px] overflow-auto rounded-md border bg-muted/40 p-2 text-xs">
+          {value}
+        </pre>
+      </div>
+    </div>
+  );
+}
+
+export const WithMentions: Story = {
+  render: () => (
+    <MentionsHost initial="Hello @Alice! Type @ to mention more characters." />
+  ),
+};
+
+export const WithCustomUriPreset: Story = {
+  name: 'Mentions / customUri preset',
+  render: () => (
+    <MentionsHost
+      initial="Reference @Alice and @Bob — markdown carries deep-link URIs."
+      renderMarkdown={mentionPresets.customUri('myapp', 'user')}
+    />
+  ),
+};
+
+export const WithMarkdownLinkPreset: Story = {
+  name: 'Mentions / markdownLink preset',
+  render: () => (
+    <MentionsHost
+      initial="Ping @Alice when ready, cc @Charlie."
+      renderMarkdown={mentionPresets.markdownLink('https://example.com/u/')}
+    />
+  ),
+};
+
+export const WithCustomRenderer: Story = {
+  name: 'Mentions / custom renderer',
+  render: () => (
+    <MentionsHost
+      initial="Tag @Alice and @Bob to assign the task."
+      renderMarkdown={({ id, label }) => `{{user:${id}|${label || 'unknown'}}}`}
+    />
+  ),
+};
+
+// ── Imperative handle ──
+
+export const ImperativeHandle: Story = {
+  name: 'Ref / focus & moveCursorToEnd',
+  render: () => {
+    function HandleDemo() {
+      const ref = useRef<MarkdownEditorHandle>(null);
+      const [value, setValue] = useState(SAMPLE);
+      return (
+        <div className="w-[680px] space-y-2">
+          <div className="flex gap-2">
+            <button
+              type="button"
+              className="rounded-md border px-3 py-1 text-xs"
+              onClick={() => ref.current?.focus()}
+            >
+              focus()
+            </button>
+            <button
+              type="button"
+              className="rounded-md border px-3 py-1 text-xs"
+              onClick={() => ref.current?.moveCursorToEnd()}
+            >
+              moveCursorToEnd()
+            </button>
+          </div>
+          <MarkdownEditor ref={ref} value={value} onChange={setValue} minHeight={200} />
+        </div>
+      );
+    }
+    return <HandleDemo />;
+  },
+};
+
+// ── File-path chips ──
+
+const FILE_PATH_REPRO =
+  'прочти манифест /Users/markinmatrix/workspace/@projects/cmdop/@docs/positioning/manifest.md интересно твоё мнение';
+
+const LONG_PATH =
+  '/Users/markinmatrix/workspace/@projects/djangocfg/projects/solution/frontend/packages/ui-tools/src/tools/dev/Map/index.ts';
+
+const FILE_PATH_MIX = [
+  'Repro: ' + FILE_PATH_REPRO,
+  '',
+  'Long path (was wrapping): ' + LONG_PATH,
+  '',
+  'Windows: C:\\Users\\me\\notes.md',
+  'UNC: \\\\srv\\share\\report.xlsx',
+  'Home: ~/dev/app/src/index.ts',
+  'URI: file:///etc/hosts',
+  'Folder: /Users/me/workspace/positioning',
+  '',
+  'Prose stays plain: a / b stays text.',
+].join('\n');
+
+/**
+ * Host that shows the editor side-by-side with the serialized markdown so
+ * you can confirm chips round-trip to the RAW path / URL on copy / submit.
+ */
+function ChipRoundTripHost({
+  initial,
+  filePathChips,
+  urlChips,
+  minHeight = 220,
+}: {
+  initial: string;
+  filePathChips?: boolean;
+  urlChips?: boolean;
+  minHeight?: number;
+}) {
+  const [value, setValue] = useState(initial);
+  return (
+    <div className="grid w-[860px] gap-3" style={{ gridTemplateColumns: '1fr 1fr' }}>
+      <MarkdownEditor
+        value={value}
+        onChange={setValue}
+        minHeight={minHeight}
+        filePathChips={filePathChips}
+        urlChips={urlChips}
+      />
+      <div>
+        <div className="mb-1 text-[10px] uppercase tracking-wide opacity-50">
+          getMarkdown() output (raw path / URL — never chip markup)
+        </div>
+        <pre className="max-h-[280px] overflow-auto rounded-md border bg-muted/40 p-2 text-xs whitespace-pre-wrap break-all">
+          {value}
+        </pre>
+      </div>
+    </div>
+  );
+}
+
+export const FilePathChips: Story = {
+  name: 'File paths / chips (atomic node)',
+  render: () => (
+    <div className="space-y-2">
+      <p className="w-[860px] text-xs opacity-60">
+        Absolute local paths render as compact, atomic chips (icon +
+        VSCode-style middle-ellipsis label, full path on hover). The chip is a
+        NODE that owns its rendering, so a long path collapses to ONE line
+        instead of wrapping. Copy / submit / <code>getMarkdown()</code> keep
+        the raw path — see the panel on the right. Type a path + space to
+        watch it become a chip.
+      </p>
+      <ChipRoundTripHost initial={FILE_PATH_MIX} minHeight={300} />
+    </div>
+  ),
+};
+
+// ── URL chips ──
+
+const URL_MIX = [
+  'Repo: https://github.com/wailsapp/wails/blob/main/v3/README.md',
+  '',
+  'Docs: https://djangocfg.com/docs/getting-started',
+  'Bare host: www.example.com/path/to/page',
+  'Mail: mailto:hello@djangocfg.com',
+  '',
+  'Type a long URL + space to watch it become a chip.',
+].join('\n');
+
+export const UrlChips: Story = {
+  name: 'URLs / chips (atomic node)',
+  render: () => (
+    <div className="space-y-2">
+      <p className="w-[860px] text-xs opacity-60">
+        URLs render as compact, clickable chips (favicon — degrading to a
+        globe glyph — + domain and a middle-ellipsis of the path, e.g.{' '}
+        <code>github.com/…/README.md</code>; full URL on hover). Replaces the
+        plain blue underlined link. Copy / submit keep the raw URL — see the
+        panel on the right.
+      </p>
+      <ChipRoundTripHost initial={URL_MIX} minHeight={260} />
+    </div>
+  ),
+};
+
+export const UrlChipsOff: Story = {
+  name: 'URLs / disabled (urlChips=false)',
+  render: () => (
+    <ChipRoundTripHost
+      initial={'Plain link stays a markdown link: https://djangocfg.com/docs'}
+      urlChips={false}
+      minHeight={140}
+    />
+  ),
+};
+
+export const FilePathChipsOff: Story = {
+  name: 'File paths / disabled (filePathChips=false)',
+  render: () => {
+    function Off() {
+      const [value, setValue] = useState(FILE_PATH_REPRO);
+      return (
+        <div className="w-[680px]">
+          <MarkdownEditor
+            value={value}
+            onChange={setValue}
+            filePathChips={false}
+            minHeight={140}
+          />
+        </div>
+      );
+    }
+    return <Off />;
+  },
+};
+
+// ── Standalone chip (outside the editor) ──
+
+export const StandaloneFilePathChip: Story = {
+  name: 'File paths / standalone <FilePathChip>',
+  render: () => (
+    <div className="flex w-[520px] flex-col items-start gap-3">
+      <p className="text-xs opacity-60">
+        <code>&lt;FilePathChip&gt;</code> is presentational and works outside
+        the editor — e.g. rendering a known path in a message.
+      </p>
+      <FilePathChip path="/Users/me/manifest.md" />
+      <FilePathChip path="/Users/markinmatrix/workspace/@projects/cmdop/@docs/positioning/manifest.md" />
+      <FilePathChip path={'C:\\Users\\me\\notes.md'} />
+      <FilePathChip path="~/dev/app/src/index.ts" />
+      <FilePathChip path="/Users/me/workspace/positioning" />
+    </div>
+  ),
+};
+
+// ── Submit on Enter (chat-style) ──
+
+export const SubmitOnEnter: Story = {
+  name: 'Behaviour / submit on Enter',
+  render: () => {
+    function ChatLike() {
+      const [value, setValue] = useState('Press Enter to submit, Shift+Enter for newline.');
+      const [log, setLog] = useState<string[]>([]);
+      return (
+        <div className="w-[680px] space-y-2">
+          <MarkdownEditor
+            value={value}
+            onChange={setValue}
+            minHeight={140}
+            placeholder="Type a message…"
+            onSubmit={() => {
+              if (!value.trim()) return false; // let HardBreak fall through
+              setLog((prev) => [...prev, value]);
+              setValue('');
+            }}
+          />
+          {log.length > 0 && (
+            <div className="rounded-md border bg-muted/30 p-2 text-xs">
+              <div className="mb-1 text-[10px] uppercase tracking-wide opacity-50">Submitted</div>
+              <ul className="space-y-1">
+                {log.map((m, i) => (
+                  <li key={i} className="font-mono">
+                    {m}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      );
+    }
+    return <ChatLike />;
+  },
+};

package/src/markdown/mentionPresets.ts

@@ -0,0 +1,49 @@
+import type { MentionMarkdownRenderer } from './types';
+
+/**
+ * Escape characters that have meaning in markdown link/inline contexts.
+ * Conservative — covers the chars that would break `[text](url)` and
+ * inline emphasis when a label contains them.
+ */
+const escapeMd = (s: string): string => s.replace(/([\\\[\]()_*~`])/g, '\\$1');
+
+/**
+ * Built-in serializers for the `MentionConfig.renderMarkdown` callback.
+ *
+ * Pick one based on what consumes the markdown:
+ *
+ * - LLM / chat composer    → `plainAt`     (the default)
+ * - Plain text export      → `plainLabel`
+ * - Web app with deep-link → `markdownLink(baseUrl)`
+ * - Notion / Linear-style  → `customUri(scheme, kind)`
+ * - Slack-style id refs    → `slackStyle`
+ * - HTML-allowing renderer → `htmlSpan(className?)`
+ *
+ * Or pass a custom function — the type is just `(attrs) => string`.
+ */
+export const mentionPresets = {
+  /** "@Label" — default, ideal for chat where LLMs read the text. */
+  plainAt: (({ label, id }) => `@${label || id}`) as MentionMarkdownRenderer,
+
+  /** "Label" — bare label, no @ prefix. */
+  plainLabel: (({ label, id }) => label || id) as MentionMarkdownRenderer,
+
+  /** "[@Label](baseUrl/id)" — clickable markdown link. */
+  markdownLink: (baseUrl: string): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `[@${escapeMd(label || id)}](${baseUrl}${encodeURIComponent(id)})`,
+
+  /** "@[Label](scheme://kind/id)" — Notion / Linear-style custom URI. */
+  customUri: (scheme: string, kind: string): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `@[${escapeMd(label || id)}](${scheme}://${kind}/${encodeURIComponent(id)})`,
+
+  /** "<@id>" — Slack-style id-only reference (label dropped — receivers resolve it). */
+  slackStyle: (({ id }) => `<@${id}>`) as MentionMarkdownRenderer,
+
+  /** Inline HTML span — for products that consume markdown with raw HTML allowed. */
+  htmlSpan:
+    (className = 'mention'): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `<span class="${className}" data-mention-id="${encodeURIComponent(id)}">@${escapeMd(label || id)}</span>`,
+};

package/src/markdown/slash/SlashCommandNode.ts

@@ -0,0 +1,162 @@
+/**
+ * `SlashCommandNode` — TipTap inline atom that renders a chosen slash
+ * verb as a styled chip inside the editor, analogous to how
+ * `@tiptap/extension-mention` renders an `@user` pill.
+ *
+ * Why a node (and not a mark / decoration):
+ *
+ * - The chip must read as one indivisible unit — pressing Backspace
+ *   removes the whole `/verb`, not the trailing letter. That's
+ *   exactly what `atom: true` + `inline: true` give us.
+ * - The chip's text content (`/verb`) participates in `editor.getText()`
+ *   and the markdown serializer's text output so the host's
+ *   `composer.value` round-trips to the same plain string the plain
+ *   `<SlashHighlightTextarea>` produces. The slash hook (which lives on
+ *   the string buffer) stays oblivious to the node form.
+ *
+ * Render parity with the plain mirror:
+ *
+ * The chip class `markdown-slash-command` mirrors the plain textarea's
+ * `bg-primary/15 text-primary` look (see `SlashHighlightTextarea.tsx`).
+ * Styles live in `../styles.css`. The TipTap chip can carry a touch of
+ * horizontal padding without breaking the caret — the node is atomic
+ * so the caret never lands inside it — which the plain mirror cannot.
+ */
+import { Node, mergeAttributes } from '@tiptap/core';
+
+declare module '@tiptap/core' {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface Commands<ReturnType> {
+    slashCommand: {
+      /**
+       * Insert a slash-command atom at the given absolute document
+       * position. The host normally calls this once per `pick()`
+       * after the slash hook has produced the new string buffer.
+       */
+      insertSlashCommandAt: (
+        pos: number,
+        from: number,
+        to: number,
+        attrs: { id: string; token: string },
+      ) => ReturnType;
+    };
+  }
+}
+
+export interface SlashCommandNodeOptions {
+  /** Extra HTML attrs spread onto the rendered `<span>`. */
+  HTMLAttributes: Record<string, unknown>;
+}
+
+/**
+ * Inline atom node that paints a `/verb` chip inside the TipTap editor.
+ *
+ * - `inline: true` — lives next to text in a paragraph.
+ * - `atom: true`   — caret cannot land inside it; Backspace removes it
+ *   wholesale, matching the plain mirror's "the verb is one token"
+ *   feel.
+ * - `selectable: false` — clicking the chip does not stick a node
+ *   selection on it (mention does the same).
+ *
+ * `renderText` returns the bare `/verb` so `editor.getText()` (and
+ * therefore the host `composer.value`) reads the same string the plain
+ * mirror produces. This is what keeps the slash hook — which only
+ * understands strings — driving the menu correctly when the editor is
+ * TipTap-backed.
+ */
+export const SlashCommandNode = Node.create<SlashCommandNodeOptions>({
+  name: 'slashCommand',
+  group: 'inline',
+  inline: true,
+  atom: true,
+  selectable: false,
+  // Higher than StarterKit text so paste rules etc. don't try to
+  // re-parse our chip text as plain.
+  priority: 101,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+    };
+  },
+
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (element) => element.getAttribute('data-id'),
+        renderHTML: (attrs) =>
+          attrs.id ? { 'data-id': attrs.id as string } : {},
+      },
+      token: {
+        default: null,
+        parseHTML: (element) => element.getAttribute('data-token'),
+        renderHTML: (attrs) =>
+          attrs.token ? { 'data-token': attrs.token as string } : {},
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: `span[data-type="${this.name}"]` }];
+  },
+
+  renderHTML({ node, HTMLAttributes }) {
+    const token =
+      (node.attrs.token as string | null) ??
+      (node.attrs.id ? `/${node.attrs.id as string}` : '/');
+    return [
+      'span',
+      mergeAttributes(
+        { 'data-type': this.name, class: 'markdown-slash-command' },
+        this.options.HTMLAttributes,
+        HTMLAttributes,
+      ),
+      token,
+    ];
+  },
+
+  // `editor.getText()` and the markdown text-serializer fallback read
+  // this — the chip flattens to its raw `/verb` glyph so consumers
+  // (slash hook, transport, backends) see plain text.
+  renderText({ node }) {
+    const token =
+      (node.attrs.token as string | null) ??
+      (node.attrs.id ? `/${node.attrs.id as string}` : '/');
+    return token;
+  },
+
+  // `@tiptap/markdown` reads `renderMarkdown` off the extension at
+  // registration time. We emit the bare token, NOT the default
+  // shortcode `[slashCommand id="..."]`, so a round-trip through
+  // `getMarkdown()` yields the same `/verb argument` string the plain
+  // mirror produces. Slash commands never need re-parsed back from
+  // markdown — fresh value sync handles that via
+  // `syncLeadingSlashNode` after each `setContent`.
+  renderMarkdown(node) {
+    const attrs = node.attrs as { token?: string | null; id?: string | null };
+    const token = attrs.token ?? (attrs.id ? `/${attrs.id}` : '');
+    return token;
+  },
+
+  addCommands() {
+    return {
+      insertSlashCommandAt:
+        (pos, from, to, attrs) =>
+        ({ chain }) => {
+          // Replace the [from, to) range (typically the leading `/verb`
+          // text the user just had the menu narrow down) with the atom
+          // node. `pos` is unused here but kept in the signature for
+          // future use (e.g. cursor-driven insertion not anchored at
+          // the start of the doc).
+          void pos;
+          return chain()
+            .insertContentAt(
+              { from, to },
+              { type: 'slashCommand', attrs },
+            )
+            .run();
+        },
+    };
+  },
+});