# 🧰 Factorize Essentials

> The store's backbone — trust notes, badges, and checkout guards.
>
> **Suite identity:** icon 🧰 · accent `#d42121` · part of the [Factorize suite](../README-FACTORIZE.md)

## What it does

Carries the store-wide WooCommerce behavior that used to live in the original store theme (`inc/woocommerce.php`). It adds the condition and pickup notes and the SAVE badge to product pages, percentage-off sale flashes and OUT OF STOCK badges to the shop loop, live cart-count fragments, a guided no-results search page, spacer-paragraph cleanup on descriptions, checkout fine print, double-tap add-to-cart protection for sold-individually items, and stale-error-notice shedding on cart/checkout. Everything registers only when WooCommerce is active; without WooCommerce the plugin is inert.

## Configuration

| Key | Default | Effect |
| --- | --- | --- |
| `condition_note` | `New and unused — packaging may have slight dents, creases, or an open box.` | Condition disclaimer shown under the product summary on single product pages. |
| `pickup_title` | `Pickup In Store — Free` | Bold first line of the pickup note under the buy box. |
| `pickup_sub` | `Free local pickup — or flat-rate shipping at checkout.` | Small-print second line of the pickup note. |

Values are read through `empire_essentials_config( $key )`. Defaults can be overridden by saving an array to the `factorize-essentials_options` option (e.g. `update_option( 'factorize-essentials_options', array( 'pickup_title' => '...' ) )`) or, at runtime, by filtering the merged array via `add_filter( 'factorize-essentials_config', ... )`. The legacy `empire-store-essentials_options` option is still read as a fallback when the new option is empty. The original per-string theme filters (`empire_tools_condition_note`, `empire_tools_pickup_title`, `empire_tools_pickup_sub`) still apply on top of the configured value, so existing overrides keep working.

## Works with

- **WooCommerce** (required for any visible effect): every hook either checks `class_exists( 'WooCommerce' )`, guards `WC()` / `wc_get_notices()` / `wc_get_featured_product_ids()` with `function_exists()`, or fires only on WooCommerce's own hooks. Without WooCommerce nothing runs and nothing breaks.
- **The store theme**: the original store theme keeps all CSS for the classes this plugin outputs (`et-oos-badge`, `et-save-badge`, `et-condition-note`, `et-pickup-note`, `et-cart-count`, `et-brand-chips`, `et-no-results`, `et-checkout-fineprint`, etc.) and its header/bottom-bar markup contains the `span.et-cart-count` element the cart fragment refreshes. On another theme the output degrades to unstyled markup.
- **Sibling Factorize plugins**: none are called and none call into this plugin. The "Hot Deals" shortcode filter subtracts featured product IDs (set by the import/finalize tooling) so Featured and Hot Deals don't render the same four products; with no featured products it simply skips that step.

## Hooks it registers

- `init` — attaches the loop OOS badge and the single-product SAVE/condition/pickup hooks, removes the WooCommerce sidebar; a second `init` callback removes the stock `wc_no_products_found` handler.
- `woocommerce_sale_flash` — real percentage-off badge (`-29%`).
- `woocommerce_add_to_cart_fragments` — live `span.et-cart-count` fragment.
- `woocommerce_product_add_to_cart_text` — "View Details" on out-of-stock loop buttons.
- `woocommerce_breadcrumb_defaults` — `/` breadcrumb delimiter.
- `woocommerce_shortcode_products_query` — restricts `sale_products` shortcode queries to in-stock, non-featured items.
- `woocommerce_before_shop_loop` (priority 15) — brand chip row on shop/search.
- `woocommerce_before_customer_login_form` — guest-checkout reassurance note.
- `gettext` (priority 20) — pickup-only rewording of three WooCommerce core strings.
- `woocommerce_related_products` — in-stock-first related products with category top-up.
- `the_title` — ellipsis on titles truncated by the Wix export.
- `woocommerce_no_products_found` — guided no-results page.
- `the_content` / `woocommerce_short_description` (priority 20) — spacer-paragraph stripping.
- `render_block` — fine-print note appended to the `woocommerce/checkout` block.
- `woocommerce_add_to_cart_validation` — silent no-op when re-adding a sold-individually item already in the cart.
- `template_redirect` (priority 1) — sheds stale session error notices on cart/checkout.
- `admin_init` — registers the plugin's card with the shared Factorize hub (Storefront tab).

## Publishing

`readme.txt` (the WordPress.org listing) and `QUICKSTART.md` (the 5-minute setup guide) live alongside this file — keep both in sync with the code when features change.
