frappe-ui 1.0.0-beta.8 → 1.0.0-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-ui",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-beta.9",
   "description": "A set of components and utilities for rapid UI development",
   "type": "module",
   "sideEffects": [
@@ -56,6 +56,10 @@
       "import": "./src/molecules/editor/index.ts",
       "types": "./src/molecules/editor/index.ts"
     },
+    "./code-editor": {
+      "import": "./src/components/CodeEditor/index.ts",
+      "types": "./src/components/CodeEditor/index.ts"
+    },
     "./drive": {
       "import": "./frappe/drive/index.js"
     },
@@ -104,6 +108,16 @@
   "author": "Frappe Technologies Pvt. Ltd.",
   "license": "MIT",
   "dependencies": {
+    "@codemirror/lang-css": "^6.3.0",
+    "@codemirror/lang-html": "^6.4.9",
+    "@codemirror/lang-javascript": "^6.2.2",
+    "@codemirror/lang-json": "^6.0.1",
+    "@codemirror/lang-markdown": "^6.3.1",
+    "@codemirror/lang-python": "^6.1.6",
+    "@codemirror/lang-sass": "^6.0.2",
+    "@codemirror/lang-sql": "^6.8.0",
+    "@codemirror/lang-xml": "^6.1.0",
+    "@codemirror/lang-yaml": "^6.1.3",
     "@floating-ui/dom": "^1.7.4",
     "@headlessui/vue": "^1.7.14",
     "@popperjs/core": "^2.11.2",
@@ -146,6 +160,7 @@
     "@tiptap/suggestion": "^3.26.0",
     "@tiptap/vue-3": "^3.26.0",
     "@vueuse/core": "^10.4.1",
+    "codemirror": "^6.0.1",
     "dayjs": "^1.11.13",
     "dompurify": "^3.4.0",
     "echarts": "^5.6.0",

package/src/components/CodeEditor/CodeEditor.api.md

@@ -0,0 +1,140 @@
+<!-- Auto Generated by scripts/propsgen.ts -->
+<script setup>
+  import PropsTable from '@/components/Docs/PropsTable.vue'
+  import SlotsTable from '@/components/Docs/SlotsTable.vue'
+  import EmitsTable from '@/components/Docs/EmitsTable.vue'
+
+  const codeEditorProps = [
+  {
+    name: 'modelValue',
+    description: 'The editor\'s text content (controlled, two-way via `v-model`).',
+    required: true,
+    type: 'string'
+  },
+  {
+    name: 'language',
+    description: 'CodeMirror language key; falls through to plain text when unset/unknown.',
+    required: false,
+    type: 'CodeLanguage | (string & {})',
+    default: '"plain"'
+  },
+  {
+    name: 'disabled',
+    description: 'If true, the editor is disabled: greyed out and not editable.',
+    required: false,
+    type: 'boolean',
+    default: 'false'
+  },
+  {
+    name: 'placeholder',
+    description: 'Placeholder shown when the editor is empty.',
+    required: false,
+    type: 'string',
+    default: '""'
+  },
+  {
+    name: 'variant',
+    description: 'Surface style; mirrors frappe-ui inputs. Defaults to `subtle`.',
+    required: false,
+    type: "Exclude<InputVariant, 'ghost'>",
+    default: '"subtle"'
+  },
+  {
+    name: 'size',
+    description: 'Size token, mirroring frappe-ui inputs. Scales the editor\'s font size and\nminimum height (`sm | md | lg | xl`). Defaults to `md`.',
+    required: false,
+    type: 'InputSize',
+    default: '"md"'
+  },
+  {
+    name: 'label',
+    description: 'Label rendered above (or beside, for binary controls) the input.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'description',
+    description: 'Helper text rendered below the input.\nHidden when `error` is set.',
+    required: false,
+    type: 'string'
+  },
+  {
+    name: 'error',
+    description: 'Error message rendered below the input. When set, the control receives\n`aria-invalid="true"` and `data-state="invalid"`. May be either a string\nor an `Error` object whose `messages?: string[]` is rendered as stacked\nlines (with `Error.message` as the fallback).',
+    required: false,
+    type: 'string | FrappeUIError'
+  },
+  {
+    name: 'required',
+    description: 'Marks the field as required. Renders an asterisk next to the label and\nforwards `required` / `aria-required` to the underlying control.',
+    required: false,
+    type: 'boolean'
+  },
+  {
+    name: 'id',
+    description: 'HTML id of the underlying control. Auto-generated via `useId()` if omitted.',
+    required: false,
+    type: 'string'
+  }
+]
+
+  const codeEditorSlots = [
+  {
+    name: 'label',
+    description: 'Overrides the rendered label content. Receives `{ required }`.',
+    type: '{ required: boolean; }'
+  },
+  {
+    name: 'description',
+    description: 'Overrides the rendered description content.',
+    type: 'any'
+  }
+]
+
+  const codeEditorEmits = [
+  {
+    name: 'update:modelValue',
+    description: 'Fired when the model value changes.',
+    type: '[value: string]'
+  },
+  {
+    name: 'change',
+    description: 'Fired after the value is committed.',
+    type: '[value: string]'
+  },
+  {
+    name: 'overflow',
+    description: 'Fired when content crosses the `--cm-max-height` cap (transitions only). The cap is a CSS hook, not a prop — set `--cm-max-height` on the root.',
+    type: '[overflowing: boolean]'
+  }
+]
+
+  const codePreviewProps = [
+  {
+    name: 'modelValue',
+    description: 'The source text to render as sanitized preview output.',
+    required: true,
+    type: 'string'
+  },
+  {
+    name: 'language',
+    description: 'Only `markdown` / `html` render a preview; anything else renders nothing.',
+    required: false,
+    type: 'CodeLanguage | (string & {})'
+  }
+]
+</script>
+## API Reference
+
+### CodeEditor
+
+<PropsTable name="CodeEditor" :data="codeEditorProps"/> 
+
+<SlotsTable :data="codeEditorSlots"/> 
+
+<EmitsTable :data="codeEditorEmits"/> 
+
+### CodePreview
+
+<PropsTable folder="CodeEditor" name="CodePreview" :data="codePreviewProps"/> 
+

package/src/components/CodeEditor/CodeEditor.cy.ts

@@ -0,0 +1,156 @@
+import CodeEditor from './CodeEditor.vue'
+
+// CodeMirror lazy-loads in `onMounted` (dynamic imports) and renders into a
+// `.cm-editor` with a contenteditable `.cm-content`. Cypress retries `cy.get`
+// until that async mount settles, so no explicit wait is needed.
+
+describe('CodeEditor', () => {
+  it('mounts the editor with the initial document', () => {
+    cy.mount(CodeEditor, { props: { modelValue: 'const a = 1' } })
+    cy.get('.cm-editor').should('exist')
+    cy.get('.cm-content').should('contain.text', 'const a = 1')
+  })
+
+  it('emits update:modelValue live while typing', () => {
+    cy.mount(CodeEditor, {
+      props: {
+        modelValue: '',
+        'onUpdate:modelValue': cy.stub().as('update'),
+      },
+    })
+    cy.get('.cm-content').type('hello')
+    cy.get('@update').should('have.been.called')
+    // The last emit carries the full document.
+    cy.get('@update')
+      .its('lastCall.args.0')
+      .should('eq', 'hello')
+  })
+
+  it('emits change only on blur (commit), not on every keystroke', () => {
+    cy.mount(CodeEditor, {
+      props: {
+        modelValue: '',
+        onChange: cy.stub().as('change'),
+      },
+    })
+    cy.get('.cm-content').type('draft')
+    // No commit while focused.
+    cy.get('@change').should('not.have.been.called')
+    cy.get('.cm-content').blur()
+    cy.get('@change').should('have.been.calledOnceWith', 'draft')
+  })
+
+  it('Escape blurs the editor so the keyboard trap has an exit (commits)', () => {
+    cy.mount(CodeEditor, {
+      props: { modelValue: '', onChange: cy.stub().as('change') },
+    })
+    cy.get('.cm-content').type('x')
+    cy.get('.cm-content').trigger('keydown', { key: 'Escape' })
+    cy.get('@change').should('have.been.calledOnceWith', 'x')
+  })
+
+  it('does not emit update:modelValue when synced from the prop', () => {
+    // Updating modelValue externally must not echo back out as fresh input.
+    cy.mount(CodeEditor, {
+      props: {
+        modelValue: 'one',
+        'onUpdate:modelValue': cy.stub().as('update'),
+      },
+    }).then(({ wrapper }) => {
+      wrapper.setProps({ modelValue: 'one two three' })
+      cy.get('.cm-content').should('contain.text', 'one two three')
+      cy.get('@update').should('not.have.been.called')
+    })
+  })
+
+  it('is not editable when disabled', () => {
+    cy.mount(CodeEditor, {
+      props: { modelValue: 'frozen', disabled: true },
+    })
+    cy.get('.cm-content').should('have.attr', 'contenteditable', 'false')
+    cy.get('.code-editor').should('have.attr', 'data-disabled', 'true')
+  })
+
+  it('swaps disabled at runtime without recreating the view', () => {
+    cy.mount(CodeEditor, {
+      props: { modelValue: 'frozen', disabled: true },
+    }).then(({ wrapper }) => {
+      cy.get('.cm-content').should('have.attr', 'contenteditable', 'false')
+      wrapper.setProps({ disabled: false })
+      cy.get('.cm-content').should('have.attr', 'contenteditable', 'true')
+    })
+  })
+
+  it('exposes the data-* styling hooks on the control', () => {
+    cy.mount(CodeEditor, {
+      props: { modelValue: '', variant: 'outline', size: 'lg' },
+    })
+    cy.get('.code-editor').should('have.attr', 'data-slot', 'control')
+    cy.get('.code-editor').should('have.attr', 'data-variant', 'outline')
+    cy.get('.code-editor').should('have.attr', 'data-size', 'lg')
+  })
+
+  describe('labeling contract', () => {
+    it('renders the label and wires aria onto the contentDOM', () => {
+      cy.mount(CodeEditor, {
+        props: {
+          modelValue: '',
+          label: 'Config',
+          description: 'JSON config',
+        },
+      })
+      cy.contains('label', 'Config').should('exist')
+      cy.get('.cm-content').then(($el) => {
+        const describedBy = $el.attr('aria-describedby')
+        expect(describedBy).to.be.ok
+        cy.get(`#${describedBy}`).should('contain.text', 'JSON config')
+      })
+    })
+
+    it('marks the contentDOM invalid and shows the error', () => {
+      cy.mount(CodeEditor, {
+        props: { modelValue: '', error: 'Invalid JSON' },
+      })
+      cy.get('.cm-content').should('have.attr', 'aria-invalid', 'true')
+      cy.get('.code-editor').should('have.attr', 'data-state', 'invalid')
+      cy.contains('Invalid JSON').should('exist')
+    })
+
+    it('forwards required onto aria-required', () => {
+      cy.mount(CodeEditor, {
+        props: { modelValue: '', label: 'Body', required: true },
+      })
+      cy.get('.cm-content').should('have.attr', 'aria-required', 'true')
+    })
+  })
+
+  describe('overflow', () => {
+    // The cap is a CSS hook (`--cm-max-height` on the root), not a prop — set it
+    // via attribute fallthrough, the same way a consumer would.
+    const longDoc = Array.from({ length: 40 }, (_, i) => `line ${i}`).join('\n')
+
+    it('emits overflow=true when content exceeds the --cm-max-height cap', () => {
+      cy.mount(CodeEditor, {
+        props: {
+          modelValue: longDoc,
+          onOverflow: cy.stub().as('overflow'),
+        },
+        attrs: { style: '--cm-max-height: 6rem' },
+      })
+      cy.get('@overflow').should('have.been.calledWith', true)
+    })
+
+    it('does not emit overflow when content fits under the cap', () => {
+      cy.mount(CodeEditor, {
+        props: {
+          modelValue: 'short',
+          onOverflow: cy.stub().as('overflow'),
+        },
+        attrs: { style: '--cm-max-height: 20rem' },
+      })
+      // Give the ResizeObserver/mount a beat, then assert it stayed quiet.
+      cy.get('.cm-editor').should('exist')
+      cy.get('@overflow').should('not.have.been.calledWith', true)
+    })
+  })
+})

package/src/components/CodeEditor/CodeEditor.md

@@ -0,0 +1,104 @@
+# CodeEditor
+
+A CodeMirror 6 code field with syntax highlighting, theming that follows the
+app's light/dark scheme, and an optional sanitized preview. CodeMirror is
+lazy-loaded, so apps that never render a code field pay no runtime cost.
+
+CodeEditor ships from its own subpath so the CodeMirror dependency only loads
+for apps that opt in:
+
+```js
+import { CodeEditor, CodePreview } from 'frappe-ui/code-editor'
+```
+
+## Playground
+
+<ClientOnly><CodeEditorBuilder /></ClientOnly>
+
+<ComponentPreview name="CodeEditor-Default" layout="stacked" class="mt-4" />
+
+## Languages
+
+Pass a `language` key to enable highlighting. Each language tree-shakes into
+its own async chunk, loaded on demand. Supported keys: `json`, `html`,
+`javascript`, `python`, `sql`, `markdown`, `css`, `scss`, `yaml`, `xml`, and
+`plain` (the default — no highlighting). Unknown keys fall through to plain
+text. `json` additionally wires an inline lint gutter so invalid JSON is
+flagged at its position.
+
+## Variants
+
+The surface mirrors frappe-ui's input convention so a code field sits flush
+with the TextInput/Textarea fields around it. `subtle` is the filled default and
+`outline` is a bordered box on white. The borderless `ghost` variant is
+intentionally not offered — a code surface without a border reads as plain text
+and loses the affordance that it's an editable field.
+
+<ComponentPreview name="CodeEditor-Variants" />
+
+## Sizes
+
+`size` mirrors the frappe-ui input sizes (`sm | md | lg | xl`, default `md`),
+scaling the editor's font size and minimum height.
+
+<ComponentPreview name="CodeEditor-Sizes" />
+
+## Max height
+
+The height cap is a CSS hook, not a prop — set the `--cm-max-height` custom
+property on the root to any CSS length and content past the cap scrolls
+internally:
+
+```vue
+<CodeEditor v-model="code" style="--cm-max-height: 12rem" />
+```
+
+Pair it with the `overflow` emit (fired only when the content crosses the cap)
+to drive an expand/collapse affordance — that's the one piece you can't measure
+from CSS yourself.
+
+<ComponentPreview name="CodeEditor-MaxHeight" />
+
+## Preview
+
+`CodePreview` is a separate, display-only primitive that renders sanitized
+output for the two languages with a meaningful preview — `markdown` (rendered
+via `marked`) and `html`. Both are passed through DOMPurify before rendering;
+any other language renders nothing. The writer and preview are independent, so
+how you compose them — editor-only, a Write/Preview toggle, or a side-by-side
+split — is up to the consumer.
+
+<ComponentPreview name="CodeEditor-Preview" />
+
+## Labeling
+
+CodeEditor implements the shared input labeling contract (`label`,
+`description`, `error`, `required`). When something needs the chrome it renders
+a wrapping field; otherwise the editor mounts bare, so the primitive's
+footprint is unchanged. Setting `error` flips the field to its invalid state
+(`data-state="invalid"`, `aria-invalid`) and renders the message below; the
+ARIA wiring is applied to the editor's internal content element so it reaches
+the focusable control.
+
+<ComponentPreview name="CodeEditor-Labeling" />
+
+## Keyboard
+
+| Keys | Action |
+| --- | --- |
+| `Tab` / `Shift`+`Tab` | Indent / dedent the current line or selection |
+| `Escape` | Release focus so `Tab` moves to the next field |
+
+`Tab` is rebound to indent (the editor default is a focus-move). `Escape`
+blurs the editor so keyboard users can still tab on — the standard CodeMirror
+keyboard-trap escape hatch (WCAG 2.1.2).
+
+## Commit contract
+
+`update:modelValue` fires live on every change (mirrors the textarea field
+contract); `change` fires on blur, the commit point where a wrapper would
+normalize the value (e.g. JSON pretty-print). External `modelValue` changes
+are diffed into the view so the caret, selection, and scroll position survive
+a live transform.
+
+<!-- @include: ./CodeEditor.api.md -->