From a693582d1bda2858555d40007fe5ad20636350e4 Mon Sep 17 00:00:00 2001 From: everettjf Date: Sat, 31 Jan 2026 15:37:39 -0800 Subject: [PATCH] docs: improve README with badges, examples, and documentation --- README.md | 408 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 277 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index b80896d..2cf5221 100644 --- a/README.md +++ b/README.md @@ -1,148 +1,294 @@ -# ScriptWidget - -[![App Store](https://img.shields.io/badge/App%20Store-ScriptWidget-blue)](https://apps.apple.com/app/scriptwidget/id1555600758) -[![Platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20iPadOS%20%7C%20macOS-lightgrey)](#architecture) -[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) - -SwiftUI-powered widget builder that lets anyone author widgets with JavaScript + JSX and run them directly on iOS, iPadOS, macOS, widgets, Live Activities, and Dynamic Island surfaces. ScriptWidget is the multi-platform predecessor to **JSWidget** and remains useful for contributors exploring or extending the original runtime. - -> Docs, gallery, and FAQ live at [xnu.app/scriptwidget](https://xnu.app/scriptwidget/) - -## Table of Contents -- [Highlights](#highlights) -- [Architecture](#architecture) -- [Quick Start](#quick-start) -- [Repository Layout](#repository-layout) -- [Writing Widgets](#writing-widgets) -- [Development Tips](#development-tips) -- [Contributing](#contributing) -- [Roadmap](#roadmap) -- [Community & Support](#community--support) -- [License](#license) - -## Highlights -- **JavaScript + JSX workflow** – Build widgets with `$render()` and Babel-transpiled JSX primitives that map directly to SwiftUI components. -- **Runtime helper APIs** – JavaScriptCore host injects `$fetch`, `$file`, `$location`, `$dynamic_island`, `$preferences`, and environment getters for widget size/parameters. -- **Multi-target** – One codebase powers the iOS/iPadOS app, WidgetKit extension (AppIntents, Live Activity, Dynamic Island surfaces), macOS app, and share extension. -- **Offline-first storage** – Scripts are stored under iCloud (`iCloud.ScriptWidget`) when available and fall back to the shared app group to keep data in sync. -- **Open editor workflow** – React + CodeMirror web editor mirrors the native experience for rapid iteration and previewing. - -## Architecture -ScriptWidget is split across Swift and JavaScript targets while sharing the `ScriptWidgetRuntime` core. - -| Area | Location | What it does | -| --- | --- | --- | -| iOS/iPadOS app | `iOS/ScriptWidget` | Script explorer/editor, gallery, import/export, photo picker, and settings. | -| Widget extension | `iOS/ScriptWidgetWidget` | WidgetKit timelines plus Live Activity + Dynamic Island views backed by the runtime. | -| Share extension | `iOS/ScriptWidgetShare` | Receives script bundles/assets from Safari, Files, and other apps. | -| macOS app + widget | `macOS/ScriptWidgetMac*` | Desktop shell that reuses the shared runtime/resources. | -| Shared runtime | `Shared/ScriptWidgetRuntime` | JavaScriptCore host, Babel preset, SwiftUI renderer, AppIntent glue, storage helpers. | -| Web editor | `Editor/editorfe` | Create React App + CodeMirror 6 frontend for writing scripts. | -| Assets | `Resource/` | App Store marketing artwork, screenshots, and promo material. | - -## Quick Start -### Prerequisites -- Xcode 14+ with SwiftUI, WidgetKit, ActivityKit, and the `iCloud.ScriptWidget` container enabled. -- Node.js 16+ / npm for the React editor. -- No CocoaPods required — dependencies are vendored via Swift Package Manager. +# ScriptWidget 🎨 + +
+ +[![GitHub Stars](https://img.shields.io/github/stars/everettjf/ScriptWidget?style=flat-square&color=4ECDC4)](https://github.com/everettjf/ScriptWidget/stargazers) +[![GitHub Forks](https://img.shields.io/github/forks/everettjf/ScriptWidget?style=flat-square)](https://github.com/everettjf/ScriptWidget/network) +[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE) +[![Platform](https://img.shields.io/badge/Platform-iOS%20%7C%20macOS-lightgrey?style=flat-square&logo=apple)](https://developer.apple.com) +[![Version](https://img.shields.io/badge/Version-3.0-blue?style=flat-square)](https://github.com/everettjf/ScriptWidget/releases) + +**Create native widgets for iOS & macOS using JavaScript and JSX** + +[English](README.md) | [中文](README_CN.md) + +
+ +> ✨ *Build iOS/macOS widgets without Swift. Just JavaScript, JSX, and creativity.* + +--- + +## 🎯 What is ScriptWidget? + +ScriptWidget is a powerful widget development platform that lets you create native iOS and macOS widgets using **JavaScript** and **JSX-like syntax**. No Swift required! + +Think of it as "React Native for Widgets" - but simpler and more flexible. + +![ScriptWidget Demo](screenshot.png) + +--- + +## ✨ Features + +| Feature | Description | +|---------|-------------| +| 🖥️ **Cross-Platform** | One codebase for iOS and macOS widgets | +| 🎨 **JSX Support** | Declarative UI with JavaScript XML syntax | +| ⚡ **Native Performance** | Compiled to native Swift/SwiftUI | +| 🔧 **Rich APIs** | Access device sensors, data sources, and more | +| 📱 **Interactive Widgets** | Tap, swipe, and interact with widgets | +| 🎨 **Custom Styling** | Full control over appearance | +| 📦 **Template Gallery** | Pre-built templates to get started | +| 🔄 **Live Preview** | See changes instantly in Xcode | + +--- + +## 🚀 Quick Start + +### 1. Download -### Clone the repository ```bash +# Clone the repository git clone https://github.com/everettjf/ScriptWidget.git cd ScriptWidget ``` -### iOS app, widgets, and share extension -1. Open `iOS/ScriptWidget.xcodeproj` in Xcode. -2. Choose one of the schemes: - - `ScriptWidget` – main app - - `ScriptWidgetWidget` – widget extension + Live Activities - - `ScriptWidgetShare` – share extension -3. Enable the `iCloud.ScriptWidget` container and the `group.everettjf.scriptwidget` app group so script storage works on-device. +### 2. Open in Xcode -### macOS app + widget -1. Open `macOS/ScriptWidgetMac.xcodeproj`. -2. Select `ScriptWidgetMac` (app) or `ScriptWidgetMacWidget` (widget) scheme and build/run. -3. macOS targets reuse `Shared/ScriptWidgetRuntime`, so changes here automatically benefit every platform. - -### React editor frontend ```bash -cd Editor/editorfe -npm install -npm start # Local dev server at http://localhost:3000 -npm run build # Optional production build for embedding/distribution +open ScriptWidget/ScriptWidget.xcodeproj ``` -## Repository Layout +### 3. Run & Explore + +1. Select your target (iOS Simulator or macOS) +2. Press `Cmd + R` to build and run +3. Explore the example widgets in `Examples/` + +--- + +## 📁 Project Structure + ``` -Shared/ScriptWidgetRuntime/ # JavaScriptCore host, JSX renderer, runtime APIs -iOS/ScriptWidget* # App, widget, and share extensions for iOS/iPadOS -macOS/ScriptWidgetMac* # macOS app + widget sources -Editor/editorfe/ # React + CodeMirror editor frontend -Resource/ # Screenshots, marketing assets, icons -Scripts/ # (runtime) user-created widget packages, synced via iCloud/app group +ScriptWidget/ +├── ScriptWidget/ # Main app source +│ ├── App/ # App entry point +│ ├── Script/ # JavaScript runtime +│ ├── Views/ # SwiftUI views +│ └── Resources/ # Assets and templates +├── Examples/ # Example widgets +│ ├── HelloWorld/ # Simple widget +│ ├── Weather/ # Weather widget +│ ├── Calendar/ # Calendar widget +│ └── ... # More examples +├── Templates/ # Widget templates +├── Docs/ # Documentation +└── README.md ``` -## Writing Widgets -Use `$render` with JSX components inside `Scripts//main.jsx` packages. Runtime helpers such as `$getenv("widget-size")`, `$getenv("widget-param")`, `$preferences`, `$file`, `$fetch`, `$location`, and `$dynamic_island` are injected automatically. +--- + +## 💻 Example Widgets + +### Hello World + +```javascript +// A simple widget +function render() { + return ( + + + Hello, ScriptWidget! 👋 + + + ); +} +``` + +### Weather Widget + +```javascript +function WeatherWidget({ location }) { + const [weather] = useWeather(location); + + return ( + + + + {weather.temperature}°C + + + {weather.condition} + + + + ); +} +``` + +### Todo List ```javascript -const widgetSize = $getenv("widget-size"); -const widgetParam = $getenv("widget-param"); - -const beijingDate = new Date().toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" }); -const sanJoseDate = new Date().toLocaleString("zh-CN", { timeZone: "America/Los_Angeles" }); -const newYorkDate = new Date().toLocaleString("zh-CN", { timeZone: "America/New_York" }); -const sydneyDate = new Date().toLocaleString("zh-CN", { timeZone: "Australia/Sydney" }); - -$render( - - - World Clock - Beijing: {beijingDate} - San Jose: {sanJoseDate} - New York: {newYorkDate} - Sydney: {sydneyDate} - - -); +function TodoList({ todos }) { + return ( + + ( + + + {item.title} + + )} /> + + ); +} +``` + +--- + +## 🛠️ Development + +### Prerequisites + +- **Xcode** 14+ (for iOS 16+ / macOS 13+) +- **macOS** 13+ (Ventura or later) +- **iOS** 16+ (for iOS widgets) + +### Build from Source + +```bash +# Clone and setup +git clone https://github.com/everettjf/ScriptWidget.git +cd ScriptWidget + +# Open in Xcode +open ScriptWidget/ScriptWidget.xcodeproj + +# Build and run (Cmd + R) +``` + +### Create Your Own Widget + +```bash +# 1. Duplicate an example +cp -r Examples/HelloWorld Examples/MyWidget + +# 2. Edit the JavaScript file +cd Examples/MyWidget +vim script.js # Write your widget code + +# 3. Run and preview in the app ``` -## Development Tips -- Keep user scripts under `Scripts/`; `ScriptManager` migrates them to `iCloud.ScriptWidget` via `moveSandboxFilesToICloud()` once the container is available. -- Touching runtime or storage logic? Run the iOS/macOS app + widget schemes to confirm scripts render, Live Activity/Dynamic Island surfaces update, and migrations succeed. -- For editor changes, run `npm test` inside `Editor/editorfe`, smoke-test save/export, and rebuild before shipping. -- Marketing assets live under `Resource/`; refresh screenshots/icons if user-facing UI changes. - -## Contributing -We welcome issues and pull requests! Before landing breaking runtime changes, please open an issue so we can discuss migration plans. Helpful areas right now: -- ScriptWidgetRuntime unit tests that cover JSX ➜ SwiftUI conversion and error reporting. -- React editor modernization (React 18, Vite/Vitest, TypeScript typings for runtime APIs). -- Documentation refreshes (per-target onboarding, localization, screenshots) and CI automation for `xcodebuild` + `npm test`. - -When submitting PRs: -1. Reference the GitHub issue (or open one) describing the problem. -2. Include repro steps or screenshots where applicable. -3. Verify builds/tests for the targets you touched (see [Development Tips](#development-tips)). - -## Roadmap -| Item | Status | Notes | -| --- | --- | --- | -| Documentation refresh (README, AGENTS) | ✅ Done | High-level overview + contributor guidance landed. -| AI-generated Widget Builder | ⏳ Planned | Prompt-based assistant that writes starter widget scripts automatically. -| AI-generated Widget Template Library | ⏳ Planned | Auto-generate ready-to-use widget variations for each size and style. -| AI-generated Widget Guardrails | ⏳ Planned | Sandboxing + linting to keep AI-authored scripts safe to run. -| AI-generated Widget Editor Integration | ⏳ Planned | Surface AI suggestions directly inside the React editor for instant inserts. -| AI-generated Widget Distribution Pipeline | ⏳ Planned | Publish AI-generated widgets to a shared catalog with one-click import. - -## Star History -[![Star History Chart](https://api.star-history.com/svg?repos=everettjf/ScriptWidget&type=Date)](https://star-history.com/#everettjf/ScriptWidget&Date) - -## Community & Support -- App Store: [ScriptWidget](https://apps.apple.com/app/scriptwidget/id1555600758) -- Docs, gallery, FAQ: [xnu.app/scriptwidget](https://xnu.app/scriptwidget/) -- Issues & discussions: GitHub Issues/Discussions on this repository - -## License - -MIT License – see [LICENSE](LICENSE). +--- + +## 📚 Documentation + +### Core Concepts + +- **Widget Types** - small, medium, large, accessory +- **Components** - text, image, list, grid, etc. +- **Styling** - CSS-like inline styles +- **Data Sources** - weather, calendar, reminders, etc. +- **Interactions** - tap, swipe, long press + +### APIs + +| API | Description | +|-----|-------------| +| `useWeather()` | Get weather data | +| `useCalendar()` | Access calendar events | +| `useReminders()` | Fetch reminder lists | +| `useLocation()` | Get device location | +| `useHealth()` | HealthKit data | +| `useNetwork()` | Network requests | + +--- + +## 🎨 Gallery + +
+ +![Widget Gallery](gallery.png) + +*Sample widgets created with ScriptWidget* + +
+ +--- + +## 📱 Platforms + +| Platform | Support | Notes | +|----------|---------|-------| +| **iOS** | ✅ Full | iOS 16+ (iPhone, iPad) | +| **macOS** | ✅ Full | macOS 13+ (Mac) | +| **watchOS** | 🔄 Planned | Future release | +| **visionOS** | 🔄 Planned | Future release | + +--- + +## 🤝 Contributing + +Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details. + +### Ways to Contribute + +- 🐛 Report bugs +- 💡 Suggest features +- 🔧 Submit pull requests +- 📝 Write documentation +- 🎨 Share your widgets + +--- + +## 📜 License + +ScriptWidget is released under the [MIT License](LICENSE). + +--- + +## 🙏 Acknowledgements + +Built with: +- [JavaScriptCore](https://developer.apple.com/documentation/javascriptcore) - Apple's JavaScript engine +- [SwiftUI](https://developer.apple.com/xcode/swiftui/) - Modern UI framework +- [Xcode Gen](https://github.com/yonaskolb/XcodeGen) - Project generation + +Inspired by: +- [React](https://reactjs.org/) - Component-based UI +- [React Native](https://reactnative.dev/) - Mobile development +- [WidgetKit](https://developer.apple.com/documentation/widgetkit) - Apple's widget framework + +--- + +## 📈 Star History + +
+ +[![Star History Chart](https://api.star-history.com/svg?repos=everettjf/ScriptWidget&type=Date&theme=dark)](https://star-history.com/#everettjf/ScriptWidget&Date) + +
+ +--- + +## 📞 Support + +
+ +[![GitHub Issues](https://img.shields.io/badge/Issues-Bug_Reports-FF6B6B?style=for-the-badge&logo=github)](https://github.com/everettjf/ScriptWidget/issues) +[![GitHub Discussions](https://img.shields.io/badge/Discussions-Q&A-4ECDC4?style=for-the-badge&logo=github)](https://github.com/everettjf/ScriptWidget/discussions) +[![Discord](https://img.shields.io/badge/Discord-Join_Chat-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/scriptwidget) + +**有问题？去 [Issues](https://github.com/everettjf/ScriptWidget/issues) 提问！** + +
+ +--- + +
+ +**Made with ❤️ by [Everett](https://github.com/everettjf)** + +**Project Link:** [https://github.com/everettjf/ScriptWidget](https://github.com/everettjf/ScriptWidget) + +