# Code Editor Component

A CodeMirror 6 based editor component that supports function autocomplete and suggestion pills, built with Material Design styling.

## Features

- **CodeMirror 6 Integration**: Uses the latest CodeMirror 6 for a modern editing experience
- **Function Autocomplete**: Dynamic function schema loading with intelligent autocomplete
- **Suggestion Pills**: Inline suggestion pills that are visually distinct from plain text
- **Material Design Styling**: Follows Material Design v3 guidelines
- **Keyboard Navigation**: Full keyboard support for autocomplete and editor interactions
- **Accessibility**: Built with accessibility in mind, including proper ARIA attributes
- **Dark Theme Support**: Optional dark theme variant
- **Syntax Highlighting**: JavaScript syntax highlighting with extensible language support

## Basic Usage

```typescript
import { CodeEditorElement } from '@api-client/ui'

// Or import the component directly
import '@api-client/ui/elements/code-editor/code-editor.js'
```

```html
<code-editor
  label="Code Editor"
  supporting-text="Enter your code here"
  .value=${this.code}
  .functionSchemas=${this.functions}
  .suggestions=${this.suggestions}
  @function-insert=${this.handleFunctionInsert}
  @suggestion-insert=${this.handleSuggestionInsert}
  @input=${this.handleInput}
></code-editor>
```

## Function Schemas

Function schemas define the available functions for autocomplete:

```typescript
const functionSchemas: FunctionSchema[] = [
  {
    id: 'getData',
    name: 'getData',
    description: 'Fetches data from the server',
    parameters: [
      {
        name: 'url',
        type: 'string',
        description: 'The URL to fetch data from',
        required: true,
      },
      {
        name: 'options',
        type: 'RequestInit',
        description: 'Fetch options',
        required: false,
      },
    ],
    returns: 'Promise<Response>',
  },
]
```

## Suggestions

Suggestions are used for @mention-style autocomplete with pill rendering:

```typescript
const suggestions: Suggestion[] = [
  {
    id: 'user-john',
    label: 'John Doe',
    description: 'Software Engineer',
    suffix: 'Engineering',
    data: { role: 'developer', department: 'engineering' },
  },
]
```

## Events

The component dispatches several events:

- `function-insert`: When a function is inserted via autocomplete
- `suggestion-insert`: When a suggestion is inserted as a pill
- `input`: When the editor content changes (standard input event)
- `change`: When the editor loses focus and content has changed

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `label` | `string` | `''` | Label text displayed as placeholder/floating label |
| `supporting-text` | `string` | `''` | Supporting text displayed below the editor |
| `disabled` | `boolean` | `false` | Whether the component is disabled |
| `invalid` | `boolean` | `false` | Whether the component is in an invalid state |
| `name` | `string` | `''` | Name attribute for form integration |
| `required` | `boolean` | `false` | Whether the input is required |
| `placeholder` | `string` | `''` | Placeholder text shown when editor is empty |
| `value` | `string` | `''` | The editor content value |
| `functionSchemas` | `FunctionSchema[]` | `[]` | Available function schemas for autocomplete |
| `suggestions` | `Suggestion[]` | `[]` | Available suggestions for autocomplete |
| `dark-theme` | `boolean` | `false` | Whether to use dark theme |
| `language` | `string` | `'javascript'` | Programming language for syntax highlighting |

## Methods

| Method | Description |
|--------|-------------|
| `focus()` | Focus the editor |
| `getSelection()` | Get the current selection range |
| `insertText(text: string)` | Insert text at the current cursor position |

## Styling

The component uses CSS custom properties for theming and follows Material Design tokens:

```css
code-editor {
  --md-sys-color-primary: #1976d2;
  --md-sys-color-on-surface: #1c1b1f;
  /* ... other Material Design tokens */
}
```

## Accessibility

The component includes:
- Proper ARIA attributes for screen readers
- Keyboard navigation support
- Focus management
- Semantic HTML structure
- High contrast support

## Examples

### Basic Editor

```html
<code-editor
  label="JavaScript Code"
  .value=${'console.log("Hello, world!")'}
>
</code-editor>
```

### With Function Autocomplete

```html
<code-editor
  label="Code with Functions"
  .value=${this.code}
  .functionSchemas=${this.functions}
  @function-insert=${this.onFunctionInsert}
>
</code-editor>
```

### With Suggestions (Pills)

```html
<code-editor
  label="Code with Mentions"
  .value=${this.code}
  .suggestions=${this.users}
  @suggestion-insert=${this.onSuggestionInsert}
>
</code-editor>
```

### Dark Theme

```html
<code-editor
  label="Dark Code Editor"
  .value=${this.code}
  dark-theme
>
</code-editor>
```

## Demo

A comprehensive demo is available at `/demo/elements/code-editor/` when running the development server.

## Browser Support

The component works in all modern browsers that support:
- ES2020+ features
- Web Components
- CSS Custom Properties
- CodeMirror 6

## Contributing

When contributing to this component, please follow the established patterns:
- Use TypeScript for type safety
- Follow the existing code style
- Include tests for new features
- Update documentation as needed
- Follow Material Design guidelines for styling
