@iris-ui-kit/react 0.1.0

package/dist/admin.d.ts

@@ -0,0 +1,183 @@
+import * as React from 'react';
+import { NavNode, TabsNav, TabItem } from '@iris-ui-kit/core';
+export { NavNode, TabItem, TabsNav, TabsNavConfig, TabsNavState, createTabsNav, filterNavByAccess, findNavNode, findNavPath, firstLeaf, flattenNav, isBranch, isClosable, nodeAllowsRoles, visibleNav } from '@iris-ui-kit/core';
+
+type IrisAdminLayoutMode = 'sidebar' | 'full-content';
+type LogoRenderer = React.ReactNode | ((state: {
+    collapsed: boolean;
+}) => React.ReactNode);
+type ContentRenderer = React.ReactNode | ((state: {
+    activeKey: string;
+}) => React.ReactNode);
+interface IrisAdminLayoutProps {
+    /** Normalized nav tree driving menu + breadcrumb. */
+    menus: NavNode[];
+    /** Active page key (controlled). */
+    activeKey?: string;
+    defaultActiveKey?: string;
+    onActiveKeyChange?: (key: string) => void;
+    /** Sidebar collapsed (controlled); undefined = uncontrolled. */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (next: boolean) => void;
+    mode?: IrisAdminLayoutMode;
+    appTitle?: string;
+    /** Optional shared tabs store; when present the tab bar is rendered. */
+    tabs?: TabsNav;
+    showBreadcrumb?: boolean;
+    sidebarWidth?: number | string;
+    collapsedWidth?: number | string;
+    /** Brand region; render-prop receives `{ collapsed }`. */
+    logo?: LogoRenderer;
+    /** Header end region (theme switch, user menu, …). */
+    toolbar?: React.ReactNode;
+    footer?: React.ReactNode;
+    onSelect?: (key: string, node: NavNode) => void;
+    /** Page content; render-prop receives `{ activeKey }`. */
+    children?: ContentRenderer;
+}
+/**
+ * The CMS / admin shell — a Vben-style, router-agnostic, data-driven layout that
+ * composes IrisSidebarLayout + IrisHeaderLayout with the admin nav pieces. One
+ * `menus` tree drives the collapsible sidebar nav, the header breadcrumb, and
+ * (when a `tabs` store is passed) the multi-tab bar; `activeKey` is the current
+ * page. The host owns routing: react to `onSelect` / `onActiveKeyChange` and
+ * render the page via the children render-prop (wrap it in keep-alive keyed by
+ * `tabs.cacheKey` for Vben-style tab caching).
+ *
+ * Modes: `sidebar` (default) and `full-content` (chrome hidden). React port of
+ * the Vue `IrisAdminLayout`.
+ */
+declare function IrisAdminLayout({ menus, activeKey, defaultActiveKey, onActiveKeyChange, collapsed, defaultCollapsed, onCollapsedChange, mode, appTitle, tabs, showBreadcrumb, sidebarWidth, collapsedWidth, logo, toolbar, footer, onSelect, children, }: IrisAdminLayoutProps): React.ReactElement;
+
+interface IrisNavMenuProps {
+    /** Normalized nav tree. */
+    items: NavNode[];
+    /** Key of the active leaf. */
+    activeKey?: string;
+    /** Controlled expanded branch keys. */
+    expandedKeys?: string[];
+    /** Initial expanded keys when uncontrolled (else the active trail expands). */
+    defaultExpandedKeys?: string[];
+    /** Icon-only rail (top-level items only). */
+    collapsed?: boolean;
+    ariaLabel?: string;
+    onSelect?: (key: string, node: NavNode) => void;
+    onExpandedKeysChange?: (keys: string[]) => void;
+}
+/**
+ * Data-driven nested navigation menu — the sidebar nav of the admin shell.
+ * Renders a normalized `NavNode[]` tree as an accordion of expandable branches
+ * and selectable leaves; the active leaf and its ancestor branches are
+ * highlighted, and the active branch trail auto-expands. Router-agnostic: takes
+ * `activeKey`, calls `onSelect(key, node)`; the host owns navigation.
+ *
+ * `collapsed` switches to an icon-only rail (top-level only); a branch click
+ * then jumps to its first leaf. React port of the Vue `IrisNavMenu`.
+ */
+declare function IrisNavMenu({ items, activeKey, expandedKeys, defaultExpandedKeys, collapsed, ariaLabel, onSelect, onExpandedKeysChange, }: IrisNavMenuProps): React.ReactElement;
+
+interface IrisAdminBreadcrumbProps {
+    /** Root→current ancestor chain (typically `findNavPath(menus, activeKey)`). */
+    trail: NavNode[];
+    /** Show each node's icon before its title. */
+    showIcon?: boolean;
+    /** Hide the breadcrumb when the trail has a single crumb. */
+    hideSingle?: boolean;
+    separator?: string;
+    onSelect?: (key: string, node: NavNode) => void;
+}
+/**
+ * Breadcrumb trail for the admin header, driven by a `NavNode[]` ancestor chain.
+ * The last crumb is the current page (auto-marked `aria-current` by
+ * IrisBreadcrumb); earlier crumbs are clickable and call `onSelect(key, node)`.
+ * React port of the Vue `IrisAdminBreadcrumb`.
+ */
+declare function IrisAdminBreadcrumb({ trail, showIcon, hideSingle, separator, onSelect, }: IrisAdminBreadcrumbProps): React.ReactElement | null;
+
+interface IrisAdminTabsProps {
+    /** Shared tabs store (from `createTabsNav`). */
+    nav: TabsNav;
+    onChange?: (key: string) => void;
+    onClose?: (key: string) => void;
+    onRefresh?: (key: string) => void;
+}
+/**
+ * Vben-style multi-tab bar over a shared {@link TabsNav} store. Each open page is
+ * a closable chip; clicking activates (`onChange`), the × closes, and a trailing
+ * actions dropdown runs Refresh / Close / Close-others / Close-all on the active
+ * tab. The store owns the tab list + active key; the host watches it to sync
+ * routing + keep-alive.
+ *
+ * Keyboard (WAI-ARIA tablist, automatic activation): ←/→ move + activate, Home/
+ * End jump, Delete/Backspace closes the focused tab. Roving tabindex keeps a
+ * single tab stop. React port of the Vue `IrisAdminTabs`.
+ */
+declare function IrisAdminTabs({ nav, onChange, onClose, onRefresh, }: IrisAdminTabsProps): React.ReactElement;
+
+interface UseTabsNavReturn {
+    tabs: TabItem[];
+    activeKey: string | undefined;
+    /** Keep-alive include-set (composite cache keys of all open tabs). */
+    cacheKeys: string[];
+    open: TabsNav['open'];
+    activate: TabsNav['activate'];
+    close: TabsNav['close'];
+    closeOthers: TabsNav['closeOthers'];
+    closeAll: TabsNav['closeAll'];
+    closeLeft: TabsNav['closeLeft'];
+    closeRight: TabsNav['closeRight'];
+    refresh: TabsNav['refresh'];
+    setPinned: TabsNav['setPinned'];
+    cacheKey: TabsNav['cacheKey'];
+}
+/**
+ * React binding for a framework-agnostic {@link TabsNav} store. Pass a shared
+ * `createTabsNav()` instance (the host owns it so the tab bar and the keep-alive
+ * content read the same state) and get the reactive `tabs` / `activeKey` /
+ * `cacheKeys` plus the store's mutators — bridged via `useStore`
+ * (`useSyncExternalStore`), mirroring the Vue adapter.
+ *
+ * ```tsx
+ * const nav = createTabsNav({ tabs: [{ key: 'home', title: 'Home', pinned: true }] })
+ * const { tabs, activeKey, open, close } = useTabsNav(nav)
+ * ```
+ */
+declare function useTabsNav(nav: TabsNav): UseTabsNavReturn;
+
+interface UseAdminShellConfig {
+    /** Normalized nav tree driving menu + breadcrumb. */
+    menus: NavNode[];
+    /** Active page key (controlled); undefined = uncontrolled. */
+    activeKey?: string;
+    defaultActiveKey?: string;
+    onActiveKeyChange?: (key: string) => void;
+    /** Fired whenever a nav node / tab becomes active, with the resolved leaf node. */
+    onSelect?: (key: string, node: NavNode) => void;
+    /** Optional shared tabs store; the shell opens/reconciles tabs through it. */
+    tabs?: TabsNav;
+}
+interface UseAdminShellReturn {
+    /** Current active leaf key ('' when none). */
+    activeKey: string;
+    /** Select a nav node: a branch redirects to its first leaf, opens its tab. */
+    navigate: (node: NavNode) => void;
+    /** Reconcile when the active TAB changed (e.g. a close picked a neighbor). */
+    syncFromTab: (key: string) => void;
+    /** Ancestor→node breadcrumb trail of the active key. */
+    breadcrumb: NavNode[];
+}
+/**
+ * React binding for the framework-agnostic {@link createAdminShell} controller —
+ * the menu→tab→active-key wiring that every AdminLayout used to re-implement
+ * byte-for-byte. The hook owns the controlled/uncontrolled `activeKey`
+ * reconciliation (idiomatic to React) and delegates navigate / syncFromTab /
+ * branch-resolution / breadcrumb to the shared core shell.
+ *
+ * Controlled mode renders from the prop directly (no flicker); an effect keeps
+ * the shell's guard-base synced to the prop so the active-change callback fires
+ * with the same semantics as before.
+ */
+declare function useAdminShell(config: UseAdminShellConfig): UseAdminShellReturn;
+
+export { IrisAdminBreadcrumb, type IrisAdminBreadcrumbProps, IrisAdminLayout, type IrisAdminLayoutMode, type IrisAdminLayoutProps, IrisAdminTabs, type IrisAdminTabsProps, IrisNavMenu, type IrisNavMenuProps, type UseAdminShellConfig, type UseAdminShellReturn, type UseTabsNavReturn, useAdminShell, useTabsNav };

package/dist/admin.js

@@ -0,0 +1,9 @@
+'use client'
+export { IrisAdminBreadcrumb, IrisAdminLayout, IrisAdminTabs, IrisNavMenu, createTabsNav, filterNavByAccess, findNavNode, findNavPath, firstLeaf, flattenNav, isBranch, isClosable, nodeAllowsRoles, useAdminShell, useTabsNav, visibleNav } from './chunk-VWCJJRSC.js';
+import './chunk-XCK4RIXB.js';
+import './chunk-J5FB2UB2.js';
+import './chunk-OMOTUHYI.js';
+import './chunk-6BMFMCMQ.js';
+import './chunk-RZNYIFV2.js';
+//# sourceMappingURL=admin.js.map
+//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":";","file":"admin.js"}

package/dist/async.cjs

@@ -0,0 +1,97 @@
+'use client'
+'use strict';
+
+var React2 = require('react');
+var core = require('@iris-ui-kit/core');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var React2__namespace = /*#__PURE__*/_interopNamespace(React2);
+
+// src/async/useAsyncResource.ts
+function useStore(store) {
+  return React2.useSyncExternalStore(
+    store.subscribe,
+    store.getState,
+    store.getState
+    // SSR fallback — same as client snapshot in our case.
+  );
+}
+
+// src/async/useAsyncResource.ts
+function useAsyncResource(fetcher, options = {}) {
+  const latest = React2__namespace.useRef(fetcher);
+  latest.current = fetcher;
+  const ref = React2__namespace.useRef(null);
+  if (ref.current === null) {
+    const config = "initialData" in options ? { initialData: options.initialData } : {};
+    ref.current = core.createAsyncResource((...params) => latest.current(...params), config);
+  }
+  const resource = ref.current;
+  const state = useStore(resource.store);
+  const immediate = React2__namespace.useRef(options.immediate ?? false);
+  React2__namespace.useEffect(() => {
+    if (immediate.current) void resource.load(...[]);
+    return () => resource.cancel();
+  }, [resource]);
+  return {
+    ...state,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    load: resource.load,
+    reload: resource.reload,
+    mutate: resource.mutate,
+    cancel: resource.cancel,
+    reset: resource.reset
+  };
+}
+function usePaginatedResource(fetcher, options = {}) {
+  const latest = React2__namespace.useRef(fetcher);
+  latest.current = fetcher;
+  const ref = React2__namespace.useRef(null);
+  if (ref.current === null) {
+    ref.current = core.createPaginatedResource((query) => latest.current(query), {
+      pageSize: options.pageSize,
+      mode: options.mode
+    });
+  }
+  const resource = ref.current;
+  const state = useStore(resource.store);
+  const initial = React2__namespace.useRef({ immediate: options.immediate ?? false, mode: options.mode });
+  React2__namespace.useEffect(() => {
+    if (!initial.current.immediate) return;
+    void (initial.current.mode === "infinite" ? resource.loadMore() : resource.goToPage(1));
+  }, [resource]);
+  return {
+    ...state,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    // `state` drives the re-render; hasMore() then reads the fresh batch state.
+    hasMore: resource.hasMore(),
+    goToPage: resource.goToPage,
+    loadMore: resource.loadMore,
+    refresh: resource.refresh,
+    setPageSize: resource.setPageSize
+  };
+}
+
+exports.useAsyncResource = useAsyncResource;
+exports.usePaginatedResource = usePaginatedResource;
+//# sourceMappingURL=async.cjs.map
+//# sourceMappingURL=async.cjs.map

package/dist/async.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useStore.ts","../src/async/useAsyncResource.ts","../src/async/usePaginatedResource.ts"],"names":["useSyncExternalStore","React2","createAsyncResource","React3","createPaginatedResource"],"mappings":"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","file":"async.cjs","sourcesContent":["import * as React from 'react'\nimport { useSyncExternalStore } from 'react'\nimport type { ReadonlyStore, Store } from '@iris-ui-kit/core'\n\n/**\n * Bridge a framework-agnostic `@iris-ui-kit/core` store into React reactivity.\n * Uses React 18's `useSyncExternalStore` — the contract is identical to the\n * one Vue uses via `ref + onMounted` and Solid uses via `createSignal`. The\n * **same** store can power Button, Popover, Dialog, etc. on any framework.\n */\nexport function useStore<T>(store: ReadonlyStore<T>): T {\n  return useSyncExternalStore(\n    store.subscribe,\n    store.getState,\n    store.getState, // SSR fallback — same as client snapshot in our case.\n  )\n}\n\n/**\n * Subscribe to a DERIVED slice of a core store — the component re-renders only\n * when `selector(state)` changes per `isEqual` (default `Object.is`), not on\n * every store emission. Built on {@link Store.subscribeWith}. Inline closures\n * for `selector`/`isEqual` are fine (captured via refs; the subscription is not\n * re-created between renders).\n */\nexport function useStoreSelector<T, U>(\n  store: Store<T>,\n  selector: (state: T) => U,\n  isEqual?: (a: U, b: U) => boolean,\n): U {\n  const [slice, setSlice] = React.useState(() => selector(store.getState()))\n  const selRef = React.useRef(selector)\n  selRef.current = selector\n  const eqRef = React.useRef(isEqual)\n  eqRef.current = isEqual\n  React.useEffect(() => {\n    const read = (s: T): U => selRef.current(s)\n    const eq = (a: U, b: U): boolean => (eqRef.current ?? Object.is)(a, b)\n    // Re-sync in case the store moved between render and this effect.\n    setSlice((prev) => {\n      const next = read(store.getState())\n      return eq(prev, next) ? prev : next\n    })\n    return store.subscribeWith(read, setSlice, eq)\n  }, [store])\n  return slice\n}\n","import * as React from 'react'\nimport {\n  createAsyncResource,\n  type AsyncResource,\n  type AsyncResourceConfig,\n  type AsyncState,\n} from '@iris-ui-kit/core'\nimport { useStore } from '../useStore'\n\nexport interface UseAsyncResourceOptions<T> extends AsyncResourceConfig<T> {\n  /** Run `load()` (no params) once on mount. Default `false`. */\n  immediate?: boolean\n}\n\nexport interface UseAsyncResourceReturn<T, P extends unknown[]> extends AsyncState<T> {\n  isLoading: boolean\n  isError: boolean\n  load: AsyncResource<T, P>['load']\n  reload: AsyncResource<T, P>['reload']\n  mutate: AsyncResource<T, P>['mutate']\n  cancel: AsyncResource<T, P>['cancel']\n  reset: AsyncResource<T, P>['reset']\n}\n\n/**\n * React binding for the framework-agnostic async resource. Instantiates the\n * resource once and bridges it via `useSyncExternalStore`. The fetcher is read\n * through a ref each render so it never goes stale, while seeding/immediacy are\n * captured on first render.\n *\n * ```tsx\n * const users = useAsyncResource(() => api.listUsers(), { immediate: true })\n * <IrisTable data={users.data ?? []} loading={users.isLoading} error={users.isError} />\n * ```\n */\nexport function useAsyncResource<T, P extends unknown[] = []>(\n  fetcher: (...params: P) => Promise<T>,\n  options: UseAsyncResourceOptions<T> = {},\n): UseAsyncResourceReturn<T, P> {\n  const latest = React.useRef(fetcher)\n  latest.current = fetcher\n\n  const ref = React.useRef<AsyncResource<T, P> | null>(null)\n  if (ref.current === null) {\n    const config: AsyncResourceConfig<T> =\n      'initialData' in options ? { initialData: options.initialData } : {}\n    ref.current = createAsyncResource<T, P>((...params) => latest.current(...params), config)\n  }\n  const resource = ref.current\n  const state = useStore(resource.store)\n\n  const immediate = React.useRef(options.immediate ?? false)\n  React.useEffect(() => {\n    if (immediate.current) void resource.load(...([] as unknown as P))\n    // Abort any in-flight request on unmount so it can't write back into an\n    // unmounted component (the token guard already prevents the state write;\n    // this also cancels the underlying request when the fetcher honors signal).\n    return () => resource.cancel()\n  }, [resource])\n\n  return {\n    ...state,\n    isLoading: state.status === 'loading',\n    isError: state.status === 'error',\n    load: resource.load,\n    reload: resource.reload,\n    mutate: resource.mutate,\n    cancel: resource.cancel,\n    reset: resource.reset,\n  }\n}\n","import * as React from 'react'\nimport {\n  createPaginatedResource,\n  type PageQuery,\n  type PageResult,\n  type PaginatedResource,\n  type PaginatedState,\n  type PaginationMode,\n} from '@iris-ui-kit/core'\nimport { useStore } from '../useStore'\n\nexport interface UsePaginatedResourceOptions {\n  pageSize?: number\n  mode?: PaginationMode\n  /** Load the first page on mount (page 1, or `loadMore` in infinite mode). */\n  immediate?: boolean\n}\n\nexport interface UsePaginatedResourceReturn<T> extends PaginatedState<T> {\n  isLoading: boolean\n  isError: boolean\n  hasMore: boolean\n  goToPage: PaginatedResource<T>['goToPage']\n  loadMore: PaginatedResource<T>['loadMore']\n  refresh: PaginatedResource<T>['refresh']\n  setPageSize: PaginatedResource<T>['setPageSize']\n}\n\n/**\n * React binding for the server-side pagination resource. Instantiates once and\n * bridges via `useSyncExternalStore`; the fetcher is read through a ref so it\n * never goes stale.\n *\n * ```tsx\n * const p = usePaginatedResource((q) => api.rows(q), { pageSize: 25, immediate: true })\n * <IrisTable data={p.items} loading={p.isLoading} error={p.isError} />\n * <IrisPagination total={p.total ?? 0} value={p.page} onValueChange={p.goToPage} />\n * ```\n */\nexport function usePaginatedResource<T>(\n  fetcher: (query: PageQuery) => Promise<PageResult<T>>,\n  options: UsePaginatedResourceOptions = {},\n): UsePaginatedResourceReturn<T> {\n  const latest = React.useRef(fetcher)\n  latest.current = fetcher\n\n  const ref = React.useRef<PaginatedResource<T> | null>(null)\n  if (ref.current === null) {\n    ref.current = createPaginatedResource<T>((query) => latest.current(query), {\n      pageSize: options.pageSize,\n      mode: options.mode,\n    })\n  }\n  const resource = ref.current\n  const state = useStore(resource.store)\n\n  const initial = React.useRef({ immediate: options.immediate ?? false, mode: options.mode })\n  React.useEffect(() => {\n    if (!initial.current.immediate) return\n    void (initial.current.mode === 'infinite' ? resource.loadMore() : resource.goToPage(1))\n  }, [resource])\n\n  return {\n    ...state,\n    isLoading: state.status === 'loading',\n    isError: state.status === 'error',\n    // `state` drives the re-render; hasMore() then reads the fresh batch state.\n    hasMore: resource.hasMore(),\n    goToPage: resource.goToPage,\n    loadMore: resource.loadMore,\n    refresh: resource.refresh,\n    setPageSize: resource.setPageSize,\n  }\n}\n"]}

package/dist/async.d.cts

@@ -0,0 +1,57 @@
+import { AsyncResourceConfig, AsyncState, AsyncResource, PaginationMode, PaginatedState, PaginatedResource, PageQuery, PageResult } from '@iris-ui-kit/core';
+
+interface UseAsyncResourceOptions<T> extends AsyncResourceConfig<T> {
+    /** Run `load()` (no params) once on mount. Default `false`. */
+    immediate?: boolean;
+}
+interface UseAsyncResourceReturn<T, P extends unknown[]> extends AsyncState<T> {
+    isLoading: boolean;
+    isError: boolean;
+    load: AsyncResource<T, P>['load'];
+    reload: AsyncResource<T, P>['reload'];
+    mutate: AsyncResource<T, P>['mutate'];
+    cancel: AsyncResource<T, P>['cancel'];
+    reset: AsyncResource<T, P>['reset'];
+}
+/**
+ * React binding for the framework-agnostic async resource. Instantiates the
+ * resource once and bridges it via `useSyncExternalStore`. The fetcher is read
+ * through a ref each render so it never goes stale, while seeding/immediacy are
+ * captured on first render.
+ *
+ * ```tsx
+ * const users = useAsyncResource(() => api.listUsers(), { immediate: true })
+ * <IrisTable data={users.data ?? []} loading={users.isLoading} error={users.isError} />
+ * ```
+ */
+declare function useAsyncResource<T, P extends unknown[] = []>(fetcher: (...params: P) => Promise<T>, options?: UseAsyncResourceOptions<T>): UseAsyncResourceReturn<T, P>;
+
+interface UsePaginatedResourceOptions {
+    pageSize?: number;
+    mode?: PaginationMode;
+    /** Load the first page on mount (page 1, or `loadMore` in infinite mode). */
+    immediate?: boolean;
+}
+interface UsePaginatedResourceReturn<T> extends PaginatedState<T> {
+    isLoading: boolean;
+    isError: boolean;
+    hasMore: boolean;
+    goToPage: PaginatedResource<T>['goToPage'];
+    loadMore: PaginatedResource<T>['loadMore'];
+    refresh: PaginatedResource<T>['refresh'];
+    setPageSize: PaginatedResource<T>['setPageSize'];
+}
+/**
+ * React binding for the server-side pagination resource. Instantiates once and
+ * bridges via `useSyncExternalStore`; the fetcher is read through a ref so it
+ * never goes stale.
+ *
+ * ```tsx
+ * const p = usePaginatedResource((q) => api.rows(q), { pageSize: 25, immediate: true })
+ * <IrisTable data={p.items} loading={p.isLoading} error={p.isError} />
+ * <IrisPagination total={p.total ?? 0} value={p.page} onValueChange={p.goToPage} />
+ * ```
+ */
+declare function usePaginatedResource<T>(fetcher: (query: PageQuery) => Promise<PageResult<T>>, options?: UsePaginatedResourceOptions): UsePaginatedResourceReturn<T>;
+
+export { type UseAsyncResourceOptions, type UseAsyncResourceReturn, type UsePaginatedResourceOptions, type UsePaginatedResourceReturn, useAsyncResource, usePaginatedResource };

package/dist/async.d.ts

@@ -0,0 +1,57 @@
+import { AsyncResourceConfig, AsyncState, AsyncResource, PaginationMode, PaginatedState, PaginatedResource, PageQuery, PageResult } from '@iris-ui-kit/core';
+
+interface UseAsyncResourceOptions<T> extends AsyncResourceConfig<T> {
+    /** Run `load()` (no params) once on mount. Default `false`. */
+    immediate?: boolean;
+}
+interface UseAsyncResourceReturn<T, P extends unknown[]> extends AsyncState<T> {
+    isLoading: boolean;
+    isError: boolean;
+    load: AsyncResource<T, P>['load'];
+    reload: AsyncResource<T, P>['reload'];
+    mutate: AsyncResource<T, P>['mutate'];
+    cancel: AsyncResource<T, P>['cancel'];
+    reset: AsyncResource<T, P>['reset'];
+}
+/**
+ * React binding for the framework-agnostic async resource. Instantiates the
+ * resource once and bridges it via `useSyncExternalStore`. The fetcher is read
+ * through a ref each render so it never goes stale, while seeding/immediacy are
+ * captured on first render.
+ *
+ * ```tsx
+ * const users = useAsyncResource(() => api.listUsers(), { immediate: true })
+ * <IrisTable data={users.data ?? []} loading={users.isLoading} error={users.isError} />
+ * ```
+ */
+declare function useAsyncResource<T, P extends unknown[] = []>(fetcher: (...params: P) => Promise<T>, options?: UseAsyncResourceOptions<T>): UseAsyncResourceReturn<T, P>;
+
+interface UsePaginatedResourceOptions {
+    pageSize?: number;
+    mode?: PaginationMode;
+    /** Load the first page on mount (page 1, or `loadMore` in infinite mode). */
+    immediate?: boolean;
+}
+interface UsePaginatedResourceReturn<T> extends PaginatedState<T> {
+    isLoading: boolean;
+    isError: boolean;
+    hasMore: boolean;
+    goToPage: PaginatedResource<T>['goToPage'];
+    loadMore: PaginatedResource<T>['loadMore'];
+    refresh: PaginatedResource<T>['refresh'];
+    setPageSize: PaginatedResource<T>['setPageSize'];
+}
+/**
+ * React binding for the server-side pagination resource. Instantiates once and
+ * bridges via `useSyncExternalStore`; the fetcher is read through a ref so it
+ * never goes stale.
+ *
+ * ```tsx
+ * const p = usePaginatedResource((q) => api.rows(q), { pageSize: 25, immediate: true })
+ * <IrisTable data={p.items} loading={p.isLoading} error={p.isError} />
+ * <IrisPagination total={p.total ?? 0} value={p.page} onValueChange={p.goToPage} />
+ * ```
+ */
+declare function usePaginatedResource<T>(fetcher: (query: PageQuery) => Promise<PageResult<T>>, options?: UsePaginatedResourceOptions): UsePaginatedResourceReturn<T>;
+
+export { type UseAsyncResourceOptions, type UseAsyncResourceReturn, type UsePaginatedResourceOptions, type UsePaginatedResourceReturn, useAsyncResource, usePaginatedResource };

package/dist/async.js

@@ -0,0 +1,5 @@
+'use client'
+export { useAsyncResource, usePaginatedResource } from './chunk-TO7YVSAI.js';
+import './chunk-RZNYIFV2.js';
+//# sourceMappingURL=async.js.map
+//# sourceMappingURL=async.js.map

package/dist/async.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":";","file":"async.js"}