feat: block doc navigation #231

sapayth · 2025-09-19T11:54:11Z

fixes #167

Show Previous Doc and Next Doc links at the bottom (or top) of a doc, helping users navigate between articles within the same section.

Summary by CodeRabbit

New Features
- Added Doc Navigation block: server-rendered previous/next links with rich editor controls for SEO rel, typography, colors, borders, spacing and arrow styling; responsive preview.
Style
- Bundled carousel styles into main CSS and added fallback styles for Doc Navigation when Tailwind is unavailable.
Chores
- Bumped build asset versions and updated bundles for cache-busting.
Refactor
- Modularized data layer/storage for improved editor/data stability.

coderabbitai · 2025-09-19T11:54:21Z

Walkthrough

Adds a server-rendered DocNavigation Gutenberg block (editor UI, styles, PHP renderer), registers it, modularizes the JavaScript data stores, updates build artifacts (webpack scaffolding, inlined CSS), adds wp-data to block dependencies, and bumps several asset version hashes.

Changes

Cohort / File(s)	Summary of Changes
DocNavigation block (source & build) `src/blocks/DocNavigation/block.json`, `src/blocks/DocNavigation/edit.js`, `src/blocks/DocNavigation/index.js`, `src/blocks/DocNavigation/save.js`, `src/blocks/DocNavigation/style.scss`, `src/blocks/DocNavigation/render.php`, `assets/build/blocks/DocNavigation/block.json`, `assets/build/blocks/DocNavigation/render.php`, `assets/build/blocks/DocNavigation/*`	New dynamic block `wedocs/wedocs-doc-navigation`: manifest, editor component with InspectorControls, fallback SCSS, server-side render PHP, save() returns null; block registered and renderer loaded in plugin.
Plugin integration `wedocs.php`	Loads and registers the new DocNavigation block and its server render callback.
Doc navigation helpers `includes/functions.php`	Adds `wedocs_get_doc_navigation_posts( $post )` and refactors `wedocs_doc_nav()` to use it for next/prev doc resolution.
Data store modularization (source & build) `src/data/`, `src/data/docs/`, `src/data/settings/*`, `src/data/store.js`, `assets/build/store.js`, `assets/build/store.asset.php`	Replaces monolithic store bundle with modular docs and settings stores, exports named constants and default stores, and registers stores via a new entry; asset version bump.
Block asset dependency change `assets/build/block.asset.php`	Adds `wp-data` to block dependencies and updates version hash.
Webpack/runtime & CSS bundling changes (build) `assets/build/frontend.js`, `assets/build/print.js`, `assets/build/frontend.css`, `assets/build/print.css`, `assets/build/index.css`	Adds webpack runtime scaffolding for CSS entries, loader header comments, inlines carousel CSS into index.css, and appends sourceMap references; no runtime behavior changes beyond bundler wiring.
Asset manifest version bumps `assets/build/frontend.asset.php`, `assets/build/index.asset.php`, `assets/build/print.asset.php`, `assets/build/block.asset.php`, `assets/build/store.asset.php`	Updated version hashes for multiple build manifests; dependencies mostly unchanged except `block.asset.php`.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Add docs grid #203 — Refactors the plugin data layer to modular stores; overlaps with the store modularization in this PR.
Add Promotional Banner to weDocs Dashboard #209 — Adds/structures settings store modules; closely related to the new src/data/settings changes.

Suggested labels

QA Approved, Ready To Merge

Suggested reviewers

iftakharul-islam

Poem

"I nibble code and hop with delight,
New arrows point left and right.
Blocks blossom where pages meet,
Stores split neat like fresh spring wheat.
A whiskered cheer — docs now glide light!" 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The PR includes several changes that appear outside the stated objective of adding the DocNavigation block: most notably a large modularization of the built data store (assets/build/store.js with many new public exports) and numerous broad build-artifact changes (inlined carousel CSS, webpack runtime wrappers, and multiple asset version bumps). These architectural and generated-asset changes are not described in the linked issue and increase review surface and risk of unrelated regressions, so they appear out-of-scope for this feature PR. A focused feature PR should avoid bundling such large refactors or unrelated build noise without explicit justification.	Either split the store refactor and other large changes into a separate PR or add a clear justification and tests in this PR explaining why they are required for the DocNavigation block; if the build outputs are incidental, restrict the commit to source changes and include only the minimal regenerated assets necessary for the new block. Also run regression tests and document any public API changes introduced by the new store layout.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "feat: block doc navigation" is concise and accurately reflects the primary change — adding a document navigation Gutenberg block. It uses a conventional "feat" prefix and contains no extraneous detail, making it easy to scan in history. The title is specific enough for teammates to understand the main intention of the PR.
Linked Issues Check	✅ Passed	The PR implements a server-rendered block (src/blocks/DocNavigation and assets/build/blocks/DocNavigation), an Edit component with InspectorControls exposing extensive styling attributes, a save() that returns null, a PHP renderer (render_wedocs_doc_navigation) and block registration in wedocs.php, which together satisfy the linked issue's request to provide a Gutenberg block and relevant customization settings. The new wedocs_get_doc_navigation_posts() centralizes the prev/next logic and is used by the block renderer, aligning the code with the feature objective. Based on the provided diffs the block's attributes and editor controls cover the declared customization requirements from issue #167.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 9

🧹 Nitpick comments (24)

assets/build/index.asset.php (1)

1-1: Confirm React handles vs wp-element.

Deps list includes react and react-dom alongside wp-element. Verify supported WP versions register these handles; otherwise prefer externalizing to wp-element only to avoid duplication.
src/blocks/DocNavigation/edit.js (3)
82-90: Remove unused themeGradients; tighten selector payload.

themeGradients isn’t used; keep only what you need.

Apply:
-    const { themeColors, themeGradients } = useSelect((select) => {
+    const { themeColors } = useSelect((select) => {
         const editorSettings = select('core/block-editor').getSettings();
         return {
-            themeColors: editorSettings.colors,
-            themeGradients: editorSettings.gradients,
+            themeColors: editorSettings.colors,
         };
     });
53-59: Arrow margin should be directional (prev vs next).

Single margin string yields wrong spacing on the next arrow. Compute per‑direction margins.

Apply:
-        const arrowStyle = {
+        const arrowStyle = {
             fontSize: arrowSize || '16px',
             color: arrowColor || '#333333',
             backgroundColor: arrowBackgroundColor || 'transparent',
             padding: arrowPadding ? `${arrowPadding.top} ${arrowPadding.right} ${arrowPadding.bottom} ${arrowPadding.left}` : '8px',
-            margin: arrowMargin ? `${arrowMargin.top} ${arrowMargin.right} ${arrowMargin.bottom} ${arrowMargin.left}` : '0 8px 0 0'
         };
+        const prevArrowStyle = {
+            ...arrowStyle,
+            margin: arrowMargin ? `${arrowMargin.top} ${arrowMargin.right} ${arrowMargin.bottom} ${arrowMargin.left}` : '0 8px 0 0',
+        };
+        const nextArrowStyle = {
+            ...arrowStyle,
+            margin: arrowMargin ? `${arrowMargin.top} ${arrowMargin.right} ${arrowMargin.bottom} ${arrowMargin.left}` : '0 0 0 8px',
+        };
...
-                        <span className="wedocs-doc-nav-arrow" style={arrowStyle}>←</span>
+                        <span className="wedocs-doc-nav-arrow" style={prevArrowStyle}>←</span>
...
-                        <span className="wedocs-doc-nav-arrow" style={arrowStyle}>→</span>
+                        <span className="wedocs-doc-nav-arrow" style={nextArrowStyle}>→</span>
Also applies to: 65-76

139-142: Clarify option label.

“Add rel” is vague; prefer “rel='prev/next'”.

Apply:
-        { label: __('Add rel', 'wedocs'), value: 'prev_next' }
+        { label: __('rel="prev/next"', 'wedocs'), value: 'prev_next' }
src/blocks/DocNavigation/style.scss (2)
10-67: Avoid blanket !important; scope selectors instead.

Excessive !important can fight themes. Prefer specificity (e.g., wrap in .wp-block-wedocs-wedocs-doc-navigation) and drop !important where not needed.

69-85: Add RTL tweaks for arrow spacing.

Improve UX in RTL locales by swapping arrow margins.

Apply at file end:
+/* RTL adjustments */
+[dir="rtl"] .wedocs-doc-navigation .wedocs-doc-nav-prev .wedocs-doc-nav-arrow { margin-left: 0.5rem; margin-right: 0; }
+[dir="rtl"] .wedocs-doc-navigation .wedocs-doc-nav-next { margin-right: auto; margin-left: 0; }
+[dir="rtl"] .wedocs-doc-navigation .wedocs-doc-nav-next .wedocs-doc-nav-arrow { margin-right: 0.5rem; margin-left: 0; }
src/blocks/DocNavigation/render.php (2)
233-239: Add aria-labels for better a11y.

Expose “Previous/Next: Title” to screen readers.

Apply:
-                    <a href="<?php echo esc_url(get_permalink($prev_post->ID)); ?>" 
-                       <?php echo ($seo_links === 'prev_next') ? 'rel="prev"' : ''; ?>>
+                    <a href="<?php echo esc_url(get_permalink($prev_post->ID)); ?>" 
+                       <?php echo ($seo_links === 'prev_next') ? 'rel="prev"' : ''; ?>
+                       aria-label="<?php echo esc_attr( sprintf( __( 'Previous: %s', 'wedocs' ), $prev_post->post_title ) ); ?>">
...
-                    <a href="<?php echo esc_url(get_permalink($next_post->ID)); ?>" 
-                       <?php echo ($seo_links === 'prev_next') ? 'rel="next"' : ''; ?>>
+                    <a href="<?php echo esc_url(get_permalink($next_post->ID)); ?>" 
+                       <?php echo ($seo_links === 'prev_next') ? 'rel="next"' : ''; ?>
+                       aria-label="<?php echo esc_attr( sprintf( __( 'Next: %s', 'wedocs' ), $next_post->post_title ) ); ?>">
Also applies to: 245-251

9-9: Tidy: silence unused parameter and drop unused local.

$content is required by signature but unused; $wp_class_name is never used.

Apply:
 function render_wedocs_doc_navigation($attributes, $content = '') {
+    // Unused by this renderer.
+    unset( $content );
...
-    $wp_class_name = $attributes['className'] ?? '';
Also applies to: 67-67
src/blocks/DocNavigation/block.json (4)
6-9: Add textdomain for i18n of title/description.

Block metadata should declare the plugin text domain so "title" and "description" can be translated.
   "name": "wedocs/wedocs-doc-navigation",
   "version": "1.0.0",
   "title": "weDocs - Doc Navigation",
+  "textdomain": "wedocs",
   "icon": "arrow-left-alt2",
22-25: Enable text color support to align with WP style engine.

You already handle background via supports; enable text as well so users can use global styles without custom attrs.
   "color": {
-    "background": true
+    "background": true,
+    "text": true
   },
29-32: Constrain seoLinks with an enum.

Prevents invalid values and improves editor tooling.
   "seoLinks": {
     "type": "string",
-    "default": "none"
+    "default": "none",
+    "enum": ["none", "prev_next"]
   },
12-26: Consider relying more on core supports (spacing/border/color/shadow).

Many custom attributes (e.g., navPadding/navMargin) duplicate core supports; this increases surface area and SSR CSS assembly. Prefer core supports unless you need per-item overrides.

Also applies to: 33-121
assets/build/blocks/DocNavigation/render.php (3)
64-68: Remove unused $wp_class_name or actually use it.

It's extracted but not used. Either pass via wrapper attributes or drop it.
-    $wp_class_name = $attributes['className'] ?? '';
232-247: Add accessible labels to navigation links.

Improves a11y for screen readers.
-                    <a href="<?php echo esc_url(get_permalink($prev_post->ID)); ?>" 
-                       <?php echo ($seo_links === 'prev_next') ? 'rel="prev"' : ''; ?>>
+                    <a href="<?php echo esc_url(get_permalink($prev_post->ID)); ?>" 
+                       <?php echo ($seo_links === 'prev_next') ? 'rel="prev"' : ''; ?>
+                       aria-label="<?php echo esc_attr( sprintf( __( 'Previous: %s', 'wedocs' ), $prev_post->post_title ) ); ?>">
@@
-                    <a href="<?php echo esc_url(get_permalink($next_post->ID)); ?>" 
-                       <?php echo ($seo_links === 'prev_next') ? 'rel="next"' : ''; ?>>
+                    <a href="<?php echo esc_url(get_permalink($next_post->ID)); ?>" 
+                       <?php echo ($seo_links === 'prev_next') ? 'rel="next"' : ''; ?>
+                       aria-label="<?php echo esc_attr( sprintf( __( 'Next: %s', 'wedocs' ), $next_post->post_title ) ); ?>">
Also applies to: 244-251

69-134: Rely on core wrapper styles instead of reassembling WP style attributes.

Manual mapping of background/text/border/spacing/shadow duplicates core style engine and risks drift. Prefer passing extra classes/styles to get_block_wrapper_attributes and let supports handle the rest.
assets/build/store.js (3)
321-331: Wrap switch-case declarations in a block and prevent doc duplicates.

Fixes lint error (noSwitchDeclarations) and avoids multiple entries of the same doc ID.
-    case 'SET_DOC':
-      const setDocState = {
-        ...state,
-        docs: [...state.docs, action.doc]
-      };
-      const isNotInParent = !state.parents.some(parent => parent?.id === action?.doc?.id);
-      if (!action.doc.parent && isNotInParent) {
-        setDocState.parents = [{
-          ...action.doc
-        }, ...state.parents];
-      }
-      return setDocState;
+    case 'SET_DOC': {
+      const idx = state.docs.findIndex(d => d?.id === action?.doc?.id);
+      const nextDocs = idx === -1
+        ? [...state.docs, action.doc]
+        : Object.assign([...state.docs], { [idx]: action.doc });
+      const setDocState = { ...state, docs: nextDocs };
+      const isNotInParent = !state.parents.some(parent => parent?.id === action?.doc?.id);
+      if (!action.doc.parent && isNotInParent) {
+        setDocState.parents = [{ ...action.doc }, ...state.parents];
+      }
+      return setDocState;
+    }
372-377: Fix unsafe optional chaining with spread in REMOVE_DOC.

Spreading possibly-undefined (docs?.filter(...)) can throw. Use safe arrays.
-    case 'REMOVE_DOC':
-      return {
-        ...state,
-        docs: [...state.docs?.filter(doc => doc.id !== action.docId)],
-        parents: [...state.parents?.filter(parent => parent.id !== action.docId)]
-      };
+    case 'REMOVE_DOC':
+      return {
+        ...state,
+        docs: (Array.isArray(state.docs) ? state.docs : []).filter(doc => doc.id !== action.docId),
+        parents: (Array.isArray(state.parents) ? state.parents : []).filter(parent => parent.id !== action.docId)
+      };
410-419: Sort without mutating and guard inputs.

Use defensive copies and array checks to avoid latent issues.
-    const parentDocs = response.filter(doc => !doc.parent);
-    const sortableDocs = parentDocs?.sort((a, b) => a.menu_order - b.menu_order);
+    const parentDocs = Array.isArray(response) ? response.filter(doc => !doc.parent) : [];
+    const sortableDocs = [...parentDocs].sort((a, b) => a.menu_order - b.menu_order);
Apply similar pattern to selectors where sections?.sort / articles?.sort are used.

Also applies to: 525-546, 548-562
wedocs.php (1)
187-193: Rely on block.json render to avoid duplication.

Since block.json already declares "render": "file:./render.php", you can omit render_callback here and let metadata drive it.
-        register_block_type(
-            plugin_dir_path(__FILE__) . 'assets/build/blocks/DocNavigation',
-            array(
-                'render_callback' => 'render_wedocs_doc_navigation'
-            )
-        );
+        register_block_type( plugin_dir_path(__FILE__) . 'assets/build/blocks/DocNavigation' );
src/blocks/DocNavigation/index.js (1)
2-2: Remove unused import.

__ isn’t used in this module; drop the import to avoid an unnecessary dependency.
-import { __ } from '@wordpress/i18n';
assets/build/index.css (1)
1-3: Exclude built artifacts from linters.

Biome errors here are from vendor/minified CSS (e.g., old IE filters, duplicate properties for prefixes). Add a linter ignore for assets/build/** to reduce noise and CI churn.

Example Biome override (adjust path as needed):
{
  "overrides": [{ "include": ["assets/build/**"], "linter": { "enabled": false }, "formatter": { "enabled": false } }]
}
assets/build/blocks/DocNavigation/block.json (3)
1-9: Add textdomain and consider inserter category.

Add "textdomain": "wedocs" for translations extracted from block metadata.

Optional: consider "category": "design" for better inserter discoverability (many sites don’t use the legacy “widgets” category in post editor).
 {
   "$schema": "https://schemas.wp.org/trunk/block.json",
   "apiVersion": 3,
   "name": "wedocs/wedocs-doc-navigation",
   "version": "1.0.0",
+  "textdomain": "wedocs",
   "title": "weDocs - Doc Navigation",
-  "icon": "arrow-left-alt2",
-  "category": "widgets",
+  "icon": "arrow-left-alt2",
+  "category": "design",
27-121: Sanitize and escape server-rendered styles/URLs.

Ensure render.php sanitizes color/dimension values and escapes URLs/attributes to avoid XSS via block attributes.

Checklist:

esc_url() for hrefs

esc_attr() for style fragments and aria labels

sanitize_hex_color() for hex colors

wp_kses_post() where HTML fragments are unavoidable

29-32: Clarify SEO behavior: seoLinks adds rel attributes to the anchor elements (no head output).

Findings: assets/build/blocks/DocNavigation/block.json default is "none". assets/build/blocks/DocNavigation/render.php sets rel="prev" (line 234) and rel="next" (line 246) on the nav anchors when $seo_links === 'prev_next'. No wp_head/add_action or <link rel="prev"/"next"> in the head was found.

Action: If you want head-level for crawlers, add a wp_head-hooked function that echoes only when the prev/next posts exist; otherwise document that seoLinks controls anchor rel attributes only.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c80fc84 and 5cce480.

⛔ Files ignored due to path filters (9)

assets/build/block.js.map is excluded by !**/*.map
assets/build/frontend.css.map is excluded by !**/*.map
assets/build/frontend.js.map is excluded by !**/*.map
assets/build/index.css.map is excluded by !**/*.map
assets/build/index.js.map is excluded by !**/*.map
assets/build/print.css.map is excluded by !**/*.map
assets/build/print.js.map is excluded by !**/*.map
assets/build/store.js.map is excluded by !**/*.map
assets/build/style-block.css.map is excluded by !**/*.map

📒 Files selected for processing (21)

assets/build/block.asset.php (1 hunks)
assets/build/blocks/DocNavigation/block.json (1 hunks)
assets/build/blocks/DocNavigation/render.php (1 hunks)
assets/build/frontend.asset.php (1 hunks)
assets/build/frontend.css (2 hunks)
assets/build/frontend.js (1 hunks)
assets/build/index.asset.php (1 hunks)
assets/build/index.css (2 hunks)
assets/build/print.asset.php (1 hunks)
assets/build/print.css (2 hunks)
assets/build/print.js (1 hunks)
assets/build/store.asset.php (1 hunks)
assets/build/store.js (1 hunks)
src/blocks/DocNavigation/block.json (1 hunks)
src/blocks/DocNavigation/edit.js (1 hunks)
src/blocks/DocNavigation/index.js (1 hunks)
src/blocks/DocNavigation/render.php (1 hunks)
src/blocks/DocNavigation/save.js (1 hunks)
src/blocks/DocNavigation/style.scss (1 hunks)
src/blocks/index.js (1 hunks)
wedocs.php (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (4)

src/blocks/DocNavigation/index.js (1)

src/blocks/DocNavigation/edit.js (1)

Edit (12-310)

assets/build/blocks/DocNavigation/render.php (1)

src/blocks/DocNavigation/edit.js (1)

attributes (14-33)

assets/build/store.js (10)

src/components/DocListing/index.js (3)

docs (27-29)

loading (37-40)

sections (103-103)

src/components/Documentations/index.js (3)

docs (19-22)

loading (29-32)

parentDocs (24-27)

src/components/SelectBox.js (1)

pages (16-16)

src/blocks/DocsGrid/edit.js (2)

loading (18-18)

wp (16-16)

src/components/DocListing/ListingHeader.js (1)

loading (13-16)

src/components/Documentations/ParentDocs.js (2)

sections (36-40)

articles (42-46)

src/components/AddArticleModal.js (1)

articles (35-39)

src/components/DocListing/QuickEditModal.js (1)

articles (34-38)

src/components/DocListing/DocSections.js (2)

articles (70-70)

settings (86-89)

src/components/ProPreviews/index.js (1)

isProLoaded (13-16)

src/blocks/DocNavigation/render.php (2)

assets/build/blocks/DocNavigation/render.php (1)

render_wedocs_doc_navigation (9-259)

src/blocks/DocNavigation/edit.js (1)

attributes (14-33)

🪛 Biome (2.1.2)

assets/build/index.css