@spree/docs 0.1.294 → 0.1.295

package/dist/developer/customization/email-variables.md

@@ -42,7 +42,8 @@ Each object's fields, and the fields of the objects nested in it.
 
 ### `store`
 
-- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`
+- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`, `branding`
+- `store.branding`: `background_color`, `card_color`, `text_color`, `heading_color`, `accent_color` (empty unless the merchant set one), `link_color`, `button_color`, `button_text_color`, `button_border`, `font`, `font_family`, `heading_font_family`, `font_url` (a web font's stylesheet, empty for email-safe fonts)
 
 ### `order`
 

package/dist/developer/customization/emails.md

@@ -8,7 +8,7 @@ Every email Spree sends — order confirmations, shipping notices, password rese
 
 To change an email, you copy its template into your app and edit it. Nothing else changes: Spree still picks the recipient, the language and the sender, and delivers the email through your [SMTP provider](../providers/emails.md).
 
-> **NOTE:** Templates read plain data — the same fields the [Store API](../../api-reference/store-api/introduction.md) returns, plus what only an email needs — never Ruby objects. The same template can later run outside Ruby, and merchants will be able to edit templates safely from the dashboard.
+> **NOTE:** Templates read plain data — the same fields the [Store API](../../api-reference/store-api/introduction.md) returns, plus what only an email needs — never Ruby objects. The same template can run outside Ruby, and merchants can edit customer emails safely from the dashboard.
 
 ## Where templates live
 
@@ -102,6 +102,73 @@ In development and test, a variable that does not exist raises an error instead
 
 To look at every email with real data, open the mailer previews at `/rails/mailers` on your Spree server.
 
+## Templates merchants edit in the dashboard
+
+Merchants can edit the emails their customers receive in **Settings → Emails → Templates**, along with the layout and the shared blocks in `spree/shared`. An edit is saved as a draft and goes live when published; publishing renders it with the store's own data first and refuses a template that does not render. An email built from a record the store does not have yet, such as an order confirmation in a store with no orders, is checked for template syntax only. Staff, store-owner and seller emails are not editable and always render from files.
+
+A store's published template comes first, so the lookup for an editable email is:
+
+1. the store's published template in the email's language
+2. the store's published template for every language
+3. your app's file
+4. Spree's file
+
+Your file stays the default the dashboard starts from and reverts to, so overriding a template in code and letting merchants edit it work together. When a Spree upgrade or a change to your file alters a default a merchant has customized, the dashboard tells them and shows what changed.
+
+The same operations are open to integrations through the [Admin API](../../api-reference/admin-api/introduction.md), with the `email_templates` permission:
+
+**Admin SDK:**
+
+```typescript
+    const preview = await client.emailTemplates.preview('spree.order_mailer.confirm_email', {
+      body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+    })
+
+    await client.emailTemplates.draft.update('spree.order_mailer.confirm_email', {
+      body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+    })
+    await client.emailTemplates.publish('spree.order_mailer.confirm_email')
+    ```
+
+  **cURL:**
+
+```bash
+    curl -X PUT https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/draft \
+      -H "X-Spree-Api-Key: sk_xxx" -H "Content-Type: application/json" \
+      -d '{"body": "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>"}'
+
+    curl -X POST https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/publication \
+      -H "X-Spree-Api-Key: sk_xxx"
+    ```
+
+
+### Branding
+
+Merchants set the colors and font of their customer emails in **Settings → Emails**, without touching a template. Templates read them from [`store.branding`](email-variables.md#store), and Spree's layout uses them throughout. If you override the layout or a template, read colors and fonts from `store.branding` rather than writing them in, so a store's branding keeps applying.
+
+### Making your own customer email editable
+
+A customer email your app adds can be edited like Spree's own. Register it with a class that builds the data its preview renders with:
+
+```ruby server/config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.editable_email_templates.register(
+    'spree/review_mailer/request_email', kind: :email, sample: 'ReviewRequestSample'
+  )
+end
+```
+
+```ruby server/app/services/review_request_sample.rb
+# Previews with the store's latest completed order, or the one the merchant picks.
+class ReviewRequestSample < Spree::Emails::Samples::Order
+  def variables
+    { order: super[:order], review_url: placeholder_url('reviews/new') }
+  end
+end
+```
+
+A sample builds from the record the merchant picked, else the store's latest one; a store with none is told there is nothing to preview with yet. Pass placeholder URLs, never real tokens, and register only emails your customers receive.
+
 ## Your own mailers
 
 A mailer that inherits `Spree::BaseMailer` and renders its own ERB views with `mail` keeps working. Spree wraps its HTML in the same layout as every other email, so it carries the store's logo, header and footer. The `spree/shared/mailer_hero` and `spree/shared/mailer_button` partials are still there for those views.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.294",
+  "version": "0.1.295",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",