better_page 2.0.0

data/guide/04-building-form-page.md

@@ -0,0 +1,309 @@
+# Building Form Pages
+
+A complete guide to building new and edit form pages.
+
+### Basic Form Page Structure
+
+```ruby
+class Products::NewPage < FormBasePage
+  def initialize(product, metadata = {})
+    @product = product
+    @user = metadata[:user]
+    super(product, metadata)
+  end
+
+  private
+
+  def header
+    { title: "New Product" }
+  end
+
+  def panels
+    [
+      panel_format(title: "Basic Info", fields: basic_fields)
+    ]
+  end
+end
+```
+
+--------------------------------
+
+### Adding Header with Description
+
+```ruby
+def header
+  {
+    title: "New Product",
+    description: "Create a new product in your catalog",
+    breadcrumbs: [
+      { label: "Products", path: products_path },
+      { label: "New" }
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Using field_format Helper
+
+Build form fields with the helper method.
+
+```ruby
+field_format(
+  name: :email,
+  type: :email,           # :text, :email, :password, :number, :textarea, :select, :checkbox, :radio
+  label: "Email Address",
+  required: true,
+  placeholder: "Enter email",
+  hint: "We'll never share your email"
+)
+```
+
+--------------------------------
+
+### Field Types
+
+```ruby
+# Text input
+field_format(name: :name, type: :text, label: "Name", required: true)
+
+# Email input
+field_format(name: :email, type: :email, label: "Email")
+
+# Password input
+field_format(name: :password, type: :password, label: "Password")
+
+# Number input
+field_format(name: :price, type: :number, label: "Price", min: 0, step: 0.01)
+
+# Textarea
+field_format(name: :description, type: :textarea, label: "Description", rows: 5)
+
+# Select dropdown
+field_format(name: :category, type: :select, label: "Category", options: category_options)
+
+# Checkbox
+field_format(name: :active, type: :checkbox, label: "Active")
+
+# Radio buttons
+field_format(name: :status, type: :radio, label: "Status", options: status_options)
+```
+
+--------------------------------
+
+### Using panel_format Helper
+
+Build form panels with the helper method.
+
+```ruby
+panel_format(
+  title: "Basic Information",
+  description: "Enter the product details",
+  fields: [
+    field_format(name: :name, type: :text, label: "Name", required: true),
+    field_format(name: :price, type: :number, label: "Price", required: true)
+  ]
+)
+```
+
+--------------------------------
+
+### Important: Separate Checkbox Panels
+
+Checkbox and radio fields MUST be in separate panels from text inputs.
+
+```ruby
+def panels
+  [
+    # Text inputs panel
+    panel_format(
+      title: "Product Details",
+      fields: [
+        field_format(name: :name, type: :text, label: "Name", required: true),
+        field_format(name: :price, type: :number, label: "Price"),
+        field_format(name: :category, type: :select, label: "Category", options: categories)
+      ]
+    ),
+    # Checkbox panel - MUST be separate
+    panel_format(
+      title: "Settings",
+      fields: [
+        field_format(name: :active, type: :checkbox, label: "Active"),
+        field_format(name: :featured, type: :checkbox, label: "Featured on Homepage")
+      ]
+    )
+  ]
+end
+```
+
+--------------------------------
+
+### Select Field with Options
+
+```ruby
+def panels
+  [
+    panel_format(
+      title: "Details",
+      fields: [
+        field_format(
+          name: :category_id,
+          type: :select,
+          label: "Category",
+          options: category_options,
+          include_blank: "Select a category"
+        )
+      ]
+    )
+  ]
+end
+
+def category_options
+  [
+    { value: 1, label: "Electronics" },
+    { value: 2, label: "Clothing" },
+    { value: 3, label: "Books" }
+  ]
+end
+```
+
+--------------------------------
+
+### Configuring Footer
+
+```ruby
+def footer
+  {
+    primary_action: {
+      label: "Save Product",
+      style: "primary"
+    },
+    secondary_actions: [
+      { label: "Cancel", path: products_path, style: "secondary" },
+      { label: "Save as Draft", action: :draft, style: "outline" }
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Edit Page Example
+
+```ruby
+class Products::EditPage < FormBasePage
+  def initialize(product, metadata = {})
+    @product = product
+    @user = metadata[:user]
+    super(product, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: "Edit #{@product.name}",
+      breadcrumbs: [
+        { label: "Products", path: products_path },
+        { label: @product.name, path: product_path(@product) },
+        { label: "Edit" }
+      ]
+    }
+  end
+
+  def panels
+    [
+      panel_format(title: "Product Details", fields: detail_fields),
+      panel_format(title: "Pricing", fields: pricing_fields),
+      panel_format(title: "Settings", fields: settings_fields)
+    ]
+  end
+
+  def detail_fields
+    [
+      field_format(name: :name, type: :text, label: "Name", required: true, value: @product.name),
+      field_format(name: :description, type: :textarea, label: "Description", value: @product.description)
+    ]
+  end
+
+  def pricing_fields
+    [
+      field_format(name: :price, type: :number, label: "Price", value: @product.price, min: 0),
+      field_format(name: :compare_price, type: :number, label: "Compare at Price", value: @product.compare_price)
+    ]
+  end
+
+  def settings_fields
+    [
+      field_format(name: :active, type: :checkbox, label: "Active", checked: @product.active?),
+      field_format(name: :featured, type: :checkbox, label: "Featured", checked: @product.featured?)
+    ]
+  end
+end
+```
+
+--------------------------------
+
+### Complete New Page Example
+
+```ruby
+class Products::NewPage < FormBasePage
+  def initialize(product, metadata = {})
+    @product = product
+    @user = metadata[:user]
+    @categories = metadata[:categories] || []
+    super(product, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: "New Product",
+      description: "Add a new product to your catalog",
+      breadcrumbs: [{ label: "Products", path: products_path }, { label: "New" }]
+    }
+  end
+
+  def panels
+    [
+      panel_format(
+        title: "Basic Information",
+        description: "Enter the product details",
+        fields: [
+          field_format(name: :name, type: :text, label: "Product Name", required: true),
+          field_format(name: :sku, type: :text, label: "SKU"),
+          field_format(name: :category_id, type: :select, label: "Category", options: category_options),
+          field_format(name: :description, type: :textarea, label: "Description", rows: 4)
+        ]
+      ),
+      panel_format(
+        title: "Pricing & Inventory",
+        fields: [
+          field_format(name: :price, type: :number, label: "Price", required: true, min: 0, step: 0.01),
+          field_format(name: :stock, type: :number, label: "Stock Quantity", min: 0)
+        ]
+      ),
+      panel_format(
+        title: "Settings",
+        fields: [
+          field_format(name: :active, type: :checkbox, label: "Active"),
+          field_format(name: :featured, type: :checkbox, label: "Featured on Homepage")
+        ]
+      )
+    ]
+  end
+
+  def footer
+    {
+      primary_action: { label: "Create Product", style: "primary" },
+      secondary_actions: [{ label: "Cancel", path: products_path, style: "secondary" }]
+    }
+  end
+
+  def category_options
+    @categories.map { |c| { value: c.id, label: c.name } }
+  end
+end
+```

data/guide/05-custom-pages.md

@@ -0,0 +1,325 @@
+# Building Custom Pages
+
+A complete guide to building dashboards, reports, and other custom pages.
+
+### Basic Custom Page Structure
+
+```ruby
+class Admin::DashboardPage < CustomBasePage
+  def initialize(data, metadata = {})
+    @data = data
+    @user = metadata[:user]
+    super(data, metadata)
+  end
+
+  private
+
+  def header
+    { title: "Dashboard" }
+  end
+
+  def content
+    { widgets: [] }
+  end
+end
+```
+
+--------------------------------
+
+### Adding Widgets
+
+```ruby
+def content
+  {
+    widgets: [
+      widget_format(title: "Total Users", type: :counter, data: { value: @data[:users_count] }),
+      widget_format(title: "Total Orders", type: :counter, data: { value: @data[:orders_count] }),
+      widget_format(title: "Revenue", type: :counter, data: { value: format_currency(@data[:revenue]) })
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Using widget_format Helper
+
+Build widgets with the helper method.
+
+```ruby
+widget_format(
+  title: "Active Users",
+  type: :counter,        # :counter, :chart, :list, :table
+  data: { value: 1234 },
+  color: "blue",
+  icon: "users"
+)
+```
+
+--------------------------------
+
+### Adding Charts
+
+```ruby
+def content
+  {
+    widgets: [
+      chart_format(
+        title: "Revenue Over Time",
+        type: :line,
+        data: {
+          labels: @data[:months],
+          datasets: [
+            { label: "Revenue", data: @data[:revenue_by_month], color: "blue" }
+          ]
+        }
+      )
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Using chart_format Helper
+
+Build charts with the helper method.
+
+```ruby
+chart_format(
+  title: "Sales Chart",
+  type: :line,           # :line, :bar, :pie, :doughnut, :area
+  data: {
+    labels: ["Jan", "Feb", "Mar", "Apr"],
+    datasets: [
+      { label: "Sales", data: [100, 200, 150, 300], color: "blue" },
+      { label: "Returns", data: [10, 20, 15, 30], color: "red" }
+    ]
+  }
+)
+```
+
+--------------------------------
+
+### Chart Types
+
+```ruby
+# Line Chart
+chart_format(title: "Trend", type: :line, data: chart_data)
+
+# Bar Chart
+chart_format(title: "Comparison", type: :bar, data: chart_data)
+
+# Pie Chart
+chart_format(title: "Distribution", type: :pie, data: pie_data)
+
+# Doughnut Chart
+chart_format(title: "Breakdown", type: :doughnut, data: pie_data)
+
+# Area Chart
+chart_format(title: "Growth", type: :area, data: chart_data)
+```
+
+--------------------------------
+
+### Adding List Widget
+
+```ruby
+def content
+  {
+    widgets: [
+      widget_format(
+        title: "Recent Orders",
+        type: :list,
+        data: {
+          items: @data[:recent_orders].map do |order|
+            {
+              title: "Order ##{order.id}",
+              subtitle: order.customer_name,
+              value: format_currency(order.total),
+              path: order_path(order)
+            }
+          end
+        }
+      )
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Adding Table Widget
+
+```ruby
+def content
+  {
+    widgets: [
+      widget_format(
+        title: "Top Products",
+        type: :table,
+        data: {
+          columns: [
+            { key: :name, label: "Product" },
+            { key: :sales, label: "Sales" },
+            { key: :revenue, label: "Revenue" }
+          ],
+          rows: @data[:top_products]
+        }
+      )
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Dashboard with Grid Layout
+
+```ruby
+def content
+  {
+    layout: :grid,
+    columns: 3,
+    widgets: [
+      # Row 1: Statistics
+      widget_format(title: "Users", type: :counter, data: { value: @data[:users] }),
+      widget_format(title: "Orders", type: :counter, data: { value: @data[:orders] }),
+      widget_format(title: "Revenue", type: :counter, data: { value: @data[:revenue] }),
+
+      # Row 2: Charts (span 2 columns)
+      chart_format(title: "Sales Trend", type: :line, data: sales_chart_data, span: 2),
+      chart_format(title: "Categories", type: :pie, data: category_chart_data, span: 1),
+
+      # Row 3: Lists
+      widget_format(title: "Recent Orders", type: :list, data: orders_data, span: 2),
+      widget_format(title: "Top Products", type: :list, data: products_data, span: 1)
+    ]
+  }
+end
+```
+
+--------------------------------
+
+### Reports Page Example
+
+```ruby
+class Reports::SalesPage < CustomBasePage
+  def initialize(report_data, metadata = {})
+    @report_data = report_data
+    @user = metadata[:user]
+    @period = metadata[:period]
+    super(report_data, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: "Sales Report",
+      description: "Sales performance for #{@period}",
+      actions: [
+        { label: "Export PDF", path: export_report_path(format: :pdf), icon: "download" },
+        { label: "Export CSV", path: export_report_path(format: :csv), icon: "file" }
+      ]
+    }
+  end
+
+  def content
+    {
+      widgets: [
+        # Summary statistics
+        widget_format(title: "Total Sales", type: :counter, data: { value: @report_data[:total_sales] }),
+        widget_format(title: "Orders", type: :counter, data: { value: @report_data[:order_count] }),
+        widget_format(title: "Avg Order Value", type: :counter, data: { value: @report_data[:avg_order] }),
+
+        # Charts
+        chart_format(title: "Daily Sales", type: :line, data: daily_sales_data),
+        chart_format(title: "Sales by Category", type: :pie, data: category_data),
+
+        # Tables
+        widget_format(title: "Top Selling Products", type: :table, data: top_products_data)
+      ]
+    }
+  end
+
+  def daily_sales_data
+    {
+      labels: @report_data[:dates],
+      datasets: [{ label: "Sales", data: @report_data[:daily_totals], color: "blue" }]
+    }
+  end
+
+  def category_data
+    {
+      labels: @report_data[:categories].keys,
+      datasets: [{ data: @report_data[:categories].values }]
+    }
+  end
+
+  def top_products_data
+    {
+      columns: [
+        { key: :name, label: "Product" },
+        { key: :quantity, label: "Qty Sold" },
+        { key: :revenue, label: "Revenue" }
+      ],
+      rows: @report_data[:top_products]
+    }
+  end
+end
+```
+
+--------------------------------
+
+### Complete Dashboard Example
+
+```ruby
+class Admin::DashboardPage < CustomBasePage
+  def initialize(stats, metadata = {})
+    @stats = stats
+    @user = metadata[:user]
+    super(stats, metadata)
+  end
+
+  private
+
+  def header
+    {
+      title: "Dashboard",
+      description: "Welcome back, #{@user.name}"
+    }
+  end
+
+  def content
+    {
+      layout: :grid,
+      columns: 4,
+      widgets: statistics_widgets + chart_widgets + list_widgets
+    }
+  end
+
+  def statistics_widgets
+    [
+      widget_format(title: "Users", type: :counter, data: { value: @stats[:users], change: "+12%" }, icon: "users", color: "blue"),
+      widget_format(title: "Orders", type: :counter, data: { value: @stats[:orders], change: "+8%" }, icon: "cart", color: "green"),
+      widget_format(title: "Revenue", type: :counter, data: { value: format_currency(@stats[:revenue]), change: "+15%" }, icon: "dollar", color: "purple"),
+      widget_format(title: "Conversion", type: :counter, data: { value: "#{@stats[:conversion]}%", change: "-2%" }, icon: "chart", color: "yellow")
+    ]
+  end
+
+  def chart_widgets
+    [
+      chart_format(title: "Revenue Trend", type: :area, data: revenue_chart_data, span: 2),
+      chart_format(title: "Orders by Status", type: :doughnut, data: orders_chart_data, span: 2)
+    ]
+  end
+
+  def list_widgets
+    [
+      widget_format(title: "Recent Orders", type: :list, data: { items: recent_orders }, span: 2),
+      widget_format(title: "Low Stock", type: :list, data: { items: low_stock_items }, span: 2)
+    ]
+  end
+end
+```