@flexacms/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Mercedes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @flexacms/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React provider and hooks for the [Flexa](https://github.com/flexacms) headless CMS.
+
+```bash
+npm install @flexacms/react
+```
+
+```tsx
+import { createClient, FlexaProvider, useEntries } from '@flexacms/react';
+
+const flexa = createClient({
+    url: import.meta.env.VITE_FLEXA_URL,
+    apiKey: import.meta.env.VITE_FLEXA_API_KEY,
+});
+
+export function App() {
+    return (
+        <FlexaProvider client={flexa}>
+            <Posts />
+        </FlexaProvider>
+    );
+}
+
+function Posts() {
+    const { data, error, isLoading, refetch } = useEntries('posts', {
+        status: 'published',
+    });
+
+    if (isLoading) return <p>Loading…</p>;
+    if (error) return <p>{error.message}</p>;
+
+    return (
+        <ul>
+            {data?.data.map((post) => (
+                <li key={post.id}>{post.title}</li>
+            ))}
+        </ul>
+    );
+}
+```
+
+`useEntry(entity, idOrSlug)` returns one entry (`null` when it does not exist) and waits while the identifier is `null` or `undefined`. Stale responses are cancelled when the arguments change.
+
+> These hooks run in the browser, so the API key is public. Use a **Read**-only key limited to the entities the site shows, or fetch on the server with [`@flexacms/next`](../next).
+
+## Typed hooks
+
+```ts
+import { createFlexaHooks } from '@flexacms/react';
+import type { FlexaSchema } from './flexa'; // npx @flexacms/cli generate
+
+export const { useEntries, useEntry } = createFlexaHooks<FlexaSchema>();
+```

package/dist/index.cjs

@@ -0,0 +1,123 @@
+'use client';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FlexaProvider: () => FlexaProvider,
+  createFlexaHooks: () => createFlexaHooks,
+  useEntries: () => useEntries,
+  useEntry: () => useEntry,
+  useFlexa: () => useFlexa
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+__reExport(index_exports, require("@flexacms/client"), module.exports);
+var FlexaContext = (0, import_react.createContext)(null);
+function FlexaProvider({
+  client,
+  children
+}) {
+  return (0, import_react.createElement)(FlexaContext.Provider, { value: client }, children);
+}
+function useFlexa() {
+  const client = (0, import_react.useContext)(FlexaContext);
+  if (!client) {
+    throw new Error("useFlexa() must be used inside a <FlexaProvider>.");
+  }
+  return client;
+}
+function useQuery(key, enabled, run) {
+  const [state, setState] = (0, import_react.useState)({
+    data: void 0,
+    error: void 0,
+    isLoading: enabled
+  });
+  const [version, setVersion] = (0, import_react.useState)(0);
+  const runRef = (0, import_react.useRef)(run);
+  runRef.current = run;
+  (0, import_react.useEffect)(() => {
+    if (!enabled) {
+      setState((current) => ({ ...current, isLoading: false }));
+      return;
+    }
+    const controller = new AbortController();
+    setState((current) => ({
+      ...current,
+      error: void 0,
+      isLoading: true
+    }));
+    runRef.current(controller.signal).then(
+      (data) => {
+        if (!controller.signal.aborted) {
+          setState({ data, error: void 0, isLoading: false });
+        }
+      },
+      (error) => {
+        if (!controller.signal.aborted) {
+          setState((current) => ({
+            ...current,
+            error: error instanceof Error ? error : new Error(String(error)),
+            isLoading: false
+          }));
+        }
+      }
+    );
+    return () => controller.abort();
+  }, [key, enabled, version]);
+  const refetch = (0, import_react.useCallback)(() => setVersion((current) => current + 1), []);
+  return { ...state, refetch };
+}
+function createFlexaHooks() {
+  return {
+    useFlexa: () => useFlexa(),
+    useEntries: (entity, params = {}) => {
+      const client = useFlexa();
+      return useQuery(
+        `${entity}:${JSON.stringify(params)}`,
+        true,
+        (signal) => client.entity(entity).list(params, { signal })
+      );
+    },
+    useEntry: (entity, idOrSlug, params = {}) => {
+      const client = useFlexa();
+      const enabled = idOrSlug !== null && idOrSlug !== void 0 && idOrSlug !== "";
+      return useQuery(
+        `${entity}:${String(idOrSlug)}:${JSON.stringify(params)}`,
+        enabled,
+        (signal) => client.entity(entity).find(idOrSlug, params, { signal })
+      );
+    }
+  };
+}
+var untypedHooks = createFlexaHooks();
+var useEntries = untypedHooks.useEntries;
+var useEntry = untypedHooks.useEntry;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlexaProvider,
+  createFlexaHooks,
+  useEntries,
+  useEntry,
+  useFlexa,
+  ...require("@flexacms/client")
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n    ContentSchema,\n    Entry,\n    EntryValues,\n    FlexaClient,\n    GetParams,\n    ListParams,\n    Paginated,\n} from '@flexacms/client';\nimport {\n    createContext,\n    createElement,\n    useCallback,\n    useContext,\n    useEffect,\n    useRef,\n    useState,\n} from 'react';\nimport type { ReactNode } from 'react';\n\nexport * from '@flexacms/client';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst FlexaContext = createContext<FlexaClient<any> | null>(null);\n\n/**\n * Makes a Flexa client available to the hooks below.\n *\n * The client runs in the browser, so its API key is public: use a key with only\n * the Read ability, limited to the entities the site shows. Prefer fetching on\n * the server (e.g. `@flexacms/next`) when you can.\n */\nexport function FlexaProvider<TSchema extends object = ContentSchema>({\n    client,\n    children,\n}: {\n    client: FlexaClient<TSchema>;\n    children?: ReactNode;\n}) {\n    return createElement(FlexaContext.Provider, { value: client }, children);\n}\n\n/** The client given to the nearest `FlexaProvider`. */\nexport function useFlexa<\n    TSchema extends object = ContentSchema,\n>(): FlexaClient<TSchema> {\n    const client = useContext(FlexaContext);\n\n    if (!client) {\n        throw new Error('useFlexa() must be used inside a <FlexaProvider>.');\n    }\n\n    return client as FlexaClient<TSchema>;\n}\n\nexport interface QueryState<T> {\n    data: T | undefined;\n    error: Error | undefined;\n    isLoading: boolean;\n    /** Fetch again, keeping the current data until the new response arrives. */\n    refetch: () => void;\n}\n\n/**\n * Run an async request on mount and whenever `key` changes, cancelling stale\n * requests so a slow response never overwrites a newer one.\n */\nfunction useQuery<T>(\n    key: string,\n    enabled: boolean,\n    run: (signal: AbortSignal) => Promise<T>,\n): QueryState<T> {\n    const [state, setState] = useState<Omit<QueryState<T>, 'refetch'>>({\n        data: undefined,\n        error: undefined,\n        isLoading: enabled,\n    });\n    const [version, setVersion] = useState(0);\n    const runRef = useRef(run);\n\n    runRef.current = run;\n\n    useEffect(() => {\n        if (!enabled) {\n            setState((current) => ({ ...current, isLoading: false }));\n\n            return;\n        }\n\n        const controller = new AbortController();\n\n        setState((current) => ({\n            ...current,\n            error: undefined,\n            isLoading: true,\n        }));\n\n        runRef.current(controller.signal).then(\n            (data) => {\n                if (!controller.signal.aborted) {\n                    setState({ data, error: undefined, isLoading: false });\n                }\n            },\n            (error: unknown) => {\n                if (!controller.signal.aborted) {\n                    setState((current) => ({\n                        ...current,\n                        error:\n                            error instanceof Error\n                                ? error\n                                : new Error(String(error)),\n                        isLoading: false,\n                    }));\n                }\n            },\n        );\n\n        return () => controller.abort();\n    }, [key, enabled, version]);\n\n    const refetch = useCallback(() => setVersion((current) => current + 1), []);\n\n    return { ...state, refetch };\n}\n\ntype ValuesFor<\n    TSchema extends object,\n    TEntity extends string,\n> = TEntity extends keyof TSchema\n    ? TSchema[TEntity] extends object\n        ? TSchema[TEntity]\n        : EntryValues\n    : EntryValues;\n\nexport interface FlexaHooks<TSchema extends object> {\n    useFlexa: () => FlexaClient<TSchema>;\n    /** A page of entries of an entity. */\n    useEntries: <\n        TEntity extends Extract<keyof TSchema, string> | (string & {}),\n    >(\n        entity: TEntity,\n        params?: ListParams,\n    ) => QueryState<Paginated<Entry<ValuesFor<TSchema, TEntity>>>>;\n    /**\n     * One entry by id or slug. `data` is `null` when it does not exist; pass\n     * `null`/`undefined` as the identifier to wait (e.g. until a route param is known).\n     */\n    useEntry: <TEntity extends Extract<keyof TSchema, string> | (string & {})>(\n        entity: TEntity,\n        idOrSlug: number | string | null | undefined,\n        params?: GetParams,\n    ) => QueryState<Entry<ValuesFor<TSchema, TEntity>> | null>;\n}\n\n/**\n * Hooks typed with your generated schema:\n *\n *     export const { useEntries, useEntry } = createFlexaHooks<FlexaSchema>();\n */\nexport function createFlexaHooks<\n    TSchema extends object = ContentSchema,\n>(): FlexaHooks<TSchema> {\n    return {\n        useFlexa: () => useFlexa<TSchema>(),\n        useEntries: (entity, params = {}) => {\n            const client = useFlexa<TSchema>();\n\n            return useQuery(\n                `${entity}:${JSON.stringify(params)}`,\n                true,\n                (signal) => client.entity(entity).list(params, { signal }),\n            ) as never;\n        },\n        useEntry: (entity, idOrSlug, params = {}) => {\n            const client = useFlexa<TSchema>();\n            const enabled =\n                idOrSlug !== null && idOrSlug !== undefined && idOrSlug !== '';\n\n            return useQuery(\n                `${entity}:${String(idOrSlug)}:${JSON.stringify(params)}`,\n                enabled,\n                (signal) =>\n                    client\n                        .entity(entity)\n                        .find(idOrSlug as number | string, params, { signal }),\n            ) as never;\n        },\n    };\n}\n\nconst untypedHooks = createFlexaHooks();\n\n/** A page of entries of an entity. Use `createFlexaHooks<FlexaSchema>()` for typed values. */\nexport const useEntries = untypedHooks.useEntries;\n\n/** One entry by id or slug (`null` when missing). Use `createFlexaHooks<FlexaSchema>()` for typed values. */\nexport const useEntry = untypedHooks.useEntry;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,mBAQO;AAGP,0BAAc,6BApBd;AAuBA,IAAM,mBAAe,4BAAuC,IAAI;AASzD,SAAS,cAAsD;AAAA,EAClE;AAAA,EACA;AACJ,GAGG;AACC,aAAO,4BAAc,aAAa,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC3E;AAGO,SAAS,WAEU;AACtB,QAAM,aAAS,yBAAW,YAAY;AAEtC,MAAI,CAAC,QAAQ;AACT,UAAM,IAAI,MAAM,mDAAmD;AAAA,EACvE;AAEA,SAAO;AACX;AAcA,SAAS,SACL,KACA,SACA,KACa;AACb,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAAyC;AAAA,IAC/D,MAAM;AAAA,IACN,OAAO;AAAA,IACP,WAAW;AAAA,EACf,CAAC;AACD,QAAM,CAAC,SAAS,UAAU,QAAI,uBAAS,CAAC;AACxC,QAAM,aAAS,qBAAO,GAAG;AAEzB,SAAO,UAAU;AAEjB,8BAAU,MAAM;AACZ,QAAI,CAAC,SAAS;AACV,eAAS,CAAC,aAAa,EAAE,GAAG,SAAS,WAAW,MAAM,EAAE;AAExD;AAAA,IACJ;AAEA,UAAM,aAAa,IAAI,gBAAgB;AAEvC,aAAS,CAAC,aAAa;AAAA,MACnB,GAAG;AAAA,MACH,OAAO;AAAA,MACP,WAAW;AAAA,IACf,EAAE;AAEF,WAAO,QAAQ,WAAW,MAAM,EAAE;AAAA,MAC9B,CAAC,SAAS;AACN,YAAI,CAAC,WAAW,OAAO,SAAS;AAC5B,mBAAS,EAAE,MAAM,OAAO,QAAW,WAAW,MAAM,CAAC;AAAA,QACzD;AAAA,MACJ;AAAA,MACA,CAAC,UAAmB;AAChB,YAAI,CAAC,WAAW,OAAO,SAAS;AAC5B,mBAAS,CAAC,aAAa;AAAA,YACnB,GAAG;AAAA,YACH,OACI,iBAAiB,QACX,QACA,IAAI,MAAM,OAAO,KAAK,CAAC;AAAA,YACjC,WAAW;AAAA,UACf,EAAE;AAAA,QACN;AAAA,MACJ;AAAA,IACJ;AAEA,WAAO,MAAM,WAAW,MAAM;AAAA,EAClC,GAAG,CAAC,KAAK,SAAS,OAAO,CAAC;AAE1B,QAAM,cAAU,0BAAY,MAAM,WAAW,CAAC,YAAY,UAAU,CAAC,GAAG,CAAC,CAAC;AAE1E,SAAO,EAAE,GAAG,OAAO,QAAQ;AAC/B;AAoCO,SAAS,mBAES;AACrB,SAAO;AAAA,IACH,UAAU,MAAM,SAAkB;AAAA,IAClC,YAAY,CAAC,QAAQ,SAAS,CAAC,MAAM;AACjC,YAAM,SAAS,SAAkB;AAEjC,aAAO;AAAA,QACH,GAAG,MAAM,IAAI,KAAK,UAAU,MAAM,CAAC;AAAA,QACnC;AAAA,QACA,CAAC,WAAW,OAAO,OAAO,MAAM,EAAE,KAAK,QAAQ,EAAE,OAAO,CAAC;AAAA,MAC7D;AAAA,IACJ;AAAA,IACA,UAAU,CAAC,QAAQ,UAAU,SAAS,CAAC,MAAM;AACzC,YAAM,SAAS,SAAkB;AACjC,YAAM,UACF,aAAa,QAAQ,aAAa,UAAa,aAAa;AAEhE,aAAO;AAAA,QACH,GAAG,MAAM,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,UAAU,MAAM,CAAC;AAAA,QACvD;AAAA,QACA,CAAC,WACG,OACK,OAAO,MAAM,EACb,KAAK,UAA6B,QAAQ,EAAE,OAAO,CAAC;AAAA,MACjE;AAAA,IACJ;AAAA,EACJ;AACJ;AAEA,IAAM,eAAe,iBAAiB;AAG/B,IAAM,aAAa,aAAa;AAGhC,IAAM,WAAW,aAAa;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { FlexaClient, ListParams, Paginated, Entry, EntryValues, GetParams, ContentSchema } from '@flexacms/client';
+export * from '@flexacms/client';
+
+/**
+ * Makes a Flexa client available to the hooks below.
+ *
+ * The client runs in the browser, so its API key is public: use a key with only
+ * the Read ability, limited to the entities the site shows. Prefer fetching on
+ * the server (e.g. `@flexacms/next`) when you can.
+ */
+declare function FlexaProvider<TSchema extends object = ContentSchema>({ client, children, }: {
+    client: FlexaClient<TSchema>;
+    children?: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<FlexaClient<any> | null>>;
+/** The client given to the nearest `FlexaProvider`. */
+declare function useFlexa<TSchema extends object = ContentSchema>(): FlexaClient<TSchema>;
+interface QueryState<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+    /** Fetch again, keeping the current data until the new response arrives. */
+    refetch: () => void;
+}
+type ValuesFor<TSchema extends object, TEntity extends string> = TEntity extends keyof TSchema ? TSchema[TEntity] extends object ? TSchema[TEntity] : EntryValues : EntryValues;
+interface FlexaHooks<TSchema extends object> {
+    useFlexa: () => FlexaClient<TSchema>;
+    /** A page of entries of an entity. */
+    useEntries: <TEntity extends Extract<keyof TSchema, string> | (string & {})>(entity: TEntity, params?: ListParams) => QueryState<Paginated<Entry<ValuesFor<TSchema, TEntity>>>>;
+    /**
+     * One entry by id or slug. `data` is `null` when it does not exist; pass
+     * `null`/`undefined` as the identifier to wait (e.g. until a route param is known).
+     */
+    useEntry: <TEntity extends Extract<keyof TSchema, string> | (string & {})>(entity: TEntity, idOrSlug: number | string | null | undefined, params?: GetParams) => QueryState<Entry<ValuesFor<TSchema, TEntity>> | null>;
+}
+/**
+ * Hooks typed with your generated schema:
+ *
+ *     export const { useEntries, useEntry } = createFlexaHooks<FlexaSchema>();
+ */
+declare function createFlexaHooks<TSchema extends object = ContentSchema>(): FlexaHooks<TSchema>;
+/** A page of entries of an entity. Use `createFlexaHooks<FlexaSchema>()` for typed values. */
+declare const useEntries: <TEntity extends string | (string & {})>(entity: TEntity, params?: ListParams) => QueryState<Paginated<Entry<ValuesFor<ContentSchema, TEntity>>>>;
+/** One entry by id or slug (`null` when missing). Use `createFlexaHooks<FlexaSchema>()` for typed values. */
+declare const useEntry: <TEntity extends string | (string & {})>(entity: TEntity, idOrSlug: number | string | null | undefined, params?: GetParams) => QueryState<Entry<ValuesFor<ContentSchema, TEntity>> | null>;
+
+export { type FlexaHooks, FlexaProvider, type QueryState, createFlexaHooks, useEntries, useEntry, useFlexa };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { FlexaClient, ListParams, Paginated, Entry, EntryValues, GetParams, ContentSchema } from '@flexacms/client';
+export * from '@flexacms/client';
+
+/**
+ * Makes a Flexa client available to the hooks below.
+ *
+ * The client runs in the browser, so its API key is public: use a key with only
+ * the Read ability, limited to the entities the site shows. Prefer fetching on
+ * the server (e.g. `@flexacms/next`) when you can.
+ */
+declare function FlexaProvider<TSchema extends object = ContentSchema>({ client, children, }: {
+    client: FlexaClient<TSchema>;
+    children?: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<FlexaClient<any> | null>>;
+/** The client given to the nearest `FlexaProvider`. */
+declare function useFlexa<TSchema extends object = ContentSchema>(): FlexaClient<TSchema>;
+interface QueryState<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+    /** Fetch again, keeping the current data until the new response arrives. */
+    refetch: () => void;
+}
+type ValuesFor<TSchema extends object, TEntity extends string> = TEntity extends keyof TSchema ? TSchema[TEntity] extends object ? TSchema[TEntity] : EntryValues : EntryValues;
+interface FlexaHooks<TSchema extends object> {
+    useFlexa: () => FlexaClient<TSchema>;
+    /** A page of entries of an entity. */
+    useEntries: <TEntity extends Extract<keyof TSchema, string> | (string & {})>(entity: TEntity, params?: ListParams) => QueryState<Paginated<Entry<ValuesFor<TSchema, TEntity>>>>;
+    /**
+     * One entry by id or slug. `data` is `null` when it does not exist; pass
+     * `null`/`undefined` as the identifier to wait (e.g. until a route param is known).
+     */
+    useEntry: <TEntity extends Extract<keyof TSchema, string> | (string & {})>(entity: TEntity, idOrSlug: number | string | null | undefined, params?: GetParams) => QueryState<Entry<ValuesFor<TSchema, TEntity>> | null>;
+}
+/**
+ * Hooks typed with your generated schema:
+ *
+ *     export const { useEntries, useEntry } = createFlexaHooks<FlexaSchema>();
+ */
+declare function createFlexaHooks<TSchema extends object = ContentSchema>(): FlexaHooks<TSchema>;
+/** A page of entries of an entity. Use `createFlexaHooks<FlexaSchema>()` for typed values. */
+declare const useEntries: <TEntity extends string | (string & {})>(entity: TEntity, params?: ListParams) => QueryState<Paginated<Entry<ValuesFor<ContentSchema, TEntity>>>>;
+/** One entry by id or slug (`null` when missing). Use `createFlexaHooks<FlexaSchema>()` for typed values. */
+declare const useEntry: <TEntity extends string | (string & {})>(entity: TEntity, idOrSlug: number | string | null | undefined, params?: GetParams) => QueryState<Entry<ValuesFor<ContentSchema, TEntity>> | null>;
+
+export { type FlexaHooks, FlexaProvider, type QueryState, createFlexaHooks, useEntries, useEntry, useFlexa };

package/dist/index.js

@@ -0,0 +1,101 @@
+'use client';
+
+// src/index.ts
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+export * from "@flexacms/client";
+var FlexaContext = createContext(null);
+function FlexaProvider({
+  client,
+  children
+}) {
+  return createElement(FlexaContext.Provider, { value: client }, children);
+}
+function useFlexa() {
+  const client = useContext(FlexaContext);
+  if (!client) {
+    throw new Error("useFlexa() must be used inside a <FlexaProvider>.");
+  }
+  return client;
+}
+function useQuery(key, enabled, run) {
+  const [state, setState] = useState({
+    data: void 0,
+    error: void 0,
+    isLoading: enabled
+  });
+  const [version, setVersion] = useState(0);
+  const runRef = useRef(run);
+  runRef.current = run;
+  useEffect(() => {
+    if (!enabled) {
+      setState((current) => ({ ...current, isLoading: false }));
+      return;
+    }
+    const controller = new AbortController();
+    setState((current) => ({
+      ...current,
+      error: void 0,
+      isLoading: true
+    }));
+    runRef.current(controller.signal).then(
+      (data) => {
+        if (!controller.signal.aborted) {
+          setState({ data, error: void 0, isLoading: false });
+        }
+      },
+      (error) => {
+        if (!controller.signal.aborted) {
+          setState((current) => ({
+            ...current,
+            error: error instanceof Error ? error : new Error(String(error)),
+            isLoading: false
+          }));
+        }
+      }
+    );
+    return () => controller.abort();
+  }, [key, enabled, version]);
+  const refetch = useCallback(() => setVersion((current) => current + 1), []);
+  return { ...state, refetch };
+}
+function createFlexaHooks() {
+  return {
+    useFlexa: () => useFlexa(),
+    useEntries: (entity, params = {}) => {
+      const client = useFlexa();
+      return useQuery(
+        `${entity}:${JSON.stringify(params)}`,
+        true,
+        (signal) => client.entity(entity).list(params, { signal })
+      );
+    },
+    useEntry: (entity, idOrSlug, params = {}) => {
+      const client = useFlexa();
+      const enabled = idOrSlug !== null && idOrSlug !== void 0 && idOrSlug !== "";
+      return useQuery(
+        `${entity}:${String(idOrSlug)}:${JSON.stringify(params)}`,
+        enabled,
+        (signal) => client.entity(entity).find(idOrSlug, params, { signal })
+      );
+    }
+  };
+}
+var untypedHooks = createFlexaHooks();
+var useEntries = untypedHooks.useEntries;
+var useEntry = untypedHooks.useEntry;
+export {
+  FlexaProvider,
+  createFlexaHooks,
+  useEntries,
+  useEntry,
+  useFlexa
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n    ContentSchema,\n    Entry,\n    EntryValues,\n    FlexaClient,\n    GetParams,\n    ListParams,\n    Paginated,\n} from '@flexacms/client';\nimport {\n    createContext,\n    createElement,\n    useCallback,\n    useContext,\n    useEffect,\n    useRef,\n    useState,\n} from 'react';\nimport type { ReactNode } from 'react';\n\nexport * from '@flexacms/client';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst FlexaContext = createContext<FlexaClient<any> | null>(null);\n\n/**\n * Makes a Flexa client available to the hooks below.\n *\n * The client runs in the browser, so its API key is public: use a key with only\n * the Read ability, limited to the entities the site shows. Prefer fetching on\n * the server (e.g. `@flexacms/next`) when you can.\n */\nexport function FlexaProvider<TSchema extends object = ContentSchema>({\n    client,\n    children,\n}: {\n    client: FlexaClient<TSchema>;\n    children?: ReactNode;\n}) {\n    return createElement(FlexaContext.Provider, { value: client }, children);\n}\n\n/** The client given to the nearest `FlexaProvider`. */\nexport function useFlexa<\n    TSchema extends object = ContentSchema,\n>(): FlexaClient<TSchema> {\n    const client = useContext(FlexaContext);\n\n    if (!client) {\n        throw new Error('useFlexa() must be used inside a <FlexaProvider>.');\n    }\n\n    return client as FlexaClient<TSchema>;\n}\n\nexport interface QueryState<T> {\n    data: T | undefined;\n    error: Error | undefined;\n    isLoading: boolean;\n    /** Fetch again, keeping the current data until the new response arrives. */\n    refetch: () => void;\n}\n\n/**\n * Run an async request on mount and whenever `key` changes, cancelling stale\n * requests so a slow response never overwrites a newer one.\n */\nfunction useQuery<T>(\n    key: string,\n    enabled: boolean,\n    run: (signal: AbortSignal) => Promise<T>,\n): QueryState<T> {\n    const [state, setState] = useState<Omit<QueryState<T>, 'refetch'>>({\n        data: undefined,\n        error: undefined,\n        isLoading: enabled,\n    });\n    const [version, setVersion] = useState(0);\n    const runRef = useRef(run);\n\n    runRef.current = run;\n\n    useEffect(() => {\n        if (!enabled) {\n            setState((current) => ({ ...current, isLoading: false }));\n\n            return;\n        }\n\n        const controller = new AbortController();\n\n        setState((current) => ({\n            ...current,\n            error: undefined,\n            isLoading: true,\n        }));\n\n        runRef.current(controller.signal).then(\n            (data) => {\n                if (!controller.signal.aborted) {\n                    setState({ data, error: undefined, isLoading: false });\n                }\n            },\n            (error: unknown) => {\n                if (!controller.signal.aborted) {\n                    setState((current) => ({\n                        ...current,\n                        error:\n                            error instanceof Error\n                                ? error\n                                : new Error(String(error)),\n                        isLoading: false,\n                    }));\n                }\n            },\n        );\n\n        return () => controller.abort();\n    }, [key, enabled, version]);\n\n    const refetch = useCallback(() => setVersion((current) => current + 1), []);\n\n    return { ...state, refetch };\n}\n\ntype ValuesFor<\n    TSchema extends object,\n    TEntity extends string,\n> = TEntity extends keyof TSchema\n    ? TSchema[TEntity] extends object\n        ? TSchema[TEntity]\n        : EntryValues\n    : EntryValues;\n\nexport interface FlexaHooks<TSchema extends object> {\n    useFlexa: () => FlexaClient<TSchema>;\n    /** A page of entries of an entity. */\n    useEntries: <\n        TEntity extends Extract<keyof TSchema, string> | (string & {}),\n    >(\n        entity: TEntity,\n        params?: ListParams,\n    ) => QueryState<Paginated<Entry<ValuesFor<TSchema, TEntity>>>>;\n    /**\n     * One entry by id or slug. `data` is `null` when it does not exist; pass\n     * `null`/`undefined` as the identifier to wait (e.g. until a route param is known).\n     */\n    useEntry: <TEntity extends Extract<keyof TSchema, string> | (string & {})>(\n        entity: TEntity,\n        idOrSlug: number | string | null | undefined,\n        params?: GetParams,\n    ) => QueryState<Entry<ValuesFor<TSchema, TEntity>> | null>;\n}\n\n/**\n * Hooks typed with your generated schema:\n *\n *     export const { useEntries, useEntry } = createFlexaHooks<FlexaSchema>();\n */\nexport function createFlexaHooks<\n    TSchema extends object = ContentSchema,\n>(): FlexaHooks<TSchema> {\n    return {\n        useFlexa: () => useFlexa<TSchema>(),\n        useEntries: (entity, params = {}) => {\n            const client = useFlexa<TSchema>();\n\n            return useQuery(\n                `${entity}:${JSON.stringify(params)}`,\n                true,\n                (signal) => client.entity(entity).list(params, { signal }),\n            ) as never;\n        },\n        useEntry: (entity, idOrSlug, params = {}) => {\n            const client = useFlexa<TSchema>();\n            const enabled =\n                idOrSlug !== null && idOrSlug !== undefined && idOrSlug !== '';\n\n            return useQuery(\n                `${entity}:${String(idOrSlug)}:${JSON.stringify(params)}`,\n                enabled,\n                (signal) =>\n                    client\n                        .entity(entity)\n                        .find(idOrSlug as number | string, params, { signal }),\n            ) as never;\n        },\n    };\n}\n\nconst untypedHooks = createFlexaHooks();\n\n/** A page of entries of an entity. Use `createFlexaHooks<FlexaSchema>()` for typed values. */\nexport const useEntries = untypedHooks.useEntries;\n\n/** One entry by id or slug (`null` when missing). Use `createFlexaHooks<FlexaSchema>()` for typed values. */\nexport const useEntry = untypedHooks.useEntry;\n"],"mappings":";;;AASA;AAAA,EACI;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACG;AAGP,cAAc;AAGd,IAAM,eAAe,cAAuC,IAAI;AASzD,SAAS,cAAsD;AAAA,EAClE;AAAA,EACA;AACJ,GAGG;AACC,SAAO,cAAc,aAAa,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC3E;AAGO,SAAS,WAEU;AACtB,QAAM,SAAS,WAAW,YAAY;AAEtC,MAAI,CAAC,QAAQ;AACT,UAAM,IAAI,MAAM,mDAAmD;AAAA,EACvE;AAEA,SAAO;AACX;AAcA,SAAS,SACL,KACA,SACA,KACa;AACb,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAyC;AAAA,IAC/D,MAAM;AAAA,IACN,OAAO;AAAA,IACP,WAAW;AAAA,EACf,CAAC;AACD,QAAM,CAAC,SAAS,UAAU,IAAI,SAAS,CAAC;AACxC,QAAM,SAAS,OAAO,GAAG;AAEzB,SAAO,UAAU;AAEjB,YAAU,MAAM;AACZ,QAAI,CAAC,SAAS;AACV,eAAS,CAAC,aAAa,EAAE,GAAG,SAAS,WAAW,MAAM,EAAE;AAExD;AAAA,IACJ;AAEA,UAAM,aAAa,IAAI,gBAAgB;AAEvC,aAAS,CAAC,aAAa;AAAA,MACnB,GAAG;AAAA,MACH,OAAO;AAAA,MACP,WAAW;AAAA,IACf,EAAE;AAEF,WAAO,QAAQ,WAAW,MAAM,EAAE;AAAA,MAC9B,CAAC,SAAS;AACN,YAAI,CAAC,WAAW,OAAO,SAAS;AAC5B,mBAAS,EAAE,MAAM,OAAO,QAAW,WAAW,MAAM,CAAC;AAAA,QACzD;AAAA,MACJ;AAAA,MACA,CAAC,UAAmB;AAChB,YAAI,CAAC,WAAW,OAAO,SAAS;AAC5B,mBAAS,CAAC,aAAa;AAAA,YACnB,GAAG;AAAA,YACH,OACI,iBAAiB,QACX,QACA,IAAI,MAAM,OAAO,KAAK,CAAC;AAAA,YACjC,WAAW;AAAA,UACf,EAAE;AAAA,QACN;AAAA,MACJ;AAAA,IACJ;AAEA,WAAO,MAAM,WAAW,MAAM;AAAA,EAClC,GAAG,CAAC,KAAK,SAAS,OAAO,CAAC;AAE1B,QAAM,UAAU,YAAY,MAAM,WAAW,CAAC,YAAY,UAAU,CAAC,GAAG,CAAC,CAAC;AAE1E,SAAO,EAAE,GAAG,OAAO,QAAQ;AAC/B;AAoCO,SAAS,mBAES;AACrB,SAAO;AAAA,IACH,UAAU,MAAM,SAAkB;AAAA,IAClC,YAAY,CAAC,QAAQ,SAAS,CAAC,MAAM;AACjC,YAAM,SAAS,SAAkB;AAEjC,aAAO;AAAA,QACH,GAAG,MAAM,IAAI,KAAK,UAAU,MAAM,CAAC;AAAA,QACnC;AAAA,QACA,CAAC,WAAW,OAAO,OAAO,MAAM,EAAE,KAAK,QAAQ,EAAE,OAAO,CAAC;AAAA,MAC7D;AAAA,IACJ;AAAA,IACA,UAAU,CAAC,QAAQ,UAAU,SAAS,CAAC,MAAM;AACzC,YAAM,SAAS,SAAkB;AACjC,YAAM,UACF,aAAa,QAAQ,aAAa,UAAa,aAAa;AAEhE,aAAO;AAAA,QACH,GAAG,MAAM,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,UAAU,MAAM,CAAC;AAAA,QACvD;AAAA,QACA,CAAC,WACG,OACK,OAAO,MAAM,EACb,KAAK,UAA6B,QAAQ,EAAE,OAAO,CAAC;AAAA,MACjE;AAAA,IACJ;AAAA,EACJ;AACJ;AAEA,IAAM,eAAe,iBAAiB;AAG/B,IAAM,aAAa,aAAa;AAGhC,IAAM,WAAW,aAAa;","names":[]}

package/package.json

@@ -1,6 +1,64 @@
 {
-  "name": "@flexacms/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@flexacms/react",
+    "version": "0.1.0",
+    "description": "React provider and hooks for the Flexa headless CMS.",
+    "keywords": [
+        "cms",
+        "flexa",
+        "headless",
+        "hooks",
+        "react"
+    ],
+    "homepage": "https://github.com/flexacms/sdk/tree/main/packages/react#readme",
+    "bugs": {
+        "url": "https://github.com/flexacms/sdk/issues"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/flexacms/sdk.git",
+        "directory": "packages/react"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsup",
+        "typecheck": "tsc -p tsconfig.json"
+    },
+    "dependencies": {
+        "@flexacms/client": "^0.1.0"
+    },
+    "devDependencies": {
+        "@testing-library/react": "^16.3.3",
+        "@types/react": "^19.3.0",
+        "jsdom": "^30.1.2",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0"
+    },
+    "peerDependencies": {
+        "react": "^18.2.0 || ^19.0.0"
+    }
+}