Phlex

https://github.com/yippee-fun/phlex
Admin
Phlex is a Ruby library for building object-oriented web views using pure Ruby, offering a...
Tokens:36,978
Snippets:423
Trust Score:7.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://github.com/yippee-fun/phlex/blob/main/CONTRIBUTING.md

Command to install all required project dependencies.

```bash
bundle install
```

--------------------------------

### Implement Phlex::Kit components

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Example of using Phlex::Kit to organize and auto-render components.

```ruby
module Components
  extend Phlex::Kit

  class Button < Phlex::HTML
    def initialize(label)
      @label = label
    end

    def view_template
      button { @label }
    end
  end
end

class Page < Phlex::HTML
  include Components

  def view_template
    div {
      Button("Click me")  # Auto-renders
    }
  end
end
```

--------------------------------

### Phlex::VERSION usage example

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

Accessing the current gem version.

```ruby
puts Phlex::VERSION  # => "2.4.1"
```

--------------------------------

### Initialize and Use Phlex::FIFOCacheStore

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Interface definitions and usage example for the FIFO in-memory cache store.

```ruby
class Phlex::FIFOCacheStore
  def initialize(max_bytesize: 2 ** 20) -> void

  def fetch(key) { |block| -> value
  def clear -> nil
end
```

```ruby
class PageWithCache < Phlex::HTML
  def initialize
    @cache = Phlex::FIFOCacheStore.new(max_bytesize: 5 * 1024 * 1024)
  end

  def cache_store
    @cache
  end

  def view_template
    cache(:products) do
      render_products
    end
  end

  private def render_products
    div { "Products here" }
  end
end
```

--------------------------------

### Phlex::FIFO Usage Example

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Demonstrates basic cache operations including setting values, retrieval, and clearing the cache.

```ruby
cache = Phlex::FIFO.new(max_bytesize: 10_000)
cache["key"] = "value"
cache["key"]  # => "value"
cache.size    # => 1
cache.clear   # => nil
```

--------------------------------

### Phlex::Escape usage example

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

Demonstrates HTML and JSON escaping using Phlex::Escape.

```ruby
Phlex::Escape.html_escape("<script>alert('xss')</script>")
# => "&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;"

Phlex::Escape.json_escape(%q{"key": "value"})
# => %q{\"key\": \"value\"}
```

--------------------------------

### Phlex.html usage example

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

Generates an HTML string using the Phlex HTML DSL with instance variable access.

```ruby
@title = "Hello"
@items = ["a", "b", "c"]

html = Phlex.html {
  div {
    h1 { @title }
    ul {
      @items.each { |item| li { item } }
    }
  }
}

# => "<div><h1>Hello</h1><ul><li>a</li><li>b</li><li>c</li></ul></div>"
```

--------------------------------

### Event Chaining and Path Manipulation

Source: https://github.com/yippee-fun/phlex/blob/main/fixtures/xss.txt

Examples of chaining events and using unconventional path separators in script tags.

```html
<div id="123"><span class=foo>Some text</span>
<a class=bar href="http://www.example.org">www.example.org</a>
<script src="http://code.jquery.com/jquery-1.4.4.js"></script>
<script>$("span.foo").click(function() {alert('foo');$("a.bar").click();});$("a.bar").click(function() {alert('bar');location="http://html5sec.org";});</script>//["''`-->]]>]</div>
```

```html
<div id="124"><script src="/\example.com\foo.js"></script> // Safari 5.0, Chrome 9, 10
<script src="\\example.com\foo.js"></script> // Safari 5.0//["''`-->]]>]</div>
```

--------------------------------

### Browser Protocol and Sandbox Manipulation

Source: https://github.com/yippee-fun/phlex/blob/main/fixtures/xss.txt

Examples using view-source, popup spamming, and iframe sandboxing.

```html
<div id="119"><iframe src="view-source:http://www.example.org/" frameborder="0" style="width:400px;height:180px"></iframe>
<textarea type="text" cols="50" rows="10"></textarea>//["''`-->]]>]</div>
```

```html
<div id="120"><script>function makePopups(){for (i=1;i<6;i++) {window.open('popup.html','spam'+i,'width=50,height=50');}}</script>
<body><a href="#" onclick="makePopups()">Spam</a>//["''`-->]]>]</div>
```

```html
<div id="122"><iframe sandbox="allow-same-origin allow-forms allow-scripts" src="http://example.org/"></iframe>//["''`-->]]>]</div>
```

--------------------------------

### Check rendering state

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

The rendering? method returns true once the component has started the rendering process.

```ruby
class Conditional < Phlex::HTML
  def view_template
    div { "Rendering" if rendering? }
  end
end
```

--------------------------------

### before_template

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

A hook called before the view_template executes, useful for running setup logic.

```APIDOC
## before_template

### Description
Called before `view_template` executes. Override to run setup logic.

### Signature
`private def before_template(&block) -> void`
```

--------------------------------

### Phlex.svg usage example

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

Generates an SVG string using the Phlex SVG DSL.

```ruby
@color = "blue"

svg = Phlex.svg {
  svg(viewBox: "0 0 100 100") {
    circle(cx: "50", cy: "50", r: "40", fill: @color)
  }
}

# => '<svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="40" fill="blue"></circle></svg>'
```

--------------------------------

### Create dynamic SVG elements

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/03-svg-elements.md

Example of using the tag method to render an SVG element dynamically based on input.

```ruby
class DynamicSVG < Phlex::SVG
  def initialize(element_type, content)
    @element_type = element_type
    @content = content
  end

  def view_template
    svg(viewBox: "0 0 100 100") {
      tag(@element_type, fill: "red") { @content }
    }
  end
end

DynamicSVG.new(:circle, "Dynamic").call
```

--------------------------------

### Implement around_template hook

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Wraps the template rendering process for setup and teardown.

```ruby
private def around_template { block } -> void
```

```ruby
class TimedComponent < Phlex::HTML
  private def around_template
    start = Time.now
    yield
    puts "Rendered in #{Time.now - start}s"
  end

  def view_template
    div { "Content" }
  end
end
```

--------------------------------

### Render Void Elements in Phlex

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/02-html-elements.md

Example of using void elements like input within a Phlex view template.

```ruby
class Form < Phlex::HTML
  def view_template
    form {
      label(for: "name") { "Name:" }
      input(id: "name", type: "text", required: true)
      
      label(for: "email") { "Email:" }
      input(id: "email", type: "email")
      
      input(type: "submit", value: "Submit")
    }
  end
end

# Output:
# <form>
#   <label for="name">Name:</label>
#   <input id="name" type="text" required>
#   <label for="email">Email:</label>
#   <input id="email" type="email">
#   <input type="submit" value="Submit">
# </form>
```

--------------------------------

### SVG and CSS Resource Injection

Source: https://github.com/yippee-fun/phlex/blob/main/fixtures/xss.txt

Examples of using SVG and CSS to reference external resources or trigger events.

```html
<div id="109"><svg xmlns="http://www.w3.org/2000/svg">
<a id="x"><rect fill="white" width="1000" height="1000"/></a>
<rect  fill="white" style="clip-path:url(test3.svg#a);fill:url(#b);filter:url(#c);marker:url(#d);mask:url(#e);stroke:url(#f);"/>
</svg>//["''`-->]]>]</div>
```

```html
<div id="110"><svg xmlns="http://www.w3.org/2000/svg">
<path d="M0,0" style="marker-start:url(test4.svg#a)"/>
</svg>//["''`-->]]>]</div>
```

--------------------------------

### around_template

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Wraps the execution of the view_template, allowing for setup and teardown logic.

```APIDOC
## around_template

### Description
Wraps `view_template` execution. Override to add setup/teardown around rendering.

### Signature
`private def around_template { block } -> void`
```

--------------------------------

### XML Stylesheet Injection

Source: https://github.com/yippee-fun/phlex/blob/main/fixtures/xss.txt

Example of using XML stylesheets to reference external or internal resources.

```xml
<div id="125"><?xml version="1.0"?>
<?xml-stylesheet type="text/xml" href="#stylesheet"?>
<!DOCTYPE doc [
<!ATTLIST xsl:stylesheet id    ID    #REQUIRED>]>
<svg xmlns="http://www.w3.org/2000/svg">
```

--------------------------------

### Handle Phlex::ArgumentError

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/04-errors.md

Example of rescuing an argument error triggered by invalid component input.

```ruby
begin
  component.tag(:div, class: unsafe_value)
rescue Phlex::ArgumentError => e
  puts "Invalid argument: #{e.message}"
end
```

--------------------------------

### Preview documentation locally

Source: https://github.com/yippee-fun/phlex/blob/main/CONTRIBUTING.md

Command to build and preview the project documentation.

```bash
bin/docs
```

--------------------------------

### Run tests

Source: https://github.com/yippee-fun/phlex/blob/main/CONTRIBUTING.md

Commands to execute the test suite using Quickdraw and Sus.

```bash
bundle exec qt && bundle exec sus
```

--------------------------------

### Organize components with Phlex::Kit

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Use Phlex::Kit to group components and include them in views for lazy-loading.

```ruby
module UI
  extend Phlex::Kit

  class Button < Phlex::HTML
    def initialize(label, style: :primary)
      @label = label
      @style = style
    end

    def view_template
      button(class: "btn btn-#{@style}") { @label }
    end
  end

  class Card < Phlex::HTML
    def initialize(title)
      @title = title
    end

    def view_template
      div(class: "card") do
        h3 { @title }
        yield
      end
    end
  end
end

class Page < Phlex::HTML
  include UI  # Enables Button, Card methods

  def view_template
    div {
      Button("Submit", style: :primary)
      Card("My Card") { p { "Content" } }
    }
  end
end
```

--------------------------------

### Define a component with options

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Pass keyword arguments to the initializer to customize component rendering.

```ruby
class Badge < Phlex::HTML
  def initialize(label, style: :default, size: :small)
    @label = label
    @style = style
    @size = size
  end

  def view_template
    span(class: ["badge", "badge-#{@style}", "badge-#{@size}"]) {
      @label
    }
  end
end

# Usage
Badge.new("New", style: :success).call
Badge.call("Popular", style: :primary, size: :large)  # Using .call directly
```

--------------------------------

### Phlex::SGML.new

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Create a new instance of the component.

```APIDOC
## new(*args, **kwargs, &block)

### Description
Create a new instance of the component. The block is not passed to initialize; instead it is stored and sent to view_template during rendering.
```

--------------------------------

### Run Quickdraw tests

Source: https://github.com/yippee-fun/phlex/blob/main/CONTRIBUTING.md

Execute tests written with the Quickdraw framework.

```bash
bundle exec qt
```

--------------------------------

### Configure document head links

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/10-element-attributes.md

Demonstrates adding various link tags to the document head for stylesheets, icons, and resource preloading.

```ruby
class Document < Phlex::HTML
  def view_template
    head {
      link(rel: "stylesheet", href: "/styles.css", type: "text/css")
      link(rel: "icon", href: "/favicon.ico")
      link(rel: "preload", href: "/fonts/main.woff2", as: "font", type: "font/woff2", crossorigin: true)
      link(rel: "dns-prefetch", href: "//fonts.googleapis.com")
    }
  end
end
```

--------------------------------

### Phlex::CSV#initialize

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Initializes a new CSV component with a collection of records.

```APIDOC
## Phlex::CSV.new(collection)

### Description
Creates a new instance of a Phlex::CSV component to process the provided collection.

### Parameters
- **collection** (Enumerable) - Required - The collection of records to render as CSV rows.
```

--------------------------------

### Render component via class method

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

Convenience method to instantiate and render a component in one step.

```ruby
def self.call(...) -> String
```

```ruby
class Greeting < Phlex::HTML
  def initialize(name)
    @name = name
  end

  def view_template
    p { "Hello, #{@name}" }
  end
end

# These are equivalent:
output1 = Greeting.new("Alice").call
output2 = Greeting.call("Alice")

# Both output: <p>Hello, Alice</p>
```

--------------------------------

### Embed CDATA sections in SVG

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/03-svg-elements.md

Examples of using cdata with blocks and strings to embed unescaped content.

```ruby
class StyledIcon < Phlex::SVG
  def view_template
    svg(viewBox: "0 0 100 100") {
      style {
        cdata {
          "circle { fill: red; }"
        }
      }
      circle(cx: "50", cy: "50", r: "40")
    }
  end
end

# Output:
# <svg viewBox="0 0 100 100">
#   <style><![CDATA[circle { fill: red; }]]></style>
#   <circle cx="50" cy="50" r="40"></circle>
# </svg>
```

```ruby
class ScriptedIcon < Phlex::SVG
  def view_template
    svg(viewBox: "0 0 100 100") {
      script(type: "application/ecmascript") {
        cdata("function test() { alert('SVG'); }")
      }
    }
  end
end
```

--------------------------------

### Event Handler Blocking

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/09-security-reference.md

Attributes starting with 'on' are blocked to prevent XSS via event handlers.

```ruby
begin
  div(onclick: "malicious()") { "Content" }
rescue Phlex::ArgumentError => e
  # "Unsafe attribute name detected: :onclick"
end
```

--------------------------------

### Phlex::SGML#call

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Renders the component to a string. This is the primary method to generate output.

```APIDOC
## call(buffer = +"", context: {}, fragments: nil, &block)

### Description
Render the component to a string. This is the primary method to generate output.

### Parameters
- **buffer** (String) - Optional - Output buffer to append rendered content to (default: +"")
- **context** (Hash) - Optional - User context available during rendering via the context method (default: {})
- **fragments** (Set, Array, nil) - Optional - Fragment names to selectively render (default: nil)
- **block** (Proc) - Optional - Block passed to view_template for yielding content

### Returns
- **String** - The rendered markup
```

--------------------------------

### Initialize a component with a block

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Blocks passed to new are stored and yielded within the view_template during rendering.

```ruby
class Greeting < Phlex::HTML
  def view_template
    h1 { yield }
  end
end

component = Greeting.new { "Hello" }
output = component.call
# => "<h1>Hello</h1>"
```

--------------------------------

### to_proc

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Returns a proc that renders the component when called.

```APIDOC
## to_proc()

### Description
Returns a proc that renders the component when called with another component. Useful for functional rendering patterns.

### Returns
- **Proc** - A proc that accepts a component and calls `render` with self
```

--------------------------------

### Initialize Phlex::SGML::State

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Constructor for the internal state object managing rendering context and buffers.

```ruby
class Phlex::SGML::State
  def initialize(user_context: {}, output_buffer:, fragments:) -> void
end
```

--------------------------------

### Create a custom safe HTML component

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Shows how to include SafeObject in a custom class to render raw HTML safely.

```ruby
class CustomHTML
  include Phlex::SGML::SafeObject

  def initialize(html)
    @html = html
  end

  def to_s
    @html
  end
end

class Page < Phlex::HTML
  def view_template
    raw CustomHTML.new("<strong>Safe</strong>")
  end
end
```

--------------------------------

### Implement CSV injection protection

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Required override to handle CSV injection characters. Includes examples for secure and unsafe configurations.

```ruby
private def escape_csv_injection? -> Boolean
```

```ruby
class SecureCSV < Phlex::CSV
  def row_template(item)
    column("Name", item.name)
  end

  private def escape_csv_injection?
    true  # Prefix formula chars with '
  end
end

class UnsafeCSV < Phlex::CSV
  def row_template(item)
    column("Data", item.data)
  end

  private def escape_csv_injection?
    false  # No escaping; for internal use only
  end
end
```

```text
=SUM(A1:A10)  →  '=SUM(A1:A10)
+1+1           →  '+1+1
-2-2           →  '-2-2
@IMPORTXML()   →  '@IMPORTXML()
```

--------------------------------

### Automatic Attribute Escaping in Phlex

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/09-security-reference.md

Attribute values are automatically escaped to prevent XSS. The example demonstrates how input containing quotes is safely rendered.

```ruby
class Link < Phlex::HTML
  def initialize(url, title)
    @url = url
    @title = title
  end

  def view_template
    a(href: @url, title: @title) { "Click" }
  end
end

# Input: url = 'javascript:alert("xss")', title = 'Test" onmouseover="alert()'
# Output: <a href="javascript:alert(&quot;xss&quot;)" title="Test&quot; onmouseover=&quot;alert()">Click</a>
```

--------------------------------

### Define and render a basic Phlex component

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/README.md

Inherit from Phlex::HTML to define a component. Use the call method or instantiate the class to render the template to a string.

```ruby
class Greeting < Phlex::HTML
  def initialize(name)
    @name = name
  end

  def view_template
    div(class: "greeting") {
      h1 { "Hello, #{@name}" }
      p { "Welcome to Phlex" }
    }
  end
end

# Render to string
output = Greeting.new("Alice").call
# or
output = Greeting.call("Alice")
```

--------------------------------

### Implement Simple Caching

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Define a cache_store and use the cache method to wrap expensive rendering logic.

```ruby
class ProductGrid < Phlex::HTML
  def initialize(products)
    @products = products
  end

  private def cache_store
    @cache ||= Phlex::FIFOCacheStore.new
  end

  def view_template
    div(class: "grid") {
      @products.each do |product|
        cache product do
          render ProductCard.new(product)
        end
      end
    }
  end
end
```

--------------------------------

### Convert component to proc in Ruby

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Returns a proc that renders the component, facilitating functional rendering patterns.

```ruby
def to_proc -> Proc
```

```ruby
components = [header, article, footer]
components.each(&Header.new.to_proc)
```

--------------------------------

### Render components from singleton methods

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Use the thread-local component context to render components from outside the standard component context.

```ruby
module UI
  extend Phlex::Kit

  class Alert < Phlex::HTML
    def view_template
      div(class: "alert") { yield }
    end
  end

  def self.render_alert
    component = Thread.current[:__phlex_component__]
    if component
      component.instance_exec { Alert { "Global Alert" } }
    end
  end
end
```

--------------------------------

### Create a simple login form in Phlex

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Defines a basic HTML form component using Phlex's DSL.

```ruby
class LoginForm < Phlex::HTML
  def view_template
    form(method: "post", action: "/login") {
      fieldset {
        legend { "Sign In" }
        
        label(for: "email") { "Email" }
        input(id: "email", type: "email", name: "email", required: true)
        
        label(for: "password") { "Password" }
        input(id: "password", type: "password", name: "password", required: true)
        
        input(type: "submit", value: "Sign In")
      }
    }
  }
end
```

--------------------------------

### Phlex::SGML.call

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

A convenience class method that instantiates a component and renders it, delegating all arguments to the class constructor.

```APIDOC
## Phlex::SGML.call

### Description
Creates an instance of the component and calls it, returning the rendered output as a string. This is a shorthand for calling .new(...).call.

### Signature
`def self.call(...) -> String`

### Parameters
- **...** (splat) - Arguments passed directly to the component's `initialize` method.

### Returns
- **String** - The rendered HTML/SGML output.

### Example
```ruby
# These are equivalent:
output1 = Greeting.new("Alice").call
output2 = Greeting.call("Alice")
```
```

--------------------------------

### Run Sus tests

Source: https://github.com/yippee-fun/phlex/blob/main/CONTRIBUTING.md

Execute legacy tests written with the Sus framework.

```bash
bundle exec sus
```

--------------------------------

### Configure Phlex::CSV metadata and formatting

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Methods for setting CSV filename, content type, and column delimiters.

```ruby
def filename -> String, nil
```

```ruby
def content_type -> String
```

```ruby
def delimiter -> String
```

```ruby
class TSVExport < Phlex::CSV
  def delimiter
    "\t"
  end
end
```

--------------------------------

### Define a Phlex component with HTML elements

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/02-html-elements.md

Create a component by inheriting from Phlex::HTML and defining a view_template method. Elements are called as methods within the template block.

```ruby
class Article < Phlex::HTML
  def initialize(title, body)
    @title = title
    @body = body
  end

  def view_template
    article(class: "post") {
      header {
        h1 { @title }
      }
      p { @body }
      footer {
        small { "Published today" }
      }
    }
  end
end

# Output:
# <article class="post">
#   <header><h1>Article Title</h1></header>
#   <p>Article body</p>
#   <footer><small>Published today</small></footer>
# </article>
```

--------------------------------

### Phlex::SGML#comment

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Wrap output in an HTML comment.

```APIDOC
## comment(&block)

### Description
Wrap output in an HTML comment. Block content is yielded and comment markers are added.
```

--------------------------------

### Render a component with call

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Use the call method to render a component instance to a string.

```ruby
class Button < Phlex::HTML
  def initialize(label)
    @label = label
  end

  def view_template
    button { @label }
  end
end

output = Button.new("Click me").call
# => "<button>Click me</button>"
```

--------------------------------

### Configure Phlex Cache Store

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Initialize a FIFOCacheStore within a component to manage memory usage for cached content.

```ruby
class MyComponent < Phlex::HTML
  def initialize
    @cache = Phlex::FIFOCacheStore.new(
      max_bytesize: 10 * 1024 * 1024  # 10 MB
    )
  end

  private def cache_store
    @cache
  end
end
```

--------------------------------

### Define a basic Phlex component

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Inherit from Phlex::HTML and implement the view_template method to define component structure.

```ruby
class UserCard < Phlex::HTML
  def initialize(user)
    @user = user
  end

  def view_template
    article(class: "card") {
      h2 { @user.name }
      p { @user.email }
    }
  end
end

# Usage
UserCard.new(user).call
# => "<article class=\"card\"><h2>Alice</h2><p>alice@example.com</p></article>"
```

--------------------------------

### Render various object types in Phlex

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Demonstrates the different types of objects that can be passed to the render method.

```ruby
component.render(Button.new("Submit"))  # Instance
component.render(Button, label: "Go")   # Class (calls new)
component.render([button1, button2])    # Array
component.render(-> { p { "Content" } })  # Proc
component.render("Text")                # String
component.render(nil) { p { "Default" } }  # nil with block
```

--------------------------------

### Create reusable SVG icon components

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Define SVG components by inheriting from Phlex::SVG and render them within standard HTML components.

```ruby
class Icon < Phlex::SVG
  def initialize(name, size: 24, color: "currentColor")
    @name = name
    @size = size
    @color = color
  end

  def view_template
    svg(
      viewBox: "0 0 24 24",
      width: @size,
      height: @size,
      fill: @color,
      class: "icon icon-#{@name}"
    ) {
      case @name
      when :home
        path(d: "M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z")
      when :star
        path(d: "M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z")
      end
    }
  end
end

# Usage in HTML component
class Button < Phlex::HTML
  def initialize(label, icon_name: nil)
    @label = label
    @icon_name = icon_name
  end

  def view_template
    button {
      render Icon.new(@icon_name) if @icon_name
      whitespace
      @label
    }
  end
end
```

--------------------------------

### Initialize thread-safe FIFO cache

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Phlex::FIFO uses Monitor to ensure thread-safe operations.

```ruby
cache = Phlex::FIFO.new
# Safe to access from multiple threads
```

--------------------------------

### render?

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

A conditional hook to determine if the component should render at all.

```APIDOC
## render?

### Description
Override to conditionally skip rendering entirely.

### Signature
`private def render? -> Boolean`
```

--------------------------------

### Implement a master layout

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Uses a layout component to wrap page content and render shared elements like headers and footers.

```ruby
class Layout < Phlex::HTML
  def initialize(title: "My Site", current_user: nil)
    @title = title
    @current_user = current_user
  end

  def view_template
    doctype
    html {
      head {
        title { @title }
        meta(charset: "utf-8")
        meta(name: "viewport", content: "width=device-width, initial-scale=1")
      }
      body {
        render Header.new(current_user: @current_user)
        main { yield }
        render Footer.new
      }
    }
  }
end

class HomePage < Phlex::HTML
  def initialize(user)
    @user = user
  end

  def view_template
    div(class: "container") {
      h1 { "Welcome, #{@user.name}" }
      p { "You have #{@user.posts.count} posts" }
    }
  end
end

# Render page with layout
html = Layout.new(title: "Home", current_user: current_user) do |layout|
  layout.render HomePage.new(current_user)
end
```

--------------------------------

### Phlex::SGML#rendering?

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Check if the component is currently rendering.

```APIDOC
## rendering?()

### Description
Returns false before rendering and true once the component has started rendering. Does not reset after rendering completes.

### Returns
- **Boolean**
```

--------------------------------

### Configure Phlex::SVG filename and content type

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Methods for setting SVG-specific metadata and MIME types.

```ruby
def filename -> String, nil
```

```ruby
def content_type -> String
```

--------------------------------

### Perform low-level caching in Ruby

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Use for advanced scenarios requiring full manual control over the cache key generation.

```ruby
def low_level_cache(cache_key, **options, &content) -> nil
```

```ruby
class Markdown < Phlex::HTML
  def initialize(content)
    @content = content
  end

  def view_template
    key = [Digest::MD5.hexdigest(@content), "v1"]
    low_level_cache(key) do
      raw safe(render_markdown(@content))
    end
  end
end
```

--------------------------------

### Configure custom cache_store

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Provides a custom cache store implementation for component caching.

```ruby
private def cache_store -> #fetch
```

```ruby
class CachedComponent < Phlex::HTML
  def initialize
    @store = Phlex::FIFOCacheStore.new
  end

  private def cache_store
    @store
  end

  def view_template
    cache(:products) { render_products }
  end
end
```

--------------------------------

### Define a responsive image component

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/10-element-attributes.md

Uses the img tag with srcset and sizes attributes to handle responsive image loading.

```ruby
class ResponsiveImage < Phlex::HTML
  def view_template
    img(
      src: "image-medium.jpg",
      alt: "Product photo",
      srcset: [
        "image-small.jpg 320w",
        "image-medium.jpg 640w",
        "image-large.jpg 1200w"
      ],
      sizes: [
        "(max-width: 320px) 280px",
        "(max-width: 640px) 620px",
        "1180px"
      ],
      loading: "lazy"
    )
  end
end
```

--------------------------------

### Use SafeValue for rendering

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Demonstrates using the safe helper to render emphasized text within a template.

```ruby
class Article < Phlex::HTML
  def view_template
    div {
      raw safe("<em>Emphasized</em>")
    }
  end
end
```

--------------------------------

### Implement before_template hook

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Executes logic before the template renders.

```ruby
private def before_template(&block) -> void
```

```ruby
class AuditedComponent < Phlex::HTML
  private def before_template
    puts "Rendering #{self.class.name}"
  end

  def view_template
    div { "Content" }
  end
end
```

--------------------------------

### Phlex::SGML#raw

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Output a safe object as-is without escaping.

```APIDOC
## raw(content)

### Description
Output a safe object as-is without escaping. The object must be marked as safe (instance of Phlex::SGML::SafeObject) or be nil.

### Parameters
- **content** (Phlex::SGML::SafeObject, nil, "") - Required - Safe content to output

### Throws
- **Phlex::ArgumentError** - if an unsafe object is passed
```

--------------------------------

### Compose multiple Phlex components

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/README.md

Use the render method within a view_template to nest child components inside a parent layout.

```ruby
class Page < Phlex::HTML
  def initialize(user, posts)
    @user = user
    @posts = posts
  end

  def view_template
    doctype
    html {
      head { title { "My Blog" } }
      body {
        render Header.new(@user)
        main {
          @posts.each { |post| render PostCard.new(post) }
        }
        render Footer.new
      }
    }
  end
end
```

--------------------------------

### Accessing Phlex::DEPLOYED_AT

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

Returns the timestamp in milliseconds of when the Phlex module was loaded, used for cache invalidation.

```ruby
DEPLOYED_AT = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
```

--------------------------------

### Cache content with automatic keys in Ruby

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Cache blocks with automatic key generation that includes deployment time and component context.

```ruby
def cache(*cache_key, **, &content) -> nil
```

```ruby
class ProductList < Phlex::HTML
  def initialize(products)
    @products = products
  end

  def view_template
    @products.each do |product|
      cache product do
        div { h3 { product.name } }
      end
    end
  end
end
```

--------------------------------

### Handle Phlex::NameError

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/04-errors.md

Demonstrates catching a name resolution error during component rendering.

```ruby
begin
  component.render(UndefinedComponent)
rescue Phlex::NameError => e
  puts "Component not found: #{e.message}"
end
```

--------------------------------

### Implement nested layouts

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Wraps specific page layouts within a base application layout to maintain consistent structure.

```ruby
class AppLayout < Phlex::HTML
  def initialize(title: "")
    @title = title
  end

  def view_template
    doctype
    html {
      head { title { @title } }
      body {
        render Navbar.new
        yield
        render Footer.new
      }
    }
  end
end

class AdminLayout < Phlex::HTML
  def initialize(title: "")
    @title = title
  end

  def view_template
    AppLayout.new(title: @title) {
      div(class: "admin-wrapper") {
        render Sidebar.new
        main(class: "admin-main") { yield }
      }
    }
  end
end
```

--------------------------------

### Implement Error Boundaries in Phlex

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Wraps components to catch rendering errors and display a fallback UI. Requires a component instance and an optional fallback message.

```ruby
class ErrorBoundary < Phlex::HTML
  def initialize(component, fallback: "Error rendering component")
    @component = component
    @fallback = fallback
  end

  def view_template
    begin
      render @component
    rescue Phlex::Error => e
      div(class: "error") { @fallback }
    rescue StandardError => e
      div(class: "error") { "Unexpected error" }
    end
  end
end

# Usage
ErrorBoundary.new(
  UnstableComponent.new,
  fallback: "Component temporarily unavailable"
).call
```

--------------------------------

### Create an inline SVG icon component

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/03-svg-elements.md

Uses a button component to wrap an SVG path for icon rendering.

```ruby
class IconButton < Phlex::HTML
  def initialize(icon_path, label)
    @icon_path = icon_path
    @label = label
  end

  def view_template
    button(class: "icon-button") {
      svg(viewBox: "0 0 24 24", width: "24", height: "24", aria_label: @label) {
        path(d: @icon_path, fill: "currentColor")
      }
    }
  end
end
```

--------------------------------

### Stream Responses with Deferred Output

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Use the flush method to send rendered content to the client immediately before the rest of the component finishes rendering.

```ruby
class StreamedPage < Phlex::HTML
  def view_template
    h1 { "Starting..." }
    flush  # Send header to client immediately
    
    # Rest of page renders and streams...
    @items.each { |item| render item }
  end
end
```

--------------------------------

### Customize app_version_key

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Sets a custom key for cache invalidation across the application.

```ruby
private def app_version_key -> any
```

```ruby
class VersionedComponent < Phlex::HTML
  private def app_version_key
    "v#{ENV['APP_VERSION']}"
  end

  def view_template
    cache(:data) { render_data }
  end
end
```

--------------------------------

### Implement conditional rendering with render?

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Controls whether a component should render based on internal state.

```ruby
private def render? -> Boolean
```

```ruby
class ConditionalComponent < Phlex::HTML
  def initialize(visible)
    @visible = visible
  end

  private def render?
    @visible
  end

  def view_template
    div { "Only shown if visible" }
  end
end

ConditionalComponent.new(false).call  # => ""
ConditionalComponent.new(true).call   # => "<div>Only shown if visible</div>"
```

--------------------------------

### Implement conditional rendering

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Use standard Ruby conditional statements within the view_template to toggle output.

```ruby
class ProductView < Phlex::HTML
  def initialize(product)
    @product = product
  end

  def view_template
    div {
      h2 { @product.name }
      
      if @product.available?
        p(class: "available") { "In Stock" }
      else
        p(class: "unavailable") { "Out of Stock" }
      end
      
      if @product.sale_price
        span(class: "price-sale") { @product.sale_price }
      else
        span(class: "price-regular") { @product.price }
      end
    }
  end
end
```

--------------------------------

### Define Style Attributes

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/10-element-attributes.md

Styles can be defined using a hash, an array for vendor prefixes, or a direct CSS string.

```ruby
button(style: {
  color: "red",
  background_color: "white",
  border_radius: "4px",
  padding: "8px 16px"
})
```

```ruby
div(style: [
  "display: flex",
  "-webkit-display: flex",
  "gap: 10px"
])
```

```ruby
div(style: "color: red; background: white;")
```

--------------------------------

### Phlex::FIFO

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

A thread-safe FIFO cache implementation for storing key-value pairs with configurable byte size limits.

```APIDOC
## Phlex::FIFO

### Description
A low-level FIFO cache using hash-based storage. It is thread-safe and uses a Monitor for synchronization.

### Constructor
`Phlex::FIFO.new(max_bytesize: 2_000, max_value_bytesize: 2_000)`

### Methods
- **expand(bytes)**: Expands the cache capacity.
- **[](key)**: Retrieves the value associated with the key, or nil if not found.
- **[]=(key, value)**: Sets the value for the given key.
- **size**: Returns the number of items in the cache.
- **clear**: Clears all items from the cache.

### Attributes
- **bytesize**: Returns the current total bytesize of the cache.
- **max_bytesize**: Returns the maximum allowed bytesize of the cache.
```

--------------------------------

### Void Element Method Signature

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/02-html-elements.md

The standard method signature for all void HTML elements in Phlex.

```APIDOC
## Method Signature

### Description
Void elements are invoked as methods that accept keyword arguments for HTML attributes. They do not accept blocks; passing a block will raise a `Phlex::ArgumentError`.

### Signature
`def element_name(**attributes) -> nil`

### Supported Elements
- `area` (Area)
- `base` (Base)
- `br` (Break)
- `col` (Column)
- `embed` (Embed)
- `hr` (HR)
- `img` (Image)
- `input` (Input)
- `link` (Link)
- `meta` (Meta)
- `param` (Param)
- `source` (Source)
- `track` (Track)
- `wbr` (Wbr)
```

--------------------------------

### Using the 💪 Alias

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/06-utility-functions.md

A Unicode alias for the Phlex module. Use this to invoke Phlex methods concisely.

```ruby
def 💪
  Phlex
end
```

```ruby
💪.html { div { "Hello" } }  # Same as Phlex.html { ... }
```

--------------------------------

### Phlex::CSV#call

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Renders the CSV content to a string.

```APIDOC
## Phlex::CSV#call(buffer: "", context: nil, delimiter: ",")

### Description
Generates the CSV output string based on the defined row templates.

### Parameters
- **buffer** (String) - Optional - Output buffer, defaults to empty string.
- **context** (Object) - Optional - Reserved context object.
- **delimiter** (String) - Optional - The character used to separate columns, defaults to ",".

### Returns
- **String** - The rendered CSV output.

### Errors
- **Phlex::ArgumentError** - Raised if the delimiter is not exactly one character.
- **Phlex::RuntimeError** - Raised if there is a header mismatch between rows.
```

--------------------------------

### Phlex::SGML#plain

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Output plain text, which is automatically HTML-escaped.

```APIDOC
## plain(content)

### Description
Output plain text. Content is HTML-escaped. Accepts strings, symbols, integers, and floats.

### Parameters
- **content** (String, Symbol, Integer, Float) - Required - Content to output

### Throws
- **Phlex::ArgumentError** - if content type is not handled by format_object
```

--------------------------------

### Create a form with error handling

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Displays validation errors by iterating over an errors hash and conditionally applying CSS classes.

```ruby
class SignupForm < Phlex::HTML
  def initialize(user, errors: {})
    @user = user
    @errors = errors
  end

  def view_template
    form(method: "post", action: "/users") {
      @errors.each do |field, messages|
        div(class: "error-messages") {
          messages.each { |msg| p { "#{field.capitalize}: #{msg}" } }
        }
      end
      
      fieldset {
        legend { "Create Account" }
        
        label(for: "name") { "Name" }
        input(
          id: "name",
          type: "text",
          name: "user[name]",
          value: @user.name,
          class: [@errors[:name] ? "input-error" : nil]
        )
        
        label(for: "email") { "Email" }
        input(
          id: "email",
          type: "email",
          name: "user[email]",
          value: @user.email
        )
        
        input(type: "submit", value: "Sign Up")
      }
    }
  }
end
```

--------------------------------

### Implement Fragment Rendering

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/07-configuration-and-behavior.md

Define named fragments within a view template to allow selective rendering of component parts.

```ruby
class Page < Phlex::HTML
  def view_template
    fragment :header do
      header { h1 { "Title" } }
    end
    fragment :main do
      main { "Content" }
    end
  end
end

# Render only header
Page.new.call(fragments: [:header])

# Render header and main
Page.new.call(fragments: [:header, :main])
```

--------------------------------

### Merging Attributes with mix

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/05-types-and-interfaces.md

Demonstrates intelligent merging of attribute-like objects, including classes and styles.

```ruby
mix({class: "btn"}, {class: "primary"})  # => {class: "btn primary"}
mix({style: {color: "red"}}, {style: {padding: "10px"}})
# => {style: {color: "red", padding: "10px"}}
```

--------------------------------

### Using Phlex::SGML::SafeValue

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/09-security-reference.md

Wrap safe content using Phlex::SGML::SafeValue to prevent automatic escaping.

```ruby
safe_html = Phlex::SGML::SafeValue.new("<em>Highlighted</em>")

class Item < Phlex::HTML
  def view_template
    div { raw safe_html }
  end
end
```

--------------------------------

### List and Content XSS

Source: https://github.com/yippee-fun/phlex/blob/main/fixtures/xss.txt

Uses list styles or content properties to trigger alerts.

```html
<li style=list-style:url() onerror=alert(41)></li>
<div style=content:url(data:image/svg+xml,%3Csvg/%3E);visibility:hidden onload=alert(41)></div>
```

--------------------------------

### Embed SVG in HTML

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/03-svg-elements.md

Shows how to use the svg method within a Phlex::HTML component to switch rendering contexts.

```ruby
class Page < Phlex::HTML
  def view_template
    div {
      h1 { "Icon Gallery" }
      svg(viewBox: "0 0 100 100") {
        circle(cx: "50", cy: "50", r: "40", fill: "blue")
      }
    }
  end
end

# The svg method automatically switches to SVG rendering context
```

--------------------------------

### Implementing Custom Error Handling in Components

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/04-errors.md

Wrap rendering logic within a component's view_template to handle errors locally and display fallback UI.

```ruby
class SafeComponent < Phlex::HTML
  def initialize(data)
    @data = data
  end

  def view_template
    div {
      begin
        render_data(@data)
      rescue Phlex::ArgumentError => e
        p(class: "error") { "Invalid data: check your attributes" }
      end
    }
  end

  private def render_data(data)
    tag(:custom_tag, data: data)
  end
end
```

--------------------------------

### Render tables in Phlex

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/08-usage-patterns.md

Structure table elements using nested blocks for headers and rows.

```ruby
class ReportTable < Phlex::HTML
  def initialize(records)
    @records = records
  end

  def view_template
    table {
      thead {
        tr {
          th { "ID" }
          th { "Name" }
          th { "Status" }
        }
      }
      tbody {
        @records.each do |record|
          tr {
            td { record.id }
            td { record.name }
            td { record.status }
          }
        end
      }
    }
  end
end
```

--------------------------------

### capture

Source: https://github.com/yippee-fun/phlex/blob/main/_autodocs/01-core-classes.md

Captures the output of a block as a string instead of rendering it directly to the page.

```APIDOC
## capture(*args, &block)

### Description
Capture the output of a block as a string without rendering it to the page.

### Parameters
- **args** (varies) - Arguments passed to the block
- **block** (Proc) - Block whose output to capture

### Returns
- **String** - The captured output
```
Tokens:
Raw