# HyperReactXML Implementation Guide

This guide shows how to connect HyperReactXML inside a real React project.

## 1. Install

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

## 2. Create XML

```ts
export const userScreenXml = `
<Page title="Users">
  <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</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" />
  </Table>
</Page>
`;
```

## 3. Connect Data Sources

```ts
const dataSources = {
  userStatus: () => [
    { label: 'Active', value: 'ACTIVE' },
    { label: 'Inactive', value: 'INACTIVE' },
  ],
  users: async ({ values, filters, page, pageSize, sort }) => {
    return {
      rows: await userApi.list({ values, filters, page, pageSize, sort }),
      total: await userApi.count({ values, filters }),
    };
  },
};
```

Data sources can return either an array or `{ rows, total }`.

## 4. Connect Actions

```ts
const actions = {
  saveUser: async ({ values, toast, reload }) => {
    await userApi.save(values);
    toast.success?.('User saved');
    await reload('users');
  },
  editUser: ({ row, openModal, setValues }) => {
    setValues({ editName: row?.name, editEmail: row?.email });
    openModal('editUserModal');
  },
};
```

## 5. Render

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

export function UsersPage() {
  return (
    <HyperReactXMLRenderer
      xml={userScreenXml}
      dataSources={dataSources}
      actions={actions}
      permissions={['USER_EDIT']}
      onError={console.error}
    />
  );
}
```

## 6. Production Checklist

- Keep XML in version-controlled files or trusted backend configuration.
- Use permissions for sensitive UI actions.
- Validate business rules on your backend also.
- Use `onError` to report rendering/data/action errors.
- Use `serverSide="true"` for large tables.
- Run `npm run typecheck` and `npm run build` before publishing.