From dee9a9ae3053880dd366a4a699fadb4b5fe012ce Mon Sep 17 00:00:00 2001 From: rafael Date: Thu, 13 May 2021 19:34:08 -0300 Subject: [PATCH] doc: README and CHANGELOG Closes #2 --- CHANGELOG.md | 15 +++++- README.md | 144 +++++++++++++++++++++++++++++++++++++++++++++++---- pubspec.yaml | 3 +- 3 files changed, 150 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 41cc7d8..3f13e3d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ -## 0.0.1 +# Changelog -* TODO: Describe initial release. +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +```dart +/* + * @todo #2 needs to release first version. +/* +``` diff --git a/README.md b/README.md index 067deab..6299a82 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,140 @@ -# eo_color +# Dartoos EO Color Package -A new Flutter package project. +[![EO principles respected here](https://www.elegantobjects.org/badge.svg)](https://www.elegantobjects.org) +[![DevOps By Rultor.com](https://www.rultor.com/b/dartoos-dev/eo_color)](https://www.rultor.com/p/dartoos-dev/eo_color) + +[![pub](https://img.shields.io/pub/v/eo_color)](https://pub.dev/packages/eo_color) +[![license](https://img.shields.io/badge/license-mit-green.svg)](https://github.com/dartoos-dev/eo_color/blob/main/LICENSE) +[![style: lint](https://img.shields.io/badge/style-lint-4BC0F5.svg)](https://pub.dev/packages/lint) +[![PDD status](https://www.0pdd.com/svg?name=dartoos-dev/eo_color)](https://www.0pdd.com/p?name=dartoos-dev/eo_color) +[![build](https://github.com/dartoos-dev/eo_color/actions/workflows/build.yml/badge.svg)](https://github.com/dartoos-dev/eo_color/actions/) +[![codecov](https://codecov.io/gh/dartoos-dev/eo_color/branch/master/graph/badge.svg)](https://codecov.io/gh/dartoos-dev/eo_color) +[![Hits-of-Code](https://hitsofcode.com/github/dartoos-dev/eo_color?branch=master)](https://hitsofcode.com/github/dartoos-dev/eo_color/view?branch=master) + +Stop wondering whether an obscure command like `Grey.colors[200]` represents a +light, medium or dark shade of grey. Spoiler: it is a light shade of grey. +Moreover, what does that '200' mean? Could it be, say, 330 or 777? Wouldn't it +be better if you could just write `Grey.light()` to **declare** that you want a +light shade of grey? + +This is a fully tested (100% test coverage), elegant and object-oriented package +to be used as an alternative to the Flutter's built-in color package. It +significantly improves the readability and maintainability of your source code +by providing: + +- a collection of color-related classes and interfaces that are declarative; +- an object-oriented implementation of the [Material + Design](https://material.io/design/color/) color palettes and swatches. + +In addition, this package can be used as a base framework for other color +related packages. ## Getting Started -This project is a starting point for a Dart -[package](https://flutter.dev/developing-packages/), -a library module containing code that can be shared easily across -multiple Flutter or Dart projects. +Like any object-oriented package, this one makes extensive use of interfaces for +defining concepts, such as color palettes, color swatches, gradients, etc. + +### Core Interfaces + +Currently there are two core interfaces: + +- **Palette**: represents a color palette from which a color can be picked. Its + single property "color" retrieves the picked color. Typically, the color + selection takes place when a Palette subclass is instantiated. For instance, + `Grey.light().color` retrieves a light shade of grey; `Blue.dark().color`, a + dark shade of blue; `Red().color`, the primary red shade; and so on. + +- **Swatch**: a color swatch is a collection of related colors, such as the + colors of the rainbow, shades of grey, the colors of the gradient of a logo, + etc. Its single property "colors" retrieves several colors at once as an + `Iterable`. For instance, `Greys().colors` retrieves ten shades of grey + as defined by the Material Design standard. + +For more details: [api +reference](https://pub.dev/documentation/eo_color/latest/eo_color/eo_color-library.html). + +### Color Palette Classes + +They are any class whose name matches with the color it represents, such as +"Grey". For example, `Grey()` represents the primary grey color, equivalent to +the Flutter's cryptic `Colors.grey.shade500`; `Grey.light()` ≡ +`Colors.grey.shade200`; `Grey.veryDark()` ≡ `Colors.grey.shade900`; and so on. + +#### Color palette in action + +```dart +import 'package:eo_color/palettes.dart'; +import 'package:flutter/material.dart'; + +class Greyish extends StatelessWidget { + + static const _light = Grey.light(); + + @override + Widget build(BuildContext context) { + return Container( + color: _light.color, + ); + } +} +``` + +### Color Swatch Classes + +Any class whose name matches with the plural of a color and represents some +shades thereof. For instance, the "Greys" class is a swatch color of ten shades +of grey. Therefore, the command `Greys().colors` retrieves an `Iterable` +containing ten shades of grey; the greater the index, the darker the color. + +#### Swatch in action + +```dart +import 'package:eo_color/swatches.dart'; +import 'package:flutter/material.dart'; + +/// Rectangle filled with a gradient of ten shades of a Material Design color. +class RectGradient extends StatelessWidget { + + /// Rectangle filled with the given color swatch. + const RectGrandient(this._swatch); + + /// Rectangle filled with ten shades of grey. + const RectGrandient.grey() : this(Greys()); + + // Material Design color swatch. + final Swatch _swatch; + + @override + Widget build(BuildContext context) { + return Container( + height: kToolbarHeight / 2, + decoration: BoxDecoration( + gradient: LinearGradient( + begin: Alignment.topRight, + end: Alignment.bottomLeft, + colors: _swatch.colors.toList(growable:false), + ), + ), + ); + } +} +``` + +### Supported Material Design color palettes + +```dart +/** + * @todo #2 nothing to be placed here; there is no palette implementation yet. +*/ +``` + +### Supported Material Design color swatches + +```dart +/** + * @todo #2 nothing to be placed here; there is no swatch implementation yet. +*/ +``` -For help getting started with Flutter, view our -[online documentation](https://flutter.dev/docs), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +See also: [material design color +palette](https://material.io/archive/guidelines/style/color.html#color-color-palette). diff --git a/pubspec.yaml b/pubspec.yaml index 69ea72b..fbbf82e 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,7 +1,8 @@ name: eo_color -description: An elegant collection of color related classes and interfaces as an alternative to the Flutter's built-in colors, as well as an object-oriented implementation of the Material Design color palettes. +description: An elegant, object-oriented implementation of the Material Design color palletes and swatches; an alternative to the Flutter's built-in colors. version: 0.0.1 homepage: https://dartoos.dev +repository: https://github.com/dartoos-dev/eo_color environment: sdk: ">=2.12.0 <3.0.0"