Below is an updated version of your README, incorporating the commands you provided, reflecting the current functionality, and addressing the style map issue you described earlier. I've also refined the content for clarity and professionalism while keeping the structure intact.
vsc-hosanna-ui README
IMPORTANT!!!!!!
- Ensure you have increased the open file limit on your machine.
on mac - add this to your ~/.zprofile file and ~/.zhrc file:
ulimit -n 262144
NOTE - there is something more permanent to do, with launchtl; but I don't remember what it is right now.
This is to avoid too many open files errors.
- In the find window of the debug console, put some random text to filter out, the output as too many log lines will show and grind your machine to a halt. We will fix this shortly
Overview
The vsc-hosanna-ui extension enhances your Visual Studio Code experience by providing advanced navigation and synchronization tools for JSON and TypeScript development. Key features include:
- JSON Navigation: Navigate style links and style key references within JSON files.
- TypeScript Navigation: Locate style links and style key references in TypeScript files.
- Source Synchronization: Keep transpiled Roku sources in sync with their TypeScript counterparts.
These tools are designed to streamline your workflow, improve code navigation, and maintain consistency across your project.
Features
JSON File Navigation
- Navigate to style links and style key references in JSON files (e.g.,
style.config.json).
- Quickly jump to style definitions to edit or review them.
TypeScript File Navigation
- Find and navigate to style links and style key references within TypeScript files.
- Seamlessly connect style usage with their definitions for faster development.
Source Synchronization
- Synchronize transpiled Roku code with its original TypeScript sources.
- Toggle synchronization on or off as needed to match your workflow.
Generated → Source navigation
When go-to-definition would land in a generated file (files matching patterns like *-generated*.ts or generated-*.ts), the extension redirects to the real implementation and symbol (class/function/const/method/property or @state).
Configurable Style JSON path (new)
- Configure where your style JSON lives using the
vsc-hosanna-ui.jsonFilePath setting.
- The extension reads and caches the raw JSON text, builds a path map (e.g.,
styles.card.title), and keeps it updated.
- When you edit the configured JSON file, the cache and map are automatically rebuilt.
- When you change the setting to point to a different file, the extension reloads and watches the new file automatically.
Commands
This extension contributes the following commands, accessible via the Command Palette (Cmd+Shift+P or Ctrl+Shift+P):
vsc-hosanna-ui.navigateToRokuCode: Navigate to Roku Code
Jumps to the corresponding Roku code from your current context.vsc-hosanna-ui.navigateToSourceCode: Navigate to Source Code
Locates the original TypeScript source for transpiled code.vsc-hosanna-ui.toggleTranspiledCodeSync: Toggle Transpiled Code Sync
Enables or disables synchronization between Roku and TypeScript sources.transpiledCodeNavigator.toggleIgnoreWhiteSpaceInSelections: Toggle Ignore White Space In Selections
Adjusts selection behavior to ignore whitespace during navigation or syncing.extension.processJsonStyleFiles: Process JSON Style Files
Manually processes or reloads JSON style files (e.g., style.config.json) to update style maps.
Running the Extension
To get started:
- Install dependencies:
npm install
- Open the project in Visual Studio Code.
- Press the "Run" button in the VS Code debugger or launch the extension.
Note: Style maps now load automatically from the configured path. You can still run Process JSON Style Files to force a reload.
Known Issues
- Completions: Autocompletion can be inconsistent and may not always trigger as expected.
- TypeScript Navigation: Style navigation in TypeScript files occasionally fails to resolve correctly.
Extension Settings
This extension provides the following settings:
vsc-hosanna-ui.buildFolder: Path to transpiled build files (used by navigation helpers).transpiledCodeNavigator.ignoreWhiteSpaceInSelections: Ignore whitespace when selecting ranges.vsc-hosanna-ui.propRegex: Regex to match props for language extraction.vsc-hosanna-ui.jsonFilePath (new): Path to the style JSON file. Defaults to ./assets/meta/style.config.json relative to each workspace folder. Accepts absolute paths as well.vsc-hosanna-ui.jsonSection, vsc-hosanna-ui.keyPrefix, vsc-hosanna-ui.keySuffix, vsc-hosanna-ui.switchToJsonFile: Language extraction helpers.vsc-hosanna-ui.excludeDiagnosticsGlobs: Glob patterns for files to exclude from diagnostics.
Watching and Reloading
- When the configured style JSON file changes, the extension rebuilds the internal style map and JSON cache automatically.
- When
vsc-hosanna-ui.jsonFilePath is changed, the extension reloads and begins watching the new file path for each workspace folder.
Release Notes
0.2.2
- Added configurable style JSON path with automatic reloads and file watching.
0.2.1
- Various improvements and diagnostics.
Following Extension Guidelines
Ensure your development adheres to VS Code's best practices:
Working with Markdown
Author this README in Visual Studio Code with these handy shortcuts:
- Split editor:
Cmd+\ (macOS) or Ctrl+\ (Windows/Linux).
- Toggle preview:
Shift+Cmd+V (macOS) or Shift+Ctrl+V (Windows/Linux).
- Markdown snippets:
Ctrl+Space (all platforms).
Embedded Documentation
The extension includes rich embedded documentation accessible through:
- Welcome Screen: Automatically appears on first install or after updates (can be disabled)
- Documentation Panel: Access via Command Palette → "Hosanna UI: Open Hosanna Documentation"
- What's New View: Located in VS Code Explorer sidebar showing key features
- Hosanna UI Docs: Direct link to official Hosanna UI documentation
- API Reference: Direct link to Hosanna UI API documentation
Enjoy!
