Editor Component

The FlyQL editor is a Vue 3 component that provides a schema-driven query input with autocomplete, syntax highlighting, and keyboard navigation.

Quick Setup

<script setup>
import { ref } from 'vue'
import { FlyqlEditor } from 'flyql/editor'

const query = ref('')
const columns = {
    status: { type: 'number', suggest: true },
    level: { type: 'enum', suggest: true, autocomplete: true, values: ['debug', 'info', 'error'] },
    service: { type: 'string', suggest: true, autocomplete: true },
    host: { type: 'string', suggest: true },
}

function onSubmit() {
    console.log('Query submitted:', query.value)
}

function onParseError(error) {
    console.log('Parse error:', error)
}
</script>

<template>
    <FlyqlEditor
        v-model="query"
        :columns="columns"
        placeholder="Type a FlyQL query..."
        @submit="onSubmit"
        @parse-error="onParseError"
    />
</template>

This renders a text input with autocomplete suggestions for columns, type-aware operators, and boolean operators — all driven by the columns schema.

Installation

npm install flyql

The editor requires Vue 3 as a peer dependency:

npm install vue

Import from the flyql/editor subpath:

import { FlyqlEditor, FlyqlColumns } from 'flyql/editor'

Both components import flyql.css internally, which provides theme variables, suggestion panel styles, and token highlighting. With standard bundlers (Vite, webpack, etc.) this works automatically.

If your setup doesn’t process CSS imports from JS, import the stylesheet manually:

import 'flyql/editor/flyql.css'

Props

Prop	Type	Default	Description
modelValue	String	''	Query text (v-model)
columns	Object	{}	Column schema
onAutocomplete	Function	null	Async value callback
onKeyDiscovery	Function	null	Remote key discovery callback
placeholder	String	''	Placeholder text
autofocus	Boolean	false	Auto-focus on mount
debug	Boolean	false	Debug logging
debounceMs	Number	300	Debounce delay (ms) for async autocomplete calls. Set to 0 to disable
dark	Boolean	false	Enable dark theme (see theming)

Callback signatures:

• onAutocomplete(key, value) — returns Promise<{ items: string[], incomplete?: boolean }>
• onKeyDiscovery(columnName, segments) — returns Promise<Array<{ name, type?, hasChildren? }>>

When incomplete is true in the response, the editor knows the returned list is partial and will re-fetch on the next keystroke. Async calls are debounced (default 150ms) and in-flight requests are automatically cancelled when a new one starts.

Events

Event	Payload	Description
update:modelValue	string	Query text changed (v-model)
submit	—	User pressed Shift+Enter
parse-error	string	Parse error message when query is invalid
focus	—	Editor gained focus
blur	—	Editor lost focus

Exposed Methods

Access via template ref:

<script setup>
import { ref } from 'vue'
import { FlyqlEditor } from 'flyql/editor'

const editorRef = ref(null)

function checkStatus() {
    const status = editorRef.value.getQueryStatus()
    console.log(status.valid, status.message)
}
</script>

<template>
    <FlyqlEditor ref="editorRef" v-model="query" :columns="columns" />
    <button @click="checkStatus">Check</button>
</template>

Method	Returns	Description
focus()	—	Focus the editor input
blur()	—	Blur the editor input
getQueryStatus()	{ valid: boolean, message: string }	Validate the current query

Async Value Autocomplete

Provide an onAutocomplete callback to fetch value suggestions from your API:

<script setup>
import { ref } from 'vue'
import { FlyqlEditor } from 'flyql/editor'

const query = ref('')
const columns = {
    service: { type: 'string', suggest: true, autocomplete: true },
    level: { type: 'enum', suggest: true, autocomplete: true, values: ['info', 'error'] },
}

async function onAutocomplete(key, value) {
    const resp = await fetch(`/api/autocomplete?key=${encodeURIComponent(key)}`)
    const data = await resp.json()
    return { items: data.values }
}
</script>

<template>
    <FlyqlEditor v-model="query" :columns="columns" :on-autocomplete="onAutocomplete" />
</template>

The callback receives the column key and current value prefix. Return { items: string[], incomplete?: boolean }. A loading indicator appears automatically after 200ms.

Stateful autocomplete flow

The editor uses a stateful autocomplete flow that minimizes server calls:

• Initial load — When entering value context (e.g., service=), the editor fetches immediately with no debounce. A full spinner is shown until results arrive.
• Complete list (incomplete: false) — The editor stores the returned items and switches to client-side filtering. Subsequent keystrokes filter instantly without server calls, until the user changes to a different column.
• Incomplete list (incomplete: true) — The editor keeps showing current suggestions while a debounced re-fetch runs in the background. An inline spinner appears in the header. When new results arrive, they replace the current suggestions.

If the server returns 0 items, the editor displays “No matching values”. For client-side filtering of a complete list, an empty result simply shows no suggestions (the user can backspace to see more).

Columns with autocomplete: true and static values use those values directly without calling the callback. Columns with autocomplete: true but no values trigger the callback.

Keyboard Shortcuts

Key	Action
Arrow Up/Down	Navigate suggestions
Enter / Tab	Accept selected suggestion
Escape	Dismiss suggestions
Shift+Enter	Submit query (emits submit event)