@publicplan/kern-react-kit 1.3.2 → 1.3.4

package/dist/skills/kern-react-kit/references/COMPONENTS.md

@@ -0,0 +1,686 @@
+# Component Catalog: Kern React Kit
+
+This is a quick reference to core components in @publicplan/kern-react-kit with import paths, prop types, and usage patterns.
+
+## Layout & Structure
+
+### Card
+A flexible container component for grouping related content.
+
+**Import:**
+```typescript
+import { Card } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+  // Compound sub-components:
+  // Card.Root | Card.Container | Card.Header | Card.Body | Card.Footer
+  // Card.Title | Card.Subline | Card.Media | Card.Preline
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Compound component pattern (from Storybook)
+<Card style={{ maxWidth: '320px' }}>
+  <Card.Media src="https://placehold.co/600x400?text=MEDIA" alt="Card media" />
+  <Card.Container>
+    <Card.Header>
+      <Card.Preline>Preline</Card.Preline>
+      <Card.Title>Title</Card.Title>
+      <Card.Subline>Subline</Card.Subline>
+    </Card.Header>
+    <Card.Body>
+      Content goes here
+    </Card.Body>
+    <Card.Footer>
+      <Button variant="primary" text="Primäraktion" />
+      <Button variant="secondary" text="Aktion" />
+    </Card.Footer>
+  </Card.Container>
+</Card>
+
+// ❌ Incorrect: Flat structure without compound components
+<Card>
+  <h2>Title</h2>
+  <p>Content</p>
+</Card>
+```
+
+### Grid
+Responsive grid system with `Row` and `Column` primitives.
+
+**Import:**
+```typescript
+import { Grid } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface GridProps extends React.HTMLAttributes<HTMLDivElement> {
+  type?: 'container' | 'fluid';
+}
+
+export interface GridColumnProps extends React.HTMLAttributes<HTMLDivElement> {
+  width?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+  breakpoint?: 'sm' | 'md' | 'lg' | 'xl';
+  isOffset?: boolean;
+  offsetWidth?: number;
+}
+
+export interface GridRowProps extends React.HTMLAttributes<HTMLDivElement> {
+  alignItems?: 'start' | 'center' | 'end';
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Responsive grid (Storybook pattern)
+<Grid>
+  <Grid.Row>
+    <Grid.Column width={4}>
+      <TextInput label="Name" id="name" name="name" required />
+    </Grid.Column>
+    <Grid.Column width={4}>
+      <TextInput label="Vorname" id="vorname" name="vorname" required />
+    </Grid.Column>
+    <Grid.Column width={4}>
+      <TextInput label="Alter" id="alter" name="alter" required />
+    </Grid.Column>
+  </Grid.Row>
+</Grid>
+
+// ❌ Avoid: Non-responsive, unclear structure
+<div className="custom-grid">
+  <Card>Item 1</Card>
+</div>
+```
+
+---
+
+## Input & Forms
+
+### TextInput
+Single-line text input field with built-in label, hint, and error states.
+
+**Import:**
+```typescript
+import { TextInput } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface TextInputProps 
+  extends React.InputHTMLAttributes<HTMLInputElement> {
+  label?: string;
+  hintText?: string;
+  error?: string | boolean;
+  hasOptionalLabel?: boolean;
+}
+```
+
+**Usage:**
+```tsx
+// ✅ With label and error handling
+<TextInput
+  id="email"
+  name="email"
+  label="Email Address"
+  hintText="Hint Text"
+  error={hasError ? 'Invalid email' : undefined}
+  aria-describedby={hasError ? 'error-msg' : undefined}
+  required
+/>
+{hasError && <span id="error-msg" role="alert">Invalid email</span>}
+
+// ❌ Avoid: No label
+<TextInput type="email" />
+```
+
+### Label
+Associates text with form inputs.
+
+**Import:**
+```typescript
+import { Label } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface LabelProps 
+  extends React.LabelHTMLAttributes<HTMLLabelElement> {}
+```
+
+**Usage:**
+```tsx
+// ✅ Paired with a custom input via htmlFor
+<Label htmlFor="username">Username</Label>
+<input id="username" className="kern-input" />
+
+// ❌ Incorrect: Label disconnected from input
+<Label>Username</Label>
+<input className="kern-input" />
+```
+
+### Fieldset
+Groups form controls with a legend.
+
+**Import:**
+```typescript
+import { Fieldset } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface FieldsetRootProps 
+  extends React.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  error?: boolean;
+}
+
+export interface FieldsetLegendProps {
+  hasOptionalLabel?: boolean;
+}
+
+export interface FieldsetContentProps {
+  horizontal?: boolean;
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Grouped form section (Storybook pattern)
+<Fieldset.Root>
+  <Fieldset.Legend>Ansprechpartner</Fieldset.Legend>
+  <Fieldset.Content>
+    <TextInput label="Vorname" id="vorname" name="vorname" required />
+    <TextInput label="Name" id="name" name="name" required />
+  </Fieldset.Content>
+</Fieldset.Root>
+
+// ✅ Optional labels and hint
+<Fieldset.Root>
+  <Fieldset.Legend hasOptionalLabel>Kontakt</Fieldset.Legend>
+  <Fieldset.Hint>Hint Text</Fieldset.Hint>
+  <Fieldset.Content>
+    <CheckboxInput id="herr" name="geschlecht" label="Herr" />
+    <CheckboxInput id="frau" name="geschlecht" label="Frau" />
+  </Fieldset.Content>
+</Fieldset.Root>
+
+// ✅ Error state
+<Fieldset.Root error>
+  <Fieldset.Legend>Ansprechpartner</Fieldset.Legend>
+  <Fieldset.Content>
+    <TextInput label="Name" id="name" name="name" error required />
+  </Fieldset.Content>
+  <Fieldset.Error>Der Name darf nicht leer sein</Fieldset.Error>
+</Fieldset.Root>
+
+// ❌ Avoid: Ungrouped form fields
+<TextInput placeholder="Name" />
+<TextInput placeholder="Email" />
+```
+
+---
+
+## Navigation & Interactive
+
+### Button
+Primary interactive control.
+
+**Import:**
+```typescript
+import { Button } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface ButtonProps
+  extends Omit<React.ComponentPropsWithoutRef<'button'>, 'text'> {
+  variant?: 'primary' | 'secondary' | 'tertiary';
+  isBlock?: boolean;
+  icon?: IconProps | React.ReactNode;
+  iconSize?: 'small' | 'default' | 'large' | 'x-large';
+  iconOnly?: boolean;
+  iconLeft?: boolean;
+  text?: string | null;
+}
+```
+
+**Usage:**
+```tsx
+// ✅ With label and semantic type
+<Button type="submit" variant="primary" text="Save Changes" />
+
+<Button 
+  variant="secondary" 
+  icon={{ name: 'trash' }} 
+  iconOnly 
+  aria-label="Delete item"
+/>
+
+// ❌ Avoid: Unlabeled icon button
+<Button icon={{ name: 'X' }} iconOnly />
+
+// ❌ Avoid: Styling button as a link
+<Button variant="tertiary">Go to page</Button> {/* Use Link instead */}
+```
+
+### Link
+Semantic hyperlink component.
+
+**Import:**
+```typescript
+import { Link } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface LinkProps 
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  variant?: 'default' | 'small';
+  icon?: IconProps;
+  iconLeft?: boolean;
+  isStretched?: boolean;
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Title-based links (Storybook pattern)
+<Link
+  href="https://www.w3.org/WAI/standards-guidelines/wcag/"
+  title="Learn more about accessibility"
+/>
+
+// ✅ Icon link (icon hidden from screen readers by default)
+<Link
+  href="https://www.w3.org/WAI/standards-guidelines/wcag/"
+  title="Learn more about accessibility"
+  icon={{ name: 'arrow-forward', size: 'default', 'aria-hidden': true }}
+  iconLeft
+/>
+
+// ❌ Avoid: Using Button for navigation
+<Button variant="tertiary" text="Go to page" />
+```
+
+### Accordion
+Expandable/collapsible content sections.
+
+**Import:**
+```typescript
+import { Accordion } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface AccordionProps 
+  extends React.HTMLAttributes<HTMLDivElement> {}
+// Compound components:
+// Accordion.Root | Accordion.Group | Accordion.Summary | Accordion.Content
+// Accordion.Summary accepts: title: { title: string; textWrapper: 'h2' | 'h3' | ... }
+```
+
+**Usage:**
+```tsx
+// ✅ Compound accordion structure (Storybook pattern)
+<Accordion.Root>
+  <Accordion.Summary title={{ title: 'Accordion 1', textWrapper: 'h2' }} />
+  <Accordion.Content>Details for section 1</Accordion.Content>
+</Accordion.Root>
+
+<Accordion.Group>
+  <Accordion.Root>
+    <Accordion.Summary title={{ title: 'Accordion 1', textWrapper: 'h3' }} />
+    <Accordion.Content>Details for section 1</Accordion.Content>
+  </Accordion.Root>
+  <Accordion.Root>
+    <Accordion.Summary title={{ title: 'Accordion 2', textWrapper: 'h3' }} />
+    <Accordion.Content>Details for section 2</Accordion.Content>
+  </Accordion.Root>
+</Accordion.Group>
+
+// ❌ Avoid: Flat content structure
+<div className="accordion">
+  <button>Section 1</button>
+  <p>Details</p>
+</div>
+```
+
+---
+
+## Content & Display
+
+### Heading
+Semantic heading elements (h1–h6).
+
+**Import:**
+```typescript
+import { Heading } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface HeadingProps 
+  extends React.HTMLAttributes<HTMLHeadingElement> {
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  visual?: 'large' | 'medium' | 'small'; // Override visual size
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Semantic heading hierarchy
+<Heading level={1}>Page Title</Heading>
+<Heading level={2}>Section</Heading>
+<Heading level={3}>Subsection</Heading>
+
+// ❌ Avoid: Skipping heading levels
+<Heading level={1}>Page Title</Heading>
+<Heading level={3}>Subsection (skipped level 2)</Heading>
+```
+
+### Body
+Container for body text content.
+
+**Import:**
+```typescript
+import { Body } from '@publicplan/kern-react-kit';
+```
+
+**Usage:**
+```tsx
+// ✅ Wrapping text content
+<Body>
+  This is body text with consistent styling and line height.
+</Body>
+
+// ❌ Avoid: Mixing styled and unstyled text
+<Body>Styled text</Body>
+<p>Unstyled text</p>
+```
+
+### Badge
+Small label or status indicator.
+
+**Import:**
+```typescript
+import { Badge } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface BadgeProps 
+  extends React.HTMLAttributes<HTMLSpanElement> {
+  title?: string;
+  variant?: 'info' | 'success' | 'warning' | 'danger';
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Status indicator (Storybook pattern)
+<Badge variant="info" title="Information" />
+<Badge variant="success" title="Erfolg" />
+<Badge variant="warning" title="Warnung" />
+<Badge variant="danger" title="Fehler" />
+
+// ❌ Avoid: Styling arbitrary text as a badge
+<Badge>Click here</Badge> {/* Use Button instead */}
+```
+
+---
+
+## Modals & Overlays
+
+### Dialog
+Modal dialog/overlay component.
+
+**Import:**
+```typescript
+import { Dialog } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface DialogProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  disableOverlayClose?: boolean;
+}
+// Compound components:
+// Dialog.Trigger | Dialog.Modal | Dialog.Header | Dialog.Content | Dialog.Footer | Dialog.Button
+// Dialog.Header accepts: dialogTitle, hasCloseButton
+// Dialog.Modal accepts: open, noOverlay
+```
+
+**Usage:**
+```tsx
+// ✅ Dialog with trigger and modal (Storybook pattern)
+<Dialog disableOverlayClose={false}>
+  <Dialog.Trigger>
+    <Button variant="primary" text="Open Dialog" />
+  </Dialog.Trigger>
+  <Dialog.Modal>
+    <Dialog.Header dialogTitle="Frage?" hasCloseButton />
+    <Dialog.Content>Are you sure?</Dialog.Content>
+    <Dialog.Footer>
+      <Dialog.Button variant="secondary" title="Abbrechen" />
+      <Dialog.Button
+        variant="primary"
+        title="Löschen"
+        onClick={(e, context) => {
+          context.closeDialog();
+        }}
+      />
+    </Dialog.Footer>
+  </Dialog.Modal>
+</Dialog>
+
+// ❌ Avoid: Uncontrolled dialog without focus management
+<div className="modal" style={{ display: 'block' }}>
+  Content
+</div>
+```
+
+---
+
+## Data Display
+
+### Table
+Semantic table component.
+
+**Import:**
+```typescript
+import { Table } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface TableProps 
+  extends React.TableHTMLAttributes<HTMLTableElement> {
+  variant?: 'default' | 'small';
+  caption?: string;
+  striped?: boolean;
+  responsive?: boolean;
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Semantic table with headers (Storybook pattern)
+<Table caption="Autovermietung Flotte" variant="default" striped={false}>
+  <Table.Header>
+    <Table.Row>
+      <Table.Column scope="col">Marke</Table.Column>
+      <Table.Column scope="col">Verfügbarkeit</Table.Column>
+      <Table.Column scope="col" numeric>
+        Tagespreis
+      </Table.Column>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Column scope="row">BMW</Table.Column>
+      <Table.Cell>Frei</Table.Cell>
+      <Table.Cell numeric>69,00 €</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+
+// ❌ Avoid: Non-semantic data grid
+<div className="custom-table">
+  <div className="row">Item 1 | Item 2</div>
+</div>
+```
+
+### Progress
+Progress bar component.
+
+**Import:**
+```typescript
+import { Progress } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface ProgressProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'role'> {
+  value?: number;
+  max?: number;
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Progress with Bar and Label (Storybook pattern)
+<Progress value={2} max={5}>
+  <Progress.Label>Schritt 2 von 5</Progress.Label>
+  <Progress.Bar />
+</Progress>
+
+// ❌ Avoid: Progress without context
+<Progress value={50}>
+  <Progress.Bar />
+</Progress>
+```
+
+---
+
+## Utilities
+
+### Icon
+Renders icons from icon set.
+
+**Import:**
+```typescript
+import { Icon } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface IconProps {
+  name: string; // e.g., 'arrow-right', 'settings', 'trash'
+  size?: 'small' | 'default' | 'large' | 'x-large';
+  aria-label?: string; // Required if used as standalone interactive element
+}
+```
+
+**Usage:**
+```tsx
+// ✅ Icon in button (button provides accessible name)
+<Button icon={{ name: 'trash' }} iconOnly aria-label="Delete" />
+
+// ✅ Icon with text
+<Button icon={{ name: 'arrow-right', size: 'large' }} text="Next" />
+
+// ❌ Avoid: Unlabeled icon button
+<Button icon={{ name: 'X' }} iconOnly />
+```
+
+### Divider
+Visual separator.
+
+**Import:**
+```typescript
+import { Divider } from '@publicplan/kern-react-kit';
+```
+
+**Usage:**
+```tsx
+// ✅ Separating content sections
+<Card.Body>Content 1</Card.Body>
+<Divider />
+<Card.Body>Content 2</Card.Body>
+
+// ❌ Avoid: Multiple dividers in a row
+<Divider />
+<Divider />
+<Divider />
+```
+
+### Loader
+Loading spinner indicator.
+
+**Import:**
+```typescript
+import { Loader } from '@publicplan/kern-react-kit';
+```
+
+**Interface:**
+```typescript
+export interface LoaderProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  visible?: boolean;
+  srDescription?: string;
+}
+```
+
+**Usage:**
+```tsx
+// ✅ With accessible label (Storybook pattern)
+<Loader visible srDescription="Wird geladen..." />
+
+// ❌ Avoid: Unlabeled spinner
+<Loader visible />
+```
+
+---
+
+## Quick Reference Table
+
+| Component | Category | Status | Notes |
+|-----------|----------|--------|-------|
+| Accordion | Navigation | ✅ | Compound component |
+| Alert | Feedback | ✅ | Contextual variants |
+| Badge | Content | ✅ | Status indicator |
+| Body | Content | ✅ | Text container |
+| Button | Interactive | ✅ | Multiple variants |
+| Card | Layout | ✅ | Compound component |
+| Divider | Utility | ✅ | Visual separator |
+| Dialog | Modal | ✅ | Compound component |
+| Fieldset | Forms | ✅ | Group controls |
+| Grid | Layout | ✅ | Responsive grid |
+| Heading | Content | ✅ | Semantic h1–h6 |
+| Icon | Utility | ✅ | Icon library |
+| Input (TextInput) | Forms | ✅ | Text, email, etc. |
+| Label | Forms | ✅ | Input association |
+| Link | Navigation | ✅ | Semantic anchor |
+| Loader | Feedback | ✅ | Loading state |
+| Progress | Feedback | ✅ | Progress indicator |
+| Table | Data | ✅ | Semantic table |
+| Title | Content | ✅ | Large heading |
+| TaskList | Lists | ✅ | Checklist component |
+
+---
+
+**For more details on each component, see the Storybook documentation:**
+```bash
+npm run storybook
+```
+
+---
+
+*Last updated: 2026-03-03*