lcp 0.1.0

data/lib/lcp_ruby/schemas/menu.json

@@ -0,0 +1,338 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lcp-ruby.dev/schemas/menu.json",
+  "title": "LCP Ruby Menu Definition",
+  "description": "Schema for menu metadata that defines navigation layout. Supports top bar, sidebar, or combined layouts. Defined in config/lcp_ruby/menu.yml. Menu items can reference view groups, contain dropdown children, link to external URLs, or act as visual separators. Items support role-based visibility and dynamic badge counters.",
+  "type": "object",
+  "properties": {
+    "top_menu": {
+      "type": ["array", "null"],
+      "description": "Items displayed in the horizontal top navigation bar. Default items render left-to-right in array order. Top-level items with position: 'right' are moved to a right-aligned zone after a flex spacer (use for profile, settings, log out, notifications). May be null when the section is seeded with only a `# lcp:menu top` insertion marker (no items yet) — runtime treats it as absent.",
+      "items": { "$ref": "#/$defs/menu_item" },
+      "examples": [
+        [
+          { "view_group": "employees" },
+          { "label": "Reports", "icon": "chart-bar", "children": [
+            { "view_group": "monthly_reports" },
+            { "view_group": "annual_reports" }
+          ]}
+        ]
+      ]
+    },
+    "sidebar_menu": {
+      "type": ["array", "null"],
+      "description": "Items displayed in the vertical sidebar navigation. Rendered top-to-bottom in array order. Items with position: 'bottom' are pinned to the sidebar footer. May be null when the section is seeded with only a `# lcp:menu sidebar` insertion marker (no items yet) — runtime treats it as absent.",
+      "items": { "$ref": "#/$defs/menu_item" },
+      "examples": [
+        [
+          { "view_group": "dashboard" },
+          { "separator": true },
+          { "view_group": "employees", "badge": { "provider": "active_employee_count", "renderer": "count_badge" } },
+          { "view_group": "settings", "icon": "cog", "position": "bottom" }
+        ]
+      ]
+    },
+    "responsive": {
+      "type": "object",
+      "description": "Responsive behaviour policy for the top menu and the sidebar. When omitted, sensible defaults apply (overflow_more@768px top, rail/off_canvas@1024px sidebar). See docs/design/responsive-menu.md.",
+      "additionalProperties": false,
+      "properties": {
+        "top_menu": {
+          "type": "object",
+          "description": "Top-nav responsive mode and per-mode settings.",
+          "additionalProperties": false,
+          "properties": {
+            "mode": {
+              "enum": ["none", "wrap", "overflow_more", "hamburger"],
+              "description": "How the top nav adapts below `breakpoint`. `none` = no responsive behaviour; `wrap` = items wrap to multiple rows; `overflow_more` = items that don't fit collapse into a *More* dropdown; `hamburger` = entire nav moves into a hamburger drawer."
+            },
+            "breakpoint": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Viewport-width threshold in pixels. For `overflow_more`/`hamburger` modes, the responsive behaviour engages below this width."
+            },
+            "more": {
+              "type": "object",
+              "description": "Trigger configuration for the synthesized *More* dropdown (only meaningful with mode: overflow_more).",
+              "additionalProperties": false,
+              "properties": {
+                "label_key": { "type": "string", "description": "i18n key for the *More* trigger label. Defaults to `lcp_ruby.nav.more` (\"More\")." },
+                "icon": { "type": "string", "description": "Icon identifier for the *More* trigger. Defaults to `more-horizontal`." }
+              }
+            }
+          }
+        },
+        "sidebar_menu": {
+          "type": "object",
+          "description": "Sidebar responsive mode policy. Sidebar has two states (above and below breakpoint), so it carries two enum keys instead of top_menu's single `mode`.",
+          "additionalProperties": false,
+          "properties": {
+            "above_breakpoint": {
+              "enum": ["none", "rail"],
+              "description": "Behaviour at viewport widths >= `breakpoint`. `rail` = sidebar can collapse to icon-only rail; `none` = sidebar stays fully expanded."
+            },
+            "below_breakpoint": {
+              "enum": ["none", "off_canvas"],
+              "description": "Behaviour at viewport widths < `breakpoint`. `off_canvas` = sidebar hides and opens as a drawer via the auto-injected sidebar_toggle; `none` = sidebar stays inline."
+            },
+            "breakpoint": { "type": "integer", "minimum": 1 },
+            "user_toggle": {
+              "type": "boolean",
+              "description": "When true, a sticky rail toggle button is rendered at the top of the sidebar so users can manually collapse / expand."
+            },
+            "persist": {
+              "enum": ["cookie", "local_storage", "none"],
+              "description": "Where to persist the user's rail collapsed / expanded state. `cookie` is the default (server-readable for FOUC-free SSR)."
+            },
+            "initial": {
+              "enum": ["expanded", "collapsed", "auto"],
+              "description": "Initial rail state when no persisted value is present. `auto` falls back to `expanded` on first paint and may toggle to collapsed via client-side viewport check."
+            },
+            "auto_inject_toggle": {
+              "type": "boolean",
+              "description": "When true (default), the framework prepends a synthesized sidebar_toggle item to top_menu when `below_breakpoint: off_canvas` is active and no explicit `- sidebar_toggle: true` is authored. Set to false to opt out (e.g. when authoring a custom trigger)."
+            }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": false,
+
+  "$defs": {
+    "menu_item": {
+      "description": "A navigation menu item. Can be one of: (1) view_group reference — links to a view group's primary presenter, (2) parent with children — dropdown/expandable group, (3) custom link — external URL, (4) separator — visual divider line. Items are displayed in array order, unless a layout-specific 'position' hint moves top-level items into a secondary slot (see position).",
+      "type": "object",
+      "properties": {
+        "separator": {
+          "type": "boolean",
+          "const": true,
+          "description": "When true, renders a horizontal divider line instead of a clickable item. All other properties except 'position' are ignored on separator items; position: 'right' on a top-level top_menu separator joins the right-aligned zone.",
+          "examples": [true]
+        },
+        "view_group": {
+          "type": "string",
+          "description": "Name of the view group this item links to. The item inherits the view group's label and icon unless explicitly overridden. Must match a view group name from config/lcp_ruby/view_groups/.",
+          "examples": ["employees", "departments", "deals"]
+        },
+        "label": {
+          "oneOf": [
+            { "type": "string" },
+            { "const": false }
+          ],
+          "description": "Display text for the menu item. Resolved via i18n. For view_group items, omitting this key falls back to the view group's resolved label; setting `false` opts out of that fallback (icon-only mode — `aria_label` then becomes required). For link/group items, omit to render icon-only. Strings auto-lookup `lcp_ruby.menu.<slug>`.",
+          "examples": ["Employees", "Reports", "Settings", false]
+        },
+        "label_key": {
+          "type": "string",
+          "description": "Explicit i18n key for the menu item label. Takes precedence over the `label` fallback when set. Use to localize a custom URL link without forking the menu.yml across locales.",
+          "examples": ["lcp_ruby.models.api_token.other", "my_app.menu.dashboards"]
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon identifier rendered alongside (or in place of) the label. Overrides the view group's default icon. Uses the icon set configured in the host application (e.g., Heroicons, FontAwesome). Always announced with `aria-hidden=\"true\"` so the icon name does not leak into the link's accessible name.",
+          "examples": ["users", "chart-bar", "cog", "folder", "bell"]
+        },
+        "aria_label": {
+          "type": "string",
+          "description": "Accessible name for screen readers. Required when no visible label renders (icon-only items, or `label: false` on a view_group). Resolved via i18n auto-lookup at `lcp_ruby.menu.aria.<slug>`. When a visible label IS rendered, this attribute is omitted on the link/button so the visible text remains the accessible name.",
+          "examples": ["Notifications", "Help", "User menu"]
+        },
+        "aria_label_key": {
+          "type": "string",
+          "description": "Explicit i18n key for `aria_label`. Mirrors `label_key`'s relationship to `label`.",
+          "examples": ["lcp_ruby.menu.aria.notifications"]
+        },
+        "url": {
+          "type": "string",
+          "description": "Custom URL for the menu item. Use for linking to external pages or host app routes outside the LCP engine. May contain path-template tokens of the form `{namespace.member}` resolved at render time — `current_user.<a>[.<b>[.<c>]]` (1–3 hops via `public_send`), `lcp_ruby.<helper>` (engine route helper), `application.<helper>` (host app route helper). When set, the item does not link to any view group.",
+          "examples": ["/admin/settings", "https://docs.example.com", "/users/{current_user.id}/avatar", "{lcp_ruby.destroy_user_session_path}"]
+        },
+        "method": {
+          "type": "string",
+          "enum": ["get", "post", "put", "patch", "delete", "GET", "POST", "PUT", "PATCH", "DELETE"],
+          "description": "HTTP method for the link. Defaults to `:get` (renders as `<a href>`). Any non-GET value renders the item as `button_to` with form-wrapping, CSRF token, and visual styling matching `<a>`. Invalid on `:view_group`, `:group` (children-bearing), and `:separator` items — those are always GET-equivalent.",
+          "examples": ["get", "post", "put", "patch", "delete"]
+        },
+        "presenter": {
+          "type": "string",
+          "description": "LCP presenter slug. Resolves the item's URL via the presenter's `record_alias` and action contract — yielding a slug-rename-resilient link. Pair with `action:` (always required) and optionally `alias:` (for show/edit/destroy/single-record custom actions). Cannot coexist with `url:`, `view_group:`, `provider:`, `children:`, or `separator:`.",
+          "examples": ["my_settings", "my_api_tokens", "notifications"]
+        },
+        "alias": {
+          "type": "string",
+          "description": "Record alias declared on the named `presenter:`. Resolves to a single record at render time (e.g., `:me` typically maps to `current_user`). Required for `action: :show / :edit / :destroy` and for single-record custom actions. Omit for `:index`, `:new`, and collection-context custom actions.",
+          "examples": ["me", "self"]
+        },
+        "action": {
+          "type": "string",
+          "description": "Presenter action name. Built-in CRUD actions: `show`, `edit`, `new`, `destroy`, `index`. Custom actions may be any string declared on the presenter's `actions.collection:` or `actions.single:`. Default HTTP method for built-in actions follows the action's CRUD method; for custom actions it defaults to `:post` (override via `method:`).",
+          "examples": ["show", "edit", "new", "destroy", "index", "mark_all_read"]
+        },
+        "defaults": {
+          "type": "object",
+          "description": "Extra query parameters forwarded to the resolved URL. Useful for `action: new` (pre-populating fields), custom actions, or any URL where the configurator wants extra params. String values support path-template tokens (e.g., `scope: \"user-{current_user.id}\"`).",
+          "examples": [{ "tab": "preferences" }, { "scope": "user-{current_user.id}" }]
+        },
+        "render": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Custom partial that owns the inner content of the link/button (the trigger, on `:group` items). Path is `<namespace>/<name>` mapping to `app/views/<namespace>/menu_renderers/_<name>.html.erb`. Locals: `item:` (the MenuItem) and `disabled:` (boolean). The framework still owns the wrapper (`<a>` / `<button_to>` / `<button class=\"lcp-nav-dropdown-toggle\">`), ARIA, active state, and badge placement — except when paired with `widget: true` which drops the wrapper entirely. Output is constrained to phrasing/inline content (HTML spec forbids block-level inside `<a>`/`<button>`); `widget: true` lifts that constraint.",
+          "examples": ["lcp_ruby/user_menu", "my_app/quick_search"]
+        },
+        "render_panel": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Custom partial for the dropdown panel of a `:group` item. Path is `<namespace>/<name>` mapping to `app/views/<namespace>/menu_renderers/_<name>.html.erb` (same directory as `render:`). Locals: `item:` (the parent group MenuItem) and `items:` (already expanded + visibility/permission-filtered children). Block-level HTML allowed (panel is `<div>`-wrapped). Requires `children:` on the same item — which may be `[]` when paired with `panel_provider:`.",
+          "examples": ["lcp_ruby/user_menu_panel", "my_app/tenant_switcher_panel"]
+        },
+        "widget": {
+          "type": "boolean",
+          "description": "When true, the framework drops the `<a>`/`<button_to>` wrapper and renders the item as a bare `<li class=\"lcp-menu-widget\">` containing the `render:` partial's HTML. Use for menu items whose inner HTML is interactive (search input, theme toggle, language switcher) where a wrapping link/button would swallow click events. Requires `render:`. Mutex with `url:`/`presenter:`/`view_group:`/`children:`/`separator:`; may coexist with `provider:` (provider returns widget data).",
+          "examples": [true]
+        },
+        "provider": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Computes the WHOLE item at render time. Names a class registered under the `menu_items` services category at `app/lcp_services/menu_items/<name>.rb` (namespaced `LcpRuby::HostServices::MenuItems::<Name>`). The class's `.call(options:, current_user:, request_context:)` returns a hash (single item) or array of hashes (siblings expanded at this YAML position) or nil/[] (item silently collapses). Cannot coexist with `url:`/`presenter:`/`view_group:`/`children:`/`separator:` (destination mutex). May coexist with `render:` (provider data + custom HTML).",
+          "examples": ["current_org_link", "user_tenants", "recently_visited"]
+        },
+        "panel_provider": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Computes panel CHILDREN for a `render_panel:` group at render time. Names a class registered under the same `menu_items` services category as `provider:`, returning an array of MenuItem-shaped hashes. Requires `render_panel:` AND `children:` (which may be `[]` for fully provider-driven panels). Mutex with `provider:` on the same item — pick one (provider: replaces the whole item; panel_provider: feeds the panel of a render_panel: group).",
+          "examples": ["user_workspaces", "tenant_switcher", "recent_records"]
+        },
+        "options": {
+          "type": "object",
+          "description": "Free-form options hash passed to a `provider:` or `panel_provider:` class as the `options:` kwarg. Use to parameterize the same provider with different configurations across menu positions (e.g., `recently_visited` with `options: { limit: 5 }` vs `options: { limit: 10 }`).",
+          "examples": [{ "limit": 5 }, { "style": "compact" }]
+        },
+        "position": {
+          "type": "string",
+          "enum": ["bottom", "right", "top", "left"],
+          "description": "Special positioning hint for top-level menu items. In sidebar_menu, 'bottom' pins the item to the sidebar footer area (e.g., settings, help links). In top_menu, 'right' right-aligns the item after a flex spacer (e.g., profile, log out). 'top' and 'left' are reserved for future sidebar alignments. Non-applicable combinations (e.g., 'bottom' in top_menu, 'right' in sidebar_menu) are silently ignored. Dropdown children ignore this key."
+        },
+        "visible_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Role-based visibility condition. When omitted, the item is visible to all authenticated users."
+        },
+        "disable_when": {
+          "$ref": "#/$defs/condition",
+          "description": "Condition controlling when the item renders in a disabled (visually muted, non-clickable) state. Same shape as `visible_when:`. Orthogonal to visibility: visibility hides the item from the DOM; disabled keeps the item rendered but suppresses click activation. Invalid on `:separator` items (no clickable target). NOT a security boundary — see the spec § \"`disable_when:` is a UI affordance\" for caveats."
+        },
+        "badge": {
+          "$ref": "#/$defs/badge_config",
+          "description": "Dynamic badge displayed next to the menu item label. Fetches data from a registered data provider and renders it using a badge renderer, template, or partial."
+        },
+        "children": {
+          "type": "array",
+          "description": "Nested menu items for dropdown (top_menu) or expandable (sidebar_menu) groups. Maximum 2 levels of children nesting. The parent item acts as a toggle and is not itself a link.",
+          "items": { "$ref": "#/$defs/menu_item" },
+          "examples": [
+            [
+              { "view_group": "monthly_reports" },
+              { "separator": true },
+              { "view_group": "annual_reports" }
+            ]
+          ]
+        },
+        "responsive_priority": {
+          "type": "integer",
+          "description": "For top_menu items in `responsive.top_menu.mode: overflow_more`: items with LOWER priority collapse into *More* first. Items without a priority default to 0. `position: right` and `pin: always` items implicitly have priority infinity (never collapse). Has no effect outside overflow_more mode."
+        },
+        "pin": {
+          "enum": ["always"],
+          "description": "For top_menu items in `mode: overflow_more`: `pin: always` items never enter the *More* dropdown even when the viewport is narrow. `position: right` items are implicitly pinned."
+        },
+        "hide_below": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Hide the item on viewports narrower than this pixel value. Client-side via matchMedia. NOT a permission boundary — the item is still in the DOM, just visually hidden via CSS."
+        },
+        "show_below": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Show the item ONLY on viewports narrower than this pixel value. Inverse of `hide_below`. Mutex with `hide_below` on the same item."
+        },
+        "collapse_label_below": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "For sidebar items: drop the visible label (keep icon only) when the viewport is narrower than this pixel value, regardless of rail/expanded state. Useful for items whose icon already communicates the destination clearly."
+        },
+        "sidebar_toggle": {
+          "type": "boolean",
+          "const": true,
+          "description": "Marker for a sidebar-toggle item in `top_menu`. Renders a button that opens the sidebar's off-canvas drawer. Mutex with every other destination key. The framework auto-injects one of these when `responsive.sidebar_menu.below_breakpoint: off_canvas` is active and no explicit `sidebar_toggle: true` is authored. Set `auto_inject_toggle: false` (or author one yourself) to suppress the synthesis."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "condition": {
+      "type": "object",
+      "description": "Condition controlling when a menu item is visible (`visible_when:`) or disabled (`disable_when:`). Routes through LcpRuby::ConditionEvaluator with no record context — supports `service:` (e.g. built-in `current_user_role`, `impersonating`, `feature_flag`) and compound `all`/`any`/`not` conditions. Field-based conditions (`field:`/`collection:`) are NOT supported because menu items have no record. When the condition is omitted or empty, the item is visible / enabled.",
+      "properties": {
+        "service": {
+          "type": "string",
+          "description": "Name of a registered condition service. The built-in `current_user_role` service evaluates the current user's roles against `params: { in: [...] }` or `params: { not_in: [...] }`. Other built-ins: `impersonating`, `feature_flag`.",
+          "examples": ["current_user_role", "impersonating", "feature_flag"]
+        },
+        "params": {
+          "type": "object",
+          "description": "Optional kwargs passed to the service. Values may use record-free dynamic refs: `{ current_user: id }` (or any `current_user.<attr>`) and `{ date: today/now }`. `field_ref:` is NOT supported in menu context — menu items have no record."
+        },
+        "all": {
+          "type": "array",
+          "description": "Compound — all child conditions must evaluate true.",
+          "items": { "$ref": "#/$defs/condition" }
+        },
+        "any": {
+          "type": "array",
+          "description": "Compound — at least one child condition must evaluate true.",
+          "items": { "$ref": "#/$defs/condition" }
+        },
+        "not": {
+          "$ref": "#/$defs/condition",
+          "description": "Compound — child condition must evaluate false."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "badge_config": {
+      "type": "object",
+      "description": "Configuration for a dynamic badge on a menu item. The badge fetches data from a data provider (registered in app/lcp_services/data_providers/) and renders it using exactly one of: renderer, template, or partial.",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "description": "Name of the data provider that supplies the badge value. Must be registered in Services::Registry. The provider receives the current user and returns the badge data.",
+          "examples": ["active_employee_count", "pending_approvals_count", "unread_notifications"]
+        },
+        "renderer": {
+          "type": "string",
+          "description": "Built-in badge renderer name. Available renderers: 'count_badge' (red pill with number, hidden for 0), 'text_badge' (uppercase text with optional color), 'icon_badge' (icon with optional color). Mutually exclusive with template and partial.",
+          "examples": ["count_badge", "text_badge", "icon_badge"]
+        },
+        "template": {
+          "type": "string",
+          "description": "String template with {key} interpolation for custom badge markup. The provider's return value is interpolated into the template. Mutually exclusive with renderer and partial.",
+          "examples": ["{count} new", "{status}"]
+        },
+        "partial": {
+          "type": "string",
+          "description": "Rails partial path for fully custom badge rendering. Receives the provider's return value as a local variable. Mutually exclusive with renderer and template.",
+          "examples": ["shared/custom_badge", "badges/notification_bell"]
+        },
+        "options": {
+          "type": "object",
+          "description": "Additional options passed to the badge renderer or partial. Content depends on the renderer being used.",
+          "default": {},
+          "examples": [{ "color": "red" }, { "max": 99 }]
+        }
+      },
+      "required": ["provider"],
+      "additionalProperties": false
+    }
+  }
+}