chore: deprecate getNativeElementProps in favor of getIntrinsicElementProps

change/@fluentui-react-components-2c838613-ebcb-423a-951e-39f4cac446cb.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "chore: deprecate getNativeElementProps in favor of getIntrinsicElementProps",
+  "packageName": "@fluentui/react-components",
+  "email": "bernardo.sunderhus@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-utilities-f62a2faa-62dc-434e-b710-08386be99632.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "chore: deprecate getNativeElementProps in favor of getIntrinsicElementProps",
+  "packageName": "@fluentui/react-utilities",
+  "email": "bernardo.sunderhus@gmail.com",
+  "dependentChangeType": "patch"
+}

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

@@ -97,6 +97,8 @@ export {
   usePortalMountNode,
 } from '@fluentui/react-shared-contexts';
 export {
+  // getNativeElementProps is deprecated but removing it would be a breaking change
+  // eslint-disable-next-line deprecation/deprecation
   getNativeElementProps,
   getIntrinsicElementProps,
   getPartitionedNativeProps,

packages/react-components/react-utilities/etc/react-utilities.api.md

@@ -60,7 +60,7 @@ export function getEventClientCoords(event: TouchOrMouseEvent): {
 // @public
 export const getIntrinsicElementProps: <Props extends UnknownSlotProps, ExcludedPropKeys extends Extract<keyof Props, string> = never>(tagName: NonNullable<Props["as"]>, props: Props & React_2.RefAttributes<InferredElementRefType<Props>>, excludedPropNames?: ExcludedPropKeys[] | undefined) => OmitWithoutExpanding<Props, ExcludedPropKeys | Exclude<keyof Props, "as" | keyof HTMLAttributes>>;
 
-// @public
+// @public @deprecated
 export function getNativeElementProps<TAttributes extends React_2.HTMLAttributes<any>>(tagName: string, props: {}, excludedPropNames?: string[]): TAttributes;
 
 // @internal

packages/react-components/react-utilities/src/compose/getIntrinsicElementProps.test.ts

@@ -0,0 +1,23 @@
+import { getIntrinsicElementProps } from './getIntrinsicElementProps';
+
+describe('getIntrinsicElementProps', () => {
+  type Props = { as?: 'span' | 'div' | 'input'; id?: string; checked?: boolean };
+  it('can filter native element properties', () => {
+    expect(getIntrinsicElementProps<Props>('div', { id: '123', checked: true })).toEqual({ id: '123' });
+    expect(getIntrinsicElementProps<Props>('input', { id: '123', checked: true })).toEqual({
+      id: '123',
+      checked: true,
+    });
+    expect(getIntrinsicElementProps<Props, 'id'>('input', { id: '123', checked: true }, ['id'])).toEqual({
+      checked: true,
+    });
+  });
+
+  it('includes `as` as a native prop', () => {
+    expect(getIntrinsicElementProps<Props>('div', { as: 'span' })).toEqual({ as: 'span' });
+  });
+
+  it('excludes props regardless of the allowed', () => {
+    expect(getIntrinsicElementProps<Props, 'as'>('div', { as: 'span' }, ['as'])).toEqual({});
+  });
+});

packages/react-components/react-utilities/src/compose/getIntrinsicElementProps.ts

@@ -22,6 +22,7 @@ export const getIntrinsicElementProps = <
   /** List of native props to exclude from the returned value */
   excludedPropNames?: ExcludedPropKeys[],
 ) => {
+  // eslint-disable-next-line deprecation/deprecation
   return getNativeElementProps<
     OmitWithoutExpanding<Props, Exclude<keyof Props, keyof HTMLAttributes | keyof UnknownSlotProps> | ExcludedPropKeys>
   >(props.as ?? tagName, props, excludedPropNames);

packages/react-components/react-utilities/src/index.ts

@@ -52,6 +52,7 @@ export { canUseDOM, useIsSSR, SSRProvider } from './ssr/index';
 
 export {
   clamp,
+  // eslint-disable-next-line deprecation/deprecation
   getNativeElementProps,
   getPartitionedNativeProps,
   getRTLSafeKey,

packages/react-components/react-utilities/src/utils/getNativeElementProps.test.ts

@@ -2,16 +2,21 @@ import { getNativeElementProps } from './getNativeElementProps';
 
 describe('getNativeElementProps', () => {
   it('can filter native element properties', () => {
+    // eslint-disable-next-line deprecation/deprecation
     expect(getNativeElementProps('div', { id: '123', checked: true })).toEqual({ id: '123' });
+    // eslint-disable-next-line deprecation/deprecation
     expect(getNativeElementProps('input', { id: '123', checked: true })).toEqual({ id: '123', checked: true });
+    // eslint-disable-next-line deprecation/deprecation
     expect(getNativeElementProps('input', { id: '123', checked: true }, ['id'])).toEqual({ checked: true });
   });
 
   it('includes `as` as a native prop', () => {
+    // eslint-disable-next-line deprecation/deprecation
     expect(getNativeElementProps('div', { as: 'span' })).toEqual({ as: 'span' });
   });
 
   it('excludes props regardless of the allowed', () => {
+    // eslint-disable-next-line deprecation/deprecation
     expect(getNativeElementProps('div', { as: 'span' }, ['as'])).toEqual({});
   });
 });

packages/react-components/react-utilities/src/utils/getNativeElementProps.ts

@@ -59,6 +59,8 @@ const nativeElementMap: Record<string, Record<string, number>> = {
  * @param tagName - Tag name (e.g. "div")
  * @param props - Props object
  * @param excludedPropNames - List of props to disallow
+ *
+ * @deprecated use getIntrinsicElementProps instead, it is a type-safe version of this method
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function getNativeElementProps<TAttributes extends React.HTMLAttributes<any>>(
@@ -99,6 +101,7 @@ export const getPartitionedNativeProps = <
 }) => {
   return {
     root: { style: props.style, className: props.className },
+    // eslint-disable-next-line deprecation/deprecation
     primary: getNativeElementProps<Omit<Props, ExcludedPropKeys>>(primarySlotTagName, props, [
       ...(excludedPropNames || []),
       'style',

tools/workspace-plugin/src/generators/react-component/files/component/use__componentName__.ts__tmpl__

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { getNativeElementProps, slot } from '@fluentui/react-utilities';
+import { getIntrinsicElementProps, slot } from '@fluentui/react-utilities';
 import type { <%= componentName %>Props, <%= componentName %>State } from './<%= componentName %>.types';
 
 /**
@@ -9,9 +9,9 @@ import type { <%= componentName %>Props, <%= componentName %>State } from './<%=
  * before being passed to render<%= componentName %>_unstable.
  *
  * @param props - props from this instance of <%= componentName %>
- * @param ref - reference to root HTMLElement of <%= componentName %>
+ * @param ref - reference to root HTMLDivElement of <%= componentName %>
  */
-export const use<%= componentName %>_unstable = (props: <%= componentName %>Props, ref: React.Ref<HTMLElement>): <%= componentName %>State => {
+export const use<%= componentName %>_unstable = (props: <%= componentName %>Props, ref: React.Ref<HTMLDivElement>): <%= componentName %>State => {
   return {
     // TODO add appropriate props/defaults
     components: {
@@ -20,7 +20,7 @@ export const use<%= componentName %>_unstable = (props: <%= componentName %>Prop
     },
     // TODO add appropriate slots, for example:
     // mySlot: resolveShorthand(props.mySlot),
-    root: slot.always(getNativeElementProps('div', {
+    root: slot.always(getIntrinsicElementProps('div', {
       ref,
       ...props,
     }), {elementType: 'div'}),