relay_ui 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48ac05153d26910dcdc24eebad0761c52fa937a8f126a78f2e64d25a8f436505
-  data.tar.gz: 907342ba056ebb313354187fb6c34328c3029a818c7e024ad86915fe079dad2d
+  metadata.gz: 7158b2530047c016d6353aba1125ad761104ae2f553656c3d28c40cf6fc74f4a
+  data.tar.gz: 917a96410664ca64d92e4f41c86d7af74ebcbdc27511dbcf167fc74bd45bec26
 SHA512:
-  metadata.gz: cd29c8eac7f421ba53e512403c940b6b71a586c3311507e005eac4b88f7fdc2b5919c116e4c78e4df210c41cf8fa8e05db808e3e5df25f272a067f34f74b17d6
-  data.tar.gz: 40da871a68f19836353ba5a92faae889e3196d851daedc5be69f141cf2c6465dccb63613a9bfc770e2ec415ced6fce4be244e7456f2e038c174d2046f5333042
+  metadata.gz: cad6bf23e5f39a374115580a70469e382cfdb3578f0c553a04394b73632902484ba479755430eed9ad5af782a7ec633f57fe8d97ea5e75404a7609463221ebf9
+  data.tar.gz: 9f9bc6189f61911c6691b73ba0e6822fd586d339c859714d492db5b5587d3e2fcc2ea5e6c20ae0b18fff65f92872124999798c66200a84308f119e5ce7aeeab1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 LogicRelay LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# RelayUI
+
+> [!WARNING]
+> This project is extremely new, and we're still working out the kinks. While it is just being used for the first time in new production apps, we're not yet ready to recommend it quite yet. It's highly likely that the API will change frequently in ways that will be extremely disruptive to your codebase. Use at your own risk for now, and we'll update this warning when we're ready to recommend it. Look for a 1.0.0 release sometime in Q2 2025.
+
+RelayUI is a set of highly prescriptive UI elements written in Phlex and designed for Ruby and Rails applications. We know what you're thinking: "Another UI kit? Really?" But hear us out...
+
+We generally see two types of UI kits available today:
+- **Highly flexible and customizable UI kits** - These are great for building consumer-facing apps where you need to have a unique look and feel, but they can create a lot of overhead for developers who just want to get business value out the door quickly. Many of them also rely on code generation, and we wanted a solution that could be updated via bundler.
+- **Paid UI kits** - These are great for businesses that want to get something out the door quickly and don't mind paying for it, but we like open-source software and we think that there's a place for a free, easy-to-use UI kit.
+
+This is why RelayUI was created. It's purposefully inflexible, meant to provide a baseline set of functionality that covers 80-90% of use cases so developers can skip decisions like what icons to use or how to style buttons and focus on the stuff that matters.
+
+RelayUI is supported by [LogicRelay](https://www.logicrelay.com), a software development agency that specializes in rapid creation of business software. We created RelayUI to help us build software faster and more consistently, and we're sharing it with the world in the hopes that it will help others do the same.
+
+## Why Phlex?
+
+[Phlex](https://github.com/phlex-ruby/phlex) is a Ruby-based DSL for building HTML views and components. After experimenting with [ViewComponents](https://viewcomponent.org/) and using the gem in some projects, we found the differentiation between views and presenter logic to be cumbersome at scale. Phlex provides the power of ruby in your views without the need for a separate presenter layer, and it's fast. Really fast.
+
+Our Phlex components [can be rendered in plain-old `erb` files](https://www.phlex.fun/components/rendering.html#rendering-phlex-components-in-erb), but we think you'll find that the Phlex DSL is so easy to use that you'll want to use it everywhere.
+
+## The RUI Namespace
+
+All of RelayUI's components are housed in the `RUI::` namespace. This turns your IDE's autocomplete into a powerful tool for building UIs quickly. Just type `RUI::` and see what's available!
+
+With this in mind, we prefer pulling basic variants up to the model level. Whereas many UI kits may specify variants via parameters (eg: `Component.new(variant: :primary)`), we prefer to give major variants class-level importance. So, we'll opt for patterns like `RUI::Buttons::Primary` and `RUI::Buttons::Secondary` instead.
+
+## Using TailwindCSS
+
+RelayUI uses [TailwindCSS v4](https://tailwindcss.com/) for styling under the hood. One of the challenges we aimed to solve is how to include the styles Tailwind provides in a way that doesn't collide with any other CSS styles or frameworks being used. For example, we wanted to make sure RelayUI still worked well in projects that used Tailwind v3, or even Bootstrap.
+
+For that reason, we've decided to prefix our CSS classes with `rui:`. This way, RelayUI is able to come out of the box with all of the styles you need to make our components work, but you can choose to use any CSS framework you want and not risk any CSS class conflicts or collisions.
+STRING
+
+# Installation
+
+### First, add the gem to your `Gemfile`:
+
+```ruby
+gem 'relay_ui'
+```
+
+### Then install your gems:
+
+```shell
+bundle install
+```
+
+### Or install it directly:
+
+```shell
+gem install relay_ui
+```
+
+### Include the gem's stylesheet in your application layout:
+
+```ruby
+stylesheet_link_tag "relay_ui/relay_ui", media: "all"
+```
+
+That's it! All of the basic functionality of the UI kit is now available to you. For certain components that require additional elements (like stimulus controllers), you'll need to include those separately. They will be documented in the component's usage instructions.
+
+# Usage
+
+The usage docs can be found at https://www.relayui.com
+
+# Contributing
+
+**If you're interested in contributing on this project we'd love to chat with you on [our Discord server](https://discord.gg/wPyvK87KFe).**
+
+There's a lot of work to be done on this project, and we're always looking for help. Here's some details on how we're going about building this kit:
+
+- We have a [public roadmap](https://github.com/orgs/logicrelay/projects/14/views/3) that we're using to track features that are slated for the next release and features that haven't been prioritized yet.
+- We're using [Github Projects](https://github.com/orgs/logicrelay/projects/14/views/1) to track WIP features and bugs.
+- We'll generally spec out a milestone in a JIT fashion as the previous milestone is released.
+
+## Prerequisites
+
+There are a couple of things you'll need to do to get your environment set up for contributing to this project:
+
+- **mise** - We use [`mise`](https://mise.jdx.dev/getting-started.html) to manage our development environment and provide easy access to the tools we need to work on the project.
+- **bundler config** - You'll need to set the local path to the root directory of the project by running the following command in the root of the repo: `bundle config local.relay_ui /path/to/relay_ui`. This will allow you to work on the UI kit locally and see changes in real time.
+- **LiveReload** - [LiveReload](https://addons.mozilla.org/en-US/firefox/addon/livereload/) is not a must have, but it's a nice to have. It will automatically refresh your browser when you're working on the UI kit locally.
+
+## Tooling
+
+There are three processes to run locally when developing...
+- `mise run watch` starts the watch process that generates a combined CSS file using TailwindCSS.
+- `mise run guard` runs `guard` and `guard-livereload` (optional)
+- `mise run server` starts the local server.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[Maintained by the team @ LogicRelay](https://www.logicrelay.com/)
+
+## Code of Conduct
+
+Everyone interacting in the RelayUi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/relay_ui/blob/main/CODE_OF_CONDUCT.md).

data/lib/relay_ui/engine.rb

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 
-module RelayUi
-  class Engine < ::Rails::Engine
-    isolate_namespace RelayUi
+module RUI
+  if defined?(Rails)
+    class Engine < ::Rails::Engine
+      isolate_namespace RUI
 
-    initializer "relay_ui.assets.precompile" do |app|
-      app.config.assets.paths << root.join("vendor", "assets", "stylesheets")
-      app.config.assets.paths << root.join("vendor", "assets", "javascripts")
-    end
-
-    initializer "relay_ui.autoload.components" do
-      Rails.autoloaders.main.push_dir(
-        "#{Gem::Specification.find_by_name('relay_ui').gem_dir}/app/components",
-        namespace: RelayUi
-      )
+      initializer "relay_ui.autoload.components" do
+        Rails.autoloaders.main.push_dir(
+          "#{Gem::Specification.find_by_name('relay_ui').gem_dir}/lib/rui",
+          namespace: RUI
+        )
+      end
     end
   end
-end
+end

data/lib/relay_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module RelayUi
-  VERSION = "0.1.1"
+module RUI
+  VERSION = "0.3.0"
 end

data/lib/relay_ui.rb

@@ -3,7 +3,7 @@
 require_relative "relay_ui/version"
 require_relative "relay_ui/engine"
 
-module RelayUi
+module RUI
   class Error < StandardError; end
   # Your code goes here...
 end

data/lib/rui/badges/base.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class RUI::Badges::Base < RUI::Base
+  def view_template
+    div do
+      span(class: "whitespace-nowrap px-3 py-0.5 text-xs rounded-full text-center font-medium #{variant_classes}") { yield }
+    end
+  end
+end

data/lib/rui/badges/blue.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Badges::Blue < RUI::Badges::Base
+  private
+
+  def variant_classes = "bg-blue-100 text-blue-700"
+end

data/lib/rui/badges/gray.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Badges::Gray < RUI::Badges::Base
+  private
+
+  def variant_classes = "bg-gray-100 text-gray-700"
+end

data/lib/rui/badges/green.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Badges::Green < RUI::Badges::Base
+  private
+
+  def variant_classes = "bg-green-100 text-green-700"
+end

data/lib/rui/badges/purple.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Badges::Purple < RUI::Badges::Base
+  private
+
+  def variant_classes = "bg-purple-100 text-purple-700"
+end

data/lib/rui/badges/red.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Badges::Red < RUI::Badges::Base
+  private
+
+  def variant_classes = "bg-red-100 text-red-700"
+end

data/lib/rui/badges/yellow.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Badges::Yellow < RUI::Badges::Base
+  private
+
+  def variant_classes = "bg-yellow-100 text-yellow-700"
+end

data/lib/rui/badges.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+module RUI::Badges; end

data/lib/rui/base.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class RUI::Base < Phlex::HTML
+  def initialize(**attrs, &)
+    @attrs = attrs
+    super(&)
+  end
+end

data/lib/rui/buttons/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class RUI::Buttons::Base < RUI::Base
+  def initialize(icon: nil, **attrs)
+    @icon = icon
+    @attrs = attrs
+  end
+
+  def view_template
+    button(class: classes, **@attrs) do
+      div(class: "flex flex-row items-center gap-2") do
+        if @icon
+          div(class: "size-4 my-1") do
+            render RUI::Icon.new(@icon)
+          end
+        end
+        span(class: "text-nowrap") { yield } if block_given?
+      end
+    end
+  end
+
+  private
+
+  def classes
+    "#{base_classes} #{variant_classes}"
+  end
+
+  def base_classes = "inline-block px-2 py-1 hover:cursor-pointer rounded-md transition duration-200 ease-in-out"
+end

data/lib/rui/buttons/destructive.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Buttons::Destructive < RUI::Buttons::Base
+  private
+
+  def variant_classes = "bg-red-700 hover:bg-red-900 text-white border border-red-700 hover:border-red-900"
+end

data/lib/rui/buttons/ghost.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Buttons::Ghost < RUI::Buttons::Base
+  private
+
+  def variant_classes = "hover:bg-zinc-100"
+end

data/lib/rui/buttons/outline.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Buttons::Outline < RUI::Buttons::Base
+  private
+
+  def variant_classes = "border rounded border-zinc-300 hover:border-zinc-700 text-zinc-700"
+end

data/lib/rui/buttons/primary.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Buttons::Primary < RUI::Buttons::Base
+  private
+
+  def variant_classes = "bg-blue-700 hover:bg-blue-900 text-white border border-blue-700 hover:border-blue-900"
+end

data/lib/rui/buttons/secondary.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Buttons::Secondary < RUI::Buttons::Base
+  private
+
+  def variant_classes = "bg-zinc-700 hover:bg-zinc-900 text-white border border-zinc-700 hover:border-zinc-900"
+end

data/lib/rui/buttons.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+module RUI::Buttons; end

data/lib/rui/card.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+class RUI::Card < RUI::Base
+  def view_template(&)
+    div(role: "region", aria: { label: "Card" }, **@attrs) do
+      div(
+        class: "#{padding(capture(&))} flex flex-col gap-4 border border-zinc-300 rounded-lg overflow-hidden",
+        data: { component: "card" },
+        &
+      )
+    end
+  end
+
+  def header(&)
+    render Header.new(&)
+  end
+
+  def image(&)
+    img(src: capture(&))
+  end
+
+  def body(&)
+    div(class: "px-4", &)
+  end
+
+  def footer(&)
+    render Footer.new(&)
+  end
+
+  class Header < RUI::Base
+    def view_template(&)
+      header(class: "flex flex-row justify-between items-center gap-4 px-4", &)
+    end
+
+    def thumbnail(&)
+      img(src: capture(&), class: "inline-block rounded-full size-10")
+    end
+
+    def titles(&)
+      render Titles.new(&)
+    end
+
+    def actions(&)
+      div(class: "flex flex-row gap-2 items-center", &)
+    end
+
+    class Titles < RUI::Base
+      def view_template(&)
+        div(class: "grow shrink basis-0 flex flex-col", &)
+      end
+
+      def title(&)
+        h2(class: "text-xl font-semibold", &)
+      end
+
+      def subtitle(&)
+        h3(class: "text-lg", &)
+      end
+    end
+  end
+
+  class Footer < RUI::Base
+    def view_template(&)
+      footer(class: "flex flex-row justify-end items-center gap-4 px-4", &)
+    end
+
+    def actions(&)
+      render Actions.new(&)
+    end
+
+    class Actions < RUI::Base
+      def view_template(&)
+        div(class: "flex flex-row gap-2 items-center", &)
+      end
+
+      def action(href: "#", **kwargs, &)
+        a(href:, class: "text-blue-700 hover:underline uppercase text-sm font-semibold", **kwargs, &)
+      end
+    end
+  end
+
+  private
+
+  def padding(content)
+    return if content.empty?
+    padding = []
+    doc = Nokogiri::HTML::DocumentFragment.parse(content)
+    padding << "pt-4" if doc.children.first.name != "img"
+    padding << "pb-4" if doc.children.last.name != "img"
+    padding.join(" ")
+  end
+end

data/lib/rui/flash.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class RUI::Flash < RUI::Base
+  def initialize(variant = "alert")
+    @variant = variant
+  end
+
+  def view_template
+    div(role: "alert", data: { controller: "flash" }, class: "lg:max-w-lg border p-3 lg:px-5 lg:py-3 rounded-lg opacity-0 transition-opacity duration-100 ease-in-out " + classes) do
+      div(class: "flex flex-row items-center justify-between gap-3") do
+        div(class: "w-6") { render RUI::Icon.new(icon) }
+        p(class: "w-full") { yield }
+        button(class: "w-6 hover:cursor-pointer", data: { action: "flash#close" }) do
+          render RUI::Icon.new("x")
+        end
+      end
+    end
+  end
+
+  private
+
+  def classes = {
+    "notice" => "bg-blue-50 text-blue-900 border-blue-500",
+    "success" => "bg-green-50 text-green-900 border-green-500",
+    "alert" => "bg-yellow-50 text-yellow-900 border-yellow-500",
+    "failure" => "bg-red-50 text-red-900 border-red-500"
+  }.fetch @variant, "bg-zinc-50 text-zinc-900 border-zinc-500"
+
+  def icon = {
+    "notice" => "info-circle",
+    "success" => "circle-check",
+    "alert" => "alert-triangle",
+    "failure" => "flag"
+  }.fetch @variant, "alert-circle-filled"
+
+  class Wrapper < RUI::Base
+    def view_template(&)
+      div(class: "fixed left-0 lg:left-auto bottom-0 right-0 m-5 lg:m-10 flex flex-col gap-3", &)
+    end
+  end
+
+  module Helper
+    def success(message)
+      flash[:success] = message
+    end
+
+    def failure(message)
+      flash[:failure] = message
+    end
+  end
+end

data/lib/rui/forms/checkbox.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Checkbox < RUI::Base
+  def initialize(**kwargs)
+    @kwargs = kwargs
+  end
+
+  def view_template(&)
+  div(class: "flex flex-row gap-3 items-center") do
+      input(
+        type: "hidden",
+        value: "0",
+        autocomplete: "off",
+        **@kwargs
+      )
+      input(
+        type: "checkbox",
+        value: "1",
+        class: "appearance-none size-4 border border-zinc-300 rounded hover:border-zinc-500 hover:cursor-pointer checked:bg-blue-700",
+        **@kwargs
+      )
+      render RUI::Forms::Label.new(&) if block_given?
+    end
+  end
+end

data/lib/rui/forms/email.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Email < RUI::Base
+  def initialize(**kwargs)
+    @kwargs = kwargs
+  end
+
+  def view_template(&)
+    render RUI::Forms::FieldGroup.new do
+      render RUI::Forms::Label.new(&) if block_given?
+      input(
+        type: "email",
+        class: "border border-zinc-300 hover:border-zinc-400 rounded px-2 py-1",
+        **@kwargs
+      )
+    end
+    div
+  end
+end

data/lib/rui/forms/field_group.rb

@@ -0,0 +1,5 @@
+class RUI::Forms::FieldGroup < RUI::Base
+  def view_template(&)
+    div(class: "flex flex-col gap-1", &)
+  end
+end

data/lib/rui/forms/label.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Label < RUI::Base
+  def view_template(&)
+    label(class: "text-sm font-semibold", &)
+  end
+end

data/lib/rui/forms/password.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Password < RUI::Base
+  def initialize(**kwargs)
+    @kwargs = kwargs
+  end
+
+  def view_template(&)
+    render RUI::Forms::FieldGroup.new do
+      render RUI::Forms::Label.new(&) if block_given?
+      input(
+        type: "password",
+        class: "border border-zinc-300 hover:border-zinc-400 rounded px-2 py-1",
+        **@kwargs
+      )
+    end
+  end
+end

data/lib/rui/forms/phone.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Phone < RUI::Base
+  def initialize(**kwargs)
+    @kwargs = kwargs
+  end
+
+  def view_template(&)
+    render RUI::Forms::FieldGroup.new do
+      render RUI::Forms::Label.new(&) if block_given?
+      input(
+        type: :tel,
+        class: "border border-zinc-300 hover:border-zinc-400 rounded px-2 py-1",
+        **@kwargs
+      )
+    end
+  end
+end

data/lib/rui/forms/radio.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Radio < RUI::Base
+  def initialize(label:, &)
+    @label = label
+    super(&)
+  end
+
+  def view_template
+    render RUI::Forms::FieldGroup.new do
+      render RUI::Forms::Label.new { @label }
+      yield
+    end
+  end
+
+  def option(**attrs, &)
+    div(class: "flex flex-row gap-3 items-center") do
+      input(class: "hover:cursor-pointer", type: :radio, **attrs)
+      label(&)
+    end
+  end
+end

data/lib/rui/forms/select.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Select < RUI::Base
+  def initialize(label:, **attrs, &)
+    @label = label
+    @attrs = attrs
+    super(&)
+  end
+
+  def view_template(&)
+    render RUI::Forms::FieldGroup.new do
+      render RUI::Forms::Label.new { @label }
+      select(
+        class: "border border-zinc-300 hover:border-zinc-400 rounded px-2 py-1.5 hover:cursor-pointer",
+        **@attrs,
+        &
+      )
+    end
+  end
+
+  def option(**attrs, &)
+    tag(:option, **attrs, &)
+  end
+end

data/lib/rui/forms/text.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class RUI::Forms::Text < RUI::Base
+  def initialize(**kwargs)
+    @kwargs = kwargs
+  end
+
+  def view_template(&)
+    render RUI::Forms::FieldGroup.new do
+      render RUI::Forms::Label.new(&) if block_given?
+      input(
+        class: "border border-zinc-300 hover:border-zinc-400 rounded px-2 py-1",
+        **@kwargs
+      )
+    end
+  end
+end