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

jac_client/docs/styling/styled-components.md

@@ -0,0 +1,395 @@
+# Styled Components
+
+CSS-in-JS library with component-scoped styles and dynamic styling for Jac applications.
+
+## Overview
+
+Styled Components allows you to write CSS-in-JS using template literals. Styles are scoped to components and can be dynamic based on props. This approach is perfect for:
+- Component-scoped styles
+- Dynamic styling based on props
+- CSS-in-JS with full CSS features
+- React component libraries
+
+## Example
+
+See the complete working example: [`examples/css-styling/styled-components/`](../../examples/css-styling/styled-components/)
+
+## Quick Start
+
+### 1. Install styled-components
+
+Add to `package.json`:
+
+```json
+{
+  "dependencies": {
+    "styled-components": "^6.1.13"
+  }
+}
+```
+
+### 2. Create Styled Components
+
+Create `styled.js`:
+
+```javascript
+import styled from "styled-components";
+
+export const Container = styled.div`
+    min-height: 100vh;
+    background: linear-gradient(to bottom right, #dbeafe, #e0e7ff);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 1rem;
+`;
+
+export const Card = styled.div`
+    background-color: #ffffff;
+    border-radius: 1rem;
+    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+    padding: 2rem;
+    max-width: 28rem;
+    width: 100%;
+`;
+
+export const Button = styled.button`
+    color: #ffffff;
+    font-weight: bold;
+    padding: 0.75rem 1.5rem;
+    border-radius: 0.5rem;
+    background-color: ${props => props.bgColor};
+
+    &:hover {
+        transform: scale(1.05);
+    }
+
+    &:active {
+        transform: scale(0.95);
+    }
+`;
+```
+
+### 3. Import and Use in Jac
+
+```jac
+# Pages
+cl import from react {useState, useEffect}
+cl import from .styled {
+    Container,
+    Card,
+    Button
+}
+
+cl {
+    def app() -> any {
+        return <Container>
+            <Card>
+                <Button bgColor="#ef4444" onClick={handleClick}>
+                    Click Me
+                </Button>
+            </Card>
+        </Container>;
+    }
+}
+```
+
+## Key Features
+
+### Dynamic Styling with Props
+
+Styled components can access props for dynamic styling:
+
+```javascript
+const Button = styled.button`
+    background-color: ${props => props.bgColor || '#007bff'};
+    color: ${props => props.primary ? 'white' : 'black'};
+    padding: ${props => props.large ? '1rem 2rem' : '0.75rem 1.5rem'};
+`;
+```
+
+### Pseudo-classes
+
+Use CSS pseudo-classes:
+
+```javascript
+const Button = styled.button`
+    background-color: #007bff;
+
+    &:hover {
+        background-color: #0056b3;
+        transform: scale(1.05);
+    }
+
+    &:active {
+        transform: scale(0.95);
+    }
+
+    &:focus {
+        outline: 2px solid #007bff;
+        outline-offset: 2px;
+    }
+`;
+```
+
+### Media Queries
+
+Responsive design with media queries:
+
+```javascript
+const Container = styled.div`
+    padding: 1rem;
+
+    @media (min-width: 768px) {
+        padding: 2rem;
+    }
+
+    @media (min-width: 1024px) {
+        padding: 3rem;
+    }
+`;
+```
+
+### Theming
+
+Use ThemeProvider for global themes:
+
+```javascript
+import { ThemeProvider } from 'styled-components';
+
+const theme = {
+    colors: {
+        primary: '#007bff',
+        secondary: '#6c757d',
+        success: '#28a745',
+    },
+    spacing: {
+        sm: '0.5rem',
+        md: '1rem',
+        lg: '2rem',
+    }
+};
+
+// In your app
+<ThemeProvider theme={theme}>
+    <App />
+</ThemeProvider>
+```
+
+Access theme in styled components:
+
+```javascript
+const Button = styled.button`
+    background-color: ${props => props.theme.colors.primary};
+    padding: ${props => props.theme.spacing.md};
+`;
+```
+
+## Best Practices
+
+### 1. Component Naming
+
+Use PascalCase for styled components:
+
+```javascript
+// Good
+const PrimaryButton = styled.button`...`;
+const CardHeader = styled.div`...`;
+
+// Avoid
+const button = styled.button`...`;
+const card_header = styled.div`...`;
+```
+
+### 2. Extract Common Styles
+
+Create base components and extend them:
+
+```javascript
+const ButtonBase = styled.button`
+    color: #ffffff;
+    font-weight: bold;
+    padding: 0.75rem 1.5rem;
+    border-radius: 0.5rem;
+    border: none;
+    cursor: pointer;
+`;
+
+const PrimaryButton = styled(ButtonBase)`
+    background-color: #007bff;
+
+    &:hover {
+        background-color: #0056b3;
+    }
+`;
+
+const SecondaryButton = styled(ButtonBase)`
+    background-color: #6c757d;
+
+    &:hover {
+        background-color: #545b62;
+    }
+`;
+```
+
+### 3. Use Props Wisely
+
+Keep prop-based styling simple:
+
+```javascript
+// Good
+const Button = styled.button`
+    background-color: ${props => props.variant === 'primary' ? '#007bff' : '#6c757d'};
+`;
+
+// Avoid complex logic in template literals
+const Button = styled.button`
+    background-color: ${props => {
+        if (props.variant === 'primary') {
+            if (props.disabled) return '#ccc';
+            return '#007bff';
+        }
+        // ... too complex
+    }};
+`;
+```
+
+### 4. Organize Files
+
+Group related styled components together:
+
+```javascript
+// components/Button.styled.js
+export const Button = styled.button`...`;
+export const ButtonGroup = styled.div`...`;
+
+// components/Card.styled.js
+export const Card = styled.div`...`;
+export const CardHeader = styled.div`...`;
+export const CardBody = styled.div`...`;
+```
+
+### 5. Performance
+
+Use `React.memo` for expensive styled components:
+
+```javascript
+const ExpensiveComponent = React.memo(styled.div`
+    /* complex styles */
+`);
+```
+
+## Advanced Patterns
+
+### Extending Components
+
+Extend existing styled components:
+
+```javascript
+const Button = styled.button`
+    padding: 0.75rem 1.5rem;
+    border-radius: 0.5rem;
+`;
+
+const PrimaryButton = styled(Button)`
+    background-color: #007bff;
+    color: white;
+`;
+
+const LargeButton = styled(Button)`
+    padding: 1rem 2rem;
+    font-size: 1.25rem;
+`;
+```
+
+### Conditional Rendering
+
+Use conditional logic in styles:
+
+```javascript
+const Container = styled.div`
+    display: ${props => props.hidden ? 'none' : 'flex'};
+    opacity: ${props => props.disabled ? 0.5 : 1};
+    pointer-events: ${props => props.disabled ? 'none' : 'auto'};
+`;
+```
+
+### Animations
+
+Use CSS animations:
+
+```javascript
+const FadeIn = styled.div`
+    animation: fadeIn 0.5s ease-in;
+
+    @keyframes fadeIn {
+        from {
+            opacity: 0;
+            transform: translateY(-10px);
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0);
+        }
+    }
+`;
+```
+
+## Advantages
+
+-  **Component-scoped styles** (no CSS conflicts)
+-  **Dynamic styling** based on props
+-  **Full CSS features** (pseudo-classes, media queries)
+-  **Type-safe** with TypeScript
+-  **Automatic vendor prefixing**
+-  **Dead code elimination**
+-  **No class name collisions**
+
+## Limitations
+
+-  **Runtime overhead** (styles generated at runtime)
+-  **Learning curve** for CSS-in-JS
+-  **Larger bundle size** than CSS
+-  **Requires JavaScript** for styling
+-  **Debugging** can be harder
+
+## When to Use
+
+Choose Styled Components when:
+
+- You want component-scoped styles
+- You need dynamic styling based on props
+- You prefer CSS-in-JS approach
+- You're building component libraries
+- You want full CSS features in JavaScript
+- You want to avoid class name conflicts
+
+## Import Syntax
+
+Styled components are imported as JavaScript modules:
+
+```jac
+cl import from .styled {
+    Container,
+    Card,
+    Button
+}
+```
+
+For external packages:
+
+```jac
+cl import from "styled-components" { default as styled }
+```
+
+## Next Steps
+
+- Explore [Emotion](./emotion.md) for similar CSS-in-JS (coming soon)
+- Check out [Vanilla Extract](./vanilla-extract.md) for zero-runtime CSS-in-JS (coming soon)
+- Learn about [JavaScript Styling](./js-styling.md) for inline styles
+- See [CSS Modules](./css-modules.md) for scoped CSS (coming soon)
+
+## Resources
+
+- [Styled Components Documentation](https://styled-components.com/docs)
+- [Styled Components Best Practices](https://styled-components.com/docs/basics#styling-any-component)

jac_client/docs/styling/tailwind.md

@@ -0,0 +1,298 @@
+# Tailwind CSS
+
+Utility-first CSS framework for rapid UI development in Jac applications.
+
+## Overview
+
+Tailwind CSS provides low-level utility classes that you can compose to build custom designs. This approach is perfect for:
+- Rapid UI development
+- Consistent design systems
+- Responsive designs
+- Modern, utility-based styling
+
+## Example
+
+See the complete working example: [`examples/css-styling/tailwind-example/`](../../examples/css-styling/tailwind-example/)
+
+## Quick Start
+
+### 1. Install Tailwind CSS
+
+Add to `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0"
+  }
+}
+```
+
+### 2. Configure Vite
+
+Update `vite.config.js`:
+
+```javascript
+import { defineConfig } from "vite";
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+  // ... other config
+});
+```
+
+### 3. Add Tailwind Directives
+
+Create `global.css`:
+
+```css
+@import "tailwindcss";
+```
+
+### 4. Import CSS in Jac
+
+```jac
+# Pages
+cl import from react {useState, useEffect}
+cl import ".global.css";
+
+cl {
+    def app() -> any {
+        return <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100">
+            <h1 className="text-3xl font-bold">Hello, Tailwind!</h1>
+        </div>;
+    }
+}
+```
+
+## Using Utility Classes
+
+### Spacing
+
+```jac
+<div className="p-4 m-2 gap-4">
+    {/* padding: 1rem, margin: 0.5rem, gap: 1rem */}
+</div>
+```
+
+### Colors
+
+```jac
+<div className="bg-blue-500 text-white hover:bg-blue-600">
+    {/* Blue background, white text, darker blue on hover */}
+</div>
+```
+
+### Layout
+
+```jac
+<div className="flex items-center justify-center">
+    {/* Flexbox with centered items */}
+</div>
+```
+
+### Responsive
+
+```jac
+<div className="text-sm md:text-lg lg:text-xl">
+    {/* Small on mobile, large on tablet, xl on desktop */}
+</div>
+```
+
+## Dynamic Classes
+
+Combine static and dynamic classes:
+
+```jac
+let countColorClass = "text-gray-800" if count == 0 else ("text-green-600" if count > 0 else "text-red-600");
+
+return <div className={"text-6xl font-bold " + countColorClass + " transition-colors duration-300"}>
+    {count}
+</div>;
+```
+
+## Common Utility Patterns
+
+### Buttons
+
+```jac
+<button className="bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded">
+    Click Me
+</button>
+```
+
+### Cards
+
+```jac
+<div className="bg-white rounded-lg shadow-lg p-6">
+    <h2 className="text-2xl font-bold mb-4">Card Title</h2>
+    <p className="text-gray-600">Card content</p>
+</div>
+```
+
+### Flexbox Layouts
+
+```jac
+<div className="flex flex-col md:flex-row gap-4">
+    <div className="flex-1">Column 1</div>
+    <div className="flex-1">Column 2</div>
+</div>
+```
+
+### Grid Layouts
+
+```jac
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    <div>Item 1</div>
+    <div>Item 2</div>
+    <div>Item 3</div>
+</div>
+```
+
+## Best Practices
+
+### 1. Use Responsive Prefixes
+
+Design mobile-first with responsive breakpoints:
+
+```jac
+<div className="text-sm md:text-base lg:text-lg">
+    Responsive text
+</div>
+```
+
+### 2. Combine Utilities
+
+Chain multiple utilities for complex styles:
+
+```jac
+<button className="bg-blue-500 hover:bg-blue-600 text-white font-bold py-3 px-6 rounded-lg shadow-lg transition-all duration-200 transform hover:scale-105">
+    Button
+</button>
+```
+
+### 3. Use Hover/Focus States
+
+Leverage pseudo-class variants:
+
+```jac
+<button className="bg-blue-500 hover:bg-blue-600 focus:ring-2 focus:ring-blue-300">
+    Interactive Button
+</button>
+```
+
+### 4. Leverage Transitions
+
+Add smooth transitions:
+
+```jac
+<div className="transition-all duration-200 hover:scale-105">
+    Hoverable element
+</div>
+```
+
+### 5. Use Arbitrary Values
+
+For custom values:
+
+```jac
+<div className="w-[500px] h-[300px] bg-[#1da1f2]">
+    Custom dimensions and color
+</div>
+```
+
+## Configuration
+
+Customize Tailwind in `tailwind.config.js`:
+
+```javascript
+export default {
+  theme: {
+    extend: {
+      colors: {
+        'brand': '#your-color',
+      },
+      spacing: {
+        '128': '32rem',
+      },
+    },
+  },
+}
+```
+
+## Advantages
+
+-  **Rapid development** with utility classes
+-  **Consistent design system**
+-  **Responsive by default**
+-  **Small bundle size** (unused classes are purged)
+-  **Great documentation** and ecosystem
+-  **Highly customizable**
+
+## Limitations
+
+-  **Can get verbose** with many classes
+-  **Learning curve** for utility-first approach
+-  **Less semantic** than component-based CSS
+-  **Requires build step**
+-  **HTML can get cluttered**
+
+## When to Use
+
+Choose Tailwind CSS when:
+
+- You want to build UIs quickly
+- You prefer utility classes over custom CSS
+- You need a consistent design system
+- You're building modern, responsive designs
+- You want a small bundle size
+- You prefer configuration over writing CSS
+
+## Purging Unused Classes
+
+Tailwind automatically removes unused classes in production builds, keeping bundle size small. No configuration needed with Vite plugin.
+
+## Customization
+
+### Custom Colors
+
+```javascript
+// tailwind.config.js
+export default {
+  theme: {
+    extend: {
+      colors: {
+        'brand-blue': '#1e40af',
+        'brand-purple': '#7c3aed',
+      },
+    },
+  },
+}
+```
+
+### Custom Spacing
+
+```javascript
+theme: {
+  extend: {
+    spacing: {
+      '18': '4.5rem',
+      '88': '22rem',
+    },
+  },
+}
+```
+
+## Next Steps
+
+- Explore [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- Check out [UnoCSS](./unocss.md) for similar utility-first approach (coming soon)
+- Learn about [CSS Modules](./css-modules.md) for component-scoped styles (coming soon)
+- See [Pure CSS](./pure-css.md) for traditional CSS approach
+
+## Resources
+
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [Tailwind UI Components](https://tailwindui.com/)
+- [Tailwind Play](https://play.tailwindcss.com/) - Online playground

jac_client/examples/all-in-one/.babelrc

@@ -0,0 +1,9 @@
+
+{
+    "presets": [[
+        "@babel/preset-env",
+        {
+            "modules": false
+        }
+    ], "@babel/preset-react"]
+}

jac_client/examples/all-in-one/README.md

@@ -0,0 +1,16 @@
+# all-in-one
+
+## Running Jac Code
+
+make sure node modules are installed:
+```bash
+npm install
+```
+
+To run your Jac code, use the Jac CLI:
+
+```bash
+jac serve app.jac
+```
+
+Happy coding with Jac!