senren-ui 0.1.5 → 0.2.0

data/docs/components.md

@@ -0,0 +1,222 @@
+# Senren Components Guide
+
+This guide covers the form-related components in detail, with runnable examples
+and explicit guidance on common pitfalls.
+
+---
+
+## FormComponent
+
+Wraps `form_with` with Senren semantic tokens and consistent spacing.
+
+### Key behavior
+
+- **Yields a Rails form builder** (`|f|`) — use `f.text_field`, `f.select`, etc.
+  inside the block just like a normal Rails form.
+- **`method:` defaults to `nil`** — Rails will infer `:post` for new records and
+  `:patch` for persisted records. Only pass `method:` explicitly when you need to
+  override this (e.g., `method: :delete`).
+- **`model: nil` is safe** — model-less forms (login, search, password reset)
+  work without passing a model.
+
+### Examples
+
+#### Basic model form (create)
+
+```erb
+<%= render(Senren::FormComponent.new(model: @post, url: posts_path)) do |f| %>
+  <%= render(Senren::LabelComponent.new(for_field: "title", variant: :required)) { "Title" } %>
+  <%= f.text_field :title, class: "senren-input" %>
+  <%= render(Senren::ButtonComponent.new(variant: :primary, type: :submit)) { "Create" } %>
+<% end %>
+```
+
+#### Edit form (Rails infers PATCH automatically)
+
+```erb
+<%= render(Senren::FormComponent.new(model: @post, url: post_path(@post))) do |f| %>
+  <%= render(Senren::LabelComponent.new(for_field: "title")) { "Title" } %>
+  <%= f.text_field :title, class: "senren-input" %>
+  <%= render(Senren::ButtonComponent.new(variant: :primary, type: :submit)) { "Update" } %>
+<% end %>
+```
+
+#### Model-less form (login)
+
+```erb
+<%= render(Senren::FormComponent.new(url: session_path)) do |f| %>
+  <%= render(Senren::InputComponent.new(name: "email", type: "email", placeholder: "you@example.com")) %>
+  <%= render(Senren::InputComponent.new(name: "password", type: "password")) %>
+  <%= render(Senren::ButtonComponent.new(variant: :primary, type: :submit)) { "Sign in" } %>
+<% end %>
+```
+
+Leave `method:` unset on edit forms for persisted models. Rails needs it to be
+`nil` to infer `PATCH`; passing `method: :post` produces
+`No route matches [POST] "/resource/:id"`.
+
+---
+
+## InputComponent
+
+### InputComponent vs `form.text_field`
+
+**`InputComponent` renders its own `<input>` tag.** It is a **replacement** for
+`form.text_field`, not an add-on. Do not combine them.
+
+#### Use one or the other
+
+```erb
+<%# Option A: Use InputComponent standalone %>
+<%= render(Senren::InputComponent.new(name: "email", type: "email")) %>
+
+<%# Option B: Use Rails form builder with plain classes %>
+<%= f.text_field :email, class: "your-input-classes" %>
+```
+
+#### Not both together
+
+```erb
+<%# This renders two inputs %>
+<%= render(Senren::InputComponent.new(name: "email")) do %>
+  <%= f.text_field :email %>
+<% end %>
+```
+
+### Required params
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | String/Symbol | **Yes** | — | Input `name` attribute |
+| `type` | String | No | `"text"` | HTML input type |
+| `value` | String | No | `nil` | Pre-filled value |
+| `placeholder` | String | No | `nil` | Placeholder text |
+| `id` | String | No | auto | Defaults to parameterized `name` |
+| `variant` | Symbol | No | `:default` | `:default` or `:error` |
+| `size` | Symbol | No | `:md` | `:sm`, `:md`, or `:lg` |
+
+### File inputs
+
+File inputs automatically get styled button treatment:
+
+```erb
+<%= render(Senren::InputComponent.new(name: "avatar", type: "file")) %>
+```
+
+The file selector button uses a segmented style with a divider, semantic surface
+color, and pointer cursor — no additional classes needed.
+
+### Date/time inputs
+
+Native date and datetime-local inputs work correctly. The component intentionally
+omits `display: flex` from base styles because it breaks browser-native
+date/time picker UI on some engines.
+
+```erb
+<%= render(Senren::InputComponent.new(name: "starts_at", type: "datetime-local")) %>
+<%= render(Senren::InputComponent.new(name: "due_date", type: "date")) %>
+```
+
+---
+
+## LabelComponent
+
+### Required params
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `for_field` | String | **Yes** | — | ID of the associated form control |
+| `text` | String | No | `nil` | Fallback label text (if block is empty) |
+| `variant` | Symbol | No | `:default` | `:default` or `:required` (adds `*`) |
+
+### Examples
+
+Both patterns below are fully supported and produce identical output:
+
+```erb
+<%# Block syntax %>
+<%= render(Senren::LabelComponent.new(for_field: "name", variant: :required)) { "Student name" } %>
+
+<%# Text param syntax (useful when block content might be empty) %>
+<%= render(Senren::LabelComponent.new(for_field: "name", text: "Student name", variant: :required)) %>
+```
+
+> **Note**: The `text:` param acts as a fallback. If both a block and `text:` are
+> provided, the block content wins.
+
+---
+
+## NativeSelectComponent
+
+Renders a native `<select>` element with Senren styling.
+
+### Key behavior
+
+- **Defaults to native browser arrow** (`native_arrow: true`). This preserves
+  the platform's familiar select appearance (iOS wheel, Android dropdown, etc.).
+- Pass `native_arrow: false` to use a custom SVG chevron overlay instead.
+
+### Required params
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | String/Symbol | **Yes** | — | Select `name` attribute |
+| `options` | Array | **Yes** | — | `["a","b"]` or `[["val","Label"],...]` |
+| `selected` | String | No | `nil` | Pre-selected value |
+| `prompt` | String | No | `nil` | Blank option text (e.g., "Choose…") |
+| `native_arrow` | Boolean | No | `true` | Use native browser arrow |
+| `variant` | Symbol | No | `:default` | `:default` or `:error` |
+
+### Examples
+
+```erb
+<%# Native arrow (default — recommended) %>
+<%= render(Senren::NativeSelectComponent.new(
+  name: "role",
+  options: [["admin", "Admin"], ["member", "Member"]],
+  prompt: "Choose role…"
+)) %>
+
+<%# Custom SVG arrow %>
+<%= render(Senren::NativeSelectComponent.new(
+  name: "role",
+  options: [["admin", "Admin"], ["member", "Member"]],
+  native_arrow: false
+)) %>
+```
+
+---
+
+## FormFieldComponent (pattern — not yet a shipped component)
+
+A common pattern when building forms is wrapping label + control + error. Until a
+dedicated `FormFieldComponent` ships, use this pattern:
+
+```erb
+<div class="space-y-1.5">
+  <%= render(Senren::LabelComponent.new(for_field: "email", variant: :required)) { "Email" } %>
+  <%= render(Senren::InputComponent.new(name: "email", type: "email", variant: @errors[:email] ? :error : :default)) %>
+  <% if @errors[:email] %>
+    <p class="text-sm text-[hsl(var(--senren-destructive))]"><%= @errors[:email] %></p>
+  <% end %>
+</div>
+```
+
+---
+
+## Render syntax reminder
+
+Always use **parentheses** around `render` when passing an inline content block:
+
+```erb
+<%# Correct: parens around render %>
+<%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
+
+<%# Correct: do/end block %>
+<%= render Senren::ButtonComponent.new(variant: :primary) do %>
+  Save
+<% end %>
+
+<%# Wrong: the block attaches to .new, not to render %>
+<%= render Senren::ButtonComponent.new(variant: :primary) { "Save" } %>
+```

data/docs/hot_reload.md

@@ -0,0 +1,103 @@
+# Hot reload
+
+What reloads automatically, what does not, and why — for both people working
+on the gem and people using it in an app.
+
+## Working on the gem
+
+`templates/` is the source of truth, and the preview app under `.local/preview`
+holds *copies* made by `bin/seed_preview`. Editing a template therefore has no
+effect on the running preview until the copy is refreshed. `bin/watch` closes
+that gap.
+
+```bash
+bin/seed_preview                       # once
+cd .local/preview && bin/rails server  # terminal 1
+bin/watch                              # terminal 2, from the gem root
+```
+
+With both running, editing `templates/components/button/button_component.html.erb`
+copies that one file into the preview app and the browser reloads within about
+a second.
+
+What each kind of edit does:
+
+| You edit | `bin/watch` does | Result |
+|---|---|---|
+| `templates/components/<name>/*` | copies the one file | page reloads |
+| `templates/controllers/*.js` | copies the one controller | page reloads |
+| `registry/*.yml` | full reinstall of every component | page reloads |
+| `lib/generators/senren/install/templates/*.tt` | copies to its host path | page reloads |
+| `lib/**/*.rb` | nothing | restart `bin/watch` and the server |
+
+`lib/` is deliberately not watched: changing gem internals requires restarting
+the Ruby process, which a file copy cannot do.
+
+`installed_components.yml.tt` is never synced. That file is a *template* for a
+ledger, and the ledger in the preview app is state — copying over it would
+erase the install history.
+
+Options:
+
+- `SENREN_PREVIEW_ROOT` — watch a preview app somewhere else. Matches
+  `bin/seed_preview`.
+- `SENREN_WATCH_INTERVAL` — poll interval in seconds, default `0.5`.
+
+### How the browser reload works
+
+`bin/watch` writes a timestamp to `tmp/senren-reload.txt` after every sync. The
+preview layout polls `/senren/reload_token` twice a second and calls
+`location.reload()` when the value changes.
+
+This exists because Rails only reloads *Ruby and ERB*. A Stimulus controller is
+JavaScript already delivered to the browser: syncing the file changes nothing
+until the page is reloaded and the module is fetched again. The token is what
+makes controller edits feel hot.
+
+There is no websocket, no ActionCable, and no extra gem — deliberately, since
+the whole plumbing exists only in the gitignored `.local/preview` app and must
+never reach a published gem or a host app.
+
+### Manual check
+
+Automated tests cover the path-mapping logic (`test/template_sync_test.rb`).
+The polling loop itself is verified by hand:
+
+1. Start the server and `bin/watch`.
+2. Change a colour class in a component template — the page reloads with the
+   new style.
+3. Add a `console.log` to a controller — the page reloads and the log appears.
+4. Add a component to `registry/components.yml` — the watcher reports a full
+   reinstall and the new component renders.
+
+## Using the gem in your app
+
+After `bin/rails senren:add`, the components are yours. Rails handles most of
+the reloading, so there is little for Senren to add:
+
+| You edit | Reloads? |
+|---|---|
+| `app/components/senren/*.rb` | Yes — Rails reloads on the next request |
+| `app/components/senren/*.html.erb` | Yes — same |
+| `app/assets/stylesheets/senren.css` | Yes, once Tailwind rebuilds |
+| `app/javascript/controllers/senren/*.js` | **No** — needs a page reload |
+
+The Stimulus row is the one to know about. With importmap the controller is a
+module the browser has already fetched, so editing it does nothing until you
+reload the page. In development Propshaft serves the new file immediately, so
+an ordinary refresh is enough — you do not need to restart the server or clear
+a cache.
+
+If you want that refresh automated, the usual choice is the `hotwire-livereload`
+gem in your own `Gemfile`. Senren does not ship one, because doing so would put
+a development dependency and a websocket into every app that installs a
+component library.
+
+### Turbo morphing
+
+If your app uses Turbo 8 page morphing, a morph can move or replace the element
+a controller is attached to, which triggers `disconnect()` and `connect()`.
+Senren controllers clean up their document-level listeners in `disconnect()`,
+so they survive repeated morphs. If you write your own controller, do the same:
+anything you add to `document` or `window` in `connect()` or on open must be
+removed in `disconnect()`, or it will accumulate on every navigation.

data/docs/performance_testing.md

@@ -0,0 +1,38 @@
+# Performance Testing
+
+Senren uses CI-safe performance gates by default. The goal is to catch
+regressions that this source-copy UI gem can control: template payload
+growth, Stimulus controller payload growth, eager controller loading, and
+runtime-heavy client behavior.
+
+## Commands
+
+```bash
+bin/performance
+bin/system
+bin/ci
+```
+
+`bin/performance` reads `config/performance_budgets.yml`.
+`bin/system` runs headless browser tests against `test/dummy`.
+
+`bin/system` runs Selenium against headless Chrome. It uses a system
+Chrome/Chromium and `/usr/bin/chromedriver` when they are present (the Linux CI
+image), and otherwise lets Selenium Manager resolve and download a matching
+driver — so macOS and other local machines need no setup.
+
+Set `SENREN_CHROME_BIN` or `SENREN_CHROMEDRIVER` only to force a specific
+binary; leaving them unset is the supported path.
+
+## Benchmark Model
+
+- Static budgets are deterministic and run on every PR.
+- System tests verify browser behavior and coarse budgets.
+- Lighthouse CI is deferred until a stable preview/docs URL exists.
+- Competitive framework benchmarking is out of scope for normal CI.
+
+## Browser Budgets
+
+System tests assert gross DOM size, controller loading, external resource,
+and interaction-duration budgets. They intentionally avoid tight timing
+thresholds because shared CI hardware is noisy.

data/lib/commands/senren/add/add_command.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rails/command'
+require 'senren/rails'
+
+module Senren
+  module Command
+    class AddCommand < ::Rails::Command::Base
+      class_option :client, type: :boolean, default: nil,
+                            desc: 'Override registry client behavior for installed components.'
+      class_option :force, type: :boolean, default: false,
+                           desc: 'Overwrite existing component files.'
+
+      desc 'add COMPONENT [COMPONENT...]',
+           'Install one or more Senren components into the current Rails app.'
+      def perform(*names)
+        require_application!
+
+        component_installer.install(
+          names: names,
+          client_override: options[:client],
+          force: options[:force]
+        )
+      rescue ArgumentError => e
+        raise ::Rails::Command::Base::Error, e.message
+      end
+
+      private
+
+      def component_installer
+        Senren::Rails::ComponentInstaller.new
+      end
+    end
+  end
+end

data/lib/generators/senren/component/templates/controller.js.tt

@@ -3,11 +3,14 @@ import { Controller } from "@hotwired/stimulus"
 // Stimulus controller for Senren <%= class_name %>.
 // Identifier: <%= stimulus_identifier %>
 //
-// Responsibilities (local UI only):
+// Scope — local UI only:
 // - Manage open/close, focus, or keyboard behavior for this component.
-// Forbidden:
-// - fetch / XHR (Turbo handles server state)
-// - importing React, Vue, Alpine, lit, or any other framework
+//
+// Out of scope:
+// - fetch / XHR. Turbo owns server state; a controller that fetches ends up
+//   holding a second copy of it.
+// - Importing a client-side rendering framework. This component's markup comes
+//   from the server, so a second renderer would be fighting it for the DOM.
 export default class extends Controller {
   static targets = []
   static values  = {}

data/lib/generators/senren/install/install_generator.rb

@@ -38,6 +38,27 @@ module Senren
         copy_file Senren::Rails.registry_path, '.senren/registry.yml'
       end
 
+      # Switches Stimulus to on-demand loading instead of documenting it.
+      #
+      # Rails' default is `eagerLoadControllersFrom("controllers", application)`,
+      # which imports every controller in the importmap on every page. Because
+      # `pin_all_from "app/javascript/controllers"` is recursive it also covers
+      # app/javascript/controllers/senren, so a static page paid for every
+      # interactive component the app had installed.
+      #
+      # This was a README instruction the developer had to follow by hand, and a
+      # "PASS" in bin/performance that only grepped that README. An instruction
+      # nobody runs is not a feature.
+      #
+      # It uses the official stimulus-loading helper rather than a Senren-specific
+      # loader, and therefore changes loading for the app's own controllers too.
+      # That is the trade the README already asked for; the generator only acts
+      # when the file still carries the untouched Rails default, and says so.
+      def configure_stimulus_loading
+        enable_lazy_controller_loading
+        disable_controller_preloading
+      end
+
       def write_skill_file
         say_status :senren, 'writing .senren/skill.md'
         Senren::Rails::SkillWriter.new(paths: host_paths).sync!
@@ -56,6 +77,59 @@ module Senren
 
       private
 
+      def enable_lazy_controller_loading
+        index = 'app/javascript/controllers/index.js'
+        unless host_file?(index)
+          return say_status(:skip,
+                            "#{index} not found; switch to lazyLoadControllersFrom by hand")
+        end
+
+        source = File.read(File.join(destination_root, index))
+        if source.include?('lazyLoadControllersFrom')
+          return say_status(:senren,
+                            'controllers already load on demand')
+        end
+
+        unless source.include?('eagerLoadControllersFrom')
+          return say_status(:skip, "#{index} has a custom loader; left alone")
+        end
+
+        gsub_file index, 'eagerLoadControllersFrom', 'lazyLoadControllersFrom'
+        say_status :senren, 'Stimulus controllers now load when their data-controller appears'
+      end
+
+      # Only strips the modulepreload tags. On its own it does not stop eager
+      # importing, which is why it is paired with the change above.
+      def disable_controller_preloading
+        importmap = 'config/importmap.rb'
+        unless host_file?(importmap)
+          return say_status(:skip,
+                            "#{importmap} not found; add preload: false by hand")
+        end
+
+        source = File.read(File.join(destination_root, importmap))
+        if source.match?(/under:\s*["']controllers["'].*preload:\s*false/)
+          return say_status(:senren,
+                            'controller preloading already disabled')
+        end
+
+        if source.match?(%r{pin_all_from\s+["']app/javascript/controllers["']})
+          # A backreference rather than a block: Thor forwards the block to
+          # String#gsub across several frames, where $~ is no longer the match.
+          # The lookahead makes a second run a no-op.
+          gsub_file importmap,
+                    %r{(pin_all_from\s+["']app/javascript/controllers["'](?![^\n]*preload:)[^\n]*)},
+                    '\1, preload: false'
+        else
+          append_to_file importmap,
+                         %(\npin_all_from "app/javascript/controllers", under: "controllers", preload: false\n)
+        end
+      end
+
+      def host_file?(relative)
+        File.exist?(File.join(destination_root, relative))
+      end
+
       def host_paths
         @host_paths ||= Senren::Rails::HostPaths.new(destination_root)
       end

data/lib/generators/senren/install/templates/base_component.rb.tt

@@ -1,3 +1,6 @@
+require 'uri'
+require 'view_component'
+
 module Senren
   # Base class for every Senren ViewComponent.
   #
@@ -6,13 +9,16 @@ module Senren
   # - variant and size resolution against class-level constants
   # - small class merger (no external `tailwind_merge` dependency in v0.1)
   # - a default root-attribute helper that emits `data-senren-component="<name>"`
-  class BaseComponent < ViewComponent::Base
-    VARIANTS = { default: "" }.freeze
-    SIZES    = { md: "" }.freeze
+  class BaseComponent < ::ViewComponent::Base
+    VARIANTS = { default: '' }.freeze
+    SIZES    = { md: '' }.freeze
+    SAFE_URL_PROTOCOLS = %w[http https mailto tel].freeze
+    SAFE_MEDIA_URL_PROTOCOLS = %w[http https].freeze
 
     attr_reader :class_name, :variant, :size, :html_attrs
 
     def initialize(variant: :default, size: :md, class_name: nil, **html_attrs)
+      super()
       @variant = resolve!(variant, self.class::VARIANTS, :variant)
       @size    = resolve!(size,    self.class::SIZES,    :size)
       @class_name = class_name
@@ -21,25 +27,100 @@ module Senren
 
     # Compose final root attributes; subclasses pass their base classes.
     def root_attrs(*classes, **extra)
-      data = (extra.delete(:data) || {}).merge(senren_component: senren_component_name)
-      tag_class = merge_classes(classes, self.class::VARIANTS[@variant], self.class::SIZES[@size], @class_name, extra.delete(:class))
-      { class: tag_class, data: data, **html_attrs, **extra }
+      # `data` arrives from two places: the caller's own attributes (html_attrs)
+      # and whatever the template passes here. Both are merged, and the
+      # component marker is applied last so it always survives.
+      #
+      # Splatting html_attrs after a computed `data:` used to overwrite it
+      # wholesale, so any component given a `data:` hash silently lost its
+      # data-senren-component marker. MaskedInput hit this on every render.
+      data = (html_attrs[:data] || {})
+             .merge(extra.delete(:data) || {})
+             .merge(senren_component: senren_component_name)
+
+      # `class` had exactly the same defect and it was never fixed alongside
+      # `data`. Every Rails tag helper accepts `class:`, so it is the first
+      # thing anyone types — and splatting html_attrs replaced the computed
+      # value outright, erasing the component's variant and size styling with
+      # no warning. It is merged like any other caller-supplied class instead,
+      # last so it still wins where the two genuinely conflict.
+      tag_class = merge_classes(
+        classes,
+        self.class::VARIANTS[@variant],
+        self.class::SIZES[@size],
+        @class_name,
+        extra.delete(:class),
+        html_attrs[:class]
+      )
+      { class: tag_class, data: data, **html_attrs.except(:data, :class), **extra }
     end
 
     def senren_component_name
-      self.class.name.to_s.sub(/^Senren::/, "").sub(/Component$/, "").gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      self.class.name.to_s.sub(/^Senren::/, '').sub(/Component$/, '').gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+    end
+
+    # Builds a DOM id from the arguments that identify this component, so the
+    # same inputs always produce the same id.
+    #
+    # Components used to append `SecureRandom.hex`, which made every render emit
+    # different HTML. That single fact disabled Turbo morph (it pairs nodes by
+    # id), HTTP ETags (the body never matched), fragment caching (cached and
+    # fresh fragments referenced different ids), and snapshot testing.
+    #
+    # Two components with identical identifying inputs on one page now produce
+    # the same id and the accessibility test fails. That is deliberate: the
+    # caller should pass an explicit `id:`. A random suffix hid the collision
+    # instead of resolving it.
+    def senren_dom_id(*parts)
+      seed = parts.flatten.map(&:to_s).reject(&:empty?).join('-')
+      base = "senren-#{senren_component_name.tr('_', '-')}"
+      return base if seed.empty?
+
+      "#{base}-#{seed.parameterize}"
     end
 
     private
 
+    def safe_url(value, fallback: '#', protocols: SAFE_URL_PROTOCOLS)
+      url = value.to_s.strip
+      return fallback if url.empty?
+      # Browsers treat "\" as "/" for special schemes and strip TAB/CR/LF
+      # before parsing, so "/\evil.example" and "/<TAB>/evil.example" would
+      # both slip past a plain "//" check and resolve off-origin.
+      return fallback if url.include?('\\')
+      return fallback if url.match?(/[[:cntrl:]]/)
+      return url if url.start_with?('#')
+      # Any leading "//" is protocol-relative regardless of how many slashes
+      # follow. Rejecting here rather than relying on URI.parse matters:
+      # URI.parse("///evil.example") reports no scheme and no host, so the
+      # scheme-less fallback below would otherwise hand back a URL the browser
+      # resolves to https://evil.example/.
+      return fallback if url.start_with?('//')
+      return url if url.start_with?('/')
+
+      uri = URI.parse(url)
+      return url if uri.scheme && Array(protocols).map(&:to_s).include?(uri.scheme.downcase)
+      return fallback if uri.host
+      return url unless uri.scheme
+
+      fallback
+    rescue URI::InvalidURIError
+      fallback
+    end
+
+    def safe_media_url(value, fallback: nil)
+      safe_url(value, fallback: fallback, protocols: SAFE_MEDIA_URL_PROTOCOLS)
+    end
+
     def resolve!(value, table, label)
       key = value.to_sym
       return key if table.key?(key)
+
       raise ArgumentError, "Unknown #{label}: #{value.inspect}. Allowed: #{table.keys.join(', ')}"
     end
 
     def merge_classes(*sources)
-      sources.flatten.map { |s| s.to_s.strip }.reject(&:empty?).join(" ")
+      sources.flatten.map { |s| s.to_s.strip }.reject(&:empty?).join(' ')
     end
   end
 end