[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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
 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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
 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.
 
 ## Basic

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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
 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 must wrap it to provide the necessary context.

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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
 `PageContainer` 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 @@ title: Persistent storage state
 
 <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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
+Toolpad Core provides a set of hooks that abstract dealing with persisting global state in the browser. Through these 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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
 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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
+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, it's recommended to read about the [basic concepts](/toolpad/core/introduction/base-concepts/) first.
+:::
+
+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,107 @@
+---
+title: Toolpad Core - Base Concepts
+---
+
+# Base concepts
+
+<p class="description">Understand 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/Button';
+import { DashboardLayout } from '@toolpad/core/DashboardLayout';
+```
+
+## Component Hierarchy
+
+The Toolpad Core library is designed to work under different React runtimes such as Next.js, Vite, or even your custom setup. Many of its components rely on functionality of the specific runtime they are used under. The key component in making the components runtime-aware 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.
+
+The `AppProvider` component accepts props to configure the app's navigation, theme, branding, router, authentication, and session, like so:
+
+```tsx
+<AppProvider
+  navigation={NAVIGATION}
+  theme={theme}
+  branding={BRANDING}
+  router={router}
+  authentication={AUTHENTICATION}
+  session={session}
+>
+  {props.children}
+</AppProvider>
+```
+
+Head over to the [AppProvider](/toolpad/core/react-app-provider/) page for more details and examples of the usage of all props.
+
+:::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.
+
+:::
+
+:::success
+If you are using Next.js, use the `AppProvider` exported from `@toolpad/core/nextjs`. This automatically sets up the router for you and you do not need to pass the `router` prop.
+:::
+
+## 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>