nexus-admin 1.0.1

package/USER-GUIDE.md

@@ -0,0 +1,166 @@
+# nexus.core — User Guide
+
+**nexus.core** is a shared React library for Nexus applications. It provides UI components, form/input builders, layout helpers, themes, loaders, and TypeScript interfaces used across public and admin modules.
+
+## Requirements
+
+| Dependency   | Version   |
+| ------------ | --------- |
+| react        | ≥ 18      |
+| react-dom    | ≥ 18      |
+| next         | ≥ 14      |
+
+The library targets **Next.js** apps (several components use `next/link`, `next/font`, or `next/script`).
+
+## Installation
+
+### From npm (when published)
+
+```bash
+npm install nexus.core
+```
+
+### From the monorepo (local path)
+
+```json
+"dependencies": {
+  "nexus.core": "file:../../nexus.packages/nexus.core"
+}
+```
+
+```bash
+npm install
+```
+
+After updating the package, rebuild it in `nexus.packages/nexus.core` with `npm run build`, then reinstall in your app if types or exports look stale.
+
+## Styles
+
+Import the bundled stylesheet once in your root layout (recommended):
+
+```ts
+import "nexus.core/styles.css";
+```
+
+If you use `GlobalLayout`, styles are also loaded through that component’s CSS imports when the layout is rendered.
+
+## Basic usage
+
+### Forms and inputs
+
+```tsx
+"use client";
+
+import { Form, GetForms, GetInputs, OnFormChangeHandler } from "nexus.core";
+
+const onChanged: OnFormChangeHandler = (value, isInit, isForced, isDisposed, key, index) => {
+  // handle form state
+};
+
+const form = GetForms.Create({
+  id: "my-form",
+  inputs: [
+    GetInputs.Textbox({ id: "email", label: "Email" }),
+    GetInputs.Textbox({ id: "password", label: "Password", type: EInputTypes.Password }),
+  ],
+  onChanged,
+});
+
+export function MyForm() {
+  return <Form param={form} />;
+}
+```
+
+Import `EInputTypes` from `nexus.core` when defining input types.
+
+### Buttons and icons
+
+```tsx
+import { Button, GetButton, Iconbox, EIcons, EIconTypes } from "nexus.core";
+
+const btn = GetButton("Save", "save-btn", undefined, EIcons.CHECKMARK);
+
+<Button button={btn} />;
+<Iconbox icon={EIcons.SETTINGS} iconType={EIconTypes.Outline} />;
+```
+
+### Loader
+
+```tsx
+import { ShowLoader, HideLoader } from "nexus.core";
+
+await ShowLoader();
+// … async work …
+await HideLoader();
+```
+
+### Global layout (Next.js)
+
+```tsx
+import { GlobalLayout, GetGlobalLayout } from "nexus.core";
+
+const globalLayout = GetGlobalLayout(/* … */);
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <GlobalLayout globalLayout={globalLayout}>{children}</GlobalLayout>;
+}
+```
+
+### Environment and config
+
+```tsx
+import { NEXUS_INFO, NEXUS_CONFIG, FILES } from "nexus.core";
+```
+
+### Theme
+
+```tsx
+import { InitializeStyles, SwitchTheme, GetCurrentTheme } from "nexus.core";
+
+InitializeStyles();
+SwitchTheme("dark");
+```
+
+## Package exports
+
+| Import path              | Purpose                          |
+| ------------------------ | -------------------------------- |
+| `nexus.core`             | All public APIs (barrel export)  |
+| `nexus.core/styles.css`  | Combined package styles          |
+
+## Main API areas
+
+Everything is exported from the package root:
+
+| Area            | Examples                                              |
+| --------------- | ----------------------------------------------------- |
+| **Components**  | `Form`, `Button`, `Iconbox`, `GlobalLayout`, `GlobalDialogbox` |
+| **Factories**   | `GetForms`, `GetInputs`, `GetButton`, `GetGlobalLayout` |
+| **DOM builders**| `CreateForm`, `CreateInput`, `CreateButton`, `CreateIconBox` |
+| **Interfaces**  | `EIcons`, `ESizes`, `EBackgrounds`, `IForm`, `IButton` |
+| **Services**    | `ShowLoader`, `HideLoader`, `InitializeStyles`      |
+| **Helpers**     | `Debounce`, `IsBrowser`, `DynamicSorting`           |
+
+See TypeScript definitions in `dist/index.d.ts` for the full list.
+
+## TypeScript
+
+Types ship with the package. No separate `@types` package is required.
+
+```ts
+import type { IForm, IButton, IGlobalLayout } from "nexus.core";
+```
+
+## Next.js notes
+
+- Use `"use client"` in files that call client-only APIs (`CreateForm`, loaders, theme switching in the browser).
+- `GlobalLayout` is a server component (`"use server"`); use it from `app/layout.tsx` as appropriate for your Next version.
+- Ensure `react` and `next` versions satisfy peer dependency ranges.
+
+## Versioning
+
+Follow semver for published releases. Patch: fixes; minor: backward-compatible features; major: breaking API or peer dependency changes.
+
+## Support
+
+For package development and contribution steps, see **DEVELOPER.md** in the source repository (not included in the npm install).