stimulus_plumbers 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1abfd2ca5a0c575652d0d6c650acbde79e656b9b806a76b8f922e682cf2f7526
+  data.tar.gz: 621aa551f6fb7b9f3a90c3313e4dedb6c901f475cb96f6631a9fc54edccf5bac
+SHA512:
+  metadata.gz: e45e2a0ea994b0e8d22edc2098974d6f15c43bb552a92dc7c5baf2dc0700b9a8f22ef570ffa913c0cae84d6bc64ecbe6b6e09613e4b73ccaccc1613d93d898d3
+  data.tar.gz: 1be1501a2b77cad35780730e84803bdb5506e6def24699c46cc1797196780aec94dfe7a451a0b4774b748258132a7b0eb3d6bae16c71c22bc7c733bf24c45f1c

data/README.md

@@ -0,0 +1,75 @@
+# Stimulus Plumbers
+
+A library of semantically correct, accessible UI components for Rails 8.0+ using ViewComponent and Stimulus.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stimulus_plumbers'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+Stimulus Plumbers provides ready-to-use ViewComponent components that render semantically correct, accessible HTML. Each component is designed with accessibility as a core requirement, not an afterthought.
+
+### Basic Example
+
+```erb
+<%# In your Rails view %>
+<%= render ButtonComponent.new(url: root_path) do %>
+  Click me
+<% end %>
+```
+
+### Available Components
+
+- **ActionList**: Accessible lists with items and sections
+- **Avatar**: User avatar component
+- **Button**: Semantic button with optional prefix/suffix
+- **Card**: Card component with sections
+- **Calendar**: Date calendar with navigation
+- **Container**: Layout container
+- **Divider**: Semantic divider/separator
+- **Dropdown**: Accessible dropdown menus
+- **Navigation**: Navigation bars, tabs, and lists
+- **Popover**: Accessible popover component
+
+## Component Philosophy
+
+All components in this library follow these principles:
+
+1. **Accessibility First**: WCAG 2.1 Level AA minimum
+2. **Semantic HTML**: Use native elements before ARIA
+3. **Keyboard Navigation**: Full keyboard support
+4. **Screen Reader Friendly**: Proper announcements and labels
+5. **Focus Management**: Visible focus indicators and logical tab order
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run the test suite with:
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ryancyq/stimulus-plumbers.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/stylesheets/stimulus_plumbers/tokens.css

@@ -0,0 +1,83 @@
+/*
+ * Stimulus Plumbers – Design Tokens
+ *
+ * CSS custom properties for all presentational values.
+ * Structural layout utilities stay in component templates.
+ * Override any token in your own :root block to retheme the library.
+ */
+
+:root {
+  /* ── Semantic colors ─────────────────────────────────────────────────── */
+  --sp-color-primary:        oklch(55% 0.2 250);
+  --sp-color-primary-fg:     oklch(98% 0.01 250);
+
+  --sp-color-secondary:      oklch(55% 0.05 250);
+  --sp-color-secondary-fg:   oklch(98% 0.01 250);
+
+  --sp-color-destructive:    oklch(55% 0.22 25);
+  --sp-color-destructive-fg: oklch(98% 0.01 25);
+
+  --sp-color-muted:          oklch(96% 0.02 250);
+  --sp-color-muted-fg:       oklch(45% 0.05 250);
+
+  --sp-color-border:         oklch(90% 0.02 250);
+  --sp-color-bg:             oklch(100% 0 0);
+  --sp-color-fg:             oklch(10% 0.02 250);
+
+
+  /* ── Focus ring ──────────────────────────────────────────────────────── */
+  --sp-focus-ring-color:  var(--sp-color-primary);
+  --sp-focus-ring-width:  2px;
+  --sp-focus-ring-offset: 2px;
+
+
+  /* ── Avatar palette (10 slots, index chosen by name hash) ────────────── */
+  --sp-avatar-color-1:  #b45309;
+  --sp-avatar-color-2:  #4d7c0f;
+  --sp-avatar-color-3:  #0369a1;
+  --sp-avatar-color-4:  #0e7490;
+  --sp-avatar-color-5:  #0f766e;
+  --sp-avatar-color-6:  #047857;
+  --sp-avatar-color-7:  #4338ca;
+  --sp-avatar-color-8:  #a21caf;
+  --sp-avatar-color-9:  #be123c;
+  --sp-avatar-color-10: #be185d;
+  --sp-avatar-fg:       #ffffff;
+
+
+  /* ── Spacing ─────────────────────────────────────────────────────────── */
+  --sp-space-1: 0.25rem;  /*  4px */
+  --sp-space-2: 0.5rem;   /*  8px */
+  --sp-space-3: 0.75rem;  /* 12px */
+  --sp-space-4: 1rem;     /* 16px */
+  --sp-space-6: 1.5rem;   /* 24px */
+
+
+  /* ── Border radius ───────────────────────────────────────────────────── */
+  --sp-radius-sm:   0.25rem;
+  --sp-radius-md:   0.375rem;
+  --sp-radius-lg:   0.5rem;
+  --sp-radius-full: 9999px;
+
+
+  /* ── Shadow ──────────────────────────────────────────────────────────── */
+  --sp-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
+  --sp-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1),
+                  0 2px 4px -2px rgb(0 0 0 / 0.1);
+
+
+  /* ── Typography ──────────────────────────────────────────────────────── */
+  --sp-text-sm:   0.875rem;
+  --sp-text-base: 1rem;
+  --sp-text-lg:   1.125rem;
+
+
+  /* ── Sizing ──────────────────────────────────────────────────────────── */
+  --sp-avatar-size:       2rem;   /* 32px */
+  --sp-icon-size:         1.5rem; /* 24px */
+  --sp-calendar-day-size: 2rem;   /* 32px */
+
+
+  /* ── Z-index ─────────────────────────────────────────────────────────── */
+  --sp-z-popover: 50;
+}

data/lib/stimulus_plumbers/components/action_list/renderer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module ActionList
+      class Renderer < Plumber::Base
+        def list(**kwargs, &block)
+          html_options = merge_html_options(
+            { classes: theme.resolve(:action_list).fetch(:classes, "") },
+            kwargs
+          )
+          template.content_tag(:div, template.capture(&block), **html_options)
+        end
+
+        def section(title: nil, **kwargs, &block)
+          html_options = merge_html_options(kwargs)
+          template.content_tag(:div, **html_options) do
+            template.safe_join(
+              [
+                (template.content_tag(:p, title) if title.present?),
+                template.content_tag(:ul, template.capture(&block))
+              ].compact
+            )
+          end
+        end
+
+        def item(content = nil, url: nil, external: false, active: false, **kwargs, &block)
+          content      = template.capture(&block) if block_given?
+          html_options = merge_html_options(
+            { classes: theme.resolve(:action_list_item, active: active).fetch(:classes, "") },
+            kwargs
+          )
+
+          inner = if url
+                    html_options[:target] = "_blank" if external
+                    template.content_tag(:a, content, href: url, **html_options)
+                  else
+                    html_options[:type] ||= "button"
+                    template.content_tag(:button, content, **html_options)
+                  end
+
+          template.content_tag(:li, inner)
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/avatar/renderer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Avatar
+      class Renderer < Plumber::Base
+        def avatar(name: nil, initials: nil, url: nil, color: nil, size: :md, **kwargs, &block)
+          color_css = resolve_color(color, name, initials) unless url || block_given?
+
+          html_options = merge_html_options(
+            {
+              classes:      [theme.resolve(:avatar, size: size).fetch(:classes, ""), color_css],
+              "aria-label": name,
+              role:         "img"
+            },
+            kwargs
+          )
+
+          template.content_tag(:span, inner(name, initials, url, &block), **html_options)
+        end
+
+        private
+
+        def inner(name, initials, url, &block)
+          if block_given?
+            template.capture(&block)
+          elsif url
+            template.tag.img(src: url, alt: name.present? ? "#{name}'s avatar" : "", onerror: "this.src=''")
+          elsif initials
+            initials_svg(initials)
+          else
+            fallback_svg
+          end
+        end
+
+        def resolve_color(color, name, initials)
+          if color
+            theme.avatar_colors.fetch(color, nil)
+          elsif (seed = name || initials)
+            theme.avatar_color_range[seed.bytes.reduce(:^) % theme.avatar_color_range.length]
+          else
+            theme.avatar_color_range.first
+          end
+        end
+
+        def initials_svg(initials)
+          template.content_tag(:svg, viewBox: "0 0 40 40") do
+            template.content_tag(
+              :text,
+              initials.upcase,
+              x:             "50%",
+              y:             "50%",
+              dy:            "0.35em",
+              fill:          "currentColor",
+              "font-size":   "20",
+              "text-anchor": "middle"
+            )
+          end
+        end
+
+        def fallback_svg
+          template.content_tag(:svg, viewBox: "0 0 40 40") do
+            template.tag.path(
+              fill: "currentColor",
+              d:    "M8.28 27.5A14.95 14.95 0 0120 21.8c4.76 0 8.97 2.24 11.72 5.7a14.02 " \
+                    "14.02 0 01-8.25 5.91 14.82 14.82 0 01-6.94 0 14.02 14.02 0 01-8.25-5.9z" \
+                    "M13.99 12.78a6.02 6.02 0 1112.03 0 6.02 6.02 0 01-12.03 0z"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/button/renderer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Button
+      class Renderer < Plumber::Base
+        def button(content = nil, url: nil, external: false, variant: :primary, size: :md, **kwargs, &block)
+          content      = template.capture(&block) if block_given?
+          html_options = merge_html_options(
+            { classes: theme.resolve(:button, variant: variant, size: size).fetch(:classes, "") },
+            kwargs
+          )
+
+          if url
+            html_options[:target] = "_blank" if external
+            template.content_tag(:a, content, href: url, **html_options)
+          else
+            html_options[:type] ||= "button"
+            template.content_tag(:button, content, **html_options)
+          end
+        end
+
+        def group(alignment: :left, direction: :row, **kwargs, &block)
+          html_options = merge_html_options(
+            { classes: theme.resolve(:button_group, alignment: alignment, direction: direction).fetch(:classes, "") },
+            kwargs
+          )
+          template.content_tag(:div, template.capture(&block), **html_options)
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/calendar/month/turbo/days_of_month.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Calendar
+      module Month
+        module Turbo
+          class DaysOfMonth < Plumber::Base
+            DAYS_IN_WEEK = 7
+
+            attr_reader :date, :today, :selectable, :selected_date, :show_other_months
+
+            def initialize(
+              template,
+              date: Date.today,
+              today: Date.today,
+              selectable: false,
+              selected_date: nil,
+              show_other_months: false
+            )
+              super(template)
+              @date              = date
+              @today             = today
+              @selectable        = selectable
+              @selected_date     = selected_date
+              @show_other_months = show_other_months
+            end
+
+            def render(**kwargs)
+              html_options = merge_html_options(
+                { classes: theme.resolve(:calendar_days_of_month).fetch(:classes, "") },
+                kwargs
+              )
+
+              template.content_tag(:div, **html_options, role: "rowgroup") do
+                template.safe_join(
+                  build_days.each_slice(DAYS_IN_WEEK).map do |week|
+                    template.content_tag(:div, role: "row") do
+                      days_in_week(week)
+                    end
+                  end
+                )
+              end
+            end
+
+            private
+
+            # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            def focus_day
+              @focus_day ||= if selected_date&.month == date.month && selected_date&.year == date.year
+                               selected_date
+                             elsif today.month == date.month && today.year == date.year
+                               today
+                             else
+                               date.beginning_of_month
+                             end
+            end
+            # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+            def build_days
+              first = date.beginning_of_month
+              last  = date.end_of_month
+
+              prev_days    = (first - first.wday).upto(first - 1).to_a
+              current_days = first.upto(last).to_a
+              total        = prev_days.length + current_days.length
+              next_count   = (DAYS_IN_WEEK - (total % DAYS_IN_WEEK)) % DAYS_IN_WEEK
+              next_days    = next_count.positive? ? (last + 1).upto(last + next_count).to_a : []
+
+              prev_days + current_days + next_days
+            end
+
+            def days_in_week(week)
+              template.safe_join(
+                week.map do |day|
+                  if day.month == date.month
+                    current_month_day_cell(day)
+                  elsif show_other_months
+                    other_month_day_cell(day)
+                  else
+                    hidden_day_cell(day)
+                  end
+                end
+              )
+            end
+
+            def hidden_day_cell(date)
+              template.content_tag(:span, role: "gridcell", tabindex: -1, aria: { hidden: "true" }) do
+                template.content_tag(:time, nil, datetime: date.iso8601)
+              end
+            end
+
+            def current_month_day_cell(date)
+              tag      = selectable ? :button : :span
+              selected = selected_date && date == selected_date ? "true" : "false"
+              template.content_tag(
+                tag,
+                role:     "gridcell",
+                tabindex: date == focus_day ? 0 : -1,
+                aria:     {
+                  current:  date == today ? "date" : nil,
+                  selected: selectable ? selected : nil
+                }
+              ) do
+                template.content_tag(:time, date.day.to_s, datetime: date.iso8601)
+              end
+            end
+
+            def other_month_day_cell(date)
+              template.content_tag(
+                :span,
+                role:     "gridcell",
+                tabindex: -1,
+                aria:     { disabled: "true", selected: "false" }
+              ) do
+                template.content_tag(:time, date.day.to_s, datetime: date.iso8601)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/calendar/month/turbo/days_of_week.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Calendar
+      module Month
+        module Turbo
+          class DaysOfWeek < Plumber::Base
+            def render(**kwargs)
+              html_options = merge_html_options(
+                { classes: theme.resolve(:calendar_days_of_week).fetch(:classes, "") },
+                kwargs
+              )
+
+              template.content_tag(:div, **html_options) do
+                template.content_tag(:div, role: "row") do
+                  template.safe_join(
+                    day_names.map do |abbr, full|
+                      template.content_tag(:span, abbr, role: "columnheader", abbr: full)
+                    end
+                  )
+                end
+              end
+            end
+
+            private
+
+            def day_names
+              I18n.t("date.abbr_day_names").zip(I18n.t("date.day_names"))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/calendar/month/turbo/renderer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Calendar
+      module Month
+        module Turbo
+          class Renderer < Plumber::Base
+            STIMULUS_CONTROLLER = "calendar-month-observer"
+
+            def render(
+              date: Date.today,
+              today: Date.today,
+              selectable: false,
+              selected_date: nil,
+              show_other_months: false,
+              **kwargs
+            )
+              html_options = merge_html_options(
+                {
+                  classes: theme.resolve(:calendar).fetch(:classes, ""),
+                  data:    { controller: STIMULUS_CONTROLLER, action: "click->#{STIMULUS_CONTROLLER}#select" }
+                },
+                kwargs
+              )
+
+              template.content_tag(:div, role: "grid", **html_options) do
+                template.safe_join(
+                  [
+                    days_of_week,
+                    days_of_month(
+                      date:              date,
+                      today:             today,
+                      selectable:        selectable,
+                      selected_date:     selected_date,
+                      show_other_months: show_other_months
+                    )
+                  ]
+                )
+              end
+            end
+
+            private
+
+            def days_of_week(**kwargs)
+              DaysOfWeek.new(template).render(**kwargs)
+            end
+
+            def days_of_month(**kwargs)
+              DaysOfMonth.new(template, **kwargs).render
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/calendar/renderer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Calendar
+      class Renderer < Plumber::Base
+        STIMULUS_CONTROLLER          = "calendar-month"
+        OBSERVER_STIMULUS_CONTROLLER = "calendar-month-observer"
+        STIMULUS_DATA                = {
+          controller: "#{STIMULUS_CONTROLLER} #{OBSERVER_STIMULUS_CONTROLLER}",
+          action:     "click->#{OBSERVER_STIMULUS_CONTROLLER}#select"
+        }.freeze
+
+        def month(**kwargs)
+          html_options = merge_html_options(
+            { classes: theme.resolve(:calendar).fetch(:classes, ""), data: STIMULUS_DATA },
+            kwargs
+          )
+
+          template.content_tag(:div, role: "grid", **html_options) do
+            template.safe_join(
+              [
+                template.tag.div(data: { "#{STIMULUS_CONTROLLER}-target" => "daysOfWeek" }),
+                template.tag.div(
+                  role: "rowgroup",
+                  data: { "#{STIMULUS_CONTROLLER}-target" => "daysOfMonth" }
+                )
+              ]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/card/renderer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Card
+      class Renderer < Plumber::Base
+        def card(title: nil, **kwargs, &block)
+          html_options = merge_html_options(
+            { classes: theme.resolve(:card).fetch(:classes, "") },
+            kwargs
+          )
+
+          template.content_tag(:div, **html_options) do
+            template.safe_join(
+              [
+                (template.content_tag(:h2, title) if title.present?),
+                template.capture(&block)
+              ].compact
+            )
+          end
+        end
+
+        def section(title: nil, **kwargs, &block)
+          html_options = merge_html_options(
+            { classes: theme.resolve(:card_section).fetch(:classes, "") },
+            kwargs
+          )
+
+          template.content_tag(:div, **html_options) do
+            template.safe_join(
+              [
+                (template.content_tag(:h3, title) if title.present?),
+                template.capture(&block)
+              ].compact
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/date_picker/navigation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module DatePicker
+      class Navigation < Plumber::Base
+        def render(stimulus_controller:, step:, **kwargs)
+          html_options = merge_html_options(
+            { classes: theme.resolve(:calendar_navigation).fetch(:classes, ""), aria: { label: "DatePicker Navigation" } },
+            kwargs
+          )
+
+          template.content_tag(:nav, **html_options) do
+            template.safe_join(navigators(stimulus_controller, step))
+          end
+        end
+
+        private
+
+        def navigators(stimulus_controller, step)
+          [
+            Navigator.new(template).render(
+              icon_options: { name: "arrow-left" },
+              aria:         { label: ["previous", step].join(" ").titleize },
+              data:         { "#{stimulus_controller}-target" => "previous" }
+            ),
+            Navigator.new(template).render(
+              aria: { label: "Day" },
+              data: { "#{stimulus_controller}-target" => "day" }
+            ),
+            Navigator.new(template).render(
+              aria: { label: "Month" },
+              data: { "#{stimulus_controller}-target" => "month" }
+            ),
+            Navigator.new(template).render(
+              aria: { label: "Year" },
+              data: { "#{stimulus_controller}-target" => "year" }
+            ),
+            Navigator.new(template).render(
+              icon_options: { name: "arrow-right" },
+              aria:         { label: ["next", step].join(" ").titleize },
+              data:         { "#{stimulus_controller}-target" => "next" }
+            )
+          ]
+        end
+      end
+    end
+  end
+end