@spree/docs 0.1.0

package/dist/developer/sdk/store/wishlists.md

@@ -0,0 +1,52 @@
+---
+title: Wishlists
+description: Manage wishlists and wished items with the Spree SDK
+---
+
+## Wishlists
+
+```typescript
+const options = { token: jwtToken };
+
+// List wishlists
+const { data: wishlists } = await client.wishlists.list({}, options);
+
+// Get wishlist by ID
+const wishlist = await client.wishlists.get('wl_xxx', {
+  expand: ['wished_items'],
+}, options);
+
+// Create wishlist
+const newWishlist = await client.wishlists.create({
+  name: 'Birthday Ideas',
+  is_private: true,
+}, options);
+
+// Update wishlist
+await client.wishlists.update('wl_xxx', {
+  name: 'Updated Name',
+}, options);
+
+// Delete wishlist
+await client.wishlists.delete('wl_xxx', options);
+```
+
+## Wishlist Items
+
+```typescript
+const options = { token: jwtToken };
+
+// Add item to wishlist
+await client.wishlists.items.create('wl_xxx', {
+  variant_id: 'var_123',
+  quantity: 1,
+}, options);
+
+// Update item quantity
+await client.wishlists.items.update('wl_xxx', 'wi_xxx', {
+  quantity: 2,
+}, options);
+
+// Remove item from wishlist
+await client.wishlists.items.delete('wl_xxx', 'wi_xxx', options);
+```

package/dist/developer/security/pci_compliance.md

@@ -0,0 +1,15 @@
+---
+title: "PCI Compliance"
+---
+
+All store owners wishing to process credit card transactions should be familiar with [PCI Compliance](http://en.wikipedia.org/wiki/Pci_compliance). All officially supported payment gateways — [Spree Stripe](https://github.com/spree/spree_stripe), [Spree Adyen](https://github.com/spree/spree_adyen), and [Spree PayPal Checkout](https://github.com/spree/spree_paypal_checkout) — are fully PCI-compliant.
+
+## Using payment tokens
+
+We do not transmit or store Credit Card numbers. Instead we're using payment processor tokens supplied by their SDKs to authorize and charge customer cards. Sensitive payment data is collected directly by the gateway's frontend SDK (e.g., Stripe.js, Adyen Drop-in) and never touches your server.
+
+## 3-D Secure and Strong Customer Authentication support
+
+[Spree Stripe integration](https://github.com/spree/spree_stripe) supports [Strong Customer Authentication (SCA)](https://stripe.com/en-pl/guides/strong-customer-authentication) out of the box. We also use Stripe JavaScript SDK to render all payment forms.
+
+[Spree Adyen integration](https://github.com/spree/spree_adyen) supports 3D Secure 2.0 through the Adyen Drop-in component.

package/dist/developer/security/security_policy.md

@@ -0,0 +1,68 @@
+---
+title: "Security Policy"
+description: "How to report vulnerabilities, supported versions, and Spree's security practices."
+---
+
+## Overview
+
+Proper application design, intelligent programming, and secure infrastructure are all essential in creating a secure e-commerce store using any software (Spree included). The Spree team has done its best to provide you with the tools to create a secure and profitable web presence, but it is up to you to take these tools and put them in good practice. We highly recommend reading and understanding the [Rails Security Guide](https://guides.rubyonrails.org/security.html).
+
+## Supported Versions
+
+The following versions are actively maintained and receive security patches.
+
+| Version | Release date | End of life |
+| ------- | ------------ | ----------- |
+| 5.0     | 26.03.2025   | 26.03.2028  |
+| 4.10    | 06.09.2024   | 06.09.2027  |
+
+If you're using an older version [please upgrade](../upgrades/). Have trouble upgrading? [Contact us for support](https://spreecommerce.org/contact/).
+
+**Versions that are not listed above will not receive any security patches or fixes.**
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+Instead, please send an email to [security@spreecommerce.org](mailto:security@spreecommerce.org).
+
+Please include as much of the following information as possible to help us triage your report:
+
+- Type of vulnerability (e.g. SQL injection, XSS, CSRF, etc.)
+- Affected version(s)
+- Step-by-step instructions to reproduce the issue
+- Proof of concept or exploit code (if available)
+- Impact assessment of the vulnerability
+
+### Submitting a Patch
+
+If you would like to provide a patch yourself for the security issue **do not open a pull request for it**. Instead, create a commit on your fork of Spree and run this command:
+
+```bash
+git format-patch HEAD~1..HEAD --stdout > patch.txt
+```
+
+Email a description of the patch along with the `patch.txt` file to [security@spreecommerce.org](mailto:security@spreecommerce.org).
+
+### Disclosure Process
+
+1. Security report is received and acknowledged within **48 hours**.
+2. The issue is confirmed and a severity level is assigned.
+3. A fix is developed and tested against all supported versions.
+4. A new release is published with the fix and a [GitHub Security Advisory](https://github.com/spree/spree/security/advisories) is created.
+5. Reporter is credited in the advisory (unless anonymity is requested).
+
+### Security Advisories
+
+Published security advisories can be found at [GitHub Security Advisories](https://github.com/spree/spree/security/advisories).
+
+## Security Best Practices
+
+Spree is built on **Ruby on Rails** which provides strong security defaults including protection against SQL injection, CSRF, and XSS. For more details on how Spree handles security in production environments, see the [Enterprise Security Overview](/user/security).
+
+We recommend:
+
+- Keeping Spree and all dependencies up to date
+- Following the [Rails Security Guide](https://guides.rubyonrails.org/security.html)
+- Using [bundler-audit](https://github.com/rubysec/bundler-audit) to scan for known vulnerabilities in dependencies
+- Running [brakeman](https://github.com/presidentbeef/brakeman) for static security analysis

package/dist/developer/storefront/blocks.md

@@ -0,0 +1,285 @@
+---
+title: "Blocks"
+description: "Learn how to utilize blocks to build your Spree Storefront"
+---
+
+Blocks are the lowest level of components in Spree Storefront. They are nested inside [sections](/developer/storefront/sections) and represent individual content elements like headings, text, buttons, and images.
+
+## How Blocks Work
+
+Each section can contain multiple blocks that store staff can manage through the Page Builder:
+
+- Add new blocks
+- Edit block content and settings
+- Reorder blocks via drag-and-drop
+- Remove blocks
+
+Not all sections support blocks. A section must explicitly enable block support by implementing `blocks_available?` and `available_blocks_to_add` methods.
+
+## Built-in Block Types
+
+Spree comes with several built-in block types:
+
+### Content Blocks
+
+| Block | Description | Class |
+|-------|-------------|-------|
+| Heading | Large text headings | [Spree::PageBlocks::Heading](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/heading.rb) |
+| Subheading | Smaller secondary headings | [Spree::PageBlocks::Subheading](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/subheading.rb) |
+| Text | Rich text content | [Spree::PageBlocks::Text](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/text.rb) |
+| Buttons | Call-to-action buttons with links | [Spree::PageBlocks::Buttons](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/buttons.rb) |
+| Image | Image with optional link | [Spree::PageBlocks::Image](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/image.rb) |
+
+### Navigation Blocks
+
+| Block | Description | Class |
+|-------|-------------|-------|
+| Nav | Simple navigation links | [Spree::PageBlocks::Nav](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/nav.rb) |
+| Mega Nav | Mega menu navigation | [Spree::PageBlocks::MegaNav](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/mega_nav.rb) |
+| Link | Single link item | [Spree::PageBlocks::Link](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/link.rb) |
+
+### Product Blocks
+
+These blocks are used in the Product Details section:
+
+| Block | Description | Class |
+|-------|-------------|-------|
+| Title | Product title | [Spree::PageBlocks::Products::Title](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/title.rb) |
+| Price | Product price display | [Spree::PageBlocks::Products::Price](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/price.rb) |
+| Description | Product description | [Spree::PageBlocks::Products::Description](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/description.rb) |
+| Variant Picker | Size/color selector | [Spree::PageBlocks::Products::VariantPicker](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/variant_picker.rb) |
+| Quantity Selector | Quantity input | [Spree::PageBlocks::Products::QuantitySelector](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/quantity_selector.rb) |
+| Buy Buttons | Add to cart button | [Spree::PageBlocks::Products::BuyButtons](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/buy_buttons.rb) |
+| Share | Social sharing buttons | [Spree::PageBlocks::Products::Share](https://github.com/spree/spree/blob/main/core/app/models/spree/page_blocks/products/share.rb) |
+
+## Architecture
+
+### Base Class
+
+All blocks inherit from [Spree::PageBlock](https://github.com/spree/spree/blob/main/core/app/models/spree/page_block.rb):
+
+```ruby
+module Spree
+  class PageBlock < Spree.base_class
+    include Spree::HasPageLinks
+
+    belongs_to :section, class_name: 'Spree::PageSection'
+
+    has_rich_text :text
+    has_one_attached :asset
+
+    # Default preferences
+    preference :text_alignment, :string, default: 'left'
+    preference :container_alignment, :string, default: 'left'
+    preference :size, :string, default: 'medium'
+    preference :width_desktop, :integer, default: 100
+    preference :top_padding, :integer, default: 0
+    preference :bottom_padding, :integer, default: 0
+  end
+end
+```
+
+### Default Preferences
+
+Every block has these default preferences:
+
+| Preference | Type | Default | Description |
+|------------|------|---------|-------------|
+| `text_alignment` | String | `left` | Text alignment (left, center, right) |
+| `container_alignment` | String | `left` | Container alignment |
+| `size` | String | `medium` | Block size (small, medium, large) |
+| `width_desktop` | Integer | `100` | Width percentage on desktop |
+| `top_padding` | Integer | `0` | Top padding in pixels |
+| `bottom_padding` | Integer | `0` | Bottom padding in pixels |
+
+### Associations
+
+- **Section**: Each block belongs to a section (`section`)
+- **Links**: Blocks can have multiple links (`links`) via `Spree::HasPageLinks`
+- **Asset**: Blocks can have an attached image (`asset`)
+- **Rich Text**: Blocks can have rich text content (`text`)
+
+## Accessing Blocks
+
+```ruby
+# Get all blocks for a section
+section.blocks
+
+# Get blocks with eager loading
+section.blocks.includes(:rich_text_text, :links)
+
+# Find specific block type
+section.blocks.where(type: 'Spree::PageBlocks::Heading')
+```
+
+## Rendering Blocks
+
+In storefront section views, blocks are rendered within their parent section:
+
+```erb
+<% section.blocks.each do |block| %>
+  <% case block.type %>
+  <% when 'Spree::PageBlocks::Heading' %>
+    <h2 <%= block_attributes(block) %>>
+      <%= block.text %>
+    </h2>
+  <% when 'Spree::PageBlocks::Text' %>
+    <div <%= block_attributes(block) %>>
+      <%= block.text %>
+    </div>
+  <% when 'Spree::PageBlocks::Buttons' %>
+    <div <%= block_attributes(block) %>>
+      <% if block.link %>
+        <%= page_builder_link_to block.link, class: 'btn-primary' %>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>
+```
+
+The `block_attributes(block)` helper returns data attributes needed for Page Builder editing.
+
+## Creating a Custom Block
+
+### Step 1: Create the Model
+
+```ruby app/models/spree/page_blocks/quote.rb
+module Spree
+  module PageBlocks
+    class Quote < Spree::PageBlock
+      SIZE_DEFAULT = 'large'
+      TEXT_ALIGNMENT_DEFAULT = 'center'
+
+      preference :author_name, :string
+      preference :author_title, :string
+      preference :text_color, :string
+      preference :background_color, :string
+
+      def icon_name
+        'quote'
+      end
+
+      def display_name
+        text.to_plain_text.truncate(30)
+      end
+    end
+  end
+end
+```
+
+### Step 2: Register the Block
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.page_builder.page_blocks += [
+    Spree::PageBlocks::Quote
+  ]
+end
+```
+
+### Step 3: Add to Section's Available Blocks
+
+In your section model, add the new block type:
+
+```ruby
+def available_blocks_to_add
+  [
+    Spree::PageBlocks::Heading,
+    Spree::PageBlocks::Text,
+    Spree::PageBlocks::Quote  # Your new block
+  ]
+end
+```
+
+### Step 4: Create Admin Form
+
+```erb app/views/spree/admin/page_blocks/forms/_quote.html.erb
+<div class="form-group">
+  <%= f.label :text, Spree.t(:quote_text) %>
+  <%= f.rich_text_area :text, data: { action: 'auto-submit#submit' } %>
+</div>
+
+<div class="form-group">
+  <%= f.label :preferred_author_name, Spree.t(:author_name) %>
+  <%= f.text_field :preferred_author_name,
+      class: 'form-control',
+      data: { action: 'auto-submit#submit' } %>
+</div>
+
+<div class="form-group">
+  <%= f.label :preferred_author_title, Spree.t(:author_title) %>
+  <%= f.text_field :preferred_author_title,
+      class: 'form-control',
+      data: { action: 'auto-submit#submit' } %>
+</div>
+```
+
+### Step 5: Render in Section View
+
+Add rendering logic to your section's storefront view:
+
+```erb
+<% when 'Spree::PageBlocks::Quote' %>
+  <blockquote <%= block_attributes(block) %> class="text-<%= block.preferred_text_alignment %>">
+    <p class="text-xl italic"><%= block.text %></p>
+    <% if block.preferred_author_name.present? %>
+      <footer class="mt-4">
+        <cite>
+          <strong><%= block.preferred_author_name %></strong>
+          <% if block.preferred_author_title.present? %>
+            <br><span class="text-sm text-gray-500"><%= block.preferred_author_title %></span>
+          <% end %>
+        </cite>
+      </footer>
+    <% end %>
+  </blockquote>
+```
+
+## Block with Links
+
+To add link support to your block, include the `Spree::HasOneLink` concern:
+
+```ruby
+module Spree
+  module PageBlocks
+    class CallToAction < Spree::PageBlock
+      include Spree::HasOneLink
+
+      preference :button_style, :string, default: 'primary'
+
+      # Called when the link is destroyed
+      def link_destroyed(_link)
+        destroy if page_links_count.zero?
+      end
+    end
+  end
+end
+```
+
+## Block with Image
+
+Blocks automatically have an `asset` attachment available:
+
+```ruby
+# Check if image is attached
+block.asset.attached?
+
+# Display image in view
+<% if block.asset.attached? %>
+  <%= spree_image_tag block.asset, width: 400, height: 300 %>
+<% end %>
+```
+
+## Key Methods
+
+| Method | Description |
+|--------|-------------|
+| `display_name` | Name shown in Page Builder sidebar |
+| `icon_name` | Icon from [Tabler Icons](https://tabler.io/icons) |
+| `form_partial_name` | Name of the admin form partial |
+
+## Related Documentation
+
+- [Sections](/developer/storefront/sections) - Parent containers for blocks
+- [Links](/developer/storefront/links) - Adding links to blocks
+- [Media](/developer/core-concepts/media) - Working with images

package/dist/developer/storefront/custom-css.md

@@ -0,0 +1,260 @@
+---
+title: "Custom CSS for Spree Storefront"
+sidebarTitle: "Custom CSS"
+description: "Learn how to add custom CSS stylesheets to your Spree storefront"
+---
+
+Spree Storefront is built on top of [Tailwind CSS 4](https://tailwindcss.com/). After installing Spree you should find a main CSS file:
+
+* [app/assets/tailwind/application.css](https://github.com/spree/spree/blob/main/storefront/lib/generators/spree/storefront/install/templates/application.css) - This is the main CSS file that imports Tailwind and adds storefront styles
+
+If you're missing this file, or migrating from a previous version of Spree, you can generate it using the following command:
+
+```bash
+bin/rails g spree:storefront:install
+```
+
+> **INFO:** Tailwind 4 uses a CSS-first configuration approach. There's no `tailwind.config.js` file - all configuration is done directly in CSS using the `@theme` directive.
+
+## Basic Structure
+
+Your [application.css](https://github.com/spree/spree/blob/main/storefront/lib/generators/spree/storefront/install/templates/application.css) file should look something like this:
+
+```css app/assets/tailwind/application.css
+@import "tailwindcss";
+
+@theme {
+  /* Theme customizations go here */
+}
+
+/* Your custom styles */
+```
+
+## Importing Additional CSS Files
+
+Create a new CSS file in the `app/assets/stylesheets` directory:
+
+```bash
+touch app/assets/tailwind/my_custom_styles.css
+```
+
+In the `my_custom_styles.css` file, add your styles:
+
+```css
+.my-custom-class {
+  color: red;
+}
+```
+
+Then import it in your `application.css` file:
+
+```css app/assets/tailwind/application.css
+@import "tailwindcss";
+@import "my_custom_styles.css"; /* [!code ++] */
+```
+
+## Importing 3rd Party CSS Libraries
+
+You can import a 3rd party CSS library directly from a CDN:
+
+```css app/assets/tailwind/application.css
+@import "tailwindcss";
+@import url("https://esm.sh/swiper@11.2.2/swiper-bundle.min.css"); /* [!code ++] */
+```
+
+## CSS Variables
+
+Spree Storefront uses CSS variables that are automatically injected into the page. This allows store owners to change colors, fonts, etc. from the admin dashboard via Page Builder.
+
+The default variables look like this:
+
+```css app/assets/tailwind/application.css
+:root {
+  --primary: #000000;
+  --accent: #F0EFE9;
+  --danger: #C73528;
+  --success: #00C773;
+  --neutral: #999999;
+
+  --background: #FFFFFF;
+  --text: #000000;
+
+  --border-default-color: #E9E7DC;
+  --border-default-width: 1px;
+  --border-default-radius: 6px;
+
+  --button: #000000;
+  --button-rgb: 0, 0, 0;
+  --button-text: #ffffff;
+  --button-border-radius: 100px;
+  --button-border-width: 1px;
+  --button-border-color: ;
+
+  --button-hover: #000000;
+  --button-hover-text: #ffffff;
+
+  --secondary-button: #FFFFFF;
+  --secondary-button-text: #000000;
+  --secondary-button-hover: #000000;
+  --secondary-button-hover-text: #FFFFFF;
+
+  --input: #E9E7DC;
+  --input-bg: #ffffff;
+  --input-text: #6b7280;
+  --input-focus-bg: #ffffff;
+  --input-border-radius: 8px;
+
+  --neutral-50: #F3F3F3;
+  --neutral-100: #EAEAEA;
+  --neutral-200: #D4D4D4;
+  --neutral-300: #B3B3B3;
+  --neutral-400: #999999;
+  --neutral-500: #808080;
+  --neutral-600: #666666;
+  --neutral-700: #4D4D4D;
+  --neutral-800: #333333;
+  --neutral-900: #1A1A1A;
+  --accent-100: #FBFAF8;
+}
+```
+
+They are defined in the [app/views/themes/default/spree/shared/_css_variables.html.erb](https://github.com/spree/spree/blob/main/storefront/app/views/themes/default/spree/shared/_css_variables.html.erb) file which should be present in your theme.
+
+## Customizing with @theme
+
+Tailwind 4 uses the `@theme` directive for customizations. You can extend or override the default theme:
+
+```css app/assets/tailwind/application.css
+@import "tailwindcss";
+
+@theme {
+  /* Add custom colors using Spree's CSS variables */
+  --color-primary: var(--primary);
+  --color-accent: var(--accent);
+  --color-danger: var(--danger);
+  --color-success: var(--success);
+
+  /* Add custom fonts */
+  --font-display: "Playfair Display", serif;
+
+  /* Add custom spacing */
+  --spacing-18: 4.5rem;
+
+  /* Add custom border radius */
+  --radius-button: var(--button-border-radius);
+}
+```
+
+Then use them in your templates:
+
+```erb
+<div class="bg-primary text-white font-display p-18 rounded-button">
+  Custom styled content
+</div>
+```
+
+## Overriding Section Styles
+
+Each section has CSS classes you can target to customize its appearance:
+
+```css
+/* Section container classes follow the pattern: section-{section-type} */
+.section-image-with-text {
+  /* Custom styles for Image with Text section */
+}
+
+.section-featured-taxon {
+  /* Custom styles for Featured Taxon section */
+}
+
+/* Block-specific styles within sections */
+.image-with-text--heading {
+  font-family: serif;
+}
+
+.rich-text--text {
+  line-height: 1.8;
+}
+```
+
+## Using Tailwind Utility Classes
+
+You can use Tailwind utility classes directly in your templates:
+
+```erb
+<div class="flex items-center gap-4 p-6 bg-accent rounded-lg">
+  <%= product.name %>
+</div>
+```
+
+### Arbitrary Values
+
+Tailwind 4 supports arbitrary values for one-off customizations:
+
+```erb
+<div class="p-[17px] bg-[#1a1a1a] text-[13px] grid-cols-[1fr_2fr]">
+  Custom values
+</div>
+```
+
+### Variant Modifiers
+
+Use variant modifiers for responsive and state-based styles:
+
+```erb
+<div class="p-4 md:p-6 lg:p-8 hover:bg-accent active:scale-95">
+  Responsive and interactive
+</div>
+```
+
+## Adding Custom Utilities
+
+You can add custom utilities using standard CSS with the `@utility` directive:
+
+```css
+@import "tailwindcss";
+
+@utility content-auto {
+  content-visibility: auto;
+}
+
+@utility scrollbar-hidden {
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+```
+
+Then use them like any other utility:
+
+```erb
+<div class="content-auto scrollbar-hidden">
+  <!-- Content -->
+</div>
+```
+
+## Adding Custom Variants
+
+Create custom variants with the `@variant` directive:
+
+```css
+@import "tailwindcss";
+
+@variant pointer-coarse (@media (pointer: coarse));
+@variant theme-dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+```
+
+Use them in your templates:
+
+```erb
+<button class="p-2 pointer-coarse:p-4 theme-dark:bg-gray-800">
+  Touch-friendly button
+</button>
+```
+
+## Related Documentation
+
+- [Themes](/developer/storefront/themes) - Theme settings and colors
+- [Custom JavaScript](/developer/storefront/custom-javascript) - Adding interactivity
+- [Tailwind CSS 4 Documentation](https://tailwindcss.com/docs) - Official Tailwind docs