@strato-admin/core 0.1.0 → 0.3.0

package/dist/ra-core/src/preferences/useSetInspectorTitle.js

@@ -0,0 +1,19 @@
+import { useEffect } from 'react';
+import { usePreferencesEditor } from './usePreferencesEditor';
+/**
+ * Set inspector title on mount
+ *
+ * @example
+ * useSetInspectorTitle('Datagrid');
+ */
+export const useSetInspectorTitle = (title, options) => {
+    const preferencesEditorContext = usePreferencesEditor();
+    if (!preferencesEditorContext) {
+        throw new Error('useSetInspectorTitle cannot be called outside of a PreferencesEditorContext');
+    }
+    const { setTitle } = preferencesEditorContext;
+    useEffect(() => {
+        setTitle(title, options);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [title, JSON.stringify(options), setTitle]);
+};

package/dist/ra-core/src/routing/AdminRouter.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+/**
+ * Creates a Router unless the app is already inside existing router.
+ * Also creates a BasenameContext with the basename prop.
+ *
+ * Uses the RouterWrapper from the configured routerProvider to create
+ * the appropriate router type (HashRouter by default with react-router).
+ */
+export declare const AdminRouter: ({ basename, children }: AdminRouterProps) => import("react/jsx-runtime").JSX.Element;
+export interface AdminRouterProps {
+    basename?: string;
+    children: React.ReactNode;
+}

package/dist/ra-core/src/routing/AdminRouter.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { BasenameContextProvider } from './BasenameContextProvider';
+import { useRouterProvider } from './RouterProviderContext';
+/**
+ * Creates a Router unless the app is already inside existing router.
+ * Also creates a BasenameContext with the basename prop.
+ *
+ * Uses the RouterWrapper from the configured routerProvider to create
+ * the appropriate router type (HashRouter by default with react-router).
+ */
+export const AdminRouter = ({ basename = '', children }) => {
+    const { RouterWrapper, useInRouterContext } = useRouterProvider();
+    const isInRouter = useInRouterContext();
+    return (_jsx(BasenameContextProvider, { basename: isInRouter ? basename : '', children: _jsx(RouterWrapper, { basename: basename, children: children }) }));
+};

package/dist/ra-core/src/routing/BasenameContext.d.ts

@@ -0,0 +1 @@
+export declare const BasenameContext: import("react").Context<string>;

package/dist/ra-core/src/routing/BasenameContext.js

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const BasenameContext = createContext('');

package/dist/ra-core/src/routing/BasenameContextProvider.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Set the string to append to all links to the admin app.
+ *
+ * Useful when the app is mounted on a sub path, e.g. '/admin'.
+ * Used internally by the `<Admin>` component.
+ *
+ * @see useBasename
+ */
+export declare const BasenameContextProvider: ({ children, basename }: {
+    children: any;
+    basename: any;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/ra-core/src/routing/BasenameContextProvider.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { BasenameContext } from './BasenameContext';
+/**
+ * Set the string to append to all links to the admin app.
+ *
+ * Useful when the app is mounted on a sub path, e.g. '/admin'.
+ * Used internally by the `<Admin>` component.
+ *
+ * @see useBasename
+ */
+export const BasenameContextProvider = ({ children, basename }) => (_jsx(BasenameContext.Provider, { value: basename, children: children }));

package/dist/ra-core/src/routing/LinkBase.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { RouterLinkProps } from './RouterProvider';
+export type { RouterLinkProps as LinkBaseProps } from './RouterProvider';
+/**
+ * Base Link component for use with react-admin's routing.
+ * This is a router-agnostic wrapper that uses the configured router provider.
+ *
+ * For most use cases, prefer the styled `Link` component from `ra-ui-materialui`.
+ *
+ * @example
+ * import { LinkBase } from '@strato-admin/ra-core';
+ *
+ * const MyComponent = () => (
+ *     <LinkBase to="/posts/1">Post 1</LinkBase>
+ * );
+ */
+export declare const LinkBase: React.ForwardRefExoticComponent<Omit<RouterLinkProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;

package/dist/ra-core/src/routing/LinkBase.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { useRouterProvider } from './RouterProviderContext';
+/**
+ * Base Link component for use with react-admin's routing.
+ * This is a router-agnostic wrapper that uses the configured router provider.
+ *
+ * For most use cases, prefer the styled `Link` component from `ra-ui-materialui`.
+ *
+ * @example
+ * import { LinkBase } from '@strato-admin/ra-core';
+ *
+ * const MyComponent = () => (
+ *     <LinkBase to="/posts/1">Post 1</LinkBase>
+ * );
+ */
+export const LinkBase = forwardRef((props, ref) => {
+    const provider = useRouterProvider();
+    // @ts-expect-error - React 19 type mismatch for provider.Link
+    return _jsx(provider.Link, { ref: ref, ...props });
+});
+LinkBase.displayName = 'LinkBase';

package/dist/ra-core/src/routing/Navigate.d.ts

@@ -0,0 +1,14 @@
+import type { RouterNavigateProps } from './RouterProvider';
+export type { RouterNavigateProps as NavigateProps } from './RouterProvider';
+/**
+ * Navigate component for declarative navigation.
+ * This is a router-agnostic wrapper that uses the configured router provider.
+ *
+ * @example
+ * import { Navigate } from 'react-admin';
+ *
+ * const MyComponent = () => (
+ *     <Navigate to="/login" replace />
+ * );
+ */
+export declare const Navigate: (props: RouterNavigateProps) => import("react/jsx-runtime").JSX.Element;

package/dist/ra-core/src/routing/Navigate.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRouterProvider } from './RouterProviderContext';
+/**
+ * Navigate component for declarative navigation.
+ * This is a router-agnostic wrapper that uses the configured router provider.
+ *
+ * @example
+ * import { Navigate } from 'react-admin';
+ *
+ * const MyComponent = () => (
+ *     <Navigate to="/login" replace />
+ * );
+ */
+export const Navigate = (props) => {
+    const provider = useRouterProvider();
+    return _jsx(provider.Navigate, { ...props });
+};

package/dist/ra-core/src/routing/Outlet.d.ts

@@ -0,0 +1,19 @@
+import type { RouterOutletProps } from './RouterProvider';
+export type { RouterOutletProps as OutletProps } from './RouterProvider';
+/**
+ * Outlet component for nested route rendering.
+ * This is a router-agnostic wrapper that uses the configured router provider.
+ *
+ * @example
+ * import { Outlet } from 'react-admin';
+ *
+ * const MyLayout = () => (
+ *     <div>
+ *         <header>My App</header>
+ *         <main>
+ *             <Outlet />
+ *         </main>
+ *     </div>
+ * );
+ */
+export declare const Outlet: (props: RouterOutletProps) => import("react/jsx-runtime").JSX.Element;

package/dist/ra-core/src/routing/Outlet.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRouterProvider } from './RouterProviderContext';
+/**
+ * Outlet component for nested route rendering.
+ * This is a router-agnostic wrapper that uses the configured router provider.
+ *
+ * @example
+ * import { Outlet } from 'react-admin';
+ *
+ * const MyLayout = () => (
+ *     <div>
+ *         <header>My App</header>
+ *         <main>
+ *             <Outlet />
+ *         </main>
+ *     </div>
+ * );
+ */
+export const Outlet = (props) => {
+    const provider = useRouterProvider();
+    return _jsx(provider.Outlet, { ...props });
+};

package/dist/ra-core/src/routing/RestoreScrollPosition.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from 'react';
+/**
+ * A component that tracks the scroll position and restores it when the component mounts.
+ * @param children The content to render
+ * @param key The key under which to store the scroll position in the store
+ * @param debounceMs The debounce time in milliseconds
+ *
+ * @example
+ * import { RestoreScrollPosition } from '@strato-admin/ra-core';
+ *
+ * const MyCustomPage = () => {
+ *   <RestoreScrollPosition key="my-list">
+ *     <div>
+ *       <h1>My Custom Page</h1>
+ *       <VeryLongContent />
+ *     </div>
+ *   </RestoreScrollPosition>
+ * };
+ */
+export declare const RestoreScrollPosition: ({ children, storeKey, debounce, }: {
+    storeKey: string;
+    debounce?: number;
+    children: ReactNode;
+}) => ReactNode;

package/dist/ra-core/src/routing/RestoreScrollPosition.js

@@ -0,0 +1,23 @@
+import { useRestoreScrollPosition } from './useRestoreScrollPosition';
+/**
+ * A component that tracks the scroll position and restores it when the component mounts.
+ * @param children The content to render
+ * @param key The key under which to store the scroll position in the store
+ * @param debounceMs The debounce time in milliseconds
+ *
+ * @example
+ * import { RestoreScrollPosition } from '@strato-admin/ra-core';
+ *
+ * const MyCustomPage = () => {
+ *   <RestoreScrollPosition key="my-list">
+ *     <div>
+ *       <h1>My Custom Page</h1>
+ *       <VeryLongContent />
+ *     </div>
+ *   </RestoreScrollPosition>
+ * };
+ */
+export const RestoreScrollPosition = ({ children, storeKey, debounce = 250, }) => {
+    useRestoreScrollPosition(storeKey, debounce);
+    return children;
+};

package/dist/ra-core/src/routing/RouterProvider.d.ts

@@ -0,0 +1,163 @@
+import { ComponentType, ReactNode } from 'react';
+export interface RouterLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+    state?: any;
+    key?: string;
+}
+export interface RouterNavigateOptions {
+    replace?: boolean;
+    state?: any;
+}
+export type RouterNavigateFunction = (to: string | Partial<RouterLocation> | number, options?: RouterNavigateOptions) => void;
+export interface RouterBlockerBlocked {
+    state: 'blocked';
+    reset: () => void;
+    proceed: () => void;
+    location: RouterLocation;
+}
+export interface RouterBlockerUnblocked {
+    state: 'unblocked';
+    reset: undefined;
+    proceed: undefined;
+    location: undefined;
+}
+export interface RouterBlockerProceeding {
+    state: 'proceeding';
+    reset: undefined;
+    proceed: undefined;
+    location: RouterLocation;
+}
+export type RouterBlocker = RouterBlockerBlocked | RouterBlockerUnblocked | RouterBlockerProceeding;
+export type RouterHistoryAction = 'POP' | 'PUSH' | 'REPLACE';
+export type RouterBlockerFunction = (args: {
+    currentLocation: RouterLocation;
+    nextLocation: RouterLocation;
+    historyAction: RouterHistoryAction;
+}) => boolean;
+export interface RouterMatch {
+    params: Record<string, string | undefined>;
+    pathname: string;
+    pathnameBase: string;
+}
+export type RouterTo = string | Partial<RouterLocation>;
+export interface RouterLinkProps {
+    to: RouterTo;
+    replace?: boolean;
+    state?: any;
+    children?: ReactNode;
+    className?: string;
+    [key: string]: any;
+}
+export interface RouterNavigateProps {
+    to: string | Partial<RouterLocation>;
+    replace?: boolean;
+    state?: any;
+}
+export interface RouterRouteProps {
+    path?: string;
+    element?: ReactNode;
+    children?: ReactNode;
+    index?: boolean;
+}
+export interface RouterRoutesProps {
+    children: ReactNode;
+    location?: RouterLocation | string;
+}
+export interface RouterOutletProps {
+    context?: any;
+}
+export interface RouterWrapperProps {
+    basename?: string;
+    children: ReactNode;
+}
+/**
+ * The RouterProvider interface defines all routing primitives used by ra-core.
+ * Implement this interface to use a different router library (e.g., TanStack Router).
+ *
+ * @example
+ * // Using the default react-router provider (no configuration needed)
+ * <Admin dataProvider={dataProvider}>
+ *   <Resource name="posts" list={PostList} />
+ * </Admin>
+ *
+ * @example
+ * // Using a custom router provider
+ * import { tanStackRouterProvider } from '@strato-admin/ra-core';
+ *
+ * <Admin dataProvider={dataProvider} routerProvider={tanStackRouterProvider}>
+ *   <Resource name="posts" list={PostList} />
+ * </Admin>
+ */
+export interface RouterProvider {
+    /**
+     * Returns the current location object.
+     */
+    useLocation: () => RouterLocation;
+    /**
+     * Returns a function to navigate programmatically.
+     */
+    useNavigate: () => RouterNavigateFunction;
+    /**
+     * Returns route parameters as key-value pairs.
+     */
+    useParams: <T extends Record<string, string | undefined> = Record<string, string | undefined>>() => T;
+    /**
+     * Blocks navigation based on a condition.
+     * Used by useWarnWhenUnsavedChanges to prevent losing form data.
+     */
+    useBlocker: (shouldBlock: RouterBlockerFunction | boolean) => RouterBlocker;
+    /**
+     * Returns a match object if the current location matches the given pattern.
+     */
+    useMatch: (pattern: {
+        path: string;
+        end?: boolean;
+    }) => RouterMatch | null;
+    /**
+     * Returns whether we are currently inside a router context.
+     */
+    useInRouterContext: () => boolean;
+    /**
+     * Returns whether navigation blocking (useBlocker) is supported in the current context.
+     * For react-router, this requires a data router. For other routers, it may always be true.
+     */
+    useCanBlock: () => boolean;
+    /**
+     * Link component for navigation.
+     */
+    Link: ComponentType<RouterLinkProps>;
+    /**
+     * Component for programmatic/declarative navigation.
+     */
+    Navigate: ComponentType<RouterNavigateProps>;
+    /**
+     * Route definition component.
+     */
+    Route: ComponentType<RouterRouteProps>;
+    /**
+     * Routes container component.
+     */
+    Routes: ComponentType<RouterRoutesProps>;
+    /**
+     * Outlet for nested routes.
+     */
+    Outlet: ComponentType<RouterOutletProps>;
+    /**
+     * Matches a path pattern against a pathname.
+     */
+    matchPath: (pattern: string | {
+        path: string;
+        end?: boolean;
+    }, pathname: string) => RouterMatch | null;
+    /**
+     * Component that wraps children with a router if not already in a router context.
+     *
+     * The component should:
+     * 1. Check if already inside a router context (using useInRouterContext)
+     * 2. If yes, render children directly
+     * 3. If no, wrap children with a router
+     */
+    RouterWrapper: ComponentType<RouterWrapperProps>;
+}

package/dist/ra-core/src/routing/RouterProvider.js

@@ -0,0 +1 @@
+export {};

package/dist/ra-core/src/routing/RouterProviderContext.d.ts

@@ -0,0 +1,15 @@
+import type { RouterProvider } from './RouterProvider';
+/**
+ * Context for providing the router provider throughout the application.
+ * Defaults to react-router provider, so existing apps work without changes.
+ */
+export declare const RouterProviderContext: import("react").Context<RouterProvider>;
+/**
+ * Hook to access the current router provider.
+ * Used internally by ra-core hooks and components to access routing primitives.
+ *
+ * @example
+ * const provider = useRouterProvider();
+ * const location = provider.useLocation();
+ */
+export declare const useRouterProvider: () => RouterProvider;

package/dist/ra-core/src/routing/RouterProviderContext.js

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+import { reactRouterProvider } from './adapters/reactRouterProvider';
+/**
+ * Context for providing the router provider throughout the application.
+ * Defaults to react-router provider, so existing apps work without changes.
+ */
+export const RouterProviderContext = createContext(reactRouterProvider);
+RouterProviderContext.displayName = 'RouterProviderContext';
+/**
+ * Hook to access the current router provider.
+ * Used internally by ra-core hooks and components to access routing primitives.
+ *
+ * @example
+ * const provider = useRouterProvider();
+ * const location = provider.useLocation();
+ */
+export const useRouterProvider = () => {
+    return useContext(RouterProviderContext);
+};

package/dist/ra-core/src/routing/TestMemoryRouter.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { Location, NavigateFunction } from 'react-router-dom';
+import type { InitialEntry } from '@remix-run/router';
+/**
+ * Wrapper around react-router's `createMemoryRouter` to be used in test components.
+ *
+ * It is similar to `MemoryRouter` but it supports
+ * [data APIs](https://reactrouter.com/en/main/routers/picking-a-router#data-apis).
+ *
+ * Additionally, it provides
+ * - a `locationCallback` prop to get the location in the test
+ * - a `navigateCallback` prop to be able to navigate in the test
+ */
+export declare const TestMemoryRouter: ({ children, locationCallback, navigateCallback, ...rest }: {
+    children: React.ReactNode;
+    locationCallback?: (l: Location) => void;
+    navigateCallback?: (n: NavigateFunction) => void;
+    basename?: string;
+    initialEntries?: InitialEntry[];
+    initialIndex?: number;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/ra-core/src/routing/TestMemoryRouter.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { createMemoryRouter, RouterProvider, useLocation, useNavigate, } from 'react-router-dom';
+const UseLocation = ({ locationCallback, }) => {
+    const location = useLocation();
+    locationCallback(location);
+    return null;
+};
+const UseNavigate = ({ navigateCallback, }) => {
+    const navigate = useNavigate();
+    navigateCallback(navigate);
+    return null;
+};
+/**
+ * Wrapper around react-router's `createMemoryRouter` to be used in test components.
+ *
+ * It is similar to `MemoryRouter` but it supports
+ * [data APIs](https://reactrouter.com/en/main/routers/picking-a-router#data-apis).
+ *
+ * Additionally, it provides
+ * - a `locationCallback` prop to get the location in the test
+ * - a `navigateCallback` prop to be able to navigate in the test
+ */
+export const TestMemoryRouter = ({ children, locationCallback, navigateCallback, ...rest }) => {
+    const router = createMemoryRouter([
+        {
+            path: '*',
+            element: (_jsxs(_Fragment, { children: [children, locationCallback && (_jsx(UseLocation, { locationCallback: locationCallback })), navigateCallback && (_jsx(UseNavigate, { navigateCallback: navigateCallback }))] })),
+        },
+    ], {
+        future: {
+            v7_fetcherPersist: false,
+            v7_normalizeFormMethod: false,
+            v7_partialHydration: false,
+            v7_relativeSplatPath: false,
+            v7_skipActionErrorRevalidation: false,
+        },
+        ...rest,
+    });
+    return (_jsx(RouterProvider, { router: router, 
+        // @ts-expect-error react-router types are not up-to-date
+        future: { v7_startTransition: false, v7_relativeSplatPath: false } }));
+};

package/dist/ra-core/src/routing/adapters/reactRouterProvider.d.ts

@@ -0,0 +1,6 @@
+import type { RouterProvider } from '../RouterProvider';
+/**
+ * Default router provider using react-router-dom.
+ * This provider is used by default when no custom routerProvider is provided to <Admin>.
+ */
+export declare const reactRouterProvider: RouterProvider;

package/dist/ra-core/src/routing/adapters/reactRouterProvider.js

@@ -0,0 +1,86 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { useContext, useEffect, useRef } from 'react';
+import { useNavigate as useReactRouterNavigate, useLocation, useParams, useBlocker, useMatch, useInRouterContext, Link, Navigate, Route, Routes, Outlet, matchPath, createHashRouter, RouterProvider as ReactRouterProvider, UNSAFE_DataRouterContext, UNSAFE_DataRouterStateContext, } from 'react-router-dom';
+const routerProviderFuture = { v7_startTransition: false, v7_relativeSplatPath: false };
+/**
+ * Hook to check if navigation blocking is supported.
+ * In react-router, blocking requires a data router.
+ */
+const useCanBlock = () => {
+    const dataRouterContext = useContext(UNSAFE_DataRouterContext);
+    const dataRouterStateContext = useContext(UNSAFE_DataRouterStateContext);
+    return !!(dataRouterContext && dataRouterStateContext);
+};
+/**
+ * Wrapper around react-router's useNavigate that returns a stable function reference.
+ *
+ * react-router's useNavigate forces rerenders on every navigation, even if we don't use the result.
+ * @see https://github.com/remix-run/react-router/issues/7634
+ *
+ * This wrapper uses a ref to return a stable function reference, avoiding unnecessary rerenders
+ * in components that use navigate but don't need to rerender on navigation.
+ */
+const useNavigate = () => {
+    const navigate = useReactRouterNavigate();
+    const navigateRef = useRef(navigate);
+    useEffect(() => {
+        navigateRef.current = navigate;
+    }, [navigate]);
+    // Return a stable function that always calls the latest navigate
+    return React.useCallback((...args) => {
+        return navigateRef.current(...args);
+    }, []);
+};
+/**
+ * Internal router component that creates a HashRouter.
+ * Only used when not already inside a router context.
+ */
+const InternalRouter = ({ children, basename, }) => {
+    const router = createHashRouter([{ path: '*', element: _jsx(_Fragment, { children: children }) }], {
+        basename,
+        future: {
+            v7_fetcherPersist: false,
+            v7_normalizeFormMethod: false,
+            v7_partialHydration: false,
+            v7_relativeSplatPath: false,
+            v7_skipActionErrorRevalidation: false,
+        },
+    });
+    return (_jsx(ReactRouterProvider, { router: router, future: routerProviderFuture }));
+};
+/**
+ * RouterWrapper component for react-router.
+ * Creates a HashRouter if not already inside a router context.
+ */
+const RouterWrapper = ({ basename, children }) => {
+    const isInRouter = useInRouterContext();
+    if (isInRouter) {
+        return _jsx(_Fragment, { children: children });
+    }
+    return _jsx(InternalRouter, { basename: basename, children: children });
+};
+/**
+ * Default router provider using react-router-dom.
+ * This provider is used by default when no custom routerProvider is provided to <Admin>.
+ */
+export const reactRouterProvider = {
+    // Hooks
+    useNavigate,
+    useLocation,
+    useParams: useParams,
+    useBlocker,
+    useMatch,
+    useInRouterContext,
+    useCanBlock,
+    // Components
+    Link,
+    Navigate,
+    Route,
+    Routes,
+    Outlet,
+    // Router creation
+    RouterWrapper,
+    // Utilities
+    matchPath,
+};

package/dist/ra-core/src/routing/index.d.ts

@@ -0,0 +1,28 @@
+export * from './AdminRouter';
+export * from './BasenameContextProvider';
+export * from './RestoreScrollPosition';
+export * from './useBasename';
+export * from './useCreatePath';
+export * from './useGetPathForRecord';
+export * from './useGetPathForRecordCallback';
+export * from './useRedirect';
+export * from './useResetErrorBoundaryOnLocationChange';
+export * from './useScrollToTop';
+export * from './useRestoreScrollPosition';
+export * from './types';
+export * from './TestMemoryRouter';
+export * from './useSplatPathBase';
+export * from './RouterProvider';
+export * from './RouterProviderContext';
+export * from './adapters/reactRouterProvider';
+export * from './useLocation';
+export * from './useNavigate';
+export * from './useParams';
+export * from './useBlocker';
+export * from './useMatch';
+export * from './useInRouterContext';
+export * from './useCanBlock';
+export * from './useMatchPath';
+export * from './LinkBase';
+export * from './Navigate';
+export * from './Outlet';