@hrbolek/uoisfrontend-template 0.6.0

package/src/Base/FormControls/Input.jsx

@@ -0,0 +1,163 @@
+import { useMemo } from "react";
+import { useEffect } from "react";
+import { Label } from "./Label";
+import { useRef } from "react";
+import { useState } from "react";
+
+/**
+ * Univerzální `<input>` wrapper s podporou controlled i uncontrolled režimu,
+ * s volitelným label obalem přes {@link Label}. Normalizuje `onChange`/`onBlur`
+ * tak, že callbacky vždy dostanou objekt ve tvaru `{ target: { id, value } }`.
+ *
+ * Chování:
+ * - **Controlled**: pokud je předán `value`, komponenta řídí hodnotu přes `value`.
+ * - **Uncontrolled**: pokud `value` není předán, použije se `defaultValue`.
+ * - `onBlur` se vyvolá pouze pokud uživatel opravdu změnil hodnotu (touched).
+ * - Pro `type="number"` komponenta převádí hodnotu na `number` (nebo `""` při prázdnu/NaN).
+ * - Pokud se interní `value_` liší od `value`, přidá se třída `bg-warning`.
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} [props.label]
+ *  Text titulku; pokud je uveden, input se zabalí do {@link Label} a použije se jako `title`.
+ *  Pokud není, vrací se přímo element `<input>`.
+ * @param {boolean} [props.ariaHidden=false]
+ *  Pokud `true`, komponenta nerenderuje nic (`null`). Vhodné pro podmíněné skrývání.
+ * @param {React.ReactNode} [props.children]
+ *  Dodatečný obsah renderovaný pod inputem (pouze pokud je `label` uveden).
+ *
+ * @param {string} [props.id]
+ *  ID inputu. Použije se i v emitovaných událostech (`target.id`).
+ * @param {string|number} [props.value]
+ *  Controlled hodnota. Pokud je definovaná, komponenta přepne do controlled režimu.
+ * @param {string|number} [props.defaultValue]
+ *  Výchozí hodnota pro uncontrolled režim.
+ * @param {("text"|"number"|string)} [props.type="text"]
+ *  Typ inputu. Pro `"number"` probíhá coercion na `number`/`""`.
+ * @param {(e: {target: {id: string, value: any}}) => void} [props.onChange]
+ *  Callback při změně; dostane normalizovaný event `{ target: { id, value } }`.
+ * @param {(e: {target: {id: string, value: any}}) => void} [props.onBlur]
+ *  Callback při blur; vyvolá se pouze pokud uživatel předtím změnil hodnotu (touched).
+ *
+ * @param {Object<string, any>} [props.rest]
+ *  Ostatní props předané přímo do `<input />` (např. `className`, `placeholder`, `disabled`,
+ *  `min`, `max`, `step`, `name`, `autoComplete`, `data-*`, atd.).
+ *
+ * @returns {JSX.Element|null}
+ *
+ * @example
+ * // Controlled
+ * <Input
+ *   id="age"
+ *   label="Age"
+ *   type="number"
+ *   value={age}
+ *   onChange={({ target }) => setAge(target.value)}
+ *   onBlur={({ target }) => saveAge(target.value)}
+ * />
+ *
+ * @example
+ * // Uncontrolled
+ * <Input id="name" defaultValue="John" onBlur={({ target }) => console.log(target.value)} />
+ */
+export const Input = ({ label, ariaHidden = false, children, ...props }) => {
+    const {
+        id,
+        value,
+        defaultValue,
+        onChange = () => null,
+        onBlur = () => null,
+        type="text",
+        reset=0,
+        ...rest
+    } = props;
+
+    const isControlled = value !== undefined; // klíčové
+    const touchedRef = useRef(false);
+
+    const coerceValue = (val) => {
+        if (type === "number") {
+            if (val === "" || val == null) return "";
+            const num = Number(val);
+            return Number.isNaN(num) ? "" : num;
+        }
+        return val ?? "";
+    };
+
+    const [value_, setValue_] = useState(() => coerceValue(value));
+    
+    useEffect(() => {
+        // console.log("Input.useEffect.value")
+        if (!isControlled) return;
+        // console.log("Input.useEffect.value changed to", value)
+        touchedRef.current = false;
+        setValue_(value)
+    }, [isControlled, value, reset])
+
+
+    // reset "touched", když se změní hodnota zvenku (typicky reload / cancel / confirm)
+    const externalValueKey = useMemo(
+        () => (isControlled ? coerceValue(value) : undefined),
+        [isControlled, value, type]
+    );
+
+    useEffect(() => {
+        if (isControlled) touchedRef.current = false;
+    }, [externalValueKey, isControlled]);
+
+    const emit = (cb) => (e) => {
+        const coercedValue = coerceValue(e.target.value);
+        cb({ target: { id, value: coercedValue } });
+    };
+
+    const handleChange = (e) => {
+        touchedRef.current = true;
+        const value = e?.target?.value
+        setValue_(value)
+        // console.log("Input.handleChange.value changed to", value, reset)
+        emit(onChange)(e);
+    };
+
+    const handleBlur = (e) => {
+        if (!touchedRef.current) return;
+        emit(onBlur)(e);
+    };
+
+    if (ariaHidden) return null;
+
+    const inputProps = {
+        id,
+        type,
+        onChange: handleChange,
+        onBlur: handleBlur,
+        ...rest,
+    };
+
+    // Controlled vs uncontrolled:
+    if (isControlled) {
+        // console.log("Input.isControlled using value", value_, value)
+        inputProps.value = coerceValue(value_);
+    } else {
+        inputProps.defaultValue = coerceValue(defaultValue);
+    }
+
+    if (value !== value_) {
+        inputProps.className = (inputProps.className ? inputProps.className + " " : "") + "bg-warning";
+    }
+    // console.log("Input default", isControlled, defaultValue, inputProps)
+    const inputElement = <input {...inputProps} />;
+
+    // console.log(inputProps)
+    if (!label) return inputElement;
+
+    return (
+        <Label title={label}>
+            {/* {JSON.stringify(inputProps)} */}
+            {inputElement}
+            {/* value_: {value_} <br />
+            value: {value}  */}
+
+            {children}
+        </Label>
+    );
+};

package/src/Base/FormControls/Label.jsx

@@ -0,0 +1,40 @@
+import { SimpleCardCapsule } from "../Components/CardCapsule"
+
+/**
+ * Komponenta pro jednoduché “označené” (labelované) zobrazení obsahu v kapsli.
+ * Využívá {@link SimpleCardCapsule} jako vizuální obal a umožňuje vložit
+ * do hlavičkové části (před `children`) volitelné nástroje/akce.
+ *
+ * Typické použití:
+ * - panel s tlačítky (tools) + obsah (children),
+ * - “sekce” formuláře s akcemi (např. Přidat, Obnovit, Uložit),
+ * - obal pro vizuální sjednocení.
+ *
+ * @component
+ * @param {Object} props
+ * @param {React.ReactNode} [props.tools]
+ *  Volitelné UI prvky zobrazené před hlavním obsahem (např. tlačítka, badge, filtr).
+ * @param {React.ReactNode} [props.children]
+ *  Hlavní obsah komponenty.
+ * @param {Object<string, any>} [props.props]
+ *  Další props jsou předány do {@link SimpleCardCapsule} (např. `id`, `title`, `header`,
+ *  `style`, `className`, `data-*`).
+ *
+ * @returns {JSX.Element}
+ *
+ * @example
+ * <Label
+ *   title="Nastavení"
+ *   tools={<button onClick={reset}>Reset</button>}
+ * >
+ *   <SettingsForm />
+ * </Label>
+ */
+export const Label = ({tools, children, ...props}) => {
+    return (
+        <SimpleCardCapsule {...props}>
+            {tools}
+            {children}
+        </SimpleCardCapsule>
+    )
+}

package/src/Base/FormControls/Select.jsx

@@ -0,0 +1,150 @@
+import React, { useState } from 'react'
+import { useEffect, useRef } from 'react'
+import { Label } from './Label'
+
+/**
+ * A React component that renders a styled `<select>` dropdown with dynamic options and enhanced change detection.
+ *
+ * This component integrates with the `Options` component to fetch and display dynamic `<option>` elements.
+ * It uses a `MutationObserver` to detect changes in the `<select>` element's children and triggers the `onChange`
+ * event accordingly. The dropdown is wrapped in a `SimpleCardCapsule` for a consistent UI layout.
+ *
+ * @function Select
+ * @param {Object} props - The properties for the Select component.
+ * @param {string} [props.label] - The label displayed as the title of the `SimpleCardCapsule`.
+ * @param {React.ReactNode} props.children - The `<option>` elements or an `Options` component to render dynamic options.
+ * @param {string} [props.id] - The unique identifier for the `<select>` element.
+ * @param {string|number} [props.value] - The current value of the `<select>` element, used for controlled components.
+ * @param {string|number} [props.defaultValue] - The default value of the `<select>` element, used for uncontrolled components.
+ * @param {Function} [props.onChange] - A callback function triggered when the `<select>` value changes. Receives an event object.
+ * @param {Function} [props.onBlur] - A callback function triggered when the `<select>` loses focus. Receives an event object.
+ * @param {Object} props.rest - Any additional props passed to the `<select>` element.
+ *
+ * @returns {JSX.Element} A styled dropdown wrapped in a `SimpleCardCapsule` with dynamic options and change detection.
+ *
+ * @example
+ * // Example usage with Options:
+ * const MyComponent = () => {
+ *   const fetchOptions = (params) => async (dispatch) => {
+ *     const response = await fetch('/api/data', {
+ *       method: 'POST',
+ *       body: JSON.stringify(params),
+ *     });
+ *     const json = await response.json();
+ *     return json;
+ *   };
+ *
+ *   const [selectedValue, setSelectedValue] = useState("");
+ *   const [fetchTrigger, setFetchTrigger] = useState(0);
+ *
+ *   const handleChange = (e) => {
+ *     setSelectedValue(e.target.value);
+ *   };
+ *
+ *   const refreshOptions = () => setFetchTrigger((prev) => prev + 1);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={refreshOptions}>Refresh Options</button>
+ *       <Select
+ *         label="Dynamic Select"
+ *         id="dynamic-select"
+ *         value={selectedValue}
+ *         onChange={handleChange}
+ *       >
+ *         <Options asyncAction={fetchOptions} params={{ someParam: "value" }} shouldFetch={fetchTrigger} />
+ *       </Select>
+ *     </div>
+ *   );
+ * };
+ */
+export const Select_ = ({ label, children, defaultValue, onChange, onBlur, ariaHidden, ...props }) => {
+    const selectRef = useRef(null);
+    const prevValueRef = useRef(defaultValue); // poslední známá hodnota
+
+    useEffect(() => {
+        if (!selectRef.current || typeof onChange !== "function") return;
+
+        const observer = new MutationObserver(() => {
+            // Oddálíme vyhodnocení, až se React přepne na novou hodnotu
+            setTimeout(() => {
+                const current = selectRef.current?.value;
+
+                if (prevValueRef.current !== current) {
+                    prevValueRef.current = current;
+                    const event = { target: { id: selectRef.current.id, value: current } };
+                    console.log("Select firing event due to real change", event);
+                    onChange(event);
+                } else {
+                    console.log("MutationObserver detected change but value unchanged");
+                }
+            }, 0);
+        });
+
+        observer.observe(selectRef.current, { childList: true, subtree: true });
+
+        // Uložíme počáteční hodnotu
+        if (selectRef.current?.value) {
+            prevValueRef.current = selectRef.current.value;
+        }
+
+        return () => observer.disconnect();
+    }, [onChange, children]);
+
+    if (ariaHidden) return null;
+
+    const selectElement = (
+        <select
+            ref={selectRef}
+            defaultValue={defaultValue}
+            onChange={onChange}
+            onBlur={onBlur}
+            {...props}
+        >
+            {children}
+        </select>
+    );
+
+    return label ? <Label title={label}>{selectElement}</Label> : selectElement;
+};
+
+
+export const Select = ({ id, label, value, onChange, onBlur, children, ...props }) => {
+    const [internalValue, setInternalValue] = useState(value ?? "");
+
+    // Když se externí `value` změní, aktualizuj i vnitřní stav
+    useEffect(() => {
+        setInternalValue(value ?? "");
+    }, [value]);
+
+    const handleChange = (e) => {
+        const newValue = e.target.value;
+        setInternalValue(newValue); // aktualizuj interní stav
+        onChange?.({ target: { id, value: newValue } }); // zavolej callback s konzistentním tvarem
+    };
+
+    const handleBlur = (e) => {
+        const newValue = e.target.value;
+        onBlur?.({ target: { id, value: newValue } });
+    };
+
+    const selectElement = (
+        <select
+            id={id}
+            value={internalValue}
+            onChange={handleChange}
+            onBlur={handleBlur}
+            {...props}
+        >
+            {children}
+        </select>
+    );
+
+    if (props.ariaHidden) return null;
+
+    return label ? (
+        <Label title={label}>{selectElement}</Label>
+    ) : (
+        selectElement
+    );
+};

package/src/Base/FormControls/TextArea.jsx

@@ -0,0 +1,86 @@
+import { useEffect, useRef, useState, useCallback } from "react";
+import { Label } from './Label';
+
+export const TextArea = ({
+    id,
+    value,
+    label,
+    placeHolder,
+    ariaHidden = false,
+    autoHeight = true,
+
+    // IMPORTANT: očekává string, ne event
+    onChange = (_value) => null,
+    onBlur = (_value) => null,
+
+    ...props
+}) => {
+    const textareaRef = useRef(null);
+
+    const [value_, setValue_] = useState(value ?? "");
+    const [dirty, setDirty] = useState(false);
+
+    const adjustHeight = useCallback(() => {
+        if (!autoHeight) return;
+        const el = textareaRef.current;
+        if (!el) return;
+        el.style.height = "auto";
+        el.style.height = `${el.scrollHeight + 10}px`;
+    }, [autoHeight]);
+
+    // autoheight reaguje na obsah
+    useEffect(() => {
+        adjustHeight();
+    }, [value_, adjustHeight]);
+
+    useEffect(() => {
+        const external = value ?? "";
+
+        // 1) sync zvenku jen když uživatel nepíše
+        if (!dirty) {
+            setValue_(external);
+            return;
+        }
+
+        // 2) když uživatel píše, ale backend dohnal stejnou hodnotu, shodit dirty
+        if (external === value_) {
+            setDirty(false);
+        }
+    }, [value, value_, dirty]);
+
+    const handleChange = (e) => {
+        const next = e?.target?.value ?? "";
+        setDirty(true);
+        setValue_(next);
+        onChange({ target: { id, value: next }}); // bez debounce uvnitř, debounce je externí
+    };
+
+    const handleBlur = () => {
+        // na blur obvykle chceš "flush" (externí debounce by měl mít flush),
+        // tady aspoň pošli aktuální hodnotu:
+        onBlur({ target: { id, value: value_ }});
+    };
+
+    const textarea = (
+        <textarea
+            {...props}
+            ref={textareaRef}
+            value={value_}
+            aria-hidden={ariaHidden ? true : undefined}
+            onChange={handleChange}
+            onBlur={handleBlur}
+        />
+    );
+
+    if (ariaHidden) return textarea;
+
+    const content = (
+        <>
+            {placeHolder && <p>{placeHolder}</p>}
+            {textarea}
+        </>
+    );
+
+    if (label) return <Label title={label}>{content}</Label>;
+    return content;
+};

package/src/Base/FormControls/index.js

@@ -0,0 +1,8 @@
+export * from "./Collapsible"
+export * from "./Dialog"
+export * from "./EntityLookup"
+export * from "./Filter"
+export * from "./Input"
+export * from "./Label"
+export * from "./Select"
+export * from "./TextArea"

package/src/Base/Helpers/AsyncStateIndicator.jsx

@@ -0,0 +1,9 @@
+import { ErrorHandler, LoadingSpinner } from "@hrbolek/uoisfrontend-shared"
+
+export const AsyncStateIndicator = ({ error, loading, text, children }) => {
+    return (<>
+        {error && <ErrorHandler errors={error} />}
+        {loading && <LoadingSpinner text={text} />}
+        {/* {!error && !loading && children} */}
+    </>)
+}

package/src/Base/Helpers/GQLEntityProvider.jsx

@@ -0,0 +1,163 @@
+import { useContext } from "react";
+import { createContext } from "react";
+import { useAsyncThunkAction } from "../../../../dynamic/src/Hooks";
+import { useState } from "react";
+import { CreateDelayer } from "@hrbolek/uoisfrontend-shared";
+import { AsyncStateIndicator } from "./AsyncStateIndicator";
+import { SimpleCardCapsule } from "../Components";
+import { useCallback } from "react";
+
+const GQLEntityContext = createContext(null);
+export const useGQLEntityContext = () => {
+    const result = useContext(GQLEntityContext)
+    if (result == null) {
+        throw new Error("useGQLEntityContext must be used within a GQLEntityProvider")
+    }
+    return result
+}
+
+
+/**
+ * Provider, který nad daným `item` spouští asynchronní thunk akci (`queryAsyncAction`)
+ * přes `useAsyncThunkAction` a zpřístupňuje stav + handlery potomkům přes `GQLEntityContext`.
+ *
+ * Kontextová hodnota obsahuje:
+ * - `loading`   {boolean}  stav načítání
+ * - `error`     {any|null} chyba z posledního volání (pokud nastala)
+ * - `reRead`    {Function} funkce pro znovunačtení (alias na `run`)
+ * - `item`      {any|null} entita ze storu (typicky `entity` z `useAsyncThunkAction`)
+ * - `data`      {any|null} návratová data z thunk akce (typicky `data` z `useAsyncThunkAction`)
+ * - `onChange`  {Function} debounced handler pro změnu (volá `run`)
+ * - `onBlur`    {Function} alias na `onChange`
+ *
+ * @component
+ *
+ * @param {Object} props
+ * @param {any} props.item
+ *        Vstupní item/vars pro `queryAsyncAction`. Typicky objekt s `{ id }` nebo rovnou entita,
+ *        podle toho, jak máš `useAsyncThunkAction`/`queryAsyncAction` postavené.
+ *
+ * @param {Function} props.queryAsyncAction
+ *        Factory pro thunk async akci. Musí být kompatibilní s `useAsyncThunkAction`,
+ *        tj. typicky funkce, kterou lze volat jako `queryAsyncAction(vars, client?)`
+ *        a která vrací thunk `(dispatch, getState, extra?) => Promise<any>`.
+ *
+ * @param {Object} [props.options]
+ * @param {boolean} [props.options.deferred=false]
+ *        Pokud je `false`, hook může spustit první načtení automaticky (podle implementace `useAsyncThunkAction`).
+ * @param {boolean} [props.options.network=true]
+ *        Pokud je `false`, `run` se nebude provádět (offline režim / vypnutí síťových volání).
+ *
+ * @param {import('react').ReactNode} props.children
+ *        Potomci, kteří budou mít přístup ke kontextu.
+ *
+ * @returns {import('react').JSX.Element}
+ */
+export const AsyncActionProvider = ({
+    item,
+    queryAsyncAction,
+    options = { deferred: false, network: true },
+
+    onChange = () => null,
+    onBlur = () => null,
+
+    children,
+}) => {
+    if (queryAsyncAction == null) {
+        throw new Error("AsyncActionProvider: queryAsyncAction is required");
+    }
+
+    const [contextid] = useState(crypto?.randomUUID?.() ?? null)
+    const { run, error, loading, entity, data } = useAsyncThunkAction(queryAsyncAction, item, options)
+    const [delayer] = useState(() => CreateDelayer())
+    const [varsState, setVarsState] = useState(item || {});
+    const onEvent = useCallback((masterEvent) => async (e) => {
+        // console.log("AsyncAcionProvider onChange e", contextid, e)
+        const value = e?.target?.value
+        setVarsState(old => value)
+        const newState = await delayer(() => run(value))
+        // console.log("AsyncAcionProvider newState e", contextid, newState)
+        const newE = { target: { value: newState } }
+        return await masterEvent(newE)
+    }, [setVarsState, delayer, run])
+    
+    const handleChange = useCallback(
+        onEvent(onChange), [onEvent, onChange]
+    )
+    const handleBlur = useCallback(
+        onEvent(onBlur), [onEvent, onBlur]
+    )
+    // console.log("GQLEntityProvider", item, "entity", entity, "data", data)
+    const contextValue = {
+        loading,
+        error,
+        reRead: run,
+        params: varsState,
+        item: entity,
+        data,
+        onChange: handleChange,
+        onBlur: handleBlur
+    }
+    // console.log("GQLEntityProvider item", contextid, entity, data)
+    // console.log("GQLEntityProvider contextValue", contextid, contextValue)
+    // if (!item) return null;
+    return (
+        <GQLEntityContext.Provider value={contextValue}>
+            {/* <h1>{contextid}</h1> */}
+            <AsyncStateIndicator error={error} loading={loading} />
+
+            {/* {(!loading && !error) && children} */}
+            {children}
+            {/* {!contextValue.item && <pre>{JSON.stringify(contextValue)}</pre>} */}
+            {/* <pre>{JSON.stringify(contextValue, null, 2)}</pre> */}
+        </GQLEntityContext.Provider>
+    );
+};
+
+export const Group = ({ id, children }) => {
+    const entityCtx = useContext(GQLEntityContext);
+    if (!entityCtx) throw Error("Group must be used within GQLEntityContext");
+
+    const wrapEvent = useCallback(
+        (eOrValue) => {
+            // dovol: event nebo přímá hodnota
+            const value =
+                eOrValue && typeof eOrValue === "object" && "target" in eOrValue
+                    ? eOrValue.target?.value
+                    : eOrValue;
+
+            return {
+                target: {
+                    id,
+                    value: { [id]: value }, // patch
+                }
+            };
+        },
+        [id]
+    );
+
+    const handleChange = useCallback(
+        (eOrValue) => entityCtx.onChange?.(wrapEvent(eOrValue)),
+        [entityCtx, wrapEvent]
+    );
+
+    const handleBlur = useCallback(
+        (eOrValue) => entityCtx.onBlur?.(wrapEvent(eOrValue)),
+        [entityCtx, wrapEvent]
+    );
+
+    const contextValue = useMemo(
+        () => ({
+            ...entityCtx,          // zachovej vše z parenta
+            onChange: handleChange,
+            onBlur: handleBlur,
+        }),
+        [entityCtx, handleChange, handleBlur]
+    );
+
+    return (
+        <GQLEntityContext.Provider value={contextValue}>
+            {children}
+        </GQLEntityContext.Provider>
+    );
+};