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

jac_client/docs/styling/pure-css.md

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

jac_client/docs/styling/sass.md

@@ -0,0 +1,403 @@
+# Sass/SCSS
+
+CSS preprocessor with variables, nesting, mixins, and functions for Jac applications.
+
+## Overview
+
+Sass (Syntactically Awesome Style Sheets) extends CSS with powerful features like variables, nesting, mixins, and functions. This approach is perfect for:
+- Large projects with shared styles
+- DRY (Don't Repeat Yourself) principles
+- Complex styling logic
+- Maintainable CSS architecture
+
+## Example
+
+See the complete working example: [`examples/css-styling/sass-example/`](../../examples/css-styling/sass-example/)
+
+## Quick Start
+
+### 1. Install Sass
+
+Add to `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "sass": "^1.77.8"
+  }
+}
+```
+
+### 2. Create SCSS File
+
+Create `styles.scss`:
+
+```scss
+$primary-color: #007bff;
+$secondary-color: #6c757d;
+
+.button {
+    background-color: $primary-color;
+    color: white;
+    padding: 0.75rem 1.5rem;
+    border-radius: 0.5rem;
+
+    &:hover {
+        background-color: darken($primary-color, 10%);
+    }
+}
+```
+
+### 3. Import in Jac
+
+```jac
+# Pages
+cl import from react {useState, useEffect}
+cl import ".styles.scss";
+
+cl {
+    def app() -> any {
+        return <div className="container">
+            <button className="button">Click Me</button>
+        </div>;
+    }
+}
+```
+
+Vite automatically compiles SCSS to CSS during the build process.
+
+## Sass Features
+
+### Variables
+
+Define reusable values:
+
+```scss
+$primary-gradient-start: #dbeafe;
+$primary-gradient-end: #e0e7ff;
+$white: #ffffff;
+$gray-800: #1f2937;
+$spacing-unit: 1rem;
+```
+
+### Nesting
+
+Nest selectors for better organization:
+
+```scss
+.button {
+    padding: 0.75rem 1.5rem;
+    border-radius: 0.5rem;
+
+    &:hover {
+        transform: scale(1.05);
+    }
+
+    &:active {
+        transform: scale(0.95);
+    }
+
+    &Decrement {
+        background-color: $red-500;
+    }
+
+    &Reset {
+        background-color: $gray-500;
+    }
+}
+```
+
+### Mixins
+
+Create reusable style blocks:
+
+```scss
+@mixin flex-center {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+@mixin button-base {
+    color: $white;
+    font-weight: bold;
+    padding: 0.75rem 1.5rem;
+    border-radius: 0.5rem;
+    border: none;
+    cursor: pointer;
+
+    &:hover {
+        transform: scale(1.05);
+    }
+}
+
+.container {
+    @include flex-center;
+    min-height: 100vh;
+}
+
+.button {
+    @include button-base;
+    background-color: $primary-color;
+}
+```
+
+### Functions
+
+Use built-in and custom functions:
+
+```scss
+.button {
+    background-color: $red-500;
+
+    &:hover {
+        background-color: darken($red-500, 10%);
+    }
+}
+
+.card {
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+
+    &:hover {
+        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
+    }
+}
+```
+
+### Partials and Imports
+
+Organize styles across multiple files:
+
+```scss
+// _variables.scss
+$primary: #007bff;
+$secondary: #6c757d;
+
+// _mixins.scss
+@mixin flex-center {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+// styles.scss
+@import 'variables';
+@import 'mixins';
+
+.container {
+    @include flex-center;
+    background-color: $primary;
+}
+```
+
+## Best Practices
+
+### 1. Use Variables
+
+Define colors, spacing, and other values as variables:
+
+```scss
+$colors: (
+    primary: #007bff,
+    secondary: #6c757d,
+    success: #28a745,
+    danger: #dc3545,
+);
+
+.button {
+    background-color: map-get($colors, primary);
+}
+```
+
+### 2. Create Mixins
+
+Extract common patterns into mixins:
+
+```scss
+@mixin respond-to($breakpoint) {
+    @media (min-width: $breakpoint) {
+        @content;
+    }
+}
+
+.container {
+    padding: 1rem;
+
+    @include respond-to(768px) {
+        padding: 2rem;
+    }
+}
+```
+
+### 3. Organize with Partials
+
+Split large files into smaller modules:
+
+```
+styles/
+├── _variables.scss
+├── _mixins.scss
+├── _components.scss
+└── main.scss
+```
+
+### 4. Use Nesting Wisely
+
+Don't nest too deeply (max 3-4 levels):
+
+```scss
+// Good
+.card {
+    padding: 1rem;
+
+    &__header {
+        font-weight: bold;
+    }
+}
+
+// Avoid
+.card {
+    .header {
+        .title {
+            .text {
+                // Too deep!
+            }
+        }
+    }
+}
+```
+
+### 5. Leverage Functions
+
+Use Sass functions for calculations:
+
+```scss
+.container {
+    width: percentage(2/3);
+    margin: rem(16px);
+}
+```
+
+## Common Patterns
+
+### BEM with Nesting
+
+```scss
+.card {
+    padding: 1rem;
+
+    &__header {
+        padding: 1rem;
+        border-bottom: 1px solid #ddd;
+    }
+
+    &__body {
+        padding: 1.5rem;
+    }
+
+    &--highlighted {
+        border: 2px solid $primary;
+    }
+}
+```
+
+### Color Management
+
+```scss
+$colors: (
+    primary: #007bff,
+    secondary: #6c757d,
+    success: #28a745,
+    danger: #dc3545,
+);
+
+@function color($name) {
+    @return map-get($colors, $name);
+}
+
+.button {
+    background-color: color(primary);
+}
+```
+
+### Responsive Mixins
+
+```scss
+@mixin respond-to($breakpoint) {
+    @if $breakpoint == mobile {
+        @media (max-width: 767px) { @content; }
+    }
+    @else if $breakpoint == tablet {
+        @media (min-width: 768px) { @content; }
+    }
+    @else if $breakpoint == desktop {
+        @media (min-width: 1024px) { @content; }
+    }
+}
+
+.container {
+    padding: 1rem;
+
+    @include respond-to(tablet) {
+        padding: 2rem;
+    }
+}
+```
+
+## Advantages
+
+-  **Variables** for maintainable theming
+-  **Nesting** for better organization
+-  **Mixins** for reusable code
+-  **Functions** for dynamic values
+-  **Partials** for modular CSS
+-  **Compiles to standard CSS**
+-  **Large ecosystem** and community
+
+## Limitations
+
+-  **Requires build step**
+-  **Learning curve** for Sass syntax
+-  **Can get complex** with deep nesting
+-  **Additional dependency**
+-  **Debugging** can be harder (source maps help)
+
+## When to Use
+
+Choose Sass/SCSS when:
+
+- You're working on large projects
+- You need variables and mixins
+- You want better CSS organization
+- You prefer preprocessing over runtime CSS
+- You need complex styling logic
+- You want to share styles across components
+
+## Import Syntax
+
+SCSS files are imported using the `cl import` syntax:
+
+```jac
+cl import ".styles.scss";
+```
+
+This compiles to:
+
+```javascript
+import "./styles.scss";
+```
+
+Vite automatically processes SCSS imports and compiles them to CSS.
+
+## Next Steps
+
+- Explore [Sass Documentation](https://sass-lang.com/documentation)
+- Check out [Less](./less.md) for similar preprocessing (coming soon)
+- Learn about [PostCSS](./postcss.md) for CSS transformations (coming soon)
+- See [Pure CSS](./pure-css.md) for traditional CSS approach
+
+## Resources
+
+- [Sass Documentation](https://sass-lang.com/documentation)
+- [Sass Guidelines](https://sass-guidelin.es/)
+- [Sass Playground](https://www.sassmeister.com/)