@smworks-cz/ui-kit 1.5.1 → 1.7.0

package/README.md

@@ -90,25 +90,70 @@ function MyApp() {
 }
 ```
 
+### Overlays: layering, Escape and z-index
+
+All overlays (Modal, Drawer, Sheet, ConfirmDialog, Spotlight, CommandMenu, Popover, DropdownMenu, Tooltip and the
+dropdowns of Select / Combobox / DatePicker / ColorPicker / PhoneInput) share one overlay stack:
+
+- Escape closes only the topmost overlay (a Select open inside a Modal closes first, the Modal stays).
+- A parent's outside-click ignores clicks into portals of nested overlays (Select inside Popover or Sheet works).
+- A nested overlay gets `parent z-index + 1`; a new modal-like overlay is always placed above everything open.
+- Modal, Drawer and Sheet trap focus (hidden elements are skipped) and return focus to the trigger on close.
+- Animations are skipped when the user prefers reduced motion.
+
+Z-index scale (CSS variables, overridable on `:root`):
+
+| Variable | Default | Used by |
+|----------|---------|---------|
+| `--sm-ui-z-overlay` | `99998` | Modal, Drawer, Sheet, Spotlight, CommandMenu, ConfirmDialog |
+| `--sm-ui-z-popover` | `99999` | Popover, DropdownMenu, Tooltip, dropdowns of form controls |
+| `--sm-ui-z-toast` | `100050` | Toasts, always above kit overlays |
+
+Nested overlays may rise a few units above the base (one per open layer). Put custom app layers that must sit above
+the kit (lightbox, tour, feedback overlay) at `calc(var(--sm-ui-z-popover, 99999) + 20)` or higher, and register them
+with `useOverlay()` so Escape and outside-click respect them. `useOverlayState()` tells you whether any kit overlay is open.
+
+```tsx
+import { useOverlayState, useOverlay, OverlayContext, Z_INDEX, tokens } from '@smworks-cz/ui-kit';
+
+const { open } = useOverlayState(); // disable global shortcuts while a modal / dropdown is open
+```
+
+### Design tokens
+
+Colors, glass values, radii, fonts, the field label typography and the z-index scale are exported so apps do not
+have to copy them from the bundle:
+
+```tsx
+import { tokens, Z_INDEX, getZIndexBase, FieldLabel } from '@smworks-cz/ui-kit';
+
+tokens.colors.primary          // '#FC4F00'
+tokens.theme.dark.panelBg      // 'rgba(24,24,24,0.65)'
+tokens.glass.panelBlur         // 'blur(32px) saturate(1.4)'
+```
+
 ## Components
 
 ### Forms
-Button, Input, Select, DatePicker, Checkbox, Radio, Switch, Textarea, Slider, FileUpload, SegmentedControl
+Button, IconButton, Input, NumberInput, Select, Combobox, DatePicker, Checkbox, Radio, Switch, Textarea, Slider, FileUpload, SegmentedControl, ColorPicker, Rating, OTPInput, PhoneInput, ImageCropper, FormField, FieldLabel
 
 ### Data display
-Table, Card, Accordion, Tabs, Tooltip, Popover, Skeleton, EmptyState, Stat, Avatar, Tag, Badge
+Table, DataGrid, MobileDataCard, Card, Accordion, Tabs, Tooltip, Popover, Skeleton, EmptyState, Stat, Avatar, AvatarStack, Tag, Badge, Calendar, Timeline, DataList, Tree, StatusBadge
+
+### Charts
+LineChart, AreaChart, BarChart, PieChart, DonutChart, Sparkline
 
 ### Navigation & layout
-Modal, Drawer, Breadcrumb, Pagination, Stepper, DropdownMenu, Link, Spotlight
+Modal, Drawer, Sheet, Breadcrumb, Pagination, Stepper, FormWizard, DropdownMenu, Link, Spotlight, CommandMenu, AppSidebar, SidebarItem, Navbar
 
 ### Feedback
-Toast, Alert, Progress, ProgressCircle, Spinner
+Toast, Alert, Banner, Notification, Progress, ProgressCircle, Spinner, ConfirmDialog, CopyButton
 
 ### Utility
-Divider, Stack, Container, DragList
+Divider, Stack, Container, DragList, SortableList, Splitter
 
 ### Hooks
-`useTheme`, `useToast`
+`useTheme`, `useToast`, `useConfirm`, `useOverlayState`, `useOverlay`, `useReducedMotion`, `useFocusTrap`
 
 ## Fonts
 
@@ -128,6 +173,21 @@ All components use inline design tokens with automatic dark/light mode support:
 - **Icons:** [@phosphor-icons/react](https://phosphoricons.com/)
 - **Fonts:** Zalando Sans (body), Zalando Sans Expanded (headings)
 
+Native inputs get their placeholder color from the theme through one injected rule scoped to the `sm-ui-input`
+class; no global `input::placeholder` override is needed in the app.
+
+## Testing
+
+`useTheme()` and every component render in plain Node / jsdom without a `matchMedia` polyfill. The theme is resolved
+synchronously on first render, so there is no light-mode flash when `data-theme="dark"` is set before mount.
+
+`scripts/smoke-preview.mjs` drives the running preview app (`yarn preview`) with Playwright and checks the overlay
+stack (nested Select / Popover / ConfirmDialog in Modal and Drawer, Escape order, focus trap, placeholder color,
+Spotlight Enter). Run it with `yarn test:preview` once Playwright's Chromium and its system libraries are installed
+(`npx playwright install --with-deps chromium`). Without root access, download the missing libraries
+(`apt-get download libnspr4 libnss3 libasound2`, extract with `dpkg-deb -x`) and point `LD_LIBRARY_PATH` at them;
+`PLAYWRIGHT_CHROMIUM` and `PREVIEW_URL` override the browser binary and the preview address.
+
 ## TypeScript
 
 Full TypeScript support out of the box. Type definitions are included in the package.