Initial commit

2026-04-15 00:51:17 +02:00
commit 0fec97163d
72 changed files with 3076 additions and 0 deletions
@@ -0,0 +1,142 @@
+# 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 8-point star, 5-point star, rectangle, diamond, hexagon, random polygon, and confetti
+- Custom sparkle shapes via parameterized `SparkleShapeSpec` factories
+- 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.eightPointStar,
+)
+```
+
+## 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.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
+
+## 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.