plutonium 0.52.0 → 0.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3015426fb7d1a742cd436928a9a8e2c24597f391d68657b8f00ed31058cf59c
-  data.tar.gz: 20bf4101ff956923bf01b28ad890bc5000760a5181ab65ac07f83f2bb739b0d7
+  metadata.gz: 1575a79af57aa89f49041cbdb1e31364cea08fb3d541398e095772470a3da6b8
+  data.tar.gz: a3d4dfebbec5836c9557c903393f7deebcfb17b94ca8d61ccb5a1dd1ffbd7aee
 SHA512:
-  metadata.gz: 14b0e28c435b199564a46eae98b84c4273c2783344a3257dcb9adc872002c8e761e058f7f76fbe909b3419facd0e90e1d9ee1a3c8fa5f128189eb1df6e365761
-  data.tar.gz: 19e6dfaf2c2526fcb4cfadba2eb2e09fa294141abb2175f52348f45d050d975aa92b59541d8aa5eb4c14b2bd973f60b45abea9498ea20bc7340529d8e2f96370
+  metadata.gz: 8c6954af1d7e64be809c28e06140b5660f58e94ec254fe2960c4d0b28b615f515df84d107528899d791ab3cc5bf38ac18cf623aa4c00d3a683bf7b963b96bc47
+  data.tar.gz: a5f6a8ea0ad4e9fafc6559aac4b488c131a6c796c58506a49a49e8088dd3408cd04641ab4ffef357b66a373f88bd6c99476eb2d1cd7cb79eaaf2c993c6322cf5

data/.claude/skills/plutonium-resource/SKILL.md

@@ -725,9 +725,10 @@ class PostDefinition < ResourceDefinition
   # nil (default) = auto (hidden for singular, shown for plural)
   submit_and_continue false
 
-  # How :new / :edit render
+  # How :new / :edit + interactive actions render
   #   :slideover (default), :centered, or false (full pages)
-  modal :centered
+  #   size: :sm / :md (default) / :lg / :xl / :auto / :full
+  modal :centered, size: :lg
 
   # Titles
   index_page_title "All Posts"
@@ -757,7 +758,7 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-`modal:` only affects the framework `:new` / `:edit` actions. Custom actions have their own per-action `modal:` option (default `:centered`).
+`modal:` is the default for framework `:new` / `:edit` *and* every interactive action on this definition. Per-action `modal:` / `size:` overrides win.
 
 ## Metadata Panel (show page)
 
@@ -983,7 +984,8 @@ action :name,
   confirmation: "Are you sure?",
   turbo_frame: "_top",
   route_options: {action: :foo},
-  modal: :slideover                 # :centered (default) or :slideover
+  modal: :slideover,                # :slideover / :centered — overrides definition's modal mode
+  size:  :lg                        # :sm / :md / :lg / :xl / :auto / :full — overrides definition's modal size
 ```
 
 `Action#with(...)` — actions are frozen value objects; clone with overrides:

data/.claude/skills/plutonium-tenancy/SKILL.md

@@ -15,7 +15,7 @@ Cross-references back to [[plutonium-resource]] (models, definitions) and [[plut
 
 ## 🚨 Critical (read first)
 
-- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity triggers `verify_default_relation_scope_applied!`. Make sure `default_relation_scope(relation)` is called somewhere in the chain — explicitly here, or via `super` to a parent policy (e.g., a package base) that calls it.
+- **Never bypass `default_relation_scope`.** Overriding `relation_scope` with `where(organization: ...)` or manual joins to the entity triggers `verify_default_relation_scope_applied!`. Make sure the chain ends up calling `default_relation_scope(relation)` — explicitly, or via `super(relation)` (the framework base calls it).
 - **Always declare an association path from model to entity.** Direct `belongs_to`, `has_one :through`, or a custom `associated_with_<entity>` scope. If `associated_with` can't resolve, Plutonium raises. Fix the **model**, not the policy.
 - **Parent scoping beats entity scoping.** When a parent is present (nested resource), `default_relation_scope` scopes via the parent, NOT via `entity_scope`. Don't double-scope.
 - **One level of nesting only.** Grandparent → parent → child nested routes are NOT supported. Use top-level routes for deeper relationships.
@@ -170,7 +170,12 @@ relation_scope { |r| r.joins(:project).where(projects: {organization_id: current
 relation_scope { |r| r.where(published: true) }
 ```
 
-**Prefer calling `default_relation_scope(relation)` explicitly** instead of relying on `super`. `super` works when you're extending a parent policy (e.g., a package-level base) that itself calls `default_relation_scope` — but it's brittle against `Plutonium::Resource::Policy` directly because `super`'s semantics depend on how ActionPolicy's DSL registered the scope. The runtime verification checks `default_relation_scope` was hit somewhere — not that you wrote it in this class.
+**`default_relation_scope(relation)` must end up being called somewhere in the chain** — runtime verification just checks it was hit, not that you wrote it in this class. Both work:
+
+- `default_relation_scope(relation).where(...)` — explicit, always safe
+- `super(relation).where(...)` — `Plutonium::Resource::Policy`'s `relation_scope` block calls `default_relation_scope`, so chaining through `super` picks it up
+
+Pick the one that reads better for the situation.
 
 ### Intentionally skipping
 
@@ -199,7 +204,7 @@ module AdminPortal
 end
 ```
 
-Routes become `/organizations/:organization_id/posts`. Portal extracts `params[:organization_id]` and loads the entity automatically.
+Routes become `/<mount>/:organization_scoped/posts` (resolving to `/<mount>/42/posts` at request time — the entity id is the first path segment after the mount). Portal extracts `params[:organization_scoped]` and loads the entity automatically. The `_scoped` suffix on the param name avoids colliding with `params[:organization]` from a `belongs_to :organization` on child models.
 
 ### Custom strategy (subdomain, session, etc.)
 
@@ -235,7 +240,7 @@ entity_scope
 
 - **Multiple associations to the same entity class.** E.g. `Match belongs_to :home_team, :away_team` both pointing at `Team`. Plutonium raises — override `scoped_entity_association` on the controller to pick one (`def scoped_entity_association = :home_team`).
 - **`param_key` differs from association name.** Fine — Plutonium matches by **class**, not param key. `scope_to_entity Competition::Team, param_key: :team` works with `belongs_to :competition_team`.
-- **Default `param_key` includes `_scoped` suffix.** `scope_to_entity Organization` produces routes like `/organization_scoped/:organization_scoped_id/posts` to avoid colliding with a `belongs_to :organization` on child models. Pass `param_key:` (and optionally `route_key:`) to override for cleaner URLs.
+- **Default `param_key` includes `_scoped` suffix.** `scope_to_entity Organization` reads `params[:organization_scoped]` (not `params[:organization]`) so it doesn't collide with `params[:organization]` from a `belongs_to :organization` on child models. The URL itself is unchanged — the entity id is just the first path segment after the mount (`/<mount>/42/posts`). Pass `param_key:` only if you want a different param name in your controllers.
 - **Forgetting compound uniqueness.** `validates :code, uniqueness: true` leaks across tenants. Use `uniqueness: {scope: :organization_id}`.
 - **"Temporary" `where` bypass for debugging.** Use `skip_default_relation_scope!` explicitly. Never leave a `where` bypass in code.
 

data/.claude/skills/plutonium-ui/SKILL.md

@@ -390,6 +390,7 @@ Inside any `Plutonium::UI::Component::Base` (or any page/form/display):
 PageHeader(title: "Dashboard", description: "...", actions: [...])
 Panel(class: "mt-4") { p { "Content" } }
 Block { TabList(items: tabs) }
+Avatar(user)                      # profile image: src → Navii fallback → icon
 EmptyCard("No items found")
 ActionButton(action, url: "/posts/new")
 DynaFrameHost(src: "/some/path", loading: :lazy)
@@ -401,6 +402,28 @@ TablePagination(pagy)
 Breadcrumbs()
 ```
 
+## Avatar
+
+`Avatar(subject = nil, src: nil, size: :md, alt: nil, **attrs)` — profile image with a deterministic [Navii](https://navii.dev) fallback. Registered in the kit.
+
+```ruby
+Avatar(user)                      # Navii fallback seeded from the record
+Avatar(user, src: :avatar)        # user.avatar if present, else Navii fallback
+Avatar(user, src: user.avatar)    # pass the attachment/uploader/URL directly
+Avatar("acme-team")               # String subject = deterministic seed
+Avatar("https://.../p.png")       # URL-shaped subject is shown as the image
+Avatar(src: avatar_url)           # bare image, no subject/fallback
+```
+
+- **subject** (positional): record → PII-free hashed seed + default `alt` (display name); String → seed. A URL-shaped String (`http(s)://…` or `/…`) is routed to `src` (shown as the image), not used as a seed.
+- **src**: a Symbol is sent to the subject (`:avatar` → `subject.avatar`, a **contract** — raises if absent); otherwise an ActiveStorage attachment, active_shrine/Shrine uploader, or URL string. ActiveStorage resolves via `helpers.url_for`; everything else via its own `#url`.
+- **size**: `:xs 24 / :sm 32 / :md 40 / :lg 48 / :xl 64`, or a raw Integer.
+- **Privacy**: the value sent to Navii is **always** a SHA256 hash — no ids, emails, or seed strings leave the app. Deterministic per subject.
+- **Resolution order**: resolved `src` → Navii (from subject) → generic user icon.
+- **Config**: `config.navii_host_url` (default `https://api.navii.dev`); the component appends `/avatar/:seed`.
+
+🚨 Ejected shells: `Avatar` only shows a Navii avatar when `NavUser` is passed `record:`. The gem's `_resource_header.html.erb` passes `record: (current_user if current_user.respond_to?(:id))`; portals that **ejected** the header before this must re-eject (`rails g pu:eject:shell --dest=<portal>`) or add the `record:` line, otherwise they keep the icon fallback. Pass a record only — a String `current_user` (e.g. a guest) would otherwise be seeded as a literal identity.
+
 ## Custom Phlex components
 
 ```ruby
@@ -450,17 +473,18 @@ All pages inherit this. Modals and frame navigation work without special handlin
 
 # Part 5 — Modals, Slideovers, Tabs
 
-## Modal/slideover for `:new` / `:edit`
+## Modal/slideover for `:new` / `:edit` + interactive actions
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  modal :slideover    # default — slide-in panel from the right
-  # modal :centered   # centered dialog
-  # modal false       # full standalone page
+  modal :slideover               # default — slide-in panel from the right
+  # modal :centered              # centered dialog
+  # modal :centered, size: :lg   # centered, wider container
+  # modal false                  # full standalone page
 end
 ```
 
-Custom interactive actions render in their own dialog with their own per-action `modal:` option (`:centered` default, or `:slideover`). See [[plutonium-resource]] › Action Options.
+Drives both framework `:new` / `:edit` and every interactive action on the definition. `size:` accepts `:sm`, `:md` (default), `:lg`, `:xl`, `:auto` (hugs content), or `:full`. Per-action `modal:` / `size:` overrides win. See [[plutonium-resource]] › Action Options.
 
 ## Tabs on the show page
 

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.53.0] - 2026-05-31
+
+### 🚀 Features
+
+- *(ui)* Add Avatar component with Navii fallback (#59)
+
+### 🐛 Bug Fixes
+
+- *(docs)* Correct broken cross-page anchors in guides
+- *(docs)* Retract incorrect "never super" guidance in relation_scope
+- *(docs)* Correct scoped-URL shape in multi-tenancy docs
+- *(rodauth)* Match change_password_notify mailer template name
+
+### 🚜 Refactor
+
+- *(helpers)* Remove dead view helpers superseded by Phlex components
 ## [0.52.0] - 2026-05-21
 
 ### 🐛 Bug Fixes