jcicl 1.0.60 → 1.0.61

package/DataPage/DataPage.d.ts

@@ -0,0 +1,24 @@
+import { DataPageControls, DataPageResult } from './useDataPage';
+import { WithLoadingProps } from '../WithLoading/WithLoading';
+export interface DataPageProps<T> {
+    /** Async function that fetches data. Throw for fatal error. Return withWarnings() for partial success. */
+    fetchFn: () => Promise<T | DataPageResult<T>>;
+    /** useEffect dependency array. Default: [] (fetch once on mount). */
+    deps?: unknown[];
+    /** Render function for happy path. Receives data + controls. Read-only pages can ignore the 2nd arg. */
+    children: (data: T, controls: DataPageControls<T>) => React.ReactNode;
+    /** Shown on empty data. String → centered <p>. ReactNode → rendered directly. Omit for interactive empty. */
+    emptyState?: React.ReactNode | string;
+    /** Shown on fatal error. String → centered red <p>. Defaults to the caught error message. */
+    errorState?: React.ReactNode | string;
+    /** Data-dependent guards. Each receives data, returns ReactNode to short-circuit or null to continue. */
+    guards?: ((data: T) => React.ReactNode | null)[];
+    /** Determines if data is "empty". Default: array length === 0 or nullish. */
+    isEmpty?: (data: T) => boolean;
+    /** Props forwarded to the internal WithLoading wrapper (e.g. size, style). */
+    loadingProps?: Omit<WithLoadingProps, 'loading' | 'children'>;
+    /** Custom warning banner renderer. Default: orange centered <p> per warning. Pass null to suppress. */
+    renderWarnings?: ((warnings: string[]) => React.ReactNode) | null;
+}
+declare function DataPage<T>({ fetchFn, deps, children, emptyState, errorState, guards, isEmpty, loadingProps, renderWarnings, }: DataPageProps<T>): import("react/jsx-runtime").JSX.Element;
+export default DataPage;

package/DataPage/DataPage.js

@@ -0,0 +1,34 @@
+import { jsx as e, Fragment as i, jsxs as A } from "react/jsx-runtime";
+import B, { defaultIsEmpty as P } from "./useDataPage.js";
+import k from "../WithLoading/WithLoading.js";
+const c = (n, t) => typeof n == "string" ? /* @__PURE__ */ e("p", { style: { textAlign: "center", color: t }, children: n }) : /* @__PURE__ */ e(i, { children: n }), v = (n) => n.map((t, o) => /* @__PURE__ */ e("p", { style: { textAlign: "center", color: "darkorange" }, children: t }, o));
+function L({
+  fetchFn: n,
+  deps: t,
+  children: o,
+  emptyState: s,
+  errorState: d,
+  guards: u,
+  isEmpty: m = P,
+  loadingProps: p,
+  renderWarnings: f
+}) {
+  const { data: r, loading: l, error: g, warnings: a, setData: x, refetch: y } = B({ fetchFn: n, deps: t }), D = { setData: x, refetch: y, warnings: a };
+  if (!l && g)
+    return /* @__PURE__ */ e(i, { children: c(d || g, "red") });
+  if (!l && r !== null && m(r) && s !== void 0)
+    return /* @__PURE__ */ e(i, { children: c(s) });
+  if (!l && r !== null && u)
+    for (const w of u) {
+      const h = w(r);
+      if (h !== null) return /* @__PURE__ */ e(i, { children: h });
+    }
+  const j = a.length > 0 && f !== null ? (f ?? v)(a) : null;
+  return /* @__PURE__ */ A(k, { loading: l, ...p, children: [
+    j,
+    r !== null ? o(r, D) : null
+  ] });
+}
+export {
+  L as default
+};

package/DataPage/index.d.ts

@@ -0,0 +1,2 @@
+export { default, type DataPageProps } from './DataPage';
+export { default as useDataPage, withWarnings, type UseDataPageOptions, type UseDataPageReturn, type DataPageControls, type DataPageResult, } from './useDataPage';

package/DataPage/index.js

@@ -0,0 +1,7 @@
+import { default as t } from "./DataPage.js";
+import { default as f, withWarnings as o } from "./useDataPage.js";
+export {
+  t as default,
+  f as useDataPage,
+  o as withWarnings
+};

package/DataPage/useDataPage.d.ts

@@ -0,0 +1,33 @@
+declare const DATA_PAGE_RESULT: unique symbol;
+export interface DataPageResult<T> {
+    [DATA_PAGE_RESULT]: true;
+    data: T;
+    warnings: string[];
+}
+/** Wrap a fetchFn return value to signal partial success with warnings. */
+export declare function withWarnings<T>(data: T, warnings: string[]): DataPageResult<T>;
+export interface DataPageControls<T> {
+    /** Update local data without re-fetching. For optimistic CRUD (add/edit/delete). */
+    setData: (updater: (prev: T) => T) => void;
+    /** Re-run fetchFn from scratch (resets to loading state). */
+    refetch: () => void;
+    /** Warnings from partial success (empty array if none). */
+    warnings: string[];
+}
+export interface UseDataPageOptions<T> {
+    /** Async function that fetches data. Throw for fatal error. Return withWarnings() for partial success. */
+    fetchFn: () => Promise<T | DataPageResult<T>>;
+    /** useEffect dependency array. Default: [] (fetch once on mount). */
+    deps?: unknown[];
+}
+export interface UseDataPageReturn<T> {
+    data: T | null;
+    loading: boolean;
+    error: string | null;
+    warnings: string[];
+    setData: (updater: (prev: T) => T) => void;
+    refetch: () => void;
+}
+export declare const defaultIsEmpty: <T>(data: T) => boolean;
+declare function useDataPage<T>({ fetchFn, deps }: UseDataPageOptions<T>): UseDataPageReturn<T>;
+export default useDataPage;

package/DataPage/useDataPage.js

@@ -0,0 +1,38 @@
+import { useState as n, useRef as R, useEffect as b, useCallback as d } from "react";
+const g = Symbol("DataPageResult");
+function S(e, a) {
+  return { [g]: !0, data: e, warnings: a };
+}
+const x = (e) => e == null ? !0 : Array.isArray(e) ? e.length === 0 : !1;
+function F({ fetchFn: e, deps: a = [] }) {
+  const [y, c] = n(null), [h, u] = n(!0), [w, o] = n(null), [A, l] = n([]), [E, m] = n(0), f = R(e);
+  f.current = e, b(() => {
+    let t = !1;
+    return u(!0), o(null), l([]), (async () => {
+      try {
+        const r = await f.current();
+        if (t) return;
+        if (r && typeof r == "object" && g in r) {
+          const i = r;
+          c(i.data), l(i.warnings);
+        } else
+          c(r);
+      } catch (r) {
+        t || o(r instanceof Error ? r.message : "An unexpected error occurred");
+      } finally {
+        t || u(!1);
+      }
+    })(), () => {
+      t = !0;
+    };
+  }, [...a, E]);
+  const p = d((t) => {
+    c((s) => s !== null ? t(s) : s);
+  }, []), D = d(() => m((t) => t + 1), []);
+  return { data: y, loading: h, error: w, warnings: A, setData: p, refetch: D };
+}
+export {
+  F as default,
+  x as defaultIsEmpty,
+  S as withWarnings
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jcicl",
   "private": false,
-  "version": "1.0.60",
+  "version": "1.0.61",
   "description": "Component library for the websites of Johnson County Iowa",
   "license": "MIT",
   "homepage": "https://devops.jc.net/JCIT/Business%20Solutions%20Delivery/_git/JCComponentLibrary?path=%2FREADME.md&version=GBmaster",