bonsaif-ui 0.1.20 → 0.1.25

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.22 - 2026-05-06
+
+- Replace `StatusSelect` native select behavior with a fully custom Bonsaif dropdown menu for consistent inline status changes.
+
+## 0.1.21 - 2026-05-06
+
+- Add `StatusSelect`, a compact pill-style select for changing statuses inline while preserving badge-like visual styling.
+
 ## 0.1.18 - 2026-05-06
 
 - Render `DataTable` rows with CSS Grid instead of native table layout so column widths, resize handles, sticky columns, and future customization are controlled by the component.

package/README.md

@@ -1,25 +1,66 @@
 # bonsaif-ui
 
-Reusable React components for Bonsaif applications.
+Reusable React components for Bonsaif applications. The package focuses on internal product screens: dense forms, admin tables, status feedback, drawers, page headers, and service composition patterns.
 
-## Package
+## Start Here
+
+Install the package, import the stylesheet once in the app shell, and then import only the components needed by each screen.
 
 ```bash
 npm install bonsaif-ui
 ```
 
-## Usage
-
 ```tsx
-import { Button, DataTable, PageHeader } from "bonsaif-ui";
+import { Button, FileUpload, PageHeader } from "bonsaif-ui";
 import "bonsaif-ui/styles.css";
 
 export function Example() {
-  return <Button>Save</Button>;
+  return (
+    <>
+      <PageHeader title="Documentos" currentPath="/admin/documents" />
+      <FileUpload
+        label="Adjuntos"
+        multiple
+        onFilesChange={(files) => console.log(files)}
+      />
+      <Button>Guardar</Button>
+    </>
+  );
 }
 ```
 
-## Components
+For Next.js consumers using a local package or monorepo setup, add `transpilePackages: ["bonsaif-ui"]` in `next.config.ts`.
+
+## Choose A Component
+
+| Need | Start with | Why |
+| --- | --- | --- |
+| Build an admin page header | `PageHeader` | Breadcrumbs, metadata, page actions, and compact action buttons. |
+| Capture form data | `InputField`, `EmailField`, `PhoneField`, `NumberField`, `FileUpload` | Shared labels, helpers, errors, focus states, and validation surfaces. |
+| Search or filter a list | `SearchableSelect`, `CompactFilterSelect`, `CompactSearchInput` | Compact controls that work inside toolbars and table headers. |
+| Show tabular records | `DataTable`, `Pagination` | Sorting, selection, loading, empty state, column width behavior, and paging. |
+| Confirm or edit in context | `Drawer`, `Modal`, `ConfirmDialog` | Overlays with consistent chrome and guardrails for unsaved changes. |
+| 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
+
+Use Storybook for component documentation and the playground for full-screen integration examples.
+
+```bash
+npm run storybook
+npm run storybook:build
+```
+
+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
+```
+
+## Component Map
 
 The package includes reusable components migrated from `prime-auth` and new shared primitives for Bonsaif apps.
 
@@ -33,15 +74,60 @@ The package includes reusable components migrated from `prime-auth` and new shar
 ### Forms
 
 - `InputField`, `EmailField`, `PhoneField`, `NumberField`, `TextInput`, `Textarea`: inputs with Bonsaif styling and inline validation for email and phone values.
+- `FileUpload`: drag-and-drop or click-to-browse file selection with single-file and multi-file modes.
 - `SearchableSelect`, `CompactFilterSelect`, `CompactSearchInput`: select and filter controls.
 - `CalendarPicker`, `DateRangePicker`: single-date and range selection.
 - `Checkbox`, `RadioGroup`, `Toggle`: boolean and option controls.
 - `FormField`: label, helper, error, and required wrapper for custom controls.
 
+### File Uploads
+
+Use `FileUpload` when a form needs attachments, CSV imports, evidence files, or any file selector that should support both drag-and-drop and regular browsing.
+
+```tsx
+import { useState } from "react";
+import { FileUpload } from "bonsaif-ui";
+
+export function AttachmentField() {
+  const [files, setFiles] = useState<File[]>([]);
+
+  return (
+    <FileUpload
+      label="Adjuntos"
+      multiple
+      appendFiles
+      maxFiles={4}
+      accept=".pdf,.png,.jpg,.jpeg,.csv"
+      value={files}
+      onFilesChange={setFiles}
+      helperText="PDF, imagenes o CSV. Maximo 4 archivos."
+      onRejectedFiles={(rejectedFiles) => {
+        console.warn("Archivos rechazados", rejectedFiles);
+      }}
+    />
+  );
+}
+```
+
+Useful props:
+
+| Prop | Description |
+| --- | --- |
+| `multiple` | Allows selecting or dropping more than one file. |
+| `accept` | Native accept filter plus drag-and-drop filtering for MIME types and extensions. |
+| `maxFiles` | Limits the accepted file list. |
+| `appendFiles` | Adds new files to the current selection instead of replacing it. |
+| `value` / `defaultValue` | Controlled or uncontrolled selected files. |
+| `onFilesChange` | Receives the accepted `File[]`. |
+| `onRejectedFiles` | Receives files blocked by `accept`. |
+| `showFileList` | Shows or hides the selected file list. |
+
 #### Form Validation
 
 Use `validateForm` with reusable validators to validate complete forms before saving. Validators run in order and return the first error per field. Add `noValidate` to the form to avoid native browser validation, then pass each error to the field with `errorDisplay="tooltip"` when the message should appear in the compact validation tooltip.
 
+Use `useValidationVisibility` when a form should validate immediately for save-button state but should not show red errors until the user touches a field or attempts to submit. Call `submit()` before blocking an invalid save, `touchField(field)` from `onChange`/`onBlur`, and `reset()` when opening a new draft.
+
 ```tsx
 import { useMemo, useState, type FormEvent } from "react";
 import {
@@ -54,6 +140,7 @@ import {
   phoneFormat,
   required,
   validateForm,
+  useValidationVisibility,
   type ValidationSchema,
 } from "bonsaif-ui";
 
@@ -93,12 +180,15 @@ function AccountFormExample() {
     [form],
   );
   const errors = validationResult.errors;
+  const validationVisibility = useValidationVisibility(errors);
 
   function submitForm(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
+    validationVisibility.submit();
     if (!validationResult.valid) return;
 
     saveAccount(form);
+    validationVisibility.reset();
   }
 
   return (
@@ -106,9 +196,17 @@ function AccountFormExample() {
       <EmailField
         label="Correo"
         value={form.contactEmail}
-        error={errors.contactEmail}
+        error={validationVisibility.getFieldError("contactEmail")}
         validate={false}
         errorDisplay="tooltip"
+        onChange={(event) => {
+          validationVisibility.touchField("contactEmail");
+          setForm((current) => ({
+            ...current,
+            contactEmail: event.currentTarget.value,
+          }));
+        }}
+        onBlur={() => validationVisibility.touchField("contactEmail")}
       />
       <PhoneField
         label="Telefono"
@@ -118,13 +216,15 @@ function AccountFormExample() {
         }
         allowedCountryCodes={["+1", "+34", "+52", "+57", "+58"]}
         value={form.contactPhone}
-        onChange={(event) =>
+        onChange={(event) => {
+          validationVisibility.touchField("contactPhone");
           setForm((current) => ({
             ...current,
             contactPhone: event.currentTarget.value,
-          }))
-        }
-        error={errors.contactPhone}
+          }));
+        }}
+        onBlur={() => validationVisibility.touchField("contactPhone")}
+        error={validationVisibility.getFieldError("contactPhone")}
         validate={false}
         errorDisplay="tooltip"
       />
@@ -237,14 +337,6 @@ How it works:
 
 App-coupled components were adapted to receive routing, session, and navigation data through props so the library does not import private `prime-auth` modules.
 
-## Playground Documentation
-
-Run the playground to browse the components by category. Each code example includes a copy action powered by `CopyButton`.
-
-```bash
-npm run playground
-```
-
 ## UI Primitives
 
 Small primitives cover common product UI patterns while keeping the same Bonsaif visual tokens.