Scaffolds more Nav components (#30227)

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

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

@@ -14,6 +14,12 @@ import { SlotClassNames } from '@fluentui/react-utilities';
 // @public
 export const Nav: ForwardRefComponent<NavProps>;
 
+// @public
+export const NavCategory: ForwardRefComponent<NavCategoryProps>;
+
+// @public (undocumented)
+export const navCategoryClassNames: SlotClassNames<NavCategorySlots>;
+
 // @public
 export const NavCategoryItem: ForwardRefComponent<NavCategoryItemProps>;
 
@@ -36,6 +42,17 @@ export type NavCategoryItemState = ComponentState<NavCategoryItemSlots> & Pick<N
     selected: boolean;
 };
 
+// @public
+export type NavCategoryProps = ComponentProps<NavCategorySlots> & {};
+
+// @public (undocumented)
+export type NavCategorySlots = {
+    root: Slot<'div'>;
+};
+
+// @public
+export type NavCategoryState = ComponentState<NavCategorySlots>;
+
 // @public (undocumented)
 export const navClassNames: SlotClassNames<NavSlots>;
 
@@ -90,6 +107,23 @@ export const NavSubItem: ForwardRefComponent<NavSubItemProps>;
 // @public (undocumented)
 export const navSubItemClassNames: SlotClassNames<NavSubItemSlots>;
 
+// @public
+export const NavSubItemGroup: ForwardRefComponent<NavSubItemGroupProps>;
+
+// @public (undocumented)
+export const navSubItemGroupClassNames: SlotClassNames<NavSubItemGroupSlots>;
+
+// @public
+export type NavSubItemGroupProps = ComponentProps<NavSubItemGroupSlots> & {};
+
+// @public (undocumented)
+export type NavSubItemGroupSlots = {
+    root: Slot<'div'>;
+};
+
+// @public
+export type NavSubItemGroupState = ComponentState<NavSubItemGroupSlots>;
+
 // @public
 export type NavSubItemProps = ComponentProps<NavSubItemSlots> & {};
 
@@ -107,27 +141,48 @@ export type RegisterNavItemEventHandler = (data: NavItemRegisterData) => void;
 // @public (undocumented)
 export const renderNav_unstable: (state: NavState, contextValues: NavContextValues) => JSX.Element;
 
+// @public
+export const renderNavCategory_unstable: (state: NavCategoryState) => JSX.Element;
+
 // @public
 export const renderNavCategoryItem_unstable: (state: NavCategoryItemState) => JSX.Element;
 
 // @public
 export const renderNavSubItem_unstable: (state: NavSubItemState) => JSX.Element;
 
+// @public
+export const renderNavSubItemGroup_unstable: (state: NavSubItemGroupState) => JSX.Element;
+
 // @public
 export const useNav_unstable: (props: NavProps, ref: React_2.Ref<HTMLDivElement>) => NavState;
 
+// @public
+export const useNavCategory_unstable: (props: NavCategoryProps, ref: React_2.Ref<HTMLDivElement>) => NavCategoryState;
+
 // @public
 export const useNavCategoryItem_unstable: (props: NavCategoryItemProps, ref: React_2.Ref<HTMLButtonElement>) => NavCategoryItemState;
 
 // @public
 export const useNavCategoryItemStyles_unstable: (state: NavCategoryItemState) => NavCategoryItemState;
 
+// @public
+export const useNavCategoryStyles_unstable: (state: NavCategoryState) => NavCategoryState;
+
 // @public (undocumented)
 export const useNavContext_unstable: () => NavContextValue;
 
+// @public
+export const useNavStyles_unstable: (state: NavState) => NavState;
+
 // @public
 export const useNavSubItem_unstable: (props: NavSubItemProps, ref: React_2.Ref<HTMLDivElement>) => NavSubItemState;
 
+// @public
+export const useNavSubItemGroup_unstable: (props: NavSubItemGroupProps, ref: React_2.Ref<HTMLDivElement>) => NavSubItemGroupState;
+
+// @public
+export const useNavSubItemGroupStyles_unstable: (state: NavSubItemGroupState) => NavSubItemGroupState;
+
 // @public
 export const useNavSubItemStyles_unstable: (state: NavSubItemState) => NavSubItemState;
 

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

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

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

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

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

@@ -1,5 +1,5 @@
-export * from './Nav';
-export * from './Nav.types';
-export * from './renderNav';
-export * from './useNav';
-export * from './useNavStyles.styles';
+export { Nav } from './Nav';
+export type { NavSlots, NavProps, OnNavItemSelectData, NavState } from './Nav.types';
+export { renderNav_unstable } from './renderNav';
+export { useNav_unstable } from './useNav';
+export { useNavStyles_unstable, navClassNames } from './useNavStyles.styles';

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

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

packages/react-components/react-nav-preview/src/components/NavCategory/NavCategory.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 { useNavCategory_unstable } from './useNavCategory';
+import { renderNavCategory_unstable } from './renderNavCategory';
+import { useNavCategoryStyles_unstable } from './useNavCategoryStyles.styles';
+import type { NavCategoryProps } from './NavCategory.types';
+
+/**
+ * NavCategory component - TODO: add more docs
+ */
+export const NavCategory: ForwardRefComponent<NavCategoryProps> = React.forwardRef((props, ref) => {
+  const state = useNavCategory_unstable(props, ref);
+
+  useNavCategoryStyles_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('useNavCategoryStyles_unstable')(state);
+  return renderNavCategory_unstable(state);
+});
+
+NavCategory.displayName = 'NavCategory';

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

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

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

@@ -0,0 +1,5 @@
+export { NavCategory } from './NavCategory';
+export type { NavCategorySlots, NavCategoryProps, NavCategoryState } from './NavCategory.types';
+export { renderNavCategory_unstable } from './renderNavCategory';
+export { useNavCategory_unstable } from './useNavCategory';
+export { useNavCategoryStyles_unstable, navCategoryClassNames } from './useNavCategoryStyles.styles';

packages/react-components/react-nav-preview/src/components/NavCategory/renderNavCategory.tsx

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

packages/react-components/react-nav-preview/src/components/NavCategory/useNavCategory.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import { getIntrinsicElementProps, slot } from '@fluentui/react-utilities';
+import type { NavCategoryProps, NavCategoryState } from './NavCategory.types';
+
+/**
+ * Create the state required to render NavCategory.
+ *
+ * The returned state can be modified with hooks such as useNavCategoryStyles_unstable,
+ * before being passed to renderNavCategory_unstable.
+ *
+ * @param props - props from this instance of NavCategory
+ * @param ref - reference to root HTMLDivElement of NavCategory
+ */
+export const useNavCategory_unstable = (props: NavCategoryProps, ref: React.Ref<HTMLDivElement>): NavCategoryState => {
+  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/NavCategory/useNavCategoryStyles.styles.ts

@@ -0,0 +1,33 @@
+import { makeStyles, mergeClasses } from '@griffel/react';
+import type { SlotClassNames } from '@fluentui/react-utilities';
+import type { NavCategorySlots, NavCategoryState } from './NavCategory.types';
+
+export const navCategoryClassNames: SlotClassNames<NavCategorySlots> = {
+  root: 'fui-NavCategory',
+  // TODO: add class names for all slots on NavCategorySlots.
+  // Should be of the form `<slotName>: 'fui-NavCategory__<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 NavCategory slots based on the state
+ */
+export const useNavCategoryStyles_unstable = (state: NavCategoryState): NavCategoryState => {
+  const styles = useStyles();
+  state.root.className = mergeClasses(navCategoryClassNames.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/components/NavCategoryItem/index.ts

@@ -1,5 +1,5 @@
-export * from './NavCategoryItem';
-export * from './NavCategoryItem.types';
-export * from './renderNavCategoryItem';
-export * from './useNavCategoryItem';
-export * from './useNavCategoryItem.styles';
+export { NavCategoryItem } from './NavCategoryItem';
+export type { NavCategoryItemSlots, NavCategoryItemProps, NavCategoryItemState } from './NavCategoryItem.types';
+export { renderNavCategoryItem_unstable } from './renderNavCategoryItem';
+export { useNavCategoryItem_unstable } from './useNavCategoryItem';
+export { useNavCategoryItemStyles_unstable, navCategoryItemClassNames } from './useNavCategoryItem.styles';

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

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

packages/react-components/react-nav-preview/src/components/NavSubItemGroup/NavSubItemGroup.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 { useNavSubItemGroup_unstable } from './useNavSubItemGroup';
+import { renderNavSubItemGroup_unstable } from './renderNavSubItemGroup';
+import { useNavSubItemGroupStyles_unstable } from './useNavSubItemGroupStyles.styles';
+import type { NavSubItemGroupProps } from './NavSubItemGroup.types';
+
+/**
+ * NavSubItemGroup component - TODO: add more docs
+ */
+export const NavSubItemGroup: ForwardRefComponent<NavSubItemGroupProps> = React.forwardRef((props, ref) => {
+  const state = useNavSubItemGroup_unstable(props, ref);
+
+  useNavSubItemGroupStyles_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('useNavSubItemGroupStyles_unstable')(state);
+  return renderNavSubItemGroup_unstable(state);
+});
+
+NavSubItemGroup.displayName = 'NavSubItemGroup';

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

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

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

@@ -0,0 +1,5 @@
+export { NavSubItemGroup } from './NavSubItemGroup';
+export type { NavSubItemGroupSlots, NavSubItemGroupProps, NavSubItemGroupState } from './NavSubItemGroup.types';
+export { renderNavSubItemGroup_unstable } from './renderNavSubItemGroup';
+export { useNavSubItemGroup_unstable } from './useNavSubItemGroup';
+export { useNavSubItemGroupStyles_unstable, navSubItemGroupClassNames } from './useNavSubItemGroupStyles.styles';

packages/react-components/react-nav-preview/src/components/NavSubItemGroup/renderNavSubItemGroup.tsx

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

packages/react-components/react-nav-preview/src/components/NavSubItemGroup/useNavSubItemGroup.ts

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import { getIntrinsicElementProps, slot } from '@fluentui/react-utilities';
+import type { NavSubItemGroupProps, NavSubItemGroupState } from './NavSubItemGroup.types';
+
+/**
+ * Create the state required to render NavSubItemGroup.
+ *
+ * The returned state can be modified with hooks such as useNavSubItemGroupStyles_unstable,
+ * before being passed to renderNavSubItemGroup_unstable.
+ *
+ * @param props - props from this instance of NavSubItemGroup
+ * @param ref - reference to root HTMLDivElement of NavSubItemGroup
+ */
+export const useNavSubItemGroup_unstable = (
+  props: NavSubItemGroupProps,
+  ref: React.Ref<HTMLDivElement>,
+): NavSubItemGroupState => {
+  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' },
+    ),
+  };
+};