@app-studio/web 0.9.17 → 0.9.19

package/docs/design-system/theming.md

@@ -0,0 +1,299 @@
+# Theming Guide
+
+This guide explains how to use and customize the theming system in the App Studio Web Component Library.
+
+## Theme System Overview
+
+The App Studio Web Component Library uses a theme system that provides consistent styling across all components. The theme includes:
+
+- Color palette
+- Typography
+- Spacing
+- Shapes
+- Shadows
+- Transitions
+
+## Theme Provider
+
+The `ThemeProvider` component is used to provide theme context to all components:
+
+```jsx
+import React from 'react';
+import { ThemeProvider } from 'app-studio';
+import { Button, Text } from '@app-studio/web';
+
+function App() {
+  return (
+    <ThemeProvider theme={{ mode: 'light' }}>
+      <Text>Themed content</Text>
+      <Button>Themed button</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+## Theme Modes
+
+The library supports light and dark theme modes:
+
+```jsx
+import React from 'react';
+import { ThemeProvider } from 'app-studio';
+import { Button } from '@app-studio/web';
+
+function App() {
+  return (
+    <ThemeProvider theme={{ mode: 'dark' }}>
+      <Button>Dark theme button</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+You can also override the theme mode for specific components:
+
+```jsx
+import React from 'react';
+import { ThemeProvider } from 'app-studio';
+import { Button } from '@app-studio/web';
+
+function App() {
+  return (
+    <ThemeProvider theme={{ mode: 'light' }}>
+      <Button>Light theme button</Button>
+      <Button themeMode="dark">Dark theme button</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+## Using Theme Values
+
+Within components, you can access theme values using the `useTheme` hook:
+
+```jsx
+import React from 'react';
+import { View, useTheme } from 'app-studio';
+
+function ThemedComponent() {
+  const { getColor, themeMode } = useTheme();
+  
+  const primaryColor = getColor('theme.primary', { themeMode });
+  const textColor = getColor('theme.text', { themeMode });
+  
+  return (
+    <View backgroundColor={primaryColor} color={textColor}>
+      Themed content
+    </View>
+  );
+}
+```
+
+## Theme Color Reference
+
+The theme includes the following color categories:
+
+### Semantic Colors
+
+- `theme.primary`: Primary brand color
+- `theme.secondary`: Secondary brand color
+- `theme.success`: Success state color
+- `theme.warning`: Warning state color
+- `theme.error`: Error state color
+- `theme.info`: Information state color
+- `theme.disabled`: Disabled state color
+
+### Neutral Colors
+
+- `color.white`: White
+- `color.black`: Black
+- `color.gray.50` to `color.gray.900`: Gray scale
+
+### Color Scales
+
+Each color has a scale from 50 (lightest) to 900 (darkest):
+
+- `color.blue.50` to `color.blue.900`
+- `color.green.50` to `color.green.900`
+- `color.red.50` to `color.red.900`
+- `color.yellow.50` to `color.yellow.900`
+- `color.purple.50` to `color.purple.900`
+
+## Typography
+
+The theme includes typography settings:
+
+- Font family: Inter/Geist
+- Font sizes: From 12px to 48px
+- Font weights: From 400 (regular) to 700 (bold)
+- Line heights: From 1.2 to 1.8
+
+Example usage:
+
+```jsx
+import React from 'react';
+import { Text } from '@app-studio/web';
+
+function TypographyExample() {
+  return (
+    <>
+      <Text fontSize={12} fontWeight="normal">Small text</Text>
+      <Text fontSize={16} fontWeight="normal">Normal text</Text>
+      <Text fontSize={24} fontWeight="bold">Large bold text</Text>
+    </>
+  );
+}
+```
+
+## Spacing
+
+The theme uses a 4px grid system for spacing:
+
+- 4px (extra small)
+- 8px (small)
+- 16px (medium)
+- 24px (large)
+- 32px (extra large)
+
+Example usage:
+
+```jsx
+import React from 'react';
+import { View, Horizontal } from 'app-studio';
+
+function SpacingExample() {
+  return (
+    <View padding={16}>
+      <Horizontal gap={8}>
+        <View width={50} height={50} backgroundColor="theme.primary" />
+        <View width={50} height={50} backgroundColor="theme.secondary" />
+      </Horizontal>
+    </View>
+  );
+}
+```
+
+## Shapes
+
+The theme includes shape definitions:
+
+- `sharp`: No border radius (0px)
+- `rounded`: Small border radius (4px)
+- `pillShaped`: Pill shape (9999px)
+
+Example usage:
+
+```jsx
+import React from 'react';
+import { Button } from '@app-studio/web';
+
+function ShapeExample() {
+  return (
+    <>
+      <Button shape="sharp">Sharp Button</Button>
+      <Button shape="rounded">Rounded Button</Button>
+      <Button shape="pillShaped">Pill Button</Button>
+    </>
+  );
+}
+```
+
+## Shadows
+
+The theme includes shadow definitions:
+
+- `shadow.sm`: Small shadow
+- `shadow.md`: Medium shadow
+- `shadow.lg`: Large shadow
+- `shadow.xl`: Extra large shadow
+
+Example usage:
+
+```jsx
+import React from 'react';
+import { Card } from '@app-studio/web';
+
+function ShadowExample() {
+  return (
+    <>
+      <Card shadow="shadow.sm">Small Shadow Card</Card>
+      <Card shadow="shadow.md">Medium Shadow Card</Card>
+      <Card shadow="shadow.lg">Large Shadow Card</Card>
+    </>
+  );
+}
+```
+
+## Custom Theming
+
+You can customize the theme by providing a custom theme object to the `ThemeProvider`:
+
+```jsx
+import React from 'react';
+import { ThemeProvider } from 'app-studio';
+
+const customTheme = {
+  mode: 'light',
+  colors: {
+    primary: '#6200ee',
+    secondary: '#03dac6',
+    success: '#00c853',
+    warning: '#ffab00',
+    error: '#b00020',
+    info: '#2196f3',
+  },
+  typography: {
+    fontFamily: 'Roboto, sans-serif',
+    fontSize: {
+      xs: 12,
+      sm: 14,
+      md: 16,
+      lg: 20,
+      xl: 24,
+    },
+  },
+  // Add other theme customizations
+};
+
+function App() {
+  return (
+    <ThemeProvider theme={customTheme}>
+      {/* Your app content */}
+    </ThemeProvider>
+  );
+}
+```
+
+## Component-Specific Styling
+
+You can override the theme for specific components using the `views` prop:
+
+```jsx
+import React from 'react';
+import { Button } from '@app-studio/web';
+
+function CustomStyledButton() {
+  return (
+    <Button
+      views={{
+        container: {
+          backgroundColor: '#6200ee',
+          borderRadius: 8,
+          boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)',
+        },
+      }}
+    >
+      Custom Styled Button
+    </Button>
+  );
+}
+```
+
+## Best Practices
+
+- Use theme variables instead of hardcoded values
+- Use the `useTheme` hook to access theme values
+- Use the `views` prop for component-specific styling
+- Use the `themeMode` prop for component-specific theme mode
+- Follow the spacing grid system (multiples of 4px)
+- Use semantic colors for consistent meaning across the application

package/docs/documentation-system.md

@@ -0,0 +1,143 @@
+# Documentation System
+
+This guide explains the documentation system used in the App Studio Web Component Library.
+
+## Overview
+
+The documentation system consists of:
+
+1. **Markdown Documentation**: General guides and tutorials in Markdown format
+2. **MDX Component Documentation**: Interactive component documentation in MDX format
+3. **Automated Documentation Generation**: Tools to generate and update documentation
+
+## Documentation Structure
+
+The documentation is organized into the following directories:
+
+- `docs/`: General documentation and guides
+- `public/files/media/`: MDX component documentation
+- `src/data/props/`: Generated component props data
+
+## MDX Component Documentation
+
+Component documentation is written in MDX format, which allows for interactive examples. Each component has an MDX file in the `public/files/media/` directory.
+
+Example MDX file structure:
+
+```mdx
+# Button
+
+Customizable button for user interaction
+
+### **Import**
+  ```tsx
+  import { Button } from '@app-studio/web';
+  ```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Button } from '../Button';
+
+export const DefaultButton = () => (
+  <Button onClick={() => alert('Hello, World!')}>Default</Button>
+);
+```
+
+### **Props**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| variant | 'filled' \| 'outline' \| 'ghost' \| 'link' | 'filled' | The visual style of the button |
+| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | The size of the button |
+```
+
+## Documentation Generation
+
+The documentation system includes tools to automatically generate and update documentation:
+
+### bot-doc
+
+The `bot-doc` tool generates component documentation by analyzing the component code. It:
+
+1. Processes component files to add comments
+2. Generates props data
+3. Creates MDX documentation
+
+To run `bot-doc` for a specific component:
+
+```bash
+npm run bot-doc -- ComponentName src/components/ComponentName
+```
+
+### create-docs
+
+The `create-docs` script checks for components without documentation and generates documentation for them. It also updates documentation for components that have changed.
+
+To run `create-docs`:
+
+```bash
+npm run create-docs
+```
+
+## Documentation Viewing
+
+The documentation can be viewed in the application using the documentation viewer at `/docs`. The documentation viewer:
+
+1. Loads MDX files
+2. Renders them with the MDX provider
+3. Provides a side menu for navigation
+
+## Adding New Documentation
+
+To add new documentation:
+
+1. Create a new Markdown file in the appropriate directory
+2. Add the file to the documentation structure
+3. Link to the file from related documentation
+
+## Updating Component Documentation
+
+To update component documentation:
+
+1. Run `bot-doc` for the component
+2. Review the generated documentation
+3. Make any necessary manual adjustments
+
+## Documentation Best Practices
+
+- Keep documentation up-to-date with code changes
+- Include examples for all components and features
+- Use consistent formatting and terminology
+- Link related documentation
+- Test all code examples
+- Include accessibility information
+- Document best practices and common pitfalls
+
+## Troubleshooting
+
+If you encounter issues with the documentation system:
+
+### Missing Component Documentation
+
+If a component is missing documentation:
+
+```bash
+npm run bot-doc -- ComponentName src/components/ComponentName
+```
+
+### Documentation Not Updating
+
+If documentation is not updating after code changes:
+
+1. Check if the component has changed significantly
+2. Run `bot-doc` manually for the component
+3. Check for errors in the console
+
+### MDX Rendering Issues
+
+If MDX files are not rendering correctly:
+
+1. Check the MDX syntax
+2. Ensure the MDX file is in the correct location
+3. Check for errors in the console

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 Web 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/web';
+
+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/web';
+
+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/web';
+
+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/web';
+
+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/web';
+
+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/web';
+
+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/web';
+
+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/web';
+
+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)