@teseor/css 1.3.0 → 1.4.0

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)"
+    }
+  ]
+}

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

@@ -0,0 +1,124 @@
+{
+  "id": "page-header",
+  "type": "primitive",
+  "title": "Page Header",
+  "description": "Content area header with title, description, actions, and optional breadcrumb.",
+  "api": "./page-header.api.json",
+  "sections": [
+    {
+      "title": "Default",
+      "description": "Title with actions on the end side.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "header",
+              "class": "ui-page-header ui-page-header--bordered",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-page-header__title",
+                  "children": [
+                    { "tag": "h1", "class": "ui-heading ui-heading--xl", "text": "Users" },
+                    { "tag": "p", "text": "Manage user accounts and permissions." }
+                  ]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-page-header__actions",
+                  "children": [
+                    { "tag": "button", "class": "ui-button ui-button--primary", "text": "Add user" }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "With Breadcrumb",
+      "description": "Breadcrumb spans the full width above the title row.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "header",
+              "class": "ui-page-header ui-page-header--bordered",
+              "children": [
+                {
+                  "tag": "nav",
+                  "class": "ui-page-header__breadcrumb",
+                  "children": [{ "tag": "span", "text": "Home / Settings / Users" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-page-header__title",
+                  "children": [
+                    { "tag": "h1", "class": "ui-heading ui-heading--xl", "text": "Users" }
+                  ]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-page-header__actions",
+                  "children": [{ "tag": "button", "class": "ui-button", "text": "Export" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Bordered",
+      "description": "Bottom border via inset box-shadow.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "header",
+              "class": "ui-page-header ui-page-header--bordered",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-page-header__title",
+                  "children": [
+                    { "tag": "h1", "class": "ui-heading ui-heading--xl", "text": "Dashboard" }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Sticky",
+      "description": "Sticks to the top of the scroll container.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "header",
+              "class": "ui-page-header ui-page-header--sticky ui-page-header--bordered",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-page-header__title",
+                  "children": [
+                    { "tag": "h1", "class": "ui-heading ui-heading--xl", "text": "Sticky Header" }
+                  ]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-page-header__actions",
+                  "children": [{ "tag": "button", "class": "ui-button", "text": "Save" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/03-layout/page-header/page-header.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, 'page-header.docs.json');
+
+test.describe('page-header visual regression', () => {
+  test('all variations', async ({ page }) => {
+    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await validateGridRhythm(page, 'page-header');
+    await saveForLostPixel(page, 'page-header');
+    await expect(page.locator('body')).toHaveScreenshot('page-header.visual.png');
+  });
+});

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

@@ -3,11 +3,11 @@
     display: flex;
     flex-direction: column;
     position: fixed;
-    inset-block-start: 0;
+    inset-block-start: var(--topbar-height, 0);
     inset-inline-start: 0;
     z-index: var(--ui-z-sticky);
 
-    block-size: 100vh;
+    block-size: calc(100vh - var(--topbar-height, 0px));
     inline-size: var(--sidebar-width, calc(var(--unit) * 30));
     overflow-y: auto;
 

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

@@ -0,0 +1,62 @@
+@layer primitives {
+  .topbar {
+    --_height: var(--ui-topbar-height, var(--ui-row-3));
+    --_bg: var(--ui-topbar-bg, var(--ui-color-bg));
+    --_padding-inline: var(--ui-topbar-padding-inline, var(--ui-space-3));
+    --_border-color: var(--ui-topbar-border-color, var(--ui-color-border));
+    --_z: var(--ui-topbar-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
+  .topbar__start {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: var(--ui-space-2);
+  }
+
+  .topbar__center {
+    display: flex;
+    flex: 1;
+    align-items: center;
+    justify-content: center;
+    gap: var(--ui-space-2);
+  }
+
+  .topbar__end {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: var(--ui-space-2);
+  }
+
+  // Position modifiers
+  .topbar--sticky {
+    position: sticky;
+    inset-block-start: 0;
+  }
+
+  .topbar--fixed {
+    position: fixed;
+    inset-block-start: 0;
+    inset-inline: 0;
+  }
+
+  // Visual modifiers
+  .topbar--bordered {
+    box-shadow: inset 0 calc(var(--ui-border-width-sm) * -1) 0 0 var(--_border-color);
+  }
+
+  .topbar--raised {
+    box-shadow: var(--shadow-sm);
+  }
+}

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

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

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

@@ -0,0 +1,110 @@
+{
+  "id": "topbar",
+  "type": "primitive",
+  "title": "Topbar",
+  "description": "Fixed or sticky header bar for app layouts with start, center, and end sections.",
+  "api": "./topbar.api.json",
+  "sections": [
+    {
+      "title": "Default",
+      "description": "Basic topbar with three sections: start (brand), center (search/nav), and end (actions).",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "header",
+              "class": "ui-topbar ui-topbar--bordered",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-topbar__start",
+                  "children": [{ "tag": "strong", "text": "Brand" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-topbar__center",
+                  "children": [{ "tag": "span", "text": "Center content" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-topbar__end",
+                  "children": [{ "tag": "span", "text": "Actions" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Sticky",
+      "description": "Stays at the top of the viewport on scroll.",
+      "examples": [
+        {
+          "code": "<header class=\"ui-topbar ui-topbar--sticky ui-topbar--bordered\">\n  <div class=\"ui-topbar__start\"><strong>Brand</strong></div>\n  <div class=\"ui-topbar__center\">Nav</div>\n  <div class=\"ui-topbar__end\">Actions</div>\n</header>"
+        }
+      ]
+    },
+    {
+      "title": "Bordered",
+      "description": "Bottom border via inset box-shadow to preserve grid rhythm.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "header",
+              "class": "ui-topbar ui-topbar--bordered",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-topbar__start",
+                  "children": [{ "tag": "strong", "text": "Bordered" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-topbar__end",
+                  "children": [{ "tag": "span", "text": "Actions" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Raised",
+      "description": "Subtle drop shadow below the topbar.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "header",
+              "class": "ui-topbar ui-topbar--raised",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-topbar__start",
+                  "children": [{ "tag": "strong", "text": "Raised" }]
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-topbar__end",
+                  "children": [{ "tag": "span", "text": "Actions" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Integration with Sidebar",
+      "description": "Set --topbar-height on .app-shell so sidebar and main offset correctly. The topbar itself uses --fixed, and sidebar/main read --topbar-height.",
+      "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    <div class=\"ui-topbar__end\">User</div>\n  </header>\n  <aside class=\"ui-sidebar\">Sidebar</aside>\n  <main class=\"ui-main\">\n    <div class=\"ui-container\">Content</div>\n  </main>\n</body>"
+        }
+      ]
+    }
+  ]
+}

package/src/03-layout/topbar/topbar.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, 'topbar.docs.json');
+
+test.describe('topbar visual regression', () => {
+  test('all variations', async ({ page }) => {
+    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await validateGridRhythm(page, 'topbar');
+    await saveForLostPixel(page, 'topbar');
+    await expect(page.locator('body')).toHaveScreenshot('topbar.visual.png');
+  });
+});