Skip to content

Commit 0bca0d6

Browse files
ThimoDEVThimoDEV
authored
docs: add docs for components and update FAQ
1 parent cf76fd9 commit 0bca0d6

File tree

1 file changed

+156
-2
lines changed

1 file changed

+156
-2
lines changed

‎README.md

Lines changed: 156 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,154 @@ Codemirror as a Nuxt module. Demo preview: Coming soon
2222
- 🌲 Custom useNuxtCodeMirror composable for creating your own editor
2323
- Built for CodeMirror 6 and above
2424

25+
## Documentation
26+
27+
This module consists of one Component, one Composable and a few types for you to use.
28+
Read the CodeMirror Reference guide for more in depth information: [CodeMirror docs](https://codemirror.net/docs/ref/)
29+
30+
### NuxtCodeMirror.vue
31+
This component is auto imported and is the CodeMirror wrapper.
32+
33+
Component props:
34+
```
35+
interface NuxtCodeMirrorProps
36+
extends Omit<EditorStateConfig, 'doc' | 'extensions'> {
37+
/** value of the auto created model in the editor. Works as underlying logic of a V-Model */
38+
modelValue?: string This is linked to a Vue V-Model
39+
/** The height value of the editor. */
40+
height?: string
41+
/** The minimum height value of the editor. */
42+
minHeight?: string
43+
/** The maximum height value of the editor. */
44+
maxHeight?: string
45+
/** The width value of the editor. */
46+
width?: string
47+
/** The minimum width value of the editor. */
48+
minWidth?: string
49+
/** The maximum width value of the editor. */
50+
maxWidth?: string
51+
/** focus on the editor. */
52+
autoFocus?: boolean
53+
/** Enables a placeholder—a piece of example content to show when the editor is empty. */
54+
placeholder?: string | HTMLElement
55+
/**
56+
* `light` / `dark` / `Extension` Defaults to `light`.
57+
* @default light
58+
*/
59+
theme?: 'light' | 'dark' | 'none' | Extension
60+
/**
61+
* Whether to optional basicSetup by default
62+
* @default true
63+
*/
64+
basicSetup?: boolean | BasicSetupOptions
65+
/**
66+
* This disables editing of the editor content by the user.
67+
* @default true
68+
*/
69+
editable?: boolean
70+
/**
71+
* This disables editing of the editor content by the user.
72+
* @default false
73+
*/
74+
readOnly?: boolean
75+
/**
76+
* Controls whether pressing the `Tab` key inserts a tab character and indents the text (`true`)
77+
* or behaves according to the browser's default behavior (`false`).
78+
* @default true
79+
*/
80+
indentWithTab?: boolean
81+
/** Fired whenever a change occurs to the document. */
82+
onChange?(value: string, viewUpdate: ViewUpdate): void
83+
/** Some data on the statistics editor. */
84+
onStatistics?(data: Statistics): void
85+
/** Fired whenever any state change occurs within the editor, including non-document changes like lint results. */
86+
onUpdate?(viewUpdate: ViewUpdate): void
87+
/** The first time the editor executes the event. */
88+
onCreateEditor?(view: EditorView, state: EditorState): void
89+
/** Fired whenever the editor is focused. */
90+
onFocus?(view: ViewUpdate): void
91+
/** Fired whenever the editor is blurred. */
92+
onBlur?(view: ViewUpdate): void
93+
/**
94+
* 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.
95+
* They can either be built-in extension-providing objects,
96+
* such as [state fields](https://codemirror.net/6/docs/ref/#state.StateField) or [facet providers](https://codemirror.net/6/docs/ref/#state.Facet.of),
97+
* or objects with an extension in its `extension` property. Extensions can be nested in arrays arbitrarily deep—they will be flattened when processed.
98+
*/
99+
extensions?: Extension[]
100+
/**
101+
* 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.
102+
* Originally from the [config of EditorView](https://codemirror.net/6/docs/ref/#view.EditorView.constructor%5Econfig.root)
103+
*/
104+
root?: ShadowRoot | Document
105+
/**
106+
* Create a state from its JSON representation serialized with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function
107+
*/
108+
initialState?: {
109+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
110+
json: any
111+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
112+
fields?: Record<string, StateField<any>>
113+
}
114+
}
115+
```
116+
117+
The NuxtCodeMirror component accepts a Template ref and exposes The CodeMirror div element, the Editor view and the Editor State
118+
119+
```
120+
interface CodeMirrorRef {
121+
/** Container element of the CodeMirror instance */
122+
container: HTMLDivElement | null
123+
/** The EditorView of the CodeMirror instance */
124+
view: EditorView | undefined
125+
/** The EditorState of the CodeMirror instance */
126+
state: EditorState | undefined
127+
/** Editor element of the CodeMirror instance */
128+
editor: HTMLDivElement | null
129+
}
130+
```
131+
132+
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.
133+
An example on how to do this can be found here: [🏀 Online playground](https://stackblitz.com/edit/nuxt-starter-ev2hgm?file=app.vue)
134+
135+
136+
If for some reason you want to write your own CodeMirror component then you can do that too :)
137+
138+
### UseNuxtCodeMirror.ts
139+
This composable is the underlying magic of the NuxtCodeMirror component and is also auto imported.
140+
141+
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
142+
143+
Make sure you execute the composable in onMounted otherwise you will get an eror because codemirror can't be linked to the DOM.
144+
145+
```
146+
/** The EditorView of the CodeMirror instance */
147+
viewRef: Ref<EditorView | undefined>
148+
/** The EditorState of the CodeMirror instance */
149+
stateRef: Ref<EditorState | undefined>
150+
/** Editor element of the CodeMirror instance */
151+
containerRef: Ref<HTMLDivElement | null>
152+
153+
const editor = ref<HTMLDivElement | null>(null)
154+
const container = ref<HTMLDivElement | null>(null)
155+
const view = ref<EditorView>()
156+
const state = ref<EditorState>()
157+
158+
onMounted(() => {
159+
useNuxtCodeMirror({
160+
...props,
161+
container: editor.value,
162+
viewRef: view,
163+
stateRef: state,
164+
containerRef: container,
165+
})
166+
})
167+
```
168+
169+
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
170+
171+
172+
25173
## Credits
26174

27175
This Nuxt module wouldn't be possible without:
@@ -41,6 +189,10 @@ That's it! You can now use Nuxt-codemirror in your Nuxt app ✨
41189

42190
## Contribution
43191

192+
If you have ideas or bugs feel free to start by opening an issue. For ideas please start a Discussion.
193+
194+
I welcome any kind of contribution Thank you in advance!!
195+
44196
<details>
45197
<summary>Local development</summary>
46198

@@ -88,6 +240,8 @@ That's it! You can now use Nuxt-codemirror in your Nuxt app ✨
88240

89241
## FAQ
90242

91-
- 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.
243+
Issue
244+
- 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"`.
92245

93-
For now write shamefully-hoist=true in your .npmrc file to solve this. We are working on a better solution
246+
Solution
247+
- Assuming you use pnpm with `shamefully-hoist=false` install `@codemirror/state` and `@codemirror/view` and these errors should disappear

0 commit comments

Comments
 (0)