From 202b78edc182d2c97f319362e10acfe44a4228c8 Mon Sep 17 00:00:00 2001
From: Anton Nesterov <anton@nesterov.cc>
Date: Sun, 8 Sep 2024 14:55:53 +0000
Subject: [PATCH] feat(Stepper): document undocumented start and end options,
 add types & improve (#7128)

---
 components/doc/common/apidoc/index.json     | 33 +++++++++++++++++++++
 components/doc/stepper/theming/styleddoc.js |  8 +++++
 components/lib/stepper/Stepper.js           | 22 ++++++++++++--
 components/lib/stepper/StepperBase.js       |  8 +++--
 components/lib/stepper/stepper.d.ts         | 18 +++++++++++
 5 files changed, 84 insertions(+), 5 deletions(-)

diff --git a/components/doc/common/apidoc/index.json b/components/doc/common/apidoc/index.json
index 889ba650a8..c2aa3b5692 100644
--- a/components/doc/common/apidoc/index.json
+++ b/components/doc/common/apidoc/index.json
@@ -47347,6 +47347,14 @@
                             "default": "0",
                             "description": "Active step index of stepper."
                         },
+                        {
+                            "name": "end",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "ReactNode | Function",
+                            "default": "",
+                            "description": "The template of end section."
+                        },
                         {
                             "name": "headerPosition",
                             "optional": true,
@@ -47387,6 +47395,14 @@
                             "default": "",
                             "description": "Used to configure passthrough(pt) options of the component."
                         },
+                        {
+                            "name": "start",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "ReactNode | Function",
+                            "default": "",
+                            "description": "The template of start section."
+                        },
                         {
                             "name": "unstyled",
                             "optional": true,
@@ -47470,6 +47486,20 @@
                             "type": "StepperPanelPassThroughOptionType",
                             "description": "Used to pass attributes to the end handler's DOM element."
                         },
+                        {
+                            "name": "start",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "StepperPassThroughType<HTMLAttributes<HTMLDivElement>>",
+                            "description": "Uses to pass attributes to the start's DOM element."
+                        },
+                        {
+                            "name": "end",
+                            "optional": true,
+                            "readonly": false,
+                            "type": "StepperPassThroughType<HTMLAttributes<HTMLDivElement>>",
+                            "description": "Uses to pass attributes to the right's DOM element."
+                        },
                         {
                             "name": "hooks",
                             "optional": true,
@@ -47535,6 +47565,9 @@
             "values": {
                 "StepperPassThroughOptionType": {
                     "values": "StepperPassThroughAttributes | Function | string | null | undefined"
+                },
+                "StepperPassThroughType": {
+                    "values": "PassThroughType<T, StepperPassThroughMethodOptions>"
                 }
             }
         }
diff --git a/components/doc/stepper/theming/styleddoc.js b/components/doc/stepper/theming/styleddoc.js
index fe2bd9429a..6e4e8330af 100644
--- a/components/doc/stepper/theming/styleddoc.js
+++ b/components/doc/stepper/theming/styleddoc.js
@@ -67,6 +67,14 @@ export function StyledDoc() {
                             <td>p-stepper-content</td>
                             <td>Container element of stepper content.</td>
                         </tr>
+                        <tr>
+                            <td>p-stepper-start</td>
+                            <td>Start content container.</td>
+                        </tr>
+                        <tr>
+                            <td>p-stepper-end</td>
+                            <td>End content container.</td>
+                        </tr>
                     </tbody>
                 </table>
             </div>
diff --git a/components/lib/stepper/Stepper.js b/components/lib/stepper/Stepper.js
index f7f59a0ed7..d88d037f1c 100644
--- a/components/lib/stepper/Stepper.js
+++ b/components/lib/stepper/Stepper.js
@@ -3,7 +3,7 @@ import { PrimeReactContext } from '../api/Api';
 import { useHandleStyle } from '../componentbase/ComponentBase';
 import { CSSTransition } from '../csstransition/CSSTransition';
 import { useMergeProps, useMountEffect, useUpdateEffect } from '../hooks/Hooks';
-import { UniqueComponentId, classNames } from '../utils/Utils';
+import { UniqueComponentId, classNames, ObjectUtils } from '../utils/Utils';
 import { StepperBase } from './StepperBase';
 import { StepperContent } from './StepperContent';
 import { StepperHeader } from './StepperHeader';
@@ -14,6 +14,8 @@ export const Stepper = React.memo(
         const mergeProps = useMergeProps();
         const context = React.useContext(PrimeReactContext);
         const props = StepperBase.getProps(inProps, context);
+        const start = ObjectUtils.getJSXElement(props.start, props);
+        const end = ObjectUtils.getJSXElement(props.end, props);
         const { ptm, cx, isUnstyled, ptmo } = StepperBase.setMetaData({
             props
         });
@@ -23,6 +25,20 @@ export const Stepper = React.memo(
 
         useHandleStyle(StepperBase.css.styles, isUnstyled, { name: 'stepper' });
 
+        const startProps = mergeProps(
+            {
+                className: cx('start')
+            },
+            ptm('start')
+        );
+
+        const endProps = mergeProps(
+            {
+                className: cx('end')
+            },
+            ptm('end')
+        );
+
         useMountEffect(() => {
             if (!idState) {
                 setIdState(UniqueComponentId());
@@ -326,10 +342,10 @@ export const Stepper = React.memo(
 
         return (
             <div {...rootProps}>
-                {props.start && props.start()}
+                {start && <div {...startProps}>{start}</div>}
                 {props.orientation === 'horizontal' && createHorizontal()}
                 {props.orientation === 'vertical' && createVertical()}
-                {props.end && props.end()}
+                {end && <div {...endProps}>{end}</div>}
             </div>
         );
     })
diff --git a/components/lib/stepper/StepperBase.js b/components/lib/stepper/StepperBase.js
index 0425906933..fd1b6734ff 100644
--- a/components/lib/stepper/StepperBase.js
+++ b/components/lib/stepper/StepperBase.js
@@ -31,7 +31,9 @@ const classes = {
                 'p-stepper-panel-active': props.orientation === 'vertical' && isStepActive(index)
             })
     },
-    panelContainer: 'p-stepper-panels'
+    panelContainer: 'p-stepper-panels',
+    start: 'p-stepper-start',
+    end: 'p-stepper-end'
 };
 
 const styles = `
@@ -134,7 +136,9 @@ export const StepperBase = ComponentBase.extend({
         orientation: 'horizontal',
         headerPosition: 'right',
         linear: false,
-        onChangeStep: null
+        onChangeStep: null,
+        start: null,
+        end: null
     },
     css: {
         classes,
diff --git a/components/lib/stepper/stepper.d.ts b/components/lib/stepper/stepper.d.ts
index 9d8454b7ab..93f40fbf7a 100644
--- a/components/lib/stepper/stepper.d.ts
+++ b/components/lib/stepper/stepper.d.ts
@@ -11,8 +11,10 @@ import * as React from 'react';
 import { ComponentHooks } from '../componentbase/componentbase';
 import { PassThroughOptions } from '../passthrough';
 import { StepperPanelPassThroughOptionType } from '../stepperpanel/stepperpanel';
+import { PassThroughType } from '../utils';
 
 export declare type StepperPassThroughOptionType = StepperPassThroughAttributes | ((options: StepperPassThroughMethodOptions) => StepperPassThroughAttributes | string) | string | null | undefined;
+export declare type StepperPassThroughType<T> = PassThroughType<T, StepperPassThroughMethodOptions>;
 
 /**
  * Custom passthrough(pt) option method.
@@ -43,6 +45,14 @@ export interface StepperPassThroughOptions {
      * Used to pass attributes to the end handler's DOM element.
      */
     stepperpanel?: StepperPanelPassThroughOptionType;
+    /**
+     * Uses to pass attributes to the start's DOM element.
+     */
+    start?: StepperPassThroughType<React.HTMLAttributes<HTMLDivElement>>;
+    /**
+     * Uses to pass attributes to the right's DOM element.
+     */
+    end?: StepperPassThroughType<React.HTMLAttributes<HTMLDivElement>>;
     /**
      * Used to manage all lifecycle hooks
      * @see {@link ComponentHooks}
@@ -122,6 +132,14 @@ export interface StepperProps {
      * Callback to invoke when an active panel is changed.
      */
     onChangeStep?(event: StepperChangeEvent): void;
+    /**
+     * The template of start section.
+     */
+    start?: React.ReactNode | ((props: StepperProps) => React.ReactNode);
+    /**
+     * The template of end section.
+     */
+    end?: React.ReactNode | ((props: StepperProps) => React.ReactNode);
     /**
      * Uses to pass attributes to DOM elements inside the component.
      * @type {StepperPassThroughOptions}