@open-mercato/ui 0.6.1-develop.3115.bc23703ef8 → 0.6.1-develop.3144.b39fb4dfa6

package/AGENTS.md

@@ -231,6 +231,85 @@ const leadTagMap: TagMap<'customer' | 'hot' | 'inactive' | 'renewal'> = {
 - Keep `extensionTableId` stable and deterministic.
 - Render injected row actions and bulk actions through `RowActions`/bulk handlers so they follow the same guard and i18n behavior as built-ins.
 
+### Using DataTable in Portal Pages
+
+`DataTable` is exported from the package root (`@open-mercato/ui`) and is the recommended list view component for **customer portal pages**, not just backoffice surfaces. Build portal list views with `DataTable` directly rather than hand-rolling `<table>` markup or wrapping a custom component, so portal lists stay consistent with the rest of the product (sorting, pagination, empty states, accessibility, row-click semantics).
+
+Backoffice-only features are **all opt-in via props** — they do not activate unless explicitly passed. Portal pages should leave them unset:
+
+| Prop | Treat as | Why portal omits it |
+|------|----------|---------------------|
+| `exporter` | backoffice-only | Portal users should not export full datasets to CSV/JSON/XML/Markdown. |
+| `perspective` | backoffice-only | Saved-view perspectives belong in admin tools. |
+| `advancedFilter` | backoffice-only | The advanced filter builder is a power-user tool. |
+| `columnChooser` | backoffice-only | Column chooser/reorder is a backoffice affordance. |
+| `injectionSpotId` / `replacementHandle` / `entityId` | backoffice-only | Widget injection and component replacement target backoffice extension points; portals use `usePortalInjectedMenuItems` and portal-specific spots instead (see Portal Extension below). |
+| `bulkActions` | backoffice-only by default | Avoid bulk admin operations from the portal; if a portal flow legitimately needs row selection, scope it tightly and gate via `requireCustomerFeatures`. |
+
+Portal-safe props (always available):
+
+- `columns` — column definitions with `header`/`accessorKey` plus optional `meta.truncate`/`meta.maxWidth`
+- `data` — the rows to render (load via `apiCall` from `@open-mercato/ui/backend/utils/apiCall`)
+- `isLoading`, `error`, `emptyState` — loading/error/empty UX
+- `pagination`, `sorting`, `onSortingChange`, `sortable`
+- `onRowClick`, `rowClickActionIds`, `disableRowClick` — row navigation
+- `rowActions` — per-row inline actions via `RowActions`
+- `searchValue`, `onSearchChange`, `searchPlaceholder` — basic search bar
+- `filters`, `filterValues`, `onFiltersApply`, `onFiltersClear` — basic FilterBar filters
+- `title`, `actions`, `toolbar` — header chrome
+
+Minimal portal usage example (drop into any `frontend/[orgSlug]/portal/.../page.tsx`):
+
+```tsx
+'use client'
+import * as React from 'react'
+import { DataTable } from '@open-mercato/ui'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+
+type PortalOrderRow = {
+  id: string
+  number: string
+  status: string
+  totalLabel: string
+}
+
+export default function PortalOrdersList({ orgSlug }: { orgSlug: string }) {
+  const t = useT()
+  const [rows, setRows] = React.useState<PortalOrderRow[]>([])
+  const [isLoading, setIsLoading] = React.useState(true)
+
+  React.useEffect(() => {
+    let cancelled = false
+    setIsLoading(true)
+    apiCall<{ items: PortalOrderRow[] }>(`/api/portal/orders?orgSlug=${encodeURIComponent(orgSlug)}`)
+      .then((res) => { if (!cancelled) setRows(res.data?.items ?? []) })
+      .finally(() => { if (!cancelled) setIsLoading(false) })
+    return () => { cancelled = true }
+  }, [orgSlug])
+
+  return (
+    <DataTable<PortalOrderRow>
+      title={t('orders.title', { fallback: 'Your orders' })}
+      columns={[
+        { header: t('orders.number'), accessorKey: 'number' },
+        { header: t('orders.status'), accessorKey: 'status' },
+        { header: t('orders.total'), accessorKey: 'totalLabel' },
+      ]}
+      data={rows}
+      isLoading={isLoading}
+      onRowClick={(row) => { window.location.href = `/${orgSlug}/portal/orders/${row.id}` }}
+      emptyState={t('orders.empty', { fallback: 'No orders yet.' })}
+    />
+  )
+}
+```
+
+Notes:
+- The example deliberately omits `exporter`, `perspective`, `advancedFilter`, `columnChooser`, `injectionSpotId`, and `replacementHandle` — those are backoffice-only.
+- Wrap mutation calls with `useGuardedMutation(...).runMutation(...)` per the **UI & HTTP** rules in the root `AGENTS.md` if the row actions perform writes.
+- Gate the page with `requireCustomerAuth` and `requireCustomerFeatures` in the sibling `page.meta.ts` (see Portal Page Metadata below).
+
 ## CrudForm Field Injection (UMES Phase G)
 
 - `CrudForm` automatically resolves injected field widgets from `crud-form:<entityId>:fields`; always pass a stable `entityId`.
@@ -289,6 +368,8 @@ const leadTagMap: TagMap<'customer' | 'hot' | 'inactive' | 'renewal'> = {
 
 The portal extensibility system lets app modules build customer-facing pages that integrate with the shared portal shell, navigation, auth, and event bridge.
 
+> **Portal list views**: use `DataTable` from `@open-mercato/ui` for any portal page that displays a list of records (orders, addresses, invoices, etc.). Do not hand-roll `<table>` markup. See **DataTable Guidelines → Using DataTable in Portal Pages** above for the portal-safe prop subset and a minimal example.
+
 ### Portal Hooks (`packages/ui/src/portal/hooks/`)
 
 | Hook | Import | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/ui",
-  "version": "0.6.1-develop.3115.bc23703ef8",
+  "version": "0.6.1-develop.3144.b39fb4dfa6",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -140,12 +140,12 @@
     "remark-gfm": "^4.0.1"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.1-develop.3115.bc23703ef8",
+    "@open-mercato/shared": "0.6.1-develop.3144.b39fb4dfa6",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.1-develop.3115.bc23703ef8",
+    "@open-mercato/shared": "0.6.1-develop.3144.b39fb4dfa6",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",