diff --git a/.eslintrc.js b/.eslintrc.js index 97c9f395194f35..25173a9f0e8a82 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -278,10 +278,9 @@ module.exports = { }, }, { - // Temporary rules until we're ready to officially deprecate the bottom margins. files: [ 'packages/*/src/**/*.[tj]s?(x)' ], excludedFiles: [ - 'packages/components/src/**/@(test|stories)/**', + 'packages/*/src/**/@(test|stories)/**', '**/*.@(native|ios|android).js', ], rules: { @@ -289,14 +288,19 @@ module.exports = { 'error', ...restrictedSyntax, ...restrictedSyntaxComponents, + // Temporary rules until we're ready to officially deprecate the bottom margins. ...[ + 'BaseControl', 'CheckboxControl', 'ComboboxControl', + 'DimensionControl', 'FocalPointPicker', 'RangeControl', 'SearchControl', + 'SelectControl', 'TextControl', 'TextareaControl', + 'ToggleControl', 'ToggleGroupControl', 'TreeSelect', ].map( ( componentName ) => ( { @@ -305,6 +309,45 @@ module.exports = { componentName + ' should have the `__nextHasNoMarginBottom` prop to opt-in to the new margin-free styles.', } ) ), + // Temporary rules until we're ready to officially default to the new size. + ...[ + 'BorderBoxControl', + 'BorderControl', + 'ComboboxControl', + 'CustomSelectControl', + 'DimensionControl', + 'FontAppearanceControl', + 'FontFamilyControl', + 'FontSizePicker', + 'FormTokenField', + 'InputControl', + 'LineHeightControl', + 'NumberControl', + 'RangeControl', + 'TextControl', + 'ToggleGroupControl', + ].map( ( componentName ) => ( { + // Falsy `__next40pxDefaultSize` without a non-default `size` prop. + selector: `JSXOpeningElement[name.name="${ componentName }"]:not(:has(JSXAttribute[name.name="__next40pxDefaultSize"][value.expression.value!=false])):not(:has(JSXAttribute[name.name="size"][value.value!="default"]))`, + message: + componentName + + ' should have the `__next40pxDefaultSize` prop to opt-in to the new default size.', + } ) ), + { + // Falsy `__next40pxDefaultSize` without a `render` prop. + selector: + 'JSXOpeningElement[name.name="FormFileUpload"]:not(:has(JSXAttribute[name.name="__next40pxDefaultSize"][value.expression.value!=false])):not(:has(JSXAttribute[name.name="render"]))', + message: + 'FormFileUpload should have the `__next40pxDefaultSize` prop to opt-in to the new default size.', + }, + // Temporary rules until all existing components have the `__next40pxDefaultSize` prop. + ...[ 'SelectControl' ].map( ( componentName ) => ( { + // Not strict. Allows pre-existing __next40pxDefaultSize={ false } usage until they are all manually updated. + selector: `JSXOpeningElement[name.name="${ componentName }"]:not(:has(JSXAttribute[name.name="__next40pxDefaultSize"])):not(:has(JSXAttribute[name.name="size"]))`, + message: + componentName + + ' should have the `__next40pxDefaultSize` prop to opt-in to the new default size.', + } ) ), ], }, }, diff --git a/.github/workflows/props-bot.yml b/.github/workflows/props-bot.yml index 0f21f47ef14f99..b2332aabb816c7 100644 --- a/.github/workflows/props-bot.yml +++ b/.github/workflows/props-bot.yml @@ -18,7 +18,7 @@ on: # You cannot filter this event for PR comments only. # However, the logic below does short-circuit the workflow for issues. issue_comment: - type: + types: - created # This event will run everytime a new PR review is initially submitted. pull_request_review: diff --git a/backport-changelog/6.6/7145.md b/backport-changelog/6.6/7145.md new file mode 100644 index 00000000000000..386f765cb22fa8 --- /dev/null +++ b/backport-changelog/6.6/7145.md @@ -0,0 +1,3 @@ +https://github.com/WordPress/wordpress-develop/pull/7145 + +* https://github.com/WordPress/gutenberg/pull/64076 diff --git a/backport-changelog/6.7/7125.md b/backport-changelog/6.7/7125.md new file mode 100644 index 00000000000000..ce208decd2d145 --- /dev/null +++ b/backport-changelog/6.7/7125.md @@ -0,0 +1,3 @@ +https://github.com/WordPress/wordpress-develop/pull/7125 + +* https://github.com/WordPress/gutenberg/pull/61577 diff --git a/backport-changelog/6.7/7137.md b/backport-changelog/6.7/7137.md new file mode 100644 index 00000000000000..00771b8bc6c21d --- /dev/null +++ b/backport-changelog/6.7/7137.md @@ -0,0 +1,5 @@ +https://github.com/WordPress/wordpress-develop/pull/7137 + +* https://github.com/WordPress/gutenberg/pull/64128 +* https://github.com/WordPress/gutenberg/pull/64192 +* https://github.com/WordPress/gutenberg/pull/64328 diff --git a/backport-changelog/6.7/7179.md b/backport-changelog/6.7/7179.md new file mode 100644 index 00000000000000..d777eace2cb05e --- /dev/null +++ b/backport-changelog/6.7/7179.md @@ -0,0 +1,5 @@ +https://github.com/WordPress/wordpress-develop/pull/7179 + +* https://github.com/WordPress/gutenberg/pull/64401 +* https://github.com/WordPress/gutenberg/pull/64459 +* https://github.com/WordPress/gutenberg/pull/64477 diff --git a/changelog.txt b/changelog.txt index b7bbdf821f374e..748df8da3484c7 100644 --- a/changelog.txt +++ b/changelog.txt @@ -1,5 +1,374 @@ == Changelog == += 19.0.0 = + +## Changelog + +### Enhancements + +- Add alt edit field to the inline image in the format library ([64124](https://github.com/WordPress/gutenberg/pull/64124)) +- Update copy from "No Title" to "No title" across multiple places on the editor. ([64184](https://github.com/WordPress/gutenberg/pull/64184)) +- Update column input to be 40px by default. ([64190](https://github.com/WordPress/gutenberg/pull/64190)) + +#### Block Library +- Add anchor block support to List Items. ([48758](https://github.com/WordPress/gutenberg/pull/48758)) +- Unset the rowStart and columnStart attributes when a block inside the Grid is removed from a manual layout. ([64186](https://github.com/WordPress/gutenberg/pull/64186)) +- Update Group block example. ([63114](https://github.com/WordPress/gutenberg/pull/63114)) +- Make SiteLogoReplaceFlow always available in the Site Logo block toolbar. ([63499](https://github.com/WordPress/gutenberg/pull/63499)) +- Make Query Loop settings more intuitive with a ToggleGroup and simplified help text. ([63739](https://github.com/WordPress/gutenberg/pull/63739)) +- Move gallery link controls to the block toolbar. ([62762](https://github.com/WordPress/gutenberg/pull/62762)) +- Hide loading when the overlay menu is selected. ([64262](https://github.com/WordPress/gutenberg/pull/64262)) +- Move the Site Logo tooltip to the middle right. ([64296](https://github.com/WordPress/gutenberg/pull/64296)) +- Prevent duplicate spacing on Tag Cloud block. ([63832](https://github.com/WordPress/gutenberg/pull/63832)) +- Fix 'can user edit' Template Part check. ([64137](https://github.com/WordPress/gutenberg/pull/64137)) +- Add clearfix in Post content. ([63690](https://github.com/WordPress/gutenberg/pull/63690)) +- Tweak Tag Cloud controls and description. ([64151](https://github.com/WordPress/gutenberg/pull/64151)) +- Tweak list block. ([64025](https://github.com/WordPress/gutenberg/pull/64025)) +- Update MediaUpload button for the site logo from "Add media" to "Choose logo". ([63498](https://github.com/WordPress/gutenberg/pull/63498)) +- Update help text for sticky control in Query loop. ([63999](https://github.com/WordPress/gutenberg/pull/63999)) +- Add border support to the following blocks: + - [Time To Read](https://github.com/WordPress/gutenberg/pull/63776) + - [Categories List](https://github.com/WordPress/gutenberg/pull/63950) + - [Post Date](https://github.com/WordPress/gutenberg/pull/64023) + - [Post Excerpt](https://github.com/WordPress/gutenberg/pull/64022) + - [Post Terms](https://github.com/WordPress/gutenberg/pull/64246) + - [Post Title](https://github.com/WordPress/gutenberg/pull/64024) + - [Site Tagline](https://github.com/WordPress/gutenberg/pull/63778) + - [Site Title](https://github.com/WordPress/gutenberg/pull/63631) + - [Table of contents](https://github.com/WordPress/gutenberg/pull/63578) + +#### Extensibility +- Add an async `__unstablePreSavePost` hook; resolving with false prevents saving. ([58022](https://github.com/WordPress/gutenberg/pull/58022)) +- Enable heading level curation. ([63535](https://github.com/WordPress/gutenberg/pull/63535)) +- Addition of `levelOptions` attribute to control available heading levels in [Post Title](https://github.com/WordPress/gutenberg/pull/64106), [Query Title](https://github.com/WordPress/gutenberg/pull/64107), [Site Tagline](https://github.com/WordPress/gutenberg/pull/64113), [Site Title](https://github.com/WordPress/gutenberg/pull/64111), and [Comments Title](https://github.com/WordPress/gutenberg/pull/64103). + +#### Data Views +- Be more clear with the copy of the "hide" action. ([63047](https://github.com/WordPress/gutenberg/pull/63047)) +- Graduate data view options out of a menu to allow more design expression. ([64175](https://github.com/WordPress/gutenberg/pull/64175)) +- Move filter UI into a toggle-able panel to improve experience on narrow viewports/containers. ([63203](https://github.com/WordPress/gutenberg/pull/63203)) +- Update field line-height across grid/list layouts. ([63945](https://github.com/WordPress/gutenberg/pull/63945)) +- Update template description in table layout. ([63942](https://github.com/WordPress/gutenberg/pull/63942)) +- De-emphasise bulk actions on Grid layout. ([64209](https://github.com/WordPress/gutenberg/pull/64209)) +- Update the copy of some of the strings on dataviews actions. ([64099](https://github.com/WordPress/gutenberg/pull/64099)) + +##### Dataviews Extensibility + +- Allow unregistering of the following post actions: [permanently delete](https://github.com/WordPress/gutenberg/pull/64088), [restore post](https://github.com/WordPress/gutenberg/pull/64134), and [trash post](https://github.com/WordPress/gutenberg/pull/64087). + +#### Dataform + +- Add author to quick edit page/post list. ([63983](https://github.com/WordPress/gutenberg/pull/63983)) +- If a field of type `text` declare `elements`, render it as a `SelectControl` in `edit`. ([64251](https://github.com/WordPress/gutenberg/pull/64251)) +- Migrate order action modal and introduce form validation. ([63895](https://github.com/WordPress/gutenberg/pull/63895)) + + + +#### Components +- Add radius scale. ([64007](https://github.com/WordPress/gutenberg/pull/64007)) +- Support generic props type on CustomSelectControl. ([63985](https://github.com/WordPress/gutenberg/pull/63985)) +- Guide: Add __next40pxDefaultSize to buttons. ([64181](https://github.com/WordPress/gutenberg/pull/64181)) +- Image: Make Placeholder white when there is a on top. ([63885](https://github.com/WordPress/gutenberg/pull/63885)) +- SelectControl: Infer `value` type from `options`. ([64069](https://github.com/WordPress/gutenberg/pull/64069)) +- SelectControl: Pass through `options` props. ([64211](https://github.com/WordPress/gutenberg/pull/64211)) +- TimeInput: Expose as subcomponent of TimePicker. ([63145](https://github.com/WordPress/gutenberg/pull/63145)) +- Update radius variables in components configuration. ([64133](https://github.com/WordPress/gutenberg/pull/64133)) +- `RadioControl`: Add support for option help text. ([63751](https://github.com/WordPress/gutenberg/pull/63751)) + +#### Block Editor +- Block Autocompleter: Force icon color to text color when item is selected. ([61376](https://github.com/WordPress/gutenberg/pull/61376)) +- Don't overlap canvas with inserter panel at large screens. ([64110](https://github.com/WordPress/gutenberg/pull/64110)) +- Format Library: Polish inline image format popover. ([64016](https://github.com/WordPress/gutenberg/pull/64016)) +- LineHeightControl: Hard deprecate bottom margin. ([64281](https://github.com/WordPress/gutenberg/pull/64281)) +- New useBlockElementRef hook for storing block element into a ref. ([63799](https://github.com/WordPress/gutenberg/pull/63799)) +- Improved tabbed sidebar styles. ([61974](https://github.com/WordPress/gutenberg/pull/61974)) +- URLInput: Hard deprecate bottom margin. ([64282](https://github.com/WordPress/gutenberg/pull/64282)) + +#### Global Styles +- Add a typesets section to Typography. ([62539](https://github.com/WordPress/gutenberg/pull/62539)) +- Add tooltips to the heading level selectors. ([64039](https://github.com/WordPress/gutenberg/pull/64039)) +- Background images: Ensure appropriate default values. ([64192](https://github.com/WordPress/gutenberg/pull/64192)) +- Create new public function to make it easier to expose style variations from other themes. ([63318](https://github.com/WordPress/gutenberg/pull/63318)) +- Style Book: Clearly denote heading levels. ([64038](https://github.com/WordPress/gutenberg/pull/64038)) + +#### Design Tools +- Column: Enable border radius support. ([63924](https://github.com/WordPress/gutenberg/pull/63924)) +- Comment Template: Add Border Block Support. ([64238](https://github.com/WordPress/gutenberg/pull/64238)) +- Post Comments Form: Add Border Block Support. ([64233](https://github.com/WordPress/gutenberg/pull/64233)) + +#### Zoom Out +- Add a control to enter and leave zoom out mode. ([63870](https://github.com/WordPress/gutenberg/pull/63870)) +- Improve zoom transition. ([64179](https://github.com/WordPress/gutenberg/pull/64179)) + +#### Site Editor +- Clarify that the site icon is a back button using an animation. ([63986](https://github.com/WordPress/gutenberg/pull/63986)) +- Site Icon: Add back filter effect to make it work for all kind of site icons. ([64172](https://github.com/WordPress/gutenberg/pull/64172)) + +#### Post Editor +- Tweak Create custom template modal. ([64255](https://github.com/WordPress/gutenberg/pull/64255)) + +#### Icons +- Add new "send" icon. ([64130](https://github.com/WordPress/gutenberg/pull/64130)) + +#### Plugin +- Bump minimum required WordPress version to 6.5. ([64126](https://github.com/WordPress/gutenberg/pull/64126)) + +#### Font Library +- Include a "Select All" options for google fonts. ([63893](https://github.com/WordPress/gutenberg/pull/63893)) + +#### Block bindings +- Allow bindings bootstrap after registration. ([63797](https://github.com/WordPress/gutenberg/pull/63797)) + +#### Interactivity API +- Refactor internal proxy and signals system. ([62734](https://github.com/WordPress/gutenberg/pull/62734)) + + +### New APIs + +- Make useStyleOverride public. ([63656](https://github.com/WordPress/gutenberg/pull/63656)) + + +### Bug Fixes + +- Core Data: Fix 'getEntityRecordPermissions' memoization. ([64091](https://github.com/WordPress/gutenberg/pull/64091)) +- Document bar: Fix long title with no spaces causing layout issue. ([64092](https://github.com/WordPress/gutenberg/pull/64092)) +- Fix density slider minus to be correct. ([64185](https://github.com/WordPress/gutenberg/pull/64185)) +- Fix: Deleting a pattern throws a notice saying undefined deleted. ([64301](https://github.com/WordPress/gutenberg/pull/64301)) +- Primitives: Add missing peer dependency. ([64218](https://github.com/WordPress/gutenberg/pull/64218)) +- Site Icon: Fix position in distraction free mode. ([64261](https://github.com/WordPress/gutenberg/pull/64261)) + +#### Data Views +- Add context to trash string. ([64249](https://github.com/WordPress/gutenberg/pull/64249)) +- Conditionally shows the description field in Template Grid layout. ([64043](https://github.com/WordPress/gutenberg/pull/64043)) +- Consider layout URL parameter when loading a default/custom view. ([64306](https://github.com/WordPress/gutenberg/pull/64306)) +- Display published date for pages/posts with published status. ([64049](https://github.com/WordPress/gutenberg/pull/64049)) +- Sort author by name + allow custom sort function. ([64064](https://github.com/WordPress/gutenberg/pull/64064)) +- Don't render action modal when there are no eligible items. ([64250](https://github.com/WordPress/gutenberg/pull/64250)) +- Pages: Update `useView` logic. ([63889](https://github.com/WordPress/gutenberg/pull/63889)) +- Update template preview dimensions in table layout. ([63938](https://github.com/WordPress/gutenberg/pull/63938)) +- Update template preview dimensions in table layout. ([63938](https://github.com/WordPress/gutenberg/pull/63938)) + +#### Dataform + +- Fix SelectControl size and spacing. ([64324](https://github.com/WordPress/gutenberg/pull/64324)) +- Provide a better default for render when field has elements. ([64338](https://github.com/WordPress/gutenberg/pull/64338)) + +#### Components +- Autocompleter UI: Fix text color when hovering selected item. ([64294](https://github.com/WordPress/gutenberg/pull/64294)) +- BaseControl: change label's display: Block. ([63911](https://github.com/WordPress/gutenberg/pull/63911)) +- Button: Fix tertiary destructive hover style. ([64152](https://github.com/WordPress/gutenberg/pull/64152)) +- ColorPalette: Remove extra bottom margin when `CircularOptionPicker` is unneeded. ([63961](https://github.com/WordPress/gutenberg/pull/63961)) +- DropdownMenuV2: Break menu item help text on multiple lines for better truncation. ([63916](https://github.com/WordPress/gutenberg/pull/63916)) +- Fix modal dismissers in development mode. ([64132](https://github.com/WordPress/gutenberg/pull/64132)) +- Fix toggle help indentation. ([63903](https://github.com/WordPress/gutenberg/pull/63903)) +- Update the TextControl padding to match the rest of the controls. ([64326](https://github.com/WordPress/gutenberg/pull/64326)) + +#### Global Styles +- Fix block custom CSS pseudo element selectors. ([63980](https://github.com/WordPress/gutenberg/pull/63980)) +- Fix block library and global styles stylesheet ordering when a block style variation is active. ([63918](https://github.com/WordPress/gutenberg/pull/63918)) +- Style Book: Fix critical error when heading block is not registered. ([64047](https://github.com/WordPress/gutenberg/pull/64047)) +- TypesetButton: Check if variations exist before running logic. ([64139](https://github.com/WordPress/gutenberg/pull/64139)) + +#### Site Editor +- Centrally align entity in focused edit mode. ([64143](https://github.com/WordPress/gutenberg/pull/64143)) +- Don't trigger template ID resolution for multi-selected posts. ([64254](https://github.com/WordPress/gutenberg/pull/64254)) +- Long slugs breaking summary panel UI. ([64053](https://github.com/WordPress/gutenberg/pull/64053)) + +#### Zoom Out +- Keep top-level block selection if entering zoom out mode. ([64178](https://github.com/WordPress/gutenberg/pull/64178)) +- Use the block editor for insertion point data. ([63934](https://github.com/WordPress/gutenberg/pull/63934)) + +#### Block Library +- Fix a typo in use-image-sizes.js. ([64100](https://github.com/WordPress/gutenberg/pull/64100)) +- Template Part: Fix capability checks for inner blocks. ([64159](https://github.com/WordPress/gutenberg/pull/64159)) +- Update useTaxonomies hook to check for taxonomies for passed post type. ([64145](https://github.com/WordPress/gutenberg/pull/64145)) + +#### Design Tools +- Quote: Prevent block theme styles overriding global border and padding. ([64045](https://github.com/WordPress/gutenberg/pull/64045)) +- Spacing controls: Using CustomSelectControlV2 for >= 8 spacing sizes. ([64284](https://github.com/WordPress/gutenberg/pull/64284)) + +#### Post Editor +- Avoid errors for post types without a 'menu_icon'. ([64015](https://github.com/WordPress/gutenberg/pull/64015)) +- Post: Add a max length to the post password protected field. ([64156](https://github.com/WordPress/gutenberg/pull/64156)) + +#### Grid layout +- Fix grid resizer drag over embed. ([64098](https://github.com/WordPress/gutenberg/pull/64098)) +- Move resizer popover slot to fix display on mobile. ([63920](https://github.com/WordPress/gutenberg/pull/63920)) + +#### Block Editor +- Fix unexpected drag & rrop row/gallery creation logic. ([64241](https://github.com/WordPress/gutenberg/pull/64241)) + +#### Icons +- Remove hardcoded color from sidesAxial and sidesBottom icons. ([64174](https://github.com/WordPress/gutenberg/pull/64174)) + +#### Document Settings +- Display empty option when post author is missing. ([64165](https://github.com/WordPress/gutenberg/pull/64165)) + +#### Patterns +- Enable cross-browser support for pattern uploading. ([64123](https://github.com/WordPress/gutenberg/pull/64123)) + +#### Commands +- Fix 'Preferences' and 'Shortcuts' commands in StrictMode. ([64019](https://github.com/WordPress/gutenberg/pull/64019)) + +#### Meta Boxes +- Prevent popover from being hidden by metaboxes. ([63939](https://github.com/WordPress/gutenberg/pull/63939)) + +#### Page Content Focus +- TemplateContentPanel: Don't show content blocks that are in a Query Loop. ([63732](https://github.com/WordPress/gutenberg/pull/63732)) + +#### Font Library +- Fix item font family item height in the sidebar. ([63125](https://github.com/WordPress/gutenberg/pull/63125)) + +#### Block API +- Block categories - ensure that categories are unique by slug. ([62954](https://github.com/WordPress/gutenberg/pull/62954)) + + +### Accessibility + +- Restore focus style in dataviews grid view. ([64298](https://github.com/WordPress/gutenberg/pull/64298)) +- A11y text for site editor. ([62648](https://github.com/WordPress/gutenberg/pull/62648)) +- Accessibility issue of device preview options. ([63958](https://github.com/WordPress/gutenberg/pull/63958)) + +#### Components +- Improve the aria-disabled focus style of the Button. ([62480](https://github.com/WordPress/gutenberg/pull/62480)) +- Restore `describedBy` functionality on CustomSelectControl. ([63957](https://github.com/WordPress/gutenberg/pull/63957)) + +#### Block Library +- Fix unlabeled Spacer block controls. ([63806](https://github.com/WordPress/gutenberg/pull/63806)) +- Move Posts Per Page, Offset, and Pages controls from the block toolbar into Inspector Controls. ([58207](https://github.com/WordPress/gutenberg/pull/58207)) + +#### Font Library +- Remove notice context and add message when fonts are updated. ([64030](https://github.com/WordPress/gutenberg/pull/64030)) + + +### Performance + +- Add User Timings for the Interactivity API. ([60522](https://github.com/WordPress/gutenberg/pull/60522)) + +#### Data Views +- Optimize the patterns dataviews by extracting the fields definition. ([63927](https://github.com/WordPress/gutenberg/pull/63927)) + +#### Layout +- Avoid iterating auto grid inner blocks unless mode specifically changed. ([64194](https://github.com/WordPress/gutenberg/pull/64194)) + +#### Block bindings +- Move logic to merge `usesContext` outside the reducer. ([63941](https://github.com/WordPress/gutenberg/pull/63941)) + + +### Experiments + +- Adds experimental blocks flag. ([64121](https://github.com/WordPress/gutenberg/pull/64121)) + +#### DataForm +- Support multiple layouts and introduce the panel layout. ([64299](https://github.com/WordPress/gutenberg/pull/64299)) + +#### DataViews Extensibility +- Add a hook to allow third-party scripts to register/unregister post type actions. ([64138](https://github.com/WordPress/gutenberg/pull/64138)) + +#### Grid Interactivity +- Fix block mover layout and styles. ([64021](https://github.com/WordPress/gutenberg/pull/64021)) + +#### Block bindings +- UI for connecting bindings. ([62880](https://github.com/WordPress/gutenberg/pull/62880)) + + +### Documentation + +- .wp-env.json schema: Fix schema and add unit tests. ([63281](https://github.com/WordPress/gutenberg/pull/63281)) +- Add WP Studio to list of tools in documentation. ([64327](https://github.com/WordPress/gutenberg/pull/64327)) +- Add documentation for some dynamically generated selectors in the core-data store. ([64269](https://github.com/WordPress/gutenberg/pull/64269)) +- Block Editor: Update 'getBlocksByName' JSDoc. ([63919](https://github.com/WordPress/gutenberg/pull/63919)) +- Components: Add missing `__nextHasNoMarginBottom` documentation. ([64313](https://github.com/WordPress/gutenberg/pull/64313)) +- Corrected @deprecated doc Order in Inline Documentation. ([64013](https://github.com/WordPress/gutenberg/pull/64013)) +- Add documentation for `render_block` and `register_block_type_args` to Block Filters. ([64118](https://github.com/WordPress/gutenberg/pull/64118)) +- Fix interactivity API documentation link. ([64060](https://github.com/WordPress/gutenberg/pull/64060)) +- Fix non working link to an interactivity API example block. ([64061](https://github.com/WordPress/gutenberg/pull/64061)) +- Fix WampServer links. ([64062](https://github.com/WordPress/gutenberg/pull/64062)) +- FormToggle, ToggleControl: Fix docgen in Storybook. ([64065](https://github.com/WordPress/gutenberg/pull/64065)) +- Provide a better example for the PluginSidebar slotfill. ([64206](https://github.com/WordPress/gutenberg/pull/64206)) +- Update data-core.md to use correct headings. ([64309](https://github.com/WordPress/gutenberg/pull/64309)) + + +### Code Quality + +- Add margin-bottom lint rules ([64212](https://github.com/WordPress/gutenberg/pull/64212)),([64213](https://github.com/WordPress/gutenberg/pull/64213)) and ([63960](https://github.com/WordPress/gutenberg/pull/63960)) +- Add new useEntityRecordsWithPermissions hook. ([63857](https://github.com/WordPress/gutenberg/pull/63857)) +- Fix deprecated sass usage. ([63990](https://github.com/WordPress/gutenberg/pull/63990)) +- Remove an unnecessary wrapper component. ([63989](https://github.com/WordPress/gutenberg/pull/63989)) +- Theme JSON: Update core theme json resolver class use to Gutenberg version. ([63981](https://github.com/WordPress/gutenberg/pull/63981)) +- Zoom out: Get store action outside the loop. ([63936](https://github.com/WordPress/gutenberg/pull/63936)) +- Remove Speak from device menu selection. ([64115](https://github.com/WordPress/gutenberg/pull/64115)) + +#### Block Editor +- BlockDraggable: Remove invalid aria-hidden attribute from button. ([64228](https://github.com/WordPress/gutenberg/pull/64228)) +- FontFamilyControl: Deprecate bottom margin. ([64280](https://github.com/WordPress/gutenberg/pull/64280)) +- Remove unnecessary/incorrect `unlock` call in `setEditorMode` action. ([64073](https://github.com/WordPress/gutenberg/pull/64073)) + +#### Data Views +- Formalize text field type definition. ([64168](https://github.com/WordPress/gutenberg/pull/64168)) +- Use items with permissions and avoid hooks to register actions. ([63923](https://github.com/WordPress/gutenberg/pull/63923)) + +#### DataForm +- Centralize edit logic in field type definitions. ([64171](https://github.com/WordPress/gutenberg/pull/64171)) +- Move validation logic to the field type definition. ([64164](https://github.com/WordPress/gutenberg/pull/64164)) + +#### Global Styles +- Background image: Remove toolspanel placeholder component. ([64242](https://github.com/WordPress/gutenberg/pull/64242)) +- Consolidate theme.json ref and URI resolution. ([64182](https://github.com/WordPress/gutenberg/pull/64182)) + +#### Plugin +- Remove compat layers for WP 6.4 and 6.5. ([64096](https://github.com/WordPress/gutenberg/pull/64096)) +- Remove leftover 'WP_Rest_Customizer_Nonces' controller. ([64221](https://github.com/WordPress/gutenberg/pull/64221)) + +#### Site Editor +- Use `structuredClone` for deep cloning. ([64203](https://github.com/WordPress/gutenberg/pull/64203)) + +#### Block Library +- Add stylelint rule to prevent usage of flex-direction reverse values. ([63081](https://github.com/WordPress/gutenberg/pull/63081)) +- Image Block Lightbox: Fix warning error when resizing. ([63995](https://github.com/WordPress/gutenberg/pull/63995)) + +#### Icons +- Fix invalid prop for `homeButton` icon. ([64191](https://github.com/WordPress/gutenberg/pull/64191)) + +#### Post Editor +- Remove resolvers hack for post actions. ([64094](https://github.com/WordPress/gutenberg/pull/64094)) + +#### Components +- Upgrade Ariakit. ([64066](https://github.com/WordPress/gutenberg/pull/64066)) + +#### Page Content Focus +- Fix the 'getBlocksByName' selector call. ([63922](https://github.com/WordPress/gutenberg/pull/63922)) + + +### Tools + +#### Testing +- Components: Cleanup flaky unit test `sleep()` hacks. ([64205](https://github.com/WordPress/gutenberg/pull/64205)) +- Fix flaky DataViews list layout end-to-end tests. ([64244](https://github.com/WordPress/gutenberg/pull/64244)) +- Fix typo in 'Verify Core Backport Changelog' job title. ([64058](https://github.com/WordPress/gutenberg/pull/64058)) +- Improve `Button` matrix in visual regression test. ([64120](https://github.com/WordPress/gutenberg/pull/64120)) +- Improve theme.json test failure messages by pretty printing css for a more accurate diff. ([64077](https://github.com/WordPress/gutenberg/pull/64077)) + + +## First-time contributors + +The following PRs were merged by first-time contributors: + +- @Chrico: Block categories - ensure that categories are unique by slug. ([62954](https://github.com/WordPress/gutenberg/pull/62954)) +- @djcowan: Update api-reference.md. ([64325](https://github.com/WordPress/gutenberg/pull/64325)) +- @meteorlxy: CustomSelectControl: Support generic props type. ([63985](https://github.com/WordPress/gutenberg/pull/63985)) +- @Rishit30G: Add WP Studio to list of tools in documentation. ([64327](https://github.com/WordPress/gutenberg/pull/64327)) +- @wzieba: ([64044](https://github.com/WordPress/gutenberg/pull/64044)) + + +## Contributors + +The following contributors merged PRs in this release: + +@aaronrobertshaw @adamsilverstein @afercia @akasunil @Aljullu @amitraj2203 @andrewserong @carolinan @cbravobernal @Chrico @ciampo @creativecoder @DaniGuardiola @DAreRodz @djcowan @ellatrix @jameskoster @jasmussen @jeryj @jorgefilipecosta @jsnajdr @kebbet @kmanijak @Mamaduka @matiasbenedetto @meteorlxy @mikachan @mirka @mtias @ndiego @noisysocks @oandregal @ramonjd @richtabor @Rishit30G @ryanwelcher @SantosGuillamot @scruffian @shail-mehta @simison @stokesman @t-hamano @talldan @tomdevisser @tomjn @tyxla @up1512001 @wzieba @youknowriad + + + + = 18.9.0 = ## Changelog diff --git a/docs/contributors/code/release.md b/docs/contributors/code/release.md index f304ec9cd3a487..ec3af0d7bd4cb2 100644 --- a/docs/contributors/code/release.md +++ b/docs/contributors/code/release.md @@ -227,7 +227,7 @@ The final step is to write a release post on [make.wordpress.org/core](https://m > The plugin was published to the WordPress.org plugin directory but the workflow failed. -This has happened ocassionally, see [this one](https://github.com/WordPress/gutenberg/actions/runs/6955409957/job/18924124118) for example. +This has happened occasionally, see [this one](https://github.com/WordPress/gutenberg/actions/runs/6955409957/job/18924124118) for example. It's important to check that: diff --git a/docs/explanations/architecture/modularity.md b/docs/explanations/architecture/modularity.md index f94f8ec7b9472e..ff619ccbfdf5b7 100644 --- a/docs/explanations/architecture/modularity.md +++ b/docs/explanations/architecture/modularity.md @@ -42,7 +42,7 @@ function MyApp() { ```php // myplugin.php -// Example of script registration dependending on the "components" and "element packages. +// Example of script registration depending on the "components" and "element packages. wp_register_script( 'myscript', 'pathtomyscript.js', array ('wp-components', "react" ) ); ``` diff --git a/docs/getting-started/devenv/README.md b/docs/getting-started/devenv/README.md index 1c2b9ed9070d30..4539dacbdf5047 100644 --- a/docs/getting-started/devenv/README.md +++ b/docs/getting-started/devenv/README.md @@ -54,6 +54,7 @@ Refer to the [Get started with `wp-env`](/docs/getting-started/devenv/get-starte This list is not exhaustive, but here are several additional options to choose from if you prefer not to use `wp-env`: - [Local](https://localwp.com/) +- [WP Studio](https://developer.wordpress.com/studio/) - [XAMPP](https://www.apachefriends.org/) - [MAMP](https://www.mamp.info/en/mamp/mac/) - [Varying Vagrant Vagrants](https://varyingvagrantvagrants.org/) (VVV) diff --git a/docs/getting-started/fundamentals/block-wrapper.md b/docs/getting-started/fundamentals/block-wrapper.md index 39c80262d7bcbe..98c435f6ebe2f7 100644 --- a/docs/getting-started/fundamentals/block-wrapper.md +++ b/docs/getting-started/fundamentals/block-wrapper.md @@ -102,7 +102,7 @@ The [example block](https://github.com/WordPress/block-development-examples/tree ## Dynamic render markup -In dynamic blocks, where the font-end markup is rendered server-side, you can utilize the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) function to output the necessary classes and attributes just like you would use `useBlockProps.save()` in the `save` function. (See [example](https://github.com/WordPress/block-development-examples/blob/f68640f42d993f0866d1879f67c73910285ca114/plugins/block-dynamic-rendering-64756b/src/render.php#L11)) +In dynamic blocks, where the front-end markup is rendered server-side, you can utilize the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) function to output the necessary classes and attributes just like you would use `useBlockProps.save()` in the `save` function. (See [example](https://github.com/WordPress/block-development-examples/blob/f68640f42d993f0866d1879f67c73910285ca114/plugins/block-dynamic-rendering-64756b/src/render.php#L11)) ```php

> diff --git a/docs/getting-started/fundamentals/static-dynamic-rendering.md b/docs/getting-started/fundamentals/static-dynamic-rendering.md index 8d199f66cccd2a..dfb6a7123b44b3 100644 --- a/docs/getting-started/fundamentals/static-dynamic-rendering.md +++ b/docs/getting-started/fundamentals/static-dynamic-rendering.md @@ -61,7 +61,7 @@ Dynamic blocks, which we'll explore in the following section, can specify an ini For a practical demonstration of how this works, refer to the [Building your first block](/docs/getting-started/tutorial.md) tutorial. Specifically, the [Adding static rendering](/docs/getting-started/tutorial.md#adding-static-rendering) section illustrates how a block can have both a saved HTML structure and dynamic rendering capabilities.

-WordPress provides mechanisms like the render_block are the $render_callback function to alter the saved HTML of a block before it appears on the front end. These tools offer developers the capability to customize block output dynamically, catering to complex and interactive user experiences. +WordPress provides mechanisms like the render_block and the render_callback function to alter the saved HTML of a block before it appears on the front end. These tools offer developers the capability to customize block output dynamically, catering to complex and interactive user experiences.
Additional examples of WordPress blocks that use static rendering, meaning their output is fixed at the time of saving and doesn't rely on server-side processing, include: diff --git a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md index 122ee3eaa0c27e..85ac956ff74ba6 100644 --- a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md +++ b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md @@ -138,6 +138,17 @@ And a `style.css` file to load on the frontend: The files will automatically be enqueued when specified in the block.json. +
+ +If you are using `@wordpress/scripts` you will need to import your stylesheet within your corresponding JavaScript file in order for `@wordpress/scripts` to process the stylesheet. + +Example: + +- In `edit.js` you would place `import './editor.scss';` +- In `index.js` you would place `import './style.scss';` +- In `view.js` you would place `import './view.scss';` (interactive block template) +
+ **Note:** If you have multiple files to include, you can use standard `wp_enqueue_style` functions like any other plugin or theme. You will want to use the following hooks for the block editor: - `enqueue_block_editor_assets` - to load only in editor view diff --git a/docs/manifest.json b/docs/manifest.json index 1704e6d711510f..e4eba19d99fa29 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -497,6 +497,30 @@ "markdown_source": "../docs/reference-guides/interactivity-api/README.md", "parent": "reference-guides" }, + { + "title": "Core Concepts", + "slug": "core-concepts", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/README.md", + "parent": "interactivity-api" + }, + { + "title": "The Reactive and Declarative mindset", + "slug": "the-reactive-and-declarative-mindset", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md", + "parent": "core-concepts" + }, + { + "title": "Understanding global state, local context and derived state", + "slug": "undestanding-global-state-local-context-and-derived-state", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md", + "parent": "core-concepts" + }, + { + "title": "Server-side rendering: Processing directives on the server", + "slug": "server-side-rendering", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md", + "parent": "core-concepts" + }, { "title": "Quick start guide", "slug": "iapi-quick-start-guide", @@ -767,6 +791,12 @@ "markdown_source": "../packages/components/src/combobox-control/README.md", "parent": "components" }, + { + "title": "Composite", + "slug": "composite", + "markdown_source": "../packages/components/src/composite/README.md", + "parent": "components" + }, { "title": "ConfirmDialog", "slug": "confirm-dialog", diff --git a/docs/reference-guides/core-blocks.md b/docs/reference-guides/core-blocks.md index 72281a53c3dd18..b9cae44550181c 100644 --- a/docs/reference-guides/core-blocks.md +++ b/docs/reference-guides/core-blocks.md @@ -426,7 +426,7 @@ An individual item within a list. ([Source](https://github.com/WordPress/gutenbe - **Category:** text - **Parent:** core/list - **Allowed Blocks:** core/list -- **Supports:** color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), splitting, typography (fontSize, lineHeight), ~~className~~ +- **Supports:** anchor, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), splitting, typography (fontSize, lineHeight), ~~className~~ - **Attributes:** content, placeholder ## Login/out @@ -783,7 +783,7 @@ Give quoted text visual emphasis. "In quoting others, we cite ourselves." — Ju - **Name:** core/quote - **Category:** text -- **Supports:** anchor, background (backgroundImage, backgroundSize), color (background, gradients, heading, link, text), dimensions (minHeight), interactivity (clientNavigation), layout (~~allowEditing~~), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ +- **Supports:** align (full, left, right, wide), anchor, background (backgroundImage, backgroundSize), color (background, gradients, heading, link, text), dimensions (minHeight), interactivity (clientNavigation), layout (~~allowEditing~~), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** citation, textAlign, value ## Read More diff --git a/docs/reference-guides/data/data-core.md b/docs/reference-guides/data/data-core.md index f4138c49dc8d6b..f08fbc960b8b28 100644 --- a/docs/reference-guides/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -2,7 +2,7 @@ Namespace: `core`. -### Dynamically generated selectors +## Dynamically generated selectors There are a number of user-friendly selectors that are wrappers of the more generic `getEntityRecord` and `getEntityRecords` that can be used to retrieve information for the various entities. diff --git a/docs/reference-guides/filters/block-filters.md b/docs/reference-guides/filters/block-filters.md index e7a31c1e3bbc83..637cecadf1402b 100644 --- a/docs/reference-guides/filters/block-filters.md +++ b/docs/reference-guides/filters/block-filters.md @@ -139,12 +139,12 @@ The following PHP filters are available to change the output of a block on the f ### `render_block` -Filters the font-end content of any block. This filter has no impact on the behavior of blocks in the Editor. +Filters the front-end content of any block. This filter has no impact on the behavior of blocks in the Editor. The callback function for this filter receives three parameters: - `$block_content` (`string`): The block content. -- `block` (`array`): The full block, including name and attributes. +- `$block` (`array`): The full block, including name and attributes. - `$instance` (`WP_Block`): The block instance. In the following example, the class `example-class` is added to all Paragraph blocks on the front end. Here the [HTML API](https://make.wordpress.org/core/2023/03/07/introducing-the-html-api-in-wordpress-6-2/) is used to easily add the class instead of relying on regex. @@ -172,12 +172,12 @@ add_filter( 'render_block', 'example_add_custom_class_to_paragraph_block', 10, 2 ### `render_block_{namespace/block}` -Filters the font-end content of the defined block. This is just a simpler form of `render_block` when you only need to modify a specific block type. +Filters the front-end content of the defined block. This is just a simpler form of `render_block` when you only need to modify a specific block type. The callback function for this filter receives three parameters: - `$block_content` (`string`): The block content. -- `block` (`array`): The full block, including name and attributes. +- `$block` (`array`): The full block, including name and attributes. - `$instance` (`WP_Block`): The block instance. In the following example, the class `example-class` is added to all Paragraph blocks on the front end. Notice that compared to the `render_block` example above, you no longer need to check the block type before modifying the content. Again, the [HTML API](https://make.wordpress.org/core/2023/03/07/introducing-the-html-api-in-wordpress-6-2/) is used instead of regex. diff --git a/docs/reference-guides/interactivity-api/README.md b/docs/reference-guides/interactivity-api/README.md index f5d410a8439f45..3a5bbb84ff159c 100644 --- a/docs/reference-guides/interactivity-api/README.md +++ b/docs/reference-guides/interactivity-api/README.md @@ -16,17 +16,17 @@ For more information about the genesis of the Interactivity API, check out the [ Use the following links to locate the topic you're interested in. If you have never worked with the Interactivity API before, consider reading through the following resources in the order listed. -- **[Requirements](#requirements-of-the-interactivity-api):** Check this section before you start creating your interactive blocks with the Interactivity API. -- **[Quick Start Guide](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-quick-start-guide/):** Get a custom block using the Interactivity API up and running in less than one minute. -- **[Tutorial: A first look at the Interactivity API](https://developer.wordpress.org/news/2024/04/11/a-first-look-at-the-interactivity-api/)** This article from the [WordPress Developer Blog](https://developer.wordpress.org/news/) is a great way to get introduced to the Interactivity API. -- **[API Reference](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/):** To take a deep dive into how the API works internally, the list of Directives, and how the Store works. -- **[Docs and Examples](#docs-examples):** Additional resources to learn/read more about the Interactivity API. +- **[Requirements](#requirements-of-the-interactivity-api):** Check this section before you start creating your interactive blocks with the Interactivity API. +- **[Quick Start Guide](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-quick-start-guide/):** Get a custom block using the Interactivity API up and running in less than one minute. +- **[Tutorial: A first look at the Interactivity API](https://developer.wordpress.org/news/2024/04/11/a-first-look-at-the-interactivity-api/)** This article from the [WordPress Developer Blog](https://developer.wordpress.org/news/) is a great way to get introduced to the Interactivity API. +- **[Core Concepts](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/)** Gain a better understanding of concepts and mental models related to Interactivity API development from this section. +- **[API Reference](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/):** To take a deep dive into how the API works internally, the list of Directives, and how the Store works. +- **[Docs and Examples](#docs-examples):** Additional resources to learn/read more about the Interactivity API. To get a deeper understanding of what the Interactivity API is or find answers to questions you may have about this standard, check the following resources: -- **[About the Interactivity API](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-about/):** To learn more about the API Goals and the reasoning behind the use of a standard to add interactivity to blocks. -- **[Frequently Asked Questions](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-faq/):** To find responses to some frequently asked questions about the technology behind and alternatives. - +- **[About the Interactivity API](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-about/):** To learn more about the API Goals and the reasoning behind the use of a standard to add interactivity to blocks. +- **[Frequently Asked Questions](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-faq/):** To find responses to some frequently asked questions about the technology behind and alternatives. ## Requirements of the Interactivity API @@ -34,9 +34,9 @@ Interactivity API is included in Core in WordPress 6.5. For versions below, you' It’s also important to highlight that the block creation workflow doesn’t change, and all the [prerequisites](https://developer.wordpress.org/block-editor/getting-started/devenv/) remain the same. These include: -- [Code Editor](https://developer.wordpress.org/block-editor/getting-started/devenv/#code-editor) -- [Node.js development tools](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-js-development-tools) -- [Local WordPress environment (site)](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment) +- [Code Editor](https://developer.wordpress.org/block-editor/getting-started/devenv/#code-editor) +- [Node.js development tools](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-js-development-tools) +- [Local WordPress environment (site)](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment) You can start creating interactions once you set up a block development environment and run WordPress 6.5+ (or Gutenberg 17.5+). @@ -56,7 +56,6 @@ Import the store into your `view.js`. Refer to the [store documentation](https:/ import { store } from '@wordpress/interactivity'; ``` - #### Add `interactivity` support to `block.json` To indicate that the block [supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) the Interactivity API features, add `"interactivity": true` to the `supports` attribute of the block's `block.json` file. @@ -84,7 +83,6 @@ The Interactivity API provides the `@wordpress/interactivity` Script Module. Jav The use of `viewScriptModule` also requires the `--experimental-modules` flag for both the [`build`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#build) and [`start`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#start) scripts of `wp-scripts` to ensure a proper build of the Script Modules. - ```json // package.json { @@ -99,11 +97,9 @@ The use of `viewScriptModule` also requires the `--experimental-modules` flag fo To "activate" the Interactivity API in a DOM element (and its children), add the [`wp-interactive`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/#wp-interactive) directive to the DOM element in the block's `render.php` or `save.js` files. - - ```html
- +
``` @@ -113,17 +109,16 @@ Refer to the [`wp-interactive` documentation](https://developer.wordpress.org/bl Here you have some more resources to learn/read more about the Interactivity API: -- [WordPress 6.5 Dev Note](https://make.wordpress.org/core/2024/03/04/interactivity-api-dev-note/) -- [Merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/) -- [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) -- [Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882), especially the [showcase](https://github.com/WordPress/gutenberg/discussions/55642#discussioncomment-9667164) discussions. -- [wpmovies.dev](http://wpmovies.dev/) demo and its [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) repo -- Examples using the Interactivity API at [block-development-examples](https://github.com/WordPress/block-development-examples): - - [`interactivity-api-block-833d15`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-block-833d15) - - [`interactivity-api-countdown-3cd73e`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-countdown-3cd73e) - - [`interactivity-api-quiz-1835fa`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-quiz-1835fa) +- [WordPress 6.5 Dev Note](https://make.wordpress.org/core/2024/03/04/interactivity-api-dev-note/) +- [Merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/) +- [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) +- [Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882), especially the [showcase](https://github.com/WordPress/gutenberg/discussions/55642#discussioncomment-9667164) discussions. +- [wpmovies.dev](http://wpmovies.dev/) demo and its [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) repo +- Examples using the Interactivity API at [block-development-examples](https://github.com/WordPress/block-development-examples): + - [`interactivity-api-block-833d15`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-block-833d15) + - [`interactivity-api-countdown-3cd73e`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-countdown-3cd73e) + - [`interactivity-api-quiz-1835fa`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-quiz-1835fa)
There's a Tracking Issue opened to ease the coordination of the work related to the Interactivity API Docs: Documentation for the Interactivity API - Tracking Issue #53296
- diff --git a/docs/reference-guides/interactivity-api/api-reference.md b/docs/reference-guides/interactivity-api/api-reference.md index 00030465415323..46bd20bece0bda 100644 --- a/docs/reference-guides/interactivity-api/api-reference.md +++ b/docs/reference-guides/interactivity-api/api-reference.md @@ -55,7 +55,7 @@ The `wp-interactive` directive "activates" the interactivity for the DOM element data-wp-interactive="myPlugin" data-wp-context='{ "myColor" : "red", "myBgColor": "yellow" }' > -

I'm interactive now, >and I can use directives!

+

I'm interactive now, and I can use directives!

I'm also interactive, and I can also use directives!

@@ -66,7 +66,7 @@ The `wp-interactive` directive "activates" the interactivity for the DOM element data-wp-interactive='{ "namespace": "myPlugin" }' data-wp-context='{ "myColor" : "red", "myBgColor": "yellow" }' > -

I'm interactive now, >and I can use directives!

+

I'm interactive now, and I can use directives!

I'm also interactive, and I can also use directives!

@@ -776,7 +776,7 @@ Actions are just regular JavaScript functions. Usually triggered by the `data-wp ```ts const { state, actions } = store("myPlugin", { actions: { - selectItem: (id?: number) => { + selectItem: ( id ) => { const context = getContext(); // `id` is optional here, so this action can be used in a directive. state.selected = id || context.id; @@ -1152,7 +1152,7 @@ store('mySliderPlugin', { ## Server functions -The Interactivity API comes with handy functions on the PHP part. Apart from [setting the store via server](#on-the-server-side), there is also a function to get and set Interactivity related config variables. +The Interactivity API comes with handy functions that allow you to initialize and reference configuration options on the server. This is necessary to feed the initial data that the Server Directive Processing will use to modify the HTML markup before it's send to the browser. It is also a great way to leverage many of WordPress's APIs, like nonces, AJAX, and translations. ### wp_interactivity_config @@ -1181,6 +1181,53 @@ This config can be retrieved on the client: const { showLikeButton } = getConfig(); ``` +### wp_interactivity_state + +`wp_interactivity_state` allows the initialization of the global state on the server, which will be used to process the directives on the server and then will be merged with any global state defined in the client. + +Initializing the global state on the server also allows you to use many critical WordPress APIs, including [AJAX](https://developer.wordpress.org/plugins/javascript/ajax/), or [nonces](https://developer.wordpress.org/plugins/javascript/enqueuing/#nonce). + +The `wp_interactivity_state` function receives two arguments, a string with the namespace that will be used as a reference and an associative array containing the values. + +Here is an example of passing the WP Admin AJAX endpoint with a nonce. + +```php +// render.php + +wp_interactivity_state( + 'myPlugin', + array( + 'ajaxUrl' => admin_url( 'admin-ajax.php' ), + 'nonce' => wp_create_nonce( 'myPlugin_nonce' ), + ), +); +``` + +```js +// view.js + +const { state } = store( 'myPlugin', { + actions: { + *doSomething() { + try { + const formData = new FormData(); + formData.append( 'action', 'do_something' ); + formData.append( '_ajax_nonce', state.nonce ); + + const data = yield fetch( state.ajaxUrl, { + method: 'POST', + body: formData, + } ).then( ( response ) => response.json() ); + console.log( 'Server data!', data ); + } catch ( e ) { + // Something went wrong! + } + }, + }, + } +); +``` + ### wp_interactivity_process_directives `wp_interactivity_process_directives` returns the updated HTML after the directives have been processed. diff --git a/docs/reference-guides/interactivity-api/core-concepts/README.md b/docs/reference-guides/interactivity-api/core-concepts/README.md new file mode 100644 index 00000000000000..f4e6891c4ff165 --- /dev/null +++ b/docs/reference-guides/interactivity-api/core-concepts/README.md @@ -0,0 +1,9 @@ +# Core Concepts + +This section provides some guides on important concepts and mental models related to Interactivity API development. Use the following links to learn more: + +1. **[The Reactive and Declarative mindset](/docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md):** This guide covers core concepts of reactivity and declarativeness, providing a foundation for effective use of the Interactivity API. + +2. **[Understanding global state, local context and derived state](/docs/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md):** The guide explains how to effectively use global state, local context, and derived state within the Interactivity API emphasizing the importance of choosing the appropriate state management technique based on the scope and requirements of your data. + +3. **[Server-side rendering: Processing directives on the server](/docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md):** The Interactivity API allows WordPress to use server-side rendering to create interactive and state-aware HTML, smoothly connected with client-side features while maintaining performance and SEO benefits. diff --git a/docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md b/docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md new file mode 100644 index 00000000000000..8c62bd82eaba90 --- /dev/null +++ b/docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md @@ -0,0 +1,491 @@ +# Server-side rendering: Processing directives on the server + +WordPress has always been built on the foundation of server-side rendering. Traditionally, when a user requests a WordPress page, the server processes the PHP code, queries the database, and generates the HTML markup that is sent to the browser. + +In recent years, modern JavaScript frameworks like Vue, React, or Svelte have revolutionized the way we build web applications. These frameworks provide reactive and declarative programming models that enable developers to create dynamic, interactive user interfaces with ease. + +However, when it comes to server-side rendering, these frameworks require a JavaScript-based server, such as NodeJS, to execute their code and generate the initial HTML. This means that PHP-based servers, like WordPress, cannot directly utilize these frameworks without sacrificing their native PHP rendering capabilities. This limitation poses a challenge for WordPress developers who want to leverage the power of reactive and declarative programming while still benefiting from WordPress's traditional server-side rendering strengths. The Interactivity API bridges this gap by bringing [reactive and declarative programming principles](/docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md) to WordPress without compromising its server-side rendering foundation. + +In this guide, we'll explore how the Interactivity API processes directives on the server, enabling WordPress to deliver interactive, state-aware HTML from the initial page load, while setting the stage for seamless client-side interactivity. + +## Processing the directives on the server + +The Interactivity API's Server Directive Processing capabilities enable WordPress to generate the initial HTML with the correct interactive state, providing a faster initial render. After the initial server-side render, the Interactivity API's client-side JavaScript takes over, enabling dynamic updates and interactions without requiring full page reloads. This approach combines the best of both worlds: the SEO and performance benefits of traditional WordPress server-side rendering, and the dynamic, reactive user interfaces offered by modern JavaScript frameworks. + +To understand how the Server Directive Processing works, let's start with an example where a list of fruits is rendered using the `data-wp-each` directive. + +The following are the necessary steps to ensure that the directives are correctly processed by the Server Directive Processing of the Interactivity API during the server-side rendering of WordPress. + +- **1. Mark the block as interactive** + + First, to enable the server processing of the interactive block's directives, you must add `supports.interactivity` to the `block.json`: + + ```json + { + "supports": { + "interactivity": true + } + } + ``` + +- **2. Initialize the global state or local context** + + Then, you must initialize either the global state or the local context that will be used during the server-side rendering of the page. + + If you are using global state, you must use the `wp_interactivity_state` function: + + ```php + wp_interactivity_state( 'myFruitPlugin', array( + 'fruits' => array( 'Apple', 'Banana', 'Cherry' ) + )); + ``` + + If you are using local context, the initial values are defined with the `data-wp-context` directive itself, either by: + + - Adding it directly to the HTML. + + ```html + + ``` + + - Using the `wp_interactivity_data_wp_context` helper. + + ```php + array( 'Apple', 'Banana', 'Cherry' ) ); + ?> + + + ``` + +- **3. Define the interactive elements using directives** + + Next, you need to add the necessary directives to the HTML markup. + + ```html + + ``` + + In this example: + + - The `data-wp-interactive` directive activates the interactivity for the DOM element and its children. + - The `data-wp-each` directive is used to render a list of elements. The directive can be used in `