all: overhaul docs, dartdoc config

.github/workflows/ci.yaml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: subosito/flutter-action@v2
         with:
-          channel: stable
+          channel: master
           cache: true
       - run: flutter pub get
       - run: flutter analyze
@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: subosito/flutter-action@v2
         with:
-          channel: stable
+          channel: master
           cache: true
       - run: flutter pub get
       - run: flutter test

.github/workflows/pr.yaml

@@ -11,7 +11,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: subosito/flutter-action@v2
         with:
-          channel: stable
+          channel: master
           cache: true
       - run: flutter pub get
       - run: flutter test --coverage

.github/workflows/preview.yaml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: subosito/flutter-action@v2
         with:
-          channel: beta
+          channel: master
           architecture: x64
           cache: true
 

.github/workflows/release.yaml

@@ -12,7 +12,7 @@ jobs:
 
       - uses: subosito/flutter-action@v2
         with:
-          channel: stable
+          channel: master
           cache: true
 
       - run: flutter pub get

.metadata

@@ -4,7 +4,7 @@
 # This file should be version controlled and should not be manually edited.
 
 version:
-  revision: 4f9d92fbbdf072a70a70d2179a9f87392b94104c
-  channel: stable
+  revision: 3f98c0f8f98bf3ddae4233316c6a57a6571e9cb1
+  channel: master
 
 project_type: package

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.1.2
+
+* Changed ScrollableList to set default `padding` value in constructor instead of inside `build`
+* Added `hintText` param to SearchBar
+
 ## 0.1.1
 
 * **BREAKING**: Removed `spaceBetween` due to conflict with divided and use of `.spaced`extension in ScrollableList

README.md

@@ -1,3 +1,166 @@
-# flume
+# <img src="https://github.com/gameflow-tv/flume_mobile/blob/main/assets/docs/cover.png?raw=true" style="width: 100%;"/>
 
-Implementation of the Flume design system written in Dart for Flutter.
+Implementation of the Flume design system written from scratch in Dart and UI Components built with Flutter.
+
+## Getting started
+
+Use the included Material adapter to get sensible defaults when utilizing Material widgets. This is not required but recommended.
+
+```dart
+return Flume(
+  theme: FlumeTheme.fallback(),
+  builder: (context, theme) {
+    return Ambiance(
+      child: MaterialApp(
+        title: 'Example',
+        theme: theme,
+      ),
+    );
+  },
+);
+```
+
+To retrieve the theme object, use its inherited widget provier or the pre-made shorthand extensions;
+
+```dart
+// Either retrieve the inherited widget
+final theme = Flume.of(context);
+
+// .. or use the shorthand extension
+final theme = context.theme;
+```
+
+## Ambiance
+
+Automated color schemes for a dynamic and colorful experience. The description below demonstrates how image-generated colors are created and implemented in a UI.
+
+### Usage
+
+First and foremost, provide an `Ambiance` widget with a seed color to generate the palette. If no color is provided, it defaults to `FlumeColors.secondary` from the theme. The `Ambiance` widget takes either a `child` or a `builder` property.
+
+```dart
+return Ambiance(
+  // Seed color, defaults to `FlumeColors.secondary`
+  color: Colors.red,
+  builder: (context, ambiance) {
+    // Use ambiance data provided by builder
+    return Container(
+      color: ambiance.color,
+      child: Container(
+        // Or retrieve ambiance from context,
+        // alternatively Ambiance.of(context).color
+        color: context.ambiance.color, 
+      ),
+    );
+  }
+)
+```
+
+This will correspond to a single ambiance "layer". If we check out the elevation property from the example above, this will start at 0;
+
+```dart
+print(ambiance.elevation); // 0
+```
+
+However, if we stack Ambiance widgets in the tree, we also increase the elevation for each layer;
+
+```dart
+return Ambiance(
+  builder: (context, ambiance1) {
+    return Ambiance(
+      builder: (context, ambiance2) {
+        return Ambiance(
+          builder: (context, ambiance3) {
+            return null;
+          },
+        );
+      },
+    );
+  },
+);
+```
+
+Which will result in the following values;
+
+```dart
+print(ambiance1.elevation); // 0
+print(ambiance2.elevation); // 1
+print(ambiance3.elevation); // 2
+print(ambiance1.color); // dark variant
+print(ambiance2.color); // mediumDark variant
+print(ambiance3.color); // medium variant
+```
+
+> Many of the Flume UI components use this system to set its own background and foreground colors in order to reflects its place in the ambiance layer tree.
+
+In order to retrieve a color for a specific elevation, we can use `ambiance.at(n)`;
+
+```dart
+return Container(
+  color: context.ambiance.at(5) // light
+);
+```
+
+We can also use the palette directly;
+
+```dart
+return Container(
+  color: context.ambiance.palette.mediumDark // mediumDark
+);
+```
+
+### Colors from images
+
+A team’s or tournament’s main logo is the basis for the color extraction algorithm (Ambiance) to build a color scheme that’s applied to an entire UI or individual components that utilize dynamic color.
+
+The goal is to give every team and tournament a distinct look, and to emphasize the uniqueness of each. Using Ambiance in web development results in a visually unified, refreshed and modern appearance whilst embracing the diversity of content and giving it visual context.
+
+<p align="center">
+  <img src="https://github.com/gameflow-tv/flume_mobile/blob/main/assets/docs/ambiance_process.png?raw=true">
+</p>
+
+
+A single source color is used to derive five tones that provide the basis for any web development use case. The dynamic color system is built using luminance. Meaning that if the hue and saturation were removed, we'd be able to see the contrast through shades. The colors ensure colorful and rich palettes while adhering to the WCAG color contrast guidelines.
+
+Combining color based on tonality, rather than hex value or hue, is one of the key systems that make any color output accessible. Layouts using dynamic color will meet requirements because the algorithmic combinations that a user can experience are designed to meet accessibility standards.
+
+### Dynamic colors schemes for UI
+
+The Ambiance color algorithm generates five colors for each identity: _dark_, _mediumDark_, _medium_, _mediumLight_ and _light_. The colors represent different levels of elevation:
+
+* _dark_ (elevation: 0) is used as the background-color on a page, and as text-color on light backgrounds.
+
+* _mediumDark_ (elevation: 1) serves as background-color for elements that sit on top of _dark_.
+
+* _medium_ (elevation: 2) is mostly used as hover state for _mediumDark_, or as background-color for elements that sit on top of _mediumDark_.
+
+* _mediumLight_ (elevation: 3) is used as hover state for _medium_.
+
+* _light_ (elevation: 4) is used for selected states, and generally as visual flourish to complement the overall color scheme of each identity.
+
+Avoid stacking more than three layers on top of each other (not including hover states) as this will clutter the UI. Always make sure layers that are stacked on top of each other are distinguished using elevation in chronological order.
+
+<p align="center">
+  <figure align="center">
+    <img src="https://github.com/gameflow-tv/flume_mobile/blob/main/assets/docs/elevation_example.png?raw=true">
+      <figcaption>
+        0 = <i>dark</i> (background)
+        1 = <i>mediumDark</i> (container)
+        2 = <i>medium</i> (hover)
+      </figcaption>
+  </figure>
+</p>
+
+## Foundation
+
+Flume Foundation is the shared design foundation for Gameflow. This is where we keep things like color, type styles, motion, spacing and other design tokens.
+
+It aims to create a recognisable and consistent user experience and speed up design development with common principles. These are things everyone should use — it’s what makes Gameflow look like Gameflow.
+
+All design tokens are gathered in a `FlumeTheme` class, and all design token classes are dead simple, as they only hold raw data.
+
+## Components
+
+The components library is a set of Flutter widgets that implements components from the Flume design system. This is a library that very likely will change a lot until the first stable release, and the API surface _is_ unstable.
+
+All components _require_ a `Flume` parent present in the tree, and most components also _require_  an `Ambiance` parent in the tree as well in order to use dynamic color palettes.

dartdoc_options.yaml

@@ -7,16 +7,19 @@ dartdoc:
   warnings:
     - tool-error
   categories:
-    Flume:
-      markdown: doc/flume.md
-      name: Flume
     Foundation:
       markdown: doc/foundation.md
       name: Foundation
     Components:
       markdown: doc/components.md
       name: Components
-  categoryOrder: [Flume, Foundation, Components]
+    Ambiance:
+      markdown: doc/ambiance.md
+      name: Ambiance
+    Tools:
+      markdown: doc/tools.md
+      name: Tools
+  categoryOrder: [Foundation, Components, Ambiance, Tools]
   examplePathPrefix: example/
   showUndocumentedCategories: true
   favicon: assets/docs/favicon.ico

doc/ambiance.md

@@ -0,0 +1,3 @@
+# Ambiance
+
+The Ambiance library consists of the core color algorithm used to generate palettes, as well as various utilities and widgets for easy use of the Ambiance system.

doc/components.md

@@ -1 +1,3 @@
 # Components
+
+The component library consists of various Flume component implementations as well as utilities and convenience tools for effectively implementing Flume in any Flutter application.

doc/foundation.md

@@ -5,7 +5,6 @@ The Foundation library consists of all Flume's design tokens put together;
 - Breakpoints
 - Colors
 - Motion
-- Palette
 - Shadows
 - Shapes
 - Spacing

doc/tools.md

@@ -0,0 +1,5 @@
+# Tools
+
+Tools and utilities for streamlining development processes.
+
+Contains programs and scripts for e.g. fetching remote assets.

example/pubspec.lock

@@ -134,10 +134,10 @@ packages:
     dependency: transitive
     description:
       name: meta
-      sha256: "6c268b42ed578a53088d834796959e4a1814b5e9e164f147f580a386e5decf42"
+      sha256: "12307e7f0605ce3da64cf0db90e5fcab0869f3ca03f76be6bb2991ce0a55e82b"
       url: "https://pub.dev"
     source: hosted
-    version: "1.8.0"
+    version: "1.9.0"
   nested:
     dependency: transitive
     description:

lib/src/ambiance/algorithm/luminance.dart

@@ -5,7 +5,7 @@ const maxIter = 20;
 
 // In-memory cache of luminance values to avoid
 // expensive re-compute.
-final lumCache = <Color, Color>{};
+final _lumCache = <Color, Color>{};
 
 /// {@category Ambiance}
 /// Extension on [Color] to get luminance values.
@@ -42,7 +42,7 @@ extension LuminanceExtension on Color {
     final result = rgb.withOpacity(opacity);
 
     // Cache the result.
-    lumCache[this] = result;
+    _lumCache[this] = result;
 
     return result;
   }

lib/src/ambiance/extensions.dart

@@ -1,6 +1,8 @@
 import 'package:flume/src/ambiance.dart';
 import 'package:flutter/widgets.dart';
 
+/// {@category Ambiance}
+/// {@subCategory Extensions}
 extension AmbianceExtension on BuildContext {
   AmbianceState get ambiance => Ambiance.of(this);
 }

lib/src/ambiance/widgets/ambiance.dart

@@ -1,6 +1,9 @@
 import 'package:flume/flume.dart';
 import 'package:flutter/widgets.dart';
 
+/// {@category Ambiance}
+/// {@subCategory Widgets}
+/// A data class that holds the current [Ambiance] state.
 class AmbianceState {
   final AmbiancePalette palette;
   final Color color;
@@ -21,6 +24,9 @@ class AmbianceState {
   });
 }
 
+/// {@category Ambiance}
+/// {@subCategory Widgets}
+/// A widget that provides the current [AmbianceState] to its descendants.
 class Ambiance extends StatelessWidget {
   final Color? source;
   final Color? color;
@@ -81,7 +87,7 @@ class Ambiance extends StatelessWidget {
 
     return AmbianceProvider(
       state: state,
-      child: Proxy(
+      child: _Proxy(
         builder: (ctx) {
           return child ?? builder!(ctx, state);
         },
@@ -90,9 +96,9 @@ class Ambiance extends StatelessWidget {
   }
 }
 
-class Proxy extends StatelessWidget {
+class _Proxy extends StatelessWidget {
   final Widget Function(BuildContext) builder;
-  const Proxy({super.key, required this.builder});
+  const _Proxy({required this.builder});
 
   @override
   Widget build(BuildContext context) {
@@ -102,6 +108,9 @@ class Proxy extends StatelessWidget {
 
 Map<Color, AmbiancePalette> _computedPalettes = {};
 
+/// {@category Ambiance}
+/// {@subCategory Functions}
+/// A function that returns an [AmbiancePalette] from a given [Color].
 AmbiancePalette getPaletteFromColor(Color color) {
   if (_computedPalettes.containsKey(color)) {
     return _computedPalettes[color]!;
@@ -110,6 +119,10 @@ AmbiancePalette getPaletteFromColor(Color color) {
   }
 }
 
+/// {@category Ambiance}
+/// {@subCategory Functions}
+/// A function that returns a [Color] from the given [color]'s ambiance palette
+/// given the [elevation].
 Color getColorFromElevation(Color color, int elevation) {
   AmbiancePalette palette;