@pgcorp/ui-kit 0.7.1 → 0.7.3

package/README.md

@@ -255,24 +255,31 @@ Components consume semantic custom properties. Consumers override documented
 tokens on the root theme container and do not depend on internal CSS classes or
 template structure.
 
-Floating surfaces teleport to `document.body`. If the host application uses an
-overlay scale above the UI-kit defaults, align the public layer tokens on
-`:root`, preserving `--s-layer-floating < --s-layer-toast <
---s-layer-overlay-backdrop`:
+Floating surfaces teleport to `document.body`; toast, drag fallbacks, modal, and
+drawer also use root-level bands. The values `--s-layer-floating`,
+`--s-layer-toast`, `--s-layer-drag`, and `--s-layer-overlay-backdrop` are base
+anchors. Registered nested layers advance by `--s-layer-overlay-step`, while a
+modal surface uses `--s-layer-overlay-surface-offset` above its backdrop.
+
+Integrate a host overlay scale through one root offset:
 
 ```css
 :root {
   --host-overlay-surface: 2400;
-  --s-layer-floating: calc(var(--host-overlay-surface) + 10);
-  --s-layer-toast: calc(var(--host-overlay-surface) + 20);
-  --s-layer-overlay-backdrop: calc(var(--host-overlay-surface) + 100);
+  --s-layer-host-offset: var(--host-overlay-surface);
 }
 ```
 
-`--host-overlay-surface` belongs to the host application. The complete layer
-integration contract and verification checklist are published in
+`--host-overlay-surface` belongs to the host application. The offset shifts all
+root UI-kit bands together and leaves local content/navigation anchors intact.
+Do not combine it with manual shifts of individual layer tokens. The complete
+owner map, dynamic-stack contract, and verification checklist are published in
 `docs/theming.md` inside the npm package.
 
+CodeMirror autocomplete in `SCodeEditor` and the overlay `SResizeHandle` stay
+inside their positioned component owners. They intentionally use the local
+`--s-layer-floating` anchor and are not shifted by `--s-layer-host-offset`.
+
 ## Публичный контракт / Public contract
 
 `package.json#exports` — источник истины для импортов. Публичный контракт

package/docs/theming.md

@@ -19,32 +19,49 @@ private selectors или зависимость от структуры template
 
 ### Интеграция шкалы слоёв host-приложения
 
-Floating surfaces (`STooltip`, меню, select и popover) телепортируются в
-`document.body`, поэтому их layer tokens разрешаются в корневом scope документа,
-а не во вложенном контейнере компонента. Базовая шкала UI-kit сохраняет порядок
-`floating < toast < overlay-backdrop`:
+Floating surfaces (`STooltip`, menu, select, combobox и popover), modal и
+drawer телепортируются в `document.body`. `SToastContainer` также размещается
+в корневой области приложения. Их layer tokens разрешаются на `:root`, а не
+во вложенном theme-контейнере trigger.
 
-- `--s-layer-floating: 40` — tooltip, menu, select и popover;
-- `--s-layer-toast: 50` — уведомления;
+Шкала задаёт base anchors, а не статический total order:
+
+- `--s-layer-floating: 40` — базовый registered floating layer;
+- `--s-layer-toast: 50` — root-контейнер уведомлений;
+- `--s-layer-drag: 10000` — root drag/fallback surface;
 - `--s-layer-overlay-backdrop: 11000` — backdrop первого modal/drawer;
-- `--s-layer-overlay-surface` вычисляется из backdrop и surface offset.
+- `--s-layer-overlay-surface-offset: 10` — surface над её backdrop;
+- `--s-layer-overlay-step: 20` — каждый следующий registered layer в том же
+  floating или overlay tier.
+
+Поэтому вложенная surface всегда выше своего owner, а базовые 40 и 50 не
+являются обещанием, что любое уведомление выше любой цепочки nested menus.
 
-Если host-приложение использует другую систему overlay-слоёв, задайте UI-kit
-tokens на `:root` относительно наибольшего top-level слоя host. Не меняйте
-`z-index` внутренних элементов компонентов и не привязывайтесь к их CSS-классам.
+Для интеграции с внешней overlay-шкалой задайте один
+`--s-layer-host-offset` на `:root`. UI-kit применяет его к root-level
+`floating`, `toast`, `drag` и `overlay-backdrop`, сохраняя high-band и
+динамические offsets. Локальные content, sticky, affordance и navigation anchors
+не сдвигаются.
 
 ```css
 :root {
   --host-overlay-surface: 2400;
-  --s-layer-floating: calc(var(--host-overlay-surface) + 10);
-  --s-layer-toast: calc(var(--host-overlay-surface) + 20);
-  --s-layer-overlay-backdrop: calc(var(--host-overlay-surface) + 100);
+  --s-layer-host-offset: var(--host-overlay-surface);
 }
 ```
 
-Значение `--host-overlay-surface` в примере является контрактом host-приложения,
-а не фиксированным значением UI-kit. После интеграции проверьте tooltip/menu,
-toast и modal/drawer внутри и снаружи host overlay.
+`--host-overlay-surface` принадлежит host-приложению. Не комбинируйте
+`--s-layer-host-offset` с ручным сдвигом отдельных UI-kit layer tokens. После
+интеграции проверьте tooltip/menu/select, toast, drag, modal/drawer и floating
+surface внутри modal. Не меняйте `z-index` внутренних элементов компонентов.
+
+Локальные floating-элементы не входят в root-level bridge. Autocomplete-tooltip
+`SCodeEditor` остаётся потомком `.cm-editor`, а overlay-вариант
+`SResizeHandle` — абсолютным потомком своего positioned owner. Они используют
+`--s-layer-floating` внутри локального stacking context и не получают
+`--s-layer-host-offset`. Конфигурация CodeMirror с переносом tooltip в
+`document.body` не входит в публичный контракт `SCodeEditor`; root-level surface
+обязана использовать зарегистрированный root layer UI-kit.
 
 ## English
 
@@ -65,29 +82,45 @@ structure dependencies.
 
 ### Host application layer-scale integration
 
-Floating surfaces (`STooltip`, menus, selects, and popovers) teleport to
-`document.body`. Their layer tokens therefore resolve in the document root scope,
-not in a nested component container. The default UI-kit scale preserves
-`floating < toast < overlay-backdrop`:
+Floating surfaces (`STooltip`, menus, selects, comboboxes, and popovers), modals,
+and drawers teleport to `document.body`. `SToastContainer` also belongs at the
+application root. Their layer tokens resolve on `:root`, not in the trigger's
+nested theme container.
+
+The scale defines base anchors, not a static total order:
+
+- `--s-layer-floating: 40` — first registered floating layer;
+- `--s-layer-toast: 50` — root notification container;
+- `--s-layer-drag: 10000` — root drag/fallback surface;
+- `--s-layer-overlay-backdrop: 11000` — first modal/drawer backdrop;
+- `--s-layer-overlay-surface-offset: 10` — surface above its backdrop;
+- `--s-layer-overlay-step: 20` — each subsequent registered layer in the same
+  floating or overlay tier.
 
-- `--s-layer-floating: 40` — tooltips, menus, selects, and popovers;
-- `--s-layer-toast: 50` — notifications;
-- `--s-layer-overlay-backdrop: 11000` — the first modal/drawer backdrop;
-- `--s-layer-overlay-surface` is derived from the backdrop and surface offset.
+A nested surface therefore stays above its owner. The base values 40 and 50 do
+not promise that every notification is above every chain of nested menus.
 
-When the host application uses another overlay scale, define the UI-kit tokens
-on `:root` relative to the highest top-level host layer. Do not change component
-internal `z-index` values or depend on internal CSS classes.
+To integrate another overlay scale, define one `--s-layer-host-offset` on
+`:root`. UI-kit applies it to the root-level floating, toast, drag, and overlay
+backdrop bands while preserving the high band and dynamic offsets. Local content,
+sticky, affordance, and navigation anchors are not shifted.
 
 ```css
 :root {
   --host-overlay-surface: 2400;
-  --s-layer-floating: calc(var(--host-overlay-surface) + 10);
-  --s-layer-toast: calc(var(--host-overlay-surface) + 20);
-  --s-layer-overlay-backdrop: calc(var(--host-overlay-surface) + 100);
+  --s-layer-host-offset: var(--host-overlay-surface);
 }
 ```
 
-The `--host-overlay-surface` value is a host-application contract, not a fixed
-UI-kit value. Verify tooltip/menu, toast, and modal/drawer behavior both inside
-and outside host overlays after integration.
+`--host-overlay-surface` belongs to the host application. Do not combine
+`--s-layer-host-offset` with manual shifts of individual UI-kit layer tokens.
+Verify tooltip/menu/select, toast, drag, modal/drawer, and a floating surface
+inside a modal. Do not override internal component `z-index` values.
+
+Local floating elements are outside the root-level bridge. The `SCodeEditor`
+autocomplete tooltip remains a descendant of `.cm-editor`, and the overlay
+`SResizeHandle` remains an absolutely positioned child of its positioned owner.
+They use `--s-layer-floating` inside a local stacking context and do not receive
+`--s-layer-host-offset`. A CodeMirror configuration that reparents tooltips into
+`document.body` is outside the public `SCodeEditor` contract; a root-level
+surface must use a registered UI-kit root layer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgcorp/ui-kit",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Typed Vue 3 design system with accessible components, semantic themes, and workbench patterns.",
   "type": "module",
   "types": "./index.ts",
@@ -571,7 +571,7 @@
     "@uiw/codemirror-extensions-langs": "^4.25.8",
     "codemirror": "6.0.2",
     "codemirror-lang-makefile": "^0.1.1",
-    "dompurify": "^3.4.12",
+    "dompurify": "^3.4.13",
     "graphology": "^0.26.0",
     "highlight.js": "^11.11.1",
     "@lucide/vue": "^1.16.0",
@@ -598,7 +598,7 @@
     "eslint-plugin-vue": "^10.8.0",
     "jsdom": "^28.1.0",
     "pinia": "^3.0.4",
-    "postcss": "8.5.19",
+    "postcss": "8.5.26",
     "postcss-selector-parser": "7.1.4",
     "storybook": "10.5.3",
     "typescript": "^5.9.3",

package/src/components/shared/_internal/markerContract.ts

@@ -1,4 +1,23 @@
-export type SMarkerTone = 'surface' | 'primary' | 'success' | 'blue' | 'sky' | 'indigo' | 'emerald' | 'green' | 'teal' | 'amber' | 'orange' | 'rose' | 'pink' | 'fuchsia' | 'cyan' | 'lime'
+export const S_MARKER_TONES = [
+  'surface',
+  'primary',
+  'success',
+  'blue',
+  'sky',
+  'indigo',
+  'emerald',
+  'green',
+  'teal',
+  'amber',
+  'orange',
+  'rose',
+  'pink',
+  'fuchsia',
+  'cyan',
+  'lime',
+] as const
+
+export type SMarkerTone = typeof S_MARKER_TONES[number]
 export type SMarker = { tone: SMarkerTone } | { tone: 'custom'; color: `#${string}` }
 export type SCustomMarker = Extract<SMarker, { tone: 'custom' }>
 

package/src/components/shared/containers/SCloudChromeRow.css

@@ -68,7 +68,7 @@
 .sortable-drag.s-cloud-chrome-row,
 .sortable-fallback.s-cloud-chrome-row {
   pointer-events: none;
-  z-index: var(--s-layer-drag);
+  z-index: var(--s-layer-root-drag);
   opacity: 0.96;
   transform: scale(1.01);
   box-shadow: var(--s-cloud-chrome-drag-shadow);

package/src/components/shared/containers/SPopover.vue

@@ -188,7 +188,7 @@ const isOpen = computed(() => props.open ?? uncontrolledOpen.value);
 useInteractiveLeafRegistration({ owner: 'SPopover', active: () => isOpen.value });
 const panelId = `s-popover-panel-${useId()}`;
 const activeTriggerId = ref<string | null>(null);
-const layerZIndex = ref('var(--s-layer-floating)');
+const layerZIndex = ref('var(--s-layer-root-floating)');
 const resolvedTriggerAriaLabel = computed(() =>
   props.triggerAriaLabel ?? (
     props.triggerIconOnly || (!props.triggerLabel && !slots.default)
@@ -426,7 +426,7 @@ function deactivateOpenState(reason: CloseReason): void {
   const shouldRestoreFocus = reason === 'explicit' || reason === 'escape' || reason === 'trigger';
   layerRegistration?.unregister({ restoreFocus: shouldRestoreFocus });
   layerRegistration = null;
-  layerZIndex.value = 'var(--s-layer-floating)';
+  layerZIndex.value = 'var(--s-layer-root-floating)';
 }
 
 function assertControlMode(): void {

package/src/components/shared/controls/SCombobox.vue

@@ -147,7 +147,7 @@ const listboxRef = shallowRef<{
 } | null>(null)
 const isOpen = shallowRef(false)
 const activeValue = shallowRef<TKey | null>(null)
-const layerZIndex = shallowRef('var(--s-layer-floating)')
+const layerZIndex = shallowRef('var(--s-layer-root-floating)')
 let layerRegistration: LayerRegistration | null = null
 
 const inputId = computed(() => props.id === undefined
@@ -285,7 +285,7 @@ function close(reason: CloseReason): void {
   activeValue.value = null
   layerRegistration?.unregister({ restoreFocus: false })
   layerRegistration = null
-  layerZIndex.value = 'var(--s-layer-floating)'
+  layerZIndex.value = 'var(--s-layer-root-floating)'
 }
 
 async function open(): Promise<void> {

package/src/components/shared/controls/SMarker.vue

@@ -18,31 +18,13 @@ export type { SCustomMarker, SMarker, SMarkerTone } from '../_internal/markerCon
 import { computed } from 'vue'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 import { resolveSemanticToneBinding } from '../../../internal/semanticTone'
-import { createCustomMarker, type SMarker } from '../_internal/markerContract'
+import { createCustomMarker, S_MARKER_TONES, type SMarker } from '../_internal/markerContract'
 
 defineOptions({ inheritAttrs: false })
 
 const props = withDefaults(defineProps<{ marker: SMarker; size?: 'sm' | 'lg' }>(), { size: 'sm' })
 const ownedAttrs = useOwnedAttrs({ component: 'SMarker', owner: 'marker root' })
-const MARKER_TONES = [
-  'surface',
-  'primary',
-  'success',
-  'blue',
-  'sky',
-  'indigo',
-  'emerald',
-  'green',
-  'teal',
-  'amber',
-  'orange',
-  'rose',
-  'pink',
-  'fuchsia',
-  'cyan',
-  'lime',
-  'custom',
-] as const
+const MARKER_TONES = [...S_MARKER_TONES, 'custom'] as const
 const toneBinding = computed(() => resolveSemanticToneBinding(
   'SMarker',
   'marker.tone',

package/src/components/shared/controls/SSelect.vue

@@ -248,7 +248,7 @@ const listboxProps = computed<
 })
 
 const isOpen = ref(false)
-const layerZIndex = ref('var(--s-layer-floating)')
+const layerZIndex = ref('var(--s-layer-root-floating)')
 let layerRegistration: LayerRegistration | null = null
 const triggerRef = ref<SComboboxTriggerApi | null>(null)
 const listboxRef = ref<{ focusSelectedOrFirst: () => void } | null>(null)
@@ -271,7 +271,7 @@ function close(reason: CloseReason = 'trigger'): void {
     restoreFocus: reason === 'trigger' || reason === 'selection' || reason === 'escape',
   })
   layerRegistration = null
-  layerZIndex.value = 'var(--s-layer-floating)'
+  layerZIndex.value = 'var(--s-layer-root-floating)'
 }
 
 function triggerElement(): HTMLElement {

package/src/components/shared/data-display/SToastContainer.css

@@ -2,7 +2,7 @@
 
 .s-toast-container {
   @apply fixed top-0 right-0 flex max-h-full min-w-0 w-full max-w-md flex-col overflow-y-auto overscroll-contain p-4;
-  z-index: var(--s-layer-toast);
+  z-index: var(--s-layer-root-toast);
   @apply pointer-events-none;
 }
 

package/src/components/shared/data-display/STooltip.vue

@@ -190,7 +190,7 @@ const triggerContractError = (message: string): Error => new Error(`STooltip: ${
 
 const isOpen = ref(false);
 const ownedAttrs = useOwnedAttrs({ component: 'STooltip', owner: 'renderless tooltip contract' });
-const layerZIndex = ref('var(--s-layer-floating)');
+const layerZIndex = ref('var(--s-layer-root-floating)');
 let layerRegistration: LayerRegistration | null = null;
 let hideTimer: number | null = null;
 let showTimer: number | null = null;
@@ -374,7 +374,7 @@ const closeImmediately = () => {
   isOpen.value = false;
   layerRegistration?.unregister({ restoreFocus: false });
   layerRegistration = null;
-  layerZIndex.value = 'var(--s-layer-floating)';
+  layerZIndex.value = 'var(--s-layer-root-floating)';
 };
 
 const openImmediately = () => {

package/src/composables/useFloatingPosition.ts

@@ -157,7 +157,7 @@ export function useFloatingPosition(options: FloatingPositionOptions): FloatingP
       position: 'fixed',
       left: `${resolvedCoordinates.value.left}px`,
       top: `${resolvedCoordinates.value.top}px`,
-      zIndex: options.zIndex?.() ?? 'var(--s-layer-floating)',
+      zIndex: options.zIndex?.() ?? 'var(--s-layer-root-floating)',
       ...(widthMatch === 'min' ? { minWidth: `${Math.round(anchor.width)}px` } : {}),
       ...(widthMatch === 'exact' ? { width: `${Math.round(anchor.width)}px` } : {}),
     }
@@ -218,7 +218,7 @@ export function useFloatingPosition(options: FloatingPositionOptions): FloatingP
       position: 'fixed',
       left: '-10000px',
       top: '-10000px',
-      zIndex: options.zIndex?.() ?? 'var(--s-layer-floating)',
+      zIndex: options.zIndex?.() ?? 'var(--s-layer-root-floating)',
     }
     await nextTick()
     attachListeners()

package/src/internal/layerStack.ts

@@ -162,8 +162,8 @@ export function registerLayer(options: LayerRegistrationOptions): LayerRegistrat
   const zIndex = previousTopmost && previousTopmost.tier === tier
     ? `calc(${previousTopmost.zIndex} + var(--s-layer-overlay-step))`
     : tier === 'overlay'
-      ? 'var(--s-layer-overlay-backdrop)'
-      : 'var(--s-layer-floating)'
+      ? 'var(--s-layer-root-overlay-backdrop)'
+      : 'var(--s-layer-root-floating)'
   const entry: LayerEntry = {
     ...options,
     id: Symbol(options.kind),

package/src/internal/useMenuLayer.ts

@@ -29,7 +29,7 @@ export function useMenuLayer(
   options: { onDismiss?: (reason: 'escape' | 'outside') => void } = {},
 ) {
   const isOpen = ref(false)
-  const zIndex = ref('var(--s-layer-floating)')
+  const zIndex = ref('var(--s-layer-root-floating)')
   let anchor: MenuAnchor | null = null
   let focusAnchor: HTMLElement | null = null
   let registration: LayerRegistration | null = null
@@ -41,7 +41,7 @@ export function useMenuLayer(
     registration = null
     anchor = null
     focusAnchor = null
-    zIndex.value = 'var(--s-layer-floating)'
+    zIndex.value = 'var(--s-layer-root-floating)'
   }
 
   function closeForTab(event: KeyboardEvent): void {

package/src/styles/tokens.css

@@ -324,15 +324,20 @@
   --s-layer-sticky: 10;
   --s-layer-affordance: 20;
   --s-layer-status: 25;
+  --s-layer-host-offset: 0;
   --s-layer-floating: 40;
   --s-layer-toast: 50;
   --s-layer-navigation: 50;
   --s-layer-navigation-submenu: 49;
   --s-layer-drag: 10000;
   --s-layer-overlay-backdrop: 11000;
+  --s-layer-root-floating: calc(var(--s-layer-host-offset) + var(--s-layer-floating));
+  --s-layer-root-toast: calc(var(--s-layer-host-offset) + var(--s-layer-toast));
+  --s-layer-root-drag: calc(var(--s-layer-host-offset) + var(--s-layer-drag));
+  --s-layer-root-overlay-backdrop: calc(var(--s-layer-host-offset) + var(--s-layer-overlay-backdrop));
   --s-layer-overlay-surface-offset: 10;
   --s-layer-overlay-step: 20;
-  --s-layer-overlay-surface: calc(var(--s-layer-overlay-backdrop) + var(--s-layer-overlay-surface-offset));
+  --s-layer-overlay-surface: calc(var(--s-layer-root-overlay-backdrop) + var(--s-layer-overlay-surface-offset));
   --s-overlay-backdrop-blur: 2px;
   --s-elevation-control: var(--shadow-sm);
   --s-elevation-floating: var(--shadow-lg);