better_page 2.0.0

data/guide/02-building-index-page.md

@@ -0,0 +1,258 @@
+# Building an Index Page
+
+A complete guide to building feature-rich index pages.
+
+### Basic Index Page Structure
+
+```ruby
+class Products::IndexPage < IndexBasePage
+  def initialize(products, metadata = {})
+    @products = products
+    @user = metadata[:user]
+    super(products, metadata)
+  end
+
+  private
+
+  def header
+    { title: "Products" }
+  end
+
+  def table
+    { items: @products, columns: table_columns }
+  end
+end
+```
+
+--------------------------------
+
+### Adding Breadcrumbs
+
+```ruby
+def header
+  {
+    title: "Products",
+    breadcrumbs: [
+      { label: "Home", path: root_path },
+      { label: "Admin", path: admin_root_path },
+      { label: "Products" }
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Adding Header Actions
+
+```ruby
+def header
+  {
+    title: "Products",
+    actions: [
+      { label: "Export", path: export_products_path, icon: "download", style: :secondary },
+      { label: "New Product", path: new_product_path, icon: "plus", style: :primary }
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Defining Table Columns
+
+```ruby
+def table
+  {
+    items: @products,
+    columns: [
+      { key: :name, label: "Name", type: :link, path: ->(p) { product_path(p) } },
+      { key: :category, label: "Category", type: :badge },
+      { key: :price, label: "Price", format: :currency },
+      { key: :stock, label: "Stock", type: :number },
+      { key: :active, label: "Status", type: :boolean },
+      { key: :created_at, label: "Created", format: :date }
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Adding Row Actions
+
+```ruby
+def table
+  {
+    items: @products,
+    columns: table_columns,
+    actions: ->(product) {
+      [
+        { label: "Edit", path: edit_product_path(product), icon: "edit" },
+        { label: "Delete", path: product_path(product), method: :delete, icon: "trash", confirm: "Are you sure?" }
+      ]
+    }
+  }
+end
+```
+
+--------------------------------
+
+### Configuring Empty State
+
+```ruby
+def table
+  {
+    items: @products,
+    columns: table_columns,
+    empty_state: {
+      icon: "box",
+      title: "No products yet",
+      message: "Create your first product to get started",
+      action: {
+        label: "New Product",
+        path: new_product_path,
+        style: :primary
+      }
+    }
+  }
+end
+```
+
+--------------------------------
+
+### Adding Statistics
+
+```ruby
+def statistics
+  [
+    { label: "Total Products", value: @products.size, icon: "box", color: "blue" },
+    { label: "Active", value: @products.count(&:active?), icon: "check", color: "green" },
+    { label: "Out of Stock", value: @products.count { |p| p.stock.zero? }, icon: "alert", color: "red" },
+    { label: "Total Value", value: format_currency(@products.sum(&:price)), icon: "dollar", color: "purple" }
+  ]
+end
+```
+
+--------------------------------
+
+### Adding Pagination
+
+```ruby
+def pagination
+  {
+    enabled: true,
+    page: @products.current_page,
+    total_pages: @products.total_pages,
+    total_count: @products.total_count,
+    per_page: @products.limit_value
+  }
+end
+```
+
+--------------------------------
+
+### Adding Search
+
+```ruby
+def search
+  {
+    enabled: true,
+    placeholder: "Search products...",
+    fields: [:name, :category, :sku]
+  }
+end
+```
+
+--------------------------------
+
+### Adding Tabs
+
+```ruby
+def tabs
+  {
+    enabled: true,
+    items: [
+      { label: "All", path: products_path, active: @filter == :all },
+      { label: "Active", path: products_path(filter: :active), active: @filter == :active },
+      { label: "Inactive", path: products_path(filter: :inactive), active: @filter == :inactive }
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Complete Index Page Example
+
+```ruby
+class Products::IndexPage < IndexBasePage
+  def initialize(products, metadata = {})
+    @products = products
+    @user = metadata[:user]
+    @filter = metadata[:filter] || :all
+    super(products, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: "Products",
+      breadcrumbs: [{ label: "Home", path: root_path }, { label: "Products" }],
+      actions: header_actions
+    }
+  end
+
+  def table
+    {
+      items: @products,
+      columns: table_columns,
+      actions: row_actions,
+      empty_state: empty_config
+    }
+  end
+
+  def statistics
+    [
+      { label: "Total", value: @products.size, icon: "box" },
+      { label: "Active", value: @products.count(&:active?), icon: "check", color: "green" }
+    ]
+  end
+
+  def pagination
+    { enabled: true, page: @products.current_page, total_pages: @products.total_pages }
+  end
+
+  def tabs
+    {
+      enabled: true,
+      items: [
+        { label: "All", path: products_path, active: @filter == :all },
+        { label: "Active", path: products_path(filter: :active), active: @filter == :active }
+      ]
+    }
+  end
+
+  # Private helper methods
+  def header_actions
+    [{ label: "New Product", path: new_product_path, icon: "plus", style: :primary }]
+  end
+
+  def table_columns
+    [
+      { key: :name, label: "Name", type: :link },
+      { key: :price, label: "Price", format: :currency },
+      { key: :stock, label: "Stock" }
+    ]
+  end
+
+  def row_actions
+    ->(p) { [{ label: "Edit", path: edit_product_path(p), icon: "edit" }] }
+  end
+
+  def empty_config
+    { icon: "box", title: "No products", message: "Create your first product" }
+  end
+end
+```

data/guide/03-building-show-page.md

@@ -0,0 +1,266 @@
+# Building a Show Page
+
+A complete guide to building detail pages with content sections.
+
+### Basic Show Page Structure
+
+```ruby
+class Products::ShowPage < ShowBasePage
+  def initialize(product, metadata = {})
+    @product = product
+    @user = metadata[:user]
+    super(product, metadata)
+  end
+
+  private
+
+  def header
+    { title: @product.name }
+  end
+end
+```
+
+--------------------------------
+
+### Adding Header with Actions
+
+```ruby
+def header
+  {
+    title: @product.name,
+    breadcrumbs: [
+      { label: "Products", path: products_path },
+      { label: @product.name }
+    ],
+    actions: [
+      action_format(path: edit_product_path(@product), label: "Edit", icon: "edit", style: "secondary"),
+      action_format(path: product_path(@product), label: "Delete", icon: "trash", style: "danger", method: :delete, confirm: "Delete this product?")
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Using action_format Helper
+
+Build action buttons with the helper method.
+
+```ruby
+action_format(
+  path: edit_product_path(@product),
+  label: "Edit",
+  icon: "edit",
+  style: "primary"  # primary, secondary, danger, warning
+)
+```
+
+--------------------------------
+
+### Adding Statistics
+
+```ruby
+def statistics
+  [
+    statistic_format(label: "Price", value: format_currency(@product.price), icon: "dollar", color: "green"),
+    statistic_format(label: "Stock", value: @product.stock, icon: "box", color: "blue"),
+    statistic_format(label: "Orders", value: @product.orders_count, icon: "shopping-cart", color: "purple"),
+    statistic_format(label: "Rating", value: "#{@product.rating}/5", icon: "star", color: "yellow")
+  ]
+end
+```
+
+--------------------------------
+
+### Using statistic_format Helper
+
+Build statistic cards with the helper method.
+
+```ruby
+statistic_format(
+  label: "Total Sales",
+  value: 1234,
+  icon: "chart",
+  color: "blue"  # blue, green, red, yellow, purple
+)
+```
+
+--------------------------------
+
+### Adding Content Sections - Info Grid
+
+```ruby
+def content_sections
+  [
+    content_section_format(
+      title: "Product Details",
+      icon: "info",
+      color: "blue",
+      type: :info_grid,
+      content: {
+        "SKU" => @product.sku,
+        "Category" => @product.category,
+        "Brand" => @product.brand,
+        "Weight" => "#{@product.weight} kg",
+        "Dimensions" => @product.dimensions,
+        "Created" => @product.created_at.strftime("%B %d, %Y")
+      }
+    )
+  ]
+end
+```
+
+--------------------------------
+
+### Adding Content Sections - Text
+
+```ruby
+def content_sections
+  [
+    content_section_format(
+      title: "Description",
+      icon: "text",
+      color: "gray",
+      type: :text,
+      content: @product.description
+    )
+  ]
+end
+```
+
+--------------------------------
+
+### Using content_section_format Helper
+
+Build content sections with the helper method.
+
+```ruby
+content_section_format(
+  title: "Section Title",
+  icon: "info",          # icon name
+  color: "blue",         # blue, green, red, gray
+  type: :info_grid,      # :info_grid or :text
+  content: { "Key" => "Value" }  # Hash for info_grid, String for text
+)
+```
+
+--------------------------------
+
+### Using info_grid_content_format Helper
+
+Convert hash to info grid array format.
+
+```ruby
+info_grid_content_format({ "Name" => "John", "Email" => "john@example.com" })
+# => [{ name: "Name", value: "John" }, { name: "Email", value: "john@example.com" }]
+```
+
+--------------------------------
+
+### Adding Multiple Content Sections
+
+```ruby
+def content_sections
+  [
+    content_section_format(
+      title: "Product Details",
+      icon: "info",
+      color: "blue",
+      type: :info_grid,
+      content: product_details_content
+    ),
+    content_section_format(
+      title: "Description",
+      icon: "text",
+      color: "gray",
+      type: :text,
+      content: @product.description
+    ),
+    content_section_format(
+      title: "Shipping Information",
+      icon: "truck",
+      color: "green",
+      type: :info_grid,
+      content: shipping_content
+    )
+  ]
+end
+
+def product_details_content
+  {
+    "SKU" => @product.sku,
+    "Category" => @product.category,
+    "Brand" => @product.brand
+  }
+end
+
+def shipping_content
+  {
+    "Weight" => "#{@product.weight} kg",
+    "Dimensions" => @product.dimensions,
+    "Ships From" => @product.warehouse
+  }
+end
+```
+
+--------------------------------
+
+### Complete Show Page Example
+
+```ruby
+class Products::ShowPage < ShowBasePage
+  def initialize(product, metadata = {})
+    @product = product
+    @user = metadata[:user]
+    super(product, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: @product.name,
+      breadcrumbs: [{ label: "Products", path: products_path }, { label: @product.name }],
+      actions: header_actions
+    }
+  end
+
+  def statistics
+    [
+      statistic_format(label: "Price", value: format_currency(@product.price), icon: "dollar", color: "green"),
+      statistic_format(label: "Stock", value: @product.stock, icon: "box", color: "blue"),
+      statistic_format(label: "Orders", value: @product.orders_count, icon: "cart", color: "purple")
+    ]
+  end
+
+  def content_sections
+    [
+      content_section_format(
+        title: "Details",
+        icon: "info",
+        color: "blue",
+        type: :info_grid,
+        content: { "SKU" => @product.sku, "Category" => @product.category }
+      ),
+      content_section_format(
+        title: "Description",
+        icon: "text",
+        color: "gray",
+        type: :text,
+        content: @product.description
+      )
+    ]
+  end
+
+  def header_actions
+    [
+      action_format(path: edit_product_path(@product), label: "Edit", icon: "edit", style: "secondary"),
+      action_format(path: product_path(@product), label: "Delete", icon: "trash", style: "danger", method: :delete)
+    ]
+  end
+
+  def format_currency(amount)
+    "$#{amount.to_f.round(2)}"
+  end
+end
+```