################################################################################
# Step 1: Initialize a New Rails 7+ Application (if not already existing)      #
# This command sets up a new Rails project with default options,              #
# including `esbuild` for JavaScript and `tailwind` for CSS.                 #
# If you have an existing Rails application, skip this step.                 #
################################################################################
# rails new my_tailwind_app --css tailwind --javascript esbuild

################################################################################
# Step 2: Add cssbundling-rails and Tailwind CSS to an Existing Rails App      #
# If you started with `rails new --css tailwind`, this step is largely done. #
# Otherwise, execute these commands in your project's root directory.        #
################################################################################

# 2.1 Add cssbundling-rails gem to your Gemfile
# Add this line to your Gemfile:
# gem 'cssbundling-rails'
# Then run:
# bundle install

# 2.2 Install Tailwind CSS via cssbundling-rails installer
# This command sets up necessary files and dependencies.
bin/bundle add cssbundling-rails
bin/rails tailwind:install

################################################################################
# Step 3: Configure Tailwind CSS for Rails Integration                       #
# The `tailwind:install` command generates these files. Review and modify.   #
################################################################################

# 3.1 tailwind.config.js (located at your project root)
# This file configures Tailwind's content paths for purging unused CSS
# and allows extending Tailwind's default theme.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './public/*.html',
    './app/helpers/**/*.rb',
    './app/javascript/**/*.js',
    './app/views/**/*.{erb,haml,html,slim}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

# 3.2 postcss.config.js (located at your project root)
# This file tells PostCSS to use the Tailwind CSS plugin.

module.exports = {
  plugins: [
    require('tailwindcss'),
    require('autoprefixer'),
  ]
}

# 3.3 application.tailwind.css (located at app/assets/stylesheets)
# This is your main Tailwind CSS entry point. Import Tailwind's base styles here.

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Add any custom CSS here if absolutely necessary, but prefer Tailwind utilities */


################################################################################
# Step 4: Include Tailwind CSS in Your Rails Layout                          #
# Ensure your application layout links to the compiled Tailwind CSS.         #
################################################################################

# app/views/layouts/application.html.erb (or your primary layout file)

<!-- Before the closing </head> tag -->
<%= stylesheet_link_tag 'application', 'data-turbo-track': 'reload' %>
<%= stylesheet_link_tag 'application.tailwind', 'data-turbo-track': 'reload' %>

# Note: 'application' stylesheet_link_tag usually refers to Sprockets assets.
# 'application.tailwind' is specifically for the cssbundling-rails compiled output.
# Ensure 'application.tailwind' is present. If you're fully moving away from Sprockets,
# you might only need the `application.tailwind` link and adjust your asset pipeline config.

################################################################################
# Step 1: Start the Rails Server and Tailwind CSS Watcher                    #
# In development, you need two processes running concurrently.               #
################################################################################

# Terminal 1: Start Rails Server
# bin/rails server

# Terminal 2: Start Tailwind CSS in JIT (Just-In-Time) mode and watch for changes
# This command is typically managed by `cssbundling-rails` during development.
# It ensures Tailwind regenerates CSS rapidly as you add or modify classes.
# If you need to run it manually (e.g., in a background job or specific setup):
# yarn tailwindcss -i ./app/assets/stylesheets/application.tailwind.css -o ./app/assets/builds/application.tailwind.css --watch
# (Note: The exact command might vary slightly based on your `package.json` scripts)

################################################################################
# Step 2: Utilizing Tailwind CSS in Your Views and Components                #
# Apply utility classes directly within your HTML.                           #
################################################################################

<!-- Example: app/views/pages/home.html.erb -->

<div class="min-h-screen flex items-center justify-center bg-gradient-to-br from-indigo-500 to-purple-600">
  <div class="p-8 bg-white rounded-xl shadow-2xl space-y-6 text-center transform hover:scale-105 transition-transform duration-300 ease-in-out">
    <h1 class="text-4xl font-extrabold text-gray-900 leading-tight">Welcome, Computational Explorer!</h1>
    <p class="text-lg text-gray-700 max-w-md mx-auto">Forge new frontiers in software development with precision and innovation.</p>
    <button class="mt-6 px-8 py-3 bg-indigo-700 text-white font-semibold rounded-lg shadow-lg hover:bg-indigo-800 transition-colors duration-200">
      Explore Our Resources
    </button>
  </div>
</div>

################################################################################
# Step 3: Leveraging @apply for Component Abstraction (Advanced)             #
# For reusable components, @apply can encapsulate utility classes.           #
# Use sparingly; prefer direct utilities where possible.                     #
################################################################################

<!-- Example: app/assets/stylesheets/custom_components.css (imported into application.tailwind.css) -->

@layer components {
  .btn-primary {
    @apply px-6 py-3 bg-blue-600 text-white font-bold rounded-lg shadow-md hover:bg-blue-700 transition-colors;
  }
  .card-container {
    @apply p-6 bg-white rounded-lg shadow-lg;
  }
}

<!-- In your view -->
<button class="btn-primary">Submit</button>
<div class="card-container">
  <p>This is a card.</p>
</div>

################################################################################
# Step 4: Extending Tailwind's Theme (Advanced)                              #
# Customize colors, spacing, fonts, etc. in `tailwind.config.js`.            #
################################################################################

// tailwind.config.js (excerpt)

module.exports = {
  // ...
  theme: {
    extend: {
      colors: {
        'ruby-red': '#E02130',
        'dev-blue': '#1a73e8',
      },
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      fontFamily: {
        headline: ['"Press Start 2P"', 'cursive'],
      }
    },
  },
  // ...
}

<!-- In your view -->
<h1 class="text-ruby-red font-headline">My Custom Title</h1>

################################################################################
# Step 1: Ensure Production Compilation is Configured                        #
# `cssbundling-rails` automatically handles this during asset precompilation.#
# This means running `rails assets:precompile` will generate your optimized #
# Tailwind CSS for production, including purging unused styles.              #
################################################################################

# Configure Rails to serve compiled assets in production
# config/environments/production.rb
# config.assets.compile = false
# config.assets.digest = true

################################################################################
# Step 2: Review `tailwind.config.js` for Content Purging                    #
# Ensure the `content` array is exhaustive to avoid missing styles.          #
################################################################################

// tailwind.config.js (verify this for production)

module.exports = {
  content: [
    './public/*.html',
    './app/helpers/**/*.rb',
    './app/javascript/**/*.js',
    './app/views/**/*.{erb,haml,html,slim}',
    # Add any other paths where you might use Tailwind classes, e.g., custom Stimulus controllers
  ],
  // ...
}

################################################################################
# Step 3: Precompile Assets for Deployment                                   #
# This command generates optimized, purged CSS and JavaScript files.         #
################################################################################

# Run this command before deploying to production
RAILS_ENV=production bundle exec rails assets:precompile

################################################################################
# Step 4: Monitor and Debug Production Issues (if any)                       #
# Use browser developer tools to inspect compiled CSS.                       #
################################################################################

# Common Issue: Missing styles in production.
# Cause: `content` array in `tailwind.config.js` is incomplete.
# Solution: Add missing paths to `content` array, re-run `assets:precompile`.

# Common Issue: Large CSS file size.
# Cause: Purging not configured or ineffective.
# Solution: Double-check `content` array, ensure JIT is not accidentally running in production.

# Best Practice: Version Control and CI/CD Integration
# Integrate `assets:precompile` into your CI/CD pipeline to ensure
# production builds are consistently optimized.