bonsaif-ui 0.1.27 → 0.1.29

package/README.md

@@ -43,22 +43,17 @@ For Next.js consumers using a local package or monorepo setup, add `transpilePac
 | Explain status | `Alert`, `StatusBadge`, `StatusSelect`, `EmptyState`, `LoadingState` | Clear operational feedback for data states and workflows. |
 | Compose related modules | `DynamicDetailTabs` | Parent-detail layout with lazy loaded child modules. |
 
-## Documentation Playground
+## Documentation App
 
-Use Storybook for component documentation and the playground for full-screen integration examples.
+Use the local Next.js documentation app for component documentation and full-screen integration examples. The app consumes `bonsaif-ui` through the local package entrypoint, so the examples use the same exports that consuming products use.
 
 ```bash
-npm run storybook
-npm run storybook:build
+npm run docs
+npm run docs:build
+npm run docs:preview
 ```
 
-Storybook is the main documentation surface for individual components. It includes autodocs, controls, accessibility checks, and isolated states such as `disabled`, `error`, `loading`, single-file upload, and multi-file upload.
-
-Run the playground when you need to see spacing, page headers, navigation, copy buttons, dark mode, and integrated behavior in one app-like screen.
-
-```bash
-npm run playground
-```
+The documentation includes isolated states such as `disabled`, `error`, `loading`, single-file upload, multi-file upload, overlays, validation, shells, tables, composition patterns, and dark mode in one app-like screen.
 
 ## Component Map
 
@@ -71,6 +66,22 @@ The package includes reusable components migrated from `prime-auth` and new shar
 - `GlobalScrollbars`: global OverlayScrollbars setup.
 - `SectionPanel`: reusable section container with header, actions, body, and footer.
 
+#### PageHeader Breadcrumbs
+
+`PageHeader` can build local breadcrumbs from `currentPath` or render custom `breadcrumbs`. Those breadcrumbs are intended for standalone screens and development views.
+
+When a page is opened through Prime Auth SSO, `MicroserviceFrame` passes `primeAuthOrigin` and `primeAuthProjectKey` to the embedded app. `PageHeader` detects those parameters, stores the SSO state for the browser session, and hides its local breadcrumbs so the Prime Auth shell remains the single source for the global breadcrumb trail.
+
+Use `showBreadcrumbs={false}` when a standalone page should also hide the local breadcrumb.
+
+```tsx
+<PageHeader
+  title="Usuarios"
+  currentPath="/admin/users"
+  showBreadcrumbs={false}
+/>
+```
+
 ### Forms
 
 - `InputField`, `EmailField`, `PhoneField`, `NumberField`, `TextInput`, `Textarea`: inputs with Bonsaif styling and inline validation for email and phone values.
@@ -310,7 +321,7 @@ Useful props:
 - `unsavedChangesCancelLabel`: label for the action that keeps editing.
 - `onDiscardChanges`: optional cleanup before `onClose` runs after discard confirmation.
 
-The playground includes a live drawer example: edit the note, then try closing with the `X`, backdrop, Escape, or Cancel button to see the discard modal.
+The documentation app includes a live drawer example: edit the note, then try closing with the `X`, backdrop, Escape, or Cancel button to see the discard modal.
 
 How it works:
 
@@ -390,6 +401,8 @@ Header controls for column reordering, resizing, and visibility are floating con
 
 DataTable renders its rows with CSS Grid instead of the browser's native table layout. Column resizing uses the saved column widths as the base grid tracks, fills any spare container width across visible columns, and switches to horizontal scrolling when the resized columns exceed the available space. This keeps resize behavior predictable without leaving a blank gutter on the right side.
 
+DataTable can also expose a table query state for server-backed screens. Enable `enableBql` to show a compact BQL input in the toolbar, listen to `onQueryChange` to receive the current BQL text, column filters, sort, page, page size, and hidden columns, and use `persistState` with `storageKey` when a screen should reopen with saved filters or BQL. The component only emits and stores query state; each app should validate and translate BQL on the server for its own allowed fields.
+
 ```tsx
 <DataTable
   columns={columns}
@@ -398,6 +411,24 @@ DataTable renders its rows with CSS Grid instead of the browser's native table l
   minTableWidth={810}
 />
 
+<DataTable
+  columns={columns}
+  data={rows}
+  getRowId={(row) => row.id}
+  storageKey="prime-auth-users-v5"
+  enableBql
+  persistState={{
+    layout: true,
+    filters: true,
+    sort: true,
+    bql: true,
+    pagination: true,
+  }}
+  onQueryChange={(query) => {
+    // Send query.bql, query.filters, query.conditionFilters, and query.sort to the API.
+  }}
+/>
+
 <DataTable
   columns={columns}
   data={rows.slice(0, 25)}