=== fraew Category Posts List ===
Contributors: fraew
Donate link: https://buymeacoffee.com/fraew
Tags: posts, category, widget, sidebar, related-posts
Requires at least: 5.0
Requires PHP: 7.2
Tested up to: 7.0
Stable tag: 1.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display all posts from the current post's category in a widget with customizable formatting, display options, and spacing.

== Description ==

fraew Category Posts List is a lightweight, flexible widget that displays posts from the same category as the currently viewed post. Perfect for blogs, news sites, and any WordPress site that wants to help visitors discover related content.

**Features:**

* Display posts from the current post's category in a widget
* Three display formats: List, Comma-separated, or Inline
* Customize spacing between posts (Compact, Normal, Comfortable, Spacious)
* Toggle post separators (borders) on or off
* Current post is highlighted in bold
* **Optional post metadata** – Show publication date, author, comment count, and reading time estimates
* **Sticky post promotion** – Move sticky posts to the top with optional visual indicators
* Configure global settings that apply to all widget instances
* Works with any theme
* Lightweight and performant
* Zero bloat – only loads CSS on pages where the widget appears

**Display Formats:**

* **List** – Traditional vertical list, one post per line
* **Comma-Separated** – Posts displayed inline: Post 1, Post 2, Post 3
* **Inline** – Posts displayed inline with spaces: Post 1 Post 2 Post 3

**Spacing Options:**

* **Compact** – 3px padding (tight list)
* **Normal** – 8px padding (default)
* **Comfortable** – 12px padding
* **Spacious** – 15px padding (generous spacing)

**Post Separators:**

Toggle borders between posts on or off to match your site's design.

== Installation ==

1. Upload the `fraew-category-posts-list` folder to `/wp-content/plugins/` via FTP or through the WordPress admin
2. Activate the plugin through the **Plugins** menu in WordPress
3. Configure settings: **Settings → Category Posts List**
4. Add the widget: **Appearance → Widgets → Category Posts List**

== Usage ==

### Widget Setup

1. Go to **Appearance → Widgets**
2. Find and add **"Category Posts List"** widget to a widget area (sidebar, footer, etc.)
3. Settings:
   - **Posts Per Page** – How many posts to display (default: 100)
   - **Sort Posts** – Choose sort order:
     - Title (A-Z)
     - Title (Z-A)
     - Date (Newest First)
     - Date (Oldest First)

Note: The widget will automatically display the category name as its heading.

### Global Settings

Go to **Settings → Category Posts List** to configure:

* **Post Separators** – Show or hide borders between posts
* **Display Format** – Choose how posts are presented (List, Comma-separated, or Inline)
* **Spacing Between Posts** – Adjust vertical spacing in list format

These settings apply to all widget instances on your site.

== How It Works ==

When a visitor views a post, this plugin:

1. Detects the post's category
2. Retrieves all posts in that category
3. Displays them according to your configured settings
4. Highlights the currently viewed post in bold

The widget only appears on single post pages and does not display on category archives, search results, or homepage.

== Configuration Examples ==

**Example 1: Clean, Minimal List**
- Display Format: List
- Separators: OFF
- Spacing: Compact

**Example 2: Prominent Related Posts**
- Display Format: List
- Separators: ON
- Spacing: Spacious

**Example 3: Compact Inline**
- Display Format: Comma-separated
- Spacing: Compact (irrelevant for inline format)

**Example 4: Bold Discovery**
- Display Format: Inline
- Spacing: Normal (irrelevant for inline format)

== FAQ ==

**Q: Why doesn't the widget show on my page?**
A: The widget only displays on single post pages, not on category archives, search results, or the homepage.

**Q: Can I customize the styling beyond what the settings provide?**
A: Yes! The plugin uses CSS classes you can override in your theme's `style.css`. Classes include:
- `.fcpl-posts-list` – Main container
- `.fcpl-category-title` – Category heading
- `.fcpl-post` – Individual post item
- `.fcpl-post-current` – Current post (highlighted)
- `.fcpl-posts-inline` – Inline format container

**Q: Does it match the fraew - modern light theme automatically?**
A: Yes. When a theme declares support for "fraew-design-tokens" (as fraew - modern light does),
the plugin loads a skin that styles the list with that theme's own palette and fonts. Under any
other theme it uses its neutral default styling.

**Q: Can I use multiple instances of the widget?**
A: Yes, you can add the widget to multiple sidebars or widget areas. All instances share the same global settings.

**Q: Does this plugin work with custom post types?**
A: Currently, this plugin only works with standard WordPress posts and post categories. Custom post types are not supported.

**Q: How many posts can I display?**
A: Up to 100 posts per widget (configurable in widget settings).

**Q: Will this slow down my site?**
A: No. The plugin is lightweight and only queries posts in the current category, not all posts. CSS is only loaded on pages where the widget appears.

**Q: Can I change the sort order per widget?**
A: Yes. Each widget instance has its own "Sort Posts" setting, so you can display different sort orders on different pages if needed.

== Support ==

Need help? Visit the plugin documentation or report issues:

* WordPress.org Plugin Page: https://wordpress.org/plugins/fraew-category-posts-list/
* Support Forum: https://wordpress.org/support/plugin/fraew-category-posts-list/

== Donate ==

Love this plugin? Support future development:
https://buymeacoffee.com/fraew

== Screenshots ==

1. The widget in a sidebar: posts from the current post's category, with a sticky post pinned to the top and author, date and reading time shown inline
2. The same list with metadata in block format, shown on its own line beneath each title
3. Widget settings, including the metadata fields and sticky post options
4. Global settings that apply to every instance of the widget

== Changelog ==

= 1.3.0 =
* Added: Optional post metadata display (publication date, author, comment count, reading time estimate)
* Added: Sticky post promotion – move sticky posts to the top of the list
* Added: Optional sticky post visual indicators (emoji badge or custom)
* Added: Support for inline and block metadata display formats
* Added: Widget settings for metadata and sticky post configuration
* Improved: All metadata elements are clickable and properly escaped for security
* Improved: CSS classes for custom styling: .fcpl-meta, .fcpl-sticky-indicator, .fcpl-item--sticky
* Maintained: Full backward compatibility – all new features are optional and disabled by default

= 1.2.0 =
* Added: automatic styling for themes that declare support for "fraew-design-tokens" (such as
  the fraew - modern light theme). The widget adopts the theme's palette and fonts via a skin
  stylesheet, and falls back to the neutral default under any other theme. No theme code required.

= 1.1.0 =
* Fixed: the rendered markup used misspelled CSS class names (fffcpl-posts-list,
  ffcpl-posts, ffcpl-post-current) that did not match the stylesheet. As a result the
  "Show separators" and "Item spacing" settings had no effect. Both now work.
* Fixed: posts are alphabetised ignoring a leading "The", "A" or "An", so "The Chills"
  files under C. "Theatre Royal" is unaffected.
* Fixed: for a post in both a parent and a child category, the list now uses the most
  specific (deepest) category rather than whichever term ID came back first.
* Added: aria-current="page" on the link to the post being viewed.
* Added: fcpl_enqueue_frontend_css filter - return false to suppress the plugin's
  stylesheet when your theme styles the widget itself.
* Added: fcpl_category_title filter to relabel or hide the heading.
* Added: fcpl_primary_category_id and fcpl_sort_key filters.

= 1.0.0 =
* Initial release
* List, Comma-separated, and Inline display formats
* Configurable spacing (Compact, Normal, Comfortable, Spacious)
* Toggle post separators on/off
* Global settings page
* Widget with sort order options
* Current post highlighting

== License ==

This plugin is licensed under the GPLv2 or later. For more information, visit:
https://www.gnu.org/licenses/gpl-2.0.html
