@app-studio/components 0.10.17

package/docs/components/Alert.mdx

@@ -0,0 +1,72 @@
+# Alert
+
+Displays important messages to users with various styles and states.
+
+### **Import**
+```tsx
+import { Alert } from '@app-studio/components';
+```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Alert } from '@app-studio/components';
+
+export const DefaultDemo = () => {
+  return (
+    <Alert
+      title="Heads up!"
+      description="You can add components to your app using the cli."
+    />
+  );
+};
+```
+
+### **icon**
+Custom icon element to display in the alert, overriding the default variant-based icon.
+
+- **Type:** `ReactNode`
+
+```tsx
+import React from 'react';
+import { EditIcon } from '@app-studio/components';
+import { Alert } from '@app-studio/components';
+
+export const IconDemo = () => {
+  return (
+    <Alert
+      title="Heads up!"
+      description="You can add components to your app using the cli."
+      icon={<EditIcon widthHeight={24} color="black" />}
+    />
+  );
+};
+```
+
+### **variant**
+Determines the visual style and semantic meaning of the alert.
+
+- **Type:** `string`
+- **Default:** `default`
+- **Possible Values:** `default, info, success, error, warning`
+
+```tsx
+import React from 'react';
+import { Horizontal } from 'app-studio';
+import { Alert } from '@app-studio/components';
+import { Variant } from '@app-studio/components';
+
+export const VariantDemo = () => (
+  <Horizontal gap={10}>
+    {['default', 'info', 'warning', 'success', 'error'].map((color, index) => (
+      <Alert
+        key={index}
+        variant={color as Variant}
+        title={'Heads Up!'}
+        description={'You can add components to your app using the cli.'}
+      />
+    ))}
+  </Horizontal>
+);
+```
+

package/docs/components/AspectRatio.mdx

@@ -0,0 +1,57 @@
+# AspectRatio
+
+This component ensures its content maintains a specified aspect ratio, adjusting its size responsively while preserving visual proportions.
+
+### **Import**
+```tsx
+import { AspectRatio } from '@app-studio/components';
+```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Image } from 'app-studio';
+import { AspectRatio } from '@app-studio/components';
+
+export const DefaultDemo = () => {
+  return (
+    <AspectRatio>
+      <Image
+        alt="image"
+        objectFit="cover"
+        width="100%"
+        height="100%"
+        src="https://t3.ftcdn.net/jpg/02/82/15/88/360_F_282158853_VtXRiSiN5eCjPddHobErJewxJ65lYZGt.jpg"
+      />
+    </AspectRatio>
+  );
+};
+```
+
+### **ratio**
+Set a default aspect ratio of 16:9 if no ratio is provided as a prop.
+
+- **Type:** `number`
+- **Default:** `16 / 9`
+- **Possible Values:** ``
+
+```tsx
+import React from 'react';
+import { Image } from 'app-studio';
+import { AspectRatio } from '@app-studio/components';
+
+export const RatioDemo = () => {
+  return (
+    <AspectRatio ratio={4 / 3} width={300}>
+      <Image
+        alt="image"
+        objectFit="cover"
+        width="100%"
+        height="100%"
+        src="https://t3.ftcdn.net/jpg/02/82/15/88/360_F_282158853_VtXRiSiN5eCjPddHobErJewxJ65lYZGt.jpg"
+      />
+    </AspectRatio>
+  );
+};
+```
+

package/docs/components/AttachmentGroup.md

@@ -0,0 +1,45 @@
+
+# AttachmentGroup
+
+The `AttachmentGroup` component displays a list of file attachments, typically used in chat interfaces or upload previews. It supports displaying thumbnails for images and videos, and generic icons for other file types. It also provides a mechanism to remove attachments.
+
+## Import
+
+```tsx
+import { AttachmentGroup } from 'src/components/AttachmentGroup/AttachmentGroup';
+```
+
+## Usage
+
+```tsx
+import React, { useState } from 'react';
+import { AttachmentGroup } from 'src/components/AttachmentGroup/AttachmentGroup';
+
+const MyComponent = () => {
+  const [files, setFiles] = useState<File[]>([]);
+
+  const handleRemove = (index: number) => {
+    setFiles((prev) => prev.filter((_, i) => i !== index));
+  };
+
+  return (
+    <AttachmentGroup 
+      files={files} 
+      onRemove={handleRemove} 
+      showPreviews={true} 
+    />
+  );
+};
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|Data | | | |
+| `files` | `File[]` | (required) | Array of File objects to display. |
+| `onRemove` | `(index: number) => void` | (required) | Callback function fired when the remove button is clicked. |
+| `showPreviews` | `boolean` | `false` | Whether to show hover previews for supported file types. |
+| `layout` | `'inline' \| 'grid'` | `'inline'` | Layout mode for the attachments. |
+| `maxHeight` | `string` | `'120px'` | Maximum height of the container container before scrolling. |
+| `sandboxId` | `string` | - | Optional ID for sandbox context (if applicable). |
+| `views` | `object` | `{}` | Custom styles for internal sub-components (`container`, `item`, `name`, etc.). |

package/docs/components/AudioInput.mdx

@@ -0,0 +1,43 @@
+# AudioInput
+
+Provides a user interface for recording, playing, and uploading audio content.
+
+### **Import**
+```tsx
+import { AudioInput } from '@app-studio/components';
+```
+
+### **Default**
+```tsx
+import React, { useState } from 'react';
+import { AudioInput } from '@app-studio/components';
+import { View, Text, Button } from 'app-studio';
+
+export const Default = () => {
+  const [audioFile, setAudioFile] = useState<File | null>(null);
+
+  const handleAudio = (file: File) => {
+    setAudioFile(file);
+  };
+
+  return (
+    <View flexDirection="column" gap={4} padding={4} alignItems="flex-start">
+      <Text variant="heading" size="lg">
+        Audio Input Example
+      </Text>
+      <AudioInput onAudio={handleAudio} />
+      {audioFile && (
+        <View flexDirection="column" gap={2}>
+          <Text>
+            Recorded Audio: <strong>{audioFile.name}</strong> (
+            {(audioFile.size / 1024).toFixed(2)} KB)
+          </Text>
+          <audio controls src={URL.createObjectURL(audioFile)} />
+          <Button onPress={() => setAudioFile(null)}>Clear Audio</Button>
+        </View>
+      )}
+    </View>
+  );
+};
+```
+

package/docs/components/Avatar.mdx

@@ -0,0 +1,60 @@
+# Avatar
+
+Displays a user's avatar, which can be an image or initials, with customizable size and styles.
+
+### **Import**
+```tsx
+import { Avatar } from '@app-studio/components';
+```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Avatar } from '@app-studio/components';
+
+export const DefaultDemo = () => (
+  <Avatar src="https://t3.ftcdn.net/jpg/06/17/13/26/360_F_617132669_YptvM7fIuczaUbYYpMe3VTLimwZwzlWf.jpg" />
+);
+```
+
+### **size**
+Optional size of the avatar, predefined in 'Size' type.
+
+- **Type:** `Size`
+- **Default:** `md`
+- **Possible Values:** `xs, sm, md, lg, xl`
+
+```tsx
+import React from 'react';
+import { Vertical } from 'app-studio';
+import { Avatar } from '@app-studio/components';
+import { Size } from '@app-studio/components';
+
+export const SizeDemo = () => {
+  return (
+    <Vertical gap={10}>
+      {['xs', 'sm', 'md', 'lg', 'xl'].map((size, index) => (
+        <Avatar
+          key={index}
+          src="https://t3.ftcdn.net/jpg/06/17/13/26/360_F_617132669_YptvM7fIuczaUbYYpMe3VTLimwZwzlWf.jpg"
+          size={size as Size}
+        />
+      ))}
+    </Vertical>
+  );
+};
+```
+
+### **fallback**
+URL or path for the fallback image if the source fails to load.
+
+- **Type:** `string`
+- **Default:** `IM`
+
+```tsx
+import React from 'react';
+import { Avatar } from '@app-studio/components';
+
+export const FallbackDemo = () => <Avatar src="" fallback="ML" />;
+```
+

package/docs/components/Background.mdx

@@ -0,0 +1,144 @@
+# Background
+
+A comprehensive collection of background effects, including animated particles, gradients, images, and videos.
+
+### **Import**
+```tsx
+import { Background } from '@app-studio/components';
+```
+
+### **Aurora**
+A smooth, flowing gradient animation resembling the northern lights.
+
+**Props:**
+- `showRadialGradient` (boolean): Adds a radial gradient overlay.
+
+```tsx
+<Background.Aurora height="300px" showRadialGradient>
+  <Center height="100%">
+    <Title color="white">Aurora Effect</Title>
+  </Center>
+</Background.Aurora>
+```
+
+### **Meteors**
+Falling meteor effects, perfect for dark themes.
+
+**Props:**
+- `number` (number): Number of meteors to render.
+
+```tsx
+<Background.Meteors number={20}>
+  <Center height="300px" backgroundColor="color-black">
+    <Title color="white">Meteor Shower</Title>
+  </Center>
+</Background.Meteors>
+```
+
+### **Particles**
+Interactive floating particles.
+
+**Props:**
+- `count` (number): Number of particles.
+- `speed` ('slow' | 'medium' | 'fast'): Movement speed.
+- `shapes` (Array): Shapes to use ('circle', 'square', 'triangle').
+- `colors` (string[]): Array of colors for particles.
+
+```tsx
+<Background.Particles 
+  count={50} 
+  speed="slow" 
+  shapes={['circle']}
+  colors={['#6366f1', '#a855f7']} 
+/>
+```
+
+### **Wall**
+A grid of squares that can animate.
+
+**Props:**
+- `rows` (number): Number of rows.
+- `cols` (number): Number of columns.
+- `squareSize` (number): Size of each square.
+
+```tsx
+<Background.Wall rows={10} cols={10} squareSize={50} />
+```
+
+### **Grid**
+A retro-style perspective grid.
+
+**Props:**
+- `gridSize` (number): Size of grid cells.
+- `animationSpeed` ('slow' | 'medium' | 'fast').
+- `lineColor` (string).
+- `pulseColor` (string).
+
+```tsx
+<Background.Grid gridSize={40} animationSpeed="medium" lineColor="rgba(255,255,255,0.1)" />
+```
+
+### **Ripples**
+Concentric ripple animations.
+
+**Props:**
+- `rippleCount` (number).
+- `maxSize` (number).
+- `frequency` (number).
+
+```tsx
+<Background.Ripples rippleCount={3} maxSize={300} />
+```
+
+### **Image**
+Background image with optional overlay and blend modes.
+
+**Props:**
+- `src` (string): Image URL.
+- `backgroundSize`, `backgroundPosition`, `backgroundRepeat`.
+- `overlay` (ReactNode): Content to overlay (like `<Background.Overlay />`).
+- `blendMode` (BlendMode): CSS blend mode.
+
+```tsx
+<Background.Image 
+  src="https://example.com/bg.jpg" 
+  height="400px"
+  overlay={<Background.Overlay contentPosition="center" backgroundColor="rgba(0,0,0,0.6)" />}
+>
+  <Title color="white">Hero Section</Title>
+</Background.Image>
+```
+
+### **Video**
+Background video with auto-play support.
+
+**Props:**
+- `src` (string): Video URL.
+- `autoPlay`, `loop`, `muted`, `playsInline` (boolean).
+- `overlay` (ReactNode).
+- `blendMode` (BlendMode).
+
+```tsx
+<Background.Video 
+  src="/assets/background.mp4" 
+  height="100vh"
+  overlay={<Background.Overlay backgroundColor="rgba(0,0,0,0.4)" />}
+>
+  <Title>Cinematic Experience</Title>
+</Background.Video>
+```
+
+### **Gradient**
+Advanced gradient backgrounds.
+
+**Props:**
+- Inherits `GradientProps`.
+
+```tsx
+<Background.Gradient 
+  from="color-blue-600" 
+  to="color-purple-600" 
+  direction="45deg" 
+  height="300px" 
+/>
+```

package/docs/components/Badge.mdx

@@ -0,0 +1,190 @@
+# Badge
+
+Renders a badge with various styles and states according to the design guidelines.
+
+### **Import**
+```tsx
+import { Badge } from '@app-studio/components';
+```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Badge } from '@app-studio/components';
+
+export const DefaultDemo = () => <Badge content="default" />;
+```
+
+### **content**
+The content to be displayed within the badge.
+
+- **Type:** `string | number`
+
+```tsx
+import React from 'react';
+import { Badge } from '@app-studio/components';
+
+export const ContentDemo = () => <Badge content="content" />;
+```
+
+### **variant**
+Determines the styling variants a UI component can have, which could include filled, outlined, or ghost styles among others.
+
+- **Type:** `Variant`
+- **Default:** `filled`
+- **Possible Values:** `filled, outline, link, ghost`
+
+```tsx
+import React from 'react';
+import { Vertical } from 'app-studio';
+
+import { Badge } from '@app-studio/components';
+import { Variant } from '@app-studio/components';
+import { View } from 'app-studio';
+export const VariantDemo = () => (
+  <Vertical gap={15}>
+    {['filled', 'outline', 'link', 'ghost'].map((variant, index) => (
+      <View position={'relative'} key={index}>
+        <Badge content={variant} variant={variant as Variant} />
+      </View>
+    ))}
+  </Vertical>
+);
+```
+
+### **position**
+Lists possible positions for UI elements that can be placed in one of the corners of a container, like notification badges.
+
+- **Type:** `Position`
+- **Possible Values:** `top-right, top-left, bottom-right, bottom-left`
+
+```tsx
+import React from 'react';
+import { Badge } from '@app-studio/components';
+import { View } from 'app-studio';
+import { Horizontal } from 'app-studio';
+import { Position } from '@app-studio/components';
+
+export const PositionDemo = () => (
+  <Horizontal gap={10}>
+    {['top-right', 'top-left', 'bottom-right', 'bottom-left'].map(
+      (position, index) => (
+        <View
+          key={index}
+          position="relative"
+          height="100px"
+          width="200px"
+          backgroundColor="color-warmGray-100"
+        >
+          <Badge position={position as Position} content={position} />
+        </View>
+      )
+    )}
+  </Horizontal>
+);
+```
+
+### **size**
+Specifies available sizes for UI elements, catering to a range of scalability from extra small to extra large.
+
+- **Type:** `Size`
+- **Default:** `md`
+- **Possible Values:** `xs, sm, md, lg, xl`
+
+```tsx
+import React from 'react';
+import { Vertical } from 'app-studio';
+
+import { Badge } from '@app-studio/components';
+import { Size } from '@app-studio/components';
+import { View } from 'app-studio';
+export const SizeDemo = () => (
+  <Vertical gap={10}>
+    {['xs', 'sm', 'md', 'lg', 'xl'].map((size, index) => (
+      <View position="relative" key={index}>
+        <Badge content={size} size={size as Size} />
+      </View>
+    ))}
+  </Vertical>
+);
+```
+
+### **children**
+Renders children content inside the badge, allowing for custom compositions.
+
+```tsx
+import React from 'react';
+import { Badge } from '@app-studio/components';
+import { Text } from 'app-studio';
+
+export const ChildrenDemo = () => (
+  <Badge>
+    <Text color="color-white">Custom Children</Text>
+  </Badge>
+);
+```
+
+### **icon**
+Displays an icon within the badge layout.
+
+```tsx
+import React from 'react';
+import { Badge } from '@app-studio/components';
+import { View } from 'app-studio';
+
+const Icon = () => (
+  <View width="12px" height="12px" backgroundColor="currentColor" borderRadius="50%" />
+);
+
+export const IconDemo = () => (
+    <Horizontal gap={10}>
+        <Badge icon={<Icon />} content="With Icon" />
+    </Horizontal>
+);
+```
+
+### **pastil**
+Shows a status dot (pastil) inside the badge. Can be a boolean or a specific status color string.
+
+- **Type:** `boolean | string`
+- **Possible Values:** `true, default, info, success, warning, error` or any color string
+
+```tsx
+import React from 'react';
+import { Badge } from '@app-studio/components';
+import { Horizontal } from 'app-studio';
+
+export const PastilDemo = () => (
+  <Horizontal gap={10}>
+    <Badge pastil={true} content="Active" />
+    <Badge pastil="success" content="Success" />
+    <Badge pastil="warning" content="Warning" />
+    <Badge pastil="error" content="Error" />
+  </Horizontal>
+);
+```
+
+### **shape**
+Defines possible values for the shape of a UI component such as buttons or badges.
+
+- **Type:** `Shape`
+- **Default:** `pill`
+- **Possible Values:** `square, rounded, pill`
+
+```tsx
+import React from 'react';
+import { Horizontal } from 'app-studio';
+import { Badge } from '@app-studio/components';
+import { Shape } from '@app-studio/components';
+import { View } from 'app-studio';
+export const ShapeDemo = () => (
+  <Horizontal gap={15}>
+    {['square', 'rounded', 'pill'].map((shape, index) => (
+      <View position="relative" key={index}>
+        <Badge content={shape} shape={shape as Shape} />
+      </View>
+    ))}
+  </Horizontal>
+);
+```
+