injast-core 1.0.78 → 1.0.79

package/README.md

@@ -11,7 +11,7 @@ npm install injast-core
 Peer requirements:
 
 ```bash
-npm install react@^19 react-dom@^19
+npm install react@^18.2.0 react-dom@^18.2.0
 ```
 
 The package is published as ESM and is intended for modern React bundlers such as Vite, Next.js, and similar tooling.
@@ -122,6 +122,18 @@ import "injast-core/fonts.css";
 
 `MobileDatePicker` imports the required `react-multi-date-picker` mobile layout stylesheet from its dependency. Ensure your bundler supports CSS imports from JavaScript modules.
 
+## Figma Make
+
+Figma Make users should select the public npm package named `injast-core`. Do not use `@alimohammadiwork/injast-core`; that is a different scoped package name.
+
+For Make kits, start with the included guidelines:
+
+```text
+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.
+
 ## License
 
 ISC

package/guidelines/Guidelines.md

@@ -0,0 +1,53 @@
+# Injast Core Design System Guidelines
+
+## 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.
+
+- 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.
+
+## Reading Order
+
+Always 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`
+
+Read focused component files before using those component groups:
+
+- `guidelines/components/buttons.md`
+- `guidelines/components/forms.md`
+- `guidelines/components/feedback.md`
+- `guidelines/components/layout.md`
+- `guidelines/components/data-display.md`
+- `guidelines/components/date-inputs.md`
+
+## Package Rules
+
+- Install and import the public package as `injast-core`.
+- Do not import `@alimohammadiwork/injast-core`; that scoped package is not this package.
+- For Figma Make and Vite React apps, use `SPAThemeProvider`.
+- 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.
+
+## Component 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.
+
+## 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.

package/guidelines/components/buttons.md

@@ -0,0 +1,43 @@
+# Buttons
+
+## Button
+
+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 { Button } from "injast-core";
+
+<Button variant="contained" color="primary" buttonSize="M">
+  ثبت
+</Button>
+```
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `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` |
+
+## 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 |
+
+## 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.
+- Keep one primary contained action per focused region.
+- Use `loading` instead of manually swapping button text.
+
+## IconButton and Fab
+
+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.

package/guidelines/components/data-display.md

@@ -0,0 +1,43 @@
+# Data Display
+
+## DataGrid
+
+Use `DataGrid` for tabular data. It wraps Material React Table with RTL and Persian localization defaults.
+
+```tsx
+import { DataGrid, type MRT_ColumnDef } from "injast-core";
+
+type Row = { id: string; name: string; status: string };
+
+const columns: MRT_ColumnDef<Row>[] = [
+  { accessorKey: "name", header: "نام" },
+  { accessorKey: "status", header: "وضعیت" },
+];
+
+<DataGrid columns={columns} data={rows} enableSorting />;
+```
+
+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.
+
+## 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.
+
+## Image
+
+Use `Image` for image content. Always provide useful `alt` text unless the image is decorative.
+
+## Pagination and Divider
+
+Use `Pagination` when data is split across pages. Use `Divider` to separate adjacent content groups, not as a substitute for spacing.
+
+## 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.

package/guidelines/components/date-inputs.md

@@ -0,0 +1,45 @@
+# Date Inputs
+
+## MobileDatePicker
+
+Use `MobileDatePicker` for Persian calendar date entry in mobile-first or responsive forms.
+
+```tsx
+<MobileDatePicker
+  label="تاریخ"
+  value={date}
+  onChange={setDate}
+  minDate="1403/01/01"
+  maxDate="1403/12/29"
+/>
+```
+
+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.
+
+## WheelDatePicker
+
+Use `WheelDatePicker` when a drawer-style date picker is more appropriate than the modal calendar.
+
+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.
+
+## Date Utilities
+
+Use utility functions from `injast-core/utils` for conversion and display:
+
+```tsx
+import {
+  gregorianToJalali,
+  jalaliToGregorian,
+  shortDateFormat,
+  longDateFormat,
+} from "injast-core";
+```

package/guidelines/components/feedback.md

@@ -0,0 +1,47 @@
+# Feedback
+
+## Toast
+
+Use `Toast` for brief status feedback. Do not use it for long instructions or complex decisions.
+
+```tsx
+<Toast
+  open={open}
+  duration={4000}
+  handleClose={() => setOpen(false)}
+  message={{ severity: "success", text: "با موفقیت ثبت شد" }}
+/>
+```
+
+Valid severity values:
+
+- `success`
+- `info`
+- `warning`
+- `error`
+
+## 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>
+</Modal>
+```
+
+Rules:
+
+- Always provide a visible close or cancel path.
+- Keep destructive confirmation actions explicit.
+- Avoid putting full pages inside modals.
+
+## Loading and Progress
+
+- Use `Loading` for full-area loading.
+- Use `LoadingModal` when a blocking process is running.
+- Use `CircularProgress` inside small controls.
+- Use `Skeleton` for content placeholders.
+- Use `ProgressBar` when progress has a known percentage or status.

package/guidelines/components/forms.md

@@ -0,0 +1,68 @@
+# Forms
+
+## General Rules
+
+- Use controlled components for form values.
+- Use `TextField` instead of raw `<input>`.
+- Put labels on every input unless the context is visually obvious.
+- Use `error` and `helperText` for validation messages.
+- Use 48px control height for default forms.
+- Use RTL layout for Persian forms.
+
+## TextField
+
+`TextField` accepts Material UI `TextFieldProps` plus:
+
+| Prop | Type | Purpose |
+|---|---|---|
+| `startAdornment` | `ReactNode` | Icon or prefix inside the input |
+| `endAdornment` | `ReactNode` | Icon or suffix inside the input |
+| `height` | `number` | Explicit field height |
+
+```tsx
+<TextField
+  label="نام"
+  value={name}
+  onChange={(event) => setName(event.target.value)}
+  height={48}
+/>
+```
+
+## Select and MultiSelect
+
+Use `Select` for a single value and `MultiSelect` for multiple values.
+
+```tsx
+<MultiSelect
+  label="دسته بندی"
+  value={selected}
+  onChange={setSelected}
+  options={[
+    { label: "فعال", value: "active" },
+    { label: "غیرفعال", value: "inactive" },
+  ]}
+/>
+```
+
+## 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.
+
+## Numeric Inputs
+
+Use `NumberInput` for formatted numeric entry. Use `fungible` when decimals are allowed.
+
+```tsx
+<NumberInput
+  label="مبلغ"
+  value={amount}
+  onChange={setAmount}
+  unit="تومان"
+/>
+```
+
+Use `CardNumberInput` for bank card numbers; it returns the cleaned digits to `onChange`.
+
+Use `OtpInput` for verification codes, not a normal text field.

package/guidelines/components/layout.md

@@ -0,0 +1,36 @@
+# Layout and Navigation
+
+## Layout Primitives
+
+Use `Box`, `Container`, and `Grid` for page structure.
+
+```tsx
+<Container maxWidth="lg">
+  <Box display="grid" gap={4}>
+    {children}
+  </Box>
+</Container>
+```
+
+Rules:
+
+- Use `gap`, `p`, `px`, `py`, `m`, and `mx` from MUI spacing.
+- Use `Container` to constrain broad pages.
+- Use `Grid` for responsive multi-column layouts.
+- Avoid raw CSS layout unless component props are not enough.
+
+## Lists
+
+Use `List` and `ListItem` for vertical collections. Keep each row's main label, metadata, and action placement consistent.
+
+## Accordion
+
+Use `Accordion`, `AccordionSummary`, and `AccordionDetails` for optional details, filters, and FAQ-like disclosure. Do not hide primary required fields in an accordion.
+
+## Tabs
+
+Use `Tab` when switching between closely related panels at the same hierarchy level. Do not use tabs as primary app navigation.
+
+## Stepper
+
+Use `Stepper` and related step components for multi-step flows such as onboarding, checkout, or profile completion. Keep the active step clear and provide Back/Next actions with `Button`.

package/guidelines/components/overview.md

@@ -0,0 +1,60 @@
+# Component Catalog
+
+Always prefer Injast Core components over raw HTML and direct Material UI primitives. Read the focused guideline file before using a component group.
+
+## Actions
+
+| Component | Also known as | Purpose | Guidelines |
+|---|---|---|---|
+| `Button` | CTA, action button | Text actions, submit, navigation, commands | `buttons.md` |
+| `IconButton` | icon action | Compact icon-only actions | `buttons.md` |
+| `Fab` | floating action | Prominent floating action | `buttons.md` |
+
+## Forms
+
+| Component | Also known as | Purpose | Guidelines |
+|---|---|---|---|
+| `TextField` | text input | General text entry | `forms.md` |
+| `NumberInput` | numeric input | Controlled formatted number entry | `forms.md` |
+| `CardNumberInput` | bank card input | Iranian bank card number entry | `forms.md` |
+| `OtpInput` | verification code | One-time password entry | `forms.md` |
+| `InputPhoneNumber` | phone input | Iranian phone number entry | `forms.md` |
+| `Select` | dropdown | Single selection | `forms.md` |
+| `MultiSelect` | tag select | Multiple selection with removable chips | `forms.md` |
+| `Checkbox` | boolean check | Independent yes/no selection | `forms.md` |
+| `Radio`, `RadioGroup` | radio buttons | One choice from a short list | `forms.md` |
+| `Toggle` | switch | On/off setting | `forms.md` |
+
+## Feedback
+
+| Component | Also known as | Purpose | Guidelines |
+|---|---|---|---|
+| `Toast` | snackbar, alert | Brief status feedback | `feedback.md` |
+| `Modal`, `Dialog` | dialog, overlay | Focused task or confirmation | `feedback.md` |
+| `Loading`, `LoadingModal`, `CircularProgress`, `Skeleton`, `ProgressBar` | progress | Loading and progress states | `feedback.md` |
+
+## Layout and Navigation
+
+| Component | Also known as | Purpose | Guidelines |
+|---|---|---|---|
+| `Box`, `Container`, `Grid` | layout primitives | Spacing and page structure | `layout.md` |
+| `List`, `ListItem` | list | Vertical repeated items | `layout.md` |
+| `Accordion`, `AccordionSummary`, `AccordionDetails` | disclosure | Collapsible sections | `layout.md` |
+| `Tab` | tabs | Switch between related panels | `layout.md` |
+| `Stepper`, `Step`, `StepLabel`, `StepContent`, `StepConnector` | step flow | Multi-step workflows | `layout.md` |
+
+## Data and Media
+
+| Component | Also known as | Purpose | Guidelines |
+|---|---|---|---|
+| `DataGrid` | table, grid | Tabular operational data | `data-display.md` |
+| `Typography` | text | Text hierarchy | `data-display.md` |
+| `Image` | image | Image rendering with fallback behavior | `data-display.md` |
+| `Divider`, `Pagination` | separator, pager | Data and content structure | `data-display.md` |
+
+## Date Inputs
+
+| Component | Also known as | Purpose | Guidelines |
+|---|---|---|---|
+| `MobileDatePicker` | Jalali date picker | Mobile-friendly Persian calendar date entry | `date-inputs.md` |
+| `WheelDatePicker` | wheel date picker | Drawer-based date selection | `date-inputs.md` |

package/guidelines/foundations/color.md

@@ -0,0 +1,51 @@
+# Color
+
+## Palette
+
+Use `defaultColors` from `injast-core/constants` or `injast-core` for semantic colors:
+
+```tsx
+import { defaultColors } from "injast-core";
+```
+
+Core palette groups:
+
+| Group | Use for |
+|---|---|
+| `neutral` | Text, borders, surfaces, low-emphasis UI |
+| `success` | Positive status and success feedback |
+| `danger` | Error and destructive status |
+| `warning` | Caution and warning status |
+| `info` | Informational status |
+| `teal` | Preferred Injast brand accent |
+| `blue`, `cyan`, `indigo`, `pink`, `orange`, `magenta`, `yellow`, `red` | Secondary accents and charts |
+
+## Rules
+
+- Use `primary` for the main action or active state.
+- Use `secondary` for supporting actions and neutral controls.
+- Use `neutral.50` to `neutral.200` for quiet surfaces and separators.
+- Use `danger`, `warning`, `info`, and `success` only for their matching status.
+- Avoid large saturated backgrounds. Keep strong colors for small highlights, badges, icons, and buttons.
+- Prefer theme palette references in `sx` when possible, for example `color: "neutral.700"`.
+
+## App Colors
+
+Every provider requires `appColors.primary` and `appColors.secondary`:
+
+```tsx
+const appColors = {
+  primary: {
+    main: "#1DBF98",
+    light: "#1DBF98",
+    dark: "#179D76",
+    contrastText: "#ffffff",
+  },
+  secondary: {
+    main: "#4F545E",
+    light: "#91969F",
+    dark: "#242933",
+    contrastText: "#ffffff",
+  },
+};
+```

package/guidelines/foundations/spacing.md

@@ -0,0 +1,34 @@
+# Spacing, Radius, and Density
+
+## Base Spacing
+
+The theme sets Material UI spacing to 4px increments.
+
+| Value | Pixel equivalent |
+|---:|---:|
+| `1` | 4px |
+| `2` | 8px |
+| `3` | 12px |
+| `4` | 16px |
+| `6` | 24px |
+| `8` | 32px |
+
+Use `sx` spacing props such as `p`, `px`, `py`, `m`, `gap`, `rowGap`, and `columnGap`.
+
+## Component Sizing
+
+- Default form controls and medium buttons are 48px tall.
+- Large buttons are 56px tall.
+- Small buttons and dense controls are 40px tall.
+- Extra small buttons are 32px tall.
+- Standard field radius is 8px.
+- Button radius is 8px or 12px depending on size.
+- Modal paper radius is 12px.
+
+## Layout Rules
+
+- Use `Box`, `Container`, and `Grid` for spacing and layout.
+- Use 16px to 24px gaps between major sections.
+- Use 8px to 12px gaps inside compact controls and field groups.
+- Keep repeated cards and table rows stable in height.
+- Avoid nested cards unless the inner card is a true repeated item or modal content.

package/guidelines/foundations/typography.md

@@ -0,0 +1,33 @@
+# Typography
+
+## Fonts
+
+Load `injast-core/fonts.css` once. The theme uses:
+
+- `IRANYekanX` for standard Persian UI text
+- `IRANYekanXFaNum` where Persian numerals are preferred
+
+## Scale
+
+Use the theme typography scale through components. Important roles:
+
+| Role | Size | Weight | Use for |
+|---|---:|---:|---|
+| `display1` | 32px | 700 | Rare page-level display headings |
+| `display2` | 24px | 700 | Page headings |
+| `display3` | 20px | 700 | Section headings |
+| `h1` | 18px | 500 | Dense page title |
+| `h2` | 16px | 500 | Panel heading |
+| `h3` | 14px | 500 | Small heading |
+| `body1` | 14px | 500 | Default body text |
+| `body2` | 12px | 500 | Secondary text |
+| `label1` | 12px | 400 | Captions and field metadata |
+| `label2` | 10px | 400 | Compact labels only |
+
+## Rules
+
+- Use `Typography` from `injast-core` for text hierarchy.
+- Do not use oversized hero text inside app screens.
+- Use concise labels in buttons and form controls.
+- Keep numeric content readable; use Persian number formatting utilities when appropriate.
+- Do not set negative letter spacing.

package/guidelines/setup.md

@@ -0,0 +1,89 @@
+# Setup
+
+## Install
+
+Use the public npm package:
+
+```bash
+npm install injast-core
+```
+
+For Figma Make package selection, search for:
+
+```text
+injast-core
+```
+
+Do not search for or install `@alimohammadiwork/injast-core`.
+
+## Required Imports
+
+Import the font stylesheet once near the app root:
+
+```tsx
+import "injast-core/fonts.css";
+```
+
+For Vite, React SPA, and Figma Make, wrap the app with `SPAThemeProvider`:
+
+```tsx
+import { SPAThemeProvider, coreFaIR, defaultColors } from "injast-core";
+import "injast-core/fonts.css";
+
+const appColors = {
+  primary: {
+    main: "#1DBF98",
+    light: "#1DBF98",
+    dark: "#179D76",
+    contrastText: "#ffffff",
+  },
+  secondary: {
+    main: "#4F545E",
+    light: "#91969F",
+    dark: "#242933",
+    contrastText: "#ffffff",
+  },
+};
+
+export function AppProviders({ children }: { children: React.ReactNode }) {
+  return (
+    <SPAThemeProvider
+      dir="rtl"
+      appColors={appColors}
+      themeOptions={{ ...coreFaIR }}
+    >
+      {children}
+    </SPAThemeProvider>
+  );
+}
+```
+
+Use `ThemeProvider` only when a project specifically needs the alternate provider API:
+
+```tsx
+import { ThemeProvider } from "injast-core";
+```
+
+## Import Patterns
+
+Root imports are preferred for common components:
+
+```tsx
+import { Button, TextField, Modal, Toast, defaultColors } from "injast-core";
+```
+
+Subpath imports are valid for focused files:
+
+```tsx
+import { Button, TextField } from "injast-core/components";
+import { defaultColors } from "injast-core/constants";
+import { createApiRequest } from "injast-core/libs";
+import { formatPersianNumber } from "injast-core/utils";
+```
+
+## Build Assumptions
+
+- The package is ESM and Vite-compatible.
+- React 18 and React 19 are supported by peer dependency range.
+- CSS imports from dependencies must be allowed because `MobileDatePicker` imports `react-multi-date-picker` CSS.
+- Do not add custom Tailwind setup for Injast Core. Styling comes from Material UI theme, component `sx` props, and package CSS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "injast-core",
-  "version": "1.0.78",
+  "version": "1.0.79",
   "description": "Reusable Injast React and Material UI components, providers, hooks, utilities, and design tokens.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,7 @@
   "types": "dist/types/index.d.ts",
   "files": [
     "dist",
+    "guidelines",
     "README.md",
     "LICENSE"
   ],
@@ -126,8 +127,8 @@
     "stylis-plugin-rtl": "^2.1.1"
   },
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^5.0.0",