@emporix/component-library 1.8.2 → 1.11.0

package/README.md

@@ -132,6 +132,237 @@ import { InputText } from '@emporix/component-library'
 
 All standard HTML input attributes (placeholder, value, onChange, etc.) are supported.
 
+### AutoComplete
+
+Search input with async suggestions. API inspired by [PrimeReact AutoComplete](https://primereact.org/autocomplete/).
+
+```tsx
+import { AutoComplete } from '@emporix/component-library'
+;<AutoComplete
+  value={query}
+  suggestions={vendors}
+  field='name'
+  dropdown
+  completeMethod={({ query }) => searchVendors(query)}
+  onChange={e => setQuery(e.value)}
+  onSelect={e => setSelectedVendor(e.value)}
+  label='Vendor'
+  placeholder='Search vendor...'
+/>
+```
+
+| Prop           | Type     | Description                        |
+| -------------- | -------- | ---------------------------------- |
+| value          | string   | Controlled input text              |
+| suggestions    | T[]      | Suggestion list from parent        |
+| completeMethod | function | Called (debounced) when user types |
+| onChange       | function | Input text changes                 |
+| onSelect       | function | Suggestion selected                |
+| dropdown       | boolean  | Show dropdown trigger button       |
+| field          | string   | Suggestion label property          |
+
+### Checkbox
+
+A checkbox built on a native `input type="checkbox"` with PrimeReact-compatible `onChange` events (`{ checked, originalEvent }`). API inspired by [PrimeReact Checkbox](https://primereact.org/checkbox/).
+
+```tsx
+import { useState } from 'react'
+import { Checkbox } from '@emporix/component-library'
+
+// Controlled single checkbox
+const [checked, setChecked] = useState(false)
+<Checkbox checked={checked} onChange={e => setChecked(e.checked)} />
+
+// With label (associate via inputId + htmlFor)
+<Checkbox inputId="remember-me" checked={checked} onChange={e => setChecked(e.checked)} />
+<label htmlFor="remember-me">Remember me</label>
+
+// Role toggles (single selection)
+const roles = ['viewer', 'editor', 'manager', 'administrator']
+const [selectedRole, setSelectedRole] = useState<string | null>(null)
+{roles.map(role => (
+  <div key={role}>
+    <Checkbox
+      inputId={role}
+      value={role}
+      checked={selectedRole === role}
+      onChange={e => setSelectedRole(e.checked ? role : null)}
+    />
+    <label htmlFor={role}>{role}</label>
+  </div>
+))}
+```
+
+#### Props
+
+| Prop        | Type                             | Default | Description                                     |
+| ----------- | -------------------------------- | ------- | ----------------------------------------------- |
+| checked     | boolean                          | false   | Whether the checkbox is checked (controlled)    |
+| onChange    | (e: CheckboxChangeEvent) => void | -       | Fired when checked state changes                |
+| value       | unknown                          | -       | Value associated with the checkbox              |
+| inputId     | string                           | -       | id for the native input (for label association) |
+| disabled    | boolean                          | false   | Whether the checkbox is disabled                |
+| invalid     | boolean                          | false   | Invalid state for validation styling            |
+| name        | string                           | -       | Name attribute for form submission              |
+| readOnly    | boolean                          | false   | Prevents user interaction                       |
+| required    | boolean                          | false   | Marks the field as required                     |
+| className   | string                           | -       | Additional CSS class for the root               |
+| data-testid | string                           | -       | Test ID for root and input (suffix `-input`)    |
+
+Standard HTML input attributes (`aria-label`, `aria-labelledby`, `tabIndex`, etc.) are supported on the native input.
+
+### Dialog
+
+A modal dialog built on [PrimeReact Dialog](https://primereact.org/dialog/). Use for focused tasks that need a decision or confirmation. Wraps PrimeReact internally with scoped Emporix styles.
+
+```tsx
+import { useState } from 'react'
+import {
+  Dialog,
+  PrimaryButton,
+  SecondaryButton,
+} from '@emporix/component-library'
+
+function ConfirmDialogExample() {
+  const [visible, setVisible] = useState(false)
+
+  return (
+    <>
+      <PrimaryButton onClick={() => setVisible(true)}>
+        Open dialog
+      </PrimaryButton>
+      <Dialog
+        visible={visible}
+        onHide={() => setVisible(false)}
+        header='Confirm changes'
+        footer={
+          <>
+            <SecondaryButton onClick={() => setVisible(false)}>
+              Cancel
+            </SecondaryButton>
+            <PrimaryButton onClick={() => setVisible(false)}>
+              Save
+            </PrimaryButton>
+          </>
+        }
+        style={{ width: '100%', maxWidth: '480px' }}
+      >
+        <p>Your changes will be applied immediately.</p>
+      </Dialog>
+    </>
+  )
+}
+```
+
+#### Props
+
+| Prop            | Type          | Default | Description                                              |
+| --------------- | ------------- | ------- | -------------------------------------------------------- |
+| visible         | boolean       | -       | Whether the dialog is visible                            |
+| onHide          | () => void    | -       | Called when the dialog closes (overlay, Escape, or icon) |
+| header          | ReactNode     | -       | Dialog title area                                        |
+| footer          | ReactNode     | -       | Footer slot (e.g. action buttons)                        |
+| children        | ReactNode     | -       | Dialog body content                                      |
+| className       | string        | -       | Additional CSS class on the dialog root                  |
+| style           | CSSProperties | -       | Inline styles on the dialog root (e.g. width)            |
+| modal           | boolean       | true    | Blocks interaction with the page behind the dialog       |
+| dismissableMask | boolean       | modal   | When true, clicking the mask closes the dialog           |
+| closable        | boolean       | true    | Shows the header close icon                              |
+| draggable       | boolean       | false   | Allows dragging the dialog by its header                 |
+| data-testid     | string        | -       | Test ID on the dialog root                               |
+
+Requires PrimeReact base CSS and a theme in the host app.
+
+### DataTable
+
+Encapsulated data table built on [PrimeReact DataTable](https://primereact.org/datatable/). Styles are scoped via CSS modules. Pass `columns`, optional controlled `pagination`, selection, `rowActions`, and an `emptyTemplate` for empty results.
+
+Import `@emporix/component-library/styles` once in your app entry, plus PrimeReact base CSS, a theme, and `primeicons` (required for paginator/sort icons).
+
+```tsx
+import { useMemo, useState } from 'react'
+import { FilterMatchMode } from 'primereact/api'
+import { DataTable } from '@emporix/component-library'
+import type { DataTablePaginationState } from '@emporix/component-library'
+import '@emporix/component-library/styles'
+import 'primereact/resources/primereact.css'
+import 'primereact/resources/themes/lara-light-cyan/theme.css'
+import 'primeicons/primeicons.css'
+
+const columns = [
+  {
+    columnKey: 'name',
+    field: 'name',
+    header: 'Name',
+    sortable: true,
+    filter: true,
+    filterMatchMode: FilterMatchMode.CONTAINS,
+    showFilterMenu: false,
+    showClearButton: false,
+  },
+  { columnKey: 'email', field: 'email', header: 'Email', sortable: true },
+]
+
+function UsersTable({
+  users,
+  totalCount,
+  loading,
+  paginationParams,
+  onPage,
+  onSort,
+  onFilter,
+}) {
+  const [selected, setSelected] = useState([])
+
+  const pagination = useMemo<DataTablePaginationState>(
+    () => ({
+      ...paginationParams,
+      totalRecords: totalCount,
+    }),
+    [paginationParams, totalCount]
+  )
+
+  return (
+    <DataTable
+      value={users}
+      columns={columns}
+      dataKey='id'
+      loading={loading}
+      pagination={pagination}
+      onPage={onPage}
+      onSort={onSort}
+      onFilter={onFilter}
+      selectionMode='multiple'
+      selection={selected}
+      onSelectionChange={setSelected}
+      rowActions={user => <button type='button'>Edit</button>}
+      currentPageReportTemplate='{first} - {last} of {totalRecords}'
+      emptyTemplate={<span>No users found</span>}
+    />
+  )
+}
+```
+
+#### Props
+
+| Prop                          | Type                              | Default | Description                                                |
+| ----------------------------- | --------------------------------- | ------- | ---------------------------------------------------------- |
+| value                         | T[]                               | -       | Row data array (required)                                  |
+| columns                       | ColumnProps[]                     | -       | Column definitions; `rowActions` appends an actions column |
+| dataKey                       | string                            | -       | Unique row identifier field                                |
+| loading                       | boolean                           | false   | Shows loading overlay                                      |
+| pagination                    | DataTablePaginationState          | -       | Controlled pagination/sort/filter state                    |
+| onPage / onSort / onFilter    | function                          | -       | Pagination, sort, and filter event handlers                |
+| selectionMode                 | `'single' \| 'multiple' \| null`  | null    | Row selection mode                                         |
+| selection / onSelectionChange | T \| T[number] \| null / function | -       | Controlled selection state                                 |
+| rowActions                    | (item) => ReactNode               | -       | Renders an actions column per row                          |
+| emptyTemplate                 | ReactNode \| () => ReactNode      | -       | Content when `value` is empty                              |
+| lazy / totalRecords           | boolean / number                  | -       | Server-driven data with external total count               |
+| className / style             | string / CSSProperties            | -       | Root table styling                                         |
+| data-testid                   | string                            | -       | Test ID on the table root                                  |
+
+Omit `pagination` to use the built-in `useDataTablePagination` hook for local client-side paging.
+
 ### Dropdown
 
 A select-style dropdown for choosing one or more items from a list. Supports optional filter/search, editable input, label, required indicator, and validation errors. Hover and focus styles match the InputText component. API inspired by [PrimeReact Dropdown](https://primereact.org/dropdown/).
@@ -179,33 +410,49 @@ const options = [
   multiple
   filter
 />
+
+// Multi-select with removable chips (PrimeReact MultiSelect display="chip" parity)
+<Dropdown
+  value={groupIds}
+  onChange={e => setGroupIds(Array.isArray(e.value) ? e.value : [])}
+  options={groupOptions}
+  multiple
+  display="chip"
+  filter
+  placeholder="Select groups"
+  label="User groups"
+/>
 ```
 
 #### Props
 
-| Prop           | Type                      | Default    | Description                                   |
-| -------------- | ------------------------- | ---------- | --------------------------------------------- |
-| value          | unknown                   | -          | Selected value (array when `multiple`)        |
-| onChange       | (e: ChangeEvent) => void  | -          | Callback when selection changes               |
-| options        | T[]                       | -          | Array of options                              |
-| optionLabel    | string                    | `"label"`  | Property name for option label                |
-| optionValue    | string                    | `"value"`  | Property name for option value                |
-| optionDisabled | string                    | -          | Property name for disabled flag on options    |
-| placeholder    | string                    | `"Select"` | Placeholder when no value selected            |
-| filter         | boolean                   | false      | Enable search filter in the overlay           |
-| editable       | boolean                   | false      | Allow typing in the trigger to filter/select  |
-| onEditEnd      | (e: EditEndEvent) => void | -          | Fired when Enter is pressed in editable mode  |
-| multiple       | boolean                   | false      | Allow multiple selection                      |
-| label          | ReactNode                 | -          | Label text above the trigger                  |
-| error          | ReactNode                 | -          | Error text displayed below the trigger        |
-| required       | boolean                   | false      | Shows asterisk on label                       |
-| inputId        | string                    | -          | id for the trigger (for label association)    |
-| disabled       | boolean                   | false      | Whether the dropdown is disabled              |
-| valueTemplate  | (option) => ReactNode     | -          | Custom render for selected value in trigger   |
-| itemTemplate   | (option) => ReactNode     | -          | Custom render for each option in the list     |
-| className      | string                    | -          | Additional CSS class for the root             |
-| panelClassName | string                    | -          | Additional CSS class for the overlay panel    |
-| data-testid    | string                    | -          | Test ID for root, trigger, panel, and options |
+| Prop               | Type                      | Default                | Description                                   |
+| ------------------ | ------------------------- | ---------------------- | --------------------------------------------- |
+| value              | unknown                   | -                      | Selected value (array when `multiple`)        |
+| onChange           | (e: ChangeEvent) => void  | -                      | Callback when selection changes               |
+| options            | T[]                       | -                      | Array of options                              |
+| optionLabel        | string                    | `"label"`              | Property name for option label                |
+| optionValue        | string                    | `"value"`              | Property name for option value                |
+| optionDisabled     | string                    | -                      | Property name for disabled flag on options    |
+| placeholder        | string                    | `"Select"`             | Placeholder when no value selected            |
+| filter             | boolean                   | false                  | Enable search filter in the overlay           |
+| editable           | boolean                   | false                  | Allow typing in the trigger to filter/select  |
+| onEditEnd          | (e: EditEndEvent) => void | -                      | Fired when Enter is pressed in editable mode  |
+| multiple           | boolean                   | false                  | Allow multiple selection                      |
+| display            | `'comma' \| 'chip'`       | `'comma'`              | Multi-select trigger display mode             |
+| maxSelectedLabels  | number                    | -                      | Max chips before showing `selectedItemsLabel` |
+| selectedItemsLabel | string                    | `'{0} items selected'` | Overflow label; `{0}` = count                 |
+| removeIcon         | ReactNode                 | -                      | Custom icon for chip remove buttons           |
+| label              | ReactNode                 | -                      | Label text above the trigger                  |
+| error              | ReactNode                 | -                      | Error text displayed below the trigger        |
+| required           | boolean                   | false                  | Shows asterisk on label                       |
+| inputId            | string                    | -                      | id for the trigger (for label association)    |
+| disabled           | boolean                   | false                  | Whether the dropdown is disabled              |
+| valueTemplate      | (option) => ReactNode     | -                      | Custom render for selected value in trigger   |
+| itemTemplate       | (option) => ReactNode     | -                      | Custom render for each option in the list     |
+| className          | string                    | -                      | Additional CSS class for the root             |
+| panelClassName     | string                    | -                      | Additional CSS class for the overlay panel    |
+| data-testid        | string                    | -                      | Test ID for root, trigger, panel, and options |
 
 ### SelectButton
 
@@ -252,6 +499,70 @@ const options = [
 | className      | string                   | -       | Additional CSS class                    |
 | data-testid    | string                   | -       | Test ID for root and option buttons     |
 
+### RadioButton
+
+Single-choice selection using native `input[type="radio"]`. API inspired by [PrimeReact RadioButton](https://primereact.org/radiobutton/). Compose multiple `RadioButton` instances with the same `name` to form a group.
+
+```tsx
+import { useState } from 'react'
+import { RadioButton } from '@emporix/component-library'
+
+function ContentTypePicker() {
+  const [contentType, setContentType] = useState('standard')
+
+  return (
+    <div style={{ display: 'flex', gap: '1.5rem' }}>
+      <RadioButton
+        name='content-type'
+        inputId='content-standard'
+        value='standard'
+        label='Standard'
+        checked={contentType === 'standard'}
+        onChange={e => setContentType(String(e.value))}
+      />
+      <RadioButton
+        name='content-type'
+        inputId='content-templates'
+        value='templates'
+        label='Templates'
+        checked={contentType === 'templates'}
+        onChange={e => setContentType(String(e.value))}
+      />
+      <RadioButton
+        name='content-type'
+        inputId='content-service'
+        value='service'
+        label='Service'
+        checked={contentType === 'service'}
+        onChange={e => setContentType(String(e.value))}
+      />
+      <RadioButton
+        name='content-type'
+        inputId='content-vendor'
+        value='vendor'
+        label='Vendor'
+        checked={contentType === 'vendor'}
+        onChange={e => setContentType(String(e.value))}
+      />
+    </div>
+  )
+}
+```
+
+#### Props
+
+| Prop        | Type                     | Default | Description                                              |
+| ----------- | ------------------------ | ------- | -------------------------------------------------------- |
+| inputId     | string                   | -       | id for the native input (auto-generated if omitted)      |
+| name        | string                   | -       | Shared name for radios in the same group (required)      |
+| value       | unknown                  | -       | Value of this radio option                               |
+| checked     | boolean                  | false   | Whether this option is selected (controlled)             |
+| onChange    | (e: ChangeEvent) => void | -       | Callback when selected; `e.value` is this option's value |
+| disabled    | boolean                  | false   | Whether the radio is disabled                            |
+| label       | ReactNode                | -       | Optional label beside the control                        |
+| className   | string                   | -       | Additional CSS class for the root                        |
+| data-testid | string                   | -       | Test ID for root and input                               |
+
 ### Tabs
 
 A flexible tabs component for organizing content into multiple panels.
@@ -307,6 +618,35 @@ const tabs: TabItem[] = [
 | label   | string    | Display label for the tab      |
 | content | ReactNode | Content to display when active |
 
+### Menu
+
+Popup and inline action menus. Wraps [PrimeReact Menu](https://primereact.org/menu/) with scoped Emporix styles.
+
+```tsx
+import { useRef } from 'react'
+import { Menu, type MenuRef, PrimaryButton } from '@emporix/component-library'
+
+function RowActionsMenu() {
+  const menuRef = useRef<MenuRef>(null)
+
+  return (
+    <>
+      <PrimaryButton onClick={e => menuRef.current?.toggle(e)}>
+        Actions
+      </PrimaryButton>
+      <Menu
+        ref={menuRef}
+        popup
+        model={[
+          { label: 'Edit', command: () => onEdit() },
+          { label: 'Delete', disabled: true },
+        ]}
+      />
+    </>
+  )
+}
+```
+
 ### Tooltip
 
 Floating overlays on hover or focus, similar to [PrimeReact Tooltip](https://primereact.org/tooltip/). Use **children mode** to wrap a button, input, or other component, or **selector mode** with a CSS `target` and `data-pr-tooltip` / `data-pr-position` on matching elements.
@@ -356,6 +696,43 @@ import { Tooltip } from '@emporix/component-library'
 
 Selector targets can override position per element with `data-pr-position`. Escape closes the tooltip.
 
+### Message
+
+Inline alert banners for contextual feedback, similar to [PrimeReact Message](https://primereact.org/message/). Use `text` for plain copy or `children` for richer content. Default severity icons come from `react-icons`.
+
+```tsx
+import { Message } from '@emporix/component-library'
+
+// Predefined entity warning (management-dashboard pattern)
+{isPredefined && (
+  <Message
+    severity="info"
+    text="This group is predefined and cannot be modified."
+  />
+)}
+
+// Other severities
+<Message severity="success" text="Your changes were saved." />
+<Message severity="warn" text="Review settings before continuing." />
+<Message severity="error" text="Unable to complete the request." />
+
+// Rich content
+<Message severity="info">
+  <strong>Note:</strong> editing is disabled for system groups.
+</Message>
+```
+
+#### Props
+
+| Prop        | Type                                     | Default | Description                                     |
+| ----------- | ---------------------------------------- | ------- | ----------------------------------------------- |
+| severity    | `info` \| `success` \| `warn` \| `error` | `info`  | Visual severity of the banner                   |
+| text        | string                                   | -       | Plain text content; ignored when `children` set |
+| children    | ReactNode                                | -       | Rich message body                               |
+| icon        | ReactNode                                | -       | Custom icon; default icon shown per severity    |
+| className   | string                                   | -       | Additional CSS class on the root element        |
+| data-testid | string                                   | -       | Test ID for testing                             |
+
 ### Accordion
 
 Collapsible content panels grouped in tabs.
@@ -485,7 +862,7 @@ The component library provides a minimal set of CSS variables that are actually
 
 #### Focus Ring
 
-Reusable focus outline for inputs, dropdowns, SelectButton, etc. Override to change focus appearance globally.
+Reusable focus outline for inputs, dropdowns, SelectButton, RadioButton, etc. Override to change focus appearance globally.
 
 ```css
 --focus-ring-box-shadow: 0 0 0 2px rgba(38, 101, 183, 0.35);
@@ -498,6 +875,23 @@ Reusable focus outline for inputs, dropdowns, SelectButton, etc. Override to cha
 --color-tooltip-text: #ffffff;
 ```
 
+#### Message
+
+```css
+--color-message-info-bg: #e9e9ff;
+--color-message-info-border: #696cff;
+--color-message-info-icon: #696cff;
+--color-message-success-bg: #e4f8f0;
+--color-message-success-border: #1ea97c;
+--color-message-success-icon: #1ea97c;
+--color-message-warn-bg: #fff2e2;
+--color-message-warn-border: #cc8925;
+--color-message-warn-icon: #cc8925;
+--color-message-error-bg: #ffe7e6;
+--color-message-error-border: #ff5757;
+--color-message-error-icon: #ff5757;
+```
+
 #### Spacing
 
 ```css
@@ -611,6 +1005,7 @@ npm run storybook
 - `npm run test:coverage` - Run tests with coverage
 - `npm run storybook` - Start Storybook
 - `npm run build-storybook` - Build Storybook
+- `npm run build:pages` - Build showcase and Storybook for GitHub Pages
 - `npm run lint` - Run ESLint
 - `npm run lint:fix` - Fix ESLint issues
 - `npm run type-check` - Run TypeScript type checking
@@ -660,6 +1055,54 @@ The build output includes:
 - TypeScript declarations (`index.d.ts`)
 - CSS styles (`styles.css`)
 
+## Publishing
+
+Releases are automated via GitHub Actions when you push a version tag. Pushing a tag triggers:
+
+1. **npm publish** — builds the library (`npm run build:lib`) and publishes `@emporix/component-library` to the npm registry
+2. **GitHub Pages** — builds the showcase app (`npm run dev`) and static Storybook, then deploys both sites
+
+### Live sites
+
+After a successful release:
+
+| Site               | URL                                                    |
+| ------------------ | ------------------------------------------------------ |
+| Showcase (dev app) | https://emporix.github.io/component-library/           |
+| Storybook          | https://emporix.github.io/component-library/storybook/ |
+
+### One-time setup
+
+In the GitHub repository, go to **Settings → Pages** and set **Source** to **GitHub Actions**.
+
+npm publishing uses [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — ensure the npm package is configured to trust this repository’s `publish.yml` workflow.
+
+### Release steps
+
+1. **Bump the version** in `package.json` (and `package-lock.json` via `npm install` if needed):
+   - **Minor** (`1.7.1` → `1.8.0`) for backward-compatible features
+   - **Major** (`1.7.1` → `2.0.0`) for breaking changes
+   - **Patch** (`1.7.1` → `1.7.2`) for bug fixes only
+2. **Merge** the version bump to the default branch.
+3. **Create and push a tag** that matches `package.json` exactly (prefix with `v`):
+
+```bash
+# Example: package.json version is 1.10.0
+git tag v1.10.0
+git push origin v1.10.0
+```
+
+The tag must match the format `v{semver}` (e.g. `v1.2.3`). CI rejects tags that do not match `package.json`.
+
+### Preview GitHub Pages locally
+
+```bash
+npm run build:pages
+npx serve gh-pages
+```
+
+Open http://localhost:3000/component-library/ (showcase) and http://localhost:3000/component-library/storybook/ (Storybook).
+
 ## Code Formatting
 
 This project uses Prettier for consistent code formatting. The configuration is defined in `.prettierrc`.
@@ -674,6 +1117,72 @@ npm run format:check
 
 The project also includes pre-commit hooks that automatically format staged files before commits.
 
+## Migrating components from management-dashboard (Cursor skill)
+
+This repository includes a **Cursor Agent Skill** that guides extracting shared UI from [management-dashboard](https://github.com/emporix/management-dashboard) into `@emporix/component-library`. It covers audits, implementation patterns, CSS encapsulation, MD thin wrappers, tests, and rollout.
+
+**Skill location:** [`.cursor/skills/migrate-to-component-library/`](.cursor/skills/migrate-to-component-library/)
+
+| File                                                                       | Purpose                                                                    |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [`SKILL.md`](.cursor/skills/migrate-to-component-library/SKILL.md)         | Step-by-step workflow (phases, checklists, anti-patterns)                  |
+| [`reference.md`](.cursor/skills/migrate-to-component-library/reference.md) | Code templates, token mapping, Jira ticket outline, verification checklist |
+
+Related Cursor rules: [`.cursor/rules/component-development.mdc`](.cursor/rules/component-development.mdc), [`.cursor/rules/version-bump-for-features.mdc`](.cursor/rules/version-bump-for-features.mdc).
+
+### When to use it
+
+Use the skill when you:
+
+- Move or extract a component from management-dashboard into this library
+- Migrate PrimeReact-based MD components (e.g. tables, dialogs) with scoped styles
+- Work on [COP-5597 MD Modularization](https://emporix.atlassian.net/browse/COP-5597) stories
+
+**Reference migration:** `DataTable` (from MD `MdDataTable`) — library export is `DataTable`; MD keeps the existing `MdDataTable` implementation unchanged. Pilot screens import `DataTable` directly from `@emporix/component-library` (or use a thin `Md*` wrapper if preferred).
+
+### How to invoke the skill in Cursor
+
+**Option 1 — Mention the skill in chat (recommended)**
+
+```
+Migrate [ComponentName] from management-dashboard to component-library
+using the migrate-to-component-library skill.
+```
+
+**Option 2 — Reference by name**
+
+Ask Cursor to read and follow `migrate-to-component-library` before starting the task.
+
+**Option 3 — Explicit file reference**
+
+```
+Follow .cursor/skills/migrate-to-component-library/SKILL.md to migrate X.
+```
+
+Cursor loads the skill automatically when your request matches its description (component extraction, MD → library migration, COP modularization).
+
+### What the skill walks you through
+
+1. **Audit** — find consumers, related SCSS, and PrimeReact dependencies in MD
+2. **Ask you to choose a pattern** (required before any implementation)
+   - **Pattern A (custom):** boilerplate + SCSS modules + **same API as PrimeReact** — e.g. `Dropdown`, `InputText`, `SelectButton` (no `primereact` dependency)
+   - **Pattern B (PrimeReact wrapper):** encapsulated `primereact/*` + scoped overrides — e.g. `Toast`, `DataTable`
+3. **Implement in component-library** — component folder, tests, Storybook, exports, version bump
+4. **Wire consumer app** — import library component directly in pilot views **or** add a thin `Md*` wrapper; leave existing `Md*` unchanged for unmigrated screens; import `@emporix/component-library/styles`
+5. **Verify** — `npm run lint`, `npm run test -- --run`, `npm run build:lib` (library); build and manual QA in MD
+
+See [`reference.md`](.cursor/skills/migrate-to-component-library/reference.md) for copy-paste templates (`MdDataTable.tsx` wrapper, `PrimeDataTableOverrides.module.scss`, Jira acceptance criteria).
+
+### Naming convention (library vs MD)
+
+| Layer                   | Name                                    | Example                                                                |
+| ----------------------- | --------------------------------------- | ---------------------------------------------------------------------- |
+| Component library       | Generic, reusable name                  | `DataTable`, `PrimaryButton`                                           |
+| Consumer app (existing) | Keep original `Md*` component unchanged | `MdDataTable` (legacy implementation)                                  |
+| Consumer app (pilot)    | Direct library import or thin wrapper   | `import { DataTable } from '@emporix/component-library'` in pilot view |
+
+This keeps existing import paths stable (`import MdDataTable from 'components/MdDataTable'`) while pilot screens opt in via direct library import or an optional wrapper.
+
 ## Contributing
 
 1. Fork the repository

package/dist/components/autocomplete/AutoComplete.d.ts

@@ -0,0 +1,40 @@
+import { default as React } from 'react';
+export interface AutoCompleteCompleteEvent {
+    query: string;
+}
+export interface AutoCompleteChangeEvent {
+    value: string;
+    originalEvent: React.SyntheticEvent;
+}
+export interface AutoCompleteSelectEvent<T> {
+    value: T;
+    originalEvent: React.SyntheticEvent;
+}
+export interface AutoCompleteProps<T extends Record<string, unknown>> {
+    /** Display text in the input (controlled). */
+    value: string;
+    /** Suggestion list from the parent (updated via completeMethod). */
+    suggestions: T[];
+    /** Called when the user types; parent should fetch/filter suggestions. */
+    completeMethod: (e: AutoCompleteCompleteEvent) => void;
+    /** Property on suggestion objects used for display (default: first string field). */
+    field?: keyof T | string;
+    /** Fired when the input text changes. */
+    onChange: (e: AutoCompleteChangeEvent) => void;
+    /** Fired when a suggestion is selected. */
+    onSelect?: (e: AutoCompleteSelectEvent<T>) => void;
+    /** Show dropdown button to open suggestions. */
+    dropdown?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    label?: React.ReactNode;
+    error?: React.ReactNode;
+    className?: string;
+    inputId?: string;
+    'data-testid'?: string;
+}
+export declare const AutoComplete: {
+    <T extends Record<string, unknown>>({ value, suggestions, completeMethod, field, onChange, onSelect, dropdown, disabled, placeholder, label, error, className, inputId: inputIdProp, "data-testid": testId, }: AutoCompleteProps<T>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+//# sourceMappingURL=AutoComplete.d.ts.map