senren-ui 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e233d7736e61036693bb895d99e0fd11a37eb9e183979fa9ea4f1d17d1686354
-  data.tar.gz: dbe764908e51d5007e876c412e2cdffeac6d2b36ac10b8b16187f376ef1e24f0
+  metadata.gz: d99681351df1dad873d945bf82b3070b3f8393c9d14b3ca65917262e6258ef6c
+  data.tar.gz: b487d9ac589b1d9ba2c304a5f53e4d93064b321d76e97a43ccfa1b9909a44b58
 SHA512:
-  metadata.gz: 4a9bd5abdf7f39b9afd87d94e263b256c4e8fd226d5505bee5e1c7cd031e44fe917442b17479718fe39d23909ceee0f94e064073a7717b6309508471db18ce8b
-  data.tar.gz: a40ab2909ac0f30900fe8e2aace6eba439820ac83cd2ccd37c6037bfcf372225c02d1268a721c3b38a4c243872c35b833ead558621a65a8399b9e8ea632d96b8
+  metadata.gz: f383e88dea3c90da1f1f93831bdf26c4bc5e00e1c63ffeb8ae53031d7c7e38c8afbaa30c445839cdbf8ad346acf247dcd04ae597c01b23704837daeb4eb4c2bf
+  data.tar.gz: 54e1f4ad10351c05906cdf1f864160cd3a0555e1698c0fa4944a728752cd97560300a9bae40a337a214a39d19eae87a3620fd4690e412d689b9430d022df0662

data/CHANGELOG.md

@@ -7,6 +7,128 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 v0.x is a pre-stable line: minor bumps may break things; patch bumps are
 bug fixes only.
 
+## [0.2.0] — 2026-08-02
+
+A hardening release. Most of it came out of an adversarial review of the whole
+library; each item below was reproduced by running it before being fixed, and
+pinned by a test that was watched failing first.
+
+### Upgrading
+
+Four changes alter existing behaviour. None requires a code change in your app,
+but read these before upgrading:
+
+- **`class:` now merges instead of replacing.** Previously
+  `ButtonComponent.new(variant: :primary, class: "mt-2")` rendered
+  `class="mt-2"` and dropped the variant and size styling entirely. It now
+  renders both. If you worked around the old behaviour by re-specifying every
+  utility, you can stop.
+- **DOM ids are derived from component arguments, not random.** Ids are now
+  stable across renders, which is what makes Turbo morphing, fragment caching,
+  and ETags work. If you hard-coded a generated id in a test or a stylesheet,
+  it will have changed.
+- **Booting with `app/components` on the asset load path now fails in
+  production.** See *Security* below. If you added that line for sidecar
+  assets, point it at `app/components/assets` instead.
+- **`Senren::Rails::Installer` was removed.** It had no callers, and copying
+  `.tt` templates without rendering them would have written raw ERB into a host
+  app. `senren:install` is the supported path.
+
+### Added
+
+- `CartComponent` and `ProductCardComponent`, plus a `storefront` recipe.
+  The cart keeps a live subtotal and quantity steppers client-side and
+  announces changes with `senren--cart:changed`; the product tile submits a
+  form and ships no JavaScript, so listing pages stay light.
+- `lib/senren-ui.rb`, so `gem "senren-ui"` loads the engine without a
+  `require:` option. Previously that form silently loaded nothing — no engine,
+  no rake tasks, and no asset guard — while the generator kept working.
+- On-demand Stimulus loading, installed rather than documented.
+  `senren:install` switches `controllers/index.js` to `lazyLoadControllersFrom`
+  and adds `preload: false` to the controllers pin. It leaves a customised
+  `index.js` or a non-importmap app alone and reports what it did.
+- `bin/watch`, which syncs template edits into the local preview app and
+  reloads the browser. Development-only; nothing ships to host apps.
+- A Ruby 3.2–3.4 × Rails 7.1–8.1 test matrix, so the versions the gemspec
+  claims are the versions that are proved.
+
+### Changed
+
+- Overlay components (dialog, sheet, popover, dropdown, context menu, alert
+  dialog) drive their state through Stimulus values instead of writing to the
+  DOM directly, so state survives Turbo morphs.
+- `--client` / `--no-client` applies only to the components you name.
+  It used to apply to the whole dependency closure, so
+  `senren:add context_menu --no-client` also stripped `dropdown_menu`'s
+  controller and the installed menu silently never opened.
+- `.senren/skill.md` describes what was actually installed. It previously
+  reported the registry default, naming controller files that were not on disk.
+- `.senren/registry.yml` refreshes on every install instead of drifting from
+  the gem after the first one.
+- Rake helpers live in `SenrenRakeArgs` rather than as top-level methods on
+  `Object`, and argument scanning stops at the next rake task —
+  `rake 'senren:add[button]' db:seed` no longer tries to install `db:seed`.
+- Documentation states the library's scope without characterising other
+  ecosystems.
+
+### Security
+
+- **Component source could be published in production.** With
+  `config.assets.paths << Rails.root.join("app/components")` — a line that
+  circulates as ViewComponent sidecar-asset guidance — Propshaft resolved every
+  component `.rb` and `.html.erb` as an asset, `assets:precompile` copied them
+  into `public/assets`, `.manifest.json` listed each by name, and the digested
+  URL returned Ruby source with `HTTP 200`. A boot check now raises in any
+  deployed environment and warns in development. Sidecar assets in their own
+  directory are unaffected.
+- **The installer could write outside the application root.** A checkout
+  shipping `app/components/senren` as a symlink redirected copied files, and
+  the agent-adapter writers read their destination before rewriting it, so
+  content outside the checkout was modified too. All writes now go through one
+  containment layer that resolves symlinks, covers dangling links, and refuses
+  only paths that leave the root — an in-repo symlink such as
+  `ln -s AGENTS.md CLAUDE.md` keeps working.
+- **`FormComponent#url` and `AvatarComponent#src` were unsanitised.** The first
+  reaches `form_with`'s action, where a protocol-relative URL sends every field
+  and the CSRF token off-origin. Both now use the same URL policy as the rest
+  of the library, and a property test covers every component rather than a list
+  of known ones.
+- Rich-text paste is sanitised, and the two URL policies (markup versus typed
+  input) are separated so neither can promote a relative path to another origin.
+- Five dependency advisories resolved, and `bundler-audit` is now a CI gate.
+
+### Fixed
+
+- `senren:doctor` reported success unconditionally.
+- Marker-managed files could be corrupted by generated content containing
+  regexp backreferences, and could inject their own markers.
+- `TypographyComponent`, `SeparatorComponent`, and `AspectRatioComponent`
+  raised on `.new` without an explicit variant.
+- `data:` passed to any component dropped its `data-senren-component` marker.
+- Eight components produced a new DOM id on every render.
+- `date_picker` lost its height to a fused CSS class.
+- Stimulus controllers no longer leak timers or document-level listeners across
+  Turbo navigations.
+- Checkbox, radio, and switch controls are reachable by their accessible name.
+
+## [0.1.6] — 2026-06-09
+
+### Added
+
+- Local preview app now seeds the full registered Senren component set and renders an exhaustive component kitchen sink.
+
+### Changed
+
+- `bin/seed_preview` is now the canonical local preview seed command and targets `.local/preview`.
+- `bin/seed_preview` writes a local-path gem entry that works for custom preview roots.
+- `.rubocop.yml` target Ruby version now matches the gem runtime floor required by ViewComponent 4.x.
+
+### Fixed
+
+- `safe_url` now accepts same-origin relative URLs such as `?page=:page`, `./settings`, and `settings` while still rejecting unsafe schemes and hosts.
+- `ComponentCopier` applies the same URL rules when patching existing host apps.
+- Local preview layout keeps the Tailwind browser compiler enabled so the preview renders correctly out of the box.
+
 ## [0.1.5] — 2026-05-03
 
 ### Added
@@ -79,7 +201,7 @@ bug fixes only.
 - Tailwind design-token stylesheet (`senren.css`) with light/dark.
 - Centralized `.senren/skill.md` system with preserved user-region.
 - `public/llms.txt` and `public/llms-full.txt` generation.
-- `apps/todolist` Rails app dogfooding the gem via local path.
+- A Rails dogfooding app for local-path gem integration.
 - Bun-based JS tooling for Stimulus templates:
   - `bun run controllers:syntax`
   - `bun run controllers:lint`
@@ -108,4 +230,4 @@ bug fixes only.
 ## [0.1.0] — 2026-04-27
 
 First tagged release once the Unreleased entries are validated end-to-end
-in `apps/todolist` per `plans/011_release_checklist.md`.
+against the project dogfooding app per `plans/011_release_checklist.md`.

data/CONTRIBUTING.md

@@ -17,24 +17,61 @@ this file before opening a PR.
 
 ```bash
 git clone <repo>
-cd senren-rails
+cd senren-ui
 bundle install
 bun install
-bundle exec rake test
+bin/ci             # every gate, reports all failures rather than the first
+bin/ci --matrix    # additionally run the Rails 7.1-8.1 matrix (slow)
+```
+
+Individual gates, if you want to run one in isolation:
+
+```bash
+bin/test                              # unit tests (no Rails app booted)
+bundle exec rake test:integration     # renders all 62 components via test/dummy
+bin/system                            # headless browser tests
+bin/performance                       # payload and runtime budgets
+bin/matrix                            # unit tests on every supported Rails
+bundle exec rubocop
+bundle exec bundle-audit check --update
 bun run controllers:check
 ```
 
-To exercise the gem against a real Rails app, use the bundled workspace:
+`bin/system` needs no setup: it uses a system Chrome and
+`/usr/bin/chromedriver` when present, and otherwise lets Selenium Manager
+fetch a matching driver.
+
+Supported versions are proved, not asserted. `gemfiles/rails_*.gemfile` drive
+the matrix via `BUNDLE_GEMFILE`, CI runs Ruby 3.2-3.4 × Rails 7.1-8.1 with
+`fail-fast: false`, and `test/gem_packaging_test.rb` fails if the gemspec's
+floors drift out of that matrix.
+
+To exercise the gem against a local host app inside this repo:
 
 ```bash
-cd ../apps/todolist
-bundle install
-bin/rails db:setup
-bin/rails generate senren:install
-bin/rails senren:add button card badge alert
+cd /path/to/senren-ui
+bin/seed_preview
+cd .local/preview
 bin/rails server
+# optional custom path:
+# SENREN_PREVIEW_ROOT=/abs/path/to/your/preview-app bin/seed_preview
 ```
 
+While the server runs, start the watcher from the gem root in another
+terminal so template edits appear without re-seeding:
+
+```bash
+bin/watch
+```
+
+It copies changed files from `templates/` and `registry/` into the preview
+app and reloads the browser. See `docs/hot_reload.md` for what does and does
+not reload.
+
+The local preview uses Tailwind's browser runtime for convenience. The
+real documentation/reference app is maintained separately in
+`senren-ui-page`.
+
 ## What to forbid in PRs
 
 - React, Vue, Alpine, lit, or any other JS framework dependency.
@@ -54,14 +91,47 @@ bin/rails server
   (`app/javascript/controllers/senren/<name>_controller.js`).
 - Component test in `test/components/`.
 - System test in `test/system/` if interactive.
+- Nothing extra is needed for render coverage: `test/integration/` renders
+  every registered component in every declared variant and size, driven
+  from the registry, so a new component is covered as soon as it has a
+  preview in `ComponentPreviewHelper`.
 - Registry entry in `registry/components.yml` (full schema).
 - Skill block produced by `SkillWriter`.
-- Demo usage in `apps/todolist` if relevant to the Todo UI.
+- Demo usage in `.local/preview` if relevant to the local preview UI.
 
 ## Commit hygiene
 
 - One logical change per commit.
 - Mention the affected plan and history files in the commit body.
+- Run `bin/ci` before pushing.
+- Run `bin/ci --matrix` if you touched the gemspec, the Gemfile, or anything
+  version sensitive.
 - Run `bundle exec rake test` before pushing.
+- Run `bin/system` before pushing if you touched component templates,
+  Stimulus controllers, or the dummy preview app.
+- Run `bundle exec rubocop` before pushing.
+- Run `bin/performance` before pushing if you touched component
+  templates, Stimulus controllers, or Importmap loading guidance.
 - Run `bun run controllers:check` before pushing if you touched
   `templates/controllers/*.js`.
+
+## Pull request workflow
+
+1. Fork the repo and branch from `main`.
+2. Keep each PR scoped to one logical change.
+3. If the change is architectural, add or update a matching `plans/`
+   entry first.
+4. Before opening the PR, add or update the matching `history/` file.
+5. Fill in the PR template with exact validation commands and results.
+
+## Security workflow
+
+- Do not report vulnerabilities in public issues.
+- Use GitHub Security Advisories or the contact in `SECURITY.md`.
+- Do not commit API keys, credentials, or private tokens, even in tests
+  or screenshots.
+- Do not pass untrusted URLs directly to component `href`/`src`
+  attributes. Use the shared `safe_url` / `safe_media_url` helpers.
+- Do not use `raw`, `html_safe`, `innerHTML =`,
+  `insertAdjacentHTML`, `eval`, direct SQL APIs, or string-built SQL.
+  The security tests intentionally fail on these escape hatches.

data/README.md

@@ -1,6 +1,6 @@
 # Senren UI (`senren-ui`)
 
-> 洗練 — refined, polished, sophisticated.
+> 洗練 *(senren)* — Japanese for "refinement".
 
 **[Live Docs & Component Reference → senren-ui.dev](https://www.senren-ui.dev)**
 
@@ -16,12 +16,19 @@ skill system and a source-copy install model inspired by shadcn/ui.
   every installed component, its dependencies, and its anti-patterns.
 - A multi-agent instruction sync for Codex, Claude, Copilot, and Cursor.
 
-## What Senren is not
+## Scope
 
-- Not React, Vue, Alpine, or any external state framework.
-- Not a CSS-only kit — components ship Ruby + ERB + (optional) Stimulus.
-- Not an opaque dependency — installed components live in your app
-  under `app/components/senren/` and you own them.
+Senren renders on the server. Components are ViewComponent classes with ERB
+templates, interactivity is Stimulus, and server state is Turbo's job. It is
+not a client-side rendering layer: if your app is built around React, Vue, or
+another client framework, a component library from that ecosystem will fit it
+better than this one.
+
+Two other things worth knowing up front:
+
+- Components ship as Ruby + ERB + optional Stimulus, not as a CSS-only kit.
+- They are copied into your app under `app/components/senren/`, so they are
+  yours to read and edit rather than an opaque dependency.
 
 ## Installation
 
@@ -42,6 +49,10 @@ bin/rails senren:add button card badge alert form input \
   textarea native_select table dropdown_menu dialog alert_dialog
 ```
 
+`senren:add` also works via `bundle exec rails senren:add ...`. The older
+bracketed Rake task form, `bin/rails 'senren:add[button,card]'`, remains
+supported for backward compatibility.
+
 ## Daily commands
 
 ```bash
@@ -50,11 +61,94 @@ bin/rails generate senren:component picker --client  # custom component with Sti
 bin/rails generate senren:component picker --no-client  # without Stimulus
 bin/rails senren:add dialog --client        # install interactive official component
 bin/rails senren:add button                 # install static official component
+bundle exec rails senren:add form input     # equivalent alternate entry point
 bin/rails senren:skill:sync                 # rebuild .senren/skill.md
 bin/rails senren:agents:sync                # rebuild .senren/agent-rules + adapters
 bin/rails senren:doctor                     # check installation health
 ```
 
+### What reloads while you work
+
+Components copied into your app are ordinary Rails code, so editing a
+`*_component.rb` or `*.html.erb` takes effect on the next request with no
+restart. The exception is Stimulus: a controller under
+`app/javascript/controllers/senren/` is a module the browser has already
+fetched, so editing it needs a page reload — the server does not need
+restarting. `docs/hot_reload.md` has the details, including Turbo morphing.
+
+## Keeping Stimulus JavaScript small
+
+`bin/rails generate senren:install` wires on-demand controller loading for
+you. It switches `app/javascript/controllers/index.js` from Rails' default
+`eagerLoadControllersFrom` to `lazyLoadControllersFrom`, and adds
+`preload: false` to the controllers pin in `config/importmap.rb`.
+
+Without it, an Importmap app downloads **every** controller on **every** page.
+`pin_all_from "app/javascript/controllers"` is recursive, so it covers
+`app/javascript/controllers/senren` too — a static marketing page paid for the
+rich text editor. With it, a module is fetched the first time its
+`data-controller` identifier appears, including markup Turbo inserts later.
+
+Two things worth knowing:
+
+- It changes loading for **your** controllers as well, because it uses the
+  official `stimulus-loading` helper rather than a Senren-specific loader.
+  Lazy loading is the better default for almost every app, but it is your
+  call — the generator only edits the file while it still carries the
+  untouched Rails default, and reports what it did.
+- If you have already customised `index.js`, or you bundle with esbuild or
+  Vite instead of Importmap, the generator leaves it alone and says so.
+
+This used to be a paragraph asking you to do it by hand, and a CI check that
+passed as long as the paragraph existed. It is now installed and asserted in
+`test/generators/install_generator_test.rb` against the files `rails new`
+actually produces.
+
+## Component source in production
+
+Senren copies editable ViewComponent, ERB and Stimulus source into your app.
+That is the point of the design, and it means minification and source maps are
+your app's decision, not the gem's — Senren ships readable source and gets out
+of the way.
+
+Readable in your repo is not the same as readable over HTTP, and there is one
+configuration that turns the first into the second:
+
+```ruby
+# config/initializers/assets.rb — do NOT do this
+Rails.application.config.assets.paths << Rails.root.join("app/components")
+```
+
+That line appears in guidance about ViewComponent sidecar assets, and under
+Propshaft it publishes the whole directory. Reproduced against Propshaft 1.3.2:
+every `.rb` and `.html.erb` under `app/components` was resolved as an asset,
+`RAILS_ENV=production rails assets:precompile` copied them into `public/assets`,
+`public/assets/.manifest.json` listed each one next to its digested filename —
+so the digest is not a secret — and requesting the digested URL returned the
+Ruby source with `HTTP 200`, served by the web server without Rails involved.
+
+Senren refuses to let this ship. A boot check runs after your initializers:
+
+- **production** — raises, so the app does not boot and `assets:precompile`
+  fails. A failed deploy is recoverable; published source is not.
+- **anywhere else** — prints a warning and carries on, because development is a
+  different risk calculation.
+
+It only objects when component source actually sits under an asset path, so
+sidecar assets remain available — put them in their own directory:
+
+```ruby
+Rails.application.config.assets.paths << Rails.root.join("app/components/assets")
+```
+
+The default configuration is unaffected: with no such line, every component
+path returns `404`. The gem itself adds no production request-path code, and
+this check is the sole exception.
+
+See `test/asset_path_guard_test.rb` and
+`test/integration/asset_path_guard_boot_test.rb`, which boot a real Rails app
+with a real Propshaft and assert that precompile cannot publish source.
+
 ## Using a component
 
 ```erb
@@ -73,17 +167,27 @@ bin/rails senren:doctor                     # check installation health
 
 ## Workspace layout
 
-This repository ships as a workspace with a real Rails dogfooding app:
+This repository ships as a gem source checkout with a git-ignored local
+preview host:
 
 ```text
-senren-workspace/
-  senren-rails/        # the local gem source directory
-  apps/
-    todolist/          # real Rails app that uses senren-ui via local path
+senren-ui/
+  .local/
+    preview/           # local Rails preview host, ignored by git
+```
+
+Use `bin/seed_preview` to create or refresh `.local/preview`. It
+installs a small Senren component preview route, imports `senren.css`,
+and loads Tailwind's browser runtime for local visual checks.
+
+```bash
+bin/seed_preview
+cd .local/preview
+bin/rails server
 ```
 
-`apps/todolist` is the production-like acceptance test for Senren — a
-small SaaS-style Todo manager built entirely from Senren components.
+The full documentation/reference site lives outside this gem checkout in
+`senren-ui-page`.
 
 ## AI Agent skill system
 
@@ -108,7 +212,7 @@ generated block and preserves your existing instructions outside that block.
 
 ## Component list
 
-See `registry/components.yml` for the canonical list. v0.1 ships:
+See `registry/components.yml` for the canonical list. Currently shipping:
 
 - **Phase 1 — Foundation** (full): Button, Link, Badge, Typography,
   Separator, Skeleton, Avatar, Alert, Card, AspectRatio.
@@ -126,6 +230,8 @@ See `registry/components.yml` for the canonical list. v0.1 ships:
 bundle install
 bun install
 bundle exec rake test            # gem tests
+bin/system                       # headless browser system tests
+bin/performance                  # local payload/performance budgets
 bun run controllers:check        # lint + syntax check for templates/controllers/*.js
 bun run controllers:lint:fix     # auto-fix lint issues for controllers
 bundle exec rake test:system     # Stimulus/system tests
@@ -139,6 +245,35 @@ See `CONTRIBUTING.md`. Two rules to know up front:
 2. Architectural decisions are captured in `plans/` before code is
    written.
 
+## Project health
+
+Every push runs the test suite, RuboCop, and the JavaScript checks against
+Ruby 3.2–3.4 × Rails 7.1–8.1. CodeQL scans Ruby and JavaScript, and Dependabot
+tracks Bundler, JS tooling, and Actions.
+
+Security reports go to `SECURITY.md`.
+
+## Acknowledgements
+
+Senren builds on ideas from prior art. No source code from either project is
+included here — the influence is on architecture and developer experience, and
+both are credited because ideas have authors even when licences do not require
+the notice.
+
+- [shadcn/ui](https://github.com/shadcn-ui/ui) (MIT) — the source-copy install
+  model: components are copied into your app so you own and can edit them,
+  rather than being rendered from inside a dependency.
+- [jetrockets/jet_ui](https://github.com/jetrockets/jet_ui) (MIT, © 2026
+  JetRockets) — a Rails/ViewComponent UI library whose maintainers write openly
+  about the trade-offs they worked through. That writing informed
+  `plans/022_jet_ui_lessons.md`: how Tailwind's content scanning interacts with
+  components shipped from inside a gem, and the case for testing every Ruby and
+  Rails version a gem claims to support. Both points made this library better.
+
+Both are MIT licensed, which permits use, modification, and study. The MIT
+notice requirement attaches to copies of the software; since Senren copies no
+code from either, this section is attribution rather than a licence obligation.
+
 ## License
 
 MIT — see `LICENSE`.

data/Rakefile

@@ -6,11 +6,24 @@ require 'rake/testtask'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb'].exclude('test/system/**/*_test.rb')
+  t.test_files = FileList['test/**/*_test.rb']
+                 .exclude('test/system/**/*_test.rb')
+                 .exclude('test/integration/**/*_test.rb')
   t.warning = false
 end
 
 namespace :test do
+  # Separate process, like system tests, and for the same reason: the unit
+  # suite `load`s component classes directly, and booting the dummy app would
+  # load them a second time. ViewComponent 4 raises RedefinedSlotError on the
+  # duplicate declaration.
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.test_files = FileList['test/integration/**/*_test.rb']
+    t.warning = false
+  end
+
   Rake::TestTask.new(:system) do |t|
     t.libs << 'test'
     t.libs << 'lib'