@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.

**Component Coverage**: This documentation covers 30+ components including layout components, form inputs, data display components, and typography elements.

## Features

### 🎯 TypeScript Component Interfaces

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

```typescript
import {
  KernAccordionInputs,
  KernAlertInputs,
  KernBadgeInputs,
  KernButtonInputs,
  KernCardInputs,
  KernDialogInputs,
  KernTableInputs,
  KernSummaryInputs,
  KernProgressInputs,
  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
};

// Card configuration with multiple properties
const cardConfig: KernCardInputs = {
  title: 'Feature Card',
  size: 'large',
  btnPrimaryLabelText: 'Learn More',
  btnSecondaryLabelText: 'Skip'
};

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

// Table configuration with typed data
const tableConfig: KernTableInputs = {
  caption: 'Data Overview',
  columns: [
    { key: 'name', header: 'Name' },
    { key: 'value', header: 'Value', numeric: true }
  ],
  data: [
    { name: 'Item 1', value: 100 },
    { name: 'Item 2', value: 200 }
  ],
  striped: true,
  responsive: true
};
```

### 📋 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>

<!-- Button with icon and event handling -->
<kern-button
  variant="primary"
  iconLeft="arrow-right"
  [disabled]="isLoading"
  (clickEvent)="onSubmit($event)"
>
  Submit Form
</kern-button>

<!-- Card component with multiple features -->
<kern-card
  [title]="cardTitle"
  [preline]="cardPreline"
  [subline]="cardSubline"
  size="large"
  [btnPrimaryLabelText]="primaryButtonText"
  [btnSecondaryLabelText]="secondaryButtonText"
  (btnPrimaryClickEvent)="onPrimaryAction($event)"
  (btnSecondaryClickEvent)="onSecondaryAction($event)"
>
  <p>Card content</p>
</kern-card>

<!-- Data table with configuration -->
<kern-table
  [columns]="tableColumns"
  [data]="tableData"
  [striped]="true"
  [responsive]="true"
  caption="User Data Overview"
>
</kern-table>

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

<!-- Number input with constraints -->
<kern-input-number
  labelText="Age"
  [required]="true"
  [min]="18"
  [max]="120"
  step="1"
>
</kern-input-number>

<!-- Summary component with action link -->
<kern-summary
  [title]="summaryTitle"
  [items]="summaryItems"
  [actionLinkHref]="detailsUrl"
  (actionLinkClickEvent)="onViewDetails($event)"
>
</kern-summary>

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

<!-- Progress indicator -->
<kern-progress
  [value]="currentProgress"
  [max]="totalSteps"
  label="Upload Progress"
>
</kern-progress>

<!-- Badge with icon -->
<kern-badge variant="success" icon="check-circle"> Completed </kern-badge>
```

### 🌐 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 = () => (
  <div>
    <kern-accordion title="My Accordion" open={false}>
      <p>Content</p>
    </kern-accordion>

    <kern-button
      variant="primary"
      iconLeft="arrow-right"
      onClick={handleClick}>
      Click me
    </kern-button>

    <kern-card
      title="Feature Card"
      preline="New"
      size="large"
      btnPrimaryLabelText="Learn More">
      <p>Card content</p>
    </kern-card>

    <kern-table
      columns={tableColumns}
      data={tableData}
      striped={true}
      responsive={true} />

    <kern-badge variant="success" icon="check">
      Completed
    </kern-badge>
  </div>
);
```

### 🛡️ Type Guards and Utilities

Helper functions for working with KERN components programmatically:

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

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

// Type-safe button interactions
const buttonElement = document.querySelector('kern-button');
if (isKernButton(buttonElement)) {
  buttonElement.disabled = true; // TypeScript validates property
  buttonElement.variant = 'secondary'; // IntelliSense shows available variants
}

// Type-safe card manipulation
const cardElement = document.querySelector('kern-card');
if (isKernCard(cardElement)) {
  cardElement.title = 'Updated Title';
  cardElement.size = 'large'; // TypeScript validates size options
}
```

## 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 & UI Components

#### kern-accordion

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

#### kern-accordion-group

```typescript
interface KernAccordionGroupInputs {
  // Container for multiple accordion items with consistent styling
}
```

#### kern-alert

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

#### kern-badge

```typescript
interface KernBadgeInputs {
  variant?: 'info' | 'success' | 'warning' | 'danger'; // Optional: Badge style (default: 'info')
  icon?: string | null; // Optional: Icon name to display
}
```

#### kern-button

```typescript
interface KernButtonInputs {
  variant?: 'primary' | 'secondary' | 'tertiary'; // Optional: Button style (default: 'primary')
  block?: boolean; // Optional: Full-width button (default: false)
  disabled?: boolean; // Optional: Disabled state (default: false)
  type?: 'button' | 'submit' | 'reset'; // Optional: Button type (default: 'button')
  iconLeft?: string | null; // Optional: Left icon name
  iconRight?: string | null; // Optional: Right icon name
  srOnlyLabel?: boolean; // Optional: Screen reader only label (default: false)
}

// Events emitted by kern-button
interface KernButtonOutputs {
  clickEvent: Event; // Fired when button is clicked
}
```

#### kern-card

```typescript
interface KernCardInputs {
  title?: string | null; // Optional: Card title
  titleLinkHref?: string | null; // Optional: Title link URL
  titleLinkTarget?: '_self' | '_blank' | '_parent' | '_top'; // Optional: Link target (default: '_self')
  preline?: string | null; // Optional: Text above title
  subline?: string | null; // Optional: Text below title
  imgSrc?: string | null; // Optional: Image source URL
  imgAlt?: string | null; // Optional: Image alt text
  size?: 'default' | 'small' | 'large'; // Optional: Card size (default: 'default')
  headingLevel?: '1' | '2' | '3' | '4' | '5'; // Optional: Heading level (default: '2')
  btnPrimaryLabelText?: string | null; // Optional: Primary button text
  btnSecondaryLabelText?: string | null; // Optional: Secondary button text
}

// Events emitted by kern-card
interface KernCardOutputs {
  titleLinkClickEvent: Event; // Fired when title link is clicked
  btnPrimaryClickEvent: Event; // Fired when primary button is clicked
  btnSecondaryClickEvent: Event; // Fired when secondary button is clicked
}
```

#### 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-divider

```typescript
interface KernDividerInputs {
  // Simple horizontal divider with consistent styling
}
```

#### kern-icon

```typescript
interface KernIconInputs {
  name: string; // Required: Icon name/identifier
  size?: string; // Optional: Icon size
}
```

#### kern-link

```typescript
interface KernLinkInputs {
  href: string; // Required: Link URL
  target?: '_self' | '_blank' | '_parent' | '_top'; // Optional: Link target (default: '_self')
  external?: boolean; // Optional: External link indicator (default: false)
}
```

#### kern-loader

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

#### kern-progress

```typescript
interface KernProgressInputs {
  value: number; // Required: Current progress value
  max?: number; // Optional: Maximum value (default: 100)
  label?: string; // Optional: Progress label
}
```

### � Data Display Components

#### kern-table

```typescript
interface KernTableInputs {
  responsive?: boolean; // Optional: Responsive table (default: true)
  small?: boolean; // Optional: Compact table (default: false)
  striped?: boolean; // Optional: Striped rows (default: false)
  caption?: string | null; // Optional: Table caption
  columns: KernTableColumn[]; // Required: Column definitions
  data: KernTableRow[]; // Required: Table data
  footer?: KernTableRow[] | null; // Optional: Footer rows
  rowHeaderKey?: string | null; // Optional: Key for row headers
}

interface KernTableColumn {
  key: string; // Column data key
  header: string; // Column header text
  numeric?: boolean; // Optional: Numeric column (default: false)
}

type KernTableRow = Record<string, unknown>; // Row data object
```

#### kern-summary

```typescript
interface KernSummaryInputs {
  titleId?: string; // Optional: Custom title ID
  title?: string | null; // Optional: Summary title
  titleNumber?: string | null; // Optional: Title number/prefix
  headingLevel?: '1' | '2' | '3' | '4' | '5' | '6'; // Optional: Heading level (default: '3')
  items: { term: string; description: string }[]; // Required: Summary items
  actionLinkHref?: string | null; // Optional: Action link URL
  actionLinkTarget?: '_self' | '_blank' | '_parent' | '_top'; // Optional: Link target (default: '_self')
}

// Events emitted by kern-summary
interface KernSummaryOutputs {
  actionLinkClickEvent: Event; // Fired when action link is clicked
}
```

#### kern-summary-group

```typescript
interface KernSummaryGroupInputs {
  // Container for multiple summary components with consistent styling
}
```

#### kern-description-list

```typescript
interface KernDescriptionListInputs {
  items: { term: string; description: string }[]; // Required: List items
  orientation?: 'horizontal' | 'vertical'; // Optional: List orientation
}
```

#### kern-tasklist

```typescript
interface KernTasklistInputs {
  tasks: KernTasklistItem[]; // Required: Task items
  editable?: boolean; // Optional: Allow editing tasks (default: false)
}

interface KernTasklistItem {
  id: string; // Unique task identifier
  text: string; // Task description
  completed?: boolean; // Task completion status
  href?: string; // Optional task link
}
```

### �📝 Form Components

### 📝 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
}
```

#### kern-fieldset

```typescript
interface KernFieldsetInputs {
  legend: string; // Required: Fieldset legend
  required?: boolean; // Optional: Mark as required
}
```

#### kern-input-error

```typescript
interface KernInputErrorInputs {
  errorText: string; // Required: Error message text
}
```

#### kern-input-hint

```typescript
interface KernInputHintInputs {
  hintText: string; // Required: Hint message text
}
```

#### Specialized Form Input Components

- **kern-input-text**: Adds `inputmode` ('decimal' | 'numeric' | null) and `maxlength` properties
- **kern-input-number**: Adds `min`, `max`, `step`, `autocomplete`, `placeholder` properties
- **kern-input-date**: Adds `min` and `max` date constraints
- **kern-input-email**: Standard email input with validation
- **kern-input-password**: Adds `maxlength` property for password constraints
- **kern-input-tel**: Telephone number input with appropriate input mode
- **kern-input-url**: URL input with validation
- **kern-input-file**: Adds `accept` and `multiple` properties for file selection
- **kern-input-radio**: Adds required `value` and `name` properties for radio groups
- **kern-input-select**: Adds `multiple` property for multi-selection
- **kern-input-checkbox**: Standard checkbox input
- **kern-input-textarea**: Adds `rows`, `cols`, and `maxlength` properties for text areas

### 🎨 Typography Components

#### kern-heading

```typescript
interface KernHeadingInputs {
  level?: '1' | '2' | '3' | '4' | '5' | '6'; // Optional: Heading level (default: '1')
  text: string; // Required: Heading text content
}
```

## Usage Examples

### 🚀 Basic Component Usage

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

@Component({
  template: `
    <!-- Accordion with configuration -->
    <kern-accordion
      [title]="accordionConfig.title"
      [open]="accordionConfig.open"
    >
      <p>Dynamic content based on configuration</p>
    </kern-accordion>

    <!-- Card with buttons and events -->
    <kern-card
      [title]="cardConfig.title"
      [preline]="cardConfig.preline"
      [subline]="cardConfig.subline"
      [btnPrimaryLabelText]="cardConfig.btnPrimaryLabelText"
      [btnSecondaryLabelText]="cardConfig.btnSecondaryLabelText"
      (btnPrimaryClickEvent)="onCardPrimaryAction($event)"
      (btnSecondaryClickEvent)="onCardSecondaryAction($event)"
    >
      <p>Card content goes here</p>
    </kern-card>

    <!-- Button with icon and events -->
    <kern-button
      [variant]="buttonConfig.variant"
      [iconLeft]="buttonConfig.iconLeft"
      [disabled]="buttonConfig.disabled"
      (clickEvent)="onButtonClick($event)"
    >
      Click me
    </kern-button>
  `
})
export class MyComponent {
  accordionConfig: KernAccordionInputs = {
    title: 'Configuration Panel',
    open: false
  };

  cardConfig: KernCardInputs = {
    title: 'Feature Card',
    preline: 'New Feature',
    subline: 'Available now',
    btnPrimaryLabelText: 'Learn More',
    btnSecondaryLabelText: 'Skip'
  };

  buttonConfig: KernButtonInputs = {
    variant: 'primary',
    iconLeft: 'arrow-right',
    disabled: false
  };

  onCardPrimaryAction(event: Event) {
    console.log('Primary action clicked', event);
  }

  onCardSecondaryAction(event: Event) {
    console.log('Secondary action clicked', event);
  }

  onButtonClick(event: Event) {
    console.log('Button clicked', event);
  }
}
```

### 📊 Data Display Examples

```typescript
import { Component } from '@angular/core';
import {
  KernTableInputs,
  KernTableColumn,
  KernTableRow,
  KernSummaryInputs
} from '@kern-ux-annex/kern-angular-kit';

@Component({
  template: `
    <!-- Data table with configuration -->
    <kern-table
      [columns]="tableConfig.columns"
      [data]="tableConfig.data"
      [striped]="tableConfig.striped"
      [responsive]="tableConfig.responsive"
      [caption]="tableConfig.caption"
    >
    </kern-table>

    <!-- Summary component -->
    <kern-summary
      [title]="summaryConfig.title"
      [items]="summaryConfig.items"
      [actionLinkHref]="summaryConfig.actionLinkHref"
      (actionLinkClickEvent)="onSummaryAction($event)"
    >
    </kern-summary>
  `
})
export class DataDisplayComponent {
  tableConfig: KernTableInputs = {
    caption: 'User Statistics',
    striped: true,
    responsive: true,
    columns: [
      { key: 'name', header: 'Name' },
      { key: 'age', header: 'Age', numeric: true },
      { key: 'email', header: 'Email' }
    ],
    data: [
      { name: 'John Doe', age: 30, email: 'john@example.com' },
      { name: 'Jane Smith', age: 25, email: 'jane@example.com' }
    ]
  };

  summaryConfig: KernSummaryInputs = {
    title: 'Project Summary',
    actionLinkHref: '/project/details',
    items: [
      { term: 'Status', description: 'In Progress' },
      { term: 'Due Date', description: '2024-12-31' },
      { term: 'Team Size', description: '5 members' }
    ]
  };

  onSummaryAction(event: Event) {
    console.log('Summary action clicked', event);
  }
}
```

### 🎛️ Dynamic Form Generation

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

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

const formFields: FormField[] = [
  {
    component: 'kern-input-text',
    config: { labelText: 'Full Name', required: true, maxlength: 100 }
  },
  {
    component: 'kern-input-email',
    config: { labelText: 'Email Address', required: true }
  },
  {
    component: 'kern-input-number',
    config: { labelText: 'Age', min: 18, max: 120, optional: false }
  },
  {
    component: 'kern-input-textarea',
    config: { labelText: 'Comments', rows: 4, maxlength: 500, optional: 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.