[docs] Add integration, base concepts

docs/data/toolpad/core/components/account/account.md

@@ -8,6 +8,10 @@ components: Account
 
 <p class="description">A component that renders an account management dropdown for your application.</p>
 
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
 The `Account` component is a quick and easy way to display an account management menu for authenticated users. It is deeply integrated with the `SignInPage` and `DashboardLayout` components, meaning that it automatically appears in the top navigation bar inside `DashboardLayout` once your users have signed in through the `SignInPage`.
 
 ## States

docs/data/toolpad/core/components/app-provider/app-provider.md

@@ -8,6 +8,10 @@ components: AppProvider
 
 <p class="description">The app provider component provides the necessary context to easily set up a Toolpad application.</p>
 
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
 By wrapping an application at the root level with an `AppProvider` component, many of Toolpad's features (such as routing, navigation and theming) can be automatically enabled to their fullest extent, abstracting away complexity and helping you focus on the details that matter.
 
 It is not mandatory that every application is wrapped in an `AppProvider`, but it is highly recommended for most apps that use Toolpad.

docs/data/toolpad/core/components/dashboard-layout/dashboard-layout.md

@@ -8,6 +8,10 @@ components: AppProvider, DashboardLayout, Account
 
 <p class="description">The dashboard layout component provides a customizable out-of-the-box layout for a typical dashboard page.</p>
 
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
 The `DashboardLayout` component is a quick, easy way to provide a standard full-screen layout with a header and sidebar to any dashboard page, as well as ready-to-use and easy to customize navigation and branding.
 
 Many features of this component are configurable through the [AppProvider](https://mui.com/toolpad/core/react-app-provider/) component that should wrap it.

docs/data/toolpad/core/components/page-container/page-container.md

@@ -8,6 +8,10 @@ components: PageContainer, PageContainerToolbar
 
 <p class="description">A component that wraps page content and provides a title, breadcrumbs, and page actions.</p>
 
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
 `PageContent` is the ideal wrapper for the content of your dashboard. It shows the current page title, and provides breadcrumbs to navigate back into the current hierarchy. It makes your page responsive through the use of the Material&nbsp;UI Container component under the hood.
 
 Just like [`DashboardLayout`](/toolpad/core/react-dashboard-layout/), `PageContainer` uses the navigation structure that is defined in the [`AppProvider`](/toolpad/core/react-app-provider/) to build up its breadcrumbs and title.

docs/data/toolpad/core/components/persistent-state/persistent-state.md

@@ -7,7 +7,11 @@
 
 <p class="description">Hooks for synchronizing React state with browser storage.</p>
 
-Toolpad provides a set of primitives that harmonize how you deal with persisting global state in the browser. Through our hooks you can synchronise React state with local storage or session storage, or in the url as a query parameter. These hooks all follow a similar philosophy: they identify their data with a unique key and support rich data types through the use of codecs.
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
+Toolpad Core provides a set of primitives that harmonize how you deal with persisting global state in the browser. Through our hooks you can synchronise React state with local storage or session storage, or in the url as a query parameter. These hooks all follow a similar philosophy: they identify their data with a unique key and support rich data types through the use of codecs.
 
 The hook's signature intentionally resembles the `React.useState` hook. Where the first parameter represents the key under which to store the state in the browser, and the second parameter corresponds to the initial value. An optional third parameter can be used to configure the hook.
 

docs/data/toolpad/core/components/sign-in-page/sign-in-page.md

@@ -8,6 +8,10 @@ components: SignInPage, Account, NotificationsProvider
 
 <p class="description">A customizable sign-in UI component that abstracts away the pain needed to wire together a secure authentication page for your application.</p>
 
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
 The `SignInPage` component is a quick way to generate a ready-to-use authentication page with multiple OAuth providers, or a credentials form.
 
 ## OAuth

docs/data/toolpad/core/components/use-dialogs/use-dialogs.md

@@ -8,7 +8,11 @@ components: DialogsProvider
 
 <p class="description">Imperative APIs to open and interact with dialogs.</p>
 
-Toolpad core offers a set of abstractions that makes interacting with dialogs simpler. It has an imperative API to open and close dialogs, and allows dialogs to be stacked on top of each other.
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
+Toolpad Core offers a set of abstractions that makes interacting with dialogs simpler. It has an imperative API to open and close dialogs, and allows dialogs to be stacked on top of each other.
 
 First thing you need to do is install the DialogsProvider at the root of your application.
 

docs/data/toolpad/core/components/use-notifications/use-notifications.md

@@ -8,7 +8,11 @@ components: NotificationsProvider
 
 <p class="description">Imperative APIs to show and interact with application notifications.</p>
 
-Toolpad core offers a set of abstractions that make it easier to interact with notifications. Notifications are used to give short updates to the user about things that are happening during the application lifetime. They appear at the bottom of the screen. The Toolpad API allows for opening multiple notifications concurrenlty.
+:::info
+If this is your first time using Toolpad Core, you might want to start with the [base concepts](/docs/data/toolpad/core/introduction/base-concepts/) instead.
+:::
+
+Toolpad Core offers a set of abstractions that make it easier to interact with notifications. Notifications are used to give short updates to the user about things that are happening during the application lifetime. They appear at the bottom of the screen. The Toolpad API allows for opening multiple notifications concurrenlty.
 
 First thing you need to do to get access to the notifications APIs is install the NotificationsProvider.
 

docs/data/toolpad/core/introduction/base-concepts.md

@@ -0,0 +1,173 @@
+---
+title: Toolpad Core - Base Concepts
+---
+
+# Base Concepts
+
+<p class="description">Understanding the fundamental concepts of Toolpad Core to effectively integrate and use it in your projects.</p>
+
+## Imports
+
+Toolpad Core components can be imported directly from the `@toolpad/core` package. This allows you to use them alongside your existing Material UI or other components.
+
+```tsx
+import { Button } from '@mui/material';
+import { DashboardLayout } from '@toolpad/core/DashboardLayout';
+```
+
+## Component Hierarchy
+
+The Toolpad Core library is designed to work within your existing React application structure. The key component in this hierarchy is the `AppProvider`.
+
+### App Provider
+
+The `AppProvider` acts as a bridge between your application's runtime and Toolpad components. It should wrap your entire application or the part of your application where you want to use Toolpad components.
+
+```tsx
+import { AppProvider } from '@toolpad/core/AppProvider';
+
+function MyApp({ Component, pageProps }) {
+ return (
+ <AppProvider>
+ <Component {...pageProps} />
+ </AppProvider>
+ );
+}
+```
+
+By wrapping your application with `AppProvider`, you ensure that all other Toolpad components you use have access to the necessary context and functionality.
+
+#### AppProvider Props
+
+The `AppProvider` component accepts the following props:
+
+- `theme`: The theme to be used by the app in light/dark mode. If you are using [Material UI with a custom theme](https://mui.com/material-ui/customization/theming/), you can directly pass it here.
+
+ ```tsx
+ import { createTheme } from '@mui/material';
+ import { AppProvider } from '@toolpad/core/AppProvider';
+
+ const customTheme = createTheme({
+ cssVariables: {
+ colorSchemeSelector: 'data-toolpad-color-scheme',
+ },
+ colorSchemes: {
+ light: {
+ // ...
+ },
+ dark: {
+ // ...
+ },
+ },
+ });
+
+ function MyApp({ Component, pageProps }) {
+ return <AppProvider theme={theme}>/* Your App */</AppProvider>;
+ }
+ ```
+
+- `branding`: Branding options for the app.
+
+ ```tsx
+ import { AppProvider } from '@toolpad/core/AppProvider';
+
+ function MyApp({ Component, pageProps }) {
+ return <AppProvider branding={{ title: 'My Company Name' }}>..</AppProvider>;
+ }
+ ```
+
+- `navigation`: The navigation structure for the app.
+
+ ```tsx
+ import { ShoppingCartIcon } from '@mui/icons-material';
+ import { AppProvider } from '@toolpad/core/AppProvider';
+
+ const NAVIGATION: Navigation = [
+ {
+ segment: 'orders',
+ title: 'Orders',
+ icon: <ShoppingCartIcon />,
+ },
+ ];
+
+ function MyApp({ Component, pageProps }) {
+ return <AppProvider navigation={NAVIGATION}>..</AppProvider>;
+ }
+ ```
+
+- `router`: Router implementation used to navigate between pages. This is the same router that you use in your application.
+
+ :::info
+ Toolpad Core doesn't handle routing itself. Instead, it's designed to integrate seamlessly with your existing routing solution, whether you're using:
+
+ - Next.js App Router
+ - Next.js Pages Router
+ - React Router
+ - Or any other routing library which implements the same interface
+
+ You can pass the router implementation to the `AppProvider` component using the `router` prop. You do not need to pass this prop if you are using Next.js, since it has a file-system based router.
+
+ :::
+
+- `authentication`: Authentication implementation used inside Toolpad components.
+
+- `session`: Session implementation used inside Toolpad components.
+
+ ```tsx
+ import { AppProvider } from '@toolpad/core/AppProvider';
+ import { SessionProvider, signIn, signOut } from 'next-auth/react';
+ import { auth } from '../auth';
+
+ function MyApp({ Component, pageProps }) {
+ const session = await auth();
+ return (
+ <SessionProvider session={session}>
+ <AppProvider authentication={{ signIn, signOut }} session={session}>
+ ..
+ </AppProvider>
+ </SessionProvider>
+ );
+ }
+ ```
+
+It is important to note that the `AppProvider` component does not perform routing or authentication by itself. It integrates with any of your existing implementations for the same.
+
+:::info
+The [AppProvider](/toolpad/core/react-app-provider/) page contains more details and examples of the usage of these props.
+:::
+
+## Slots
+
+Toolpad Core uses slots for component customization. Slots allow you to override specific parts of a component, providing flexibility in styling and functionality. You can also pass additional props to specific slots using the `slotProps` prop.
+
+Here's an example using the `SignInPage` component:
+
+```tsx
+import { SignInPage } from '@toolpad/core/SignInPage';
+function MyComponent() {
+ return (
+ <SignInPage
+ slots={{
+ emailField: CustomEmailField,
+
+ }}
+ slotProps={{
+ passwordField: {
+ variant: 'outlined',
+ },
+ }}
+ >
+ Custom Button
+ </Button>
+ );
+}
+```
+
+In this example:
+
+- The `slots` prop allows you to replace entire parts of the component.
+- The `slotProps` prop lets you pass additional props to specific slots.
+
+## Next Steps
+
+Now that you understand the basic concepts of Toolpad Core, you're ready to start integrating it into your project. Head over to the [integration docs](/toolpad/core/introduction/integration/) to learn more.

docs/data/toolpad/core/introduction/installation.md

@@ -4,6 +4,44 @@ title: Toolpad Core - Installation
 
 # Installation
 
+## Manual Installation
+
+Use your preferred package manager to install `@toolpad/core` in your project:
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npm install -S @toolpad/core
+```
+
+```bash yarn
+yarn add @toolpad/core
+```
+
+```bash pnpm
+pnpm add @toolpad/core
+```
+
+</codeblock>
+
+The Toolpad Core package has a peer dependency on `@mui/material` and `@mui/icons-material`. If you aren't using these already in your project, you can install them with:
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npm install -S @mui/material @mui/icons-material @emotion/react @emotion/styled
+```
+
+```bash yarn
+yarn add @mui/material @mui/icons-material @emotion/react @emotion/styled
+```
+
+```bash pnpm
+pnpm add @mui/material @mui/icons-material @emotion/react @emotion/styled
+```
+
+</codeblock>
+
 ## Automatic Installation
 
 <p class="description">Learn how to install Toolpad Core in your local environment.</p>
@@ -74,41 +112,3 @@ yarn dev
 {{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/core/installation-1.png", "alt": "Toolpad Core entry point", "caption": "Starting with Toolpad Core", "zoom": true, "indent": 1 }}
 
 5. Installation is complete! Begin building your project by making edits to `(dashboard/page/page.tsx`. To understand how to leverage Toolpad Core to build dashboards quickly, [see the detailed tutorial](/toolpad/core/introduction/tutorial/).
-
-## Manual Installation
-
-Use your preferred package manager to install `@toolpad/core` in your project:
-
-<codeblock storageKey="package-manager">
-
-```bash npm
-npm install -S @toolpad/core
-```
-
-```bash yarn
-yarn add @toolpad/core
-```
-
-```bash pnpm
-pnpm add @toolpad/core
-```
-
-</codeblock>
-
-The Toolpad Core package has a peer dependency on `@mui/material` and `@mui/icons-material`. If you aren't using these already in your project, you can install them with:
-
-<codeblock storageKey="package-manager">
-
-```bash npm
-npm install -S @mui/material @mui/icons-material @emotion/react @emotion/styled
-```
-
-```bash yarn
-yarn add @mui/material @mui/icons-material @emotion/react @emotion/styled
-```
-
-```bash pnpm
-pnpm add @mui/material @mui/icons-material @emotion/react @emotion/styled
-```
-
-</codeblock>