view_component-contrib

To handle complex styling where one variant depends on another (e.g., a primary theme that looks different when the size is lg), you have two options:

1. Ruby Blocks: Pass the current variant values as block arguments to the variant definition for dynamic logic.
2. compound directive: Use a declarative approach to define styles that apply only when a specific combination of variant values is met.

# Option 1: Ruby Blocks
style do
  variants {
    size { sm { "text-sm" }; lg { "text-lg" } }
    theme {
      primary do |size:, **|
        %w[bg-blue-500 text-white].tap do
          _1 << "uppercase" if size == :lg
        end
      end
    }
  }
end

# Option 2: Compound directive
style do
  variants {
    size { sm { "text-sm" }; lg { "text-lg" } }
    theme { primary { %w[bg-blue-500 text-white] } }
  }
  compound(size: :lg, theme: :primary) { %w[uppercase] }
end

Since v0.2.0, ViewComponentContrib::StyleVariants allows you to define a schema for CSS classes (ideal for TailwindCSS) within your component class. You define base classes, variants (like color, size, or disabled), and defaults.

In your template, use the #style method to compile the classes based on the current component state.

Key behaviors:

• Boolean variants: Passing true or false automatically maps to yes or no variant keys.
• Nil values: Passing nil triggers the use of the defined defaults.
• Multiple sets: You can define multiple style sets (e.g., style :image do ... end) and call them specifically via style(:image, ...).
• Manual classes: Use the special class: key to append additional classes: style(size:, class: 'extra-class').

class ButtonComponent < ViewComponent::Base
  include ViewComponentContrib::StyleVariants

  style do
    base { %w[font-medium bg-blue-500 text-white rounded-full] }
    variants {
      color {
        primary { %w[bg-blue-500 text-white] }
        secondary { %w[bg-purple-500 text-white] }
      }
      size {
        sm { "text-sm" }
        md { "text-base" }
        lg { "px-4 py-3 text-lg" }
      }
      disabled {
        yes { "opacity-75" }
      }
    }
    defaults { {size: :md, color: :primary} }
  end

  def initialize(size: nil, color: nil, disabled: false)
    @size = size
    @color = color
    @disabled = disabled
  end
end

<button class="<%= style(size:, color:, disabled: true) %>">Click me</button>

To avoid global CSS collisions, use postcss-modules to generate unique, scoped class names. This allows you to use local names in your CSS and reference them in Ruby.

1. Install: yarn add postcss-modules.
2. Configure PostCSS: Set up generateScopedName to follow a convention: c-{identifier}-{name}. The identifier should match the Stimulus controller name.

PostCSS Config Example:

module.exports = {
  plugins: {
    'postcss-modules': {
      generateScopedName: (name, filename, _css) => {
        const matches = filename.match(/\/app\/frontend\/components\/?(.*)\/index.css$/);
        if (!matches) return name;
        const identifier = matches[1].replace("/", "--");
        return `c-${identifier}-${name}`;
      },
      getJSON: () => {}
    }
  }
}

3. Ruby Helper: Implement a class_for method in your ApplicationViewComponent to construct the scoped class name.

class ApplicationViewComponent
  private

  def identifier
    @identifier ||= self.class.name.sub("::Component", "").underscore.split("/").join("--")
  end

  def class_for(name, from: identifier)
    "c-" + from + "-" + name
  end
end

Usage in Template:

<div class="<%= class_for("container") %>">
  <p class="<%= class_for("body") %>"><%= text %></p>
</div>

Instead of using isolated localization files, you can use a namespacing convention to manage translations centrally. By default, translations should be placed under the <locale>.view_components.<component_scope> key in your YAML files.

Example YAML structure:

en:
  view_components:
    login_form:
      submit: "Log in"
    nav:
      user_info:
        login: "Log in"
        logout: "Log out"

Usage in templates: Use the standard t(".key") syntax within your component templates. The helper will automatically resolve the path based on the component's scope.

Setup: If you are using ViewComponentContrib::Base, translation support is included automatically. If you are inheriting directly from ViewComponent::Base, you must include the ViewComponentContrib::TranslationHelper module.

<!-- login_form/component.html.erb -->
<button type="submit"><%= t(".submit") %></button>

<!-- nav/user_info/component.html.erb -->
<a href="/logout"><%= t(".logout") %></a>