Midwest Component Library v0.24.0

Previews

No matching results.

🗺️ Roadmap

This roadmap groups items from the Future Plans reference into versioned milestones. Each minor release targets 2–3 new components and 5–6 improvements to existing ones. Ordering reflects priority and implementation dependency, not a delivery commitment.

v0.21 — Repeatable Forms, Date Display & MCP Foundation

Dynamic field arrays, date-range display, and the first Model Context Protocol server release.

New Components

  • Repeatable Fields ✅ — Dynamic field array for adding/removing nested form sets. Form::RepeatableComponent with Stimulus controller, Rails nested attributes integration (accepts_nested_attributes_for), min/max limits, animated add/remove with _destroy support, template-based new rows, form builder shorthand (f.repeatable), and Lookbook previews
  • Calendar Date ✅ — Date/time display tiles with range support. CalendarDateComponent with single date and date-range modes (start/end tiles with arrow separator), analog SVG clock face with accurate hour/minute hand rotation, formatted time text, custom strftime format mode, inline two-column time layout, vertical stacking, three sizes (sm/default/lg), semantic state theming, string date parsing, and Lookbook playground preview
  • MCP Server (Alpha) ✅ — Model Context Protocol server for AI-powered component assistance
    • list_components — Full component catalog with categories, descriptions, deprecation status
    • get_component_api — Detailed API information for a specific component (options, slots, methods)
    • search_components — Search for components by feature, keyword, or capability
    • get_component_examples — Usage examples from previews and tests
    • Component metadata parsing, midwest_mcp executable

MCP Server Features

  • Component Discovery ✅ — Full component catalog with categories, descriptions, deprecation status
  • Multi-Framework Support — Rails and Bridgetown integration documentation per component
  • Asset Dependencies — JavaScript/CSS requirements per component (Chart.js, Stimulus controllers, etc.)
  • Component Lifecycle — Stability indicators (alpha/beta/stable/deprecated) per component
  • Lookbook Integration — API panel with component documentation in Lookbook UI

Improvements

  • AvatarComponent ✅ — processing: spinner overlay, extended shape variants
  • BreadcrumbComponent ✅ — as: :button render mode
  • DropdownComponent ✅ — align: positioning prop (12 positions)
  • Form::SelectComponent ✅ — no_clear: and resize: false options

v0.22 — Password, Groups, Code & MCP Patterns

Password UX, grouped overflow components, syntax highlighting, and MCP enhancements.

New Components

  • Password Requirements ✅ — Visual checklist for real-time password validation
  • Group ✅ — Horizontal cluster with +N more overflow indicator
  • Code Block ✅ — Syntax-highlighted code via Rouge with copy-to-clipboard, theme system (rouge/midwest), CardComponent composition, language badge, line numbers
  • Date Picker ✅ — Native date input with calendar popup
  • Time Picker ✅ — 12/24 hour formats with increment/decrement buttons

MCP Server Features

  • get_helper_methods ✅ — Helper method signatures and descriptions
  • get_form_builder_info ✅ — Form builder integration, available methods, wrapper patterns
  • get_component_relationships ✅ — Component composition patterns and related components
  • validate_component_usage ✅ — Validate option names, constant-constrained values, and slot names with suggestions
  • Stimulus Controllers ✅ — Controller values, actions, targets per component (via get_component_api)
  • Component Descriptions ✅ — Add class-level doc comments to all components for richer MCP search results and listings
  • Form Validation Patterns ✅ — Shopify-style validation, error display, integration docs
  • Template Language Examples ✅ — HAML, ERB, Ruby, and HTML output for all examples
  • Customization Points ✅ — Allowed/discouraged customizations and extension points per component

Improvements

  • Form::FileComponent — Drag-and-drop zone ✅
  • BadgeComponent — Action slot for dismissible tags ✅
  • TooltipComponent — Full 9-position alignment grid ✅
  • CalloutComponent — dark: variant ✅
  • DialogComponent — Remote content loading ❌ — Removed; clashed with the Dialogable concern's design
  • Form Validation — Shopify-style validation patterns ✅

v0.23 — Content, Intersection, Accessibility & MCP Validation

Markdown rendering, social previews, viewport detection, onboarding tours, accessibility improvements, and MCP validation tools.

New Components

  • Markdown ✅ — Server-side rendering via Commonmarker
  • Social Preview ✅ — Platform-specific social media post previews (Facebook, Twitter/X, LinkedIn, Instagram) with image mosaic grids, link preview cards, avatar layouts, and platform-accurate styling. Parent SocialPreviewComponent orchestrates platform sub-components via slots
  • Intersection Observer ✅ — Declarative Stimulus controller for viewport detection
  • Guided Onboarding ✅ — Native (dependency-free) product tours: a parent OnboardingComponent orchestrates nested Onboarding::StepComponent slots through a Stimulus tour engine (dimmed overlay, target highlighting, positioned card with arrow, Back/Next/Done + keyboard navigation, focus trapping, optional exit confirmation)
  • Skip Links ✅ — Skip navigation components for keyboard users
  • Focus Trap ✅ — Focus management wrapper for modals

MCP Server Features

  • validate_component_usage ✅ — Moved to v0.22
  • suggest_components ✅ — Context-aware component suggestions from a code/markup snippet or NL description, combining an intent map (raw HTML tags + synonyms), keyword search, and complementary slot-composition signals; reports what you already use
  • diagnose_component ✅ — Symptom-driven debugging: runs nesting, Stimulus-wiring, form-context, constrained-option, and accessibility checks against parsed metadata, ranks likely causes by symptom keywords, and surfaces curated common fixes
  • get_accessibility_info ✅ — ARIA roles, keyboard patterns, focus management, and WCAG criteria per component. Data-driven via accessibility.yml (managed with bin/a11y) with a shared roving-focus pattern; covers the interactive component set (dropdown, dialog, tabs, command palette, onboarding, notification, tooltip, skip link, focus trap, live region)
  • Accessibility Checklist ✅ — Per-component WCAG success criteria (level + note) surfaced through get_accessibility_info
  • Screen Reader Patterns ✅ — Announcement/semantic behavior documented per component in accessibility.yml
  • Keyboard Interaction Docs ✅ — Per-component keyboard tables, with shared patterns (roving focus) merged in
  • Auto-Generated Previews ✅ — generate_preview scaffolds a Lookbook preview from a component's parsed metadata: a default example, a playground with @param controls inferred from options (constant→select, boolean→toggle, integer→number, else text), optional extra example stubs, and matching sidecar .html.erb templates that render the component through its registered view helper (with slot setters seeded for slotted components)

Improvements

  • ARIA Patterns ✅ — Shared AriaHelper concern: aria_live_attributes (polite/assertive live regions) + humanized_label auto aria-label generation. New LiveRegionComponent; NotificationComponent politeness now state-aware; IconComponent labels fixed for multi-hyphen names
  • Keyboard Navigation ✅ — Shared handleRovingFocusKeydown() helper (arrow/Home/End/Escape/Tab roving focus); DropdownComponent refactored as reference consumer
  • Screen Reader ✅ — LayoutComponent opt-in <main> landmark (display:contents, pairs with midwest_skip_link); midwest_heading helper for level-clamped heading hierarchy; EmptyStateComponent heading_level:
  • Form::SwitchComponent — change_theme: for dark/light mode toggle ✅

v0.24 — Device Frames, Media, Theming & MCP Tokens

Device mockups, rich media players, theming system, and MCP design token tools.

New Components

  • Social Preview: TikTok, YouTube ✅ — Video-centric social platform previews extending the SocialPreview::BasePlatformComponent pattern. TiktokComponent (vertical 9:16 frame, right-hand action rail with abbreviated engagement counts, follow badge, bottom caption + sound row) and YoutubeComponent (16:9 thumbnail, duration badge, watch-row with channel avatar/title/verified badge and "views · timestamp" meta). Shared format_count helper on the base platform (1.2K/1.2M abbreviation); both wired into the parent orchestrator and Lookbook previews
  • Device Frame ✅ — Pure-CSS, zero-dependency Apple device bezels: DeviceFrameComponent wrapping a src: screenshot or rich screen slot content (Video, Carousel, live markup) in an iPhone (Dynamic Island + home indicator + side buttons), iPad (thin bezel + camera), MacBook (lid + hinge base with thumb notch), Apple Watch (digital crown + side button + top/bottom band), or Apple TV (16:9 panel + stand). orientation: :portrait/:landscape for handhelds, four body color: variants (black/silver/gold/blue), optional drop shadow:, and a responsive: mode (container-query --du scale unit) that fluidly scales the entire frame + contents to the parent's inline size. Wired into the midwest_device_frame helper and Lookbook previews
  • Playlist ✅ — Native, zero-dependency audio playlist player. PlaylistComponent orchestrates nested SongComponent slots through a Stimulus controller wrapping a single <audio> element: play/pause toggle, previous/next transport, click-to-seek progress bar with elapsed/total time, keyboard controls (space/k, arrow keys), and auto-advance on track end. Two display modes — a scrollable track list (view: :playlist) and an album-art focus view (view: :art) with details revealed on hover. Per-track artwork: shows album-art previews + a blurred backdrop; autoplay:, dark:, and a collapsible list round it out. Wired into midwest_playlist/midwest_song helpers and Lookbook previews
  • 360° Viewer ✅ — Native, zero-dependency drag-to-pan viewer for wide panoramic (360°) images and video. PanoramaComponent sizes the media to fill the viewport height and pans it horizontally via Pointer Events (unified mouse + touch with pointer capture), keyboard (arrow keys / Home-to-reset), and release inertia. Images wrap: seamlessly for a true 360° loop (the controller clones the media and applies modulo offsets); video panning is clamped to the frame. Optional auto_rotate: drift (pauses on hover/focus/drag, honors prefers-reduced-motion), a fading drag hint + reset button (controls:), start: position, and an sr-only live region announcing pan percentage. Wired into the midwest_panorama helper and Lookbook previews
  • Theme Switcher ❌ — Dynamic theme switching with persistence — CANCELLED: Panel context doesn't support loading Midwest CSS/JS reliably
  • Theme Builder Panel ❌ — Lookbook panel for theme customization — CANCELLED: Panel context doesn't support loading Midwest CSS/JS reliably

AI & Agents

  • Command Palette AI Chat ✅ — Opt-in conversational mode on CommandPaletteComponent (chat:) that streams from any OpenAI-compatible endpoint (cocore.dev, OpenAI, Ollama, …) with a dependency-free native markdown renderer. Two transports: direct browser fetch (local/dev) and a server proxy.
  • Midwest::LlmAgent Rails feature ✅ — Controller concern + Midwest::Routing::LLM_AGENT + generator, powered by the optional RubyLLM gem: server-owned key/model/system prompt, ActionController::Live SSE relay, and durable history via acts_as_chat (history: :fresh/:resume)
  • Agentic tools ✅ — The model can run palette commands: RubyLLM::Tool server tools plus client-directive tools (tools: :commands) that stream inline action rows and reuse the palette's existing selection path, gated by a server-side allowlist

MCP Server Features

  • get_design_tokens ✅ — Full token tree (colors, spacing, typography, shadows, motion), scoped by optional category; parsed from the gem's token source of truth via Midwest::Tokens
  • get_migration_guide ✅ — Breaking changes between versions, compiled from the changelog (the version source of truth). A ChangelogParser reads each demo/app/docs/changelog/vX_Y_Z.md.erb into version/title/sections; ChangelogIndex orders releases by semver and answers range queries. Pass from/to to bound the range (defaults to the latest release); each release returns its removals, changes, adoptable additions (the ### headings), and heuristic migration notes — sentences carrying conservative signals (removed/renamed/replaced/no longer/deprecated), with bug-description false positives ("breaking the …") deliberately excluded. A flattened migration_summary gives the quick "what breaks" scan
  • Design Token Export ✅ — CLI: midwest_mcp tokens:export --format json|css|scss
  • Token Usage Mapping ✅ — Which components use which design tokens, via the get_token_usage MCP tool. A TokenReferenceParser pulls token references from each component's CSS and templates (var(--token) refs plus Tailwind colour utilities like bg-theme-7, which resolve to Midwest colours through @theme); TokenUsageIndex classifies them against the canonical token registry built from Midwest::Tokens (so component-local CSS variables like --du/--card-width are excluded) and builds both forward and inverse maps. Three query modes: pass component: for the tokens it uses (grouped by category), token: for the components using a given token, or neither for an adoption overview (per-category usage counts, unused scalar tokens, and most-used tokens). Doubles as an adoption audit — surfaces that colour tokens are broadly used (59/210 across 61 components) while the v0.24 scalar token layer (spacing/radius/shadow/typography) is still barely consumed
  • Theme Migration Guide ✅ — Migration paths for the theming/styling engine, served through get_migration_guide's topic: filter (Midwest has no separately-versioned themes — Theme Switcher/Builder were cancelled — so theme migrations live in the changelog like everything else). get_migration_guide(topic: "tailwind") traces the styling engine across all history (v0.8.0 → the v0.23.4 Tailwind v3→v4 migration); topic: "theme" / "tokens" trace the colour/token system. The topic scan spans all versions rather than a single range
  • Animation Documentation ✅ — Per-component animation behavior via the get_animation_info MCP tool. A MotionParser extracts the facts straight from each component's CSS (the source of truth) — keyframes, durations, easing curves, animated properties, prefers-reduced-motion support, and whether it uses the motion tokens — across all 39 animated components. The AnimationIndex merges those parsed facts with a curated YAML overlay (data/animation.yml, 14 flagship entries) adding a prose summary, customization guidance, and JS-driven-motion notes. The tool matches every parsed duration/easing against the canonical --duration-*/--ease-* tokens (surfacing on-system vs one-off values) and emits auto-derived advisories (missing reduced-motion fallback, off-token durations). Managed with bin/motion (list/show/check)
  • Responsive Breakpoints ✅ — Breakpoint system documentation via the get_breakpoints MCP tool. Documents Midwest's design-token breakpoint scale (--breakpoint-*, xs–2xl, parsed from the token source of truth), the root-font-size ladder those breakpoints drive in responsive-system.css (10px→16px, so rem/em-sized components scale fluidly without per-component media queries), CSS container-query support (the --du design unit), and — crucially — how the token scale (400/600/800/1000/1200/1400px) differs from Tailwind's utility-variant defaults (640/768/…px) plus how to align them. Scopable via section: (strategy/breakpoints/container_queries/tailwind)

Improvements

  • Design Token System ✅ — Token architecture in tokens.css (@layer midwest.tokens: spacing, radius, elevation, motion, typography, z-index, breakpoints) with a Midwest::Tokens Ruby API; colours delegate to the existing Midwest::Theme. CSS is the single source of truth, parsed by Ruby (mirrors color-system.css / Midwest::Theme)
  • Dark Mode ✅ — Comprehensive palette: a :not([class])-scoped bare-element foundation in dark-mode.css (selection, hr, links, inline code/kbd, blockquote, tables) plus per-component dark overrides for surfaces that assumed light backgrounds (AccordionComponent, TreeViewComponent, TimelineComponent neutral tokens)
  • Tailwind CSS v4 ✅ — Upgraded the styling engine to Tailwind v4 (CSS-first @theme/@custom-variant/@source, Lightning CSS). Fixes a v3 cascade-layer corruption bug; drops the JS tailwind.config.js + postcss.config.js. v4 consumers use config/tailwind.theme.css (the JS tailwind.theme.js is v3-only)
  • Token Export ✅ — JSON, CSS, SCSS export via Midwest::Tokens.to_json/to_css/to_scss (surfaced through the tokens:export CLI)
  • ChartComponent ✅ — Sparkline rendering mode (sparkline: true): compact, chrome-less trend line — hides axes, legend, tooltip, and title, applies tight-padding presets, and defaults to a :line chart. Every preset is overridable
  • StatComponent ✅ — Embedded sparkline: (array or { data:, type:, color: }, color follows trend direction) plus a comparison-period baseline (comparison: / comparison_label:)
  • CommandPaletteComponent — AI chat mode composed from ButtonGroup, Timeline, and Card ✅
  • TimelineComponent — chat: conversation variant with per-item left/right placement ✅
  • ButtonComponent — type-relative sizing (font-size in rem, box metrics in em) ✅

v0.25 — Motion, Maps, Audio & Animation

Parallax effects, maps, web audio, and motion system.

New Components

  • Social Preview: Threads, Bluesky — Newer text-based social platform previews extending the SocialPreview::BasePlatformComponent pattern
  • Parallax — Scroll-driven parallax components
  • Map — Google Maps integration with markers
  • Web Audio — AudioContext suite for audio applications
  • Motion Primitives — Fade, slide, scale, rotate animations
  • Page Transitions — Turbo navigation transitions

MCP Server Features

  • Motion System Docs — Standardized easings, duration scale, preference detection
  • Performance Characteristics — Rendering time, dataset limits per component
  • Animation API — Play/pause, seek, playback rate documentation

Improvements

  • Motion System — Standardized easings and duration scale
  • Animation Controller — Play/pause, seek, motion preference detection
  • FormComponent — autosave:, ajax:, close_modal_on_success:

v0.26 — Data Visualization Enhancements

Enhanced charting and data display capabilities.

New Components

  • Social Preview: Pinterest, Reddit — Community and visual social platform previews extending the SocialPreview::BasePlatformComponent pattern
  • Sparkline — Mini trend indicators with trend arrow
  • Heatmap — Color scale visualization with tooltips

MCP Server Features

  • Chart Relationship Graph — Chart component relationships and data flow
  • Data Requirement Docs — Data format requirements per chart type
  • Turbo Integration Patterns — Turbo Frames, Streams, and Channels documentation

Improvements

  • ChartComponent — Hover crosshairs, drill-down, selection highlighting, export
  • TableComponent — Inline editing, column resizing, multi-sort, advanced filtering
  • StatComponent — Enhanced metric card with sparkline integration

v0.27 — Navigation Patterns

Comprehensive navigation components.

New Components

  • Social Preview: Mastodon — Federated social platform preview extending the SocialPreview::BasePlatformComponent pattern
  • Mega Menu — Multi-column dropdowns with icons and descriptions
  • Sidebar Navigation — Collapsible sections with nested menus
  • Context Menu — Right-click activation with submenus

MCP Server Features

  • Navigation Component Graph — Navigation patterns and relationship mapping
  • Route-to-Component Mapping — Active state detection patterns

Improvements

  • TabsComponent — Overflow menu, drag to reorder, badges, mobile bottom sheet
  • BreadcrumbsComponent — Truncation and dropdown for intermediates
  • MobileNavComponent — Enhanced with gesture support
  • Route Helpers — Active path detection, active link component
  • Scrollspy — Section highlighting with smooth scroll

v0.28 — Advanced Layout

Layout components for complex structures.

New Components

  • Masonry Grid — Pinterest-style layout
  • Split View — Resizable panes with persistent sizing via localstorage
  • Stack Layout — Vertical/horizontal stack with gap control
  • Container Queries — Responsive-at-container components
  • Dashboard Grid — Widget grid with draggable items

MCP Server Features

  • get_responsive_info — Breakpoint system, responsive behavior per component
  • Layout Pattern Docs — Composition patterns for complex layouts
  • Error Diagnosis — Common layout issues and fixes

Improvements

  • LayoutComponent — App shell pattern with fixed header/footer
  • EmptyStateComponent — Enhanced with action suggestions and illustrations

v0.29 — Performance & Loading

Performance optimizations and loading states.

New Components

  • Lazy Load — Intersection observer-based lazy loading (investigate if turbo frames provides this functionality)
  • Virtual Scroll — Large list rendering with dynamic heights (Use https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/content-visibility and NO JavaScript, EVER.)
  • Progressive Image — Blur-up effect with low-quality placeholders

MCP Server Features

  • Performance Monitor CLI — Component render time, interaction delay tracking
  • Bundle Analyzer — Component size, dependency analysis
  • Lazy Loading Docs — Which components support lazy loading, how to implement

Improvements

  • SkeletonComponent — Enhanced with proper shimmer effects
  • ImageComponent — Progressive loading mode
  • Performance Monitor — Render time, interaction delay tracking
  • Bundle Analyzer — Component size, dependency analysis

v0.30 — Turbo, Real-time & i18n

Deep Turbo/Hotwire integration and internationalization.

New Components

  • Turbo Frame Wrapper — Frame component with loading states
  • Cable Ready Integration — Real-time list updates
  • Broadcasting Components — Turbo Streams broadcasting
  • Optimistic UI Helpers — Optimistic deletion/creation

MCP Server Features

  • Turbo Integration Docs — Complete Turbo/Hotwire pattern documentation
  • i18n Support — Internationalization capabilities per component
  • RTL Layout Docs — Right-to-left layout support
  • Real-time Patterns — Turbo Streams, Cable Ready patterns

Improvements

  • Hotwire Modals — Modal frame navigation with history
  • Hotwire Forms — Turbo form submissions with progress
  • Request Lifecycle — Start/end handlers, error states, retry
  • Real-time Presence — Online user indicators
  • i18n — Translation keys, Rails integration, RTL support

1.0.0 — Stable Release (Target: Q2 2027)

First stable release with API stability guarantees.

Stability Guarantees

  • Semantic Versioning with 6-month deprecation policy
  • Backward compatible component, option, and slot APIs
  • Automated upgrade tools

Documentation

  • Complete API docs for all components
  • Design guidelines and accessibility guide
  • Migration guides for breaking changes

MCP Server Completeness

  • [ ] All 14 MCP tools implemented (v0.21–v0.28)
  • [ ] Lookbook integration complete
  • [ ] CLI commands (tokens:export, docs:generate, validate)
  • [ ] Multi-framework support documented

Testing & Quality

  • 95%+ test coverage
  • Integration and visual regression tests
  • A11y test suite, cross-browser E2E tests
  • Security audit passed

Release Checklist

  • [ ] All components stable with committed APIs
  • [ ] All breaking changes documented
  • [ ] Migration guides complete
  • [ ] Performance benchmarks met
  • [ ] Accessibility audit passed
  • [ ] Security audit passed
  • [ ] MCP server feature-complete

Beyond 1.0

Potential areas for post-1.0 development:

  • Bridgetown 3.0 support
  • ViewComponent 4.0 features
  • Stimulus 3.0 patterns
  • CSS nesting & container queries
  • Web Components support
  • React/Vue wrappers

Last Updated: July 2026 Current Version: 0.24.0 — released. All new components (Device Frames, Playlist/Song, 360° Panorama, TikTok/YouTube social previews), AI & Agents (agentic Command Palette chat, expanded Midwest::LlmAgent), and the token/introspection MCP set landed; Theme Switcher/Builder cancelled. The MCP server ships 17 tools: get_breakpoints, get_animation_info, get_token_usage, and get_migration_guide completed the milestone's token/introspection set. Next Target: 0.25.0 — Motion, Maps, Audio & Animation