@unabridged/midwest 0.22.0 → 0.23.0

package/README.md

@@ -3,7 +3,7 @@
 [![Rails Tests](https://github.com/unabridged/midwest/actions/workflows/rails-tests.yml/badge.svg?branch=main)](https://github.com/unabridged/midwest/actions/workflows/rails-tests.yml)
 [![Bridgetown Tests](https://github.com/unabridged/midwest/actions/workflows/bridgetown-tests.yml/badge.svg?branch=main)](https://github.com/unabridged/midwest/actions/workflows/bridgetown-tests.yml)
 [![Ruby](https://img.shields.io/badge/Ruby-3.3_%7C_3.4-CC342D?logo=ruby&logoColor=white)](https://github.com/unabridged/midwest/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](https://github.com/unabridged/midwest/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-96%25-brightgreen)](https://github.com/unabridged/midwest/actions/workflows/ci.yml)
 
 Midwest Component Library is an implementation of the Midwest Design System using [ViewComponent](https://github.com/github/view_component).
 
@@ -109,6 +109,69 @@ bin/rails midwest:generate:component YourComponent
 
 The syntax follows [ViewComponent's generator](https://viewcomponent.org/guide/generators.html).
 
+### MCP Server
+
+Midwest ships an [MCP](https://modelcontextprotocol.io) server that gives AI agents live access to the component API. To connect, add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "midwest": {
+      "command": "bundle",
+      "args": ["exec", "midwest_mcp"]
+    }
+  }
+}
+```
+
+The server exposes 8 tools: `list_components`, `get_component_api`, `search_components`, `get_component_examples`, `get_helper_methods`, `get_form_builder_info`, `get_component_relationships`, and `validate_component_usage`.
+
+### Component Guidance
+
+The MCP server includes a guidance system that helps agents avoid common composition mistakes. Guidance is stored in `lib/midwest/mcp/data/component_guidance.yml` and surfaced through MCP tools automatically.
+
+Two data sources feed into guidance:
+
+- **Auto-detected**: Template scanning discovers which components internally render other components (e.g., `StatComponent` renders a `CardComponent`). This powers redundant nesting warnings.
+- **Curated**: Anti-patterns and best practices added to the YAML file from real agent mistakes observed in the field.
+
+Use `bin/guidance` to manage guidance data:
+
+```bash
+bin/guidance              # List components with guidance and auto-detected internal renders
+bin/guidance show stat    # Show full guidance for a component
+bin/guidance add          # Describe a pattern in plain text; Claude formats and appends it
+bin/guidance scan         # Display the internally-renders graph for all components
+bin/guidance check        # Validate YAML keys against the component index
+```
+
+The `add` command opens your `$EDITOR` for you to describe an anti-pattern or best practice in plain English. When you save and close, the Claude CLI processes your description into properly formatted YAML and appends it to the guidance file. This is the fastest way to capture a mistake you spotted an agent making in the field.
+
+You can also edit `lib/midwest/mcp/data/component_guidance.yml` directly:
+
+```yaml
+stat_component:
+  anti_patterns:
+    - title: "Wrapping stat in a card"
+      description: "StatComponent already renders a CardComponent internally."
+      bad: |
+        <%= midwest_card do %>
+          <%= midwest_stat value: "1,234", label: "Users" %>
+        <% end %>
+      good: |
+        <%= midwest_stat value: "1,234", label: "Users" %>
+  best_practices:
+    - title: "Group stats in a grid"
+      description: "Use midwest_grid to lay out multiple stats."
+      example: |
+        <%= midwest_grid columns: 3 do %>
+          <%= midwest_stat value: "1,234", label: "Users" %>
+          <%= midwest_stat value: "567", label: "Orders" %>
+        <% end %>
+```
+
+Run `bin/guidance check` after editing to verify all component keys are valid.
+
 ### Deploying your application
 
 In order to deploy your application the deploy server will need access to the private repo. One way to accomplish that is to add the deploy key on this repo to the deploy server. You should be able to create the key from the values in the Shared 1Password vault entry "GitHub - Midwest"

package/app/assets/javascript/midwest/index.ts

@@ -32,6 +32,10 @@ import PasswordRequirements from '../../../components/midwest/password_requireme
 import CodeBlock from '../../../components/midwest/code_block_component/code_block_component_controller'
 import DatePicker from '../../../components/midwest/form/date_picker_component/date_picker_component_controller'
 import TimePicker from '../../../components/midwest/form/time_picker_component/time_picker_component_controller'
+import IntersectionObserver from '../../../components/midwest/intersection_observer_component/intersection_observer_component_controller'
+import FocusTrap from '../../../components/midwest/focus_trap_component/focus_trap_component_controller'
+import Onboarding from '../../../components/midwest/onboarding_component/onboarding_component_controller'
+import ThemeSwitch from '../../../components/midwest/form/switch_component/theme_switch_controller'
 /* IMPORTS */
 
 export { Card, Banner, CountdownTimer, Chart }
@@ -71,5 +75,9 @@ export function registerMidwestControllers (application: any) {
   application.register('midwest-code-block', CodeBlock)
   application.register('midwest-date-picker', DatePicker)
   application.register('midwest-time-picker', TimePicker)
+  application.register('midwest-intersection-observer', IntersectionObserver)
+  application.register('midwest-focus-trap', FocusTrap)
+  application.register('midwest-onboarding', Onboarding)
+  application.register('midwest-theme-switch', ThemeSwitch)
   /* EXPORTS */
 }

package/app/assets/javascript/midwest/keyboard_navigation.ts

@@ -0,0 +1,68 @@
+// Shared keyboard-navigation helpers for menu/list components.
+//
+// Implements the WAI-ARIA "roving focus" pattern: arrow keys move DOM focus
+// between a flat list of items, Home/End jump to the ends, and Escape/Tab hand
+// control back to the caller (typically to close a popover and restore focus).
+// Components own *which* elements are navigable and *what* closing means; this
+// module owns the key handling so the behavior stays consistent across the
+// library.
+
+const NAVIGATION_KEYS = ['ArrowDown', 'ArrowUp', 'Home', 'End', 'Escape', 'Tab']
+
+export interface RovingFocusOptions {
+  // Called on Escape. Typically closes the menu and returns focus to the trigger.
+  onEscape?: () => void
+  // Called on Tab. The default Tab behavior is left intact so focus still leaves
+  // the menu; use this to close the menu alongside it.
+  onTab?: () => void
+  // When true (default) arrow navigation wraps from the last item to the first
+  // and vice versa. When false it stops at the ends.
+  loop?: boolean
+}
+
+// Handles a keydown against a roving-focus list. Returns true when the event
+// was one this helper is responsible for, so callers can `stopPropagation()`
+// only for keys that were actually handled.
+export function handleRovingFocusKeydown (
+  event: KeyboardEvent,
+  items: HTMLElement[],
+  options: RovingFocusOptions = {}
+): boolean {
+  if (items.length === 0) return false
+  if (!NAVIGATION_KEYS.includes(event.key)) return false
+
+  const { onEscape, onTab, loop = true } = options
+  const current = items.findIndex(item => item === document.activeElement)
+
+  switch (event.key) {
+    case 'ArrowDown': {
+      event.preventDefault()
+      const next = current < items.length - 1 ? current + 1 : (loop ? 0 : items.length - 1)
+      items[next].focus()
+      break
+    }
+    case 'ArrowUp': {
+      event.preventDefault()
+      const prev = current > 0 ? current - 1 : (loop ? items.length - 1 : 0)
+      items[prev].focus()
+      break
+    }
+    case 'Home':
+      event.preventDefault()
+      items[0].focus()
+      break
+    case 'End':
+      event.preventDefault()
+      items[items.length - 1].focus()
+      break
+    case 'Escape':
+      event.preventDefault()
+      onEscape?.()
+      break
+    case 'Tab':
+      onTab?.()
+      break
+  }
+
+  return true
+}