namirasoft-site-react 1.4.528 → 1.4.530

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/SKILL.md ADDED
@@ -0,0 +1,307 @@
1
+ ---
2
+ name: namirasoft-site-react
3
+ description: Use the namirasoft-site-react component library (NS* prefixed React components) when building UIs in projects that import "namirasoft-site-react". Covers form inputs (NSBoxString, NSBoxEmail, NSBoxPhone, NSBoxDate, NSBoxMoney, etc.), buttons (NSButton, NSButtonBlue/Green/Red), cards, dialogs, layouts, tables, charts, formatters, and routing. Trigger when the user adds or modifies UI in a project whose package.json depends on namirasoft-site-react, asks how to render a form field/button/dialog/table with NS components, or imports anything from "namirasoft-site-react".
4
+ ---
5
+
6
+ # namirasoft-site-react
7
+
8
+ A React component library published as `namirasoft-site-react` on npm. All components are prefixed `NS`. This skill teaches you how to pick the right component and wire its props correctly.
9
+
10
+ ## When this skill applies
11
+
12
+ Trigger when the project's `package.json` lists `namirasoft-site-react` as a dependency, or when the user imports anything from `"namirasoft-site-react"`. Skip otherwise — do not push these components on projects that use a different design system (MUI, Chakra, shadcn, etc.).
13
+
14
+ ## Cardinal rules
15
+
16
+ 1. **Prefer `NS*` components over raw HTML.** When designing or modifying a page, do not reach for `<div>`, `<span>`, `<a>`, `<button>`, `<input>`, `<table>`, `<form>`, `<h1..h6>`, `<ul>`/`<li>`, `<img>`, `<section>`, etc. The whole point of this library is reuse — every visible element should map to an `NS*` component. Specifically:
17
+ - layout: `NSLayout` / `NSSection` / `NSRow` / `NSColumn` / `NSSpace` / `NSPanel` instead of `<div>` + flex CSS
18
+ - text: `NSTitle` / `NSLabel` / `NSLineText` instead of `<h1>` / `<span>` / `<p>`
19
+ - links: `NSLink` (or `NSLinkBlue` / `NSLinkGreen` / `NSLinkRed`) instead of `<a>`
20
+ - actions: `NSButton` (or color variants) instead of `<button>`
21
+ - inputs: an `NSBox*` matching the data type instead of `<input>` / `<select>` / `<textarea>`
22
+ - lists: `NSListGrouped` / `NSRepeater` / `NSTable` instead of `<ul>` / `<table>`
23
+ - cards/tiles: `NSCard` / `NSTile` instead of bespoke `<div>` containers
24
+ - dialogs: `NSDialog` (or its variants) instead of a hand-rolled modal
25
+
26
+ Raw HTML is only acceptable when (a) no `NS*` equivalent exists, (b) you're rendering inside a component that explicitly takes `children: ReactNode` and a wrapper element is unavoidable, or (c) you're working with a third-party integration that requires it. When you do fall back to HTML, leave a one-line comment explaining why no `NS*` fit.
27
+
28
+ 2. **Always import from the package root**: `import { NSBoxString, NSButton } from "namirasoft-site-react";` — never deep-import from `dist/...`.
29
+ 3. **Every component accepts `IBaseComponentProps`**: `id?`, `name?`, `classList?: string[]`, `style?: React.CSSProperties`. Use `classList` (string array), not `className`.
30
+ 4. **NSBox\* inputs are class components with a ref-based imperative API**: hold a `React.createRef<NSBoxString>()` and call `ref.current?.getValue()` / `setValue(v)` / `setDisabled(b)`. They are not controlled inputs — pass `defaultValue`, read via ref.
31
+ 5. **Validation is built in**: every `NSBox*` requires `title: string` and `required: boolean`. `getValue()` throws if validation fails (call `getValue(false)` to skip the check).
32
+ 6. **Buttons take an `onClick` *object*, not a function**: `<NSButton onClick={{ action: (done) => { ...; done(); }, showLoading: true }} />`. The `done` callback hides the spinner.
33
+ 7. **CSS is bundled** — the package ships `.module.css` files alongside components. No separate stylesheet import is needed beyond what the package does internally.
34
+
35
+ ## Picking the right component
36
+
37
+ ### Form inputs (NSBox*)
38
+
39
+ All take `title` (label) and `required`. Choose by data type:
40
+
41
+ | Data | Component |
42
+ |---|---|
43
+ | Free text | `NSBoxString` |
44
+ | Long text | `NSBoxTextArea` |
45
+ | Email | `NSBoxEmail` |
46
+ | URL | `NSBoxURL` |
47
+ | Phone | `NSBoxPhone` (uses `react-phone-number-input`) |
48
+ | Password / secret | `NSBoxSensitive` |
49
+ | Whole number | `NSBoxInteger` |
50
+ | Decimal | `NSBoxDouble` |
51
+ | Currency | `NSBoxMoney` |
52
+ | Boolean (checkbox) | `NSBoxBoolean` |
53
+ | Multiple booleans | `NSBoxBooleans` |
54
+ | Radio group | `NSBoxRadio` |
55
+ | Enum / select | `NSBoxEnum` |
56
+ | Combo (select with search) | `NSBoxCombo` |
57
+ | Date only | `NSBoxDate` |
58
+ | Date + time | `NSBoxDateTime` |
59
+ | Time only | `NSBoxTime` |
60
+ | Time zone | `NSBoxTimeZone` |
61
+ | Duration | `NSBoxDuration` |
62
+ | File upload | `NSBoxFile` |
63
+ | IPv4 / IPv6 | `NSBoxIPV4`, `NSBoxIPV6` |
64
+ | Semver | `NSBoxVersion` |
65
+ | Search bar | `NSBoxSearch` |
66
+ | Entity reference (FK) | `NSBoxEntity` |
67
+ | Schema-driven dynamic field | `NSBoxDynamic`, `NSBoxDynamics`, `NSBoxSchemaBase`, `NSBoxSchemaVariable` |
68
+
69
+ If you need to reach for a field type not in this table, prefer composing from `NSBoxString` over inventing a new component.
70
+
71
+ ### Buttons & links
72
+
73
+ - `NSButton` — base button, takes `title`, optional `icon`, and the `onClick` object (see rule 5).
74
+ - `NSButtonBlue` / `NSButtonGreen` / `NSButtonRed` — semantic color variants (primary / success / destructive).
75
+ - `NSLink` — base link.
76
+ - `NSLinkBlue` / `NSLinkGreen` / `NSLinkRed` — semantic link variants.
77
+ - `NSMenuButton` — button that opens a menu.
78
+ - `NSMenuAction` — action menu item.
79
+
80
+ ### Layout & structure
81
+
82
+ - `NSLayout` — top-level page shell (header + footer + alerts + notifications + main). Requires `scope`, `logo`, `header.right`, `notifications`, `isLoggedIn`, and `notifier` (from `NSRouterMaker`). Use this once at the app root.
83
+ - `NSHeader`, `NSFooter`, `NSMegaMenu` — pieces of `NSLayout`. You usually don't render these directly; let `NSLayout` compose them.
84
+ - `NSSection`, `NSSectionTitle`, `NSSectionCards`, `NSSectionTiles` — vertical content blocks.
85
+ - `NSRow`, `NSColumn` — flex row/column.
86
+ - `NSSpace` — vertical/horizontal spacer (`size: NSSpaceSizeType.MINI | SMALL | ...`).
87
+ - `NSSplitter` — resizable split pane.
88
+ - `NSPanel`, `NSPanelAccordion` — bordered panels.
89
+ - `NSTabPage` — tabbed pages.
90
+ - `NSCard`, `NSCardScreenshot` — content cards with link.
91
+ - `NSTile` — clickable tile.
92
+
93
+ ### Data display
94
+
95
+ - `NSTable` — full-featured table with pagination, sorts, column visibility, xlsx export. Driven by `columns: TableColumnInfo[]` (formatter-based) and `getRows: (page, size, sorts) => Promise<{rows, count}>`.
96
+ - `NSPagination` — paginator.
97
+ - `NSListGrouped`, `NSListProduct` — list layouts.
98
+ - `NSRepeater`, `NSRepeaterNSTag`, `NSRepeaterNSBoxSchemaVariable` — render arrays of items.
99
+ - `NSTag` — chip/tag.
100
+ - `NSLabel`, `NSLabelErrorNotifier`, `NSLabelSensitive` — text labels.
101
+ - `NSID` — formatted ID display.
102
+ - `NSCopy`, `NSCopyBox` — copy-to-clipboard widgets.
103
+ - `NSElectronicCard` — credit-card-style display card.
104
+ - `NSEntityCardBackground` — backgrounded entity card.
105
+
106
+ ### Charts & gauges
107
+
108
+ - `NSChartColumn`, `NSChartDoughnut`, `NSChartPie`, `NSChartRange`, `NSChartTable` — chart.js / antd-charts wrappers.
109
+ - `NSGauge`, `NSGaugeNumber`, `NSGaugeDate` — single-metric gauges.
110
+ - `NSProgressBar`, `NSRange` — progress / range bars.
111
+ - `NSTimelineMonthly` — monthly timeline.
112
+
113
+ ### Dialogs
114
+
115
+ - `NSDialog` — base dialog. Takes `onClose: () => void` and `children`. Render conditionally based on local state.
116
+ - `NSDialogDelete` — confirm-delete dialog.
117
+ - `NSDialogInfo` — info/alert dialog.
118
+ - `NSDialogPageSelection` — page-selection picker.
119
+ - `NSDialogBox`, `NSDialogBoxString`, `NSDialogBoxDate`, `NSDialogBoxDateTime`, `NSDialogBoxPhone` — single-field edit dialogs.
120
+ - `NSInfo` — inline info popover (smaller than a dialog).
121
+
122
+ ### Bars & banners
123
+
124
+ - `NSBanner` — page-top banner.
125
+ - `NSBarTitle` — page title bar.
126
+ - `NSBarAction` — action bar.
127
+ - `NSBarAlert` — alert strip (driven by `isVisible()` predicate).
128
+ - `NSBarNotification` — notification toast strip (managed by the `NSNotifier`).
129
+
130
+ ### Filters
131
+
132
+ - `NSFilterBox`, `NSFilterBoxItems`, `NSFilterItem` — query/filter UI for tables and lists.
133
+
134
+ ### Misc / state
135
+
136
+ - `NSLoading` — spinner. Takes `small`, `hideTitle`, `hideDescription`.
137
+ - `NSNoData` — empty-state placeholder.
138
+ - `NSDownTimer` — countdown.
139
+ - `NSDownload` — download button/link.
140
+ - `NSProductSearch` — product search dropdown (uses `ProductCacheService`).
141
+ - `NSLine`, `NSLineText` — separators.
142
+ - `NSTitle` — heading.
143
+
144
+ ### Pages
145
+
146
+ - `NSImplementing` — "this feature is being implemented" page.
147
+ - `NSUpdating` — "this feature is updating" page.
148
+ - `NSNotFoundPage` — 404 page. Use as the catch-all route.
149
+
150
+ ## Formatters (for NSTable columns)
151
+
152
+ Import and instantiate a `BaseColumnFormatter` subclass per column. Pick by data type:
153
+
154
+ `StringFormatter`, `IntegerFormatter`, `FloatFormatter`, `MoneyFormatter`, `PercentFormatter`, `BooleanFormatter`, `EnumFormatter`, `DateFormatter`, `DateTimeFormatter`, `TimeFormatter`, `DurationFormatter`, `EmailFormatter`, `PhoneFormatter`, `URLFormatter`, `IPFormatter`, `IDFormatter`, `JsonFormatter`, `BytesFormatter`, `SensitiveFormatter`, `BackColorFormatter`, `ForeColorFormatter`, `BaseURLImageFormatter`, `UnknowFormatter` (fallback).
155
+
156
+ ## Routing
157
+
158
+ - `NSRouterMaker` — wraps a `NSRouterMakerComponent` with a `setState` callback and storage. Produces an `onRender()` that returns the routed JSX and provides a `NSNotifier` to children.
159
+ - `NSNotifier` — lives on the `notifier` prop passed through `NSLayout` and friends. Methods: `addNotification`, `delNotification`, `onChangeState`.
160
+ - `NSRouterMakerProps` — interface that exposes `notifier: NSNotifier` to a component.
161
+
162
+ The `NSBaseMetaDatabase.getServerBaseURL` resolver is set up at module load so `Namirasoft<X>` package names map to `REACT_APP_BASE_URL_<X>` env vars (snake-uppercased). Define those env vars in `.env`.
163
+
164
+ ## Utilities (named exports from the root)
165
+
166
+ - `Validator` — static methods: `getError(title, value, props)`, `getErrorString(title, value, props)`. Used internally by NSBox\* but exposed for custom validation.
167
+ - `NSBoxBuilder` — schema-driven NSBox factory.
168
+ - `ProductCacheService` — async cache for product lookups (used by `NSProductSearch`).
169
+ - `CopyToClipboard` — programmatic copy.
170
+ - `EncryptionOperation` — client-side encryption helpers.
171
+ - `Color` — color palette / utilities.
172
+
173
+ ## Canonical examples
174
+
175
+ ### Form with three fields and a submit
176
+
177
+ ```tsx
178
+ import React, { createRef } from "react";
179
+ import { NSBoxString, NSBoxEmail, NSBoxPhone, NSButtonBlue } from "namirasoft-site-react";
180
+
181
+ export function ContactForm() {
182
+ const nameRef = createRef<NSBoxString>();
183
+ const emailRef = createRef<NSBoxEmail>();
184
+ const phoneRef = createRef<NSBoxPhone>();
185
+
186
+ return (
187
+ <>
188
+ <NSBoxString ref={nameRef} title="Full Name" required min_length={2} max_length={120} />
189
+ <NSBoxEmail ref={emailRef} title="Email" required />
190
+ <NSBoxPhone ref={phoneRef} title="Phone" required={false} />
191
+ <NSButtonBlue
192
+ title="Submit"
193
+ onClick={{
194
+ action: (done) => {
195
+ try {
196
+ const payload = {
197
+ name: nameRef.current?.getValue(),
198
+ email: emailRef.current?.getValue(),
199
+ phone: phoneRef.current?.getValue(false),
200
+ };
201
+ // ... submit payload
202
+ } finally {
203
+ done();
204
+ }
205
+ },
206
+ showLoading: true,
207
+ }}
208
+ />
209
+ </>
210
+ );
211
+ }
212
+ ```
213
+
214
+ Notes:
215
+ - `getValue()` throws on validation failure and surfaces the error inline; that's intentional — wrap in try/finally so the spinner clears.
216
+ - Use `getValue(false)` only for optional fields where you want the raw value without validation.
217
+ - Don't try to read NSBox\* values via `useState` + `onChange` — the imperative ref API is the supported path.
218
+
219
+ ### Confirm-delete dialog
220
+
221
+ `NSDialogDelete` extends `NSDialogInfoProps` and takes `onYes` / `onNo` — each a `NSButtonOnClickProps` object (`{ action, showLoading? }`), not a plain function. `show_as_code` is required (set `false` for plain text).
222
+
223
+ ```tsx
224
+ import React, { useState } from "react";
225
+ import { NSButtonRed, NSDialogDelete } from "namirasoft-site-react";
226
+
227
+ export function DeleteRow({ onDelete }: { onDelete: () => Promise<void> }) {
228
+ const [open, setOpen] = useState(false);
229
+ return (
230
+ <>
231
+ <NSButtonRed title="Delete" onClick={{ action: (d) => { setOpen(true); d(); } }} />
232
+ {open && (
233
+ <NSDialogDelete
234
+ title="Delete record?"
235
+ description="This cannot be undone."
236
+ show_as_code={false}
237
+ onClose={() => setOpen(false)}
238
+ onYes={{
239
+ action: async (done) => {
240
+ try { await onDelete(); setOpen(false); }
241
+ finally { done(); }
242
+ },
243
+ showLoading: true,
244
+ }}
245
+ onNo={{ action: (done) => { setOpen(false); done(); } }}
246
+ />
247
+ )}
248
+ </>
249
+ );
250
+ }
251
+ ```
252
+
253
+ ### Table with formatted columns
254
+
255
+ ```tsx
256
+ import { NSTable, IntegerFormatter, StringFormatter, DateTimeFormatter, TableColumnInfo } from "namirasoft-site-react";
257
+
258
+ const table = { name: "user", text: "User" };
259
+ const columns: TableColumnInfo[] = [
260
+ { table, index: 0, name: "id", text: "ID", formatter: new IntegerFormatter() },
261
+ { table, index: 1, name: "name", text: "Name", formatter: new StringFormatter() },
262
+ { table, index: 2, name: "created_at", text: "Created", formatter: new DateTimeFormatter() },
263
+ ];
264
+
265
+ <NSTable
266
+ name="users"
267
+ checkbox={false}
268
+ columns={columns}
269
+ getRows={async (page, size, sorts) => {
270
+ const res = await api.users.list({ page, size, sorts });
271
+ return { rows: res.items, count: res.total };
272
+ }}
273
+ getRowKey={(row) => String(row.value.id)}
274
+ />
275
+ ```
276
+
277
+ ### App shell
278
+
279
+ ```tsx
280
+ <NSLayout
281
+ scope="MyApp"
282
+ logo="/logo.png"
283
+ notifier={notifier}
284
+ isLoggedIn={() => !!session}
285
+ header={{ right: { /* IHeaderRightProps */ }, left: { title: "Dashboard" } }}
286
+ notifications={notifications}
287
+ >
288
+ {pageContent}
289
+ </NSLayout>
290
+ ```
291
+
292
+ ## Common mistakes to avoid
293
+
294
+ - ❌ Reaching for raw HTML (`<div>`, `<a>`, `<button>`, `<input>`, `<table>`, etc.) when an `NS*` equivalent exists — see Cardinal rule #1.
295
+ - ❌ Passing `className="foo"` — use `classList={["foo"]}`.
296
+ - ❌ Treating NSBox\* as controlled (`value`/`onChange`) — use refs + `defaultValue`.
297
+ - ❌ Passing a function to `NSButton.onClick` — must be `{ action, showLoading? }`.
298
+ - ❌ Forgetting to call `done()` in the button action — the spinner will hang forever.
299
+ - ❌ Importing from `"namirasoft-site-react/dist/..."` — only the root path is supported.
300
+ - ❌ Mixing this library with another design system on the same screen — visual conventions clash.
301
+ - ❌ Inventing a new `NSBox<Type>` when an existing one fits — check the data-type table first.
302
+
303
+ ## Peer expectations
304
+
305
+ The package depends on (and re-exports types from) `namirasoft-core`, `namirasoft-schema`, `namirasoft-site`, `namirasoft-site-map`, `namirasoft-api-link`, `namirasoft-api-product`. If you import a type like `BaseMetaTable`, `SortItem`, `IStorage`, or `NamingConvention`, it lives in `namirasoft-core` — import it from there, not from `namirasoft-site-react`.
306
+
307
+ React 18 and `react-router-dom` 7 are required peers. The library uses `react-app-rewired` for its own dev/test scripts, but consumers don't need it.
package/SKILLS.md ADDED
@@ -0,0 +1,188 @@
1
+ ---
2
+ name: namirasoft-site-react
3
+ description: Use when working inside the Namirasoft Site React NPM Package or when any Namirasoft portal frontend imports from namirasoft-site-react. Covers all 40+ NSBox* form/display components, NSBoxBuilder, routing, formatters, and Ant Design integration.
4
+ ---
5
+
6
+ # Namirasoft Site React Package Skill
7
+
8
+ ## Trigger
9
+ Use this skill when working inside `d:\01 - Code Base\Namira\Package\TypeScript\Namirasoft Site React NPM Package` or when any Namirasoft portal frontend imports from `namirasoft-site-react`.
10
+
11
+ ## Package Identity
12
+ - **npm name:** `namirasoft-site-react`
13
+ - **Entry point:** `dist/main.js` / React app entry: `src/index.tsx`
14
+ - **Purpose:** React UI component library and application framework for Namirasoft portal interfaces. 40+ `NSBox*` form/display components, routing, data formatting, and portal infrastructure built on Ant Design + Bootstrap.
15
+
16
+ ## Key Dependencies
17
+ `react ^18`, `react-dom`, `react-router-dom ^7`, `antd ^6`, `@ant-design/icons ^6`, `react-bootstrap ^2`, `bootstrap`, `chart.js`, `react-chartjs-2`, `axios`, `@uiw/react-json-view`, `namirasoft-core`, `namirasoft-schema`, `namirasoft-site`, `namirasoft-site-map`, `namirasoft-api-product`, `namirasoft-api-link`
18
+
19
+ ## Source Structure
20
+
21
+ ```
22
+ src/
23
+ ├── components/ # 40+ NSBox* components
24
+ ├── pages/ # Page-level components
25
+ ├── props/ # Prop type interfaces
26
+ ├── routing/ # Route definitions
27
+ ├── formatter/ # Data formatters
28
+ ├── App.tsx # Main application component
29
+ ├── main.ts # Module entry (for npm consumers)
30
+ └── index.tsx # React app entry
31
+ ```
32
+
33
+ ## NSBox Component Library
34
+
35
+ All input/display components follow the `NSBox*` naming convention. They are built on top of Ant Design and handle type-specific rendering, validation, and editing.
36
+
37
+ ### Boolean
38
+ | Component | Description |
39
+ |-----------|-------------|
40
+ | `NSBoxBoolean` | Toggle/checkbox for boolean values |
41
+
42
+ ### Text & String
43
+ | Component | Description |
44
+ |-----------|-------------|
45
+ | `NSBoxString` | Text input |
46
+ | `NSBoxEmail` | Email input with format validation |
47
+ | `NSBoxURL` | URL input |
48
+ | `NSBoxPhone` | Phone number input (E.164) |
49
+ | `NSBoxColor` | Color picker (hex) |
50
+ | `NSBoxFont` | Font name selector |
51
+ | `NSBoxVersion` | SemVer string input |
52
+ | `NSBoxFilePath` | File path input |
53
+ | `NSBoxIPV4` | IPv4 address input |
54
+ | `NSBoxIPV6` | IPv6 address input |
55
+ | `NSBoxIPV4Range` | IPv4 CIDR range input |
56
+ | `NSBoxIPV6Range` | IPv6 CIDR range input |
57
+
58
+ ### Numeric
59
+ | Component | Description |
60
+ |-----------|-------------|
61
+ | `NSBoxInteger` | Integer number input |
62
+ | `NSBoxFloat` | Float input |
63
+ | `NSBoxDouble` | Double input |
64
+ | `NSBoxDecimal` | Decimal/arbitrary precision input |
65
+ | `NSBoxBigInt` | BigInt input |
66
+ | `NSBoxMoney` | Currency amount input |
67
+
68
+ ### Date & Time
69
+ | Component | Description |
70
+ |-----------|-------------|
71
+ | `NSBoxDate` | Date picker (YYYY-MM-DD) |
72
+ | `NSBoxDateTime` | Date + time picker |
73
+ | `NSBoxTime` | Time picker (HH:mm:ss) |
74
+ | `NSBoxDuration` | Duration input (ISO 8601) |
75
+ | `NSBoxTimeZone` | IANA timezone selector |
76
+
77
+ ### Selection
78
+ | Component | Description |
79
+ |-----------|-------------|
80
+ | `NSBoxCombo` | Dropdown/combo box (enum values) |
81
+ | `NSBoxEntity` | Entity reference selector (FK-like dropdown) |
82
+ | `NSBoxEnum` | Enum display/input |
83
+
84
+ ### Complex
85
+ | Component | Description |
86
+ |-----------|-------------|
87
+ | `NSBoxArray` | Array of items editor |
88
+ | `NSBoxAny` | Unconstrained value input |
89
+ | `NSBoxBuilder` | Large composite form builder (35KB). Generates entire forms from schema definitions. |
90
+
91
+ ## Utilities
92
+ | Export | Description |
93
+ |--------|-------------|
94
+ | `Validator` | Client-side validation (delegates to `namirasoft-schema` JoiValidator) |
95
+ | `EncryptionOperation` | Client-side AES encrypt/decrypt |
96
+ | `Color` | Color manipulation helpers |
97
+ | `CopyToClipboard` | Copy text to clipboard |
98
+ | `ProductCacheService` | Caches product/API metadata on the client side |
99
+
100
+ ## Common Usage Patterns
101
+
102
+ ### Using an NSBox component
103
+ ```tsx
104
+ import { NSBoxString } from 'namirasoft-site-react';
105
+
106
+ function UserForm() {
107
+ const [email, setEmail] = React.useState('');
108
+
109
+ return (
110
+ <NSBoxEmail
111
+ value={email}
112
+ onChange={setEmail}
113
+ label="Email Address"
114
+ required
115
+ />
116
+ );
117
+ }
118
+ ```
119
+
120
+ ### Using NSBoxBuilder (schema-driven forms)
121
+ ```tsx
122
+ import { NSBoxBuilder } from 'namirasoft-site-react';
123
+ import { ApplicationSchema } from 'namirasoft-schema';
124
+
125
+ function AutoForm({ schema, data, onChange }) {
126
+ return (
127
+ <NSBoxBuilder
128
+ schema={schema}
129
+ data={data}
130
+ onChange={onChange}
131
+ />
132
+ );
133
+ }
134
+ ```
135
+
136
+ ### Using NSBoxCombo (enum dropdown)
137
+ ```tsx
138
+ import { NSBoxCombo } from 'namirasoft-site-react';
139
+
140
+ <NSBoxCombo
141
+ value={status}
142
+ onChange={setStatus}
143
+ options={[
144
+ { label: 'Active', value: 'active' },
145
+ { label: 'Inactive', value: 'inactive' },
146
+ ]}
147
+ label="Status"
148
+ />
149
+ ```
150
+
151
+ ### Routing setup
152
+ ```tsx
153
+ // src/routing/ defines routes using react-router-dom v7
154
+ import { createBrowserRouter, RouterProvider } from 'react-router-dom';
155
+ import { routes } from './routing/routes';
156
+
157
+ const router = createBrowserRouter(routes);
158
+
159
+ function App() {
160
+ return <RouterProvider router={router} />;
161
+ }
162
+ ```
163
+
164
+ ### Formatters
165
+ ```tsx
166
+ import { formatDate, formatMoney, formatDuration } from 'namirasoft-site-react/formatter';
167
+
168
+ formatDate('2024-01-15'); // → 'Jan 15, 2024'
169
+ formatMoney(12345.67, 'USD'); // → '$12,345.67'
170
+ formatDuration('PT1H30M'); // → '1h 30m'
171
+ ```
172
+
173
+ ## Build Configuration
174
+ Uses `react-app-rewired` to customize CRA build without ejecting. Static assets (CSS, HTML, images) are copied to `dist/` using `copyfiles`.
175
+
176
+ ```bash
177
+ npm run start # dev server (CRA)
178
+ npm run build # production build → dist/
179
+ npm run build:lib # build library module → dist/main.js
180
+ ```
181
+
182
+ ## Conventions
183
+ - Always use `NSBox*` components for form inputs — never raw Ant Design/Bootstrap inputs directly.
184
+ - Each `NSBox*` component corresponds to a type schema in `namirasoft-schema` — match them.
185
+ - `NSBoxBuilder` is the canonical way to render schema-driven forms — use it instead of writing manual form layouts when a full schema is available.
186
+ - Component props always include `value`, `onChange`, `label`, and `required` as standard fields.
187
+ - All data display formatting goes through `formatter/` — no ad-hoc `Date.toLocaleDateString()` calls.
188
+ - `ProductCacheService` should be initialized once at app startup, not per-component.
package/dist/App.d.ts CHANGED
@@ -1,13 +1,14 @@
1
1
  import 'bootstrap/dist/css/bootstrap.min.css';
2
2
  import { Component } from 'react';
3
3
  import './App.css';
4
- import { NSBoxSensitive } from './main';
5
4
  interface AppProps {
6
5
  }
7
6
  interface AppState {
7
+ dialog_show: boolean;
8
+ dialog_loading: boolean;
8
9
  }
9
10
  export declare class App extends Component<AppProps, AppState> {
10
- ref: import("react").RefObject<NSBoxSensitive>;
11
+ private repeaterAdd;
11
12
  constructor(props: AppProps);
12
13
  render(): import("react/jsx-runtime").JSX.Element;
13
14
  }
package/dist/App.js CHANGED
@@ -7,23 +7,24 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
7
7
  step((generator = generator.apply(thisArg, _arguments || [])).next());
8
8
  });
9
9
  };
10
- import { jsx as _jsx } from "react/jsx-runtime";
10
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
11
11
  import 'bootstrap/dist/css/bootstrap.min.css';
12
- import { EncodingOperation, IStorageLocal } from 'namirasoft-core';
13
- import { NamirasoftMap } from 'namirasoft-site-map';
14
- import { Component, createRef } from 'react';
12
+ import { Component } from 'react';
15
13
  import './App.css';
16
14
  import { NSLayout } from './components/NSLayout';
17
- import { EmailFormatter, EncryptionOperation, IDFormatter, IntegerFormatter, NSColumn, NSTable, PhoneFormatter, SensitiveFormatter, StringFormatter, StringFormatterSizeType } from './main';
15
+ import { PercentFormatter } from './formatter/PercentFormatter';
16
+ import { NSBoxSensitive, NSBoxString, NSButtonBlue, NSColumn, NSRepeater, NSTable, StringFormatter, URLFormatter } from './main';
18
17
  export class App extends Component {
19
18
  constructor(props) {
20
19
  super(props);
21
- this.ref = createRef();
22
- this.state = {};
20
+ this.repeaterAdd = null;
21
+ this.state = {
22
+ dialog_show: false,
23
+ dialog_loading: false,
24
+ };
23
25
  }
26
+ ;
24
27
  render() {
25
- let namirasoft = new NamirasoftMap();
26
- EncryptionOperation.AES256GCMEncrypt("1234", EncodingOperation.Base64Encode("")).then(console.log);
27
28
  return (_jsx(NSLayout, { header: {
28
29
  right: {
29
30
  icons: [
@@ -34,92 +35,23 @@ export class App extends Component {
34
35
  }
35
36
  ],
36
37
  },
37
- mega_menu: true
38
- }, isLoggedIn: () => true, logo: 'https://static.namirasoft.com/image/namirasoft/access/logo/base.png', background: { image: "https://static.namirasoft.com/image/namirasoft/access/background/base.svg" }, notifications: [], notifier: {}, scope: '', children: _jsx(NSColumn, { style: { alignItems: "center" }, children: _jsx(NSTable, { name: 'users', checkbox: true, getRows: () => __awaiter(this, void 0, void 0, function* () {
39
- return ({
40
- count: 10,
41
- rows: [
42
- {
43
- id: ["prd-c7836310e7e54170"], first_name: "Amin", last_name: "Pasban", gender: "Male", age: 27,
44
- phone: "09117579093", email: "amin.cj0077@gmail.com",
45
- password: "1234", sensitive: false,
46
- },
47
- {
48
- id: ["prd-c7836310e7e54171"], first_name: "Sara", last_name: "Moradi", gender: "Female", age: 24,
49
- phone: "09123456781", email: "sara.moradi@example.com",
50
- password: "CKaKg94ACeR56eqJtZFXgidZQ+lbRTOuZfHxRjaqlPpMO+tWWnYdnEinONB+1oUWvLlLvIj0", sensitive: true,
51
- },
52
- {
53
- id: ["prd-c7836310e7e54172"], first_name: "Reza", last_name: "Karimi", gender: "Male", age: 31,
54
- phone: "09129876542", email: "reza.karimi@example.com",
55
- password: "1234", sensitive: false,
56
- },
57
- {
58
- id: ["prd-c7836310e7e54173"], first_name: "Niloofar", last_name: "Ahmadi", gender: "Female", age: 29,
59
- phone: "09351234567", email: "niloofar.ahmadi@example.com",
60
- password: "gNYeNtQQAPvc8SqiT7hQG77LjowyOsTM+oOX6J0GBv+XrYakhu7u9FDEi80yvgKjlK7gKMy1", sensitive: true,
61
- },
62
- {
63
- id: ["prd-c7836310e7e54174"], first_name: "Hossein", last_name: "Bagheri", gender: "Male", age: 35,
64
- phone: "09134561234", email: "hossein.bagheri@example.com",
65
- password: "1234", sensitive: false,
66
- },
67
- {
68
- id: ["prd-c7836310e7e54175"], first_name: "Maryam", last_name: "Shahbazi", gender: "Female", age: 26,
69
- phone: "09141239876", email: "maryam.shahbazi@example.com",
70
- password: "iKg0wY9m9xeUWSzx1UsVY4QBqR7CAlIuX3JAXmN9Y3tAdE2g/6jIkREh1xOVN3BV+3mNVgJp", sensitive: true,
71
- },
72
- {
73
- id: ["prd-c7836310e7e54176"], first_name: "Ali", last_name: "Rostami", gender: "Male", age: 28,
74
- phone: "09151237654", email: "ali.rostami@example.com",
75
- password: "1234", sensitive: false,
76
- },
77
- {
78
- id: ["prd-c7836310e7e54177"], first_name: "Fatemeh", last_name: "Jafari", gender: "Female", age: 30,
79
- phone: "09361234589", email: "fatemeh.jafari@example.com",
80
- password: "Z2SuGaena/4oXcvf0RL5Fh6dX4OqvwxY0RD9gnp07zwLYS1PJpE2Ftr9WiZYlwcKsOCRptiI", sensitive: true,
81
- },
82
- {
83
- id: ["prd-c7836310e7e54178"], first_name: "Mohammad", last_name: "Esfandiari", gender: "Male", age: 33,
84
- phone: "09162348752", email: "mohammad.esfandiari@example.com",
85
- password: "1234", sensitive: false,
86
- },
87
- {
88
- id: ["prd-c7836310e7e54179"], first_name: "Elham", last_name: "Khosravi", gender: "Female", age: 25,
89
- phone: "09203456781", email: "elham.khosravi@example.com",
90
- password: "G3E9av/PnhcCZMmU8t342TZbTmyxP0efWI9gV7rfPfVLEtekQoDmExdBP/Y61m8BFQHNgoFJ", sensitive: true,
91
- },
92
- {
93
- id: ["prd-c7836310e7e54180"], first_name: "Mohammad", last_name: "Esfandiari", gender: "Male", age: 33,
94
- phone: "09162348752", email: "mohammad.esfandiari@example.com",
95
- password: "1234", sensitive: false,
96
- },
97
- {
98
- id: ["prd-c7836310e7e54181"], first_name: "Elham", last_name: "Khosravi", gender: "Female", age: 25,
99
- phone: "09203456781", email: "elham.khosravi@example.com",
100
- password: "I69kFc3BYEOjf8tdbWxFlV1CTpfSGkVfRx/s54YoNeL7AO+321NF0ZmHEb+2c2i1vA8irJDw", sensitive: true,
101
- },
102
- ]
103
- });
104
- }), getRowKey: (item) => item.value.id[0], columns: [
105
- { index: 0, name: "id", text: "ID", table: { name: "users", text: "users" }, formatter: new IDFormatter(namirasoft, new IStorageLocal()) },
106
- { index: 1, name: "first_name", text: "First Name", table: { name: "users", text: "users" }, formatter: new StringFormatter(StringFormatterSizeType.TwoWords) },
107
- { index: 2, name: "last_name", text: "Last Name", table: { name: "users", text: "users" }, formatter: new StringFormatter(StringFormatterSizeType.TwoWords) },
108
- { index: 3, name: "gender", text: "Gender", table: { name: "users", text: "users" }, formatter: new StringFormatter(StringFormatterSizeType.TwoWords) },
109
- { index: 4, name: "age", text: "Age", table: { name: "users", text: "users" }, formatter: new IntegerFormatter() },
110
- {
111
- index: 4, name: "password", text: "Password", table: { name: "users", text: "users" },
112
- formatter: new SensitiveFormatter((value) => __awaiter(this, void 0, void 0, function* () {
113
- let decrypted = yield EncryptionOperation.AES256GCMDecrypt("1234", value);
114
- let decoded = EncodingOperation.Base64Decode(decrypted);
115
- return decoded;
116
- }), (_col, row) => {
117
- return row.value.sensitive;
118
- })
119
- },
120
- { index: 6, name: "phone", text: "Phone Number", table: { name: "users", text: "users" }, formatter: new PhoneFormatter() },
121
- { index: 7, name: "email", text: "Email Address", table: { name: "users", text: "users" }, formatter: new EmailFormatter() },
122
- ], scroll: false }) }) }));
38
+ mega_menu: true,
39
+ onCollapse: () => { },
40
+ }, isLoggedIn: () => true, logo: 'https://static.namirasoft.com/image/namirasoft/access/logo/base.png', background: { image: "https://static.namirasoft.com/image/namirasoft/access/background/base.svg" }, notifications: [], notifier: {}, scope: '', children: _jsxs(NSColumn, { style: { alignItems: "center" }, children: [_jsx(NSTable, { name: "", checkbox: true, columns: [
41
+ { index: 0, name: "title", text: "Title", formatter: new StringFormatter(), table: { name: "", text: "" } },
42
+ { index: 1, name: "percentage", text: "Percentage", formatter: new PercentFormatter(), table: { name: "", text: "" } },
43
+ { index: 2, name: "url", text: "URL", formatter: new URLFormatter(), table: { name: "", text: "" } },
44
+ ], getRowKey: (item) => item.value.id, getRows: () => __awaiter(this, void 0, void 0, function* () {
45
+ return {
46
+ count: 2,
47
+ rows: [
48
+ { id: "1", title: "Amin", percentage: 19, url: "https://example.com/amin" },
49
+ { id: "2", title: "Negar", percentage: 21, url: "example.com/negar" },
50
+ ]
51
+ };
52
+ }), getRowCheckboxDisabled: row => {
53
+ return row.value.percentage < 20;
54
+ } }), _jsx(NSRepeater, { title: "Items (external add)", required: false, onExternalAddRef: (add) => { this.repeaterAdd = add; }, max: 3, createItem: (_gIndex, lIndex, ref, onChange, onDelete) => _jsx(NSBoxString, { ref: ref, title: `Item ${lIndex + 1}`, required: false, onChanged: onChange, menu: { builtin: { delete: { enabled: onDelete != null, onDelete: () => onDelete === null || onDelete === void 0 ? void 0 : onDelete(lIndex) } }, items: [] } }), getValue: (item, checkError) => item.getValue(checkError), setValue: (item, _index, value, callback) => item.setValue(value !== null && value !== void 0 ? value : null, callback), isEmpty: (_item, value) => !value || value.trim() === '' }), _jsx(NSButtonBlue, { title: "Add Item", onClick: { action: (done) => { var _a; (_a = this.repeaterAdd) === null || _a === void 0 ? void 0 : _a.call(this); done(); } } }), _jsx(NSBoxSensitive, { required: true, title: "Sensitive" })] }) }));
123
55
  }
124
56
  }
125
57
  //# sourceMappingURL=App.js.map