blixify-ui-web-mcp 0.1.28 → 0.1.29

package/lib/components/input/markdown/README.md

@@ -162,6 +162,7 @@ On error the editor draws a red outline (`border border-red-500 rounded`) — th
 | `compress`           | `{ maxFileSize?: number, fileQuality?: number}` | `null`  | Image compression settings. `maxFileSize` in MB (default: 30), `fileQuality` 0.0-1.0 (default: 0.8)              |
 | `lib`                | `{ axios?: any, mermaid?: () => Promise<any> }` | `null`  | External libraries — axios for API calls; `mermaid` loader (e.g. `() => import("mermaid")`) to draw diagrams     |
 | `uploadEndpoint`     | `string`                                        | `null`  | API endpoint for uploading media files                                                                           |
+| `onHeadingsChange`   | `(headings: MarkdownHeading[]) => void`         | `null`  | Reports the document's `h1`–`h3` outline whenever it changes — feed it to `MarkdownOutline`                       |
 
 ##### Ref Methods
 
@@ -260,6 +261,85 @@ the block. The `/` menu gains **Diagram**, which inserts a starter flowchart.
 - **The source is what is stored**, as a normal fenced block, so search and
   anything reading the raw markdown still see the diagram's text.
 
+##### Heading ids
+
+Both renderers give `h1`–`h3` a slug id and report the outline through
+`onHeadingsChange`, so a host can build its own navigation — a sticky rail, tabs,
+a jump menu — without parsing the markdown itself or reaching into the rendered
+DOM to find anchors.
+
+```tsx
+const [headings, setHeadings] = useState<MarkdownHeading[]>([]);
+
+<MarkdownInput value={body} onChange={handleChange} onHeadingsChange={setHeadings} />;
+
+// each entry is { id, level, text }; the id is on the rendered heading
+document.getElementById(headings[0].id)?.scrollIntoView({ behavior: "smooth" });
+```
+
+What the rail looks like is deliberately left out of this component — an outline in
+a dashboard's own chrome is that app's design problem, and the only thing it needs
+from here is where the sections are.
+
+- **Ids are derived, never stored.** Slugs of the heading text, computed at
+  render, so a document written before any of this existed gets them with no
+  migration and no change to a single stored byte.
+- **Each renderer carries the id the way its own DOM survives.** `MarkdownStatic`
+  injects it into the html string, because React re-commits that string on
+  re-render and wipes anything written to the mounted nodes afterwards. The editor
+  uses a ProseMirror decoration, which is rebuilt from the document on every
+  redraw and never enters the document — a node attribute would reach
+  `getHTML()`, which is turndown's input, and a DOM write is undone on the next
+  redraw.
+- **One parser for both.** The editor and `MarkdownStatic` draw headings through
+  completely different paths, and an outline read from either would only be right
+  there. Both are labelled against the markdown instead, so a note and the page
+  published from it can never list different sections.
+- **Fenced blocks are skipped**, so a `#` comment in a ```` ```bash ```` block or
+  a ```` ```mermaid ```` diagram is not mistaken for a heading. A closing fence
+  must be at least as long as the one that opened it.
+- **Repeated headings get distinct ids** — `overview`, `overview-2`. Two
+  "Overview" sections in a long page are ordinary, and sharing an id would send
+  every click to the first.
+
+##### Resizing an image
+
+Hover or select an image in the editor and drag the handle on either edge. A
+double click returns it to its natural size.
+
+- **Only a width is stored, never a height.** The image keeps its own aspect
+  ratio, which is what makes one axis enough and makes it impossible to save a
+  distorted image.
+- **A resized image is stored as html**, `<img src="…" alt="…" width="420" />`,
+  because markdown has no syntax for a size — the same route `<video>`, the file
+  attachment and the space embed take, and markdown-it runs with `html: true` so
+  it parses back on load. An image nobody resized still serialises as
+  `![alt](src)`, so every document written before this existed round-trips
+  byte-for-byte.
+- **The handle starts the drag in the capture phase.** ProseMirror handles pointer
+  events on the editor element to move the selection and to drag a node around the
+  document, and its listener sits on an ancestor of the handle — so a bubble-phase
+  handler never runs at all.
+- **The document is edited once per drag, on release.** Writing the width on
+  every pointer move would put one transaction per mouse move into the history —
+  undo would take fifty presses — and fire the host's autosave just as often.
+- **Capped at the width of the column** it sits in — measured from the editor
+  element, not from the node view wrapper, which is `fit-content` and therefore
+  exactly the image's current width.
+- **`MarkdownStatic` needs nothing.** The width attribute is html a browser
+  already honours, under the `max-width: 100%` prose already sets, so a published
+  page shows the size the author chose and still fits a phone.
+- **Works on a touch screen.** Two things are load-bearing and neither is
+  obvious: `touch-action: none` on the handle, or the browser claims the gesture
+  as a scroll and cancels the pointer stream a couple of dozen pixels in — which
+  reads as the handle being unresponsive rather than as a scroll — and a hit area
+  far larger than the 6px bar it draws. The drag also takes pointer capture, so
+  it keeps tracking after the finger leaves the handle, and a touch on the image
+  reveals the handles, since a phone never fires hover.
+- **The tiptap extension's own `resize` option is deliberately not used.** It
+  commits a height as well as a width, which is a distorted image waiting to
+  happen, and it hides the image until `onload` fires.
+
 ##### The slash menu
 
 Only a real edit opens it. The detection also runs on selection changes so that

package/lib/components/input/markdown/markdown.stories.tsx

@@ -2,7 +2,7 @@ import React, { useState } from "react";
 import { MarkdownInput as MarkdownInputImpl, MarkdownStatic } from ".";
 import { StorySection } from "../../storyUtils";
 
-const meta = { title: "Input/Markdown Input" };
+const meta = { title: "Input/Markdown/Input" };
 export default meta;
 
 // INFO: the host passes mermaid in; the library never imports it

package/lib/components/input/markdown/markdownImageResize.stories.tsx

@@ -0,0 +1,60 @@
+import React, { useState } from "react";
+import { MarkdownInput, MarkdownStatic } from ".";
+import { StorySection } from "../../storyUtils";
+
+const meta = { title: "Input/Markdown/Image Resize" };
+export default meta;
+
+// INFO: a neutral remote placeholder — nothing here points at a project bucket
+const IMAGE = "https://placehold.co/900x500/png";
+
+const SIZED = [
+  "An image nobody has touched is stored as plain markdown:",
+  "",
+  `![A wide placeholder](${IMAGE})`,
+  "",
+  "One that has been resized carries its width as html:",
+  "",
+  `<img src="${IMAGE}" alt="A wide placeholder" width="320" />`,
+].join("\n");
+
+export const Editor = () => {
+  const [value, setValue] = useState<string | undefined>(SIZED);
+
+  return (
+    <>
+      <StorySection
+        title="Drag to resize"
+        description="Hover or select an image and drag the handle on either edge. Double click returns it to its natural size. The width is previewed while dragging and written to the document once, on release — watch the markdown below, which only changes when the drag ends."
+      >
+        <div className="w-full">
+          <MarkdownInput
+            id="markdown"
+            value={value ?? ""}
+            placeholder="Press / to see the available commands"
+            borderless={true}
+            onChange={(_id: string, next?: string) => setValue(next)}
+            enableImageUpload={true}
+          />
+        </div>
+      </StorySection>
+      <StorySection
+        title="Stored markdown"
+        description="A resized image is html because markdown has no syntax for a size; an untouched one stays ![alt](src), so documents written before resizing existed serialise exactly as they did. Only a width is ever stored — the image keeps its own aspect ratio."
+      >
+        <pre
+          data-testid="stored-markdown"
+          className="w-full overflow-x-auto rounded bg-gray-50 p-3 text-xs text-gray-700"
+        >
+          {value}
+        </pre>
+      </StorySection>
+      <StorySection
+        title="Read-only"
+        description="The same document with no editor. The width attribute is html a browser already honours under the max-width prose sets, so a published page shows the size the author chose and still fits a phone."
+      >
+        <MarkdownStatic label="" value={value ?? ""} />
+      </StorySection>
+    </>
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blixify-ui-web-mcp",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "license": "MIT",
   "main": "lib/mcp/server.js",
   "bin": {