Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Audit experimental APIs for WP 6.3 #51315

Closed
tellthemachines opened this issue Jun 8, 2023 · 11 comments
Closed

Audit experimental APIs for WP 6.3 #51315

tellthemachines opened this issue Jun 8, 2023 · 11 comments
Labels
Gutenberg Plugin Issues or PRs related to Gutenberg Plugin management related efforts [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.

Comments

@tellthemachines
Copy link
Contributor

tellthemachines commented Jun 8, 2023

New APIs since 6.2

Here are all the non-private uses of __experimental that are new since 6.4 (for reference, the previous API audit was in #47196):

__experimentalDisableBlockOverlay @youknowriad
__experimentalHasContentRoleAttribute @jorgefilipecosta (this refers to the one in the blocks package; the more recent one in block-editor is already marked private)
__experimentalInteractivityAPI @c4rl0sbr4v0 (this is a Gutenberg experiment)
__experimentalEnableGroupGridVariation @tellthemachines (also a Gutenberg experiment)
__experimentalEnablePatternEnhancements @glendaviesnz (also a Gutenberg experiment)
__experimentalAutoSelectFirstMatch @dinhtungdu (components package)
__experimentalNavigatorToParentButton @youknowriad
__experimentalInjectInteractivityRuntime @gziolo (webpack related)

Could you folks take a look at these and see if they're ready for stabilisation, if they should go into 6.3 at all, or if they can be marked private?

New private APIs since 6.2

For these there's no action needed for now, unless they are ready to be stabilised!

__experimentalPopoverLegacyPositionToPlacement
__experimentalUpdateSettings

If I missed anything in the lists above please feel free to add to them as needed.

All experimental APis

Generated using @noisysocks' script from #28157

Edit: I updated the list below to remove duplicate entries with the aid of #51341 (thanks @mcsf!)

Cc @WordPress/gutenberg-core is there anything in the list below that can be stabilised, marked private or removed?

Complete list of experimental APIs

lib

__experimentalBorder
__experimentalDefault
__experimentalDuotone
__experimentalEnableColorRandomizer
__experimentalEnableGroupGridVariation
__experimentalEnableListBlockV2
__experimentalEnablePatternEnhancements
__experimentalEnableQuoteBlockV2
__experimentalEnableZoomedOutView
__experimentalFeatures
__experimentalFontFamily
__experimentalFontStyle
__experimentalFontWeight
__experimentalInteractivityAPI
__experimentalLayout
__experimentalLetterSpacing
__experimentalSelector
__experimentalSettings
__experimentalStyle
__experimentalStyles
__experimentalTextDecoration
__experimentalTextTransform

packages/annotations

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

packages/block-directory

__experimentalIsFocusable

packages/block-editor

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

packages/block-library

__experimentalConvert
__experimentalDiscussionSettings
__experimentalGetCoreBlocks
__experimentalGetDefaultTemplatePartAreas
__experimentalInputControl
__experimentalIsEditingReusableBlock
__experimentalOnEnter
__experimentalRegisterExperimentalCoreBlocks
__experimentalShowHowTo
__experimentalShowTooltip
__experimentalTooltipProps

packages/blocks

__experimentalGetUnprocessedBlockTypes
__experimentalReapplyBlockTypeFilters
__experimentalRegisterBlockType
__experimentalSanitizeBlockAttributes

packages/commands

__experimentalHideHeader

packages/components

__experimentalApplyValueToSides
__experimentalAutoSelectFirstMatch
__experimentalBorderControl
__experimentalConfirmDialog
__experimentalDimensionControl
__experimentalDivider
__experimentalElevation
__experimentalExpandOnFocus
__experimentalInputControlPrefixWrapper
__experimentalInputControlSuffixWrapper
__experimentalInvalid
__experimentalIsEmptyBorder
__experimentalNavigation
__experimentalNavigationBackButton
__experimentalNavigationGroup
__experimentalNavigationItem
__experimentalNavigationMenu
__experimentalNavigatorToParentButton
__experimentalPaletteEdit
__experimentalRadio
__experimentalRadioGroup
__experimentalRenderItem
__experimentalScrollable
__experimentalSurface
__experimentalTheme
__experimentalToggleGroupControlOptionBase
__experimentalUseDialog
__experimentalUseDragging
__experimentalUseFocusOutside
__experimentalUseNavigator
__experimentalUseSlot
__experimentalValidateInput

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/dependency-extraction-webpack-plugin

__experimentalInjectInteractivityRuntime

packages/e2e-test-utils

__experimentalActivatePlugin
__experimentalDeactivatePlugin
__experimentalRest

packages/edit-post

__experimentalFullscreenModeClose
__experimentalGetPreviewDeviceType
__experimentalMainDashboardButton
__experimentalSetPreviewDeviceType

packages/edit-site

__experimentalAdditionalBlockPatternCategories
__experimentalAdditionalBlockPatterns
__experimentalDashboardLink
__experimentalGetDefaultTemplateTypes
__experimentalGetTemplateInfo

packages/editor

__experimentalCreatePageEntity
__experimentalGetDefaultTemplateType
__experimentalTearDownEditor
__experimentalUserCanCreatePages

packages/reusable-blocks

__experimentalConvertBlocksToReusable
__experimentalDeleteReusableBlock
__experimentalSetEditingReusableBlock

@tellthemachines tellthemachines added Gutenberg Plugin Issues or PRs related to Gutenberg Plugin management related efforts [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues. labels Jun 8, 2023
@cbravobernal
Copy link
Contributor

Hi!

__experimentalInteractivityAPI Should not go into WP 6.3, as we are planning to remove that experimental setting from Gutenberg.

__experimentalInjectInteractivityRuntime Should not go into WP 6.3 too, as is an option to bundle the interactivity API in Gutenberg. It is a temporary fix that should be updated when the Interactivity API is moved to its own package.

@youknowriad
Copy link
Contributor

__experimentalDisableBlockOverlay

Unfortunately, the block.json and theme.json can't use private APIs, so experimental/internal prefixes are still useful for these.

@glendaviesnz
Copy link
Contributor

__experimentalEnablePatternEnhancements

We will most likely revert this, so won't be going into 6.3.

@nerrad
Copy link
Contributor

nerrad commented Jun 8, 2023

I wonder if it'd be helpful for future versions of the script generating this list to split out already deprecated APIs (such as __experimentalUseEntityRecord) into a separate section? That might help speed up the triage a bit?

@tellthemachines
Copy link
Contributor Author

I wonder if it'd be helpful for future versions of the script generating this list to split out already deprecated APIs (such as __experimentalUseEntityRecord) into a separate section? That might help speed up the triage a bit?

That would be helpful, but is there any way we can tell for sure an API has been deprecated? Even if we check that it appears within a deprecated() it might not be the API itself that has been deprecated, as in this case.

Relatedly, do we have any policy for removing deprecated APIs altogether? So, if we work out a way of splitting the deprecated APIs out, would it still be useful to output them as a separate list?

@nerrad
Copy link
Contributor

nerrad commented Jun 11, 2023

The point you made about reliable detection is valid - it would be tricky.

Relatedly, do we have any policy for removing deprecated APIs altogether? So, if we work out a way of splitting the deprecated APIs out, would it still be useful to output them as a separate list?

I think even without the policy, there's some value in being able to parse the list and know at a glance that certain APIs have already been triaged and have stable counterparts. In those cases (for now) the deprecation is just a back-compat accommodation. There could even be argument that those APIs shouldn't be included in this post if they've already been "handled".

@tellthemachines
Copy link
Contributor Author

tellthemachines commented Jun 29, 2023

Update:

  • __experimentalLayout has now been stabilised;
  • __experimentalLayoutStyle, __experimentaluseLayoutClassesand __experimentaluseLayoutStyles have been made private.

(See #51434)

@kmanijak
Copy link
Contributor

Hi, I'd like to raise that we could potentially stabilize components from @wordpress/components package. We're using them within WooCommerce Blocks to extend/enrich Inspector Controls of multiple blocks.

These components seem stable as they don't change for the last couple of versions and the Inspector Controls and we don't see issues or limitations in regards to them.

Components that we rely on:

__experimentalToggleGroupControl
__experimentalToggleGroupControlOption
__experimentalRadio as Radio,
__experimentalRadioGroup as RadioGroup
__experimentalToolsPanel
__experimentalToolsPanelItem
__experimentalNumberControl

Note: for some reason in the API list above, they're listed under packages/block-editor while they are exported from packages/components.

@tellthemachines
Copy link
Contributor Author

Thanks @kmanijak ! As we're fast approaching Beta 3 it might be a bit late in the cycle to get these done, but perhaps we can start work on them for 6.4. @mirka what do you think?

Note: for some reason in the API list above, they're listed under packages/block-editor while they are exported from packages/components

It's a very simple script that generates these entries, and it picks the first package it finds mention of the API in 🙂

@mirka
Copy link
Member

mirka commented Jul 3, 2023

As we're fast approaching Beta 3 it might be a bit late in the cycle to get these done, but perhaps we can start work on them for 6.4. @mirka what do you think?

Sure. We've recently started to consider versioning components in order to introduce major breaking changes in a sustainable way. So it's looking hopeful!

@tellthemachines
Copy link
Contributor Author

Closing this issue as RC1 is next week; we're past the time for stabilising further APIs for 6.3 😅

Thanks everyone!

@github-project-automation github-project-automation bot moved this from 🏗️ In Progress to ✅ Done in WordPress 6.3.x Editor Tasks Jul 13, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Gutenberg Plugin Issues or PRs related to Gutenberg Plugin management related efforts [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.
Projects
No open projects
Development

No branches or pull requests

7 participants