injast-core 1.0.80 → 1.0.81

package/guidelines/Guidelines.md

@@ -2,24 +2,27 @@
 
 ## Product Character
 
-Injast Core is an RTL-first React and Material UI design system for Persian product interfaces. Build calm, practical application screens with clear hierarchy, compact spacing, and predictable form and data workflows.
+Injast Core is an RTL-first React and Material UI design system for Persian product interfaces. Generated screens should feel like focused product UI: mobile-first, operational, compact, and easy to scan repeatedly.
 
-- Use `injast-core` components before raw HTML or direct Material UI components.
-- Use RTL by default unless the user explicitly asks for LTR.
-- Use Persian-friendly labels and layout direction when content is Persian.
-- Keep layouts dense enough for operational use, but preserve breathing room around forms, dialogs, tables, and decision points.
-- Use brand color for primary actions and active states, not large decorative backgrounds.
+- Build Persian and RTL experiences by default.
+- Prefer task screens, forms, tables, status feedback, and flows over marketing pages.
+- Keep the main app canvas constrained to `max-width: 550px` with `margin-inline: auto` unless a data-heavy desktop layout clearly needs more width.
+- Use brand color for primary actions and active states only. Do not use strong colors as large decorative backgrounds.
+- Use measured density: compact controls, clear labels, and enough spacing around decisions and errors.
 
 ## Reading Order
 
-Always read these files before writing app code with this package:
+Make must read these files before writing app code with this package:
 
-1. `guidelines/Guidelines.md`
-2. `guidelines/setup.md`
-3. `guidelines/foundations/color.md`
-4. `guidelines/foundations/typography.md`
-5. `guidelines/foundations/spacing.md`
-6. `guidelines/components/overview.md`
+1. `guidelines/Guidelines.md` - product character, routing, and hard rules.
+2. `guidelines/setup.md` - package install, CSS imports, providers, viewport, and icon package.
+3. `guidelines/foundations/color.md` - app colors, semantic palette, and status colors.
+4. `guidelines/foundations/typography.md` - theme typography variants and usage.
+5. `guidelines/foundations/spacing.md` - 4px spacing scale, page shell, padding, gaps, and sizing.
+6. `guidelines/foundations/icons.md` - Iconsax import, sizing, placement, and color rules.
+7. `guidelines/components/overview.md` - component catalog and selection rules.
+8. `guidelines/runtime.md` - hooks, utilities, API helpers, logging, Sentry, and app integration helpers.
+9. `guidelines/types.md` - exported TypeScript types and when to use them.
 
 Read focused component files before using those component groups:
 
@@ -30,6 +33,10 @@ Read focused component files before using those component groups:
 - `guidelines/components/data-display.md`
 - `guidelines/components/date-inputs.md`
 
+Composition and app-shell rules live in `guidelines/components/layout.md`.
+Runtime integration rules live in `guidelines/runtime.md`.
+Type import rules live in `guidelines/types.md`.
+
 ## Package Rules
 
 - Install and import the public package as `injast-core`.
@@ -37,19 +44,25 @@ Read focused component files before using those component groups:
 - Do not import `@alimohammadiwork/injast-core`; that scoped package is not this package.
 - Do not use `@make-kits/injast-core-make-kit` for the public npm package path.
 - For Figma Make and Vite React apps, use `SPAThemeProvider`.
+- For Next.js app providers, use `ThemeProvider`.
+- Wrap generated app content with `MessageProvider` when toast/status feedback is needed.
 - Import `injast-core/fonts.css` once near the app root.
-- Use named imports from `injast-core` for common usage; use subpath imports for focused entrypoints.
+- Use `coreFaIR` in SPA/Figma Make theme options for Persian Material UI localization.
+- Use named imports from `injast-core` for common usage; use subpath imports only for focused entrypoints.
 
-## Component Rules
+## Hard UI Rules
 
-- Use `Button` for actions, not raw `<button>`.
-- Use `TextField`, `NumberInput`, `CardNumberInput`, `OtpInput`, `Select`, `MultiSelect`, `Checkbox`, `RadioGroup`, and `Toggle` for input.
-- Use `Modal` for focused tasks; use `Toast` for brief status feedback.
-- Use `DataGrid` for tabular operational data.
-- Use `Box`, `Container`, and `Grid` for layout.
-- Use `defaultColors` and theme palette values instead of hardcoded colors when possible.
-- Do not guess unsupported component props. Use Material UI props plus the documented Injast-specific props.
+- Use Injast Core components before raw HTML or direct Material UI primitives.
+- Do not use raw `<button>`, `<input>`, `<select>`, checkbox, radio, dialog, table, or image elements when an Injast component exists.
+- Use RTL by default: provider `dir="rtl"`, Persian labels, right-aligned reading flow, and logical CSS properties such as `marginInline` or `px`.
+- Keep the primary app surface centered with `maxWidth: 550` or CSS `max-width: 550px; margin-inline: auto;`.
+- Do not guess unsupported component props. Use Material UI props plus documented Injast-specific props.
+- Use `iconsax-react` for all generated app icons. Do not use Lucide, Heroicons, Font Awesome, inline SVGs, emoji icons, or `@mui/icons-material` in generated screens.
+- Keep icon sizes consistent: 20px for input adornments, 24px for standard actions, 28px for status icons.
+- Use `defaultColors`, `appColors`, and theme palette values instead of hardcoded colors where possible.
+- Keep all controls reachable on mobile. Do not rely on hover-only actions for required workflows.
+- Do not create nested cards unless the inner card is a repeated item, modal content, or a genuinely separate framed tool.
 
 ## Output Expectations
 
-Generated screens should look like production product UI, not a marketing page. Prefer direct task surfaces, clear forms, data tables, status feedback, and navigation patterns that users can scan and operate repeatedly.
+Generated screens should look like production Persian product UI. Favor concise copy, clear hierarchy, stable control sizes, predictable forms, visible validation, compact data displays, and direct recovery actions for empty or error states.

package/guidelines/components/buttons.md

@@ -5,9 +5,10 @@
 Use `Button` for every visible action. It wraps Material UI `Button` and accepts Material UI button props plus Injast-specific sizing and loading props.
 
 ```tsx
+import { Add } from "iconsax-react";
 import { Button } from "injast-core";
 
-<Button variant="contained" color="primary" buttonSize="M">
+<Button variant="contained" color="primary" buttonSize="M" startIcon={<Add size={24} />}>
   ثبت
 </Button>
 ```
@@ -19,25 +20,53 @@ import { Button } from "injast-core";
 | `buttonSize` | `"L" | "M" | "S" | "XS"` | `"M"` | Controls height, radius, and font size |
 | `loading` | `boolean` | `false` | Replaces content with spinner and disables click |
 | `loadingColor` | `string` | `neutral.50` | Spinner color |
-| Material UI `ButtonProps` | varies | - | Use `variant`, `color`, `disabled`, `startIcon`, `endIcon`, `fullWidth` |
+| Material UI `ButtonProps` | varies | - | Use `variant`, `color`, `disabled`, `startIcon`, `endIcon`, `fullWidth`, `onClick`, `type` |
 
 ## Sizing
 
-| Size | Height | Use for |
-|---|---:|---|
-| `L` | 56px | High-emphasis primary actions |
-| `M` | 48px | Default form and page actions |
-| `S` | 40px | Dense toolbars or secondary actions |
-| `XS` | 32px | Compact inline actions |
+| Size | Height | Radius | Font | Use for |
+|---|---:|---:|---:|---|
+| `L` | 56px | 12px | 16px / 700 | High-emphasis primary actions |
+| `M` | 48px | 12px | 16px / 700 | Default form and page actions |
+| `S` | 40px | 8px | 14px / 700 | Dense toolbars or secondary actions |
+| `XS` | 32px | 8px | 12px / 700 | Compact inline actions and modal secondary actions |
+
+Button content uses an 8px icon/text gap. Icons in normal buttons should be 20px to 24px. Large FAB-like actions can use 28px icons.
 
 ## Variant Rules
 
 - Use `variant="contained"` and `color="primary"` for the main action.
 - Use `variant="outlined"` for secondary actions.
-- Use `variant="text"` only for low-emphasis actions.
+- Use `variant="text"` only for low-emphasis actions, inline navigation, or cancel links.
 - Keep one primary contained action per focused region.
-- Use `loading` instead of manually swapping button text.
+- Use `fullWidth` for mobile bottom actions and one-column forms.
+- Use `loading` instead of manually swapping button text or adding a separate spinner.
+- Do not add custom elevation or ripple behavior; the component disables elevation and ripple for a quiet product feel.
+
+## Action Layout
+
+- In RTL modals and drawers, place the primary action at the end of the row when actions are horizontal.
+- Use `gap: 2` between adjacent buttons.
+- Use a fixed bottom action area for long mobile forms when the submit action must stay visible.
+- Use `buttonSize="M"` for the main bottom action and `buttonSize="XS"` or `S` for compact modal footer actions.
+
+## IconButton
+
+Use `IconButton` for compact icon-only controls such as close, remove, edit, calendar, search, and increment/decrement.
+
+Rules:
+
+- Use Iconsax icons only.
+- Give unfamiliar icon-only actions a tooltip or visible adjacent label when context is not obvious.
+- Keep common icon-only targets 40px to 48px. Compact inline controls can be 32px.
+- Do not use text inside `IconButton`.
+
+## Fab
+
+Use `Fab` only for a single prominent floating action in a screen. Do not place multiple FABs in the same view.
 
-## IconButton and Fab
+Sizing:
 
-Use `IconButton` for compact icon-only controls and pair it with a visible label nearby or a tooltip when possible. Use `Fab` only for a single prominent floating action.
+- Small FAB: 20px icon.
+- Default FAB: 24px icon.
+- Large FAB: 28px icon.

package/guidelines/components/data-display.md

@@ -2,7 +2,7 @@
 
 ## DataGrid
 
-Use `DataGrid` for tabular data. It wraps Material React Table with RTL and Persian localization defaults.
+Use `DataGrid` for tabular operational data. It wraps `material-react-table` with RTL and Persian localization defaults.
 
 ```tsx
 import { DataGrid, type MRT_ColumnDef } from "injast-core";
@@ -17,27 +17,65 @@ const columns: MRT_ColumnDef<Row>[] = [
 <DataGrid columns={columns} data={rows} enableSorting />;
 ```
 
+Default behavior and sizing:
+
+| Setting | Default |
+|---|---|
+| Direction | RTL wrapper |
+| Localization | Persian Material React Table localization |
+| Layout mode | `grid` |
+| Density | `compact` |
+| Paper radius | 12px |
+| Table container max height | `calc(100vh - 300px)` |
+| Header background | `neutral.100` equivalent |
+| Header font | 16px / 500 |
+| Body cell font | 14px |
+| Row action minimum width | 160px |
+
 Rules:
 
 - Define stable `columns` outside render or memoize them.
 - Use compact density for operational pages.
 - Use built-in MRT options for sorting, filtering, selection, row actions, and pagination.
 - Keep row actions concise and aligned.
+- Use right alignment for Persian text, center alignment for small status columns, and left or LTR alignment for Latin IDs when necessary.
+- Avoid placing wide `DataGrid` tables inside the 550px mobile shell unless horizontal scrolling is intentional.
 
 ## Typography
 
 Use `Typography` for labels, headings, metadata, and body text. Match text scale to context; do not use display styles inside dense cards or tables.
 
+Rules:
+
+- Use `body1` for primary row/card text.
+- Use `body2` or `label1` for metadata.
+- Use `h2` or `h3` for section titles inside dense app screens.
+
 ## Image
 
 Use `Image` for image content. Always provide useful `alt` text unless the image is decorative.
 
+Sizing:
+
+- `src` is required.
+- Pass explicit `width` and `height`.
+- Default `objectFit` is `cover`.
+- Use `contain` for logos, receipts, cards, and documents that must not crop.
+- `fallbackSrc` exists in the prop type but current runtime fallback handling is not active; do not rely on it for critical broken-image recovery.
+- Use `style` only for image-specific CSS such as border radius or filter, not for page layout.
+
 ## Pagination and Divider
 
 Use `Pagination` when data is split across pages. Use `Divider` to separate adjacent content groups, not as a substitute for spacing.
 
+Rules:
+
+- Keep pagination close to the data it controls.
+- Do not use dividers between every small form field; use gaps first.
+
 ## Empty and Loading States
 
 - Use `Skeleton` when data is loading.
 - Use a concise empty state with one primary recovery action when no data exists.
 - Use `ProgressBar` for determinate progress.
+- Keep empty state copy short and Persian when the app content is Persian.

package/guidelines/components/date-inputs.md

@@ -14,22 +14,57 @@ Use `MobileDatePicker` for Persian calendar date entry in mobile-first or respon
 />
 ```
 
+Behavior and sizing:
+
+| Property | Default or rule |
+|---|---|
+| Width | `100%` |
+| Field height | 48px |
+| Field radius | 8px through `TextField` |
+| Calendar icon | Iconsax `Calendar`, 20px |
+| Date shown to user | Jalali |
+| `onChange` value | Gregorian string |
+| Modal radius | 12px |
+| Modal action buttons | `buttonSize="XS"` |
+
 Rules:
 
-- `onChange` receives the selected date converted to Gregorian format.
 - Use `label`, `placeholder`, `error`, and `helperText` for form clarity.
 - Pass `disabled` when the date cannot be edited.
-- Ensure the app build supports CSS imports from npm packages.
+- Use `minDate` and `maxDate` when the business flow has valid ranges.
+- Use `textFieldSxProps` only for field-level `sx` overrides that cannot be expressed through layout wrappers.
+- Ensure the app build supports CSS imports from npm packages. `MobileDatePicker` uses `react-multi-date-picker`, `react-date-object`, and the Persian calendar/locale internally.
+- Keep date fields full width in the 550px mobile shell.
 
 ## WheelDatePicker
 
-Use `WheelDatePicker` when a drawer-style date picker is more appropriate than the modal calendar.
+Use `WheelDatePicker` when a drawer-style date picker is more appropriate than the modal calendar, especially for touch-heavy flows.
+
+Behavior and sizing:
+
+| Property | Default or rule |
+|---|---|
+| Field height | 48px |
+| Field radius | 8px |
+| Drawer max width | 550px |
+| Drawer horizontal alignment | centered with `mx: "auto"` |
+| Drawer body padding | `px: 3.5`, `py: 6` |
+| Wheel item height | 44px |
+| Visible wheel items | 3 |
+| Confirm action | full-width contained button |
+| Default format | Unix seconds unless `dateFormat` is set |
 
 Rules:
 
-- Prefer it for touch-heavy flows.
-- Keep surrounding form actions clear: cancel and confirm.
-- Use the `onChange` format expected by the receiving form state.
+- Prefer it for mobile bottom-sheet selection.
+- Keep surrounding form actions clear: cancel/close and confirm.
+- Use `title` for the drawer/input label and `placeholder` for empty display text.
+- Use `dateFormat="jalali"` when the form state should store Jalali text.
+- Use `dateFormat="gregorian"` when the form state should store a Gregorian date string.
+- Use `valueFormat` when the incoming `value` format differs from the desired `onChange` format.
+- Use `onChangeDateFormat` when the emitted value format must differ from the incoming `value`.
+- Use `defaultDate` as the initial date when `value` is empty.
+- Use `minDate` and `maxDate` with Unix seconds when the selectable range is constrained.
 
 ## Date Utilities
 
@@ -43,3 +78,9 @@ import {
   longDateFormat,
 } from "injast-core";
 ```
+
+Rules:
+
+- Do not hand-roll Jalali/Gregorian conversions.
+- Keep storage format explicit in component state and API payloads.
+- Display dates in Persian/Jalali format for Persian users unless the product requirement says otherwise.

package/guidelines/components/feedback.md

@@ -20,23 +20,75 @@ Valid severity values:
 - `warning`
 - `error`
 
+Toast sizing and style:
+
+| Property | Default or rule |
+|---|---|
+| Width | `90%` |
+| Alert max width | 450px |
+| Wide minimum width | 350px |
+| Radius | 8px |
+| Horizontal padding | `px: 3.5` (14px) |
+| Vertical padding | `py: 4` (16px) |
+| Status icon | 28px Iconsax `Bold` |
+| Default duration | 4000ms through `MessageProvider` |
+
+Rules:
+
+- Prefer `MessageProvider` and `useMessage` for app-level feedback.
+- Match icon, text, border, and background to severity.
+- Keep toast copy short and actionable.
+- In 550px app shells, keep toasts visually aligned to the centered app surface.
+- Use `anchorOrigin` to change placement; default is top-left.
+- Use `isWide` only for messages that need a wider minimum width.
+- `handleClose` should close the toast and should be safe to call from click or timeout.
+
 ## Modal and Dialog
 
 Use `Modal` for focused tasks, confirmations, and compact forms. Keep modal content short and actionable.
 
 ```tsx
 <Modal open={open} onClose={handleClose} width={420}>
-  <Typography variant="h2">حذف مورد</Typography>
-  <Typography variant="body1">آیا مطمئن هستید؟</Typography>
-  <Button variant="contained" color="primary">تایید</Button>
+  <Box display="grid" gap={4}>
+    <Typography variant="h2">حذف مورد</Typography>
+    <Typography variant="body1">آیا مطمئن هستید؟</Typography>
+    <Box display="flex" gap={2} justifyContent="end">
+      <Button variant="outlined" buttonSize="XS">لغو</Button>
+      <Button variant="contained" color="primary" buttonSize="XS">تایید</Button>
+    </Box>
+  </Box>
 </Modal>
 ```
 
+Modal sizing and style:
+
+- Paper radius: 12px.
+- Paper margin: 8px on small screens.
+- Backdrop: dark translucent blur.
+- Use explicit `width` for compact dialogs, usually 320px to 420px.
+- Use `gap: 4` inside modal content.
+
 Rules:
 
-- Always provide a visible close or cancel path.
+- Always provide a visible close, cancel, or back path.
 - Keep destructive confirmation actions explicit.
 - Avoid putting full pages inside modals.
+- Do not nest cards inside modal content unless they are repeated selectable items.
+
+## Drawers
+
+Use drawers for bottom-sheet-like mobile tasks such as date selection, filters, and short pickers.
+
+Rules:
+
+- Control visibility with `isDrawerOpen`.
+- Use `onClose` for backdrop, escape, and close-button behavior.
+- Default `anchor` is bottom; use `anchor="right"` for RTL side navigation drawers.
+- Align drawer content to the 550px app shell when possible.
+- Use `maxWidth: 550` and `mx: "auto"` for drawer roots or content wrappers.
+- Use `px: 3.5`, `py: 6` for drawer body padding.
+- Put the title and close icon in the header row.
+- Use a full-width contained button for the main confirm action.
 
 ## Loading and Progress
 
@@ -45,3 +97,25 @@ Rules:
 - Use `CircularProgress` inside small controls.
 - Use `Skeleton` for content placeholders.
 - Use `ProgressBar` when progress has a known percentage or status.
+
+Sizing:
+
+- `LoadingModal` content is 150px wide with `gap: 4`.
+- `LoadingModal` opens with `isOpen`.
+- Default progress bar height is 20px.
+- Button loading spinner uses 24px.
+
+ProgressBar props:
+
+- `progress` is the determinate percentage value.
+- `color` controls the filled bar color.
+- `height` defaults to 20px.
+- Use `disablePercentage` when the label would be redundant or cramped.
+- Use `isRtl` when the filled direction should visually flip for RTL progress.
+
+## Empty and Error States
+
+- Keep empty states concise.
+- Provide one primary recovery action when the user can fix the state.
+- Use `danger` colors only for real errors and destructive decisions.
+- Use `warning` for reversible risk or caution, not validation failure.

package/guidelines/components/forms.md

@@ -4,10 +4,13 @@
 
 - Use controlled components for form values.
 - Use `TextField` instead of raw `<input>`.
-- Put labels on every input unless the context is visually obvious.
+- Put labels on every input unless the surrounding context makes the value unmistakable.
 - Use `error` and `helperText` for validation messages.
 - Use 48px control height for default forms.
 - Use RTL layout for Persian forms.
+- Use `gap: 3` to `gap: 4` between related fields.
+- Use `gap: 1` to `gap: 2` between field labels/helper copy and the field.
+- Do not place required fields inside collapsed accordions.
 
 ## TextField
 
@@ -20,17 +23,62 @@
 | `height` | `number` | Explicit field height |
 
 ```tsx
+import { SearchNormal1 } from "iconsax-react";
+import { TextField, defaultColors } from "injast-core";
+
 <TextField
   label="نام"
   value={name}
   onChange={(event) => setName(event.target.value)}
   height={48}
+  startAdornment={<SearchNormal1 size={20} color={defaultColors.neutral.main} />}
+/>
+```
+
+Sizing:
+
+- Default height: 48px.
+- Radius: 8px.
+- Input adornment icon: 20px.
+- Use `fullWidth` in mobile forms and 550px app shells.
+- Use `dir="ltr"` only for Latin codes, OTP, card numbers, phone-like numeric values, or technical identifiers.
+
+## Form Wrappers
+
+Use `FormControl`, `InputLabel`, `MenuItem`, and `FormControlLabel` when composing Material UI-compatible form groups.
+
+Rules:
+
+- Use `FormControl` to bind labels, helper text, and selection controls into one accessible group.
+- Use `InputLabel` with `Select`, `MultiSelect`, or custom field groups that need a floating label.
+- Use `MenuItem` only inside `Select` or menu-like option lists.
+- Use `FormControlLabel` for `Checkbox`, `Radio`, and `Toggle` labels.
+- In RTL forms, use `labelPlacement="start"` when the visual layout needs the control on the trailing side, as in drawer radio lists.
+
+## Autocomplete
+
+Use `Autocomplete` when users choose from a longer list, need search-as-you-type, or may need multiple searchable selections.
+
+```tsx
+<Autocomplete
+  options={options}
+  getOptionLabel={(option) => option.label}
+  renderInput={(params) => (
+    <TextField {...params} label="دسته بندی" height={48} fullWidth />
+  )}
 />
 ```
 
+Rules:
+
+- Render the input with Injast `TextField`.
+- Keep the field 48px tall unless the surrounding UI is intentionally dense.
+- Use `multiple` only when selected values are naturally a set.
+- Prefer `Select` for short static lists and `Autocomplete` for longer or searchable lists.
+
 ## Select and MultiSelect
 
-Use `Select` for a single value and `MultiSelect` for multiple values.
+Use `Select` for one value and `MultiSelect` for multiple values.
 
 ```tsx
 <MultiSelect
@@ -44,15 +92,74 @@ Use `Select` for a single value and `MultiSelect` for multiple values.
 />
 ```
 
+Rules:
+
+- Use 48px height and 8px radius.
+- `MultiSelect` default `minWidth` is `13rem`; override only when the layout needs a tighter or full-width control.
+- MultiSelect chips use a neutral surface, pill radius, `px: 3`, `py: 1.5`, and compact 18px remove icons.
+- Keep option labels short enough to scan in Persian.
+
 ## Boolean Inputs
 
-- Use `Checkbox` for independent form choices.
-- Use `RadioGroup` when the user must choose one option from a short list.
-- Use `Toggle` for settings that take effect as on/off state.
+Use `Checkbox` for independent form choices. The default checkbox icon is 24px with 4px corner radius.
+
+Checkbox customization props:
+
+| Prop | Use for |
+|---|---|
+| `iconSize` | Custom checkbox square size; default is 24px |
+| `borderColor` | Unchecked border color override |
+| `checkedBorderColor` | Checked border color fallback when theme primary is not available |
+| `backgroundColor` | Checked square background override |
+| `tickColor` | Checkmark color fallback when theme primary is not available |
+
+Prefer theme primary and neutral colors before custom checkbox colors.
+
+Use `RadioGroup` when the user must choose one option from a short list. Keep radio labels short and avoid more than 5 options before considering a select.
+
+Use `Toggle` for settings that take effect as an on/off state.
+
+Toggle sizing:
+
+| Size | Track |
+|---|---:|
+| `small` | 48px by 26px |
+| `medium` | 59px by 32px |
+
+Toggle props:
+
+- Use `checked` for controlled on/off state.
+- Use `onChange` to update the controlled value.
+- Use `disabled` when the setting cannot currently change.
+- Use custom `color` only when the theme primary color is not appropriate.
+
+## Slider
+
+Use `Slider` for bounded numeric ranges where dragging is faster than typing.
+
+Rules:
+
+- Always provide `min`, `max`, and `step` when the domain is known.
+- Show the current value in nearby text when precision matters.
+- Use `NumberInput` instead when users need exact manual numeric entry.
+- Keep horizontal sliders at least 240px wide on mobile.
+
+## Phone Input
+
+Use `InputPhoneNumber` for Iranian phone numbers instead of a normal `TextField`.
+
+Rules:
+
+- It normalizes Persian and Arabic numerals to ASCII digits.
+- It accepts `+98`, `0098`, `98`, and 10-digit mobile numbers that start with `9`, then normalizes to a leading `0`.
+- Default `maxDigitLength` is 11.
+- Use `dir="rtl"` by default; use `dir="ltr"` only when the surrounding form needs Latin number alignment.
+- Pass `inputRef` when parent logic needs focus control.
+- Use `onBlur` for touched/validation behavior.
 
 ## Numeric Inputs
 
-Use `NumberInput` for formatted numeric entry. Use `fungible` when decimals are allowed.
+Use `NumberInput` for formatted numeric entry.
 
 ```tsx
 <NumberInput
@@ -63,6 +170,62 @@ Use `NumberInput` for formatted numeric entry. Use `fungible` when decimals are
 />
 ```
 
-Use `CardNumberInput` for bank card numbers; it returns the cleaned digits to `onChange`.
+Rules:
+
+- Use `fungible` when decimals are allowed.
+- `NumberInput` returns the cleaned numeric string to `onChange`.
+- Use `unit` for currency or measurement labels.
+- Use `hasClearButton` only when reset is a useful action.
+- Pair `hasClearButton` with `onReset`.
+- Use `maxLength` and `minLength` when the numeric identifier has length rules.
+- Do not use `type="number"` raw inputs for Persian numeric forms.
+
+## Card and OTP Inputs
+
+Use `CardNumberInput` for Iranian bank card numbers. It displays groups with dashes and returns cleaned digits to `onChange`.
+
+Rules:
+
+- Use `bankLogo` for a 20px bank logo at the start of the field when detected.
+- Use `hasClearButton` only when users often need to reset the field.
+- Pair `hasClearButton` with `onReset`.
+- Keep the visible field RTL context-friendly, but the card number itself behaves as numeric input.
 
 Use `OtpInput` for verification codes, not a normal text field.
+
+OTP sizing:
+
+- Default cell: 54px by 54px.
+- Cell radius: 8px.
+- Cell padding: 8px vertical.
+- Direction: LTR.
+- Text alignment: center.
+- Use 4 or 6 cells depending on the verification flow.
+- Use `focusedBorderColor` to customize the focused cell border.
+- Use `backgroundColor` for a custom cell background only when the product surface requires it.
+- Use the `error` prop to show danger-colored cell borders.
+
+Use `IosHiddenOtpInput` only as an invisible iOS one-time-code autofill bridge beside a visible `OtpInput`. It renders a 1px hidden input, focuses on iOS, normalizes Persian/Arabic digits to Latin digits, and calls `onOtpChange`.
+
+Rules:
+
+- Do not use `IosHiddenOtpInput` as the visible OTP UI.
+- Keep the visible code cells in `OtpInput`.
+- Use it only on client-side screens where `navigator.userAgent` and `document` are available.
+
+## CounterBoxInput
+
+Use `CounterBoxInput` for stepper-like numeric changes where increment and decrement actions are central to the workflow.
+
+Rules:
+
+- Default field height is 48px.
+- Plus/minus controls are 32px square.
+- Keep the unit visible when the number depends on currency, inventory, or quantity.
+- Set `min`, `max`, and `step` explicitly when business rules exist.
+- Use `allowFloat` for decimal steps.
+- `defaultValue` is kept for API compatibility; prefer controlled `value`.
+- Use `disabledInput` when the field should only change through plus/minus controls.
+- Use `iconColor` and `iconBackgroundColor` sparingly; prefer neutral defaults.
+- Use `minErrText`, `maxErrText`, and `maxAvailable` for domain-specific bounds.
+- Use `mb` only to reserve vertical space when helper/error text is shown.