=== ShopShelf – Product Grid & Carousel for WooCommerce ===
Contributors: shshakib2001
Tags: woocommerce, product grid, product carousel, product slider, product showcase
Requires at least: 5.7
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show WooCommerce products anywhere in responsive grids and carousels, with full control over what appears on each product card.

== Description ==

ShopShelf turns any WooCommerce catalogue into a product showcase you can place anywhere with a shortcode.

Build a **layout** — one saved product showcase — by choosing which products it shows, how they are arranged, and which parts of a product appear on each card. Save it, copy its shortcode, and paste it into any post, page, widget or block.

= Two layouts =

* **Grid** — products in rows and columns, with a column count for each of five screen sizes
* **Carousel** — the same cards on a sliding track, in three modes: Standard, Center and Ticker

= Choose your products =

* Draw from all products, or only featured, on-sale, best-selling, top-rated or free ones
* Limit to simple, variable, grouped or external products
* Show a set number of products
* Include only specific products, or exclude specific ones
* Filter by product category, tag or any product attribute, with IN / AND / NOT IN operators
* Hide out-of-stock, on-sale, free or image-less products, and show or hide catalog-hidden ones
* Sort by date, title, price, popularity, rating, modified date, menu order, ID or at random

= Let shoppers filter =

* Live taxonomy filters shown as buttons, a dropdown, radio buttons or checkboxes, with optional product counts
* A keyword search box
* Everything updates without reloading the page

= Build the card =

Drag the parts of a product card into the order you want and switch off the ones you do not need:

* Product image, at any registered size or a custom cropped size
* Title, with your choice of HTML tag and a length limit
* Meta fields — category or tag, SKU, stock status, stock quantity, units sold, weight, dimensions and date
* Description — the short description, a trimmed description or the full one
* Price, with a separate colour for the struck-through regular price
* Add to Cart, Read More button or Read More text link
* Social share links for Facebook, X (Twitter), LinkedIn, Pinterest and email

= Make it fit your theme =

* Columns and gap per screen size, and equal card heights
* Card border, corner radius, shadow, background and inner padding
* Typography for every text element, with separate sizes for desktop, tablet and mobile
* A site-wide colour scheme that every layout falls back to
* Custom CSS and JavaScript, kept safe from theme and plugin updates
* Pagination for grids: Load More button, AJAX numbered pages, infinite scroll or ordinary page links

= Carousel controls =

* Autoplay with pause on hover, speed and infinite loop
* Slide, fade, coverflow, cube and flip transitions
* Multiple rows, and slides-to-scroll per screen size
* Navigation arrows in nine positions, with a choice of icons and colours
* Dot or numbered pagination, with dynamic bullets
* Keyboard navigation, touch swipe, mouse drag and mouse wheel
* Editable screen-reader messages

= Built to stay out of the way =

* A live preview while you edit — including before you save
* Templates you can override from your theme
* Every setting is scoped to its layout, so two showcases on one page can look completely different
* All scripts, styles, icons and fonts are served from your own site
* Sample layouts, a settings backup and a system status report under Tools
* A built-in Help screen documenting every control

= Source code =

The plugin ships the human-readable source of everything it minifies:

* Front end: `src/Frontend/assets/js/scripts.js` and `src/Frontend/assets/css/style.css` / `shopshelf-grid.css` sit beside their `.min` versions.
* Admin: the React source of `src/Admin/assets/app/shopshelf-admin-app.js` is in the `shopshelf-admin/` folder. To rebuild it, run `npm install` and `npm run build` inside that folder (Node.js 20 or newer).

Bundled third-party libraries:

* [Swiper](https://github.com/nolimits4web/swiper) 14.3.0 — MIT License. Both `swiper-bundle.js` and `swiper-bundle.min.js` are the unmodified files from the official package.
* [IcoFont](https://icofont.com/) — the font is licensed under the SIL Open Font License 1.1 and its CSS under the MIT License.
* The admin bundle includes [React](https://github.com/facebook/react), [React Router](https://github.com/remix-run/react-router), [Radix UI](https://github.com/radix-ui/primitives), [Lucide](https://github.com/lucide-icons/lucide), [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss), [date-fns](https://github.com/date-fns/date-fns), [React Day Picker](https://github.com/gpbl/react-day-picker), [react-colorful](https://github.com/omgovich/react-colorful), [class-variance-authority](https://github.com/joe-bell/cva), [clsx](https://github.com/lukeed/clsx) and [tailwind-merge](https://github.com/dcastil/tailwind-merge), all under the MIT or ISC licenses. The full list with versions is in `shopshelf-admin/package.json`.

== Installation ==

1. Install and activate WooCommerce, if you have not already.
2. Go to **Plugins → Add New**, search for "ShopShelf", and click **Install Now** — or upload the plugin zip there.
3. Activate the plugin.
4. Go to **ShopShelf → Add New Layout**, build a layout, and publish it.
5. Copy the layout's shortcode, for example `[shopshelf id="12"]`, and paste it into any post, page or widget.

== Frequently Asked Questions ==

= Does this require WooCommerce? =

Yes. ShopShelf displays WooCommerce products and calls WooCommerce directly, so it needs WooCommerce installed and active.

= How do I show a layout? =

Each layout has a shortcode, shown in the layouts list and in the editor: `[shopshelf id="12"]`. Paste it into a Shortcode block, the classic editor, a text widget or a page builder's shortcode element. In a theme template, use `<?php echo do_shortcode( '[shopshelf id="12"]' ); ?>`.

= My layout shows no products. =

Check that the layout is published, then look at its filters: almost always they are narrower than the catalogue — a category with nothing published in it, or a Best Selling or Top Rated source on a shop with no sales or reviews yet. Clear the filters one at a time and preview after each.

= Can I put several layouts on one page? =

Yes. Each layout is wrapped in its own element and its settings, filters and pagination are scoped to it.

= Can I style one layout with my own CSS? =

Yes. Every layout is wrapped in an element with its own id, so a rule that starts with that id affects only that layout:

`#shopshelf_wrapper-12 .shopshelf__item--title a { text-transform: uppercase; }`

Add it with WordPress's own CSS editor: **Appearance → Customize → Additional CSS**, or **Styles → Additional CSS** in the Site Editor.

= Can I change the markup? =

Yes. Copy any template from the plugin's `src/Frontend/templates` folder into a `shopshelf` folder in your theme, keeping the same path — for example `yourtheme/shopshelf/item/title.php` — and edit it there. Your copy is used instead of the plugin's and survives plugin updates. **Tools → System status** lists any overrides it finds, which is worth checking if a setting seems to have no effect.

= Does the plugin load anything from other websites? =

No. Scripts, styles, icons and fonts are all served from your own site. The only outbound links are the optional social share links described under "External services" below, and they do nothing until a visitor clicks one.

= What happens to my layouts if I remove the plugin? =

Deactivating the plugin keeps everything. Deleting it from the Plugins screen removes its layouts and settings.

== Screenshots ==

1. The layouts list — every saved showcase, with its shortcode
2. Editing a layout: preset, filter settings and card content
3. The live preview
4. Settings: colour scheme, scripts and styles, accessibility
5. Tools: sample layouts, settings backup and the system status report

== External services ==

This plugin does not connect to any external service by itself. It loads no remote scripts, styles, fonts or images, and it sends no data anywhere.

If you switch on **Social Share** for a layout, each product card shows ordinary links to the share pages of the networks you chose. No request is made to any of these services when the page loads. A link is opened only when a visitor clicks that share button, and at that moment the product's public URL and its title are passed to the service in the link's address so the service can prefill the post. No other data is sent by the plugin. What the service does after the visitor arrives there is governed by that service's own terms and privacy policy.

= Facebook =

Facebook's sharing dialog (`https://www.facebook.com/sharer/sharer.php`), provided by Meta Platforms, lets the visitor post the product link to Facebook. Opened only when the visitor clicks the Facebook share button. Data sent: the product URL.
[Terms of Service](https://www.facebook.com/legal/terms) · [Privacy Policy](https://www.facebook.com/privacy/policy/)

= X (Twitter) =

X's post composer (`https://twitter.com/intent/tweet`, which redirects to x.com), provided by X Corp., lets the visitor post the product link to X. Opened only when the visitor clicks the X share button. Data sent: the product URL and the product title.
[Terms of Service](https://x.com/en/tos) · [Privacy Policy](https://x.com/en/privacy)

= LinkedIn =

LinkedIn's share page (`https://www.linkedin.com/sharing/share-offsite/`), provided by LinkedIn Corporation, lets the visitor share the product link on LinkedIn. Opened only when the visitor clicks the LinkedIn share button. Data sent: the product URL.
[User Agreement](https://www.linkedin.com/legal/user-agreement) · [Privacy Policy](https://www.linkedin.com/legal/privacy-policy)

= Pinterest =

Pinterest's pin-creation page (`https://www.pinterest.com/pin/create/button/`), provided by Pinterest, Inc., lets the visitor save the product as a pin. Opened only when the visitor clicks the Pinterest share button. Data sent: the product URL and the product title.
[Terms of Service](https://policy.pinterest.com/en/terms-of-service) · [Privacy Policy](https://policy.pinterest.com/en/privacy-policy)

= Email =

The Email share button is a `mailto:` link. It opens the visitor's own email application with the product title as the subject and the product URL as the message body. Nothing is sent to any service by the plugin.

== Changelog ==

= 1.1.0 =
* New: Settings → Custom CSS & JS, with code editors for your own styles and scripts. Custom CSS loads after ShopShelf's styles; custom JavaScript runs only on pages that show a layout. Only users who may add unfiltered HTML can change it.
* New: `shopshelf:ready` and `shopshelf:products-loaded` jQuery events, fired when a layout starts and after filters, pagination or Load More bring in new products.
* New: Filter Products — draw from all products, or only featured, on-sale, best-selling, top-rated or free ones.
* New: Product Type filter — simple, variable, grouped or external products.
* New: Show Hidden Products, and options to hide out-of-stock, on-sale, free and image-less products.
* New: Order By and Order, including price, popularity and average rating.
* Changed: "Product Selection" is now "Filter Settings", reorganised into Products, Visibility & Stock, Order & Limit and Advanced Filtering.
* Changed: Clearer titles, descriptions and help text throughout the admin, with consistent terms.
* Changed: Defaults for new layouts — a light card border, a full-width product image, meta fields shown (category and stock status) and rounded carousel arrows. Saved layouts are not changed.
* Changed: Products set to Hidden or Search results only in WooCommerce are no longer shown unless Show Hidden Products is on.
* Removed: Skip First. Layouts that used it now start from the first matching product.
* Removed: The shopper sort-direction filter.
* Fixed: The social share Alignment setting showed no option selected by default.

= 1.0.0 =
* First release.
* Grid and Carousel layouts, with Standard, Center and Ticker carousel modes.
* Product selection by limit, offset, include/exclude lists and product taxonomies, with a choice of sort order.
* Live filters for shoppers: taxonomy filters (buttons, dropdown, radio, checkbox), keyword search and sort direction.
* Sortable card content: image, title, meta fields, description, price, button and social share.
* Per-layout card styling and typography, and a site-wide colour scheme.
* Grid pagination: Load More, AJAX numbered pages, infinite scroll and ordinary page links.
* Carousel navigation, pagination, autoplay, transitions, multiple rows and accessibility messages.
* Live preview in the layout editor, including before a layout is saved.
* Settings for scripts and styles, and accessibility messages.
* Tools: sample layouts, settings backup and restore, and a system status report.
* Built-in Help screen.
* Theme-overridable templates.

== Upgrade Notice ==

= 1.1.0 =
Adds Custom CSS & JS and more product filters. Catalog-hidden products are now left out by default, and the Skip First and shopper sort options are removed — check layouts that relied on them.
