nuxt-codemirror 0.0.7 → 0.0.9

package/README.md

@@ -22,6 +22,152 @@ Codemirror as a Nuxt module. Demo preview: Coming soon
 - 🌲 Custom useNuxtCodeMirror composable for creating your own editor
 - Built for CodeMirror 6 and above
 
+## Documentation
+
+This module consists of one Component, one Composable and a few types for you to use. 
+Read the CodeMirror Reference guide for more in depth information: [CodeMirror docs](https://codemirror.net/docs/ref/)
+
+### NuxtCodeMirror.vue
+This component is auto imported and is the CodeMirror wrapper.
+
+Component props:
+```
+interface NuxtCodeMirrorProps
+  extends Omit<EditorStateConfig, 'doc' | 'extensions'> {
+  /** value of the auto created model in the editor. Works as underlying logic of a V-Model */
+  modelValue?: string                                                                                    This is linked to a Vue V-Model
+  /** The height value of the editor. */
+  height?: string
+  /** The minimum height value of the editor. */
+  minHeight?: string
+  /** The maximum height value of the editor. */
+  maxHeight?: string
+  /** The width value of the editor. */
+  width?: string
+  /** The minimum width value of the editor. */
+  minWidth?: string
+  /** The maximum width value of the editor. */
+  maxWidth?: string
+  /** focus on the editor. */
+  autoFocus?: boolean
+  /** Enables a placeholder—a piece of example content to show when the editor is empty. */
+  placeholder?: string | HTMLElement
+  /**
+   * `light` / `dark` / `Extension` Defaults to `light`.
+   * @default light
+   */
+  theme?: 'light' | 'dark' | 'none' | Extension
+  /**
+   * Whether to optional basicSetup by default
+   * @default true
+   */
+  basicSetup?: boolean | BasicSetupOptions
+  /**
+   * This disables editing of the editor content by the user.
+   * @default true
+   */
+  editable?: boolean
+  /**
+   * This disables editing of the editor content by the user.
+   * @default false
+   */
+  readOnly?: boolean
+  /**
+   * Controls whether pressing the `Tab` key inserts a tab character and indents the text (`true`)
+   * or behaves according to the browser's default behavior (`false`).
+   * @default true
+   */
+  indentWithTab?: boolean
+  /** Fired whenever a change occurs to the document. */
+  onChange?(value: string, viewUpdate: ViewUpdate): void
+  /** Some data on the statistics editor. */
+  onStatistics?(data: Statistics): void
+  /** Fired whenever any state change occurs within the editor, including non-document changes like lint results. */
+  onUpdate?(viewUpdate: ViewUpdate): void
+  /** The first time the editor executes the event. */
+  onCreateEditor?(view: EditorView, state: EditorState): void
+  /** Fired whenever the editor is focused. */
+  onFocus?(view: ViewUpdate): void
+  /** Fired whenever the editor is blurred. */
+  onBlur?(view: ViewUpdate): void
+  /**
+   * Extension values can be [provided](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions) when creating a state to attach various kinds of configuration and behavior information.
+   * They can either be built-in extension-providing objects,
+   * such as [state fields](https://codemirror.net/6/docs/ref/#state.StateField) or [facet providers](https://codemirror.net/6/docs/ref/#state.Facet.of),
+   * or objects with an extension in its `extension` property. Extensions can be nested in arrays arbitrarily deep—they will be flattened when processed.
+   */
+  extensions?: Extension[]
+  /**
+   * If the view is going to be mounted in a shadow root or document other than the one held by the global variable document (the default), you should pass it here.
+   * Originally from the [config of EditorView](https://codemirror.net/6/docs/ref/#view.EditorView.constructor%5Econfig.root)
+   */
+  root?: ShadowRoot | Document
+  /**
+   * Create a state from its JSON representation serialized with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function
+   */
+  initialState?: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    json: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    fields?: Record<string, StateField<any>>
+  }
+}
+```
+
+The NuxtCodeMirror component accepts a Template ref and exposes The CodeMirror div element, the Editor view and the Editor State
+
+```
+interface CodeMirrorRef {
+  /** Container element of the CodeMirror instance */
+  container: HTMLDivElement | null
+  /** The EditorView of the CodeMirror instance */
+  view: EditorView | undefined
+  /** The EditorState of the CodeMirror instance */
+  state: EditorState | undefined
+  /** Editor element of the CodeMirror instance */
+  editor: HTMLDivElement | null
+}
+```
+
+If you need access to the underlying CodeMirror instance You can do so by adding a ref with the same name as your Template ref. 
+An example on how to do this can be found here: [🏀 Online playground](https://stackblitz.com/edit/nuxt-starter-ev2hgm?file=app.vue)
+
+
+If for some reason you want to write your own CodeMirror component then you can do that too :)
+
+### UseNuxtCodeMirror.ts
+This composable is the underlying magic of the NuxtCodeMirror component and is also auto imported.
+
+It requires minimum 3 Refs, one for the div element CodeMirror will connect to, one for the CodeMirror view, and one for the CodeMirror state
+
+Make sure you execute the composable in onMounted otherwise you will get an eror because codemirror can't be linked to the DOM.
+
+```
+  /** The EditorView of the CodeMirror instance */
+  viewRef: Ref<EditorView | undefined>
+  /** The EditorState of the CodeMirror instance */
+  stateRef: Ref<EditorState | undefined>
+  /** Editor element of the CodeMirror instance */
+  containerRef: Ref<HTMLDivElement | null>
+
+const editor = ref<HTMLDivElement | null>(null)
+const container = ref<HTMLDivElement | null>(null)
+const view = ref<EditorView>()
+const state = ref<EditorState>()
+
+  onMounted(() => {
+  useNuxtCodeMirror({
+    ...props,
+    container: editor.value,
+    viewRef: view,
+    stateRef: state,
+    containerRef: container,
+  })
+})
+```
+
+For more information on how this is implemented see the [source](https://github.com/ThimoDEV/nuxt-codemirror/blob/master/src/runtime/components/NuxtCodeMirror.vue), to get inspiration for your own version
+
 ## Credits
 
 This Nuxt module wouldn't be possible without:
@@ -39,8 +185,25 @@ npx nuxi module add nuxt-codemirror
 
 That's it! You can now use Nuxt-codemirror in your Nuxt app ✨
 
+### Tested extensions
+
+Below is a list of tested extensions you can use as of @codemirror/view version 6.29.1 and @codemirror/state verion 6.4.1
+
+- [LineNumbersRelative](https://www.npmjs.com/package/@uiw/codemirror-extensions-line-numbers-relative)
+- [lang-javascript](https://www.npmjs.com/package/@codemirror/lang-javascript)
+- [IndentationMarkers](https://github.com/replit/codemirror-indentation-markers)
+- [interact](https://github.com/replit/codemirror-interact)
+- [Themes -- like](https://www.npmjs.com/package/@uiw/codemirror-theme-okaidia)
+- [Zebra Stripes](https://www.npmjs.com/package/@uiw/codemirror-extensions-zebra-stripes)
+
+and many more...
+
 ## Contribution
 
+If you have ideas or bugs feel free to start by opening an issue. For ideas please start a Discussion.
+
+I welcome any kind of contribution Thank you in advance!!
+
 <details>
   <summary>Local development</summary>
 
@@ -88,6 +251,8 @@ That's it! You can now use Nuxt-codemirror in your Nuxt app ✨
 
 ## FAQ
 
-- I get an extension duplicate error:  Fix Unrecognized extension value in extension set ([object Object]). This sometimes happens because multiple instances of @codemirror/state are loaded, breaking instanceof checks.
+Issue
+- I get errors when starting the dev server with your module: `Pre-transform error: Failed to resolve import "@codemirror/view"`, `Pre-transform error: Failed to resolve import "@codemirror/state"`.
 
-For now write shamefully-hoist=true in your .npmrc file to solve this. We are working on a better solution
+Solution
+- Assuming you use pnpm with `shamefully-hoist=false` install `@codemirror/state` and `@codemirror/view` and these errors should disappear

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-codemirror",
   "configKey": "nuxtCodemirror",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "builder": {
     "@nuxt/module-builder": "0.8.1",
     "unbuild": "2.0.0"

package/dist/runtime/components/NuxtCodeMirror.vue

@@ -49,10 +49,6 @@ onMounted(() => {
     stateRef: state,
     containerRef: container,
   })
-
-  /** DEBUGGING the variables exposed by defineExpose */
-  // await nextTick()
-  // console.log('test: ', view.value)
 })
 
 onBeforeUnmount(() => {

package/dist/runtime/types/nuxt-codemirror.d.ts

@@ -1,128 +1,137 @@
-import type { EditorState, EditorStateConfig, Extension, StateField, EditorSelection, SelectionRange, Line } from '@codemirror/state'
-import type { EditorView, ViewUpdate } from '@codemirror/view'
-import type { BasicSetupOptions } from '@uiw/codemirror-extensions-basic-setup'
-import type { Ref } from '#imports'
-
-export interface NuxtCodeMirrorProps
-  extends Omit<EditorStateConfig, 'doc' | 'extensions'> {
-  /** value of the auto created model in the editor. */
-  modelValue?: string
-  height?: string
-  minHeight?: string
-  maxHeight?: string
-  width?: string
-  minWidth?: string
-  maxWidth?: string
-  /** focus on the editor. */
-  autoFocus?: boolean
-  /** Enables a placeholder—a piece of example content to show when the editor is empty. */
-  placeholder?: string | HTMLElement
-  /**
-   * `light` / `dark` / `Extension` Defaults to `light`.
-   * @default light
-   */
-  theme?: 'light' | 'dark' | 'none' | Extension
-  /**
-   * Whether to optional basicSetup by default
-   * @default true
-   */
-  basicSetup?: boolean | BasicSetupOptions
-  /**
-   * This disables editing of the editor content by the user.
-   * @default true
-   */
-  editable?: boolean
-  /**
-   * This disables editing of the editor content by the user.
-   * @default false
-   */
-  readOnly?: boolean
-  /**
-   * Controls whether pressing the `Tab` key inserts a tab character and indents the text (`true`)
-   * or behaves according to the browser's default behavior (`false`).
-   * @default true
-   */
-  indentWithTab?: boolean
-  /** Fired whenever a change occurs to the document. */
-  onChange?(value: string, viewUpdate: ViewUpdate): void
-  /** Some data on the statistics editor. */
-  onStatistics?(data: Statistics): void
-  /** Fired whenever any state change occurs within the editor, including non-document changes like lint results. */
-  onUpdate?(viewUpdate: ViewUpdate): void
-  /** The first time the editor executes the event. */
-  onCreateEditor?(view: EditorView, state: EditorState): void
-  /** Fired whenever the editor is focused. */
-  onFocus?(view: ViewUpdate): void
-  /** Fired whenever the editor is blurred. */
-  onBlur?(view: ViewUpdate): void
-  /**
-   * Extension values can be [provided](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions) when creating a state to attach various kinds of configuration and behavior information.
-   * They can either be built-in extension-providing objects,
-   * such as [state fields](https://codemirror.net/6/docs/ref/#state.StateField) or [facet providers](https://codemirror.net/6/docs/ref/#state.Facet.of),
-   * or objects with an extension in its `extension` property. Extensions can be nested in arrays arbitrarily deep—they will be flattened when processed.
-   */
-  extensions?: Extension[]
-  /**
-   * If the view is going to be mounted in a shadow root or document other than the one held by the global variable document (the default), you should pass it here.
-   * Originally from the [config of EditorView](https://codemirror.net/6/docs/ref/#view.EditorView.constructor%5Econfig.root)
-   */
-  root?: ShadowRoot | Document
-  /**
-   * Create a state from its JSON representation serialized with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function
-   */
-  initialState?: {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    json: any
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    fields?: Record<string, StateField<any>>
-  }
-}
-
-export interface UseCodeMirrorProps extends NuxtCodeMirrorProps {
-  /** Container element of the CodeMirror instance */
-  container?: HTMLDivElement | null
-  viewRef: Ref<EditorView | undefined>
-  stateRef: Ref<EditorState | undefined>
-  containerRef: Ref<HTMLDivElement | null>
-}
-
-export interface Statistics {
-  /** total length of the document */
-  length: number
-  /** Get the number of lines in the editor. */
-  lineCount: number
-  /** Get the currently line description around the given position. */
-  line: Line
-  /** Get the proper [line-break](https://codemirror.net/docs/ref/#state.EditorState^lineSeparator) string for this state. */
-  lineBreak: string
-  /** Returns true when the editor is [configured](https://codemirror.net/6/docs/ref/#state.EditorState^readOnly) to be read-only. */
-  readOnly: boolean
-  /** The size (in columns) of a tab in the document, determined by the [`tabSize`](https://codemirror.net/6/docs/ref/#state.EditorState^tabSize) facet. */
-  tabSize: number
-  /** Cursor Position */
-  selection: EditorSelection
-  /** Make sure the selection only has one range. */
-  selectionAsSingle: SelectionRange
-  /** Retrieves a list of all current selections. */
-  ranges: readonly SelectionRange[]
-  /** Get the currently selected code. */
-  selectionCode: string
-  /**
-   * The length of the given array should be the same as the number of active selections.
-   * Replaces the content of the selections with the strings in the array.
-   */
-  selections: string[]
-  /** Return true if any text is selected. */
-  selectedText: boolean
-}
-
-export interface CodeMirrorRef {
-  /** Container element of the CodeMirror instance */
-  container: HTMLDivElement | null
-  /** The EditorView of the CodeMirror instance */
-  view: EditorView | undefined
-  /** The EditorState of the CodeMirror instance */
-  state: EditorState | undefined
-  /** Editor element of the CodeMirror instance */
-  editor: HTMLDivElement | null
-}
+import type { EditorState, EditorStateConfig, Extension, StateField, EditorSelection, SelectionRange, Line } from '@codemirror/state'
+import type { EditorView, ViewUpdate } from '@codemirror/view'
+import type { BasicSetupOptions } from '@uiw/codemirror-extensions-basic-setup'
+import type { Ref } from '#imports'
+
+export interface NuxtCodeMirrorProps
+  extends Omit<EditorStateConfig, 'doc' | 'extensions'> {
+  /** value of the auto created model in the editor. Works as underlying logic of a V-Model */
+  modelValue?: string
+  /** The height value of the editor. */
+  height?: string
+  /** The minimum height value of the editor. */
+  minHeight?: string
+  /** The maximum height value of the editor. */
+  maxHeight?: string
+  /** The width value of the editor. */
+  width?: string
+  /** The minimum width value of the editor. */
+  minWidth?: string
+  /** The maximum width value of the editor. */
+  maxWidth?: string
+  /** focus on the editor. */
+  autoFocus?: boolean
+  /** Enables a placeholder—a piece of example content to show when the editor is empty. */
+  placeholder?: string | HTMLElement
+  /**
+   * `light` / `dark` / `Extension` Defaults to `light`.
+   * @default light
+   */
+  theme?: 'light' | 'dark' | 'none' | Extension
+  /**
+   * Whether to optional basicSetup by default
+   * @default true
+   */
+  basicSetup?: boolean | BasicSetupOptions
+  /**
+   * This disables editing of the editor content by the user.
+   * @default true
+   */
+  editable?: boolean
+  /**
+   * This disables editing of the editor content by the user.
+   * @default false
+   */
+  readOnly?: boolean
+  /**
+   * Controls whether pressing the `Tab` key inserts a tab character and indents the text (`true`)
+   * or behaves according to the browser's default behavior (`false`).
+   * @default true
+   */
+  indentWithTab?: boolean
+  /** Fired whenever a change occurs to the document. */
+  onChange?(value: string, viewUpdate: ViewUpdate): void
+  /** Some data on the statistics editor. */
+  onStatistics?(data: Statistics): void
+  /** Fired whenever any state change occurs within the editor, including non-document changes like lint results. */
+  onUpdate?(viewUpdate: ViewUpdate): void
+  /** The first time the editor executes the event. */
+  onCreateEditor?(view: EditorView, state: EditorState): void
+  /** Fired whenever the editor is focused. */
+  onFocus?(view: ViewUpdate): void
+  /** Fired whenever the editor is blurred. */
+  onBlur?(view: ViewUpdate): void
+  /**
+   * Extension values can be [provided](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions) when creating a state to attach various kinds of configuration and behavior information.
+   * They can either be built-in extension-providing objects,
+   * such as [state fields](https://codemirror.net/6/docs/ref/#state.StateField) or [facet providers](https://codemirror.net/6/docs/ref/#state.Facet.of),
+   * or objects with an extension in its `extension` property. Extensions can be nested in arrays arbitrarily deep—they will be flattened when processed.
+   */
+  extensions?: Extension[]
+  /**
+   * If the view is going to be mounted in a shadow root or document other than the one held by the global variable document (the default), you should pass it here.
+   * Originally from the [config of EditorView](https://codemirror.net/6/docs/ref/#view.EditorView.constructor%5Econfig.root)
+   */
+  root?: ShadowRoot | Document
+  /**
+   * Create a state from its JSON representation serialized with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function
+   */
+  initialState?: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    json: any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    fields?: Record<string, StateField<any>>
+  }
+}
+
+export interface UseCodeMirrorProps extends NuxtCodeMirrorProps {
+  /** Container element of the CodeMirror instance */
+  container?: HTMLDivElement | null
+  /** The EditorView of the CodeMirror instance */
+  viewRef: Ref<EditorView | undefined>
+  /** The EditorState of the CodeMirror instance */
+  stateRef: Ref<EditorState | undefined>
+  /** Editor element of the CodeMirror instance */
+  containerRef: Ref<HTMLDivElement | null>
+}
+
+export interface Statistics {
+  /** total length of the document */
+  length: number
+  /** Get the number of lines in the editor. */
+  lineCount: number
+  /** Get the currently line description around the given position. */
+  line: Line
+  /** Get the proper [line-break](https://codemirror.net/docs/ref/#state.EditorState^lineSeparator) string for this state. */
+  lineBreak: string
+  /** Returns true when the editor is [configured](https://codemirror.net/6/docs/ref/#state.EditorState^readOnly) to be read-only. */
+  readOnly: boolean
+  /** The size (in columns) of a tab in the document, determined by the [`tabSize`](https://codemirror.net/6/docs/ref/#state.EditorState^tabSize) facet. */
+  tabSize: number
+  /** Cursor Position */
+  selection: EditorSelection
+  /** Make sure the selection only has one range. */
+  selectionAsSingle: SelectionRange
+  /** Retrieves a list of all current selections. */
+  ranges: readonly SelectionRange[]
+  /** Get the currently selected code. */
+  selectionCode: string
+  /**
+   * The length of the given array should be the same as the number of active selections.
+   * Replaces the content of the selections with the strings in the array.
+   */
+  selections: string[]
+  /** Return true if any text is selected. */
+  selectedText: boolean
+}
+
+export interface CodeMirrorRef {
+  /** Container element of the CodeMirror instance */
+  container: HTMLDivElement | null
+  /** The EditorView of the CodeMirror instance */
+  view: EditorView | undefined
+  /** The EditorState of the CodeMirror instance */
+  state: EditorState | undefined
+  /** Editor element of the CodeMirror instance */
+  editor: HTMLDivElement | null
+}

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "nuxt-codemirror",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Nuxt codemirror module",
   "repository": "https://github.com/ThimoDEV/nuxt-codemirror",
   "license": "MIT",
   "type": "module",
+  "author": {
+    "name": "ThimoDEV",
+    "url": "https://github.com/ThimoDEV"
+  },
   "exports": {
     ".": {
       "types": "./dist/types.d.ts",
@@ -29,6 +33,7 @@
     "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
   },
   "dependencies": {
+    "@babel/runtime": "^7.25.0",
     "@codemirror/commands": "^6.6.0",
     "@codemirror/state": "6.4.1",
     "@codemirror/theme-one-dark": "^6.1.1",
@@ -49,5 +54,11 @@
     "typescript": "latest",
     "vitest": "^2.0.3",
     "vue-tsc": "^2.0.26"
-  }
-}
+  },
+  "keywords": [
+    "nuxt",
+    "codemirror",
+    "vue"
+  ],
+  "packageManager": "pnpm@9.6.0"
+}