ideasonpurpose / wp-theme-addons
WordPress Block Editor add-ons — JavaScript blocks, utilities, and PHP components
Package info
github.com/ideasonpurpose/wp-theme-addons
Language:JavaScript
pkg:composer/ideasonpurpose/wp-theme-addons
Requires
None
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Version 0.5.1
This repository contains JavaScript and PHP add-ons for the WordPress Block Editor and Hybrid themes. The project is used in production, but is under active development and implementations are likely to change.
What's in here
Block Variations
Linked Group Block
A variation on the Group block which adds standard Link controls. The link implementation uses ideas from Accessible cards and Inclusive Components: Cards.
new LinkedGroup() wraps the core/group render callback and, when the variation has a URL, appends an empty overlay link inside the group. The stretch-link rules live in editor/Block/Variation/Group/LinkedGroup/linked-group.css. The editor script imports that file. PHP reads the same file and inlines it on the iop-linked-group handle from wp_enqueue_scripts, so the rules print in the head. No theme copy is required.
Related Posts Query
A variation on the Query Loop block which replaces the query with ranked related posts. Ranking lives in lib/RelatedPosts (IdeasOnPurpose\WP\RelatedPosts) — weighted shared taxonomies, post type, and recency, with optional REST at GET /wp-json/ideasonpurpose/v1/related_posts/{id} (see PHP usage to enable it).
Carousel
Three core/group variations — Carousel, Viewport, and Container — plus a front-end module. Any direct child of the container is a slide (cover, group, a pattern, or the items of a query loop). The editor shows the slides for editing and does not autoplay. The front end uses Embla Carousel 9.
Namespaces and classes:
| Piece | Block | Namespace | Class |
|---|---|---|---|
| Carousel | core/group |
ideasonpurpose/carousel |
iop-carousel |
| Viewport | core/group |
ideasonpurpose/carousel-viewport |
iop-carousel__viewport |
| Container | core/group |
ideasonpurpose/carousel-container |
iop-carousel__container |
| Slide | any direct child | — | iop-carousel__slide is added in the browser if missing |
Viewport and Container are hidden from the inserter. Insert Carousel; it starts with a viewport, a container, and two group slides. Replace those slides with whatever the site needs. For a query loop, put the loop inside the viewport and add iop-carousel__container to the post template. Each post item is then a slide.
Settings live on the Carousel variation and are copied to data attributes when PHP renders the block. The saved group markup is unchanged. Omitted attributes use the defaults below.
| Block attribute | Data attribute | Default |
|---|---|---|
carouselAutoplay |
data-autoplay |
true |
carouselDuration |
data-duration |
6 (seconds) |
carouselArrows |
data-arrows |
true |
carouselDots |
data-dots |
true |
carouselPause |
data-pause |
false |
carouselLoop |
data-loop |
true |
carouselRandom |
data-random |
0 (keep every slide) |
carouselRandom greater than 0 keeps that many slides, chosen in the browser on each visit, and removes the rest before Embla starts. That still varies when the HTML is served from a page cache.
A slide can set its own slideDuration (seconds) in the inspector. It is saved as data-slide-duration on that block and overrides carouselDuration for that slide only.
Arrow clicks and dot clicks both restart the autoplay timer. carouselPause adds a pause button that stops and resumes it. The button is off by default; an autoplaying carousel needs it to meet WCAG 2.2.2. It sits on its own, outside the pagination row. Autoplay does not start when prefers-reduced-motion: reduce is set, while the pointer is over the carousel, or while the carousel is off screen. Arrow keys move only the carousel that contains the focus, and they leave text fields alone.
Look is custom properties on .iop-carousel. Override these in the theme; the structural selectors can stay alone.
| Property | Default | Use |
|---|---|---|
--carousel-max-width |
none |
Viewport max width |
--carousel-arrow-size |
2.75rem |
Previous / next hit target |
--carousel-arrow-icon-size |
1.25rem |
Icon inside the arrow |
--carousel-arrow-offset |
0.75rem |
Inset from the sides |
--carousel-arrow-color |
currentColor |
Icon color |
--carousel-arrow-bg |
translucent Canvas |
Arrow and pause fill |
--carousel-arrow-radius |
999px |
Arrow and pause radius |
--carousel-arrow-shadow |
none |
Arrow and pause shadow |
--carousel-arrow-prev |
chevron | mask-image for the previous icon |
--carousel-arrow-next |
chevron | mask-image for the next icon |
--carousel-pause-icon |
pause bars | Pause icon |
--carousel-play-icon |
triangle | Play icon |
--carousel-pause-size |
2.25rem |
Pause button |
--carousel-pause-inset |
auto 1rem 1rem auto |
Pause position (inset shorthand) |
--carousel-dot-width |
0.625rem |
Pagination mark |
--carousel-dot-height |
0.625rem |
Pagination mark |
--carousel-dot-radius |
999px |
0 makes bars |
--carousel-dot-gap |
0.5rem |
Space between marks |
--carousel-dot-color |
translucent currentColor |
Inactive mark |
--carousel-dot-active-color |
currentColor |
Active mark and hover |
--carousel-controls-offset |
1rem |
Distance from the bottom |
--carousel-controls-justify |
center |
flex-start for left aligned |
--carousel-controls-padding |
1rem |
Inline padding of the control row |
Embla's class-names plugin adds is-snapped and is-in-view on slides. Use those for motion that should wait until a slide is current. The package does not ship a slide-content animation.
Bars instead of dots, for example:
.iop-carousel { --carousel-dot-width: 1.5rem; --carousel-dot-height: 3px; --carousel-dot-radius: 0; --carousel-dot-color: #fff; --carousel-dot-active-color: var(--wp--preset--color--accent); --carousel-controls-justify: flex-start; --carousel-arrow-prev: var(--i-arrow-prev); --carousel-arrow-next: var(--i-arrow-next); }
An example slide pattern a theme can register. The carousel structure comes from the variation, so the pattern is only the slide:
<?php /** * Title: Carousel slide * Slug: theme/carousel-slide * Inserter: true */ ?> <!-- wp:group {"className":"iop-carousel__slide"} --> <div class="wp-block-group iop-carousel__slide"> <!-- wp:heading {"level":2} --> <h2 class="wp-block-heading">Slide title</h2> <!-- /wp:heading --> <!-- wp:paragraph --> <p>Slide text.</p> <!-- /wp:paragraph --> </div> <!-- /wp:group -->
A carousel inserted from the variation is a section with no alignment and no color. Set those on the block, or in the theme pattern that wraps it.
Block Extensions
Button Icons
This extension adds an icon-picker to the core/button block. Markup is unchanged, icons are specified by adding classes. Classes are added in the Block Editor as well as the front end, so authors can work with a true representation of the final button.
import { initButtonIconPicker } from "@ideasonpurpose/wp-theme-addons"; initButtonIconPicker( [ { label: "Arrow Right", value: "arrow-right" }, { label: "Mail", value: "mail" }, { label: "Download", value: "download" }, ], "arrow-right", // optional default icon, defaults to "" );
Icons are displayed using CSS in the theme. Each icon maps to a mask variable the theme defines:
.wp-block-button.iop-button-icon.icon-arrow-right .wp-block-button__link::before { mask-image: var(--i-arrow-right); }
CSS Local Props
Injects block color attributes as CSS custom properties (--local-text-color, --local-bg-color, --local-border-color) so theme styles can use them.
This feature includes a pair of front-end and block editor files:
| File | Runtime | Role |
|---|---|---|
CssLocalProps/CssLocalProps.php |
PHP (frontend + editor bootstrap) | On render_block, writes the local props onto the outer wrapper tag. On enqueue_block_editor_assets, localizes the allowed-block list to window.iopLocalProps. |
CssLocalProps/css-local-props.js |
Block editor | Higher-order component on editor.BlockListBlock that injects the same vars into wrapperProps.style for live editor preview. |
Named colors from theme.json are converted to var(--wp--preset--color--*); custom hex/rgb values pass through as-is.
By default only core/button is targeted. Change the list from PHP:
add_filter('iop/add_css_local_props_allowed_blocks', fn() => ['core/button', 'core/group']);
Both sides must stay in sync: enable PHP for frontend output and call initCssLocalProps() in the editor bundle so the canvas matches the saved markup.
The PHP block list is localized to the script handle {stylesheet}-editor (from get_stylesheet()). If the theme's editor script uses a different handle, or is enqueued after enqueue_block_editor_assets priority 10, the editor falls back to core/button. Pass the list to initCssLocalProps(['core/button', 'core/group']) directly in that case.
Utilities
A few utility hooks are exported. usePublicPostTypes and usePublicTaxonomies are direct lifts from the WordPress Gutenberg source code. These functions are useful for pre-populating a WordPress data-store with all PostType and Taxonomy data for use in interfaces or block rendering.
Installation
Prerequisites
- SSH access to GitHub configured (your SSH key must be added to your GitHub account)
- You or the consuming project must have access to this private repository
npm
npm install @ideasonpurpose/wp-theme-addons
Or in package.json:
{
"dependencies": {
"@ideasonpurpose/wp-theme-addons": "^0.5.1"
}
}
Composer
Add the VCS repository and require the package in your project's composer.json:
{
"repositories": [
{
"type": "vcs",
"url": "git@github.com:ideasonpurpose/wp-theme-addons.git"
}
],
"require": {
"ideasonpurpose/wp-theme-addons": "dev-main"
}
}
Usage
JavaScript
Import into editor.js. Minimal required styles are bundled with the JS:
// @link https://github.com/ideasonpurpose/wp-theme-addons import { initButtonIconPicker, initCarouselBlock, initCssLocalProps, initLinkedGroupBlock, initRelatedPostsQueryBlock, } from "@ideasonpurpose/wp-theme-addons"; initLinkedGroupBlock(); initRelatedPostsQueryBlock(); initCarouselBlock(); initCssLocalProps(); initButtonIconPicker([...]);
Call initCarouselBlock() while the editor script evaluates, same as the other inits. The import pulls carousel.css into the editor bundle. Autoplay does not run in the editor.
Front end, in main.js. This entry is separate so the editor bundle does not load Embla:
import { initCarousels } from "@ideasonpurpose/wp-theme-addons/carousel"; initCarousels();
Embla and its accessibility, autoplay, and class-names plugins are dependencies of this package, pinned to the 9.0.0 release candidate (9.0.0-rc04) because the carousel uses the v9 API. initCarousels() waits for DOMContentLoaded if the document is still loading.
The package ships untranspiled source: .js files contain JSX and import .scss files. The theme's build must transpile JSX and compile Sass for this package inside node_modules. @wordpress/* packages are expected to be provided as externals by the theme's build (for example @wordpress/scripts).
PHP
use IdeasOnPurpose\WP\RelatedPosts; use IdeasOnPurpose\WP\Theme\Addons\Block\Variation\Group\Carousel\Carousel; use IdeasOnPurpose\WP\Theme\Addons\Block\Variation\Group\LinkedGroup\LinkedGroup; use IdeasOnPurpose\WP\Theme\Addons\Block\Variation\Query\RelatedPostsQuery\RelatedPostsQuery; use IdeasOnPurpose\WP\Theme\Addons\CssLocalProps\CssLocalProps; new LinkedGroup(); new Carousel(); // inlines carousel.css and writes data-* settings new RelatedPostsQuery(); // uses RelatedPosts for ranking new CssLocalProps(); // Optional: enables the REST endpoint. Must run before `rest_api_init`, e.g. in functions.php new RelatedPosts(); // Optional: use the ranker directly // $posts = (new RelatedPosts())->get(['post' => $id, 'posts_per_page' => 4]);
PHP components require WordPress 6.2 or later (WP_HTML_Tag_Processor).
Coexistence
npm and Composer operate independently in the same repository:
| npm | Composer | |
|---|---|---|
| Config | package.json |
composer.json |
| Package name | @ideasonpurpose/wp-theme-addons |
ideasonpurpose/wp-theme-addons |
| Installs to | node_modules/ |
vendor/ |
| Serves | JS + SCSS | PHP |
| Imports resolve via | npm package name | PSR-4 autoloading |
No conflicts: separate config files, separate dependency directories, separate language ecosystems.
graph TD
subgraph REPO["Single Git Repository: ideasonpurpose/wp-theme-addons"]
PJ[package.json]
CJ[composer.json]
JS[JS + SCSS files]
PHP[PHP files]
end
subgraph NPM_CONSUMER["npm Consumer Project"]
NPJ[package.json]
NM[node_modules/]
end
subgraph COMPOSER_CONSUMER["Composer Consumer Project"]
CPJ[composer.json]
VD[vendor/]
end
NPJ -- "npm install" --> PJ
PJ -- "resolves to" --> NM
JS -- "import from" --> NM
CPJ -- "composer require" --> CJ
CJ -- "resolves to" --> VD
PHP -- "PSR-4 autoload" --> VD
Loading
- npm reads
package.json→ installs tonode_modules/→ JS/SCSS imports resolve via@ideasonpurpose/wp-theme-addons - Composer reads
composer.json→ installs tovendor/→ PHP classes autoload via PSR-4 - No conflicts: separate config files, separate dependency directories, separate language ecosystems.
Brought to you by IOP
| This project is actively developed and used in production at Ideas On Purpose. |
|---|