Audit Experimental APIs for WP 6.2

[ntsekouras]

Cc @WordPress/gutenberg-core

APIs that never released in a stable WP version

This is a first pass of the new APIs based on this diff that compares the APIs in 6.1.

• If you think it can become stable, open a PR to rename it.
• If it needs more time, lock it. See Experiments: sharing private APIs with lock() and unlock() #46131.
   
• __experimentalBlockInspectorAnimation @artemiomorales
• __experimentalClearBlockSelection @joshuatf @talldan
• __experimentalHeightControl @andrewserong
• __experimentalHideBlockInterface, __experimentalIsBlockInterfaceHidden, __experimentalShowBlockInterface @glendaviesnz
• __experimentalPopoverPositionToPlacement @ciampo
• __experimentalMetadata @getdave 👀 👍
• __experimentalOffCanvasEditor @draganescu
• __experimentalShowSelectedHint @noisysocks
• __experimentalStyles @noisysocks
• __experimentalUseSlotFills @youknowriad
• __experimentalDashboardLink
• __experimentaluseLayoutClasses, __experimentaluseLayoutStyles @tellthemachines (punted for later version)
• __experimentalTheme @mirka
• inserterMediaCategories @ntsekouras

All experimental APIs

Generated using @noisysocks' script from #28157, with a small tweak to add each API only once, in the first package it was found.

I'm sharing the suggestions from previous similar issues(example) for older WP versions by @youknowriad in #31416, although we need to evaluate per case the proper handling:

• If it's an API that is never meant to be made available to third-party developers as is, rename it to __unstable instead
• If you think it's time to consider making the API stable, open a PR to rename it and soft deprecate it for two version(example PR).
• If you think it's an API worth having, but you're still uncertain whether future changes might impact it, consider asking for help to make the right call, or comment here.
• if you want to give the API more time to mature, just ignore it for now.

The list will be updated again, since APIs might change before the last GB version to be included in 6.2.

List of experimental APIs

packages/annotations

__experimentalAddAnnotation
__experimentalCreateOnChangeEditableValue
__experimentalCreatePrepareEditableTree
__experimentalGetAllAnnotationsForBlock
__experimentalGetAnnotations
__experimentalGetAnnotationsForBlock
__experimentalGetAnnotationsForRichText
__experimentalGetPropsForEditableTreeChangeHandler
__experimentalGetPropsForEditableTreePreparation
__experimentalRemoveAnnotation
__experimentalRemoveAnnotationsBySource
__experimentalUpdateAnnotationRange

packages/block-directory

__experimentalIsFocusable

packages/block-editor

__experimentalAlignmentMatrixControl
__experimentalAppenderTagName
__experimentalApplyValueToSides
__experimentalBlockAlignmentMatrixControl
__experimentalBlockDirectory
__experimentalBlockFullHeightAligmentControl
__experimentalBlockPatternCategories
__experimentalBlockPatternSetup
__experimentalBlockPatterns
__experimentalBlockPatternsList
__experimentalBlockVariationPicker
__experimentalBlockVariationTransforms
__experimentalBorder
__experimentalBorderBoxControl
__experimentalBorderRadiusControl
__experimentalBoxControl
__experimentalCanUserUseUnfilteredHTML
__experimentalCaptureToolbars
__experimentalCloneSanitizedBlock
__experimentalColorGradientControl
__experimentalColorGradientSettingsDropdown
__experimentalConvertBlockToStatic
__experimentalDateFormatPicker
__experimentalDefaultBlock
__experimentalDefaultControls
__experimentalDirectInsert
__experimentalDragComponent
__experimentalDropdownContentWrapper
__experimentalDuotone
__experimentalDuotoneControl
__experimentalEnableOffCanvasNavigationEditor
__experimentalExposeControlsToChildren
__experimentalFeatures
__experimentalFetchLinkSuggestions
__experimentalFetchReusableBlocks
__experimentalFetchRichUrlData
__experimentalFilterValue
__experimentalFirstVisibleItemClass
__experimentalFontAppearanceControl
__experimentalFontFamily
__experimentalFontFamilyControl
__experimentalFontStyle
__experimentalFontWeight
__experimentalGetAccessibleBlockLabel
__experimentalGetActiveBlockIdByBlockNames
__experimentalGetAllowedBlocks
__experimentalGetAllowedPatterns
__experimentalGetBlockAttributesNamesByRole
__experimentalGetBlockLabel
__experimentalGetBlockListSettingsForBlocks
__experimentalGetBorderClassesAndStyles
__experimentalGetColorClassesAndStyles
__experimentalGetDirectInsertBlock
__experimentalGetElementClassName
__experimentalGetGapCSSValue
__experimentalGetGlobalBlocksByName
__experimentalGetGradientClass
__experimentalGetGradientObjectByGradientValue
__experimentalGetLastBlockAttributeChanges
__experimentalGetMatchingVariation
__experimentalGetParsedPattern
__experimentalGetPatternTransformItems
__experimentalGetReusableBlockTitle
__experimentalGetSpacingClassesAndStyles
__experimentalGlobalStylesBaseStyles
__experimentalGroup
__experimentalHStack
__experimentalHandleURLSuggestions
__experimentalHasSplitBorders
__experimentalHeading__experimentalHideChildBlockControls
__experimentalHint
__experimentalImageEditor
__experimentalImageSizeControl
__experimentalImageURLInputUI
__experimentalInitialIndex
__experimentalInitialPosition
__experimentalInsertionIndex
__experimentalInspectorPopoverHeader
__experimentalIsDefinedBorder
__experimentalIsItemGroup
__experimentalIsQuick
__experimentalIsRenderedInSidebar
__experimentalItem
__experimentalItemGroup
__experimentalLabel
__experimentalLastVisibleItemClass
__experimentalLayout
__experimentalLayoutStyle
__experimentalLetterSpacing
__experimentalLetterSpacingControl
__experimentalLibrary
__experimentalLinkControl
__experimentalLinkControlSearchInput
__experimentalLinkControlSearchItem
__experimentalLinkControlSearchResults
__experimentalListView
__experimentalMinHeight
__experimentalNavigatorBackButton
__experimentalNavigatorButton
__experimentalNavigatorProvider
__experimentalNavigatorScreen
__experimentalNumberControl
__experimentalOnIndexChange
__experimentalOnlyMediaLibrary
__experimentalPadding
__experimentalPanelColorGradientSettings
__experimentalParentSelector
__experimentalParseQuantityAndUnitFromRawValue
__experimentalPreferPatternsOnRoot
__experimentalPreferredStyleVariations
__experimentalPreviewOptions
__experimentalPublishDateTimePicker
__experimentalRecursionProvider
__experimentalRenderControl
__experimentalRenderSuggestions
__experimentalResponsiveBlockControl
__experimentalReusableBlocks
__experimentalRichText
__experimentalRole
__experimentalSelectBlock
__experimentalSetIsInserterOpened
__experimentalSettings
__experimentalShareWithChildBlocks
__experimentalShouldInsertAtTheTop__experimentalShowInitialSuggestions
__experimentalSkipSerialization
__experimentalSlashInserter
__experimentalSpacer
__experimentalSpacingSizesControl
__experimentalStyleProvider
__experimentalText
__experimentalTextDecoration
__experimentalTextDecorationControl
__experimentalTextTransform
__experimentalTextTransformControl
__experimentalToggleGroupControl
__experimentalToggleGroupControlOption
__experimentalToggleGroupControlOptionIcon
__experimentalToolbar
__experimentalToolbarContext
__experimentalToolsPanel
__experimentalToolsPanelContext
__experimentalToolsPanelItem
__experimentalTransferDataType
__experimentalTreeGrid
__experimentalTreeGridCell
__experimentalTreeGridItem
__experimentalTreeGridRow
__experimentalTruncate
__experimentalUndo
__experimentalUnitControl
__experimentalUpdateSelection
__experimentalUseBlockOverlayActive
__experimentalUseBlockPreview
__experimentalUseBorderProps
__experimentalUseColorProps
__experimentalUseCustomSides
__experimentalUseCustomUnits
__experimentalUseDropZone
__experimentalUseFixedWindowList
__experimentalUseGradient
__experimentalUseHasRecursion
__experimentalUseMultipleOriginColorsAndGradients
__experimentalUseResizeCanvas
__experimentalUseSlot
__experimentalVStack
__experimentalVersion
__experimentalView

packages/block-library

__experimentalConvert
__experimentalDefault
__experimentalDiscussionSettings
__experimentalGetCoreBlocks
__experimentalGetDefaultTemplatePartAreas
__experimentalHideHeader
__experimentalIsEditingReusableBlock
__experimentalOnEnter
__experimentalRegisterExperimentalCoreBlocks
__experimentalSelector
__experimentalShowHowTo
__experimentalShowTooltip
__experimentalStyle
__experimentalTooltipProps

packages/blocks

__experimentalGetUnprocessedBlockTypes
__experimentalReapplyBlockTypeFilters
__experimentalRegisterBlockType
__experimentalSanitizeBlockAttributes

packages/components

__experimentalBorderControl
__experimentalConfirmDialog
__experimentalDimensionControl
__experimentalDivider
__experimentalElevation
__experimentalExpandOnFocus
__experimentalGrid
__experimentalInputControl
__experimentalInputControlPrefixWrapper
__experimentalInputControlSuffixWrapper
__experimentalInvalid
__experimentalIsEmptyBorder
__experimentalNavigation
__experimentalNavigationBackButton
__experimentalNavigationGroup
__experimentalNavigationItem
__experimentalNavigationMenu
__experimentalPaletteEdit
__experimentalRadio
__experimentalRadioGroup
__experimentalRenderItem
__experimentalScrollable
__experimentalSurface
__experimentalToggleGroupControlOptionBase
__experimentalUseDialog
__experimentalUseDragging
__experimentalUseFocusOutside
__experimentalUseNavigator
__experimentalValidateInput
__experimentalZStack

packages/compose

__experimentalWidthProvider

packages/core-data

__experimentalBatch
__experimentalFetchUrlData
__experimentalGetCurrentGlobalStylesId
__experimentalGetCurrentThemeBaseGlobalStyles
__experimentalGetCurrentThemeGlobalStylesVariations
__experimentalGetDirtyEntityRecords
__experimentalGetEntitiesBeingSaved
__experimentalGetEntityRecordNoResolver
__experimentalGetTemplateForLink
__experimentalNoFetch
__experimentalReceiveCurrentGlobalStylesId
__experimentalReceiveThemeBaseGlobalStyles
__experimentalReceiveThemeGlobalStyleVariations
__experimentalSaveSpecifiedEntityEdits
__experimentalUseEntityRecord
__experimentalUseEntityRecords
__experimentalUseResourcePermissions

packages/customize-widgets

__experimentalGetInsertionPoint

packages/date

__experimentalGetSettings

packages/e2e-test-utils

__experimentalActivatePlugin
__experimentalDeactivatePlugin
__experimentalRest

packages/edit-post

__experimentalFullscreenModeClose
__experimentalGetPreviewDeviceType
__experimentalMainDashboardButton
__experimentalSetPreviewDeviceType

packages/edit-site

__experimentalAdditionalBlockPatternCategories
__experimentalAdditionalBlockPatterns
__experimentalEnableColorRandomizer
__experimentalEnableGlobalStylesCustomCSS
__experimentalEnableZoomedOutView
__experimentalGetDefaultTemplateTypes
__experimentalGetTemplateInfo
__experimentalGlobalStylesCustomCSS

packages/editor

__experimentalCreatePageEntity
__experimentalGetDefaultTemplateType
__experimentalTearDownEditor
__experimentalUserCanCreatePages

packages/eslint-plugin

__experimentalFoo
__experimentalSafe
__experimentalUnsafe

packages/experiments

__experimentalFunction

packages/reusable-blocks

__experimentalConvertBlocksToReusable
__experimentalDeleteReusableBlock
__experimentalSetEditingReusableBlock

lib

__experimentalEnableListBlockV2
__experimentalEnableQuoteBlockV2

[fabiankaegy]

I would like to understand what the procedure for __experimental APIs that were already introduced in previous versions of WordPress core and locking looks like. Will these API's be subject to locking or does the locking only apply to newly introduced __experimental APIs to prevent their usage?

From my perspective, the latter would be much preferred because several components have been experimental for a very long time and are so crucial that they have been used relatively widely. For example, the __experimentalLinkControl is getting used by quite a few third-party plugins just because it has been around for so long and I don't think it should get locked away at this point.

In order to prevent these kinds of things I'm 100% ob board with locking new introductions so they cannot get used before they are stable. But because weren't using this approach before there just are many components that are getting used relatively widely even when they shouldn't have been.

[ntsekouras]

@fabiankaegy the locking will be for new experimental APIs that haven't been released in a stable WP version. The rest will be examined per use case about how to handle them.

[noisysocks]

Definitely agree we should use API in #46131 to lock() any new experimental APIs added between 6.1 and 6.2.

I'd personally be on board with then considering all pre-6.2 experimental APIs as "stable but discouraged". But not a strong opinion—I know it's a contentious issue 😅

Thinking that we should also reevaluate these posts. They don't seem to work—the list grows longer each release. Not sure what would work best. Perhaps assigning each experimental API an owner might work to remove any bystander effect. Or perhaps we don't need to audit experimental APIs at all.

[ntsekouras]

Sorry for the massive ping, but I've updated the description to pinpoint the new APIs for 6.2. We need to check if we can stabilize any of them or lock them after merging this one - which is expected to land today probably.

[mirka]

__experimentalTheme @mirka

This component isn't publicly exported from the package yet so it should be fine. But I just realized that the readme isn't excluded from the public docs, so I'll get that fixed asap 🙊

[noisysocks]

Thanks @ntsekouras. I edited the issue to bury the unimportant stuff in a <details>.

This is a much more manageable list. We should do it this way for future releases 🙂

[tellthemachines]

Thanks for the ping @ntsekouras !

__experimentaluseLayoutClasses, __experimentaluseLayoutStyles

These are closely tied to the Layout block support which is also still an experimental API. I'm looking at stabilising it together with these smaller pieces soon, but I'm not sure it will be done in time for 6.2.

[getdave]

Noting that this PR landed #46131

[noisysocks]

• __experimentalShowSelectedHint @noisysocks

I've privatised this in #47229.

• __experimentalStyles @noisysocks

I've stabilised this in #47231.