Merge pull request #12 from tidbcloud/doc

doc: add READMEs

LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 PingCAP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,15 +1,129 @@
-# tisqleditor
+# TiSQLEditor
+
+TiSQLEditor is a CodeMirror6 based SQL code editor which is used in TiDB Cloud Console.
+
+[Try Playground](https://tisqleditor-playground.netlify.app/)
+
+![image](./packages/playground/public/playground.png)
+
+## Features
+
+- Support edit multiple SQL files
+- Supply React component (Vue component wip)
+- Out of box extensions
+- AI Widget (wip)
+
+## Packages
+
+- @tidbcloud/tisqleditor
+- @tidbcloud/tisqleditor-react - React component wrapper
+- @tidbcloud/tisqleditor-extension-sql-parser
+- @tidbcloud/tisqleditor-extension-cur-sql
+- @tidbcloud/tisqleditor-extension-cur-sql-gutter
+- @tidbcloud/tisqleditor-extension-save-helper
+- @tidbcloud/tisqleditor-extension-autocomplete
+- @tidbcloud/tisqleditor-extension-linters
+- @tidbcloud/tisqleditor-extension-events
+- @tidbcloud/tisqleditor-extension-themes - 2 simple builtin theme, `bbedit` for light mode, `oneDark` for dark mode
+- @tidbcloud/tisqleditor-extension-basic-setup
 
 ## Usage
 
-// TODO
+See [editor.tsx](./packages/playground/src/components/biz/editor-panel/editor.tsx) to get more details.
+
+```tsx
+import { SQLEditor } from '@tidbcloud/tisqleditor-react'
+import { saveHelper } from '@tidbcloud/tisqleditor-extension-save-helper'
+import { bbedit, oneDark } from '@tidbcloud/tisqleditor-extension-themes'
+import { curSqlGutter } from '@tidbcloud/tisqleditor-extension-cur-sql-gutter'
+import {
+  useDbLinter,
+  fullWidthCharLinter
+} from '@tidbcloud/tisqleditor-extension-linters'
+import { autoCompletion } from '@tidbcloud/tisqleditor-extension-autocomplete'
+
+export function Editor() {
+  const {
+    api: { saveFile },
+    state: { activeFileId, openedFiles }
+  } = useFilesContext()
 
-## Contributing
+  const { isDark } = useTheme()
+
+  const { schema } = useSchemaContext()
+  const sqlConfig = useMemo(
+    () => convertSchemaToSQLConfig(schema ?? []),
+    [schema]
+  )
+
+  const activeFile = useMemo(
+    () => openedFiles.find((f) => f.id === activeFileId),
+    [activeFileId, openedFiles]
+  )
+
+  const extraExts = useMemo(() => {
+    if (activeFile && activeFile.status === 'loaded') {
+      return [
+        saveHelper({
+          save: (view: EditorView) => {
+            saveFile(activeFile.id, view.state.doc.toString())
+          }
+        }),
+        autoCompletion(),
+        curSqlGutter(),
+        useDbLinter(),
+        fullWidthCharLinter()
+      ]
+    }
+    return []
+  }, [activeFile])
+
+  if (!activeFile) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <h1 className="scroll-m-20 text-4xl font-extrabold tracking-tight lg:text-5xl">
+          TiSQLEditor
+        </h1>
+      </div>
+    )
+  }
+
+  if (activeFile.status === 'loading') {
+    return (
+      <SQLEditor
+        className="h-full"
+        editorId="loading"
+        doc=""
+        theme={isDark ? oneDark : bbedit}
+        extraExts={[
+          placeholder('loading...'),
+          // both needed to prevent user from typing
+          EditorView.editable.of(false),
+          EditorState.readOnly.of(true)
+        ]}
+      />
+    )
+  }
+
+  return (
+    <SQLEditor
+      className="h-full"
+      editorId={activeFile.id}
+      doc={activeFile.content}
+      sqlConfig={sqlConfig}
+      theme={isDark ? oneDark : bbedit}
+      extraExts={extraExts}
+    />
+  )
+}
+```
+
+## Development
 
 ### Setup
 
 - node.js >18.16.0
-- [use corepack](https://www.totaltypescript.com/how-to-use-corepack): `corepack enable && corepack enable npm`
+- [enable corepack](https://www.totaltypescript.com/how-to-use-corepack): `corepack enable && corepack enable npm`
 
 ### Local Development
 
@@ -24,7 +138,7 @@
 
 ### PR Commit Convention
 
-Before you create a Pull Request, please check whether your commits comply with the commit conventions used in this repository. When you create a commit, you should follow the convention category(scope or module): message in your commit message while using one of the following categories:
+Before you create a pull request, please check whether your commits comply with the commit conventions used in this repository. When you create a commit, you should follow the convention `category(scope or module): message` in your commit message while using one of the following categories:
 
 - feat/feature: all changes that introduce completely new code or new features
 - fix: changes that fix a bug (ideally you will additionally reference an issue if present)
@@ -38,3 +152,7 @@ Before you create a Pull Request, please check whether your commits comply with
 - Commit the generated changeset file (a markdown file in `.changeset` folder), create a pull request to main branch.
 - After your pull request is merged, a new pull request will be created by a bot, you can review your release there.
 - After that pull request is merged, a new release will be published automatically to github registry.
+
+## License
+
+[MIT License](./LICENSE)

packages/core/README.md

@@ -1 +1,88 @@
 # @tidbcloud/tisqleditor
+
+This package provides the `SQLEditorInstance` and `EditorCache` implementation.
+
+`SQLEditorInstance` creates EditorView instance with pre-configured extensions to make it available to edit SQL code.
+
+`EditorCache` stores the `SQLEditorInstance` in a map.
+
+## Installation
+
+```shell
+npm install @tidbcloud/tisqleditor
+```
+
+You need to install its peer dependencies as well.
+
+```shell
+npm install @codemirror/view @codemirror/state @codemirror/lang-sql @codemirror/language @codemirror/search
+```
+
+## Usage
+
+```js
+import { EditorCache, createSQLEditorInstance } from '@tidbcloud/tisqleditor'
+
+const cache = new EditorCache()
+const editorId = '1'
+const editorInst = createSQLEditorInstance({
+  editorId,
+  doc: 'select * from test;'
+})
+
+cache.addEditor(editorId, editorInst)
+```
+
+## API
+
+### createSQLEditorInstance
+
+```js
+type CreateSQLEditorOptions = {
+    editorId: string;
+    doc: string;
+
+    basicSetupOptions?: BasicSetupOptions;
+    sqlConfig?: SQLConfig;
+    theme?: Extension;
+    extraExts?: Extension;
+    extraData?: {};
+};
+
+const createSQLEditorInstance: (options: CreateSQLEditorOptions) => SQLEditorInstance;
+```
+
+### SQLEditorInstance
+
+```js
+class SQLEditorInstance {
+    editorId: string;
+    editorView: EditorView;
+    themeCompartment: Compartment;
+    sqlCompartment: Compartment;
+    extraData: {};
+
+    constructor(editorId: string, editorView: EditorView, themeCompartment: Compartment, sqlCompartment: Compartment, extraData: {});
+
+    changeTheme(theme: Extension): void;
+    changeSQLConfig(sqlConfig: SQLConfig): void;
+
+    /* get all statements */
+    getAllStatements(): SqlStatement[];
+    /* get selected statements */
+    getCurStatements(): SqlStatement[];
+    /* get the nearest statement before the cursor */
+    getNearbyStatement(): SqlStatement | undefined;
+}
+```
+
+### EditorCache
+
+```js
+class EditorCache {
+    addEditor: (editorId: string, editor: SQLEditorInstance) => void;
+    getEditor: (editorId: string) => SQLEditorInstance | undefined;
+    deleteEditor: (editorId: string) => void;
+    clearEditors: () => void;
+}
+```

packages/core/src/editor-cache.tsx

@@ -3,7 +3,7 @@ import { SQLEditorInstance } from './editor-instance'
 //-------------
 
 export class EditorCache {
-  cache: Map<string, SQLEditorInstance> = new Map()
+  private cache: Map<string, SQLEditorInstance> = new Map()
 
   addEditor = (editorId: string, editor: SQLEditorInstance) => {
     this.cache.set(editorId, editor)

packages/extensions/autocomplete/README.md

@@ -0,0 +1,34 @@
+# @tidbcloud/tisqleditor-extension-autocomplete
+
+// TODO: desc
+
+## Installation
+
+```shell
+npm install @tidbcloud/tisqleditor-extension-autocomplete
+```
+
+You need to install its peer dependencies as well:
+
+```shell
+npm install @codemirror/view @codemirror/state @codemirror/autocomplete @codemirror/commands
+```
+
+## Usage
+
+```js
+import { EditorView } from '@codemirror/view'
+import { EditorState } from '@codemirror/state'
+import { autoCompletion } from '@tidbcloud/tisqleditor-extension-autocomplete'
+
+const editorView = new EditorView({
+  state: EditorState.create({
+    doc,
+    extensions: [autoCompletion()]
+  })
+})
+```
+
+## API
+
+// TODO

packages/extensions/cur-sql-gutter/README.md

@@ -0,0 +1,50 @@
+# @tidbcloud/tisqleditor-extension-cur-sql-gutter
+
+This extension listens the editor selection change, and shows gutter for the selected statements to make it highlight.
+
+## Installation
+
+```shell
+npm install @tidbcloud/tisqleditor-extension-cur-sql-gutter
+```
+
+You need to install its peer dependencies as well:
+
+```shell
+npm install @codemirror/view @codemirror/state
+```
+
+## Usage
+
+```js
+import { EditorView } from '@codemirror/view'
+import { EditorState } from '@codemirror/state'
+import { curSqlGutter } from '@tidbcloud/tisqleditor-extension-cur-sql-gutter'
+
+const editorView = new EditorView({
+  state: EditorState.create({
+    doc,
+    extensions: [curSqlGutter()]
+  })
+})
+```
+
+## API
+
+```js
+interface CurSqlGutterConfig {
+    // gutter background
+    backgroundColor?: string;
+
+    // gutter width
+    width?: number;
+
+    // gutter extra css class
+    className?: string;
+
+    // control gutter to hide when some cases happen
+    whenHide?: (view: EditorView) => boolean;
+}
+
+const curSqlGutter: (config?: CurSqlGutterConfig) => Extension;
+```

packages/extensions/cur-sql/README.md

@@ -0,0 +1,41 @@
+# @tidbcloud/tisqleditor-extension-cur-sql
+
+This extension listens the editor selection change, return the selected statements.
+
+This extension is installed internally inside the `SQLEditorInstance`.
+
+## Installation
+
+```shell
+npm install @tidbcloud/tisqleditor-extension-cur-sql
+```
+
+You need to install its peer dependencies as well:
+
+```shell
+npm install @codemirror/view @codemirror/state
+```
+
+## Usage
+
+```js
+import { EditorView } from '@codemirror/view'
+import { EditorState } from '@codemirror/state'
+import { curSql } from '@tidbcloud/tisqleditor-extension-cur-sql'
+
+const editorView = new EditorView({
+  state: EditorState.create({
+    doc,
+    extensions: [curSql()]
+  })
+})
+```
+
+## API
+
+```js
+function curSql(): Extension;
+
+/* get selected statements */
+function getCurStatements(state: EditorState): SqlStatement[];
+```