bonsaif-ui 0.1.19 → 0.1.24

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.
 
@@ -32,12 +73,169 @@ The package includes reusable components migrated from `prime-auth` and new shar
 
 ### Forms
 
-- `InputField`, `TextInput`, `Textarea`: text inputs with Bonsaif styling.
+- `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 {
+  EmailField,
+  PhoneField,
+  emailFormat,
+  maxValue,
+  minLength,
+  minValue,
+  phoneFormat,
+  required,
+  validateForm,
+  useValidationVisibility,
+  type ValidationSchema,
+} from "bonsaif-ui";
+
+type AccountForm = {
+  contactName: string;
+  contactEmail: string;
+  contactCountryCode: string;
+  contactPhone: string;
+  seats: string;
+  discountCode: string;
+};
+
+const schema = {
+  contactName: [required("Escribe el nombre."), minLength(3)],
+  contactEmail: [required(), emailFormat()],
+  contactCountryCode: [required()],
+  contactPhone: (value, values) =>
+    phoneFormat()(`${values.contactCountryCode} ${value}`),
+  seats: [required(), minValue(1), maxValue(500)],
+  discountCode: (value, values) =>
+    Number(values.seats) > 100 && String(value).trim() === ""
+      ? "Solicita un codigo para cuentas de mas de 100 usuarios."
+      : undefined,
+} satisfies ValidationSchema<AccountForm>;
+
+function AccountFormExample() {
+  const [form, setForm] = useState<AccountForm>({
+    contactName: "",
+    contactEmail: "",
+    contactCountryCode: "+1",
+    contactPhone: "",
+    seats: "",
+    discountCode: "",
+  });
+  const validationResult = useMemo(
+    () => validateForm(form, schema),
+    [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 (
+    <form noValidate onSubmit={submitForm}>
+      <EmailField
+        label="Correo"
+        value={form.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"
+        countryCode={form.contactCountryCode}
+        onCountryCodeChange={(countryCode) =>
+          setForm((current) => ({ ...current, contactCountryCode: countryCode }))
+        }
+        allowedCountryCodes={["+1", "+34", "+52", "+57", "+58"]}
+        value={form.contactPhone}
+        onChange={(event) => {
+          validationVisibility.touchField("contactPhone");
+          setForm((current) => ({
+            ...current,
+            contactPhone: event.currentTarget.value,
+          }));
+        }}
+        onBlur={() => validationVisibility.touchField("contactPhone")}
+        error={validationVisibility.getFieldError("contactPhone")}
+        validate={false}
+        errorDisplay="tooltip"
+      />
+      <button type="submit" disabled={!validationResult.valid}>
+        Guardar
+      </button>
+    </form>
+  );
+}
+```
+
 ### Actions And Overlays
 
 - `Button`, `BonsaifButton`: action buttons.
@@ -139,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.