Kaeru UI Extension Library #

Kaeru UI is a Flutter extension library that provides chainable, declarative syntax for building UI more concisely and expressively. It extends core Dart and Flutter types with additional utilities, and introduces Virtual Widgets for fluent UI composition.

Features #

• 🚀 Chainable extensions on Widget, String, Color, Future, Stream, etc.
• 🎨 Syntactic sugar for padding, margin, alignment, transforms, and animations.
• 📦 Virtual widgets (VContainer, VText, VRichText) for fluent UI building.
• ⚡ Simplifies common Flutter patterns (stacks, wraps, padding, inkwell, etc.).
• 💡 Inspired by frameworks like VelocityX, TailwindCSS, and Vue.

Installation #

Add the dependency to your pubspec.yaml:

dependencies:
  kaeru_ui:
    git:
      url: https://github.com/tachibana-shin/kaeru_ui.git

Then import it:

import 'package:kaeru_ui/kaeru_ui.dart';

Example Usage #

import 'package:flutter/material.dart';
import 'package:kaeru_ui/kaeru_ui.dart';

class DemoPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: "Hello Kaeru"
            .text
            .lg
            .red(600)
            .underline
            .make()
            .p(12)
            .inkWell(onTap: () => print("Tapped!"))
            .fadeIn(),
      ),
    );
  }
}

(Generated by docuwriter.ai)

Kaeru UI Extension Library Documentation #

Below you’ll find detailed documentation for each file in the Kaeru UI extension library. These extensions streamline Flutter UI code by enabling chainable, declarative syntax.

Generic Extensions #

These extensions augment core Dart and Flutter types with handy utilities.

lib/extensions/generic/list/flex.dart #

Provides hStack/row and vStack/column builders on List<Widget> for concise Flex layouts.

• hStack / row: Creates a Row from the list.
• vStack / column: Creates a Column from the list.

const [Text('A'), Text('B'), Text('C')]
  .hStack(mainAxisAlignment: MainAxisAlignment.spaceBetween);

lib/extensions/generic/list/flex_gap.dart #

Adds gap support between children in Flex layouts.

• hStackWithGap: Horizontal stack with configurable gap.
• vStackWithGap: Vertical stack with configurable gap.

const [Text('1'), Text('2'), Text('3')]
  .hStackWithGap(gap: 8, mainAxisSize: MainAxisSize.min);

lib/extensions/generic/list/wrap.dart #

Builds a Wrap widget from List<Widget> with spacing options.

• wrap: Wrap with parameters for spacing, runSpacing, alignment, and direction.

const [Text('A'), Text('B'), Text('C')]
  .wrap(spacing: 4, runSpacing: 8);

lib/extensions/generic/color.dart #

Enables chainable color channel and semantic color access.

• sr/sg/sb/sa: Set red/green/blue/alpha channel.
• o: Set overall opacity.
• ColorPalette: Predefined palette (primary, success, etc.).
• KaeruSemanticColor: Access palette via color.primary.

Colors.blue
  .sa(200)        // set alpha
  .o(0.5)         // set opacity
  .secondary;     // switch to secondary palette color

lib/extensions/generic/edge_insets.dart #

Merges two EdgeInsets by adding their values.

• merge: Returns the sum of two insets.

const EdgeInsets.all(8).merge(const EdgeInsets.symmetric(horizontal: 4));

lib/extensions/generic/future.dart #

Wraps Future<T> in a Flutter FutureBuilder with concise callbacks.

• futureBuilder: Specify success, optional error, and loading builders.

myFuture.futureBuilder(
  success: (ctx, data) => Text('$data'),
  loading: (_) => CircularProgressIndicator(),
);

lib/extensions/generic/int.dart #

Converts integer hex values to Color.

• color: Interprets int as ARGB color.

0xFF112233.color   // Color(0xFF112233)

lib/extensions/generic/num.dart #

Provides screen-percent sizing, padding/margin shorthands, durations, and number formatting.

• w/h/sp: Percent of screen width/height for size or font.
• p, px, py, pt, pb, pl, pr, m, mx, my, mt, mb, ml, mr: EdgeInsets.
• seconds, milliseconds, minutes, hours: Duration.
• toFixed: Format number of decimal places.

20.w(context)        // 20% of screen width
8.p                  // EdgeInsets.all(8)
5.seconds            // Duration(seconds: 5)
3.14159.toFixed(2)   // "3.14"

lib/extensions/generic/stream.dart #

Wraps Stream<T> in a StreamBuilder with concise callbacks.

• streamBuilder: Specify success, optional error, and loading builders.

myStream.streamBuilder(
  success: (ctx, data) => Text('$data'),
  loading: (_) => CircularProgressIndicator(),
);

lib/extensions/generic/string.dart #

Enhances String with case conversions, parsing, email check, and text builder.

• capitalize, titleCase, camelCase, snakeCase: Case transformations.
• isEmail: Basic email regex check.
• toInt, toDouble: Safe parsing.
• text: Wraps string into VText for further styling.

'hello_world'.camelCase    // "helloWorld"
'3.14'.toDouble            // 3.14
'user@example.com'.isEmail // true

lib/extensions/generic/string_avatar.dart #

Treats String as image URL and builds a CircleAvatar.

• avatar: Parameters for radius and backgroundColor.

'https://.../avatar.png'
  .avatar(radius: 24, backgroundColor: Colors.blueGrey);

Widget Extensions #

These chainable extensions simplify common widget wrappers.

lib/extensions/animate.dart #

Chainable entrance animations: fade in, slide up, scale, rotate.

• fadeIn, slideUp, scale, rotate: Customize duration, curve, and parameters like distance or begin/end.

Text('Hello').fadeIn().slideUp(distance: 30);

lib/extensions/badge.dart #

Wraps a widget in a badge-style container.

• badge: Configure bgColor, textColor, paddingH/V, borderRadius, fontSize.

Text('5').badge(bgColor: Colors.green, fontSize: 14);

lib/extensions/box.dart #

Begins a chainable Container builder via VContainer.

• box: Starts a VContainer chain.

Text('A').box.bg(Colors.red).rounded(4).make();

lib/extensions/clip.dart #

Quick clipping methods on any widget.

• rounded(radius): ClipRRect.
• circle: ClipOval.
• square(size): Sized box constraint.

Image.network(url).circle;

lib/extensions/display.dart #

Conditional display helpers.

• show(bool): Shows or replaces with empty.
• none: Always hidden.

widget.show(isVisible);

lib/extensions/flex.dart #

Alignment, scrolling, and flex wrappers on any widget.

• centered, topLeft, etc.: Wrap in Align.
• scrollable: SingleChildScrollView.
• expand, flexible: Wrap in Expanded or Flexible.

Icon(Icons.home).centered.expand(flex: 2);

lib/extensions/gesture.dart #

Gesture detectors on any widget.

• onTap, onDoubleTap, onLongPress: Attach callbacks.

Text('Tap me').onTap(() => print('Tapped'));

lib/extensions/icon.dart #

Chainable size and color setters on Icon.

• size: Adjust icon size.
• iconColor: Adjust icon color.

Icon(Icons.add).size(30).iconColor(Colors.green);

lib/extensions/image.dart #

Chainable methods on Image widgets.

• size(width, height): Set dimensions.
• fitBox(BoxFit): Adjust fit.

Image.network(url).size(width: 100, height: 60).fitBox(BoxFit.cover);

lib/extensions/ink_well.dart #

Wrap any widget in an InkWell with configuration.

• inkWell: Tap, double-tap, long-press, hover, splash, etc.

Text('Click').inkWell(onTap: () => print('InkWell tapped'));

lib/extensions/margin.dart #

Shorthand margin helpers by combining box and generic m methods.

• m, mx, my, mt, mb, ml, mr: Apply margins via VContainer.

Text('Hi').m(8).make();

lib/extensions/padding.dart #

Shorthand padding on any widget.

• pad(EdgeInsets), p, px, py, pt, pb, pl, pr: Directional Padding.

Text('Hello').p(12).px(8);

lib/extensions/positioned.dart #

Wrap in Positioned within a Stack.

• positioned: Set top, left, right, bottom, width, height.

Container().positioned(top: 0, left: 0);

lib/extensions/responsive.dart #

Responsive helpers based on BuildContext breakpoints.

• isXs, isSm, isMd, isLg, isXl on BuildContext.
• xsOnly/..., mdUp: Show/hide widgets at certain breakpoints.

Text('Mobile view').xsOnly(context);

lib/extensions/spacing.dart #

Numeric spacing shortcuts.

• hSpace, vSpace: SizedBox horizontal/vertical gaps.

5.0.hSpace;
10.0.vSpace;

lib/extensions/text.dart #

Bridges Text to VText for rich, chainable text styling.

• text: Convert Text to VText for further styling.

Text('Hello').text.color(Colors.red).size(18).make();

lib/extensions/transform.dart #

Chainable transforms.

• rotate(radians): Rotate widget.
• flipX, flipY: Mirror horizontally/vertically.
• translate(dx, dy): Translate widget.

Icon(Icons.arrow_upward).rotate(pi / 4).translate(dx: 10);

lib/extensions/visibility.dart #

Wrap in Visibility widget.

• visible(flag, replacement): Show or replace.
• hide: Always hidden.

widget.visible(isActive, replacement: Text('Off'));

Virtual Widgets #

Provide fluent builders for complex widget trees.

lib/virtual/v_container.dart #

VContainer is a builder for Container with chainable methods:

• childWidget: Set child.
• rounded, bg: Border radius and background color.
• padding, margin: Insets.
• size(width, height): Dimensions.
• align, make(): Alignment and final Container.

Text('A')
  .box.bg(Colors.blue)
  .rounded(12)
  .size(80, 40)
  .alignCenter
  .make();

lib/virtual/v_rich_text.dart #

VRichText builds a RichText with multiple TextSpan children:

• bold, italic, color, size, underline, etc.: Apply style to all spans.
• align, textDirection, maxLines, overflowClip: Layout.
• make(): Final RichText widget.
• richText on String: Starts a VRichText chain.

'Hello'.richText
  .bold
  .color(Colors.red)
  .underline
  .make();

lib/virtual/v_text.dart #

VText is a chainable text builder wrapping Flutter Text:

• color, size, spacing, wordSpacing, opacity, letter spacing shortcuts (tight, wide).
• lineHeight shortcuts (lhTight, lhNormal, etc.).
• xs, sm, base, lg, xl, …: Predefined font sizes.
• make(): Builds a Text widget.

'Kaeru UI'
  .text
  .lg
  .red(700)
  .tight
  .make();

Entry Point #

lib/kaeru_ui.dart #

Exports all extensions and virtual widgets in one import:

import 'package:kaeru_ui/kaeru_ui.dart';

This single import gives access to the entire fluent API.