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

jac_client/docs/styling/intro.md

@@ -1,249 +0,0 @@
-# Styling in Jac
-
-This guide covers all styling approaches available in Jac web applications. Each approach is demonstrated with a complete, working counter application example.
-
-## Quick Navigation
-
-###  Available Examples
-
-| Styling Approach | Documentation | Example Location |
-|------------------|---------------|------------------|
-| [**Pure CSS**](./pure-css.md) | Traditional CSS with external stylesheet | [`examples/css-styling/pure-css/`](../../examples/css-styling/pure-css/) |
-| [**Tailwind CSS**](./tailwind.md) | Utility-first CSS framework | [`examples/css-styling/tailwind-example/`](../../examples/css-styling/tailwind-example/) |
-| [**Sass/SCSS**](./sass.md) | CSS preprocessor with variables, mixins, nesting | [`examples/css-styling/sass-example/`](../../examples/css-styling/sass-example/) |
-| [**Styled Components**](./styled-components.md) | CSS-in-JS with styled-components | [`examples/css-styling/styled-components/`](../../examples/css-styling/styled-components/) |
-| [**JavaScript Styling**](./js-styling.md) | Inline styles using JavaScript objects | [`examples/css-styling/js-styling/`](../../examples/css-styling/js-styling/) |
-| [**Material-UI**](./material-ui.md) | React component library with Material Design | [`examples/css-styling/material-ui/`](../../examples/css-styling/material-ui/) |
-
-## Styling Approaches Overview
-
-### Traditional CSS
-- **Pure CSS** — Standard CSS with external stylesheets
-  - Maximum control, minimal dependencies
-  - Perfect for simple projects and learning
-
-### CSS Preprocessors
-- **Sass/SCSS** — Variables, nesting, mixins, and functions
-  - Better organization for large projects
-  - DRY principles with reusable code
-
-### Utility-First CSS
-- **Tailwind CSS** — On-demand utility classes
-  - Rapid UI development
-  - Consistent design system
-
-### CSS-in-JS Libraries
-- **Styled Components** — CSS-in-JS with template literals
-  - Component-scoped styles
-  - Dynamic styling with props
-
-- **JavaScript Styling** — Inline styles using JavaScript objects
-  - Programmatic style generation
-  - Dynamic styles based on state
-
-### Component Libraries
-- **Material-UI** — Comprehensive React component library
-  - Pre-built, accessible components
-  - Material Design system
-
-## Choosing the Right Approach
-
-### Decision Matrix
-
-| Approach | Complexity | Bundle Size | Runtime Cost | Best For |
-|----------|-----------|-------------|--------------|----------|
-| Pure CSS | Low | Small | None | Simple projects |
-| Tailwind | Medium | Small* | None | Rapid development |
-| Sass/SCSS | Medium | Small | None | Large projects |
-| Styled Components | Medium | Medium | Medium | Component libraries |
-| JavaScript Styling | Low | Small | Low | Dynamic styles |
-| Material-UI | Low | Large | Low | Enterprise apps |
-
-*Tailwind bundle size is small after purging unused classes.
-
-### Quick Decision Guide
-
-**Choose Pure CSS if**:
-- Building a simple application
-- Wanting minimal dependencies
-- Learning CSS fundamentals
-
-**Choose Tailwind CSS if**:
-- Building modern UIs quickly
-- Preferring utility classes
-- Needing responsive design
-
-**Choose Sass/SCSS if**:
-- Working on large projects
-- Needing variables and mixins
-- Wanting better organization
-
-**Choose Styled Components if**:
-- Wanting component-scoped styles
-- Needing dynamic styling
-- Preferring CSS-in-JS
-
-**Choose JavaScript Styling if**:
-- Needing dynamic styles
-- Preferring JavaScript
-- Building component libraries
-
-**Choose Material-UI if**:
-- Wanting pre-built components
-- Needing accessibility
-- Preferring Material Design
-
-## Import Syntax
-
-All styling approaches use the `cl import` syntax for client-side imports:
-
-### CSS Files
-
-```jac
-# Pure CSS
-cl import ".styles.css";
-
-# Sass/SCSS
-cl import ".styles.scss";
-```
-
-### JavaScript Modules
-
-```jac
-# Default export
-cl import from .styles { default as styles }
-
-# Named exports
-cl import from .styled { Container, Card, Button }
-```
-
-### External Packages
-
-```jac
-# Styled Components
-cl import from "styled-components" { default as styled }
-
-# Material-UI
-cl import from "@mui/material/Button" { default as Button }
-cl import from "@mui/icons-material/Add" { default as AddIcon }
-```
-
-## Running Examples
-
-Each example is a complete, runnable project:
-
-```bash
-# Navigate to example directory
-cd jac_client/examples/css-styling/<example-name>
-
-# Install dependencies
-npm install
-
-# Run the application
-jac serve app.jac
-```
-
-
-## Best Practices
-
-### General Styling
-
-1. **Consistency**: Choose one approach per project
-2. **Performance**: Consider bundle size and runtime cost
-3. **Maintainability**: Keep styles organized and documented
-4. **Accessibility**: Ensure styles don't break accessibility
-5. **Responsive**: Design mobile-first
-
-### CSS Files
-
-1. **Organization**: Use comments to separate sections
-2. **Naming**: Use semantic class names (BEM, etc.)
-3. **Specificity**: Avoid overly specific selectors
-4. **Variables**: Use CSS custom properties for theming
-
-### CSS-in-JS
-
-1. **Scoping**: Leverage component-scoped styles
-2. **Performance**: Memoize expensive styled components
-3. **Theming**: Use theme providers for global styles
-4. **Props**: Keep prop-based styling simple
-
-### Component Libraries
-
-1. **Customization**: Use theme system for brand colors
-2. **Variants**: Prefer built-in variants when possible
-3. **Composition**: Compose components for flexibility
-4. **Accessibility**: Use accessible components by default
-
-## Resources
-
-- [Import System Documentation](../imports.md)
-- [Routing Documentation](../routing.md)
-- [Lifecycle Hooks](../lifecycle-hooks.md)
-- [Complete Example Guide](../guide-example/intro.md)
-
->  **Upcoming Styling Patterns**
-
-<div style="border: 1.5px solid #ffa500; background: #fff4cc; color: #333; padding: 1.2em 1.4em; border-radius: 8px; margin: 2em 0;">
-
-The following styling approaches are <strong>planned</strong> for documentation in Jac, but full code examples are coming soon:
-
----
-
-<strong>CSS-in-JS Libraries</strong>
-<ul>
-  <li><strong>Emotion</strong> — CSS-in-JS with similar API to styled-components</li>
-  <li><strong>Styled JSX</strong> — CSS-in-JS (Next.js style)</li>
-</ul>
-
-<strong>CSS Modules</strong>
-<ul>
-  <li><strong>CSS Modules</strong> — Scoped CSS with local class names</li>
-</ul>
-
-<strong>Modern CSS</strong>
-<ul>
-  <li><strong>CSS Variables (Custom Properties)</strong> — Native CSS variables for theming</li>
-  <li><strong>PostCSS</strong> — CSS transformations and plugins</li>
-</ul>
-
-<strong>Component Libraries</strong>
-<ul>
-  <li><strong>Chakra UI</strong> — Modular and accessible component library</li>
-  <li><strong>Ant Design</strong> — Enterprise-focused component library</li>
-  <li><strong>Radix UI</strong> — Unstyled, accessible primitives</li>
-  <li><strong>Mantine</strong> — Full-featured React components</li>
-</ul>
-
-<strong>CSS Frameworks</strong>
-<ul>
-  <li><strong>Bulma</strong> — Flexbox-based CSS framework</li>
-  <li><strong>Foundation</strong> — Responsive framework</li>
-  <li><strong>Semantic UI</strong> — Natural language class names</li>
-</ul>
-
-<strong>Zero-runtime CSS-in-JS</strong>
-<ul>
-  <li><strong>Vanilla Extract</strong> — Type-safe, zero-runtime CSS-in-JS</li>
-  <li><strong>Linaria</strong> — Zero-runtime CSS-in-JS</li>
-  <li><strong>Stitches</strong> — CSS-in-JS with variants API</li>
-</ul>
-
-<strong>Utility-first</strong>
-<ul>
-  <li><strong>UnoCSS</strong> — On-demand atomic CSS engine</li>
-</ul>
-
-<em>Examples for these patterns will be added soon.</em>
-</div>
-
-## Contributing
-
-When adding new styling examples:
-
-1. Create a new directory in `examples/css-styling/`
-2. Include a complete working counter app
-3. Add a README.md with setup instructions
-4. Create a documentation file in `docs/styling/`
-5. Update this intro.md file
-6. Follow the existing example structure

jac_client/docs/styling/js-styling.md

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