nexstruct 1.0.0

package/templates/ui/antd/COMPONENT_GUIDE.md

@@ -0,0 +1,326 @@
+# Ant Design Component System
+
+This template includes a comprehensive reusable component system built on **Ant Design 5**.
+
+## Architecture
+
+```
+src/components/
+├── common/
+│   ├── button/
+│   │   └── action-button.component.tsx    # Button + Tooltip + Loading
+│   ├── dialog/
+│   │   └── dialog-wrapper.component.tsx    # Scrollable modal wrapper
+│   ├── DynamicTable/
+│   │   └── dynamic-table.component.tsx     # Config-driven table
+│   ├── fields/
+│   │   ├── assets/
+│   │   │   ├── components/                # Individual field components
+│   │   │   └── interface/
+│   │   │       └── input-props.type.ts     # Shared type definitions
+│   │   └── cusInputField.component.tsx     # CustomField barrel export
+│   └── pagination/
+│       └── pagination.component.tsx        # Page navigation
+└── ui/                                     # Base primitives (22 components)
+    ├── avatar.component.tsx
+    ├── badge.component.tsx
+    ├── button.component.tsx
+    ├── card.component.tsx
+    ├── checkbox.component.tsx
+    ├── dialog.component.tsx               # Ant Design Modal wrapper
+    ├── dropdown-menu.component.tsx        # Ant Design Dropdown wrapper
+    ├── form.component.tsx                 # Ant Design Form + Form.Item
+    ├── input.component.tsx                # Input + TextArea + OTP + Password + Search
+    ├── label.component.tsx
+    ├── popover.component.tsx
+    ├── progress.component.tsx
+    ├── radio-group.component.tsx
+    ├── scroll-area.component.tsx
+    ├── select.component.tsx
+    ├── separator.component.tsx            # Ant Design Divider wrapper
+    ├── sheet.component.tsx                # Ant Design Drawer wrapper
+    ├── switch.component.tsx
+    ├── table.component.tsx
+    ├── tabs.component.tsx
+    ├── textarea.component.tsx
+    └── tooltip.component.tsx
+```
+
+---
+
+## CustomField System
+
+The `CustomField` compound object provides 17 field types. Every field supports **dual-mode**:
+
+- **With `form` prop**: Integrates with `react-hook-form` via `<Controller>` for validation/errors.
+- **Without `form` prop**: Renders standalone using `value`/`setValue` props.
+
+### Import
+
+```tsx
+import { CustomField } from '@/components/common/fields/cusInputField.component';
+```
+
+### Available Fields
+
+| Field | Component | Description |
+|-------|-----------|-------------|
+| Text | `CustomField.Text` | Single-line text input |
+| TextArea | `CustomField.TextArea` | Multi-line text area with optional `maxLength`/`showCount` |
+| Number | `CustomField.Number` | Numeric input with `numberType` (`float`/`integer`), `min`, `max`, `step` |
+| StringNumber | `CustomField.StringNumber` | Text input that only allows digits and decimals |
+| Password | `CustomField.Password` | Password input with show/hide toggle; `mode="validate"` adds confirm field |
+| SingleSelectField | `CustomField.SingleSelectField` | Dropdown select from string array |
+| SelectField | `CustomField.SelectField` | Advanced select with `single`/`multiple`, search, images, flags |
+| SwitchField | `CustomField.SwitchField` | Toggle switch with optional description and border |
+| RadioField | `CustomField.RadioField` | Radio button group |
+| CheckField | `CustomField.CheckField` | Checkbox group |
+| MultiCheckField | `CustomField.MultiCheckField` | Multi-select checkbox group (alias for CheckField) |
+| SingleCheckField | `CustomField.SingleCheckField` | Single checkbox with label |
+| SearchField | `CustomField.SearchField` | Search input with clear and enter-button |
+| DatePickerField | `CustomField.DatePickerField` | Date picker with `picker` prop (`date`, `week`, `month`, `quarter`, `year`) |
+| RangeDatePicker | `CustomField.RangeDatePicker` | Date range picker |
+| PhoneNumber | `CustomField.PhoneNumber` | Phone number text input (type="tel") |
+| OTP | `CustomField.OTP` | OTP input with configurable `length` |
+| LimitField | `CustomField.LimitField` | Per-page limit selector for pagination |
+
+### Dual-mode Example
+
+```tsx
+// With react-hook-form (recommended)
+<CustomField.Text
+  form={form}
+  name="fullName"
+  labelName="Full Name"
+  placeholder="Enter your name"
+  required
+/>
+
+// Standalone (without form)
+<CustomField.Text
+  labelName="Full Name"
+  value={name}
+  setValue={setName}
+/>
+```
+
+---
+
+## Common Components
+
+### ActionButton
+
+A button component with icon positions, loading spinner, and optional Ant Design Tooltip.
+
+```tsx
+import { ActionButton } from '@/components/common/button/action-button.component';
+
+// Basic
+<ActionButton buttonContent="Save" variant="primary" />
+
+// With loading state
+<ActionButton buttonContent="Saving..." isPending variant="primary" />
+
+// With icons
+<ActionButton
+  buttonContent="Add User"
+  icon={<PlusOutlined />}
+  lastIcon={<ArrowRightOutlined />}
+  variant="primary"
+/>
+
+// With tooltip
+<ActionButton
+  buttonContent="Delete"
+  variant="primary"
+  danger
+  tooltipContent="Permanently delete this item"
+  side="top"
+/>
+
+// Submit button
+<ActionButton htmlType="submit" buttonContent="Submit" variant="primary" />
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'primary' \| 'dashed' \| 'link' \| 'text' \| 'default'` | `'primary'` | Button variant |
+| `btnSize` | `'small' \| 'middle' \| 'large'` | `'middle'` | Button size |
+| `danger` | `boolean` | `false` | Danger styling |
+| `isPending` | `boolean` | `false` | Show loading spinner |
+| `icon` | `ReactNode` | - | Icon before content |
+| `lastIcon` | `ReactNode` | - | Icon after content |
+| `tooltipContent` | `string` | - | Tooltip text (wraps in Tooltip) |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Tooltip placement |
+| `htmlType` | `'submit' \| 'button' \| 'reset'` | `'button'` | HTML button type |
+| `handleOpen` | `function` | - | Click handler |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `ghost` | `boolean` | - | Ghost mode |
+| `block` | `boolean` | - | Full-width block |
+
+---
+
+### DialogWrapper
+
+A scrollable modal with sticky header, close button, optional trigger content, and footer slot.
+
+```tsx
+import { DialogWrapper } from '@/components/common/dialog/dialog-wrapper.component';
+
+const [open, setOpen] = useState(false);
+
+<DialogWrapper
+  open={open}
+  setOpen={setOpen}
+  title="Dialog Title"
+  description="Optional description"
+  footer={
+    <Space>
+      <ActionButton variant="default" buttonContent="Cancel" handleOpen={() => setOpen(false)} />
+      <ActionButton variant="primary" buttonContent="Confirm" />
+    </Space>
+  }
+>
+  <p>Your content here — scrollable if long.</p>
+</DialogWrapper>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | required | Visibility state |
+| `setOpen` | `function` | required | State setter |
+| `triggerContent` | `ReactNode` | - | Optional trigger element |
+| `title` | `ReactNode` | - | Modal title |
+| `description` | `string` | - | Subtitle text |
+| `children` | `ReactNode` | required | Modal body content |
+| `closer` | `boolean` | `true` | Show close button |
+| `footer` | `ReactNode` | - | Footer content |
+| `width` | `number \| string` | `520` | Modal width |
+
+---
+
+### DynamicTable
+
+A config-driven table built on Ant Design Table.
+
+```tsx
+import { DynamicTable, type TableColumn } from '@/components/common/DynamicTable/dynamic-table.component';
+
+const columns: TableColumn[] = [
+  { key: 'name', header: 'Name' },
+  { key: 'email', header: 'Email' },
+  { key: 'role', header: 'Role', render: (item) => <Tag>{item.role}</Tag> },
+];
+
+<DynamicTable
+  data={data}
+  isLoading={isLoading}
+  config={{ columns, emptyMessage: 'No users found' }}
+  isCheckBox
+  selectedIds={selectedIds}
+  setSelectedIds={setSelectedIds}
+  rowKey="id"
+/>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `any[]` | required | Table data |
+| `isLoading` | `boolean` | required | Loading state |
+| `config` | `TableConfig` | required | Column definitions |
+| `isCheckBox` | `boolean` | `false` | Enable row checkbox selection |
+| `selectedIds` | `string[]` | `[]` | Controlled selected row IDs |
+| `setSelectedIds` | `function` | noop | Selected IDs setter |
+| `setSelectObject` | `function` | noop | Full selected row objects setter |
+| `rowKey` | `string` | `'id'` | Unique ID field name |
+
+---
+
+### Pagination
+
+Page navigation using Ant Design Pagination.
+
+```tsx
+import { Pagination } from '@/components/common/pagination/pagination.component';
+
+<Pagination
+  currentPage={currentPage}
+  totalPages={totalPages}
+  setCurrentPage={setCurrentPage}
+  total={totalItems}
+/>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currentPage` | `number` | required | Current active page |
+| `totalPages` | `number` | required | Total number of pages |
+| `setCurrentPage` | `function` | required | Page setter |
+| `total` | `number` | - | Total items (for display) |
+
+---
+
+## UI Primitives
+
+Each primitive in `src/components/ui/` is a thin re-export of an Ant Design component with consistent naming.
+Import directly from their respective files:
+
+```tsx
+import { Button } from '@/components/ui/button.component';
+import { Card } from '@/components/ui/card.component';
+import { Tabs } from '@/components/ui/tabs.component';
+import { Table } from '@/components/ui/table.component';
+// etc.
+```
+
+### Full List
+
+| Component | Ant Design Equivalent | File |
+|-----------|----------------------|------|
+| `Avatar` | `Avatar` | `avatar.component.tsx` |
+| `Badge` | `Badge` | `badge.component.tsx` |
+| `Button` | `Button` | `button.component.tsx` |
+| `Card` | `Card` | `card.component.tsx` |
+| `Checkbox` | `Checkbox` | `checkbox.component.tsx` |
+| `Dialog` | `Modal` | `dialog.component.tsx` |
+| `DropdownMenu` | `Dropdown` | `dropdown-menu.component.tsx` |
+| `Form`, `FormItem` | `Form`, `Form.Item` | `form.component.tsx` |
+| `Input` | `Input` | `input.component.tsx` |
+| `Label` | `Typography.Text` | `label.component.tsx` |
+| `Popover` | `Popover` | `popover.component.tsx` |
+| `Progress` | `Progress` | `progress.component.tsx` |
+| `RadioGroup` | `Radio.Group` | `radio-group.component.tsx` |
+| `ScrollArea` | Custom scrollable div | `scroll-area.component.tsx` |
+| `Select` | `Select` | `select.component.tsx` |
+| `Separator` | `Divider` | `separator.component.tsx` |
+| `Sheet` | `Drawer` | `sheet.component.tsx` |
+| `Switch` | `Switch` | `switch.component.tsx` |
+| `Table` | `Table` | `table.component.tsx` |
+| `Tabs` | `Tabs` | `tabs.component.tsx` |
+| `Textarea` | `Input.TextArea` | `textarea.component.tsx` |
+| `Tooltip` | `Tooltip` | `tooltip.component.tsx` |
+
+---
+
+## Theme
+
+The Ant Design theme is configured in `src/lib/theme.util.ts` using the `ThemeConfig` API.
+The `AntdProvider` in `src/providers/antd.provider.tsx` wraps the app with `<ConfigProvider>`.
+
+```tsx
+// Customize in src/lib/theme.util.ts
+export const themeConfig: ThemeConfig = {
+  token: {
+    colorPrimary: '#1677ff',
+    borderRadius: 6,
+  },
+};
+```

package/templates/ui/antd/src/app/examples/dialog/page.tsx

@@ -0,0 +1,205 @@
+'use client';
+
+import { useState } from 'react';
+import { Typography, Space, Tag, Card, Row, Col, Divider, theme } from 'antd';
+import {
+  EditOutlined, DeleteOutlined, PlusOutlined,
+  InfoCircleOutlined, CheckCircleOutlined, WarningOutlined,
+} from '@ant-design/icons';
+import { DialogWrapper } from '@/components/common/dialog/dialog-wrapper.component';
+import { ActionButton } from '@/components/common/button/action-button.component';
+import { Pagination } from '@/components/common/pagination/pagination.component';
+
+const { Title, Text, Paragraph } = Typography;
+
+const sampleItems = Array.from({ length: 25 }, (_, i) => ({
+  id: i + 1,
+  title: `Item ${i + 1}`,
+  status: ['Active', 'Pending', 'Archived'][i % 3],
+}));
+
+export default function DialogExamplePage() {
+  const { token } = theme.useToken();
+  const [basicOpen, setBasicOpen] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  const [currentPage, setCurrentPage] = useState(1);
+  const perPage = 5;
+  const totalPages = Math.ceil(sampleItems.length / perPage);
+  const paginatedItems = sampleItems.slice((currentPage - 1) * perPage, currentPage * perPage);
+
+  const getStatusColor = (status: string) => {
+    switch (status) {
+      case 'Active': return 'green';
+      case 'Pending': return 'orange';
+      case 'Archived': return 'default';
+      default: return 'default';
+    }
+  };
+
+  return (
+    <div style={{ maxWidth: 960, margin: '0 auto', padding: 32 }}>
+      <div style={{ marginBottom: 24 }}>
+        <Title level={2} style={{ fontWeight: 800, margin: 0 }}>Dialog, ActionButton & Pagination Demo</Title>
+        <Text type="secondary" style={{ fontSize: 15, display: 'block', marginTop: 4 }}>
+          Reusable DialogWrapper with sticky header, ActionButton variants with tooltips, and pagination.
+        </Text>
+      </div>
+
+      {/* ActionButton Variants */}
+      <Card title="ActionButton Variants" style={{ borderRadius: 12, marginBottom: 24 }} variant="outlined">
+        <Space wrap size="middle">
+          <ActionButton
+            variant="primary"
+            icon={<InfoCircleOutlined />}
+            buttonContent="Info"
+            tooltipContent="Default primary variant"
+          />
+          <ActionButton
+            variant="primary"
+            danger
+            icon={<DeleteOutlined />}
+            buttonContent="Delete"
+            tooltipContent="Danger variant"
+          />
+          <ActionButton
+            variant="default"
+            icon={<EditOutlined />}
+            buttonContent="Edit"
+            tooltipContent="Default variant"
+          />
+          <ActionButton
+            variant="dashed"
+            icon={<PlusOutlined />}
+            buttonContent="Add"
+            tooltipContent="Dashed variant"
+          />
+          <ActionButton
+            variant="text"
+            icon={<WarningOutlined />}
+            buttonContent="Warn"
+            tooltipContent="Text variant"
+          />
+          <ActionButton
+            variant="link"
+            icon={<CheckCircleOutlined />}
+            buttonContent="Confirm"
+            tooltipContent="Link variant"
+          />
+        </Space>
+      </Card>
+
+      {/* Loading State */}
+      <Card title="ActionButton States" style={{ borderRadius: 12, marginBottom: 24 }} variant="outlined">
+        <Space wrap size="middle">
+          <ActionButton
+            buttonContent="Save Changes"
+            isPending
+            variant="primary"
+          />
+          <ActionButton
+            buttonContent="Disabled"
+            disabled
+            variant="default"
+          />
+          <ActionButton
+            buttonContent="With Icon"
+            icon={<PlusOutlined />}
+            variant="primary"
+          />
+          <ActionButton
+            buttonContent="Icon After"
+            lastIcon={<EditOutlined />}
+            variant="default"
+          />
+        </Space>
+      </Card>
+
+      {/* Dialogs */}
+      <Row gutter={[16, 16]} style={{ marginBottom: 24 }}>
+        <Col xs={24} md={12}>
+          <Card title="Basic Dialog" style={{ borderRadius: 12 }} variant="outlined">
+            <ActionButton
+              buttonContent="Open Dialog"
+              variant="primary"
+              handleOpen={() => setBasicOpen(true)}
+            />
+          </Card>
+        </Col>
+        <Col xs={24} md={12}>
+          <Card title="Confirmation Dialog" style={{ borderRadius: 12 }} variant="outlined">
+            <ActionButton
+              buttonContent="Confirm Action"
+              variant="default"
+              danger
+              icon={<DeleteOutlined />}
+              handleOpen={() => setConfirmOpen(true)}
+            />
+          </Card>
+        </Col>
+      </Row>
+
+      <DialogWrapper
+        open={basicOpen}
+        setOpen={setBasicOpen}
+        title="Basic Dialog"
+        description="This is a reusable dialog wrapper with a sticky header and close button."
+        footer={
+          <Space>
+            <ActionButton variant="default" buttonContent="Cancel" handleOpen={() => setBasicOpen(false)} />
+            <ActionButton variant="primary" buttonContent="Confirm" handleOpen={() => { alert('Confirmed!'); setBasicOpen(false); }} />
+          </Space>
+        }
+      >
+        <Paragraph>
+          This dialog content area is scrollable. The header and footer remain sticky.
+          The close button in the top-right corner dismisses the dialog.
+        </Paragraph>
+        <Paragraph>
+          DialogWrapper uses Ant Design Modal under the hood with a polished scrollable body,
+          sticky header with title and description, and an optional footer slot.
+        </Paragraph>
+      </DialogWrapper>
+
+      <DialogWrapper
+        open={confirmOpen}
+        setOpen={setConfirmOpen}
+        title="Confirm Delete"
+        description="Are you sure you want to delete this item? This action cannot be undone."
+        footer={
+          <Space>
+            <ActionButton variant="default" buttonContent="Cancel" handleOpen={() => setConfirmOpen(false)} />
+            <ActionButton variant="primary" danger buttonContent="Delete" handleOpen={() => { alert('Deleted!'); setConfirmOpen(false); }} />
+          </Space>
+        }
+      >
+        <Paragraph>
+          <WarningOutlined style={{ color: token.colorWarning, marginRight: 8 }} />
+          This action is irreversible. All associated data will be permanently removed.
+        </Paragraph>
+      </DialogWrapper>
+
+      {/* Pagination */}
+      <Card title="Pagination" style={{ borderRadius: 12 }} variant="outlined">
+        <div style={{ marginBottom: 16 }}>
+          {paginatedItems.map((item) => (
+            <div key={item.id} style={{
+              display: 'flex', justifyContent: 'space-between',
+              alignItems: 'center', padding: '8px 12px',
+              borderBottom: `1px solid ${token.colorBorderSecondary}`,
+            }}>
+              <Text>{item.title}</Text>
+              <Tag color={getStatusColor(item.status)} style={{ borderRadius: 6 }}>
+                {item.status}
+              </Tag>
+            </div>
+          ))}
+        </div>
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          setCurrentPage={setCurrentPage}
+        />
+      </Card>
+    </div>
+  );
+}

package/templates/ui/antd/src/app/examples/form/page.tsx

@@ -0,0 +1,160 @@
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Typography, Divider, Row, Col, Card, Space, theme } from 'antd';
+import { CustomField } from '@/components/common/fields/cusInputField.component';
+import { ActionButton } from '@/components/common/button/action-button.component';
+
+const { Title, Text } = Typography;
+
+const formSchema = z.object({
+  fullName: z.string().min(2, 'Name must be at least 2 characters'),
+  bio: z.string().optional(),
+  age: z.coerce.number().min(1, 'Required').max(150),
+  phone: z.string().optional(),
+  password: z.string().min(6, 'Min 6 characters'),
+  role: z.string().min(1, 'Select a role'),
+  notify: z.boolean().optional(),
+  acceptTerms: z.boolean().refine((v) => v === true, 'You must accept'),
+});
+
+type FormValues = z.infer<typeof formSchema>;
+
+export default function FormExamplePage() {
+  const { token } = theme.useToken();
+  const form = useForm<FormValues>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      fullName: '', bio: '', age: undefined, phone: '',
+      password: '', role: '', notify: false, acceptTerms: false,
+    },
+  });
+
+  const onSubmit = (data: FormValues) => alert(JSON.stringify(data, null, 2));
+
+  return (
+    <div style={{ maxWidth: 900, margin: '0 auto', padding: 32 }}>
+      <div style={{ marginBottom: 24 }}>
+        <Title level={2} style={{ fontWeight: 800, margin: 0 }}>CustomField Form Demo</Title>
+        <Text type="secondary" style={{ fontSize: 15, display: 'block', marginTop: 4 }}>
+          All field types with react-hook-form + Zod validation.
+        </Text>
+      </div>
+
+      <Card style={{ borderRadius: 12 }} variant="outlined">
+        <form onSubmit={form.handleSubmit(onSubmit)}>
+          <Row gutter={[24, 0]}>
+            <Col xs={24} md={12}>
+              <CustomField.Text
+                form={form}
+                name="fullName"
+                labelName="Full Name"
+                placeholder="Enter your name"
+                required
+              />
+            </Col>
+            <Col xs={24} md={12}>
+              <CustomField.Number
+                form={form}
+                name="age"
+                labelName="Age"
+                numberType="integer"
+                placeholder="Enter age"
+                required
+              />
+            </Col>
+            <Col xs={24}>
+              <CustomField.TextArea
+                form={form}
+                name="bio"
+                labelName="Biography"
+                placeholder="Tell us about yourself"
+                rows={3}
+              />
+            </Col>
+            <Col xs={24} md={12}>
+              <CustomField.PhoneNumber
+                form={form}
+                name="phone"
+                labelName="Phone Number"
+                placeholder="+1 (555) 123-4567"
+              />
+            </Col>
+            <Col xs={24} md={12}>
+              <CustomField.Password
+                form={form}
+                name="password"
+                labelName="Password"
+                placeholder="Min 6 characters"
+                required
+              />
+            </Col>
+            <Col xs={24} md={12}>
+              <CustomField.SelectField
+                form={form}
+                name="role"
+                labelName="Role"
+                placeholder="Select role"
+                required
+                options={[
+                  { value: 'admin', label: 'Admin' },
+                  { value: 'editor', label: 'Editor' },
+                  { value: 'viewer', label: 'Viewer' },
+                ]}
+              />
+            </Col>
+            <Col xs={24} md={12}>
+              <CustomField.SingleSelectField
+                form={form}
+                name="department"
+                labelName="Department"
+                placeholder="Select department"
+                options={['Engineering', 'Design', 'Marketing', 'Sales']}
+              />
+            </Col>
+          </Row>
+
+          <Divider />
+
+          <Row gutter={[24, 0]}>
+            <Col xs={24} md={12}>
+              <CustomField.SwitchField
+                form={form}
+                name="notify"
+                labelName="Enable Notifications"
+                description="Receive email updates about your account"
+                border
+              />
+            </Col>
+            <Col xs={24} md={12}>
+              <CustomField.SingleCheckField
+                form={form}
+                name="acceptTerms"
+                labelName="I accept the terms and conditions"
+                required
+              />
+            </Col>
+          </Row>
+
+          <Divider />
+
+          <Space>
+            <ActionButton
+              htmlType="submit"
+              buttonContent="Submit"
+              variant="primary"
+              isPending={form.formState.isSubmitting}
+            />
+            <ActionButton
+              buttonContent="Reset"
+              variant="default"
+              handleOpen={() => form.reset()}
+            />
+          </Space>
+        </form>
+      </Card>
+    </div>
+  );
+}