hemn/mataba
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement WooCommerce storefront foundation

Browse Source
This commit is contained in:
XShop
2026-09-13 19:51:31 +03:30
parent f11e1d650d
commit 00439fcea9
18 changed files with 871 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
shop/docs/ARCHITECTURE.md
+36 -34
View File
@@ -15,33 +15,32 @@ Two installable artifacts: theme (`xshop`) + plugin (`xshop-core`). Theme never
## 2. Theme – `xshop-theme`
### 2.1 File map (M1)
### 2.1 File map (M2)
```
xshop-theme/
style.css # WP header
functions.php # thin loader (requires inc/setup/* only)
screenshot.png # placeholder until final artwork
rtl.css # WP RTL flag; logical props used, not duplicated stylesheet
header.php # <html> + skip link + xshop-header wrapper + breadcrumbs
footer.php # </main> + footer + wp_footer
index.php / front-page.php / single.php / page.php / archive.php / search.php / 404.php / sidebar.php / comments.php
style.css
functions.php # thin loader
screenshot.png / rtl.css
header.php / footer.php / index.php / front-page.php / single.php / page.php / archive.php / search.php / 404.php / sidebar.php / comments.php
inc/
setup/ # theme-support, menus, sidebars, body-classes, assets
helpers/ # sanitize, template (xshop_get_setting, xshop_svg, xshop_is_dark_mode, xshop_has_woocommerce, branding fallback)
customization/ # options (xshop_settings) — full UI in M6
compatibility/ # gutenberg, elementor (no hard dep)
woocommerce/ # wrappers + dequeued WC styles + notice compat
performance/ # defer for xshop.js
setup/ # theme-support, menus, sidebars, body-classes, assets (woo.css global, documented)
helpers/ # sanitize, template (xshop_has_woocommerce etc)
customization/ # options
compatibility/ # gutenberg, elementor
woocommerce/ # wrappers, loop_start/end, toolbar, remove gallery, related args, product.js enqueue, cart quantity filter
performance/ # defer
assets/
css/ # tokens, base, layout, components, utilities
js/ # theme.js (mobile nav + dark toggle + focus trap)
images/ fonts/
css/ # tokens, base, layout, components, woo (shop/product/cart/account/checkout), utilities
js/ # theme.js + product.js (gallery thumbs, keyboard)
template-parts/components/
site-header.php, site-footer.php,
breadcrumbs.php, pagination.php, search-form.php, post-card.php,
empty-state.php, loading.php, section-heading.php, hero.php, promo-banner.php
woocommerce/ # empty in M1 — overrides only when justified (documented)
site-header/-footer, breadcrumbs, pagination, search-form, post-card,
product-card.php (WC_Product, badges, price, rating, hooks), product-grid.php, product-gallery.php (featured+thumbs, keyboard), mini-cart.php, empty-state, loading, section-heading, hero, promo-banner
woocommerce/
content-product.php (3.6.0) — delegates to product-card
archive-product.php (3.4.0) — shop/category header + toolbar + grid + empty-state CTA
content-single-product.php (3.6.0) — grid gallery+summary, hooks preserved
single-product.php (1.6.4) — delegator to content-single-product
languages/
```
@@ -106,19 +105,16 @@ Plugin owns persistence for wishlist/compare/Q&A/banners. Theme only renders.
Avoid custom tables in v1; revisit via ADR if scale demands.
## 5. Design System (M1)
## 5. Design System (M2)
CSS custom properties in `assets/css/tokens.css` — full token set: primary/secondary/bg/surface/card/text/muted/border/input/focus/link/success/warning/danger (+ bg variants), typography (xs–4xl, weights 400/500/700, leading tight/normal/relaxed), spacing (1–16), container/narrow, radius (sm/md/lg/full), shadow (sm/md/lg), z, transition (fast/normal/slow). Dark mode semantic swap on `[data-theme="dark"]`. Layering: `tokens→base→layout→components→utilities→style.css` via `inc/setup/assets.php:1`.
Tokens: `tokens.css` unchanged — adds WC tokens `--xshop-wc-badge-sale/--xshop-wc-price` etc. Layering `tokens→base→layout→components→woo→utilities→style.css` (woo.css 159 lines, tokens for shop/product/cart). Dark mode semantic swap covers `bg/surface/card/text/muted/border/input/focus/link/notice` — verified on shop/card/gallery/tabs/cart/checkout. Logical props only, zero `left/right`.
Logical properties (`margin-inline`, `padding-inline`, `inset-inline`, `inset-block`, `inline-size`) throughout; zero `left`/`right` in theme CSS. Components consume tokens, never hardcode colours.
## 6. Asset Strategy (M2)
## 6. Asset Strategy (M1)
- No jQuery for new code (vanilla JS; `theme.js:1` is deferred). WC jQuery remains for its handlers.
- Enqueue: `tokens→base→layout→components→utilities→style.css` chain in `inc/setup/assets.php:1` with version `XSHOP_VERSION`; `style.css` declares `rtl` replace. WC styles dequeued (`woocommerce_enqueue_styles` → `__return_empty_array`) to avoid duplication — theme provides compat in `components.css:1`.
- Conditional: feature modules (search/filter/wishlist) will be enqueued per-template in M5; M1 only loads `theme.js`.
- Localized `xshopData` (restUrl, nonce, isRtl, i18n) on `xshop` handle.
- Build: no build step required to activate; release minify via `tools/build-release.ps1`.
- Vanilla JS: `theme.js` (deferred) + `product.js` (enqueued only on `is_product()` via `xshop_wc_single_setup` guard). No gallery framework, 40 lines, keyboard Arrow/Home/End.
- Enqueue: `tokens→base→layout→components→woo→utilities→style.css` chain in `inc/setup/assets.php:1` (`woo.css` **intentionally global** 12KB — replaces Woo's 3 stylesheets, avoids FOUC on shop/product/cart/account; documented, tiny vs conditional complexity). WC styles dequeued (`woocommerce_enqueue_styles → __return_empty_array`). `product.js` conditional, `comment-reply` conditional.
- Localized `xshopData` on `xshop` handle. No jQuery for theme code; Woo's jQuery remains for variations/add-to-cart.
- Build: `tools/build-release.ps1` now includes top-level folder `xshop/` wrapper (fixed in M1.1).
## 7. AJAX / REST
@@ -138,11 +134,17 @@ See `PERFORMANCE.md`. Conditional assets, lazy-load, transients for expensive qu
- Logical CSS, `dir` attribute toggling, `is_rtl()` branching only where logical props insufficient.
- Persian typography tokens, `lang="fa"` support, mixed LTR numbers handled via `unicode-bidi` where needed.
## 11. Templating (M1)
## 11. Templating (M2)
`header.php:1` renders `site-header.php:1` + `breadcrumbs:1` (except front/404); `footer.php:1` renders `site-footer.php:1`. All content templates (`index.php:1`, `front-page.php:1`, `single.php:1`, `page.php:1`, `archive.php:1`, `search.php:1`, `404.php:1`) use Loop + `get_template_part()` + `comments_template()` / `dynamic_sidebar()` where appropriate. Reusable components: `breadcrumbs`, `pagination`, `search-form`, `post-card`, `empty-state`, `loading`, `section-heading`, `hero`, `promo-banner`. No markup duplication. `front-page.php:1` is section-based (hero, category grid, product grid via `wc_get_products`, promo, latest posts) — extensible via `xshop_front_hero_args` filter.
`header.php` → `site-header` + breadcrumbs; `footer.php` → `site-footer`. Content templates use Loop + `get_template_part`. Reusable: `product-card.php:1` (WC_Product badges/price/rating, hook `xshop_product_card_after_actions`), `product-grid.php:1`, `product-gallery.php:1` (featured+thumbs, keyboard). `front-page.php` section-based via `xshop_front_hero_args`.
WC overrides: none in M1; wrappers via `woocommerce_before_main_content`/`after_main_content` in `inc/woocommerce/setup.php:1`. Future overrides documented in `docs/woocommerce.md` with version map.
**Woo overrides (4, all minimal, versioned):**
- `woocommerce/content-product.php` (3.6.0) — Why: grid/token alignment; Hooks/CSS insufficient (li.product markup). Minimal: single `<li>` + `get_template_part product-card`. Risk: Woo 3.6 → bump → re-check `wc_product_class`.
- `woocommerce/archive-product.php` (3.4.0) — Why: XShop header (category title/desc/count) + toolbar + empty-state CTA. Hooks could do header but empty-state needs override. Minimal.
- `woocommerce/content-single-product.php` (3.6.0) — Why: grid layout `.xshop-product` gallery+summary + custom gallery component. Hooks alone can't provide grid wrapper without CSS hacks. Minimal: wraps hooks, replaces `woocommerce_show_product_images`.
- `woocommerce/single-product.php` (1.6.4) — Delegator to `content-single-product.php`; kept for explicitness, could be removed (Woo default works) but retained for clarity.
All keep Woo hooks (`woocommerce_before_single_product`, `woocommerce_single_product_summary`, `woocommerce_after_single_product_summary` etc.) — no business logic rewrite. `inc/woocommerce/setup.php:1` handles `loop_start/end` filter (`xshop-products`), toolbar `woocommerce_before_shop_loop` 9/35, remove gallery, related args `posts_per_page 4 columns 4`.
## 12. Decision Records