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

jac_client/docs/styling/material-ui.md

@@ -0,0 +1,346 @@
+# 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/)
+
+
+
+
+

jac_client/docs/styling/pure-css.md

@@ -0,0 +1,305 @@
+# Pure CSS
+
+Traditional CSS with external stylesheets. The most straightforward styling approach for Jac applications.
+
+## Overview
+
+Pure CSS is the foundation of web styling. You write CSS in a separate file and import it into your Jac code. This approach is perfect for:
+- Simple projects
+- Learning CSS fundamentals
+- Maximum control over styling
+- Minimal dependencies
+
+## Example
+
+See the complete working example: [`examples/css-styling/pure-css/`](../../examples/css-styling/pure-css/)
+
+## Quick Start
+
+### 1. Create CSS File
+
+Create a `styles.css` file in your project:
+
+```css
+.container {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    min-height: 100vh;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+.card {
+    background: white;
+    border-radius: 20px;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+    padding: 40px;
+    min-width: 400px;
+    text-align: center;
+}
+
+.title {
+    font-size: 2rem;
+    color: #667eea;
+    margin: 0 0 10px 0;
+    font-weight: 600;
+}
+```
+
+### 2. Import CSS in Jac
+
+In your Jac file, import the CSS file:
+
+```jac
+# Pages
+cl import from react {useState, useEffect}
+cl import ".styles.css";
+
+cl {
+    def app() -> any {
+        let [count, setCount] = useState(0);
+
+        return <div className="container">
+            <div className="card">
+                <h1 className="title">Counter Application</h1>
+                <p>Count: {count}</p>
+            </div>
+        </div>;
+    }
+}
+```
+
+### 3. Use Class Names
+
+Apply CSS classes using the `className` prop:
+
+```jac
+return <div className="container">
+    <div className="card">
+        <h1 className="title">Counter Application</h1>
+    </div>
+</div>;
+```
+
+### 4. Dynamic Classes
+
+Dynamically construct class names based on state:
+
+```jac
+let countClass = "countDisplay " + ("positive" if count > 0 else "negative" if count < 0 else "zero");
+
+return <div className={countClass}>{count}</div>;
+```
+
+## Import Syntax
+
+CSS files are imported using the `cl import` syntax:
+
+```jac
+cl import ".styles.css";
+```
+
+This compiles to:
+
+```javascript
+import "./styles.css";
+```
+
+Vite automatically processes CSS imports and extracts them to a separate CSS file during the build process.
+
+## Best Practices
+
+### 1. Organize Your CSS
+
+Use comments to separate sections:
+
+```css
+/* ============================================
+   Container Styles
+   ============================================ */
+.container {
+    /* styles */
+}
+
+/* ============================================
+   Card Styles
+   ============================================ */
+.card {
+    /* styles */
+}
+```
+
+### 2. Use Semantic Class Names
+
+Make class names descriptive and meaningful:
+
+```css
+/* Good */
+.button-primary { }
+.card-header { }
+.navigation-menu { }
+
+/* Avoid */
+.btn1 { }
+.div1 { }
+.red { }
+```
+
+### 3. Use CSS Variables for Theming
+
+Leverage CSS custom properties for theming:
+
+```css
+:root {
+    --primary-color: #007bff;
+    --secondary-color: #6c757d;
+    --spacing-unit: 1rem;
+}
+
+.button {
+    background-color: var(--primary-color);
+    padding: var(--spacing-unit);
+}
+```
+
+### 4. Mobile-First Design
+
+Design for mobile, then enhance for desktop:
+
+```css
+/* Mobile first */
+.container {
+    padding: 1rem;
+}
+
+/* Desktop */
+@media (min-width: 768px) {
+    .container {
+        padding: 2rem;
+    }
+}
+```
+
+### 5. Avoid Inline Styles
+
+Keep styles in the CSS file for maintainability:
+
+```jac
+// ❌ Avoid
+<div style={{"padding": "1rem", "color": "blue"}}>
+
+// ✅ Prefer
+<div className="container">
+```
+
+## Advantages
+
+- ✅ **No build step required** for CSS
+- ✅ **Easy to understand** and maintain
+- ✅ **Works with any CSS framework**
+- ✅ **Minimal dependencies**
+- ✅ **Great browser support**
+- ✅ **Familiar syntax** for developers
+
+## Limitations
+
+- ❌ **No variables or nesting** (use CSS variables for theming)
+- ❌ **No preprocessing features**
+- ❌ **Global scope** (use BEM or similar for scoping)
+- ❌ **No dynamic styling** based on props
+- ❌ **Manual organization** required
+
+## When to Use
+
+Choose Pure CSS when:
+
+- You're building a simple application
+- You want minimal dependencies
+- You prefer traditional CSS workflow
+- You're learning CSS fundamentals
+- You need maximum control
+- You want to avoid build complexity
+
+## CSS Variables (Custom Properties)
+
+Use CSS custom properties for theming and dynamic values:
+
+```css
+:root {
+    --primary: #007bff;
+    --secondary: #6c757d;
+    --success: #28a745;
+    --danger: #dc3545;
+    --spacing-sm: 0.5rem;
+    --spacing-md: 1rem;
+    --spacing-lg: 2rem;
+}
+
+.button {
+    background-color: var(--primary);
+    padding: var(--spacing-md);
+}
+
+.button-success {
+    background-color: var(--success);
+}
+```
+
+## Responsive Design
+
+Use media queries for responsive layouts:
+
+```css
+.container {
+    padding: 1rem;
+}
+
+@media (min-width: 768px) {
+    .container {
+        padding: 2rem;
+    }
+}
+
+@media (min-width: 1024px) {
+    .container {
+        padding: 3rem;
+    }
+}
+```
+
+## Naming Conventions
+
+### BEM (Block Element Modifier)
+
+```css
+.card { }                    /* Block */
+.card__header { }           /* Element */
+.card__header--highlighted { } /* Modifier */
+```
+
+### Utility Classes
+
+```css
+.text-center { text-align: center; }
+.mt-1 { margin-top: 0.25rem; }
+.p-2 { padding: 0.5rem; }
+```
+
+## Next Steps
+
+- Learn about [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for advanced theming
+- Explore [Sass/SCSS](./sass.md) for preprocessing features
+- Check out [Tailwind CSS](./tailwind.md) for utility-first approach
+- See [CSS Modules](./css-modules.md) for scoped styles (coming soon)
+
+## Resources
+
+- [MDN CSS Documentation](https://developer.mozilla.org/en-US/docs/Web/CSS)
+- [CSS Tricks](https://css-tricks.com/)
+- [Can I Use](https://caniuse.com/) - Browser compatibility
+
+
+
+
+
+