@ideasonpurpose/wp-theme-addons 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # WordPress Theme Addons
2
2
 
3
- #### Version 0.4.0
3
+ #### Version 0.4.1
4
4
 
5
5
  [![NPM Version](https://img.shields.io/npm/v/%40ideasonpurpose%2Fwp-theme-addons?logo=npm)](https://www.npmjs.com/package/@ideasonpurpose/wp-theme-addons)
6
6
  [![Packagist](https://badgen.net/packagist/v/ideasonpurpose/wp-theme-addons)](https://packagist.org/packages/ideasonpurpose/wp-theme-addons)
@@ -15,9 +15,11 @@ This repository contains JavaScript and PHP add-ons for the WordPress Block Edit
15
15
 
16
16
  A variation on the Group block which adds standard Link controls. The link implementation uses ideas from [Accessible cards](https://kittygiraudel.com/2022/04/02/accessible-cards/) and [Inclusive Components: Cards](https://inclusive-components.design/cards/).
17
17
 
18
+ `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.
19
+
18
20
  #### Related Posts Query
19
21
 
20
- 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}`.
22
+ 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](#php) to enable it).
21
23
 
22
24
  ### Block Extensions
23
25
 
@@ -50,7 +52,7 @@ Icons are displayed using CSS in the theme. Each icon maps to a mask variable th
50
52
 
51
53
  Injects block color attributes as CSS custom properties (`--local-text-color`, `--local-bg-color`, `--local-border-color`) so theme styles can use them.
52
54
 
53
- This feature include a pair of front-end and block editor files:
55
+ This feature includes a pair of front-end and block editor files:
54
56
 
55
57
  | File | Runtime | Role |
56
58
  | ---------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -67,9 +69,11 @@ add_filter('iop/add_css_local_props_allowed_blocks', fn() => ['core/button', 'co
67
69
 
68
70
  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.
69
71
 
72
+ 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.
73
+
70
74
  ### Utilities
71
75
 
72
- A few utility classes are exported. `usePublicPostTypes` and `usePublicTaxonomies` are direct lifts from the [WordPress Gutenberg source code](https://github.com/WordPress/gutenberg/blob/e90c88fee31120e0091e044c149f8b4f5f947f4a/packages/edit-site/src/components/add-new-template/utils.js#L91-L125). These functions are useful for pre-populating a WordPress data-store with all PostType and Taxonomy data for use in interfaces or block rendering.
76
+ A few utility hooks are exported. `usePublicPostTypes` and `usePublicTaxonomies` are direct lifts from the [WordPress Gutenberg source code](https://github.com/WordPress/gutenberg/blob/e90c88fee31120e0091e044c149f8b4f5f947f4a/packages/edit-site/src/components/add-new-template/utils.js#L91-L125). These functions are useful for pre-populating a WordPress data-store with all PostType and Taxonomy data for use in interfaces or block rendering.
73
77
 
74
78
  ## Installation
75
79
 
@@ -89,7 +93,7 @@ Or in `package.json`:
89
93
  ```json
90
94
  {
91
95
  "dependencies": {
92
- "@ideasonpurpose/wp-theme-addons": "^0.2.2"
96
+ "@ideasonpurpose/wp-theme-addons": "^0.4.1"
93
97
  }
94
98
  }
95
99
  ```
@@ -120,13 +124,21 @@ Import into **editor.js**. Minimal required styles are bundled with the JS:
120
124
 
121
125
  ```javascript
122
126
  // @link https://github.com/ideasonpurpose/wp-theme-addons
123
- import { initLinkedGroupBlock, initCssLocalProps, initButtonIconPicker } from "@ideasonpurpose/wp-theme-addons";
127
+ import {
128
+ initButtonIconPicker,
129
+ initCssLocalProps,
130
+ initLinkedGroupBlock,
131
+ initRelatedPostsQueryBlock,
132
+ } from "@ideasonpurpose/wp-theme-addons";
124
133
 
125
134
  initLinkedGroupBlock();
135
+ initRelatedPostsQueryBlock();
126
136
  initCssLocalProps();
127
137
  initButtonIconPicker([...]);
128
138
  ```
129
139
 
140
+ 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`).
141
+
130
142
  ### PHP
131
143
 
132
144
  ```php
@@ -136,13 +148,18 @@ use IdeasOnPurpose\WP\Theme\Addons\Block\Variation\Query\RelatedPostsQuery\Relat
136
148
  use IdeasOnPurpose\WP\Theme\Addons\CssLocalProps\CssLocalProps;
137
149
 
138
150
  new LinkedGroup();
139
- new RelatedPostsQuery(); // also loads RelatedPosts for ranking + REST
151
+ new RelatedPostsQuery(); // uses RelatedPosts for ranking
140
152
  new CssLocalProps();
141
153
 
154
+ // Optional: enables the REST endpoint. Must run before `rest_api_init`, e.g. in functions.php
155
+ new RelatedPosts();
156
+
142
157
  // Optional: use the ranker directly
143
158
  // $posts = (new RelatedPosts())->get(['post' => $id, 'posts_per_page' => 4]);
144
159
  ```
145
160
 
161
+ PHP components require WordPress 6.2 or later (`WP_HTML_Tag_Processor`).
162
+
146
163
  ## Coexistence
147
164
 
148
165
  npm and Composer operate independently in the same repository:
@@ -20,6 +20,7 @@ class LinkedGroup
20
20
  * Callbacks are per block, and cannot be specific to a single variation
21
21
  */
22
22
  add_filter('register_block_type_args', [$this, 'wrap_render_callback'], 10, 2);
23
+ add_action('wp_enqueue_scripts', [$this, 'enqueue_styles']);
23
24
  }
24
25
 
25
26
  public function wrap_render_callback($args, $block_type)
@@ -73,4 +74,26 @@ class LinkedGroup
73
74
 
74
75
  return $blockHTML;
75
76
  }
77
+
78
+ /**
79
+ * Inline the same CSS the editor imports. Construction is the opt-in,
80
+ * so this runs on wp_enqueue_scripts and prints in the head.
81
+ */
82
+ public function enqueue_styles()
83
+ {
84
+ static $done = false;
85
+ if ($done) {
86
+ return;
87
+ }
88
+ $done = true;
89
+
90
+ $css = file_get_contents(__DIR__ . '/linked-group.css');
91
+ if (!$css) {
92
+ return;
93
+ }
94
+
95
+ wp_register_style('iop-linked-group', false);
96
+ wp_add_inline_style('iop-linked-group', $css);
97
+ wp_enqueue_style('iop-linked-group');
98
+ }
76
99
  }
@@ -0,0 +1,22 @@
1
+ .iop-linked-group {
2
+ position: relative;
3
+ }
4
+
5
+ .iop-linked-group a.iop-linked-group__link {
6
+ position: absolute;
7
+ top: 0;
8
+ left: 0;
9
+ z-index: 10;
10
+
11
+ width: 100%;
12
+ max-width: 100%;
13
+ height: 100%;
14
+ margin: 0;
15
+ }
16
+
17
+ /* every clickable element in the group needs to be position:relative */
18
+ .iop-linked-group button,
19
+ .iop-linked-group a:not(.iop-linked-group__link) {
20
+ position: relative;
21
+ z-index: 20;
22
+ }
@@ -1,6 +1,6 @@
1
1
  // @ts-check
2
2
 
3
- import "./linked-group.scss";
3
+ import "./linked-group.css";
4
4
  import {
5
5
  BlockControls,
6
6
  InspectorControls,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ideasonpurpose/wp-theme-addons",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "WordPress Block Editor add-ons — JavaScript blocks, utilities, and PHP components",
5
5
  "keywords": [
6
6
  "wordpress",
@@ -60,6 +60,7 @@
60
60
  "version-everything": {
61
61
  "files": [
62
62
  "README.md"
63
- ]
63
+ ],
64
+ "prefix": "\"@ideasonpurpose/wp-theme-addons\": \"\\^"
64
65
  }
65
66
  }
@@ -1,22 +0,0 @@
1
- .iop-linked-group {
2
- position: relative;
3
-
4
- & a.iop-linked-group__link {
5
- position: absolute;
6
- top: 0;
7
- left: 0;
8
- z-index: 10;
9
-
10
- width: 100%;
11
- max-width: 100%;
12
- height: 100%;
13
- margin: 0;
14
- }
15
-
16
- /* every clickable element in the group needs to be position:relative */
17
- & button,
18
- & a:not(.iop-linked-group__link) {
19
- position: relative;
20
- z-index: 20;
21
- }
22
- }