v1.0.0 - Initial release (#1)

Initial release 🥳

Reviewed-on: #1

example/list_or_example.dart

@@ -0,0 +1,56 @@
+import 'package:list_or/list_or.dart';
+
+void main() {
+  print('--- Example 1: Wrapping a Single Value ---');
+  // A single value is converted into a list containing just that value.
+  final singleItem = ListOr<String>('Hello World');
+
+  print('Length: ${singleItem.length}'); // Output: 1
+  print('First item: ${singleItem[0]}'); // Output: Hello World
+
+  // Notice the custom toString():it prints just the string, not ['Hello World']
+  print('String representation: $singleItem'); // Output: Hello World
+
+  print('\n--- Example 2: Wrapping an Iterable ---');
+  // A standard List or Set is normalized into a modifiable ListOr.
+  final multipleItems = ListOr<String>(['Apple', 'Banana']);
+
+  // Because it mixes in ListMixin, you can use all standard list methods.
+  multipleItems.add('Cherry');
+
+  print('Length: ${multipleItems.length}'); // Output: 3
+
+  // When the length is not exactly 1, toString() acts like a normal List.
+  print(
+    'String representation: $multipleItems',
+  ); // Output: [Apple, Banana, Cherry]
+
+  print('\n--- Example 3: Parsing Flexible JSON Data ---');
+  // Imagine an API that irregularly returns 'tags' as either a String or a List.
+  final Map<String, dynamic> jsonResponse1 = {'id': 1, 'tags': 'flutter'};
+  final Map<String, dynamic> jsonResponse2 = {
+    'id': 2,
+    'tags': ['dart', 'backend'],
+  };
+
+  // ListOr cleanly normalizes both scenarios without complex type checking.
+  final tags1 = ListOr<String>(jsonResponse1['tags']);
+  final tags2 = ListOr<String>(jsonResponse2['tags']);
+
+  print(
+    'Tags 1 contains "flutter": ${tags1.contains('flutter')}',
+  ); // Output: true
+  print('Tags 2 length: ${tags2.length}'); // Output: 2
+
+  print('\n--- Example 4: Handling Nulls with Nullable Types ---');
+  // If your data might explicitly be null and you want to keep that null
+  // as a valid single element, you must use a nullable generic type.
+  final nullableList = ListOr<int?>(null);
+
+  print('Nullable list length: ${nullableList.length}'); // Output: 1
+  print('First item: ${nullableList.first}'); // Output: null
+
+  // Note: Trying to do the following would throw an ArgumentError,
+  // keeping your types safe:
+  // final strictList = ListOr<int>(null); // THROWS!
+}