bonsaif-ui 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1 - 2026-05-02
+
+- Mark the generated JavaScript bundle as a Next.js client bundle.
+- Add compatibility props to `UserAvatar` for name display and label styling.
+
 ## 0.1.0 - 2026-05-02
 
 - Initial npm-ready release of reusable Bonsaif React UI components.

package/README.md

@@ -23,13 +23,283 @@ export function Example() {
 
 The package includes reusable components migrated from `prime-auth`:
 
-- UI: `Button`, `CalendarPicker`, `CompactFilterSelect`, `CompactSearchInput`, `ConfirmDialog`, `DataTable`, `DateRangePicker`, `Drawer`, `InputField`, `LoadingState`, `Modal`, `MouseTooltip`, `SearchableSelect`, `TextInput`, `Toggle`.
+- UI: `Button`, `CalendarPicker`, `CompactFilterSelect`, `CompactSearchInput`, `ConfirmDialog`, `DataTable`, `DateRangePicker`, `Drawer`, `InputField`, `LoadingState`, `Modal`, `MouseTooltip`, `SearchableSelect`, `StepWizard`, `TextInput`, `Toggle`.
+- Composition: `DynamicDetailTabs`.
 - Layout: `AuthShell`, `GlobalScrollbars`, `PageHeader`, `PageSearchInput`, `PrimeAuthRouteShell`.
 - Messaging and services: `PrimeSuiteChatFrame`, `MicroserviceFrame`.
 - Notifications and users: `PrimeAuthToaster`, `UserAvatar`.
 
 App-coupled components were adapted to receive routing, session, and navigation data through props so the library does not import private `prime-auth` modules.
 
+## DataTable
+
+`DataTable` owns its horizontal and vertical scrolling. When a table is rendered inside a constrained panel, pass `minTableWidth` so the table keeps usable column widths and exposes its own internal horizontal scrollbar.
+
+```tsx
+<DataTable
+  columns={columns}
+  data={rows}
+  getRowId={(row) => row.id}
+  minTableWidth={810}
+/>
+```
+
+## StepWizard
+
+`StepWizard` renders animated, gated steps. A future step stays locked until every previous non-optional step is marked as completed.
+
+```tsx
+import { Button, StepWizard } from "bonsaif-ui";
+
+<StepWizard
+  steps={[
+    {
+      id: "method",
+      title: "Metodo de carga",
+      description: "Cliente, plantilla y archivo",
+      content: (wizard) => (
+        <Button onClick={() => wizard.completeStep()}>
+          Marcar completado
+        </Button>
+      ),
+    },
+    {
+      id: "sms",
+      title: "Configuracion de SMS",
+      content: (wizard) => (
+        <Button onClick={() => wizard.completeStep()}>
+          Marcar completado
+        </Button>
+      ),
+    },
+    {
+      id: "summary",
+      title: "Resumen",
+      content: <Summary />,
+    },
+  ]}
+  onBlockedStep={(step, requiredStep) => {
+    toast.error(`Completa ${requiredStep.title} antes de abrir ${step.title}.`);
+  }}
+/>
+```
+
+The component can be controlled with `activeStepId`, `completedStepIds`, `onActiveStepChange`, and `onCompletedStepIdsChange`.
+
+## DynamicDetailTabs
+
+`DynamicDetailTabs` renders a parent-detail panel next to a tabbed workspace. Each tab is declared with a `service` id and loaded lazily through a registry owned by the consuming app.
+
+Use this component when a main entity detail needs to host multiple independent modules, such as related lists, API keys, settings, contacts, billing records, or any child feature that owns its own list/detail flow.
+
+### Basic Setup
+
+```tsx
+import {
+  DynamicDetailTabs,
+  type DynamicDetailModuleProps,
+  type DynamicDetailModuleRegistry,
+  type DynamicDetailParentPanelProps,
+} from "bonsaif-ui";
+
+type ClientContext = {
+  clientId: string;
+  permissions: string[];
+};
+
+const moduleRegistry: DynamicDetailModuleRegistry<ClientContext> = {
+  "views/settings/lv_server_by_client": () =>
+    import("@/modules/settings/ServerByClientModule"),
+  "views/settings/lv_account_executive": () =>
+    import("@/modules/settings/AccountExecutiveModule"),
+  "views/api_keys/lv_api_keys": () =>
+    import("@/modules/api-keys/ApiKeysModule"),
+};
+
+function ClientSummaryPanel({
+  parent,
+  context,
+  selectedLink,
+}: DynamicDetailParentPanelProps<ClientContext, Client>) {
+  return (
+    <aside>
+      <h2>{parent.name}</h2>
+      <p>Cliente: {context.clientId}</p>
+      <p>Vista activa: {selectedLink?.label ?? "Sin vista"}</p>
+    </aside>
+  );
+}
+
+export function ClientDetailPage({ client }: { client: Client }) {
+  return (
+    <DynamicDetailTabs
+      title="Modulos relacionados"
+      subtitle="Listados y detalles cargados de forma independiente"
+      parent={client}
+      context={{ clientId: client._id, permissions: client.permissions }}
+      parentPanelComponent={ClientSummaryPanel}
+      links={[
+        {
+          service: "views/settings/lv_server_by_client",
+          label: "Servidores",
+        },
+        {
+          service: "views/settings/lv_account_executive",
+          label: "Ejecutivos",
+        },
+        {
+          service: "views/api_keys/lv_api_keys",
+          label: "API Keys",
+          requiredPermission: "api-keys:view",
+        },
+      ]}
+      moduleRegistry={moduleRegistry}
+      searchableTabs="auto"
+      tabsSearchThreshold={6}
+      tabsSearchPlaceholder="Buscar modulo..."
+      canAccess={(link, context) => {
+        if (!link.requiredPermission) return true;
+        const permissions = Array.isArray(link.requiredPermission)
+          ? link.requiredPermission
+          : [link.requiredPermission];
+        return permissions.every((permission) =>
+          context.permissions.includes(permission),
+        );
+      }}
+    />
+  );
+}
+```
+
+### Parent Panel Contract
+
+The left panel can be static JSX with `parentPanel`, a reusable component with `parentPanelComponent`, or a render callback with `renderParentPanel`.
+
+```tsx
+import { useState } from "react";
+import { Button, Drawer, type DynamicDetailParentPanelProps } from "bonsaif-ui";
+
+function ClientSummaryPanel({
+  parent,
+  context,
+  selectedLink,
+  visibleLinks,
+  onSelectService,
+}: DynamicDetailParentPanelProps<ClientContext, Client>) {
+  const [editing, setEditing] = useState(false);
+
+  return (
+    <>
+      <section>
+        <h2>{parent.name}</h2>
+        <p>{context.clientId}</p>
+        <p>{selectedLink?.label}</p>
+        <Button onClick={() => setEditing(true)}>Editar</Button>
+        <button onClick={() => onSelectService(visibleLinks[0])}>
+          Ir a primera vista
+        </button>
+      </section>
+
+      <Drawer open={editing} onClose={() => setEditing(false)} title="Editar cliente">
+        <ClientEditForm client={parent} onSaved={() => setEditing(false)} />
+      </Drawer>
+    </>
+  );
+}
+
+<DynamicDetailTabs
+  parent={client}
+  context={context}
+  links={links}
+  moduleRegistry={moduleRegistry}
+  parentPanelComponent={ClientSummaryPanel}
+/>
+```
+
+### Child Module Contract
+
+Each module should export a default React component. The module receives the shared parent context and navigation helpers.
+
+```tsx
+import { Button, DataTable, type DynamicDetailModuleProps } from "bonsaif-ui";
+
+type ClientContext = {
+  clientId: string;
+  permissions: string[];
+};
+
+export default function ApiKeysModule({
+  context,
+  activeItemId,
+  onOpenDetail,
+  onBackToList,
+}: DynamicDetailModuleProps<ClientContext>) {
+  if (activeItemId) {
+    return (
+      <section>
+        <Button variant="secondary" onClick={onBackToList}>
+          Volver al listado
+        </Button>
+        <ApiKeyDetail clientId={context.clientId} apiKeyId={activeItemId} />
+      </section>
+    );
+  }
+
+  return <ApiKeysList clientId={context.clientId} onOpen={onOpenDetail} />;
+}
+```
+
+### Props
+
+| Prop | Description |
+| --- | --- |
+| `parentPanel` | Static React content rendered in the left parent-detail panel. |
+| `parentPanelComponent` | Reusable component rendered in the left panel with workspace props. |
+| `renderParentPanel` | Render callback alternative for fully custom left-panel composition. |
+| `context` | Shared context passed to every loaded module. |
+| `parent` | Optional parent object passed to every module. |
+| `links` | Declarative tab config. Each item needs at least `service`. |
+| `moduleRegistry` | Map of `service` ids to lazy import functions. |
+| `loadModule` | Optional fallback loader when a service is not in `moduleRegistry`. |
+| `canAccess` | Optional permission/filter callback for hiding tabs. |
+| `activeService` | Controlled active tab service id. |
+| `initialService` | Initial uncontrolled active tab service id. |
+| `onActiveServiceChange` | Callback fired when the user selects a tab. |
+| `keepAlive` | Keeps loaded module components cached. Defaults to `true`. |
+| `loadingState` | Optional custom loading UI. |
+| `errorState` | Optional render function for module loading errors. |
+| `searchableTabs` | Enables the tab search box. Use `true`, `false`, or `"auto"`. Defaults to `"auto"`. |
+| `tabsSearchThreshold` | Minimum visible tab count before automatic search appears. Defaults to `6`. |
+| `tabsSearchPlaceholder` | Placeholder text for the tab search input. |
+| `tabsSearchValue` | Optional controlled search value. |
+| `onTabsSearchChange` | Callback fired when the tab search changes. |
+| `emptySearchState` | Optional custom UI when the search returns no tabs. |
+| `showTabCount` | Shows `filtered / total` tab count. Defaults to `true`. |
+
+### Link Shape
+
+```ts
+type DynamicDetailTabLink = {
+  service: string;
+  label?: string;
+  description?: string;
+  icon?: React.ReactNode;
+  badge?: React.ReactNode;
+  disabled?: boolean;
+  hidden?: boolean;
+  requiredPermission?: string | string[];
+};
+```
+
+### Notes
+
+- The consuming app owns business logic, API calls, permissions, and actual module imports.
+- `bonsaif-ui` owns only the layout, tabs, lazy loading state, error state, and list/detail navigation helpers.
+- When there are many tabs, the component keeps horizontal scrolling and can show an animated header search. With `searchableTabs="auto"`, the search icon appears when the visible tab count reaches `tabsSearchThreshold`, and the input expands inline before the close icon.
+- Tab search matches `label`, generated service label, `description`, and `service`. Arrow keys, Home, and End navigate between currently filtered tabs.
+- Prefer static registry keys over arbitrary backend-provided import paths. If links come from a backend, map those service ids to known registry entries in the frontend.
+- For Next.js consumers using the local package or monorepo setup, add `transpilePackages: ["bonsaif-ui"]` in `next.config.ts`.
+
 ## Scripts
 
 ```bash