Copilot instructions

1---
2description: Hotwire Native Guidelines
3applyTo: "**/*.rb,**/*.js,**/*.html.erb"
4---
5 
6# Hotwire Native Guidelines
7 
8## Core Concepts
9 
10- Hotwire Native displays web content in a native shell with platform-specific navigation
11- Web content renders in a WebView with native-feeling transitions and behaviors
12- Link navigation is intercepted and handled by the native adapter
13- Build once for the web, deploy simultaneously to web and native mobile apps
14- Progressively enhance with native components where higher fidelity is needed
15 
16## Navigation Best Practices
17 
18- Design web content to work across web, iOS, and Android
19- Links between pages become native screen transitions automatically
20- External links open in an in-app browser (SFSafariViewController on iOS, Custom Tabs on Android)
21- Use `data-turbo-action="replace"` to replace the current screen instead of pushing a new one
22- Ensure all screens are accessible via URLs for proper native navigation
23 
24## Path Configuration
25 
26- Define platform-specific navigation rules in a JSON configuration file
27- Host configuration files at versioned URLs (e.g., `/configurations/ios_v1.json`)
28- Include both local (bundled) and remote (server-hosted) configurations
29- Use regex patterns to match URLs and apply specific behaviors
30- Configuration example:
31 
32```json
33{
34  "settings": {
35    "feature_flags": [
36      {
37        "name": "enable_new_feature",
38        "enabled": true
39      }
40    ]
41  },
42  "rules": [
43    {
44      "patterns": ["/modal/.*"],
45      "properties": {
46        "context": "modal"
47      }
48    },
49    {
50      "patterns": ["/tabs/.*"],
51      "properties": {
52        "presentation": "refresh"
53      }
54    }
55  ]
56}
57```
58 
59## Bridge Components
60 
61- Use Bridge Components for web-to-native communication
62- Components have both web (Stimulus) and native (Swift/Kotlin) counterparts
63- Register component handlers in your native app and attach web controllers in HTML
64- Use for native UI elements like top bar buttons, action sheets, and platform APIs
65- Web component implementation example:
66 
67```javascript
68// app/javascript/controllers/native_button_controller.js
69import { Controller } from "@hotwired/stimulus";
70import { BridgeComponent } from "@hotwired/bridge";
71 
72export default class extends Controller {
73  static values = { title: String, style: String };
74 
75  connect() {
76    this.bridge = new BridgeComponent("button", this);
77    this.bridge.send("connect", {
78      title: this.titleValue,
79      style: this.styleValue || "default",
80    });
81  }
82 
83  disconnect() {
84    this.bridge.send("disconnect");
85  }
86 
87  handleTap(message) {
88    // Handle tap event from native
89    const form = this.element.closest("form");
90    if (form) form.requestSubmit();
91  }
92}
93```
94 
95```html
96<!-- In your view -->
97<div
98  data-controller="native-button"
99  data-native-button-title-value="Save"
100  data-native-button-style-value="primary"
101></div>
102```
103 
104## Native Screen Integration
105 
106- Create fully native screens for high-fidelity interactions
107- Register URL routes that map to native screen controllers
108- Ensure each native screen has a corresponding URL for consistent navigation
109- Share data between web and native using URL parameters or Bridge Components
110- Follow platform design guidelines for native screens (Human Interface Guidelines for iOS, Material Design for Android)
111 
112## Progressive Enhancement Strategy
113 
114- Start with web-only implementation to quickly ship features
115- Add Bridge Components for native UI elements and platform integrations
116- Build fully native screens only where high fidelity is required
117- Maintain a consistent navigation model across all screen types
118- Use feature flags in path configuration to enable native features gradually
119 
120## Mobile-Optimized HTML/CSS
121 
122- Test all web pages in mobile viewports
123- Use responsive design principles for fluid layouts
124- Ensure tap targets are appropriately sized (minimum 44×44pt on iOS, 48×48dp on Android)
125- Optimize images and assets for mobile devices
126- Consider mobile-specific meta tags:
127 
128```html
129<meta
130  name="viewport"
131  content="width=device-width, initial-scale=1, user-scalable=no"
132/>
133<meta name="apple-mobile-web-app-capable" content="yes" />
134<meta name="turbo-visit-control" content="reload" />
135```
136 
137## Performance Considerations
138 
139- Keep initial page load fast (under 2 seconds)
140- Minimize JavaScript usage to conserve battery and performance
141- Optimize image sizes for mobile network conditions
142- Use Turbo Frames to load content incrementally
143- Consider offline capabilities with service workers where appropriate
144