feat: implement internal/alpha/beta/ API removals from package public API surface #23369

Hotell · 2022-06-02T11:59:14Z

This implements revamped build workflow and api-generation with stripping of APIs marked via @internal/@alpha/@beta JSDoc annotation.

💡NOTE:

implementation affects only v9
CHANGES IN THIS PR will have NO EFFECT on any v9 package as it is implemented with gradual migration enablement. To enable this new behaviours follow up set of PR's will be created that will invoke migrate-converged-pkg automation per package.

Current Behavior

Build tasks:

build task doesn't uses path aliases
build:local task uses path aliases

API-extractor configuration:

we need to maintain 2 different configs for build and build:local, which tend to not work all the time ( react-components suite)
we generate all api-extractor metadata that are not needed/used (api report, tsdoc metadata, dts rollup, doc model )

API Surface:

api surface of an package is being shipped to npm as rolluped index.d.ts, which might expose APIs not intended to be used for consumers

New Behavior

Build tasks:

build task uses path aliases
- compiled output will be emitted to root dist instead of per package dist, afterwards assets are copied to package scope for publishing purposes
build:local npm script task is replaced with generate-api task that uses path aliases

API-extractor configuration:

we use only 1 api-extractor configuration which works for all use-cases
we generate only api report and dts rollup via api-extractor

API Surface:

apis marked as @internal/@alpha/@beta are removed from package API surface ( rolluped index.d.ts )
- this protects us on tooling from exposing or even re-exporting from other package non public apis

Detailed workflow comparison

generating `api.md` file

BEFORE:

yarn workspace @fluentui/react-text build:local

🚨 No failures ever as there is no api trimming/validation

AFTER:

yarn workspace @fluentui/react-text generate-api

✅ This might fail in 2 scenarios:

dependant packages are missing generated index.d.ts file.

If this case occurs tooling will guide you with following DX:

your package is using non public API from dependant packages as a part of its PUBLIC API

NOTE:

in some scenarios type information might be properly inlined so things will work

re-exporting a non public API from other package will not be allowed and will throw an error

If this case occurs tooling will guide you with following DX:

🛠 Known issues:

currently if you expose a non public API inside package it will generate invalid index.d.ts file. A follow up work will be done after this will be merged.
💁‍♂️ note: if such a scenario occurs ts-minbar-react-components will catch such an issue on CI

// @filename package-a/src/index.ts
/**
 * @internal
 */
export type InternalApi = {day: string}
export function hello(): InternalApi {...}
export function time():number {...}

⬇⬇⬇ tsc emit

// @filename package-a/dist/index.d.ts

// 🚨 InternalApi was removed - index.d.ts is invalid type declaration
export declare function hello(): InternalApi {...}
//                                                    ~~~~~~~~   
export declare function time():number {...}

Related Issue(s)

Fixes partially #23343

fabricteam · 2022-06-02T12:05:40Z

📊 Bundle size report

Unchanged fixtures

Package & Exports	Size (minified/GZIP)
`global-context` createContext	`533 B` `341 B`
`global-context` createContextSelector	`554 B` `348 B`
`priority-overflow` createOverflowManager	`2.936 kB` `1.212 kB`
`react-accordion` Accordion (including children components)	`79.562 kB` `24.121 kB`
`react-alert` Alert	`83.79 kB` `20.841 kB`
`react-avatar` Avatar	`48.283 kB` `13.644 kB`
`react-avatar` AvatarGroup	`15.072 kB` `6.016 kB`
`react-avatar` AvatarGroupItem	`68.464 kB` `19.067 kB`
`react-badge` Badge	`22.503 kB` `7.153 kB`
`react-badge` CounterBadge	`23.406 kB` `7.449 kB`
`react-badge` PresenceBadge	`23.947 kB` `7.022 kB`
`react-button` Button	`36.396 kB` `9.579 kB`
`react-button` CompoundButton	`43.469 kB` `10.812 kB`
`react-button` MenuButton	`39.014 kB` `10.456 kB`
`react-button` SplitButton	`46.544 kB` `11.84 kB`
`react-button` ToggleButton	`51.91 kB` `11.003 kB`
`react-card` Card - All	`67.458 kB` `19.264 kB`
`react-card` Card	`63.14 kB` `18.176 kB`
`react-card` CardFooter	`8.461 kB` `3.555 kB`
`react-card` CardHeader	`9.504 kB` `3.896 kB`
`react-card` CardPreview	`8.562 kB` `3.61 kB`
`react-combobox` Combobox (including child components)	`72.762 kB` `23.757 kB`
`react-combobox` Dropdown (including child components)	`71.026 kB` `23.291 kB`
`react-components` react-components: Accordion, Button, FluentProvider, Image, Menu, Popover	`189.031 kB` `51.967 kB`
`react-components` react-components: FluentProvider & webLightTheme	`32.895 kB` `10.778 kB`
`react-dialog` Dialog (including children components)	`85.574 kB` `25.521 kB`
`react-divider` Divider	`16.359 kB` `5.853 kB`
`react-image` Image	`10.68 kB` `4.215 kB`
`react-input` Input	`23.554 kB` `7.644 kB`
`react-label` Label	`9.238 kB` `3.815 kB`
`react-link` Link	`12.231 kB` `4.925 kB`
`react-menu` Menu (including children components)	`115.91 kB` `35.382 kB`
`react-menu` Menu (including selectable components)	`119.109 kB` `35.876 kB`
`react-overflow` hooks only	`10.898 kB` `4.174 kB`
`react-popover` Popover	`103.05 kB` `31.561 kB`
`react-portal` Portal	`10.576 kB` `3.875 kB`
`react-positioning` usePositioning	`19.7 kB` `7.404 kB`
`react-provider` FluentProvider	`15.655 kB` `5.835 kB`
`react-radio` Radio	`36.238 kB` `12 kB`
`react-radio` RadioGroup	`14.361 kB` `5.728 kB`
`react-select` Select	`20.746 kB` `7.299 kB`
`react-slider` Slider	`32.07 kB` `10.033 kB`
`react-spinbutton` SpinButton	`43.899 kB` `12.362 kB`
`react-spinner` Spinner	`19.848 kB` `6.384 kB`
`react-switch` Switch	`32.562 kB` `10.253 kB`
`react-text` Text - Default	`11.682 kB` `4.561 kB`
`react-text` Text - Wrappers	`14.992 kB` `4.995 kB`
`react-textarea` Textarea	`23.674 kB` `7.83 kB`
`react-theme` Single theme token import	`69 B` `89 B`
`react-theme` Teams: all themes	`29.224 kB` `6.255 kB`
`react-theme` Teams: Light theme	`17.088 kB` `4.89 kB`
`react-tooltip` Tooltip	`41.504 kB` `14.622 kB`
`react-utilities` SSRProvider	`180 B` `159 B`

_{🤖 This report was generated against bf151e71e0ffa5de5c44cc722e629cdeb7abdbb2}

size-auditor · 2022-06-15T18:55:35Z

Asset size changes

Size Auditor did not detect a change in bundle size for any component!

Baseline commit: bf151e71e0ffa5de5c44cc722e629cdeb7abdbb2 (build)

fabricteam · 2022-06-15T19:01:37Z

Perf Analysis (`@fluentui/react-northstar`)

Perf tests with no regressions

Scenario	Current PR Ticks	Baseline Ticks	Ratio
RefMinimalPerf.default	185	159	1.16:1
ChatWithPopoverPerf.default	310	269	1.15:1
DropdownManyItemsPerf.default	565	497	1.14:1
TreeMinimalPerf.default	675	592	1.14:1
ButtonSlotsPerf.default	452	403	1.12:1
HeaderSlotsPerf.default	600	534	1.12:1
ItemLayoutMinimalPerf.default	964	860	1.12:1
ListMinimalPerf.default	415	369	1.12:1
MenuMinimalPerf.default	694	627	1.11:1
SliderMinimalPerf.default	1416	1277	1.11:1
ImageMinimalPerf.default	300	273	1.1:1
RadioGroupMinimalPerf.default	364	332	1.1:1
SegmentMinimalPerf.default	279	254	1.1:1
ChatDuplicateMessagesPerf.default	234	215	1.09:1
PopupMinimalPerf.default	523	482	1.09:1
CardMinimalPerf.default	447	417	1.07:1
ToolbarMinimalPerf.default	743	692	1.07:1
RosterPerf.default	946	894	1.06:1
ListWith60ListItems.default	480	455	1.05:1
AvatarMinimalPerf.default	139	134	1.04:1
ButtonMinimalPerf.default	117	113	1.04:1
ButtonOverridesMissPerf.default	1192	1145	1.04:1
FlexMinimalPerf.default	211	203	1.04:1
ListNestedPerf.default	467	448	1.04:1
ProviderMergeThemesPerf.default	961	925	1.04:1
CheckboxMinimalPerf.default	2136	2083	1.03:1
EmbedMinimalPerf.default	3334	3248	1.03:1
SkeletonMinimalPerf.default	285	277	1.03:1
AccordionMinimalPerf.default	105	103	1.02:1
AnimationMinimalPerf.default	445	435	1.02:1
AttachmentSlotsPerf.default	885	866	1.02:1
ChatMinimalPerf.default	596	583	1.02:1
GridMinimalPerf.default	247	242	1.02:1
LayoutMinimalPerf.default	265	259	1.02:1
ListCommonPerf.default	506	496	1.02:1
InputMinimalPerf.default	1090	1083	1.01:1
TextMinimalPerf.default	279	275	1.01:1
CustomToolbarPrototype.default	2109	2096	1.01:1
ProviderMinimalPerf.default	323	322	1:1
IconMinimalPerf.default	444	446	1:1
AlertMinimalPerf.default	217	219	0.99:1
AttachmentMinimalPerf.default	119	120	0.99:1
BoxMinimalPerf.default	274	276	0.99:1
DatepickerMinimalPerf.default	4486	4535	0.99:1
DropdownMinimalPerf.default	2493	2509	0.99:1
TableMinimalPerf.default	291	293	0.99:1
TreeWith60ListItems.default	125	127	0.98:1
MenuButtonMinimalPerf.default	1263	1296	0.97:1
SplitButtonMinimalPerf.default	3298	3407	0.97:1
TooltipMinimalPerf.default	845	874	0.97:1
VideoMinimalPerf.default	495	510	0.97:1
CarouselMinimalPerf.default	342	360	0.95:1
DialogMinimalPerf.default	594	635	0.94:1
FormMinimalPerf.default	283	300	0.94:1
ReactionMinimalPerf.default	281	300	0.94:1
StatusMinimalPerf.default	499	538	0.93:1
TextAreaMinimalPerf.default	376	404	0.93:1
TableManyItemsPerf.default	1412	1538	0.92:1
HeaderMinimalPerf.default	268	298	0.9:1
LabelMinimalPerf.default	277	310	0.89:1
LoaderMinimalPerf.default	501	562	0.89:1
PortalMinimalPerf.default	123	140	0.88:1
DividerMinimalPerf.default	248	284	0.87:1

fabricteam · 2022-06-15T19:08:38Z

Perf Analysis (`@fluentui/react`)

No significant results to display.

All results

Scenario	Render type	Master Ticks	PR Ticks	Iterations
BaseButton	mount	793	787	5000
Breadcrumb	mount	2401	2393	1000
Checkbox	mount	2262	2243	5000
CheckboxBase	mount	1890	1957	5000
ChoiceGroup	mount	3975	4073	5000
ComboBox	mount	824	783	1000
CommandBar	mount	9155	8776	1000
ContextualMenu	mount	10680	11737	1000
DefaultButton	mount	900	996	5000
DetailsRow	mount	3266	3326	5000
DetailsRowFast	mount	3272	3341	5000
DetailsRowNoStyles	mount	3112	3179	5000
Dialog	mount	2493	2414	1000
DocumentCardTitle	mount	158	159	1000
Dropdown	mount	2696	2865	5000
FocusTrapZone	mount	1551	1632	5000
FocusZone	mount	1569	1500	5000
IconButton	mount	1526	1471	5000
Label	mount	303	303	5000
Layer	mount	2859	2793	5000
Link	mount	408	413	5000
MenuButton	mount	1279	1270	5000
MessageBar	mount	1830	1816	5000
Nav	mount	2866	2718	1000
OverflowSet	mount	876	933	5000
Panel	mount	1907	1829	1000
Persona	mount	870	870	1000
Pivot	mount	1227	1250	1000
PrimaryButton	mount	1110	1000	5000
Rating	mount	6666	6654	5000
SearchBox	mount	1074	1110	5000
Shimmer	mount	2176	2189	5000
Slider	mount	1683	1682	5000
SpinButton	mount	4269	4209	5000
Spinner	mount	378	387	5000
SplitButton	mount	2740	2770	5000
Stack	mount	457	397	5000
StackWithIntrinsicChildren	mount	1848	1953	5000
StackWithTextChildren	mount	4442	4427	5000
SwatchColorPicker	mount	9942	9890	5000
TagPicker	mount	2172	2322	5000
TeachingBubble	mount	82809	84964	5000
Text	mount	376	322	5000
TextField	mount	1208	1228	5000
ThemeProvider	mount	1066	1097	5000
ThemeProvider	virtual-rerender	641	622	5000
ThemeProvider	virtual-rerender-with-unmount	1625	1556	5000
Toggle	mount	681	683	5000
buttonNative	mount	102	92	5000

codesandbox-ci · 2022-06-16T10:47:11Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit bcab8a6:

Sandbox	Source
@fluentui/react 8 starter	Configuration
@fluentui/react-components 9 starter	Configuration

fabricteam · 2022-06-16T13:03:29Z

Perf Analysis (`@fluentui/react-components`)

No significant results to display.

All results

Scenario	Render type	Master Ticks	PR Ticks	Iterations
Avatar	mount	1608	1594	5000
Button	mount	1116	1161	5000
FluentProvider	mount	1891	1881	5000
FluentProviderWithTheme	mount	717	715	10
FluentProviderWithTheme	virtual-rerender	652	676	10
FluentProviderWithTheme	virtual-rerender-with-unmount	719	722	10
MakeStyles	mount	2263	2285	50000
SpinButton	mount	3153	3147	5000

Hotell · 2022-07-25T12:06:39Z

TODO:

check if ts-minbar catches "known issues" part prior to merging this

Hotell · 2022-07-25T11:17:38Z

scripts/monorepo/runPublished.js

@@ -29,16 +29,24 @@ const websitePackages = [
 // in the root package.json's publishing-related scripts and will need to be updated if --scope changes.
 const beachballPackageScopes = Object.entries(getAllPackageInfo())
  .filter(([, { packageJson, packagePath }]) => {
-    // Ignore northstar
-    if (/[\\/]fluentui[\\/]/.test(packagePath)) {
+    const isNorthstar = /[\\/]fluentui[\\/]/.test(packagePath);


~~add test to cover this logic~~ not right now....

Hotell · 2022-07-25T11:18:34Z

scripts/tasks/api-extractor.ts

            apiExtractorVerifyTask({
-              configJsonFilePath: configPath,
+              showVerboseMessages: args.verbose,


adding support for all raw api-extractor CLI APIs

Hotell · 2022-07-27T11:50:50Z

packages/react-components/priority-overflow/etc/priority-overflow.api.md

@@ -4,8 +4,6 @@

 ```ts

-// Warning: (ae-internal-missing-underscore) The name "createOverflowManager" should be prefixed with an underscore because the declaration is marked as @internal
-//


regenerated api - caused by https://github.com/microsoft/fluentui/pull/23369/files#diff-6e6689b37dbb9f03e96cb4b543dee65569e52f8e0099d2370a9a0fcb01ec497cR43

Hotell · 2022-07-27T11:51:02Z

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

@@ -7,16 +7,12 @@
 import { DispatchWithoutAction } from 'react';
 import * as React_2 from 'react';

-// Warning: (ae-internal-missing-underscore) The name "applyTriggerPropsToChildren" should be prefixed with an underscore because the declaration is marked as @internal


regenerated api - caused by https://github.com/microsoft/fluentui/pull/23369/files#diff-6e6689b37dbb9f03e96cb4b543dee65569e52f8e0099d2370a9a0fcb01ec497cR43

Hotell · 2022-07-28T11:49:25Z

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

@@ -106,8 +106,6 @@ export type AvatarState = ComponentState<AvatarSlots> & Required<Pick<AvatarProp
    color: NonNullable<Exclude<AvatarProps['color'], 'colorful'>>;
 };

-// Warning: (ae-internal-missing-underscore) The name "getInitials" should be prefixed with an underscore because the declaration is marked as @internal


regenerated api - caused by https://github.com/microsoft/fluentui/pull/23369/files#diff-6e6689b37dbb9f03e96cb4b543dee65569e52f8e0099d2370a9a0fcb01ec497cR43

… run published

Migrates the react-avatar package to use the new build experience introduced in microsoft#23369

* chore: Migrate react-avatar to use new build Migrates the react-avatar package to use the new build experience introduced in #23369 * changefile

* chore: Migrate react-table to use new build Migrates the react-avatar package to use the new build experience introduced in #23369 * changefile

* chore: Migrate react-avatar to use new build Migrates the react-avatar package to use the new build experience introduced in microsoft#23369 * changefile

* chore: Migrate react-table to use new build Migrates the react-avatar package to use the new build experience introduced in microsoft#23369 * changefile

msft-fluent-ui-bot added the Area: Build System label Jun 2, 2022

msft-fluent-ui-bot assigned ling1726 Jun 2, 2022

github-actions bot added this to the June Project Cycle Q2 2022 milestone Jun 2, 2022

Hotell force-pushed the hotell/build/new-ts-compilation-with-private-api-support branch 2 times, most recently from d455c19 to 070e45e Compare June 9, 2022 12:30

Hotell changed the title ~~Hotell/build/new ts compilation with private api support~~ feat: implement internal/alpha/beta/ API removals from package public API surface Jun 15, 2022

Hotell unassigned ling1726 Jun 15, 2022

Hotell force-pushed the hotell/build/new-ts-compilation-with-private-api-support branch 2 times, most recently from 749a682 to 7adc9bb Compare June 16, 2022 10:38

Hotell force-pushed the hotell/build/new-ts-compilation-with-private-api-support branch from 1898dcf to 35a98ac Compare June 16, 2022 12:51

Hotell added the Fluent UI react-components (v9) label Jun 16, 2022

Hotell force-pushed the hotell/build/new-ts-compilation-with-private-api-support branch from 35a98ac to dd64082 Compare June 16, 2022 13:07

Hotell mentioned this pull request Jun 16, 2022

docs(rfc): add api access modifiers style-guide RFC for v9 #23577

Merged

tudorpopams assigned Hotell Jul 7, 2022

github-actions bot modified the milestones: June Project Cycle Q2 2022, July Project Cycle Q3 2022 Jul 22, 2022

Hotell force-pushed the hotell/build/new-ts-compilation-with-private-api-support branch from 79a4462 to d1fc9af Compare July 22, 2022 16:07

Hotell commented Jul 25, 2022

View reviewed changes

Hotell force-pushed the hotell/build/new-ts-compilation-with-private-api-support branch 2 times, most recently from 2798e80 to 7de0565 Compare July 25, 2022 13:51

Hotell commented Jul 27, 2022

View reviewed changes

Hotell commented Jul 28, 2022

View reviewed changes

Hotell added 8 commits August 22, 2022 14:37

generate changefile

984bc5b

docs(react-context-selector): re-generate api.md

89c1735

generate changefile

10809d4

docs(react-aria): re-generate api.md

1a9a563

generate changelog

5f9a83e

docs: re-generate api.md files

b35fa36

generate changefiles

f58ed84

refactor(scripts): combine isNorthstar with private package check for…

bcab8a6

… run published

Hotell force-pushed the hotell/build/new-ts-compilation-with-private-api-support branch from 67df780 to bcab8a6 Compare August 22, 2022 12:37

Hotell merged commit 16aa65d into microsoft:master Aug 22, 2022

Hotell deleted the hotell/build/new-ts-compilation-with-private-api-support branch August 22, 2022 13:41

ling1726 added a commit to ling1726/fluentui that referenced this pull request Sep 27, 2022

chore: Migrate react-avatar to use new build

4785b6e

Migrates the react-avatar package to use the new build experience introduced in microsoft#23369

ling1726 mentioned this pull request Sep 27, 2022

chore: Migrate react-avatar to use new build #24969

Merged

ling1726 added a commit to ling1726/fluentui that referenced this pull request Sep 27, 2022

chore: Migrate react-table to use new build

bb85796

Migrates the react-avatar package to use the new build experience introduced in microsoft#23369

ling1726 mentioned this pull request Sep 27, 2022

chore: Migrate react-table to use new build #24970

Merged

ling1726 added a commit that referenced this pull request Sep 28, 2022

chore: Migrate react-avatar to use new build (#24969)

1333dab

* chore: Migrate react-avatar to use new build Migrates the react-avatar package to use the new build experience introduced in #23369 * changefile

TristanWatanabe mentioned this pull request Sep 28, 2022

fix(create-component): Replace build:local with new generate-api script #24996

Merged

ling1726 added a commit that referenced this pull request Sep 28, 2022

chore: Migrate react-table to use new build (#24970)

cd88ecf

* chore: Migrate react-table to use new build Migrates the react-avatar package to use the new build experience introduced in #23369 * changefile

Hotell mentioned this pull request Oct 24, 2022

feat(scripts): improve API violation reporting #25356

Merged

Hotell mentioned this pull request Nov 8, 2022

feat(scripts): remove @internal stripping and enable no deps build needed for api generation #25575

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: implement internal/alpha/beta/ API removals from package public API surface #23369

feat: implement internal/alpha/beta/ API removals from package public API surface #23369

Hotell commented Jun 2, 2022 •

edited

Loading

fabricteam commented Jun 2, 2022 •

edited

Loading

size-auditor bot commented Jun 15, 2022 •

edited

Loading

fabricteam commented Jun 15, 2022 •

edited

Loading

fabricteam commented Jun 15, 2022 •

edited

Loading

codesandbox-ci bot commented Jun 16, 2022 •

edited

Loading

fabricteam commented Jun 16, 2022 •

edited

Loading

Hotell commented Jul 25, 2022 •

edited

Loading

Hotell Jul 25, 2022 •

edited

Loading

Hotell Jul 25, 2022

Hotell Jul 27, 2022

Hotell Jul 27, 2022

Hotell Jul 28, 2022

feat: implement internal/alpha/beta/ API removals from package public API surface #23369

feat: implement internal/alpha/beta/ API removals from package public API surface #23369

Conversation

Hotell commented Jun 2, 2022 • edited Loading

Current Behavior

New Behavior

Detailed workflow comparison

generating api.md file

Related Issue(s)

fabricteam commented Jun 2, 2022 • edited Loading

📊 Bundle size report

size-auditor bot commented Jun 15, 2022 • edited Loading

Asset size changes

fabricteam commented Jun 15, 2022 • edited Loading

Perf Analysis (@fluentui/react-northstar)

fabricteam commented Jun 15, 2022 • edited Loading

Perf Analysis (@fluentui/react)

codesandbox-ci bot commented Jun 16, 2022 • edited Loading

fabricteam commented Jun 16, 2022 • edited Loading

Perf Analysis (@fluentui/react-components)

Hotell commented Jul 25, 2022 • edited Loading

Hotell Jul 25, 2022 • edited Loading

Choose a reason for hiding this comment

Hotell Jul 25, 2022

Choose a reason for hiding this comment

Hotell Jul 27, 2022

Choose a reason for hiding this comment

Hotell Jul 27, 2022

Choose a reason for hiding this comment

Hotell Jul 28, 2022

Choose a reason for hiding this comment

Hotell commented Jun 2, 2022 •

edited

Loading

generating `api.md` file

fabricteam commented Jun 2, 2022 •

edited

Loading

size-auditor bot commented Jun 15, 2022 •

edited

Loading

fabricteam commented Jun 15, 2022 •

edited

Loading

Perf Analysis (`@fluentui/react-northstar`)

fabricteam commented Jun 15, 2022 •

edited

Loading

Perf Analysis (`@fluentui/react`)

codesandbox-ci bot commented Jun 16, 2022 •

edited

Loading

fabricteam commented Jun 16, 2022 •

edited

Loading

Perf Analysis (`@fluentui/react-components`)

Hotell commented Jul 25, 2022 •

edited

Loading

Hotell Jul 25, 2022 •

edited

Loading