nn-widgets 0.1.0

package/README.md

@@ -0,0 +1,577 @@
+# nn-widgets
+
+Expo config plugin for native widgets — iOS WidgetKit & Android App Widgets.
+
+Supports four widget types:
+
+| Type       | Description                                             | Data Source                 |
+| ---------- | ------------------------------------------------------- | --------------------------- |
+| `"image"`  | Full-bleed background image                             | Static asset at build time  |
+| `"single"` | Icon + Title + Subtitle + Value                         | `updateWidget()` at runtime |
+| `"list"`   | Vertical list of items with icon/title/description      | `updateWidget()` at runtime |
+| `"grid"`   | Grid of items, each cell with icon on top + title below | `updateWidget()` at runtime |
+
+---
+
+## Installation
+
+```bash
+npx expo install nn-widgets
+```
+
+## Quick Start
+
+### 1. Configure in `app.json`
+
+```json
+{
+  "plugins": [
+    [
+      "nn-widgets",
+      {
+        "widgets": [
+          {
+            "name": "QuickActions",
+            "displayName": "Quick Actions",
+            "type": "list",
+            "deepLinkUrl": "myapp://widget",
+            "widgetFamilies": ["systemMedium", "systemLarge"],
+            "fallbackTitle": "Quick Actions",
+            "fallbackSubtitle": "Open app to set up",
+            "style": {
+              "backgroundColor": "#1E1E2E",
+              "titleColor": "#CDD6F4",
+              "subtitleColor": "#A6ADC8",
+              "accentColor": "#F38BA8"
+            }
+          }
+        ],
+        "ios": {
+          "devTeam": "YOUR_TEAM_ID",
+          "useAppGroups": true
+        }
+      }
+    ]
+  ]
+}
+```
+
+### 2. Push data from your app
+
+```ts
+import { NNWidgets } from "nn-widgets";
+
+await NNWidgets.updateWidget("QuickActions", {
+  items: [
+    {
+      icon: "star.fill",
+      title: "Morning Focus",
+      description: "25 min session",
+      deepLink: "myapp://session/123",
+    },
+    {
+      icon: { url: "brain", size: 28, radius: 14, backgroundColor: "#3B3B5C" },
+      title: { text: "Brainstorm", color: "#F38BA8", fontWeight: "bold" },
+      description: { text: "15 min", fontSize: "caption" },
+    },
+  ],
+});
+```
+
+### 3. Rebuild
+
+```bash
+npx expo prebuild --clean
+npx expo run:ios
+```
+
+---
+
+## Plugin Configuration
+
+### `widgets[]` — Per-widget config
+
+| Property           | Type                            | Default                                        | Description                                       |
+| ------------------ | ------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
+| `name`             | `string`                        | **required**                                   | Unique identifier (valid Swift/Kotlin identifier) |
+| `displayName`      | `string`                        | **required**                                   | Name shown in widget gallery                      |
+| `description`      | `string`                        | `"A widget for your app"`                      | Description in widget gallery                     |
+| `type`             | `"single" \| "list" \| "image"` | auto-detect                                    | Widget display type                               |
+| `deepLinkUrl`      | `string`                        | —                                              | URL opened when widget is tapped                  |
+| `showAppIcon`      | `boolean`                       | `true`                                         | Show app icon in widget UI                        |
+| `widgetFamilies`   | `string[]`                      | `["systemSmall","systemMedium","systemLarge"]` | Supported sizes (iOS)                             |
+| `fallbackTitle`    | `string`                        | `displayName`                                  | Title shown when no data set                      |
+| `fallbackSubtitle` | `string`                        | `"Open app to start"`                          | Subtitle shown when no data set                   |
+| `image`            | `object \| string`              | —                                              | Background image paths (image type)               |
+| `icons`            | `Record<string, string>`        | —                                              | Bundled icon images (name → path)                 |
+| `style`            | `object`                        | —                                              | Widget-level colors                               |
+| `android`          | `object`                        | —                                              | Android-specific overrides                        |
+
+#### `type` auto-detection
+
+- If `image` prop is set → `"image"`
+- Otherwise → `"single"`
+- Set `type: "list"` explicitly for list widgets
+- Set `type: "grid"` explicitly for grid widgets
+
+#### `gridLayout` (for type `"grid"`)
+
+Format: `"COLUMNSxROWS"` — controls the grid dimensions.
+
+```json
+{ "gridLayout": "3x2" }
+```
+
+| Value   | Columns | Rows | Max Items |
+| ------- | ------- | ---- | --------- |
+| `"2x2"` | 2       | 2    | 4         |
+| `"3x2"` | 3       | 2    | 6         |
+| `"4x2"` | 4       | 2    | 8         |
+| `"2x3"` | 2       | 3    | 6         |
+
+If omitted, columns auto-adjust based on widget family:
+- `systemSmall`: 2 columns
+- `systemMedium`: 4 columns
+- `systemLarge`: 4 columns
+
+#### `image` (for type `"image"`)
+
+```json
+{
+  "image": {
+    "small": "./assets/widgets/bg-small.png",
+    "medium": "./assets/widgets/bg-medium.png",
+    "large": "./assets/widgets/bg-large.png"
+  }
+}
+```
+
+Or a single image for all sizes: `"image": "./assets/widgets/bg.png"`
+
+#### `icons` (for type `"list"` / `"single"`)
+
+Bundle icon images at build time. Referenced by name at runtime.
+
+```json
+{
+  "icons": {
+    "brainstorm": "./assets/widgets/icons/brainstorm.png",
+    "meditation": "./assets/widgets/icons/meditation.png",
+    "focus": "./assets/widgets/icons/focus.png"
+  }
+}
+```
+
+At runtime, use the icon name:
+
+```ts
+{ icon: 'brainstorm', title: 'Morning Focus' }
+```
+
+On iOS, the icon is checked: if a bundled image matches the name, it's used as `Image(name)`. Otherwise, it's treated as an SF Symbol (`Image(systemName:)`).
+
+#### `style`
+
+```json
+{
+  "style": {
+    "backgroundColor": "#1E1E2E",
+    "titleColor": "#CDD6F4",
+    "subtitleColor": "#A6ADC8",
+    "accentColor": "#F38BA8"
+  }
+}
+```
+
+These provide widget-level defaults. Items can override per-item via `WidgetItemText` objects.
+
+### `ios` — Shared iOS config
+
+| Property             | Type      | Default            | Description                              |
+| -------------------- | --------- | ------------------ | ---------------------------------------- |
+| `deploymentTarget`   | `string`  | `"17.0"`           | Minimum iOS version for widget extension |
+| `useAppGroups`       | `boolean` | `true`             | Enable App Groups for data sharing       |
+| `appGroupIdentifier` | `string`  | `group.{bundleId}` | Custom App Group ID                      |
+| `devTeam`            | `string`  | —                  | Apple development team ID                |
+
+> **Important:** `useAppGroups: true` requires the App Group capability to be configured in your Apple Developer account. For local development without provisioning, set `useAppGroups: false` (widget won't receive data from the app).
+
+### `android` — Shared Android config
+
+| Property             | Type     | Default                  | Description                       |
+| -------------------- | -------- | ------------------------ | --------------------------------- |
+| `minSdkVersion`      | `number` | `26`                     | Minimum SDK for widget            |
+| `updatePeriodMillis` | `number` | `1800000`                | Auto-update interval (min 30 min) |
+| `minWidth`           | `number` | `110`                    | Default widget width in dp        |
+| `minHeight`          | `number` | `40`                     | Default widget height in dp       |
+| `resizeMode`         | `string` | `"horizontal\|vertical"` | Resize behavior                   |
+
+---
+
+## Runtime API
+
+### `NNWidgets.updateWidget(widgetName, data)`
+
+Push structured data to a specific widget and reload its timeline.
+
+```ts
+import { NNWidgets } from "nn-widgets";
+
+// List-type widget
+await NNWidgets.updateWidget("SessionsList", {
+  items: [
+    {
+      icon: "star.fill",
+      title: "Morning Focus",
+      description: "25 min",
+      deepLink: "myapp://session/1",
+    },
+    {
+      icon: { url: "meditation", size: 28, radius: 14 },
+      title: { text: "Wind Down", color: "#CDD6F4", fontWeight: "bold" },
+      description: { text: "15 min", color: "#A6ADC8", fontSize: "caption" },
+    },
+  ],
+});
+
+// Single-type widget
+await NNWidgets.updateWidget("StatsWidget", {
+  title: "Focus Time",
+  subtitle: "This week",
+  value: 142,
+});
+```
+
+#### `WidgetDataPayload`
+
+| Field      | Type               | Used by                 | Description           |
+| ---------- | ------------------ | ----------------------- | --------------------- |
+| `title`    | `string`           | single, list (fallback) | Title text            |
+| `subtitle` | `string`           | single, list (fallback) | Subtitle text         |
+| `value`    | `number`           | single                  | Numeric display value |
+| `items`    | `WidgetListItem[]` | list                    | Array of list items   |
+
+#### `WidgetListItem`
+
+| Field         | Type                       | Default      | Description                     |
+| ------------- | -------------------------- | ------------ | ------------------------------- |
+| `icon`        | `string \| WidgetItemIcon` | —            | Left icon (name or config)      |
+| `rightIcon`   | `string \| WidgetItemIcon` | —            | Right icon (name or config)     |
+| `title`       | `string \| WidgetItemText` | **required** | Title text or styled text       |
+| `description` | `string \| WidgetItemText` | —            | Description text or styled text |
+| `deepLink`    | `string`                   | —            | Per-item deep link URL          |
+
+#### `WidgetItemIcon` (object form)
+
+| Field             | Type     | Default      | Description                         |
+| ----------------- | -------- | ------------ | ----------------------------------- |
+| `url`             | `string` | **required** | SF Symbol name or bundled icon name |
+| `size`            | `number` | `32`         | Icon size in points/dp              |
+| `radius`          | `number` | `0`          | Corner radius (size/2 = circle)     |
+| `backgroundColor` | `string` | —            | Background color (hex)              |
+
+**Icon styling examples:**
+
+```ts
+// Simple SF Symbol (default size 32, no background)
+icon: "star.fill"
+
+// Circular icon with background
+icon: { url: "star.fill", size: 40, radius: 20, backgroundColor: "#FFD700" }
+
+// Square icon with rounded corners
+icon: { url: "brain", size: 36, radius: 8, backgroundColor: "#3B3B5C" }
+
+// Right icon (e.g. chevron indicator)
+rightIcon: { url: "chevron.right", size: 20, radius: 0 }
+
+// Right icon as circular badge
+rightIcon: { url: "checkmark.circle.fill", size: 24, radius: 12, backgroundColor: "#4CAF50" }
+```
+
+Both `icon` (left) and `rightIcon` (right) accept the same format — either a string or a `WidgetItemIcon` object.
+
+#### `WidgetItemText` (object form)
+
+| Field        | Type               | Default                                      | Description      |
+| ------------ | ------------------ | -------------------------------------------- | ---------------- |
+| `text`       | `string`           | **required**                                 | Text content     |
+| `color`      | `string`           | widget style                                 | Text color (hex) |
+| `fontSize`   | `WidgetFontSize`   | `"subheadline"` (title) / `"caption"` (desc) | Font size key    |
+| `fontWeight` | `WidgetFontWeight` | `"semibold"` (title) / `"regular"` (desc)    | Font weight      |
+
+### Font Size Reference
+
+| Key           | iOS (SwiftUI)           | Android (sp) |
+| ------------- | ----------------------- | ------------ |
+| `caption2`    | `.caption2` (11pt)      | 11sp         |
+| `caption`     | `.caption` (12pt)       | 12sp         |
+| `footnote`    | `.footnote` (13pt)      | 13sp         |
+| `subheadline` | `.subheadline` (15pt)   | 15sp         |
+| `body`        | `.body` (17pt)          | 17sp         |
+| `headline`    | `.headline` (17pt bold) | 17sp bold    |
+| `title3`      | `.title3` (20pt)        | 20sp         |
+| `title2`      | `.title2` (22pt)        | 22sp         |
+| `title`       | `.title` (28pt)         | 28sp         |
+
+### Font Weight Reference
+
+| Key        | iOS         | Android                 |
+| ---------- | ----------- | ----------------------- |
+| `regular`  | `.regular`  | `Typeface.NORMAL`       |
+| `medium`   | `.medium`   | `Typeface.NORMAL` + 500 |
+| `semibold` | `.semibold` | `Typeface.BOLD`         |
+| `bold`     | `.bold`     | `Typeface.BOLD`         |
+
+### Max Items per Widget Size (iOS)
+
+| Size               | Max Items |
+| ------------------ | --------- |
+| `systemSmall`      | 3         |
+| `systemMedium`     | 3         |
+| `systemLarge`      | 7         |
+| `systemExtraLarge` | 7         |
+
+### Other API Methods
+
+```ts
+// Legacy flat key-value data (backward compatible)
+await NNWidgets.setWidgetData({ key: "value", count: 42 });
+
+// Get stored data
+const data = await NNWidgets.getWidgetData();
+
+// Reload a specific widget
+await NNWidgets.reloadWidget({ widgetName: "MyWidget" });
+
+// Reload all widgets
+await NNWidgets.reloadWidget();
+
+// Check support
+const supported = NNWidgets.isSupported();
+```
+
+---
+
+## How Data Flows
+
+```
+┌──────────────────────┐
+│   React Native App   │
+│                      │
+│  NNWidgets.update    │
+│  Widget("List", {    │
+│    items: [...]      │
+│  })                  │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│   Native Module      │
+│   (NNWidgetsModule)  │
+│                      │
+│  Stores key-value    │
+│  pairs to shared     │
+│  storage             │
+│                      │
+│  iOS: UserDefaults   │
+│    (App Groups)      │
+│  Android: Shared     │
+│    Preferences       │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│   Widget Extension   │
+│   (TimelineProvider) │
+│                      │
+│  Reads items JSON    │
+│  from shared storage │
+│  Parses & renders    │
+│  the widget UI       │
+└──────────────────────┘
+```
+
+### Key Naming Convention
+
+Data is stored with the `widget_` prefix:
+
+| JS call                                    | Storage key           | Widget reads                |
+| ------------------------------------------ | --------------------- | --------------------------- |
+| `updateWidget("MyList", { title: "Hi" })`  | `widget_MyList_title` | `getString("MyList_title")` |
+| `updateWidget("MyList", { items: [...] })` | `widget_MyList_items` | `getJSON("MyList_items")`   |
+| `setWidgetData({ foo: "bar" })`            | `widget_foo`          | `getString("foo")`          |
+
+---
+
+## Full Example: `app.json`
+
+```json
+{
+  "plugins": [
+    [
+      "nn-widgets",
+      {
+        "widgets": [
+          {
+            "name": "MainWidget",
+            "displayName": "My App",
+            "type": "single",
+            "deepLinkUrl": "myapp://widget",
+            "showAppIcon": true,
+            "widgetFamilies": ["systemSmall"]
+          },
+          {
+            "name": "RecentSessions",
+            "displayName": "Recent Sessions",
+            "type": "list",
+            "deepLinkUrl": "myapp://sessions",
+            "widgetFamilies": ["systemMedium", "systemLarge"],
+            "fallbackTitle": "Recent Sessions",
+            "fallbackSubtitle": "Open app to see sessions",
+            "icons": {
+              "focus": "./assets/widgets/icons/focus.png",
+              "relax": "./assets/widgets/icons/relax.png"
+            },
+            "style": {
+              "backgroundColor": "#1E1E2E",
+              "titleColor": "#CDD6F4",
+              "subtitleColor": "#A6ADC8",
+              "accentColor": "#F38BA8"
+            }
+          },
+          {
+            "name": "BannerWidget",
+            "displayName": "Banner",
+            "deepLinkUrl": "myapp://banner",
+            "widgetFamilies": ["systemMedium"],
+            "image": {
+              "medium": "./assets/widgets/banner.png"
+            }
+          },
+          {
+            "name": "QuickGrid",
+            "displayName": "Quick Grid",
+            "type": "grid",
+            "gridLayout": "3x2",
+            "deepLinkUrl": "myapp://grid",
+            "widgetFamilies": ["systemMedium", "systemLarge"],
+            "fallbackTitle": "Quick Grid",
+            "fallbackSubtitle": "Open app to set up",
+            "style": {
+              "backgroundColor": "#1A1A2E",
+              "titleColor": "#E0E0E0",
+              "accentColor": "#BB86FC"
+            }
+          }
+        ],
+        "ios": {
+          "devTeam": "YOUR_TEAM_ID",
+          "useAppGroups": true,
+          "appGroupIdentifier": "group.com.myapp"
+        }
+      }
+    ]
+  ]
+}
+```
+
+## Full Example: Pushing data from a screen
+
+```tsx
+import React, { useEffect } from 'react';
+import { NNWidgets } from 'nn-widgets';
+
+function SessionsScreen({ sessions }) {
+  useEffect(() => {
+    // Update list widget with styled icons
+    NNWidgets.updateWidget('RecentSessions', {
+      items: sessions.slice(0, 7).map((s) => ({
+        icon: { url: s.type, size: 32, radius: 8, backgroundColor: '#3B3B5C' },
+        title: { text: s.name, fontWeight: 'semibold' },
+        description: { text: `${s.duration} min`, fontSize: 'caption' },
+        rightIcon: { url: 'chevron.right', size: 16 },
+        deepLink: `myapp://session/${s.id}`,
+      })),
+    });
+  }, [sessions]);
+
+  return (/* ... */);
+}
+```
+
+## Full Example: Grid widget data
+
+```tsx
+// Grid widget with 3x2 layout (3 columns, 2 rows, max 6 items)
+await NNWidgets.updateWidget('QuickGrid', {
+  items: [
+    {
+      icon: { url: 'star.fill', size: 40, radius: 20, backgroundColor: '#FFD700' },
+      title: 'Favorites',
+      deepLink: 'myapp://favorites',
+    },
+    {
+      icon: { url: 'clock.fill', size: 40, radius: 20, backgroundColor: '#4A90D9' },
+      title: 'Recent',
+      deepLink: 'myapp://recent',
+    },
+    {
+      icon: { url: 'bolt.fill', size: 40, radius: 20, backgroundColor: '#FF6B6B' },
+      title: 'Quick Start',
+      deepLink: 'myapp://quick',
+    },
+    {
+      icon: { url: 'person.2.fill', size: 40, radius: 20, backgroundColor: '#66BB6A' },
+      title: 'Team',
+      deepLink: 'myapp://team',
+    },
+    {
+      icon: { url: 'chart.bar.fill', size: 40, radius: 20, backgroundColor: '#AB47BC' },
+      title: 'Stats',
+      deepLink: 'myapp://stats',
+    },
+    {
+      icon: { url: 'gearshape.fill', size: 40, radius: 20, backgroundColor: '#78909C' },
+      title: 'Settings',
+      deepLink: 'myapp://settings',
+    },
+  ],
+});
+```
+
+---
+
+## Troubleshooting
+
+### Widget shows fallback text ("Open app to start")
+
+- The app hasn't called `updateWidget()` yet, or `useAppGroups` is `false`
+- Ensure `useAppGroups: true` in `ios` config and the App Group is provisioned
+
+### Widget doesn't update after calling `updateWidget()`
+
+- `updateWidget()` automatically calls `reloadWidget()` after storing data
+- iOS may delay widget updates. Force refresh by removing and re-adding the widget
+
+### Build error: "App Group not configured"
+
+- Add the App Group capability in Apple Developer portal
+- The App Group ID must match `appGroupIdentifier` (default: `group.{bundleIdentifier}`)
+- For local dev without provisioning, set `useAppGroups: false`
+
+### Icons not showing
+
+- Bundled icons: ensure paths in `icons` config are correct and files exist
+- SF Symbols: use exact symbol names (e.g., `"star.fill"`, not `"star"`)
+- Android: icon names are lowercased for drawable resources
+
+## Requirements
+
+- Expo SDK 53+
+- iOS 17.0+ (for WidgetKit)
+- Android API 26+ (for App Widgets)
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,90 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'maven-publish'
+
+group = 'expo.modules.nnwidgets'
+version = '0.1.0'
+
+buildscript {
+  def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+  if (expoModulesCorePlugin.exists()) {
+    apply from: expoModulesCorePlugin
+    applyKotlinExpoModulesCorePlugin()
+  }
+
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+
+  ext.getKotlinVersion = {
+    if (ext.has("kotlinVersion")) {
+      ext.kotlinVersion()
+    } else {
+      ext.safeExtGet("kotlinVersion", "1.8.10")
+    }
+  }
+
+  repositories {
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${getKotlinVersion()}")
+  }
+}
+
+afterEvaluate {
+  publishing {
+    publications {
+      release(MavenPublication) {
+        from components.release
+      }
+    }
+    repositories {
+      maven {
+        url = mavenLocal().url
+      }
+    }
+  }
+}
+
+android {
+  namespace = "expo.modules.nnwidgets"
+
+  compileSdkVersion safeExtGet("compileSdkVersion", 34)
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = JavaVersion.VERSION_17.majorVersion
+  }
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 26)
+    targetSdkVersion safeExtGet("targetSdkVersion", 34)
+    versionCode 1
+    versionName "0.1.0"
+  }
+
+  lintOptions {
+    abortOnError false
+  }
+
+  publishing {
+    singleVariant("release") {
+      withSourcesJar()
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  implementation project(':expo-modules-core')
+  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${getKotlinVersion()}"
+}

package/app.plugin.js

@@ -0,0 +1,4 @@
+// nn-widgets Expo Config Plugin Entry Point
+// This file loads the compiled plugin from the plugin/build directory
+
+module.exports = require("./plugin/build").default;