@festo-ui/react 10.1.0 → 10.1.1-dev.918

package/llm-doc/components.md

@@ -0,0 +1,661 @@
+# UI Components
+
+## Accordion
+
+Collapsible content sections.
+
+### Components
+- `Accordion` — Container
+- `AccordionHeader` — Header of the entire accordion
+- `AccordionItem` — Single collapsible element
+- `AccordionItemHeader` — Header of an item
+- `AccordionItemBody` — Content of an item
+
+### Accordion Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showMore` | `string` | `"Show more"` | Text for "Show more" |
+| `showLess` | `string` | `"Show less"` | Text for "Show less" |
+| `keepItemsOpen` | `boolean` | `true` | Multiple items open simultaneously. `false` = auto-collapse |
+| `transparent` | `boolean` | `false` | Transparent background |
+| `highlighted` | `boolean` | `true` | Highlighted style |
+
+### AccordionItem Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `expanded` | `boolean` | Controlled: whether open |
+| `defaultExpanded` | `boolean` | Initial state (default: `false`) |
+| `onChange` | `(expanded: boolean, event) => void` | Callback on state change |
+
+### Example — Basic
+```tsx
+<Accordion>
+  <AccordionHeader>Title</AccordionHeader>
+  <AccordionItem>
+    <AccordionItemHeader>Item 1</AccordionItemHeader>
+    <AccordionItemBody>Content 1</AccordionItemBody>
+  </AccordionItem>
+  <AccordionItem>
+    <AccordionItemHeader>Item 2</AccordionItemHeader>
+    <AccordionItemBody>Content 2</AccordionItemBody>
+  </AccordionItem>
+</Accordion>
+```
+
+### Example — Auto-Collapse
+```tsx
+<Accordion keepItemsOpen={false}>
+  <AccordionHeader>Title</AccordionHeader>
+  <AccordionItem>
+    <AccordionItemHeader>Item 1</AccordionItemHeader>
+    <AccordionItemBody>Content 1</AccordionItemBody>
+  </AccordionItem>
+</Accordion>
+```
+
+### Example — Controlled
+```tsx
+const [expanded, setExpanded] = useState('item1');
+const handleChange = (panel) => (isExpanded) => {
+  setExpanded(isExpanded ? panel : false);
+};
+
+<Accordion>
+  <AccordionItem expanded={expanded === 'item1'} onChange={handleChange('item1')}>
+    <AccordionItemHeader>Item 1</AccordionItemHeader>
+    <AccordionItemBody>Content 1</AccordionItemBody>
+  </AccordionItem>
+</Accordion>
+```
+
+---
+
+## BottomSheet
+
+Mobile bottom sheet overlay.
+
+### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | — | Controlled: whether visible |
+| `defaultExpanded` | `boolean` | — | Initial state |
+| `expandFrom` | `"center" \| "bottom"` | `"center"` | Expand direction |
+| `hasBackdrop` | `boolean` | `true` | Show backdrop overlay |
+| `hideCloseIcon` | `boolean` | — | Hide close icon |
+| `onOpenChange` | `(value: boolean) => void` | — | Callback on open/close |
+
+### Example
+```tsx
+const [open, setOpen] = useState(false);
+
+<button onClick={() => setOpen(true)}>Open</button>
+<BottomSheet open={open} onOpenChange={setOpen}>
+  <p>Content</p>
+</BottomSheet>
+```
+
+---
+
+## Breadcrumb
+
+Navigation path display.
+
+### Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `locations` | `BreadcrumbLocation[]` | Array with `{ text, href }` |
+| `onClick` | `(event) => void` | Click handler for links |
+
+### Example — With locations array
+```tsx
+<Breadcrumb
+  locations={[
+    { text: 'Home', href: '/' },
+    { text: 'Products', href: '/products' },
+    { text: 'Current', href: '/products/current' },
+  ]}
+  onClick={(e) => e.preventDefault()}
+/>
+```
+
+### Example — With children
+```tsx
+<Breadcrumb>
+  <a href="/components">Components</a>
+  <a href="/components/breadcrumbs">Breadcrumbs</a>
+</Breadcrumb>
+```
+
+---
+
+## Button
+
+Standard buttons in various variants.
+
+### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `primary` | `boolean` | `false` | Primary/hero button |
+| `tertiary` | `boolean` | `false` | Tertiary button (text style) |
+| `icon` | `ReactNode` | — | Icon element |
+| `iconOnly` | `boolean` | `false` | Icon only, no text |
+| `large` | `boolean` | `false` | Larger variant |
+| `floating` | `boolean` | `false` | Floating action button |
+| `disabled` | `boolean` | `false` | Disabled |
+
+### Examples
+```tsx
+<Button>Default</Button>
+<Button primary>Primary</Button>
+<Button tertiary>Tertiary</Button>
+<Button large>Large</Button>
+<Button icon={<IconCoreRangeProduct />}>With Icon</Button>
+<Button iconOnly icon={<IconCoreRangeProduct />} />
+<Button iconOnly large primary floating icon={<IconCoreRangeProduct />} />
+```
+
+---
+
+## Card
+
+Card component with header, body, and notifications.
+
+### Components
+- `Card` — Container
+- `CardHeader` — Header with optional image, subtitle, and action
+- `CardBody` — Text content with optional children
+- `CardNotification` — Notification bar
+
+### Example
+```tsx
+<Card>
+  <CardHeader
+    title="Card Title"
+    subtitle="Description"
+    image={{ src: 'image.webp', alt: 'Image', aspectRatio: '16/9' }}
+    action={<button className="fwe-btn fwe-btn-icon">...</button>}
+  />
+  <CardBody text="Card text">
+    <button className="fwe-btn fwe-btn-hero fwe-btn-block">Action</button>
+  </CardBody>
+  <CardNotification className="fwe-bg-orange" title="Warning" message="Details" />
+</Card>
+```
+
+---
+
+## Chip / ChipContainer
+
+Chips for filters, categories, selection, and actions.
+
+### Chip Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `ChipType` | `ChipType.Choice` | Chip type: `Choice`, `Category`, `Filter`, `Action`, `Readonly` |
+| `icon` | `ReactNode` | — | Icon |
+| `selected` | `boolean` | `false` | Selected |
+| `disabled` | `boolean` | `false` | Disabled |
+| `large` | `boolean` | `false` | Large |
+
+### ChipContainer Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `large` | `boolean` | `false` | Large chips in container |
+
+### Example
+```tsx
+import { Chip, ChipContainer, ChipType } from '@festo-ui/react';
+
+<ChipContainer>
+  <Chip>Choice</Chip>
+  <Chip selected>Selected</Chip>
+  <Chip type={ChipType.Filter} selected>Filter</Chip>
+  <Chip type={ChipType.Action} icon={<IconCoreRangeProduct />}>Action</Chip>
+  <Chip type={ChipType.Readonly}>Readonly</Chip>
+</ChipContainer>
+```
+
+---
+
+## LoadingIndicator
+
+Loading indicator in three sizes.
+
+### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `"large" \| "medium" \| "small"` | `"large"` | Size |
+
+### Example
+```tsx
+<LoadingIndicator />
+<LoadingIndicator size="medium">Loading...</LoadingIndicator>
+<LoadingIndicator size="small">Loading...</LoadingIndicator>
+```
+
+---
+
+## MobileFlyout
+
+Mobile navigation with nested pages.
+
+### MobileFlyout Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | — | Controlled: whether open |
+| `defaultOpen` | `boolean` | — | Initial state |
+| `visible` | `string[]` | — | Controlled: visible pages |
+| `defaultVisible` | `string[]` | `['root']` | Initially visible pages |
+| `onOpenChange` | `(value: boolean) => void` | — | Callback |
+| `onVisibleChange` | `(value: string) => void` | — | Callback |
+| `back` | `string` | — | Back text |
+
+### MobileFlyoutItem Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `ReactNode` | Icon |
+| `pageLink` | `string` | Links to a MobileFlyoutPage |
+| `active` | `boolean` | Active state |
+| `component` | `ElementType` | Alternative HTML element |
+
+### MobileFlyoutPage Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `name` | `string` | Unique page name |
+| `root` | `boolean` | Whether this is the root page |
+| `back` | `string` | Back text |
+
+### Example
+```tsx
+<MobileFlyout>
+  <MobileFlyoutPage root name="root">
+    <MobileFlyoutItem href="/page1">Page 1</MobileFlyoutItem>
+    <MobileFlyoutItem icon={<IconSettings />} pageLink="settings">
+      Settings
+    </MobileFlyoutItem>
+  </MobileFlyoutPage>
+  <MobileFlyoutPage name="settings">
+    <h3>Settings</h3>
+    <MobileFlyoutItem pageLink="advanced">Advanced</MobileFlyoutItem>
+  </MobileFlyoutPage>
+</MobileFlyout>
+```
+
+---
+
+## Modals (AlertModal, ConfirmModal, CustomModal, Prompt)
+
+Various dialog types.
+
+### AlertModal
+Displays a warning/info dialog.
+```tsx
+<AlertModal
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  onCancel={() => setOpen(false)}
+  onOk={() => setOpen(false)}
+  title="Title"
+  subtitle="Subtitle"
+  body="Message"
+  alertType="info"  // or "warning"
+  cancel="Cancel"
+  ok="OK"
+  strong={false}  // true for strong warning
+/>
+```
+
+### ConfirmModal
+Confirmation dialog.
+```tsx
+<ConfirmModal
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  onCancel={() => setOpen(false)}
+  onOk={() => setOpen(false)}
+  title="Confirmation"
+  subtitle="Subtitle"
+  body="Do you want to continue?"
+  cancel="Cancel"
+  ok="OK"
+  large={false}  // true for large scrollable variant
+/>
+```
+
+### Prompt
+Input dialog.
+```tsx
+<Prompt
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  onCancel={() => setOpen(false)}
+  onOk={() => setOpen(false)}
+  title="Headline"
+  subtitle="Category"
+  label="Label"
+  hint="Optional hint"
+  cancel="Cancel"
+  ok="Send"
+/>
+```
+
+### CustomModal
+Freely customizable dialog.
+```tsx
+<CustomModal
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  title="Title"
+  subtitle="Subtitle"
+  closeOnBackdrop={false}
+>
+  <form onSubmit={handleSubmit}>
+    <div className="fwe-modal-body">
+      {/* Form content */}
+    </div>
+    <div className="fwe-modal-footer">
+      <div className="fwe-modal-buttons">
+        <button type="button" className="fwe-btn fwe-btn-lg" onClick={() => setOpen(false)}>
+          Cancel
+        </button>
+        <button className="fwe-btn fwe-btn-lg fwe-btn-hero" type="submit">
+          Submit
+        </button>
+      </div>
+    </div>
+  </form>
+</CustomModal>
+```
+
+### Common Modal Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `isOpen` | `boolean` | **Required.** Whether the dialog is visible |
+| `isLoading` | `boolean` | Show loading state |
+| `closeOnBackdrop` | `boolean` | Close by clicking backdrop (default: `true`) |
+| `onClose` | `() => void` | Callback on close |
+| `onCloseDone` | `() => void` | Callback after close animation |
+
+---
+
+## ImageGallery
+
+Fullscreen image gallery overlay.
+
+### Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `isOpen` | `boolean` | **Required.** Whether open |
+| `startIndex` | `number` | **Required.** Starting image index |
+| `images` | `ImageGalleryItemData[]` | Array of images |
+| `thumbnailImages` | `ImageGalleryItemData[]` | Thumbnail images |
+| `pagination` | `number \| boolean` | Show pagination |
+| `showScaleButton` | `boolean` | Show zoom button |
+| `descriptiveContent` | `boolean \| (index: number) => ReactNode` | Descriptive text |
+| `onClose` | `() => void` | Callback on close |
+| `onSlideChanged` | `(index: number) => void` | Callback on slide change |
+
+### Example
+```tsx
+const [open, setOpen] = useState(false);
+
+<button onClick={() => setOpen(true)}>Open Gallery</button>
+<ImageGallery
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  images={images}
+  startIndex={0}
+  pagination
+  thumbnailImages={images}
+  showScaleButton
+  descriptiveContent
+/>
+```
+
+---
+
+## Pagination
+
+Page navigation in three styles.
+
+### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"NUMERIC" \| "SIMPLE" \| "DOTS"` | `"NUMERIC"` | Display style |
+| `pageMax` | `number` | — | **Required.** Maximum page count |
+| `pageCurrent` | `number` | — | Controlled: current page |
+| `defaultPageCurrent` | `number` | `1` | Initial page |
+| `onChange` | `(page: number, event) => void` | — | Callback |
+
+### Example
+```tsx
+<Pagination pageMax={10} defaultPageCurrent={3} />
+<Pagination pageMax={10} defaultPageCurrent={3} type="SIMPLE" />
+<Pagination pageMax={5} defaultPageCurrent={3} type="DOTS" />
+```
+
+---
+
+## Popover / Tooltip / Legend / PopoverMenu
+
+Overlay elements for additional information.
+
+### Popover Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `content` | `ReactNode` | Popover content |
+| `position` | `Placement` | Position (e.g. `"right"`, `"top"`) |
+| `isOpen` | `boolean` | Controlled |
+| `onChange` | `(isOpen: boolean) => void` | Callback |
+| `openOnHover` | `boolean` | Open on hover |
+| `openByDefault` | `boolean` | Initially open |
+| `onTriggerClick` | `(event) => void` | Custom trigger handler |
+
+### Examples
+```tsx
+<Popover content="Content">Click me</Popover>
+<Popover position="right" content="Right">Click</Popover>
+<Popover openOnHover content="Hover info">Hover</Popover>
+<Tooltip content="Tooltip text">Element</Tooltip>
+
+<PopoverMenu items={[
+  { text: 'Download', icon: <IconDownload />, onClick: () => {} },
+  { text: 'Delete', icon: <IconDelete />, onClick: () => {} },
+]}>
+  <IconMore size={24} />
+</PopoverMenu>
+
+<Legend items={[{ name: 'PN', text: 'Part Number' }]}>
+  <button className="fwe-btn fwe-btn-link fwe-dark"><IconInfo />Legend</button>
+</Legend>
+```
+
+---
+
+## Progress
+
+Progress bar.
+
+### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `progress` | `number` | — | **Required.** Progress 0–100 |
+| `background` | `"white" \| "background" \| "black"` | `"white"` | Background color |
+| `error` | `boolean` | `false` | Error state (red) |
+
+### Example
+```tsx
+<Progress progress={50} />
+<Progress progress={50} error />
+<Progress progress={75} background="background" />
+```
+
+---
+
+## SearchInput
+
+Search field with autocomplete suggestions.
+
+### SearchInput Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Placeholder text |
+| `value` | `string` | Controlled |
+| `defaultValue` | `string` | Initial value |
+| `debounceTime` | `number` | Debounce in ms (default: 0) |
+| `onChange` | `(value: string) => void` | Callback on input |
+| `onSearch` | `(value: string) => void` | Callback on Enter/selection |
+
+### Example
+```tsx
+const [query, setQuery] = useState('');
+const [results, setResults] = useState([]);
+
+function handleChange(value) {
+  setQuery(value);
+  setResults(allItems.filter(s => s.toLowerCase().includes(value.toLowerCase())));
+}
+
+<SearchInput label="Search" onChange={handleChange} onSearch={console.log}>
+  {results.map(item => (
+    <SearchInputOption key={item} value={item}>
+      <SearchResult label={item} query={query} />
+    </SearchInputOption>
+  ))}
+</SearchInput>
+```
+
+---
+
+## Snackbar
+
+Toast notifications.
+
+### Setup
+Wrap with `SnackbarProvider` at the root:
+```tsx
+<SnackbarProvider>
+  <App />
+</SnackbarProvider>
+```
+
+### Usage with hook
+```tsx
+const showSnackbar = useSnackbar();
+showSnackbar({ text: 'Successfully saved!' });
+```
+
+### Usage without hook
+```tsx
+import { addSnackbar } from '@festo-ui/react';
+addSnackbar({ text: 'Saved!' });
+```
+
+---
+
+## Stepper (Vertical & Horizontal)
+
+Step indicator for multi-step processes.
+
+### Example — Vertical
+```tsx
+const [stepIndex, setStepIndex] = useState(0);
+
+<StepperVertical stepIndex={stepIndex} onChange={setStepIndex}>
+  <StepVertical title="Step 1">
+    <p>Content</p>
+    <button className="fwe-btn" onClick={() => setStepIndex(stepIndex + 1)}>Next</button>
+  </StepVertical>
+  <StepVertical title="Step 2">
+    <p>Content</p>
+  </StepVertical>
+</StepperVertical>
+```
+
+### Example — Horizontal
+```tsx
+<StepperHorizontal stepIndex={stepIndex} onChange={setStepIndex}>
+  <StepHorizontal title="Step 1">Content</StepHorizontal>
+  <StepHorizontal title="Step 2">Content</StepHorizontal>
+</StepperHorizontal>
+```
+
+---
+
+## Tabs
+
+Tab navigation with content areas.
+
+### Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `TabsConfiguration` | — | Configuration (tabBar, tabItems) |
+| `viewType` | `"responsive" \| "legacy"` | `"responsive"` | View type |
+| `showDivider` | `boolean` | `false` | Divider line under tabs |
+| `onChange` | `({ previous, current }) => void` | — | Callback on tab change |
+
+### TabPane Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `name` | `string` | **Required.** Tab name/label |
+| `icon` | `ReactNode` | Optional: icon in tab |
+
+### Example
+```tsx
+<Tabs>
+  <TabPane name="Tab 1">Content 1</TabPane>
+  <TabPane name="Tab 2">Content 2</TabPane>
+  <TabPane name="Tab 3">Content 3</TabPane>
+</Tabs>
+```
+
+### Configuration example
+```tsx
+<Tabs
+  viewType="legacy"
+  config={{
+    tabBar: { fullWidth: true },
+    tabItems: { appearance: 'fill' },  // 'equal' | 'fill'
+  }}
+>
+  <TabPane name="Tab 1">Content</TabPane>
+</Tabs>
+```
+
+---
+
+## TableHeaderCell
+
+Sortable table header cell.
+
+### Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `active` | `boolean` | Whether this column is actively sorted |
+| `ascending` | `boolean` | **Required.** Sort direction |
+
+### Example
+```tsx
+const [orderBy, setOrderBy] = useState('name');
+const [ascending, setAscending] = useState(true);
+
+<table className="fwe-table">
+  <thead>
+    <tr>
+      <TableHeaderCell
+        ascending={ascending}
+        active={orderBy === 'name'}
+        onClick={() => {
+          setAscending(orderBy === 'name' ? !ascending : true);
+          setOrderBy('name');
+        }}
+      >
+        Name
+      </TableHeaderCell>
+    </tr>
+  </thead>
+  <tbody>
+    <tr className="fwe-tr-md"><td>Entry</td></tr>
+  </tbody>
+</table>
+```