@jsenv/navi 0.0.1 → 0.1.0

package/src/components/field/README.md

@@ -0,0 +1,247 @@
+# UI State Controller
+
+The UI State Controller solves a fundamental problem in web applications: managing the relationship between what the user sees (UI state) and what the application knows (external state).
+
+## The Problem
+
+Traditional approaches have limitations:
+
+1. **React limitations** - No built-in way to revert UI state back to external state when needed
+2. **Form limitations** - Regular forms can't do immediate server calls (like PATCH) for instant feedback
+3. **UX trade-offs** - You're forced to choose between immediate feedback OR traditional form workflow
+
+## The Solution
+
+UI State Controller introduces clear separation:
+
+- **External State**: The "source of truth" (props, backend data)
+- **UI State**: What the user currently sees and interacts with
+- **Controller**: Manages the relationship between them
+
+There are **two distinct usage patterns** depending on your needs:
+
+## Pattern 1: UI with Action (Auto-revert on Error)
+
+For interactive components that need immediate feedback with server synchronization:
+
+```jsx
+const [savedValue, setSavedValue] = useState(false);
+
+<InputCheckbox
+  checked={savedValue} // External state
+  action={async (
+    // newValue is undefined when unchecked, "on" when checked (default HTML behavior)
+    // Customize checked value: <InputCheckbox value="yes" /> sends "yes" instead of "on"
+    newValue,
+  ) => {
+    // PATCH to update existing resource
+    const response = await fetch("/api/user/preferences", {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ emailNotifications: newValue }),
+    });
+    const result = await response.json();
+    setSavedValue(result.emailNotifications);
+  }}
+/>;
+```
+
+**How it works:**
+
+1. User clicks checkbox → UI updates immediately (responsive)
+2. Action executes in background
+3. **Success**: External state updates, UI stays in sync
+4. **Error**: UI automatically reverts to match external state (auto-revert)
+
+**Use when:** You want immediate feedback with automatic error recovery.
+
+## Pattern 2: UI within `<form>` (User Choice on Error)
+
+For traditional form workflows where users control submission:
+
+```jsx
+<Form
+  action={async ({ email, consent }) => {
+    const response = await fetch("/api/user/settings", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email,
+        consent,
+      }),
+    });
+    if (!response.ok) {
+      throw new Error("Failed to save settings");
+    }
+    // Update your app state here
+    const result = await response.json();
+    updateUserSettings(result);
+  }}
+>
+  <label>
+    Email Address:
+    <Input type="email" name="email" defaultValue="user@example.com" required />
+  </label>
+
+  <label>
+    <InputCheckbox name="consent" />I agree to receive marketing emails
+  </label>
+
+  <button type="submit">Save Settings</button>
+  <button type="reset">Reset Form</button>
+</Form>
+```
+
+**Key differences:**
+
+- **Form submission errors**: UI state is NOT reverted
+- **Reasoning**: User might want to fix the issue and re-submit as-is
+- **Form reset**: UI state is properly restored to original values
+- **Navigation**: Form state persists during page navigation
+
+**Use when:** You want traditional form behavior with user control over submission.
+
+## When to Use Each Pattern
+
+### Use Action Pattern When:
+
+- Building interactive dashboards or real-time interfaces
+- Each change should be immediately persisted
+- You want automatic error recovery
+- User expects instant feedback
+
+### Use Form Pattern When:
+
+- Building traditional forms with submit/reset workflow
+- Users need to make multiple changes before saving
+- You want standard form validation behavior
+- Users should control when changes are persisted
+
+## Advanced APIs
+
+### Tracking State Changes
+
+Use `onUIStateChange` to track what the user has selected (like in our demo). This can be useful for showing what would be submitted/reset, though it's not always needed:
+
+```jsx
+const [colorChoices, setColorChoices] = useState([
+  { id: 1, color: "red", selected: true },
+  { id: 2, color: "blue", selected: false },
+  { id: 3, color: "green", selected: true },
+]);
+
+// What's currently saved
+const selectedColors = colorChoices
+  .filter((choice) => choice.selected)
+  .map((choice) => choice.color);
+
+// What user has selected in UI (may differ)
+const [uiSelectedColors, setUiSelectedColors] = useState(selectedColors);
+
+<Form action={submitColorPreferences}>
+  <CheckboxList
+    name="colors"
+    onUIStateChange={(colors) => {
+      // Track what user has selected
+      setUiSelectedColors(colors);
+      // Can be used for UI feedback or internal logic
+    }}
+  >
+    {colorChoices.map(({ id, color }) => (
+      <Label key={id}>
+        {color}
+        <Checkbox value={color} checked={selectedColors.includes(color)} />
+      </Label>
+    ))}
+  </CheckboxList>
+
+  <button type="submit">Submit ({uiSelectedColors.join(", ")})</button>
+  <button type="reset">Reset to saved ({selectedColors.join(", ")})</button>
+</Form>;
+```
+
+### External Control via Custom Events
+
+Programmatically control UI state from outside the component:
+
+```jsx
+// Set UI state externally
+const checkbox = document.querySelector("#my-checkbox");
+checkbox.dispatchEvent(
+  new CustomEvent("setuistate", {
+    detail: { value: true },
+  }),
+);
+
+// Reset UI state to match external state
+checkbox.dispatchEvent(new CustomEvent("resetuistate"));
+```
+
+### Error Recovery Patterns
+
+```jsx
+<InputCheckbox
+  checked={savedValue}
+  action={updateServer}
+  onActionError={(error) => {
+    // UI already reverted automatically
+    showErrorMessage("Failed to save: " + error.message);
+  }}
+  onActionAbort={() => {
+    // UI reverted when action was cancelled
+    console.log("Action was cancelled");
+  }}
+/>
+```
+
+### Group Controllers (Checkbox Lists)
+
+Coordinate multiple related inputs:
+
+```jsx
+const [selectedOptions, setSelectedOptions] = useState([]);
+
+<CheckboxList
+  values={selectedOptions} // External state
+  onUIStateChange={(uiState) => {
+    // Track what user has selected (internal use)
+    console.log("Currently selected:", uiState);
+  }}
+  action={async (newValues) => {
+    const response = await fetch("/api/options", {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ selectedOptions: newValues }),
+    });
+    const result = await response.json();
+    setSelectedOptions(result.selectedOptions);
+  }}
+>
+  <InputCheckbox value="option1" />
+  <InputCheckbox value="option2" />
+  <InputCheckbox value="option3" />
+</CheckboxList>;
+```
+
+**Group features:**
+
+- Aggregates individual checkbox states into arrays
+- Coordinate reset operations across all children
+- Single action handles all checkbox changes
+
+## Key Benefits
+
+- **Instant feedback**: UI updates immediately, no lag
+- **Flexible error handling**: Auto-revert for actions, user choice for forms
+- **Form compatibility**: Works seamlessly with native form behavior
+- **External control**: Programmatic state control when needed
+- **Group coordination**: Multiple inputs work together naturally
+
+## Summary
+
+Choose the pattern that fits your use case:
+
+- **Action pattern**: For immediate persistence with auto-revert
+- **Form pattern**: For traditional submit/reset workflows with user control
+
+Both patterns provide responsive UI while maintaining data consistency.

package/src/components/{input → field}/button.jsx

@@ -1,44 +1,68 @@
 import { resolveCSSSize } from "@jsenv/dom";
-import { requestAction, useConstraints } from "@jsenv/validation";
 import { forwardRef } from "preact/compat";
-import { useImperativeHandle, useRef } from "preact/hooks";
+import { useContext, useImperativeHandle, useRef } from "preact/hooks";
+
 import { useActionStatus } from "../../use_action_status.js";
+import { requestAction } from "../../validation/custom_constraint_validation.js";
+import { useConstraints } from "../../validation/hooks/use_constraints.js";
 import { renderActionableComponent } from "../action_execution/render_actionable_component.jsx";
 import { useAction } from "../action_execution/use_action.js";
 import { useExecuteAction } from "../action_execution/use_execute_action.js";
-import { LoaderBackground } from "../loader/loader_background.jsx";
-import { useActionEvents } from "../use_action_events.js";
+import { LoadableInlineElement } from "../loader/loader_background.jsx";
 import { useAutoFocus } from "../use_auto_focus.js";
 import "./field_css.js";
+import { useActionEvents } from "./use_action_events.js";
+import { useFormEvents } from "./use_form_events.js";
+import {
+  DisabledContext,
+  LoadingContext,
+  LoadingElementContext,
+  ReadOnlyContext,
+} from "./use_ui_state_controller.js";
+
+/**
+ * We need a content the visually shrink (scale down) but the button interactive are must remain intact
+ * Otherwise a click on the edges of the button cannot not trigger the click event (mouseup occurs outside the button)
+ **/
 
 /**
  * We have to re-define the CSS of button because getComputedStyle(button).borderColor returns
  * rgb(0, 0, 0) while being visually grey in chrome
  * So we redefine chrome styles so that loader can keep up with the actual color visible to the user
- *
  */
 import.meta.css = /* css */ `
   button[data-custom] {
+    border: none;
+    background: none;
+    display: inline-block;
+    padding: 0;
+  }
+
+  button[data-custom] .navi_button_content {
     transition-duration: 0.15s;
     transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
     transition-property: transform;
+    display: inline-flex;
+    position: relative;
+    padding-block: 1px;
+    padding-inline: 6px;
   }
-  button[data-custom]:active {
+
+  button[data-custom]:active .navi_button_content {
     transform: scale(0.9);
   }
-  button[data-custom]:disabled {
+
+  button[data-custom]:disabled .navi_button_content {
     transform: none;
   }
 
-  button[data-custom] > .shadow {
+  button[data-custom] .navi_button_shadow {
     position: absolute;
-    inset: calc(
-      -1 * (var(--button-border-width) + var(--button-outline-width))
-    );
+    inset: calc(-1 * (var(--field-border-width) + var(--field-outline-width)));
     pointer-events: none;
     border-radius: inherit;
   }
-  button[data-custom]:active > .shadow {
+  button[data-custom]:active .navi_button_shadow {
     box-shadow:
       inset 0 3px 6px rgba(0, 0, 0, 0.2),
       inset 0 1px 2px rgba(0, 0, 0, 0.3),
@@ -46,7 +70,7 @@ import.meta.css = /* css */ `
       inset 2px 0 4px rgba(0, 0, 0, 0.1),
       inset -2px 0 4px rgba(0, 0, 0, 0.1);
   }
-  button[data-custom]:disabled > .shadow {
+  button[data-custom]:disabled > .navi_button_shadow {
     box-shadow: none;
   }
 `;
@@ -55,28 +79,36 @@ export const Button = forwardRef((props, ref) => {
     Basic: ButtonBasic,
     WithAction: ButtonWithAction,
     InsideForm: ButtonInsideForm,
-    InsideFormWithAction: ButtonWithActionInsideForm,
+    WithActionInsideForm: ButtonWithActionInsideForm,
   });
 });
 
 const ButtonBasic = forwardRef((props, ref) => {
+  const contextLoading = useContext(LoadingContext);
+  const contextLoadingElement = useContext(LoadingElementContext);
+  const contextReadOnly = useContext(ReadOnlyContext);
+  const contextDisabled = useContext(DisabledContext);
   const {
-    autoFocus,
-    constraints = [],
-    loading,
     readOnly,
-    children,
+    disabled,
+    loading,
+    constraints = [],
+    autoFocus,
     appearance = "custom",
     discrete,
     style = {},
+    children,
     ...rest
   } = props;
-
   const innerRef = useRef();
   useImperativeHandle(ref, () => innerRef.current);
+
   useAutoFocus(innerRef, autoFocus);
   useConstraints(innerRef, constraints);
-
+  const innerLoading =
+    loading || (contextLoading && contextLoadingElement === innerRef.current);
+  const innerReadOnly = readOnly || contextReadOnly || innerLoading;
+  const innerDisabled = disabled || contextDisabled;
   let {
     border,
     borderWidth = border === "none" || discrete ? 0 : 1,
@@ -88,40 +120,44 @@ const ButtonBasic = forwardRef((props, ref) => {
   outlineWidth = resolveCSSSize(outlineWidth);
 
   return (
-    <LoaderBackground
-      loading={loading}
-      inset={
-        borderWidth -
-        // -1 is the outline offset thing
-        1
-      }
-      color="light-dark(#355fcc, #3b82f6)"
+    <button
+      {...rest}
+      ref={innerRef}
+      data-custom={appearance === "custom" ? "" : undefined}
+      data-readonly-silent={innerReadOnly ? "" : undefined}
+      data-readonly={innerReadOnly ? "" : undefined}
+      aria-busy={innerLoading}
+      style={{
+        ...restStyle,
+      }}
     >
-      <button
-        ref={innerRef}
-        {...rest}
-        data-field=""
-        data-field-with-background=""
-        data-field-with-hover=""
-        data-field-with-border={borderWidth ? "" : undefined}
-        data-field-with-border-hover={discrete ? "" : undefined}
-        data-field-with-background-hover={discrete ? "" : undefined}
-        data-custom={appearance === "custom" ? "" : undefined}
-        data-validation-message-arrow-x="center"
-        data-readonly={readOnly ? "" : undefined}
-        aria-busy={loading}
-        style={{
-          ...restStyle,
-          "--button-border-width": `${borderWidth}px`,
-          "--button-outline-width": `${outlineWidth}px`,
-          "--button-border-color": borderColor,
-          "position": "relative",
-        }}
+      <LoadableInlineElement
+        loading={innerLoading}
+        inset={-1}
+        color="light-dark(#355fcc, #3b82f6)"
       >
-        {children}
-        <div className="shadow"></div>
-      </button>
-    </LoaderBackground>
+        <span
+          className="navi_button_content"
+          data-field=""
+          data-field-with-background=""
+          data-field-with-hover=""
+          data-field-with-border={borderWidth ? "" : undefined}
+          data-field-with-border-hover={discrete ? "" : undefined}
+          data-field-with-background-hover={discrete ? "" : undefined}
+          data-validation-message-arrow-x="center"
+          data-readonly={innerReadOnly ? "" : undefined}
+          data-disabled={innerDisabled ? "" : undefined}
+          style={{
+            "--field-border-width": `${borderWidth}px`,
+            "--field-outline-width": `${outlineWidth}px`,
+            "--field-border-color": borderColor,
+          }}
+        >
+          {children}
+          <span className="navi_button_shadow"></span>
+        </span>
+      </LoadableInlineElement>
+    </button>
   );
 });
 
@@ -129,20 +165,17 @@ const ButtonWithAction = forwardRef((props, ref) => {
   const {
     action,
     loading,
-    readOnly,
-    children,
     onClick,
     actionErrorEffect,
     onActionPrevented,
     onActionStart,
     onActionError,
     onActionEnd,
+    children,
     ...rest
   } = props;
-
   const innerRef = useRef();
   useImperativeHandle(ref, () => innerRef.current);
-
   const boundAction = useAction(action);
   const { loading: actionLoading } = useActionStatus(boundAction);
   const executeAction = useExecuteAction(innerRef, {
@@ -156,20 +189,23 @@ const ButtonWithAction = forwardRef((props, ref) => {
     onError: onActionError,
     onEnd: onActionEnd,
   });
-
   const handleClick = (event) => {
     event.preventDefault();
-    requestAction(boundAction, { event });
+    const button = innerRef.current;
+    requestAction(button, boundAction, {
+      event,
+      actionOrigin: "action_prop",
+    });
   };
   const innerLoading = loading || actionLoading;
 
   return (
     <ButtonBasic
+      // put data-action first to help find it in devtools
       data-action={boundAction.name}
-      ref={innerRef}
       {...rest}
+      ref={innerRef}
       loading={innerLoading}
-      readOnly={readOnly || innerLoading}
       onClick={(event) => {
         handleClick(event);
         onClick?.(event);
@@ -181,30 +217,26 @@ const ButtonWithAction = forwardRef((props, ref) => {
 });
 
 const ButtonInsideForm = forwardRef((props, ref) => {
-  const { formContext, type, loading, readOnly, onClick, children, ...rest } =
-    props;
-  const { formAction, formIsBusy, formIsReadOnly, formActionRequester } =
-    formContext;
-
+  const { formContext, type, onClick, children, loading, ...rest } = props;
+  const formLoading = formContext.loading;
   const innerRef = useRef();
   useImperativeHandle(ref, () => innerRef.current);
 
   const wouldSubmitFormByType = type === "submit" || type === "image";
-  const innerReadOnly = readOnly || formIsReadOnly;
-
+  const innerLoading = loading || (formLoading && wouldSubmitFormByType);
   const handleClick = (event) => {
-    const buttonElement = event.target;
+    const buttonElement = innerRef.current;
     const { form } = buttonElement;
     let wouldSubmitForm = wouldSubmitFormByType;
-    if (!wouldSubmitForm) {
+    if (!wouldSubmitForm && type === undefined) {
       const formSubmitButton = form.querySelector(
         "button[type='submit'], input[type='submit'], input[type='image']",
       );
-      const wouldSubmitFormBecauseSingleButton = !formSubmitButton;
-      wouldSubmitForm = wouldSubmitFormBecauseSingleButton;
+      const wouldSubmitFormBecauseSingleButtonWithoutType = !formSubmitButton;
+      wouldSubmitForm = wouldSubmitFormBecauseSingleButtonWithoutType;
     }
     if (!wouldSubmitForm) {
-      if (innerReadOnly) {
+      if (buttonElement.hasAttribute("data-readonly")) {
         event.preventDefault();
       }
       return;
@@ -212,24 +244,24 @@ const ButtonInsideForm = forwardRef((props, ref) => {
     // prevent default behavior that would submit the form
     // we want to go through the action execution process (with validation and all)
     event.preventDefault();
-    requestAction(formAction, {
-      event,
-      target: form,
-      requester: buttonElement,
-      meta: { isSubmit: true },
-    });
+    form.dispatchEvent(
+      new CustomEvent("actionrequested", {
+        detail: {
+          requester: buttonElement,
+          event,
+          meta: { isSubmit: true },
+          actionOrigin: "action_prop",
+        },
+      }),
+    );
   };
 
   return (
     <ButtonBasic
-      ref={innerRef}
       {...rest}
+      ref={innerRef}
       type={type}
-      loading={
-        loading || (formIsBusy && formActionRequester === innerRef.current)
-      }
-      readOnly={innerReadOnly}
-      data-readonly-silent={formIsReadOnly ? "" : undefined}
+      loading={innerLoading}
       onClick={(event) => {
         handleClick(event);
         onClick?.(event);
@@ -246,10 +278,8 @@ const ButtonWithActionInsideForm = forwardRef((props, ref) => {
     type,
     action,
     loading,
-    readOnly,
     children,
     onClick,
-    actionErrorEffect,
     onActionPrevented,
     onActionStart,
     onActionAbort,
@@ -261,69 +291,60 @@ const ButtonWithActionInsideForm = forwardRef((props, ref) => {
     type === "submit" || type === "reset" || type === "image";
   if (import.meta.dev && hasEffectOnForm) {
     throw new Error(
-      "Button with type submit/reset/image should not have their own action",
+      `<Button type="${type}" /> should not have their own action`,
     );
   }
-
+  const { formParamsSignal } = formContext;
   const innerRef = useRef();
   useImperativeHandle(ref, () => innerRef.current);
-
-  const { formIsReadOnly, formParamsSignal } = formContext;
   const actionBoundToFormParams = useAction(action, formParamsSignal);
   const { loading: actionLoading } = useActionStatus(actionBoundToFormParams);
-  const executeAction = useExecuteAction(innerRef, {
-    errorEffect: actionErrorEffect,
-  });
 
-  useActionEvents(innerRef, {
-    onPrevented: onActionPrevented,
-    onAction: executeAction,
-    onStart: (e) => {
-      e.target.form.dispatchEvent(
-        new CustomEvent("actionstart", { detail: e.detail }),
-      );
-      onActionStart?.(e);
+  const innerLoading = loading || actionLoading;
+  useFormEvents(innerRef, {
+    onFormActionPrevented: (e) => {
+      if (e.detail.action === actionBoundToFormParams) {
+        onActionPrevented?.(e);
+      }
     },
-    onAbort: (e) => {
-      e.target.form.dispatchEvent(
-        new CustomEvent("actionabort", { detail: e.detail }),
-      );
-      onActionAbort?.(e);
+    onFormActionStart: (e) => {
+      if (e.detail.action === actionBoundToFormParams) {
+        onActionStart?.(e);
+      }
     },
-    onError: (e) => {
-      e.target.form.dispatchEvent(
-        new CustomEvent("actionerror", { detail: e.detail }),
-      );
-      onActionError?.(e);
+    onFormActionAbort: (e) => {
+      if (e.detail.action === actionBoundToFormParams) {
+        onActionAbort?.(e);
+      }
     },
-    onEnd: (e) => {
-      e.target.form.dispatchEvent(
-        new CustomEvent("actionend", { detail: e.detail }),
-      );
-      onActionEnd?.(e);
+    onFormActionError: (e) => {
+      if (e.detail.action === actionBoundToFormParams) {
+        onActionError?.(e.detail.error);
+      }
+    },
+    onFormActionEnd: (e) => {
+      if (e.detail.action === actionBoundToFormParams) {
+        onActionEnd?.(e);
+      }
     },
   });
 
-  const handleClick = (event) => {
-    event.preventDefault();
-    // lorsque cette action s'éxecute elle doit mettre le form en mode busy
-    // je vois pas encore comment je vais faire ca mais a priori
-    // on va juste le faire "manuellement"
-    // en utilisnt un truc du formContext
-    requestAction(actionBoundToFormParams, { event });
-  };
-
   return (
     <ButtonBasic
       data-action={actionBoundToFormParams.name}
-      ref={innerRef}
       {...rest}
+      ref={innerRef}
       type={type}
-      loading={loading || actionLoading}
-      readOnly={readOnly || formIsReadOnly}
-      data-readonly-silent={!readOnly && formIsReadOnly ? "" : undefined}
+      loading={innerLoading}
       onClick={(event) => {
-        handleClick(event);
+        const button = innerRef.current;
+        const form = button.form;
+        event.preventDefault();
+        requestAction(form, actionBoundToFormParams, {
+          event,
+          requester: button,
+          actionOrigin: "action_prop",
+        });
         onClick?.(event);
       }}
     >