@kern-ux-annex/kern-angular-kit/INTELLISENSE.md

Angular-Umsetzung der KERN UX-Standard Komponenten

# IntelliSense Support for KERN Angular Kit

This package provides comprehensive IntelliSense support for all KERN Angular Kit components to enhance your development experience with autocomplete, type checking, and inline documentation.

## Features

### 🎯 TypeScript Component Interfaces

All components have strongly typed interfaces that provide autocomplete and compile-time type checking:

```typescript
import {
  KernAccordionInputs,
  KernAlertInputs,
  KernDialogInputs,
  ComponentInputs
} from '@kern-ux-annex/kern-angular-kit';

// Full type safety when configuring components
const accordionConfig: KernAccordionInputs = {
  title: 'My Accordion',
  open: true // TypeScript validates this boolean
};

// Generic component configuration helper
const alertConfig: ComponentInputs<'kern-alert'> = {
  title: 'Warning!',
  type: 'warning' // IntelliSense shows available types
};
```

### 📋 JSON Schema Validation

Use the included JSON schema for configuration files and get validation in your IDE:

```json
{
  "$schema": "node_modules/@kern-ux-annex/kern-angular-kit/schemas/kern-components.schema.json",
  "components": {
    "kern-accordion": {
      "title": "Example Accordion",
      "open": false
    },
    "kern-dialog": {
      "title": "Confirmation Dialog",
      "btnPrimaryLabelText": "Confirm",
      "btnSecondaryLabelText": "Cancel"
    }
  }
}
```

### 🔧 Angular Template IntelliSense

Components provide full IntelliSense in Angular templates with property validation and documentation:

```html
<!-- IntelliSense shows available inputs with descriptions -->
<kern-accordion [title]="accordionTitle" [open]="isExpanded">
  <p>Accordion content goes here</p>
</kern-accordion>

<!-- Type checking and validation for form inputs -->
<kern-input-text
  labelText="Username"
  [required]="true"
  inputmode="text"
  [maxlength]="50"
>
</kern-input-text>

<!-- Dialog with event handlers -->
<kern-dialog
  [title]="dialogTitle"
  btnPrimaryLabelText="Save"
  btnSecondaryLabelText="Cancel"
  (btnPrimaryClickEvent)="onSave($event)"
  (btnSecondaryClickEvent)="onCancel($event)"
>
  <p>Dialog content</p>
</kern-dialog>
```

### 🌐 Custom Element Support

For use with custom elements, web components, or JSX/TSX:

```typescript
// Import for JSX/TSX IntelliSense
import '@kern-ux-annex/kern-angular-kit';

// Now you have full IntelliSense in JSX
const MyComponent = () => (
  <kern-accordion title="My Accordion" open={false}>
    <p>Content</p>
  </kern-accordion>
);
```

### 🛡️ Type Guards and Utilities

Helper functions for working with KERN components programmatically:

```typescript
import {
  isKernAccordion,
  isKernDialog,
  KernDialogElement
} from '@kern-ux-annex/kern-angular-kit';

// Type-safe DOM manipulation
const element = document.querySelector('kern-dialog');
if (isKernDialog(element)) {
  element.showModal(); // TypeScript knows this method exists
  element.title = 'New Title'; // Property is typed
}
```

## Setup Instructions

### 📝 VS Code Setup

1. **Install Angular Language Service extension** for the best experience
2. **Configure TypeScript** to include library types in your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "types": ["@kern-ux-annex/kern-angular-kit"],
    "lib": ["DOM", "ES2022"]
  }
}
```

### 🔍 JSON Schema Validation

To enable JSON schema validation in VS Code, add to your workspace `settings.json`:

```json
{
  "json.schemas": [
    {
      "fileMatch": [
        "**/kern-components.config.json",
        "**/components.config.json"
      ],
      "url": "./node_modules/@kern-ux-annex/kern-angular-kit/schemas/kern-components.schema.json"
    }
  ]
}
```

### 🎨 Enhanced Angular Templates

For better template IntelliSense, ensure your Angular project includes:

```typescript
// In your app.module.ts or component
import { KernElementsModule } from '@kern-ux-annex/kern-angular-kit';

@NgModule({
  imports: [
    // ... other imports
    KernElementsModule // Enables custom element recognition
  ]
})
export class AppModule {}
```

## Component Reference

### 📦 Layout Components

#### kern-accordion

```typescript
interface KernAccordionInputs {
  title: string; // Required: Header text
  open?: boolean; // Optional: Initially expanded (default: false)
}
```

#### kern-alert

```typescript
interface KernAlertInputs {
  title: string; // Required: Alert message
  type?: 'info' | 'success' | 'warning' | 'danger'; // Optional: Style type
}
```

#### kern-dialog

```typescript
interface KernDialogInputs {
  title: string; // Required: Dialog title
  dialogId?: string; // Optional: Custom element ID
  btnCloseLabelText?: string; // Optional: Close button text
  btnPrimaryLabelText?: string | null; // Optional: Primary button text
  btnSecondaryLabelText?: string | null; // Optional: Secondary button text
}

// Events emitted by kern-dialog
interface KernDialogOutputs {
  cancelEvent: Event; // Fired when dialog is cancelled
  btnPrimaryClickEvent: Event; // Fired when primary button clicked
  btnSecondaryClickEvent: Event; // Fired when secondary button clicked
}
```

#### kern-loader

```typescript
interface KernLoaderInputs {
  text?: string; // Optional: Loading message (default: "Laden...")
}
```

### 📝 Form Components

All form components extend the base input interface:

```typescript
interface KernInputBaseInputs {
  labelText: string; // Required: Input label
  inputId?: string; // Optional: Custom element ID
  optional?: boolean; // Optional: Show "(optional)" in label
  readonly?: boolean; // Optional: Make input read-only
  required?: boolean; // Optional: Mark as required
}
```

#### Specialized Form Components

- **kern-input-text**: Adds `inputmode` and `maxlength` properties
- **kern-input-date**: Adds `min` and `max` date constraints
- **kern-input-file**: Adds `accept` and `multiple` properties
- **kern-input-radio**: Adds required `value` and `name` properties
- **kern-input-select**: Adds `multiple` property
- **kern-input-textarea**: Adds `rows`, `cols`, and `maxlength` properties

## Usage Examples

### 🚀 Basic Component Usage

```typescript
import { Component } from '@angular/core';
import { KernAccordionInputs } from '@kern-ux-annex/kern-angular-kit';

@Component({
  template: `
    <kern-accordion [title]="config.title" [open]="config.open">
      <p>Dynamic content based on configuration</p>
    </kern-accordion>
  `
})
export class MyComponent {
  config: KernAccordionInputs = {
    title: 'Configuration Panel',
    open: false
  };
}
```

### 🎛️ Dynamic Form Generation

```typescript
import {
  ComponentInputs,
  KernComponentSelector
} from '@kern-ux-annex/kern-angular-kit';

interface FormField {
  component: KernComponentSelector;
  config: ComponentInputs<KernComponentSelector>;
}

const formFields: FormField[] = [
  {
    component: 'kern-input-text',
    config: { labelText: 'Name', required: true }
  },
  {
    component: 'kern-input-email',
    config: { labelText: 'Email', required: true }
  }
];
```

## Benefits

✅ **Autocomplete**: Get intelligent suggestions for all component properties  
✅ **Type Safety**: Catch configuration errors at compile time  
✅ **Documentation**: Hover tooltips show property descriptions and examples  
✅ **Validation**: Real-time validation of property types and values  
✅ **Refactoring**: Safe renaming and refactoring across your entire codebase  
✅ **Schema Validation**: JSON configuration files are validated against schemas  
✅ **Custom Elements**: Full support for web component and JSX usage patterns

## Troubleshooting

### IntelliSense Not Working?

1. Ensure Angular Language Service extension is installed and enabled
2. Check that `@kern-ux-annex/kern-angular-kit` is in your `package.json` dependencies
3. Restart the TypeScript service in VS Code (`Cmd/Ctrl + Shift + P` → "TypeScript: Restart TS Server")
4. Verify your `tsconfig.json` includes the library types

### Schema Validation Issues?

1. Check that the schema path in your `settings.json` is correct
2. Ensure your JSON files match the configured file patterns
3. Validate your JSON syntax is correct

### Template IntelliSense Missing?

1. Import `KernElementsModule` in your Angular module
2. Ensure you're using the latest version of Angular Language Service
3. Check that your component templates have the correct file extensions (`.html`)

For more help, please refer to the [project documentation](https://gitlab.opencode.de/kern-ux/community/angular-kit) or open an issue.