jac-client 0.2.0__py3-none-any.whl → 0.2.3__py3-none-any.whl

jac_client/docs/styling/js-styling.md

@@ -0,0 +1,367 @@
+# JavaScript Styling
+
+Inline styles using JavaScript objects for dynamic styling in Jac applications.
+
+## Overview
+
+JavaScript styling uses JavaScript objects to define styles, which are then applied via the `style` prop. This approach is perfect for:
+- Dynamic styling based on state
+- Programmatic style generation
+- Component-scoped styles without CSS files
+- React-style inline styling
+
+## Example
+
+See the complete working example: [`examples/css-styling/js-styling/`](../../examples/css-styling/js-styling/)
+
+## Quick Start
+
+### 1. Define Style Objects
+
+Create `styles.js`:
+
+```javascript
+const countDisplay = {
+    fontSize: "3.75rem",
+    fontWeight: "bold",
+    transition: "color 0.3s ease"
+};
+
+export default {
+    container: {
+        minHeight: "100vh",
+        background: "linear-gradient(to bottom right, #dbeafe, #e0e7ff)",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        padding: "1rem"
+    },
+    card: {
+        backgroundColor: "#ffffff",
+        borderRadius: "1rem",
+        boxShadow: "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
+        padding: "2rem",
+        maxWidth: "28rem",
+        width: "100%"
+    },
+    countDisplayZero: {
+        ...countDisplay,
+        color: "#1f2937"
+    },
+    countDisplayPositive: {
+        ...countDisplay,
+        color: "#16a34a"
+    },
+    countDisplayNegative: {
+        ...countDisplay,
+        color: "#dc2626"
+    },
+    button: {
+        color: "#ffffff",
+        fontWeight: "bold",
+        padding: "0.75rem 1.5rem",
+        borderRadius: "0.5rem",
+        border: "none",
+        cursor: "pointer"
+    },
+    buttonDecrement: {
+        backgroundColor: "#ef4444"
+    },
+    buttonReset: {
+        backgroundColor: "#6b7280"
+    },
+    buttonIncrement: {
+        backgroundColor: "#22c55e"
+    }
+};
+```
+
+### 2. Import Styles
+
+```jac
+# Pages
+cl import from react {useState, useEffect}
+cl import from .styles { default as styles }
+
+cl {
+    def app() -> any {
+        return <div style={styles.container}>
+            <div style={styles.card}>
+                <h1 style={styles.title}>Counter Application</h1>
+            </div>
+        </div>;
+    }
+}
+```
+
+### 3. Apply Styles
+
+Use the `style` prop with style objects:
+
+```jac
+return <div style={styles.container}>
+    <div style={styles.card}>
+        <h1 style={styles.title}>Counter Application</h1>
+    </div>
+</div>;
+```
+
+### 4. Dynamic Styles
+
+Select styles based on state:
+
+```jac
+let countStyle = styles.countDisplayZero if count == 0 else (styles.countDisplayPositive if count > 0 else styles.countDisplayNegative);
+
+return <div style={countStyle}>{count}</div>;
+```
+
+## Style Object Format
+
+JavaScript style objects use camelCase property names (React convention):
+
+```javascript
+{
+    backgroundColor: "#ffffff",  // not background-color
+    fontSize: "1.5rem",         // not font-size
+    marginTop: "10px",          // not margin-top
+    zIndex: 1,                  // not z-index
+    borderTopLeftRadius: "4px"  // not border-top-left-radius
+}
+```
+
+## Best Practices
+
+### 1. Use Object Spread
+
+Share common styles with spread operator:
+
+```javascript
+const baseButton = {
+    padding: "0.75rem 1.5rem",
+    borderRadius: "0.5rem",
+    border: "none",
+    cursor: "pointer"
+};
+
+export default {
+    primaryButton: {
+        ...baseButton,
+        backgroundColor: "#007bff",
+        color: "#ffffff"
+    },
+    secondaryButton: {
+        ...baseButton,
+        backgroundColor: "#6c757d",
+        color: "#ffffff"
+    }
+};
+```
+
+### 2. Organize by Component
+
+Group related styles together:
+
+```javascript
+export default {
+    // Container styles
+    container: { ... },
+    card: { ... },
+
+    // Button styles
+    button: { ... },
+    buttonPrimary: { ... },
+    buttonSecondary: { ... },
+
+    // Text styles
+    title: { ... },
+    subtitle: { ... }
+};
+```
+
+### 3. Use Constants
+
+Define reusable values at the top:
+
+```javascript
+const COLORS = {
+    primary: "#007bff",
+    secondary: "#6c757d",
+    success: "#28a745",
+    danger: "#dc3545"
+};
+
+const SPACING = {
+    sm: "0.5rem",
+    md: "1rem",
+    lg: "2rem"
+};
+
+export default {
+    button: {
+        backgroundColor: COLORS.primary,
+        padding: SPACING.md
+    }
+};
+```
+
+### 4. CamelCase Properties
+
+Follow React naming convention:
+
+```javascript
+// Good
+{
+    backgroundColor: "#fff",
+    fontSize: "1rem",
+    marginTop: "10px"
+}
+
+// Avoid
+{
+    "background-color": "#fff",  // Wrong
+    "font-size": "1rem"          // Wrong
+}
+```
+
+### 5. Extract Complex Logic
+
+Move style calculations to functions:
+
+```javascript
+export const getButtonStyle = (variant, disabled) => {
+    const base = {
+        padding: "0.75rem 1.5rem",
+        borderRadius: "0.5rem",
+        border: "none",
+        cursor: disabled ? "not-allowed" : "pointer",
+        opacity: disabled ? 0.5 : 1
+    };
+
+    const variants = {
+        primary: { backgroundColor: "#007bff", color: "#ffffff" },
+        secondary: { backgroundColor: "#6c757d", color: "#ffffff" }
+    };
+
+    return { ...base, ...variants[variant] };
+};
+```
+
+## Advanced Patterns
+
+### Style Functions
+
+Create functions that return styles:
+
+```javascript
+export const getButtonStyle = (variant) => ({
+    padding: "0.75rem 1.5rem",
+    borderRadius: "0.5rem",
+    backgroundColor: variant === 'primary' ? '#007bff' : '#6c757d',
+    color: '#ffffff'
+});
+```
+
+Use in Jac:
+
+```jac
+let buttonStyle = getButtonStyle("primary");
+
+return <button style={buttonStyle}>Click Me</button>;
+```
+
+### Conditional Styles
+
+Use ternary operators for conditional styles:
+
+```javascript
+export default {
+    button: (isActive, isDisabled) => ({
+        backgroundColor: isActive ? '#007bff' : '#6c757d',
+        opacity: isDisabled ? 0.5 : 1,
+        cursor: isDisabled ? 'not-allowed' : 'pointer'
+    })
+};
+```
+
+### Dynamic Values
+
+Calculate styles based on props:
+
+```javascript
+export const getContainerStyle = (width, height) => ({
+    width: `${width}px`,
+    height: `${height}px`,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center"
+});
+```
+
+## Advantages
+
+-  **Dynamic styling** based on props/state
+-  **No CSS file needed**
+-  **Type-safe** with TypeScript
+-  **Component-scoped** by default
+-  **Programmatic style generation**
+-  **Easy to debug** (JavaScript objects)
+-  **No build step** for styles
+
+## Limitations
+
+-  **No pseudo-classes** (hover, focus, etc.)
+-  **No media queries**
+-  **No CSS animations** (use JavaScript)
+-  **Verbose** for complex styles
+-  **No CSS preprocessor features**
+-  **Performance** can be slower for many elements
+
+## When to Use
+
+Choose JavaScript Styling when:
+
+- You need dynamic styles based on state
+- You want programmatic style generation
+- You prefer keeping styles in JavaScript
+- You're building component libraries
+- You need runtime style calculations
+- You want type safety with TypeScript
+
+## Import Syntax
+
+Style objects are imported as JavaScript modules:
+
+```jac
+# Default export
+cl import from .styles { default as styles }
+
+# Named exports (if using named exports)
+cl import from .styles { button, card, container }
+```
+
+## Combining Styles
+
+You can combine multiple style objects:
+
+```jac
+let combinedStyle = {
+    ...styles.base,
+    ...styles.button,
+    ...(isActive ? styles.active : {})
+};
+
+return <button style={combinedStyle}>Click Me</button>;
+```
+
+## Next Steps
+
+- Explore [Styled Components](./styled-components.md) for CSS-in-JS with more features
+- Check out [Emotion](./emotion.md) for similar CSS-in-JS approach (coming soon)
+- Learn about [CSS Modules](./css-modules.md) for scoped CSS (coming soon)
+- See [Pure CSS](./pure-css.md) for traditional CSS approach
+
+## Resources
+
+- [React Inline Styles](https://react.dev/learn/javascript-in-jsx-with-curly-braces#using-double-curlies-css-and-other-objects-in-jsx)
+- [CSS-in-JS Comparison](https://github.com/MicheleBertoli/css-in-js)

jac_client/docs/styling/material-ui.md

@@ -0,0 +1,341 @@
+# Material-UI
+
+Comprehensive React component library with Material Design for Jac applications.
+
+## Overview
+
+Material-UI (MUI) provides pre-built, accessible React components following Material Design principles. This approach is perfect for:
+- Rapid application development
+- Consistent Material Design
+- Accessible components out of the box
+- Enterprise applications
+
+## Example
+
+See the complete working example: [`examples/css-styling/material-ui/`](../../examples/css-styling/material-ui/)
+
+## Quick Start
+
+### 1. Install Material-UI
+
+Add to `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@mui/material": "^5.15.0",
+    "@mui/icons-material": "^5.15.0"
+  }
+}
+```
+
+### 2. Import Components
+
+In your Jac file:
+
+```jac
+# Pages
+cl import from react {useState, useEffect}
+cl import from "@mui/material/Button" { default as Button }
+cl import from "@mui/material/Card" { default as Card }
+cl import from "@mui/material/CardContent" { default as CardContent }
+cl import from "@mui/material/Box" { default as Box }
+cl import from "@mui/icons-material/Add" { default as AddIcon }
+cl import from "@mui/icons-material/Remove" { default as RemoveIcon }
+
+cl {
+    def app() -> any {
+        return <Box sx={{"display": "flex", "justifyContent": "center"}}>
+            <Card>
+                <CardContent>
+                    <Button variant="contained" onClick={handleIncrement}>
+                        <AddIcon />
+                    </Button>
+                </CardContent>
+            </Card>
+        </Box>;
+    }
+}
+```
+
+## Key Features
+
+### Theming
+
+Material-UI comes with a built-in theme system:
+
+```javascript
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+
+const theme = createTheme({
+    palette: {
+        primary: {
+            main: '#1976d2',
+        },
+        secondary: {
+            main: '#dc004e',
+        },
+    },
+    typography: {
+        fontFamily: 'Roboto, Arial, sans-serif',
+    },
+    spacing: 8, // 8px base unit
+});
+
+// Wrap your app
+<ThemeProvider theme={theme}>
+    <App />
+</ThemeProvider>
+```
+
+### sx Prop
+
+Use the `sx` prop for styling:
+
+```jac
+<Box sx={{
+    display: "flex",
+    justifyContent: "center",
+    alignItems: "center",
+    minHeight: "100vh",
+    backgroundColor: "background.default"
+}}>
+    <Card sx={{
+        maxWidth: 400,
+        padding: 2
+    }}>
+        Content
+    </Card>
+</Box>
+```
+
+### Component Variants
+
+Use built-in variants:
+
+```jac
+<Button variant="contained" color="primary">Contained</Button>
+<Button variant="outlined" color="secondary">Outlined</Button>
+<Button variant="text">Text</Button>
+```
+
+## Common Components
+
+### Layout Components
+
+```jac
+# Box - Container component
+<Box sx={{"display": "flex", "gap": 2}}>
+    <Box>Item 1</Box>
+    <Box>Item 2</Box>
+</Box>
+
+# Grid - Responsive grid system
+cl import from "@mui/material/Grid" { default as Grid }
+<Grid container spacing={2}>
+    <Grid item xs={12} md={6}>Column 1</Grid>
+    <Grid item xs={12} md={6}>Column 2</Grid>
+</Grid>
+
+# Stack - Flexbox container
+cl import from "@mui/material/Stack" { default as Stack }
+<Stack direction="row" spacing={2}>
+    <Button>Button 1</Button>
+    <Button>Button 2</Button>
+</Stack>
+```
+
+### Input Components
+
+```jac
+# TextField
+cl import from "@mui/material/TextField" { default as TextField }
+<TextField label="Name" variant="outlined" />
+
+# Button
+<Button variant="contained" color="primary" onClick={handleClick}>
+    Click Me
+</Button>
+
+# Select
+cl import from "@mui/material/Select" { default as Select }
+cl import from "@mui/material/MenuItem" { default as MenuItem }
+<Select value={value} onChange={handleChange}>
+    <MenuItem value="option1">Option 1</MenuItem>
+    <MenuItem value="option2">Option 2</MenuItem>
+</Select>
+```
+
+### Feedback Components
+
+```jac
+# Card
+<Card>
+    <CardContent>
+        <Typography variant="h5">Card Title</Typography>
+        <Typography variant="body2">Card content</Typography>
+    </CardContent>
+</Card>
+
+# Dialog
+cl import from "@mui/material/Dialog" { default as Dialog }
+cl import from "@mui/material/DialogTitle" { default as DialogTitle }
+<Dialog open={open} onClose={handleClose}>
+    <DialogTitle>Dialog Title</DialogTitle>
+</Dialog>
+
+# Snackbar
+cl import from "@mui/material/Snackbar" { default as Snackbar }
+cl import from "@mui/material/Alert" { default as Alert }
+<Snackbar open={open} autoHideDuration={6000}>
+    <Alert severity="success">Success message!</Alert>
+</Snackbar>
+```
+
+## Best Practices
+
+### 1. Use sx Prop
+
+For component-specific styling:
+
+```jac
+<Box sx={{
+    display: "flex",
+    justifyContent: "center",
+    padding: 2,
+    backgroundColor: "primary.main"
+}}>
+```
+
+### 2. Leverage Variants
+
+Use built-in variants when possible:
+
+```jac
+<Button variant="contained" color="primary">Primary</Button>
+<Typography variant="h1">Heading</Typography>
+```
+
+### 3. Theme Customization
+
+Customize theme for brand colors:
+
+```javascript
+const theme = createTheme({
+    palette: {
+        primary: {
+            main: '#your-brand-color',
+        },
+    },
+});
+```
+
+### 4. Accessibility
+
+MUI components are accessible by default:
+
+```jac
+<Button aria-label="Add item">
+    <AddIcon />
+</Button>
+```
+
+### 5. Icons
+
+Use @mui/icons-material for consistent icons:
+
+```jac
+cl import from "@mui/icons-material/Add" { default as AddIcon }
+cl import from "@mui/icons-material/Delete" { default as DeleteIcon }
+cl import from "@mui/icons-material/Edit" { default as EditIcon }
+```
+
+## Advantages
+
+-  **Pre-built, accessible components**
+-  **Consistent Material Design**
+-  **Comprehensive component library**
+-  **Built-in theming system**
+-  **TypeScript support**
+-  **Active community** and documentation
+-  **Production-ready** components
+
+## Limitations
+
+-  **Larger bundle size**
+-  **Material Design aesthetic** (may not fit all brands)
+-  **Learning curve** for component API
+-  **Less flexibility** than custom CSS
+-  **Requires JavaScript** for styling
+
+## When to Use
+
+Choose Material-UI when:
+
+- You want pre-built components
+- You need accessible components
+- You prefer Material Design
+- You're building enterprise applications
+- You want to focus on functionality over styling
+- You need comprehensive component library
+
+## Import Syntax
+
+MUI components are imported from their specific packages:
+
+```jac
+# Material components
+cl import from "@mui/material/Button" { default as Button }
+cl import from "@mui/material/Card" { default as Card }
+
+# Icons
+cl import from "@mui/icons-material/Add" { default as AddIcon }
+cl import from "@mui/icons-material/Delete" { default as DeleteIcon }
+
+# Multiple imports
+cl import from "@mui/material" {
+    Button,
+    Card,
+    CardContent,
+    Box
+}
+```
+
+## Theming Example
+
+```javascript
+// theme.js
+import { createTheme } from '@mui/material/styles';
+
+export const theme = createTheme({
+    palette: {
+        mode: 'light',
+        primary: {
+            main: '#1976d2',
+        },
+        secondary: {
+            main: '#dc004e',
+        },
+    },
+    typography: {
+        fontFamily: 'Roboto, Arial, sans-serif',
+        h1: {
+            fontSize: '2.5rem',
+        },
+    },
+    spacing: 8,
+});
+```
+
+## Next Steps
+
+- Explore [Material-UI Documentation](https://mui.com/)
+- Check out [Chakra UI](./chakra-ui.md) for alternative component library (coming soon)
+- Learn about [Ant Design](./ant-design.md) for enterprise components (coming soon)
+- See [Styled Components](./styled-components.md) for CSS-in-JS approach
+
+## Resources
+
+- [Material-UI Documentation](https://mui.com/)
+- [Material-UI Components](https://mui.com/material-ui/getting-started/)
+- [Material Design Guidelines](https://m3.material.io/)