@kern-ux-annex/kern-angular-kit 1.0.1 → 1.2.0

package/INTELLISENSE.md

@@ -1,812 +0,0 @@
-# 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.