Skip to content

Commit b4def29

Browse files
RockerFlowerRockerFlower
committed
Improve docs, demo, and publish workflow
1 parent ad89519 commit b4def29

7 files changed

Lines changed: 1597 additions & 297 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,31 @@ on:
88

99
jobs:
1010
publish:
11+
name: Publish to pub.dev
1112
permissions:
1213
contents: read
1314
id-token: write
14-
uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
15-
with:
16-
# Specify the github actions deployment environment
17-
environment: pub.dev
18-
# working-directory: path/to/package/within/repository
15+
runs-on: ubuntu-latest
16+
environment: pub.dev
17+
18+
steps:
19+
- uses: actions/checkout@v6
20+
21+
- name: Set up Dart OIDC
22+
uses: dart-lang/setup-dart@v1
23+
24+
- name: Set up Flutter
25+
uses: subosito/flutter-action@v2
26+
with:
27+
flutter-version: "3.7.12"
28+
channel: stable
29+
cache: true
30+
31+
- name: Install dependencies
32+
run: dart pub get
33+
34+
- name: Publish - dry run
35+
run: dart pub publish --dry-run
36+
37+
- name: Publish to pub.dev
38+
run: dart pub publish --force

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66
* Add CI coverage for both Flutter 3.7.12 and the latest stable Flutter.
77
* Avoid deprecated color opacity APIs on current Flutter.
88
* Add dartdoc coverage for the main public API.
9+
* Replace the reusable publish workflow with Node 24 compatible publish steps.
10+
* Expand README usage guidance with minimal examples, parameter tables, and common errors.
11+
* Refresh the example app with a Material 3 responsive demo.
912

1013
## 0.2.3
1114

‎README.md‎

Lines changed: 118 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -8,90 +8,155 @@
88
[![Pub](https://img.shields.io/pub/v/wave.svg?logo=flutter&style=flat-square)](https://pub.dev/packages/wave)
99
![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg?longCache=true&style=flat-square)
1010

11-
A Flutter package for displaying waves.
11+
A Flutter package for displaying animated wave backgrounds.
1212

1313
## Demo
1414

1515
| Platform | URL |
1616
| -: | -: |
1717
| Web | [wave.glorylab.xyz](https://wave.glorylab.xyz "The demo page of the wave package.") |
1818

19+
The web demo is an interactive generator. Adjust the config mode, palette,
20+
layer count, height, amplitude, speed, and loop behavior, then copy the
21+
generated `WaveWidget` code into your app.
22+
1923
## Deployment
2024

2125
The web demo is built from `example/` and deployed with Cloudflare Workers Static Assets. See [docs/cloudflare-workers.md](docs/cloudflare-workers.md) for the GitHub Actions and migration setup.
2226

27+
## Install
28+
29+
```yaml
30+
dependencies:
31+
wave: ^0.2.3
32+
```
2333
34+
## Minimal Example
2435
25-
## Getting Started
36+
```dart
37+
import 'package:flutter/material.dart';
38+
import 'package:wave/wave.dart';
2639

27-
``` Dart
40+
class WaveBackground extends StatelessWidget {
41+
const WaveBackground({Key? key}) : super(key: key);
42+
43+
@override
44+
Widget build(BuildContext context) {
45+
return WaveWidget(
46+
config: SingleConfig(
47+
color: Color(0xFF00BBF9),
48+
layers: 3,
49+
),
50+
size: Size(double.infinity, double.infinity),
51+
);
52+
}
53+
}
54+
```
2855

29-
static const _backgroundColor = Color(0xFFF15BB5);
56+
Use `WaveWidget` anywhere a normal widget can be painted. Give it a bounded
57+
parent, such as `SizedBox.expand`, `Positioned.fill`, or a fixed-height
58+
container.
3059

31-
static const _colors = [
32-
Color(0xFFFEE440),
33-
Color(0xFF00BBF9),
34-
];
60+
## Config Modes
3561

36-
static const _durations = [
37-
5000,
38-
4000,
39-
];
62+
### Single color
4063

41-
static const _heightPercentages = [
42-
0.65,
43-
0.66,
44-
];
64+
`SingleConfig` creates layered waves from one base color.
4565

66+
```dart
4667
WaveWidget(
47-
config: CustomConfig(
48-
colors: _colors,
49-
durations: _durations,
50-
heightPercentages: _heightPercentages,
51-
),
52-
backgroundColor: _backgroundColor,
53-
size: Size(double.infinity, double.infinity),
54-
waveAmplitude: 0,
55-
),
68+
config: SingleConfig(
69+
color: const Color(0xFF00BBF9),
70+
layers: 3,
71+
),
72+
size: const Size(double.infinity, double.infinity),
73+
)
5674
```
5775

58-
## Config modes
76+
### Seeded random colors
5977

60-
`CustomConfig` is the most explicit mode. Use it when you want full control over
61-
each wave layer's colors or gradients, duration, and height.
78+
`RandomConfig` creates generated colors for each layer. Provide `seed` when
79+
deterministic output is useful for tests, demos, or copyable examples. Omit
80+
`seed` only when you really want a new generated palette for each config
81+
construction.
6282

63-
``` Dart
83+
```dart
6484
WaveWidget(
65-
config: CustomConfig(
66-
gradients: [
67-
[Color(0xFF00BBF9), Color(0xFF9B5DE5)],
68-
[Color(0xFFFEE440), Color(0xFFF15BB5)],
69-
],
70-
durations: [5000, 4000],
71-
heightPercentages: [0.65, 0.66],
72-
),
73-
size: Size(double.infinity, double.infinity),
85+
config: RandomConfig(
86+
seed: 7,
87+
layers: 4,
88+
),
89+
size: const Size(double.infinity, double.infinity),
7490
)
7591
```
7692

77-
`SingleConfig` creates layered waves from one color. `RandomConfig` creates
78-
layer colors for you, with an optional `seed` when deterministic output is
79-
useful for tests or demos.
93+
### Custom colors or gradients
94+
95+
`CustomConfig` is the most explicit mode. Use it when you want full control over
96+
each layer's color or gradient, duration, and height.
8097

81-
``` Dart
98+
```dart
8299
WaveWidget(
83-
config: SingleConfig(
84-
color: Color(0xFF00BBF9),
85-
layers: 3,
86-
),
87-
size: Size(double.infinity, double.infinity),
100+
config: CustomConfig(
101+
gradients: const [
102+
[Color(0xFF00BBF9), Color(0xFF9B5DE5)],
103+
[Color(0xFFFEE440), Color(0xFFF15BB5)],
104+
],
105+
durations: const [5000, 4000],
106+
heightPercentages: const [0.65, 0.66],
107+
),
108+
size: const Size(double.infinity, double.infinity),
88109
)
110+
```
89111

90-
WaveWidget(
91-
config: RandomConfig(
92-
seed: 7,
93-
layers: 4,
94-
),
95-
size: Size(double.infinity, double.infinity),
112+
## Parameters
113+
114+
### WaveWidget
115+
116+
| Parameter | Type | Default | Description |
117+
| --- | --- | --- | --- |
118+
| `config` | `Config` | required | Layer colors, durations, heights, and blur. |
119+
| `size` | `Size` | required | Paint size for the wave stack. |
120+
| `waveAmplitude` | `double` | `20.0` | Base vertical movement of the wave path. |
121+
| `wavePhase` | `double` | `10.0` | Initial phase offset for the animation. |
122+
| `waveFrequency` | `double` | `1.6` | Horizontal frequency of the wave path. |
123+
| `duration` | `int?` | `6000` | Total runtime in milliseconds when `isLoop` is false. |
124+
| `backgroundColor` | `Color?` | `null` | Background color behind the waves. |
125+
| `backgroundImage` | `DecorationImage?` | `null` | Background image behind the waves. |
126+
| `isLoop` | `bool` | `true` | Whether animations repeat indefinitely. |
127+
128+
### Config classes
129+
130+
| Class | Best for | Key parameters |
131+
| --- | --- | --- |
132+
| `SingleConfig` | One-color layered waves | `color`, `layers`, `opacityPercentages`, `durations`, `heightPercentages` |
133+
| `RandomConfig` | Fast generated palettes | `layers`, `seed`, `colors`, `durations`, `heightPercentages` |
134+
| `CustomConfig` | Exact colors or gradients | `colors` or `gradients`, `durations`, `heightPercentages`, `gradientBegin`, `gradientEnd` |
135+
136+
## Common Errors
137+
138+
`CustomConfig` requires exactly one of `colors` or `gradients`.
139+
140+
```dart
141+
CustomConfig(
142+
colors: const [Color(0xFF00BBF9)],
143+
gradients: const [
144+
[Color(0xFF00BBF9), Color(0xFF9B5DE5)],
145+
],
146+
durations: const [5000],
147+
heightPercentages: const [0.65],
96148
)
97149
```
150+
151+
All per-layer lists must have the same length.
152+
153+
```dart
154+
CustomConfig(
155+
colors: const [Color(0xFF00BBF9), Color(0xFF9B5DE5)],
156+
durations: const [5000],
157+
heightPercentages: const [0.65, 0.66],
158+
)
159+
```
160+
161+
`heightPercentages` and `opacityPercentages` values must be between `0` and
162+
`1`, and every `duration` must be positive.

‎example/README.md‎

Lines changed: 17 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,30 @@
1-
# Wave
1+
# Wave Generator Example
22

3-
<img src='https://github.com/glorylab/wave/blob/master/assets/wave_banner.png?raw=true' width="1000" height="auto" alt="Flutter package: tm - WAVE" />
3+
This example is an interactive generator for the `wave` package.
44

5-
---
5+
Use the controls to adjust:
66

7-
[![Awesome: Flutter](https://img.shields.io/badge/⌐◨─◨-AwesomeFlutter-blue.svg?logo=flutter&longCache=true&style=flat-square)](https://github.com/Solido/awesome-flutter#effect)
8-
[![Pub](https://img.shields.io/pub/v/wave.svg?logo=flutter&style=flat-square)](https://pub.dev/packages/wave)
9-
![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg?longCache=true&style=flat-square)
7+
- config mode: `SingleConfig`, seeded `RandomConfig`, or `CustomConfig`
8+
- palette
9+
- layer count
10+
- wave height
11+
- amplitude
12+
- animation speed
13+
- loop behavior
1014

11-
A Flutter package for displaying waves.
15+
The preview updates immediately, and the top bar shows live frame metrics for
16+
the current animation. Use **Code** to inspect and copy the complete generated
17+
Flutter widget from a dialog.
1218

1319
## Demo
1420

1521
| Platform | URL |
1622
| -: | -: |
1723
| Web | [wave.glorylab.xyz](https://wave.glorylab.xyz "The demo page of the wave package.") |
1824

25+
## Run Locally
1926

20-
21-
## Getting Started
22-
23-
``` Dart
24-
25-
static const _backgroundColor = Color(0xFFF15BB5);
26-
27-
static const _colors = [
28-
Color(0xFFFEE440),
29-
Color(0xFF00BBF9),
30-
];
31-
32-
static const _durations = [
33-
5000,
34-
4000,
35-
];
36-
37-
static const _heightPercentages = [
38-
0.65,
39-
0.66,
40-
];
41-
42-
WaveWidget(
43-
config: CustomConfig(
44-
colors: _colors,
45-
durations: _durations,
46-
heightPercentages: _heightPercentages,
47-
),
48-
backgroundColor: _backgroundColor,
49-
size: Size(double.infinity, double.infinity),
50-
waveAmplitude: 0,
51-
),
27+
```sh
28+
flutter pub get
29+
flutter run -d chrome
5230
```

‎example/lib/generated_plugin_registrant.dart‎

Lines changed: 0 additions & 17 deletions
This file was deleted.

0 commit comments

Comments
 (0)