Skip to content

A full-featured CRM built with React, shadcn/ui, and Supabase.

Upgrade shadcn admin kit

fzaninottofcf65aa7cde1
diff --git a/package-lock.json b/package-lock.json
index 7423fff7..5a429496 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -27,7 +27,7 @@
"@radix-ui/react-tabs": "^1.1.12",
"@radix-ui/react-tooltip": "^1.2.8",
"@tailwindcss/vite": "^4.1.11",
- "@tanstack/react-query": "^5.90.8",
+ "@tanstack/react-query": "^5.90.12",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"cmdk": "^1.1.1",
@@ -40,10 +40,10 @@
"next-themes": "^0.4.6",
"papaparse": "^5.5.3",
"query-string": "^7.1.3",
- "ra-core": "^5.13.1",
+ "ra-core": "^5.13.3",
"ra-data-fakerest": "^5.10.0",
- "ra-i18n-polyglot": "^5.13.1",
- "ra-language-english": "^5.13.1",
+ "ra-i18n-polyglot": "^5.13.3",
+ "ra-language-english": "^5.13.3",
"ra-supabase-core": "^3.5.2",
"ra-supabase-language-english": "^3.5.0",
"react": "^19.1.0",
@@ -51,8 +51,8 @@
"react-dom": "^19.1.0",
"react-dropzone": "^14.3.8",
"react-error-boundary": "^6.0.0",
- "react-hook-form": "^7.66.0",
- "react-router": "^7.9.6",
+ "react-hook-form": "^7.68.0",
+ "react-router": "^7.10.1",
"rollup-plugin-visualizer": "^6.0.3",
"sonner": "^2.0.7",
"tailwind-merge": "^3.4.0",
@@ -4381,9 +4381,9 @@
}
},
"node_modules/@tanstack/query-core": {
- "version": "5.90.8",
- "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.90.8.tgz",
- "integrity": "sha512-4E0RP/0GJCxSNiRF2kAqE/LQkTJVlL/QNU7gIJSptaseV9HP6kOuA+N11y4bZKZxa3QopK3ZuewwutHx6DqDXQ==",
+ "version": "5.90.12",
+ "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.90.12.tgz",
+ "integrity": "sha512-T1/8t5DhV/SisWjDnaiU2drl6ySvsHj1bHBCWNXd+/T+Hh1cf6JodyEYMd5sgwm+b/mETT4EV3H+zCVczCU5hg==",
"license": "MIT",
"funding": {
"type": "github",
@@ -4391,12 +4391,12 @@
}
},
"node_modules/@tanstack/react-query": {
- "version": "5.90.8",
- "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.90.8.tgz",
- "integrity": "sha512-/3b9QGzkf4rE5/miL6tyhldQRlLXzMHcySOm/2Tm2OLEFE9P1ImkH0+OviDBSvyAvtAOJocar5xhd7vxdLi3aQ==",
+ "version": "5.90.12",
+ "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.90.12.tgz",
+ "integrity": "sha512-graRZspg7EoEaw0a8faiUASCyJrqjKPdqJ9EwuDRUF9mEYJ1YPczI9H+/agJ0mOJkPCJDk0lsz5QTrLZ/jQ2rg==",
"license": "MIT",
"dependencies": {
- "@tanstack/query-core": "5.90.8"
+ "@tanstack/query-core": "5.90.12"
},
"funding": {
"type": "github",
@@ -9476,12 +9476,11 @@
"license": "MIT"
},
"node_modules/ra-core": {
- "version": "5.13.1",
- "resolved": "https://registry.npmjs.org/ra-core/-/ra-core-5.13.1.tgz",
- "integrity": "sha512-7pjERvKNtFaeTg2OvZS2uKUQt3G4OnZFfZLKrGpc4dzLzWj7CRwG+7YCcc/Q69yw2fhA7eJCBJtTfJl+EEncCw==",
+ "version": "5.13.3",
+ "resolved": "https://registry.npmjs.org/ra-core/-/ra-core-5.13.3.tgz",
+ "integrity": "sha512-EAUIK/PVDTvUv/ZM0uZFrSFBbE7iwGFrPwyGvPrIrqvbvpyYgxzE9AeP9kf3twDM0Ks9RQCIA5zGGraRwH199w==",
"license": "MIT",
"dependencies": {
- "@tanstack/react-query": "^5.83.0",
"date-fns": "^3.6.0",
"eventemitter3": "^5.0.1",
"inflection": "^3.0.0",
@@ -9492,6 +9491,7 @@
"react-is": "^18.2.0 || ^19.0.0"
},
"peerDependencies": {
+ "@tanstack/react-query": "^5.83.0",
"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0",
"react-hook-form": "^7.65.0",
@@ -9524,22 +9524,22 @@
}
},
"node_modules/ra-i18n-polyglot": {
- "version": "5.13.1",
- "resolved": "https://registry.npmjs.org/ra-i18n-polyglot/-/ra-i18n-polyglot-5.13.1.tgz",
- "integrity": "sha512-/jh7Auir8zSeby3H0sCS4po1pXhvvImcDnQtiUzwa8P0vK/nFd22s2BxENOkq/XtGf0nSLGu7odCLkimtTH6QQ==",
+ "version": "5.13.3",
+ "resolved": "https://registry.npmjs.org/ra-i18n-polyglot/-/ra-i18n-polyglot-5.13.3.tgz",
+ "integrity": "sha512-qNKckbYJVmlbBX7P/tOYVQ+SPsDAs4SexGPS5BrEb2JvfWHvT9uUWokyauSLJJLIcorZOpsLwKGxTIkcDIAvFA==",
"license": "MIT",
"dependencies": {
"node-polyglot": "^2.2.2",
- "ra-core": "^5.13.1"
+ "ra-core": "^5.13.3"
}
},
"node_modules/ra-language-english": {
- "version": "5.13.1",
- "resolved": "https://registry.npmjs.org/ra-language-english/-/ra-language-english-5.13.1.tgz",
- "integrity": "sha512-JGe29ujMdsOCaP/6Cz5Q/jIUwUw/NOTqIj5S0ZQHY4KzMQUCiv/5BQhma4GjmAvD2mbQFBRF1mN1Sf3rgfZXXg==",
+ "version": "5.13.3",
+ "resolved": "https://registry.npmjs.org/ra-language-english/-/ra-language-english-5.13.3.tgz",
+ "integrity": "sha512-50YQfBsPzs7O8rpAd8U0H1g1ZP1H4c0RrRSjlbK1/7Y/bfqLVQEh2Edy7HjHYbc/nQfdaGjVTqG6RzhtWYk8iQ==",
"license": "MIT",
"dependencies": {
- "ra-core": "^5.13.1"
+ "ra-core": "^5.13.3"
}
},
"node_modules/ra-supabase-core": {
@@ -9674,9 +9674,9 @@
}
},
"node_modules/react-hook-form": {
- "version": "7.66.0",
- "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.66.0.tgz",
- "integrity": "sha512-xXBqsWGKrY46ZqaHDo+ZUYiMUgi8suYu5kdrS20EG8KiL7VRQitEbNjm+UcrDYrNi1YLyfpmAeGjCZYXLT9YBw==",
+ "version": "7.68.0",
+ "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.68.0.tgz",
+ "integrity": "sha512-oNN3fjrZ/Xo40SWlHf1yCjlMK417JxoSJVUXQjGdvdRCU07NTFei1i1f8ApUAts+IVh14e4EdakeLEA+BEAs/Q==",
"license": "MIT",
"engines": {
"node": ">=18.0.0"
@@ -9776,9 +9776,9 @@
}
},
"node_modules/react-router": {
- "version": "7.9.6",
- "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.9.6.tgz",
- "integrity": "sha512-Y1tUp8clYRXpfPITyuifmSoE2vncSME18uVLgaqyxh9H35JWpIfzHo+9y3Fzh5odk/jxPW29IgLgzcdwxGqyNA==",
+ "version": "7.10.1",
+ "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.10.1.tgz",
+ "integrity": "sha512-gHL89dRa3kwlUYtRQ+m8NmxGI6CgqN+k4XyGjwcFoQwwCWF6xXpOCUlDovkXClS0d0XJN/5q7kc5W3kiFEd0Yw==",
"license": "MIT",
"dependencies": {
"cookie": "^1.0.1",
@@ -9798,13 +9798,13 @@
}
},
"node_modules/react-router-dom": {
- "version": "7.9.6",
- "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.9.6.tgz",
- "integrity": "sha512-2MkC2XSXq6HjGcihnx1s0DBWQETI4mlis4Ux7YTLvP67xnGxCvq+BcCQSO81qQHVUTM1V53tl4iVVaY5sReCOA==",
+ "version": "7.10.1",
+ "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.10.1.tgz",
+ "integrity": "sha512-JNBANI6ChGVjA5bwsUIwJk7LHKmqB4JYnYfzFwyp2t12Izva11elds2jx7Yfoup2zssedntwU0oZ5DEmk5Sdaw==",
"license": "MIT",
"peer": true,
"dependencies": {
- "react-router": "7.9.6"
+ "react-router": "7.10.1"
},
"engines": {
"node": ">=20.0.0"
diff --git a/package.json b/package.json
index a9aaf8d4..f65308ed 100644
--- a/package.json
+++ b/package.json
@@ -40,7 +40,7 @@
"@radix-ui/react-tabs": "^1.1.12",
"@radix-ui/react-tooltip": "^1.2.8",
"@tailwindcss/vite": "^4.1.11",
- "@tanstack/react-query": "^5.90.8",
+ "@tanstack/react-query": "^5.90.12",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"cmdk": "^1.1.1",
@@ -53,10 +53,10 @@
"next-themes": "^0.4.6",
"papaparse": "^5.5.3",
"query-string": "^7.1.3",
- "ra-core": "^5.13.1",
+ "ra-core": "^5.13.3",
"ra-data-fakerest": "^5.10.0",
- "ra-i18n-polyglot": "^5.13.1",
- "ra-language-english": "^5.13.1",
+ "ra-i18n-polyglot": "^5.13.3",
+ "ra-language-english": "^5.13.3",
"ra-supabase-core": "^3.5.2",
"ra-supabase-language-english": "^3.5.0",
"react": "^19.1.0",
@@ -64,8 +64,8 @@
"react-dom": "^19.1.0",
"react-dropzone": "^14.3.8",
"react-error-boundary": "^6.0.0",
- "react-hook-form": "^7.66.0",
- "react-router": "^7.9.6",
+ "react-hook-form": "^7.68.0",
+ "react-router": "^7.10.1",
"rollup-plugin-visualizer": "^6.0.3",
"sonner": "^2.0.7",
"tailwind-merge": "^3.4.0",
diff --git a/src/components/admin/admin.tsx b/src/components/admin/admin.tsx
index ffcc3294..aa591fcf 100644
--- a/src/components/admin/admin.tsx
+++ b/src/components/admin/admin.tsx
@@ -15,10 +15,26 @@ import { AuthCallback } from "@/components/admin/authentication";
const defaultStore = localStorageStore();
+/**
+ * Context provider for the Admin component.
+ *
+ * Wraps CoreAdminContext to provide core admin functionality including data provider,
+ * auth provider, i18n provider, and store access to child components.
+ *
+ * @internal
+ */
const AdminContext = (props: CoreAdminContextProps) => (
<CoreAdminContext {...props} />
);
+/**
+ * UI component for the Admin application.
+ *
+ * Wraps CoreAdminUI with theme provider and handles telemetry reporting.
+ * Provides the main layout, login page, ready page, and authentication callback.
+ *
+ * @internal
+ */
const AdminUI = (props: CoreAdminUIProps) => (
<ThemeProvider>
<CoreAdminUI
@@ -31,6 +47,37 @@ const AdminUI = (props: CoreAdminUIProps) => (
</ThemeProvider>
);
+/**
+ * Root component of a shadcn-admin-kit application.
+ *
+ * Creates context providers to allow its children to access the app configuration.
+ * Renders the main routes and layout, and delegates content area rendering to Resource children.
+ * Combines AdminContext and AdminUI to provide a complete admin interface.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/admin/ Admin documentation}
+ *
+ * @example
+ * // Basic usage with dataProvider and Resources
+ * import { Admin } from "@/components/admin";
+ * import { Resource } from 'ra-core';
+ * import simpleRestProvider from 'ra-data-simple-rest';
+ *
+ * const App = () => (
+ * <Admin dataProvider={simpleRestProvider('http://path.to.my.api')}>
+ * <Resource name="posts" list={PostList} />
+ * </Admin>
+ * );
+ *
+ * @example
+ * // With authentication and i18n
+ * <Admin
+ * dataProvider={dataProvider}
+ * authProvider={authProvider}
+ * i18nProvider={i18nProvider}
+ * >
+ * <Resource name="posts" list={PostList} edit={PostEdit} />
+ * </Admin>
+ */
export const Admin = (props: CoreAdminProps) => {
const {
accessDenied,
diff --git a/src/components/admin/app-sidebar.tsx b/src/components/admin/app-sidebar.tsx
index 9fe04696..4f3ad119 100644
--- a/src/components/admin/app-sidebar.tsx
+++ b/src/components/admin/app-sidebar.tsx
@@ -23,6 +23,18 @@ import {
import { Skeleton } from "@/components/ui/skeleton";
import { House, List, Shell } from "lucide-react";
+/**
+ * Navigation sidebar displaying menu items, allowing users to navigate between different sections of the application.
+ *
+ * The sidebar can collapse to an icon-only view and renders as a collapsible drawer on mobile devices.
+ * It automatically includes links to the dashboard (if defined) and all list views defined in Resource components.
+ *
+ * Included in the default Layout component
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/appsidebar AppSidebar documentation}
+ * @see {@link https://ui.shadcn.com/docs/components/sidebar shadcn/ui Sidebar component}
+ * @see layout.tsx
+ */
export function AppSidebar() {
const hasDashboard = useHasDashboard();
const resources = useResourceDefinitions();
@@ -74,6 +86,15 @@ export function AppSidebar() {
);
}
+/**
+ * Menu item for the dashboard link in the sidebar.
+ *
+ * This component renders a sidebar menu item that links to the dashboard page.
+ * It displays as active when the user is on the dashboard route.
+ *
+ * @example
+ * <DashboardMenuItem onClick={handleClick} />
+ */
export const DashboardMenuItem = ({ onClick }: { onClick?: () => void }) => {
const translate = useTranslate();
const label = translate("ra.page.dashboard", {
@@ -92,6 +113,16 @@ export const DashboardMenuItem = ({ onClick }: { onClick?: () => void }) => {
);
};
+/**
+ * Menu item for a resource link in the sidebar.
+ *
+ * This component renders a sidebar menu item that links to a resource's list view.
+ * It checks permissions using canAccess and displays as active when the user is viewing that resource.
+ * The component icon and label are derived from the resource definition.
+ *
+ * @example
+ * <ResourceMenuItem key={name} name="posts" onClick={handleClick} />
+ */
export const ResourceMenuItem = ({
name,
onClick,
diff --git a/src/components/admin/array-field.tsx b/src/components/admin/array-field.tsx
index 1550dc41..5da8972e 100644
--- a/src/components/admin/array-field.tsx
+++ b/src/components/admin/array-field.tsx
@@ -2,6 +2,40 @@ import type { ReactNode } from "react";
import type { RaRecord, UseListOptions, UseFieldValueOptions } from "ra-core";
import { ListContextProvider, useList, useFieldValue } from "ra-core";
+/**
+ * Reads an array field value, puts it in a ListContext and renders its children.
+ *
+ * This field enables the use of list rendering components like SingleFieldList or
+ * DataTable to display array data.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/arrayfield/ ArrayField documentation}
+ *
+ * @example
+ * import {
+ * Show,
+ * ArrayField,
+ * RecordField,
+ * SingleFieldList,
+ * BadgeField,
+ * } from '@/components/admin';
+ *
+ * const PostShow = () => (
+ * <Show>
+ * <div className="flex flex-col gap-4">
+ * <RecordField source="title" />
+ * <RecordField source="content" />
+ * <RecordField source="tags">
+ * <ArrayField source="tags">
+ * <SingleFieldList>
+ * <BadgeField source="name" />
+ * </SingleFieldList>
+ * </ArrayField>
+ * </RecordField>
+ * </div>
+ * </Show>
+ * );
+ */
export const ArrayField = <RecordType extends RaRecord = RaRecord>(
props: ArrayFieldProps<RecordType>,
) => {
diff --git a/src/components/admin/array-input.tsx b/src/components/admin/array-input.tsx
index f64f2cdd..f3328dfc 100644
--- a/src/components/admin/array-input.tsx
+++ b/src/components/admin/array-input.tsx
@@ -23,6 +23,41 @@ import { Skeleton } from "../ui/skeleton";
import { InputHelperText } from "@/components/admin/input-helper-text";
import { FormError, FormField } from "@/components/admin/form";
+/**
+ * Creates a list of sub-forms for editing arrays of data embedded inside a record.
+ *
+ * Use `<ArrayInput>` when you need to edit array fields like order items, tags, or any
+ * repeatable embedded data. Requires a form iterator child (typically `<SimpleFormIterator>`)
+ * to render and manage individual array items.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/arrayinput/ ArrayInput documentation}
+ *
+ * @example
+ * import {
+ * Edit,
+ * SimpleForm,
+ * TextInput,
+ * NumberInput,
+ * ArrayInput,
+ * SimpleFormIterator,
+ * } from '@/components/admin';
+ *
+ * const OrderEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="customer" />
+ * <TextInput source="date" type="date" />
+ * <ArrayInput source="items">
+ * <SimpleFormIterator inline>
+ * <TextInput source="name" />
+ * <NumberInput source="price" />
+ * <NumberInput source="quantity" />
+ * </SimpleFormIterator>
+ * </ArrayInput>
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const ArrayInput = (props: ArrayInputProps) => {
const {
className,
diff --git a/src/components/admin/authentication.tsx b/src/components/admin/authentication.tsx
index bdd5311a..da94d48c 100644
--- a/src/components/admin/authentication.tsx
+++ b/src/components/admin/authentication.tsx
@@ -6,19 +6,21 @@ import { Button } from "@/components/ui/button";
import { Loading } from "@/components/admin/loading";
/**
- * A standalone page to be used in a route called by external authentication services (e.g. OAuth)
- * after the user has been authenticated.
+ * A standalone page to be used as a redirection target for external authentication services (e.g. OAuth)
*
- * Copy and adapt this component to implement your own login logic
- * (e.g. to show a different waiting screen, start onboarding procedures, etc.).
+ * It displays a loading indicator while processing the authentication response,
+ * then redirects to the admin app or shows an error message if authentication fails.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/security/ Security documentation}
*
* @example
- * import MyAuthCallbackPage from './MyAuthCallbackPage';
- * const App = () => (
- * <Admin authCallbackPage={MyAuthCallbackPage} authProvider={authProvider}>
- * ...
- * </Admin>
- * );
+ * import { Admin } from "@/components/admin";
+ * import MyAuthCallbackPage from './MyAuthCallbackPage';
+ * const App = () => (
+ * <Admin authCallbackPage={MyAuthCallbackPage} authProvider={authProvider}>
+ * ...
+ * </Admin>
+ * );
*/
export const AuthCallback = () => {
const { error } = useHandleAuthCallback();
@@ -38,6 +40,20 @@ export interface AuthErrorProps {
message?: string;
}
+/**
+ * Authentication error page displayed when authentication fails.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/security/ Security documentation}
+ *
+ * @example
+ * import { Admin } from "@/components/admin";
+ * import MyAuthErrorPage from './MyAuthErrorPage';
+ * const App = () => (
+ * <Admin authenticationError={MyAuthErrorPage} authProvider={authProvider}>
+ * ...
+ * </Admin>
+ * );
+ */
export const AuthError = (props: AuthErrorProps) => {
const {
className,
diff --git a/src/components/admin/autocomplete-array-input.tsx b/src/components/admin/autocomplete-array-input.tsx
index 24bf8cf6..8f367333 100644
--- a/src/components/admin/autocomplete-array-input.tsx
+++ b/src/components/admin/autocomplete-array-input.tsx
@@ -27,6 +27,40 @@ import {
import { InputHelperText } from "./input-helper-text";
import { useCallback } from "react";
+/**
+ * Form control that lets users choose multiple values from a list using a dropdown with autocompletion.
+ *
+ * This input allows editing array values with a searchable dropdown interface and displays selected items as removable badges.
+ * Works seamlessly inside ReferenceArrayInput for editing many-to-many relationships.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/autocompletearrayinput/ AutocompleteArrayInput documentation}
+ *
+ * @example
+ * import {
+ * Create,
+ * SimpleForm,
+ * AutocompleteArrayInput,
+ * ReferenceArrayInput,
+ * } from '@/components/admin';
+ *
+ * const PostCreate = () => (
+ * <Create>
+ * <SimpleForm>
+ * <AutocompleteArrayInput
+ * source="tags"
+ * choices={[
+ * { id: 'tech', name: 'Tech' },
+ * { id: 'news', name: 'News' },
+ * { id: 'lifestyle', name: 'Lifestyle' },
+ * ]}
+ * />
+ * <ReferenceArrayInput source="tag_ids" reference="tags">
+ * <AutocompleteArrayInput />
+ * </ReferenceArrayInput>
+ * </SimpleForm>
+ * </Create>
+ * );
+ */
export const AutocompleteArrayInput = (
props: Omit<InputProps, "source"> &
Partial<Pick<InputProps, "source">> &
diff --git a/src/components/admin/autocomplete-input.tsx b/src/components/admin/autocomplete-input.tsx
index b069f777..5b9b4a79 100644
--- a/src/components/admin/autocomplete-input.tsx
+++ b/src/components/admin/autocomplete-input.tsx
@@ -38,6 +38,40 @@ import {
useSupportCreateSuggestion,
} from "@/hooks/useSupportCreateSuggestion";
+/**
+ * Form control that lets users choose a value from a list using a dropdown with autocompletion.
+ *
+ * This input allows editing scalar values with a searchable dropdown interface. It supports creating
+ * new choices on the fly and works seamlessly inside ReferenceInput for editing foreign key relationships.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/autocompleteinput/ AutocompleteInput documentation}
+ *
+ * @example
+ * import {
+ * Create,
+ * SimpleForm,
+ * AutocompleteInput,
+ * ReferenceInput,
+ * } from '@/components/admin';
+ *
+ * const PostCreate = () => (
+ * <Create>
+ * <SimpleForm>
+ * <AutocompleteInput
+ * source="category"
+ * choices={[
+ * { id: 'tech', name: 'Tech' },
+ * { id: 'lifestyle', name: 'Lifestyle' },
+ * { id: 'people', name: 'People' },
+ * ]}
+ * />
+ * <ReferenceInput label="Author" source="author_id" reference="authors">
+ * <AutocompleteInput />
+ * </ReferenceInput>
+ * </SimpleForm>
+ * </Create>
+ * );
+ */
export const AutocompleteInput = (
props: Omit<InputProps, "source"> &
Omit<SupportCreateSuggestionOptions, "handleChange" | "filter"> &
diff --git a/src/components/admin/badge-field.tsx b/src/components/admin/badge-field.tsx
index 7d6ba368..39aaab30 100644
--- a/src/components/admin/badge-field.tsx
+++ b/src/components/admin/badge-field.tsx
@@ -6,6 +6,34 @@ import type { FieldProps } from "@/lib/field.type";
type BadgeProps = React.ComponentProps<typeof Badge>;
+/**
+ * Displays a text value inside a styled badge component.
+ *
+ * This field wraps values in a Badge UI component with customizable variants (default, outline, secondary, destructive).
+ * Use it to highlight status values, tags, or categorical information.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/badgefield/ BadgeField documentation}
+ * @see {@link https://ui.shadcn.com/docs/components/badge Badge documentation}
+ *
+ * @example
+ * import {
+ * List,
+ * DataTable,
+ * BadgeField,
+ * } from '@/components/admin';
+ *
+ * const OrderList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="id" />
+ * <DataTable.Col>
+ * <BadgeField source="status" variant="outline" />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
+ */
export const BadgeField = <RecordType extends RaRecord = RaRecord>({
defaultValue,
source,
diff --git a/src/components/admin/boolean-input.tsx b/src/components/admin/boolean-input.tsx
index 1828992c..55435c04 100644
--- a/src/components/admin/boolean-input.tsx
+++ b/src/components/admin/boolean-input.tsx
@@ -4,6 +4,34 @@ import { FormError, FormField, FormLabel } from "@/components/admin/form";
import { useInput, FieldTitle } from "ra-core";
import { InputHelperText } from "./input-helper-text";
+/**
+ * Toggle switch for boolean (true/false) values.
+ *
+ * Use `<BooleanInput>` for binary settings like "is published", "is active", or feature flags.
+ * Leverages shadcn's Switch component for a native-looking toggle. Note: this input doesn't
+ * support `null` values—use `<SelectInput>` for nullable booleans.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/booleaninput/ BooleanInput documentation}
+ * @see {@link https://ui.shadcn.com/docs/components/switch Switch documentation}
+ *
+ * @example
+ * import {
+ * Edit,
+ * SimpleForm,
+ * BooleanInput,
+ * TextInput,
+ * } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <BooleanInput source="is_published" />
+ * <BooleanInput source="allow_comments" />
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const BooleanInput = (props: BooleanInputProps) => {
const {
className,
diff --git a/src/components/admin/breadcrumb.tsx b/src/components/admin/breadcrumb.tsx
index 84b2741c..be4e5e38 100644
--- a/src/components/admin/breadcrumb.tsx
+++ b/src/components/admin/breadcrumb.tsx
@@ -23,6 +23,38 @@ import {
import { useIsMobile } from "@/hooks/use-mobile";
import { Translate } from "ra-core";
+/**
+ * A breadcrumb navigation component with mobile drawer support.
+ *
+ * Renders breadcrumb navigation in the app header via portal. On mobile, shows a drawer with
+ * ellipsis for long breadcrumb trails. Use Breadcrumb.Item and Breadcrumb.PageItem as children.
+ *
+ * CRUD pages already include a Breadcrumb by default; set `disableBreadcrumb` to hide the
+ * breadcrumb and/or provide your own.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/breadcrumb/ Breadcrumb documentation}
+ * @see {@link https://ui.shadcn.com/docs/components/breadcrumb Breadcrumb UI documentation}
+ *
+ * @example
+ * import { Edit, Breadcrumb, SimpleForm } from "@/components/admin";
+ * import { RecordRepresentation } from 'ra-core';
+ * import { Link } from "react-router";
+ *
+ * const PostEdit = () => (
+ * <Edit disableBreadcrumb>
+ * <Breadcrumb>
+ * <Breadcrumb.Item><Link to="/">Home</Link></Breadcrumb.Item>
+ * <Breadcrumb.Item><Link to="/posts">Articles</Link></Breadcrumb.Item>
+ * <Breadcrumb.PageItem>
+ * Edit Article "<RecordRepresentation />"
+ * </Breadcrumb.Item>
+ * </Breadcrumb>
+ * <SimpleForm>
+ * ...
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const Breadcrumb = ({ children, ref }: BreadcrumbProps) => {
const breadcrumbPortal = document.getElementById("breadcrumb");
const isMobile = useIsMobile();
diff --git a/src/components/admin/bulk-actions-toolbar.tsx b/src/components/admin/bulk-actions-toolbar.tsx
index 32388e88..f48b3adc 100644
--- a/src/components/admin/bulk-actions-toolbar.tsx
+++ b/src/components/admin/bulk-actions-toolbar.tsx
@@ -6,6 +6,11 @@ import { BulkDeleteButton } from "@/components/admin/bulk-delete-button";
import { X } from "lucide-react";
import { BulkExportButton } from "./bulk-export-button";
+/**
+ * Default children for BulkActionsToolbar. Renders BulkExportButton and BulkDeleteButton.
+ *
+ * @internal
+ */
export function BulkActionsToolbarChildren() {
return (
<>
@@ -15,6 +20,31 @@ export function BulkActionsToolbarChildren() {
);
}
+/**
+ * A sticky toolbar that appears when rows are selected in a DataTable.
+ *
+ * Shows the number of selected rows and provides bulk action buttons. Automatically hidden
+ * when no rows are selected. Positioned at the bottom center of the screen.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/bulkactionstoolbar/ BulkActionsToolbar documentation}
+ *
+ * @example
+ * import { BulkActionsToolbar, BulkDeleteButton } from '@/components/admin';
+ *
+ * const CustomBulkToolbar = () => (
+ * <BulkActionsToolbar>
+ * <BulkDeleteButton />
+ * </BulkActionsToolbar>
+ * );
+ *
+ * const PostList = () => (
+ * <List>
+ * <DataTable bulkActionsToolbar={<CustomBulkToolbar />}>
+ * ...
+ * </DataTable>
+ * </List>
+ * );
+ */
export const BulkActionsToolbar = ({
children = <BulkActionsToolbarChildren />,
}: {
diff --git a/src/components/admin/bulk-delete-button.tsx b/src/components/admin/bulk-delete-button.tsx
index 888ae4fc..de316427 100644
--- a/src/components/admin/bulk-delete-button.tsx
+++ b/src/components/admin/bulk-delete-button.tsx
@@ -5,6 +5,32 @@ import { Translate, useBulkDeleteController } from "ra-core";
import { cn } from "@/lib/utils";
import type { ReactNode } from "react";
+/**
+ * A button that deletes multiple selected records at once.
+ *
+ * Allows to delete selected records in a DataTable. Use within
+ * the bulkActionsButtons prop of DataTable or inside BulkActionsToolbar.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/bulkdeletebutton/ BulkDeleteButton documentation}
+ *
+ * @example
+ * import { BulkDeleteButton, BulkExportButton, DataTable, List } from '@/components/admin';
+ *
+ * export const PostList = () => (
+ * <List>
+ * <DataTable
+ * bulkActionsButtons={
+ * <>
+ * <BulkExportButton />
+ * <BulkDeleteButton />
+ * </>
+ * }
+ * >
+ * ...
+ * </DataTable>
+ * </List>
+ * );
+ */
export const BulkDeleteButton = <
RecordType extends RaRecord = any,
MutationOptionsError = unknown,
diff --git a/src/components/admin/bulk-export-button.tsx b/src/components/admin/bulk-export-button.tsx
index 798d7328..865cd9f1 100644
--- a/src/components/admin/bulk-export-button.tsx
+++ b/src/components/admin/bulk-export-button.tsx
@@ -9,7 +9,9 @@ import { Button } from "../ui/button";
*
* To be used inside the <DataTable bulkActionsButtons> prop.
*
- * @example // basic usage
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/bulkexportbutton/ BulkExportButton documentation}
+ *
+ * @example
* import { BulkDeleteButton, BulkExportButton, DataTable, List } from '@/components/admin';
*
* export const PostList = () => (
diff --git a/src/components/admin/cancel-button.tsx b/src/components/admin/cancel-button.tsx
index 93834e49..22ea21e6 100644
--- a/src/components/admin/cancel-button.tsx
+++ b/src/components/admin/cancel-button.tsx
@@ -4,6 +4,31 @@ import { useNavigate } from "react-router";
import { Button } from "../ui/button";
+/**
+ * A button that navigates back to the previous page.
+ *
+ * Commonly used in form toolbars alongside SaveButton.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/cancelbutton/ CancelButton documentation}
+ *
+ * @example
+ * import { CancelButton, SaveButton, SimpleForm } from '@/components/admin';
+ *
+ * const FormToolbar = () => (
+ * <div className="flex flex-row gap-2 justify-end">
+ * <CancelButton />
+ * <SaveButton />
+ * </div>
+ * );
+ *
+ * const PostEdit = () => (
+ * <Edit>
+ * <SimpleForm toolbar={<FormToolbar />}>
+ * ...
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export function CancelButton(props: React.ComponentProps<"button">) {
const navigate = useNavigate();
return (
diff --git a/src/components/admin/columns-button.tsx b/src/components/admin/columns-button.tsx
index db0d4914..282a60d8 100644
--- a/src/components/admin/columns-button.tsx
+++ b/src/components/admin/columns-button.tsx
@@ -42,22 +42,24 @@ import { cn } from "@/lib/utils";
/**
* Renders a button that lets users show / hide columns in a DataTable
*
- * @example
- * import { ColumnsButton, DataTable } from 'shadcn-admin-kit';
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/columnsbutton/ ColumnsButton documentation}
*
- * const PostListActions = () => (
- * <div className="flex items-center gap-2">
- <ColumnsButton />
- <FilterButton />
- * </div>
- * );
+ * @example
+ * import { List, DataTable, EditButton, CreateButton, ExportButton, ColumnsButton } from '@/components/admin';
*
- * const PostList = () => (
- * <List actions={<PostListActions />}>
+ * const PostsList = () => (
+ * <List
+ * actions={<>
+ * <ColumnsButton />
+ * <CreateButton />
+ * <ExportButton />
+ * </>}
+ * >
* <DataTable>
* <DataTable.Col source="title" />
- * <DataTable.Col source="author" />
- ...
+ * <DataTable.Col source="body" />
+ * <DataTable.Col source="updated_at" />
+ * <EditButton />
* </DataTable>
* </List>
* );
diff --git a/src/components/admin/confirm.tsx b/src/components/admin/confirm.tsx
index 1f3bdb59..6cc08b77 100644
--- a/src/components/admin/confirm.tsx
+++ b/src/components/admin/confirm.tsx
@@ -13,6 +13,58 @@ import {
DialogTitle,
} from "@/components/ui/dialog";
+/**
+ * Generic confirmation dialog component for destructive actions.
+ *
+ * Displays a dialog with customizable title, content, and action buttons.
+ * Used internally for delete operations and other confirmations.
+ * Supports custom icons, button labels, and loading states.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/confirm Confirm documentation}
+ *
+ * @example
+ * import { useState } from "react";
+ * import { useDelete, useRecordContext, useResourceContext, useRedirect } from "ra-core";
+ * import { Button } from "@/components/ui/button";
+ * import { Confirm } from "@/components/admin/confirm";
+ *
+ * const DeleteButton = () => {
+ * const resource = useResourceContext();
+ * const record = useRecordContext();
+ * const [isOpen, setIsOpen] = useState(false);
+ * const [deleteOne, { isPending }] = useDelete();
+ * const redirect = useRedirect();
+ *
+ * const handleDelete = () => {
+ * deleteOne(
+ * resource,
+ * { id: record?.id, previousData: record },
+ * {
+ * onSuccess: () => {
+ * setIsOpen(false);
+ * redirect("list", resource);
+ * },
+ * },
+ * );
+ * };
+ *
+ * return (
+ * <>
+ * <Button variant="destructive" onClick={() => setIsOpen(true)}>
+ * Delete
+ * </Button>
+ * <Confirm
+ * isOpen={isOpen}
+ * title="Are you sure you want to delete this element?"
+ * content="This action cannot be undone."
+ * onConfirm={handleDelete}
+ * onClose={() => setIsOpen(false)}
+ * loading={isPending}
+ * />
+ * </>
+ * );
+ * };
+ */
export const Confirm = (props: ConfirmProps) => {
const {
className,
diff --git a/src/components/admin/count.tsx b/src/components/admin/count.tsx
index 757997c6..84bb991b 100644
--- a/src/components/admin/count.tsx
+++ b/src/components/admin/count.tsx
@@ -10,23 +10,26 @@ import { CircleX, LoaderCircle } from "lucide-react";
import { Link } from "react-router";
/**
- * Fetch and render the number of records of a given resource
+ * Fetches and displays the item count for a resource.
*
- * Relies on dataProvider.getList() returning a total property
+ * Uses dataProvider.getList() with minimal pagination to fetch the total count.
+ * Displays a loading spinner while fetching and an error icon on failure.
+ * By default, uses the current resource from ResourceContext.
*
- * @example // Display the number of records in the current resource (based on ResourceContext)
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/count/ Count documentation}
+ *
+ * @example
+ * import { Count } from '@/components/admin';
+ * // Display the number of records in the current resource
* <Count />
*
- * @example // Display the number of posts
+ * @example
+ * // Display the number of posts
* <Count resource="posts" />
*
- * @example // Display the number of published posts
- * <Count resource="posts" filter={{ is_published: true }}/>
- *
- * @example // Display the number of posts, with a custom Typography variant
- * <Count resource="posts" variant="h1" />
- *
- * @see ReferenceManyCount for a similar component which fetches the number of records related to the current one
+ * @example
+ * // Display the number of published posts with a link
+ * <Count resource="posts" filter={{ is_published: true }} link />
*/
export const Count = (props: CountProps) => {
const {
diff --git a/src/components/admin/create-button.tsx b/src/components/admin/create-button.tsx
index 4d3621b8..24f1721c 100644
--- a/src/components/admin/create-button.tsx
+++ b/src/components/admin/create-button.tsx
@@ -9,6 +9,27 @@ export type CreateButtonProps = {
resource?: string;
};
+/**
+ * A button that navigates to the create page for a resource.
+ *
+ * Automatically uses the current resource unless overridden.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/createbutton/ CreateButton documentation}
+ *
+ * @example
+ * import { CreateButton, List, ExportButton } from '@/components/admin';
+ *
+ * const PostList = () => (
+ * <List
+ * actions={<>
+ * <CreateButton />
+ * <ExportButton />
+ * </>}
+ * >
+ * ...
+ * </List>
+ * );
+ */
export const CreateButton = ({
label,
resource: targetResource,
diff --git a/src/components/admin/create.tsx b/src/components/admin/create.tsx
index a44a3626..61289c1b 100644
--- a/src/components/admin/create.tsx
+++ b/src/components/admin/create.tsx
@@ -19,6 +19,26 @@ import { cn } from "@/lib/utils";
export type CreateProps = CreateViewProps & CreateBaseProps;
+/**
+ * A complete create page with breadcrumb, title, and actions.
+ *
+ * Combines data fetching, form context, and UI layout for creating new records. Renders breadcrumb
+ * navigation, page title, and wraps your form components.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/create/ Create documentation}
+ *
+ * @example
+ * import { Create, SimpleForm, TextInput } from '@/components/admin';
+ *
+ * export const PostCreate = () => (
+ * <Create>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <TextInput source="body" />
+ * </SimpleForm>
+ * </Create>
+ * );
+ */
export const Create = ({
actions,
children,
@@ -47,6 +67,11 @@ export type CreateViewProps = {
title?: ReactNode | string | false;
};
+/**
+ * The view component for Create pages with layout and UI.
+ *
+ * @internal
+ */
export const CreateView = ({
actions,
disableBreadcrumb,
diff --git a/src/components/admin/data-table.tsx b/src/components/admin/data-table.tsx
index 859d04ca..e5124879 100644
--- a/src/components/admin/data-table.tsx
+++ b/src/components/admin/data-table.tsx
@@ -60,6 +60,32 @@ import {
const defaultBulkActionButtons = <BulkActionsToolbarChildren />;
+/**
+ * A powerful data table with sorting, selection, and column customization.
+ *
+ * Displays records in a table with built-in support for column sorting, bulk selection, row clicks,
+ * and column visibility controls. Use DataTable.Col to define columns.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/datatable/ DataTable documentation}
+ *
+ * @example
+ * import { List, DataTable, ReferenceField, EditButton } from '@/components/admin';
+ *
+ * export const PostList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="id" />
+ * <DataTable.Col label="User">
+ * <ReferenceField source="user_id" reference="users" />
+ * </DataTable.Col>
+ * <DataTable.Col source="title" />
+ * <DataTable.Col>
+ * <EditButton />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
+ */
export function DataTable<RecordType extends RaRecord = RaRecord>(
props: DataTableProps<RecordType>,
) {
diff --git a/src/components/admin/date-field.tsx b/src/components/admin/date-field.tsx
index c04deec1..9b7f1496 100644
--- a/src/components/admin/date-field.tsx
+++ b/src/components/admin/date-field.tsx
@@ -4,30 +4,6 @@ import { useFieldValue, useTranslate } from "ra-core";
import { genericMemo } from "@/lib/genericMemo";
import type { FieldProps } from "@/lib/field.type";
-/**
- * Display a date value as a locale string.
- *
- * Uses Intl.DateTimeFormat() if available, passing the locales and options props as arguments.
- * If Intl is not available, it outputs date as is (and ignores the locales and options props).
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString
- * @example
- * <DateField source="published_at" />
- * // renders the record { id: 1234, published_at: new Date('2012-11-07') } as
- * <span>07/11/2012</span>
- *
- * <DateField source="published_at" className="red" />
- * // renders the record { id: 1234, new Date('2012-11-07') } as
- * <span class="red">07/11/2012</span>
- *
- * <DateField source="share" options={{ weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }} />
- * // renders the record { id: 1234, new Date('2012-11-07') } as
- * <span>Wednesday, November 7, 2012</span>
- *
- * <DateField source="price" locales="fr-FR" options={{ weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }} />
- * // renders the record { id: 1234, new Date('2012-11-07') } as
- * <span>mercredi 7 novembre 2012</span>
- */
const DateFieldImpl = <
// eslint-disable-next-line @typescript-eslint/no-explicit-any
RecordType extends Record<string, any> = Record<string, any>,
@@ -98,6 +74,36 @@ const DateFieldImpl = <
};
DateFieldImpl.displayName = "DateFieldImpl";
+/**
+ * Displays a date value with locale-specific formatting.
+ *
+ * This field automatically formats dates according to the user's locale using Intl.DateTimeFormat.
+ * It supports showing date only, time only, or both, with custom locales and formatting options.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/datefield/ DateField documentation}
+ *
+ * @example
+ * import {
+ * List,
+ * DataTable,
+ * DateField,
+ * } from '@/components/admin';
+ *
+ * const PostList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="title" />
+ * <DataTable.Col>
+ * <DateField source="published_at" />
+ * </DataTable.Col>
+ * <DataTable.Col>
+ * <DateField source="updated_at" showTime />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
+ */
export const DateField = genericMemo(DateFieldImpl);
export interface DateFieldProps<
diff --git a/src/components/admin/date-input.tsx b/src/components/admin/date-input.tsx
index 1f69e03c..48d4c880 100644
--- a/src/components/admin/date-input.tsx
+++ b/src/components/admin/date-input.tsx
@@ -12,19 +12,31 @@ import { InputHelperText } from "@/components/admin/input-helper-text";
import { cn } from "@/lib/utils";
/**
- * Form input to edit a Date string value in the "YYYY-MM-DD" format (e.g. '2021-06-23').
+ * Date picker input for editing date values in "YYYY-MM-DD" format.
*
- * Renders a date picker (the exact UI depends on the browser).
+ * Use `<DateInput>` for publication dates, deadlines, birthdays, or any date field. Renders
+ * a native browser date picker (appearance varies by browser). Automatically handles date parsing
+ * from ISO strings, Date objects, or timestamps.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/dateinput/ DateInput documentation}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date MDN documentation for input type="date"}
*
* @example
- * import { Edit, SimpleForm, DateInput } from 'react-admin';
+ * import {
+ * Edit,
+ * SimpleForm,
+ * DateInput,
+ * TextInput,
+ * } from '@/components/admin';
*
* const PostEdit = () => (
- * <Edit>
- * <SimpleForm>
- * <DateInput source="published_at" />
- * </SimpleForm>
- * </Edit>
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <DateInput source="published_at" />
+ * <DateInput source="expires_at" />
+ * </SimpleForm>
+ * </Edit>
* );
*
* @example
diff --git a/src/components/admin/date-time-input.tsx b/src/components/admin/date-time-input.tsx
index 53bbc6d2..590b7ba5 100644
--- a/src/components/admin/date-time-input.tsx
+++ b/src/components/admin/date-time-input.tsx
@@ -12,7 +12,32 @@ import { Input } from "@/components/ui/input";
import { InputHelperText } from "@/components/admin/input-helper-text";
/**
- * Input component for entering a date and a time with timezone, using the browser locale
+ * Date and time picker input for editing datetime values with timezone support.
+ *
+ * Use `<DateTimeInput>` for timestamps like "created at", "updated at", or scheduled events.
+ * Renders a native browser datetime-local picker. Expects and returns ISO 8601 formatted strings
+ * (e.g. '2025-11-17T10:10:32.390Z'), automatically converting other formats like Date objects or timestamps.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/datetimeinput/ DateTimeInput documentation}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local MDN documentation for input type="datetime-local"}
+ *
+ * @example
+ * import {
+ * Edit,
+ * SimpleForm,
+ * DateTimeInput,
+ * TextInput,
+ * } from '@/components/admin';
+ *
+ * const EventEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <DateTimeInput source="starts_at" />
+ * <DateTimeInput source="ends_at" />
+ * </SimpleForm>
+ * </Edit>
+ * );
*/
export const DateTimeInput = ({
className,
diff --git a/src/components/admin/delete-button.tsx b/src/components/admin/delete-button.tsx
index f6f3c233..0f0b52a1 100644
--- a/src/components/admin/delete-button.tsx
+++ b/src/components/admin/delete-button.tsx
@@ -30,6 +30,23 @@ export type DeleteButtonProps = {
| "link";
};
+/**
+ * A button that deletes a record with undo capability.
+ *
+ * Renders a destructive button that deletes the current record and shows an undo notification.
+ * Automatically redirects after deletion and works with the RecordContext.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/deletebutton/ DeleteButton documentation}
+ *
+ * @example
+ * import { DeleteButton, Edit } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <Edit actions={<DeleteButton />}>
+ * ...
+ * </Edit>
+ * );
+ */
export const DeleteButton = (props: DeleteButtonProps) => {
const {
label: labelProp,
diff --git a/src/components/admin/edit-button.tsx b/src/components/admin/edit-button.tsx
index 69dbeef8..10e01c8a 100644
--- a/src/components/admin/edit-button.tsx
+++ b/src/components/admin/edit-button.tsx
@@ -16,6 +16,27 @@ export type EditButtonProps = {
label?: string;
};
+/**
+ * A button that navigates to the edit page for a record.
+ *
+ * Works within RecordContext to automatically get the record ID.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/editbutton/ EditButton documentation}
+ *
+ * @example
+ * import { DataTable, EditButton } from '@/components/admin';
+ *
+ * const PostList = () => (
+ * <DataTable>
+ * <DataTable.Col source="title" />
+ * <DataTable.Col source="author" />
+ * <DataTable.Col source="published_at" />
+ * <DataTable.Col>
+ * <EditButton />
+ * </DataTable.Col>
+ * </DataTable>
+ * );
+ */
export const EditButton = (props: EditButtonProps) => {
const resource = useResourceContext(props);
const record = useRecordContext(props);
diff --git a/src/components/admin/edit-guesser.tsx b/src/components/admin/edit-guesser.tsx
index 9e52e747..fdda4c96 100644
--- a/src/components/admin/edit-guesser.tsx
+++ b/src/components/admin/edit-guesser.tsx
@@ -17,6 +17,26 @@ import { ReferenceInput } from "@/components/admin/reference-input";
import { AutocompleteInput } from "@/components/admin/autocomplete-input";
import { ReferenceArrayInput } from "@/components/admin/reference-array-input";
+/**
+ * An edit page that automatically generates a form from your data.
+ *
+ * Inspects the record to infer field types and automatically creates appropriate inputs.
+ * Useful for rapid prototyping. Logs generated code to console.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/edit/#scaffolding-an-edit-page EditGuesser documentation}
+ *
+ * @example
+ * import { Admin, EditGuesser } from '@/components/admin';
+ * import { Resource } from 'ra-core';
+ * import dataProvider from './dataProvider';
+ *
+ * const App = () => (
+ * <Admin dataProvider={dataProvider}>
+ * ...
+ * <Resource name="customers" edit={EditGuesser} />
+ * </Admin>
+ * );
+ */
export const EditGuesser = (props: { enableLog?: boolean }) => {
return (
<EditBase>
diff --git a/src/components/admin/edit.tsx b/src/components/admin/edit.tsx
index 8b196499..3c23138a 100644
--- a/src/components/admin/edit.tsx
+++ b/src/components/admin/edit.tsx
@@ -23,6 +23,30 @@ import { DeleteButton } from "./delete-button";
export interface EditProps extends EditViewProps, EditBaseProps {}
+/**
+ * A complete edit page with breadcrumb, title, and default actions.
+ *
+ * Combines data fetching, form context, and UI layout for editing records. Renders breadcrumb,
+ * page title, Show and Delete buttons, and wraps your form components.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/edit/ Edit documentation}
+ *
+ * @example
+ * import { Edit, SimpleForm, BooleanInput, TextInput } from "@/components/admin";
+ * import { required } from 'ra-core';
+ *
+ * export const CustomerEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="first_name" validate={required()} />
+ * <TextInput source="last_name" validate={required()} />
+ * <TextInput source="email" validate={required()} />
+ * <BooleanInput source="has_ordered" />
+ * <TextInput multiline source="notes" />
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const Edit = ({
actions,
children,
@@ -51,6 +75,11 @@ export interface EditViewProps {
className?: string;
}
+/**
+ * The view component for Edit pages with layout and UI.
+ *
+ * @internal
+ */
export const EditView = ({
disableBreadcrumb,
title,
diff --git a/src/components/admin/email-field.tsx b/src/components/admin/email-field.tsx
index 68d7a016..523c37ad 100644
--- a/src/components/admin/email-field.tsx
+++ b/src/components/admin/email-field.tsx
@@ -7,6 +7,7 @@ import { genericMemo } from "@/lib/genericMemo";
import type { FieldProps } from "@/lib/field.type";
const EmailFieldImpl = <
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
RecordType extends Record<string, any> = Record<string, any>,
>(
inProps: EmailFieldProps<RecordType>,
@@ -40,9 +41,30 @@ const EmailFieldImpl = <
};
EmailFieldImpl.displayName = "EmailFieldImpl";
+/**
+ * Displays an email address as a clickable mailto link.
+ *
+ * Click events are prevented from bubbling up, making it safe to use in DataTable rows with rowClick.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/emailfield/ EmailField documentation}
+ *
+ * @example
+ * import { List, DataTable, EmailField } from '@/components/admin';
+ *
+ * const UserList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="name" />
+ * <DataTable.Col source="email" field={EmailField} />
+ * </DataTable>
+ * </List>
+ * );
+ */
export const EmailField = genericMemo(EmailFieldImpl);
export interface EmailFieldProps<
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
RecordType extends Record<string, any> = Record<string, any>,
> extends FieldProps<RecordType>,
AnchorHTMLAttributes<HTMLAnchorElement> {}
diff --git a/src/components/admin/error.tsx b/src/components/admin/error.tsx
index 480a74a1..b64c3aec 100644
--- a/src/components/admin/error.tsx
+++ b/src/components/admin/error.tsx
@@ -1,5 +1,4 @@
import type { FallbackProps } from "react-error-boundary";
-
import { useResetErrorBoundaryOnLocationChange, Translate } from "ra-core";
import { CircleAlert, History } from "lucide-react";
import {
@@ -9,9 +8,16 @@ import {
AccordionTrigger,
} from "@/components/ui/accordion";
import { Button } from "@/components/ui/button";
-import type { HtmlHTMLAttributes } from "react";
-import { ErrorInfo } from "react";
+import type { HtmlHTMLAttributes, ErrorInfo } from "react";
+/**
+ * App-wide error component for displaying error boundaries.
+ *
+ * Displays the error message and a back button.
+ * In development mode, also shows the component stack trace in an expandable accordion.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/error Error documentation}
+ */
export const Error = (props: InternalErrorProps & {}) => {
const { error, errorInfo, resetErrorBoundary, ...rest } = props;
diff --git a/src/components/admin/export-button.tsx b/src/components/admin/export-button.tsx
index 7143426b..0738668c 100644
--- a/src/components/admin/export-button.tsx
+++ b/src/components/admin/export-button.tsx
@@ -11,6 +11,31 @@ import {
} from "ra-core";
import { Button } from "@/components/ui/button";
+/**
+ * A button that exports list data to a file.
+ *
+ * Respects current filters and sort order, with configurable maximum results.
+ * Use a custom exporter to customize the result and fetch related records.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/exportbutton/ ExportButton documentation}
+ *
+ * @example
+ * import { CreateButton, ExportButton, TopToolbar } from '@/components/admin';
+ *
+ * const PostListActions = () => (
+ * <>
+ * <FilterButton />
+ * <CreateButton />
+ * <ExportButton />
+ * </>
+ * );
+ *
+ * export const PostList = () => (
+ * <List actions={<PostListActions />}>
+ * ...
+ * </List>
+ * );
+ */
export const ExportButton = (props: ExportButtonProps) => {
const {
maxResults = 1000,
diff --git a/src/components/admin/field-toggle.tsx b/src/components/admin/field-toggle.tsx
index eb7d7549..38b61e6d 100644
--- a/src/components/admin/field-toggle.tsx
+++ b/src/components/admin/field-toggle.tsx
@@ -5,7 +5,9 @@ import { Switch } from "@/components/ui/switch";
import { cn } from "@/lib/utils";
/**
- * UI to enable/disable a field
+ * A toggleable field item with drag-and-drop reordering, used by ColumnsSelector
+ *
+ * @internal
*/
export const FieldToggle = (props: FieldToggleProps) => {
const { selected, label, onToggle, onMove, source, index } = props;
diff --git a/src/components/admin/file-field.tsx b/src/components/admin/file-field.tsx
index 5d731a60..2fc34a89 100644
--- a/src/components/admin/file-field.tsx
+++ b/src/components/admin/file-field.tsx
@@ -6,7 +6,13 @@ import { cn } from "@/lib/utils";
import type { FieldProps } from "@/lib/field.type";
/**
- * Render a link to a file based on a path contained in a record field
+ * Displays a downloadable file link with customizable title and target.
+ *
+ * This field renders file URLs as clickable links that can open in new tabs or trigger downloads.
+ * It supports arrays of files and prevents click bubbling in DataTable rows.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/filefield/ FileField documentation}
*
* @example
* import { FileField } from '@/components/admin/file-field';
diff --git a/src/components/admin/file-input.tsx b/src/components/admin/file-input.tsx
index 57b838d6..9eba3dc0 100644
--- a/src/components/admin/file-input.tsx
+++ b/src/components/admin/file-input.tsx
@@ -28,6 +28,36 @@ import { FormError, FormField, FormLabel } from "@/components/admin/form";
import { InputHelperText } from "@/components/admin/input-helper-text";
import { Button } from "@/components/ui/button";
+/**
+ * File upload input with drag-and-drop support and preview capabilities.
+ *
+ * Use `<FileInput>` for document uploads, images, PDFs, CSV files, or any file attachment field.
+ * Powered by react-dropzone with support for multiple files, file type restrictions (accept), and
+ * size constraints. Pass a child component (typically `<FileField>`) to render file previews.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/fileinput/ FileInput documentation}
+ * @see {@link https://react-dropzone.js.org/ React Dropzone documentation}
+ *
+ * @example
+ * import {
+ * Edit,
+ * SimpleForm,
+ * TextInput,
+ * FileInput,
+ * FileField,
+ * } from '@/components/admin';
+ *
+ * const DocumentEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <FileInput source="attachments" multiple accept={{ 'image/*': [], 'application/pdf': [] }}>
+ * <FileField source="src" title="title" />
+ * </FileInput>
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const FileInput = (props: FileInputProps) => {
const {
alwaysOn,
@@ -277,6 +307,11 @@ export interface TransformedFile {
title: string;
}
+/**
+ * Preview container for uploaded files in `<FileInput>`, with a remove button.
+ *
+ * @internal
+ */
export const FileInputPreview = (props: FileInputPreviewProps) => {
const {
className,
diff --git a/src/components/admin/filter-form.tsx b/src/components/admin/filter-form.tsx
index 0acbe08e..a2de7a03 100644
--- a/src/components/admin/filter-form.tsx
+++ b/src/components/admin/filter-form.tsx
@@ -41,6 +41,13 @@ import {
RemoveSavedQueryDialog,
} from "@/components/admin/saved-queries";
+/**
+ * A form for filter inputs with live updates. Included by default in List.
+ *
+ * To be used in conjunction with FilterButton.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/list/#filter-button--form-combo FilterForm documentation}
+ */
export const FilterForm = (inProps: FilterFormProps) => {
const { filters: filtersProps, ...rest } = inProps;
const filters = useFilterContext() || filtersProps;
@@ -203,6 +210,14 @@ export interface FilterFormInputProps {
const emptyRecord = {};
+/**
+ * A button that opens a dropdown to add, remove, and manage filters.
+ *
+ * Displays available filters, saved queries, and options to save or clear current filters.
+ * Works with the FilterForm to provide a complete filtering UI.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/list/#filter-button--form-combo FilterForm documentation}
+ */
export const FilterButton = (props: FilterButtonProps) => {
const {
filters: filtersProp,
diff --git a/src/components/admin/form.tsx b/src/components/admin/form.tsx
index f44e6ffa..5a4d45b6 100644
--- a/src/components/admin/form.tsx
+++ b/src/components/admin/form.tsx
@@ -147,6 +147,25 @@ const FormError = ({ className, ...props }: React.ComponentProps<"p">) => {
);
};
+/**
+ * A button that saves form data with loading state and validation.
+ *
+ * Automatically handles form submission, validation, and loading states. Shows a spinner during
+ * save operations and can be disabled when the form is pristine or invalid.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/savebutton/ SaveButton documentation}
+ *
+ * @example
+ * import { SimpleForm, SaveButton } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <Edit>
+ * <SimpleForm toolbar={<SaveButton />}>
+ * // form inputs here
+ * </SimpleForm>
+ * </Edit>
+ * )
+ */
const SaveButton = <RecordType extends RaRecord = RaRecord>(
props: SaveButtonProps<RecordType>,
) => {
diff --git a/src/components/admin/icon-button-with-tooltip.tsx b/src/components/admin/icon-button-with-tooltip.tsx
index 51ed4e7c..55700c20 100644
--- a/src/components/admin/icon-button-with-tooltip.tsx
+++ b/src/components/admin/icon-button-with-tooltip.tsx
@@ -11,8 +11,16 @@ import {
} from "@/components/ui/tooltip";
/**
- * A Button with a tooltip which ensures the tooltip is closed on click to avoid ghost tooltips
- * when the button position changes.
+ * A button with a tooltip that ensures the tooltip is closed on click to avoid ghost tooltips.
+ *
+ * Prevents ghost tooltips that can appear when the button position changes after interaction.
+ * Supports internationalization for the label text.
+ *
+ * @example
+ * // Basic usage with icon and label
+ * <IconButtonWithTooltip label="Delete">
+ * <Trash2 />
+ * </IconButtonWithTooltip>
*/
export const IconButtonWithTooltip = ({
label,
diff --git a/src/components/admin/input-helper-text.tsx b/src/components/admin/input-helper-text.tsx
index d32230ac..05caa80e 100644
--- a/src/components/admin/input-helper-text.tsx
+++ b/src/components/admin/input-helper-text.tsx
@@ -3,6 +3,11 @@ import type { ReactNode } from "react";
import { isValidElement } from "react";
import { FormDescription } from "@/components/admin/form";
+/**
+ * Renders helper text below form inputs with automatic translation support.
+ *
+ * @internal
+ */
export function InputHelperText({ helperText }: { helperText?: ReactNode }) {
const translate = useTranslate();
diff --git a/src/components/admin/layout.tsx b/src/components/admin/layout.tsx
index be1c3c91..f7b1e80e 100644
--- a/src/components/admin/layout.tsx
+++ b/src/components/admin/layout.tsx
@@ -13,6 +13,14 @@ import { LocalesMenuButton } from "@/components/admin/locales-menu-button";
import { Error } from "@/components/admin/error";
import { Loading } from "@/components/admin/loading";
+/**
+ * The main application layout with sidebar, header, and content area.
+ *
+ * Renders the app structure with a collapsible sidebar, header with breadcrumb navigation,
+ * theme toggle, user menu, and main content area. Includes error boundary and loading states.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/layout/ Layout documentation}
+ */
export const Layout = (props: CoreLayoutProps) => {
const [errorInfo, setErrorInfo] = useState<ErrorInfo | undefined>(undefined);
const handleError = (_: Error, info: ErrorInfo) => {
diff --git a/src/components/admin/list-guesser.tsx b/src/components/admin/list-guesser.tsx
index f7aa671d..ab527ca0 100644
--- a/src/components/admin/list-guesser.tsx
+++ b/src/components/admin/list-guesser.tsx
@@ -20,6 +20,26 @@ import { ReferenceField } from "@/components/admin/reference-field";
import { SingleFieldList } from "@/components/admin/single-field-list";
import { ReferenceArrayField } from "@/components/admin/reference-array-field";
+/**
+ * A list page that automatically generates a DataTable from your data.
+ *
+ * Inspects the first record to infer field types and automatically creates appropriate columns.
+ * Useful for rapid prototyping. Logs generated code to console.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/list/#scaffolding-a-list-page ListGuesser documentation}
+ *
+ * @example
+ * import { Admin, ListGuesser } from '@/components/admin';
+ * import { Resource } from 'ra-core';
+ * import { dataProvider } from './dataProvider';
+ *
+ * const App = () => (
+ * <Admin dataProvider={dataProvider}>
+ * // ...
+ * <Resource name="posts" list={ListGuesser} />
+ * </Admin>
+ * );
+ */
export const ListGuesser = <RecordType extends RaRecord = RaRecord>(
props: Omit<ListProps, "children"> & { enableLog?: boolean },
) => {
diff --git a/src/components/admin/list-pagination.tsx b/src/components/admin/list-pagination.tsx
index d2a537ef..845c5671 100644
--- a/src/components/admin/list-pagination.tsx
+++ b/src/components/admin/list-pagination.tsx
@@ -16,6 +16,27 @@ import {
import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
import { useListPaginationContext, Translate, useTranslate } from "ra-core";
+/**
+ * A pagination component with page numbers and rows per page selector.
+ *
+ * Displays pagination controls with previous/next buttons, page numbers with ellipsis for long lists,
+ * and a dropdown to change items per page. Works with List context.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/listpagination/ ListPagination documentation}
+ *
+ * @example
+ * import { List, ListPagination } from '@/components/admin';
+ *
+ * const PostListPagination = () => (
+ * <ListPagination rowsPerPageOptions={[5, 10, 25]} />
+ * );
+ *
+ * export const PostList = () => (
+ * <List pagination={<PostListPagination />}>
+ * // ...
+ * </List>
+ * );
+ */
export const ListPagination = ({
rowsPerPageOptions = [5, 10, 25, 50],
className,
diff --git a/src/components/admin/list.tsx b/src/components/admin/list.tsx
index 2c1b0ff5..c98f97ea 100644
--- a/src/components/admin/list.tsx
+++ b/src/components/admin/list.tsx
@@ -3,26 +3,53 @@ import {
BreadcrumbItem,
BreadcrumbPage,
} from "@/components/admin/breadcrumb";
-import type { ListBaseProps, RaRecord } from "ra-core";
+import type { ListBaseProps, ListControllerResult, RaRecord } from "ra-core";
import {
FilterContext,
ListBase,
- type ListControllerResult,
Translate,
useGetResourceLabel,
useHasDashboard,
useResourceContext,
useResourceDefinition,
+ useTranslate,
} from "ra-core";
import type { ReactElement, ReactNode } from "react";
import { Link } from "react-router";
import { cn } from "@/lib/utils";
-import type { FilterElementProps } from "@/hooks/filter-context";
import { CreateButton } from "@/components/admin/create-button";
import { ExportButton } from "@/components/admin/export-button";
import { ListPagination } from "@/components/admin/list-pagination";
-import { FilterForm } from "@/components/admin/filter-form";
+import { FilterButton, FilterForm } from "@/components/admin/filter-form";
+/**
+ * A complete list page with breadcrumb, title, filters, and pagination.
+ *
+ * It fetches a list of records from the data provider (via ra-core hooks),
+ * puts them in a ListContext, renders a default layout (breadcrumb, title,
+ * action buttons, inline filters, pagination), then renders its children
+ * (usually a <DataTable>).
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/list/ List documentation}
+ *
+ * @example
+ * import { DataTable, List } from "@/components/admin";
+ *
+ * export const UserList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="id" />
+ * <DataTable.Col source="name" />
+ * <DataTable.Col source="username" />
+ * <DataTable.Col source="email" />
+ * <DataTable.Col source="address.street" />
+ * <DataTable.Col source="phone" />
+ * <DataTable.Col source="website" />
+ * <DataTable.Col source="company.name" />
+ * </DataTable>
+ * </List>
+ * );
+ */
export const List = <RecordType extends RaRecord = RaRecord>(
props: ListProps<RecordType>,
) => {
@@ -66,10 +93,23 @@ export interface ListProps<RecordType extends RaRecord = RaRecord>
extends ListBaseProps<RecordType>,
ListViewProps<RecordType> {}
+/**
+ * The view component for List pages with layout and UI.
+ *
+ * @internal
+ */
export const ListView = <RecordType extends RaRecord = RaRecord>(
props: ListViewProps<RecordType>,
) => {
- const { filters, pagination = defaultPagination, children, actions } = props;
+ const {
+ disableBreadcrumb,
+ filters,
+ pagination = defaultPagination,
+ title,
+ children,
+ actions,
+ } = props;
+ const translate = useTranslate();
const resource = useResourceContext();
if (!resource) {
throw new Error(
@@ -78,32 +118,44 @@ export const ListView = <RecordType extends RaRecord = RaRecord>(
}
const getResourceLabel = useGetResourceLabel();
const resourceLabel = getResourceLabel(resource, 2);
+ const finalTitle =
+ title !== undefined
+ ? title
+ : translate("ra.page.list", {
+ name: resourceLabel,
+ });
const { hasCreate } = useResourceDefinition({ resource });
const hasDashboard = useHasDashboard();
return (
<>
- <Breadcrumb>
- {hasDashboard && (
- <BreadcrumbItem>
- <Link to="/">
- <Translate i18nKey="ra.page.dashboard">Home</Translate>
- </Link>
- </BreadcrumbItem>
- )}
- <BreadcrumbPage>{resourceLabel}</BreadcrumbPage>
- </Breadcrumb>
+ {!disableBreadcrumb && (
+ <Breadcrumb>
+ {hasDashboard && (
+ <BreadcrumbItem>
+ <Link to="/">
+ <Translate i18nKey="ra.page.dashboard">Home</Translate>
+ </Link>
+ </BreadcrumbItem>
+ )}
+ <BreadcrumbPage>{resourceLabel}</BreadcrumbPage>
+ </Breadcrumb>
+ )}
<FilterContext.Provider value={filters}>
- <div className="flex justify-between items-center flex-wrap gap-2 my-2">
- <FilterForm />
+ <div className="flex justify-between items-start flex-wrap gap-2 my-2">
+ <h2 className="text-2xl font-bold tracking-tight mb-2">
+ {finalTitle}
+ </h2>
{actions ?? (
<div className="flex items-center gap-2">
+ {filters && filters.length > 0 ? <FilterButton /> : null}
{hasCreate ? <CreateButton /> : null}
{<ExportButton />}
</div>
)}
</div>
+ <FilterForm />
<div className={cn("my-2", props.className)}>{children}</div>
{pagination}
@@ -116,14 +168,11 @@ const defaultPagination = <ListPagination />;
export interface ListViewProps<RecordType extends RaRecord = RaRecord> {
children?: ReactNode;
+ disableBreadcrumb?: boolean;
render?: (props: ListControllerResult<RecordType, Error>) => ReactNode;
actions?: ReactElement | false;
- filters?: ReactElement<FilterElementProps>[];
+ filters?: ReactNode[];
pagination?: ReactNode;
title?: ReactNode | string | false;
className?: string;
}
-
-export type FiltersType =
- | ReactElement<FilterElementProps>
- | ReactElement<FilterElementProps>[];
diff --git a/src/components/admin/loading.tsx b/src/components/admin/loading.tsx
index b94dcf14..631da3e1 100644
--- a/src/components/admin/loading.tsx
+++ b/src/components/admin/loading.tsx
@@ -1,6 +1,15 @@
import { Translate, useTimeout } from "ra-core";
import { Spinner } from "./spinner";
+/**
+ * Loading indicator used for slow element or page loads.
+ *
+ * Displays a spinner and customizable loading messages.
+ * Automatically shown by the default Layout when page loading takes more than 1 second.
+ * Works as a fallback for React Suspense boundaries.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/loading/ Loading documentation}
+ */
export const Loading = (props: LoadingProps) => {
const {
loadingPrimary = "ra.page.loading",
diff --git a/src/components/admin/locales-menu-button.tsx b/src/components/admin/locales-menu-button.tsx
index 73413473..d4349e65 100644
--- a/src/components/admin/locales-menu-button.tsx
+++ b/src/components/admin/locales-menu-button.tsx
@@ -9,6 +9,16 @@ import {
import { cn } from "@/lib/utils";
import { useLocales, useLocaleState } from "ra-core";
+/**
+ * Language switcher button that displays a menu allowing users to select the interface language.
+ *
+ * Automatically renders in the header when multiple locales are configured in the i18nProvider.
+ * User's language selection is persisted using the store.
+ * Returns null if only one language is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/localesmenubutton LocalesMenuButton documentation}
+ * @see {@link https://marmelab.com/ra-core/translationsetup/ i18nProvider setup}
+ */
export function LocalesMenuButton() {
const languages = useLocales();
const [locale, setLocale] = useLocaleState();
diff --git a/src/components/admin/login-page.tsx b/src/components/admin/login-page.tsx
index 8e8e4a88..3dc558bb 100644
--- a/src/components/admin/login-page.tsx
+++ b/src/components/admin/login-page.tsx
@@ -7,6 +7,15 @@ import { TextInput } from "@/components/admin/text-input";
import { Notification } from "@/components/admin/notification";
import { useConfigurationContext } from "@/components/atomic-crm/root/ConfigurationContext.tsx";
+/**
+ * Login page displayed when authentication is enabled and the user is not authenticated.
+ *
+ * Automatically shown when an unauthenticated user tries to access a protected route.
+ * Handles login via authProvider.login() and displays error notifications on failure.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/loginpage LoginPage documentation}
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/security Security documentation}
+ */
export const LoginPage = (props: { redirectTo?: string }) => {
const { darkModeLogo, title } = useConfigurationContext();
const { redirectTo } = props;
diff --git a/src/components/admin/notification.tsx b/src/components/admin/notification.tsx
index 46c58beb..caae37fe 100644
--- a/src/components/admin/notification.tsx
+++ b/src/components/admin/notification.tsx
@@ -10,6 +10,27 @@ import {
useTranslate,
} from "ra-core";
+/**
+ * Displays notifications triggered with the useNotify hook.
+ *
+ * Supports different notification types (info, success, warning, error) and undoable mutations.
+ * Automatically adapts to the current theme (light/dark).
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/notification Notification documentation}
+ * @see {@link https://marmelab.com/ra-core/usenotify/ useNotify hook}
+ *
+ * @example
+ * // Trigger a notification
+ * import { useNotify } from 'ra-core';
+ *
+ * const NotifyButton = () => {
+ * const notify = useNotify();
+ * const handleClick = () => {
+ * notify('Comment approved', { type: 'success' });
+ * };
+ * return <button onClick={handleClick}>Notify</button>;
+ * };
+ */
export const Notification = (props: ToasterProps) => {
const translate = useTranslate();
const { notifications, takeNotification } = useNotificationContext();
diff --git a/src/components/admin/number-field.tsx b/src/components/admin/number-field.tsx
index 73fb9509..a80a8b44 100644
--- a/src/components/admin/number-field.tsx
+++ b/src/components/admin/number-field.tsx
@@ -2,6 +2,29 @@ import type { HTMLAttributes } from "react";
import { useFieldValue, useTranslate } from "ra-core";
import type { FieldProps } from "@/lib/field.type";
+/**
+ * Displays a numeric value with locale-specific formatting.
+ *
+ * This field automatically formats numbers according to the user's locale using Intl.NumberFormat.
+ * It supports custom locales and formatting options for currencies, percentages, and more.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/numberfield/ NumberField documentation}
+ *
+ * @example
+ * import { Show, RecordField, NumberField } from '@/components/admin';
+ *
+ * const ProductShow = () => (
+ * <Show>
+ * <div className="flex flex-col gap-4">
+ * <RecordField source="reference" />
+ * <RecordField source="price">
+ * <NumberField source="price" options={{ style: 'currency', currency: 'USD' }} />
+ * </RecordField>
+ * </div>
+ * </Show>
+ * );
+ */
export const NumberField = <
RecordType extends Record<string, any> = Record<string, any>,
>({
diff --git a/src/components/admin/number-input.tsx b/src/components/admin/number-input.tsx
index 72597662..cf84718f 100644
--- a/src/components/admin/number-input.tsx
+++ b/src/components/admin/number-input.tsx
@@ -7,6 +7,28 @@ import { Input } from "@/components/ui/input";
import { FormError } from "@/components/admin/form";
import { InputHelperText } from "@/components/admin/input-helper-text";
+/**
+ * Input component for numeric values (integers and floats) with parsing and formatting support.
+ *
+ * Use `<NumberInput>` for prices, quantities, counts, or any numeric field. Manages a local string
+ * state internally so users can type incomplete numbers (e.g. '-' or '0.') before the value is parsed.
+ * Supports min/max constraints and step increments.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/numberinput/ NumberInput documentation}
+ *
+ * @example
+ * import { Edit, SimpleForm, NumberInput, TextInput } from '@/components/admin';
+ *
+ * const ProductEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="name" />
+ * <NumberInput source="price" step={0.01} min={0} />
+ * <NumberInput source="quantity" min={0} />
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const NumberInput = (props: NumberInputProps) => {
const {
label,
diff --git a/src/components/admin/radio-button-group-input.tsx b/src/components/admin/radio-button-group-input.tsx
index 4613b0d7..89e0bbcf 100644
--- a/src/components/admin/radio-button-group-input.tsx
+++ b/src/components/admin/radio-button-group-input.tsx
@@ -13,6 +13,34 @@ import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
import { Skeleton } from "@/components/ui/skeleton";
import { InputHelperText } from "@/components/admin/input-helper-text";
+/**
+ * Single-select input rendered as a list of radio buttons, arranged vertically or horizontally.
+ *
+ * Use `<RadioButtonGroupInput>` when you have a small set of options (2-5) that users should
+ * see all at once, like status, priority, or category fields. For longer lists, prefer
+ * `<SelectInput>`. Set `row` to `true` for horizontal layout.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/radiobuttongroupinput/ RadioButtonGroupInput documentation}
+ *
+ * @example
+ * import { Edit, SimpleForm, TextInput, RadioButtonGroupInput } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <RadioButtonGroupInput
+ * source="category"
+ * choices={[
+ * { id: 'tech', name: 'Tech' },
+ * { id: 'lifestyle', name: 'Lifestyle' },
+ * { id: 'people', name: 'People' },
+ * ]}
+ * />
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const RadioButtonGroupInput = (inProps: RadioButtonGroupInputProps) => {
const {
choices: choicesProp,
diff --git a/src/components/admin/ready.tsx b/src/components/admin/ready.tsx
index e670b31f..0fd367fc 100644
--- a/src/components/admin/ready.tsx
+++ b/src/components/admin/ready.tsx
@@ -5,6 +5,14 @@ import {
Github,
} from "lucide-react";
+/**
+ * Splash screen displayed when no resources are configured yet.
+ *
+ * Provides helpful links to documentation, demo, and GitHub repository.
+ * Automatically shown when the admin app has no Resource children defined.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/ready/ Ready documentation}
+ */
export const Ready = () => (
<div className="flex flex-col h-screen">
<div
diff --git a/src/components/admin/record-field.tsx b/src/components/admin/record-field.tsx
index 7d42a9f8..a404033c 100644
--- a/src/components/admin/record-field.tsx
+++ b/src/components/admin/record-field.tsx
@@ -11,6 +11,36 @@ import { cn } from "@/lib/utils";
import { TextField } from "@/components/admin/text-field";
+/**
+ * Displays a labeled field-value pair with flexible rendering options.
+ *
+ * Supports either vertical or inline layout.
+ * It can render children, use a custom field component, or display a TextField by default.
+ * To be used with RecordContext, e.g. inside Show, or inside ArrayField to display array items.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/recordfield/ RecordField documentation}
+ *
+ * @example
+ * import { NumberField, RecordField, Show } from '@/components/admin';
+ *
+ * const PostShow = () => (
+ * <Show>
+ * <div className="flex flex-col gap-4">
+ * <RecordField source="reference" label="Ref." />
+ * <RecordField
+ * label="dimensions"
+ * render={record => `${record.width}x${record.height}`}
+ * />
+ * <RecordField source="price">
+ * <NumberField source="price" options={
+ * style: 'currency',
+ * currency: 'USD',
+ * }/>
+ * <RecordField source="status" variant="inline" />
+ * </div>
+ * </Show>
+ * );
+ */
export const RecordField = <
RecordType extends Record<string, any> = Record<string, any>,
>(
diff --git a/src/components/admin/reference-array-field.tsx b/src/components/admin/reference-array-field.tsx
index e814cc8b..91fcc5bf 100644
--- a/src/components/admin/reference-array-field.tsx
+++ b/src/components/admin/reference-array-field.tsx
@@ -5,67 +5,39 @@ import type {
ListControllerResult,
RaRecord,
SortPayload,
-} from "ra-core";
-import {
ExtractRecordPaths,
HintedString,
- ReferenceArrayFieldBase,
- useListContext,
} from "ra-core";
+import { ReferenceArrayFieldBase, useListContext } from "ra-core";
import type { UseQueryOptions } from "@tanstack/react-query";
import { SingleFieldList } from "@/components/admin/single-field-list";
/**
- * A container component that fetches records from another resource specified
- * by an array of *ids* in current record.
- *
- * You must define the fields to be passed to the iterator component as children.
- *
- * @example Display all the categories of the current product as a list of chips (the default)
- * // product = {
- * // id: 456,
- * // category_ids: [11, 22, 33],
- * // }
- * <ReferenceArrayField label="Categories" reference="categories" source="category_ids"/ >
- *
- * @example Display all the products of the current order as DataTable
- * // order = {
- * // id: 123,
- * // product_ids: [456, 457, 458],
- * // }
- * <ReferenceArrayField label="Products" reference="products" source="product_ids">
- * <DataTable>
- * <DataTable.Col source="id" />
- * <DataTable.Col source="description" />
- * <DataTable.NumberCol source="price" options={{ style: 'currency', currency: 'USD' }} />
- * <DataTable.Col><EditButton /></DataTable.Col>
- * </DataTable>
- * </ReferenceArrayField>
+ * Displays multiple related records by following an array of foreign keys.
*
- * By default, restricts the displayed values to 1000. You can extend this limit
- * by setting the `perPage` prop.
+ * This field fetches related records using an array of IDs and renders them using a child component (SingleFieldList by default).
+ * It supports custom sorting, filtering, and rendering with DataTable or other list components.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
*
- * @example
- * <ReferenceArrayField perPage={10} reference="categories" source="category_ids">
- * ...
- * </ReferenceArrayField>
- *
- * By default, the field displays the results in the order in which they are referenced
- * (i.e. in the order of the list of ids). You can change this order
- * by setting the `sort` prop (an object with `field` and `order` properties).
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/referencearrayfield/ ReferenceArrayField documentation}
*
* @example
- * <ReferenceArrayField sort={{ field: 'name', order: 'ASC' }} reference="categories" source="category_ids">
- * ...
- * </ReferenceArrayField>
- *
- * Also, you can filter the results to display only a subset of values. Use the
- * `filter` prop for that.
+ * import { List, DataTable, ReferenceArrayField } from '@/components/admin';
*
- * @example
- * <ReferenceArrayField filter={{ is_published: true }} reference="categories" source="category_ids">
- * ...
- * </ReferenceArrayField>
+ * export const PostList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="id" />
+ * <DataTable.Col source="title" />
+ * <DataTable.Col source="tag_ids" label="Tags">
+ * <ReferenceArrayField reference="tags" source="tag_ids" />
+ * </DataTable.Col>
+ * <DataTable.Col>
+ * <EditButton />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
*/
export const ReferenceArrayField = <
RecordType extends RaRecord = RaRecord,
diff --git a/src/components/admin/reference-array-input.tsx b/src/components/admin/reference-array-input.tsx
index 8ce7e972..3934143e 100644
--- a/src/components/admin/reference-array-input.tsx
+++ b/src/components/admin/reference-array-input.tsx
@@ -9,63 +9,26 @@ import {
import { AutocompleteArrayInput } from "@/components/admin/autocomplete-array-input";
/**
- * An Input component for fields containing a list of references to another resource.
- * Useful for 'hasMany' relationship.
+ * Form input for editing arrays of foreign key relationships with autocompletion.
*
- * @example
- * The post object has many tags, so the post resource looks like:
- * {
- * id: 1234,
- * tag_ids: [ "1", "23", "4" ]
- * }
- *
- * ReferenceArrayInput component fetches the current resources (using
- * `dataProvider.getMany()`) as well as possible resources (using
- * `dataProvider.getList()`) in the reference endpoint. It then
- * delegates rendering to its child component, to which it makes the possible
- * choices available through the ChoicesContext.
- *
- * @example
- * export const PostEdit = () => (
- * <Edit>
- * <SimpleForm>
- * <ReferenceArrayInput source="tag_ids" reference="tags" />
- * </SimpleForm>
- * </Edit>
- * );
- *
- * By default, restricts the possible values to 25. You can extend this limit
- * by setting the `perPage` prop.
+ * This component fetches related records from a reference resource and displays them
+ * in a searchable multi-select interface using AutocompleteArrayInput.
+ * Use it to edit one-to-many or many-to-many relationships, where the current record
+ * has an array of foreign keys to another resource.
*
- * @example
- * <ReferenceArrayInput
- * source="tag_ids"
- * reference="tags"
- * perPage={100}
- * />
- *
- * By default, orders the possible values by id desc. You can change this order
- * by setting the `sort` prop (an object with `field` and `order` properties).
- *
- * @example
- * <ReferenceArrayInput
- * source="tag_ids"
- * reference="tags"
- * sort={{ field: 'name', order: 'ASC' }}
- * />
- *
- * Also, you can filter the query used to populate the possible values. Use the
- * `filter` prop for that.
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/referencearrayinput/ ReferenceArrayInput documentation}
*
* @example
- * <ReferenceArrayInput
- * source="tag_ids"
- * reference="tags"
- * filter={{ is_public: true }}
- * />
+ * import { Edit, SimpleForm, TextInput, ReferenceArrayInput } from '@/components/admin';
*
- * The enclosed component may filter results. ReferenceArrayInput create a ChoicesContext which provides
- * a `setFilters` function. You can call this function to filter the results.
+ * const PostEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <ReferenceArrayInput source="tag_ids" reference="tags" />
+ * </SimpleForm>
+ * </Edit>
+ * );
*/
export const ReferenceArrayInput = (props: ReferenceArrayInputProps) => {
const {
diff --git a/src/components/admin/reference-field.tsx b/src/components/admin/reference-field.tsx
index ce3e60a6..877c5cf1 100644
--- a/src/components/admin/reference-field.tsx
+++ b/src/components/admin/reference-field.tsx
@@ -15,6 +15,29 @@ import type { MouseEvent, ReactNode } from "react";
import { Link } from "react-router";
import type { UseQueryOptions } from "@tanstack/react-query";
+/**
+ * Displays a field from a related record by following a foreign key relationship.
+ *
+ * This field fetches the related record using the foreign key value and displays it using the record representation.
+ * It supports linking to the related record's show or edit page.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/referencefield/ ReferenceField documentation}
+ *
+ * @example
+ * import { List, DataTable, ReferenceField } from '@/components/admin';
+ *
+ * const PostList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="title" />
+ * <DataTable.Col label="Author">
+ * <ReferenceField source="author_id" reference="authors" link="show" />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
+ */
export const ReferenceField = <
RecordType extends RaRecord = RaRecord,
ReferenceRecordType extends RaRecord = RaRecord,
diff --git a/src/components/admin/reference-input.tsx b/src/components/admin/reference-input.tsx
index c15a7290..27c5ee44 100644
--- a/src/components/admin/reference-input.tsx
+++ b/src/components/admin/reference-input.tsx
@@ -2,6 +2,28 @@ import type { ReferenceInputBaseProps } from "ra-core";
import { ReferenceInputBase } from "ra-core";
import { AutocompleteInput } from "./autocomplete-input";
+/**
+ * Form input for editing foreign key relationships with autocompletion.
+ *
+ * This component fetches related records from a reference resource and displays them in a searchable dropdown using AutocompleteInput.
+ * Use it to edit many-to-one relationships, where the current record has a foreign key to another resource.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/referenceinput/ ReferenceInput documentation}
+ *
+ * @example
+ * import { Edit, SimpleForm, TextInput, ReferenceInput } from '@/components/admin';
+ *
+ * const ContactEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="first_name" />
+ * <TextInput source="last_name" />
+ * <TextInput source="title" />
+ * <ReferenceInput source="company_id" reference="companies" />
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const ReferenceInput = (props: ReferenceInputProps) => {
const { children = defaultChildren, ...rest } = props;
diff --git a/src/components/admin/reference-many-count.tsx b/src/components/admin/reference-many-count.tsx
index f6e0efb1..bd2e3843 100644
--- a/src/components/admin/reference-many-count.tsx
+++ b/src/components/admin/reference-many-count.tsx
@@ -6,6 +6,28 @@ import {
} from "ra-core";
import { Link } from "react-router";
+/**
+ * Displays the count of related records that reference the current record.
+ *
+ * Calls dataProvider.getList() to compute the the number of records in a related resource that have a foreign key pointing to the current record.
+ * It can optionally link to a filtered list of those records.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/referencemanycount/ ReferenceManyCount documentation}
+ *
+ * @example
+ * import { List, DataTable, ReferenceManyCount } from '@/components/admin';
+ *
+ * const AuthorList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="name" />
+ * <DataTable.Col label="Number of Books">
+ * <ReferenceManyCount reference="books" target="author_id" link />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
+ */
export const ReferenceManyCount = <RecordType extends RaRecord = RaRecord>(
props: ReferenceManyCountProps<RecordType>,
) => {
diff --git a/src/components/admin/reference-many-field.tsx b/src/components/admin/reference-many-field.tsx
index eb569725..7d6aed43 100644
--- a/src/components/admin/reference-many-field.tsx
+++ b/src/components/admin/reference-many-field.tsx
@@ -6,6 +6,34 @@ import type {
} from "ra-core";
import { ReferenceManyFieldBase, useListContext } from "ra-core";
+/**
+ * Displays multiple related records that reference the current record via a foreign key.
+ *
+ * This field fetches records from a related resource where the foreign key points to the current record.
+ * It provides a ListContext to its children, enabling list rendering with DataTable or custom components.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/referencemanyfield/ ReferenceManyField documentation}
+ *
+ * @example
+ * import { Show, ReferenceManyField, DataTable, DateField, RecordField } from '@/components/admin';
+ *
+ * const AuthorShow = () => (
+ * <Show>
+ * <div className="flex flex-col gap-4">
+ * <RecordField source="first_name" />
+ * <RecordField source="last_name" />
+ * <RecordField label="Books">
+ * <ReferenceManyField reference="books" target="author_id" label="Books">
+ * <DataTable>
+ * <DataTable.Col source="title" />
+ * <DataTable.Col source="published_at" field={DateField} />
+ * </DataTable>
+ * </ReferenceManyField>
+ * </RecordField>
+ * </div>
+ * </Show>
+ * );
+ */
export const ReferenceManyField = <
RecordType extends RaRecord = RaRecord,
ReferenceRecordType extends RaRecord = RaRecord,
diff --git a/src/components/admin/refresh-button.tsx b/src/components/admin/refresh-button.tsx
index f45eceda..93edff98 100644
--- a/src/components/admin/refresh-button.tsx
+++ b/src/components/admin/refresh-button.tsx
@@ -2,6 +2,14 @@ import { useRefresh, useLoading } from "ra-core";
import { Button } from "@/components/ui/button";
import { LoaderCircle, RotateCw } from "lucide-react";
+/**
+ * A button that refreshes the current view's data.
+ *
+ * When clicked, reloads data from the server. Shows a spinner animation during loading.
+ * Included in the default top app bar. Hidden on small screens.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/refreshbutton/ RefreshButton documentation}
+ */
export const RefreshButton = () => {
const refresh = useRefresh();
const loading = useLoading();
diff --git a/src/components/admin/saved-queries.tsx b/src/components/admin/saved-queries.tsx
index 578bccaa..8249622d 100644
--- a/src/components/admin/saved-queries.tsx
+++ b/src/components/admin/saved-queries.tsx
@@ -19,6 +19,13 @@ import {
useSavedQueries,
} from "@/hooks/saved-queries";
+/**
+ * Dialog for saving the current list view query (filters, sort, pagination) as a named saved query.
+ *
+ * Used by FilterButton in the List view.
+ *
+ * @internal
+ */
export const AddSavedQueryDialog = ({
open,
onClose,
@@ -99,6 +106,11 @@ export interface AddSavedQueryDialogProps {
onClose: () => void;
}
+/**
+ * Dialog for removing a saved query from the user's list.
+ *
+ * @internal
+ */
export const RemoveSavedQueryDialog = ({
open,
onClose,
diff --git a/src/components/admin/search-input.tsx b/src/components/admin/search-input.tsx
index 3e75d165..17ecab45 100644
--- a/src/components/admin/search-input.tsx
+++ b/src/components/admin/search-input.tsx
@@ -4,6 +4,30 @@ import type { TextInputProps } from "@/components/admin/text-input";
import { TextInput } from "@/components/admin/text-input";
import { cn } from "@/lib/utils";
+/**
+ * Text input with a search icon, designed for filter forms without a label.
+ *
+ * It automatically uses the 'q' source for full-text search by default.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/searchinput/ SearchInput documentation}
+ *
+ * @example
+ * import { List, DataTable, SearchInput } from '@/components/admin';
+ *
+ * const postListFilters = [
+ * <SearchInput source="q" alwaysOn />,
+ * ];
+ *
+ * const PostList = () => (
+ * <List filters={postListFilters}>
+ * <DataTable>
+ * <DataTable.Col source="title" />
+ * <DataTable.Col source="author" />
+ * <DataTable.Col source="published_at" />
+ * </DataTable>
+ * </List>
+ * );
+ */
export const SearchInput = (inProps: SearchInputProps) => {
const { label, className, ...rest } = inProps;
diff --git a/src/components/admin/select-field.tsx b/src/components/admin/select-field.tsx
index 1d269120..db070510 100644
--- a/src/components/admin/select-field.tsx
+++ b/src/components/admin/select-field.tsx
@@ -6,52 +6,28 @@ import type { FieldProps } from "@/lib/field.type";
import { genericMemo } from "@/lib/genericMemo";
/**
- * Display a value in an enumeration
+ * Displays a value from an enumeration by mapping it to a human-readable label.
*
- * Pass possible options as an array of objects in the 'choices' attribute.
+ * Supports custom optionText and optionValue properties, and automatic translation of choice labels.
+ * To be used with RecordField or DataTable.Col components, or anywhere a RecordContext is available.
*
- * @example
- * const choices = [
- * { id: 'M', name: 'Male' },
- * { id: 'F', name: 'Female' },
- * ];
- * <SelectField source="gender" choices={choices} />
- *
- * By default, the text is built by
- * - finding a choice where the 'id' property equals the field value
- * - using the 'name' property as the option text
- *
- * You can also customize the properties to use for the value and text,
- * thanks to the 'optionValue' and 'optionText' attributes.
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/selectfield/ SelectField documentation}
*
* @example
- * const choices = [
- * { _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
- * { _id: 456, full_name: 'Jane Austen', sex: 'F' },
- * ];
- * <SelectField source="author_id" choices={choices} optionText="full_name" optionValue="_id" />
+ * import { List, DataTable, SelectField } from '@/components/admin';
*
- * `optionText` also accepts a function, so you can shape the option text at will:
- * @example
- * const choices = [
- * { id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
- * { id: 456, first_name: 'Jane', last_name: 'Austen' },
- * ];
- * const optionRenderer = choice => `${choice.first_name} ${choice.last_name}`;
- * <SelectField source="author_id" choices={choices} optionText={optionRenderer} />
+ * const choices = [{ id: 'M', name: 'Male' }, { id: 'F', name: 'Female' }];
*
- * `optionText` also accepts a React Element, that can access
- * the related choice through the `useRecordContext` hook. You can use Field components there.
- * @example
- * const choices = [
- * { id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
- * { id: 456, first_name: 'Jane', last_name: 'Austen' },
- * ];
- * const FullNameField = () => {
- * const record = useRecordContext();
- * return (<Chip>{record.first_name} {record.last_name}</Chip>)
- * };
- * <SelectField source="gender" choices={choices} optionText={<FullNameField />}/>
+ * const UserList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="name" />
+ * <DataTable.Col>
+ * <SelectField source="gender" choices={choices} />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
*
* The current choice is translated by default, so you can use translation identifiers as choices:
* @example
diff --git a/src/components/admin/select-input.tsx b/src/components/admin/select-input.tsx
index 238fecc9..a033f811 100644
--- a/src/components/admin/select-input.tsx
+++ b/src/components/admin/select-input.tsx
@@ -21,12 +21,39 @@ import {
SelectValue,
} from "@/components/ui/select";
import { Skeleton } from "@/components/ui/skeleton";
-import {
- SupportCreateSuggestionOptions,
- useSupportCreateSuggestion,
-} from "@/hooks/useSupportCreateSuggestion";
+import type { SupportCreateSuggestionOptions } from "@/hooks/useSupportCreateSuggestion";
+import { useSupportCreateSuggestion } from "@/hooks/useSupportCreateSuggestion";
import { cn } from "@/lib/utils";
+/**
+ * Dropdown select input for choosing a single value from a list of options.
+ *
+ * Use `<SelectInput>` for fields with many possible values (5+) like categories, statuses, or
+ * countries. Supports creating new options on the fly with the `create` or `onCreate` props.
+ * Wrap in `<ReferenceInput>` to select from related resources.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/selectinput/ SelectInput documentation}
+ * @see {@link https://ui.shadcn.com/docs/components/select Select documentation}
+ *
+ * @example
+ * import { Edit, SimpleForm, TextInput, SelectInput } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <SelectInput
+ * source="category"
+ * choices={[
+ * { id: 'tech', name: 'Tech' },
+ * { id: 'lifestyle', name: 'Lifestyle' },
+ * { id: 'people', name: 'People' },
+ * ]}
+ * />
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const SelectInput = (props: SelectInputProps) => {
const {
choices: choicesProp,
@@ -140,7 +167,6 @@ export const SelectInput = (props: SelectInputProps) => {
}, [emptyText, translate]);
const renderMenuItemOption = useCallback(
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
(choice: any) => getChoiceText(choice),
[getChoiceText],
);
@@ -291,7 +317,7 @@ export type SelectInputProps = ChoicesProps &
Partial<InputProps> &
Omit<SupportCreateSuggestionOptions, "handleChange"> & {
emptyText?: string | ReactElement;
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
emptyValue?: any;
onChange?: (value: string) => void;
} & Omit<ComponentProps<typeof FormField>, "id" | "name" | "children">;
diff --git a/src/components/admin/show-button.tsx b/src/components/admin/show-button.tsx
index 029ee9ce..86ef40f1 100644
--- a/src/components/admin/show-button.tsx
+++ b/src/components/admin/show-button.tsx
@@ -14,6 +14,20 @@ export type ShowButtonProps = {
icon?: React.ReactNode;
} & React.AnchorHTMLAttributes<HTMLAnchorElement>;
+/**
+ * A button that navigates to the show page for a record.
+ *
+ * Works within RecordContext to automatically get the record ID.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/showbutton/ ShowButton documentation}
+ *
+ * @example
+ * import { ShowButton } from '@/components/admin';
+ *
+ * const PostActions = () => (
+ * <ShowButton label="View Details" />
+ * );
+ */
export const ShowButton = (props: ShowButtonProps) => {
const resource = useResourceContext();
const record = useRecordContext();
diff --git a/src/components/admin/show-guesser.tsx b/src/components/admin/show-guesser.tsx
index 6b56dd98..11ab8f42 100644
--- a/src/components/admin/show-guesser.tsx
+++ b/src/components/admin/show-guesser.tsx
@@ -19,6 +19,17 @@ import { BadgeField } from "@/components/admin/badge-field";
import { SingleFieldList } from "@/components/admin/single-field-list";
import { ReferenceArrayField } from "@/components/admin/reference-array-field";
+/**
+ * A show page that automatically generates fields from your data.
+ *
+ * Inspects the record to infer field types and automatically creates appropriate display fields.
+ * Useful for rapid prototyping. Logs generated code to console when enableLog is true.
+ *
+ * @example
+ * import { ShowGuesser } from '@/components/admin';
+ *
+ * export const PostShow = () => <ShowGuesser enableLog />;
+ */
export const ShowGuesser = (props: { enableLog?: boolean }) => (
<ShowBase>
<ShowViewGuesser {...props} />
diff --git a/src/components/admin/show.tsx b/src/components/admin/show.tsx
index 4fa23abe..f1f6ac40 100644
--- a/src/components/admin/show.tsx
+++ b/src/components/admin/show.tsx
@@ -24,6 +24,33 @@ export interface ShowProps
extends ShowViewProps,
Omit<ShowBaseProps, "children"> {}
+/**
+ * A complete show page with breadcrumb, title, and default actions.
+ *
+ * Combines data fetching and UI layout for displaying record details. Inside, use
+ * RecordField to display individual fields with labels.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/show/ Show documentation}
+ *
+ * @example
+ * import { RecordField, NumberField, ReferenceField, Show } from "@/components/admin";
+ *
+ * export const ProductShow = () => (
+ * <Show>
+ * <div className="flex flex-col gap-4">
+ * <RecordField source="reference" />
+ * <RecordField source="category_id">
+ * <ReferenceField source="category_id" reference="categories" />
+ * </RecordField>
+ * <RecordField
+ * source="price"
+ * render={(record) => Intl.NumberFormat().format(record.price)}
+ * />
+ * <RecordField source="size" field={NumberField} />
+ * </div>
+ * </Show>
+ * );
+ */
export const Show = ({
actions,
children,
@@ -65,6 +92,23 @@ export interface ShowViewProps {
title?: ReactNode | string | false;
}
+/**
+ * The view component for Show pages with layout and UI.
+ *
+ * Renders breadcrumb, title, and default actions for show pages. Use Show instead unless you need
+ * custom data fetching logic with ShowBase.
+ *
+ * @example
+ * import { ShowBase, ShowView, SimpleShowLayout } from '@/components/admin';
+ *
+ * export const PostShow = () => (
+ * <ShowBase>
+ * <ShowView>
+ * <SimpleShowLayout>...</SimpleShowLayout>
+ * </ShowView>
+ * </ShowBase>
+ * );
+ */
export const ShowView = ({
actions,
children,
diff --git a/src/components/admin/simple-form-iterator.tsx b/src/components/admin/simple-form-iterator.tsx
index a078a963..4500fd51 100644
--- a/src/components/admin/simple-form-iterator.tsx
+++ b/src/components/admin/simple-form-iterator.tsx
@@ -44,6 +44,26 @@ import { IconButtonWithTooltip } from "@/components/admin/icon-button-with-toolt
type GetItemLabelFunc = (index: number) => string | ReactElement;
+/**
+ * An array input iterator for managing dynamic lists of items in forms.
+ *
+ * Renders a list of form items with add, remove, and reorder controls. Use inside ArrayInput
+ * for arrays of objects or scalar values. Supports inline layouts and custom buttons.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/arrayinput/ ArrayInput documentation}
+ *
+ * @example
+ * import { ArrayInput, SimpleFormIterator, TextInput } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <ArrayInput source="authors">
+ * <SimpleFormIterator>
+ * <TextInput source="name" />
+ * <TextInput source="email" />
+ * </SimpleFormIterator>
+ * </ArrayInput>
+ * );
+ */
export const SimpleFormIterator = (props: SimpleFormIteratorProps) => {
const {
addButton = defaultAddItemButton,
@@ -159,10 +179,18 @@ export const SimpleFormIterator = (props: SimpleFormIteratorProps) => {
total: fields.length,
add: addField,
remove: removeField,
+ clear: handleArrayClear,
reOrder: handleReorder,
source: finalSource,
}),
- [addField, fields.length, handleReorder, removeField, finalSource],
+ [
+ fields.length,
+ addField,
+ removeField,
+ handleArrayClear,
+ handleReorder,
+ finalSource,
+ ],
);
return fields ? (
<SimpleFormIteratorContext.Provider value={context}>
@@ -236,6 +264,17 @@ export interface SimpleFormIteratorProps extends Partial<UseFieldArrayReturn> {
source?: string;
}
+/**
+ * A single item in a SimpleFormIterator list with controls.
+ *
+ * Renders one item from an array with its input fields and action buttons (remove, reorder).
+ * Usually used internally by SimpleFormIterator but can be customized.
+ *
+ * @example
+ * import { SimpleFormIteratorItem } from '@/components/admin';
+ *
+ * // Typically used internally by SimpleFormIterator
+ */
export const SimpleFormIteratorItem = React.forwardRef(
(
props: SimpleFormIteratorItemProps,
@@ -376,6 +415,23 @@ export type SimpleFormIteratorItemProps = Partial<ArrayInputContextValue> & {
source?: string;
};
+/**
+ * A button to add new items to a SimpleFormIterator.
+ *
+ * Renders a plus icon button that appends a new item to the array. Works with the
+ * SimpleFormIterator context to add items with default values.
+ *
+ * @example
+ * import { ArrayInput, SimpleFormIterator, AddItemButton } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <ArrayInput source="tags">
+ * <SimpleFormIterator addButton={<AddItemButton />}>
+ * ...
+ * </SimpleFormIterator>
+ * </ArrayInput>
+ * );
+ */
export const AddItemButton = (props: React.ComponentProps<"button">) => {
const { add, source } = useSimpleFormIterator();
const { className, ...rest } = props;
@@ -401,6 +457,21 @@ export const AddItemButton = (props: React.ComponentProps<"button">) => {
);
};
+/**
+ * Up and down buttons for reordering items in a SimpleFormIterator.
+ *
+ * Renders arrow buttons that move an item up or down in the list. Used internally
+ * by SimpleFormIterator but can be customized.
+ *
+ * @example
+ * import { SimpleFormIterator, ReOrderButtons } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <SimpleFormIterator reOrderButtons={<ReOrderButtons />}>
+ * ...
+ * </SimpleFormIterator>
+ * );
+ */
export const ReOrderButtons = ({ className }: { className?: string }) => {
const { index, total, reOrder } = useSimpleFormIteratorItem();
const { source } = useSimpleFormIterator();
@@ -431,6 +502,17 @@ export const ReOrderButtons = ({ className }: { className?: string }) => {
);
};
+/**
+ * A button to clear all items from a SimpleFormIterator.
+ *
+ * Renders a trash icon button that removes all items from the array after confirmation.
+ * Used internally by SimpleFormIterator when disableClear is false.
+ *
+ * @example
+ * import { ClearArrayButton } from '@/components/admin';
+ *
+ * // Typically used internally by SimpleFormIterator
+ */
export const ClearArrayButton = (props: React.ComponentProps<"button">) => {
const translate = useTranslate();
return (
@@ -449,6 +531,21 @@ export const ClearArrayButton = (props: React.ComponentProps<"button">) => {
);
};
+/**
+ * A button to remove a single item from a SimpleFormIterator.
+ *
+ * Renders a close icon button that removes the current item from the array. Used internally
+ * by SimpleFormIterator for each item when disableRemove is false.
+ *
+ * @example
+ * import { SimpleFormIterator, RemoveItemButton } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <SimpleFormIterator removeButton={<RemoveItemButton />}>
+ * ...
+ * </SimpleFormIterator>
+ * );
+ */
export const RemoveItemButton = (props: React.ComponentProps<"button">) => {
const { remove, index } = useSimpleFormIteratorItem();
const { source } = useSimpleFormIterator();
diff --git a/src/components/admin/simple-form.tsx b/src/components/admin/simple-form.tsx
index df86394d..1b9fe39d 100644
--- a/src/components/admin/simple-form.tsx
+++ b/src/components/admin/simple-form.tsx
@@ -7,6 +7,25 @@ import { cn } from "@/lib/utils";
import { CancelButton } from "@/components/admin/cancel-button";
import { SaveButton } from "@/components/admin/form";
+/**
+ * A simple form layout with vertical stacking, validation, and default toolbar.
+ *
+ * Automatically includes a toolbar with Cancel and Save buttons unless you provide a custom toolbar.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/simpleform/ SimpleForm documentation}
+ *
+ * @example
+ * import { Create, SimpleForm, TextInput } from '@/components/admin';
+ *
+ * const PostCreate = () => (
+ * <Create>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <TextInput source="body" />
+ * </SimpleForm>
+ * </Create>
+ * );
+ */
export const SimpleForm = ({
children,
className,
@@ -22,6 +41,22 @@ export const SimpleForm = ({
</Form>
);
+/**
+ * A sticky form toolbar with default Cancel and Save buttons.
+ *
+ * Provides a consistent action bar for forms that sticks to the bottom of the viewport. By default,
+ * renders Cancel and Save buttons, but you can provide custom buttons as children.
+ *
+ * @example
+ * import { FormToolbar, CancelButton, SaveButton } from '@/components/admin';
+ *
+ * const CustomToolbar = () => (
+ * <FormToolbar>
+ * <CancelButton />
+ * <SaveButton label="Publish" />
+ * </FormToolbar>
+ * );
+ */
export const FormToolbar = ({
children,
className,
diff --git a/src/components/admin/single-field-list.tsx b/src/components/admin/single-field-list.tsx
index 89941297..42b9017d 100644
--- a/src/components/admin/single-field-list.tsx
+++ b/src/components/admin/single-field-list.tsx
@@ -5,6 +5,38 @@ import {
} from "ra-core";
import { Badge } from "@/components/ui/badge";
+/**
+ * Renders a horizontal list of records from a ListContext, displaying each as a badge.
+ *
+ * This component is used inside ArrayField, ReferenceArrayField, or ReferenceManyField to display
+ * records in a compact inline format. By default, it renders each record with its record representation.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/singlefieldlist/ SingleFieldList documentation}
+ *
+ * @example
+ * import {
+ * Show,
+ * RecordField,
+ * TextField,
+ * ReferenceArrayField,
+ * SingleFieldList,
+ * } from '@/components/admin';
+ *
+ * const PostShow = () => (
+ * <Show>
+ * <div className="flex flex-col gap-4">
+ * <RecordField source="title" />
+ * <RecordField label="Tags">
+ * <ReferenceArrayField reference="tags" source="tag_ids">
+ * <SingleFieldList>
+ * <TextField source="name" />
+ * </SingleFieldList>
+ * </ReferenceArrayField>
+ * </RecordField>
+ * </div>
+ * </Show>
+ * );
+ */
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export const SingleFieldList = <RecordType = any,>({
children,
diff --git a/src/components/admin/sort-button.tsx b/src/components/admin/sort-button.tsx
index a09f41e3..55000e03 100644
--- a/src/components/admin/sort-button.tsx
+++ b/src/components/admin/sort-button.tsx
@@ -24,6 +24,29 @@ import {
type ButtonProps = React.ComponentProps<typeof Button>;
+/**
+ * A button that opens a dropdown menu to change list sorting.
+ *
+ * Displays current sort field and order, and toggles between ASC and DESC when clicking the same field again.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/sortbutton/ SortButton documentation}
+ *
+ * @example
+ * import { SortButton } from '@/components/admin';
+ *
+ * const PostList = () => (
+ * <List render={({ data }) => (
+ * <div>
+ * <SortButton fields={["title", "published_at"]} />
+ * <ul>
+ * {data.map(post => (
+ * <li key={post.id}>{post.title}</li>
+ * ))}
+ * </ul>
+ * </div>
+ * )}>
+ * );
+ */
const SortButtonComponent = (props: SortButtonProps) => {
const {
fields,
diff --git a/src/components/admin/spinner.tsx b/src/components/admin/spinner.tsx
index 08c3b566..259f8eb4 100644
--- a/src/components/admin/spinner.tsx
+++ b/src/components/admin/spinner.tsx
@@ -34,6 +34,9 @@ interface SpinnerContentProps
className?: string;
}
+/**
+ * Animated spinner component for loading states.
+ */
export function Spinner({ size, show, className }: SpinnerContentProps) {
return (
<span className={spinnerVariants({ show })}>
diff --git a/src/components/admin/text-field.tsx b/src/components/admin/text-field.tsx
index 477c4dee..fbb89816 100644
--- a/src/components/admin/text-field.tsx
+++ b/src/components/admin/text-field.tsx
@@ -2,6 +2,27 @@ import type { HTMLAttributes } from "react";
import { useFieldValue, useTranslate } from "ra-core";
import type { FieldProps } from "@/lib/field.type";
+/**
+ * Displays a text value from a record field inside a span element.
+ *
+ * This is the default field component used in DataTable columns and RecordField components.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/textfield/ TextField documentation}
+ *
+ * @example
+ * import { List, DataTable, TextField } from '@/components/admin';
+ *
+ * export const UserList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="id" />
+ * <DataTable.Col>
+ * <TextField source="name" empty="resources.users.fields.name.empty" />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
+ */
export const TextField = <
RecordType extends Record<string, any> = Record<string, any>,
>({
diff --git a/src/components/admin/text-input.tsx b/src/components/admin/text-input.tsx
index 64d5b5eb..5253acd8 100644
--- a/src/components/admin/text-input.tsx
+++ b/src/components/admin/text-input.tsx
@@ -16,6 +16,27 @@ export type TextInputProps = InputProps & {
} & React.ComponentProps<"textarea"> &
React.ComponentProps<"input">;
+/**
+ * Single-line or multiline text input for string values.
+ *
+ * Use `<TextInput>` for short text fields like titles or names. Set `multiline` to `true`
+ * for longer content like descriptions or comments. Wraps shadcn's `<Input>` or `<Textarea>`
+ * component depending on the `multiline` prop.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/textinput/ TextInput documentation}
+ *
+ * @example
+ * import { Edit, SimpleForm, TextInput } from '@/components/admin';
+ *
+ * const PostEdit = () => (
+ * <Edit>
+ * <SimpleForm>
+ * <TextInput source="title" />
+ * <TextInput source="description" multiline rows={4} />
+ * </SimpleForm>
+ * </Edit>
+ * );
+ */
export const TextInput = (props: TextInputProps) => {
const resource = useResourceContext(props);
const {
diff --git a/src/components/admin/theme-mode-toggle.tsx b/src/components/admin/theme-mode-toggle.tsx
index bea6a7a6..d76584aa 100644
--- a/src/components/admin/theme-mode-toggle.tsx
+++ b/src/components/admin/theme-mode-toggle.tsx
@@ -9,6 +9,14 @@ import {
import { cn } from "@/lib/utils";
import { useTheme } from "@/components/admin/theme-provider";
+/**
+ * Toggle button that lets users switch between light, dark, and system UI themes.
+ *
+ * User's selection is persisted using the store.
+ * Automatically included in the default Layout component header.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/thememodetoggle ThemeModeToggle documentation}
+ */
export function ThemeModeToggle() {
const { theme, setTheme } = useTheme();
diff --git a/src/components/admin/theme-provider.tsx b/src/components/admin/theme-provider.tsx
index 62539880..5da8c05a 100644
--- a/src/components/admin/theme-provider.tsx
+++ b/src/components/admin/theme-provider.tsx
@@ -21,6 +21,11 @@ const initialState: ThemeProviderState = {
const ThemeProviderContext = createContext<ThemeProviderState>(initialState);
+/**
+ * Theme provider that enables light, dark, and system theme modes.
+ *
+ * @internal
+ */
export function ThemeProvider({
children,
defaultTheme = "system",
diff --git a/src/components/admin/toggle-filter-button.tsx b/src/components/admin/toggle-filter-button.tsx
index 0999ad03..379ea66a 100644
--- a/src/components/admin/toggle-filter-button.tsx
+++ b/src/components/admin/toggle-filter-button.tsx
@@ -6,6 +6,24 @@ import matches from "lodash/matches";
import pickBy from "lodash/pickBy";
import { CircleX } from "lucide-react";
+/**
+ * A button that toggles a specific filter value on/off.
+ *
+ * Renders a button that applies or removes a filter when clicked. Shows a close icon when the
+ * filter is active. Useful for quick filter presets like status or category.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/togglefilterbutton/ ToggleFilterButton documentation}
+ *
+ * @example
+ * import { ToggleFilterButton } from '@/components/admin';
+ *
+ * const PostFilters = () => (
+ * <div className="flex flex-row gap-2">
+ * <ToggleFilterButton label="Published" value={{ status: 'published' }} />
+ * <ToggleFilterButton label="Draft" value={{ status: 'draft' }} />
+ * </div>
+ * );
+ */
export const ToggleFilterButton = ({
label,
size = "sm",
diff --git a/src/components/admin/url-field.tsx b/src/components/admin/url-field.tsx
index fbe9ccf1..aa78eac6 100644
--- a/src/components/admin/url-field.tsx
+++ b/src/components/admin/url-field.tsx
@@ -6,6 +6,27 @@ import { cn } from "@/lib/utils";
import { genericMemo } from "@/lib/genericMemo";
import { FieldProps } from "@/lib/field.type";
+/**
+ * Displays a URL as a clickable hyperlink.
+ *
+ * Click events are prevented from bubbling up, making it safe to use in DataTable rows with rowClick.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/urlfield/ UrlField documentation}
+ *
+ * @example
+ * import { List, DataTable, UrlField } from '@/components/admin';
+ *
+ * const WebsiteList = () => (
+ * <List>
+ * <DataTable>
+ * <DataTable.Col source="id" />
+ * <DataTable.Col source="website">
+ * <UrlField source="website" empty="No website available" />
+ * </DataTable.Col>
+ * </DataTable>
+ * </List>
+ * );
+ */
const UrlFieldImpl = <
//eslint-disable-next-line @typescript-eslint/no-explicit-any
RecordType extends Record<string, any> = Record<string, any>,
diff --git a/src/components/admin/user-menu.tsx b/src/components/admin/user-menu.tsx
index 0bc7c411..bffb4188 100644
--- a/src/components/admin/user-menu.tsx
+++ b/src/components/admin/user-menu.tsx
@@ -22,6 +22,15 @@ export type UserMenuProps = {
children?: React.ReactNode;
};
+/**
+ * A user menu component displayed in the top right corner of the admin layout.
+ *
+ * Provides access to user-related actions such as profile, settings, and logout.
+ * Displays the user's avatar and name from the identity provider, and includes a logout option.
+ * Only displays in applications using authentication.
+ *
+ * @see {@link https://marmelab.com/shadcn-admin-kit/docs/usermenu UserMenu documentation}
+ */
export function UserMenu({ children }: UserMenuProps) {
const authProvider = useAuthProvider();
const { data: identity } = useGetIdentity();
diff --git a/src/hooks/saved-queries.tsx b/src/hooks/saved-queries.tsx
index ae1d70b0..8f8d80a2 100644
--- a/src/hooks/saved-queries.tsx
+++ b/src/hooks/saved-queries.tsx
@@ -14,8 +14,9 @@ export const useSavedQueries = (resource: string) => {
export interface SavedQuery {
label: string;
value: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
filter?: any;
-
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
displayedFilters?: any[];
sort?: SortPayload;
perPage?: number;
diff --git a/src/hooks/useSupportCreateSuggestion.tsx b/src/hooks/useSupportCreateSuggestion.tsx
index 02bfe1cb..73e630d1 100644
--- a/src/hooks/useSupportCreateSuggestion.tsx
+++ b/src/hooks/useSupportCreateSuggestion.tsx
@@ -74,7 +74,7 @@ export const useSupportCreateSuggestion = <T = unknown,>(
: createLabel,
);
},
-
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
handleChange: async (eventOrValue: MouseEvent | any) => {
const value = eventOrValue?.target?.value || eventOrValue;
const finalValue = Array.isArray(value) ? [...value].pop() : value;
@@ -116,6 +116,7 @@ export const useSupportCreateSuggestion = <T = unknown,>(
</CreateSuggestionContext.Provider>
) : null,
getOptionDisabled: (option) =>
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
(option as any)?.id === createHintValue || option === createHintValue,
};
};
@@ -143,7 +144,7 @@ export interface UseSupportCreateValue<T = unknown> {
createHintId: string;
getCreateItem: (filterValue?: string) => {
id: Identifier;
-
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
[key: string]: any;
};
handleChange: (eventOrValue: ChangeEvent | T) => Promise<void>;
@@ -183,5 +184,5 @@ export const useCreateSuggestionContext = () => {
/**
* @deprecated Use `OnCreateHandler` from "ra-core" when available.
*/
-
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type OnCreateHandler = (filter?: string) => any | Promise<any>;
diff --git a/src/lib/field.type.ts b/src/lib/field.type.ts
index ec1c74b1..63a4d746 100644
--- a/src/lib/field.type.ts
+++ b/src/lib/field.type.ts
@@ -2,9 +2,9 @@ import type { BaseFieldProps } from "ra-core";
import type { ReactNode } from "react";
export interface FieldProps<
-
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
RecordType extends Record<string, any> = Record<string, any>,
-> extends Omit<BaseFieldProps<RecordType>, 'resource'> {
+> extends Omit<BaseFieldProps<RecordType>, "resource"> {
/**
* The component to display when the field value is empty. Defaults to empty string.
*
diff --git a/src/lib/genericMemo.ts b/src/lib/genericMemo.ts
index a1c99a4b..0c83fd8b 100644
--- a/src/lib/genericMemo.ts
+++ b/src/lib/genericMemo.ts
@@ -1,4 +1,4 @@
-import type { FunctionComponent} from "react";
+import type { FunctionComponent } from "react";
import { memo } from "react";
/**