defmodule SutraUI do
  @moduledoc """
  Sutra UI - We define the rules, so you don't have to.

  A pure Phoenix LiveView UI component library with **55 components**,
  CSS-first theming, and colocated JavaScript hooks. Built for Phoenix 1.8+ and
  Phoenix LiveView 1.2+ with Tailwind CSS v4.

  ## Quick Start

      # mix.exs
      {:sutra_ui, "~> 0.4.0"}

      # lib/my_app_web.ex
      defp html_helpers do
        quote do
          use SutraUI
        end
      end

      # assets/css/app.css
      @import "tailwindcss";
      @source "../../deps/sutra_ui/lib";
      @import "../../deps/sutra_ui/priv/static/sutra_ui.css";

  See the [Installation Guide](installation.md) for detailed setup instructions.

  ## Requirements

  | Dependency | Version | Notes |
  |------------|---------|-------|
  | Elixir | 1.20+ | Matches the package constraint |
  | Phoenix | **1.8+** | Required for colocated hooks |
  | Phoenix LiveView | **1.2+** | Current supported LiveView line |
  | Tailwind CSS | **v4** | CSS-first configuration |

  > #### Why Phoenix 1.8+? {: .info}
  >
  > Sutra UI uses [colocated hooks](colocated-hooks.md) - JavaScript hooks defined
  > alongside components. Runtime hooks need no app-side hook file; extracted
  > hooks such as `dialog` and animated `response` are merged into LiveSocket.

  ## Components by Category

  ### Foundation

  Basic building blocks for any interface.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Button` | Buttons with 6 variants and 4 sizes |
  | `SutraUI.Badge` | Status indicators |
  | `SutraUI.Spinner` | Loading indicators |
  | `SutraUI.Kbd` | Keyboard shortcut display |

  ### Form Controls

  Complete form toolkit with validation support.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Input` | Text, email, password, number, date inputs |
  | `SutraUI.Textarea` | Multi-line text input |
  | `SutraUI.Checkbox` | Checkbox input |
  | `SutraUI.Switch` | Toggle switch |
  | `SutraUI.RadioGroup` | Radio button groups |
  | `SutraUI.Select` | Searchable dropdown (hook) |
  | `SutraUI.Slider` | Range slider (hook) |
  | `SutraUI.RangeSlider` | Dual-handle range (hook) |
  | `SutraUI.LiveSelect` | LiveComponent async searchable select (hook) |
  | `SutraUI.Label` | Form labels |
  | `SutraUI.SimpleForm` | Form with auto-styling |
  | `SutraUI.InputGroup` | Input with prefix/suffix |
  | `SutraUI.InputOTP` | One-time password inputs (hook) |
  | `SutraUI.FileUpload` | LiveView upload dropzone |
  | `SutraUI.FilterBar` | Filter controls layout |

  ### Layout

  Structure and organize content.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Card` | Content container |
  | `SutraUI.Header` | Page headers |
  | `SutraUI.Table` | Data tables |
  | `SutraUI.Item` | List items |
  | `SutraUI.Drawer` | Navigation drawer (hook) |
  | `SutraUI.Stepper` | Multi-step progress indicators |
  | `SutraUI.StepperWizard` | Multi-step wizard shell |
  | `SutraUI.TreeView` | Hierarchical navigation trees |

  ### Feedback

  Communicate status and progress.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Alert` | Alert messages |
  | `SutraUI.Flash` | Phoenix flash messages |
  | `SutraUI.Toast` | Toast notifications (hook) |
  | `SutraUI.Progress` | Progress bars |
  | `SutraUI.Skeleton` | Loading placeholders |
  | `SutraUI.Empty` | Empty states |
  | `SutraUI.LoadingState` | Loading indicators |

  ### Overlay

  Layered UI elements.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Dialog` | Modal dialogs (hook) |
  | `SutraUI.Popover` | Click-triggered popups (hook) |
  | `SutraUI.Tooltip` | Hover and focus tooltips (hook) |
  | `SutraUI.DropdownMenu` | Dropdown menus (hook) |
  | `SutraUI.ContextMenu` | Right-click action menus (hook) |
  | `SutraUI.HoverCard` | Hover preview cards (hook) |
  | `SutraUI.Command` | Command palette (hook) |

  ### Navigation

  Help users move through your app.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Tabs` | Tab panels (hook) |
  | `SutraUI.Accordion` | Collapsible sections |
  | `SutraUI.Breadcrumb` | Breadcrumb trails |
  | `SutraUI.Pagination` | Page navigation |
  | `SutraUI.TabNav` | Routed tab-style navigation |

  ### Display

  Present content and media.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Avatar` | User avatars |
  | `SutraUI.Carousel` | Image carousels (hook) |
  | `SutraUI.ThemeSwitcher` | Light/dark theme event button (hook) |
  | `SutraUI.Separator` | Visual content dividers |
  | `SutraUI.Marquee` | Scrolling content banners |
  | `SutraUI.Calendar` | Monthly calendar grid |
  | `SutraUI.Timeline` | Chronological event lists |

  ### AI

  Composable primitives for AI-assisted interfaces.

  | Component | Description |
  |-----------|-------------|
  | `SutraUI.Response` | Text responses with reveal styles, or streamed Markdown |
  | `SutraUI.Activity` | Safe user-facing agent progress with slot-owned rows |

  ## Theming

  Sutra UI uses CSS variables compatible with [shadcn/ui themes](https://ui.shadcn.com/themes).

      :root {
        --primary: oklch(0.65 0.20 260);
        --primary-foreground: oklch(0.98 0 0);
      }

  See the [Theming Guide](theming.md) for complete customization options.

  ## Accessibility

  Sutra UI components use accessibility patterns appropriate to their behavior:

  - Semantic HTML elements
  - ARIA roles and attributes for composite widgets
  - Keyboard navigation for interactive components
  - Focus management where applicable
  - Screen reader support for status-style components

  See the [Accessibility Guide](accessibility.md) for details.

  ## Guides

  - [Installation](installation.md) - Setup and configuration
  - [Theming](theming.md) - Customize colors and styles
  - [Accessibility](accessibility.md) - ARIA and keyboard support
  - [JavaScript Hooks](colocated-hooks.md) - Colocated hook patterns

  ## Quick Reference

  - [Components Cheatsheet](components.cheatmd) - All components at a glance
  - [Forms Cheatsheet](forms.cheatmd) - Form patterns and validation
  """

  @doc """
  Use Sutra UI in your Phoenix application.

  This macro imports Sutra UI function components for use in your templates.
  `SutraUI.LiveSelect` is a LiveComponent; render it with
  `<.live_component module={SutraUI.LiveSelect} ... />`. The macro imports
  its `decode/1` and `normalize_options/1` helpers.

  ## Example

      defmodule MyAppWeb do
        def html_helpers do
          quote do
            use SutraUI
          end
        end
      end
  """
  defmacro __using__(_opts) do
    quote do
      # Phase 1: Foundation
      import SutraUI.Button
      import SutraUI.Badge
      import SutraUI.Spinner
      import SutraUI.Kbd

      # Phase 2: Form Primitives
      import SutraUI.Label
      import SutraUI.Input
      import SutraUI.Textarea
      import SutraUI.Checkbox
      import SutraUI.Switch
      import SutraUI.RadioGroup
      import SutraUI.Select
      import SutraUI.Slider

      # Phase 3: Layout & Data Display
      import SutraUI.Card
      import SutraUI.Header
      import SutraUI.Table
      import SutraUI.Skeleton
      import SutraUI.Empty
      import SutraUI.Alert
      import SutraUI.Flash
      import SutraUI.Progress

      # Phase 4: Navigation & Interactive
      import SutraUI.Breadcrumb
      import SutraUI.Pagination
      import SutraUI.Accordion
      import SutraUI.Tabs
      import SutraUI.DropdownMenu
      import SutraUI.Toast

      # Phase 5: Advanced UI
      import SutraUI.Avatar
      import SutraUI.Tooltip
      import SutraUI.Dialog
      import SutraUI.Popover
      import SutraUI.Command
      import SutraUI.Carousel

      # Phase 6: Form & Layout Helpers
      import SutraUI.FilterBar
      import SutraUI.InputGroup
      import SutraUI.InputOTP
      import SutraUI.FileUpload
      import SutraUI.Item
      import SutraUI.LoadingState
      import SutraUI.SimpleForm

      # Phase 7: Navigation
      import SutraUI.Drawer
      import SutraUI.TabNav
      import SutraUI.Stepper
      import SutraUI.StepperWizard
      import SutraUI.TreeView
      import SutraUI.ThemeSwitcher

      # Phase 8: Advanced Form Controls
      import SutraUI.RangeSlider
      # LiveSelect is a LiveComponent - only import helper functions, not lifecycle callbacks
      import SutraUI.LiveSelect, only: [decode: 1, normalize_options: 1]

      # Phase 9: New Components
      import SutraUI.Separator
      import SutraUI.Marquee
      import SutraUI.HoverCard
      import SutraUI.Calendar
      import SutraUI.Timeline
      import SutraUI.ContextMenu

      # Phase 10: AI Primitives
      import SutraUI.Response
      import SutraUI.Activity
    end
  end
end