kasy-cli 1.17.0 → 1.19.0

package/templates/firebase/lib/features/home/home_components_preview_registry.dart

@@ -231,6 +231,36 @@ ComponentPreviewDefinition? getComponentPreviewDefinition(
           ),
         ],
       );
+    case 'DatePicker':
+      return const ComponentPreviewDefinition(
+        title: 'DatePicker',
+        variants: [
+          ComponentPreviewVariant(
+            label: 'Presentations',
+            builder: _buildDatePickerPresentations,
+          ),
+          ComponentPreviewVariant(
+            label: 'Range selection',
+            builder: _buildDatePickerRange,
+          ),
+          ComponentPreviewVariant(
+            label: 'Multi-month',
+            builder: _buildDatePickerMultiMonth,
+          ),
+          ComponentPreviewVariant(
+            label: 'Date formats',
+            builder: _buildDatePickerFormats,
+          ),
+          ComponentPreviewVariant(
+            label: 'Variants',
+            builder: _buildDatePickerVariants,
+          ),
+          ComponentPreviewVariant(
+            label: 'Field states',
+            builder: _buildDatePickerFieldStates,
+          ),
+        ],
+      );
     case 'Dialog':
       return const ComponentPreviewDefinition(
         title: 'Dialog',
@@ -654,6 +684,7 @@ class _SidebarPreviewState extends State<_SidebarPreview> {
 }
 
 
+// ─────────────────────────────────────────────────────────────────────────────
 // ─────────────────────────────────────────────────────────────────────────────
 // Tabs — interactive demos
 // ─────────────────────────────────────────────────────────────────────────────
@@ -667,6 +698,83 @@ Widget _buildTabsSecondaryVariant(BuildContext context) =>
 Widget _buildTabsFillModeVariant(BuildContext context) =>
     const _TabsFillModePreview();
 
+// ── Shared tab content helpers ────────────────────────────────────────────
+
+/// Fades [child] in when [tabIndex] == [currentIndex], out otherwise.
+///
+/// Used inside an [IndexedStack] so the content area never changes height —
+/// the stack always sizes to the tallest child and only the active one is
+/// visible.
+Widget _tabFade(int tabIndex, int currentIndex, Widget child) {
+  return AnimatedOpacity(
+    opacity: tabIndex == currentIndex ? 1.0 : 0.0,
+    duration: const Duration(milliseconds: 180),
+    curve: Curves.easeInOut,
+    child: child,
+  );
+}
+
+// ── Card container helper ─────────────────────────────────────────────────
+
+Widget _tabsCard(BuildContext context, Widget child) {
+  return DecoratedBox(
+    decoration: BoxDecoration(
+      color: context.colors.surface,
+      borderRadius: KasyRadius.lgBorderRadius,
+      border: Border.all(
+        color: context.colors.outline.withValues(alpha: 0.4),
+      ),
+    ),
+    child: child,
+  );
+}
+
+// ── Divider helper ────────────────────────────────────────────────────────
+
+Widget _tabsDivider(BuildContext context) => Divider(
+      height: 1,
+      thickness: 1,
+      indent: KasySpacing.md,
+      endIndent: KasySpacing.md,
+      color: context.colors.outline.withValues(alpha: 0.33),
+    );
+
+// ── Radio-style option row ────────────────────────────────────────────────
+
+/// Single-select option row that looks like a radio button using KasyCheckbox.
+class _RadioOptionTile extends StatelessWidget {
+  const _RadioOptionTile({
+    required this.label,
+    required this.description,
+    required this.selected,
+    required this.onTap,
+  });
+
+  final String label;
+  final String description;
+  final bool selected;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    return Padding(
+      padding: const EdgeInsets.symmetric(
+        horizontal: KasySpacing.md,
+        vertical: KasySpacing.smd,
+      ),
+      child: KasyCheckbox(
+        value: selected,
+        onChanged: (_) => onTap(),
+        label: label,
+        description: description,
+        style: const KasyCheckboxStyle(
+          shape: KasyCheckboxShape.circle,
+        ),
+      ),
+    );
+  }
+}
+
 // ── Primary variant ────────────────────────────────────────────────────────
 
 class _TabsPrimaryPreview extends StatefulWidget {
@@ -679,40 +787,239 @@ class _TabsPrimaryPreview extends StatefulWidget {
 class _TabsPrimaryPreviewState extends State<_TabsPrimaryPreview> {
   int _index = 0;
 
-  static const List<String> _tabs = ['Overview', 'Details', 'Settings'];
+  // General tab
+  final TextEditingController _urlController = TextEditingController();
+  bool _analytics = true;
+  bool _errorReports = false;
 
-  static const List<String> _content = [
-    'Overview content — a summary of the most important information at a glance.',
-    'Details content — in-depth information about each specific aspect.',
-    'Settings content — configure preferences and options here.',
-  ];
+  // Appearance tab
+  int _theme = 0; // 0=Auto 1=Light 2=Dark
+  int _fontSize = 1; // 0=Small 1=Medium 2=Large
+
+  // Notifications tab
+  bool _pushEnabled = true;
+  bool _emailEnabled = true;
+  bool _mentions = true;
+  bool _weeklyDigest = false;
+
+  // Profile tab
+  final TextEditingController _nameController =
+      TextEditingController(text: 'Paulo Morales');
+  final TextEditingController _usernameController =
+      TextEditingController(text: 'paulomorales');
 
   @override
-  Widget build(BuildContext context) {
-    final KasyColors c = context.colors;
+  void dispose() {
+    _urlController.dispose();
+    _nameController.dispose();
+    _usernameController.dispose();
+    super.dispose();
+  }
+
+  Widget _generalTab(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        Padding(
+          padding: const EdgeInsets.all(KasySpacing.md),
+          child: KasyTextField(
+            controller: _urlController,
+            variant: KasyTextFieldVariant.secondary,
+            label: 'Homepage URL',
+            hint: 'https://yoursite.com',
+          ),
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _analytics,
+          onChanged: (v) => setState(() => _analytics = v),
+          label: 'Enable analytics',
+          description: 'Collect anonymous usage data to improve the app',
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _errorReports,
+          onChanged: (v) => setState(() => _errorReports = v),
+          label: 'Send error reports',
+          description: 'Automatically share crash reports with the team',
+        ),
+      ],
+    );
+  }
+
+  Widget _appearanceTab(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        Padding(
+          padding: const EdgeInsets.fromLTRB(
+            KasySpacing.md,
+            KasySpacing.md,
+            KasySpacing.md,
+            KasySpacing.sm,
+          ),
+          child: Text(
+            'Theme',
+            style: context.textTheme.labelMedium?.copyWith(
+              color: context.colors.onSurface,
+              fontWeight: FontWeight.w600,
+            ),
+          ),
+        ),
+        _RadioOptionTile(
+          label: 'Auto',
+          description: 'Follows your system appearance',
+          selected: _theme == 0,
+          onTap: () => setState(() => _theme = 0),
+        ),
+        _tabsDivider(context),
+        _RadioOptionTile(
+          label: 'Light',
+          description: 'Always use the light theme',
+          selected: _theme == 1,
+          onTap: () => setState(() => _theme = 1),
+        ),
+        _tabsDivider(context),
+        _RadioOptionTile(
+          label: 'Dark',
+          description: 'Always use the dark theme',
+          selected: _theme == 2,
+          onTap: () => setState(() => _theme = 2),
+        ),
+        _tabsDivider(context),
+        Padding(
+          padding: const EdgeInsets.fromLTRB(
+            KasySpacing.md,
+            KasySpacing.md,
+            KasySpacing.md,
+            KasySpacing.sm,
+          ),
+          child: Text(
+            'Font size',
+            style: context.textTheme.labelMedium?.copyWith(
+              color: context.colors.onSurface,
+              fontWeight: FontWeight.w600,
+            ),
+          ),
+        ),
+        _RadioOptionTile(
+          label: 'Small',
+          description: 'Compact text for more content on screen',
+          selected: _fontSize == 0,
+          onTap: () => setState(() => _fontSize = 0),
+        ),
+        _tabsDivider(context),
+        _RadioOptionTile(
+          label: 'Medium',
+          description: 'Balanced size for most displays',
+          selected: _fontSize == 1,
+          onTap: () => setState(() => _fontSize = 1),
+        ),
+        _tabsDivider(context),
+        _RadioOptionTile(
+          label: 'Large',
+          description: 'Larger text for better readability',
+          selected: _fontSize == 2,
+          onTap: () => setState(() => _fontSize = 2),
+        ),
+      ],
+    );
+  }
+
+  Widget _notificationsTab(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        KasyCheckboxTile(
+          value: _pushEnabled,
+          onChanged: (v) => setState(() => _pushEnabled = v),
+          label: 'Push notifications',
+          description: 'Receive alerts directly on your device',
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _emailEnabled,
+          onChanged: (v) => setState(() => _emailEnabled = v),
+          label: 'Email notifications',
+          description: 'Get updates delivered to your inbox',
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _mentions,
+          onChanged: (v) => setState(() => _mentions = v),
+          label: 'Mentions and replies',
+          description: 'Notify when someone mentions or replies to you',
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _weeklyDigest,
+          onChanged: (v) => setState(() => _weeklyDigest = v),
+          label: 'Weekly digest',
+          description: 'A summary of activity sent every Monday',
+        ),
+      ],
+    );
+  }
+
+  Widget _profileTab(BuildContext context) {
+    return Padding(
+      padding: const EdgeInsets.all(KasySpacing.md),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          KasyTextField(
+            controller: _nameController,
+            variant: KasyTextFieldVariant.secondary,
+            label: 'Name',
+            hint: 'Your full name',
+            textInputAction: TextInputAction.next,
+          ),
+          const SizedBox(height: KasySpacing.md),
+          KasyTextField(
+            controller: _usernameController,
+            variant: KasyTextFieldVariant.secondary,
+            label: 'Username',
+            hint: 'yourhandle',
+            textInputAction: TextInputAction.done,
+          ),
+          const SizedBox(height: KasySpacing.md),
+          KasyButton(
+            label: 'Update profile',
+            onPressed: () {},
+          ),
+        ],
+      ),
+    );
+  }
 
+  @override
+  Widget build(BuildContext context) {
     return Column(
       crossAxisAlignment: CrossAxisAlignment.stretch,
       mainAxisSize: MainAxisSize.min,
       children: [
         KasyTabs(
-          tabs: _tabs,
+          tabs: const ['General', 'Appearance', 'Notifications', 'Profile'],
           selectedIndex: _index,
           onTabSelected: (i) => setState(() => _index = i),
         ),
         const SizedBox(height: KasySpacing.md),
-        AnimatedSwitcher(
-          duration: const Duration(milliseconds: 200),
-          child: KasyCard(
-            key: ValueKey(_index),
-            padding: const EdgeInsets.all(KasySpacing.md),
-            child: Text(
-              _content[_index],
-              style: context.textTheme.bodyMedium?.copyWith(
-                color: c.onSurface.withValues(alpha: 0.75),
-                height: 1.5,
-              ),
-            ),
+        // IndexedStack keeps height fixed at the tallest child (Appearance).
+        // AnimatedOpacity on each child provides the smooth crossfade.
+        _tabsCard(
+          context,
+          IndexedStack(
+            index: _index,
+            children: [
+              _tabFade(0, _index, _generalTab(context)),
+              _tabFade(1, _index, _appearanceTab(context)),
+              _tabFade(2, _index, _notificationsTab(context)),
+              _tabFade(3, _index, _profileTab(context)),
+            ],
           ),
         ),
         const SizedBox(height: KasySpacing.lg),
@@ -720,7 +1027,7 @@ class _TabsPrimaryPreviewState extends State<_TabsPrimaryPreview> {
         Text(
           'WITH DISABLED TAB',
           style: context.textTheme.labelSmall?.copyWith(
-            color: c.muted,
+            color: context.colors.muted,
             letterSpacing: 1.2,
             fontWeight: FontWeight.w700,
           ),
@@ -752,41 +1059,146 @@ class _TabsSecondaryPreview extends StatefulWidget {
 class _TabsSecondaryPreviewState extends State<_TabsSecondaryPreview> {
   int _index = 0;
 
-  static const List<String> _tabs = ['Inbox', 'Sent', 'Drafts'];
+  // General tab
+  final TextEditingController _siteController = TextEditingController();
+  bool _cacheEnabled = true;
+  bool _debugMode = false;
 
-  static const List<String> _content = [
-    'Inbox — your incoming messages appear here.',
-    'Sent — messages you have already sent.',
-    'Drafts — unfinished messages saved for later.',
-  ];
+  // Notifications tab
+  bool _pushEnabled = true;
+  bool _emailEnabled = false;
+  bool _weeklyDigest = true;
+
+  // Profile tab
+  final TextEditingController _nameController =
+      TextEditingController(text: 'Paulo Morales');
+  final TextEditingController _emailController =
+      TextEditingController(text: 'paulo@kasy.dev');
 
   @override
-  Widget build(BuildContext context) {
-    final KasyColors c = context.colors;
+  void dispose() {
+    _siteController.dispose();
+    _nameController.dispose();
+    _emailController.dispose();
+    super.dispose();
+  }
+
+  Widget _generalTab(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        Padding(
+          padding: const EdgeInsets.all(KasySpacing.md),
+          child: KasyTextField(
+            controller: _siteController,
+            variant: KasyTextFieldVariant.secondary,
+            label: 'Site URL',
+            hint: 'https://yoursite.com',
+          ),
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _cacheEnabled,
+          onChanged: (v) => setState(() => _cacheEnabled = v),
+          label: 'Enable caching',
+          description: 'Speed up page loads with local cache',
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _debugMode,
+          onChanged: (v) => setState(() => _debugMode = v),
+          label: 'Debug mode',
+          description: 'Show detailed logs and error messages',
+        ),
+      ],
+    );
+  }
 
+  Widget _notificationsTab(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        KasyCheckboxTile(
+          value: _pushEnabled,
+          onChanged: (v) => setState(() => _pushEnabled = v),
+          label: 'Push notifications',
+          description: 'Receive alerts directly on your device',
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _emailEnabled,
+          onChanged: (v) => setState(() => _emailEnabled = v),
+          label: 'Email notifications',
+          description: 'Get updates delivered to your inbox',
+        ),
+        _tabsDivider(context),
+        KasyCheckboxTile(
+          value: _weeklyDigest,
+          onChanged: (v) => setState(() => _weeklyDigest = v),
+          label: 'Weekly digest',
+          description: 'A summary of activity sent every Monday',
+        ),
+      ],
+    );
+  }
+
+  Widget _profileTab(BuildContext context) {
+    return Padding(
+      padding: const EdgeInsets.all(KasySpacing.md),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          KasyTextField(
+            controller: _nameController,
+            variant: KasyTextFieldVariant.secondary,
+            label: 'Name',
+            hint: 'Your full name',
+            textInputAction: TextInputAction.next,
+          ),
+          const SizedBox(height: KasySpacing.md),
+          KasyTextField(
+            controller: _emailController,
+            variant: KasyTextFieldVariant.secondary,
+            label: 'Email',
+            hint: 'email@example.com',
+            contentType: KasyTextFieldContentType.email,
+            textInputAction: TextInputAction.done,
+          ),
+          const SizedBox(height: KasySpacing.md),
+          KasyButton(
+            label: 'Save changes',
+            onPressed: () {},
+          ),
+        ],
+      ),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
     return Column(
       crossAxisAlignment: CrossAxisAlignment.stretch,
       mainAxisSize: MainAxisSize.min,
       children: [
         KasyTabs(
-          tabs: _tabs,
+          tabs: const ['General', 'Notifications', 'Profile'],
           selectedIndex: _index,
           onTabSelected: (i) => setState(() => _index = i),
           variant: KasyTabsVariant.secondary,
         ),
         const SizedBox(height: KasySpacing.md),
-        AnimatedSwitcher(
-          duration: const Duration(milliseconds: 200),
-          child: KasyCard(
-            key: ValueKey(_index),
-            padding: const EdgeInsets.all(KasySpacing.md),
-            child: Text(
-              _content[_index],
-              style: context.textTheme.bodyMedium?.copyWith(
-                color: c.onSurface.withValues(alpha: 0.75),
-                height: 1.5,
-              ),
-            ),
+        _tabsCard(
+          context,
+          IndexedStack(
+            index: _index,
+            children: [
+              _tabFade(0, _index, _generalTab(context)),
+              _tabFade(1, _index, _notificationsTab(context)),
+              _tabFade(2, _index, _profileTab(context)),
+            ],
           ),
         ),
         const SizedBox(height: KasySpacing.lg),
@@ -794,7 +1206,7 @@ class _TabsSecondaryPreviewState extends State<_TabsSecondaryPreview> {
         Text(
           'WITH ICONS',
           style: context.textTheme.labelSmall?.copyWith(
-            color: c.muted,
+            color: context.colors.muted,
             letterSpacing: 1.2,
             fontWeight: FontWeight.w700,
           ),
@@ -826,14 +1238,19 @@ class _TabsFillModePreview extends StatefulWidget {
 
 class _TabsFillModePreviewState extends State<_TabsFillModePreview> {
   int _primaryIndex = 0;
-  int _secondaryIndex = 0;
+  int _iconIndex = 0;
+
+  static const List<String> _primaryContent = [
+    'Overview — see a high-level summary of your project status and recent activity.',
+    'Analytics — track metrics like sessions, retention, and conversion rates over time.',
+    'Settings — manage project configuration, integrations, and team access.',
+  ];
 
   @override
   Widget build(BuildContext context) {
-    final KasyColors c = context.colors;
-    final TextStyle labelStyle =
+    final TextStyle sectionLabel =
         context.textTheme.labelSmall?.copyWith(
-          color: c.muted,
+          color: context.colors.muted,
           letterSpacing: 1.2,
           fontWeight: FontWeight.w700,
         ) ??
@@ -843,38 +1260,52 @@ class _TabsFillModePreviewState extends State<_TabsFillModePreview> {
       crossAxisAlignment: CrossAxisAlignment.stretch,
       mainAxisSize: MainAxisSize.min,
       children: [
-        Text('PRIMARY + FILL', style: labelStyle),
+        Text('PRIMARY FILL', style: sectionLabel),
         const SizedBox(height: KasySpacing.sm),
         KasyTabs(
-          tabs: const ['Tab 1', 'Tab 2', 'Tab 3'],
+          tabs: const ['Overview', 'Analytics', 'Settings'],
           selectedIndex: _primaryIndex,
           onTabSelected: (i) => setState(() => _primaryIndex = i),
           mode: KasyTabsMode.fill,
         ),
-        const SizedBox(height: KasySpacing.lg),
-        Text('SECONDARY + FILL', style: labelStyle),
-        const SizedBox(height: KasySpacing.sm),
-        KasyTabs(
-          tabs: const ['Tab 1', 'Tab 2', 'Tab 3'],
-          selectedIndex: _secondaryIndex,
-          onTabSelected: (i) => setState(() => _secondaryIndex = i),
-          variant: KasyTabsVariant.secondary,
-          mode: KasyTabsMode.fill,
-        ),
         const SizedBox(height: KasySpacing.md),
-        AnimatedSwitcher(
-          duration: const Duration(milliseconds: 200),
-          child: KasyCard(
-            key: ValueKey('fill_$_secondaryIndex'),
+        _tabsCard(
+          context,
+          Padding(
             padding: const EdgeInsets.all(KasySpacing.md),
-            child: Text(
-              'Content for Tab ${_secondaryIndex + 1}',
-              style: context.textTheme.bodyMedium?.copyWith(
-                color: c.onSurface.withValues(alpha: 0.75),
+            child: IndexedStack(
+              index: _primaryIndex,
+              children: List.generate(
+                _primaryContent.length,
+                (i) => _tabFade(
+                  i,
+                  _primaryIndex,
+                  Text(
+                    _primaryContent[i],
+                    style: context.textTheme.bodyMedium?.copyWith(
+                      color: context.colors.onSurface.withValues(alpha: 0.75),
+                      height: 1.5,
+                    ),
+                  ),
+                ),
               ),
             ),
           ),
         ),
+        const SizedBox(height: KasySpacing.lg),
+        Text('SECONDARY FILL + ICONS', style: sectionLabel),
+        const SizedBox(height: KasySpacing.sm),
+        KasyTabs.items(
+          items: const [
+            KasyTabItem(label: 'Home', icon: KasyIcons.home),
+            KasyTabItem(label: 'Profile', icon: KasyIcons.person),
+            KasyTabItem(label: 'Settings', icon: KasyIcons.settings),
+          ],
+          selectedIndex: _iconIndex,
+          onTabSelected: (i) => setState(() => _iconIndex = i),
+          variant: KasyTabsVariant.secondary,
+          mode: KasyTabsMode.fill,
+        ),
       ],
     );
   }
@@ -1199,7 +1630,7 @@ Widget _buildAvatarGroupVariant(BuildContext context) {
   // Shared gradient avatars list
   final List<Widget> gradients = [
     KasyAvatar.gradientFill(size: KasyAvatarSize.small, diameter: d, showShadow: false, gradient: KasyAvatarGradients.blue),
-    KasyAvatar.gradientFill(size: KasyAvatarSize.small, diameter: d, showShadow: false, gradient: KasyAvatarGradients.teal),
+    KasyAvatar.gradientFill(size: KasyAvatarSize.small, diameter: d, showShadow: false, gradient: KasyAvatarGradients.sky),
     KasyAvatar.gradientFill(size: KasyAvatarSize.small, diameter: d, showShadow: false, gradient: KasyAvatarGradients.orange),
     KasyAvatar.gradientFill(size: KasyAvatarSize.small, diameter: d, showShadow: false, gradient: KasyAvatarGradients.red),
     KasyAvatar.gradientFill(size: KasyAvatarSize.small, diameter: d, showShadow: false, gradient: KasyAvatarGradients.silver),
@@ -2096,7 +2527,7 @@ Widget _buildBadgeDefault(BuildContext context) {
               child: KasyAvatar.gradientFill(
                 size: KasyAvatarSize.medium,
                 showShadow: false,
-                gradient: KasyAvatarGradients.teal,
+                gradient: KasyAvatarGradients.sky,
               ),
             ),
             const SizedBox(height: KasySpacing.sm),
@@ -4028,9 +4459,9 @@ class _BadgeColorsPreview extends StatelessWidget {
       KasyBadgeTone.warning,
       KasyBadgeTone.danger,
     ];
-    final List<Gradient> gradients = [
+    final List<KasyAvatarGradientData> gradients = [
       KasyAvatarGradients.blue,
-      KasyAvatarGradients.teal,
+      KasyAvatarGradients.sky,
       KasyAvatarGradients.purple,
       KasyAvatarGradients.orange,
       KasyAvatarGradients.red,
@@ -4153,9 +4584,9 @@ class _BadgePlacementsPreview extends StatelessWidget {
 class _BadgeDotPreview extends StatelessWidget {
   const _BadgeDotPreview();
 
-  static const List<(KasyBadgeTone, Gradient)> _items = [
+  static const List<(KasyBadgeTone, KasyAvatarGradientData)> _items = [
     (KasyBadgeTone.neutral, KasyAvatarGradients.blue),
-    (KasyBadgeTone.primary, KasyAvatarGradients.teal),
+    (KasyBadgeTone.primary, KasyAvatarGradients.sky),
     (KasyBadgeTone.success, KasyAvatarGradients.purple),
     (KasyBadgeTone.warning, KasyAvatarGradients.red),
     (KasyBadgeTone.danger, KasyAvatarGradients.orange),
@@ -4197,9 +4628,9 @@ class _BadgeVariantsPreview extends StatelessWidget {
     KasyBadgeTone.danger,
   ];
 
-  static const List<Gradient> _gradients = [
+  static const List<KasyAvatarGradientData> _gradients = [
     KasyAvatarGradients.blue,
-    KasyAvatarGradients.teal,
+    KasyAvatarGradients.sky,
     KasyAvatarGradients.purple,
     KasyAvatarGradients.red,
     KasyAvatarGradients.orange,
@@ -4332,7 +4763,7 @@ class _BadgeWithContentPreview extends StatelessWidget {
 class _BadgeContentItem extends StatelessWidget {
   final String label;
   final KasyBadge badge;
-  final Gradient gradient;
+  final KasyAvatarGradientData gradient;
 
   const _BadgeContentItem({
     required this.label,
@@ -8119,3 +8550,444 @@ class _SwipePreviewTile extends StatelessWidget {
     );
   }
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DatePicker — Presentations
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Maps the running app's locale onto a [KasyDatePickerLocale] preset so the
+/// preview demonstrates the same regional defaults (month names, week start,
+/// date format) the user would see in their own app.
+KasyDatePickerLocale _datePickerLocaleForApp(BuildContext context) {
+  switch (Localizations.localeOf(context).languageCode) {
+    case 'es':
+      return KasyDatePickerLocale.es;
+    case 'pt':
+      return KasyDatePickerLocale.pt;
+    default:
+      return KasyDatePickerLocale.en;
+  }
+}
+
+Widget _buildDatePickerPresentations(BuildContext context) =>
+    const _DatePickerPresentationsPreview();
+
+class _DatePickerPresentationsPreview extends StatefulWidget {
+  const _DatePickerPresentationsPreview();
+
+  @override
+  State<_DatePickerPresentationsPreview> createState() =>
+      _DatePickerPresentationsPreviewState();
+}
+
+class _DatePickerPresentationsPreviewState
+    extends State<_DatePickerPresentationsPreview> {
+  DateTime? _popoverDate;
+  DateTime? _dialogDate;
+  DateTime? _sheetDate;
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyDatePickerLocale locale = _datePickerLocaleForApp(context);
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        KasyDatePicker(
+          label: 'Popover',
+          placeholder: 'Choose a date',
+          value: _popoverDate,
+          onChanged: (d) => setState(() => _popoverDate = d),
+          locale: locale,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        KasyDatePicker(
+          label: 'Dialog',
+          placeholder: 'Choose a date',
+          value: _dialogDate,
+          onChanged: (d) => setState(() => _dialogDate = d),
+          presentation: KasyDatePickerPresentation.dialog,
+          locale: locale,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        KasyDatePicker(
+          label: 'Bottom sheet',
+          placeholder: 'Choose a date',
+          value: _sheetDate,
+          onChanged: (d) => setState(() => _sheetDate = d),
+          presentation: KasyDatePickerPresentation.bottomSheet,
+          locale: locale,
+        ),
+      ],
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DatePicker — Range selection (Airbnb-style start + end)
+// ─────────────────────────────────────────────────────────────────────────────
+
+Widget _buildDatePickerRange(BuildContext context) =>
+    const _DatePickerRangePreview();
+
+class _DatePickerRangePreview extends StatefulWidget {
+  const _DatePickerRangePreview();
+
+  @override
+  State<_DatePickerRangePreview> createState() =>
+      _DatePickerRangePreviewState();
+}
+
+class _DatePickerRangePreviewState extends State<_DatePickerRangePreview> {
+  KasyDateRange? _stay;
+  KasyDateRange? _project;
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyDatePickerLocale locale = _datePickerLocaleForApp(context);
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        // Classic stay-style picker: tap a check-in date, then a check-out
+        // date. The calendar keeps the start highlighted while waiting for
+        // the end, then auto-closes after the second tap.
+        KasyDatePicker(
+          label: 'Stay',
+          placeholder: 'Check-in  ->  Check-out',
+          description: 'Tap a start date, then an end date.',
+          selectionMode: KasyDateSelectionMode.range,
+          range: _stay,
+          onRangeChanged: (r) => setState(() => _stay = r),
+          locale: locale,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        // Dialog presentation of the same range mode — handy on smaller
+        // screens where the popover may not have enough room.
+        KasyDatePicker(
+          label: 'Project window (dialog)',
+          placeholder: 'Pick start  ->  end',
+          selectionMode: KasyDateSelectionMode.range,
+          range: _project,
+          onRangeChanged: (r) => setState(() => _project = r),
+          presentation: KasyDatePickerPresentation.dialog,
+          locale: locale,
+        ),
+      ],
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DatePicker — Multi-month (2 or 3 months side by side, Airbnb desktop look)
+// ─────────────────────────────────────────────────────────────────────────────
+
+Widget _buildDatePickerMultiMonth(BuildContext context) =>
+    const _DatePickerMultiMonthPreview();
+
+class _DatePickerMultiMonthPreview extends StatefulWidget {
+  const _DatePickerMultiMonthPreview();
+
+  @override
+  State<_DatePickerMultiMonthPreview> createState() =>
+      _DatePickerMultiMonthPreviewState();
+}
+
+class _DatePickerMultiMonthPreviewState
+    extends State<_DatePickerMultiMonthPreview> {
+  KasyDateRange? _stay;
+  DateTime? _single;
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyDatePickerLocale locale = _datePickerLocaleForApp(context);
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        // 3-month layout combined with range selection — the classic
+        // Airbnb / Booking desktop pattern for picking a stay.
+        KasyDatePicker(
+          label: '3 months  +  range',
+          placeholder: 'Check-in  ->  Check-out',
+          description: 'Pass monthsToShow: 3 to opt in. Best on wide canvases.',
+          selectionMode: KasyDateSelectionMode.range,
+          range: _stay,
+          onRangeChanged: (r) => setState(() => _stay = r),
+          monthsToShow: 3,
+          locale: locale,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        // 2-month layout in single-date mode — useful when there's enough
+        // horizontal room but you still want one tap to commit.
+        KasyDatePicker(
+          label: '2 months  +  single date',
+          placeholder: 'Pick a date',
+          value: _single,
+          onChanged: (d) => setState(() => _single = d),
+          monthsToShow: 2,
+          locale: locale,
+        ),
+      ],
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DatePicker — Variants (filled, no backdrop, no suffix, no focus border)
+// ─────────────────────────────────────────────────────────────────────────────
+
+Widget _buildDatePickerVariants(BuildContext context) =>
+    const _DatePickerVariantsPreview();
+
+class _DatePickerVariantsPreview extends StatefulWidget {
+  const _DatePickerVariantsPreview();
+
+  @override
+  State<_DatePickerVariantsPreview> createState() =>
+      _DatePickerVariantsPreviewState();
+}
+
+class _DatePickerVariantsPreviewState
+    extends State<_DatePickerVariantsPreview> {
+  DateTime? _filledDate;
+  DateTime? _noBarrierDate;
+  DateTime? _noSuffixDate;
+  DateTime? _noFocusDate;
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyDatePickerLocale locale = _datePickerLocaleForApp(context);
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        // Filled / flat surface — matches KasyTextField.secondary, useful on
+        // backgrounds where the default drop shadow feels heavy.
+        KasyDatePicker(
+          label: 'Filled (no shadow)',
+          placeholder: 'Choose a date',
+          value: _filledDate,
+          onChanged: (d) => setState(() => _filledDate = d),
+          variant: KasyTextFieldVariant.secondary,
+          locale: locale,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        // Popover without the dimmed backdrop — feels lighter / tooltip-like.
+        KasyDatePicker(
+          label: 'No backdrop',
+          placeholder: 'Choose a date',
+          description: 'Popover floats over the page without a dimmed scrim.',
+          value: _noBarrierDate,
+          onChanged: (d) => setState(() => _noBarrierDate = d),
+          showBarrier: false,
+          locale: locale,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        // No calendar icon in the suffix slot.
+        KasyDatePicker(
+          label: 'No suffix icon',
+          placeholder: 'Choose a date',
+          value: _noSuffixDate,
+          onChanged: (d) => setState(() => _noSuffixDate = d),
+          showSuffix: false,
+          locale: locale,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        // Disables the blue focus outline while the calendar is open — quieter
+        // affordance for very dense forms.
+        KasyDatePicker(
+          label: 'No focus border',
+          placeholder: 'Choose a date',
+          value: _noFocusDate,
+          onChanged: (d) => setState(() => _noFocusDate = d),
+          focusBorder: false,
+          locale: locale,
+        ),
+      ],
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DatePicker — Date formats
+// ─────────────────────────────────────────────────────────────────────────────
+
+Widget _buildDatePickerFormats(BuildContext context) =>
+    const _DatePickerFormatsPreview();
+
+const List<String> _kEnglishMonthsLong = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+];
+
+String _longUsFormat(DateTime d) =>
+    '${_kEnglishMonthsLong[d.month - 1]} ${d.day}, ${d.year}';
+
+class _DatePickerFormatsPreview extends StatefulWidget {
+  const _DatePickerFormatsPreview();
+
+  @override
+  State<_DatePickerFormatsPreview> createState() =>
+      _DatePickerFormatsPreviewState();
+}
+
+// Each tab maps to one preset (or to the "Auto" / "Custom" entries). The
+// `format` field is null for the two non-preset entries; the build method
+// branches on those.
+class _DatePickerFormatOption {
+  const _DatePickerFormatOption({
+    required this.label,
+    required this.description,
+    this.format,
+    this.useAppLocale = false,
+    this.customFormat,
+  });
+
+  final String label;
+  final String description;
+  final KasyDateFormat? format;
+  final bool useAppLocale;
+  final String Function(DateTime)? customFormat;
+}
+
+const List<_DatePickerFormatOption> _kDatePickerFormatOptions = [
+  _DatePickerFormatOption(
+    label: 'Auto',
+    description: 'Follows the active app language (US, South American, …).',
+    useAppLocale: true,
+  ),
+  _DatePickerFormatOption(
+    label: 'US',
+    description: 'MM / DD / YYYY — United States.',
+    format: KasyDateFormat.us,
+  ),
+  _DatePickerFormatOption(
+    label: 'South American',
+    description: 'DD / MM / YYYY — South America, UK, Spain, Portugal.',
+    format: KasyDateFormat.southAmerican,
+  ),
+  _DatePickerFormatOption(
+    label: 'European',
+    description: 'DD.MM.YYYY — Germany, Austria, Switzerland.',
+    format: KasyDateFormat.european,
+  ),
+  _DatePickerFormatOption(
+    label: 'ISO 8601',
+    description: 'YYYY-MM-DD — international standard.',
+    format: KasyDateFormat.iso,
+  ),
+  _DatePickerFormatOption(
+    label: 'East Asian',
+    description: 'YYYY / MM / DD — Japan, China, Korea.',
+    format: KasyDateFormat.eastAsian,
+  ),
+  _DatePickerFormatOption(
+    label: 'Custom',
+    description: 'Any layout via the formatDate callback (long form here).',
+    customFormat: _longUsFormat,
+  ),
+];
+
+class _DatePickerFormatsPreviewState extends State<_DatePickerFormatsPreview> {
+  int _tab = 0;
+  DateTime _date = DateTime(2026, 5, 12);
+
+  @override
+  Widget build(BuildContext context) {
+    final _DatePickerFormatOption option = _kDatePickerFormatOptions[_tab];
+    final KasyDatePickerLocale appLocale = _datePickerLocaleForApp(context);
+
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        // Secondary (underline) variant keeps the format switcher visually
+        // light on phones — pill tabs were too bulky for a switch with many
+        // labels and hug mode lets the row scroll horizontally when needed.
+        KasyTabs(
+          tabs: [
+            for (final o in _kDatePickerFormatOptions) o.label,
+          ],
+          selectedIndex: _tab,
+          onTabSelected: (i) => setState(() => _tab = i),
+          variant: KasyTabsVariant.secondary,
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        KasyDatePicker(
+          label: option.label,
+          description: option.description,
+          value: _date,
+          onChanged: (d) => setState(() => _date = d),
+          locale: option.useAppLocale ? appLocale : KasyDatePickerLocale.en,
+          dateFormat: option.format,
+          formatDate: option.customFormat,
+        ),
+      ],
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DatePicker — Field states
+// ─────────────────────────────────────────────────────────────────────────────
+
+Widget _buildDatePickerFieldStates(BuildContext context) =>
+    const _DatePickerFieldStatesPreview();
+
+const List<String> _kEnglishMonthAbbrev = [
+  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+
+String _abbrevFormat(DateTime d) =>
+    '${_kEnglishMonthAbbrev[d.month - 1]} ${d.day}, ${d.year}';
+
+class _DatePickerFieldStatesPreview extends StatefulWidget {
+  const _DatePickerFieldStatesPreview();
+
+  @override
+  State<_DatePickerFieldStatesPreview> createState() =>
+      _DatePickerFieldStatesPreviewState();
+}
+
+class _DatePickerFieldStatesPreviewState
+    extends State<_DatePickerFieldStatesPreview> {
+  DateTime? _deadline;
+  DateTime? _shipDate;
+  final DateTime _disabledDate = DateTime(2026, 6, 15);
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        KasyDatePicker(
+          label: 'Deadline',
+          placeholder: 'Select a deadline',
+          showRequiredIndicator: true,
+          description: 'Required for the project timeline.',
+          value: _deadline,
+          onChanged: (d) => setState(() => _deadline = d),
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        KasyDatePicker(
+          label: 'Ship date',
+          placeholder: 'Choose a date',
+          errorText: 'Please select a valid ship date.',
+          value: _shipDate,
+          onChanged: (d) => setState(() => _shipDate = d),
+        ),
+        const SizedBox(height: KasySpacing.lg),
+        KasyDatePicker(
+          label: 'Disabled date',
+          enabled: false,
+          value: _disabledDate,
+          formatDate: _abbrevFormat,
+          description: 'The date cannot be changed when the order is locked.',
+        ),
+      ],
+    );
+  }
+}