# appshare React lane instructions

Use this lane only for advanced appshare mini apps.

## Stack

The React lane is closed.

Allowed:

- React.
- TypeScript.
- Vite.
- Appshare SDK.
- Appshare React Kit.
- Bootstrap 5, themed by appshare.
- React Hook Form.
- Zod.
- TanStack Table.
- TanStack Query.
- React Router only when there are multiple real views.
- Lucide React for icons.

Do not install anything else unless the user explicitly approves an exception.

Forbidden by default:

- MUI.
- Ant Design.
- Chakra.
- Mantine.
- PrimeReact.
- Tailwind.
- shadcn installed per app.
- Radix components installed ad hoc.
- Redux, MobX, Zustand, or another state manager.
- Preact.
- Alpine.
- Random npm component libraries.

## When to use

Use React for:

- Complex local state.
- Master-detail with several nested editors.
- Rich editing.
- Drag/drop.
- Multi-step workflows.
- Reusable interactive components.
- Views where vanilla state would become fragile.

Do not use React for simple CRUD, simple dashboards, or single-form utilities. Use the Bootstrap lane.

## Appshare SDK

Use the SDK for all server calls. Do not hand-code project REST URLs.

```ts
const appshare = Appshare.create({
  projectId: "prj_...",
  environment: "dev"
});
```

For business logic, prefer project functions:

```ts
const result = await appshare
  .function("mis_incidencias_pendientes")
  .invoke<{ incidents: Incident[] }>({ limit: 50 });
```

## Appshare React Kit

Use appshare's React kit before creating local primitives:

- `AppshareProvider`.
- `useAppshare`.
- `Combobox`.

Browser asset shape for no-install prototypes:

```html
<link rel="stylesheet" href="APPROVED_BOOTSTRAP_5_CSS_URL">
<link rel="stylesheet" href="/sdk/appshare-bootstrap.css">
<script src="/sdk/appshare.js"></script>
<script src="/sdk/appshare-react.js"></script>
```

Bundled apps may import equivalent local copies, but the API surface should stay aligned with this kit.

Initialize the browser kit with the React runtime and the appshare SDK:

```ts
const { AppshareProvider, useAppshare, Combobox } =
  AppshareReact.createAppshareReact(React, Appshare);
```

Combobox example:

```tsx
<Combobox
  placeholder="Buscar producto por EAN o nombre"
  search={async (query) => {
    const response = await appshare.function("buscar_producto").invoke({ query });
    return response.result.products.map((product) => ({
      value: product.id,
      label: `${product.ean} · ${product.name}`,
      meta: product.price
    }));
  }}
  onSelect={(product) => addOrderLine(product)}
/>
```

## UI rules

- Use Bootstrap classes for layout and visual primitives.
- Keep components small and named by domain.
- Use controlled state for editors.
- Keep data fetching in hooks or TanStack Query.
- Validate forms with Zod.
- Do not put business authorization or sensitive filtering only in React; use project functions server-side.

## Master-detail pattern

For an order editor:

- `OrdersPage` owns selected order id and modal open state.
- `OrdersTable` renders the master list.
- `OrderModal` owns the draft order and line editing.
- `ProductCombobox` wraps the Appshare React Kit `Combobox`.
- Save through a project function such as `guardar_pedido`.
- Product lookup through a project function such as `buscar_producto`.

## Dependency policy

If a needed component does not exist:

1. Build it locally using React, Bootstrap, and the Appshare React Kit.
2. If it is generally reusable, add it to the Appshare React Kit.
3. Ask before adding a new package.

The correct default is to extend the platform kit, not to install a one-off library.