@jsenv/navi 0.0.1

package/src/components/details/details.jsx

@@ -0,0 +1,248 @@
+import { elementIsFocusable, findAfter } from "@jsenv/dom";
+import { requestAction } from "@jsenv/validation";
+import { forwardRef } from "preact/compat";
+import { useEffect, useImperativeHandle, useRef, useState } from "preact/hooks";
+import { useNavState } from "../../browser_integration/browser_integration.js";
+import { useActionStatus } from "../../use_action_status.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 { ActionRenderer } from "../action_renderer.jsx";
+import { useKeyboardShortcuts } from "../shortcut/shortcut_context.jsx";
+import { useActionEvents } from "../use_action_events.js";
+import { useFocusGroup } from "../use_focus_group.js";
+import { SummaryMarker } from "./summary_marker.jsx";
+
+import.meta.css = /* css */ `
+  .navi_details {
+    display: flex;
+    flex-direction: column;
+    position: relative;
+    z-index: 1;
+    flex-shrink: 0;
+  }
+
+  .navi_details > summary {
+    flex-shrink: 0;
+    cursor: pointer;
+    display: flex;
+    flex-direction: column;
+    user-select: none;
+  }
+  .summary_body {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    width: 100%;
+    gap: 0.2em;
+  }
+  .summary_label {
+    display: flex;
+    flex: 1;
+    gap: 0.2em;
+    align-items: center;
+    padding-right: 10px;
+  }
+
+  .navi_details > summary:focus {
+    z-index: 1;
+  }
+`;
+
+export const Details = forwardRef((props, ref) => {
+  return renderActionableComponent(props, ref, {
+    Basic: DetailsBasic,
+    WithAction: DetailsWithAction,
+  });
+});
+
+const DetailsBasic = forwardRef((props, ref) => {
+  const {
+    id,
+    label = "Summary",
+    children,
+    open,
+    loading,
+    className,
+    focusGroup,
+    focusGroupDirection,
+    arrowKeyShortcuts = true,
+    openKeyShortcut = "ArrowRight",
+    closeKeyShortcut = "ArrowLeft",
+    onToggle,
+    ...rest
+  } = props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  const [navState, setNavState] = useNavState(id);
+  const [innerOpen, innerOpenSetter] = useState(open || navState);
+  useFocusGroup(innerRef, {
+    enabled: focusGroup,
+    name: typeof focusGroup === "string" ? focusGroup : undefined,
+    direction: focusGroupDirection,
+  });
+
+  /**
+   * Browser will dispatch "toggle" event even if we set open={true}
+   * When rendering the component for the first time
+   * We have to ensure the initial "toggle" event is ignored.
+   *
+   * If we don't do that code will think the details has changed and run logic accordingly
+   * For example it will try to navigate to the current url while we are already there
+   *
+   * See:
+   * - https://techblog.thescore.com/2024/10/08/why-we-decided-to-change-how-the-details-element-works/
+   * - https://github.com/whatwg/html/issues/4500
+   * - https://stackoverflow.com/questions/58942600/react-html-details-toggles-uncontrollably-when-starts-open
+   *
+   */
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    mountedRef.current = true;
+  }, []);
+
+  const summaryRef = useRef(null);
+
+  useKeyboardShortcuts(
+    innerRef,
+    [
+      {
+        key: openKeyShortcut,
+        enabled: arrowKeyShortcuts,
+        when: (e) =>
+          document.activeElement === summaryRef.current &&
+          // avoid handling openKeyShortcut twice when keydown occurs inside nested details
+          !e.defaultPrevented,
+        action: (e) => {
+          const details = innerRef.current;
+          if (!details.open) {
+            e.preventDefault();
+            details.open = true;
+            return;
+          }
+          const summary = summaryRef.current;
+          const firstFocusableElementInDetails = findAfter(
+            summary,
+            elementIsFocusable,
+            { root: details },
+          );
+          if (!firstFocusableElementInDetails) {
+            return;
+          }
+          e.preventDefault();
+          firstFocusableElementInDetails.focus();
+        },
+      },
+      {
+        key: closeKeyShortcut,
+        enabled: arrowKeyShortcuts,
+        when: () => {
+          const details = innerRef.current;
+          return details.open;
+        },
+        action: (e) => {
+          const details = innerRef.current;
+          const summary = summaryRef.current;
+          if (document.activeElement === summary) {
+            e.preventDefault();
+            summary.focus();
+            details.open = false;
+          } else {
+            e.preventDefault();
+            summary.focus();
+          }
+        },
+      },
+    ],
+    (shortcut, e) => {
+      shortcut.action(e);
+    },
+  );
+
+  return (
+    <details
+      {...rest}
+      id={id}
+      className={[
+        "navi_details",
+        ...(className ? className.split(" ") : []),
+      ].join(" ")}
+      ref={innerRef}
+      onToggle={(e) => {
+        const isOpen = e.newState === "open";
+        if (mountedRef.current) {
+          if (isOpen) {
+            innerOpenSetter(true);
+            setNavState(true);
+          } else {
+            innerOpenSetter(false);
+            setNavState(undefined);
+          }
+        }
+        onToggle?.(e);
+      }}
+      open={innerOpen}
+    >
+      <summary ref={summaryRef}>
+        <div className="summary_body">
+          <SummaryMarker open={innerOpen} loading={loading} />
+          <div className="summary_label">{label}</div>
+        </div>
+      </summary>
+      {children}
+    </details>
+  );
+});
+
+const DetailsWithAction = forwardRef((props, ref) => {
+  const {
+    action,
+    loading,
+    onToggle,
+    onActionPrevented,
+    onActionStart,
+    onActionError,
+    onActionEnd,
+    children,
+    ...rest
+  } = props;
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  const effectiveAction = useAction(action);
+  const { loading: actionLoading } = useActionStatus(effectiveAction);
+  const executeAction = useExecuteAction(innerRef, {
+    // the error will be displayed by actionRenderer inside <details>
+    errorEffect: "none",
+  });
+  useActionEvents(innerRef, {
+    onPrevented: onActionPrevented,
+    onAction: executeAction,
+    onStart: onActionStart,
+    onError: onActionError,
+    onEnd: onActionEnd,
+  });
+
+  return (
+    <DetailsBasic
+      {...rest}
+      ref={innerRef}
+      onToggle={(toggleEvent) => {
+        const isOpen = toggleEvent.newState === "open";
+        if (isOpen) {
+          requestAction(effectiveAction, {
+            event: toggleEvent,
+            method: "run",
+          });
+        } else {
+          effectiveAction.abort();
+        }
+        onToggle?.(toggleEvent);
+      }}
+      loading={loading || actionLoading}
+    >
+      <ActionRenderer action={effectiveAction}>{children}</ActionRenderer>
+    </DetailsBasic>
+  );
+});

package/src/components/details/summary_marker.jsx

@@ -0,0 +1,141 @@
+import { useLayoutEffect, useRef } from "preact/hooks";
+import { useDebounceTrue } from "../use_debounce_true.js";
+
+const rightArrowPath = "M680-480L360-160l-80-80 240-240-240-240 80-80 320 320z";
+const downArrowPath = "M480-280L160-600l80-80 240 240 240-240 80 80-320 320z";
+
+import.meta.css = /* css */ `
+  .summary_marker {
+    width: 1em;
+    height: 1em;
+    line-height: 1em;
+  }
+  .summary_marker_svg .arrow {
+    animation-duration: 0.3s;
+    animation-fill-mode: forwards;
+    animation-timing-function: cubic-bezier(0.34, 1.56, 0.64, 1);
+  }
+  .summary_marker_svg .arrow[data-animation-target="down"] {
+    animation-name: morph-to-down;
+  }
+  @keyframes morph-to-down {
+    from {
+      d: path("${rightArrowPath}");
+    }
+    to {
+      d: path("${downArrowPath}");
+    }
+  }
+  .summary_marker_svg .arrow[data-animation-target="right"] {
+    animation-name: morph-to-right;
+  }
+  @keyframes morph-to-right {
+    from {
+      d: path("${downArrowPath}");
+    }
+    to {
+      d: path("${rightArrowPath}");
+    }
+  }
+
+  .summary_marker_svg .foreground_circle {
+    stroke-dasharray: 503 1507; /* ~25% of circle perimeter */
+    stroke-dashoffset: 0;
+    animation: progress-around-circle 1.5s linear infinite;
+  }
+  @keyframes progress-around-circle {
+    0% {
+      stroke-dashoffset: 0;
+    }
+    100% {
+      stroke-dashoffset: -2010;
+    }
+  }
+
+  /* fading and scaling */
+  .summary_marker_svg .arrow {
+    transition: opacity 0.3s ease-in-out;
+    opacity: 1;
+  }
+  .summary_marker_svg .loading_container {
+    transition: transform 0.3s linear;
+    transform: scale(0.3);
+  }
+  .summary_marker_svg .background_circle,
+  .summary_marker_svg .foreground_circle {
+    transition: opacity 0.3s ease-in-out;
+    opacity: 0;
+  }
+  .summary_marker_svg[data-loading] .arrow {
+    opacity: 0;
+  }
+  .summary_marker_svg[data-loading] .loading_container {
+    transform: scale(1);
+  }
+  .summary_marker_svg[data-loading] .background_circle {
+    opacity: 0.2;
+  }
+  .summary_marker_svg[data-loading] .foreground_circle {
+    opacity: 1;
+  }
+`;
+
+export const SummaryMarker = ({ open, loading }) => {
+  const showLoading = useDebounceTrue(loading, 300);
+  const mountedRef = useRef(false);
+  const prevOpenRef = useRef(open);
+
+  useLayoutEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const shouldAnimate = mountedRef.current && prevOpenRef.current !== open;
+  prevOpenRef.current = open;
+
+  return (
+    <span className="summary_marker">
+      <svg
+        className="summary_marker_svg"
+        viewBox="0 -960 960 960"
+        xmlns="http://www.w3.org/2000/svg"
+        data-loading={open ? showLoading || undefined : undefined}
+      >
+        <g className="loading_container" transform-origin="480px -480px">
+          <circle
+            className="background_circle"
+            cx="480"
+            cy="-480"
+            r="320"
+            stroke="currentColor"
+            fill="none"
+            strokeWidth="60"
+            opacity="0.2"
+          />
+          <circle
+            className="foreground_circle"
+            cx="480"
+            cy="-480"
+            r="320"
+            stroke="currentColor"
+            fill="none"
+            strokeWidth="60"
+            strokeLinecap="round"
+            strokeDasharray="503 1507"
+          />
+        </g>
+        <g className="arrow_container" transform-origin="480px -480px">
+          <path
+            className="arrow"
+            fill="currentColor"
+            data-animation-target={
+              shouldAnimate ? (open ? "down" : "right") : undefined
+            }
+            d={open ? downArrowPath : rightArrowPath}
+          />
+        </g>
+      </svg>
+    </span>
+  );
+};

package/src/components/editable_text/editable_text.jsx

@@ -0,0 +1,96 @@
+import { forwardRef } from "preact/compat";
+import {
+  useCallback,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "preact/hooks";
+import { Input } from "../input/input.jsx";
+
+export const useEditableController = () => {
+  const [editable, editableSetter] = useState(null);
+  const startEditing = useCallback(({ focusVisible } = {}) => {
+    editableSetter({
+      focusVisible,
+    });
+  }, []);
+  const stopEditing = useCallback(() => {
+    editableSetter(null);
+  }, []);
+
+  const prevEditableRef = useRef(editable);
+  const editableJustEnded = prevEditableRef.current && !editable;
+  prevEditableRef.current = editable;
+
+  return { editable, startEditing, stopEditing, editableJustEnded };
+};
+
+export const EditableText = forwardRef((props, ref) => {
+  let { children, action, editable, value, valueSignal, onEditEnd, ...rest } =
+    props;
+  if (import.meta.DEV && !action) {
+    console.warn(`EditableText requires an action prop`);
+  }
+
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+
+  if (valueSignal) {
+    value = valueSignal.value;
+  }
+
+  const editablePreviousRef = useRef(editable);
+  const valueWhenEditStartRef = useRef(editable ? value : undefined);
+  if (editablePreviousRef.current !== editable) {
+    if (editable) {
+      valueWhenEditStartRef.current = value;
+    }
+    editablePreviousRef.current = editable;
+  }
+
+  return (
+    <>
+      <div style={{ display: editable ? "none" : "inline-flex", flexGrow: 1 }}>
+        {children || <span>{value}</span>}
+      </div>
+      {editable && (
+        <Input
+          autoFocus
+          autoFocusVisible
+          autoSelect
+          required
+          cancelOnEscape
+          cancelOnBlurInvalid
+          onCancel={(e) => {
+            if (valueSignal) {
+              valueSignal.value = valueWhenEditStartRef.current;
+            }
+            onEditEnd({
+              cancelled: true,
+              event: e,
+            });
+          }}
+          onBlur={(e) => {
+            if (e.target.value === valueWhenEditStartRef.current) {
+              onEditEnd({
+                cancelled: true,
+                event: e,
+              });
+            }
+          }}
+          action={action}
+          onActionEnd={(e) => {
+            onEditEnd({
+              success: true,
+              event: e,
+            });
+          }}
+          ref={innerRef}
+          value={value}
+          valueSignal={valueSignal}
+          {...rest}
+        />
+      )}
+    </>
+  );
+});

package/src/components/error_boundary_context.js

@@ -0,0 +1,9 @@
+import { createContext } from "preact";
+import { useContext } from "preact/hooks";
+
+export const ErrorBoundaryContext = createContext(null);
+
+export const useResetErrorBoundary = () => {
+  const resetErrorBoundary = useContext(ErrorBoundaryContext);
+  return resetErrorBoundary;
+};

package/src/components/form.jsx

@@ -0,0 +1,144 @@
+/**
+ *
+ * Here we want the same behaviour as web standards:
+ *
+ * 1. When submitting the form URL does not change
+ * 2. When form submission id done user is redirected (by default the current one)
+ *    (we can configure this using target)
+ *    So for example user might be reidrect to a page with the resource he just created
+ *    I could create an example where we would put a link on the page to let user see what he created
+ *    but by default user stays on the form allowing to create multiple resources at once
+ *    And an other where he is redirected to the resource he created
+ * 3. If form submission fails ideally we should display this somewhere on the UI
+ *    right now it's just logged to the console I need to see how we can achieve this
+ */
+
+import { requestAction, useConstraints } from "@jsenv/validation";
+import { forwardRef } from "preact/compat";
+import { useImperativeHandle, useRef, useState } from "preact/hooks";
+import { FormContext } from "./action_execution/form_context.js";
+import { renderActionableComponent } from "./action_execution/render_actionable_component.jsx";
+import { useFormActionBoundToFormParams } from "./action_execution/use_action.js";
+import { useExecuteAction } from "./action_execution/use_execute_action.js";
+import { collectFormElementValues } from "./collect_form_element_values.js";
+import { useActionEvents } from "./use_action_events.js";
+
+export const Form = forwardRef((props, ref) => {
+  return renderActionableComponent(props, ref, {
+    Basic: FormBasic,
+    WithAction: FormWithAction,
+  });
+});
+
+const FormBasic = forwardRef((props, ref) => {
+  return <form ref={ref} {...props} />;
+});
+
+const FormWithAction = forwardRef((props, ref) => {
+  let {
+    action,
+    method,
+    readOnly = false,
+    allowConcurrentActions: formAllowConcurrentActions = false,
+    actionErrorEffect = "show_validation_message", // "show_validation_message" or "throw"
+    onActionPrevented,
+    onActionStart,
+    onActionAbort,
+    onActionError,
+    onActionEnd,
+    children,
+    ...rest
+  } = props;
+
+  const innerRef = useRef();
+  useImperativeHandle(ref, () => innerRef.current);
+  // instantiation validation to:
+  // - receive "requestsubmit" custom event ensure submit is prevented
+  // (and also execute action without validation if form.submit() is ever called)
+  useConstraints(innerRef, []);
+
+  const [boundAction, formParamsSignal, setFormParams] =
+    useFormActionBoundToFormParams(action);
+  const [formActionRequester, setFormActionRequester] = useState(null);
+  const [formIsBusy, setFormIsBusy] = useState(false);
+  const [formActionError, setFormActionError] = useState(null);
+  const [formActionAborted, setFormActionAborted] = useState(false);
+  const executeAction = useExecuteAction(innerRef, {
+    errorEffect: actionErrorEffect,
+  });
+  const formIsReadOnly =
+    readOnly || (formIsBusy && !formAllowConcurrentActions);
+
+  useActionEvents(innerRef, {
+    onPrevented: onActionPrevented,
+    onAction: (actionEvent) => {
+      const form = innerRef.current;
+      const formElementValues = collectFormElementValues(form);
+      setFormParams(formElementValues);
+
+      setFormActionRequester(actionEvent.detail.requester);
+      executeAction(actionEvent);
+    },
+    onStart: (e) => {
+      setFormIsBusy(true);
+      setFormActionError(null);
+      setFormActionAborted(false);
+      onActionStart?.(e);
+    },
+    onAbort: (e) => {
+      setFormIsBusy(false);
+      setFormActionAborted(true);
+      onActionAbort?.(e);
+    },
+    onError: (e) => {
+      setFormIsBusy(false);
+      setFormActionError(e);
+      onActionError?.(e);
+    },
+    onEnd: (e) => {
+      setFormIsBusy(false);
+      onActionEnd?.(e);
+    },
+  });
+
+  return (
+    <form
+      {...rest}
+      data-action={boundAction.name}
+      data-method={action.meta?.httpVerb || method || "GET"}
+      ref={innerRef}
+      // eslint-disable-next-line react/no-unknown-property
+      onrequestsubmit={(e) => {
+        // prevent "submit" event that would be dispatched by the browser after form.requestSubmit()
+        // (not super important because our <form> listen the "action" and do does preventDefault on "submit")
+        e.preventDefault();
+        requestAction(boundAction, { event: e });
+      }}
+    >
+      <FormContext.Provider
+        value={{
+          formAllowConcurrentActions,
+          formAction: boundAction,
+          formParamsSignal,
+          formActionRequester,
+          formIsReadOnly,
+          formIsBusy,
+          formActionAborted,
+          formActionError,
+        }}
+      >
+        {children}
+      </FormContext.Provider>
+    </form>
+  );
+});
+
+// const dispatchCustomEventOnFormAndFormElements = (type, options) => {
+//   const form = innerRef.current;
+//   const customEvent = new CustomEvent(type, options);
+//   // https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements
+//   for (const element of form.elements) {
+//     element.dispatchEvent(customEvent);
+//   }
+//   form.dispatchEvent(customEvent);
+// };