solid_web_ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 733e4f6cdd63c6b22b5e3ca4166576ebfe2db2a482d6b2fa7e25035e0a12c7a9
+  data.tar.gz: e1b1e0755169b3ba6f74d576f155bcce21bf029f5d1a2de3e833be7713d806e5
+SHA512:
+  metadata.gz: 66d72bca337446f1df7ae48b7faebe2c760c56e1079eba0a280deb1047bd6ef0a0719bcd64137609a0df7207bc7632239eff6920aa30f16fb28775f7d4b97fa9
+  data.tar.gz: ae241b3d25a1108b038b88a92e81e36da9137c5c3af126a1abd4c6767ca135e46b9f3200641239cc162a74c690bb73eaa3ad6145450a6b61231e60717afb5348

data/README.md

@@ -0,0 +1,74 @@
+# solid_web_ui
+
+Web dashboards for Rails' **Solid Queue**, **Solid Cache** and **Solid Cable** — one gem
+(`solid_web_ui`) with three independently mountable Rails engines sharing one design system.
+
+> The repository is named `solid-web`; the gem it ships is `solid_web_ui`.
+
+| Engine | Mount | What it does |
+|--------|-------|--------------|
+| `SolidWebUi::Queue::Engine` | `/admin/queue` | Solid Queue: dashboard, queues (pause/resume), jobs by status, failed jobs (retry/discard), processes, recurring tasks. |
+| `SolidWebUi::Cache::Engine` | `/admin/cache` | Solid Cache: entry/size statistics, entry browser, clear. |
+| `SolidWebUi::Cable::Engine` | `/admin/cable` | Solid Cable: message/channel activity, volume, retention trim. |
+
+The shared core (`SolidWebUi`) provides the layout, ViewComponents, design-token theming and a
+dry-configurable base. The engines are plain Rails mountable engines — **no ActiveAdmin required**;
+host authentication is inherited through a configurable `base_controller_class`.
+
+## Install
+
+```ruby
+# Gemfile
+gem "solid_web_ui"
+```
+
+```ruby
+# config/routes.rb — mount only the parts you want
+mount SolidWebUi::Queue::Engine => "/admin/queue"
+mount SolidWebUi::Cache::Engine => "/admin/cache"
+mount SolidWebUi::Cable::Engine => "/admin/cable"
+```
+
+```ruby
+# config/initializers/solid_web_ui.rb — protect the dashboards behind your auth
+SolidWebUi::Queue.config.base_controller_class = "Admin::BaseController"
+SolidWebUi::Cache.config.base_controller_class = "Admin::BaseController"
+SolidWebUi::Cable.config.base_controller_class = "Admin::BaseController"
+```
+
+## Development
+
+A single dummy Rails app under `spec/dummy` (SQLite, schema loaded from the Solid* gems) exercises
+all three engines.
+
+```bash
+bundle install
+bundle exec rspec               # full suite
+bundle exec rake assets:build   # rebuild the precompiled Tailwind stylesheet
+```
+
+> Requires the Ruby pinned for this workspace. In a non-interactive shell use mise:
+> `mise exec -- bundle exec rspec`.
+
+## Releasing
+
+Pushing a version tag builds and releases the gem via
+[`.github/workflows/release.yml`](.github/workflows/release.yml):
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow builds `solid_web_ui.gem`, attaches it to a GitHub Release, and publishes it to RubyGems
+via **OIDC Trusted Publishing** (no API key / secret — MFA-compatible).
+
+One-time setup on [rubygems.org](https://rubygems.org): register a trusted publisher for `solid_web_ui`
+(repo `doromones/solid-web`, workflow `release.yml`). Before the first release use a *pending* trusted
+publisher (`https://rubygems.org/profile/oidc/pending_trusted_publishers/new`).
+
+## Documentation
+
+- [Configuration reference](docs/configuration.md)
+- [Theming — projecting the host design](docs/theming.md)
+- [Authentication](docs/authentication.md)

data/app/assets/stylesheets/solid_web_ui.css

@@ -0,0 +1,232 @@
+/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.com */
+@layer theme, components, utilities;
+@layer utilities {
+  .static {
+    position: static;
+  }
+  .block {
+    display: block;
+  }
+  .contents {
+    display: contents;
+  }
+}
+@layer components {
+  .solid-web-ui {
+    color: var(--swui-color-text);
+    background: var(--swui-color-bg);
+    font-family: var(--swui-font);
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+  .solid-web-ui *, .solid-web-ui *::before, .solid-web-ui *::after {
+    box-sizing: border-box;
+  }
+  .solid-web-ui .swui-page {
+    max-width: 72rem;
+    margin-inline: auto;
+    padding: 1.5rem;
+  }
+  .solid-web-ui .swui-page__header {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    margin-bottom: 1.5rem;
+    border-bottom: 1px solid var(--swui-color-border);
+    padding-bottom: 1rem;
+  }
+  .solid-web-ui .swui-page__title {
+    font-size: 1.5rem;
+    font-weight: 700;
+    margin: 0;
+  }
+  .solid-web-ui .swui-nav {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem;
+  }
+  .solid-web-ui .swui-nav__link {
+    display: inline-block;
+    padding: 0.4rem 0.75rem;
+    border-radius: var(--swui-radius);
+    color: var(--swui-color-muted);
+    text-decoration: none;
+    font-size: 0.9rem;
+    font-weight: 500;
+  }
+  .solid-web-ui .swui-nav__link:hover {
+    background: var(--swui-color-primary);
+    @supports (color: color-mix(in lab, red, red)) {
+      background: color-mix(in srgb, var(--swui-color-primary) 10%, transparent);
+    }
+    color: var(--swui-color-text);
+  }
+  .solid-web-ui .swui-nav__link--active {
+    background: var(--swui-color-primary);
+    color: var(--swui-color-primary-contrast);
+  }
+  .solid-web-ui .swui-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(11rem, 1fr));
+    gap: 1rem;
+    margin-bottom: 1.5rem;
+  }
+  .solid-web-ui .swui-card {
+    display: flex;
+    flex-direction: column;
+    gap: 0.35rem;
+    padding: 1rem 1.1rem;
+    background: var(--swui-color-surface);
+    border: 1px solid var(--swui-color-border);
+    border-left: 3px solid var(--swui-color-border);
+    border-radius: var(--swui-radius);
+    text-decoration: none;
+    color: inherit;
+  }
+  .solid-web-ui a.swui-card:hover {
+    border-color: var(--swui-color-primary);
+  }
+  .solid-web-ui .swui-card__label {
+    font-size: 0.8rem;
+    color: var(--swui-color-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+  }
+  .solid-web-ui .swui-card__value {
+    font-size: 1.75rem;
+    font-weight: 700;
+  }
+  .solid-web-ui .swui-card--primary {
+    border-left-color: var(--swui-color-primary);
+  }
+  .solid-web-ui .swui-card--success {
+    border-left-color: var(--swui-color-success);
+  }
+  .solid-web-ui .swui-card--warning {
+    border-left-color: var(--swui-color-warning);
+  }
+  .solid-web-ui .swui-card--danger {
+    border-left-color: var(--swui-color-danger);
+  }
+  .solid-web-ui .swui-badge {
+    display: inline-block;
+    padding: 0.15rem 0.5rem;
+    border-radius: 999px;
+    font-size: 0.75rem;
+    font-weight: 600;
+    background: var(--swui-color-muted);
+    @supports (color: color-mix(in lab, red, red)) {
+      background: color-mix(in srgb, var(--swui-color-muted) 18%, transparent);
+    }
+    color: var(--swui-color-text);
+  }
+  .solid-web-ui .swui-badge--info {
+    background: var(--swui-color-primary);
+    @supports (color: color-mix(in lab, red, red)) {
+      background: color-mix(in srgb, var(--swui-color-primary) 18%, transparent);
+    }
+  }
+  .solid-web-ui .swui-badge--success {
+    background: var(--swui-color-success);
+    @supports (color: color-mix(in lab, red, red)) {
+      background: color-mix(in srgb, var(--swui-color-success) 22%, transparent);
+    }
+  }
+  .solid-web-ui .swui-badge--warning {
+    background: var(--swui-color-warning);
+    @supports (color: color-mix(in lab, red, red)) {
+      background: color-mix(in srgb, var(--swui-color-warning) 24%, transparent);
+    }
+  }
+  .solid-web-ui .swui-badge--danger {
+    background: var(--swui-color-danger);
+    @supports (color: color-mix(in lab, red, red)) {
+      background: color-mix(in srgb, var(--swui-color-danger) 22%, transparent);
+    }
+  }
+  .solid-web-ui .swui-table {
+    width: 100%;
+    border-collapse: collapse;
+    background: var(--swui-color-surface);
+    border: 1px solid var(--swui-color-border);
+    border-radius: var(--swui-radius);
+    overflow: hidden;
+    font-size: 0.9rem;
+  }
+  .solid-web-ui .swui-table th, .solid-web-ui .swui-table td {
+    text-align: left;
+    padding: 0.6rem 0.85rem;
+    border-bottom: 1px solid var(--swui-color-border);
+  }
+  .solid-web-ui .swui-table th {
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+    color: var(--swui-color-muted);
+    background: var(--swui-color-muted);
+    @supports (color: color-mix(in lab, red, red)) {
+      background: color-mix(in srgb, var(--swui-color-muted) 6%, transparent);
+    }
+  }
+  .solid-web-ui .swui-table tr:last-child td {
+    border-bottom: 0;
+  }
+  .solid-web-ui .swui-table__empty td {
+    text-align: center;
+    color: var(--swui-color-muted);
+    padding: 1.5rem;
+  }
+  .solid-web-ui .swui-btn {
+    display: inline-block;
+    padding: 0.35rem 0.7rem;
+    border: 1px solid var(--swui-color-border);
+    border-radius: var(--swui-radius);
+    background: var(--swui-color-surface);
+    color: var(--swui-color-text);
+    font-size: 0.85rem;
+    font-weight: 500;
+    cursor: pointer;
+    text-decoration: none;
+  }
+  .solid-web-ui .swui-btn:hover {
+    border-color: var(--swui-color-primary);
+  }
+  .solid-web-ui .swui-btn--danger {
+    color: var(--swui-color-danger);
+    border-color: var(--swui-color-danger);
+  }
+  .solid-web-ui .swui-pagination {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem;
+    margin-top: 1rem;
+  }
+  .solid-web-ui .swui-pagination__item {
+    display: inline-block;
+    min-width: 2rem;
+    text-align: center;
+    padding: 0.3rem 0.55rem;
+    border: 1px solid var(--swui-color-border);
+    border-radius: var(--swui-radius);
+    color: var(--swui-color-text);
+    text-decoration: none;
+    font-size: 0.85rem;
+  }
+  .solid-web-ui .swui-pagination__item--current {
+    background: var(--swui-color-primary);
+    color: var(--swui-color-primary-contrast);
+    border-color: var(--swui-color-primary);
+  }
+  .solid-web-ui .swui-pagination__item--disabled {
+    color: var(--swui-color-muted);
+    opacity: 0.5;
+    pointer-events: none;
+  }
+  .solid-web-ui .swui-section-title {
+    font-size: 1.05rem;
+    font-weight: 600;
+    margin: 1.5rem 0 0.75rem;
+  }
+}

data/app/components/solid_web_ui/ui/page_component.html.erb

@@ -0,0 +1,15 @@
+<div class="swui-page">
+  <header class="swui-page__header">
+    <h1 class="swui-page__title"><%= title %></h1>
+    <% if nav.any? %>
+      <nav class="swui-nav">
+        <% nav.each do |item| %>
+          <%= link_to item[:label], item[:href], class: nav_link_class(item) %>
+        <% end %>
+      </nav>
+    <% end %>
+  </header>
+  <main class="swui-page__body">
+    <%= content %>
+  </main>
+</div>

data/app/components/solid_web_ui/ui/page_component.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SolidWebUi
+  module Ui
+    # Page chrome shared by every dashboard screen: a title, an optional nav bar
+    # (array of { label:, href:, active: }) and the page body as content.
+    class PageComponent < ViewComponent::Base
+      def initialize(title:, nav: [])
+        @title = title
+        @nav = nav || []
+      end
+
+      private
+
+      attr_reader :title, :nav
+
+      def nav_link_class(item)
+        [ "swui-nav__link", item[:active] ? "swui-nav__link--active" : nil ].compact.join(" ")
+      end
+    end
+  end
+end

data/app/components/solid_web_ui/ui/paginator_component.html.erb

@@ -0,0 +1,21 @@
+<nav class="swui-pagination" aria-label="Pagination">
+  <% if paginator.prev_page %>
+    <%= link_to "‹ Prev", page_url.call(paginator.prev_page), class: "swui-pagination__item" %>
+  <% else %>
+    <span class="swui-pagination__item swui-pagination__item--disabled">‹ Prev</span>
+  <% end %>
+
+  <% (1..paginator.total_pages).each do |number| %>
+    <% if number == paginator.current_page %>
+      <span class="swui-pagination__item swui-pagination__item--current" aria-current="page"><%= number %></span>
+    <% else %>
+      <%= link_to number, page_url.call(number), class: "swui-pagination__item" %>
+    <% end %>
+  <% end %>
+
+  <% if paginator.next_page %>
+    <%= link_to "Next ›", page_url.call(paginator.next_page), class: "swui-pagination__item" %>
+  <% else %>
+    <span class="swui-pagination__item swui-pagination__item--disabled">Next ›</span>
+  <% end %>
+</nav>

data/app/components/solid_web_ui/ui/paginator_component.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SolidWebUi
+  module Ui
+    # Renders pagination controls for a SolidWebUi::Paginator. `page_url` is a
+    # callable mapping a page number to a URL (so the component stays decoupled
+    # from any engine's routes). Hidden entirely when there is only one page.
+    class PaginatorComponent < ViewComponent::Base
+      def initialize(paginator:, page_url:)
+        @paginator = paginator
+        @page_url = page_url
+      end
+
+      def render?
+        @paginator.total_pages > 1
+      end
+
+      private
+
+      attr_reader :paginator, :page_url
+    end
+  end
+end

data/app/components/solid_web_ui/ui/stat_card_component.html.erb

@@ -0,0 +1,11 @@
+<% if href %>
+  <%= link_to href, class: css_classes do %>
+    <span class="swui-card__label"><%= label %></span>
+    <span class="swui-card__value"><%= value %></span>
+  <% end %>
+<% else %>
+  <div class="<%= css_classes %>">
+    <span class="swui-card__label"><%= label %></span>
+    <span class="swui-card__value"><%= value %></span>
+  </div>
+<% end %>

data/app/components/solid_web_ui/ui/stat_card_component.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SolidWebUi
+  module Ui
+    # A single dashboard metric: a label and a (usually numeric) value, optionally
+    # toned (neutral/primary/success/warning/danger) and linkable.
+    class StatCardComponent < ViewComponent::Base
+      def initialize(label:, value:, tone: :neutral, href: nil)
+        @label = label
+        @value = value
+        @tone = tone
+        @href = href
+      end
+
+      private
+
+      attr_reader :label, :value, :href
+
+      def css_classes
+        [ "swui-card", "swui-card--#{@tone}" ].join(" ")
+      end
+    end
+  end
+end

data/app/components/solid_web_ui/ui/status_badge_component.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SolidWebUi
+  module Ui
+    # A small pill conveying a record's status. Maps a domain status symbol to one
+    # of the shared tone classes; unknown statuses degrade to a neutral pill.
+    class StatusBadgeComponent < ViewComponent::Base
+      TONES = {
+        ready: :info,
+        scheduled: :info,
+        in_progress: :info,
+        claimed: :info,
+        finished: :success,
+        succeeded: :success,
+        failed: :danger,
+        blocked: :warning,
+        paused: :warning,
+        stale: :warning
+      }.freeze
+
+      def initialize(label:, status: nil)
+        @label = label
+        @status = status
+      end
+
+      def call
+        content_tag(:span, @label, class: "swui-badge swui-badge--#{tone}")
+      end
+
+      private
+
+      def tone
+        TONES.fetch(@status&.to_sym, :neutral)
+      end
+    end
+  end
+end

data/app/components/solid_web_ui/ui/table_component.html.erb

@@ -0,0 +1,18 @@
+<table class="swui-table">
+  <thead>
+    <tr>
+      <% headers.each do |header| %>
+        <th scope="col"><%= header %></th>
+      <% end %>
+    </tr>
+  </thead>
+  <tbody>
+    <% if content.present? %>
+      <%= content %>
+    <% else %>
+      <tr class="swui-table__empty">
+        <td colspan="<%= headers.size %>"><%= empty_message %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/components/solid_web_ui/ui/table_component.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SolidWebUi
+  module Ui
+    # A styled data table. Pass column `headers`; render the body rows as the
+    # component's content (a block of <tr> rows). Shows an empty state when no
+    # rows are given.
+    class TableComponent < ViewComponent::Base
+      def initialize(headers:, empty_message: "Nothing to show.")
+        @headers = headers
+        @empty_message = empty_message
+      end
+
+      private
+
+      attr_reader :headers, :empty_message
+    end
+  end
+end

data/app/controllers/solid_web_ui/cable/application_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Cable
+  class ApplicationController < SolidWebUi.resolve_base_controller(SolidWebUi::Cable.config.base_controller_class)
+    layout "solid_web_ui"
+    helper SolidWebUi::ComponentHelper
+
+    private
+
+    def trimmable_scope
+      SolidCable::Message.where(created_at: ...SolidWebUi::Cable.config.retention.ago)
+    end
+  end
+end

data/app/controllers/solid_web_ui/cable/channels_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Cable
+  class ChannelsController < ApplicationController
+    def index
+      counts = SolidCable::Message.group(:channel).count
+      last_seen = SolidCable::Message.group(:channel).maximum(:created_at)
+      @channels = counts
+                  .map { |channel, count| { name: channel, count: count, last: last_seen[channel] } }
+                  .sort_by { |row| -row[:count] }
+    end
+  end
+end

data/app/controllers/solid_web_ui/cable/dashboard_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Cable
+  class DashboardController < ApplicationController
+    def index
+      @total = SolidCable::Message.count
+      @channel_count = SolidCable::Message.distinct.count(:channel)
+      @trimmable = trimmable_scope.count
+      @last_hour = SolidCable::Message.where(created_at: 1.hour.ago..).count
+      @top_channels = SolidCable::Message.group(:channel).count.max_by(10) { |_channel, count| count }
+    end
+  end
+end

data/app/controllers/solid_web_ui/cable/messages_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Cable
+  class MessagesController < ApplicationController
+    before_action :ensure_trim_enabled, only: :trim
+
+    def trim
+      deleted = trimmable_scope.delete_all
+      redirect_to root_path, notice: "Trimmed #{deleted} old message(s)."
+    end
+
+    private
+
+    def ensure_trim_enabled
+      head :forbidden unless SolidWebUi::Cable.config.enable_trim
+    end
+  end
+end

data/app/controllers/solid_web_ui/cache/application_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Cache
+  class ApplicationController < SolidWebUi.resolve_base_controller(SolidWebUi::Cache.config.base_controller_class)
+    layout "solid_web_ui"
+    helper SolidWebUi::ComponentHelper
+
+    private
+
+    def per_page
+      SolidWebUi::Cache.config.per_page
+    end
+  end
+end

data/app/controllers/solid_web_ui/cache/dashboard_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Cache
+  class DashboardController < ApplicationController
+    def index
+      @count = SolidCache::Entry.count
+      @total_bytes = SolidCache::Entry.sum(:byte_size)
+      @avg_bytes = SolidCache::Entry.average(:byte_size).to_f.round
+      @oldest = SolidCache::Entry.minimum(:created_at)
+      @newest = SolidCache::Entry.maximum(:created_at)
+    end
+  end
+end

data/app/controllers/solid_web_ui/cache/entries_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Cache
+  class EntriesController < ApplicationController
+    before_action :ensure_clear_enabled, only: :clear
+
+    def index
+      scope = SolidCache::Entry.order(id: :desc)
+      @paginator = SolidWebUi::Paginator.new(scope, page: params[:page], per_page: per_page)
+      @entries = @paginator.records
+    end
+
+    def clear
+      SolidCache::Entry.delete_all
+      redirect_to root_path, notice: "Cache cleared."
+    end
+
+    private
+
+    def ensure_clear_enabled
+      head :forbidden unless SolidWebUi::Cache.config.enable_clear
+    end
+  end
+end

data/app/controllers/solid_web_ui/queue/application_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Queue
+  # Inherits from the host-configured controller (default ActionController::Base)
+  # so host authentication/authorization applies. Resolved lazily at autoload
+  # time, after host initializers have set `base_controller_class`.
+  class ApplicationController < SolidWebUi.resolve_base_controller(SolidWebUi::Queue.config.base_controller_class)
+    layout "solid_web_ui"
+    helper SolidWebUi::ComponentHelper
+
+    private
+
+    def per_page
+      SolidWebUi::Queue.config.per_page
+    end
+  end
+end

data/app/controllers/solid_web_ui/queue/dashboard_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SolidWebUi::Queue
+  class DashboardController < ApplicationController
+    def index
+      @counts = {
+        ready: SolidQueue::ReadyExecution.count,
+        scheduled: SolidQueue::ScheduledExecution.count,
+        in_progress: SolidQueue::ClaimedExecution.count,
+        blocked: SolidQueue::BlockedExecution.count,
+        failed: SolidQueue::FailedExecution.count,
+        finished: SolidQueue::Job.where.not(finished_at: nil).count
+      }
+      @queue_count = SolidQueue::Queue.all.size
+      @process_count = SolidQueue::Process.count
+    end
+  end
+end