@axzydev/axzy_ui_system 1.4.7 → 1.5.0

package/src/components/organisms/dropfile/dropfile.doc.mdx

@@ -1,74 +0,0 @@
-import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
-import * as StoriesData from './dropfile.stories';
-
-<Meta of={StoriesData} />
-
-# ITDropfile
-
-A drag-and-drop file upload zone with preview support for images. Tracks upload lifecycle with status enumeration and provides confirm/cancel actions. Configurable accepted file types limit which formats are allowed.
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `onFileSelect` | `(file: File \| null) => void` | — | Called when a file is selected or cleared. |
-| `onCancel` | `() => void` | — | Called when the user cancels the current selection. |
-| `onSubmit` | `(file: File) => void` | — | Called when the user confirms and submits the file. |
-| `acceptedFileTypes` | `FileTypeEnum[]` | — | List of accepted MIME types (PDF, XLS, CSV, PNG, JPG, etc.). |
-| `contentClassName` | `string` | — | CSS classes for the preview/content area. |
-| `containerClassName` | `string` | — | CSS classes for the outermost container. |
-| `showStatusBadge` | `boolean` | — | Whether to show the status badge (pending/uploading/uploaded/error). |
-| `uploadStatus` | `UploadStatus` | — | Externally controlled upload status. |
-| `onStatusChange` | `(status: UploadStatus) => void` | — | Callback when upload status changes. |
-| `initialPreviewUrl` | `string \| null` | — | Initial preview URL shown before any file is selected (e.g., editing an existing entry). |
-| `view` | `"drop" \| "button"` | `"drop"` | `"drop"` renders the dropzone/preview inline. `"button"` renders a compact trigger button that opens the same UI inside an `ITDialog` modal. |
-| `buttonLabel` | `string` | `"Subir archivo"` | Label for the trigger button when `view="button"` and no file is selected yet. |
-| `modalTitle` | `string` | `buttonLabel` | Title of the modal opened when `view="button"`. |
-
-### Enums
-
-| Enum | Values |
-|------|--------|
-| `UploadStatus` | `PENDING` (`"pendiente"`), `UPLOADING` (`"subiendo"`), `UPLOADED` (`"subido"`), `ERROR` (`"error"`) |
-| `FileTypeEnum` | `PDF`, `XLS`, `XLSX`, `CSV`, `PNG`, `JPG`, `JPEG` |
-
-## Usage
-
-```tsx
-import { ITDropfile, UploadStatus, FileTypeEnum } from '@axzydev/axzy_ui_system';
-
-<ITDropfile
-  onFileSelect={(file) => setSelectedFile(file)}
-  onSubmit={(file) => uploadFile(file)}
-  onCancel={() => clearFile()}
-  acceptedFileTypes={[FileTypeEnum.PNG, FileTypeEnum.JPG, FileTypeEnum.PDF]}
-  uploadStatus={UploadStatus.PENDING}
-  showStatusBadge
-/>
-```
-
-### `view="button"`
-
-```tsx
-<ITDropfile
-  view="button"
-  buttonLabel="Subir archivos"
-  onFileSelect={(file) => setSelectedFile(file)}
-/>
-```
-
-Use this when you'd otherwise write your own button + modal wrapper around `ITDropfile` — it's built in. The button shows the picked file's name (and status badge, if `showStatusBadge`) once one is selected, and reopens the same dropzone/preview to change it. ~900ms after a successful confirm the modal closes **and the selection resets**, so the button goes back to `buttonLabel`, ready to upload another file — this mode is built for repeated uploads (e.g. an attachments list), replacing the old pattern of remounting `ITDropfile` with a changing `key` after each upload.
-
-## Notes
-
-- Displays image preview for image file types; shows a file icon for non-image types.
-- The `uploadStatus` and `showStatusBadge` props enable external lifecycle control and visual feedback.
-- `initialPreviewUrl` is useful for edit forms where an existing file is already associated.
-- Only one file at a time is supported — selecting a new file replaces the current one.
-- The confirm/cancel flow gives users a chance to review their selection before submission.
-
-## Stories
-
-<Primary />
-<Controls />
-<Stories />

package/src/components/organisms/dropfile/dropfile.stories.tsx

@@ -1,93 +0,0 @@
-import type { Meta } from '@storybook/react';
-import ITDropfile, { UploadStatus } from '@/components/organisms/dropfile/dropfile';
-
-const meta = {
-  title: 'Components/Actions/ITDropfile',
-  component: ITDropfile,
-  parameters: {
-    layout: 'centered',
-  },
-  argTypes: {
-    onFileSelect: { action: 'file selected' },
-    onCancel: { action: 'cancelled' },
-    onSubmit: { action: 'submitted' },
-    showStatusBadge: { control: 'boolean' },
-    uploadStatus: {
-      control: 'select',
-      options: Object.values(UploadStatus),
-    },
-    view: {
-      control: 'radio',
-      options: ['drop', 'button'],
-    },
-  },
-} satisfies Meta<typeof ITDropfile>;
-
-export default meta;
-
-// Wrapper for stateful file handling in story
-const DropfileWrapper = (args: any) => {
-    return <ITDropfile {...args} className="w-[500px]" />;
-}
-
-export const Default: any = {
-  render: (args) => <DropfileWrapper {...args} />,
-  args: {
-    showStatusBadge: true,
-    containerClassName: 'w-[400px]',
-  },
-};
-
-export const WithImage: any = {
-  render: (args) => <DropfileWrapper {...args} />,
-  args: {
-    showStatusBadge: true,
-    initialPreviewUrl: 'https://images.unsplash.com/photo-1575936123452-b67c3203c357?ixlib=rb-4.0.3&auto=format&fit=crop&w=1000&q=80',
-    uploadStatus: UploadStatus.UPLOADED,
-    containerClassName: 'w-[400px]',
-  },
-    parameters: {
-        docs: {
-            description: {
-                story: 'Simulates a pre-loaded image (e.g., editing an existing entry).'
-            }
-        }
-    }
-};
-
-export const Uploading: any = {
-  render: (args) => <DropfileWrapper {...args} />,
-  args: {
-    showStatusBadge: true,
-    initialPreviewUrl: 'https://images.unsplash.com/photo-1575936123452-b67c3203c357?ixlib=rb-4.0.3&auto=format&fit=crop&w=1000&q=80',
-    uploadStatus: UploadStatus.UPLOADING,
-    containerClassName: 'w-[400px]',
-  },
-};
-
-export const ButtonView: any = {
-  render: (args) => <DropfileWrapper {...args} />,
-  args: {
-    view: 'button',
-    buttonLabel: 'Subir archivos',
-    showStatusBadge: true,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Compact trigger button that opens the dropzone/preview inside a modal (`ITDialog`) — use this instead of wrapping `ITDropfile` in your own "open a modal" button.',
-      },
-    },
-  },
-};
-
-export const ErrorState: any = {
-  render: (args) => <DropfileWrapper {...args} />,
-  args: {
-    showStatusBadge: true,
-    initialPreviewUrl: 'https://images.unsplash.com/photo-1575936123452-b67c3203c357?ixlib=rb-4.0.3&auto=format&fit=crop&w=1000&q=80',
-    uploadStatus: UploadStatus.ERROR,
-    containerClassName: 'w-[400px]',
-  },
-};

package/src/components/organisms/form-builder/formBuilder.doc.mdx

@@ -1,251 +0,0 @@
-import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
-import * as StoriesData from './formBuilder.stories';
-
-<Meta of={StoriesData} />
-
-# ITFormBuilder
-
-Dynamic form generator that renders fields from a JSON-like array. Integrates with
-Formik + Yup, supports both a backward-compatible V1 (`fields`) and the powerful
-Enterprise V2 (`config`) API, and exposes a `useFormBuilder()` hook for building
-custom submit buttons, progress meters, and dirty-state indicators.
-
-## When to use
-
-- You want to drive a form from a declarative config (server-driven forms, CMS schemas).
-- You need conditional fields (`renderWhen`), derived values (`onChangeAction`),
-  dynamic props (`dynamicProps`), or cascading selects.
-- You need to render a custom React component as a field (`type: "custom"`).
-
-## Props
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `fields` | `FieldConfig[]` | — | No | Legacy V1 field definitions. Kept for backward compatibility. |
-| `config` | `FieldConfigV2[]` | — | No | V2 field configuration. Recommended. Shadows `fields` when both supplied. |
-| `columns` | `number` | `12` | No | Grid column count (1–12). |
-| `values` | `Record<string, unknown>` | — | Yes | Current form values keyed by field `name`. |
-| `handleChange` | `(event) => void` | — | Yes | Change handler — pass Formik's `handleChange` directly. |
-| `handleBlur` | `(event) => void` | — | Yes | Blur handler — pass Formik's `handleBlur` directly. |
-| `touched` | `Record<string, boolean>` | — | Yes | Touch state keyed by field `name`. |
-| `errors` | `Record<string, string>` | — | Yes | Errors keyed by field `name`. |
-| `setFieldValue` | `(field, value, shouldValidate?) => Promise` | no-op | No | Required for V2 `onChangeAction` and `dynamicProps` side effects. |
-| `setFieldTouched` | `(field, touched?, shouldValidate?) => Promise` | no-op | No | Programmatic touch. |
-| `setFieldError` | `(field, message?) => void` | no-op | No | Programmatic field-level error. |
-| `isSubmitting` | `boolean` | `false` | No | Surface submit state to the context. |
-
-When both `config` and `fields` are supplied, `config` wins. When neither is supplied the
-component renders an empty grid.
-
-## FieldConfigV2 reference
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `"text" \| "number" \| "password" \| "email" \| "select" \| "date" \| "time" \| "section" \| "custom" \| "array"` | Field kind. |
-| `name` | `string` | Matches the key in `values` / `errors` / `touched`. |
-| `label` | `string` | Text rendered above the field (or as the section heading). |
-| `column` | `number \| { sm?, md?, lg?, xl? }` | Grid span. Responsive object or single number. |
-| `dependsOn` | `string[]` | Sibling field names watched by `renderWhen`/`dynamicProps`. |
-| `renderWhen` | `(values) => boolean` | Hide this field when returns `false`. |
-| `dynamicProps` | `(values) => Partial<FieldConfigV2>` | Compute per-render overrides (e.g. toggle `disabled`). |
-| `validation` | `Yup.AnySchema` | Per-field Yup schema. |
-| `asyncValidation` | `(value, values) => Promise<string \| null>` | Async validator returning an error message or `null`. |
-| `onChangeAction` | `(value, context) => void \| Promise<void>` | Side-effect fired on change. Use to compute derived fields. |
-| `options` | `Array \| () => Promise<Array>` | Sync or async options for `select`. Async → renders `ITSearchSelect`. |
-| `component` | `React.ComponentType` | Renderer for `type: "custom"`. |
-| `fields` | `FieldConfigV2[]` | Nested fields for `type: "section"` (or `array` placeholder). |
-| `placeholder` | `string` | Placeholder text. |
-| `required` | `boolean \| (values) => boolean` | Required flag. |
-| `disabled` | `boolean \| (values) => boolean` | Disabled flag. |
-| `readOnly` | `boolean` | Read-only flag. |
-| `defaultValue` | `any` | Initial value. |
-| `valueField` / `labelField` | `string` | Keys read off each option object. |
-| `leftIcon` / `rightIcon` | `React.ReactNode` | Icon adornments. |
-| `className` | `string` | Extra classes for the field's container. |
-| `maxLength` / `minLength` | `number` | Length bounds for text/textarea. |
-| `rows` | `number` | Rows for textarea-style inputs. |
-| `formatNumber` | `boolean` | Apply thousand-separator formatting as the user types. |
-| `currencyFormat` | `boolean` | Render a `$`-style currency treatment on numeric input. |
-| `showHintLength` | `boolean` | Show a live character counter. |
-
-## FieldConfig (V1) reference (legacy)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Key in `values`/`errors`/`touched`. |
-| `label` | `string` | Field label. |
-| `type` | `"text" \| "number" \| "password" \| "select" \| "date"` | Input kind. |
-| `placeholder` | `string` | Placeholder text. |
-| `required` | `boolean` | Required flag. |
-| `disabled` | `boolean` | Disabled flag. |
-| `column` | `number` | Grid span. |
-| `options` | `{ value, label }[]` | Options for `select`. |
-| `leftIcon` / `rightIcon` | `React.ReactNode` | Icon adornments. |
-| `valueField` / `labelField` | `string` | Keys read off each option object. |
-| `maxLength` / `minLength` | `number` | Length bounds. |
-| `rows` | `number` | Rows for multi-line inputs. |
-| `formatNumber` | `boolean` | Thousand-separator formatting. |
-| `currencyFormat` | `boolean` | Currency-style numeric input. |
-| `showHintLength` | `boolean` | Live character counter. |
-| `validation` | `Yup.AnySchema` | Per-field Yup schema. |
-| `onChangeAction` | `(value, setFieldValue) => void` | Side-effect fired on change. |
-
-## Usage
-
-### 1. Minimal Formik + Yup form (V2)
-
-```tsx
-import { Formik } from "formik";
-import * as Yup from "yup";
-import { ITFormBuilder } from "@axzydev/axzy_ui_system";
-import type { FieldConfigV2 } from "@axzydev/axzy_ui_system";
-
-const schema = Yup.object({
-  email: Yup.string().email().required(),
-  password: Yup.string().min(8).required(),
-});
-
-const config: FieldConfigV2[] = [
-  { name: "email", label: "Email", type: "email", required: true, column: 6 },
-  { name: "password", label: "Password", type: "password", required: true, column: 6 },
-];
-
-<Formik
-  initialValues={{ email: "", password: "" }}
-  validationSchema={schema}
-  onSubmit={(values) => console.log(values)}
->
-  {(p) => (
-    <form onSubmit={p.handleSubmit}>
-      <ITFormBuilder
-        config={config}
-        values={p.values}
-        handleChange={p.handleChange}
-        handleBlur={p.handleBlur}
-        touched={p.touched}
-        errors={p.errors}
-        setFieldValue={p.setFieldValue}
-      />
-      <button type="submit">Submit</button>
-    </form>
-  )}
-</Formik>
-```
-
-### 2. Conditional + derived fields
-
-```tsx
-const config: FieldConfigV2[] = [
-  {
-    name: "country",
-    label: "País",
-    type: "select",
-    required: true,
-    options: [{ value: "MX", label: "México" }, { value: "US", label: "USA" }],
-  },
-  {
-    name: "rfc",
-    label: "RFC",
-    type: "text",
-    required: true,
-    dependsOn: ["country"],
-    renderWhen: (v) => v.country === "MX",
-  },
-  {
-    name: "subtotal",
-    label: "Subtotal",
-    type: "number",
-    currencyFormat: true,
-    onChangeAction: (val, ctx) => {
-      const n = parseFloat(String(val).replace(/,/g, "")) || 0;
-      ctx.setFieldValue("total", (n * 1.16).toFixed(2));
-    },
-  },
-  { name: "total", label: "Total", type: "number", disabled: true, currencyFormat: true },
-];
-```
-
-### 3. Async / cascading options
-
-```tsx
-{
-  name: "city",
-  label: "Ciudad",
-  type: "select",
-  options: async () => {
-    const res = await fetch(`/api/cities?country=${values.country}`);
-    return res.json();
-  },
-}
-```
-
-Async option lists use `ITSearchSelect` underneath and render a spinner fallback
-while loading (`data-testid="field-loading-{name}"`).
-
-### 4. Custom component
-
-```tsx
-const ConfirmToggle = ({ value, onChange, label }) => (
-  <label>
-    <input type="checkbox" checked={!!value} onChange={(e) => onChange(e.target.checked)} />
-    {label}
-  </label>
-);
-
-{
-  name: "confirm",
-  label: "Acepto términos",
-  type: "custom",
-  component: ConfirmToggle,
-  defaultValue: false,
-}
-```
-
-### 5. Section grouping
-
-```tsx
-{
-  name: "identity",
-  label: "Personal Information",
-  type: "section",
-  fields: [
-    { name: "firstName", label: "First Name", type: "text" },
-    { name: "lastName", label: "Last Name", type: "text" },
-  ],
-}
-```
-
-### 6. Custom submit button via `useFormBuilder`
-
-```tsx
-import { useFormBuilder } from "@axzydev/axzy_ui_system";
-
-const SubmitButton = () => {
-  const { progress, isSubmitting } = useFormBuilder();
-  return (
-    <button type="submit" disabled={progress < 100 || isSubmitting}>
-      {isSubmitting ? "Saving…" : `Submit (${progress}%)`}
-    </button>
-  );
-};
-```
-
-`useFormBuilder` must be rendered inside the `<ITFormBuilder>` subtree (so the
-V2 provider must be active). It throws a clear error if used outside.
-
-## Notes
-
-- The component is fully controlled — it does not own form state. Pass values
-  and handlers from Formik (or any state holder of your choice).
-- V1 and V2 can coexist on a single page; mixing both on the same `<ITFormBuilder>`
-  is not supported — `config` wins.
-- The V2 registry of registered fields is exposed via `useFormBuilder` and via
-  `useITFormBuilderContext().getAllFieldConfigs()`.
-- `validation`/`asyncValidation` are NOT applied automatically — wire them to
-  Yup at the Formik root, or run them manually inside `onChangeAction`.
-
-## Stories
-
-<Primary />
-<Controls />
-<Stories />