Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions IMPROVEMENT_PLAN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# Credits Shortcode & Block improvement plan

Start with a small reliability release, follow with improvements to everyday editing and styling, then add grouped credits. Keep existing shortcodes, saved block attributes, and site-wide settings compatible throughout.

The initial review was completed on September 18, 2026 against version 1.5.0. The local suite passed with 38 tests and 162 assertions on PHP 8.5.10. Those tests use WordPress stubs; a live WordPress editor and theme compatibility check is still needed.

| Order | Work | Expected outcome |
| --- | --- | --- |
| 1 | Fix block registration and rendering inconsistencies | Editor settings and published output behave consistently. |
| 2 | Add WordPress integration coverage | Tests catch failures caused by real WordPress behavior. |
| 3 | Improve link entry and default controls | Authors can add valid credits with fewer steps. |
| 4 | Improve styling and accessibility | Credits fit different themes, devices, and input methods. |
| 5 | Finish performance, documentation, and release checks | The release is accurate, lightweight, and installable. |
| 6 | Build a grouped credits block | Authors can manage several references together. |

1. **Fix the confirmed editor and rendering issues.**

- [x] Correct the block API version passed from PHP to JavaScript. ~~WordPress localization converts the number `3` to the string `"3"`, which currently fails the strict JavaScript comparison and selects API version 1. Normalize the value or pass typed configuration using `wp_add_inline_script()` and `wp_json_encode()`.~~ Done as of 1.6.0: `apiVersion: 3` is hardcoded in both `block.json` and `js/credits-block.js` rather than passed through localization, so the string/number mismatch this bullet describes cannot occur. Regression test: `tests/test_settings.php` asserts `block_api_version` is never localized.
- [ ] ~~Retain the older WordPress registration fallback~~ Superseded by a 1.6.0 decision: the legacy Block API version 1 fallback was removed outright instead of retained (see `readme.txt` changelog, 1.6.0). Flagging the mismatch with this bullet rather than resolving it — reintroducing a fallback is a product decision, not a bug fix.
- [x] Preserve a block's custom CSS classes in published output. Implemented via `credits_get_block_wrapper_class()` using `get_block_wrapper_attributes()` (WP 5.6+) with a `className`-attribute fallback for older WordPress; see `credits_shortcode.php`.
- [x] Keep shortcode rendering independent of the active block's wrapper context. `credits_print_shortcode()` only receives a wrapper class when called from `credits_render_block()`; direct shortcode calls never see it (see `test_shortcode_rendering_is_independent_of_block_wrapper_context`). The HTML allowlist needed no change — `ul.class` was already permitted and only additional class tokens are added, never new attributes.
- [x] Add focused regression coverage for API version selection and custom class preservation. API version: `tests/test_settings.php`. Custom class preservation: new tests in `tests/test_renderer.php` (duplicate-class, multi-class merge, hostile-input sanitization, and shortcode/block parity checks).

Acceptance: modern WordPress registers the block with API version 3 on both sides; the legacy path still works; a custom class entered in the editor appears on the front end; existing shortcode output remains compatible.

Main files: `credits_shortcode.php`, `js/credits-block.js`, `tests/bootstrap.php`, and the renderer/settings tests.

2. **Add tests that run against actual WordPress.**

- [ ] Keep the fast unit suite and add a separate WordPress integration suite.
- [ ] Exercise real script localization, block registration, `do_shortcode()`, and `render_block()` rather than only direct calls to the renderer.
- [ ] Cover site defaults, explicit overrides, custom classes, and representative unsafe URL, text, and color inputs using WordPress's own sanitizers.
- [ ] Add an editor smoke test: insert a credit, edit its values, save, reload, and verify the published output.
- [ ] Test representative older and current supported WordPress versions using compatible PHP versions. Add PHP 8.5 to CI after confirming dependency compatibility.
- [ ] Document how contributors run both suites and the editor check.

Acceptance: the integration suite detects the API version issue from step 1 when that fix is reverted. Saving and reloading a block retains its name, URL, type, colors, spacing, and custom class.

Main files: `tests/`, `.github/workflows/ci.yml`, `composer.json`, and PHPUnit configuration.

3. **Make individual credits easier to edit.**

- [ ] Add inline name and URL editing to the block, while retaining sidebar controls for appearance.
- [ ] Show an instructional empty state and clear feedback for missing or invalid URLs. Avoid presenting an untouched credit as a finished link.
- [ ] Define and test incomplete-credit rendering before changing it. Preserve existing valid links and intentionally used fragment links; distinguish the editor placeholder from saved content.
- [ ] Add an "Open in new tab" control to blocks and shortcodes. Preserve the existing new-tab behavior when the new attribute is absent, and retain appropriate link security attributes.
- [ ] Add "Use site default" to the credit-type selector so an explicit Source/Via override can be cleared.
- [ ] Make inherited colors and per-credit overrides understandable, with a clear reset-to-default action.
- [ ] Replace the Classic Editor's sequence of browser prompts with one form containing type, name, and URL. Prefill the name from selected text and use the same validation expectations as the block.
- [ ] Ensure inserted shortcode values cannot break out of shortcode syntax or become unintended editor HTML.
- [ ] Translate all new strings and verify that they load in both editors.

Acceptance: an author can create a valid credit directly in the block, identify an incomplete link before publishing, reset the type to the site default, and choose link-opening behavior. Existing saved credits keep their behavior. The Classic Editor supports keyboard entry, cancellation, and safe insertion.

Main files: `js/credits-block.js`, `credits_shortcode_plugin.js`, `credits_shortcode.php`, and `block.json`.

4. **Improve theme compatibility and accessibility.**

- [ ] Replace unnecessary `!important` rules with scoped styles and CSS variables for colors and spacing. Retain targeted legacy rules where a compatibility check demonstrates they are needed.
- [ ] Allow theme typography and container layout to influence the credit without losing its compact badge presentation.
- [ ] Handle long names and unbroken text on narrow screens without horizontal overflow.
- [ ] Use logical alignment, spacing, and corner rules for right-to-left layouts.
- [ ] Add visible keyboard focus styles and ensure they are not clipped by the badge container.
- [ ] Respect `prefers-reduced-motion` for hover movement and transitions.
- [ ] Check default and inherited color combinations in light and dark themes; add useful contrast feedback for custom colors where practical.
- [ ] Associate settings-page labels with their controls using stable IDs and Settings API label configuration.
- [ ] Verify editor/front-end consistency in a classic theme and a block theme, including narrow layouts, 200% zoom, and keyboard navigation.

Acceptance: credits remain readable and operable across the checked themes and layouts, long text does not overflow, RTL presentation is coherent, and site owners can customize appearance without competing with broad overrides.

Main files: `css/style.css`, settings markup in `credits_shortcode.php`, and editor controls.

5. **Complete performance and release polish.**

- [ ] Replace unconditional front-end CSS loading with a loading strategy that covers blocks and shortcodes, including widgets, templates, reusable content, and programmatic rendering. Avoid relying solely on scanning the current post.
- [ ] Verify that styles arrive in time to prevent unstyled credits. Keep the change separate if reliable loading across the supported environments needs further work.
- [ ] Update the README's old color defaults and outdated test count. Use a real CI status badge.
- [ ] Document site defaults, override precedence, link-opening behavior, empty-link behavior, and the updated Classic Editor workflow.
- [ ] Refresh screenshots after the UI changes are stable.
- [ ] Keep plugin headers, block metadata, changelogs, and release versions consistent. Set "Tested up to" from completed compatibility checks.
- [ ] Exclude this plan and other development-only files from the release package.
- [ ] Verify a clean packaged installation, an upgrade from 1.5.0, settings persistence, and deactivation/reactivation behavior.

Acceptance: pages without credits avoid unnecessary plugin CSS where the supported loading strategy allows it; all credit locations remain styled; the installation package and documentation match the shipped behavior.

Main files: `credits_shortcode.php`, `README.md`, `readme.txt`, `.distignore`, `.github/workflows/ci.yml`, and release assets.

6. **Add grouped credits as a separate feature release.**

- [ ] Introduce a new parent Credits Group block that contains existing Credits Link blocks, preserving the individual block and shortcode formats.
- [ ] Provide add, remove, and reorder controls for references.
- [ ] Add shared appearance and spacing controls. Define inheritance explicitly: individual override, then group setting, then site default.
- [ ] Use accessible group/list markup and avoid applying individual outer margins between every grouped item.
- [ ] Add an explicit way to group selected existing credit blocks without changing their names or URLs.
- [ ] Cover saving, reloading, reordering, inheritance, and responsive rendering in the editor and integration checks.

Acceptance: authors can maintain several references as one unit, retain per-credit exceptions, and group existing credits without losing attribution data. Individual credits continue to work independently.

Ship steps 1–2 as the first reliability milestone. Ship steps 3–5 as the usability milestone once editor and theme checks pass. Begin step 6 after those changes are stable. Avoid coupling the fixes to a broad PHP rewrite or a new JavaScript build system.

Implementation references: [WordPress script localization](https://developer.wordpress.org/reference/classes/wp_scripts/localize/), [dynamic block wrappers](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper/), and [block supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/).
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

[![WordPress](https://img.shields.io/badge/WordPress-6.3%2B-blue.svg)](https://wordpress.org)
[![PHP](https://img.shields.io/badge/PHP-7.4%2B-purple.svg)](https://php.net)
[![Version](https://img.shields.io/badge/version-1.6.0-green.svg)](https://github.com/jashjacob/Credits-Shortcode-Plugin-for-Wordpress)
[![Version](https://img.shields.io/badge/version-1.6.1-green.svg)](https://github.com/jashjacob/Credits-Shortcode-Plugin-for-Wordpress)
[![License](https://img.shields.io/badge/license-GPLv2-orange.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-PHPUnit%20%7C%20CI-brightgreen.svg)](.github/workflows/) <!-- TODO: replace with real CI status badge once the workflow runs on a public CI service -->

Expand Down Expand Up @@ -187,6 +187,9 @@ The plugin is translation-ready via the `credits-shortcode` text domain. If you'

## 📜 Changelog

### Version 1.6.1
- Fixed the Gutenberg block dropping a custom CSS class added in the editor's Advanced panel from the published output.

### Version 1.6.0
- Requires WordPress 6.3 or newer.
- Registers the Gutenberg block with Block API version 3 consistently.
Expand Down
2 changes: 1 addition & 1 deletion block.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "credits/shortcode",
"version": "1.6.0",
"version": "1.6.1",
"title": "Credits Link",
"category": "widgets",
"icon": "share",
Expand Down
73 changes: 66 additions & 7 deletions credits_shortcode.php
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?php
/*
Plugin Name: Credits Shortcode & Block
Version: 1.6.0
Version: 1.6.1
Plugin URI: https://github.com/jashjacob/Credits-Shortcode-Plugin-for-Wordpress
Description: Add clean Source and Via attribution links with a Gutenberg block, shortcode, or Classic Editor button.
Author: Jash Jacob
Expand Down Expand Up @@ -36,7 +36,7 @@
}

if ( ! defined( 'CREDITS_SHORTCODE_VERSION' ) ) {
define( 'CREDITS_SHORTCODE_VERSION', '1.6.0' );
define( 'CREDITS_SHORTCODE_VERSION', '1.6.1' );
}

/**
Expand Down Expand Up @@ -98,6 +98,31 @@ function credits_sanitize_color( $color ) {
return is_string( $hex ) ? $hex : '';
}

/**
* Turn a space-separated class list into sanitized, deduplicated class tokens.
*
* @param string $class_list Raw class names, space separated.
* @return string[] Sanitized class names, empty tokens removed.
*/
function credits_sanitize_class_list( $class_list ) {
$class_list = trim( credits_string_attr( $class_list ) );
if ( '' === $class_list ) {
return array();
}

$classes = array();
foreach ( preg_split( '/\s+/', $class_list ) as $class_name ) {
$sanitized = function_exists( 'sanitize_html_class' )
? sanitize_html_class( $class_name )
: preg_replace( '/[^A-Za-z0-9_-]/', '', $class_name );
if ( '' !== $sanitized ) {
$classes[] = $sanitized;
}
}

return $classes;
}

/**
* Sanitize a credit type value against the allowlist.
*
Expand Down Expand Up @@ -271,11 +296,14 @@ function credits_load_textdomain() {
* Sanitize/validate first. Escape only when a value is concatenated into HTML,
* using the function that matches that context.
*
* @param array $atts Shortcode or block attributes.
* @param string|null $content Optional shortcode inner content (the name).
* @param array $atts Shortcode or block attributes.
* @param string|null $content Optional shortcode inner content (the name).
* @param string $wrapper_class Extra wrapper class(es) from the active block context.
* Never populated for shortcode calls, so shortcode
* output stays independent of any block wrapper.
* @return string
*/
function credits_print_shortcode( $atts, $content = null ) {
function credits_print_shortcode( $atts, $content = null, $wrapper_class = '' ) {
if ( ! is_array( $atts ) ) {
$atts = array();
}
Expand Down Expand Up @@ -335,7 +363,12 @@ function credits_print_shortcode( $atts, $content = null ) {
$link_text_clr = $settings['link_text_color'];
}

$html = '<ul class="credits wp-block-credits-shortcode credits-spacing-' . esc_attr( $spacing ) . '">';
$wrapper_classes = array_merge(
array( 'credits', 'wp-block-credits-shortcode', 'credits-spacing-' . $spacing ),
credits_sanitize_class_list( $wrapper_class )
);

$html = '<ul class="' . esc_attr( implode( ' ', $wrapper_classes ) ) . '">';
$html .= '<li class="credits">';
$html .= '<span class="cre_cate"';
if ( '' !== $badge_bg ) {
Expand All @@ -359,14 +392,40 @@ function credits_print_shortcode( $atts, $content = null ) {

add_shortcode( 'credits', 'credits_print_shortcode' );

/**
* Read any custom CSS class the author added in the block's Advanced panel.
*
* Prefers get_block_wrapper_attributes() (WP 5.6+) so classes added by core
* block supports (not just the saved "className" attribute) are preserved;
* falls back to the raw attribute on older WordPress. The block's own
* default "wp-block-credits-shortcode" class is stripped since the renderer
* already adds it, avoiding a duplicate.
*
* @param array $attributes Block attributes.
* @return string Extra class(es), space separated.
*/
function credits_get_block_wrapper_class( $attributes ) {
if ( function_exists( 'get_block_wrapper_attributes' ) ) {
$wrapper_attributes = get_block_wrapper_attributes();
if ( is_string( $wrapper_attributes ) && preg_match( '/\bclass="([^"]*)"/', $wrapper_attributes, $matches ) ) {
$classes = array_diff( credits_sanitize_class_list( $matches[1] ), array( 'wp-block-credits-shortcode' ) );
return implode( ' ', $classes );
}
return '';
}

return isset( $attributes['className'] ) ? credits_string_attr( $attributes['className'] ) : '';
}

/**
* Block render callback. Pass attributes only so inner block HTML is not treated as the name.
*
* @param array $attributes Block attributes.
* @return string
*/
function credits_render_block( $attributes ) {
return credits_print_shortcode( is_array( $attributes ) ? $attributes : array() );
$attributes = is_array( $attributes ) ? $attributes : array();
return credits_print_shortcode( $attributes, null, credits_get_block_wrapper_class( $attributes ) );
}

/**
Expand Down
5 changes: 4 additions & 1 deletion readme.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Donate link: https://jashjacob.com
Tags: attribution, source, credits, block, shortcode
Requires at least: 6.3
Tested up to: 7.1
Stable tag: 1.6.0
Stable tag: 1.6.1
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Expand Down Expand Up @@ -114,6 +114,9 @@ Yes. When the Classic Editor is active, an Add Credits toolbar button inserts th

== Changelog ==

= 1.6.1 =
* Fixed the Gutenberg block dropping a custom CSS class added in the editor's Advanced panel from the published output.

= 1.6.0 =
* Requires WordPress 6.3 or newer.
* Registers the Gutenberg block with Block API version 3 consistently.
Expand Down
22 changes: 22 additions & 0 deletions tests/bootstrap.php
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,21 @@ function register_block_type_from_metadata( $file_or_folder, $args = array() ) {
}
}

if ( ! function_exists( 'get_block_wrapper_attributes' ) ) {
/**
* WP 5.6+. Return value is controlled per test via
* $GLOBALS['credits_test_block_wrapper_attributes'] so both a bare
* default class and one carrying an editor-added custom class can be
* exercised without needing a full block-rendering context.
*/
function get_block_wrapper_attributes( $extra_attributes = array() ) {
if ( array_key_exists( 'credits_test_block_wrapper_attributes', $GLOBALS ) ) {
return $GLOBALS['credits_test_block_wrapper_attributes'];
}
return 'class="wp-block-credits-shortcode"';
}
}

if ( ! function_exists( 'wp_register_script' ) ) {
function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false ) {
return true;
Expand Down Expand Up @@ -260,6 +275,13 @@ function wp_add_inline_script( $handle, $data, $position = 'after' ) {
* Sanitization
* ---------------------------------------------------------------------- */

if ( ! function_exists( 'sanitize_html_class' ) ) {
function sanitize_html_class( $class, $fallback = '' ) {
$sanitized = preg_replace( '/[^A-Za-z0-9_-]/', '', (string) $class );
return '' !== $sanitized ? $sanitized : $fallback;
}
}

if ( ! function_exists( 'sanitize_key' ) ) {
function sanitize_key( $key ) {
return preg_replace( '/[^a-z0-9_\-]/', '', strtolower( (string) $key ) );
Expand Down
Loading
Loading