namirasoft-site-react 1.5.14 → 1.5.16

package/SKILL.md

@@ -1,307 +1,307 @@
----
-name: namirasoft-site-react
-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".
----
-
-# namirasoft-site-react
-
-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.
-
-## When this skill applies
-
-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.).
-
-## Cardinal rules
-
-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:
-    - layout: `NSLayout` / `NSSection` / `NSRow` / `NSColumn` / `NSSpace` / `NSPanel` instead of `<div>` + flex CSS
-    - text: `NSTitle` / `NSLabel` / `NSLineText` instead of `<h1>` / `<span>` / `<p>`
-    - links: `NSLink` (or `NSLinkBlue` / `NSLinkGreen` / `NSLinkRed`) instead of `<a>`
-    - actions: `NSButton` (or color variants) instead of `<button>`
-    - inputs: an `NSBox*` matching the data type instead of `<input>` / `<select>` / `<textarea>`
-    - lists: `NSListGrouped` / `NSRepeater` / `NSTable` instead of `<ul>` / `<table>`
-    - cards/tiles: `NSCard` / `NSTile` instead of bespoke `<div>` containers
-    - dialogs: `NSDialog` (or its variants) instead of a hand-rolled modal
-
-   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.
-
-2. **Always import from the package root**: `import { NSBoxString, NSButton } from "namirasoft-site-react";` — never deep-import from `dist/...`.
-3. **Every component accepts `IBaseComponentProps`**: `id?`, `name?`, `classList?: string[]`, `style?: React.CSSProperties`. Use `classList` (string array), not `className`.
-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.
-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).
-6. **Buttons take an `onClick` *object*, not a function**: `<NSButton onClick={{ action: (done) => { ...; done(); }, showLoading: true }} />`. The `done` callback hides the spinner.
-7. **CSS is bundled** — the package ships `.module.css` files alongside components. No separate stylesheet import is needed beyond what the package does internally.
-
-## Picking the right component
-
-### Form inputs (NSBox*)
-
-All take `title` (label) and `required`. Choose by data type:
-
-| Data | Component |
-|---|---|
-| Free text | `NSBoxString` |
-| Long text | `NSBoxTextArea` |
-| Email | `NSBoxEmail` |
-| URL | `NSBoxURL` |
-| Phone | `NSBoxPhone` (uses `react-phone-number-input`) |
-| Password / secret | `NSBoxSensitive` |
-| Whole number | `NSBoxInteger` |
-| Decimal | `NSBoxDouble` |
-| Currency | `NSBoxMoney` |
-| Boolean (checkbox) | `NSBoxBoolean` |
-| Multiple booleans | `NSBoxBooleans` |
-| Radio group | `NSBoxRadio` |
-| Enum / select | `NSBoxEnum` |
-| Combo (select with search) | `NSBoxCombo` |
-| Date only | `NSBoxDate` |
-| Date + time | `NSBoxDateTime` |
-| Time only | `NSBoxTime` |
-| Time zone | `NSBoxTimeZone` |
-| Duration | `NSBoxDuration` |
-| File upload | `NSBoxFile` |
-| IPv4 / IPv6 | `NSBoxIPV4`, `NSBoxIPV6` |
-| Semver | `NSBoxVersion` |
-| Search bar | `NSBoxSearch` |
-| Entity reference (FK) | `NSBoxEntity` |
-| Schema-driven dynamic field | `NSBoxDynamic`, `NSBoxDynamics`, `NSBoxSchemaBase`, `NSBoxSchemaVariable` |
-
-If you need to reach for a field type not in this table, prefer composing from `NSBoxString` over inventing a new component.
-
-### Buttons & links
-
-- `NSButton` — base button, takes `title`, optional `icon`, and the `onClick` object (see rule 5).
-- `NSButtonBlue` / `NSButtonGreen` / `NSButtonRed` — semantic color variants (primary / success / destructive).
-- `NSLink` — base link.
-- `NSLinkBlue` / `NSLinkGreen` / `NSLinkRed` — semantic link variants.
-- `NSMenuButton` — button that opens a menu.
-- `NSMenuAction` — action menu item.
-
-### Layout & structure
-
-- `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.
-- `NSHeader`, `NSFooter`, `NSMegaMenu` — pieces of `NSLayout`. You usually don't render these directly; let `NSLayout` compose them.
-- `NSSection`, `NSSectionTitle`, `NSSectionCards`, `NSSectionTiles` — vertical content blocks.
-- `NSRow`, `NSColumn` — flex row/column.
-- `NSSpace` — vertical/horizontal spacer (`size: NSSpaceSizeType.MINI | SMALL | ...`).
-- `NSSplitter` — resizable split pane.
-- `NSPanel`, `NSPanelAccordion` — bordered panels.
-- `NSTabPage` — tabbed pages.
-- `NSCard`, `NSCardScreenshot` — content cards with link.
-- `NSTile` — clickable tile.
-
-### Data display
-
-- `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}>`.
-- `NSPagination` — paginator.
-- `NSListGrouped`, `NSListProduct` — list layouts.
-- `NSRepeater`, `NSRepeaterNSTag`, `NSRepeaterNSBoxSchemaVariable` — render arrays of items.
-- `NSTag` — chip/tag.
-- `NSLabel`, `NSLabelErrorNotifier`, `NSLabelSensitive` — text labels.
-- `NSID` — formatted ID display.
-- `NSCopy`, `NSCopyBox` — copy-to-clipboard widgets.
-- `NSElectronicCard` — credit-card-style display card.
-- `NSEntityCardBackground` — backgrounded entity card.
-
-### Charts & gauges
-
-- `NSChartBar`, `NSChartDoughnut`, `NSChartPie`, `NSChartRange`, `NSTableChart` — chart.js / antd-charts wrappers.
-- `NSGauge`, `NSGaugeNumber`, `NSGaugeDate` — single-metric gauges.
-- `NSProgressBar`, `NSRange` — progress / range bars.
-- `NSTimelineMonthly` — monthly timeline.
-
-### Dialogs
-
-- `NSDialog` — base dialog. Takes `onClose: () => void` and `children`. Render conditionally based on local state.
-- `NSDialogDelete` — confirm-delete dialog.
-- `NSDialogInfo` — info/alert dialog.
-- `NSDialogPageSelection` — page-selection picker.
-- `NSDialogBox`, `NSDialogBoxString`, `NSDialogBoxDate`, `NSDialogBoxDateTime`, `NSDialogBoxPhone` — single-field edit dialogs.
-- `NSInfo` — inline info popover (smaller than a dialog).
-
-### Bars & banners
-
-- `NSBanner` — page-top banner.
-- `NSBarTitle` — page title bar.
-- `NSBarAction` — action bar.
-- `NSBarAlert` — alert strip (driven by `isVisible()` predicate).
-- `NSBarNotification` — notification toast strip (managed by the `NSNotifier`).
-
-### Filters
-
-- `NSFilterBox`, `NSFilterBoxItems`, `NSFilterItem` — query/filter UI for tables and lists.
-
-### Misc / state
-
-- `NSLoading` — spinner. Takes `small`, `hideTitle`, `hideDescription`.
-- `NSNoData` — empty-state placeholder.
-- `NSDownTimer` — countdown.
-- `NSDownload` — download button/link.
-- `NSProductSearch` — product search dropdown (uses `ProductCacheService`).
-- `NSLine`, `NSLineText` — separators.
-- `NSTitle` — heading.
-
-### Pages
-
-- `NSImplementing` — "this feature is being implemented" page.
-- `NSUpdating` — "this feature is updating" page.
-- `NSNotFoundPage` — 404 page. Use as the catch-all route.
-
-## Formatters (for NSTable columns)
-
-Import and instantiate a `BaseColumnFormatter` subclass per column. Pick by data type:
-
-`StringFormatter`, `IntegerFormatter`, `FloatFormatter`, `MoneyFormatter`, `PercentFormatter`, `BooleanFormatter`, `EnumFormatter`, `DateFormatter`, `DateTimeFormatter`, `TimeFormatter`, `DurationFormatter`, `EmailFormatter`, `PhoneFormatter`, `URLFormatter`, `IPFormatter`, `IDFormatter`, `JsonFormatter`, `BytesFormatter`, `SensitiveFormatter`, `BackColorFormatter`, `ForeColorFormatter`, `BaseURLImageFormatter`, `UnknowFormatter` (fallback).
-
-## Routing
-
-- `NSRouterMaker` — wraps a `NSRouterMakerComponent` with a `setState` callback and storage. Produces an `onRender()` that returns the routed JSX and provides a `NSNotifier` to children.
-- `NSNotifier` — lives on the `notifier` prop passed through `NSLayout` and friends. Methods: `addNotification`, `delNotification`, `onChangeState`.
-- `NSRouterMakerProps` — interface that exposes `notifier: NSNotifier` to a component.
-
-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`.
-
-## Utilities (named exports from the root)
-
-- `Validator` — static methods: `getError(title, value, props)`, `getErrorString(title, value, props)`. Used internally by NSBox\* but exposed for custom validation.
-- `NSBoxBuilder` — schema-driven NSBox factory.
-- `ProductCacheService` — async cache for product lookups (used by `NSProductSearch`).
-- `CopyToClipboard` — programmatic copy.
-- `EncryptionOperation` — client-side encryption helpers.
-- `Color` — color palette / utilities.
-
-## Canonical examples
-
-### Form with three fields and a submit
-
-```tsx
-import React, { createRef } from "react";
-import { NSBoxString, NSBoxEmail, NSBoxPhone, NSButtonBlue } from "namirasoft-site-react";
-
-export function ContactForm() {
-    const nameRef = createRef<NSBoxString>();
-    const emailRef = createRef<NSBoxEmail>();
-    const phoneRef = createRef<NSBoxPhone>();
-
-    return (
-        <>
-            <NSBoxString ref={nameRef} title="Full Name" required min_length={2} max_length={120} />
-            <NSBoxEmail ref={emailRef} title="Email" required />
-            <NSBoxPhone ref={phoneRef} title="Phone" required={false} />
-            <NSButtonBlue
-                title="Submit"
-                onClick={{
-                    action: (done) => {
-                        try {
-                            const payload = {
-                                name: nameRef.current?.getValue(),
-                                email: emailRef.current?.getValue(),
-                                phone: phoneRef.current?.getValue(false),
-                            };
-                            // ... submit payload
-                        } finally {
-                            done();
-                        }
-                    },
-                    showLoading: true,
-                }}
-            />
-        </>
-    );
-}
-```
-
-Notes:
-- `getValue()` throws on validation failure and surfaces the error inline; that's intentional — wrap in try/finally so the spinner clears.
-- Use `getValue(false)` only for optional fields where you want the raw value without validation.
-- Don't try to read NSBox\* values via `useState` + `onChange` — the imperative ref API is the supported path.
-
-### Confirm-delete dialog
-
-`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).
-
-```tsx
-import React, { useState } from "react";
-import { NSButtonRed, NSDialogDelete } from "namirasoft-site-react";
-
-export function DeleteRow({ onDelete }: { onDelete: () => Promise<void> }) {
-    const [open, setOpen] = useState(false);
-    return (
-        <>
-            <NSButtonRed title="Delete" onClick={{ action: (d) => { setOpen(true); d(); } }} />
-            {open && (
-                <NSDialogDelete
-                    title="Delete record?"
-                    description="This cannot be undone."
-                    show_as_code={false}
-                    onClose={() => setOpen(false)}
-                    onYes={{
-                        action: async (done) => {
-                            try { await onDelete(); setOpen(false); }
-                            finally { done(); }
-                        },
-                        showLoading: true,
-                    }}
-                    onNo={{ action: (done) => { setOpen(false); done(); } }}
-                />
-            )}
-        </>
-    );
-}
-```
-
-### Table with formatted columns
-
-```tsx
-import { NSTable, IntegerFormatter, StringFormatter, DateTimeFormatter, TableColumnInfo } from "namirasoft-site-react";
-
-const table = { name: "user", text: "User" };
-const columns: TableColumnInfo[] = [
-    { table, index: 0, name: "id",         text: "ID",         formatter: new IntegerFormatter() },
-    { table, index: 1, name: "name",       text: "Name",       formatter: new StringFormatter() },
-    { table, index: 2, name: "created_at", text: "Created",    formatter: new DateTimeFormatter() },
-];
-
-<NSTable
-    name="users"
-    checkbox={false}
-    columns={columns}
-    getRows={async (page, size, sorts) => {
-        const res = await api.users.list({ page, size, sorts });
-        return { rows: res.items, count: res.total };
-    }}
-    getRowKey={(row) => String(row.value.id)}
-/>
-```
-
-### App shell
-
-```tsx
-<NSLayout
-    scope="MyApp"
-    logo="/logo.png"
-    notifier={notifier}
-    isLoggedIn={() => !!session}
-    header={{ right: { /* IHeaderRightProps */ }, left: { title: "Dashboard" } }}
-    notifications={notifications}
->
-    {pageContent}
-</NSLayout>
-```
-
-## Common mistakes to avoid
-
-- ❌ Reaching for raw HTML (`<div>`, `<a>`, `<button>`, `<input>`, `<table>`, etc.) when an `NS*` equivalent exists — see Cardinal rule #1.
-- ❌ Passing `className="foo"` — use `classList={["foo"]}`.
-- ❌ Treating NSBox\* as controlled (`value`/`onChange`) — use refs + `defaultValue`.
-- ❌ Passing a function to `NSButton.onClick` — must be `{ action, showLoading? }`.
-- ❌ Forgetting to call `done()` in the button action — the spinner will hang forever.
-- ❌ Importing from `"namirasoft-site-react/dist/..."` — only the root path is supported.
-- ❌ Mixing this library with another design system on the same screen — visual conventions clash.
-- ❌ Inventing a new `NSBox<Type>` when an existing one fits — check the data-type table first.
-
-## Peer expectations
-
-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`.
-
-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.
+---
+name: namirasoft-site-react
+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".
+---
+
+# namirasoft-site-react
+
+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.
+
+## When this skill applies
+
+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.).
+
+## Cardinal rules
+
+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:
+    - layout: `NSLayout` / `NSSection` / `NSRow` / `NSColumn` / `NSSpace` / `NSPanel` instead of `<div>` + flex CSS
+    - text: `NSTitle` / `NSLabel` / `NSLineText` instead of `<h1>` / `<span>` / `<p>`
+    - links: `NSLink` (or `NSLinkBlue` / `NSLinkGreen` / `NSLinkRed`) instead of `<a>`
+    - actions: `NSButton` (or color variants) instead of `<button>`
+    - inputs: an `NSBox*` matching the data type instead of `<input>` / `<select>` / `<textarea>`
+    - lists: `NSListGrouped` / `NSRepeater` / `NSTable` instead of `<ul>` / `<table>`
+    - cards/tiles: `NSCard` / `NSTile` instead of bespoke `<div>` containers
+    - dialogs: `NSDialog` (or its variants) instead of a hand-rolled modal
+
+   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.
+
+2. **Always import from the package root**: `import { NSBoxString, NSButton } from "namirasoft-site-react";` — never deep-import from `dist/...`.
+3. **Every component accepts `IBaseComponentProps`**: `id?`, `name?`, `classList?: string[]`, `style?: React.CSSProperties`. Use `classList` (string array), not `className`.
+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.
+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).
+6. **Buttons take an `onClick` *object*, not a function**: `<NSButton onClick={{ action: (done) => { ...; done(); }, showLoading: true }} />`. The `done` callback hides the spinner.
+7. **CSS is bundled** — the package ships `.module.css` files alongside components. No separate stylesheet import is needed beyond what the package does internally.
+
+## Picking the right component
+
+### Form inputs (NSBox*)
+
+All take `title` (label) and `required`. Choose by data type:
+
+| Data | Component |
+|---|---|
+| Free text | `NSBoxString` |
+| Long text | `NSBoxTextArea` |
+| Email | `NSBoxEmail` |
+| URL | `NSBoxURL` |
+| Phone | `NSBoxPhone` (uses `react-phone-number-input`) |
+| Password / secret | `NSBoxSensitive` |
+| Whole number | `NSBoxInteger` |
+| Decimal | `NSBoxDouble` |
+| Currency | `NSBoxMoney` |
+| Boolean (checkbox) | `NSBoxBoolean` |
+| Multiple booleans | `NSBoxBooleans` |
+| Radio group | `NSBoxRadio` |
+| Enum / select | `NSBoxEnum` |
+| Combo (select with search) | `NSBoxCombo` |
+| Date only | `NSBoxDate` |
+| Date + time | `NSBoxDateTime` |
+| Time only | `NSBoxTime` |
+| Time zone | `NSBoxTimeZone` |
+| Duration | `NSBoxDuration` |
+| File upload | `NSBoxFile` |
+| IPv4 / IPv6 | `NSBoxIPV4`, `NSBoxIPV6` |
+| Semver | `NSBoxVersion` |
+| Search bar | `NSBoxSearch` |
+| Entity reference (FK) | `NSBoxEntity` |
+| Schema-driven dynamic field | `NSBoxDynamic`, `NSBoxDynamics`, `NSBoxSchemaBase`, `NSBoxSchemaVariable` |
+
+If you need to reach for a field type not in this table, prefer composing from `NSBoxString` over inventing a new component.
+
+### Buttons & links
+
+- `NSButton` — base button, takes `title`, optional `icon`, and the `onClick` object (see rule 5).
+- `NSButtonBlue` / `NSButtonGreen` / `NSButtonRed` — semantic color variants (primary / success / destructive).
+- `NSLink` — base link.
+- `NSLinkBlue` / `NSLinkGreen` / `NSLinkRed` — semantic link variants.
+- `NSMenuButton` — button that opens a menu.
+- `NSMenuAction` — action menu item.
+
+### Layout & structure
+
+- `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.
+- `NSHeader`, `NSFooter`, `NSMegaMenu` — pieces of `NSLayout`. You usually don't render these directly; let `NSLayout` compose them.
+- `NSSection`, `NSSectionTitle`, `NSSectionCards`, `NSSectionTiles` — vertical content blocks.
+- `NSRow`, `NSColumn` — flex row/column.
+- `NSSpace` — vertical/horizontal spacer (`size: NSSpaceSizeType.MINI | SMALL | ...`).
+- `NSSplitter` — resizable split pane.
+- `NSPanel`, `NSPanelAccordion` — bordered panels.
+- `NSTabPage` — tabbed pages.
+- `NSCard`, `NSCardScreenshot` — content cards with link.
+- `NSTile` — clickable tile.
+
+### Data display
+
+- `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}>`.
+- `NSPagination` — paginator.
+- `NSListGrouped`, `NSListProduct` — list layouts.
+- `NSRepeater`, `NSRepeaterNSTag`, `NSRepeaterNSBoxSchemaVariable` — render arrays of items.
+- `NSTag` — chip/tag.
+- `NSLabel`, `NSLabelErrorNotifier`, `NSLabelSensitive` — text labels.
+- `NSID` — formatted ID display.
+- `NSCopy`, `NSCopyBox` — copy-to-clipboard widgets.
+- `NSElectronicCard` — credit-card-style display card.
+- `NSEntityCardBackground` — backgrounded entity card.
+
+### Charts & gauges
+
+- `NSChartBar`, `NSChartDoughnut`, `NSChartPie`, `NSChartRange`, `NSTableChart` — chart.js / antd-charts wrappers.
+- `NSGauge`, `NSGaugeNumber`, `NSGaugeDate` — single-metric gauges.
+- `NSProgressBar`, `NSRange` — progress / range bars.
+- `NSTimelineMonthly` — monthly timeline.
+
+### Dialogs
+
+- `NSDialog` — base dialog. Takes `onClose: () => void` and `children`. Render conditionally based on local state.
+- `NSDialogDelete` — confirm-delete dialog.
+- `NSDialogInfo` — info/alert dialog.
+- `NSDialogPageSelection` — page-selection picker.
+- `NSDialogBox`, `NSDialogBoxString`, `NSDialogBoxDate`, `NSDialogBoxDateTime`, `NSDialogBoxPhone` — single-field edit dialogs.
+- `NSInfo` — inline info popover (smaller than a dialog).
+
+### Bars & banners
+
+- `NSBanner` — page-top banner.
+- `NSBarTitle` — page title bar.
+- `NSBarAction` — action bar.
+- `NSBarAlert` — alert strip (driven by `isVisible()` predicate).
+- `NSBarNotification` — notification toast strip (managed by the `NSNotifier`).
+
+### Filters
+
+- `NSFilterBox`, `NSFilterBoxItems`, `NSFilterItem` — query/filter UI for tables and lists.
+
+### Misc / state
+
+- `NSLoading` — spinner. Takes `small`, `hideTitle`, `hideDescription`.
+- `NSNoData` — empty-state placeholder.
+- `NSDownTimer` — countdown.
+- `NSDownload` — download button/link.
+- `NSProductSearch` — product search dropdown (uses `ProductCacheService`).
+- `NSLine`, `NSLineText` — separators.
+- `NSTitle` — heading.
+
+### Pages
+
+- `NSImplementing` — "this feature is being implemented" page.
+- `NSUpdating` — "this feature is updating" page.
+- `NSNotFoundPage` — 404 page. Use as the catch-all route.
+
+## Formatters (for NSTable columns)
+
+Import and instantiate a `BaseColumnFormatter` subclass per column. Pick by data type:
+
+`StringFormatter`, `IntegerFormatter`, `FloatFormatter`, `MoneyFormatter`, `PercentFormatter`, `BooleanFormatter`, `EnumFormatter`, `DateFormatter`, `DateTimeFormatter`, `TimeFormatter`, `DurationFormatter`, `EmailFormatter`, `PhoneFormatter`, `URLFormatter`, `IPFormatter`, `IDFormatter`, `JsonFormatter`, `BytesFormatter`, `SensitiveFormatter`, `BackColorFormatter`, `ForeColorFormatter`, `BaseURLImageFormatter`, `UnknowFormatter` (fallback).
+
+## Routing
+
+- `NSRouterMaker` — wraps a `NSRouterMakerComponent` with a `setState` callback and storage. Produces an `onRender()` that returns the routed JSX and provides a `NSNotifier` to children.
+- `NSNotifier` — lives on the `notifier` prop passed through `NSLayout` and friends. Methods: `addNotification`, `delNotification`, `onChangeState`.
+- `NSRouterMakerProps` — interface that exposes `notifier: NSNotifier` to a component.
+
+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`.
+
+## Utilities (named exports from the root)
+
+- `Validator` — static methods: `getError(title, value, props)`, `getErrorString(title, value, props)`. Used internally by NSBox\* but exposed for custom validation.
+- `NSBoxBuilder` — schema-driven NSBox factory.
+- `ProductCacheService` — async cache for product lookups (used by `NSProductSearch`).
+- `CopyToClipboard` — programmatic copy.
+- `EncryptionOperation` — client-side encryption helpers.
+- `Color` — color palette / utilities.
+
+## Canonical examples
+
+### Form with three fields and a submit
+
+```tsx
+import React, { createRef } from "react";
+import { NSBoxString, NSBoxEmail, NSBoxPhone, NSButtonBlue } from "namirasoft-site-react";
+
+export function ContactForm() {
+    const nameRef = createRef<NSBoxString>();
+    const emailRef = createRef<NSBoxEmail>();
+    const phoneRef = createRef<NSBoxPhone>();
+
+    return (
+        <>
+            <NSBoxString ref={nameRef} title="Full Name" required min_length={2} max_length={120} />
+            <NSBoxEmail ref={emailRef} title="Email" required />
+            <NSBoxPhone ref={phoneRef} title="Phone" required={false} />
+            <NSButtonBlue
+                title="Submit"
+                onClick={{
+                    action: (done) => {
+                        try {
+                            const payload = {
+                                name: nameRef.current?.getValue(),
+                                email: emailRef.current?.getValue(),
+                                phone: phoneRef.current?.getValue(false),
+                            };
+                            // ... submit payload
+                        } finally {
+                            done();
+                        }
+                    },
+                    showLoading: true,
+                }}
+            />
+        </>
+    );
+}
+```
+
+Notes:
+- `getValue()` throws on validation failure and surfaces the error inline; that's intentional — wrap in try/finally so the spinner clears.
+- Use `getValue(false)` only for optional fields where you want the raw value without validation.
+- Don't try to read NSBox\* values via `useState` + `onChange` — the imperative ref API is the supported path.
+
+### Confirm-delete dialog
+
+`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).
+
+```tsx
+import React, { useState } from "react";
+import { NSButtonRed, NSDialogDelete } from "namirasoft-site-react";
+
+export function DeleteRow({ onDelete }: { onDelete: () => Promise<void> }) {
+    const [open, setOpen] = useState(false);
+    return (
+        <>
+            <NSButtonRed title="Delete" onClick={{ action: (d) => { setOpen(true); d(); } }} />
+            {open && (
+                <NSDialogDelete
+                    title="Delete record?"
+                    description="This cannot be undone."
+                    show_as_code={false}
+                    onClose={() => setOpen(false)}
+                    onYes={{
+                        action: async (done) => {
+                            try { await onDelete(); setOpen(false); }
+                            finally { done(); }
+                        },
+                        showLoading: true,
+                    }}
+                    onNo={{ action: (done) => { setOpen(false); done(); } }}
+                />
+            )}
+        </>
+    );
+}
+```
+
+### Table with formatted columns
+
+```tsx
+import { NSTable, IntegerFormatter, StringFormatter, DateTimeFormatter, TableColumnInfo } from "namirasoft-site-react";
+
+const table = { name: "user", text: "User" };
+const columns: TableColumnInfo[] = [
+    { table, index: 0, name: "id",         text: "ID",         formatter: new IntegerFormatter() },
+    { table, index: 1, name: "name",       text: "Name",       formatter: new StringFormatter() },
+    { table, index: 2, name: "created_at", text: "Created",    formatter: new DateTimeFormatter() },
+];
+
+<NSTable
+    name="users"
+    checkbox={false}
+    columns={columns}
+    getRows={async (page, size, sorts) => {
+        const res = await api.users.list({ page, size, sorts });
+        return { rows: res.items, count: res.total };
+    }}
+    getRowKey={(row) => String(row.value.id)}
+/>
+```
+
+### App shell
+
+```tsx
+<NSLayout
+    scope="MyApp"
+    logo="/logo.png"
+    notifier={notifier}
+    isLoggedIn={() => !!session}
+    header={{ right: { /* IHeaderRightProps */ }, left: { title: "Dashboard" } }}
+    notifications={notifications}
+>
+    {pageContent}
+</NSLayout>
+```
+
+## Common mistakes to avoid
+
+- ❌ Reaching for raw HTML (`<div>`, `<a>`, `<button>`, `<input>`, `<table>`, etc.) when an `NS*` equivalent exists — see Cardinal rule #1.
+- ❌ Passing `className="foo"` — use `classList={["foo"]}`.
+- ❌ Treating NSBox\* as controlled (`value`/`onChange`) — use refs + `defaultValue`.
+- ❌ Passing a function to `NSButton.onClick` — must be `{ action, showLoading? }`.
+- ❌ Forgetting to call `done()` in the button action — the spinner will hang forever.
+- ❌ Importing from `"namirasoft-site-react/dist/..."` — only the root path is supported.
+- ❌ Mixing this library with another design system on the same screen — visual conventions clash.
+- ❌ Inventing a new `NSBox<Type>` when an existing one fits — check the data-type table first.
+
+## Peer expectations
+
+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`.
+
+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.