@teseor/css 1.7.0 → 1.9.0

package/src/{03-layout → layout}/footer/footer.docs.json

@@ -97,6 +97,15 @@
         }
       ]
     },
+    {
+      "title": "Fixed",
+      "description": "Fixed to viewport bottom, always visible.",
+      "examples": [
+        {
+          "code": "<footer class=\"ui-footer ui-footer--fixed ui-footer--bordered\">\n  <div class=\"ui-footer__start\"><small>Brand</small></div>\n  <div class=\"ui-footer__end\"><small>v1.0.0</small></div>\n</footer>"
+        }
+      ]
+    },
     {
       "title": "Full Layout",
       "description": "Footer inside an app-shell with topbar and sidebar.",

package/src/{03-layout → layout}/footer/index.scss

@@ -1,9 +1,21 @@
+@use '../../config/tokens/variables' as t;
+// @component footer
+// @element footer
+
 @layer primitives {
   .footer {
+    --_space-2: var(--ui-space-2);
+    --_border-width-sm: var(--ui-border-width-sm);
+    --_hue-primary: var(--ui-hue-primary, #{t.$hue-primary});
+    // @desc Overall height
     --_height: var(--ui-footer-height, var(--ui-row-3));
+    // @desc Background color
     --_bg: var(--ui-footer-bg, var(--ui-color-bg));
+    // @desc Horizontal padding
     --_padding-inline: var(--ui-footer-padding-inline, var(--ui-space-3));
+    // @desc Border color
     --_border-color: var(--ui-footer-border-color, var(--ui-color-border));
+    // @desc Z-index stacking order
     --_z: var(--ui-footer-z, var(--ui-z-sticky));
 
     display: flex;
@@ -21,7 +33,7 @@
     display: flex;
     flex-shrink: 0;
     align-items: center;
-    gap: var(--ui-space-2);
+    gap: var(--_space-2);
   }
 
   .footer__center {
@@ -29,22 +41,24 @@
     flex: 1;
     align-items: center;
     justify-content: center;
-    gap: var(--ui-space-2);
+    gap: var(--_space-2);
   }
 
   .footer__end {
     display: flex;
     flex-shrink: 0;
     align-items: center;
-    gap: var(--ui-space-2);
+    gap: var(--_space-2);
   }
 
   // Position modifiers
+  // @modifier boolean sticky
   .footer--sticky {
     position: sticky;
     inset-block-end: 0;
   }
 
+  // @modifier boolean fixed
   .footer--fixed {
     position: fixed;
     inset-block-end: 0;
@@ -52,11 +66,13 @@
   }
 
   // Visual modifiers
+  // @modifier boolean bordered
   .footer--bordered {
-    box-shadow: inset 0 var(--ui-border-width-sm) 0 0 var(--_border-color);
+    box-shadow: inset 0 var(--_border-width-sm) 0 0 var(--_border-color);
   }
 
+  // @modifier boolean raised
   .footer--raised {
-    box-shadow: 0 calc(var(--ui-border-width-sm) * -1) 6px hsl(var(--ui-hue-primary, 220) 10% 20% / 0.08);
+    box-shadow: 0 calc(var(--_border-width-sm) * -1) 6px hsl(var(--_hue-primary) 10% 20% / 0.08);
   }
 }

package/src/layout/grid/grid.api.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "grid",
+  "element": "div",
+  "modifiers": {
+    "columns": {
+      "values": ["2", "3", "4", "auto"]
+    }
+  },
+  "cssVars": []
+}

package/src/layout/grid/grid.visual.spec.ts

@@ -0,0 +1,13 @@
+import { resolve } from 'node:path';
+import { expect, test } from '@playwright/test';
+import { saveForLostPixel, setupVisualTestFromDocs } from '../../testing';
+
+const DOCS_PATH = resolve(__dirname, 'grid.docs.json');
+
+test.describe('grid visual regression', () => {
+  test('all variations', async ({ page }) => {
+    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await saveForLostPixel(page, 'grid');
+    await expect(page.locator('body')).toHaveScreenshot('grid.visual.png');
+  });
+});

package/src/{03-layout → layout}/grid/index.scss

@@ -1,10 +1,15 @@
+// @component grid
+// @element div
+
 @layer primitives {
   .grid {
+    --_space-4: var(--ui-space-4);
     display: grid;
-    gap: var(--grid-gap, var(--ui-space-4));
+    gap: var(--grid-gap, var(--_space-4));
     grid-template-columns: repeat(var(--grid-cols, 1), minmax(0, 1fr));
   }
 
+  // @modifier columns
   .grid--2 { --grid-cols: 2; }
   .grid--3 { --grid-cols: 3; }
   .grid--4 { --grid-cols: 4; }

package/src/{03-layout → layout}/index.scss

@@ -2,16 +2,15 @@
 @forward './aspect-ratio';
 @forward './box';
 @forward './center';
-@forward './cluster';
+@forward './column';
 @forward './container';
 @forward './content';
-@forward './flex';
 @forward './footer';
 @forward './grid';
 @forward './main';
 @forward './nav-rail';
 @forward './page-header';
+@forward './row';
 @forward './sidebar';
 @forward './sidebar-nav';
-@forward './stack';
 @forward './topbar';

package/src/layout/main/index.scss

@@ -0,0 +1,24 @@
+// @component main
+// @element main
+
+@layer primitives {
+  .main {
+    --_unit: var(--ui-unit);
+    padding-block-start: var(--topbar-height, 0);
+    margin-inline-start: var(--sidebar-width, calc(var(--_unit) * 30));
+  }
+
+  // When sidebar is on the end
+  // @modifier boolean sidebar-end
+  .main--sidebar-end {
+    margin-inline-start: 0;
+    margin-inline-end: var(--sidebar-width, calc(var(--_unit) * 30));
+  }
+
+  // No sidebar
+  // @modifier boolean full
+  .main--full {
+    margin-inline-start: 0;
+    margin-inline-end: 0;
+  }
+}

package/src/{03-layout → layout}/main/main.api.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
   "name": "main",
   "element": "main",
   "modifiers": {

package/src/{03-layout → layout}/nav-rail/index.scss

@@ -1,9 +1,19 @@
+// @component nav-rail
+// @element nav
+
 @layer primitives {
   .nav-rail {
+    --_space-2: var(--ui-space-2);
+    --_border-width-sm: var(--ui-border-width-sm);
+    // @desc Overall width
     --_width: var(--ui-nav-rail-width, var(--ui-row-4));
+    // @desc Background color
     --_bg: var(--ui-nav-rail-bg, var(--ui-color-bg-subtle));
+    // @desc Border color
     --_border-color: var(--ui-nav-rail-border-color, var(--ui-color-border));
+    // @desc Gap between children
     --_gap: var(--ui-nav-rail-gap, var(--ui-space-1));
+    // @desc Z-index stacking order
     --_z: var(--ui-nav-rail-z, var(--ui-z-sticky));
 
     display: flex;
@@ -15,10 +25,10 @@
     z-index: var(--_z);
 
     inline-size: var(--_width);
-    padding-block: var(--ui-space-2);
+    padding-block: var(--_space-2);
 
     background: var(--_bg);
-    box-shadow: inset calc(var(--ui-border-width-sm) * -1) 0 0 0 var(--_border-color);
+    box-shadow: inset calc(var(--_border-width-sm) * -1) 0 0 0 var(--_border-color);
   }
 
   // Navigation items area
@@ -41,10 +51,11 @@
   }
 
   // Position on end side
+  // @modifier boolean end
   .nav-rail--end {
     inset-inline-start: auto;
     inset-inline-end: 0;
 
-    box-shadow: inset var(--ui-border-width-sm) 0 0 0 var(--_border-color);
+    box-shadow: inset var(--_border-width-sm) 0 0 0 var(--_border-color);
   }
 }

package/src/layout/nav-rail/nav-rail.api.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "nav-rail",
+  "element": "nav",
+  "modifiers": {
+    "end": {
+      "type": "boolean"
+    }
+  },
+  "elements": {
+    "items": {},
+    "actions": {}
+  },
+  "cssVars": [
+    {
+      "name": "--ui-nav-rail-width",
+      "default": "var(--ui-row-4)",
+      "description": "Overall width"
+    },
+    {
+      "name": "--ui-nav-rail-bg",
+      "default": "var(--ui-color-bg-subtle)",
+      "description": "Background color"
+    },
+    {
+      "name": "--ui-nav-rail-border-color",
+      "default": "var(--ui-color-border)",
+      "description": "Border color"
+    },
+    {
+      "name": "--ui-nav-rail-gap",
+      "default": "var(--ui-space-1)",
+      "description": "Gap between children"
+    },
+    {
+      "name": "--ui-nav-rail-z",
+      "default": "var(--ui-z-sticky)",
+      "description": "Z-index stacking order"
+    }
+  ]
+}

package/src/{03-layout → layout}/page-header/index.scss

@@ -1,8 +1,21 @@
+// @component page-header
+// @element header
+
 @layer primitives {
   .page-header {
+    --_body-line-height: var(--ui-body-line-height);
+    --_space-1: var(--ui-space-1);
+    --_space-2: var(--ui-space-2);
+    --_border-width-sm: var(--ui-border-width-sm);
+    --_z-sticky: var(--ui-z-sticky);
+    --_color-bg: var(--ui-color-bg);
+    // @desc Vertical padding
     --_padding-block: var(--ui-page-header-padding-block, var(--ui-space-3));
+    // @desc Horizontal padding
     --_padding-inline: var(--ui-page-header-padding-inline, 0);
+    // @desc Gap between children
     --_gap: var(--ui-page-header-gap, var(--ui-space-2));
+    // @desc Border color
     --_border-color: var(--ui-page-header-border-color, var(--ui-color-border));
 
     display: flex;
@@ -13,7 +26,7 @@
     padding-block: var(--_padding-block);
     padding-inline: var(--_padding-inline);
 
-    line-height: var(--ui-body-line-height);
+    line-height: var(--_body-line-height);
   }
 
   // Title area: stacks title + description vertically
@@ -21,7 +34,7 @@
     display: flex;
     flex: 1;
     flex-direction: column;
-    gap: var(--ui-space-1);
+    gap: var(--_space-1);
   }
 
   // Actions slot: right-aligned buttons/controls
@@ -29,7 +42,7 @@
     display: flex;
     flex-shrink: 0;
     align-items: center;
-    gap: var(--ui-space-2);
+    gap: var(--_space-2);
   }
 
   // Breadcrumb slot: full-width above title row
@@ -38,15 +51,17 @@
   }
 
   // Modifiers
+  // @modifier boolean bordered
   .page-header--bordered {
-    box-shadow: inset 0 calc(var(--ui-border-width-sm) * -1) 0 0 var(--_border-color);
+    box-shadow: inset 0 calc(var(--_border-width-sm) * -1) 0 0 var(--_border-color);
   }
 
+  // @modifier boolean sticky
   .page-header--sticky {
     position: sticky;
     inset-block-start: 0;
-    z-index: var(--ui-z-sticky);
+    z-index: var(--_z-sticky);
 
-    background: var(--ui-color-bg);
+    background: var(--_color-bg);
   }
 }

package/src/{03-layout → layout}/page-header/page-header.api.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
   "name": "page-header",
   "element": "header",
   "modifiers": {
@@ -17,19 +18,23 @@
   "cssVars": [
     {
       "name": "--ui-page-header-padding-block",
-      "default": "var(--ui-space-3)"
+      "default": "var(--ui-space-3)",
+      "description": "Vertical padding"
     },
     {
       "name": "--ui-page-header-padding-inline",
-      "default": "0"
+      "default": "0",
+      "description": "Horizontal padding"
     },
     {
       "name": "--ui-page-header-gap",
-      "default": "var(--ui-space-2)"
+      "default": "var(--ui-space-2)",
+      "description": "Gap between children"
     },
     {
       "name": "--ui-page-header-border-color",
-      "default": "var(--ui-color-border)"
+      "default": "var(--ui-color-border)",
+      "description": "Border color"
     }
   ]
 }

package/src/layout/row/index.scss

@@ -0,0 +1,26 @@
+// @component row
+// @element div
+
+@layer primitives {
+  .row {
+    --_space-2: var(--ui-space-2);
+    --_space-1: var(--ui-space-1);
+    --_space-4: var(--ui-space-4);
+    --_space-6: var(--ui-space-6);
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--row-gap, var(--_space-2));
+  }
+
+  // @modifier size
+  .row--xs { --row-gap: var(--_space-1); }
+  .row--sm { --row-gap: var(--_space-2); }
+  .row--md { --row-gap: var(--_space-4); }
+  .row--lg { --row-gap: var(--_space-6); }
+
+  .row--start { justify-content: flex-start; }
+  .row--center { justify-content: center; }
+  .row--end { justify-content: flex-end; }
+  .row--between { justify-content: space-between; }
+}

package/src/layout/row/row.api.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "row",
+  "element": "div",
+  "modifiers": {
+    "size": {
+      "values": ["xs", "sm", "md", "lg", "start", "center", "end", "between"]
+    }
+  },
+  "cssVars": []
+}

package/src/{03-layout/cluster/cluster.docs.json → layout/row/row.docs.json}

@@ -1,9 +1,9 @@
 {
-  "id": "cluster",
+  "id": "row",
   "type": "primitive",
-  "title": "Cluster",
+  "title": "Row",
   "description": "Horizontal layout with wrapping.",
-  "api": "cluster.api.json",
+  "api": "row.api.json",
   "sections": [
     {
       "title": "Basic",
@@ -12,7 +12,7 @@
           "items": [
             {
               "tag": "div",
-              "class": "ui-cluster ui-cluster--md",
+              "class": "ui-row ui-row--md",
               "children": [
                 {
                   "tag": "div",
@@ -59,7 +59,7 @@
           "items": [
             {
               "tag": "div",
-              "class": "ui-cluster ui-cluster--xs",
+              "class": "ui-row ui-row--xs",
               "children": [
                 {
                   "tag": "div",
@@ -93,7 +93,7 @@
           "items": [
             {
               "tag": "div",
-              "class": "ui-cluster ui-cluster--lg",
+              "class": "ui-row ui-row--lg",
               "children": [
                 {
                   "tag": "div",

package/src/{03-layout/cluster/cluster.visual.spec.ts → layout/row/row.visual.spec.ts}

@@ -2,14 +2,14 @@ import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
 import { saveForLostPixel, setupVisualTestFromDocs } from '../../testing';
 
-const DOCS_PATH = resolve(__dirname, 'cluster.docs.json');
+const DOCS_PATH = resolve(__dirname, 'row.docs.json');
 
-test.describe('cluster visual regression', () => {
+test.describe('row visual regression', () => {
   test('all variations', async ({ page }) => {
     await setupVisualTestFromDocs(page, DOCS_PATH);
-    // skip validateGridRhythm: cluster is a layout primitive that
+    // skip validateGridRhythm: row is a layout primitive that
     // controls gap/alignment, not child height
-    await saveForLostPixel(page, 'cluster');
-    await expect(page.locator('body')).toHaveScreenshot('cluster.visual.png');
+    await saveForLostPixel(page, 'row');
+    await expect(page.locator('body')).toHaveScreenshot('row.visual.png');
   });
 });

package/src/layout/sidebar/index.scss

@@ -0,0 +1,40 @@
+// @component sidebar
+// @element aside
+
+@layer primitives {
+  .sidebar {
+    --_z-sticky: var(--ui-z-sticky);
+    --_unit: var(--ui-unit);
+    --_color-bg-subtle: var(--ui-color-bg-subtle);
+    --_border-width-sm: var(--ui-border-width-sm);
+    --_color-border: var(--ui-color-border);
+    display: flex;
+    flex-direction: column;
+    position: fixed;
+    inset-block-start: var(--topbar-height, 0);
+    inset-inline-start: 0;
+    z-index: var(--_z-sticky);
+
+    block-size: calc(100vh - var(--topbar-height, 0px));
+    inline-size: var(--sidebar-width, calc(var(--_unit) * 30));
+    overflow-y: auto;
+
+    background: var(--_color-bg-subtle);
+    box-shadow: inset calc(var(--_border-width-sm) * -1) 0 0 0 var(--_color-border);
+  }
+
+  // Width modifiers
+  // @modifier size
+  .sidebar--sm { --sidebar-width: calc(var(--_unit) * 24); }
+  .sidebar--md { --sidebar-width: calc(var(--_unit) * 30); }
+  .sidebar--lg { --sidebar-width: calc(var(--_unit) * 40); }
+
+  // Position modifier - sidebar on end (right in LTR)
+  // @modifier boolean end
+  .sidebar--end {
+    inset-inline-start: auto;
+    inset-inline-end: 0;
+
+    box-shadow: inset var(--_border-width-sm) 0 0 0 var(--_color-border);
+  }
+}

package/src/{03-layout → layout}/sidebar/sidebar.api.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
   "name": "sidebar",
   "element": "aside",
   "modifiers": {

package/src/{03-layout → layout}/sidebar/sidebar.docs.json

@@ -19,11 +19,11 @@
       "description": "Three width options via size modifiers.",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             {
               "tag": "div",
-              "class": "ui-cluster",
+              "class": "ui-row",
               "children": [
                 { "tag": "code", "text": "--sm" },
                 { "tag": "span", "text": "192px (24 units)" }
@@ -31,7 +31,7 @@
             },
             {
               "tag": "div",
-              "class": "ui-cluster",
+              "class": "ui-row",
               "children": [
                 { "tag": "code", "text": "--md" },
                 { "tag": "span", "text": "240px (30 units, default)" }
@@ -39,13 +39,14 @@
             },
             {
               "tag": "div",
-              "class": "ui-cluster",
+              "class": "ui-row",
               "children": [
                 { "tag": "code", "text": "--lg" },
                 { "tag": "span", "text": "320px (40 units)" }
               ]
             }
-          ]
+          ],
+          "code": "<aside class=\"ui-sidebar ui-sidebar--sm\">192px</aside>\n<aside class=\"ui-sidebar ui-sidebar--md\">240px (default)</aside>\n<aside class=\"ui-sidebar ui-sidebar--lg\">320px</aside>"
         }
       ]
     },