@app-studio/web 0.9.41 → 0.9.44

package/docs/components/Loader.mdx

@@ -1,527 +1,344 @@
 # Loader
 
-A versatile loading indicator component with multiple animation types, customizable sizes, colors, and text positioning. Perfect for showing loading states, progress indicators, and providing visual feedback during asynchronous operations.
+A loading indicator component with multiple types, sizes, speeds, and text positioning options.
 
 ### **Import**
-  ```tsx
-  import { Loader } from '@app-studio/web';
-  ```
+```tsx
+import { Loader } from '@app-studio/web';
+```
 
-### **Basic Usage**
+### **Default**
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
 
-export const BasicLoader = () => (
-  <Loader>Loading...</Loader>
+export const DefaultLoader = () => (
+  <Loader />
 );
 ```
 
-### **Loader Types**
+### **type**
+Defines the type of the loader.
+
+- **Type:** `LoaderType`
+- **Default:** `'spinner'`
+- **Possible Values:** `'spinner' | 'dotted' | 'quarter' | 'pulse' | 'bars'`
+
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
-import { Vertical, Horizontal } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
 
 export const LoaderTypes = () => (
-  <Vertical gap={24}>
-    <Horizontal gap={32} alignItems="center">
-      <Loader type="default">Default Spinner</Loader>
-      <Loader type="dotted">Dotted Loader</Loader>
-      <Loader type="quarter">Quarter Loader</Loader>
-    </Horizontal>
-  </Vertical>
+  <Horizontal gap={30}>
+    <Loader type="spinner" />
+    <Loader type="dotted" />
+    <Loader type="quarter" />
+    <Loader type="pulse" />
+    <Loader type="bars" />
+  </Horizontal>
 );
 ```
 
-### **Loader Sizes**
+### **size**
+Sets the size of the loader.
+
+- **Type:** `number | Size`
+- **Default:** `'md'`
+- **Possible Values:** `'xs' | 'sm' | 'md' | 'lg' | 'xl'` or pixel number
+
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
-import { Horizontal } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
 
 export const LoaderSizes = () => (
-  <Horizontal gap={24} alignItems="center">
-    <Loader size="xs">XS</Loader>
-    <Loader size="sm">Small</Loader>
-    <Loader size="md">Medium</Loader>
-    <Loader size="lg">Large</Loader>
-    <Loader size="xl">XL</Loader>
+  <Horizontal gap={20} alignItems="center">
+    <Loader size="xs" />
+    <Loader size="sm" />
+    <Loader size="md" />
+    <Loader size="lg" />
+    <Loader size="xl" />
   </Horizontal>
 );
 ```
 
-### **Custom Sizes**
+### **Custom Size**
+Using pixel values for custom sizes.
+
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
-import { Horizontal } from '@app-studio/web';
-
-export const CustomSizes = () => (
-  <Horizontal gap={24} alignItems="center">
-    <Loader size={16}>16px</Loader>
-    <Loader size={32}>32px</Loader>
-    <Loader size={48}>48px</Loader>
-    <Loader size={64}>64px</Loader>
+import { Horizontal } from 'app-studio';
+
+export const CustomSizeLoaders = () => (
+  <Horizontal gap={20} alignItems="center">
+    <Loader size={16} />
+    <Loader size={32} />
+    <Loader size={48} />
+    <Loader size={64} />
   </Horizontal>
 );
 ```
 
-### **Text Positioning**
-```tsx
-import React from 'react';
-import { Loader } from '@app-studio/web';
-import { Vertical } from '@app-studio/web';
-
-export const TextPositioning = () => (
-  <Vertical gap={32}>
-    <Loader textPosition="right">Loading (Right)</Loader>
-    <Loader textPosition="left">Loading (Left)</Loader>
-    <Loader textPosition="top">Loading (Top)</Loader>
-    <Loader textPosition="bottom">Loading (Bottom)</Loader>
-  </Vertical>
-);
-```
+### **loaderColor**
+Defines the color of the loader element.
+
+- **Type:** `string`
 
-### **Colors and Theming**
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
-import { Vertical } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
 
 export const ColoredLoaders = () => (
-  <Vertical gap={20}>
-    <Loader
-      loaderColor="color.blue.500"
-      textColor="color.blue.700"
-    >
-      Blue Loader
-    </Loader>
-
-    <Loader
-      loaderColor="color.green.500"
-      textColor="color.green.700"
-    >
-      Green Loader
-    </Loader>
-
-    <Loader
-      loaderColor="color.red.500"
-      textColor="color.red.700"
-    >
-      Red Loader
-    </Loader>
-
-    <Loader
-      loaderColor="theme.primary"
-      textColor="theme.primary"
-    >
-      Theme Primary
-    </Loader>
-  </Vertical>
+  <Horizontal gap={30}>
+    <Loader loaderColor="#3b82f6" />
+    <Loader loaderColor="#10b981" />
+    <Loader loaderColor="#ef4444" />
+    <Loader loaderColor="#f59e0b" />
+    <Loader loaderColor="#8b5cf6" />
+  </Horizontal>
 );
 ```
 
-### **Animation Speeds**
+### **speed**
+Controls the speed of the loader's animation.
+
+- **Type:** `Speed`
+- **Default:** `'normal'`
+- **Possible Values:** `'slow' | 'normal' | 'fast'`
+
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
-import { Horizontal } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
 
-export const AnimationSpeeds = () => (
-  <Horizontal gap={32} alignItems="center">
-    <Loader speed="slow">Slow</Loader>
-    <Loader speed="normal">Normal</Loader>
-    <Loader speed="fast">Fast</Loader>
+export const LoaderSpeeds = () => (
+  <Horizontal gap={30}>
+    <Loader speed="slow" />
+    <Loader speed="normal" />
+    <Loader speed="fast" />
   </Horizontal>
 );
 ```
 
-### **Loading States in Components**
-```tsx
-import React, { useState } from 'react';
-import { Loader } from '@app-studio/web';
-import { Button } from '@app-studio/web';
-import { View, Text, Vertical } from '@app-studio/web';
+### **children**
+Text or content to display with the loader.
 
-export const LoadingStates = () => {
-  const [isLoading, setIsLoading] = useState(false);
-  const [data, setData] = useState(null);
-
-  const handleLoad = async () => {
-    setIsLoading(true);
-    // Simulate API call
-    setTimeout(() => {
-      setData('Data loaded successfully!');
-      setIsLoading(false);
-    }, 2000);
-  };
+- **Type:** `React.ReactNode`
 
-  return (
-    <Vertical gap={20} alignItems="center">
-      <Button onClick={handleLoad} disabled={isLoading}>
-        Load Data
-      </Button>
+```tsx
+import React from 'react';
+import { Loader } from '@app-studio/web';
 
-      <View
-        height={100}
-        width={300}
-        border="1px solid"
-        borderColor="color.gray.200"
-        borderRadius={8}
-        display="flex"
-        alignItems="center"
-        justifyContent="center"
-      >
-        {isLoading ? (
-          <Loader loaderColor="theme.primary">
-            Loading data...
-          </Loader>
-        ) : data ? (
-          <Text color="color.green.600">{data}</Text>
-        ) : (
-          <Text color="color.gray.500">No data loaded</Text>
-        )}
-      </View>
-    </Vertical>
-  );
-};
+export const LoaderWithText = () => (
+  <Loader>Loading...</Loader>
+);
 ```
 
-### **Props**
-
-| Prop | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| children | React.ReactNode | undefined | Text to display alongside the loader |
-| type | `'default' \| 'dotted' \| 'quarter'` | 'default' | Type of loading animation |
-| size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | 'md' | Size of the loader |
-| speed | `'slow' \| 'normal' \| 'fast'` | 'normal' | Animation speed |
-| loaderColor | string | 'currentColor' | Color of the loader animation |
-| textColor | string | 'currentColor' | Color of the text |
-| textPosition | `'left' \| 'right' \| 'top' \| 'bottom'` | 'right' | Position of text relative to loader |
+### **textPosition**
+Determines the position of the text relative to the loader.
 
-**Inherited ViewProps:**
-- All standard view properties like `margin`, `padding`, `width`, `height`
-- Layout properties like `display`, `position`, `flex`
-- Styling properties like `backgroundColor`, `borderRadius`
+- **Type:** `TextPosition`
+- **Default:** `'bottom'`
+- **Possible Values:** `'top' | 'bottom' | 'left' | 'right'`
 
-### **Full Page Loading**
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
-import { Center } from '@app-studio/web';
-
-export const FullPageLoader = () => (
-  <Center
-    position="fixed"
-    top={0}
-    left={0}
-    right={0}
-    bottom={0}
-    backgroundColor="rgba(255, 255, 255, 0.9)"
-    zIndex={9999}
-  >
-    <Loader
-      size="lg"
-      loaderColor="theme.primary"
-      textColor="theme.primary"
-    >
-      Loading application...
-    </Loader>
-  </Center>
+import { Vertical } from 'app-studio';
+
+export const TextPositions = () => (
+  <Vertical gap={30}>
+    <Loader textPosition="top">Loading from top</Loader>
+    <Loader textPosition="bottom">Loading from bottom</Loader>
+    <Loader textPosition="left">Loading from left</Loader>
+    <Loader textPosition="right">Loading from right</Loader>
+  </Vertical>
 );
 ```
 
-### **Inline Loading**
-```tsx
-import React, { useState } from 'react';
-import { Loader } from '@app-studio/web';
-import { Button } from '@app-studio/web';
-import { Horizontal, Text } from '@app-studio/web';
-
-export const InlineLoader = () => {
-  const [saving, setSaving] = useState(false);
+### **textColor**
+Sets the color of the text displayed with the loader.
 
-  const handleSave = () => {
-    setSaving(true);
-    setTimeout(() => setSaving(false), 2000);
-  };
+- **Type:** `string`
 
-  return (
-    <Horizontal gap={16} alignItems="center">
-      <Button onClick={handleSave} disabled={saving}>
-        Save Changes
-      </Button>
-
-      {saving && (
-        <Loader size="sm" loaderColor="color.blue.500">
-          Saving...
-        </Loader>
-      )}
-
-      {!saving && (
-        <Text color="color.green.600" fontSize={14}>
-          All changes saved
-        </Text>
-      )}
-    </Horizontal>
-  );
-};
-```
-
-### **Card Loading State**
 ```tsx
-import React, { useState, useEffect } from 'react';
+import React from 'react';
 import { Loader } from '@app-studio/web';
-import { View, Text, Vertical } from '@app-studio/web';
-
-export const CardLoader = () => {
-  const [loading, setLoading] = useState(true);
-  const [content, setContent] = useState(null);
-
-  useEffect(() => {
-    // Simulate data loading
-    setTimeout(() => {
-      setContent({
-        title: 'Card Title',
-        description: 'This is the card content that was loaded.',
-      });
-      setLoading(false);
-    }, 3000);
-  }, []);
 
-  return (
-    <View
-      width={300}
-      height={200}
-      border="1px solid"
-      borderColor="color.gray.200"
-      borderRadius={12}
-      padding={20}
-      backgroundColor="color.white"
-    >
-      {loading ? (
-        <Center height="100%">
-          <Loader
-            type="dotted"
-            loaderColor="color.gray.400"
-            textColor="color.gray.600"
-          >
-            Loading content...
-          </Loader>
-        </Center>
-      ) : (
-        <Vertical gap={12}>
-          <Text fontSize={18} fontWeight="bold">
-            {content.title}
-          </Text>
-          <Text color="color.gray.600">
-            {content.description}
-          </Text>
-        </Vertical>
-      )}
-    </View>
-  );
-};
+export const ColoredTextLoader = () => (
+  <Loader 
+    loaderColor="#3b82f6" 
+    textColor="#3b82f6"
+  >
+    Loading...
+  </Loader>
+);
 ```
 
-### **Button Loading States**
+### **Loading States**
+Common loading state patterns.
+
 ```tsx
 import React, { useState } from 'react';
 import { Loader } from '@app-studio/web';
-import { Button } from '@app-studio/web';
-import { Horizontal } from '@app-studio/web';
-
-export const ButtonLoaders = () => {
-  const [loading1, setLoading1] = useState(false);
-  const [loading2, setLoading2] = useState(false);
+import { Button, Vertical } from 'app-studio';
 
+export const LoadingStates = () => {
+  const [loading, setLoading] = useState(false);
+  
   return (
-    <Horizontal gap={16}>
-      <Button
-        onClick={() => {
-          setLoading1(true);
-          setTimeout(() => setLoading1(false), 2000);
-        }}
-        disabled={loading1}
-        icon={loading1 ? <Loader size={16} loaderColor="currentColor" /> : undefined}
-      >
-        {loading1 ? 'Submitting...' : 'Submit'}
-      </Button>
-
-      <Button
-        variant="outline"
+    <Vertical gap={20}>
+      <Button 
         onClick={() => {
-          setLoading2(true);
-          setTimeout(() => setLoading2(false), 2000);
+          setLoading(true);
+          setTimeout(() => setLoading(false), 3000);
         }}
-        disabled={loading2}
       >
-        {loading2 ? (
-          <Loader size={16} loaderColor="currentColor">
-            Processing
-          </Loader>
-        ) : (
-          'Process'
-        )}
+        Start Loading
       </Button>
-    </Horizontal>
+      
+      {loading && (
+        <Loader>Please wait...</Loader>
+      )}
+    </Vertical>
   );
 };
 ```
 
-### **Custom Loader Styling**
+### **Inline Loader**
+Small loader for inline use.
+
 ```tsx
 import React from 'react';
 import { Loader } from '@app-studio/web';
-import { View } from '@app-studio/web';
+import { Text, Horizontal } from 'app-studio';
 
-export const CustomLoader = () => (
-  <View
-    padding={24}
-    backgroundColor="color.gray.900"
-    borderRadius={12}
-  >
-    <Loader
-      type="quarter"
-      size={48}
-      loaderColor="color.white"
-      textColor="color.white"
-      textPosition="bottom"
-      views={{
-        container: {
-          gap: 16,
-        },
-        text: {
-          fontWeight: 'medium',
-          fontSize: 16,
-        },
-      }}
-    >
-      Loading...
-    </Loader>
-  </View>
+export const InlineLoader = () => (
+  <Horizontal gap={10} alignItems="center">
+    <Text>Saving</Text>
+    <Loader size={16} />
+  </Horizontal>
 );
 ```
 
-### **Best Practices**
-
-**When to Use:**
-- During API calls and data fetching
-- File uploads and downloads
-- Form submissions
-- Page transitions
-- Long-running operations
-
-**User Experience:**
-- Show loaders for operations taking longer than 200ms
-- Provide meaningful loading text when possible
-- Use appropriate sizes for the context
-- Consider skeleton screens for content loading
-- Ensure loaders are accessible to screen readers
-
-**Performance:**
-- Use CSS animations instead of JavaScript when possible
-- Avoid showing loaders for very quick operations
-- Consider lazy loading for better perceived performance
-- Use appropriate animation speeds (not too fast or slow)
-
-**Accessibility:**
-- Include descriptive text for screen readers
-- Use `aria-live` regions for dynamic loading states
-- Ensure sufficient color contrast
-- Provide alternative feedback for users who can't see animations
-
-### **Integration Examples**
-
-**With Forms:**
-```tsx
-import { FormikForm, FormikTextField } from '@app-studio/web';
+### **Full Page Loader**
+Centered loader for full page loading.
 
-const FormWithLoader = () => {
-  const [submitting, setSubmitting] = useState(false);
+```tsx
+import React from 'react';
+import { Loader } from '@app-studio/web';
+import { Center } from 'app-studio';
 
-  return (
-    <FormikForm>
-      <FormikTextField name="email" label="Email" />
-      <Button
-        type="submit"
-        disabled={submitting}
-        icon={submitting ? <Loader size={16} /> : undefined}
-      >
-        {submitting ? 'Submitting...' : 'Submit'}
-      </Button>
-    </FormikForm>
-  );
-};
+export const FullPageLoader = () => (
+  <Center width="100vw" height="100vh">
+    <Loader size="xl">Loading application...</Loader>
+  </Center>
+);
 ```
 
-**With Data Tables:**
+### **Card Loading**
+Loader inside a card component.
+
 ```tsx
-const DataTable = ({ data, loading }) => (
-  <View>
-    {loading ? (
-      <Center height={200}>
-        <Loader>Loading table data...</Loader>
-      </Center>
-    ) : (
-      <Table data={data} />
-    )}
-  </View>
+import React from 'react';
+import { Loader } from '@app-studio/web';
+import { Card } from '@app-studio/web';
+import { Center } from 'app-studio';
+
+export const CardLoader = () => (
+  <Card width={300} height={200}>
+    <Center width="100%" height="100%">
+      <Loader>Loading content...</Loader>
+    </Center>
+  </Card>
 );
 ```
 
-**With Image Loading:**
+### **Button Loading**
+Loader integrated with button.
+
 ```tsx
-const ImageWithLoader = ({ src, alt }) => {
-  const [loading, setLoading] = useState(true);
+import React, { useState } from 'react';
+import { Loader } from '@app-studio/web';
+import { Button, Horizontal } from 'app-studio';
 
+export const ButtonLoader = () => {
+  const [loading, setLoading] = useState(false);
+  
   return (
-    <View position="relative">
-      {loading && (
-        <Center
-          position="absolute"
-          top={0}
-          left={0}
-          right={0}
-          bottom={0}
-          backgroundColor="color.gray.100"
-        >
-          <Loader size="sm">Loading image...</Loader>
-        </Center>
-      )}
-      <img
-        src={src}
-        alt={alt}
-        onLoad={() => setLoading(false)}
-        style={{ opacity: loading ? 0 : 1 }}
-      />
-    </View>
+    <Button 
+      onClick={() => {
+        setLoading(true);
+        setTimeout(() => setLoading(false), 2000);
+      }}
+      isDisabled={loading}
+    >
+      <Horizontal gap={10} alignItems="center">
+        {loading && <Loader size={16} loaderColor="#ffffff" />}
+        {loading ? 'Submitting...' : 'Submit'}
+      </Horizontal>
+    </Button>
   );
 };
 ```
 
-### **Advanced Patterns**
+### **Different Types Showcase**
+Showcasing all loader types with customization.
 
-**Progress Loader:**
 ```tsx
-const ProgressLoader = ({ progress }) => (
-  <Vertical gap={8} alignItems="center">
-    <Loader size="lg" />
-    <Text fontSize={14} color="color.gray.600">
-      {progress}% complete
-    </Text>
+import React from 'react';
+import { Loader } from '@app-studio/web';
+import { Vertical, Horizontal, Text } from 'app-studio';
+
+export const LoaderShowcase = () => (
+  <Vertical gap={30}>
+    <Vertical gap={15}>
+      <Text fontWeight="bold">Spinner Variants</Text>
+      <Horizontal gap={20}>
+        <Loader type="spinner" size="sm" loaderColor="#3b82f6" />
+        <Loader type="spinner" size="md" loaderColor="#10b981" />
+        <Loader type="spinner" size="lg" loaderColor="#ef4444" />
+      </Horizontal>
+    </Vertical>
+    
+    <Vertical gap={15}>
+      <Text fontWeight="bold">Dotted Variants</Text>
+      <Horizontal gap={20}>
+        <Loader type="dotted" size="sm" loaderColor="#3b82f6" />
+        <Loader type="dotted" size="md" loaderColor="#10b981" />
+        <Loader type="dotted" size="lg" loaderColor="#ef4444" />
+      </Horizontal>
+    </Vertical>
+    
+    <Vertical gap={15}>
+      <Text fontWeight="bold">With Text</Text>
+      <Horizontal gap={30}>
+        <Loader type="spinner" loaderColor="#3b82f6" textColor="#3b82f6">
+          Loading...
+        </Loader>
+        <Loader 
+          type="dotted" 
+          loaderColor="#10b981" 
+          textColor="#10b981"
+          textPosition="right"
+        >
+          Processing
+        </Loader>
+      </Horizontal>
+    </Vertical>
+    
+    <Vertical gap={15}>
+      <Text fontWeight="bold">Different Speeds</Text>
+      <Horizontal gap={30}>
+        <Loader speed="slow">Slow</Loader>
+        <Loader speed="normal">Normal</Loader>
+        <Loader speed="fast">Fast</Loader>
+      </Horizontal>
+    </Vertical>
   </Vertical>
 );
 ```
 
-**Conditional Loader:**
-```tsx
-const ConditionalLoader = ({ condition, children }) => (
-  condition ? (
-    <Loader>Loading...</Loader>
-  ) : (
-    children
-  )
-);
-```