@smwb/ui-styles 2.9.0 → 2.10.0

package/README.md

@@ -339,6 +339,27 @@ holds the tab stop (`menuitemcheckbox`, `menuitemradio`, `treeitem`, `spinbutton
 `scrollbar`) are listed next to the focusable elements. A control the generic list cannot see opts out with
 `.smwb-appbar__no-drag` or `data-no-drag`.
 
+#### Overlay layers
+
+The surfaces the components portal to `<body>` sit in a z-index scale of Less variables, so an app puts them over its
+own header, sheets and windows from its theme, with no rule on the `.smwb-*` classes:
+
+| Variable    | Default | Layer                                                                                  |
+| ----------- | ------- | -------------------------------------------------------------------------------------- |
+| `@menuZ`    | 1300    | the floating `Menu` (`OverflowMenu`, `SelectField` options, submenus), above the modal |
+| `@tooltipZ` | 1400    | the `Tooltip` tip, above the menu and the dialogs it is raised from                    |
+
+The tip stays above the menu: a hint on a menu item, on a dialog's button or on a docked window's control must not hide
+under them. Keep that order if you change one value. The modal overlay (1001), the chat shell (1002), the floating
+window (`@floatingWindowZ`, 150) and the sheet (100) stay below both. `npm run lint` of this package renders the
+stylesheet and checks the order and that each variable reaches its rule.
+
+```less
+// theme.config: the host's own layers go up to 2000, the menus and tips stay over them
+@menuZ: 2100;
+@tooltipZ: 2200;
+```
+
 ## License
 
 [MIT](./LICENSE)

package/less/components/menu/menu.less

@@ -4,7 +4,7 @@
 
   &--floating {
     box-shadow: @menuBoxShadow;
-    z-index: 1300;
+    z-index: @menuZ;
     min-width: 112px;
     cursor: default;
   }

package/less/components/tooltip/tooltip.less

@@ -2,7 +2,7 @@
   border-radius: 4px;
   background-color: var(--smui-tooltipBg);
   color: var(--smui-tooltipTextColor);
-  z-index: 5;
+  z-index: @tooltipZ;
   font-size: 12px;
   padding: 0 @tooltipPaddingX;
   height: 24px;

package/less/default/globals/default.variables.less

@@ -559,6 +559,19 @@
 // stack. Hosts add their stacking index on top, leaving headroom before 200.
 @floatingWindowZ: 150;
 
+/*-------------------
+  Overlay layers
+--------------------*/
+// z-index of the surfaces the components portal to <body>. A theme overrides them by setting
+// the variable, with no rule on the `.smwb-*` classes; each must stay above whatever the host
+// app stacks under it (its header, sheets, windows, dialogs).
+// A floating Menu (OverflowMenu, SelectField options, submenus) sits above the modal (1001),
+// the chat shell (1002) and every surface that opens it. Off-grid.
+@menuZ: 1300;
+// A Tooltip sits above the menu and the dialogs it is raised from: a hint on a menu item,
+// a dialog's button or a docked window's control must not hide under them. Off-grid.
+@tooltipZ: 1400;
+
 /*-------------------
     Tooltip
 --------------------*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smwb/ui-styles",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Framework-agnostic LESS design tokens and component styles (smwb-*) shared by the @smwb UI libraries. Prebuilt aggregate CSS lives in @smwb/ui-css.",
   "license": "MIT",
   "sideEffects": [
@@ -19,7 +19,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "lint": "node scripts/check-aggregate.mjs && node scripts/check-tokens.mjs && node scripts/check-control-heights.mjs && node scripts/check-typography-case.mjs && node scripts/check-chart-series.mjs && node scripts/check-normalize-specificity.mjs"
+    "lint": "node scripts/check-aggregate.mjs && node scripts/check-tokens.mjs && node scripts/check-control-heights.mjs && node scripts/check-typography-case.mjs && node scripts/check-overlay-layers.mjs && node scripts/check-chart-series.mjs && node scripts/check-normalize-specificity.mjs"
   },
   "homepage": "https://sourcecraft.dev/elfenmail/ui",
   "repository": {