injast-core 1.0.80 → 1.0.82

package/guidelines/foundations/spacing.md

@@ -2,33 +2,93 @@
 
 ## Base Spacing
 
-The theme sets Material UI spacing to 4px increments.
+The theme sets Material UI spacing to 4px increments. Use numeric `sx` values so spacing stays on this scale.
 
-| Value | Pixel equivalent |
-|---:|---:|
-| `1` | 4px |
-| `2` | 8px |
-| `3` | 12px |
-| `4` | 16px |
-| `6` | 24px |
-| `8` | 32px |
+| `sx` value | Pixel equivalent | Common use |
+|---:|---:|---|
+| `0.5` | 2px | Hairline label/icon nudge only |
+| `1` | 4px | Tiny icon or table-cell gap |
+| `1.5` | 6px | Compact chip vertical padding |
+| `2` | 8px | Tight internal gap, button/icon spacing |
+| `3` | 12px | Field group gap, chip horizontal padding |
+| `3.5` | 14px | Mobile side padding used by drawers/toasts |
+| `4` | 16px | Default section padding and content gap |
+| `5` | 20px | Dense page block spacing |
+| `6` | 24px | Major section gap and drawer vertical rhythm |
+| `8` | 32px | Large page break only |
 
-Use `sx` spacing props such as `p`, `px`, `py`, `m`, `gap`, `rowGap`, and `columnGap`.
+Use `p`, `px`, `py`, `m`, `mx`, `my`, `gap`, `rowGap`, and `columnGap` instead of arbitrary CSS margins.
+
+## App Shell
+
+Use this for generated mobile-first app screens:
+
+```tsx
+<Box
+  sx={{
+    maxWidth: 520,
+    mx: "auto",
+    minHeight: "100dvh",
+    bgcolor: "neutral.50",
+  }}
+>
+  {children}
+</Box>
+```
+
+Equivalent CSS:
+
+```css
+max-width: 520px;
+margin-inline: auto;
+```
+
+Rules:
+
+- Center the shell with `mx: "auto"` or `margin-inline: auto`.
+- Keep the shell full width below 520px.
+- Use `minHeight: "100dvh"` for app-like screens.
+- Apply page padding inside the shell, not on `body`.
+- Use wider layouts only for data-heavy desktop dashboards, large tables, or split-pane workflows.
+
+## Page Padding and Gaps
+
+| Context | Recommended spacing |
+|---|---|
+| Mobile page side padding | `px: 4` (16px) |
+| Dense page side padding | `px: 3.5` (14px) |
+| Page top/bottom padding | `py: 4` to `py: 6` (16px to 24px) |
+| Major sections | `gap: 4` to `gap: 6` (16px to 24px) |
+| Related form fields | `gap: 3` to `gap: 4` (12px to 16px) |
+| Label/helper text to field | `gap: 1` to `gap: 2` (4px to 8px) |
+| Inline icon to label | `gap: 2` (8px) |
+| Toolbar actions | `gap: 2` to `gap: 3` (8px to 12px) |
+| Modal content blocks | `gap: 4` (16px) |
+| Drawer content | `px: 3.5`, `py: 6` (14px, 24px) |
 
 ## 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.
+| Component or pattern | Size |
+|---|---:|
+| Default text fields | 48px height |
+| `Button` `L` | 56px height, 12px radius |
+| `Button` `M` | 48px height, 12px radius |
+| `Button` `S` | 40px height, 8px radius |
+| `Button` `XS` | 32px height, 8px radius |
+| Small IconButton target | 32px minimum |
+| Standard icon action target | 40px to 48px |
+| OTP input cell | 54px by 54px |
+| Checkbox icon | 24px by default |
+| Toggle small | 48px by 26px |
+| Toggle medium | 59px by 32px |
+| Progress bar default | 20px height |
+| Modal paper radius | 12px |
+| Text field radius | 8px |
+
+## Density Rules
+
+- Keep default forms at 48px control height.
+- Use 40px controls only in dense toolbars, tables, or secondary rows.
+- Use 32px controls only for compact inline actions or modal footer secondary actions.
+- Keep repeated rows stable in height; do not let hover states or labels shift layout.
+- Avoid nested cards. Use spacing, headings, and dividers before adding another framed surface.

package/guidelines/foundations/typography.md

@@ -2,32 +2,55 @@
 
 ## Fonts
 
-Load `injast-core/fonts.css` once. The theme uses:
+Load `injast-core/fonts.css` once. The package includes Persian-friendly fonts:
 
-- `IRANYekanX` for standard Persian UI text
-- `IRANYekanXFaNum` where Persian numerals are preferred
+- `IRANYekanX` for standard Persian UI text.
+- `IRANYekanXFaNum` where Persian numerals are preferred.
 
-## Scale
+`SPAThemeProvider` uses `IRANYekanXFaNum` by default. `ThemeProvider` uses `IRANYekanX` by default. Do not replace the font family in generated screens unless the user explicitly asks.
 
-Use the theme typography scale through components. Important roles:
+## Theme Scale
 
-| Role | Size | Weight | Use for |
+Use `Typography` from `injast-core` and theme typography variants.
+
+| Variant | Size | Weight | Use for |
 |---|---:|---:|---|
-| `display1` | 32px | 700 | Rare page-level display headings |
-| `display2` | 24px | 700 | Page headings |
-| `display3` | 20px | 700 | Section headings |
+| `display1` | 32px | 700 | Rare top-level display heading |
+| `display2` | 24px | 700 | Main page heading in roomy screens |
+| `display3` | 20px | 700 | Section title or modal title |
 | `h1` | 18px | 500 | Dense page title |
-| `h2` | 16px | 500 | Panel heading |
-| `h3` | 14px | 500 | Small heading |
+| `h2` | 16px | 500 | Panel, drawer, and modal heading |
+| `h3` | 14px | 500 | Small section heading |
+| `title1` | 16px | 500 | Card title or list group title |
+| `title2` | 14px | 500 | Compact card/list title |
+| `title3` | 12px | 500 | Small title or table metadata |
+| `title4` | 10px | 500 | Very compact label title |
+| `input1` | 16px | 500 | Large input text |
+| `input2` | 14px | 500 | Default input text |
+| `input3` | 12px | 500 | Compact input text |
+| `button1` | 16px | 700 | Large and medium button text |
+| `button2` | 14px | 700 | Small button text |
+| `button3` | 12px | 700 | Extra small button text |
 | `body1` | 14px | 500 | Default body text |
-| `body2` | 12px | 500 | Secondary text |
-| `label1` | 12px | 400 | Captions and field metadata |
+| `body2` | 12px | 500 | Secondary body text and metadata |
+| `label1` | 12px | 400 | Captions, helper text, field metadata |
 | `label2` | 10px | 400 | Compact labels only |
 
-## Rules
+## Usage 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.
+- Use `display1`, `display2`, and `display3` sparingly. App screens should not look like landing pages.
+- Use `h1` or `display3` for most mobile page titles.
+- Use `h2` for drawer and modal titles.
+- Use `body1` for readable content and form helper paragraphs.
+- Use `body2`, `label1`, and `label2` only for secondary metadata.
+- Use concise Persian labels for buttons and fields. Avoid long button text that wraps.
+- Keep numeric content readable and use Persian number utilities when values are shown to users.
 - Do not set negative letter spacing.
+- Do not scale font size with viewport width.
+- Do not place hero-scale text inside cards, tables, drawers, or modals.
+
+## Alignment
+
+- Persian and RTL text should be right-aligned by default.
+- Numeric codes, OTP digits, card numbers, and Latin-only values can use `dir="ltr"` and centered or left alignment when needed.
+- Keep table headers and body cells right-aligned unless the column is numeric, currency, or an action column.

package/guidelines/runtime.md

@@ -0,0 +1,141 @@
+# Runtime, Hooks, Utilities, and Services
+
+Use this file before adding API clients, error handling, toast calls, date conversion, query strings, logging, Sentry, WebView bridge behavior, or shared hooks.
+
+## Hooks
+
+Import hooks from `injast-core/hooks` or from the package root when available.
+
+```tsx
+import { useErrorHandler, useMessage } from "injast-core/hooks";
+```
+
+| Hook | Use for |
+|---|---|
+| `useMessage` | Showing app-level toast messages through `MessageProvider` |
+| `useErrorHandler` | Converting API errors into toast messages and form field errors |
+| `useWebOtpListener` | Listening for Web OTP when the environment supports it |
+| `useTheme` | Reading the active Material UI theme |
+| `useColorScheme` | Reading or controlling MUI color scheme state |
+| `useLocalStorage` | Local storage-backed state from `@wojtekmaj/react-hooks` |
+| `useWindowHeight`, `useWindowWidth` | Responsive measurements when CSS/container queries are not enough |
+
+Rules:
+
+- `useMessage` and `useErrorHandler` require `MessageProvider` above the component tree.
+- Use `useErrorHandler` in forms and service-driven screens instead of writing one-off toast parsing.
+- When using React Hook Form, pass its `setError` as the field handler to `handleError`.
+- Keep generated hooks client-side when they depend on `window`, `document`, `navigator`, local storage, or Web OTP.
+
+## Error Handling Pattern
+
+```tsx
+const { handleError } = useErrorHandler<FormValues>();
+
+try {
+  await submitForm(values);
+} catch (error) {
+  handleError(error, setError);
+}
+```
+
+`useErrorHandler` shows string errors as an error toast. If the API returns field errors, it can pass each field error to the provided field handler.
+
+## Messages
+
+Use `useMessage` for deliberate app messages:
+
+```tsx
+const { showMessage } = useMessage();
+
+showMessage("با موفقیت ثبت شد", "success");
+```
+
+Valid severities are `success`, `info`, `warning`, and `error`. Keep messages concise and Persian when the app content is Persian.
+
+## API Requests
+
+Use `createApiRequest` from `injast-core/libs` for Axios clients. It wraps `axios`:
+
+```tsx
+import { createApiRequest } from "injast-core/libs";
+
+export const apiRequest = createApiRequest({
+  baseURL: process.env.NEXT_PUBLIC_API_URL,
+});
+```
+
+Rules:
+
+- Keep one shared API client per API base.
+- Use request/response interceptors through the helper arguments when auth, redirects, or response normalization are needed.
+- The helper defaults to JSON headers and `withCredentials: true`.
+- In browser clients, it reads auth tokens from local storage unless `disableAuthHeader` is set.
+- Do not create unrelated raw Axios instances when `createApiRequest` fits the app.
+
+## Query Strings
+
+Use `createQueryParams` from `injast-core/utils` instead of hand-building query strings.
+
+```tsx
+import { createQueryParams } from "injast-core/utils";
+
+const endpoint = `/chats/messages?${createQueryParams({ category, page })}`;
+```
+
+`createQueryParams` skips empty values and URL-encodes values. Do not pass nested objects to it.
+
+## Dates and Persian Formatting
+
+Use the package utilities for Jalali/Gregorian conversion and Persian display:
+
+| Utility | Use for |
+|---|---|
+| `gregorianToJalali` | Convert `YYYY-MM-DD` Gregorian values for display |
+| `jalaliToGregorian` | Convert `YYYY/MM/DD` Jalali values before API submission |
+| `shortDateFormat` | Compact Persian date display |
+| `longDateFormat` | Persian date plus time display |
+| `longFormatInWords` | Human-readable Persian date wording |
+| `getPersianYMD` | Extract Persian calendar year/month/day from a `Date` |
+| `jalaliToDateUTC` | Build UTC dates from Jalali year/month/day |
+| `formatPersianNumber` | Display numbers in Persian format |
+| `toLatinDigits` | Normalize Persian/Arabic digits before validation or API submission |
+| `convertRialToToman` | Currency conversion for Iranian money displays |
+
+Rules:
+
+- Do not hand-roll Jalali conversion, Persian digit conversion, or query-string serialization.
+- Store API values in the format the API expects; convert at the UI boundary.
+- Use `toLatinDigits` before validating numeric user input when Persian digits are allowed.
+- `formatPersianNumber` returns an empty string for non-finite input.
+- `convertRialToToman` should be used before display only when the product copy expects Toman rather than Rial.
+
+`coreFaIR` is the exported MUI Persian locale option, re-exported from MUI `faIR`. Use it in `SPAThemeProvider` theme options:
+
+```tsx
+const options = {
+  ...coreFaIR,
+};
+```
+
+## App and WebView Helpers
+
+| Utility | Use for |
+|---|---|
+| `getClaims` | Reading decoded auth claims when the app stores compatible tokens |
+| `checkUser` | User/auth guard checks in app flows |
+| `postToParent` | Posting events from embedded or WebView contexts |
+| `delay` | Small async waits in controlled UI flows |
+| `styled` | Injast-styled helper for components that need styled wrappers |
+
+Use WebView bridge helpers only in client components and only after checking the host environment.
+
+## Logging and Observability
+
+Use `createLogger` from `injast-core/libs` for optional prefixed logging and iOS WebView console bridging.
+
+Use `initSentry` and `Sentry` from `injast-core/libs` only when the app is configured for Sentry. These helpers wrap `@sentry/react`. Do not initialize Sentry in generated prototypes unless the user asks for observability setup or the app already has DSN/environment configuration.
+
+## Constants
+
+Use `defaultColors` from `injast-core/constants` or the package root for palette values. Use `stepConnectorClasses` only when customizing Stepper connector styling; otherwise rely on the Stepper defaults.

package/guidelines/setup.md

@@ -16,6 +16,16 @@ injast
 
 Then select the public unscoped package `injast-core`. If exact search for `injast-core` returns unrelated `core` packages first, use `injast` as the search term. Do not search for or install `@alimohammadiwork/injast-core` or `@make-kits/injast-core-make-kit` for this public package path.
 
+## Figma MCP
+
+For design-driven implementation, use the Figma MCP server and fetch both structured design context and a screenshot before writing code. The local MCP endpoint is:
+
+```text
+http://127.0.0.1:3845/mcp
+```
+
+Translate the MCP output into Injast Core patterns, RTL layout, Persian copy, and the Gold reference app structure. Do not keep generic generated React, Tailwind classes, raw controls, or decorative mobile OS status bars from the design payload.
+
 ## Required Imports
 
 Import the font stylesheet once near the app root:
@@ -24,10 +34,54 @@ Import the font stylesheet once near the app root:
 import "injast-core/fonts.css";
 ```
 
-For Vite, React SPA, and Figma Make, wrap the app with `SPAThemeProvider`:
+Use root imports for normal Make output:
+
+```tsx
+import {
+  Button,
+  MessageProvider,
+  SPAThemeProvider,
+  ThemeProvider,
+  coreFaIR,
+  defaultColors,
+} from "injast-core";
+```
+
+Use `iconsax-react` for generated app icons:
+
+```tsx
+import { Add, Calendar, CloseCircle, SearchNormal1 } from "iconsax-react";
+```
+
+Do not import icons from Lucide, Heroicons, Font Awesome, inline SVG files, or `@mui/icons-material` in generated app screens.
+
+## 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",
+  },
+};
+```
+
+## Figma Make and React SPA Provider
+
+For Vite, React SPA, and Figma Make, wrap the app with `SPAThemeProvider`, pass RTL direction, apply Persian locale options, and include `MessageProvider` inside the theme:
 
 ```tsx
-import { SPAThemeProvider, coreFaIR, defaultColors } from "injast-core";
+import { MessageProvider, SPAThemeProvider, coreFaIR } from "injast-core";
 import "injast-core/fonts.css";
 
 const appColors = {
@@ -45,23 +99,117 @@ const appColors = {
   },
 };
 
+const options = {
+  ...coreFaIR,
+};
+
 export function AppProviders({ children }: { children: React.ReactNode }) {
   return (
-    <SPAThemeProvider
-      dir="rtl"
-      appColors={appColors}
-      themeOptions={{ ...coreFaIR }}
-    >
-      {children}
+    <SPAThemeProvider dir="rtl" appColors={appColors} themeOptions={options}>
+      <MessageProvider>{children}</MessageProvider>
     </SPAThemeProvider>
   );
 }
 ```
 
-Use `ThemeProvider` only when a project specifically needs the alternate provider API:
+## Next.js Provider
+
+For Next.js client layouts or app providers, use `ThemeProvider`. Keep `MessageProvider` inside the theme provider and `Suspense` inside `MessageProvider`:
+
+```tsx
+"use client";
+
+import { MessageProvider, ThemeProvider } from "injast-core";
+import "injast-core/fonts.css";
+import { Suspense } from "react";
+
+const appColors = {
+  primary: {
+    main: "#1DBF98",
+    light: "#1DBF98",
+    dark: "#179D76",
+    contrastText: "#ffffff",
+  },
+  secondary: {
+    main: "#4F545E",
+    light: "#91969F",
+    dark: "#242933",
+    contrastText: "#ffffff",
+  },
+};
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider dir="rtl" appColors={appColors}>
+      <MessageProvider>
+        <Suspense>{children}</Suspense>
+      </MessageProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+If an existing Next.js app keeps `Suspense` around the whole provider component, keep `ThemeProvider` and `MessageProvider` together and do not split toast/message consumers outside `MessageProvider`.
+
+## Next.js Viewport
+
+For mobile app-like products, lock the viewport scale in `app/layout.tsx` or the relevant Next.js layout module:
 
 ```tsx
-import { ThemeProvider } from "injast-core";
+import type { Viewport } from "next";
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1.0,
+  maximumScale: 1.0,
+  userScalable: false,
+};
+```
+
+## App Shell
+
+Generated mobile-first app roots should use a centered shell. In Next.js App Router, the root layout can apply the shell directly to `<body>`:
+
+```tsx
+import { defaultColors } from "injast-core";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="fa" dir="rtl">
+      <body
+        style={{
+          backgroundColor: defaultColors.neutral[100],
+          maxWidth: "520px",
+          marginInline: "auto",
+        }}
+      >
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+Inside generated pages, use the same centered constraint with Injast layout primitives:
+
+```tsx
+<Box
+  sx={{
+    maxWidth: 520,
+    mx: "auto",
+    minHeight: "100dvh",
+    bgcolor: "neutral.50",
+  }}
+>
+  {children}
+</Box>
+```
+
+Equivalent CSS is allowed for the outer shell:
+
+```css
+max-width: 520px;
+margin-inline: auto;
 ```
 
 ## Import Patterns
@@ -78,12 +226,19 @@ Subpath imports are valid for focused files:
 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";
+import { useErrorHandler, useMessage } from "injast-core/hooks";
+import { createQueryParams, formatPersianNumber } from "injast-core/utils";
 ```
 
+Read `guidelines/runtime.md` before using hooks, API helpers, date helpers, Persian-number utilities, local storage/window hooks, Sentry, logger helpers, or WebView bridge helpers.
+
 ## Build Assumptions
 
 - The package is ESM and Vite-compatible.
 - React 18 is the default target for Figma Make. React 19 is also allowed by the package peer dependency range for non-Figma consumers.
 - 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.
+- Do not change package exports, public component APIs, or provider APIs in generated examples.
+- Injast Core wraps Material UI (`@mui/material`), Emotion (`@emotion/react`, `@emotion/cache`, `@emotion/styled`), and RTL Stylis (`stylis`, `stylis-plugin-rtl`). Do not install or configure separate theme/cache providers unless the host app already owns that setup.
+- Use package exports only: root, `components`, `providers`, `hooks`, `libs`, `utils`, `context`, `constants`, `types`, and `fonts.css`.
+- Build generated examples as wired app flows. Connect navigation, drawer/modal open and close behavior, and submit/confirm actions with local state when no backend exists.

package/guidelines/types.md

@@ -0,0 +1,60 @@
+# Types
+
+Import shared types from `injast-core/types` only when they improve type safety in app code. Do not copy package type definitions into generated apps.
+
+```tsx
+import type { AppColors, ApiResponse, SelectChangeEvent } from "injast-core/types";
+```
+
+## Theme and Color Types
+
+| Type | Use for |
+|---|---|
+| `ColorShades` | A palette object with `main`, `light`, `dark`, optional numbered shades, and optional `contrastText` |
+| `AppColors` | The required `primary` and `secondary` object passed to `ThemeProvider` and `SPAThemeProvider` |
+| `DefaultColors` | The full built-in semantic palette shape |
+| `CorePalette` | Combined app and default palette shape |
+
+Use `AppColors` when defining reusable `appColors` constants.
+
+## API and Error Types
+
+| Type | Use for |
+|---|---|
+| `QueryParamsObj` | Flat query-string objects accepted by query helpers |
+| `ApiResponse<T>` | Standard API response shape with `meta` and `data` |
+| `ErrorFields` | Field-level API validation errors |
+| `ErrorData` | API error payload consumed by `useErrorHandler` |
+
+Use these types with service modules and form submit handlers. Keep API data models in the app domain when they are app-specific.
+
+## MUI and DataGrid Types
+
+| Type | Use for |
+|---|---|
+| `SelectChangeEvent<T>` | Typed MUI select change events |
+| `MRT_ColumnDef`, `MRT_RowData`, `MRT_TableOptions`, `MRT_TableInstance`, `MRT_Row` | Common `DataGrid` and Material React Table types |
+| Other `MRT_*` re-exports | Advanced DataGrid customization only |
+
+Prefer importing common DataGrid types directly from `injast-core` when the root export provides them:
+
+```tsx
+import { DataGrid, type MRT_ColumnDef } from "injast-core";
+```
+
+## Window and WebView Types
+
+| Type | Use for |
+|---|---|
+| `DeviceInfo` | Device metadata received from native hosts |
+| `AndroidPageName` | Native Android navigation targets |
+| `PermissionsArray` | Native permission code arrays |
+| `IframeMessages` | Messages posted to or from iframe/webview contexts |
+
+Use these only in client-side integration code. Check that `window`, `window.webkit`, or `window.injast_android_app` exists before calling native bridge methods.
+
+## Typography Module Types
+
+The package augments MUI typography variants for `display1`, `display2`, `display3`, `title1` through `title4`, `input1` through `input3`, `button1` through `button3`, `body1`, `body2`, `label1`, and `label2`.
+
+Use these variants through `Typography`; do not redeclare the module augmentation in generated apps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "injast-core",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "description": "Reusable Injast React and Material UI components, providers, hooks, utilities, and design tokens.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "guidelines",
+    "skills",
     "README.md",
     "LICENSE"
   ],