lumina-sass 2.0.2 → 2.1.0

package/README.md

@@ -22,42 +22,34 @@ This will add `lumina-sass` to your `package.json` file. Do not install the libr
 
 You can use the library directly in your Sass files using standard `@use` syntax.
 
-#### 1. Import Everything
-To use all mixins and utility classes, import the main library file:
+#### 1. Import Flexbox Utilities (the only public export)
+
+You can import the flexbox utilities directly:
 
 ```sass
 // In your style.sass or style.scss file:
-@use 'lumina-sass' as *
+@use 'lumina-sass/flexbox' as flex;
 
-// Now all mixins and classes are available:
-.container
-  +flex-center
+// Now all flexbox mixins and classes are available:
+.container {
+  @include flex.flexbox-generator('flex');
+}
 ```
 
+
 #### 2. Import Specific Modules
-If you only need certain parts, you can import them individually:
 
-```sass
-@use 'lumina-sass/color' as *
-@use 'lumina-sass/mixins' as mix
-@use 'lumina-sass/utils' as utils
-
-// Example usage:
-.social-button
-  background-color: $discord-blue
-// $youtube-red-hover now uses rgb(120, 6, 6)
-.container
-  @include mix.flex-center // Using mixins
-```
+ > The package now exports the `flexbox` sub‑path and other public sub‑paths (`color`, `mix`). Other internal modules (`utils`, `map`, …) remain private.
+
 
 ### Module Breakdown
 
 | Module | Description |
 | :--- | :--- |
-| `lumina-sass/color` | Color variables (Brands, Tech, UI States). |
-| `lumina-sass/mixins` | General utility mixins (Typography, Media Queries, Buttons). |
-| `lumina-sass/utils` | Flexbox utilities and CSS classes. |
-| `lumina-sass/map` | Configuration maps (Breakpoints, icons, flexbox). |
+| `lumina-sass/flexbox` | Flexbox utilities and CSS classes. |
+| `lumina-sass/color`   | Color variables and palettes. |
+| `lumina-sass/mix`     | General mixins (layout, typography, media). |
+
 
 ### Utility Classes
 
@@ -66,21 +58,18 @@ If you prefer to use CSS classes directly in your HTML (like `.flex-center`), pl
 ### Semantic Media Queries
 For common media queries, you can use these simple helper mixins to make your code more readable.
 
-```scss
-.my-component {
+```sass
+.my-component
   // Base styles
-  background: white;
+  background: white
 
   // Applies styles for medium screens and smaller
-  @include on-breakpoint(md) {
-    font-size: 0.9rem;
-  }
+  @include on-breakpoint(md)
+    font-size: 0.9rem
 
   // Applies styles when the user prefers dark mode
-  @include on-dark-mode {
-    background: black;
-  }
-}
+  @include on-dark-mode
+    background: black
 ```
 
 Available helpers:
@@ -117,6 +106,136 @@ To learn how to contribute or understand the release process, please see:
 - [**Development Guide**](docs/developer/development.md) - Project structure and setup rules.
 - [**Releasing & Publishing**](docs/developer/releasing.md) - Details on the release process.
 
+---
+
+# AI Operations Guide for **lumina-sass**
+
+> This document is intended for the Antigravity AI (or any other automated assistant) that contributes to the `lumina-sass` project. It consolidates the repository‑specific conventions, tooling, and policies that enable the AI to work safely, efficiently, and in compliance with the user’s personal rules.
+
+---
+
+## 1️⃣ Project Overview
+- **Name:** `lumina-sass`
+- **Purpose:** Provides design tokens, mixins, and flexbox utilities for Sass‑based web projects.
+- **Primary public entry point:** `lumina-sass/flexbox` (the only sub‑path exported in `package.json`).
+- **Main files:**
+  - `src/_index.sass` – default entry (re‑exports flexbox).
+  - `src/flexbox/_index.sass` – collection of flexbox mixins and utility classes.
+  - `README.md` – user‑facing documentation (kept up‑to‑date with export changes).
+
+---
+
+## 2️⃣ Development Environment (User‑defined rules)
+- **Node.js version:** Use the latest **Stable LTS** (v24.x) via `fnm`.
+  ```bash
+  fnm use lts   # activates the stable LTS version
+  ```
+- **Package manager:** `npm` (default for this repo).
+- **GPG signing:** All commits must be **GPG‑signed** (`git commit -S`). The AI should stage changes and let the user provide the pass‑phrase; never use `--no-gpg-sign`.
+- **Conventional Commits:** Follow the `type: description.` format, ending with a period. Emphasise *why* a change is made.
+- **Python tools:** When needed, create a virtual environment with `python -m venv .venv` (not required for this repo, but noted for future scripts).
+
+---
+
+## 3️⃣ Repository Layout (important paths)
+```
+lumina-sass/
+├─ src/                     # Sass source files
+│  ├─ _index.sass          # Default entry point (re‑exports flexbox)
+│  ├─ flexbox/             # Public module – only exported sub‑path
+│  │   ├─ _index.sass
+│  │   └─ …
+│  └─ (other internal directories: color/, mix/, utils/, map/)
+├─ dist/                    # Build artefacts (generated by `npm run build`)
+├─ docs/                    # Additional documentation
+│  └─ ai_guide.md          # **This file** – AI reference guide
+├─ README.md                # Consumer‑facing docs – kept in sync with exports
+├─ package.json
+└─ ...
+```
+
+---
+
+## 4️⃣ Core Tasks for the AI
+| Task | How the AI should perform it | Important notes |
+|------|-----------------------------|----------------|
+| **Edit files** | Use `replace_file_content` for a single contiguous block or `multi_replace_file_content` for multiple non‑adjacent edits. Never overwrite a whole file with `write_to_file` unless explicitly creating a new artifact. | Preserve existing comments and docstrings. |
+| **Stage changes** | `git add <file>` after editing. |
+| **Commit** | `git commit -S -m "<Conventional Commit>"`. The AI must describe the command before execution and ensure GPG signing is enabled. |
+| **Run builds** | `npm run build` (or `npm run dev` if a dev server is needed). Ensure the LTS Node version is active via `fnm`. |
+| **Verify exports** | Test that `import 'lumina-sass/flexbox'` works and that importing any other sub‑path fails with `Package subpath ... is not defined`. |
+| **Update documentation** | Keep `README.md` and any internal docs in sync with code changes, especially the `exports` field. |
+| **Memory synchronization** | Whenever the AI updates a file that is part of the user’s memory (e.g., global or project‑specific memory files), also copy the changes to `/home/kristoffer/Gdrive/Administration/Gemini-Memory-Backup/`. |
+
+---
+
+## 5️⃣ Export Management (Key AI Responsibility)
+- The `package.json` **exports** block defines the public API. The AI must:
+  1. Ensure only the intended sub‑paths are listed (currently `.` and `./flexbox`).
+  2. Update the **module breakdown table** in `README.md` to reflect the exported modules.
+  3. When new public modules are added, remember to:
+     - Add them to `exports`.
+     - Update the README table.
+     - Adjust the documentation guide.
+- Any attempt to expose internal modules (`color`, `mixins`, `utils`, `map`) must be rejected unless the user explicitly asks for it.
+
+---
+
+## 6️⃣ Testing & Verification Workflow
+1. **Local import test**
+   ```bash
+   node -e "import 'lumina-sass/flexbox'"   # should succeed
+   node -e "import 'lumina-sass/utils'"     # should fail
+   ```
+2. **Build**
+   ```bash
+   npm run build
+   ```
+3. **Run demo** (optional) to ensure compiled CSS works:
+   ```bash
+   npm run serve   # serves the demo folder via http‑server
+   ```
+4. **Commit verification**: After committing, run `git log --show-signature -1` to confirm the GPG signature is present.
+
+---
+
+## 7️⃣ Contribution Guidelines (for AI and humans)
+- **Pull‑request workflow:**
+  1. Create a feature branch.
+  2. Make the required edits.
+  3. Run the verification steps above.
+  4. Commit with a signed Conventional Commit.
+  5. Push and open a PR.
+- **Documentation:** Every public change must be reflected in `README.md` and, if relevant, in the AI guide.
+- **Linting / Formatting:** Keep the repo formatted according to the existing style (Sass indentation, no trailing spaces).
+
+---
+
+## 8️⃣ Quick Reference Commands (AI‑friendly)
+| Purpose | Command |
+|---------|---------|
+| Activate LTS Node | `fnm use lts` |
+| Install dependencies | `npm install` |
+| Build the package | `npm run build` |
+| Serve demo (optional) | `npm run serve` |
+| Stage a file | `git add <path>` |
+| Signed commit (example) | `git commit -S -m "feat: description of change."` |
+| Verify signature | `git log --show-signature -1` |
+| Test valid import | `node -e "import 'lumina-sass/flexbox'"` |
+| Test invalid import | `node -e "import 'lumina-sass/utils'"` |
+
+---
+
+## 9️⃣ Contact & Further Help
+- For any ambiguity, the AI should ask the user via a clarifying question before proceeding.
+- The AI must always **present a plan before executing** any non‑trivial change (as per user‑global rules).
+
+---
+
+*This guide is version‑controlled along with the rest of the repository, ensuring the AI always has an up‑to‑date reference when working on `lumina-sass`.*
+
+
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lumina-sass",
-  "version": "2.0.2",
-  "description": "Lumina Sass design tokens and mixins",
+  "version": "2.1.0",
+  "description": "Lumina Sass design tokens, mixins and public sub-modules (flexbox, color, mix).",
   "main": "src/_index.sass",
   "sass": "src/_index.sass",
   "exports": {
@@ -9,21 +9,17 @@
       "sass": "./src/_index.sass",
       "default": "./src/_index.sass"
     },
+    "./flexbox": {
+      "sass": "./src/flexbox/_index.sass",
+      "default": "./src/flexbox/_index.sass"
+    },
     "./color": {
       "sass": "./src/color/_index.sass",
       "default": "./src/color/_index.sass"
     },
-    "./mixins": {
+    "./mix": {
       "sass": "./src/mix/_index.sass",
       "default": "./src/mix/_index.sass"
-    },
-    "./utils": {
-      "sass": "./src/utils/_flexbox.sass",
-      "default": "./src/utils/_flexbox.sass"
-    },
-    "./map": {
-      "sass": "./src/map/_index.sass",
-      "default": "./src/map/_index.sass"
     }
   },
   "repository": {

package/src/mix/_generators.sass

@@ -2,42 +2,93 @@
 @use '../map/icons' as icon-map
 @use '../map/tag-theme' as tag-map
 @use '../map/flexbox' as flexbox-mapping
-
+@use '../map/inputs' as inputs
+@use "sass:list" as list
 
 @mixin icon-generator($name: null, $color: null, $font-family: 'bootstrap-icons')
-    @if icon-map.$icons
-        @if $name == null
-            @each $category, $maps in icon-map.$icons
-                @each $icon, $props in $maps
-                    .#{$icon}
-                        font-family: $font-family
-                        &:before
-                            content: map.get($props, icon)
-                        @if $color
-                            color: $color
-        @else
-            $found: false
-            @each $category, $maps in icon-map.$icons
-                @if map.has-key($maps, $name)
-                    $found: true
-                    $props: map.get($maps, $name)
-                    .#{$name}
-                        font-family: $font-family
-                        &:before
-                            content: map.get($props, icon)
-                        @if $color
-                            color: $color
-            
-            @if not $found
-                @warn 'Icon "#{$name}" not found in icon mapping.'
+  @if icon-map.$icons
+    @if $name == null
+      @each $category, $maps in icon-map.$icons
+        @each $icon, $props in $maps
+          .#{$icon}
+            font-family: $font-family
+            &::before
+              content: map.get($props, icon)
+            @if $color
+              color: $color
     @else
-        @error 'Icon mapping not found.'
+      $found: false
+      @each $category, $maps in icon-map.$icons
+        @if map.has-key($maps, $name)
+          $found: true
+          $props: map.get($maps, $name)
+          .#{$name}
+            font-family: $font-family
+            &::before
+              content: map.get($props, icon)
+            @if $color
+              color: $color
+      @if not $found
+        @warn "Icon #{$name} not found in icon mapping."
+  @else
+    @error "Icon mapping not found."
 
 @mixin flexbox-generator($name)
-    $props: map.get(flexbox-mapping.$flexbox, $name)
+  $props: map.get(flexbox-mapping.$flexbox, $name)
+  @if $props
+    @each $property, $value in $props
+      #{$property}: $value
+  @else
+    @error "#{$name} not found in flexbox mapping."
 
-    @if $props
-        @each $property, $value in $props
-            #{$property}: $value
-    @else
-        @error '"#{$name}" not found in flexbox mapping.'
+@mixin input-generator($name, $placeholder-color: null, $custom: ())
+  $props: map.merge(inputs.$default-input-props, $custom)
+
+  // Determine focus outline (custom overrides default)
+  $focus-outline: map.get($custom, 'focus-outline') or rgb(0, 120, 215)
+
+  @if $name == null
+    @each $cat, $list in inputs.$inputs
+      @each $input in $list
+        input[type="#{$input}"]
+          @each $prop, $val in $props
+            #{$prop}: $val
+          @if $placeholder-color != null
+            &::placeholder
+              color: $placeholder-color
+          &:focus
+            outline: $focus-outline
+  @else
+    $category: null
+    @each $cat, $list in inputs.$inputs
+      @if list.index($list, $name)
+        $category: $cat
+  
+    @if $category == null
+      @warn "Input '#{$name}' not found in inputs map. Check inputs/_inputs.sass for valid names."
+  
+    input[type="#{$name}"]
+      @each $prop, $val in $props
+        #{$prop}: $val
+      @if $placeholder-color != null
+        &::placeholder
+          color: $placeholder-color
+    
+      &:focus
+        outline: $focus-outline
+
+
+  // Range track styling
+  &::-webkit-slider-runnable-track
+    height: 0.4rem
+    background: #ddd
+    border-radius: 0.2rem
+
+  // Range thumb styling
+  &::-webkit-slider-thumb
+    -webkit-appearance: none
+    width: 1rem
+    height: 1rem
+    background: #0078d7
+    border-radius: 50%
+    margin-top: -0.3rem

package/src/mix/_media.sass

@@ -53,17 +53,42 @@
   @else
     @error "Invalid orientation `#{$orientation}` – use portrait or landscape."
 
-/* Figure and image helper – unchanged */
-@mixin figure-and-image($object-fit: cover, $size: null, $style: null)
+@mixin figure($object-fit: cover, $size: null, $style: italic, $width: 16, $length: 9, $position: null, $percentage: null)
   figure
-    picture, img
+    // Portrait video – forced 9:16 ratio
+    video.portrait-media
+      max-inline-size: 20em !important
+      @include mix.aspect-ratio($width: 9, $length: 16)
+
+    // Landscape video – default ratio
+    video.landscape-media
+      object-position: center 35%
+      @include mix.aspect-ratio()
+
+    // Image and picture handling
+    picture,
+    img
       inline-size: 100%
       object-fit: $object-fit
+      @include mix.aspect-ratio($width, $length)
+      @if $position != null or $percentage != null
+        object-position: $position $percentage
 
+    // Nested <picture><img> – duplicate settings for readability
     picture
       img
         inline-size: 100%
         object-fit: $object-fit
+        @include mix.aspect-ratio($width, $length)
+        @if $position != null or $percentage != null
+          object-position: $position $percentage
+
+      // Figcaption styling if size provided
       figcaption
-        @if $size != null and $style != null
           @include typo.font($size, $style)
+
+@mixin aspect-ratio($width: 16, $length: 9)
+    aspect-ratio: calc($width / $length)/ $length
+
+    @include aspect-ratio(9, 16)
+    aspect-ratio: calc($width / $length)/ $length

package/src/mix/_typography.sass

@@ -1,34 +1,45 @@
-@use 'sass:list'
-
-
-@mixin text-wrap-safe()
-    p, h1, h2, h3, h4, h5, h6, figcaption, a, li
-        hyphens: auto
-        min-inline-size: 0
-        word-wrap: anywhere
-        white-space: pre-wrap
-        overflow-wrap: anywhere
-
-@mixin font-style($font, $family: null)
-    $sans-serif: ('Roboto', 'Work Sans', 'Nunito')
-
-    @if list.index($sans-serif, $font)
-        $family: sans-serif
-
-    font-family: $font, $family
-
-@mixin font($size: null, $weight: null, $font: null, $family: null, $style: null)
-    @if $font != null
-        @include font-style($font, $family)
-    @else if $family != null
-        font-family: $family
-
-    @if $size != null
-        font-size: $size
-
-    @if $weight != null
-        font-weight: $weight
-
-    @if $style != null
-        font-style: $style
 
+@use 'sass:map'
+@use 'sass:list'
+@use '../map/fonts' as fonts
+
+@mixin text-wrap-safe($inline: 0)
+  p, h1, h2, h3, h4, h5, h6, figcaption, a, li
+    hyphens: auto
+    word-wrap: anywhere
+    white-space: pre-wrap
+    overflow-wrap: anywhere
+    min-inline-size: $inline
+
+@mixin font-style($font, $family: null, $line-height: null, $variant: null)
+  $detected-family: font-family-of($font)
+  @if $detected-family != null
+    $family: $detected-family
+  @if $line-height != null
+    line-height: $line-height
+  @if $variant != null
+    font-variant: $variant
+  // Always include a fallback family.
+  font-family: $font, $family
+
+@mixin font( $font: null, $size: 1rem, $family: null, $style: normal, $weight: normal)
+  @if $font != null
+    @include font-style($font, $family)
+
+  @else if $family != null
+    font-family: $family
+
+  @if $size != null
+    font-size: $size
+
+  @if $weight != null
+    font-weight: $weight
+
+  @if $style != null
+    font-style: $style
+
+// Helper: return the generic family for a given font name using the fonts map.
+@function font-family-of($font)
+  @if map.has-key(fonts.$font-family, $font)
+    @return map.get(fonts.$font-family, $font)
+  @return null