@app-studio/components 0.10.17

package/docs/getting-started/component-usage.md

@@ -0,0 +1,211 @@
+# Component Usage Guide
+
+This guide provides an overview of how to use components from the App Studio Components Component Library in your application.
+
+## Basic Component Usage
+
+Most components can be imported directly from the library and used with their default props:
+
+```jsx
+import React from 'react';
+import { Button, Text } from '@app-studio/components';
+
+function MyComponent() {
+  return (
+    <div>
+      <Text>Click the button below</Text>
+      <Button onClick={() => alert('Button clicked!')}>Click Me</Button>
+    </div>
+  );
+}
+```
+
+## Component Props
+
+Each component accepts a set of props that control its appearance and behavior. Common props include:
+
+- `variant`: Controls the visual style (e.g., 'default', 'primary', 'secondary')
+- `size`: Controls the size (e.g., 'xs', 'sm', 'md', 'lg', 'xl')
+- `shape`: Controls the shape (e.g., 'sharp', 'rounded', 'pillShaped')
+- `isDisabled`: Controls whether the component is disabled
+- `views`: Allows for custom styling of specific parts of the component
+
+Example with props:
+
+```jsx
+import React from 'react';
+import { Button } from '@app-studio/components';
+
+function MyComponent() {
+  return (
+    <Button 
+      variant="primary"
+      size="lg"
+      shape="pillShaped"
+      isDisabled={false}
+      views={{ container: { backgroundColor: 'blue' } }}
+      onClick={() => alert('Button clicked!')}
+    >
+      Click Me
+    </Button>
+  );
+}
+```
+
+## Layout Components
+
+Layout components help structure your UI. The main layout components are:
+
+- `View`: Base container component
+- `Horizontal`: Horizontal flex container
+- `Vertical`: Vertical flex container
+- `Center`: Centered flex container
+
+Example:
+
+```jsx
+import React from 'react';
+import { View, Horizontal, Vertical, Center, Text, Button } from '@app-studio/components';
+
+function MyLayout() {
+  return (
+    <View padding={20}>
+      <Vertical gap={16}>
+        <Text>Header</Text>
+        <Horizontal gap={8} justifyContent="space-between">
+          <Button>Left Button</Button>
+          <Button>Right Button</Button>
+        </Horizontal>
+        <Center>
+          <Text>Centered Content</Text>
+        </Center>
+      </Vertical>
+    </View>
+  );
+}
+```
+
+## Form Components
+
+Form components can be used standalone or integrated with Formik:
+
+### Standalone Usage
+
+```jsx
+import React, { useState } from 'react';
+import { TextField, Button } from '@app-studio/components';
+
+function MyForm() {
+  const [value, setValue] = useState('');
+  
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); alert(`Submitted: ${value}`); }}>
+      <TextField 
+        label="Name"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+}
+```
+
+### Formik Integration
+
+```jsx
+import React from 'react';
+import { Formik, Form } from 'formik';
+import { FormikTextField, Button } from '@app-studio/components';
+
+function MyFormikForm() {
+  return (
+    <Formik
+      initialValues={{ name: '' }}
+      onSubmit={(values) => alert(`Submitted: ${values.name}`)}
+    >
+      <Form>
+        <FormikTextField name="name" label="Name" />
+        <Button type="submit">Submit</Button>
+      </Form>
+    </Formik>
+  );
+}
+```
+
+## Compound Components
+
+Some components use the compound component pattern, where a main component has sub-components for different parts:
+
+```jsx
+import React from 'react';
+import { Card, Text, Button, Horizontal } from '@app-studio/components';
+
+function MyCard() {
+  return (
+    <Card>
+      <Card.Header>
+        <Text fontWeight="bold" fontSize={18}>Card Title</Text>
+      </Card.Header>
+      <Card.Content>
+        <Text>This is the card content.</Text>
+      </Card.Content>
+      <Card.Footer>
+        <Horizontal justifyContent="flex-end" gap={10}>
+          <Button variant="outline">Cancel</Button>
+          <Button>Submit</Button>
+        </Horizontal>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+## Theming
+
+Components automatically use the theme from the ThemeProvider context. You can override the theme mode for specific components:
+
+```jsx
+import React from 'react';
+import { ThemeProvider, Button } from '@app-studio/components';
+
+function MyThemedApp() {
+  return (
+    <ThemeProvider theme={{ mode: 'light' }}>
+      <Button>Light Theme Button</Button>
+      <Button themeMode="dark">Dark Theme Button</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+## Custom Styling
+
+You can customize component styling using the `views` prop:
+
+```jsx
+import React from 'react';
+import { Button } from '@app-studio/components';
+
+function MyCustomButton() {
+  return (
+    <Button
+      views={{
+        container: {
+          backgroundColor: '#6200ee',
+          borderRadius: 8,
+          boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)',
+        },
+      }}
+    >
+      Custom Styled Button
+    </Button>
+  );
+}
+```
+
+## Next Steps
+
+- [Theming Guide](../design-system/theming.md)
+- [Form Components Guide](../component-usage/form-components.md)
+- [Layout Components Guide](../component-usage/layout-components.md)

package/docs/getting-started/introduction.md

@@ -0,0 +1,136 @@
+# Introduction to App Studio Components
+
+`@app-studio/components` is a comprehensive, accessible, and customizable
+**cross-platform** component library built with TypeScript and
+[`app-studio`](https://app-studio.dev). It ships a **web** build (React + DOM)
+and a **React Native** build that share the same public API.
+
+## Features
+
+- **60+ UI Components**: From basic elements to complex interactive components
+- **One API on web and React Native**: Metro resolves `.native.tsx` siblings
+  automatically; consumers import the same module on both platforms
+- **Fully Typed**: TypeScript everywhere; package exports use
+  `react-native`/`browser` conditions so `tsc` picks the right typings
+- **Accessible**: Follows WCAG guidelines on web
+- **Customizable**: CSS-in-props via `app-studio`, theme tokens
+  (`theme-primary`, `color-gray-500`, …) work on both platforms
+- **Responsive**: Works across all device sizes
+- **Cross-platform animations** via `Animation.*` + `react-native-reanimated`
+- **Form Integration**: Seamless integration with Formik
+- **Modern Design**: Clean, consistent design following best practices
+
+## Installation
+
+### Web
+
+```bash
+npm install @app-studio/components app-studio
+npm install react react-dom react-router-dom formik zustand lucide-react
+```
+
+### React Native
+
+```bash
+npm install @app-studio/components app-studio react react-native
+# Optional but recommended (degrade gracefully if absent)
+npm install lucide-react-native react-native-svg \
+            react-native-linear-gradient react-native-reanimated
+cd ios && pod install
+```
+
+See the dedicated **[React Native guide](./react-native.md)** for the full
+compatibility matrix, Reanimated wiring, and Metro/typecheck configuration.
+
+## Quick Start
+
+```jsx
+import React from 'react';
+import { Button, Text } from '@app-studio/components';
+
+function App() {
+  return (
+    <div>
+      <Text>Hello, world!</Text>
+      <Button onClick={() => alert('Clicked!')}>Click me</Button>
+    </div>
+  );
+}
+```
+
+## Component Categories
+
+The library includes components in the following categories:
+
+### Layout Components
+- View
+- Center
+- Horizontal
+- Vertical
+- AspectRatio
+- Separator
+- Resizable
+
+### Form Components
+- Checkbox
+- ChatInput
+- Radio
+- Select
+- Switch
+- TextArea
+- TextField
+- OTPInput
+
+### Navigation Components
+- Accordion
+- Menubar
+- NavigationMenu
+- Pagination
+- Sidebar
+- Tabs
+
+### Feedback Components
+- Alert
+- Modal
+- Toast
+- Tooltip
+
+### Data Display Components
+- Avatar
+- Badge
+- Card
+- Table
+- Chart
+- Flow
+- Tree
+
+### Utility Components
+- Button
+- Gradient
+- Loader
+- Text
+
+### Interactive Components
+- Carousel
+- ContextMenu
+- DropdownMenu
+- HoverCard
+- Slider
+- Toggle
+- ToggleGroup
+
+## Design System
+
+All components follow a consistent design system with:
+
+- **Typography**: Inter/Geist font, specific sizes/weights
+- **Spacing**: 4px grid system
+- **Colors**: Neutral palette with semantic colors
+- **Rounded corners**: Consistent border radius
+- **Transitions**: Subtle animations
+
+## Next Steps
+
+- [Component Usage Guide](./component-usage.md)
+- [Theming Guide](../design-system/theming.md)
+- [Component Development Guide](../component-development/guide.md)

package/docs/getting-started/react-native.md

@@ -0,0 +1,243 @@
+# React Native Guide
+
+`@app-studio/components` ships a **dual build**: the same imports work on web
+(React + DOM) and on React Native. This page covers the RN-specific bits —
+peer deps, how the build resolves files, what runs at full fidelity, and what
+degrades.
+
+---
+
+## TL;DR
+
+```bash
+npm install @app-studio/components app-studio \
+  react react-native lucide-react-native \
+  react-native-svg react-native-linear-gradient react-native-reanimated
+cd ios && pod install
+```
+
+```tsx
+import { ThemeProvider, View, Animation } from 'app-studio';
+import { Button, Text, TextField, Loader } from '@app-studio/components';
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <View padding={16} gap={12}>
+        <Text>Hello from React Native</Text>
+        <TextField label="Name" />
+        <Button animate={Animation.fadeIn({ duration: '0.5s' })}>
+          Press me
+        </Button>
+        <Loader type="dotted" size="md" />
+      </View>
+    </ThemeProvider>
+  );
+}
+```
+
+There is a full smoke-test app at `../app-studio-rn-demo/App.tsx` that
+exercises Button, TextField, Switch, Loader, Modal, Title, Alert, Tabs,
+Tooltip, Gradient, ProgressBar, Pagination and three Animation presets.
+
+---
+
+## How the dual build works
+
+### 1. Package exports
+
+`package.json` exposes the `react-native` condition first:
+
+```json
+{
+  "exports": {
+    ".": {
+      "react-native": {
+        "types":   "./dist/native/components/index.d.ts",
+        "import":  "./dist/native/components/index.js",
+        "require": "./dist/native/components/index.cjs",
+        "default": "./dist/native/components/index.js"
+      },
+      "browser": { /* … web build … */ }
+    }
+  }
+}
+```
+
+At **runtime** Metro picks the `react-native` branch.  
+At **typecheck** time, set `moduleResolution: "bundler"` and
+`customConditions: ["react-native"]` in your `tsconfig.json` so TypeScript
+follows the same branch (see `app-studio-rn-demo/tsconfig.json` for a
+working example).
+
+### 2. Per-component `.native.tsx` siblings
+
+Inside each component folder you'll find:
+
+```
+Button/Button/
+├── Button.view.tsx          ← web (DOM, CSS, hover, gradients)
+└── Button.view.native.tsx   ← React Native (Pressable, no hover)
+```
+
+The parent `Button.tsx` does `import ButtonView from './Button/Button.view'`.
+- **Metro** has `resolver.sourceExts` ordered as `['native.tsx', 'tsx', …]`,
+  so it picks the `.native.tsx`.
+- **TypeScript** uses our `moduleSuffixes: [".native", ""]` option to do the
+  same when typechecking against the source.
+
+### 3. Shared files
+
+`Button.props.ts`, `Button.state.ts`, `Button.style.ts`, `Button.type.d.ts`
+are platform-neutral and shared by both builds.
+
+---
+
+## Required peer deps
+
+| Peer                          | Required for                                   | Optional? |
+| ----------------------------- | ---------------------------------------------- | --------- |
+| `react`                       | every component                                | no        |
+| `react-native`                | every component (RN side)                      | no        |
+| `app-studio`                  | every component                                | no        |
+| `lucide-react-native`         | every icon (Icon, Pagination chevrons, …)      | yes¹      |
+| `react-native-svg`            | Loader (default/dotted/quarter), ProgressBar (circle), Accordion chevron²    | yes       |
+| `react-native-linear-gradient`| `<Gradient/>` actual gradients                 | yes       |
+| `react-native-reanimated`     | `animate={Animation.…()}` on any component     | yes       |
+| `formik`                      | `<Formik/>` integration                        | yes       |
+| `zustand`                     | Modal/Toast/Drawer stores                      | no        |
+
+¹ All icon-name exports (`UserIcon`, `SearchIcon`, etc.) will render an empty
+wrapper if `lucide-react-native` is missing. Plain `<Icon name="user"/>` also
+degrades gracefully.
+
+² Without `react-native-svg`, the Loader falls back to `<ActivityIndicator/>`
+and ProgressBar `shape="circle"` falls back to the linear bar.
+
+---
+
+## Compatibility matrix
+
+| Component             | Web | RN  | Notes                                                                                  |
+| --------------------- | --- | --- | -------------------------------------------------------------------------------------- |
+| Button                | ✅  | ✅  | Animations `borderMoving`/`animatedStroke`/`borderReveal` fall back to standard on RN  |
+| Text / Title          | ✅  | ✅  | Title `<br>` mapped to `\n`; typewriter/slide effects dropped on RN                    |
+| View / Horizontal / Vertical / Center | ✅ | ✅ | Direct primitives from `app-studio`                                       |
+| Image                 | ✅  | ✅  |                                                                                        |
+| Icon                  | ✅  | ✅  | Web uses `lucide-react` lazy imports; RN uses `lucide-react-native` static map         |
+| Link                  | ✅  | ✅  | Web: `react-router-dom`. RN: `Linking.openURL` (external) + `onPress` (internal)       |
+| Modal                 | ✅  | ✅  | RN uses `<Modal/>` for portal-like overlay                                             |
+| Drawer                | ✅  | ✅  | RN uses `<Modal/>` + absolute side panel                                               |
+| TextField / TextArea  | ✅  | ✅  | RN uses app-studio `<Input/>` (mapped to `TextInput`)                                  |
+| Password              | ✅  | ✅  | RN: `secureTextEntry` automatically                                                    |
+| Switch                | ✅  | ✅  | RN uses built-in `<Switch/>`                                                           |
+| Checkbox / Radio      | ✅  | ✅  | RN: pressable View + Tick/circle icon (no HTML inputs)                                 |
+| Select                | ✅  | ✅  | RN renders options in a `<Modal/>` + `<ScrollView/>`                                   |
+| Tabs                  | ✅  | ✅  |                                                                                        |
+| Tooltip / HoverCard   | ✅  | ✅  | RN: tap-toggled, content in a `<Modal/>` (no hover anchoring)                          |
+| DropdownMenu / ContextMenu / Menubar / NavigationMenu | ✅  | ✅  | RN: open via tap (long-press for context), centered Modal           |
+| Accordion             | ✅  | ✅  |                                                                                        |
+| Sidebar               | ✅  | ✅  |                                                                                        |
+| Carousel              | ✅  | ✅  | RN drops translateX sliding; renders active slide only                                 |
+| Pagination            | ✅  | ✅  |                                                                                        |
+| OTPInput              | ✅  | ✅  | RN: hidden `TextInput` over visible slot cells                                         |
+| Slider                | ✅  | ✅  | RN uses the responder system (no `_hover` tooltip)                                     |
+| Toast                 | ✅  | ✅  | `position:fixed` → absolute; shadow via elevation                                      |
+| ProgressBar           | ✅  | ✅  | Circle variant needs `react-native-svg`                                                |
+| Loader                | ✅  | ✅  | 3 variants restored via `react-native-svg` + Reanimated                                |
+| Gradient              | ✅  | ✅  | Conic falls back to flat color; linear uses `react-native-linear-gradient`             |
+| Background            | ✅  | ⚠️  | Decorative variants (Aurora, Meteors, Particles, Grid, Ripples) render as solid color  |
+| Toggle / ToggleGroup  | ✅  | ✅  |                                                                                        |
+| Alert / Avatar / Badge / Card / Separator / AspectRatio / Resizable / StatusIndicator | ✅ | ✅ | Use only portable primitives                              |
+| Chart                 | ✅  | ❌  | Recharts is web-only                                                                   |
+| EmojiPicker / ColorPicker / IconPicker | ✅ | ❌  | Web-only                                                              |
+| Command               | ✅  | ❌  | `cmdk` is web-only                                                                     |
+| DragAndDrop / DropZone / Uploader / File / AudioInput / MediaPreview | ✅ | ❌ | DOM `File` / `MediaStream`         |
+| CookieConsent         | ✅  | ❌  | Cookies do not apply on RN                                                             |
+| ChatWidget / ChatInput / EditComponent | ✅ | ❌  | Author-time tools, web-only                                           |
+
+✅ available, ⚠️ degraded, ❌ not exported on RN (importing them throws).
+
+---
+
+## Animations on React Native
+
+`app-studio` exposes the same `Animation.*` factories on both platforms:
+
+```tsx
+import { Animation, View } from 'app-studio';
+
+<View animate={Animation.fadeIn({ duration: '0.6s' })}>…</View>
+
+<View animate={Animation.pulse({
+  duration: '1.2s',
+  iterationCount: 'infinite',
+  direction: 'alternate',
+})} />
+
+<View animate={[
+  Animation.slideInUp({ duration: '0.5s' }),
+]} />
+```
+
+On RN this is interpreted by the **`useAnimation` hook** (in
+`app-studio/src/native/useAnimation.ts`) which:
+
+- Parses `duration` (`"1s"`, `"500ms"`, `"0.3s"`) into ms
+- Maps CSS `timingFunction` (`linear`, `ease`, `ease-in`, `ease-out`,
+  `ease-in-out`, `cubic-bezier(...)`) to `Easing.bezier(...)`
+- Translates CSS transforms (`translateX(-100%)`, `scale(0.5)`,
+  `rotate(180deg)`, `skewX`, …) into RN transform arrays. Percentage
+  translates are resolved against `Dimensions.get('window')`.
+- Unrolls multi-stop keyframes (`'20%'`, `'40%'`, …) into a
+  `withSequence(withTiming, withTiming, …)` chain.
+- Honours `iterationCount` (`'infinite'` → `-1`) and `direction: 'alternate'`
+  via `withRepeat(anim, count, reverse)`.
+- Honours `delay` via `withDelay`.
+
+Without `react-native-reanimated` installed, `useAnimation` is a no-op and
+the element renders statically (no crash).
+
+### Limitations
+
+- One animation per element. To compose multiple, nest Views.
+- `translateX(-100%)` resolves against window width, not the element's own
+  width.
+- No `timeline: view()` or `timeline: scroll()` (CSS scroll-driven
+  animations). For scroll-driven RN animations, combine with Reanimated's
+  `useAnimatedScrollHandler` manually.
+
+---
+
+## Setting up a fresh RN app
+
+```bash
+npx @react-native-community/cli@latest init MyApp --skip-install
+cd MyApp
+npm install
+npm install ../app-studio ../app-studio-components
+npm install react-native-svg react-native-linear-gradient \
+            react-native-reanimated lucide-react-native
+cd ios && pod install && cd ..
+
+# Reanimated needs the babel plugin
+# babel.config.js
+# plugins: ['react-native-reanimated/plugin']
+
+npm run ios   # or npm run android
+```
+
+Then copy `app-studio-rn-demo/App.tsx` to `MyApp/App.tsx` as a starter.
+
+---
+
+## Troubleshooting
+
+| Symptom                                                  | Fix                                                                                                       |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `Cannot find module '@app-studio/components'`            | Make sure `moduleResolution: "bundler"` and `customConditions: ["react-native"]` in your tsconfig.        |
+| Icons render as empty wrappers                           | `npm install lucide-react-native`                                                                         |
+| `<Loader/>` shows `<ActivityIndicator/>` instead of SVG  | `npm install react-native-svg` (+ `cd ios && pod install`)                                                |
+| `<Gradient/>` renders as a flat color                    | `npm install react-native-linear-gradient` (+ pod install)                                                |
+| `animate={…}` doesn't move                               | `npm install react-native-reanimated` and add `'react-native-reanimated/plugin'` to `babel.config.js`     |
+| Build error about `HTMLDivElement` / `document`          | These are typed in shared `.tsx` files but never executed on RN — make sure your tsconfig has `lib: ["dom", "esnext"]` (RN never runs that code, TS just needs the symbols). |

package/docs/tutorials/README.md

@@ -0,0 +1,51 @@
+# Tutorials
+
+This section provides step-by-step tutorials for common tasks using the App Studio Components library.
+
+## Basic Tutorials
+
+- [Creating a Simple Form](./basic/creating-a-simple-form.md)
+- [Building a Dashboard Layout](./basic/building-a-dashboard-layout.md)
+- [Creating a Navigation Menu](./basic/creating-a-navigation-menu.md)
+
+## Intermediate Tutorials
+
+- [Form Validation with Formik](./intermediate/form-validation-with-formik.md)
+- [Creating a Data Table](./intermediate/creating-a-data-table.md)
+- [Building a Modal Dialog System](./intermediate/building-a-modal-dialog-system.md)
+- [Creating a Toast Notification System](./intermediate/creating-a-toast-notification-system.md)
+
+## Advanced Tutorials
+
+- [Building a Complex Form Wizard](./advanced/building-a-complex-form-wizard.md)
+- [Creating a Custom Theme](./advanced/creating-a-custom-theme-md)
+- [Building a Responsive Dashboard](./advanced/building-a-responsive-dashboard.md)
+- [Creating Custom Components](./advanced/creating-custom-components.md)
+
+## Component Integration Tutorials
+
+- [Integrating with React Router](./integration/integrating-with-react-router.md)
+- [Using with State Management Libraries](./integration/using-with-state-management-libraries.md)
+- [Integrating with Backend APIs](./integration/integrating-with-backend-apis.md)
+
+## Tutorial Structure
+
+Each tutorial follows a consistent structure:
+
+1. **Introduction** - Overview of what will be built
+2. **Prerequisites** - Required knowledge and setup
+3. **Step-by-Step Instructions** - Detailed steps with code examples
+4. **Complete Example** - The full code for the tutorial
+5. **Next Steps** - Suggestions for extending or modifying the example
+
+## Contributing Tutorials
+
+We welcome contributions to our tutorials. If you have an idea for a tutorial or want to improve an existing one, please follow these guidelines:
+
+1. Use clear, concise language
+2. Include complete code examples
+3. Explain the reasoning behind design decisions
+4. Include screenshots or diagrams where helpful
+5. Follow the established tutorial structure
+
+For more information on contributing, see the [Contributing Guide](../contributing/documentation.md).