@teseor/css 1.2.4 → 1.4.0

package/src/03-layout/content/content.visual.spec.ts

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

package/src/03-layout/content/index.scss

@@ -0,0 +1,25 @@
+@layer primitives {
+  .content {
+    --_padding-block: var(--ui-content-padding-block, var(--ui-space-4));
+    --_padding-inline: var(--ui-content-padding-inline, var(--ui-space-4));
+    --_gap: var(--ui-content-gap, var(--ui-space-3));
+
+    display: flex;
+    flex-direction: column;
+    gap: var(--_gap);
+
+    padding-block: var(--_padding-block);
+    padding-inline: var(--_padding-inline);
+  }
+
+  // Prose-friendly: narrower max-width for readability
+  .content--prose {
+    max-inline-size: calc(var(--unit) * 80);
+  }
+
+  // Flush: no padding, just gap
+  .content--flush {
+    padding-block: 0;
+    padding-inline: 0;
+  }
+}

package/src/03-layout/footer/footer.api.json

@@ -0,0 +1,45 @@
+{
+  "name": "footer",
+  "element": "footer",
+  "modifiers": {
+    "sticky": {
+      "type": "boolean"
+    },
+    "fixed": {
+      "type": "boolean"
+    },
+    "bordered": {
+      "type": "boolean"
+    },
+    "raised": {
+      "type": "boolean"
+    }
+  },
+  "elements": {
+    "start": {},
+    "center": {},
+    "end": {}
+  },
+  "cssVars": [
+    {
+      "name": "--ui-footer-height",
+      "default": "var(--ui-row-3)"
+    },
+    {
+      "name": "--ui-footer-bg",
+      "default": "var(--ui-color-bg)"
+    },
+    {
+      "name": "--ui-footer-padding-inline",
+      "default": "var(--ui-space-3)"
+    },
+    {
+      "name": "--ui-footer-border-color",
+      "default": "var(--ui-color-border)"
+    },
+    {
+      "name": "--ui-footer-z",
+      "default": "var(--ui-z-sticky)"
+    }
+  ]
+}

package/src/03-layout/footer/footer.docs.json

@@ -0,0 +1,110 @@
+{
+  "id": "footer",
+  "type": "primitive",
+  "title": "Footer",
+  "description": "Page footer with start, center, and end sections. Supports sticky/fixed positioning and border/shadow variants.",
+  "api": "./footer.api.json",
+  "sections": [
+    {
+      "title": "Default",
+      "description": "Basic footer with three sections.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "footer",
+              "class": "ui-footer ui-footer--bordered",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-footer__start",
+                  "children": [{ "tag": "small", "text": "2026 Brand" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-footer__center",
+                  "children": [{ "tag": "span", "text": "Footer links" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-footer__end",
+                  "children": [{ "tag": "small", "text": "v1.0.0" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Sticky",
+      "description": "Stays at the bottom of the viewport on scroll.",
+      "examples": [
+        {
+          "code": "<footer class=\"ui-footer ui-footer--sticky ui-footer--bordered\">\n  <div class=\"ui-footer__start\"><small>Brand</small></div>\n  <div class=\"ui-footer__center\">Links</div>\n  <div class=\"ui-footer__end\"><small>v1.0.0</small></div>\n</footer>"
+        }
+      ]
+    },
+    {
+      "title": "Bordered",
+      "description": "Top border via inset box-shadow to preserve grid rhythm.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "footer",
+              "class": "ui-footer ui-footer--bordered",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-footer__start",
+                  "children": [{ "tag": "small", "text": "Bordered footer" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-footer__end",
+                  "children": [{ "tag": "small", "text": "v1.0.0" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Raised",
+      "description": "Subtle drop shadow above the footer.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "footer",
+              "class": "ui-footer ui-footer--raised",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-footer__start",
+                  "children": [{ "tag": "small", "text": "Raised footer" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-footer__end",
+                  "children": [{ "tag": "small", "text": "v1.0.0" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Full Layout",
+      "description": "Footer inside an app-shell with topbar and sidebar.",
+      "examples": [
+        {
+          "code": "<body class=\"ui-app-shell\">\n  <header class=\"ui-topbar ui-topbar--bordered\">\n    <div class=\"ui-topbar__start\"><strong>App</strong></div>\n  </header>\n  <main class=\"ui-main ui-main--full\">\n    <div class=\"ui-container\">Content</div>\n    <footer class=\"ui-footer 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>\n  </main>\n</body>"
+        }
+      ]
+    }
+  ]
+}

package/src/03-layout/footer/footer.visual.spec.ts

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

package/src/03-layout/footer/index.scss

@@ -0,0 +1,62 @@
+@layer primitives {
+  .footer {
+    --_height: var(--ui-footer-height, var(--ui-row-3));
+    --_bg: var(--ui-footer-bg, var(--ui-color-bg));
+    --_padding-inline: var(--ui-footer-padding-inline, var(--ui-space-3));
+    --_border-color: var(--ui-footer-border-color, var(--ui-color-border));
+    --_z: var(--ui-footer-z, var(--ui-z-sticky));
+
+    display: flex;
+    align-items: center;
+    z-index: var(--_z);
+
+    block-size: var(--_height);
+    padding-inline: var(--_padding-inline);
+
+    background: var(--_bg);
+  }
+
+  // Sections
+  .footer__start {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: var(--ui-space-2);
+  }
+
+  .footer__center {
+    display: flex;
+    flex: 1;
+    align-items: center;
+    justify-content: center;
+    gap: var(--ui-space-2);
+  }
+
+  .footer__end {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: var(--ui-space-2);
+  }
+
+  // Position modifiers
+  .footer--sticky {
+    position: sticky;
+    inset-block-end: 0;
+  }
+
+  .footer--fixed {
+    position: fixed;
+    inset-block-end: 0;
+    inset-inline: 0;
+  }
+
+  // Visual modifiers
+  .footer--bordered {
+    box-shadow: inset 0 var(--ui-border-width-sm) 0 0 var(--_border-color);
+  }
+
+  .footer--raised {
+    box-shadow: 0 calc(var(--ui-border-width-sm) * -1) 6px hsl(var(--ui-hue-primary, 220) 10% 20% / 0.08);
+  }
+}

package/src/03-layout/index.scss

@@ -1,11 +1,17 @@
+@forward './app-shell';
+@forward './aspect-ratio';
 @forward './box';
-@forward './stack';
+@forward './center';
 @forward './cluster';
+@forward './container';
+@forward './content';
 @forward './flex';
-@forward './center';
+@forward './footer';
 @forward './grid';
-@forward './app-shell';
+@forward './main';
+@forward './nav-rail';
+@forward './page-header';
 @forward './sidebar';
 @forward './sidebar-nav';
-@forward './main';
-@forward './container';
+@forward './stack';
+@forward './topbar';

package/src/03-layout/main/index.scss

@@ -1,5 +1,6 @@
 @layer primitives {
   .main {
+    padding-block-start: var(--topbar-height, 0);
     margin-inline-start: var(--sidebar-width, calc(var(--unit) * 30));
   }
 

package/src/03-layout/nav-rail/index.scss

@@ -0,0 +1,50 @@
+@layer primitives {
+  .nav-rail {
+    --_width: var(--ui-nav-rail-width, var(--ui-row-4));
+    --_bg: var(--ui-nav-rail-bg, var(--ui-color-bg-subtle));
+    --_border-color: var(--ui-nav-rail-border-color, var(--ui-color-border));
+    --_gap: var(--ui-nav-rail-gap, var(--ui-space-1));
+    --_z: var(--ui-nav-rail-z, var(--ui-z-sticky));
+
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    position: fixed;
+    inset-block: var(--topbar-height, 0);
+    inset-inline-start: 0;
+    z-index: var(--_z);
+
+    inline-size: var(--_width);
+    padding-block: var(--ui-space-2);
+
+    background: var(--_bg);
+    box-shadow: inset calc(var(--ui-border-width-sm) * -1) 0 0 0 var(--_border-color);
+  }
+
+  // Navigation items area
+  .nav-rail__items {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--_gap);
+  }
+
+  // Bottom-pinned actions (settings, profile)
+  .nav-rail__actions {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--_gap);
+
+    margin-block-start: auto;
+  }
+
+  // Position on end side
+  .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);
+  }
+}

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

@@ -0,0 +1,35 @@
+{
+  "name": "nav-rail",
+  "element": "nav",
+  "modifiers": {
+    "end": {
+      "type": "boolean"
+    }
+  },
+  "elements": {
+    "items": {},
+    "actions": {}
+  },
+  "cssVars": [
+    {
+      "name": "--ui-nav-rail-width",
+      "default": "var(--ui-row-4)"
+    },
+    {
+      "name": "--ui-nav-rail-bg",
+      "default": "var(--ui-color-bg-subtle)"
+    },
+    {
+      "name": "--ui-nav-rail-border-color",
+      "default": "var(--ui-color-border)"
+    },
+    {
+      "name": "--ui-nav-rail-gap",
+      "default": "var(--ui-space-1)"
+    },
+    {
+      "name": "--ui-nav-rail-z",
+      "default": "var(--ui-z-sticky)"
+    }
+  ]
+}

package/src/03-layout/nav-rail/nav-rail.docs.json

@@ -0,0 +1,76 @@
+{
+  "id": "nav-rail",
+  "type": "primitive",
+  "title": "Nav Rail",
+  "description": "Narrow fixed vertical navigation rail for icon-based navigation with bottom actions.",
+  "api": "./nav-rail.api.json",
+  "sections": [
+    {
+      "title": "Default",
+      "description": "Fixed narrow rail with icon items and bottom actions.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "nav",
+              "class": "ui-nav-rail",
+              "style": "position: relative; block-size: 320px",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-nav-rail__items",
+                  "children": [
+                    {
+                      "tag": "button",
+                      "class": "ui-button ui-button--ghost ui-button--icon",
+                      "text": "H"
+                    },
+                    {
+                      "tag": "button",
+                      "class": "ui-button ui-button--ghost ui-button--icon",
+                      "text": "S"
+                    },
+                    {
+                      "tag": "button",
+                      "class": "ui-button ui-button--ghost ui-button--icon",
+                      "text": "M"
+                    }
+                  ]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-nav-rail__actions",
+                  "children": [
+                    {
+                      "tag": "button",
+                      "class": "ui-button ui-button--ghost ui-button--icon",
+                      "text": "G"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "End Position",
+      "description": "Rail on the end (right in LTR) side.",
+      "examples": [
+        {
+          "code": "<nav class=\"ui-nav-rail ui-nav-rail--end\">\n  <div class=\"ui-nav-rail__items\">\n    <!-- icon buttons -->\n  </div>\n  <div class=\"ui-nav-rail__actions\">\n    <!-- settings, profile -->\n  </div>\n</nav>"
+        }
+      ]
+    },
+    {
+      "title": "With Topbar",
+      "description": "Nav rail respects --topbar-height, offsetting below the topbar.",
+      "examples": [
+        {
+          "code": "<body class=\"ui-app-shell\" style=\"--topbar-height: var(--ui-row-3)\">\n  <header class=\"ui-topbar ui-topbar--fixed ui-topbar--bordered\">\n    <div class=\"ui-topbar__start\"><strong>App</strong></div>\n  </header>\n  <nav class=\"ui-nav-rail\">\n    <div class=\"ui-nav-rail__items\"><!-- icons --></div>\n  </nav>\n</body>"
+        }
+      ]
+    }
+  ]
+}

package/src/03-layout/nav-rail/nav-rail.visual.spec.ts

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

package/src/03-layout/page-header/index.scss

@@ -0,0 +1,52 @@
+@layer primitives {
+  .page-header {
+    --_padding-block: var(--ui-page-header-padding-block, var(--ui-space-3));
+    --_padding-inline: var(--ui-page-header-padding-inline, 0);
+    --_gap: var(--ui-page-header-gap, var(--ui-space-2));
+    --_border-color: var(--ui-page-header-border-color, var(--ui-color-border));
+
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--_gap);
+
+    padding-block: var(--_padding-block);
+    padding-inline: var(--_padding-inline);
+
+    line-height: var(--ui-body-line-height);
+  }
+
+  // Title area: stacks title + description vertically
+  .page-header__title {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    gap: var(--ui-space-1);
+  }
+
+  // Actions slot: right-aligned buttons/controls
+  .page-header__actions {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: var(--ui-space-2);
+  }
+
+  // Breadcrumb slot: full-width above title row
+  .page-header__breadcrumb {
+    flex-basis: 100%;
+  }
+
+  // Modifiers
+  .page-header--bordered {
+    box-shadow: inset 0 calc(var(--ui-border-width-sm) * -1) 0 0 var(--_border-color);
+  }
+
+  .page-header--sticky {
+    position: sticky;
+    inset-block-start: 0;
+    z-index: var(--ui-z-sticky);
+
+    background: var(--ui-color-bg);
+  }
+}

package/src/03-layout/page-header/page-header.api.json

@@ -0,0 +1,35 @@
+{
+  "name": "page-header",
+  "element": "header",
+  "modifiers": {
+    "bordered": {
+      "type": "boolean"
+    },
+    "sticky": {
+      "type": "boolean"
+    }
+  },
+  "elements": {
+    "title": {},
+    "actions": {},
+    "breadcrumb": {}
+  },
+  "cssVars": [
+    {
+      "name": "--ui-page-header-padding-block",
+      "default": "var(--ui-space-3)"
+    },
+    {
+      "name": "--ui-page-header-padding-inline",
+      "default": "0"
+    },
+    {
+      "name": "--ui-page-header-gap",
+      "default": "var(--ui-space-2)"
+    },
+    {
+      "name": "--ui-page-header-border-color",
+      "default": "var(--ui-color-border)"
+    }
+  ]
+}