@molecule/app-admin-table-react 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,213 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T01:49:53.453Z
+-->
+
+# @molecule/app-admin-table-react
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+`@molecule/app-admin-table-react` — generic admin-style data table.
+Define columns, optionally enable row-click navigation, bulk-select
+checkboxes, and a row-actions kebab menu; supply a pagination footer
+via the `footer` slot.
+
+Generalised from the AdminProductsTable / AdminOrdersTable shapes in
+the online-store flagship — the table itself is the reusable
+primitive; product-specific cells (sale price, stock badges) stay in
+the consumer.
+
+## Quick Start
+
+```tsx
+import { AdminTable, type AdminTableColumn } from '@molecule/app-admin-table-react'
+
+const columns: AdminTableColumn<Product>[] = [
+  { id: 'name', header: 'Product', render: (p) => <Product p={p} /> },
+  { id: 'price', header: 'Price', render: (p) => `$${(p.price / 100).toFixed(2)}`, align: 'right' },
+  { id: 'stock', header: 'Stock', render: (p) => <StockBadge stock={p.stock} /> },
+]
+
+<AdminTable
+  rows={products}
+  columns={columns}
+  rowKey={(p) => p.id}
+  loading={loading}
+  onRowClick={(p) => navigate(`/product/${p.id}`)}
+  bulkSelect
+  rowActions={[
+    { label: 'Edit', hrefFor: (p) => `/product/${p.id}`, onSelect: () => {} },
+    { label: 'Delete', destructive: true, onSelect: (p) => http.delete(`/api/products/${p.id}`) },
+  ]}
+  footer={pagination}
+/>
+```
+
+## Type
+
+`feature`
+
+## Installation
+
+```bash
+npm install @molecule/app-admin-table-react @molecule/app-react @molecule/app-ui @molecule/app-ui-react react
+npm install -D @types/react
+```
+
+## API
+
+### Interfaces
+
+#### `AdminTableColumn`
+
+A column definition. Drives header rendering + per-row cell rendering.
+
+```typescript
+interface AdminTableColumn<T> {
+  /** Stable identifier (also used as React key). */
+  id: string
+  /** Column header (rendered in `<th>`). */
+  header: ReactNode
+  /** Cell renderer for one row. */
+  render: (row: T) => ReactNode
+  /** Optional alignment override; defaults to left. */
+  align?: 'left' | 'right' | 'center'
+  /** Optional class string appended to the `<td>` (resolve via `getClassMap()` — e.g. `cm.textRight` — rather than raw utilities). */
+  className?: string
+  /** Optional class string appended to the `<th>` (resolve via `getClassMap()` rather than raw utilities). */
+  headerClassName?: string
+}
+```
+
+#### `AdminTableProps`
+
+Props for {@link AdminTable}.
+
+```typescript
+interface AdminTableProps<T> {
+  rows: T[]
+  columns: AdminTableColumn<T>[]
+  rowKey: (row: T) => string
+  loading?: boolean
+  skeletonRowCount?: number
+  /** Click handler for whole-row navigation. */
+  onRowClick?: (row: T) => void
+  /** When set, renders a leading checkbox column and tracks selection. */
+  bulkSelect?: boolean
+  /**
+   * Selected row keys. Honored ONLY when `onSelectedIdsChange` is also
+   * provided (controlled mode); otherwise selection state is internal.
+   */
+  selectedIds?: string[]
+  /** Selection-change handler — providing it switches selection to controlled mode. */
+  onSelectedIdsChange?: (ids: string[]) => void
+  /** Kebab menu items. When set, a trailing right-aligned actions column is rendered. */
+  rowActions?: AdminTableRowAction<T>[]
+  rowActionsAriaLabel?: (row: T) => string
+  /** Slot rendered below the table (typically a `<Pagination>` row). */
+  footer?: ReactNode
+  className?: string
+  /** Optional `data-mol-id` to attach to the rendered `<tbody>` for tests/AI. */
+  tbodyDataMolId?: string
+}
+```
+
+#### `AdminTableRowAction`
+
+One entry in the row-action kebab menu.
+
+```typescript
+interface AdminTableRowAction<T> {
+  /** Label rendered in the menu (post-i18n). */
+  label: ReactNode
+  /** Called when the action is selected. */
+  onSelect: (row: T) => void | Promise<void>
+  /** Optional `data-mol-id` for tests/automation. */
+  dataMolIdFor?: (row: T) => string
+  /** Marks the action visually as destructive (red). */
+  destructive?: boolean
+  /** Optional href for non-click actions (rendered as a link). */
+  hrefFor?: (row: T) => string
+}
+```
+
+#### `AdminTableRowActionsProps`
+
+Props for {@link AdminTableRowActions}.
+
+```typescript
+interface AdminTableRowActionsProps<T> {
+  row: T
+  actions: AdminTableRowAction<T>[]
+  ariaLabel: string
+}
+```
+
+### Functions
+
+#### `AdminTable(props)`
+
+Admin-style data table.
+
+```typescript
+function AdminTable({
+  rows,
+  columns,
+  rowKey,
+  loading,
+  skeletonRowCount = 8,
+  onRowClick,
+  bulkSelect,
+  selectedIds = [],
+  onSelectedIdsChange,
+  rowActions,
+  rowActionsAriaLabel,
+  footer,
+  className,
+  tbodyDataMolId,
+}: AdminTableProps<T>): JSX.Element
+```
+
+#### `AdminTableRowActions(props)`
+
+Three-dots row actions menu.
+
+```typescript
+function AdminTableRowActions({
+  row,
+  actions,
+  ariaLabel,
+}: AdminTableRowActionsProps<T>): JSX.Element
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-react` ^1.0.1
+- `@molecule/app-ui` ^1.0.1
+- `@molecule/app-ui-react` ^1.0.1
+- `react` ^18.0.0 || ^19.0.0
+
+### Runtime Dependencies
+
+- `@molecule/app-react`
+- `@molecule/app-ui`
+- `@molecule/app-ui-react`
+- `react`
+
+- Requires the Material Symbols Outlined font (row-actions kebab icon) —
+  load it via an `@molecule/app-fonts-*` bond or a font link.
+- Styling resolves entirely through the ClassMap bond (`getClassMap()` /
+  `cm.*`): surfaces, borders, text, and hover all use theme tokens, so the
+  table renders correctly in both light and dark themes with no per-app
+  restyling.
+- `selectedIds` is honored only together with `onSelectedIdsChange`
+  (controlled selection); omit both for internal selection state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-admin-table-react",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Admin-style data table: column-defs, row click navigation, bulk-select, row-action kebab menu, loading skeleton, pagination slot. Generalised from AdminProductsTable / AdminOrdersTable in the online-store flagship.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -27,16 +28,21 @@
     "react"
   ],
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/app/features/admin-table-react"
+  },
   "peerDependencies": {
-    "@molecule/app-react": "^1.0.0",
-    "@molecule/app-ui": "^1.0.0",
-    "@molecule/app-ui-react": "^1.0.0",
+    "@molecule/app-react": "^1.0.1",
+    "@molecule/app-ui": "^1.0.1",
+    "@molecule/app-ui-react": "^1.0.1",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@molecule/app-react": "1.0.0",
-    "@molecule/app-ui": "1.0.0",
-    "@molecule/app-ui-react": "1.0.0",
+    "@molecule/app-react": "1.0.1",
+    "@molecule/app-ui": "1.0.1",
+    "@molecule/app-ui-react": "1.0.1",
     "@types/node": "26.1.2",
     "@types/react": "19.2.17",
     "react": "19.2.8",