@idds/react 1.6.20 → 1.6.22

package/AGENT.md

@@ -0,0 +1,444 @@
+# INA Digital Design System (IDDS) - React Comprehensive Agent Manual
+
+This manual provides complete documentation for AI Coding Agents (such as GitHub Copilot, Cursor, Claude, Gemini) and human developers implementing `@idds/react` components. It outlines every available component, its complete set of React props, allowed parameter values, and clear usage patterns.
+
+---
+
+## Core Setup & Global Integration
+
+### 1. Stylesheet Registration
+The application MUST import the global stylesheet once at the application's top-level entry file (e.g., `main.tsx`, `App.tsx`, or `layout.tsx`):
+```tsx
+import '@idds/react/index.css';
+```
+
+### 2. Component Import Rules
+Always import components using standard named imports directly from the package root:
+```tsx
+import { Button, TextField, Modal, SelectDropdown } from '@idds/react';
+```
+
+---
+
+## Exhaustive Component Reference
+
+### 1. Layout, Indicators & Generic Containers
+
+#### `Button`
+Trigger component supporting leading/trailing slots and multiple interaction hierarchies.
+- **Props**:
+  - `hierarchy`: `'primary' | 'secondary' | 'tertiary' | 'link' | 'custom'` (Default: `'primary'`)
+  - `size`: `'2xl' | 'xl' | 'lg' | 'md' | 'sm'` (Default: `'md'`)
+  - `prefixIcon`: `ReactNode` (Optional leading icon)
+  - `suffixIcon`: `ReactNode` (Optional trailing icon)
+  - `disabled`: `boolean` (Default: `false`)
+  - `className`: `string`
+  - Inherits standard `ButtonHTMLAttributes<HTMLButtonElement>` (`onClick`, `type`, etc.)
+- **Usage**:
+  ```tsx
+  <Button hierarchy="primary" size="lg" onClick={() => handleSubmit()}>
+    Simpan Data
+  </Button>
+  ```
+
+#### `ButtonGroup`
+Groups multiple consecutive buttons into a unified border-radius strip.
+- **Props**:
+  - `children`: `ReactNode` containing `<Button>` instances.
+  - `className`: `string`
+- **Usage**:
+  ```tsx
+  <ButtonGroup>
+    <Button hierarchy="secondary">Kiri</Button>
+    <Button hierarchy="secondary">Tengah</Button>
+    <Button hierarchy="primary">Kanan</Button>
+  </ButtonGroup>
+  ```
+
+#### `Card`
+Standardized container structure with consistent surface shadow and background layout.
+- **Props**:
+  - `children`: `ReactNode`
+  - `className`: `string`
+  - `onClick`: `() => void`
+- **Usage**:
+  ```tsx
+  <Card className="p-4 border border-stroke-primary">
+    <h3>Judul Kartu</h3>
+  </Card>
+  ```
+
+#### `CardPlain`
+Minimalist unstyled semantic container wrapper.
+- **Props**: `children`: `ReactNode`, `className`: `string`
+
+#### `Divider`
+Horizontal or vertical semantic line break separator.
+- **Props**:
+  - `orientation`: `'horizontal' | 'vertical'` (Default: `'horizontal'`)
+  - `className`: `string`
+
+#### `Skeleton`
+Placeholder state element shown during loading pipelines.
+- **Props**:
+  - `variant`: `'circular' | 'rectangular' | 'rounded'` (Default: `'rounded'`)
+  - `width`: `string | number`
+  - `height`: `string | number`
+  - `className`: `string`
+- **Usage**:
+  ```tsx
+  <Skeleton variant="rounded" height={40} width="100%" />
+  ```
+
+#### `Spinner`
+Indeterminate circular graphical loading indicator.
+- **Props**:
+  - `size`: `'sm' | 'md' | 'lg'` (Default: `'md'`)
+  - `color`: `string` (Optional custom CSS color override)
+  - `className`: `string`
+
+#### `Avatar`
+Displays profile thumbnail representation.
+- **Props**:
+  - `src`: `string` (Image URL)
+  - `alt`: `string`
+  - `size`: `'sm' | 'md' | 'lg' | 'xl'` (Default: `'md'`)
+  - `fallbackText`: `string` (Initials shown if image fails/empty)
+- **Usage**:
+  ```tsx
+  <Avatar src="/path/img.png" fallbackText="JD" size="lg" />
+  ```
+
+#### `Badge`
+Contextual status tag indicator.
+- **Props**:
+  - `text`: `string | ReactNode`
+  - `variant`: `'success' | 'danger' | 'warning' | 'info' | 'neutral'` (Default: `'neutral'`)
+  - `type`: `'solid' | 'soft' | 'outline'` (Default: `'soft'`)
+  - `icon`: `ReactNode` (Optional icon placement)
+  - `className`: `string`
+- **Usage**:
+  ```tsx
+  <Badge text="Selesai" variant="success" type="solid" />
+  ```
+
+#### `CircleProgressBar`
+Radial circular progression tracking interface.
+- **Props**:
+  - `progress`: `number` (Percentage 0 to 100)
+  - `size`: `number` (Pixel radius)
+  - `strokeWidth`: `number`
+  - `showLabel`: `boolean` (Default: `true`)
+
+#### `ProgressBar` / `LinearProgressIndicator` / `TableProgressBar`
+Horizontal bar progress displays.
+- **Props**:
+  - `progress`: `number` (0 to 100)
+  - `status`: `'default' | 'success' | 'error'`
+  - `className`: `string`
+
+---
+
+### 2. Form Inputs (Controlled Pattern)
+
+#### `TextField`
+Standard robust input supporting debounce and direct clear logic.
+- **Props**:
+  - `value`: `string` (Required controlled binding)
+  - `onChange`: `(val: string) => void`
+  - `onInput`: `(event: ChangeEvent<HTMLInputElement>) => void`
+  - `debounce`: `number` (Delay ms. Default: `0`)
+  - `onChangeDebounced`: `(val: string) => void`
+  - `label`: `ReactNode`
+  - `placeholder`: `string`
+  - `helperText`: `ReactNode`
+  - `errorMessage`: `string`
+  - `status`: `'neutral' | 'error' | 'warning' | 'success'` (Default: `'neutral'`)
+  - `statusMessage`: `ReactNode` (Overrides helperText based on state)
+  - `size`: `'sm' | 'md' | 'lg'` (Default: `'md'`)
+  - `maxLength`: `number`
+  - `showCharCount`: `boolean` (Default: `false`)
+  - `showClearButton`: `boolean` (Default: `true`)
+  - `onClear`: `() => void` (Custom clear action trigger)
+  - `disabled`: `boolean`
+  - `securityConfig`: `SecurityConfig` object
+- **Usage**:
+  ```tsx
+  <TextField
+    label="Nama Lengkap"
+    value={name}
+    onChange={(val) => setName(val)}
+    status={error ? 'error' : 'neutral'}
+    statusMessage={error ? 'Nama wajib diisi' : undefined}
+    showClearButton
+  />
+  ```
+
+#### `TextArea`
+Adjustable multi-line text input field.
+- **Props**:
+  - `value`: `string`
+  - `onChange`: `(val: string) => void`
+  - `label`, `placeholder`, `helperText`: `ReactNode`
+  - `status`: `'neutral' | 'error' | 'warning' | 'success'`
+  - `rows`: `number` (Default: `4`)
+  - `maxLength`: `number`
+  - `showCharCount`: `boolean`
+  - `disabled`: `boolean`
+
+#### `PasswordInput`
+Input field embedding masked string views with instant reveal toggle.
+- **Props**: Identical base pattern to `TextField` minus irrelevant multi-line scopes. Includes accessible visibility toggle button.
+
+#### `InputSearch`
+Search bar optimized for quick search entries and reset triggers.
+- **Props**: Identical to `TextField`, rendering leading search glass graphic automatically.
+
+#### `PhoneInput`
+Structured field featuring international formatting and dial codes.
+- **Props**:
+  - `value`: `string`
+  - `onChange`: `(val: string) => void`
+  - `defaultCountry`: `string` (e.g., `'ID'`)
+  - `disabled`: `boolean`
+  - Includes space/enter accessibility bindings on embedded clear controls.
+
+#### `Checkbox`
+Single option boolean toggler.
+- **Props**:
+  - `checked`: `boolean`
+  - `onChange`: `(checked: boolean) => void`
+  - `label`: `ReactNode`
+  - `disabled`: `boolean`
+  - `indeterminate`: `boolean`
+- **Usage**:
+  ```tsx
+  <Checkbox checked={agree} onChange={(c) => setAgree(c)} label="Setuju syarat" />
+  ```
+
+#### `RadioInput`
+Selection input targeting array groups.
+- **Props**:
+  - `options`: `Array<{ label: string; value: string | number; disabled?: boolean }>`
+  - `value`: `string | number`
+  - `onChange`: `(val: string | number) => void`
+  - `orientation`: `'horizontal' | 'vertical'`
+  - `label`: `ReactNode`
+  - `disabled`: `boolean`
+
+#### `Toggle`
+Switch boolean state toggler.
+- **Props**: `checked`: `boolean`, `onChange`: `(checked: boolean) => void`, `label`: `ReactNode`, `disabled`: `boolean`.
+
+#### `OneTimePassword`
+Multi-segmented input field grouping code entries securely.
+- **Props**:
+  - `length`: `number` (Default: `6`)
+  - `value`: `string`
+  - `onChange`: `(val: string) => void`
+  - `onComplete`: `(val: string) => void`
+  - `disabled`: `boolean`
+
+---
+
+### 3. Selection, Pickers & Uploading
+
+#### `SelectDropdown`
+Robust feature-rich dropdown layout encapsulating remote load/search.
+- **Props**:
+  - `options`: `Array<{ label: string; value: any; disabled?: boolean }>`
+  - `selected`: `any | any[]`
+  - `onSelect`: `(selectedValue: any | any[], rawValue?: any) => void`
+  - `placeholder`: `string`
+  - `size`: `'sm' | 'md' | 'lg'`
+  - `multiple`: `boolean` (Default: `false`)
+  - `indicator`: `'check' | 'radio'`
+  - `width`: `number | string` (Default: `'100%'`)
+  - `panelWidth`, `panelHeight`: `number | string`
+  - `searchable`: `boolean` (Default: `true`)
+  - `onSearch`: `(term: string) => void`
+  - `hasMore`, `loading`: `boolean` (Infinite scrolling flags)
+  - `onLoadMore`: `(page: number) => void`
+  - `mandatorySelected`: `boolean` (Ensures at least one item remains locked/selected)
+- **Usage**:
+  ```tsx
+  <SelectDropdown
+    options={[{ label: 'Opsi 1', value: 1 }, { label: 'Opsi 2', value: 2 }]}
+    selected={selectedItem}
+    onSelect={(val) => setSelectedItem(val)}
+    mandatorySelected
+  />
+  ```
+
+#### `ActionDropdown` / `BasicDropdown`
+Trigger buttons exhibiting contextual menu floating lists.
+- **Props**:
+  - `items`: `Array<{ label: ReactNode; onClick: () => void; icon?: ReactNode; disabled?: boolean }>`
+  - `triggerLabel`: `ReactNode`
+
+#### `Chip`
+Tags optimized for multi-select context filters.
+- **Props**:
+  - `label`: `string`
+  - `selected`: `boolean`
+  - `onClick`: `() => void`
+  - `onRemove`: `() => void`
+  - `multiple`: `boolean`
+  - `disabled`: `boolean`
+- Supports keyboard roving focus and deselect actions.
+
+#### `MultipleChoiceGrid`
+Grid map arrangement wrapper for multi-option mapping.
+- **Props**: `options`: `Array`, `selectedValues`: `Array`, `onChange`: `(arr) => void`
+
+#### `DatePicker`
+Interactive date selector supporting fluid input layers.
+- **Props**:
+  - `mode`: `'single' | 'range' | 'multiple'` (Default: `'single'`)
+  - `selected`: `Date | [Date | null, Date | null] | Date[] | null`
+  - `onChange`: `(date: any) => void`
+  - `placeholder`: `string`
+  - `disabled`: `boolean`
+  - `minDate`, `maxDate`: `Date`
+- **Usage**:
+  ```tsx
+  <DatePicker selected={date} onChange={(d) => setDate(d)} mode="single" />
+  ```
+
+#### `MonthPicker` / `YearPicker`
+Granular rapid timeframe scoping drillers.
+- **Props**: `selected`: `number | string`, `onChange`: `(val) => void`, `minYear`/`maxYear`
+
+#### `TimePicker`
+Time tracking inputs.
+- **Props**:
+  - `value`: `string` (Format: `'HH:mm'` or `'HH:mm:ss'`)
+  - `onChange`: `(val: string) => void`
+  - Fully embeds auto-formatting logic (injecting `:` automatically during manual text entries). Includes accessible Space/Enter trigger handling on reset icons.
+
+#### `FileUpload` / `SingleFileUpload`
+Drag-and-drop structural media file upload blocks.
+- **Props**:
+  - `onFilesSelected`: `(files: File[]) => void` (or `File` for single)
+  - `maxSize`: `number` (Bytes limit)
+  - `acceptedFormats`: `string` (e.g., `'.pdf, .jpg, .png'`)
+  - `disabled`: `boolean`
+
+---
+
+### 4. Navigation, View Structures & Feedback
+
+#### `Accordion` / `AccordionGroup` / `AccordionCard`
+Expandable structural stack containers.
+- **Props**:
+  - `title`: `ReactNode`
+  - `children`: `ReactNode`
+  - `defaultExpanded`: `boolean`
+  - Fully navigable using Keyboard Arrow keys.
+
+#### `Breadcrumb`
+Path trailing step indicator interfaces.
+- **Props**:
+  - `items`: `Array<{ label: string; href?: string; onClick?: () => void }>`
+- **Usage**:
+  ```tsx
+  <Breadcrumb
+    items={[
+      { label: 'Beranda', onClick: () => navigate('/') },
+      { label: 'Formulir' }
+    ]}
+  />
+  ```
+
+#### `TabHorizontal` / `TabVertical`
+Tab structures managing context sub-views smoothly.
+- **Props**:
+  - `tabs`: `Array<{ id: string; label: ReactNode; content?: ReactNode; disabled?: boolean }>`
+  - `activeTab`: `string`
+  - `onChange`: `(tabId: string) => void`
+
+#### `Pagination`
+Data listing page controller.
+- **Props**:
+  - `currentPage`: `number`
+  - `totalPages`: `number`
+  - `onPageChange`: `(page: number) => void`
+
+#### `Stepper`
+Workflow progress milestone tracks.
+- **Props**: `steps`: `Array<{ label: string; description?: string }>`, `activeStep`: `number`
+
+#### `Table` / `FieldInputTable`
+High fidelity complex layout grids supporting responsive dimensions.
+- **Props**:
+  - `columns`: `Array<{ header: ReactNode; accessor: string; width?: string | number; className?: string }>`
+  - `data`: `Array<Record<string, any>>`
+
+#### `Modal`
+Portal accessible overlay interface containing automated flex overflow features.
+- **Props**:
+  - `open`: `boolean`
+  - `onClose`: `() => void`
+  - `title`: `ReactNode`
+  - `children`: `ReactNode`
+  - `size`: `'sm' | 'md' | 'lg' | 'xl' | 'full' | ''`
+  - `hideHeader`: `boolean` (Default: `false`)
+  - `closeOnBackdrop`: `boolean` (Default: `true`)
+- **Usage**:
+  ```tsx
+  <Modal open={isOpen} onClose={() => setIsOpen(false)} title="Peringatan" size="md">
+    <p>Apakah Anda yakin ingin menghapus data ini?</p>
+  </Modal>
+  ```
+
+#### `Drawer` / `BottomSheet`
+Side and bottom sliding dynamic responsive panels.
+- **Props**: `open`: `boolean`, `onClose`: `() => void`, `placement`: `'left' | 'right'` (Drawer)
+
+#### `Collapse`
+Smooth transition container wrapper hiding sub-DOM nodes.
+- **Props**: `isOpen`: `boolean`, `children`: `ReactNode`
+
+#### `Tooltip`
+Floating informational cues.
+- **Props**:
+  - `content`: `ReactNode`
+  - `children`: `ReactElement`
+  - `placement`: Supports 12 distinct positions (`'top-start'`, `'top'`, `'top-end'`, `'bottom-start'`, `'bottom'`, `'bottom-end'`, `'left-start'`, `'left'`, `'left-end'`, `'right-start'`, `'right'`, `'right-end'`)
+
+#### `Toast` / `ToastProvider`
+Contextual non-blocking messaging API.
+- **Usage**:
+  Ensure application wraps top layers inside `<ToastProvider>`. Trigger messages directly using the internal context hook:
+  ```tsx
+  import { useToast } from '@idds/react';
+
+  function Child() {
+    const { toast } = useToast();
+    return (
+      <button onClick={() => toast({ state: 'positive', title: 'Sukses', description: 'Tersimpan' })}>
+        Kirim
+      </button>
+    );
+  }
+  ```
+
+#### `Alert`
+Static informative view strip.
+- **Props**: `state`: `'info' | 'positive' | 'warning' | 'destructive'`, `title`: `string`, `description`: `ReactNode`
+
+#### `ThemeToggle`
+Out-of-the-box UI widget switching global light/dark layouts automatically.
+
+---
+
+## Global Theme Commands
+IDDS reads the root HTML document `[data-theme]` parameter securely.
+- Access available runtime toggle commands:
+  ```typescript
+  import { setThemeMode, getThemeMode, toggleThemeMode } from '@idds/react';
+  ```
+
+## AI Implementor Guidelines
+1. **Rely strictly on provided design props** (e.g., `status="error"`, `variant="danger"`). Do not attempt to inject custom CSS classes modifying border frames or colors manually.
+2. **Accessible inputs**: Prefer setting native form helpers via the `errorMessage` property directly to guarantee proper ARIA screen reader link indices.