nk_jtb 0.20.0 → 0.22.0

package/.github/copilot-instructions.md

@@ -0,0 +1,71 @@
+# Copilot Instructions for JTB (Just the Basics)
+
+## Project Overview
+- **JTB** is a Sass-based utility framework focused on composable classes, minimal components, and predictable naming. It avoids runtime JavaScript and prioritizes build-time CSS generation.
+- The architecture centers on SCSS mixins for class generation, using configuration maps and builder/maker mixins.
+
+- This framework uses tailwind-like class, but is not tailwind.
+- Read the conventions in `docs/conventions.md` for naming patterns and class structures.
+
+## Key Files & Structure
+- `src/` — Main SCSS source. Organized by `base/`, `components/`, `forms/`, `functions/`, `maps_and_variables/`, `mixins/`, `utilities/`.
+- `build.scss` — Entry point for building the full framework.
+- `docs/` — Documentation, conventions, and architecture explanations.
+- `examples/` — Examples are provided in the documents not the examples/ folder.
+- `package.json` — Build/test/lint scripts and dependencies.
+
+## Before Responding
+- Always consider existing patterns in the codebase
+- Reference docs/ when explaining architecture
+- Don't give generic CSS advice—this is a framework with specific conventions
+
+For more details, see:
+- `docs/core-architecture.md`
+- `docs/conventions.md`
+- `docs/responsive-design.md`
+- `README.md`
+
+## Class Generation Patterns
+- **Builders**: Use configuration maps to generate sets of utility classes. Example:
+  ```scss
+  @include build-classes((margin: (prefix: 'm-', values: (1,2,3), unit: 'rem')));
+  // Generates: .m-1, .m-2, .m-3
+  ```
+- **Makers**: For single, precise classes. Example:
+  ```scss
+  @include make-single-property-class('display', 'hidden', 'none', $breakpoints: (md, lg), $states: (hover));
+  // Generates: .hidden, .md:hidden, .lg:hidden, .hover:hidden:hover
+  ```
+- **Responsive Prefixes**: `md:`, `on-md:`, `to-md:` control when styles apply. See `docs/responsive-design.md` for details.
+
+## Naming Conventions
+- Utility classes: `{breakpoint}:{property}-{variant/value}`
+  - Examples: `mxy`, `gap-lg`, `md:mxy-3`, `on-lg:hidden`
+- Properties use short prefixes: `m` (margin), `p` (padding), `bg` (background), `txt` (text)
+- Variants: Semantic keywords (`sm`, `lg`) or direct values (`1.5`, `0`)
+
+## Developer Workflows
+- **Build**: `npm run build` (uses Vite)
+- **Dev**: `npm run dev` (hot reload, watches SCSS)
+- **Watch**: `npm run watch` (watches build.scss)
+- **Lint**: `npm run lint` or `npm run lint:base` (uses stylelint)
+- **Playground**: `npm run play` (watches play.scss, opens files)
+- **Debug**: `npm run debug` (Vite debug mode)
+
+## Customization & Configuration
+- Override variables in `maps_and_variables/` before importing modules.
+- Import only needed modules for smaller builds.
+- Vite config for SCSS: see `docs/installation.md` for `additionalData` usage.
+
+## Integration Points
+- Minimal JS: Only for interactive components (see `public/docs/components/` and dependencies in `package.json`).
+- External: Uses Alpine.js for some components, Highlight.js and Marked for docs/examples.
+
+## Project-Specific Patterns
+- **No runtime CSS-in-JS.** All class generation is build-time via SCSS.
+- **Responsive system**: Three prefix types for breakpoints (`md:`, `on-md:`, `to-md:`).
+- **Spacing scale**: See `README.md` for px/rem mapping.
+- **Class name prediction**: See `docs/conventions.md` for structure and examples.
+
+---
+

package/.stylelintrc.json

@@ -1,16 +1,17 @@
-{
-    "extends": "stylelint-config-standard-scss",
-    "plugins": [
-        "stylelint-order"
-    ],
-    "ignoreFiles": [
-        "dist/**/*",
-        "**/*.min.css"
-    ],
-    "rules": {
-        "scss/comment-no-empty": null,
-        "order/properties-alphabetical-order": true,
-        "scss/dollar-variable-colon-space-after": "always",
-        "scss/dollar-variable-empty-line-before": null
-    }
+{
+    "extends": "stylelint-config-standard-scss",
+    "plugins": [
+        "stylelint-order"
+    ],
+    "ignoreFiles": [
+        "dist/**/*",
+        "**/*.min.css"
+    ],
+    "rules": {
+        "scss/comment-no-empty": null,
+        "order/properties-alphabetical-order": true,
+        "scss/dollar-variable-colon-space-after": "always",
+        "scss/dollar-variable-empty-line-before": null,
+        "hue-degree-notation": null
+    }
 }

package/dev.html

@@ -6,12 +6,12 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/svg+xml" href="/images/favicon.svg" />
     <title>DEV</title>
-    <script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
-    <!-- <script src="https://cdn.tailwindcss.com"></script> -->
+    <!-- order matters, make sure the plugin comes before alpine.js -->
+    <script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/collapse@3.x.x/dist/cdn.min.js"></script>
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
 </head>
 
-
-<body class="container py-5">
+<body class="container py-5 bg-gray-200">
 
     <script type="module" src="/main.js"></script>
 </body>

package/docs/animation.md

@@ -0,0 +1,131 @@
+# Animation Utilities
+
+<h2>Loading States</h2>
+<div class="grid md:cols-2 lg:cols-3 gap">
+    <!-- Simple Spinner -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Simple Spinner</h3>
+        <div class="animate-spin rounded-full wh-4 bdr-4 bdr-gray-200 bdr-t-blue-600"></div>
+        <p class="txt-sm txt-gray-600">Sending message...</p>
+    </div>
+    <!-- Ring Spinner (Thicker) -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Ring Spinner</h3>
+        <div class="animate-spin rounded-full wh-4 bdr-8 bdr-gray-200 bdr-t-indigo-600"></div>
+        <p class="txt-sm txt-gray-600">Processing...</p>
+    </div>
+    <!-- Dual Ring -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Dual Ring</h3>
+        <div class="relative">
+            <div class="animate-spin rounded-full wh-4 bdr-4 bdr-gray-200 bdr-t-purple-600"></div>
+            <div class="absolute top-05 left-05 animate-spin rounded-full wh-3 bdr-4 bdr-gray-100 bdr-t-purple-400" style="animation-direction: reverse;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Loading...</p>
+    </div>
+    <!-- Bouncing Dots -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Bouncing Dots</h3>
+        <div class="flex space-x-05">
+            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0s;"></div>
+            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.1s;"></div>
+            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.2s;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Submitting...</p>
+    </div>
+    <!-- Pulsing Circle -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Pulse</h3>
+        <div class="wh-4 bg-teal-500 rounded-full animate-pulse"></div>
+        <p class="txt-sm txt-gray-600">Please wait...</p>
+    </div>
+    <!-- Pulse Rings -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Pulse Rings</h3>
+        <div class="relative">
+            <div class="wh-4 bg-emerald-500 rounded-full"></div>
+            <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring"></div>
+            <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring" style="animation-delay: 0.5s;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Processing...</p>
+    </div>
+    <!-- SVG Spinner -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">SVG Spinner</h3>
+        <svg class="animate-spin wh-4 txt-orange-600" fill="none" viewBox="0 0 24 24">
+            <circle class="opacity-30" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+            <path class="opacity-80" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+        </svg>
+        <p class="txt-sm txt-gray-600">Uploading...</p>
+    </div>
+    <!-- Progress Bar -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Progress Bar</h3>
+        <div class="w-full h-2 bg-gray-200 rounded-full overflow-hidden">
+            <div class="h-full bg-blue-600 rounded-full animate-pulse" style="width: 70%;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">70% Complete</p>
+    </div>
+    <!-- Sequential Dots -->
+    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
+        <h3 class="bx-title txt-1 font-semibold">Sequential Dots</h3>
+        <div class="flex space-x-05 items-center h-2">
+            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0s;"></div>
+            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0.3s;"></div>
+            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0.6s;"></div>
+        </div>
+        <p class="txt-sm txt-gray-600">Loading...</p>
+    </div>
+</div>
+
+## Loading Animations
+
+<div class="loader-container bx dark">
+    <div class="spinner"></div>
+    <div class="loading-text">Loading<span class="dots"></span></div>
+</div>
+
+<div class="loader-container bx dark">
+    <div class="loading-text">Loading<span class="dots"></span></div>
+</div>
+
+
+## SVG Spinners
+
+<div class="bx  flex va-c">
+    <svg class="wh-2 animate-spin" viewBox="0 0 200 200">
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-gray-400" stroke-width="12" />
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-gray-100" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
+    </svg>
+    <svg class="wh-3 animate-spin" viewBox="0 0 200 200">
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-red-300" stroke-width="12" />
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-blue-500" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
+    </svg>
+    <svg class="wh-4 animate-spin" viewBox="0 0 200 200">
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-yellow-300" stroke-width="12" />
+        <circle cx="100" cy="100" r="80" fill="none" class="stroke-green-500" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
+    </svg>
+</div>
+
+
+## Border Animations
+
+### Spinner
+
+```html +code +preview +collapse
+<div class="dark flex-centered gap bx">
+    <div class="spinner sm"></div>
+    <div class="spinner"></div>
+    <div class="spinner lg"></div>
+</div>
+```
+
+**Thick Spinners:**
+
+```html +code +preview +collapse
+<div class="dark flex-centered gap bx">
+    <div class="spinner sm thick"></div>
+    <div class="spinner thick "></div>
+    <div class="spinner lg thick"></div>
+</div>
+```

package/docs/api/architecture-naming.md

@@ -0,0 +1,79 @@
+# Mixin Architecture & Naming Conventions
+
+
+
+## Architecture Levels
+
+## The 4 Layers
+
+**Layer 1: Base**
+Foundation classes without breakpoints or states. Lowest priority in cascade.
+
+**Layer 2: Responsive**
+Media query variants that override base at different breakpoints (md:, lg:, etc).
+
+**Layer 3: State**
+Interaction state variants (hover:, focus:, active:) that override responsive.
+
+**Layer 4: Responsive + State**
+Combined breakpoint and state variants (md:hover:, lg:focus:, etc). Highest priority.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Based on the pattern, here's my recommendation:
+
+## Naming Convention: **class** vs **variant**
+
+- **`make-base-class()`** — Generates THE class (foundation, layer 1 only)
+- **`make-responsive-variant()`** — Generates variants OF that class (layer 2)
+- **`make-state-variant()`** — Generates variants OF that class (layer 3)
+- **`make-responsive-state-variant()`** — Generates variants OF that class (layer 4)
+
+And for position-based:
+- **`make-responsive-position-variant()`** — Responsive variants (layer 2)
+- **`make-state-position-variant()`** — State variants (layer 3)
+- **`make-responsive-state-position-variant()`** — Both (layer 4)
+
+
+
+## Data Flow
+
+```
+User Config (property map)
+        ↓
+build-classes-new (normalize config)
+        ↓
+build-base-layer (loop through values)
+        ↓
+make-base-class (generate CSS for one class)
+        ↓
+Final CSS Output
+```
+
+
+
+
+## Layer Order (Cascade Priority)
+
+1. **Base Layer** → Lowest priority, establishes defaults
+2. **Responsive Layer** → Overrides base at screen sizes
+3. **State Layer** → Interactive states (hover, focus)
+4. **Responsive+State Layer** → Highest priority, combined variants
+
+
+
+
+
+
+

package/docs/api/build-classes.md

@@ -0,0 +1,108 @@
+# build-classes()
+
+## Signature
+
+```scss +code
+@mixin build-classes(
+    $properties-map,
+    $responsive: false,
+    $with-state: false,
+    $debug: false
+)
+```
+
+## Parameters
+
+| Parameter         | Type    | Default | Description                                                                        |
+| ----------------- | ------- | ------- | ---------------------------------------------------------------------------------- |
+| `$properties-map` | Map     | —       | CSS property config with `prefix`, `values`, `unit`, `positions`, `omit-axis-keys` |
+| `$responsive`     | Boolean | `false` | Generate responsive variants (`md:`, `lg:`, etc.)                                  |
+| `$with-state`     | Boolean | `false` | Generate state variants (`:hover`, `:focus`, `:active`)                            |
+| `$debug`          | Boolean | `false` | Output debug info during compilation                                               |
+
+### `$properties-map` Configuration
+
+```scss +code
+$border-properties-map: (
+    border-width: (
+        prefix: 'bdr-',              // Class prefix (optional)
+        values: $border-width-map,   // Values to generate (required)
+        positions: $logical-position-map,  // For directional properties (t, b, l, r)
+        omit-axis-keys: (xy),        // Exclude x/y combinations
+        unit: 'px'                   // CSS unit
+    ),
+    border-color: (
+        prefix: 'bdr-',
+        values: $colors-map
+    )
+);
+
+@include build-classes($border-properties-map);
+```
+
+## Examples
+
+### Basic Usage
+
+```scss +code
+@include build-classes((
+    margin: (
+        prefix: 'm-',
+        values: (1, 2, 3, 4),
+        unit: 'rem'
+    )
+));
+// Output: .m-1, .m-2, .m-3, .m-4
+```
+
+### With Positions
+
+```scss +code
+@include build-classes((
+    margin: (
+        prefix: 'm-',
+        values: (1, 2, 3),
+        positions: (t: margin-top, b: margin-bottom, l: margin-left, r: margin-right),
+        unit: 'rem'
+    )
+));
+// Output: .m-1, .mt-1, .mb-1, .ml-1, .mr-1
+```
+
+### With Responsive Variants
+
+```scss +code
+@include build-classes((
+    display: (prefix: 'd-', values: (flex, grid, block, hidden))
+), $responsive: true);
+// Output: .d-flex, .md:d-flex, .lg:d-flex, etc.
+```
+
+### With State Variants
+
+```scss +code
+@include build-classes((
+    opacity: (prefix: 'op-', values: (0.5, 0.75, 1))
+), $with-state: true);
+// Output: .op-0.5, .op-0.5:hover, .op-0.5:focus, etc.
+```
+
+### Omitting Axis Combinations
+
+```scss +code
+@include build-classes((
+    border-width: (
+        prefix: 'bdr-',
+        values: (1, 2, 3),
+        positions: $logical-position-map,
+        omit-axis-keys: (xy),  // Exclude x/y combinations
+        unit: 'px'
+    )
+));
+```
+
+## Output Structure
+
+Pattern: `{breakpoint}:{property}-{value}{state}`
+
+Examples: `m-1`, `md:m-1`, `m-1:hover`, `md:m-1:hover`

package/docs/api/make-from-breakpoint.md

@@ -0,0 +1,52 @@
+# make-from-breakpoint()
+
+Generate classes that apply from a specific breakpoint upward.
+
+## Signature
+
+```scss +code
+@mixin make-from-breakpoint(
+    $properties,
+    $class,
+    $breakpoints
+)
+```
+
+## Parameters
+
+| Parameter           | Type    | Default | Description                                                    |
+| ------------------- | ------- | ------- | -------------------------------------------------------------- |
+| `$props`            | Map     | —       | CSS properties and values (e.g., `(display: flex, gap: 1rem)`) |
+| `$identifier`       | String  | —       | Class name identifier (e.g., `flex-row`, `grid-2col`)          |
+| `$breakpoints`      | List    | —       | Breakpoints (e.g., `(md, lg, xl)`)                             |
+| `$child-selector` | Boolean | `false` | Generate child selector variant                                |
+
+## Examples
+
+### Basic Usage
+
+```scss +code
+@include make-from-breakpoint(
+    (display: flex, flex-direction: row),
+    'flex-row',
+    (md, lg)
+);
+// Output: .md:flex-row, .lg:flex-row
+```
+
+### Single Breakpoint
+
+```scss +code
+@include make-from-breakpoint(
+    (display: grid, grid-template-columns: repeat(3, 1fr)),
+    'grid-3',
+    (lg)
+);
+// Output: .lg:grid-3
+```
+
+## Output Structure
+
+- `.{breakpoint}:{class-name}` — Applies from that breakpoint upward
+
+Use case: Responsive layouts that change at specific screen sizes.

package/docs/api/make-on-breakpoint.md

@@ -0,0 +1,52 @@
+# make-on-breakpoint()
+
+Generate classes that apply only on a specific breakpoint.
+
+## Signature
+
+```scss +code
+@mixin make-on-breakpoint(
+    $properties,
+    $class,
+    $breakpoints
+)
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `$props` | Map | — | CSS properties and values (e.g., `(display: grid)`) |
+| `$identifier` | String | — | Class name identifier (e.g., `tablet-grid`, `desktop-only`) |
+| `$breakpoints` | List | — | Breakpoints (e.g., `(md, lg, xl)`) |
+
+## Examples
+
+### Basic Usage
+
+```scss +code
+@include make-on-breakpoint(
+    (display: grid, grid-template-columns: repeat(2, 1fr)),
+    'grid-2',
+    (md)
+);
+// Output: .on-md:grid-2
+// Applies only on medium screens
+```
+
+### Multiple Breakpoints
+
+```scss +code
+@include make-on-breakpoint(
+    (font-size: 0.875rem),
+    'text-sm',
+    (sm, md)
+);
+// Output: .on-sm:text-sm, .on-md:text-sm
+```
+
+## Output Structure
+
+- `.on-{breakpoint}:{class-name}` — Applies only on that breakpoint
+
+Use case: Breakpoint-specific styling that doesn't cascade.

package/docs/api/make-position-based-class.md

@@ -0,0 +1,83 @@
+# make-position-based-class()
+
+Generate classes for directional properties (margin, padding, border, etc.) with position variants.
+
+## Signature
+
+```scss +code
+@mixin make-position-based-class(
+    $property,
+    $value,
+    $positions-map,
+    $identifier,
+    $variant,
+    $breakpoints,
+    $states: (),
+    $omit-axis-keys: (),
+    $child-selector: false
+)
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `$property` | String | — | CSS property name (e.g., `margin`, `padding`, `border-width`) |
+| `$value` | String | — | CSS value (e.g., `1rem`, `2px`) |
+| `$positions-map` | Map | — | Position keys to CSS properties (e.g., `(t: margin-top, b: margin-bottom)`) |
+| `$identifier` | String | — | Class name identifier (e.g., `m`, `p`, `bdr`) |
+| `$variant` | String | — | Variant suffix (e.g., `lg`, `sm`, `base`) |
+| `$breakpoints` | List | — | Breakpoints for responsive variants (e.g., `(md, lg)`) |
+| `$states` | List | `()` | Pseudo-classes for state variants (e.g., `(hover, focus)`) |
+| `$omit-axis-keys` | List | `()` | Exclude axis combinations (e.g., `(xy)`) |
+| `$child-selector` | Boolean | `false` | Generate child selector variant |
+
+## Examples
+
+### Basic Positional Classes
+
+```scss +code
+@include make-position-based-class(
+    'margin',
+    '1rem',
+    (t: margin-top, b: margin-bottom, l: margin-left, r: margin-right),
+    'm',
+    'base',
+    ()
+);
+// Output: .m-base, .m-t-base, .m-b-base, .m-l-base, .m-r-base
+```
+
+### With Variant Name
+
+```scss +code
+@include make-position-based-class(
+    'padding',
+    '1.5rem',
+    (t: padding-top, b: padding-bottom, x: (padding-left, padding-right)),
+    'p',
+    'lg',
+    ()
+);
+// Output: .p-lg, .p-t-lg, .p-b-lg, .p-x-lg
+```
+
+### With Responsive Variants
+
+```scss +code
+@include make-position-based-class(
+    'margin',
+    '2rem',
+    $logical-position-map,
+    'm',
+    'base',
+    (md, lg)
+);
+// Output: .m-base, .md:m-base, .lg:m-base, .m-t-base, .md:m-t-base, etc.
+```
+
+## Output Structure
+
+- All positions: `.{id}`, `.{id}-t`, `.{id}-b`, `.{id}-l`, `.{id}-r`, `.{id}-x`, `.{id}-y`
+- With variant: `.{id}-{variant}`, `.{id}-t-{variant}`, etc.
+- With breakpoints: `.{bp}:{id}`, `.{bp}:{id}-t`, etc.