orb_template 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd68f471e3fbd9acaad2e9c35de29d1b7007c012095b477bdedc0ee2e5c97f8e
-  data.tar.gz: fc4531a398382faea20b133b34b57b821826bd98390bcf30d1017016b3538114
+  metadata.gz: 9cef68c21c57f074ee08bb76aacb4d88df41ff5726ca65cf3ef1c579e5d56e8d
+  data.tar.gz: 3fb10347aada2d9fcd845e8590aaea771c2260b907cdc55f87927ff2afde44de
 SHA512:
-  metadata.gz: 7643721a1c16badd894605c1e99832ed2ea782ff2f67b5169b0ef26ee6b97b36ecd7f201adfb61976a93cdcbc8925a2dbcc7a7aa0240a660f6521c268b4abc7c
-  data.tar.gz: d33b3d3c66f7915d3e03057050e97fad95d2de709e34edd2f12b6522d49dcb1f961d798527490f84d9001218718af48469f523e927be8da52c0bcff09108650b
+  metadata.gz: 05debe94445dee051e126bf574ba1ed3d2ea93030fe86225261da50ae33af39c7d77b75d9b7f2607e98b655c8076c83a4dc5c111ef8810292353d1f2104fdb65
+  data.tar.gz: 9a2469f3a8a7379f84cbcf3bd78644b15f7bc89e5da2c350d73e9b82c60cbf8f97dff305bee834a470b4021c2a685aee672a1a6fb1097e0fdf9c7eef53eee0f2

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-11-04
+
+### Changed
+
+- **Breaking:** Require Ruby 3.4 or newer.
+- `ORB.html_escape` now delegates to `Temple::Utils.escape_html`. (`lib/orb.rb`)
+- `make test` now also runs the benchmark suite, and `make trivy` lists lower-severity findings without failing on them.
+
+### Fixed
+
+- Stop loading `cgi/util`, which removes the load warning on Ruby 4.0. `ORB.html_escape` still handles non-ASCII-compatible strings such as UTF-16 and returns them in their original encoding. (`lib/orb.rb`)
+- `ORB::VERSION` is now defined after `require "orb"`. Previously it raised `NameError` when the gem was loaded outside bundler. (`lib/orb.rb`)
+
+## [0.2.5] - 2026-04-28
+
+### Added
+
+- `:unwrap` directive — conditionally strips a wrapper element while keeping its children. When the condition is true, only the children are rendered; when false, the element renders normally. Works on both HTML elements and components, and composes with `:if` and `:for`. (`lib/orb/temple/compiler.rb`, `lib/orb/temple/filters.rb`, `lib/orb/ast/tag_node.rb`)
+
+### Fixed
+
+- Fixed directive priority order: `:for` is now always outermost, followed by `:if`, then `:unwrap`. Previously, `:if` and `:unwrap` wrapped outside `:for`, which caused `NameError` at runtime when `:if` or `:unwrap` conditions referenced the loop variable (e.g., `<li :if={visible?(item)} :for="item in @items">`). (`lib/orb/temple/compiler.rb`)
+
+### Changed
+
+- Refactored `compiler_directives?` to use a `COMPILER_DIRECTIVES` constant set instead of chained `||` conditions, making it trivial to add future directives (`lib/orb/ast/tag_node.rb`)
+- Refactored `transform_directives_for_tag_node` into `handle_if`, `handle_unwrap`, and `handle_for` helper methods, keeping the entry point as a single-line priority chain (`lib/orb/temple/compiler.rb`)
+- Replaced `rails` gem with `railties`, `actionpack`, and `activemodel` in the test dummy app, removing unused frameworks (ActionCable, ActionText, ActiveStorage, ActionMailbox, ActionMailer, ActiveRecord) and reducing the dependency surface from 116 to 98 gems
+- Added `make security` target running bundler-audit, brakeman, and trivy; integrated into the `make test` pipeline
+
 ## [0.2.4] - 2026-03-22
 
 ### Fixed

data/README.md

@@ -28,12 +28,12 @@ https://github.com/user-attachments/assets/8380b9a8-2063-40f3-a9b6-1b5d623d6f31
 
 **The ORB Way**
 
-```html
+```jsx
 <Card title="Your friends">
   <Card:Section title="Birthdays today">
     <List>
       <List.Item :for={friend in @friends}>
-        <Link url={friend_path(friend)}>{{friend.name}}</Link>
+        <Link url={member_path(friend)}>{{friend.name}}</Link>
       </List.Item>
     </List>
   </Card:Section>
@@ -118,15 +118,15 @@ But that's still not ideal. The code is still verbose, and the heavy use of Ruby
 
 The `ORB` template language takes another path and allows you to write components exactly how you picture them: as elements in a document tree.
 
-```html
+```jsx
 <Card title="Your friends">
   <Card:Section title="Birthdays today">
     <List>
       <List.Item>
-        <Link url={member_path(2)} Carl Schwartz (27) />
+        <Link url={member_path(2)}>Carl Schwartz (27)</Link>
       </List.Item>
       <List.Item>
-        <Link url={member_path(3)} Floralie Brain (38) />
+        <Link url={member_path(3)}>Floralie Brain (38)</Link>
       </List.Item>
     </List>
   </Card:Section>
@@ -171,7 +171,7 @@ This will instruct the `ORB` engine to look for components under the `MyComponen
 
 Regular HTML tags are fully supported by `ORB`. Just write your HTML tags as you are used to and you are good to go.
 
-```html
+```jsx
 <div id="page-banner" class="banner" aria-role="alert">
   <span class="message">Hello World!</span>
 </div>
@@ -181,7 +181,7 @@ Regular HTML tags are fully supported by `ORB`. Just write your HTML tags as you
 
 `ORB` supports Ruby expressions in the code through double curly-braces (mustache-like syntax). The code inside the curly-braces will be evaluated at render time, and the result will be HTML-safe escaped and inserted into the output.:
 
-```html
+```jsx
 <div id="page-banner" class="banner" aria-role="alert">
   <span class="message">{{banner.message}}</span>
 </div>
@@ -189,7 +189,7 @@ Regular HTML tags are fully supported by `ORB`. Just write your HTML tags as you
 
 Should you need to execute non-printing code, for instance to assign local variables, you can use the non-printing expression syntax with percent signs:
 
-```html
+```jsx
 {% user = current_user %}
 
 <div id="page-banner" class="banner" aria-role="alert">
@@ -203,7 +203,7 @@ The `ORB` language allows you to define dynamic attribute values for HTML tags t
 
 Example:
 
-```html
+```jsx
 <div id={dom_id(banner)} class={banner.classes}>
   <span class="message">{{banner.message}}</span>
 </div>
@@ -213,42 +213,142 @@ Example:
 
 `ORB` supports flow control constructs through block instructions. The general syntax for a block is:
 
-```html
+```jsx
 {#blockname expression} ... {/blockname}
 ```
 
 For example, a `Banner` may be conditionally rendered through an `{#if}` block construct like this:
 
-```html
+```jsx
 {#if banner.urgent?}
-<div id={dom_id(banner)} class={banner.classNames}>
-  <span class="message">{{banner.message}}</span>
-</div>
+  <div id={dom_id(banner)} class={banner.classNames}>
+    <span class="message">{{banner.message}}</span>
+  </div>
 {/if}
 ```
 
 Since control flow is such a common thing in templates, `ORB` provides special syntactic sugar for the `{#if}` and `{#for}` blocks through the `:if` and `:for` directives on HTML tags. The above example can thus be rewritten as:
 
-```html
+```jsx
 <div id={dom_id(banner)} class={banner.classNames} :if={banner.urgent?}>
   <span class="message">{{banner.message}}</span>
 </div>
 ```
 
+#### The `:unwrap` Directive
+
+The `:unwrap` directive conditionally strips a wrapper element while keeping its children. When the condition is true, only the children are rendered. When false, the element renders normally with its children inside.
+
+```jsx
+<div class="tooltip-wrapper" :unwrap={!@needs_tooltip}>
+  <span>Always rendered</span>
+</div>
+```
+
+| `:unwrap` condition | Result |
+|---|---|
+| `true` | Children only (`<span>Always rendered</span>`) |
+| `false` | Full element (`<div class="tooltip-wrapper"><span>...</span></div>`) |
+
+This eliminates the need to duplicate child markup when a wrapper is conditional:
+
+```jsx
+{!-- Before: duplicated children --}
+<Tooltip :if={@is_last_method} description="Only active method.">
+  <Toggle><Toggle:Option label="On" /><Toggle:Option label="Off" /></Toggle>
+</Tooltip>
+{#if !@is_last_method}
+  <Toggle><Toggle:Option label="On" /><Toggle:Option label="Off" /></Toggle>
+{/if}
+
+{!-- After: single child block, zero duplication --}
+<Tooltip description="Only active method." :unwrap={!@is_last_method}>
+  <Toggle><Toggle:Option label="On" /><Toggle:Option label="Off" /></Toggle>
+</Tooltip>
+```
+
+`:unwrap` works on both HTML elements and components.
+
+#### Combining Directives
+
+Multiple directives can be combined on the same element. When they are, they are evaluated in a fixed priority order, regardless of the order they appear in the template:
+
+> **`:for`** (outermost) > **`:if`** > **`:unwrap`** (innermost)
+
+This ordering ensures that loop variables introduced by `:for` are always in scope for `:if` and `:unwrap` conditions.
+
+**`:for` + `:if`** — filter items inside a loop:
+
+```jsx
+<li :for="item in @items" :if={item.visible?}>{{item.name}}</li>
+```
+
+The `:for` loop runs first, then `:if` is evaluated per iteration with `item` in scope:
+
+```ruby
+@items.each do |item|
+  if item.visible?
+    _buf << "<li>" << escape_html(item.name) << "</li>"
+  end
+end
+```
+
+**`:for` + `:unwrap`** — conditionally strip wrappers per item:
+
+```jsx
+<li :for="item in @items" :unwrap={item.inline?}>{{item.name}}</li>
+```
+
+```ruby
+@items.each do |item|
+  if item.inline?
+    _buf << escape_html(item.name)
+  else
+    _buf << "<li>" << escape_html(item.name) << "</li>"
+  end
+end
+```
+
+**`:if` + `:unwrap`** — conditionally render, conditionally wrap:
+
+```jsx
+<Tooltip description="..." :if={@show_section} :unwrap={!@needs_tooltip}>
+  <Badge label="Status" />
+</Tooltip>
+```
+
+| `@show_section` | `@needs_tooltip` | Result |
+|---|---|---|
+| `false` | (any) | Nothing |
+| `true` | `true` | `<Tooltip>` wrapping `<Badge>` |
+| `true` | `false` | `<Badge>` alone |
+
+**All three** — loop, filter, and conditionally wrap:
+
+```jsx
+<li :for="item in @items" :if={item.visible?} :unwrap={item.inline?}>
+  {{item.name}}
+</li>
+```
+
 ### Splatted Attributes
 
 `ORB` supports attribute splatting for both HTML tags and view components through the `**attributes` syntax. The attribute name for the splat must be a `Hash`; all key-value pairs will be added as attributes to the tag. For example:
 
-```html
-<div **banner_attributes>... content ...</div>
+```jsx
+<div **banner_attributes>
+  <!-- other content ... -->
+</div>
 ```
 
 ### Splatted Attribute Expressions
 
 You can also use an expression to define the splatted attributes through the `**{expression}` syntax. The expression must evaluate to a `Hash`, and all key-value pairs will be added as attributes to the tag. For example:
 
-```html
-<div **{dynamic_attributes}>... content ...</div>
+```jsx
+<div **{dynamic_attributes(member)}>
+  <!-- other content ... -->
+</div>
 ```
 
 ### View Components
@@ -272,19 +372,56 @@ class MyComponents::Button < ViewComponent::Base
 end
 ```
 
-you can render the component in an ORB template `show.html.orb` as:
+You can render this component in an ORB template `show.html.orb` as:
 
 ```jsx
 <Button url="/click_me">I am a button</Button>
 ```
 
-Tip: you can also define the markup for a component inline as an `orb_template <<-ORB ... ORB` block to use the `ORB` template language for the component's own view template.
+### Inline Templates
+
+You can define the markup for a component inline using `orb_template` to use the ORB template language for the component's own view template:
+
+```ruby
+class ButtonComponent < ViewComponent::Base
+  def initialize(url:)
+    @url = url
+  end
+
+  orb_template <<~ORB
+    <a href={@url} class="btn">{{ content }}</a>
+  ORB
+end
+```
+
+If your template needs string interpolation, you have several options:
+
+```ruby
+# 1. Single-quoted heredoc (recommended) — #{} is preserved for render time
+orb_template <<~'ORB'
+  <div id={"#{@id}_suffix"}>Hello</div>
+ORB
+
+# 2. String concatenation — avoids #{} entirely
+orb_template <<~ORB
+  <div id={@id + "_suffix"}>Hello</div>
+ORB
+
+# 3. Helper method — move the interpolation into Ruby
+orb_template <<~ORB
+  <div id={suffixed_id}>Hello</div>
+ORB
+
+def suffixed_id
+  "#{@id}_suffix"
+end
+```
 
 ### ViewComponent Slots
 
 `ORB` also provides a DSL for invoking a component slot and passing content to the slot through the `Component:Slot` syntax. For example, if you have a `Card` component that defines a `Sections` slot via `renders_many :sections, Card::Section`, you can invoke and fill the slot in an `ORB` template like this:
 
-```html
+```jsx
 <Card title="Products">
   <Card:Section title="Description">
     <p>Blue t-shirt in size L ...</p>
@@ -298,13 +435,13 @@ Tip: Slot names are case-insensitive, so `<Card:section> ... </Card:section>` al
 
 Sometimes, you may want to organize your components in sub-namespaces, or use components from other libraries. `ORB` supports this through dot notation in the tag names. For example, if you have a `MyComponents::Admin::Button` component, you can render it in an `ORB` template like this:
 
-```html
+```jsx
 <Admin.Button url="/admin/click_me">Admin Button</Admin.Button>
 ```
 
 If you have a third-party component `ThirdParty::UI::Modal`, you can render it like this:
 
-```html
+```jsx
 <ThirdParty.UI.Modal title="Terms and Conditions">
   <p>...</p>
 </ThirdParty.UI.Modal>
@@ -313,7 +450,7 @@ If you have a third-party component `ThirdParty::UI::Modal`, you can render it l
 To make life easier when using components from a specific namespace frequently, you can configure additional namespaces in the `ORB` configuration:
 
 ```ruby
-ORB.namespaces = ['MyComponents ThirdParty::UI']
+ORB.namespaces = ['MyComponents', 'ThirdParty::UI']
 ```
 
 Namespaces defined in this way will be searched in order of definition when resolving component tag names in templates.
@@ -387,6 +524,7 @@ To enable `Tailwindcss` support for ORB, add this to your `settings.json`:
   - [x] `**{expression}` splats for html tags, components and slots
   - [x] `:if` directive
   - [x] `:for` directive
+  - [x] `:unwrap` directive
   - [x] verbatim tags
   - [x] ensure output safety and proper escaping of output
   - [x] security review and hardening of compilation pipeline

data/lib/orb/ast/tag_node.rb

@@ -192,8 +192,10 @@ module ORB
         directives.any?
       end
 
+      COMPILER_DIRECTIVES = %i[if unwrap for].freeze
+
       def compiler_directives?
-        directives.any? { |k, _v| k == :if || k == :for }
+        directives.any? { |k, _v| COMPILER_DIRECTIVES.include?(k) }
       end
 
       ##

data/lib/orb/temple/compiler.rb

@@ -155,24 +155,31 @@ module ORB
 
       # Compile a tag node with directives
       def transform_directives_for_tag_node(node)
-        # First, process any :if directives
-        if_directive = node.directives.fetch(:if, false)
-        if if_directive
-          node.remove_directive(:if)
-          return [:if,
-            if_directive,
-            transform(node)]
-        end
+        handle_for(node) || handle_if(node) || handle_unwrap(node) || transform(node)
+      end
 
-        # Second, process any :for directives
-        for_directive = node.directives.fetch(:for, false)
-        if for_directive
-          node.remove_directive(:for)
-          return [:orb, :for, for_directive, transform(node)]
-        end
+      def handle_if(node)
+        directive = node.directives.fetch(:if, false)
+        return unless directive
+
+        node.remove_directive(:if)
+        [:if, directive, transform(node)]
+      end
+
+      def handle_unwrap(node)
+        directive = node.directives.fetch(:unwrap, false)
+        return unless directive
+
+        node.remove_directive(:unwrap)
+        [:orb, :unwrap, directive, transform(node), transform_children(node)]
+      end
+
+      def handle_for(node)
+        directive = node.directives.fetch(:for, false)
+        return unless directive
 
-        # Last, render as a dynamic node expression
-        transform(node)
+        node.remove_directive(:for)
+        [:orb, :for, directive, transform(node)]
       end
 
       # Compile a dynamic tag node

data/lib/orb/temple/filters.rb

@@ -127,6 +127,19 @@ module ORB
         result
       end
 
+      # Handle an unwrap directive expression `[:orb, :unwrap, condition, element, children]`
+      #
+      # When condition is true, renders only the children (unwrapped).
+      # When condition is false, renders the full element with children inside.
+      #
+      # @param [String] condition The condition to be evaluated
+      # @param [Array] element The full element Temple expression
+      # @param [Array] children The children-only Temple expression
+      # @return [Array] compiled Temple expression
+      def on_orb_unwrap(condition, element, children)
+        [:if, condition, compile(children), compile(element)]
+      end
+
       # Handle a for block expression `[:orb, :for, expression, content]`
       #
       # @param [String] expression The iterator expression to be evaluated

data/lib/orb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ORB
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/lib/orb.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require 'temple'
-require 'cgi/util'
 
+require_relative "orb/version"
 require_relative "orb/errors"
 require_relative "orb/token"
 require_relative "orb/tokenizer"
@@ -34,7 +34,11 @@ module ORB
   end
 
   def self.html_escape(str)
-    CGI.escapeHTML(str.to_s)
+    str = str.to_s
+    return ::Temple::Utils.escape_html(str) if str.encoding.ascii_compatible?
+
+    # The native escaper can't handle encodings such as UTF-16 on Ruby 3.4.
+    ::Temple::Utils.escape_html(str.encode(Encoding::UTF_8)).encode(str.encoding)
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orb_template
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - KUY.io Inc.
@@ -34,12 +34,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
-- Makefile
 - README.md
-- Rakefile
-- docs/2026-03-12-security-analysis.md
 - lib/orb.rb
 - lib/orb/ast.rb
 - lib/orb/ast/abstract_node.rb
@@ -92,14 +88,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.23
 specification_version: 4
 summary: The ORB template language for Ruby.
 test_files: []

data/CODE_OF_CONDUCT.md

@@ -1,132 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations