injast-core 1.0.80 → 1.0.82

package/README.md

@@ -142,6 +142,26 @@ guidelines/Guidelines.md
 
 The guidelines route Make to setup instructions, foundations, component selection rules, and focused component usage notes. In a Vite/React Make file, use `SPAThemeProvider`, import `injast-core/fonts.css` once, and prefer Injast components over raw HTML controls.
 
+For Figma-driven implementation, use the Figma MCP flow before coding. The local MCP endpoint is:
+
+```text
+http://127.0.0.1:3845/mcp
+```
+
+Fetch structured design context and a screenshot for the exact node, then translate the design into Injast Core components, RTL layout, Persian copy, and the project guidelines.
+
+Generated mobile app screens should follow the Gold reference app at `/Users/ali/Documents/Gold`: centered `max-width: 520px` shell, wired navigation and overlay behavior, Injast Core inputs, drawer-based pre-invoices, and no mobile OS/app status bar chrome.
+
+## Codex Skill
+
+The package ships a Codex skill for Injast app generation:
+
+```text
+skills/injast-app-builder
+```
+
+After installing the package, consumers can point Codex at `node_modules/injast-core/skills/injast-app-builder` or copy that folder into their Codex skills directory if their Codex setup does not auto-discover package-bundled skills.
+
 ## License
 
 ISC

package/guidelines/Guidelines.md

@@ -2,24 +2,28 @@
 
 ## 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, wired together, 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.
+- Treat `/Users/ali/Documents/Gold` as the canonical reference for mobile app shell structure, component composition, wired flows, and drawer behavior.
+- Keep the main app canvas constrained to `max-width: 520px` 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 +34,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 +45,52 @@ 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.
+
+## Figma MCP Workflow
+
+For Figma-driven implementation, use the Figma MCP server before writing app code. The local MCP endpoint is:
+
+```text
+http://127.0.0.1:3845/mcp
+```
+
+Rules:
+
+- Fetch design context for the exact frame or node first.
+- Fetch a screenshot for the same frame or variant before implementation.
+- Use metadata to narrow the request when the initial design context is too large.
+- Translate Figma output into Injast Core, RTL, Persian, and Gold-style app conventions. Do not copy generic generated React or Tailwind structure as final code.
+- If Figma includes mobile OS chrome or an app status bar, omit it from implementation.
+
+## Hard UI Rules
+
+- 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.
+- All visible inputs must come from Injast Core, such as `TextField`, `NumberInput`, `InputPhoneNumber`, `CardNumberInput`, `OtpInput`, `Select`, `MultiSelect`, `Autocomplete`, `Checkbox`, `Radio`, `Toggle`, `Slider`, or `CounterBoxInput`.
+- Do not use direct Material UI input primitives in generated app code when an Injast input 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: 520` or CSS `max-width: 520px; 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.
+- Do not implement mobile OS status bars or decorative app status bars, even when the design file includes them.
+- Generated apps must be wired flows, not a set of disconnected static screens. Navigation actions, drawer/modal triggers, submit buttons, close buttons, and confirmation actions should update local state or route to the next screen.
 
-## Component Rules
+## Overlay and Drawer 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.
+- Pre-invoices (`پیش‌فاکتور`) are drawer or bottom-sheet overlays, not independent pages.
+- Drawers should feel like drawers: fixed overlay, backdrop, centered `maxWidth: 520` sheet, visible close path, and entrance/exit motion from the drawer edge.
+- When a drawer is open, dim, blur, or subtly scale the underlying page when it helps communicate layering.
+- Keep modal content compact and centered inside the 520px app shell. Do not put full pages inside modals.
 
 ## 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, wired actions, 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 520px 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 520px 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 | 520px |
+| 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,81 @@ 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 520px 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.
+- Keep modal paper and content visually centered inside the 520px app shell.
+- 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.
+
+Pre-invoices (`پیش‌فاکتور`) must be drawers or bottom sheets. Do not build pre-invoices as independent pages.
+
+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 520px app shell when possible.
+- Use `maxWidth: 520` 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.
+- Make drawer layering clear with a backdrop and fixed overlay behavior.
+- Animate bottom drawers from `translateY(100%)` to `translateY(0)` and animate the backdrop opacity so the UI does not feel like a sudden page swap.
+- When useful, dim, blur, or subtly scale the underlying page while the drawer is open.
 
 ## Loading and Progress
 
@@ -45,3 +103,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.