Scaffold NavSubItem component (#30205)

Co-authored-by: Makoto Morimoto <[email protected]>
Co-authored-by: Humberto Makoto Morimoto Burgos <[email protected]>

packages/react-components/react-nav-preview/etc/react-nav-preview.api.md

@@ -84,6 +84,23 @@ export type NavSlots = {
 // @public
 export type NavState = ComponentState<NavSlots> & NavContextValue;
 
+// @public
+export const NavSubItem: ForwardRefComponent<NavSubItemProps>;
+
+// @public (undocumented)
+export const navSubItemClassNames: SlotClassNames<NavSubItemSlots>;
+
+// @public
+export type NavSubItemProps = ComponentProps<NavSubItemSlots> & {};
+
+// @public (undocumented)
+export type NavSubItemSlots = {
+    root: Slot<'div'>;
+};
+
+// @public
+export type NavSubItemState = ComponentState<NavSubItemSlots>;
+
 // @public (undocumented)
 export type RegisterNavItemEventHandler = (data: NavItemRegisterData) => void;
 
@@ -93,6 +110,9 @@ export const renderNav_unstable: (state: NavState, contextValues: NavContextValu
 // @public
 export const renderNavCategoryItem_unstable: (state: NavCategoryItemState) => JSX.Element;
 
+// @public
+export const renderNavSubItem_unstable: (state: NavSubItemState) => JSX.Element;
+
 // @public
 export const useNav_unstable: (props: NavProps, ref: React_2.Ref<HTMLDivElement>) => NavState;
 
@@ -105,6 +125,12 @@ export const useNavCategoryItemStyles_unstable: (state: NavCategoryItemState) =>
 // @public (undocumented)
 export const useNavContext_unstable: () => NavContextValue;
 
+// @public
+export const useNavSubItem_unstable: (props: NavSubItemProps, ref: React_2.Ref<HTMLDivElement>) => NavSubItemState;
+
+// @public
+export const useNavSubItemStyles_unstable: (state: NavSubItemState) => NavSubItemState;
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/react-components/react-nav-preview/src/NavSubItem.ts

@@ -0,0 +1 @@
+export * from './components/NavSubItem/index';

packages/react-components/react-nav-preview/src/components/NavSubItem/NavSubItem.test.tsx

@@ -0,0 +1,9 @@
+import { isConformant } from '../../testing/isConformant';
+import { NavSubItem } from './NavSubItem';
+
+describe('NavSubItem', () => {
+  isConformant({
+    Component: NavSubItem,
+    displayName: 'NavSubItem',
+  });
+});

packages/react-components/react-nav-preview/src/components/NavSubItem/NavSubItem.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type { ForwardRefComponent } from '@fluentui/react-utilities';
+// import { useCustomStyleHook_unstable } from '@fluentui/react-shared-contexts';
+import { useNavSubItem_unstable } from './useNavSubItem';
+import { renderNavSubItem_unstable } from './renderNavSubItem';
+import { useNavSubItemStyles_unstable } from './useNavSubItemStyles.styles';
+import type { NavSubItemProps } from './NavSubItem.types';
+
+/**
+ * NavSubItem component - TODO: add more docs
+ */
+export const NavSubItem: ForwardRefComponent<NavSubItemProps> = React.forwardRef((props, ref) => {
+  const state = useNavSubItem_unstable(props, ref);
+
+  useNavSubItemStyles_unstable(state);
+  // TODO update types in packages/react-components/react-shared-contexts/src/CustomStyleHooksContext/CustomStyleHooksContext.ts
+  // https://github.com/microsoft/fluentui/blob/master/rfcs/react-components/convergence/custom-styling.md
+  // useCustomStyleHook_unstable('useNavSubItemStyles_unstable')(state);
+  return renderNavSubItem_unstable(state);
+});
+
+NavSubItem.displayName = 'NavSubItem';

packages/react-components/react-nav-preview/src/components/NavSubItem/NavSubItem.types.ts

@@ -0,0 +1,17 @@
+import type { ComponentProps, ComponentState, Slot } from '@fluentui/react-utilities';
+
+export type NavSubItemSlots = {
+  root: Slot<'div'>;
+};
+
+/**
+ * NavSubItem Props
+ */
+export type NavSubItemProps = ComponentProps<NavSubItemSlots> & {};
+
+/**
+ * State used in rendering NavSubItem
+ */
+export type NavSubItemState = ComponentState<NavSubItemSlots>;
+// TODO: Remove semicolon from previous line, uncomment next line, and provide union of props to pick from NavSubItemProps.
+// & Required<Pick<NavSubItemProps, 'propName'>>

packages/react-components/react-nav-preview/src/components/NavSubItem/index.ts

@@ -0,0 +1,5 @@
+export { NavSubItem } from './NavSubItem';
+export type { NavSubItemSlots, NavSubItemProps, NavSubItemState } from './NavSubItem.types';
+export { renderNavSubItem_unstable } from './renderNavSubItem';
+export { useNavSubItem_unstable } from './useNavSubItem';
+export { useNavSubItemStyles_unstable, navSubItemClassNames } from './useNavSubItemStyles.styles';

packages/react-components/react-nav-preview/src/components/NavSubItem/renderNavSubItem.tsx

@@ -0,0 +1,15 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource @fluentui/react-jsx-runtime */
+
+import { assertSlots } from '@fluentui/react-utilities';
+import type { NavSubItemState, NavSubItemSlots } from './NavSubItem.types';
+
+/**
+ * Render the final JSX of NavSubItem
+ */
+export const renderNavSubItem_unstable = (state: NavSubItemState) => {
+  assertSlots<NavSubItemSlots>(state);
+
+  // TODO Add additional slots in the appropriate place
+  return <state.root />;
+};

packages/react-components/react-nav-preview/src/components/NavSubItem/useNavSubItem.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import { getIntrinsicElementProps, slot } from '@fluentui/react-utilities';
+import type { NavSubItemProps, NavSubItemState } from './NavSubItem.types';
+
+/**
+ * Create the state required to render NavSubItem.
+ *
+ * The returned state can be modified with hooks such as useNavSubItemStyles_unstable,
+ * before being passed to renderNavSubItem_unstable.
+ *
+ * @param props - props from this instance of NavSubItem
+ * @param ref - reference to root HTMLDivElement of NavSubItem
+ */
+export const useNavSubItem_unstable = (props: NavSubItemProps, ref: React.Ref<HTMLDivElement>): NavSubItemState => {
+  return {
+    // TODO add appropriate props/defaults
+    components: {
+      // TODO add each slot's element type or component
+      root: 'div',
+    },
+    // TODO add appropriate slots, for example:
+    // mySlot: resolveShorthand(props.mySlot),
+    root: slot.always(
+      getIntrinsicElementProps('div', {
+        ref,
+        ...props,
+      }),
+      { elementType: 'div' },
+    ),
+  };
+};

packages/react-components/react-nav-preview/src/components/NavSubItem/useNavSubItemStyles.styles.ts

@@ -0,0 +1,33 @@
+import { makeStyles, mergeClasses } from '@griffel/react';
+import type { SlotClassNames } from '@fluentui/react-utilities';
+import type { NavSubItemSlots, NavSubItemState } from './NavSubItem.types';
+
+export const navSubItemClassNames: SlotClassNames<NavSubItemSlots> = {
+  root: 'fui-NavSubItem',
+  // TODO: add class names for all slots on NavSubItemSlots.
+  // Should be of the form `<slotName>: 'fui-NavSubItem__<slotName>`
+};
+
+/**
+ * Styles for the root slot
+ */
+const useStyles = makeStyles({
+  root: {
+    // TODO Add default styles for the root element
+  },
+
+  // TODO add additional classes for different states and/or slots
+});
+
+/**
+ * Apply styling to the NavSubItem slots based on the state
+ */
+export const useNavSubItemStyles_unstable = (state: NavSubItemState): NavSubItemState => {
+  const styles = useStyles();
+  state.root.className = mergeClasses(navSubItemClassNames.root, styles.root, state.root.className);
+
+  // TODO Add class names to slots, for example:
+  // state.mySlot.className = mergeClasses(styles.mySlot, state.mySlot.className);
+
+  return state;
+};

packages/react-components/react-nav-preview/src/index.ts

@@ -21,3 +21,9 @@ export type {
   NavItemRegisterData,
   RegisterNavItemEventHandler,
 } from './components/NavContext.types';
+
+export { NavSubItem } from './components/NavSubItem/NavSubItem';
+export type { NavSubItemSlots, NavSubItemProps, NavSubItemState } from './components/NavSubItem/NavSubItem.types';
+export { renderNavSubItem_unstable } from './components/NavSubItem/renderNavSubItem';
+export { useNavSubItem_unstable } from './components/NavSubItem/useNavSubItem';
+export { useNavSubItemStyles_unstable, navSubItemClassNames } from './components/NavSubItem/useNavSubItemStyles.styles';

packages/react-components/react-nav-preview/stories/NavSubItem/NavSubItemBestPractices.md

@@ -0,0 +1,5 @@
+## Best practices
+
+### Do
+
+### Don't

packages/react-components/react-nav-preview/stories/NavSubItem/NavSubItemDefault.stories.tsx

@@ -0,0 +1,5 @@
+import * as React from 'react';
+import { NavSubItem } from '@fluentui/react-nav-preview';
+import type { NavSubItemProps } from '@fluentui/react-nav-preview';
+
+export const Default = (props: Partial<NavSubItemProps>) => <NavSubItem {...props} />;

packages/react-components/react-nav-preview/stories/NavSubItem/index.stories.tsx

@@ -0,0 +1,18 @@
+import { NavSubItem } from '@fluentui/react-nav-preview';
+
+import descriptionMd from './NavSubItemDescription.md';
+import bestPracticesMd from './NavSubItemBestPractices.md';
+
+export { Default } from './NavSubItemDefault.stories';
+
+export default {
+  title: 'Preview Components/NavSubItem',
+  component: NavSubItem,
+  parameters: {
+    docs: {
+      description: {
+        component: [descriptionMd, bestPracticesMd].join('\n'),
+      },
+    },
+  },
+};