proscenium-phlex 0.6.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 158d488f475dc828ca1a7b76aa570fb3a464caf5e5d95fabf5946dd7c86b7188
-  data.tar.gz: df2cb3239e69fb998c903cbcb1cbd894fcd570e4d5d90646e3d7d56104832852
+  metadata.gz: df6115d20026dc696f5920cb6abd477395b67fd4e75aa2865c689b2da0d8f04c
+  data.tar.gz: 1d6e22163c6821e5c4da3004e4ad1d8e798ebe17bd6a8e407e760c4ef4c3a026
 SHA512:
-  metadata.gz: f00c7dc4260b0174e674c9eb895bd8f6f483cc968d4cc69f4c69ff7cca86006bbb582f8d5aa0422e6dda43914fad42197a9efd7ae4c6db6c6c1dbf95d37f2ba0
-  data.tar.gz: d3d317eef341c2e9a11c98d7ff92425041d1928cfd275ea588fc6a3eb6f2163a1b6307189b74925290815815a761763dd8ab71b0809f8e9cdbb587d51fd47cca
+  metadata.gz: b255e3d2a1d88f06e952b98a83bc2c414f6af365c54262b8171a704db5a3ed4d292eb13af2a9b793510bcc91d5f9da4fbb22ac80dbf2cb403829bcaaf25929a3
+  data.tar.gz: 163ac3ed9355884df2c02cc90904725e19689b6119e5cf7d5382e7d868547706653fb0950225b809bd36fef44bf320a7ec612b05727f949106badd1bc89c6f65

data/.rubocop.yml

@@ -7,7 +7,7 @@ plugins:
   - rubocop-performance
 
 AllCops:
-  TargetRubyVersion: 3.3
+  TargetRubyVersion: 3.4
   NewCops: enable
   SuggestExtensions: false
   Exclude:

data/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## Agent skills
+
+### Issue tracker
+
+Issues tracked in GitHub Issues (joelmoss/proscenium-phlex) via `gh`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default five-role vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: root `CONTEXT.md` + `docs/adr/`. See `docs/agents/domain.md`.

data/Appraisals

@@ -19,3 +19,13 @@ appraise 'phlex2/rails8' do
   gem 'rails', '~> 8.0.1'
   gem 'phlex-rails', '~> 2.3'
 end
+
+appraise 'phlex1/rails81' do
+  gem 'rails', '~> 8.1.0'
+  gem 'phlex-rails', '~> 1.2'
+end
+
+appraise 'phlex2/rails81' do
+  gem 'rails', '~> 8.1.0'
+  gem 'phlex-rails', '~> 2.3'
+end

data/README.md

@@ -2,6 +2,19 @@
 
 [Proscenium](https://proscenium.rocks/) integration for Phlex.
 
+## Requirements
+
+- Ruby >= 3.4
+- [Proscenium](https://github.com/joelmoss/proscenium) ~> 0.26
+- Rails >= 7.2 and < 9.0
+- Phlex Rails >= 1.2 and < 3.0
+
+## Upgrading to 0.7
+
+- Ruby 3.3 is no longer supported. Upgrade to Ruby 3.4 or later.
+- Proscenium 0.26 or later is required. Outside production, CSS module class names now end with the module's path (see [CSS Modules](#css-modules)), so tests that match exact class names need updating.
+- `Proscenium::Phlex::React` has been removed. Remove any `include Proscenium::Phlex::React` from your components.
+
 ## Usage
 
 [Phlex](https://www.phlex.fun/) is a framework for building fast, reusable, testable views in pure Ruby. [Proscenium](https://proscenium.rocks/) works perfectly with [Phlex](https://www.phlex.fun), with support for side-loading, CSS modules, and more.
@@ -27,7 +40,7 @@ class ApplicationLayout < Phlex::HTML
 end
 ```
 
-You can specifically include CCS and JS assets using the `include_stylesheets` and `include_javascripts` helpers, allowing you to control where they are included in the HTML.
+You can specifically include CSS and JS assets using the `include_stylesheets` and `include_javascripts` helpers, allowing you to control where they are included in the HTML.
 
 ### Side-loading
 
@@ -43,9 +56,11 @@ class MyComponent < Phlex::HTML
 end
 ```
 
+Components are not side loaded when `Proscenium.config.side_load` is `false`. Otherwise, a controller's [`sideload_assets`](https://github.com/joelmoss/proscenium?tab=readme-ov-file#side-loading) options apply to the components it renders, just as they do to its views. A Proc given to the controller's `sideload_assets` is evaluated against the controller. A component can also call `sideload_assets` itself, and a Proc given there is evaluated against the component.
+
 ### CSS Modules
 
-[CSS Modules](https://github.com/joelmoss/proscenium?tab=readme-ov-file#css-modules) are fully supported in Phlex classes, with access to the [`css_module` helper](https://github.com/joelmoss/proscenium?tab=readme-ov-file#in-your-views) if you need it. However, there is a better and more seemless way to reference CSS module classes in your Phlex classes.
+[CSS Modules](https://github.com/joelmoss/proscenium?tab=readme-ov-file#css-modules) are fully supported in Phlex classes, with access to the [`css_module` helper](https://github.com/joelmoss/proscenium?tab=readme-ov-file#in-your-views) if you need it. However, there is a better and more seamless way to reference CSS module classes in your Phlex classes.
 
 Within your Phlex classes, any class names that begin with `@` will be treated as a CSS module class.
 
@@ -64,44 +79,64 @@ end
 
 ```css
 /* /app/views/users/show_view.module.css */
-.userName {
+.user_name {
   color: red;
   font-size: 50px;
 }
 ```
 
-In the above `Users::ShowView` Phlex class, the `@user_name` class will be resolved to the `userName` class in the `users/show_view.module.css` file.
+In the above `Users::ShowView` Phlex class, the `@user_name` class will be resolved to the `user_name` class in the `users/show_view.module.css` file. Class names are used as written: `@user_name` does not match a `.userName` class.
 
-The view above will be rendered something like this:
+In production, the view above will be rendered something like this:
 
 ```html
-<h1 class="user_name-ABCD1234"></h1>
+<h1 class="user_name_abcd1234"></h1>
 ```
 
+In development and test, or when `Proscenium.config.debug` is set, the module's path is appended, so you can see where a class comes from: `user_name_abcd1234_app-views-users-show_view-module`.
+
 You can of course continue to reference regular class names in your view, and they will be passed through as is. This will allow you to mix and match CSS modules and regular CSS classes in your views.
 
 ```ruby
 # /app/views/users/show_view.rb
 class Users::ShowView < Phlex::HTML
-  include Proscenium::Phlex::Sideload
+  include Proscenium::Phlex::CssModules
 
   def view_template
-    h1 class: :[@user_name, :title] do
+    h1 class: [:@user_name, :title] do
       @user.name
     end
   end
 end
 ```
 
+In production, this renders:
+
 ```html
-<h1 class="user_name-ABCD1234 title">Joel Moss</h1>
+<h1 class="user_name_abcd1234 title">Joel Moss</h1>
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rails test` to run the tests, or `bundle exec appraisal rails test` to run them against Rails 7.2, 8.0 and 8.1, each with Phlex 1 and Phlex 2. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Releasing
+
+Releases are published to [rubygems.org](https://rubygems.org) by the `release` GitHub Actions workflow, using trusted publishing, so no API key or one-time code is needed.
+
+1. Update the version number in `lib/proscenium/phlex/version.rb`, run `bundle install && bundle exec appraisal install` to update every lockfile, and commit. CI installs gems in frozen mode, so a lockfile left on the old version fails the build.
+2. Push a tag matching the new version, replacing `X.Y.Z`:
+
+   ```sh
+   git tag vX.Y.Z
+   git push origin master vX.Y.Z
+   ```
+
+The workflow checks that the tag matches the version, runs the tests, builds the gem and pushes it. If a run fails partway, re-run it: a version already on RubyGems is skipped.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Don't use `bundle exec rake release`. It pushes the gem from your machine, and the workflow then has nothing to publish.
 
 ## Contributing
 

data/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

data/docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

data/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

data/gemfiles/phlex1_rails7.gemfile

@@ -15,7 +15,7 @@ gem "rubocop-rails", require: false
 gem "rubocop-rake", require: false
 gem "capybara"
 gem "maxitest"
-gem "minitest", "~> 5.0"
+gem "minitest"
 gem "minitest-difftastic"
 gem "minitest-focus"
 gem "minitest-spec-rails"