orb_template 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b74243313337dd63535ee8506813a2f389bae51dc9acd867af03daa1698a4460
-  data.tar.gz: 7afda4bc5343e9ce87aebb99f0adaca66f9c46fb6cb47df861a3fb6db90753d6
+  metadata.gz: 72cfaec138706b6a2a92cec82fc558a6dfe13a56e21dbad5fa18fd5234104a08
+  data.tar.gz: 8fc11d77077c47693176181594c1ade6e39de19300ad66acfddbe9383bc8da3f
 SHA512:
-  metadata.gz: 46d2138975a21d7011c519f5621ca98058d6823c6c1fa1a33634e0acfd5baa18cdddf15a68902c00562721017ded9bf6cb7d489875586c4eb15f991bed4d3cf7
-  data.tar.gz: 2ffee3abc581416c96b294e4d8d2d9b6fc46f6b332fbb75d2eb91a74d1c67d5907624c5f3e7ecff8f954fbe5dd13765dcb3f76f026a52487e9547c251800bd07
+  metadata.gz: 3cd200ecc1e3292f31fa5d90120a97850b5e6494bc157ba77cad66ea77662be835723fb2fe6a1bc7056052ee120c8e73bde4abf62177e36acebc6d11e5eebbd2
+  data.tar.gz: eb9a1b1edb4e41cbbfeac8ff9f2230fb05ad1c9ea932c0a4bd2cdddb16697508394758a1b752121e1b2ea096f84dcdc9a6a1a245e87193657fb210d91be4a2a2

data/README.md

@@ -2,12 +2,8 @@
 
 [![Gem Version](https://badge.fury.io/rb/orb_template.svg)](https://badge.fury.io/rb/orb_template)
 
-
-
 https://github.com/user-attachments/assets/8380b9a8-2063-40f3-a9b6-1b5d623d6f31
 
-
-
 **ORB** is a template language for Ruby with the express goal of providing a first-class DSL for rendering [ViewComponents](https://viewcomponent.org). It is heavily inspired by [React JSX](https://react.dev/learn/writing-markup-with-jsx) and [Surface](https://surace-ui.org).
 
 ## Show me an Example
@@ -63,7 +59,6 @@ https://github.com/user-attachments/assets/8380b9a8-2063-40f3-a9b6-1b5d623d6f31
 - [Editor Support](#editor-support)
 - [Roadmap](#roadmap)
 
-
 ## Installation
 
 In your `Gemfile`, add:
@@ -78,13 +73,13 @@ then run:
 bundle install
 ```
 
-The gem automatically registers the `ORB` template engine as the renderer for `*.orb` template files through a Railtie.
+The gem automatically registers the `ORB` template engine as the renderer for `*.html.orb` view template files.
 
 ## Motivation
 
-There already exist a plethora of fast, battle-proven template langauges for the Ruby/Rails ecosystem, so why invent another one?
+There already exist a plethora of fast, battle-proven template languages for the Ruby/Rails ecosystem, so why invent another one?
 
-ORB was born out of the frustration that instantiating and rendering view components with existing template engines quickly becomes tedious. This hindered adoption of ViewComponents in our projects, impacted velocity, maintainance and new-developer onboarding. These effects were especially pronounced with highly customizable view components with long argument lists, as well as deeply nested components, and component trees - like a Design System / Component Library.
+ORB was born out of the frustration that instantiating and rendering view components with existing template engines quickly becomes tedious. This hindered adoption of ViewComponents in our projects, impacted velocity, maintenance and new-developer onboarding. These effects were especially pronounced with highly customizable view components with long argument lists, as well as deeply nested components, and component trees - like a Design System / Component Library.
 
 A common solution to making the rendering of view components less verbose is to define component-specific view helpers like so:
 
@@ -106,7 +101,7 @@ module ComponentsHelper
 end
 ```
 
-You can then using these view helpers in your front-end code, wherever a view components needs to be rendered:
+You can then use these view helpers in your front-end code, wherever a view components needs to be rendered:
 
 ```erb
 <%= card(title: "Your friends") do %>
@@ -128,17 +123,17 @@ The `ORB` template language takes another path and allows you to write component
   <Card:Section title="Birthdays today">
     <List>
       <List.Item>
-        <Link url={member_path(2)}>Carl Schwartz (27)</Link>
+        <Link url={member_path(2)} Carl Schwartz (27) />
       </List.Item>
       <List.Item>
-        <Link url={member_path(3)}>Floralie Brain (38)</Link>
+        <Link url={member_path(3)} Floralie Brain (38) />
       </List.Item>
     </List>
   </Card:Section>
 </Card>
 ```
 
-Your code becomes more focussed, grokable and maintainable. Front-end teams that may already be familiar with JSX or VUE can become productive faster, and can make use of their existing editor tooling for HTML like `Emmet` when writing templates.
+Your code becomes more focused, grokable and maintainable. Front-end teams that may already be familiar with JSX or VUE can become productive faster, and can make use of their existing editor tooling for HTML like `Emmet` when writing templates.
 
 ### Core Values
 
@@ -151,11 +146,10 @@ We believe that any template language should be enjoyable to the user:
 - Dynamic: Rendering with a context of local variables and objects is fast.
 - Polite: guide the user with useful error messages when their templates contain problems.
 
-
 ### Conventions
 
 - Components rendered by the `ORB` engine live under the configured namespace and omit the `Component` suffix from their class names.
-- Templates have a file extension of `.orb`, for example: `my_template.html.orb` for a template named `:my_template` that outputs in `format: :html`.
+- HTML view templates have a file extension of `.*.orb`, for example: `my_template.html.orb` for a template named `:my_template` that outputs in `format: :html`.
 
 ---
 
@@ -164,6 +158,7 @@ We believe that any template language should be enjoyable to the user:
 ORB fully supports the HTML5 markup language standard and extends HTML with additional syntax for expressions, dynamic attributes, blocks, components, slots, and comments.
 
 ### Configuration
+
 You can configure the `ORB` engine in your Rails application with an initializer, e.g., `config/initializers/orb.rb`:
 
 ```ruby
@@ -174,7 +169,7 @@ This will instruct the `ORB` engine to look for components under the `MyComponen
 
 ### HTML5
 
-Regular HTML tags are fully supported by `ORB`. Just write your HTML tags as you are used to and your are good to go.
+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
 <div id="page-banner" class="banner" aria-role="alert">
@@ -184,7 +179,7 @@ Regular HTML tags are fully supported by `ORB`. Just write your HTML tags as you
 
 ### Expressions
 
-`ORB` supports Ruby expressions in the code through double curly-braces (mustachy 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.:
+`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
 <div id="page-banner" class="banner" aria-role="alert">
@@ -226,38 +221,44 @@ For example, a `Banner` may be conditionally rendered through an `{#if}` block c
 
 ```html
 {#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
-<div id="{dom_id(banner)}" class="{banner.classNames}" :if={banner.urgent?}>
+<div id={dom_id(banner)} class={banner.classNames} :if={banner.urgent?}>
   <span class="message">{{banner.message}}</span>
 </div>
 ```
 
 ### Splatted Attributes
-`ORB` supports attribute splatting for both HTML tags and view components through the `**attributes` syntax. The expression provided for the splat must evaluate to a `Hash`, whose key-value pairs will be added as attributes to the tag. For example:
+
+`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>
+<div **banner_attributes>... 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>
+```
 
 ### View Components
 
-In `ORB` templates, you can render your view components as if they were HTML tags. The component class name is mapped to the tag name by omitting the configured namespace and the `Component` suffix.
+In `ORB` templates, you can render ViewComponents as if they were HTML tags. The `Component` suffix on ViewComponents may be omitted to make the markup nicer.
 
 For example, if you have a `Button` view component that may be defined as:
 
 ```ruby
-class MyComponents::Button < ::ViewComponent::Base
+class MyComponents::Button < ViewComponent::Base
   def initialize(url: "#", **options)
     @url = url
     @options = options
@@ -271,12 +272,14 @@ class MyComponents::Button < ::ViewComponent::Base
 end
 ```
 
-you can render the component in an ORB template `button.html.orb` as:
+you can render the 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.
+
 ### 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:
@@ -289,6 +292,8 @@ you can render the component in an ORB template `button.html.orb` as:
 </Card>
 ```
 
+Tip: Slot names are case-insensitive, so `<Card:section> ... </Card:section>` also works.
+
 ### Namespaces
 
 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:
@@ -317,14 +322,14 @@ Namespaces defined in this way will be searched in order of definition when reso
 
 **Public comments** are sent to the browser, and can be read by users inspecting the page source. ORB considers default HTML comments `<!-- -->` to be public comments.
 
-```heex
+```html
 <!-- I will be sent to the browser -->
 <p>Hello World!</p>
 ```
 
 **Private comments**, unlike public comments, won't be sent to the browser. Use private comments to mark up your ORB template with annotations that you do not wish users to see.
 
-```heex
+```ruby-orb
 {!-- I won't be sent to the browser --}
 <p>Hello World!</p>
 ```
@@ -337,6 +342,24 @@ Namespaces defined in this way will be searched in order of definition when reso
 
 Your favorite editor is not listed? Feel free to contribute an extension/plugin for your editor of choice!
 
+### Visual Studio Code
+
+To enable `Emmet` support for ORB, add this to your `settings.json`:
+
+```json
+"emmet.includeLanguages": {
+  "ruby-orb": "html",
+}
+```
+
+To enable `Tailwindcss` support for ORB, add this to your `settings.json`:
+
+```json
+"tailwindCSS.includeLanguages": {
+  "ruby-orb": "html"
+}
+```
+
 ## Roadmap
 
 - [x] **Step 1: Make it work**
@@ -361,6 +384,7 @@ Your favorite editor is not listed? Feel free to contribute an extension/plugin
 - [ ] **Step 2: Make it nice**
   - [x] improved errors with super helpful error messages and locations throughout the entire stack, possibly custom rendered error pages
   - [x] `**attribute` splats for html tags, components and slots
+  - [x] `**{expression}` splats for html tags, components and slots
   - [x] `:if` directive
   - [x] `:for` directive
   - [x] verbatim tags
@@ -391,12 +415,12 @@ Your favorite editor is not listed? Feel free to contribute an extension/plugin
   - [ ] support additional block constructs
   - [ ] support additional language constructs
 
-
 > This library is in beta stage and demonstrates the technical aspects of a custom DSL for rendering ViewComponent objects in an HTML-like manner. It is meant as a kick-off point for further discussion on the definition and implementation of the template language. It may contain critical bugs that could compromise the security and integrity of your application. Additionally, the API and DSL are likely to change as the library evolves to a stable state. Don't say we didn't warn you!
 
 ## Development
 
 To set up your development environment, follow these steps:
+
 1. Clone the repository:
 
    ```bash
@@ -414,20 +438,18 @@ To set up your development environment, follow these steps:
 
    ```bash
    make test
-    ```
+   ```
 
 4. Start the development server for the test application:
 
-    ```bash
-    bin/rails server
-    ```
-
+   ```bash
+   bin/rails server
+   ```
 
 ## Contributing
 
 This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. We recommend reading the [contributing guide](./docs/CONTRIBUTING.md) as well.
 
-
 ## License
 
 ORB is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/orb/patterns.rb

@@ -28,7 +28,8 @@ module ORB
     ATTRIBUTE_ASSIGN              = /=/
     SINGLE_QUOTE                  = /'/
     DOUBLE_QUOTE                  = /"/
-    SPLAT_START                   = /\*/
+    SPLAT_ATTRIBUTE               = %r{\*[^\s>/=]+}
+    SPLAT_EXPRESSION_START        = /\*\*\{/
     BRACE_OPEN                    = /\{/
     BRACE_CLOSE                   = /\}/
     CR                            = /\r/

data/lib/orb/rails_template.rb

@@ -39,7 +39,32 @@ module ORB
       end
 
       # Pipe through the ORB Temple engine
-      ORB::Temple::Engine.new(options).call(source)
+      code = ORB::Temple::Engine.new(options).call(source)
+
+      # Validate generated code with Prism to catch syntax errors BEFORE Rails does.
+      # This is a workaround for a Rails 8.1.1 bug where SyntaxErrorProxy fails
+      # is_a?(Exception) checks in ActiveSupport::ErrorReporter#report.
+      # See: rails-syntax-error-bug.md for details.
+      #
+      # Only run in development mode to avoid performance impact in production.
+      # In production, syntax errors will still be caught but with less friendly display.
+      if defined?(Prism) && defined?(Rails) && Rails.env.local?
+        result = Prism.parse(code)
+        if result.failure?
+          first_error = result.errors.first
+          error_line = first_error.location.start_line
+          message = first_error.message
+
+          # Return code that raises the error when executed.
+          # This way Rails' normal error handling will kick in, providing proper
+          # extracted source display and backtrace. We add newlines to position
+          # the error at the correct line number in the template.
+          escaped_message = message.gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")
+          return "#{'\\n' * (error_line - 1)}raise ORB::CompilerError.new('#{escaped_message}', #{error_line})"
+        end
+      end
+
+      code
     end
 
     # See https://github.com/rails/rails/pull/47005

data/lib/orb/tokenizer2.rb

@@ -139,6 +139,7 @@ module ORB
     end
 
     # Read next token in :tag_open_content state
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def next_in_tag_open_content
       if @source.scan(NEWLINE) || @source.scan(CRLF) || @source.scan(BLANK)
         move_by_matched
@@ -163,7 +164,13 @@ module ORB
         transition_to(:initial)
       elsif @source.scan(START_TAG_START)
         syntax_error!("Unexpected start of tag")
-      elsif @source.scan(%r{\*[^\s>/=]+})
+      elsif @source.scan(Patterns::SPLAT_EXPRESSION_START)
+        @attributes << [nil, :splat, nil]
+        clear_braces
+        clear_buffer
+        move_by_matched
+        transition_to(:splat_attribute_expression)
+      elsif @source.scan(Patterns::SPLAT_ATTRIBUTE)
         splat = @source.matched
         @attributes << [nil, :splat, splat]
         move_by_matched
@@ -173,6 +180,7 @@ module ORB
         syntax_error!("Unexpected '#{@source.peek(1)}'")
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # Read next token in :attribute_name state
     def next_in_attribute_name
@@ -275,6 +283,32 @@ module ORB
       end
     end
 
+    # Read next token in :splat_attribute_expression state
+    def next_in_splat_attribute_expression
+      if @source.scan(BRACE_OPEN)
+        @braces << "{"
+        buffer_matched
+        move_by_matched
+      elsif @source.scan(BRACE_CLOSE)
+        if @braces.any?
+          @braces.pop
+          buffer_matched
+          move_by_matched
+        else
+          splat_expression = consume_buffer
+          current_attribute[2] = "**#{splat_expression.strip}"
+          move_by_matched
+          clear_braces
+          transition_to(:tag_open_content)
+        end
+      elsif @source.scan(NEWLINE) || @source.scan(CRLF) || @source.scan(BLANK) || @source.scan(OTHER)
+        buffer_matched
+        move_by_matched
+      else
+        syntax_error!("Unexpected end of input while reading splat attribute value")
+      end
+    end
+
     # Read next token in :attribute_value_unquoted state
     def next_in_attribute_value_unquoted
       if @source.scan(UNQUOTED_VALUE)

data/lib/orb/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orb_template
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - KUY.io Inc.