mui-design-system 0.0.31 → 0.0.33

package/README.md

@@ -0,0 +1,690 @@
+# mui-design-system
+
+Design system based on MUI (Material UI) with custom theme, form components, table, and utilities.
+
+---
+
+## Installation
+
+```bash
+npm install mui-design-system
+```
+
+### Peer dependencies
+
+Install in your project if not already present:
+
+- `react` & `react-dom` (^18.2.0)
+- `@mui/material` (^6.1.9)
+- `@emotion/react`, `@emotion/styled`
+- `styled-components` (^6.1.8)
+- `stylis-plugin-rtl` (for RTL)
+- For form: `react-hook-form` (^7.51.2)
+- For table: `@tanstack/react-table` (^8.17.3)
+
+---
+
+## Quick start
+
+```tsx
+import { ReactCacheProvider, themeOptions, Form, colors } from 'mui-design-system';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+
+const theme = createTheme(themeOptions('light', false)); // mode, isRtl
+
+<ThemeProvider theme={theme}>
+  <ReactCacheProvider isRtl={false}>
+    <App />
+  </ReactCacheProvider>
+</ThemeProvider>
+
+// Colors from subpath
+import { colors } from 'mui-design-system/colors/index';
+```
+
+---
+
+## Exports overview
+
+| Category | Exports |
+|----------|---------|
+| Theme & providers | `themeOptions`, `ReactCacheProvider`, `NextCacheProvider` |
+| Form | `Form`, `FormProvider`, and all UF* field components + `CheckboxList` |
+| Table | `CustomTable`, `useTable` |
+| OTP | `OTPInput` |
+| Methods | `debounce`, `result`, `deepMerge` |
+| Colors | `colors` (from `mui-design-system/colors/index`) |
+
+---
+
+## 1. Theme & providers
+
+### `themeOptions(mode, isRtl)`
+
+Builds MUI `ThemeOptions` (palette, typography, components, direction).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `mode` | `'light' \| 'dark'` | Palette mode |
+| `isRtl` | `boolean` | RTL/LTR direction |
+
+**Example:**
+
+```tsx
+import { createTheme } from '@mui/material/styles';
+import { themeOptions } from 'mui-design-system';
+
+const theme = createTheme(themeOptions('light', false));
+```
+
+---
+
+### `ReactCacheProvider`
+
+Emotion cache provider for React apps (non-Next). Use for correct RTL/LTR styling with the theme.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | App content |
+| `isRtl` | `boolean` | — | Use RTL cache (with stylis-plugin-rtl) |
+
+**Example:**
+
+```tsx
+import { ReactCacheProvider } from 'mui-design-system';
+
+<ReactCacheProvider isRtl={false}>
+  <App />
+</ReactCacheProvider>
+```
+
+---
+
+### `NextCacheProvider`
+
+Provider for Next.js (with `@mui/material-nextjs`). In the current version it mainly wraps `children`; use Next’s config for RTL if needed.
+
+**Props:** `children`, `isRtl`
+
+**Example:**
+
+```tsx
+import { NextCacheProvider } from 'mui-design-system';
+
+<NextCacheProvider isRtl={false}>
+  <App />
+</NextCacheProvider>
+```
+
+---
+
+## 2. Form
+
+Form is built on **react-hook-form** and a **schema** array that describes each field.
+
+### `Form`
+
+Renders form fields from a `schema` and a react-hook-form instance.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `schema` | `TFormSchema` | — | Array of field configs |
+| `form` | `UseFormReturn<any>` | — | Return value of `useForm()` |
+| `gridContainerProps` | `GridProps` | — | Grid container props |
+| `gridItemProps` | `GridProps` | — | Props for each grid item |
+| `itemProps` | `any` | — | Shared item props |
+| `labelsProps` | `Partial<TypographyProps>` | — | Label typography/style |
+| `hideRequiredStar` | `boolean` | `false` | Hide required asterisk |
+| `inputLabelMode` | `'static' \| 'relative'` | `'static'` | Label placement |
+| `inputVariants` | `'outlined' \| 'filled' \| 'standard'` | `'outlined'` | Text field variant |
+| `withoutHelperText` | `boolean` | — | Hide helper text |
+| `disabled` | `boolean` | — | Disable entire form |
+
+**Schema item shape (summary):** `name`, `label`, `type`, `rules` (react-hook-form), `defaultValue`, `placeholder`, `options` (for select/radio/etc.), `props` / `itemProps` per type.
+
+**Schema field types:** `'text'`, `'email'`, `'password'`, `'number'`, `'tel'`, `'text-area'`, `'select'`, `'multi-select'`, `'auto-complete'`, `'radio'`, `'checkbox'`, `'multi-checkbox'`, `'switch'`, `'date-picker'`, `'time'`, `'currency'`, `'uploader'`.
+
+**Example:**
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { Form } from 'mui-design-system';
+
+const schema = [
+  { name: 'email', label: 'Email', type: 'email', rules: { required: true } },
+  { name: 'age', label: 'Age', type: 'number' },
+  {
+    name: 'country',
+    label: 'Country',
+    type: 'select',
+    options: [
+      { value: 'us', label: 'United States' },
+      { value: 'uk', label: 'United Kingdom' },
+    ],
+  },
+];
+
+const MyForm = () => {
+  const form = useForm({ defaultValues: { email: '', age: 0, country: '' } });
+  return (
+    <form onSubmit={form.handleSubmit((data) => console.log(data))}>
+      <Form schema={schema} form={form} />
+      <button type="submit">Submit</button>
+    </form>
+  );
+};
+```
+
+---
+
+### `FormProvider`
+
+Provides form theme and optional custom inputs. Wrap your form when you need default styling or custom field types.
+
+**Props:** `children`, `theme?` (TFormTheme), `customInputs?`
+
+**Example:**
+
+```tsx
+import { FormProvider, Form } from 'mui-design-system';
+
+<FormProvider theme={{ text: { /* default TextField props */ } }}>
+  <Form schema={schema} form={form} />
+</FormProvider>
+```
+
+---
+
+### Form field components (UF*)
+
+These are used internally by `Form` but can also be used standalone with react-hook-form’s `register` / `control`. All are wrapped with an error boundary when exported.
+
+#### `UFTextField`
+
+Text input for `text`, `email`, `password`, `number`, `tel`.
+
+**Example:**
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { UFTextField } from 'mui-design-system';
+
+const MyField = () => {
+  const form = useForm({ defaultValues: { username: '' } });
+  return (
+    <UFTextField
+      form={form}
+      name="username"
+      label="Username"
+      type="text"
+      placeholder="Enter username"
+    />
+  );
+};
+```
+
+---
+
+#### `UFTextArea`
+
+Multiline text field.
+
+**Example:**
+
+```tsx
+import { Form, useForm } from 'mui-design-system';
+
+const schema = [
+  { name: 'bio', label: 'Bio', type: 'text-area', placeholder: 'Tell us about yourself' },
+];
+const form = useForm({ defaultValues: { bio: '' } });
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFSelect`
+
+Single select dropdown.
+
+**Example:**
+
+```tsx
+const schema = [
+  {
+    name: 'city',
+    label: 'City',
+    type: 'select',
+    options: [
+      { value: 'ny', label: 'New York' },
+      { value: 'la', label: 'Los Angeles' },
+    ],
+  },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFMultiSelect`
+
+Multi-select dropdown.
+
+**Example:**
+
+```tsx
+const schema = [
+  {
+    name: 'tags',
+    label: 'Tags',
+    type: 'multi-select',
+    options: [
+      { value: 'a', label: 'Tag A' },
+      { value: 'b', label: 'Tag B' },
+    ],
+  },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFAutoComplete`
+
+Autocomplete with search, options, and optional async loading.
+
+**Example:**
+
+```tsx
+const schema = [
+  {
+    name: 'country',
+    label: 'Country',
+    type: 'auto-complete',
+    options: countries,
+    onSearch: (value) => fetchCountries(value),
+    isLoading: loading,
+  },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFCheckbox`
+
+Single checkbox.
+
+**Example:**
+
+```tsx
+const schema = [
+  { name: 'agree', label: 'I agree to terms', type: 'checkbox' },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFMultiCheckbox` / `CheckboxList`
+
+List of checkboxes; used for multi-checkbox fields.
+
+**Example:**
+
+```tsx
+const schema = [
+  {
+    name: 'interests',
+    label: 'Interests',
+    type: 'multi-checkbox',
+    options: [
+      { value: 'sports', label: 'Sports' },
+      { value: 'music', label: 'Music' },
+    ],
+  },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFRadio`
+
+Radio group.
+
+**Example:**
+
+```tsx
+const schema = [
+  {
+    name: 'gender',
+    label: 'Gender',
+    type: 'radio',
+    options: [
+      { value: 'm', label: 'Male' },
+      { value: 'f', label: 'Female' },
+    ],
+  },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFSwitch`
+
+Toggle switch.
+
+**Example:**
+
+```tsx
+const schema = [
+  { name: 'notifications', label: 'Enable notifications', type: 'switch' },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFDatePicker`
+
+Date picker field.
+
+**Example:**
+
+```tsx
+const schema = [
+  { name: 'birthDate', label: 'Birth date', type: 'date-picker' },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFTime`
+
+Time input (hours/minutes).
+
+**Example:**
+
+```tsx
+const schema = [
+  { name: 'appointmentTime', label: 'Time', type: 'time' },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFCurrency`
+
+Numeric/currency input with formatting.
+
+**Example:**
+
+```tsx
+const schema = [
+  { name: 'price', label: 'Price', type: 'currency', placeholder: '0.00' },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+#### `UFUploader`
+
+File upload with optional multiple files and delete handler.
+
+**Example:**
+
+```tsx
+const schema = [
+  {
+    name: 'attachments',
+    label: 'Attachments',
+    type: 'uploader',
+    multiple: true,
+    onDelete: (index) => removeFile(index),
+  },
+];
+<Form schema={schema} form={form} />;
+```
+
+---
+
+## 3. Table
+
+### `useTable`
+
+Hook that builds a **@tanstack/react-table** instance and returns `table`, `pagination`, and optional selection/expand helpers for `CustomTable`.
+
+**Parameters (`IUseTableProps`):** `columns`, `data`, `pageSize?`, `multiSelect?`, `onSelectRow?`, `getRowId?`, `renderSubComponent?`, `getRowCanExpand?`, `state?`, and other react-table options.
+
+**Returns:** `{ table, pagination, selectedRows, renderSubComponent }`.
+
+**Example:**
+
+```tsx
+import { useTable, CustomTable } from 'mui-design-system';
+
+const columns = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'age', header: 'Age' },
+];
+const data = [
+  { id: '1', name: 'Alice', age: 28 },
+  { id: '2', name: 'Bob', age: 32 },
+];
+
+const MyTable = () => {
+  const { table, pagination, renderSubComponent } = useTable({
+    columns,
+    data,
+    pageSize: 10,
+  });
+  return (
+    <CustomTable
+      table={table}
+      pagination={pagination}
+      renderSubComponent={renderSubComponent}
+    />
+  );
+};
+```
+
+---
+
+### `CustomTable`
+
+Table UI with header, body, loading skeleton, pagination, optional row selection (radio/checkbox) and expandable rows.
+
+**Props (`ICustomTable`):** `id?`, `table`, `pagination?`, `variant?` (`'zebra' | 'linear'`), `isLoading?`, `wrapperStackProps?`, `footerProps?`, `onClickRow?`, `renderSubComponent?`, `withRadio?`, `withSelect?`, `withIndex?`, `rowStyle?`, `cellsStyle?`, `headerStyle?`, `headerTypoProps?`, `checkboxProps?`, `radioProps?`, `emptyListComponent?`, `rowBorderRadius?`, `borderRadius?`.
+
+**Example:**
+
+```tsx
+import { useTable, CustomTable } from 'mui-design-system';
+
+const columns = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'email', header: 'Email' },
+];
+const data = [
+  { id: '1', name: 'Alice', email: 'alice@example.com' },
+  { id: '2', name: 'Bob', email: 'bob@example.com' },
+];
+
+const DataTable = () => {
+  const { table, pagination } = useTable({ columns, data, pageSize: 5 });
+  return (
+    <CustomTable
+      id="users-table"
+      table={table}
+      pagination={pagination}
+      variant="zebra"
+      emptyListComponent="No users found"
+    />
+  );
+};
+```
+
+---
+
+## 4. OTP Input
+
+### `OTPInput`
+
+Multi-digit OTP input (one box per digit).
+
+**Props:** `valueLength`, `value?`, `onChange`, `size?`, `gap?`, `inputStyle?`, `activeInputStyle?`, `onFinish?`, `onBack?`, `containerProp?`, `readonly?`, `disabled?`, `isError?`.
+
+**Example:**
+
+```tsx
+import { useState } from 'react';
+import { OTPInput } from 'mui-design-system';
+
+const VerifyCode = () => {
+  const [otp, setOtp] = useState('');
+  return (
+    <OTPInput
+      valueLength={6}
+      value={otp}
+      onChange={setOtp}
+      onFinish={(val) => console.log('OTP completed:', val)}
+      gap={2}
+    />
+  );
+};
+```
+
+---
+
+## 5. Methods
+
+### `debounce(func, wait, immediate?)`
+
+Debounces a function (e.g. for search input).
+
+**Example:**
+
+```tsx
+import { debounce } from 'mui-design-system';
+
+const handleSearch = debounce((query: string) => {
+  fetchSuggestions(query);
+}, 300);
+
+// In JSX: <Input onChange={(e) => handleSearch(e.target.value)} />
+```
+
+---
+
+### `result(object, key, defaultValue?)`
+
+Reads a value from an object with optional default or lazy default (function).
+
+**Example:**
+
+```tsx
+import { result } from 'mui-design-system';
+
+const userName = result(user, 'name', 'Guest');
+const value = result(config, 'key', () => computeExpensiveDefault());
+```
+
+---
+
+### `deepMerge<T>(...objects)`
+
+Deep-merges objects. Arrays and non-object values are overwritten.
+
+**Example:**
+
+```tsx
+import { deepMerge } from 'mui-design-system';
+
+const merged = deepMerge(
+  { a: 1, b: { x: 1 } },
+  { b: { y: 2 }, c: 3 }
+);
+// { a: 1, b: { x: 1, y: 2 }, c: 3 }
+```
+
+---
+
+## 6. Colors
+
+Color palettes are available from the colors subpath.
+
+**Example:**
+
+```tsx
+import { colors } from 'mui-design-system/colors/index';
+
+// Each color has keys 50–900
+colors.blue[500];  // "#1e88e5"
+colors.grey[700];  // "#535353"
+
+// Available: yellow, blue, green, orange, red, purple, grey
+```
+
+**TypeScript types:** `TColors`, `ColorScale` (`"50" | "100" | ... | "900"`), `IColor`.
+
+---
+
+## Export tree (summary)
+
+```
+mui-design-system
+├── themeOptions
+├── ReactCacheProvider
+├── NextCacheProvider
+├── Form
+├── FormProvider
+├── UFTextField, UFTextArea, UFSelect, UFMultiSelect, UFAutoComplete
+├── UFCheckbox, UFMultiCheckbox, CheckboxList
+├── UFRadio, UFSwitch
+├── UFDatePicker, UFTime, UFCurrency, UFUploader
+├── CustomTable
+├── useTable
+├── OTPInput
+├── debounce, result, deepMerge
+└── (colors from mui-design-system/colors/index)
+```
+
+---
+
+## Not exported from main entry
+
+These exist in the library but are not re-exported from the main package. You can add them to `index.ts` if needed:
+
+- **`useEffectOnce`** — Hook that runs an effect once (mount) with cleanup. File: `src/lib/hooks/useEffectOnce.ts`
+- **`useFormContext`** — Access form context (theme, custom inputs) when inside `FormProvider`. File: `src/lib/context/FormContext.tsx`
+
+---
+
+## Build (for maintainers)
+
+From repo root:
+
+```bash
+npm run build:lib
+```
+
+Or from this directory (after `npm install` here):
+
+```bash
+npm run build
+```
+
+---
+
+## License
+
+ISC

package/dist/assets/icons/AlertCircle.d.ts

@@ -0,0 +1,7 @@
+import type { SVGProps } from 'react';
+interface Props extends SVGProps<SVGSVGElement> {
+    primarycolor?: string;
+    secondarycolor?: string;
+}
+declare const SvgAlertCircle: ({ primarycolor, secondarycolor, ...props }: Props) => import("react/jsx-runtime").JSX.Element;
+export default SvgAlertCircle;

package/dist/assets/icons/AlertCircle.js

@@ -0,0 +1,3 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const SvgAlertCircle = ({ primarycolor, secondarycolor, ...props }) => (_jsx("svg", { xmlns: 'http://www.w3.org/2000/svg', viewBox: '0 0 24 24', fill: 'none', ...props, children: _jsx("path", { fill: primarycolor || '#D03430', fillRule: 'evenodd', d: 'M2 12C2 6.48 6.48 2 12 2c5.53 0 10 4.48 10 10s-4.47 10-10 10C6.48 22 2 17.52 2 12Zm9.12-3.79c0-.48.4-.88.88-.88s.87.4.87.88v4.42a.87.87 0 0 1-.87.87.879.879 0 0 1-.88-.87V8.21Zm.89 8.47c-.49 0-.88-.4-.88-.88s.39-.87.87-.87c.49 0 .88.39.88.87s-.39.88-.87.88Z', clipRule: 'evenodd' }) }));
+export default SvgAlertCircle;

package/dist/assets/icons/ArrowLeft.d.ts

@@ -0,0 +1,7 @@
+import type { SVGProps } from 'react';
+interface Props extends SVGProps<any> {
+    primarycolor?: string;
+    secondarycolor?: string;
+}
+declare const SvgArrowLeft: ({ primarycolor, secondarycolor, ...props }: Props) => import("react/jsx-runtime").JSX.Element;
+export default SvgArrowLeft;

package/dist/assets/icons/ArrowLeft.js

@@ -0,0 +1,3 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const SvgArrowLeft = ({ primarycolor, secondarycolor, ...props }) => (_jsxs("svg", { xmlns: 'http://www.w3.org/2000/svg', width: '18', height: '18', viewBox: '0 0 18 18', fill: secondarycolor || 'none', ...props, children: [_jsx("path", { d: 'M17.5 8.77466C17.5 9.15436 17.2178 9.46815 16.8518 9.51781L16.75 9.52466H1.74999C1.33577 9.52466 0.999987 9.18887 0.999987 8.77466C0.999987 8.39497 1.28214 8.08117 1.64822 8.03151L1.74999 8.02466H16.75C17.1642 8.02466 17.5 8.36045 17.5 8.77466Z', fill: primarycolor || '#000' }), _jsx("path", { d: 'M8.32897 14.2676C8.6225 14.5599 8.62352 15.0347 8.33126 15.3282C8.06556 15.5951 7.64895 15.6202 7.35487 15.403L7.2706 15.3305L1.2206 9.30653C0.952963 9.04005 0.928616 8.62193 1.14757 8.32786L1.22056 8.24363L7.27056 2.21863C7.56405 1.92635 8.03893 1.92733 8.33121 2.22083C8.59693 2.48765 8.62027 2.90436 8.40181 3.19752L8.32902 3.28149L2.81299 8.77536L8.32897 14.2676Z', fill: primarycolor || '#000' })] }));
+export default SvgArrowLeft;

package/dist/assets/icons/ArrowRight.d.ts

@@ -0,0 +1,7 @@
+import type { SVGProps } from 'react';
+interface Props extends SVGProps<any> {
+    primarycolor?: string;
+    secondarycolor?: string;
+}
+declare const SvgArrowRight: ({ primarycolor, secondarycolor, ...props }: Props) => import("react/jsx-runtime").JSX.Element;
+export default SvgArrowRight;