@multiplatform.one/frappe-ui 6.3.0 → 6.4.1

package/src/fields/MarkdownEditor/MarkdownEditor.spec.tsx

@@ -1,11 +1,13 @@
 /**
- * MarkdownEditorField contract specs: canonical onChange emission (LC-14),
- * readOnly/disabled gating, table-cell chromeless branch, skeleton branch,
- * and registry resolution for the "Markdown Editor" fieldtype.
+ * MarkdownEditorField contract specs: rich editor in markdown capabilities
+ * (LC-52 MARKDOWN-EXPRESSIBLE-EDITING — no highlight/underline/color
+ * controls), canonical onChange emitting markdown (LC-14), readOnly/disabled
+ * gating, table-cell chromeless branch, skeleton branch, and registry
+ * resolution for the "Markdown Editor" fieldtype.
  */
 import { TableCellContext } from "@multiplatform.one/forms";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { act, cleanup, fireEvent } from "@testing-library/react";
+import { act, cleanup, fireEvent, waitFor } from "@testing-library/react";
 import type React from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { getFieldComponent, type FieldRenderProps } from "../../fieldRegistry";
@@ -13,63 +15,85 @@ import { MarkdownEditorField } from ".";
 
 afterEach(cleanup);
 
+const getProseMirror = (container: HTMLElement) =>
+  container.querySelector<HTMLElement>('[contenteditable="true"]');
+
 describe("MarkdownEditorField (standalone)", () => {
-  it("emits the markdown source through canonical onChange", async () => {
-    const onChange = vi.fn();
+  it("renders the rich text editor (WYSIWYG), not a source textarea", async () => {
     const result = renderWithProviders(
-      <MarkdownEditorField label="Notes" value="" onChange={onChange} />,
+      <MarkdownEditorField label="Notes" value="# Hello" onChange={() => {}} />,
     );
-    const textarea = result.getTextArea();
-    expect(textarea).toBeTruthy();
-    await act(async () => {
-      if (textarea) fireEvent.change(textarea, { target: { value: "# Hello" } });
-    });
-    expect(onChange).toHaveBeenCalledWith("# Hello");
+    await waitFor(() => expect(getProseMirror(result.container)).toBeTruthy());
+    expect(result.getTextArea()).toBeNull();
+    // markdown value parsed into rich nodes
+    expect(result.container.querySelector("h1")?.textContent).toBe("Hello");
   });
 
-  it("readOnly gates onChange (no emission even if the DOM event fires)", async () => {
+  it("markdown capabilities: no underline/highlight/color toolbar controls (LC-52)", async () => {
+    const result = renderWithProviders(
+      <MarkdownEditorField label="Notes" value="hello" onChange={() => {}} />,
+    );
+    await waitFor(() => expect(result.queryByLabelText("Bold")).toBeTruthy());
+    expect(result.queryByLabelText("Underline")).toBeNull();
+    expect(result.queryByLabelText("Text Color")).toBeNull();
+    expect(result.queryByLabelText("Highlight Color")).toBeNull();
+    // markdown-expressible controls stay
+    expect(result.queryByLabelText("Italic")).toBeTruthy();
+    expect(result.queryByLabelText("Blockquote")).toBeTruthy();
+  });
+
+  it("emits markdown (not HTML) through canonical onChange", async () => {
     const onChange = vi.fn();
     const result = renderWithProviders(
-      <TableCellContext.Provider value={{ inTableCell: true, editable: true }}>
-        <MarkdownEditorField label="Notes" value="original" readOnly onChange={onChange} />
-      </TableCellContext.Provider>,
+      <MarkdownEditorField label="Notes" value="hello" onChange={onChange} />,
     );
-    const textarea = result.getTextArea();
-    expect(textarea).toBeTruthy();
+    await waitFor(() => expect(result.queryByLabelText("Blockquote")).toBeTruthy());
     await act(async () => {
-      if (textarea) fireEvent.change(textarea, { target: { value: "mutated" } });
+      fireEvent.click(result.getByLabelText("Blockquote"));
     });
-    expect(onChange).not.toHaveBeenCalled();
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    const emitted = onChange.mock.calls.at(-1)?.[0] as string;
+    expect(emitted).toContain("> hello");
+    expect(emitted).not.toContain("<blockquote>");
   });
 
-  it("disabled gates onChange", async () => {
+  it("readOnly renders a non-editable surface without emitting changes", async () => {
     const onChange = vi.fn();
     const result = renderWithProviders(
-      <TableCellContext.Provider value={{ inTableCell: true, editable: true }}>
-        <MarkdownEditorField label="Notes" value="original" disabled onChange={onChange} />
-      </TableCellContext.Provider>,
+      <MarkdownEditorField label="Notes" value="original" readOnly onChange={onChange} />,
     );
-    const textarea = result.getTextArea();
-    await act(async () => {
-      if (textarea) fireEvent.change(textarea, { target: { value: "mutated" } });
-    });
+    await waitFor(() =>
+      expect(result.container.querySelector('[contenteditable="false"]')).toBeTruthy(),
+    );
+    expect(getProseMirror(result.container)).toBeNull();
     expect(onChange).not.toHaveBeenCalled();
   });
 
-  it("renders chromeless (bare source pane, no Write/Preview tabs) in table cells", () => {
+  it("disabled renders a non-editable surface", async () => {
+    const result = renderWithProviders(
+      <MarkdownEditorField label="Notes" value="original" disabled onChange={() => {}} />,
+    );
+    await waitFor(() =>
+      expect(result.container.querySelector('[contenteditable="false"]')).toBeTruthy(),
+    );
+    expect(getProseMirror(result.container)).toBeNull();
+  });
+
+  it("renders chromeless (no fixed formatting toolbar) in table cells", async () => {
     const result = renderWithProviders(
       <TableCellContext.Provider value={{ inTableCell: true, editable: true }}>
         <MarkdownEditorField label="Notes" value="# cell" onChange={() => {}} />
       </TableCellContext.Provider>,
     );
-    expect(result.getTextArea()).toBeTruthy();
-    expect(result.queryByText("Preview")).toBeNull();
+    await waitFor(() => expect(getProseMirror(result.container)).toBeTruthy());
+    expect(result.queryByLabelText("Formatting toolbar")).toBeNull();
   });
 
   it("skeleton branch renders no editable surface", () => {
     const result = renderWithProviders(
       <MarkdownEditorField label="Notes" skeleton value="# hidden" onChange={() => {}} />,
     );
+    expect(getProseMirror(result.container)).toBeNull();
     expect(result.getTextArea()).toBeNull();
   });
 });

package/src/fields/MarkdownEditor/MarkdownEditor.stories.tsx

@@ -9,14 +9,14 @@ const FIXTURE = `# Release notes
 
 Dedicated **Markdown Editor** field for the Frappe \`Markdown Editor\` fieldtype.
 
-- Live preview through the house renderer
-- Side-by-side above the md breakpoint, tabs below it
+- WYSIWYG editing via the canonical rich text editor
+- Constrained to what ~~HTML~~ *markdown* can express (LC-52)
 - Full field contract: label / hint / error / readOnly / skeleton
 
-> Write on the left, read on the right.
+> Serializes to and from a GFM markdown string.
 
 \`\`\`python
-print("fenced code renders too")
+print("fenced code works too")
 \`\`\`
 `;
 
@@ -28,7 +28,7 @@ export default {
     docs: {
       description: {
         component:
-          "Frappe `Markdown Editor` fieldtype: markdown source pane + live preview (house @multiplatform.one/markdown renderer). Side-by-side ≥ md container width, Write/Preview tabs below it.",
+          "Frappe `Markdown Editor` fieldtype: the canonical rich text editor in markdown capabilities (LC-52) — WYSIWYG constrained to GFM-expressible features (no highlight/underline/color/alignment), serializing to and from a markdown string. Native falls back to markdown source editing.",
       },
     },
   },

package/src/fields/MarkdownEditor/index.native.tsx

@@ -0,0 +1,292 @@
+/**
+ * MarkdownEditorField (NATIVE fallback) — markdown source pane with a live
+ * rendered preview (house `@multiplatform.one/markdown` renderer).
+ *
+ * The web tier renders the canonical rich text editor constrained to
+ * markdown capabilities (LC-52 MARKDOWN-EXPRESSIBLE-EDITING). On native the
+ * 10Tap WebView cannot express that constraint honestly tonight (extension
+ * gating + markdown serialization live in the web bundle), so this tier
+ * keeps plain markdown source editing — documented fallback, not a parallel
+ * WYSIWYG implementation.
+ *
+ * Full field contract: three-branch render (skeleton → standalone →
+ * form-integrated), canonical `onChange(value)` (LC-14), FieldLayout slot
+ * order, chromeless inside table cells (useIsInTableCell).
+ */
+
+import {
+  Field,
+  FieldLayout,
+  Skeleton,
+  TextArea,
+  formCommonColors,
+  getFieldError,
+  mergeFieldHandler,
+  useFormField,
+  useIsInTableCell,
+  useResolvedValidators,
+  type AnyFormApi,
+} from "@multiplatform.one/forms";
+import { useEffect, useState, type ComponentType, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import type { FontSizeTokens, LabelProps, SizeTokens } from "tamagui";
+import { Paragraph, YStack } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { EditorPreviewPanes, PreviewSurface } from "../shared/EditorPreviewPanes";
+
+// ---------------------------------------------------------------------------
+// Preview (lazy house Markdown renderer)
+// ---------------------------------------------------------------------------
+
+type MarkdownComponent = ComponentType<{ children?: string }>;
+
+// Module-level cache so the renderer loads once per session, not per field.
+let markdownRendererCache: MarkdownComponent | null = null;
+
+/**
+ * The house Markdown renderer loads on demand the first time a preview pane
+ * renders (same optional-dependency pattern as the components shiki
+ * Highlighter): `@multiplatform.one/markdown` reaches consumers transitively
+ * via `@multiplatform.one/rich-text`, and a failed import degrades to a
+ * plain-text preview instead of crashing the field.
+ */
+function useMarkdownRenderer(enabled: boolean): MarkdownComponent | null {
+  const [renderer, setRenderer] = useState<MarkdownComponent | null>(markdownRendererCache);
+
+  useEffect(() => {
+    if (!enabled || renderer) return;
+    let cancelled = false;
+    import("@multiplatform.one/markdown")
+      .then((mod) => {
+        markdownRendererCache = mod.Markdown as MarkdownComponent;
+        if (!cancelled) setRenderer(() => markdownRendererCache);
+      })
+      .catch(() => {
+        // Renderer unavailable — the plain-text fallback below stays up.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [enabled, renderer]);
+
+  return renderer;
+}
+
+interface MarkdownPreviewProps {
+  value: string;
+  compact?: boolean;
+}
+
+function MarkdownPreview({ value, compact }: MarkdownPreviewProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ compact });
+  const Renderer = useMarkdownRenderer(!!value);
+  // Content type scale follows the size knob (same idiom as CodeBlock).
+  const textSize = knobProps.sizeToken as FontSizeTokens;
+
+  return (
+    <PreviewSurface compact={compact}>
+      {!value ? (
+        <Paragraph color={formCommonColors.muted} size={textSize}>
+          {t("Nothing to preview")}
+        </Paragraph>
+      ) : Renderer ? (
+        <Renderer>{value}</Renderer>
+      ) : (
+        // Loading / renderer unavailable: honest plain-text fallback.
+        <Paragraph size={textSize} whiteSpace="pre-wrap">
+          {value}
+        </Paragraph>
+      )}
+    </PreviewSurface>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MarkdownEditorField
+// ---------------------------------------------------------------------------
+
+export interface MarkdownEditorFieldProps {
+  name?: string;
+  form?: AnyFormApi;
+  validators?: Record<string, unknown>;
+  label?: ReactNode;
+  labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+  helperText?: string;
+  error?: string | boolean;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  skeleton?: boolean;
+  compact?: boolean;
+  size?: SizeTokens;
+  id?: string;
+  value?: string;
+  defaultValue?: string;
+  /** Canonical change contract (LC-14): emits the markdown source string. */
+  onChange?: (value: string) => void;
+  onBlur?: (...args: any[]) => void;
+  placeholder?: string;
+  /** Minimum visible source rows (default 6). */
+  minRows?: number;
+  /** Maximum source rows before the textarea scrolls (default 16). */
+  maxRows?: number;
+  "aria-label"?: string;
+}
+
+export function MarkdownEditorField({
+  name,
+  form: formProp,
+  validators,
+  label,
+  labelProps,
+  helperText,
+  error,
+  required,
+  disabled,
+  readOnly,
+  skeleton,
+  compact,
+  size,
+  id: idProp,
+  value,
+  defaultValue,
+  onChange,
+  onBlur,
+  placeholder,
+  minRows = 6,
+  maxRows = 16,
+  "aria-label": ariaLabel,
+}: MarkdownEditorFieldProps) {
+  const { t } = useTranslation();
+  const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
+  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const inTableCell = useIsInTableCell();
+
+  // Standalone/uncontrolled mirror so the live preview always has the current
+  // source (the form branch reads field state instead).
+  const [internalValue, setInternalValue] = useState(value ?? defaultValue ?? "");
+  useEffect(() => {
+    if (value !== undefined) setInternalValue(value);
+  }, [value]);
+
+  const accessibleName =
+    ariaLabel ?? (typeof label === "string" ? label : undefined) ?? placeholder;
+
+  if (skeleton) {
+    return (
+      <YStack {...knobProps.gap} width="100%">
+        {label && <Skeleton variant="text" width="30%" height={14} />}
+        <Skeleton variant="rounded" width="100%" height={compact ? 120 : 200} />
+      </YStack>
+    );
+  }
+
+  const renderSource = (
+    textValue: string,
+    handleChange?: (text: string) => void,
+    hasError?: boolean,
+  ) => (
+    <TextArea
+      id={id}
+      value={textValue}
+      onChangeText={(text) => {
+        if (disabled || readOnly) return;
+        handleChange?.(text);
+        onChange?.(text);
+      }}
+      placeholder={placeholder}
+      disabled={disabled}
+      readOnly={readOnly}
+      required={required}
+      error={hasError ? true : undefined}
+      compact={compact}
+      size={size}
+      minRows={minRows}
+      maxRows={maxRows}
+      textAreaProps={{
+        fontFamily: "$mono",
+        autoCapitalize: "none",
+        autoCorrect: false,
+        spellCheck: false,
+        ...(accessibleName ? { "aria-label": accessibleName } : {}),
+      }}
+    />
+  );
+
+  // Table cells get the chromeless source pane only (no tabs/preview chrome);
+  // InputParts inside the forms TextArea detects the cell context itself.
+  const renderControl = (
+    textValue: string,
+    handleChange?: (text: string) => void,
+    hasError?: boolean,
+  ) => {
+    if (inTableCell) return renderSource(textValue, handleChange, hasError);
+    return (
+      <EditorPreviewPanes
+        editor={renderSource(textValue, handleChange, hasError)}
+        preview={<MarkdownPreview value={textValue} compact={compact} />}
+        editTabLabel={t("Write")}
+        previewTabLabel={t("Preview")}
+        compact={compact}
+        defaultPreview={!!readOnly}
+      />
+    );
+  };
+
+  if (!resolvedForm || !name) {
+    if (inTableCell) return renderControl(internalValue, setInternalValue, !!error);
+    return (
+      <FieldLayout
+        id={id}
+        label={label}
+        labelProps={labelProps}
+        error={error}
+        helperText={helperText}
+        required={required}
+        disabled={disabled}
+        size={size}
+        knobProps={knobProps}
+        onBlur={onBlur}
+        aria-label={ariaLabel}
+        placeholder={placeholder}
+      >
+        {renderControl(internalValue, setInternalValue, !!error)}
+      </FieldLayout>
+    );
+  }
+
+  return (
+    <Field
+      form={resolvedForm}
+      name={name}
+      defaultValue={defaultValue}
+      validators={resolvedValidators}
+    >
+      {(field) => {
+        const resolvedError = getFieldError(field, error);
+        const fieldValue = typeof field.state.value === "string" ? field.state.value : "";
+        const handleChange = (text: string) => field.handleChange(text as any);
+        if (inTableCell) return renderControl(fieldValue, handleChange, !!resolvedError);
+        return (
+          <FieldLayout
+            id={id}
+            label={label}
+            labelProps={labelProps}
+            error={resolvedError}
+            helperText={helperText}
+            required={required}
+            disabled={disabled}
+            size={size}
+            knobProps={knobProps}
+            onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+            aria-label={ariaLabel}
+            placeholder={placeholder}
+          >
+            {renderControl(fieldValue, handleChange, !!resolvedError)}
+          </FieldLayout>
+        );
+      }}
+    </Field>
+  );
+}