[Improvement] Docs: symlink Stimulus controllers to gem source instead of copying

[djalmaaraujo]

Problem

`docs/app/javascript/controllers/ruby_ui/_controller.js` was a hand-maintained copy of `gem/lib/ruby_ui//_controller.js`, kept in sync by manually copying files. This drifted silently: the accordion Stimulus fix landed in the gem (commit 0897b2a) but the docs copy was never updated, so the live accordion preview at rubyui.com/docs/accordion broke (content never revealed on click). That fix is currently sitting in still-open PR #490.

The Ruby side of this exact problem is already solved — `docs/config/initializers/ruby_ui.rb` autoloads Phlex components straight from `gem/lib/ruby_ui` via Zeitwerk, no copy at all. Only the JS side still duplicated.

Fix

Replace all 37 docs controller files with relative symlinks into the corresponding gem source file, e.g.:

```
docs/app/javascript/controllers/ruby_ui/accordion_controller.js
-> ../../../../../gem/lib/ruby_ui/accordion/accordion_controller.js
```

The gem subdirectory doesn't always match the controller basename (e.g. `checkbox_group_controller.js` lives under `gem/lib/ruby_ui/checkbox/`, `select_item_controller.js` under `gem/lib/ruby_ui/select/`) — the mapping was built from a real `find` over both trees, not guessed.

Files with genuinely stale content pre-migration (diffed docs copy vs. gem source before symlinking):

• `accordion_controller.js` — missing the hidden-attribute handling (the bug fixed in PR [Bug Fix] Accordion: sync docs Stimulus controller with gem #490)
• `avatar_controller.js` — missing a couple of defensive checks/comments
• `combobox_controller.js` — missing minPopoverWidth/placement Stimulus values, hardcoded 'bottom-start' placement
• `sheet_controller.js` — missing an open Stimulus value + connect() auto-open behavior

The other 33 were already byte-identical.

This PR supersedes #490 for `accordion_controller.js` specifically — the symlink now points at the gem's current (correct) source regardless of whether #490 merges. Not touching or closing #490; leaving its fate to a human.

New dev workflow for adding a component

`rake ruby_ui:sync_controller_symlinks` (new task, `docs/lib/tasks/ruby_ui.rake`) scans `gem/lib/ruby_ui/**/*_controller.js` and creates/repairs any missing symlink. Idempotent — safe to re-run. It replaces the old "copy the file by hand" step. It intentionally does not touch the Stimulus manifest — `bin/rails stimulus:manifest:update` is still a required separate step to register a brand-new controller in `controllers/index.js`.

esbuild wrinkle found along the way

esbuild's default symlink handling resolves a symlinked module's imports relative to its real path. Since `gem/` and `docs/` are sibling directories with no shared ancestor `node_modules`, this broke resolution of `@hotwired/stimulus`, `@floating-ui/dom`, and `motion` for every symlinked controller with an external import. Fixed by adding `--preserve-symlinks` to the `build` script in `docs/package.json`, which makes esbuild resolve relative to the symlink's own location instead.

Docs updated in this PR

• Root `CLAUDE.md` — routing note on the symlink relationship + new rake task.
• `gem/AGENTS.md` — JavaScript section notes docs symlinks straight to these files now.
• `docs/CLAUDE.md` — new short section on the symlinked directory + workflow.
• `.claude/skills/ruby-ui-stimulus/SKILL.md` — "Register & declare deps" step now mentions the symlink + sync task.

Test plan

Verified in the docs devcontainer (a fresh instance mounted against this branch, ports 3002/host to avoid clashing with any other running instance):

• All 37 symlinks created; each verified individually with readlink -f resolving to the correct existing gem file (not just trusting the naming pattern).
• bin/rails stimulus:manifest:update regenerates app/javascript/controllers/index.js byte-identical to before the migration (import paths are relative to app/javascript/controllers, unaffected by symlinks).
• New rake ruby_ui:sync_controller_symlinks is idempotent on a fully-synced tree, and correctly recreates a symlink I deleted as a test (verified the recreated link's target).
• pnpm build — failed initially on unresolved @hotwired/stimulus / @floating-ui/dom / motion imports (see esbuild wrinkle above); passes after adding --preserve-symlinks.
• pnpm build:css — passes.
• Grepped the built app/assets/builds/application.js for controller-specific code (not just import statements): found content.removeAttribute("hidden") / content.setAttribute("hidden", "") from the gem's fixed accordion controller, and computePosition from the real @floating-ui/dom package — confirms the bundle contains real gem-sourced content, not broken/empty imports.
• Booted bin/rails server in the container and curl'd it directly: /docs/accordion, /docs/tooltip, /docs/popover, /docs/checkbox, /docs/select all return 200; fetched the served, fingerprinted application-*.js asset over HTTP and re-confirmed the same accordion/floating-ui strings are present in what the server actually serves.
• bin/rails test (docs) — 75 runs, 107 assertions, 0 failures, 0 errors.
• bundle exec standardrb (docs) — clean, exit 0.

Not verified: no real browser was available in this environment, so I could not click through the accordion/combobox/tooltip UI interactively. Confidence here rests on the four checks above (manifest diff, bundle content grep, HTTP 200 + asset content over curl, and the existing Rails test suite) rather than a driven browser session — flagging this explicitly rather than overclaiming.

---

Summary by cubic

Symlinked all docs’ Stimulus controllers to the gem source to eliminate drift and ensure previews always use the latest code. Fixes the broken accordion demo and updates the build to support symlinks.

• Refactors

  • Replaced 37 files in docs/app/javascript/controllers/ruby_ui/ with symlinks to gem/lib/ruby_ui/<component>/….
  • Updated esbuild build script with --preserve-symlinks so imports from @hotwired/stimulus, @floating-ui/dom, and motion resolve correctly.
  • Added ruby_ui:sync_controller_symlinks task; it creates/repairs symlinks and now aborts on duplicate controller basenames to prevent clobbering.

• Migration

  • For new components: run bin/rails ruby_ui:sync_controller_symlinks, then bin/rails stimulus:manifest:update.
  • No changes needed for existing components; docs now serve the gem controllers directly.

^{Written for commit 64d756a. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 80 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cirdes]

@djalmaaraujo, please take a look on cubic issues!

[djalmaaraujo]

@cirdes done — both cubic findings addressed in 64d756a, and the branch is rebased onto current main (the conflict was stale, resolved clean).

• P2 (docs/lib/tasks/ruby_ui.rake) — valid. The docs controllers directory is flat, so two gem controllers sharing a basename would have the second symlink silently clobber the first. The task now detects collisions up front and aborts listing the offending paths, before touching any symlink. Verified by planting a duplicate tabs_controller.js under a second gem subdirectory.
• P3 (.claude/skills/ruby-ui-stimulus/SKILL.md) — valid, applied the suggestion (rake stimulus:manifest:update).

Re-verified on a clean checkout (fresh pnpm install, no reused node_modules):

• pnpm build — passes, 1.1mb bundle; grepped the output for content.removeAttribute("hidden") (gem accordion source) and computePosition (real @floating-ui/dom), both present, so --preserve-symlinks resolves through the symlinks correctly.
• bin/rails db:test:prepare test (docs) — 75 runs, 107 assertions, 0 failures, 0 errors.
• bundle exec standardrb (docs) — clean.
• bundle exec rake (gem) — 281 runs, 1251 assertions, 0 failures; 402 files, no offenses.
• rake ruby_ui:sync_controller_symlinks — idempotent, all 37 links report ok.

Same caveat as before: still no interactive browser click-through, confidence rests on the bundle-content checks above.