# HyperReactXML

[![npm version](https://img.shields.io/npm/v/hyper-react-xml?color=2563eb)](https://www.npmjs.com/package/hyper-react-xml)
[![React](https://img.shields.io/badge/React-18%20%7C%2019-149eca)](https://react.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6)](https://www.typescriptlang.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Custom SDK](https://img.shields.io/badge/SDK-Fully%20Custom-black)](https://bsgtechnologies.com)

HyperReactXML is a fully custom React + TypeScript XML UI SDK for building enterprise admin panels, CRUD screens, forms, tables, reports, dashboards, and internal tools from simple XML.

Built by **Pradeep Kumar Sheoran (Developer)** at **BSG Technologies**.

Official website: **[https://bsgtechnologies.com](https://bsgtechnologies.com)**  
Visit here to meet, learn, contribute, and discuss new topics with us.

Contact and WhatsApp: **+91-8595147850**

## Why HyperReactXML

- Write complete React screens with XML instead of repeating JSX for every page.
- Keep your UI declarative, configurable, and easy to modify.
- Use your own data sources, actions, permissions, theme, translations, and custom renderers.
- Build admin panels, enterprise apps, dashboards, reports, and CRUD screens faster.
- Fully custom SDK source code. No paid builder, no template lock-in, no unsafe `eval`.
- Compatible with modern React projects: React 18 and React 19.

## Install

```bash
npm install hyper-react-xml
```

Peer dependencies:

```bash
npm install react react-dom
```

## Quickstart

```tsx
import { HyperReactXMLRenderer } from 'hyper-react-xml';

const xml = `
<Page title="User Management">
  <Form action="saveUser">
    <Card title="Create User">
      <Grid columns="2">
        <Input name="name" label="Name" required="true" />
        <Input name="email" label="Email" type="email" required="true" />
        <Select name="status" label="Status" source="userStatus" />
      </Grid>
      <Button type="submit" variant="primary">Save User</Button>
    </Card>
  </Form>

  <Table source="users" pagination="true" pageSize="10" pageSizeOptions="10,25,50">
    <Column field="name" label="Name" filter="true" sortable="true" />
    <Column field="email" label="Email" filter="true" sortable="true" />
    <Column field="status" label="Status" renderer="statusBadge" />
    <Action label="Edit" action="editUser" permission="USER_EDIT" />
    <Action label="Delete" action="deleteUser" permission="USER_DELETE" />
    <BulkAction label="Export Selected" action="exportUsers" permission="USER_EXPORT" />
  </Table>
</Page>
`;

export function App() {
  return (
    <HyperReactXMLRenderer
      xml={xml}
      permissions={['USER_EDIT', 'USER_DELETE', 'USER_EXPORT']}
      dataSources={{
        userStatus: () => [
          { label: 'Active', value: 'ACTIVE' },
          { label: 'Inactive', value: 'INACTIVE' },
        ],
        users: ({ filters, page, pageSize, sort }) => {
          console.log({ filters, page, pageSize, sort });
          return {
            rows: [
              { id: 1, name: 'Pradeep', email: 'pradeep@example.com', status: 'ACTIVE' },
              { id: 2, name: 'BSG Demo User', email: 'demo@bsgtechnologies.com', status: 'INACTIVE' },
            ],
            total: 2,
          };
        },
      }}
      actions={{
        saveUser: ({ values, toast }) => toast.success?.(`Saved ${String(values.name ?? '')}`),
        editUser: ({ row }) => console.log('Edit', row),
        deleteUser: ({ row }) => console.log('Delete', row),
        exportUsers: ({ selectedRows }) => console.log('Export', selectedRows),
      }}
      cellRenderers={{
        statusBadge: ({ value, context }) => (
          <span
            style={{
              borderRadius: 999,
              padding: '2px 8px',
              color: value === 'ACTIVE' ? context.theme.successColor : context.theme.mutedTextColor,
              background: value === 'ACTIVE' ? '#16a34a1a' : '#6b72801a',
              fontSize: 12,
              fontWeight: 700,
            }}
          >
            {String(value)}
          </span>
        ),
      }}
      toast={{
        success: console.log,
        error: console.error,
        info: console.log,
      }}
      onError={console.error}
    />
  );
}
```

## Live Demo Connection

This repository includes a ready example:

- XML screen: `src/examples/user-management.xml.ts`
- React connection: `src/examples/user-management.example.tsx`
- Mock service: `src/examples/user.service.ts`

Use the example component in your app:

```tsx
import { UserManagementExample } from './src/examples/user-management.example';

export function DemoPage() {
  return <UserManagementExample />;
}
```

For a Vite demo app, render `DemoPage` in your `main.tsx`. More details are in [docs/LIVE_DEMO.md](docs/LIVE_DEMO.md).

## Features

- XML to React rendering
- Safe XML parsing with `DOMParser`
- Bounded parser cache with configuration
- No unsafe `eval`
- React 18 and React 19 compatibility
- TypeScript-first API
- Component registry pattern
- Built-in XML components
- Custom component registration
- Controlled form state
- Form submit validation with `<Form>`
- Required, email, min, max, minLength, maxLength, and pattern validation
- Custom validation messages
- Conditional `showWhen`, `requiredWhen`, `disabledWhen`, and `readOnlyWhen`
- `&&` and `||` condition expressions
- Data source binding
- Action binding
- Role and permission based UI
- Theme customization
- Style slot customization
- i18n label and text support
- Loader and error handling
- Toast hook support
- Tables with pagination
- Table sorting
- Table page size selector
- Server-side table args: `{ values, filters, page, pageSize, sort }`
- Column filters
- Row actions
- Bulk actions
- Export hook support
- Custom table cell renderers
- Modal support
- Tabs support
- API loading support
- XML schema/reference file
- Publish-ready `dist` output

Full feature list: [FEATURES.md](FEATURES.md)

## Built-In XML Tags

`Page`, `Card`, `Form`, `Grid`, `Row`, `Col`, `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `DatePicker`, `Button`, `Modal`, `Tabs`, `Tab`, `Table`, `Column`, `Action`, `BulkAction`, `Badge`, `Alert`, `Divider`, `Text`, `Heading`.

## Customization Options

HyperReactXML is designed for full customization:

- Replace or add XML tags with `registerHyperReactXMLComponent`.
- Customize colors, spacing, radius, font, and style slots with `theme`.
- Provide your own data loading logic with `dataSources`.
- Provide your own business logic with `actions`.
- Provide your own permission model with `permissions`.
- Provide your own cell renderers with `cellRenderers`.
- Provide your own notifications with `toast`.
- Provide your own translations with `translations`.

See [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.md).

## Implementation Guide

Start here for real project wiring:

- [docs/IMPLEMENTATION_GUIDE.md](docs/IMPLEMENTATION_GUIDE.md)
- [docs/LIVE_DEMO.md](docs/LIVE_DEMO.md)
- [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.md)
- [docs/RESPONSE_GUIDE.md](docs/RESPONSE_GUIDE.md)

## XML Conditions

```xml
<Input name="rejectionReason" label="Reason" showWhen="status=REJECTED" />
<Input name="gstNumber" label="GST Number" requiredWhen="type=BUSINESS && country=IN" />
<Button action="approve" disabledWhen="status!=PENDING">Approve</Button>
```

Supported operators: `=`, `!=`, `>`, `<`, `>=`, `<=`.  
Supported composition: `&&`, `||`.

## Forms And Validation

```xml
<Form action="saveUser">
  <Input name="name" label="Name" required="true" requiredMessage="Please enter a name" />
  <Input name="email" label="Email" type="email" />
  <Input name="phone" label="Phone" pattern="^[0-9]{10}$" patternMessage="Enter a 10 digit phone number" />
  <Button type="submit" variant="primary">Save</Button>
</Form>
```

When a form is submitted, HyperReactXML validates fields inside the form and runs the form action only when there are no errors.

## Tables

```xml
<Table source="users" pagination="true" pageSize="10" pageSizeOptions="10,25,50" serverSide="true">
  <Column field="name" label="Name" filter="true" sortable="true" />
  <Column field="email" label="Email" filter="true" sortable="true" />
</Table>
```

Your data source receives table state:

```ts
const dataSources = {
  users: async ({ values, filters, page, pageSize, sort }) => {
    return api.users.list({ values, filters, page, pageSize, sort });
  },
};
```

## Custom Components

```tsx
import {
  registerHyperReactXMLComponent,
  type HyperReactXMLComponentProps,
} from 'hyper-react-xml';

function CustomStatusBadge({ node, context }: HyperReactXMLComponentProps) {
  const value = node.attributes.field ? context.values[node.attributes.field] : '';
  return <span style={{ color: context.theme.primaryColor }}>{String(value)}</span>;
}

registerHyperReactXMLComponent('CustomStatusBadge', CustomStatusBadge);
```

Then use it in XML:

```xml
<CustomStatusBadge field="status" />
```

## XML Schema

The package includes:

```text
schemas/hyper-react-xml.schema.json
```

Use it as a reference for supported tags and attributes.

## No Builder Lock-In

This SDK does not use Plasmic, Builder.io, Retool, Appsmith, or any paid visual builder. The SDK source is custom. It does not use unsafe `eval`.

Because this is a React SDK, React and React DOM are peer dependencies. Development tools such as TypeScript and Vite are used only for building and local development.

## Donation And Support

If this library helps your project, you can support development:

UPI / mobile number: **+91-8595147850**

Contact and WhatsApp: **+91-8595147850**

More details: [DONATION.md](DONATION.md)

## Publish Checklist

```bash
npm run typecheck
npm run build
npm publish
```

Current package version: **1.1.0**

## Author

Developer: **Pradeep Kumar Sheoran**  
Company: **BSG Technologies**  
Contact / WhatsApp: **+91-8595147850**  
Official website: **[https://bsgtechnologies.com](https://bsgtechnologies.com)**

## Hashtags

`#HyperReactXML` `#React` `#React19` `#TypeScript` `#XMLUI` `#CustomSDK` `#AdminPanel` `#CRUD` `#EnterpriseUI` `#BSGTechnologies` `#PradeepKumarSheoran`

## License And Copyright

MIT License. See [COPYRIGHT.md](COPYRIGHT.md).