Skip to content

docs(v2): trim, dedupe, and split the docs for clarity #241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
V3RON wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(v2): trim, dedupe, and split the docs for clarity #241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
56f71a0
docs(v2): trim, dedupe, and split the docs for clarity
V3RON Aug 13, 2026
d563c77
docs(v2): fix Expo SDK wording in prior art
V3RON Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions website/docs/v2/android/api/_meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
[
{
"type": "file",
"name": "plugin-configuration",
"label": "Plugin Configuration"
},
{
"type": "file",
"name": "widget-sizing-and-previews",
"label": "Widget Sizing & Previews"
}
]
140 changes: 2 additions & 138 deletions website/docs/v2/android/api/plugin-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,147 +104,11 @@ Fallback behavior:
- If there is still no match, it prefers an English locale such as `en` or `en-US`.
- If no English entry exists, it uses the first configured locale.

## Widget Sizing

### Grid Cells vs Density-Independent Pixels (dp)

Android uses grid cells to define widget sizes. By default, the formula is:
- **minWidth/minHeight (dp) = (cellCount × 70) - 30**

**Example:**
- 2 cells = (2 × 70) - 30 = **110 dp**
- 4 cells = (4 × 70) - 30 = **250 dp**

You can override this with explicit `minWidth` and `minHeight` in dp.

### Standard Dimensions

| Family | Cells | Default DP | Typical Use |
|--------|-------|-----------|-------------|
| Small | 2×1 | 110 × 40 | Quick glance info |
| Medium | 2×2 | 110 × 110 | Main widget size |
| Large | 4×2 | 250 × 110 | Rich content |
| Extra Large | 4×4 | 250 × 250 | Complex layouts |

## Widget Picker Previews

When users add a widget to their home screen, Android displays a preview in the widget picker. Voltra supports three preview methods, with automatic fallback:

### Preview Priority Chain

1. **`previewLayout`** (Android 12+) - Custom XML layout for scalable preview
2. **`previewImage`** (All versions) - Static image or auto-generated layout
3. **Default** - System placeholder layout

### Using `previewImage`

Static preview image for all Android versions:

```json
{
"widgets": [
{
"id": "weather",
"displayName": "Weather Widget",
"targetCellWidth": 2,
"targetCellHeight": 2,
"previewImage": "./assets/widgets/weather-preview.png"
}
]
}
```

When only `previewImage` is specified, Voltra automatically generates a layout that displays the image with proper scaling.

### Using `previewLayout`

Custom XML layout for scalable previews (Android 12+):

```json
{
"widgets": [
{
"id": "todos",
"displayName": "Todo Widget",
"targetCellWidth": 2,
"targetCellHeight": 2,
"previewLayout": "./assets/widgets/todos-preview.xml"
}
]
}
```

**Example `todos-preview.xml`:**

```xml
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
android:padding="16dp"
android:background="#FFFFFF">

<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="Todo List"
android:textSize="18sp"
android:textStyle="bold" />

<!-- Add more layout elements here -->

</LinearLayout>
```

The preview layout is rendered at the widget's target size and displayed in the widget picker.

### Combined Preview Setup

For best results across Android versions:

```json
{
"widgets": [
{
"id": "weather",
"displayName": "Weather Widget",
"targetCellWidth": 2,
"targetCellHeight": 2,
"previewImage": "./assets/widgets/weather-preview.png",
"previewLayout": "./assets/widgets/weather-preview.xml",
"initialStatePath": "./widgets/weather-initial.tsx"
}
]
}
```

This configuration:
- Uses `previewLayout` on Android 12+ (scalable, accurate preview)
- Falls back to `previewImage` on Android 11 and earlier
- Shows actual widget content on home screen via `initialStatePath` (when available)
For widget sizing math and widget-picker preview setup (`previewImage`, `previewLayout`), see [Widget Sizing & Previews](./widget-sizing-and-previews).

## Widget Pre-rendering

Use `initialStatePath` to provide pre-rendered widget state:

```json
{
"widgets": [
{
"id": "weather",
"displayName": "Weather Widget",
"targetCellWidth": 2,
"targetCellHeight": 2,
"initialStatePath": "./widgets/weather-initial.tsx"
}
]
}
```

When the app is built, Voltra pre-renders the widget at the specified path and bundles it as `voltra_initial_states.json`. The widget displays this content immediately when first added to the home screen, before any dynamic updates.

See [Widget Pre-rendering](../development/widget-pre-rendering) for details on creating initial state files.
Use `initialStatePath` to bundle pre-rendered widget state for the first time a widget is added to the home screen. See [Widget Pre-rendering](../development/widget-pre-rendering) for details.

## Example Configuration

Expand Down
115 changes: 115 additions & 0 deletions website/docs/v2/android/api/widget-sizing-and-previews.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# Widget Sizing & Previews (Android)

## Widget Sizing

### Grid Cells vs Density-Independent Pixels (dp)

Android uses grid cells to define widget sizes. By default:

- **minWidth/minHeight (dp) = (cellCount × 70) - 30**

For example, 2 cells comes out to 110 dp, and 4 cells to 250 dp.

You can override this with explicit `minWidth` and `minHeight` in dp.

### Standard Dimensions

| Family | Cells | Default DP | Typical Use |
|--------|-------|-----------|-------------|
| Small | 2×1 | 110 × 40 | Quick glance info |
| Medium | 2×2 | 110 × 110 | Main widget size |
| Large | 4×2 | 250 × 110 | Rich content |
| Extra Large | 4×4 | 250 × 250 | Complex layouts |

## Widget Picker Previews

When users add a widget to their home screen, Android displays a preview in the widget picker. Voltra supports three preview methods, with automatic fallback:

1. **`previewLayout`** (Android 12+) - Custom XML layout for scalable preview
2. **`previewImage`** (All versions) - Static image or auto-generated layout
3. **Default** - System placeholder layout

### Using `previewImage`

Static preview image for all Android versions:

```json
{
"widgets": [
{
"id": "weather",
"displayName": "Weather Widget",
"targetCellWidth": 2,
"targetCellHeight": 2,
"previewImage": "./assets/widgets/weather-preview.png"
}
]
}
```

When only `previewImage` is specified, Voltra automatically generates a layout that displays the image with proper scaling.

### Using `previewLayout`

Custom XML layout for scalable previews (Android 12+):

```json
{
"widgets": [
{
"id": "todos",
"displayName": "Todo Widget",
"targetCellWidth": 2,
"targetCellHeight": 2,
"previewLayout": "./assets/widgets/todos-preview.xml"
}
]
}
```

**Example `todos-preview.xml`:**

```xml
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
android:padding="16dp"
android:background="#FFFFFF">

<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:text="Todo List"
android:textSize="18sp"
android:textStyle="bold" />

<!-- Add more layout elements here -->

</LinearLayout>
```

The preview layout is rendered at the widget's target size and displayed in the widget picker.

### Combined Preview Setup

For best results across Android versions, provide both:

```json
{
"widgets": [
{
"id": "weather",
"displayName": "Weather Widget",
"targetCellWidth": 2,
"targetCellHeight": 2,
"previewImage": "./assets/widgets/weather-preview.png",
"previewLayout": "./assets/widgets/weather-preview.xml",
"initialStatePath": "./widgets/weather-initial.tsx"
}
]
}
```

This uses `previewLayout` on Android 12+, falls back to `previewImage` on Android 11 and earlier, and shows actual widget content on the home screen via `initialStatePath` once available.
45 changes: 2 additions & 43 deletions website/docs/v2/android/charts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@

Use charts in Android widgets to show trends, comparisons, progress, or composition at a glance. You can mix bars, lines, areas, points, rules, and sectors in a single chart.

:::info
Charts are rendered to a bitmap using the Android Canvas API and displayed as a Glance `Image`. This approach is required because Jetpack Glance has no native charting components.
:::

:::warning
Mark components (`BarMark`, `LineMark`, and the other mark types) must be direct children of `<VoltraAndroid.Chart>`. Do not wrap them in a custom component.
:::
Expand Down Expand Up @@ -49,9 +45,9 @@ type SectorDataPoint = {

## Marks

### BarMark
Pick the mark that fits your data: bars for comparing values across categories, lines for trends over time, areas for volume, points for sparse or scattered measurements, rules for reference lines, and sectors for pie/donut breakdowns.

Use bars when people need to compare values across categories.
### BarMark

**Parameters:**

Expand Down Expand Up @@ -79,8 +75,6 @@ Use bars when people need to compare values across categories.

### LineMark

Use a line when the shape of change matters more than individual columns.

**Parameters:**

- `data` (ChartDataPoint[], required): The data points.
Expand Down Expand Up @@ -109,8 +103,6 @@ Use a line when the shape of change matters more than individual columns.

### AreaMark

Use an area chart when you want the overall volume or rise/fall pattern to read quickly.

**Parameters:**

- `data` (ChartDataPoint[], required): The data points.
Expand All @@ -134,8 +126,6 @@ Use an area chart when you want the overall volume or rise/fall pattern to read

### PointMark

Use points for sparse measurements, scatter plots, or to emphasize exact observations.

**Parameters:**

- `data` (ChartDataPoint[], required): The data points.
Expand Down Expand Up @@ -232,20 +222,6 @@ The `<VoltraAndroid.Chart>` container accepts these props in addition to the sta
| `yAxisGridStyle` | `{ visible?: boolean }` | Show or hide y-axis grid lines |
| `foregroundStyleScale` | `Record<string, string>` | Map series names to colors |

## Grid Lines

Hide grid lines when you want the chart to feel more compact:

```tsx
<VoltraAndroid.Chart
style={{ width: '100%', height: '100%' }}
xAxisGridStyle={{ visible: false }}
yAxisGridStyle={{ visible: false }}
>
<VoltraAndroid.LineMark data={data} color="#4285f4" interpolation="monotone" />
</VoltraAndroid.Chart>
```

## Multi-Series Charts

Add a `series` field to your data points when you want multiple datasets in the same chart. Use `foregroundStyleScale` to keep those series colors consistent:
Expand Down Expand Up @@ -292,23 +268,6 @@ Mix mark types when one chart needs both context and emphasis, such as bars for
</VoltraAndroid.Chart>
```

## Sparkline / Minimal Style

Hide axes for a clean, compact visualization:

```tsx
<VoltraAndroid.Chart
style={{ width: '100%', height: '100%' }}
xAxisVisibility="hidden"
yAxisVisibility="hidden"
>
<VoltraAndroid.AreaMark
data={data}
color="#4285f4"
/>
</VoltraAndroid.Chart>
```

## Sizing

Chart dimensions are read from the `style` prop:
Expand Down
Loading
Loading