@jsenv/navi 0.0.1 → 0.1.1

package/src/components/field/input_textual.jsx

@@ -0,0 +1,418 @@
+/**
+ * Input component for all textual input types.
+ *
+ * Supports:
+ * - text (default)
+ * - password
+ * - hidden
+ * - email
+ * - url
+ * - search
+ * - tel
+ * - etc.
+ *
+ * For non-textual inputs, specialized components will be used:
+ * - <InputCheckbox /> for type="checkbox"
+ * - <InputRadio /> for type="radio"
+ */
+
+import { forwardRef } from "preact/compat";
+import {
+  useContext,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  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 { useActionBoundToOneParam } from "../action_execution/use_action.js";
+import { useExecuteAction } from "../action_execution/use_execute_action.js";
+import { LoadableInlineElement } from "../loader/loader_background.jsx";
+import { useAutoFocus } from "../use_auto_focus.js";
+import "./field_css.js";
+import { ReportReadOnlyOnLabelContext } from "./label.jsx";
+import { useActionEvents } from "./use_action_events.js";
+import {
+  DisabledContext,
+  LoadingContext,
+  LoadingElementContext,
+  ReadOnlyContext,
+  UIStateContext,
+  UIStateControllerContext,
+  useUIState,
+  useUIStateController,
+} from "./use_ui_state_controller.js";
+
+export const InputTextual = forwardRef((props, ref) => {
+  const uiStateController = useUIStateController(props, "input");
+  const uiState = useUIState(uiStateController);
+
+  const input = renderActionableComponent(props, ref, {
+    Basic: InputTextualBasic,
+    WithAction: InputTextualWithAction,
+    InsideForm: InputTextualInsideForm,
+  });
+  return (
+    <UIStateControllerContext.Provider value={uiStateController}>
+      <UIStateContext.Provider value={uiState}>{input}</UIStateContext.Provider>
+    </UIStateControllerContext.Provider>
+  );
+});
+
+const InputTextualBasic = forwardRef((props, ref) => {
+  const contextReadOnly = useContext(ReadOnlyContext);
+  const contextDisabled = useContext(DisabledContext);
+  const contextLoading = useContext(LoadingContext);
+  const contextLoadingElement = useContext(LoadingElementContext);
+  const reportReadOnlyOnLabel = useContext(ReportReadOnlyOnLabelContext);
+  const uiStateController = useContext(UIStateControllerContext);
+  const uiState = useContext(UIStateContext);
+  const {
+    type,
+    onInput,
+
+    readOnly,
+    disabled,
+    constraints = [],
+    loading,
+
+    autoFocus,
+    autoFocusVisible,
+    autoSelect,
+    appearance = "custom",
+    width,
+    height,
+    ...rest
+  } = props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  const innerValue =
+    type === "datetime-local" ? convertToLocalTimezone(uiState) : uiState;
+  const innerLoading =
+    loading || (contextLoading && contextLoadingElement === innerRef.current);
+  const innerReadOnly =
+    readOnly || contextReadOnly || innerLoading || uiStateController.readOnly;
+  const innerDisabled = disabled || contextDisabled;
+  // infom any <label> parent of our readOnly state
+  reportReadOnlyOnLabel?.(innerReadOnly);
+  useAutoFocus(innerRef, autoFocus, {
+    autoFocusVisible,
+    autoSelect,
+  });
+  useConstraints(innerRef, constraints);
+
+  const inputTextual = (
+    <input
+      {...rest}
+      ref={innerRef}
+      type={type}
+      data-value={uiState}
+      value={innerValue}
+      data-field=""
+      data-field-with-border=""
+      data-custom={appearance === "custom" ? "" : undefined}
+      readOnly={innerReadOnly}
+      disabled={innerDisabled}
+      onInput={(e) => {
+        let inputValue;
+        if (type === "number") {
+          inputValue = e.target.valueAsNumber;
+        } else if (type === "datetime-local") {
+          inputValue = convertToUTCTimezone(e.target.value);
+        } else {
+          inputValue = e.target.value;
+        }
+        uiStateController.setUIState(inputValue, e);
+        onInput?.(e);
+      }}
+      // eslint-disable-next-line react/no-unknown-property
+      onresetuistate={(e) => {
+        uiStateController.resetUIState(e);
+      }}
+      // eslint-disable-next-line react/no-unknown-property
+      onsetuistate={(e) => {
+        uiStateController.setUIState(e.detail.value, e);
+      }}
+    />
+  );
+
+  return (
+    <LoadableInlineElement
+      loading={innerLoading}
+      color="light-dark(#355fcc, #3b82f6)"
+      width={width}
+      height={height}
+    >
+      {inputTextual}
+    </LoadableInlineElement>
+  );
+});
+
+const InputTextualWithAction = forwardRef((props, ref) => {
+  const uiState = useContext(UIStateContext);
+  const {
+    action,
+    loading,
+    onCancel,
+    onActionPrevented,
+    onActionStart,
+    onActionError,
+    onActionEnd,
+    cancelOnBlurInvalid,
+    cancelOnEscape,
+    actionErrorEffect,
+    onInput,
+    onKeyDown,
+    ...rest
+  } = props;
+  const innerRef = useRef(null);
+  useImperativeHandle(ref, () => innerRef.current);
+  const [boundAction] = useActionBoundToOneParam(action, uiState);
+  const { loading: actionLoading } = useActionStatus(boundAction);
+  const executeAction = useExecuteAction(innerRef, {
+    errorEffect: actionErrorEffect,
+  });
+  const valueAtInteractionRef = useRef(null);
+
+  useOnInputChange(innerRef, (e) => {
+    if (
+      valueAtInteractionRef.current !== null &&
+      e.target.value === valueAtInteractionRef.current
+    ) {
+      valueAtInteractionRef.current = null;
+      return;
+    }
+    requestAction(e.target, boundAction, {
+      event: e,
+      actionOrigin: "action_prop",
+    });
+  });
+  // here updating the input won't call the associated action
+  // (user have to blur or press enter for this to happen)
+  // so we can keep the ui state on cancel/abort/error and let user decide
+  // to update ui state or retry via blur/enter as is
+  useActionEvents(innerRef, {
+    onCancel: (e, reason) => {
+      if (reason.startsWith("blur_invalid")) {
+        if (!cancelOnBlurInvalid) {
+          return;
+        }
+        if (
+          // error prevent cancellation until the user closes it (or something closes it)
+          e.detail.failedConstraintInfo.level === "error" &&
+          e.detail.failedConstraintInfo.reportStatus !== "closed"
+        ) {
+          return;
+        }
+      }
+      if (reason === "escape_key") {
+        if (!cancelOnEscape) {
+          return;
+        }
+        /**
+         * Browser trigger a "change" event right after the escape is pressed
+         * if the input value has changed.
+         * We need to prevent the next change event otherwise we would request action when
+         * we actually want to cancel
+         */
+        valueAtInteractionRef.current = e.target.value;
+      }
+      onCancel?.(e, reason);
+    },
+    onPrevented: onActionPrevented,
+    onAction: executeAction,
+    onStart: onActionStart,
+    onError: onActionError,
+    onEnd: onActionEnd,
+  });
+
+  return (
+    <InputTextualBasic
+      data-action={boundAction.name}
+      {...rest}
+      ref={innerRef}
+      loading={loading || actionLoading}
+      onInput={(e) => {
+        valueAtInteractionRef.current = null;
+        onInput?.(e);
+      }}
+      onKeyDown={(e) => {
+        if (e.key !== "Enter") {
+          return;
+        }
+        e.preventDefault();
+        /**
+         * Browser trigger a "change" event right after the enter is pressed
+         * if the input value has changed.
+         * We need to prevent the next change event otherwise we would request action twice
+         */
+        valueAtInteractionRef.current = e.target.value;
+        requestAction(e.target, boundAction, {
+          event: e,
+          actionOrigin: "action_prop",
+        });
+        onKeyDown?.(e);
+      }}
+    />
+  );
+});
+const InputTextualInsideForm = forwardRef((props, ref) => {
+  const {
+    onKeyDown,
+    // We destructure formContext to avoid passing it to the underlying input element
+    // eslint-disable-next-line no-unused-vars
+    formContext,
+    ...rest
+  } = props;
+
+  return (
+    <InputTextualBasic
+      {...rest}
+      ref={ref}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") {
+          const inputElement = e.target;
+          const { form } = inputElement;
+          const formSubmitButton = form.querySelector(
+            "button[type='submit'], input[type='submit'], input[type='image']",
+          );
+          e.preventDefault();
+          form.dispatchEvent(
+            new CustomEvent("actionrequested", {
+              detail: {
+                requester: formSubmitButton ? formSubmitButton : inputElement,
+                event: e,
+                meta: { isSubmit: true },
+                actionOrigin: "action_prop",
+              },
+            }),
+          );
+        }
+        onKeyDown?.(e);
+      }}
+    />
+  );
+});
+
+const useOnInputChange = (inputRef, callback) => {
+  // we must use a custom event listener because preact bind onChange to onInput for compat with react
+  useEffect(() => {
+    const input = inputRef.current;
+    input.addEventListener("change", callback);
+    return () => {
+      input.removeEventListener("change", callback);
+    };
+  }, [callback]);
+
+  // Handle programmatic value changes that don't trigger browser change events
+  //
+  // Problem: When input values are set programmatically (not by user typing),
+  // browsers don't fire the 'change' event. However, our application logic
+  // still needs to detect these changes.
+  //
+  // Example scenario:
+  // 1. User starts editing (letter key pressed, value set programmatically)
+  // 2. User doesn't type anything additional (this is the key part)
+  // 3. User clicks outside to finish editing
+  // 4. Without this code, no change event would fire despite the fact that the input value did change from its original state
+  //
+  // This distinction is crucial because:
+  //
+  // - If the user typed additional text after the initial programmatic value,
+  //   the browser would fire change events normally
+  // - But when they don't type anything else, the browser considers it as "no user interaction"
+  //   even though the programmatic initial value represents a meaningful change
+  const valueAtStartRef = useRef();
+  const interactedRef = useRef(false);
+  useLayoutEffect(() => {
+    const input = inputRef.current;
+    valueAtStartRef.current = input.value;
+
+    const onfocus = () => {
+      interactedRef.current = false;
+      valueAtStartRef.current = input.value;
+    };
+    const oninput = (e) => {
+      if (!e.isTrusted) {
+        // non trusted "input" events will be ignored by the browser when deciding to fire "change" event
+        // we ignore them too
+        return;
+      }
+      interactedRef.current = true;
+    };
+    const onblur = (e) => {
+      if (interactedRef.current) {
+        return;
+      }
+      if (valueAtStartRef.current === input.value) {
+        return;
+      }
+      callback(e);
+    };
+
+    input.addEventListener("focus", onfocus);
+    input.addEventListener("input", oninput);
+    input.addEventListener("blur", onblur);
+
+    return () => {
+      input.removeEventListener("focus", onfocus);
+      input.removeEventListener("input", oninput);
+      input.removeEventListener("blur", onblur);
+    };
+  }, []);
+};
+// As explained in https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local#setting_timezones
+// datetime-local does not support timezones
+const convertToLocalTimezone = (dateTimeString) => {
+  const date = new Date(dateTimeString);
+  // Check if the date is valid
+  if (isNaN(date.getTime())) {
+    return dateTimeString;
+  }
+
+  // Format to YYYY-MM-DDThh:mm:ss
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  const seconds = String(date.getSeconds()).padStart(2, "0");
+
+  return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}`;
+};
+/**
+ * Converts a datetime string without timezone (local time) to UTC format with 'Z' notation
+ *
+ * @param {string} localDateTimeString - Local datetime string without timezone (e.g., "2023-07-15T14:30:00")
+ * @returns {string} Datetime string in UTC with 'Z' notation (e.g., "2023-07-15T12:30:00Z")
+ */
+const convertToUTCTimezone = (localDateTimeString) => {
+  if (!localDateTimeString) {
+    return localDateTimeString;
+  }
+
+  try {
+    // Create a Date object using the local time string
+    // The browser will interpret this as local timezone
+    const localDate = new Date(localDateTimeString);
+
+    // Check if the date is valid
+    if (isNaN(localDate.getTime())) {
+      return localDateTimeString;
+    }
+
+    // Convert to UTC ISO string
+    const utcString = localDate.toISOString();
+
+    // Return the UTC string (which includes the 'Z' notation)
+    return utcString;
+  } catch (error) {
+    console.error("Error converting local datetime to UTC:", error);
+    return localDateTimeString;
+  }
+};

package/src/components/field/label.jsx

@@ -0,0 +1,32 @@
+import { createContext } from "preact";
+import { forwardRef } from "preact/compat";
+import { useImperativeHandle, useRef, useState } from "preact/hooks";
+
+import.meta.css = /* css */ `
+  label[data-readonly] {
+    color: rgba(0, 0, 0, 0.5);
+  }
+`;
+
+export const ReportReadOnlyOnLabelContext = createContext();
+
+export const Label = forwardRef((props, ref) => {
+  const { readOnly, children, ...rest } = props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  const [inputReadOnly, setInputReadOnly] = useState(false);
+  const innerReadOnly = readOnly || inputReadOnly;
+
+  return (
+    <label
+      ref={innerRef}
+      data-readonly={innerReadOnly ? "" : undefined}
+      {...rest}
+    >
+      <ReportReadOnlyOnLabelContext.Provider value={setInputReadOnly}>
+        {children}
+      </ReportReadOnlyOnLabelContext.Provider>
+    </label>
+  );
+});

package/src/components/field/radio_list.jsx

@@ -0,0 +1,182 @@
+import { forwardRef } from "preact/compat";
+import {
+  useContext,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "preact/hooks";
+
+import { useActionStatus } from "../../use_action_status.js";
+import { requestAction } from "../../validation/custom_constraint_validation.js";
+import { renderActionableComponent } from "../action_execution/render_actionable_component.jsx";
+import { useActionBoundToOneParam } from "../action_execution/use_action.js";
+import { useExecuteAction } from "../action_execution/use_execute_action.js";
+import { InputRadio } from "./input_radio.jsx";
+import { useActionEvents } from "./use_action_events.js";
+import {
+  DisabledContext,
+  FieldNameContext,
+  LoadingContext,
+  LoadingElementContext,
+  ParentUIStateControllerContext,
+  ReadOnlyContext,
+  RequiredContext,
+  UIStateContext,
+  UIStateControllerContext,
+  useUIGroupStateController,
+  useUIState,
+} from "./use_ui_state_controller.js";
+
+import.meta.css = /* css */ `
+  .navi_radio_list {
+    display: flex;
+    flex-direction: column;
+  }
+`;
+
+export const RadioList = forwardRef((props, ref) => {
+  const uiStateController = useUIGroupStateController(props, "radio_list", {
+    childComponentType: "radio",
+    aggregateChildStates: (childUIStateControllers) => {
+      let activeValue;
+      for (const childUIStateController of childUIStateControllers) {
+        if (childUIStateController.uiState) {
+          activeValue = childUIStateController.uiState;
+          break;
+        }
+      }
+      return activeValue;
+    },
+  });
+  const uiState = useUIState(uiStateController);
+  const radioList = renderActionableComponent(props, ref, {
+    Basic: RadioListBasic,
+    WithAction: RadioListWithAction,
+    InsideForm: RadioListInsideForm,
+  });
+  return (
+    <UIStateControllerContext.Provider value={uiStateController}>
+      <UIStateContext.Provider value={uiState}>
+        {radioList}
+      </UIStateContext.Provider>
+    </UIStateControllerContext.Provider>
+  );
+});
+export const Radio = InputRadio;
+
+const RadioListBasic = forwardRef((props, ref) => {
+  const contextReadOnly = useContext(ReadOnlyContext);
+  const contextDisabled = useContext(DisabledContext);
+  const contextLoading = useContext(LoadingContext);
+  const uiStateController = useContext(UIStateControllerContext);
+  const { name, loading, disabled, readOnly, children, required, ...rest } =
+    props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  const innerLoading = loading || contextLoading;
+  const innerReadOnly =
+    readOnly || contextReadOnly || innerLoading || uiStateController.readOnly;
+  const innerDisabled = disabled || contextDisabled;
+
+  return (
+    <div
+      data-action={rest["data-action"]}
+      {...rest}
+      ref={innerRef}
+      className="navi_radio_list"
+      data-radio-list
+      // eslint-disable-next-line react/no-unknown-property
+      onresetuistate={(e) => {
+        uiStateController.resetUIState(e);
+      }}
+    >
+      <ParentUIStateControllerContext.Provider value={uiStateController}>
+        <FieldNameContext.Provider value={name}>
+          <ReadOnlyContext.Provider value={innerReadOnly}>
+            <DisabledContext.Provider value={innerDisabled}>
+              <RequiredContext.Provider value={required}>
+                <LoadingContext.Provider value={innerLoading}>
+                  {children}
+                </LoadingContext.Provider>
+              </RequiredContext.Provider>
+            </DisabledContext.Provider>
+          </ReadOnlyContext.Provider>
+        </FieldNameContext.Provider>
+      </ParentUIStateControllerContext.Provider>
+    </div>
+  );
+});
+const RadioListWithAction = forwardRef((props, ref) => {
+  const uiStateController = useContext(UIStateControllerContext);
+  const uiState = useContext(UIStateContext);
+  const {
+    action,
+
+    onCancel,
+    onActionPrevented,
+    onActionStart,
+    onActionAbort,
+    onActionError,
+    onActionEnd,
+    actionErrorEffect,
+    loading,
+    children,
+    ...rest
+  } = props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+  const [boundAction] = useActionBoundToOneParam(action, uiState);
+  const { loading: actionLoading } = useActionStatus(boundAction);
+  const executeAction = useExecuteAction(innerRef, {
+    errorEffect: actionErrorEffect,
+  });
+  const [actionRequester, setActionRequester] = useState(null);
+
+  useActionEvents(innerRef, {
+    onCancel: (e, reason) => {
+      uiStateController.resetUIState(e);
+      onCancel?.(e, reason);
+    },
+    onPrevented: onActionPrevented,
+    onAction: (actionEvent) => {
+      setActionRequester(actionEvent.detail.requester);
+      executeAction(actionEvent);
+    },
+    onStart: onActionStart,
+    onAbort: (e) => {
+      uiStateController.resetUIState(e);
+      onActionAbort?.(e);
+    },
+    onError: (e) => {
+      uiStateController.resetUIState(e);
+      onActionError?.(e);
+    },
+    onEnd: (e) => {
+      onActionEnd?.(e);
+    },
+  });
+
+  return (
+    <RadioListBasic
+      data-action={boundAction}
+      {...rest}
+      ref={innerRef}
+      onChange={(e) => {
+        const radio = e.target;
+        const radioListContainer = innerRef.current;
+        requestAction(radioListContainer, boundAction, {
+          event: e,
+          requester: radio,
+          actionOrigin: "action_prop",
+        });
+      }}
+      loading={loading || actionLoading}
+    >
+      <LoadingElementContext.Provider value={actionRequester}>
+        {children}
+      </LoadingElementContext.Provider>
+    </RadioListBasic>
+  );
+});
+const RadioListInsideForm = RadioListBasic;