@jsenv/navi 0.10.2 → 0.11.0

package/src/components/edition/editable.jsx

@@ -1,186 +0,0 @@
-/**
- * - We must keep the edited element in the DOM so that
- * the layout remains the same (especially important for table cells)
- * And the editable part is in absolute so that it takes the original content dimensions
- * AND for table cells it can actually take the table cell dimensions
- *
- * This means an editable thing MUST have a parent with position relative that wraps the content and the eventual editable input
- *
- */
-
-import { forwardRef } from "preact/compat";
-import {
-  useCallback,
-  useImperativeHandle,
-  useLayoutEffect,
-  useRef,
-  useState,
-} from "preact/hooks";
-
-import { Input } from "../field/input.jsx";
-
-import.meta.css = /* css */ `
-  .navi_editable_wrapper {
-    position: absolute;
-    inset: 0;
-  }
-`;
-
-export const useEditionController = () => {
-  const [editing, editingSetter] = useState(null);
-  const startEditing = useCallback((event) => {
-    editingSetter((current) => {
-      return current || { event };
-    });
-  }, []);
-  const stopEditing = useCallback(() => {
-    editingSetter(null);
-  }, []);
-
-  const prevEditingRef = useRef(editing);
-  const editionJustEnded = prevEditingRef.current && !editing;
-  prevEditingRef.current = editing;
-
-  return { editing, startEditing, stopEditing, editionJustEnded };
-};
-
-export const Editable = forwardRef((props, ref) => {
-  let {
-    children,
-    action,
-    editing,
-    name,
-    value,
-    valueSignal,
-    onEditEnd,
-    constraints,
-    type,
-    required,
-    readOnly,
-    min,
-    max,
-    step,
-    minLength,
-    maxLength,
-    pattern,
-    wrapperProps,
-    autoSelect = true,
-    width,
-    height,
-    ...rest
-  } = props;
-  if (import.meta.dev && !action) {
-    console.warn(`Editable requires an action prop`);
-  }
-
-  const innerRef = useRef();
-  useImperativeHandle(ref, () => innerRef.current);
-
-  if (valueSignal) {
-    value = valueSignal.value;
-  }
-
-  const editingPreviousRef = useRef(editing);
-  const valueWhenEditStartRef = useRef(editing ? value : undefined);
-
-  if (editingPreviousRef.current !== editing) {
-    if (editing) {
-      valueWhenEditStartRef.current = value; // Always store the external value
-    }
-    editingPreviousRef.current = editing;
-  }
-
-  // Simulate typing the initial value when editing starts with a custom value
-  useLayoutEffect(() => {
-    if (!editing) {
-      return;
-    }
-    const editingEvent = editing.event;
-    if (!editingEvent) {
-      return;
-    }
-    const editingEventInitialValue = editingEvent.detail?.initialValue;
-    if (editingEventInitialValue === undefined) {
-      return;
-    }
-    const input = innerRef.current;
-    input.value = editingEventInitialValue;
-    input.dispatchEvent(
-      new CustomEvent("input", {
-        bubbles: false,
-      }),
-    );
-  }, [editing]);
-
-  const input = (
-    <Input
-      ref={innerRef}
-      {...rest}
-      type={type}
-      name={name}
-      value={value}
-      valueSignal={valueSignal}
-      autoFocus
-      autoFocusVisible
-      autoSelect={autoSelect}
-      cancelOnEscape
-      cancelOnBlurInvalid
-      constraints={constraints}
-      required={required}
-      readOnly={readOnly}
-      min={min}
-      max={max}
-      step={step}
-      minLength={minLength}
-      maxLength={maxLength}
-      pattern={pattern}
-      width={width}
-      height={height}
-      onCancel={(e) => {
-        if (valueSignal) {
-          valueSignal.value = valueWhenEditStartRef.current;
-        }
-        onEditEnd({
-          cancelled: true,
-          event: e,
-        });
-      }}
-      onBlur={(e) => {
-        const value =
-          type === "number" ? e.target.valueAsNumber : e.target.value;
-        const valueWhenEditStart = valueWhenEditStartRef.current;
-        if (value === valueWhenEditStart) {
-          onEditEnd({
-            cancelled: true,
-            event: e,
-          });
-          return;
-        }
-      }}
-      action={action || (() => {})}
-      onActionEnd={(e) => {
-        onEditEnd({
-          success: true,
-          event: e,
-        });
-      }}
-    />
-  );
-
-  return (
-    <>
-      {children || <span>{value}</span>}
-      {editing && (
-        <div
-          {...wrapperProps}
-          className={[
-            "navi_editable_wrapper",
-            ...(wrapperProps?.className || "").split(" "),
-          ].join(" ")}
-        >
-          {input}
-        </div>
-      )}
-    </>
-  );
-});

package/src/components/error_boundary_context.js

@@ -1,9 +0,0 @@
-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/field/README.md

@@ -1,247 +0,0 @@
-# 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.