# holo_shiny

`holo_shiny` is a Flutter package that renders shader-driven holographic shine.

It exposes two widget layers:

- `Shiny`: apply shine to any widget (no clipping and no rotation)
- `ShinyCard`: card-oriented convenience widget with shape clipping and tilt rotation

## Features

- GLSL shader-driven holographic effects
- Optional motion input via sensors or custom tilt stream
- Generic wrapper API for any widget via `Shiny(child: ...)`
- Card API with `background`, `foreground`, `shape`, and drag tilt via `ShinyCard`
- Built-in sparkle presets including `none` (default), 8-point star, 5-point star, rectangle, diamond, hexagon, random polygon, and confetti
- Custom sparkle shapes via parameterized `SparkleShapeSpec` factories
- Global shader opacity control via `opacity`
- Cross-platform Flutter support (mobile, web, desktop)

## Installation

Add the package:

```yaml
dependencies:
  holo_shiny: ^0.1.0
```

Then run:

```bash
flutter pub get
```

## Quick Start

```dart
import 'package:flutter/material.dart';
import 'package:holo_shiny/holo_shiny.dart';

class Demo extends StatelessWidget {
  const Demo({super.key});

  @override
  Widget build(BuildContext context) {
    return const Shiny(
      child: ColoredBox(
        color: Color(0xFF202A3A),
        child: SizedBox(width: 280, height: 80),
      ),
    );
  }
}
```

## Card Usage

```dart
ShinyCard(
  controller: controller,
  background: Container(color: const Color(0xFF1B2D4B)),
  foreground: const Center(child: Text('HOLO')),
  sparkleShape: SparkleShapeSpec.none,
  opacity: 1.0,
)
```

## Motion with Controller

```dart
final ShinyController controller = ShinyController(useSensor: true);

Shiny(
  controller: controller,
  child: Container(color: const Color(0xFF1B2D4B)),
)
```

## Sparkle Shapes

Use built-in sparkle presets:

```dart
ShinyCard(
  sparkleShape: SparkleShapeSpec.none,
)

ShinyCard(
  sparkleShape: SparkleShapeSpec.hexagon,
)
```

Or create your own parameterized shapes:

```dart
ShinyCard(
  sparkleShape: SparkleShapeSpec.customStar(
    points: 7,
    innerRatio: 0.36,
  ),
)

Shiny(
  sparkleShape: SparkleShapeSpec.customPolygon(
    sides: 8,
    aspectRatio: 1.2,
    rotation: 0.2,
  ),
  child: const SizedBox(width: 240, height: 120),
)
```

You can also provide a custom stream:

```dart
final StreamController<Offset> input = StreamController<Offset>.broadcast();
final ShinyController controller = ShinyController(tiltStream: input.stream);
```

## API Summary

- `Shiny`: generic effect wrapper
- `ShinyCard`: shape + rotation + composition convenience widget
- `SparkleShapeSpec`: built-in and custom sparkle silhouette configuration
- `ShinyController`: optional source selection for tilt
- `SensorTiltController`: low-level sensor fusion stream utility

Important defaults:

- `sparkleShape` defaults to `SparkleShapeSpec.none` (no sparkles)
- `opacity` defaults to `1.0`

## Platform Notes

- Shader uses Flutter runtime effects and avoids derivative functions (`dFdx`, `dFdy`, `fwidth`) for web compatibility.
- If a sensor is unavailable, motion input simply emits no events.

## Example

See the package example app in `example/` for:

- Basic usage
- Any-widget shiny wrapper usage
- Sensor-driven motion
- External stream override
- Custom card shape/background/foreground composition
- Built-in sparkle shape toggles in the demo UI
- User-defined sparkle shape presets using `SparkleShapeSpec`

## Publishing Notes

Replace placeholder package metadata URLs in `pubspec.yaml` before publishing.