Add TimePicker to docsite (#25175)

* Add TimePicker to docsite

It had a react-example but wasn't added to the public docsite.

* Add TimePicker to docsite api generator.

* Added TimePicker control best practices docs

* add @docCategory tag to TimePicker

This enables proper API generation in public-docsite-resources.

* change files

Co-authored-by: James Wu <[email protected]>

apps/public-docsite-resources/config/api-docs.js

@@ -85,6 +85,7 @@ module.exports = {
       'TeachingBubble',
       'Text',
       'TextField',
+      'TimePicker',
       'Toggle',
       'Tooltip',
     ],

apps/public-docsite-resources/src/AppDefinition.tsx

@@ -485,6 +485,12 @@ export const AppDefinition: IAppDefinition = {
           name: 'TextField',
           url: '#/examples/textfield',
         },
+        {
+          component: require<any>('./components/pages/TimePickerPage').TimePickerPage,
+          key: 'TimePicker',
+          name: 'TimePicker',
+          url: '#/examples/timepicker',
+        },
         {
           component: require<any>('./components/pages/TogglePage').TogglePage,
           key: 'Toggle',

apps/public-docsite-resources/src/components/pages/TimePickerPage.tsx

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { DemoPage } from '../DemoPage';
+
+import { TimePickerPageProps } from '@fluentui/react-examples/lib/react/TimePicker/TimePicker.doc';
+
+export const TimePickerPage = (props: { isHeaderVisible: boolean }) => (
+  <DemoPage
+    jsonDocs={require('../../../dist/api/react/TimePicker.page.json')}
+    {...{ ...TimePickerPageProps, ...props }}
+  />
+);

apps/public-docsite/src/SiteDefinition/SiteDefinition.pages/Controls/web.tsx

@@ -35,6 +35,7 @@ export const categories: { Other?: ICategory; [name: string]: ICategory } = {
     DatePicker: {},
     PeoplePicker: {},
     SwatchColorPicker: {},
+    TimePicker: {},
   },
   'Items & Lists': {
     List: { title: 'Basic List' },

apps/public-docsite/src/pages/Controls/TimePickerPage/TimePickerPage.doc.ts

@@ -0,0 +1,8 @@
+import { TFabricPlatformPageProps } from '../../../interfaces/Platforms';
+import { TimePickerPageProps as ExternalProps } from '@fluentui/react-examples/lib/react/TimePicker/TimePicker.doc';
+
+export const TimePickerPageProps: TFabricPlatformPageProps = {
+  web: {
+    ...(ExternalProps as any),
+  },
+};

apps/public-docsite/src/pages/Controls/TimePickerPage/TimePickerPage.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { ControlsAreaPage, IControlsPageProps } from '../ControlsAreaPage';
+import { TimePickerPageProps } from './TimePickerPage.doc';
+
+export const TimePickerPage: React.FunctionComponent<IControlsPageProps> = props => {
+  return <ControlsAreaPage {...props} {...TimePickerPageProps[props.platform]} />;
+};

change/@fluentui-react-d7ed3976-3c18-467f-affb-9928fd9ec770.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "docs: add @docCategory documentation comment to TimePicker",
+  "packageName": "@fluentui/react",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-examples/src/react/TimePicker/TimePicker.doc.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+import { IDocPageProps } from '@fluentui/react/lib/common/DocPage.types';
+
+import { TimePickerBasicExample } from './TimePicker.Example';
+const TimePickerExampleCode = require('!raw-loader?esModule=false!@fluentui/react-examples/src/react/TimePicker/TimePicker.Example.tsx') as string;
+
+export const TimePickerPageProps: IDocPageProps = {
+  title: 'TimePicker',
+  componentName: 'TimePicker',
+  componentUrl: 'https://github.com/microsoft/fluentui/tree/master/packages/react/src/components/TimePicker',
+  examples: [
+    {
+      title: 'TimePicker basic',
+      code: TimePickerExampleCode,
+      view: <TimePickerBasicExample />,
+    },
+  ],
+  overview: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react/TimePicker/docs/TimePickerOverview.md'),
+  bestPractices: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react/TimePicker/docs/TimePickerBestPractices.md'),
+  isHeaderVisible: true,
+  isFeedbackVisible: true,
+};

packages/react-examples/src/react/TimePicker/docs/TimePickerBestPractices.md

@@ -0,0 +1,11 @@
+### Layout
+
+- Time pickers can be coupled with the date picker control. The selected date object returned by the date picker can be supplied to the time picker via time picker's `defaultValue` prop. The time picker should be horizontally aligned next to the date picker if these two controls are used together.
+
+### Content
+
+- By default, the time picker dropdown list displays time options in 30 minute increments over a 24-hour time range using 24-hour formatting (hh:mm).
+- The time increment between each dropdown option can be modified using the `increments` prop.
+- The overall time range the dropdown options span can be modified using the `timeRange` prop.
+- Each dropdown option can display seconds using the `showSeconds` prop.
+- Each dropdown option can display time in 12-hour format (hh:mm AM/PM) using the `useHour12` prop.

packages/react-examples/src/react/TimePicker/docs/TimePickerOverview.md

@@ -0,0 +1 @@
+`TimePicker` offers a control that’s optimized for selecting a time from a drop-down list or using free-form input to enter a custom time.

packages/react/src/components/TimePicker/TimePicker.tsx

@@ -30,6 +30,9 @@ const getDefaultStrings = (useHour12: boolean, showSeconds: boolean): ITimePicke
   };
 };
 
+/**
+ * {@docCategory TimePicker}
+ */
 export const TimePicker: React.FunctionComponent<ITimePickerProps> = ({
   label,
   increments = 30,

packages/react/src/components/TimePicker/TimePicker.types.ts

@@ -2,6 +2,7 @@ import * as React from 'react';
 import type { IComboBox, IComboBoxProps } from '../../ComboBox';
 
 /**
+ * {@docCategory TimePicker}
  * Range of start and end hours to be shown in the TimePicker.
  */
 export interface ITimeRange {
@@ -13,13 +14,17 @@ export interface ITimeRange {
 }
 
 /**
+ * {@docCategory TimePicker}
  * Localized strings to use in the TimePicker
  */
 export interface ITimePickerStrings {
   /** Error message to render below the field if input parsing fails. */
   invalidInputErrorMessage: string;
 }
 
+/**
+ * {@docCategory TimePicker}
+ */
 export interface ITimePickerProps
   extends Omit<
     IComboBoxProps,