@spree/docs 0.1.0 → 0.1.2

package/dist/developer/storefront/blocks.md

@@ -1,285 +0,0 @@
----
-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

@@ -1,260 +0,0 @@
----
-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

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

@@ -1,166 +0,0 @@
----
-title: "Custom JavaScript for Spree Storefront"
-sidebarTitle: "Custom JavaScript"
-description: "Learn how to add custom JavaScript to your Spree storefront"
----
-
-## Extending Storefront with JavaScript
-
-Spree Storefront can be easily extended with custom JavaScript. Most of the JavaScript in the storefront is powered by a framework called [Stimulus.js](https://stimulus.hotwired.dev/) which is the Ruby on Rails default. It's a very simple and minimalistic framework only enhancing our server-side rendered HTML with a bit of interactivity.
-
-### 3rd party JavaScript libraries
-
-Spree Storefront comes with a few 3rd party JavaScript libraries already included.
-
-Main libraries we're using:
-
-* [Stimulus.js](https://stimulus.hotwired.dev/)
-* [Turbo](https://turbo.hotwired.dev/)
-* [Swiper.js](https://swiper.com/)
-* [PhotoSwipe](https://photoswipe.com/)
-* [noUISlider](https://refreshless.com/nouislider/)
-* [card-validator](https://github.com/braintree/card-validator) and [credit-card-type](https://github.com/braintree/credit-card-type)
-
-You can find them in the [app/assets/javascripts/vendor](https://github.com/spree/spree/blob/main/storefront/vendor/javascript) directory.
-
-### Managing JavaScript dependencies
-
-You're probably wondering why these libraries are in the `vendor` directory, and not in `node_modules`.
-
-That's because we're not using Node.js at all. So no Yarn or npm. We're using a different approach to manage dependencies.
-
-We're using a tool called [Importmaps](https://github.com/rails/importmap-rails) to manage dependencies which is the Ruby on Rails default.
-
-> **INFO:** If you want to use a different JavaScript package manager you can do so by using [jsbundling-rails](https://github.com/rails/jsbundling-rails) gem.
-
-#### Install dependencies
-
-To install dependencies you need to run the following command:
-
-```bash
-bin/importmap pin react
-```
-
-This will install the dependencies, download the files to your `vendor/javascript` directory and add them to your `config/importmap.rb` file, eg.
-
-```ruby
-pin "react" # @19.1.0
-```
-
-Now you can just import the library in your application entry point, eg. `application.js`:
-
-```js
-import "react";
-```
-
-### Application entry point
-
-Mentioned above, the application entry point is the `application.js` file. It's located in the `app/javascript` directory.
-
-If you want to add custom JavaScript to your Spree storefront, you can do so by adding a new file to the `app/javascript` directory.
-
-### Stimulus Controllers
-
-Stimulus controllers are a way to add interactivity to your Spree storefront. Storefront controllers can be found in the Spree repository in the [storefront/app/javascript/spree/storefront/controllers](https://github.com/spree/spree/tree/main/storefront/app/javascript/spree/storefront/controllers) directory.
-
-You can find more information about Stimulus controllers in the [Stimulus.js documentation](https://stimulus.hotwired.dev/handbook/controllers).
-
-To add a new controller you need to create a new file in the `app/javascript/controllers` directory. It will be automatically picked up by the application.
-
-```js
-// app/javascript/controllers/hello_controller.js
-import { Controller } from '@hotwired/stimulus'
-
-export default class extends Controller {
-  connect() {
-    console.log("Hello Spree Commerce Stimulus!", this.element);
-  }
-}
-```
-
-To use the controller in your HTML you need to add the `data-controller` attribute to your element, eg.
-
-```html
-<div data-controller="hello">
-  Hello Spree Commerce Stimulus!
-</div>
-```
-
-## JavaScript snippets
-
-If you need to add a small piece of JavaScript code (eg. tracking, marketing, analytics, customer service etc.) you can do this by:
-
-1. Declaring a new head partial in the `config/initializers/spree.rb` file, eg.
-
-    **Spree 5.2+:**
-
-```ruby config/initializers/spree.rb
-        Rails.application.config.after_initialize do
-          Spree.storefront.partials.head << 'spree/shared/my_tracking_code'
-        end
-        ```
-
-      **Spree 5.1 and below:**
-
-```ruby config/initializers/spree.rb
-        Rails.application.config.spree_storefront.head_partials << 'spree/shared/my_tracking_code'
-        ```
-
-
-2. Creating a new file in the `app/views/spree/shared/my_tracking_code.html.erb`, where you can add your tracking code, eg.
-
-    ```erb app/views/spree/shared/my_tracking_code.html.erb
-    <script>
-      console.log("I'm a spy!");
-    </script>
-    ```
-
-> **INFO:** Check out the [Integrations](/integrations) for existing integrations you can plug into your storefront.
-
-## Extending Existing Stimulus Controllers
-
-You can extend or override existing Storefront Stimulus controllers:
-
-```js
-// app/javascript/controllers/cart_controller.js
-
-export default class extends CartController {
-  connect() {
-    super.connect()
-    console.log('Extended cart controller connected!')
-  }
-
-  // Override existing method
-  addItem(event) {
-    // Custom logic before adding
-    console.log('Adding item...')
-    super.addItem(event)
-    // Custom logic after adding
-  }
-}
-```
-
-## Turbo Events
-
-Spree Storefront uses [Turbo](https://turbo.hotwired.dev/) for navigation. You can hook into Turbo events:
-
-```js
-// app/javascript/application.js
-document.addEventListener('turbo:load', () => {
-  console.log('Page loaded via Turbo')
-})
-
-document.addEventListener('turbo:before-visit', (event) => {
-  console.log('About to visit:', event.detail.url)
-})
-
-document.addEventListener('turbo:frame-load', (event) => {
-  console.log('Turbo frame loaded:', event.target.id)
-})
-```
-
-## Related Documentation
-
-- [Custom CSS](/developer/storefront/custom-css) - Styling your storefront
-- [Sections](/developer/storefront/sections) - Creating custom sections
-- [Blocks](/developer/storefront/blocks) - Creating custom blocks