@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/CodeEditor/ai-documentation.md

@@ -1,350 +0,0 @@
-# CodeEditor - AI Documentation
-
-> Auto-generated AI agent documentation for CodeEditor component
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-
-**Component:** CodeEditor
-**Import Path:** `import { CodeEditor } from '@pushwoosh/dumb-components'`
-**Files:** CodeEditor.tsx, types.ts, styles.ts, constants.ts, index.ts, languages/
-**Type:** Form Component / Text Editor
-**Description:** Code editor component built on CodeMirror with syntax highlighting, theme support, and language extensions
-
-## TypeScript Interface
-
-```typescript
-interface CodeEditorProps {
-  value: string;
-  readOnly?: boolean;
-  width?: string;
-  height?: string;
-  hasError?: boolean;
-  extensions: Extension[];
-  placeholder?: string;
-  themeOptions?: CreateThemeOptions;
-  onChange?: (value: string, viewUpdate: ViewUpdate) => void;
-  onBlur?: () => void;
-}
-```
-
-## Import & Usage
-
-**Import:**
-```typescript
-import { CodeEditor, html, liquid, json } from '@pushwoosh/dumb-components';
-import type { CodeEditorProps } from '@pushwoosh/dumb-components';
-```
-
-**Basic Usage:**
-```tsx
-import { json } from '@pushwoosh/dumb-components';
-
-function App() {
-  const [code, setCode] = useState('{\n  "hello": "world"\n}');
-
-  return (
-    <CodeEditor 
-      value={code}
-      onChange={(val) => setCode(val)}
-      extensions={[json()]}
-    />
-  );
-}
-```
-
-**Advanced Examples:**
-```tsx
-// HTML editor with custom size
-<CodeEditor 
-  value={htmlCode}
-  onChange={setHtmlCode}
-  extensions={[html()]}
-  width="100%"
-  height="400px"
-  placeholder="Enter HTML code..."
-/>
-
-// Read-only editor for code display
-<CodeEditor 
-  value={exampleCode}
-  readOnly={true}
-  extensions={[json()]}
-  height="200px"
-/>
-
-// Editor with error state
-<CodeEditor 
-  value={invalidJson}
-  onChange={handleJsonChange}
-  extensions={[json()]}
-  hasError={jsonParseError}
-  onBlur={() => validateJson(invalidJson)}
-/>
-
-// Liquid template editor
-<CodeEditor 
-  value={liquidTemplate}
-  onChange={setLiquidTemplate}
-  extensions={[liquid()]}
-  placeholder="Enter Liquid template..."
-  height="300px"
-/>
-
-// Custom theme editor
-<CodeEditor 
-  value={code}
-  onChange={setCode}
-  extensions={[html()]}
-  themeOptions={{
-    theme: 'dark',
-    settings: {
-      background: '#1e1e1e',
-      foreground: '#d4d4d4',
-      caret: '#ffffff',
-      selection: '#264f78',
-      lineHighlight: '#2d2d30'
-    }
-  }}
-/>
-
-// Form integration with validation
-function CodeForm() {
-  const [jsonValue, setJsonValue] = useState('');
-  const [error, setError] = useState(null);
-
-  const handleChange = (value: string) => {
-    setJsonValue(value);
-    try {
-      JSON.parse(value);
-      setError(null);
-    } catch (e) {
-      setError('Invalid JSON syntax');
-    }
-  };
-
-  return (
-    <div>
-      <label>JSON Configuration:</label>
-      <CodeEditor 
-        value={jsonValue}
-        onChange={handleChange}
-        extensions={[json()]}
-        hasError={!!error}
-        placeholder='{\n  "key": "value"\n}'
-        height="200px"
-      />
-      {error && <span style={{ color: 'red' }}>{error}</span>}
-    </div>
-  );
-}
-
-// Multi-language editor with switcher
-function MultiLanguageEditor() {
-  const [language, setLanguage] = useState('json');
-  const [code, setCode] = useState('');
-
-  const getExtensions = () => {
-    switch (language) {
-      case 'html': return [html()];
-      case 'json': return [json()];
-      case 'liquid': return [liquid()];
-      default: return [];
-    }
-  };
-
-  return (
-    <div>
-      <select value={language} onChange={(e) => setLanguage(e.target.value)}>
-        <option value="json">JSON</option>
-        <option value="html">HTML</option>
-        <option value="liquid">Liquid</option>
-      </select>
-      
-      <CodeEditor 
-        value={code}
-        onChange={setCode}
-        extensions={getExtensions()}
-        height="300px"
-      />
-    </div>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| value | string | required | Current editor content |
-| onChange | (value: string, viewUpdate: ViewUpdate) => void | undefined | Content change callback |
-| extensions | Extension[] | required | CodeMirror language/feature extensions |
-| readOnly | boolean | false | Whether editor is read-only |
-| width | string | undefined | Editor width (CSS value) |
-| height | string | undefined | Editor height (CSS value) |
-| hasError | boolean | false | Whether editor shows error styling |
-| placeholder | string | undefined | Placeholder text when empty |
-| themeOptions | CreateThemeOptions | undefined | Custom theme configuration |
-| onBlur | () => void | undefined | Blur event callback |
-
-## Language Extensions
-
-The library provides pre-configured language extensions:
-
-| Extension | Usage | Description |
-|-----------|-------|-------------|
-| `html()` | HTML editing | HTML syntax highlighting and completion |
-| `json()` | JSON editing | JSON syntax highlighting and validation |
-| `liquid()` | Liquid templates | Liquid template language support |
-
-**Usage:**
-```typescript
-import { html, json, liquid } from '@pushwoosh/dumb-components';
-
-// Use in extensions prop
-<CodeEditor extensions={[json()]} />
-<CodeEditor extensions={[html()]} />
-<CodeEditor extensions={[liquid()]} />
-```
-
-## Theme Customization
-
-```typescript
-// Custom theme example
-const customTheme = {
-  theme: 'dark', // or 'light'
-  settings: {
-    background: '#1a1a1a',
-    foreground: '#ffffff',
-    caret: '#ffcc00',
-    selection: '#3d4c5f',
-    selectionMatch: '#3d4c5f',
-    lineHighlight: '#2a2a2a',
-    gutterBackground: '#1a1a1a',
-    gutterForeground: '#999999'
-  },
-  styles: [
-    { tag: 'comment', color: '#6a9955' },
-    { tag: 'string', color: '#ce9178' },
-    { tag: 'number', color: '#b5cea8' }
-  ]
-};
-
-<CodeEditor 
-  themeOptions={customTheme}
-  extensions={[json()]}
-  value={code}
-  onChange={setCode}
-/>
-```
-
-## AI Agent Guidelines
-
-### ✅ Recommended Patterns
-- Always provide appropriate `extensions` for the content type
-- Use `hasError` to indicate validation problems
-- Set reasonable `height` for better UX (200px-500px typically)
-- Include `placeholder` text for empty editors
-- Handle `onChange` to maintain controlled component state
-- Use `readOnly` for code display/preview scenarios
-
-### ❌ Common Mistakes to Avoid
-- Don't forget to import and use language extensions
-- Don't use without `onChange` unless read-only
-- Avoid very small heights that make editing difficult
-- Don't mix different language extensions inappropriately
-- Avoid setting both `readOnly` and `onChange` (unnecessary)
-
-### Integration Tips
-- Works well in forms for configuration editing
-- Good for template editing interfaces
-- Can be combined with preview components
-- Use with validation libraries for syntax checking
-- Effective in admin interfaces for code customization
-
-## Common Use Cases
-
-### JSON Configuration Editor
-```tsx
-function JsonConfigEditor({ config, onConfigChange }) {
-  const [jsonString, setJsonString] = useState(
-    JSON.stringify(config, null, 2)
-  );
-  const [error, setError] = useState(null);
-
-  const handleChange = (value: string) => {
-    setJsonString(value);
-    try {
-      const parsed = JSON.parse(value);
-      onConfigChange(parsed);
-      setError(null);
-    } catch (e) {
-      setError('Invalid JSON');
-    }
-  };
-
-  return (
-    <div>
-      <CodeEditor 
-        value={jsonString}
-        onChange={handleChange}
-        extensions={[json()]}
-        hasError={!!error}
-        height="300px"
-      />
-      {error && <div className="error">{error}</div>}
-    </div>
-  );
-}
-```
-
-### Template Editor
-```tsx
-function TemplateEditor() {
-  const [template, setTemplate] = useState('');
-  const [preview, setPreview] = useState('');
-
-  useEffect(() => {
-    // Generate preview from template
-    setPreview(processLiquidTemplate(template));
-  }, [template]);
-
-  return (
-    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px' }}>
-      <div>
-        <h3>Template</h3>
-        <CodeEditor 
-          value={template}
-          onChange={setTemplate}
-          extensions={[liquid()]}
-          height="400px"
-          placeholder="Enter Liquid template..."
-        />
-      </div>
-      <div>
-        <h3>Preview</h3>
-        <CodeEditor 
-          value={preview}
-          readOnly
-          extensions={[html()]}
-          height="400px"
-        />
-      </div>
-    </div>
-  );
-}
-```
-
-## Accessibility Features
-- **Keyboard Navigation**: Full keyboard support for code editing
-- **Screen Reader Support**: Accessible to screen readers
-- **Focus Management**: Proper focus handling and indication
-- **High Contrast**: Supports high contrast themes
-
-## Related Components
-- Textarea - for simple multi-line text input
-- Input - for single-line text input
-- Modal - often contains code editors
-- Button - for editor actions (save, format, etc.)
-
----