Work on Calendar doc page

mui · Nov 27, 2024 · 053cba2 · 053cba2
1 parent 87542d7
commit 053cba2
Show file tree

Hide file tree

Showing 3 changed files with 154 additions and 18 deletions.
diff --git a/docs/data/date-pickers/rfc/calendar.md b/docs/data/date-pickers/rfc/calendar.md
@@ -37,7 +37,7 @@ import { Calendar } from '@base-ui/x-date-pickers/Calendar';
 <Calendar.Root value={value} onChange={setValue}>
   <Calendar.Header.Root>
     <Calendar.GoToMonth target="previous">◀</Calendar.GoToMonth>
-    <Calendar.Header.Label />
+    <Calendar.Header.Title />
     <Calendar.GoToMonth target="next">▶</Calendar.GoToMonth>
   </Calendar.Header.Root>
   <Calendar.Days.Root>
@@ -88,7 +88,7 @@ import { Calendar } from '@base-ui/x-date-pickers/Calendar';
 <Calendar.Root value={value} onChange={setValue}>
   <Calendar.Header.Root>
     <Calendar.GoToYear target="previous">◀</Calendar.GoToYear>
-    <Calendar.Header.Label format="YYYY" />
+    <Calendar.Header.Title format="YYYY" />
     <Calendar.GoToYear target="next">▶</Calendar.GoToYear>
   </Calendar.Header.Root>
   <Calendar.Months.Root>
@@ -167,7 +167,7 @@ When MD3 is supported, the default views of `<DateCalendar />` should probably b
             target={view === 'year' ? 'day' : 'year'}
             disabled={view === 'month'}
           >
-            <Calendar.Header.Label format="YYYY" />
+            <Calendar.Header.Title format="YYYY" />
           </Calendar.SetView>
           <Calendar.GoToMonth target="next">▶</Calendar.GoToMonth>
         </div>
@@ -177,7 +177,7 @@ When MD3 is supported, the default views of `<DateCalendar />` should probably b
             target={view === 'month' ? 'day' : 'month'}
             disabled={view === 'year'}
           >
-            <Calendar.Header.Label format="YYYY" />
+            <Calendar.Header.Title format="YYYY" />
           </Calendar.SetView>
           <Calendar.GoToYear target="next">▶</Calendar.GoToYear>
         </div>
@@ -224,7 +224,7 @@ Today's `<DateCalendar />` header would look as follow:
   {({ view }) => (
     <React.Fragment>
       <Calendar.SetView target={view === 'year' ? 'month' : 'year'}>
-        <Calendar.Header.Label /> {view === 'year' ? '▲' : '▼'}
+        <Calendar.Header.Title /> {view === 'year' ? '▲' : '▼'}
       </Calendar.SetView>
       <Calendar.MatchView match="day">
         <div>
@@ -338,7 +338,7 @@ The `<CustomCalendarHeader />` component can be built in a few different ways:
    function CustomCalendarHeader() {
      return (
        <Calendar.Header.Root>
-         <Calendar.Header.Label format="MMMM YYYY" />
+         <Calendar.Header.Title format="MMMM YYYY" />
        </Calendar.Header.Root>
      );
    }
@@ -379,7 +379,7 @@ The `<CustomCalendarHeader />` component can be built in a few different ways:
      paddingRight: 12,
    });
 
-   export const PickerCalendarHeaderLabel = styled(Calendar.Header.Label)({
+   export const PickerCalendarHeaderLabel = styled(Calendar.Header.Title)({
      /** ... */
    });
 
@@ -507,7 +507,7 @@ Top level component for the `Calendar.Header.*` components.
 
 - Extends `React.HTMLAttributes<HTMLDivElement>`
 
-### `Calendar.Header.Label`
+### `Calendar.Header.Title`
 
 Renders the header label for the current value based on the provided format.
 

diff --git a/docs/data/date-pickers/rfc/field.md b/docs/data/date-pickers/rfc/field.md
@@ -8,7 +8,7 @@ title: DX - Field
 <p class="description">This page describes how people can use field with Material UI and how they can build custom fields while keeping the built-in editing behavior.</p>
 
 :::success
-This page extends the initial proposal made in [this Github comment](https://github.com/mui/mui-x/issues/14496#issuecomment-2348917294)
+This page extends the initial proposal made in [this GitHub comment](https://github.com/mui/mui-x/issues/14496#issuecomment-2348917294)
 :::
 
 ## Basic standalone usage
@@ -87,9 +87,12 @@ The field can then be rendered just like the Material UI fields:
 ### With Material UI
 
 :::success
-No DX change here compared to today
+No DX change here compared to today.
+The only change is that the field component are detecting if there is a picker around them and adding an opening button if so (instead of having the picker pass a prop to define this opening button).
 :::
 
+The field exposed by `@mui/x-date-pickers` and `@mui/x-date-pickers` automatically
+
 ```tsx
 import { DatePicker } from '@mui/x-date-pickers/DatePicker';
 
@@ -102,6 +105,15 @@ The concept of slots does not fit this use case very well, but the exploration o
 
 ### Without Material UI
 
+To use the field inside a picker, it has to contain a way to open the picker.
+
+:::success
+TODO: Find the DX to define a trigger button.
+
+- Should it a custom `Picker.Trigger` or directly the `Popover.Trigger` and `Dialog.Trigger`?
+- If it uses the Base UI component, how should it handle the responsive version of the picker?
+  :::
+
 #### Inside a picker from `@mui/x-date-pickers`
 
 Even if most applications with a custom field probably want to remove `@mui/material` entirely, using these custom fields inside a self contained picker component from `@mui/x-date-pickers/DatePicker` is totally doable.
@@ -187,7 +199,7 @@ When used inside a picker, `<MultiInputRangeField />` can be passed directly and
 ```
 
 :::success
-I have a POC of this in [#15505](https://github.com/mui/mui-x/pull/15505).
+THere is a POC of this in [#15505](https://github.com/mui/mui-x/pull/15505).
 :::
 
 ### Without Material UI

diff --git a/docs/data/date-pickers/rfc/picker.md b/docs/data/date-pickers/rfc/picker.md
@@ -1,28 +1,152 @@
 ---
 productId: x-date-pickers
-title: DX - Pickers
+title: DX - Picker
 ---
 
-# Fields
+# Picker
 
 <p class="description">This page describes how people can use picker with Material UI and how they can build custom pickers.</p>
 
 :::success
 This page extends the initial proposal made in [#14718](https://github.com/mui/mui-x/issues/14718)
 :::
 
-## With Material UI
+## Basic usage
 
-### Basic usage
+### With Material UI
 
 TODO
 
-### Override part of the UI
+### Without Material UI
+
+```tsx
+function CustomDatePicker(props) {
+  const manager = useDateManager();
+
+  return (
+    <Popover.Root>
+      <Picker.Root manager={manager} {...props}>
+        <PickerField.Root>
+          <PickerField.Root>
+            {/** See field documentation */}
+            <Popover.Trigger>📅</Popover.Trigger>
+          </PickerField.Root>
+        </PickerField.Root>
+        <Popover.Backdrop />
+        <Popover.Positioner>
+          <Popover.Popup>
+            <Picker.Views></Picker.Views>
+          </Popover.Popup>
+        </Popover.Positioner>
+      </Picker.Root>
+    </Popover.Root>
+  );
+}
+```
+
+## Add an action bar
+
+### With Material UI
+
+TODO
+
+### Without Material UI
+
+```tsx
+<Picker.Layout>
+  <Picker.Views>{/** See demo above */}</Picker.Views>
+  <div>
+    <Picker.Clear>Clear</Picker.Clear>
+    <Popover.Close>Close</Popover.Close>
+  </div>
+</Picker.Layout>
+```
+
+## Add a toolbar
+
+### With Material UI
+
+TODO
+
+### Without Material UI
+
+```tsx
+<Picker.Layout>
+  <Picker.Toolbar.Root>
+    <Picker.Toolbar.Title />
+  </Picker.Toolbar.Root>
+  <Picker.Views>{/** See demo above */}</Picker.Views>
+</Picker.Layout>
+```
+
+```tsx
+<Picker.Layout>
+  <Picker.Toolbar.Root>
+    <Picker.SetView target="year">
+      <Picker.Toolbar.Title format="YYYY" />
+    </Picker.SetView>
+    <Picker.SetView target="day">
+      <Picker.Toolbar.Title format="DD MMMM" />
+    </Picker.SetView>
+  </Picker.Toolbar.Root>
+  <Picker.Views>{/** See demo above */}</Picker.Views>
+</Picker.Layout>
+```
+
+## Add tabs
+
+### With Material UI
+
+TODO
+
+### Without Material UI
 
 TODO
 
-## Without Material UI
+## Add shortcuts
+
+### With Material UI
+
+TODO
+
+### Without Material UI
+
+TODO
+
+## Anatomy of `Picker.*`
+
+### `Picker.Root`
+
+TODO
+
+### `Picker.Clear`
+
+TODO
+
+### `Picker.SetValue`
+
+TODO
+
+### `Picker.SetView`
+
+TODO
+
+### `Picker.Layout`
+
+TODO
+
+### `Picker.Toolbar.Root`
+
+TODO
+
+### `Picker.Toolbar.Title`
+
+TODO
+
+### `Picker.Shortcuts.Root`
+
+TODO
 
-### Basic usage
+### `Picker.Shortcut.Item`
 
 TODO