lcp 0.1.0

data/lib/lcp_ruby/metadata/menu_item.rb

@@ -0,0 +1,792 @@
+require "set"
+
+module LcpRuby
+  module Metadata
+    class MenuItem
+      TYPES = %i[view_group link group separator sidebar_toggle].freeze
+      POSITION_BOTTOM = "bottom"
+      POSITION_RIGHT = "right"
+      POSITION_TOP = "top"
+      POSITION_LEFT = "left"
+      POSITIONS = [ POSITION_BOTTOM, POSITION_RIGHT, POSITION_TOP, POSITION_LEFT ].freeze
+      MAX_NESTING_DEPTH = 2
+
+      # Built-in CRUD actions implicit on every presenter. Used by
+      # `meets_visibility?` to pick `can?(action)` (built-in) vs
+      # `can_execute_action?(action)` (custom) for permission gating
+      # of `presenter:` items, and by `MenuItemResolver` to pick the
+      # correct route helper.
+      BUILTIN_ACTIONS = %w[show edit new destroy index].freeze
+
+      attr_reader   :type, :view_group_name,
+                    :label, :label_key, :icon, :url, :children,
+                    :visible_when, :disable_when, :position, :badge,
+                    :aria_label, :aria_label_key,
+                    :http_method, :presenter_slug, :alias_name, :action_name, :defaults,
+                    :render_partial, :render_panel_partial, :widget,
+                    :provider_name, :provider_options, :panel_provider_name,
+                    :label_source_loc, :aria_label_source_loc,
+                    :responsive_priority, :pin, :hide_below, :show_below,
+                    :collapse_label_below
+
+      def initialize(type:, view_group_name: nil, label: nil, label_key: nil, icon: nil,
+                     url: nil, children: [], visible_when: {}, disable_when: {},
+                     position: nil, badge: nil, aria_label: nil, aria_label_key: nil,
+                     http_method: nil, presenter_slug: nil, alias_name: nil, action_name: nil,
+                     defaults: nil,
+                     render_partial: nil, render_panel_partial: nil, widget: nil,
+                     provider_name: nil, provider_options: nil, panel_provider_name: nil,
+                     label_source_loc: nil, aria_label_source_loc: nil,
+                     responsive_priority: nil, pin: nil, hide_below: nil,
+                     show_below: nil, collapse_label_below: nil)
+        @type = type
+        @view_group_name = view_group_name
+        # `label` may be a String, `false` (explicit opt-out from any
+        # resolved fallback — relevant for view_group items where the
+        # presenter would otherwise supply a label), or nil/omitted.
+        @label = label
+        @label_key = label_key
+        @icon = icon
+        @url = url
+        @children = children
+        @visible_when = HashUtils.stringify_deep(visible_when || {})
+        @disable_when = HashUtils.stringify_deep(disable_when || {})
+        @position = position
+        @badge = badge.is_a?(Hash) ? HashUtils.stringify_deep(badge) : nil
+        @aria_label = aria_label
+        @aria_label_key = aria_label_key
+        # `method:` (YAML key) is stored as `http_method` to avoid
+        # shadowing `Object#method(name)`. Normalized to a lowercase
+        # symbol (`:get`, `:post`, `:put`, `:patch`, `:delete`); `nil`
+        # means "unspecified" (renderer picks a default — `:get` for
+        # url:/view_group:/presenter+show, etc.).
+        @http_method = http_method&.to_s&.downcase&.to_sym
+        @presenter_slug = presenter_slug&.to_s
+        @alias_name = alias_name&.to_s
+        @action_name = action_name&.to_s
+        @defaults = defaults.is_a?(Hash) ? HashUtils.stringify_deep(defaults) : nil
+        # PR #2b modifiers: `render:` partial path, `render_panel:`
+        # partial path, `widget:` flag, `provider:` and `panel_provider:`
+        # service names, and the shared `options:` hash both providers
+        # consume (mutex with each other so no key collision).
+        @render_partial = render_partial&.to_s
+        @render_panel_partial = render_panel_partial&.to_s
+        @widget = widget == true
+        @provider_name = provider_name&.to_s
+        @provider_options = provider_options.is_a?(Hash) ? HashUtils.stringify_deep(provider_options) : {}
+        @panel_provider_name = panel_provider_name&.to_s
+        # i18n_check Phase 3a — populated when a menu DSL builder is
+        # added (none exists today; menu is YAML-only). YAML-loaded
+        # menus carry nil and Pass 3 covers them.
+        @label_source_loc = label_source_loc
+        @aria_label_source_loc = aria_label_source_loc
+
+        # Responsive per-item keys (all optional; nil = no effect at
+        # runtime). Type coercion only — depth/layout-aware warnings
+        # live in ConfigurationValidator.
+        @responsive_priority = responsive_priority&.to_i
+        @pin = pin&.to_s
+        @hide_below = hide_below&.to_i
+        @show_below = show_below&.to_i
+        @collapse_label_below = collapse_label_below&.to_i
+
+        validate!
+      end
+
+      # Returns a copy of this item with selected attributes overridden.
+      # Used by `LayoutHelper#visible_menu_items` to rebuild a `:group`
+      # item with filtered children without re-enumerating every
+      # attribute by hand.
+      def with(**overrides)
+        self.class.new(**to_kwargs.merge(overrides))
+      end
+
+      # Build a MenuItem from a parsed YAML hash.
+      # Detection priority: separator > view_group > children > url|presenter
+      # Existing call style preserved: `from_hash("view_group" => "x", ...)`
+      # works because the method takes a single positional Hash. Any
+      # incoming `:type` / `"type"` key is silently ignored — type is
+      # always re-derived from the destination keys present (so merging
+      # `to_kwargs` with provider returns works without colliding on type).
+      def self.from_hash(hash)
+        build_from_hash(hash, 0)
+      end
+
+      # Variant that threads an explicit depth budget through static
+      # `:children:` recursion AND provider expansion (PR #2b). Public
+      # so `LayoutHelper#expand_provider` can pass the running depth
+      # without re-implementing the construction logic. The leading
+      # positional `hash` keeps Ruby 3 from misinterpreting string-key
+      # hash literals as kwargs.
+      def self.from_hash_at_depth(hash, depth)
+        build_from_hash(hash, depth)
+      end
+
+      # Destination keys — exactly one must appear on every non-widget item.
+      # `widget:` (PR #2b) accepts `provider:` only; that mutex is layered
+      # on top in PR #2b's MenuItem extensions.
+      DESTINATION_KEYS = %w[url presenter view_group provider children separator sidebar_toggle].freeze
+
+      # Keys allowed on a `:separator` item. Anything else is a configurator
+      # footgun — a separator with a `label:` is invisible (no element renders
+      # it); a separator with `disable_when:` makes no sense (nothing to
+      # disable). Validator rejects at boot.
+      SEPARATOR_ALLOWED_KEYS = %w[separator position visible_when].freeze
+
+      # Keys allowed on a `:sidebar_toggle` item. Platform-owned UI chrome
+      # has no destination, no children, and no responsive overflow
+      # semantics (it's implicitly `pin: always` at render time). The
+      # responsive keys (responsive_priority/pin/hide_below/show_below/
+      # collapse_label_below) would be no-ops here, so reject them at
+      # parse time rather than letting them silently slide.
+      SIDEBAR_TOGGLE_ALLOWED_KEYS = %w[
+        sidebar_toggle label label_key icon aria_label aria_label_key
+        position visible_when
+      ].freeze
+
+      def self.build_from_hash(hash, depth)
+        hash = HashUtils.stringify_deep(hash)
+
+        # Destination mutex (B1, simple form): exactly one of the
+        # destination keys may be present. (PR #2a doesn't parse
+        # `provider:` — schema rejects unknown keys via
+        # `additionalProperties: false` — but the mutex check covers
+        # `provider:` for forward-compat with PR #2b.)
+        present_destinations = DESTINATION_KEYS.select { |k| hash[k] }
+        if present_destinations.size > 1
+          raise MetadataError,
+                "menu item has more than one destination key: " \
+                "#{present_destinations.join(', ')} — pick one"
+        end
+
+        if hash["separator"]
+          extra = hash.keys - SEPARATOR_ALLOWED_KEYS
+          unless extra.empty?
+            raise MetadataError,
+                  "separator menu item only allows #{SEPARATOR_ALLOWED_KEYS.join(', ')} " \
+                  "(got extra key(s): #{extra.join(', ')})"
+          end
+          return new(type: :separator, position: hash["position"], visible_when: hash["visible_when"] || {})
+        end
+
+        # sidebar_toggle: a platform-owned UI chrome marker. Renders a
+        # button that opens the sidebar's off-canvas drawer. Carries no
+        # destination — destination mutex above already enforces exclusivity.
+        if hash["sidebar_toggle"] == true
+          extra = hash.keys - SIDEBAR_TOGGLE_ALLOWED_KEYS
+          unless extra.empty?
+            raise MetadataError,
+                  "sidebar_toggle menu item only allows #{SIDEBAR_TOGGLE_ALLOWED_KEYS.join(', ')} " \
+                  "(got extra key(s): #{extra.join(', ')}). " \
+                  "Note: pin/responsive_priority/hide_below/show_below have no effect on " \
+                  "platform chrome (sidebar_toggle is implicitly pin: always)."
+          end
+          return new(
+            type: :sidebar_toggle,
+            label: hash["label"],
+            label_key: hash["label_key"],
+            icon: hash["icon"] || "menu",
+            aria_label: hash["aria_label"],
+            aria_label_key: hash["aria_label_key"] || "lcp_ruby.nav.open_menu",
+            position: hash["position"],
+            visible_when: hash["visible_when"] || {}
+          )
+        end
+
+        # method: is only valid on link items (presenter: + url:). Block
+        # on view_group: (always GET for index) and group: (trigger always
+        # opens a panel).
+        if hash["method"] && (hash["view_group"] || hash["children"])
+          dest = hash["view_group"] ? "view_group:" : "children: (group)"
+          raise MetadataError,
+                "method: is only valid on link items — got method: " \
+                "#{hash["method"].inspect} on #{dest}"
+        end
+
+        # Empty-string rejection for presenter/alias/action (configurator
+        # typos, likely deletion gone wrong).
+        %w[presenter alias action provider panel_provider render render_panel].each do |k|
+          next unless hash.key?(k)
+          v = hash[k]
+          # Skip the widget:/separator: boolean keys — they're handled
+          # separately. We only care about string-typed keys here.
+          next unless v.is_a?(String) || v.nil?
+          if v.nil? || v.strip.empty?
+            raise MetadataError, "#{k}: must not be empty"
+          end
+        end
+
+        # widget: true mutex — drops the wrapper, so destination URLs
+        # have nowhere to attach. provider: is the one compatible
+        # destination (provider returns widget data; render: produces
+        # the markup).
+        if hash["widget"] == true
+          conflicting = %w[url presenter view_group children separator].select { |k| hash[k] }
+          unless conflicting.empty?
+            raise MetadataError,
+                  "widget: true is incompatible with #{conflicting.join(', ')} — " \
+                  "widgets drop the wrapper, so a destination URL has nowhere to attach"
+          end
+          if hash["render"].nil? || (hash["render"].is_a?(String) && hash["render"].strip.empty?)
+            raise MetadataError,
+                  "widget: true requires render: — without it, the widget <li> " \
+                  "would render empty"
+          end
+        end
+
+        # render_panel: requires children: (may be []). render_panel: is a
+        # modifier on :group items; :group is expressed by the children:
+        # key. Without children:, render_panel: has no `:group` to attach
+        # to.
+        if hash["render_panel"] && !hash.key?("children")
+          raise MetadataError,
+                "render_panel: requires children: (which may be [] when paired " \
+                "with panel_provider:) — it customizes the dropdown panel of a " \
+                ":group item"
+        end
+
+        # panel_provider: rules: requires render_panel: AND children:; mutex
+        # with provider: (provider replaces the whole item; panel_provider
+        # feeds the panel of a render_panel: group — pick one).
+        if hash["panel_provider"]
+          unless hash["render_panel"]
+            raise MetadataError,
+                  "panel_provider: requires render_panel: — without a custom " \
+                  "panel partial, panel_provider has nowhere to render its items"
+          end
+          unless hash.key?("children")
+            raise MetadataError,
+                  "panel_provider: requires children: (which may be []) — " \
+                  "panel_provider modifies a :group, expressed by the children: key"
+          end
+          if hash["provider"]
+            raise MetadataError,
+                  "panel_provider: and provider: on the same item — pick one " \
+                  "(provider: replaces the whole item; panel_provider: feeds " \
+                  "the panel of a render_panel: group)"
+          end
+        end
+
+        # Empty `children: []` requires render_panel: — otherwise the group
+        # has no content (renders a permanently-empty dropdown).
+        if hash["children"].is_a?(Array) && hash["children"].empty? && hash["render_panel"].nil?
+          raise MetadataError,
+                "empty children: [] requires render_panel: — a group with no " \
+                "children and no custom panel renderer would render an empty " \
+                "dropdown (use visible_when: instead, or remove the item)"
+        end
+
+        # Shared optional keys for the non-separator branches
+        # (view_group, group, link). Centralising them here keeps the
+        # construction sites consistent — adding a new optional key is a
+        # single edit instead of three.
+        common = {
+          label: hash["label"],
+          label_key: hash["label_key"],
+          icon: hash["icon"],
+          aria_label: hash["aria_label"],
+          aria_label_key: hash["aria_label_key"],
+          visible_when: hash["visible_when"] || {},
+          disable_when: hash["disable_when"] || {},
+          position: hash["position"],
+          badge: hash["badge"],
+          render_partial: hash["render"],
+          render_panel_partial: hash["render_panel"],
+          panel_provider_name: hash["panel_provider"],
+          provider_options: hash["options"],
+          label_source_loc: hash["_label_source_loc"],
+          aria_label_source_loc: hash["_aria_label_source_loc"],
+          responsive_priority: hash["responsive_priority"],
+          pin: hash["pin"],
+          hide_below: hash["hide_below"],
+          show_below: hash["show_below"],
+          collapse_label_below: hash["collapse_label_below"]
+        }
+
+        if hash["view_group"]
+          return new(type: :view_group, view_group_name: hash["view_group"].to_s, **common)
+        end
+
+        if hash["children"]
+          if depth >= MAX_NESTING_DEPTH
+            raise MetadataError, "Menu nesting too deep at '#{hash["label"]}': maximum #{MAX_NESTING_DEPTH} levels allowed"
+          end
+          children = hash["children"].map { |child| build_from_hash(child, depth + 1) }
+          return new(type: :group, children: children, **common)
+        end
+
+        # `:link`-typed catch-all for url-bearing items + presenter:
+        # resolution + provider: computed items + widget: items (whose
+        # render: partial drives the markup, no destination URL needed).
+        if hash["url"] || hash["presenter"] || hash["provider"] || hash["widget"]
+          return new(
+            type: :link,
+            url: hash["url"],
+            presenter_slug: hash["presenter"],
+            alias_name: hash["alias"],
+            action_name: hash["action"],
+            http_method: hash["method"],
+            defaults: hash["defaults"],
+            widget: hash["widget"],
+            provider_name: hash["provider"],
+            **common
+          )
+        end
+
+        raise MetadataError,
+              "Menu item must have one of: separator, view_group, children, url, presenter, provider, or widget"
+      end
+      private_class_method :build_from_hash
+
+      # Resolve label with i18n support.
+      # Priority: explicit `label: false` short-circuit > label_key >
+      # explicit label > view_group's primary presenter resolved_label >
+      # `presenter:` referenced presenter resolved_label.
+      # Returns nil when the item should render no visible label —
+      # icon-only items, separator items, or items whose underlying
+      # presenter exposes no resolvable label.
+      def resolved_label(loader)
+        return nil if @label == false
+
+        if @label_key.present?
+          fallback = @label.is_a?(String) && @label.present? ? @label : @label_key.split(".").last.humanize
+          return I18n.t(@label_key, default: fallback)
+        end
+
+        if @label.is_a?(String) && @label.present?
+          result = I18n.t("lcp_ruby.menu.#{@label.parameterize(separator: '_')}", default: nil)
+          return result || @label
+        end
+
+        # No `view_group_name.humanize` fallback — a view_group whose
+        # presenter has no resolvable label is a misconfiguration that
+        # the validator surfaces, not something we silently humanize.
+        return primary_presenter(loader)&.resolved_label if view_group?
+
+        # `presenter:` items inherit the referenced presenter's resolved
+        # label as the fallback — keeps `validate_resolved_content!`
+        # happy without forcing the configurator to repeat the label.
+        if presenter_slug.present?
+          return loader.presenter_definitions[presenter_slug]&.resolved_label
+        end
+
+        nil
+      end
+
+      # Resolve the accessible name for the link/button. Required when
+      # no visible label is rendered (icon-only items). Mirrors
+      # `resolved_label` priority: explicit aria_label_key > literal
+      # aria_label with i18n auto-lookup. Namespace
+      # `lcp_ruby.menu.aria.<slug>` keeps it separate from labels so
+      # the same literal used in both roles does not collide.
+      def resolved_aria_label(_loader = nil)
+        if @aria_label_key.present?
+          fallback = @aria_label.is_a?(String) && @aria_label.present? ? @aria_label : @aria_label_key.split(".").last.humanize
+          return I18n.t(@aria_label_key, default: fallback)
+        end
+
+        return nil unless @aria_label.is_a?(String) && @aria_label.present?
+
+        I18n.t("lcp_ruby.menu.aria.#{@aria_label.parameterize(separator: '_')}", default: nil) || @aria_label
+      end
+
+      # Resolve icon from view group's primary presenter when not explicitly set
+      def resolved_icon(loader)
+        return @icon if @icon.present?
+        return nil unless view_group?
+
+        presenter = primary_presenter(loader)
+        presenter&.icon
+      end
+
+      # Resolve slug from view group's primary page
+      def resolved_slug(loader)
+        return nil unless view_group?
+
+        vg = loader.view_group_definitions[view_group_name]
+        return nil unless vg
+
+        page = loader.page_definitions[vg.primary_page]
+        page&.slug
+      end
+
+      # Recursively check if this item or any descendant contains the given slug
+      def contains_slug?(slug, loader)
+        if view_group?
+          vg = loader.view_group_definitions[view_group_name]
+          return false unless vg
+
+          all_slugs = vg.page_names.filter_map do |name|
+            loader.page_definitions[name]&.slug
+          end
+          return true if all_slugs.include?(slug)
+        end
+
+        children.any? { |child| child.contains_slug?(slug, loader) }
+      end
+
+      # Menu items evaluate visibility from two stacks: the `visible_when:`
+      # condition tree (record-free; supports service: and compound
+      # all/any/not — `field:`/`collection:` are rejected by the
+      # validator) AND, for `presenter:` items, the same permission gate
+      # the presenter toolbar runs (`can_access_presenter?` plus
+      # `can?(action)` for built-in CRUD or `can_execute_action?` for
+      # custom actions).
+      #
+      # The optional `helper` arg lets the layout helper share its
+      # per-render `@permission_cache` so N siblings with the same
+      # presenter pay the evaluator construction cost once. When
+      # `helper` is nil (specs and any non-helper context) the method
+      # falls back to constructing a fresh evaluator per call —
+      # functionally identical, just slower.
+      def meets_visibility?(user, helper = nil)
+        return false unless meets_condition_visibility?(user)
+        return true unless presenter_slug.present?
+        meets_presenter_permission?(user, helper)
+      end
+
+      # Mirror of `meets_visibility?` but for `disable_when:`. Returns
+      # true when the item should render in its enabled (clickable)
+      # state. Returns false when `disable_when:` evaluates true →
+      # rendering applies `aria-disabled` / `<button disabled>` plus
+      # the `lcp-menu-item--disabled` CSS class.
+      #
+      # On condition errors: dev/test re-raises, production records and
+      # returns true (item enabled). The "enabled by default on error"
+      # bias mirrors today's failure-modes table — disable_when is a UI
+      # affordance, not a security boundary, so its failure should not
+      # silently block users from a working endpoint.
+      def meets_enabled?(user, _helper = nil)
+        return true if disable_when.blank?
+
+        !LcpRuby::ConditionEvaluator.evaluate_any(
+          nil,
+          disable_when,
+          context: { current_user: user }
+        )
+      rescue LcpRuby::ConditionError => e
+        raise unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+        LcpRuby.record_error(e, subsystem: "menu_disable", item: label || view_group_name || url)
+        true
+      end
+
+      private
+
+      def meets_condition_visibility?(user)
+        return true if visible_when.blank?
+
+        LcpRuby::ConditionEvaluator.evaluate_any(
+          nil,
+          visible_when,
+          context: { current_user: user }
+        )
+      rescue LcpRuby::ConditionError => e
+        raise unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+        LcpRuby.record_error(e, subsystem: "menu_visibility", item: label || view_group_name || url)
+        false
+      end
+
+      def meets_presenter_permission?(user, helper)
+        presenter_def = LcpRuby.loader.presenter_definitions[presenter_slug.to_s]
+        # Validator surfaces unknown slugs at boot. If we somehow get here
+        # with an unresolvable slug (test bypass), default to visible —
+        # the URL resolution will null out and the wrapper just won't
+        # render a path.
+        return true unless presenter_def
+
+        evaluator =
+          if helper
+            helper.permission_evaluator_for(presenter_def, user)
+          else
+            # Singular accessor: handles _default fallback + STI parent walk.
+            LcpRuby::Authorization::PermissionEvaluator.new(
+              LcpRuby.loader.permission_definition(presenter_def.model),
+              user,
+              presenter_def.model
+            )
+          end
+
+        return false unless evaluator.can_access_presenter?(presenter_slug.to_s)
+        return true unless action_name.present?
+
+        if BUILTIN_ACTIONS.include?(action_name.to_s)
+          evaluator.can?(action_name.to_s)
+        else
+          evaluator.can_execute_action?(action_name.to_s)
+        end
+      end
+
+      public
+
+      def badge_provider
+        badge&.dig("provider")
+      end
+
+      def has_badge?
+        badge_provider.present?
+      end
+
+      def badge_form
+        if badge&.dig("renderer")
+          :renderer
+        elsif badge&.dig("partial")
+          :partial
+        elsif badge&.dig("template")
+          :template
+        end
+      end
+
+      def badge_renderer
+        badge&.dig("renderer")
+      end
+
+      def badge_partial
+        badge&.dig("partial")
+      end
+
+      def badge_template
+        badge&.dig("template")
+      end
+
+      def badge_options
+        badge&.dig("options") || {}
+      end
+
+      def bottom?
+        position.to_s == POSITION_BOTTOM
+      end
+
+      def right?
+        position.to_s == POSITION_RIGHT
+      end
+
+      # Forward-compat predicates for `position: top` / `position: left`.
+      # Reserved for future sidebar alignments — no consumer paths exist
+      # today, so these always return false unless the YAML opts in.
+      def top?
+        position.to_s == POSITION_TOP
+      end
+
+      def left?
+        position.to_s == POSITION_LEFT
+      end
+
+      def view_group?
+        type == :view_group
+      end
+
+      def link?
+        type == :link
+      end
+
+      def group?
+        type == :group
+      end
+
+      def separator?
+        type == :separator
+      end
+
+      def sidebar_toggle?
+        type == :sidebar_toggle
+      end
+
+      # Loader-aware boot-time validation. Called by
+      # `ConfigurationValidator#validate_menu_items` after the loader is
+      # fully populated so view_group fallbacks resolve. Raises with a
+      # descriptor that points at the offending entry.
+      def validate_resolved_content!(loader)
+        return if separator?
+        # Platform-owned UI chrome — no destination, no privilege
+        # escalation surface, stable aria_label.
+        return if sidebar_toggle?
+        # widget: items drop the wrapper entirely — the render: partial
+        # owns all visible content + accessibility semantics. The
+        # validator can't introspect the partial's HTML.
+        return if widget?
+        # provider: items are computed at render time — the provider
+        # supplies label/icon/url in its return hash. Static YAML
+        # content is optional (and usually empty); the validator
+        # cannot introspect provider returns at boot.
+        return if provider_name.present?
+
+        content = visible_content(loader)
+
+        # render: items provide visible content via the renderer
+        # partial; label/icon are not required. aria_label/aria_label_key
+        # is still strongly recommended (the renderer's HTML may not
+        # include accessible text); enforce when neither label nor
+        # aria_label is set.
+        if content.empty? && render_partial.blank?
+          raise MetadataError, "Menu item #{descriptor} has no visible content (label or icon)"
+        end
+
+        # Items with no visible label (icon-only OR render: producing
+        # opaque HTML) need an explicit aria_label/aria_label_key. We
+        # cannot introspect a render: partial's accessible text, so we
+        # require the aria attribute regardless when no YAML label resolves.
+        if !content.include?(:label) && @aria_label.blank? && @aria_label_key.blank?
+          raise MetadataError, "Icon-only menu item #{descriptor} requires `aria_label` or `aria_label_key`"
+        end
+      end
+
+      # Snapshot of the keyword arguments needed to reconstruct this item
+      # via `MenuItem.new(**kwargs)`. Powers `#with` and keeps the
+      # rebuild path in `LayoutHelper#visible_menu_items` from drifting
+      # away from `initialize` whenever a new optional key is added.
+      # Public so provider expansion (PR #2b) can reconstruct items
+      # via `to_kwargs.merge(provider_returned_keys)`.
+      def to_kwargs
+        {
+          type: type,
+          view_group_name: view_group_name,
+          label: label,
+          label_key: label_key,
+          icon: icon,
+          url: url,
+          children: children,
+          visible_when: visible_when,
+          disable_when: disable_when,
+          position: position,
+          badge: badge,
+          aria_label: aria_label,
+          aria_label_key: aria_label_key,
+          http_method: http_method,
+          presenter_slug: presenter_slug,
+          alias_name: alias_name,
+          action_name: action_name,
+          defaults: defaults,
+          render_partial: render_partial,
+          render_panel_partial: render_panel_partial,
+          widget: widget,
+          provider_name: provider_name,
+          provider_options: provider_options,
+          panel_provider_name: panel_provider_name,
+          label_source_loc: label_source_loc,
+          aria_label_source_loc: aria_label_source_loc,
+          responsive_priority: responsive_priority,
+          pin: pin,
+          hide_below: hide_below,
+          show_below: show_below,
+          collapse_label_below: collapse_label_below
+        }
+      end
+
+      # `<namespace>/menu_renderers/<name>` — Rails partial path for
+      # the trigger renderer. Returns nil when `render:` is unset so
+      # callers can guard with `if render_partial.present?`.
+      def render_partial_path
+        return nil if render_partial.blank?
+        ns, name = render_partial.split("/", 2)
+        return nil if name.blank?
+        "#{ns}/menu_renderers/#{name}"
+      end
+
+      # `<namespace>/menu_renderers/<name>` — Rails partial path for
+      # the panel renderer. Same naming convention as
+      # `render_partial_path`; the role distinguishing `render:` from
+      # `render_panel:` lives at the YAML key level.
+      def render_panel_partial_path
+        return nil if render_panel_partial.blank?
+        ns, name = render_panel_partial.split("/", 2)
+        return nil if name.blank?
+        "#{ns}/menu_renderers/#{name}"
+      end
+
+      # Predicate sugar — clearer at call sites than `widget == true`.
+      def widget?
+        @widget == true
+      end
+
+      private
+
+      def primary_presenter(loader)
+        vg = loader.view_group_definitions[view_group_name]
+        return nil unless vg
+
+        page = loader.page_definitions[vg.primary_page]
+        return nil unless page
+
+        loader.presenter_definitions[page.main_presenter_name]
+      end
+
+      # Per-instance structural validation — runs at construction time
+      # without loader access. Catches misconfigurations expressible
+      # purely from the YAML/DSL keys on this item. Content-driven rules
+      # (label or icon must resolve to *something*; aria_label required
+      # for icon-only items) need the loader to walk presenter fallbacks
+      # and live in `validate_resolved_content!`.
+      def validate!
+        unless TYPES.include?(type)
+          raise MetadataError, "Invalid menu item type: #{type.inspect}"
+        end
+
+        # Link items must declare a URL source: either an explicit `url:`,
+        # OR a `presenter:` slug whose URL is computed at render time,
+        # OR a `provider:` whose returned hash supplies the URL,
+        # OR a `widget: true` flag whose `render:` partial drives the
+        # markup (no wrapping link/button → no URL needed).
+        # Presenter / provider resolution is deferred from boot to
+        # render because both require the loader / registry, neither
+        # available in #initialize.
+        if link? && @url.blank? && @presenter_slug.blank? &&
+           @provider_name.blank? && !@widget
+          raise MetadataError, "Menu link requires a url, presenter, provider, or widget: true"
+        end
+
+        unless @label.nil? || @label == false || @label.is_a?(String)
+          raise MetadataError, "Menu item label must be a string or `false`, got #{@label.class}"
+        end
+
+        if @badge
+          raise MetadataError, "Badge requires a provider" unless badge_provider.present?
+          forms = [ badge_renderer, badge_template, badge_partial ].compact
+          if forms.empty?
+            raise MetadataError, "Badge must have one of: renderer, template, or partial"
+          elsif forms.size > 1
+            raise MetadataError, "Badge must have exactly one of: renderer, template, or partial"
+          end
+        end
+
+        # Responsive per-item keys — early-gate type / enum / mutex.
+        if @pin && @pin != "always"
+          raise MetadataError, "pin: must be 'always' (got #{@pin.inspect})"
+        end
+
+        if @hide_below && @show_below
+          raise MetadataError,
+                "hide_below: and show_below: are mutually exclusive — pick one"
+        end
+
+        [ [ :hide_below, @hide_below ], [ :show_below, @show_below ],
+          [ :collapse_label_below, @collapse_label_below ] ].each do |key, value|
+          next if value.nil?
+          unless value.is_a?(Integer) && value > 0
+            raise MetadataError, "#{key}: must be a positive integer (got #{value.inspect})"
+          end
+        end
+
+        if separator? && (@responsive_priority || @pin || @hide_below ||
+                          @show_below || @collapse_label_below)
+          raise MetadataError,
+                "separator menu item cannot carry responsive_priority/pin/" \
+                "hide_below/show_below/collapse_label_below keys"
+        end
+      end
+
+      # Set of {:label, :icon} indicating which channels would render
+      # for this item. Drives both validation and the rendering A11y
+      # decision (visible label suppresses aria-label on the link).
+      def visible_content(loader)
+        out = Set.new
+        out << :label if resolved_label(loader).present?
+        out << :icon if resolved_icon(loader).present?
+        out
+      end
+
+      def descriptor
+        "'#{@label || view_group_name || @url || type}'"
+      end
+    end
+  end
+end