@ziyarago/ui 0.15.3 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.16.0](https://github.com/ziyarago/ui/compare/v0.15.3...v0.16.0) (2026-10-21)
+
+### Features
+
+* keyboard and ARIA for Combobox, MultiSelect, Calendar and DatePicker, Tooltip Escape, client-side today, changelog cleanup ([ec905ac](https://github.com/ziyarago/ui/commit/ec905ace4be6d59c884b62941a697b53a2d236b7))
+
 ## [0.15.3](https://github.com/ziyarago/ui/compare/v0.15.2...v0.15.3) (2026-10-21)
 
 ### Bug Fixes
@@ -117,44 +123,3 @@
 ### Features
 
 * publish @ziyarago/ui and @ziyarago/ui-mcp to npm ([bc42145](https://github.com/ziyarago/ui/commit/bc42145f7750fdd8071a29bc088b8366a1adb391))
-
-# Changelog
-
-All notable changes follow [Keep a Changelog](https://keepachangelog.com) and [SemVer](https://semver.org). Pre-1.0: minor versions may break.
-
-## 0.1.0 — first release
-
-### Added
-- Docs site SEO: canonical, Open Graph, Twitter and JSON-LD tags per page, generated `sitemap.xml` and `robots.txt`, 404 page with noindex, og.png, favicon; Google Analytics 4 and Yandex Metrika loaded from build variables.
-- Deployment of the docs to your own server over SSH (releases directory, atomic switch, rollback): `deploy/`, `.github/workflows/deploy-docs.yml`, `docs/DEPLOYMENT.md`.
-- Display settings: `useUiTheme()` gains `setMotion('auto|on|off')`, `setEffects('auto|full|lite')` and `setBackground(name)`; attributes `data-motion`, `data-fx`, `data-bg`; no-flash init script in the Nuxt module.
-- Page backgrounds (`aurora`, `sunset`, `ocean`, `emerald`, `rose`, `mesh`) and gradient cards (`<UiCard variant="gradient" tone intensity>`; 8 tones, soft and vivid, dark and light).
-- API metadata for all 182 components in `src/meta/` (props with every value, defaults, slots, events), validated against the render code by `npm run check`; shown as API reference tables in the docs.
-- AI tooling: `dist/manifest.json`, `llms.txt`, `llms-full.txt` and the `@ziyarago/ui-mcp` package (MCP server + `init` for AGENTS.md, Claude skill, Cursor rule).
-- Automated releases: GitHub Actions + semantic-release (version from commit messages), npm publish with provenance and docs deploy to ziyara.vip. See CONTRIBUTING.md.
-- Page templates gallery in the docs site (`/docs/templates`): 17 live templates in the app shell with top or side menu, slot highlighting and an inspector (accepted components, props, example) for 89 page slots and 5 shell slots.
-- `size` prop (`xs | sm | md | lg | xl`, default `md`) on controls and density-bearing components (about 120). Adapters set `data-size` on the root; `md` keeps the previous look. Scale tokens `--zg-sz-*` live in `tokens.css`, per-group overrides in `src/styles/sizes/`.
-- Popup surfaces (`--zg-pop`), stacking tokens (`--zg-z-bar`, `--zg-z-pop`, `--zg-z-modal`) and entrance motion for selects, calendars, menus, hover cards, modals and drawers.
-- Docs pages for Fonts and Colors (families, tokens, weight mapping, swatches in both themes and both palettes).
-- Documentation site in `site/` (Nuxt): landing, getting started, theming, 182 component pages with live previews and Vue/React code.
-- gluestack parity, 16 components: Heading, Text, Box, Center, HStack, VStack, Grid, Link, Pressable, Icon, Portal, LiquidGlass, BottomSheet, Actionsheet, ImageViewer, ChatAi.
-- Nuxt module `@ziyarago/ui/nuxt` (auto-registered components, CSS, theme attributes, SSR).
-- Framework-neutral core with Vue 3 (`@ziyarago/ui/vue`) and React 18+ (`@ziyarago/ui/react`) adapters.
-- 160+ components in 12 groups: actions, forms, surfaces, data, navigation, layout, CRM, hotels, tours and 360°, prayer and Ramadan.
-- 16 page templates with named slots (`PageDashboard`, `PageCrm`, `PageBookings`, `PageCatalog`, `PageDetail`, `PageSettings`, `PageUserList`, `PageProfile`, `PageForm`, `PageOrder`, `PageAccount`, `PagePricing`, `PageFaq`, `PagePatterns`, `PageAuth`, `PageStatus`).
-- Two menus in one shell: top and side, with a collapsible sidebar.
-- OKLCH tokens, palettes `gold` and `tamam`, dark and light themes, RTL, Thmanyah and Manrope.
-- Validation rules (`rules`) and `ValidatedField`.
-- `UiMap`, `UiTour` with spotlight, `UiSortable`, `UiTreeSelect`, `UiRichEditor`.
-- `tokens/tokens.json` for Flutter and native clients; `dist/style.css` single-file stylesheet.
-
-### Known gaps
-- Props are typed for 9 core components; the rest accept `Record<string, any>`.
-- Installed from the packed tarball into clean Vite+Vue, Vite+React and Nuxt 3 apps: all build, Nuxt SSR renders. No automated tests yet.
-- Light theme and RTL are covered by tokens but not yet screenshot-tested for every component.
-
-### Fixed before release
-- Arabic looked bold: Thmanyah has no 600 face and is heavier than Manrope. `fonts.css` now maps weights with ranges (200-300 Light, 400-600 Regular, 700 Medium, 800 Bold, 900 Black).
-- Light theme: stronger card separation (`--zg-s1/s2/s3`, `--zg-stroke`, `--zg-rim`, `--zg-shadow-1`); `UiCard variant="inverse"` re-scopes tokens to dark so content inside stays readable; bell counter and incoming-call button text contrast.
-- `Page*` templates with `title` crashed in Vue/React (`C.PageHeader` was called as a function).
-- `useUiTheme()` and `UiMap` touched `document` during SSR.

package/dist/llms-full.txt

@@ -2,7 +2,7 @@
 
 > ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 102 free components and 6 page templates (more in @ziyarago/ui-pro).
 
-Version 0.15.3. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
+Version 0.16.0. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
 
 ## Setup
 - import { UiButton } from '@ziyarago/ui/vue'
@@ -674,6 +674,7 @@ Events:
 Notes:
 - Selecting from the list is the only way to set a value: free text is never emitted.
 - The list closes on outside click and on Escape.
+- Keyboard (WAI-ARIA combobox): the input has role=combobox with aria-expanded, aria-controls and aria-activedescendant; focus stays in the input, Arrow Down and Up open the list and move the active option (wraps, skips disabled), Enter chooses it, Escape closes.
 
 ## UiTreeSelect  (forms, Pro)
 Dropdown with a searchable tree. Use for hierarchical choices such as regions, categories or org units.
@@ -836,12 +837,14 @@ Props:
 - `min`: Date | string | number. Earliest selectable day; earlier days are disabled.
 - `max`: Date | string | number. Latest selectable day; later days are disabled.
 - `disabledDate`: (date: Date) => boolean. Return true to disable a specific day.
+- `today`: Date | string | number. The day marked as today. By default it is read from the browser clock after mount (nothing is marked in server-rendered HTML), so server and client never disagree near midnight or across time zones. Pass it to mark a day in the HTML too.
 - `events`: Record<string, string> = "{}". Marked days: keys are YYYY-MM-DD, values are the tooltip text.
 - `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = "md". Day cell and header size.
 Events:
 - change: Called with a Date object (local time) for the clicked day.
 Notes:
 - The event payload is a Date, not a string: convert to ISO yourself if the model is a string.
+- Keyboard: one tab stop on the day grid; arrows move by day or week, Home and End to the week start and end, PageUp and PageDown change month (Shift: year), Enter or Space picks. Without a selected date the visible month is the current month, which server and client can disagree on right at a month boundary; pass modelValue or today to make it deterministic.
 
 ## UiRangeCalendar  (forms, Pro)
 Month grid for picking a date range with hover preview. Use for stays, trips and report periods.
@@ -866,6 +869,7 @@ Props:
 - `min`: Date | string | number. Earliest selectable day, forwarded to the calendar.
 - `max`: Date | string | number. Latest selectable day, forwarded to the calendar.
 - `disabledDate`: (date: Date) => boolean. Return true to disable a specific day, forwarded to the calendar.
+- `today`: Date | string | number. The day marked as today in the calendar; by default read from the browser clock after mount. Forwarded to the calendar.
 - `required`: boolean = false. Adds a red asterisk to the label. Does not validate.
 - `label`: string. Label shown above the control.
 - `hint`: string. Helper text under the control. Hidden while error is set.
@@ -877,7 +881,7 @@ Events:
 - change: Called with a Date object (local midnight) for the chosen day. The popup closes after picking.
 Notes:
 - The event payload is a Date, not a string: convert to ISO yourself if the model is a string.
-- The popup closes on outside click and on Escape.
+- The popup closes on outside click and on Escape (focus returns to the trigger). Arrow Down or Up on the trigger opens it and focus moves into the calendar, which uses the Calendar keys.
 
 ## UiTimePicker  (forms)
 Hour and minute selects for a time of day. Use for opening hours and appointment times.
@@ -1596,6 +1600,7 @@ Slots:
 - default: The element the tooltip is attached to.
 Notes:
 - Pure CSS bubble; it cannot contain markup. For rich content use HoverCard.
+- Escape hides the bubble while it is shown (hover or focus) without moving focus; it stays visible while the pointer is over the trigger or the bubble, and returns on the next hover or focus.
 
 ## UiDropdown  (overlay)
 Button that opens a menu of actions; use for "more" menus and action lists.
@@ -1696,11 +1701,12 @@ Events:
 - close: Close icon.
 
 ## UiScreensaver  (overlay, Pro)
-Full-screen idle screen with a large clock, date and the brand mark; show it after inactivity.
+Full-screen idle screen with a large clock, date and an optional logo; show it after inactivity.
 Props:
 - `open`: boolean = false. Shows the screensaver when true; renders nothing when false.
 - `locale`: string = "en-GB". BCP 47 locale for the date line.
 - `hint`: string. Small hint under the date, e.g. "Tap to continue".
+- `logo`: string. URL of an image shown above the clock. Use an absolute URL or a root-relative path such as "/brand/logo.svg". Nothing is shown when it is not set, so the screensaver never requests a missing file.
 - `idleMs`: number = 0. When greater than 0 and the screensaver is closed, a hidden sentinel listens for pointer, key, wheel and touch activity and calls idle after this many milliseconds without any. 0 disables it.
 Events:
 - close: Called on click or any key (including Escape) while open.

package/dist/llms.txt

@@ -2,7 +2,7 @@
 
 > ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 102 free components and 6 page templates (more in @ziyarago/ui-pro).
 
-Version 0.15.3. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
+Version 0.16.0. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
 
 ## Setup
 - import { UiButton } from '@ziyarago/ui/vue'
@@ -170,7 +170,7 @@ Dialogs, sheets and popovers.
 - UiImageViewer (Pro): Full-screen lightbox for one or several images with previous/next buttons and a counter.
 - UiTour (Pro): Guided product tour that dims the page, highlights a target element and shows a step popover.
 - UiTourPopover (Pro): Step card of a tour with title, text, step counter and Back/Next buttons; used by Tour and usable standalone.
-- UiScreensaver (Pro): Full-screen idle screen with a large clock, date and the brand mark; show it after inactivity.
+- UiScreensaver (Pro): Full-screen idle screen with a large clock, date and an optional logo; show it after inactivity.
 
 ## Navigation
 Menus, tabs and paging.

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
  "name": "@ziyarago/ui",
- "version": "0.15.3",
+ "version": "0.16.0",
  "homepage": "https://ziyara.vip",
  "imports": {
   "vue": "import { UiButton } from '@ziyarago/ui/vue'",
@@ -7834,7 +7834,8 @@
    },
    "notes": [
     "Selecting from the list is the only way to set a value: free text is never emitted.",
-    "The list closes on outside click and on Escape."
+    "The list closes on outside click and on Escape.",
+    "Keyboard (WAI-ARIA combobox): the input has role=combobox with aria-expanded, aria-controls and aria-activedescendant; focus stays in the input, Arrow Down and Up open the list and move the active option (wraps, skips disabled), Enter chooses it, Escape closes."
    ]
   },
   {
@@ -8480,6 +8481,10 @@
      "type": "(date: Date) => boolean",
      "description": "Return true to disable a specific day."
     },
+    "today": {
+     "type": "Date | string | number",
+     "description": "The day marked as today. By default it is read from the browser clock after mount (nothing is marked in server-rendered HTML), so server and client never disagree near midnight or across time zones. Pass it to mark a day in the HTML too."
+    },
     "events": {
      "type": "Record<string, string>",
      "default": "{}",
@@ -8502,7 +8507,8 @@
     "change": "Called with a Date object (local time) for the clicked day."
    },
    "notes": [
-    "The event payload is a Date, not a string: convert to ISO yourself if the model is a string."
+    "The event payload is a Date, not a string: convert to ISO yourself if the model is a string.",
+    "Keyboard: one tab stop on the day grid; arrows move by day or week, Home and End to the week start and end, PageUp and PageDown change month (Shift: year), Enter or Space picks. Without a selected date the visible month is the current month, which server and client can disagree on right at a month boundary; pass modelValue or today to make it deterministic."
    ]
   },
   {
@@ -8596,6 +8602,11 @@
      "forwarded": true,
      "description": "Return true to disable a specific day, forwarded to the calendar."
     },
+    "today": {
+     "type": "Date | string | number",
+     "forwarded": true,
+     "description": "The day marked as today in the calendar; by default read from the browser clock after mount. Forwarded to the calendar."
+    },
     "required": {
      "type": "boolean",
      "default": false,
@@ -8644,7 +8655,7 @@
    },
    "notes": [
     "The event payload is a Date, not a string: convert to ISO yourself if the model is a string.",
-    "The popup closes on outside click and on Escape."
+    "The popup closes on outside click and on Escape (focus returns to the trigger). Arrow Down or Up on the trigger opens it and focus moves into the calendar, which uses the Calendar keys."
    ]
   },
   {
@@ -11378,7 +11389,8 @@
     "default": "The element the tooltip is attached to."
    },
    "notes": [
-    "Pure CSS bubble; it cannot contain markup. For rich content use HoverCard."
+    "Pure CSS bubble; it cannot contain markup. For rich content use HoverCard.",
+    "Escape hides the bubble while it is shown (hover or focus) without moving focus; it stays visible while the pointer is over the trigger or the bubble, and returns on the next hover or focus."
    ]
   },
   {
@@ -11688,7 +11700,7 @@
    "tier": "pro",
    "implemented": false,
    "package": "@ziyarago/ui-pro",
-   "description": "Full-screen idle screen with a large clock, date and the brand mark; show it after inactivity.",
+   "description": "Full-screen idle screen with a large clock, date and an optional logo; show it after inactivity.",
    "props": {
     "open": {
      "type": "boolean",
@@ -11704,6 +11716,10 @@
      "type": "string",
      "description": "Small hint under the date, e.g. \"Tap to continue\"."
     },
+    "logo": {
+     "type": "string",
+     "description": "URL of an image shown above the clock. Use an absolute URL or a root-relative path such as \"/brand/logo.svg\". Nothing is shown when it is not set, so the screensaver never requests a missing file."
+    },
     "idleMs": {
      "type": "number",
      "default": 0,

package/dist/style.css

@@ -570,6 +570,13 @@
 .zg-sr{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0}
 .zg-select__opt:focus-visible{outline:3px solid var(--zg-brand-soft);outline-offset:-3px;background:var(--zg-s2)}
 .zg-seg button:focus-visible,.zg-tabs button:focus-visible,.zg-code-b pre:focus-visible{outline:3px solid var(--zg-brand-soft);outline-offset:2px}
+.zg-select__opt[data-active],.zg-select__opt[data-active]:hover{background:var(--zg-s2);outline:3px solid var(--zg-brand-soft);outline-offset:-3px}
+.zg-tip:hover::after,.zg-tip:focus-visible::after{pointer-events:auto}
+.zg-tip:hover::before{content:"";position:absolute;left:0;right:0;bottom:100%;height:10px}
+.zg-tip--bottom:hover::before{bottom:auto;top:100%}
+.zg-tip--left:hover::before,.zg-tip--right:hover::before{top:0;bottom:0;height:auto;width:10px}
+.zg-tip--left:hover::before{left:auto;right:100%}.zg-tip--right:hover::before{right:auto;left:100%}
+.zg-tip[data-tip-off]::after{opacity:0!important;pointer-events:none!important}.zg-tip[data-tip-off]::before{display:none}
 
 
 /* ./sizes/typography.css */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziyarago/ui",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 102 free components and 6 page templates (more in @ziyarago/ui-pro).",
   "keywords": [
     "ui",

package/src/core/components2.js

@@ -1,11 +1,16 @@
 // @ziyarago/ui · components, part 2 — Forms, Surfaces, Actions, Data, Navigation, Layout, CRM, Hotels.
 import { icon, cx, ddRef, pick, INPUT_ATTRS } from './components.js';
 import { trap } from './dialog.js';
-import { listKeys, openKeys, tabIdx, toTrigger, trigger } from './keys.js';
+import { listKeys, openKeys, tabIdx, toTrigger, trigger, calKeys, dateKey } from './keys.js';
 const tipId = s => { let x = 5381; for (const c of String(s)) x = (x * 33 ^ c.charCodeAt(0)) >>> 0; return 'zg-tip-' + x.toString(36); };
-let tipN = 0;
+let tipN = 0, cbN = 0;
+const tipScroll = el => { if (el && el.scrollIntoView) el.scrollIntoView({ block: 'nearest' }); };
 // Same text twice on one page would repeat the id: the later tooltip gets a unique one (browser only, after mount).
 const tipRef = el => { const s = el && el.lastElementChild; if (!s || !s.id || typeof document === 'undefined') return; const same = document.querySelectorAll('[id="' + s.id + '"]'); if (same.length > 1 && same[0] !== s) { s.id += '-' + (++tipN); el.setAttribute('aria-describedby', s.id); } };
+// WCAG 1.4.13: while the tip is shown (hover or keyboard focus) Escape hides it without moving focus; it comes back on the next hover or focus.
+const tipEsc = el => ev => { if (ev.key === 'Escape') el.setAttribute('data-tip-off', ''); };
+const tipShow = e => { const el = e.currentTarget; if (e.type === 'mouseenter' || e.type === 'focus') el.removeAttribute('data-tip-off'); if (!el._zgTip) { el._zgTip = tipEsc(el); document.addEventListener('keydown', el._zgTip); } };
+const tipHide = (e, still) => { const el = e.currentTarget; if (el.matches(still)) return; if (el._zgTip) document.removeEventListener('keydown', el._zgTip); el._zgTip = null; el.removeAttribute('data-tip-off'); };
 import { t, getUiLocale, intlLocale } from '../i18n/index.js';
 const dloc = p => p.locale || (getUiLocale() === 'en' ? 'en-GB' : intlLocale());
 const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
@@ -35,7 +40,7 @@ export const more = {
   /* ── Actions ── */
   Dropdown: { state: { open: false }, render: ({ h, props: p, state, set }) => h('div', { class: 'zg-dd' }, h('button', { type: 'button', class: cx('zg-btn', p.size && 'zg-btn--' + p.size), 'aria-haspopup': 'menu', 'aria-expanded': String(state.open && !p.disabled), disabled: p.disabled, onClick: () => set({ open: !state.open }), onKeydown: openKeys(state.open && !p.disabled, () => set({ open: true })) }, p.icon ? icon(h, p.icon, 16) : null, p.label, icon(h, 'chevron-down', 14)), state.open && !p.disabled ? h('div', { class: 'zg-menu', role: 'menu', 'data-zg-dd': '', ref: ddRef(() => set({ open: false }), { focus: true }), onKeydown: listKeys('[role=menuitem]', { wrap: true, onTab: e => { const t = trigger(e.currentTarget); t && t.focus(); set({ open: false }); } }) }, ...(p.items || []).map((it, i, all) => it.separator ? h('div', { key: i, class: 'zg-menu__sep', role: 'separator' }) : h('button', { key: i, type: 'button', role: 'menuitem', tabIndex: tabIdx(all.map(x => ({ disabled: x.separator || x.disabled })), () => false)(i), disabled: it.disabled, 'aria-disabled': it.disabled ? 'true' : undefined, class: cx('zg-menu__i', it.tone === 'danger' && 'zg-menu__i--danger'), onClick: e => { toTrigger(e); set({ open: false }); it.onClick && it.onClick(it); p.onSelect && p.onSelect(it.value); } }, it.icon ? icon(h, it.icon, 16) : null, it.label, it.shortcut ? h('span', { class: 'zg-kbd' }, it.shortcut) : null))) : null) },
   Menu: { render: ({ h, props: p }) => p.open === false ? null : h('div', { class: 'zg-menu zg-menu--static', role: 'menu', 'data-zg-dd': '', ref: p.open === true && p.onClose ? ddRef(p.onClose, { self: true, focus: true }) : undefined, onKeydown: listKeys('[role=menuitem]', { wrap: true, onTab: () => p.onClose && p.onClose() }) }, ...(p.items || []).map((it, i, all) => it.separator ? h('div', { key: i, class: 'zg-menu__sep', role: 'separator' }) : h('button', { key: i, type: 'button', role: 'menuitem', tabIndex: tabIdx(all.map(x => ({ disabled: x.separator || x.disabled })), () => false)(i), disabled: it.disabled, 'aria-disabled': it.disabled ? 'true' : undefined, class: cx('zg-menu__i', it.tone === 'danger' && 'zg-menu__i--danger'), onClick: () => { it.onClick && it.onClick(it); p.onSelect && p.onSelect(it.value); } }, it.icon ? icon(h, it.icon, 16) : null, it.label, it.shortcut ? h('span', { class: 'zg-kbd' }, it.shortcut) : null))) },
-  Tooltip: { render: ({ h, props: p, children }) => h('span', { class: cx('zg-tip', p.placement && p.placement !== 'top' && 'zg-tip--' + p.placement), 'data-tip': p.text, tabIndex: 0, 'aria-describedby': p.text ? tipId(p.text) : undefined, ref: p.text ? tipRef : undefined }, ...children, p.text ? h('span', { id: tipId(p.text), role: 'tooltip', class: 'zg-sr' }, p.text) : null) },
+  Tooltip: { render: ({ h, props: p, children }) => h('span', { class: cx('zg-tip', p.placement && p.placement !== 'top' && 'zg-tip--' + p.placement), 'data-tip': p.text, tabIndex: 0, 'aria-describedby': p.text ? tipId(p.text) : undefined, ref: p.text ? tipRef : undefined, onMouseenter: tipShow, onFocus: tipShow, onMouseleave: e => tipHide(e, ':focus-visible'), onBlur: e => tipHide(e, ':hover') }, ...children, p.text ? h('span', { id: tipId(p.text), role: 'tooltip', class: 'zg-sr' }, p.text) : null) },
   Popover: { state: { open: false }, render: ({ C, h, props: p, state, set, children }) => h('span', { class: 'zg-dd' }, h(C.Button, { size: p.size, onClick: () => set({ open: !state.open }) }, p.label), state.open ? h('div', { class: 'zg-pop zg-glass', 'data-zg-dd': '', ref: ddRef(() => set({ open: false })) }, ...children) : null) },
   CopyButton: { state: { done: false, err: false }, render: ({ C, h, props: p, state, set }) => { const reset = () => setTimeout(() => set({ done: false, err: false }), 1500), fail = e => { set({ done: false, err: true }); p.onError && p.onError(e); reset(); }, ok = () => { set({ done: true, err: false }); p.onCopy && p.onCopy(p.value); reset(); };
     const msg = state.err ? t('CopyButton', 'failed') : state.done ? t('CopyButton', 'copied') : '';
@@ -62,21 +67,28 @@ export const more = {
   FileUpload: { state: { drag: false }, render: ({ h, props: p, state, set }) => { const ac = String(p.accept || '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean), okType = f => !ac.length || ac.some(a => a[0] === '.' ? f.name.toLowerCase().endsWith(a) : a.endsWith('/*') ? (f.type || '').toLowerCase().startsWith(a.slice(0, -1)) : (f.type || '').toLowerCase() === a), rej = (f, r) => p.onReject && p.onReject(f, r),
     take = list => { const ok = []; for (const f of list) { if (!okType(f)) rej(f, 'type'); else if (p.maxSize && f.size > p.maxSize) rej(f, 'size'); else ok.push(f); } if (!p.multiple) ok.slice(1).forEach(f => rej(f, 'count')); const out = p.multiple ? ok : ok.slice(0, 1); if (out.length && p.onChange) p.onChange(out); }, pick = e => { const i = e.currentTarget.querySelector('input'); if (i) i.click(); };
     return h('div', { class: 'zg-field' }, p.label ? h('span', { class: 'zg-label' }, p.label) : null, h('div', { class: 'zg-fdrop', role: 'button', tabIndex: 0, 'aria-label': p.title || t('FileUpload', 'title'), 'data-drag': state.drag ? '' : undefined, onClick: pick, onKeydown: e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); pick(e); } }, onDragenter: e => { e.preventDefault(); if (!state.drag) set({ drag: true }); }, onDragover: e => { e.preventDefault(); if (e.dataTransfer) e.dataTransfer.dropEffect = 'copy'; if (!state.drag) set({ drag: true }); }, onDragleave: e => { if (!e.currentTarget.contains(e.relatedTarget)) set({ drag: false }); }, onDrop: e => { e.preventDefault(); set({ drag: false }); take([...(e.dataTransfer ? e.dataTransfer.files : [])]); } }, icon(h, p.image ? 'image-up' : 'upload', 24), h('b', null, p.title || t('FileUpload', 'title')), h('span', { class: 'zg-hint' }, p.hint || t('FileUpload', 'hint')), h('input', { type: 'file', multiple: p.multiple, accept: p.accept, tabIndex: -1, 'aria-hidden': 'true', style: { display: 'none' }, onClick: e => e.stopPropagation(), onChange: e => { take([...e.target.files]); e.target.value = ''; } })), p.error ? h('span', { class: 'zg-hint zg-hint--error', role: 'alert' }, p.error) : null); } },
-  Combobox: { state: { open: false, q: '' }, render: ({ h, props: p, state, set }) => { const cur = (p.options || []).find(o => o.value === p.modelValue), f = (p.options || []).filter(o => !state.q || (p.filter ? p.filter(o, state.q) : o.label.toLowerCase().includes(state.q.toLowerCase())));
-    return lab(h, p, h('div', { class: 'zg-select' }, field(h, p, icon(h, 'search', 16), h('input', { value: state.open && !p.disabled ? state.q : (cur ? cur.label : ''), disabled: p.disabled, placeholder: p.placeholder || t('Combobox', 'placeholder'), onFocus: () => set({ open: true, q: '' }), onInput: e => set({ q: e.target.value, open: true }) }), [p.clearable && cur && !p.disabled ? h('button', { key: 'x', type: 'button', class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('Combobox', 'clear'), onMouseDown: e => e.preventDefault(), onClick: () => { set({ open: false, q: '' }); p.onChange && p.onChange(null); } }, icon(h, 'x', 14)) : null, icon(h, 'chevron-down', 16)]),
-      state.open && !p.disabled ? h('div', { class: 'zg-select__list', role: 'listbox', 'aria-label': p.label || p.placeholder, 'data-zg-dd': '', ref: ddRef(() => set({ open: false, q: '' })) }, ...(f.length ? f.map(o => h('button', { key: o.value, type: 'button', role: 'option', class: 'zg-select__opt', disabled: o.disabled, 'aria-disabled': o.disabled ? 'true' : undefined, 'aria-selected': String(o.value === p.modelValue), onMouseDown: e => e.preventDefault(), onClick: () => { set({ open: false, q: '' }); p.onChange && p.onChange(o.value); } }, o.label)) : [h('div', { key: 'e', class: 'zg-empty' }, p.emptyText || '—')])) : null)); } },
+  Combobox: { state: { open: false, q: '', ai: -1, id: '' }, render: ({ h, props: p, state, set }) => { const all = p.options || [], cur = all.find(o => o.value === p.modelValue), f = all.filter(o => !state.q || (p.filter ? p.filter(o, state.q) : o.label.toLowerCase().includes(state.q.toLowerCase()))), open = state.open && !p.disabled, id = state.id, oid = i => id + '-o' + i, lid = id + '-l';
+    const op = o => set({ open: true, id: id || 'zg-cb' + (++cbN), ...o }), pickO = o => { set({ open: false, q: '', ai: -1 }); p.onChange && p.onChange(o.value); };
+    const step = d => { const ok = f.map((o, i) => i).filter(i => !f[i].disabled); if (!ok.length) return; const k = ok.indexOf(state.ai); op({ ai: ok[k < 0 ? (d > 0 ? 0 : ok.length - 1) : (k + d + ok.length) % ok.length] }); };
+    const keys = e => { if (e.altKey || e.ctrlKey || e.metaKey || p.disabled) return;
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { e.preventDefault(); if (!open) { const ok = f.map((o, i) => i).filter(i => !f[i].disabled), i = f.findIndex(o => o.value === p.modelValue && !o.disabled); op({ q: '', ai: i >= 0 ? i : ok.length ? (e.key === 'ArrowDown' ? ok[0] : ok[ok.length - 1]) : -1 }); } else step(e.key === 'ArrowDown' ? 1 : -1); }
+      else if (e.key === 'Enter' && open && f[state.ai] && !f[state.ai].disabled) { e.preventDefault(); pickO(f[state.ai]); } };
+    return lab(h, p, h('div', { class: 'zg-select' }, field(h, p, icon(h, 'search', 16), h('input', { role: 'combobox', 'aria-autocomplete': 'list', 'aria-haspopup': 'listbox', 'aria-expanded': String(open), 'aria-controls': open ? lid : undefined, 'aria-activedescendant': open && f[state.ai] ? oid(state.ai) : undefined, autoComplete: 'off', value: open ? state.q : (cur ? cur.label : ''), disabled: p.disabled, placeholder: p.placeholder || t('Combobox', 'placeholder'), onFocus: () => op({ q: '', ai: -1 }), onKeydown: keys, onInput: e => op({ q: e.target.value, ai: -1 }) }), [p.clearable && cur && !p.disabled ? h('button', { key: 'x', type: 'button', class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('Combobox', 'clear'), onMouseDown: e => e.preventDefault(), onClick: () => { set({ open: false, q: '', ai: -1 }); p.onChange && p.onChange(null); } }, icon(h, 'x', 14)) : null, icon(h, 'chevron-down', 16)]),
+      open ? h('div', { id: lid, class: 'zg-select__list', role: 'listbox', 'aria-label': p.label || p.placeholder, 'data-zg-dd': '', ref: ddRef(() => set({ open: false, q: '', ai: -1 })) }, ...(f.length ? f.map((o, i) => h('button', { key: o.value, id: oid(i), type: 'button', role: 'option', tabIndex: -1, class: 'zg-select__opt', 'data-active': i === state.ai ? '' : undefined, ref: i === state.ai ? tipScroll : undefined, disabled: o.disabled, 'aria-disabled': o.disabled ? 'true' : undefined, 'aria-selected': String(o.value === p.modelValue), onMouseDown: e => e.preventDefault(), onClick: () => pickO(o) }, o.label)) : [h('div', { key: 'e', class: 'zg-empty' }, p.emptyText || '—')])) : null)); } },
   MultiSelect: { state: { open: false }, render: ({ h, props: p, state, set }) => { const v = p.modelValue || [], tog = x => p.onChange && p.onChange(v.includes(x) ? v.filter(i => i !== x) : [...v, x]);
-    return h('div', { class: 'zg-field' }, p.label ? h('span', { class: 'zg-label' }, p.label) : null, h('div', { class: 'zg-select' }, h('button', { type: 'button', class: 'zg-btn zg-select__trigger', 'aria-haspopup': 'listbox', 'aria-expanded': String(state.open && !p.disabled), disabled: p.disabled, style: { height: 'var(--zg-h-lg)' }, onClick: () => set({ open: !state.open }) }, h('span', null, v.length ? t('MultiSelect', 'selected', { n: v.length }) : (p.placeholder || '—')), icon(h, 'chevron-down', 16)),
-      state.open && !p.disabled ? h('div', { class: 'zg-select__list', role: 'listbox', 'aria-label': p.label || p.placeholder, 'aria-multiselectable': 'true', 'data-zg-dd': '', ref: ddRef(() => set({ open: false })) }, ...(p.options || []).map(o => h('button', { key: o.value, type: 'button', role: 'option', class: 'zg-select__opt', disabled: o.disabled, 'aria-disabled': o.disabled ? 'true' : undefined, 'aria-selected': String(v.includes(o.value)), onClick: () => tog(o.value) }, h('span', { class: 'zg-check__box', style: { width: '18px', height: '18px', borderRadius: '6px', background: v.includes(o.value) ? 'var(--zg-brand)' : 'transparent' } }, v.includes(o.value) ? icon(h, 'check', 12) : null), h('span', { style: { flex: 1, marginInlineStart: '10px' } }, o.label)))) : null)); } },
+    return h('div', { class: 'zg-field' }, p.label ? h('span', { class: 'zg-label' }, p.label) : null, h('div', { class: 'zg-select' }, h('button', { type: 'button', class: 'zg-btn zg-select__trigger', 'aria-haspopup': 'listbox', 'aria-expanded': String(state.open && !p.disabled), disabled: p.disabled, style: { height: 'var(--zg-h-lg)' }, onClick: () => set({ open: !state.open }), onKeydown: openKeys(state.open && !p.disabled, () => set({ open: true })) }, h('span', null, v.length ? t('MultiSelect', 'selected', { n: v.length }) : (p.placeholder || '—')), icon(h, 'chevron-down', 16)),
+      state.open && !p.disabled ? h('div', { class: 'zg-select__list', role: 'listbox', 'aria-label': p.label || p.placeholder, 'aria-multiselectable': 'true', 'data-zg-dd': '', ref: ddRef(() => set({ open: false }), { focus: true }), onKeydown: listKeys('[role=option]', { onTab: e => { const t = trigger(e.currentTarget); t && t.focus(); set({ open: false }); } }) }, ...(p.options || []).map((o, i, all) => h('button', { key: o.value, type: 'button', role: 'option', tabIndex: tabIdx(all, x => v.includes(x.value))(i), class: 'zg-select__opt', disabled: o.disabled, 'aria-disabled': o.disabled ? 'true' : undefined, 'aria-selected': String(v.includes(o.value)), onClick: () => tog(o.value) }, h('span', { class: 'zg-check__box', style: { width: '18px', height: '18px', borderRadius: '6px', background: v.includes(o.value) ? 'var(--zg-brand)' : 'transparent' } }, v.includes(o.value) ? icon(h, 'check', 12) : null), h('span', { style: { flex: 1, marginInlineStart: '10px' } }, o.label)))) : null)); } },
   PhoneInput: { render: ({ C, h, props: p }) => { const CC = p.countries || [{ value: '+966', label: 'SA +966' }, { value: '+998', label: 'UZ +998' }, { value: '+7', label: 'RU +7' }, { value: '+90', label: 'TR +90' }, { value: '+20', label: 'EG +20' }], v = p.modelValue || {};
     return h('div', { class: 'zg-field' }, p.label ? h('span', { class: 'zg-label' }, p.label) : null, h('div', { style: { display: 'grid', gridTemplateColumns: '130px minmax(0,1fr)', gap: '8px', alignItems: 'start' } }, h(C.Select, { options: CC, modelValue: v.code || CC[0].value, onChange: c => p.onChange && p.onChange({ ...v, code: c }) }), field(h, p, icon(h, 'phone', 16), h('input', { type: 'tel', inputMode: 'tel', value: v.number || '', placeholder: p.placeholder ?? '90 123 45 67', onInput: e => p.onChange && p.onChange({ ...v, number: e.target.value }) }))), typeof p.error === 'string' && p.error ? h('span', { class: 'zg-hint zg-hint--error', role: 'alert' }, p.error) : p.hint ? h('span', { class: 'zg-hint' }, p.hint) : null); } },
-  Calendar: { state: { ym: null }, render: ({ h, props: p, state, set }) => { const s = pd(p.modelValue), b = state.ym ? new Date(state.ym) : (s || new Date()), y = b.getFullYear(), m = b.getMonth(), loc = dloc(p), ws = p.weekStartsOn ?? 1, off = (new Date(y, m, 1).getDay() - ws + 7) % 7, dn = new Date(y, m + 1, 0).getDate(), today = new Date();
+  Calendar: { state: { ym: null, fd: null, today: null }, render: ({ h, props: p, state, set }) => { const s = pd(p.modelValue), now = pd(p.today) || (state.today ? new Date(state.today) : null), b = state.ym ? new Date(state.ym) : (s || now || new Date()), y = b.getFullYear(), m = b.getMonth(), loc = dloc(p), ws = p.weekStartsOn ?? 1, off = (new Date(y, m, 1).getDay() - ws + 7) % 7, dn = new Date(y, m + 1, 0).getDate(), today = now, ml = new Intl.DateTimeFormat(loc, { month: 'long', year: 'numeric' }).format(b);
     const wd = Array.from({ length: 7 }, (_, i) => new Intl.DateTimeFormat(loc, { weekday: 'narrow' }).format(new Date(2023, 0, 1 + ((i + ws) % 7))));
-    const same = (a, d) => a && a.getFullYear() === y && a.getMonth() === m && a.getDate() === d, ev = p.events || {}, lo = pd(p.min), hi = pd(p.max), day0 = x => new Date(x.getFullYear(), x.getMonth(), x.getDate()), blocked = d => { const t = new Date(y, m, d); return !!((lo && t < day0(lo)) || (hi && t > day0(hi)) || (p.disabledDate && p.disabledDate(t))); };
-    return h('div', { class: 'zg-cal' }, h('div', { class: 'zg-cal__h' }, h('button', { type: 'button', class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('Calendar', 'prev'), onClick: () => set({ ym: new Date(y, m - 1, 1).getTime() }) }, icon(h, 'chevron-left', 16)), h('b', null, new Intl.DateTimeFormat(loc, { month: 'long', year: 'numeric' }).format(b)), h('button', { type: 'button', class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('Calendar', 'next'), onClick: () => set({ ym: new Date(y, m + 1, 1).getTime() }) }, icon(h, 'chevron-right', 16))),
-      h('div', { class: 'zg-cal__g' }, ...wd.map((d, i) => h('span', { key: 'w' + i, class: 'zg-cal__w' }, d)), ...Array.from({ length: off }, (_, i) => h('span', { key: 'o' + i })), ...Array.from({ length: dn }, (_, i) => { const d = i + 1, key = `${y}-${String(m + 1).padStart(2, '0')}-${String(d).padStart(2, '0')}`; return h('button', { key: d, type: 'button', class: 'zg-cal__d', 'aria-pressed': String(!!same(s, d)), 'data-today': String(same(today, d)), 'data-ev': ev[key] ? '' : undefined, title: ev[key] || undefined, disabled: blocked(d) || undefined, onClick: () => !blocked(d) && p.onChange && p.onChange(new Date(y, m, d)) }, d); }))); } },
-  DatePicker: { state: { open: false }, render: ({ C, h, props: p, state, set }) => lab(h, p, h('div', { class: 'zg-select' }, h('button', { type: 'button', class: 'zg-btn zg-select__trigger', 'aria-haspopup': 'dialog', 'aria-expanded': String(state.open && !p.disabled), disabled: p.disabled, style: { height: 'var(--zg-h-lg)' }, onClick: () => set({ open: !state.open }) }, h('span', { style: { display: 'flex', gap: '10px', alignItems: 'center' } }, icon(h, 'calendar', 16), p.modelValue ? new Intl.DateTimeFormat(dloc(p), { dateStyle: 'medium' }).format(pd(p.modelValue) || new Date()) : (p.placeholder || t('DatePicker', 'placeholder'))), h('span', { style: { display: 'flex', alignItems: 'center', gap: '6px' } }, p.clearable && p.modelValue && !p.disabled ? h('span', { role: 'button', tabIndex: 0, class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('DatePicker', 'clear'), onClick: e => { e.stopPropagation(); p.onChange && p.onChange(null); }, onKeydown: e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); e.stopPropagation(); p.onChange && p.onChange(null); } } }, icon(h, 'x', 14)) : null, icon(h, 'chevron-down', 16))),
-    state.open && !p.disabled ? h('div', { class: 'zg-select__list', 'data-zg-dd': '', ref: ddRef(() => set({ open: false })), style: { padding: '12px' } }, h(C.Calendar, { modelValue: p.modelValue, locale: p.locale, weekStartsOn: p.weekStartsOn, min: p.min, max: p.max, disabledDate: p.disabledDate, onChange: d => { set({ open: false }); p.onChange && p.onChange(d); } })) : null)) },
+    const same = (a, d) => a && a.getFullYear() === y && a.getMonth() === m && a.getDate() === d, ev = p.events || {}, lo = pd(p.min), hi = pd(p.max), day0 = x => new Date(x.getFullYear(), x.getMonth(), x.getDate()), blockedAt = t => !!((lo && t < day0(lo)) || (hi && t > day0(hi)) || (p.disabledDate && p.disabledDate(t))), blocked = d => blockedAt(new Date(y, m, d));
+    const mk = d => dateKey(new Date(y, m, d)), fk = state.fd && state.fd.slice(0, 7) === mk(1).slice(0, 7) ? +state.fd.slice(8) : 0;
+    const fd = [fk, same(s, s && s.getDate()) ? s.getDate() : 0, same(today, today && today.getDate()) ? today.getDate() : 0, 1].find(d => d && !blocked(d)) || Array.from({ length: dn }, (_, i) => i + 1).find(d => !blocked(d));
+    return h('div', { class: 'zg-cal', ref: p.today == null && state.today == null ? (el => { if (el) Promise.resolve().then(() => set({ today: Date.now() })); }) : undefined }, h('div', { class: 'zg-cal__h' }, h('button', { type: 'button', class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('Calendar', 'prev'), onClick: () => set({ ym: new Date(y, m - 1, 1).getTime() }) }, icon(h, 'chevron-left', 16)), h('b', { 'aria-live': 'polite' }, ml), h('button', { type: 'button', class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('Calendar', 'next'), onClick: () => set({ ym: new Date(y, m + 1, 1).getTime() }) }, icon(h, 'chevron-right', 16))),
+      h('div', { class: 'zg-cal__g', role: 'group', 'aria-label': ml, onKeydown: calKeys({ ws, blocked: blockedAt, show: (t, k) => set({ ym: new Date(t.getFullYear(), t.getMonth(), 1).getTime(), fd: k }) }) }, ...wd.map((d, i) => h('span', { key: 'w' + i, class: 'zg-cal__w' }, d)), ...Array.from({ length: off }, (_, i) => h('span', { key: 'o' + i })), ...Array.from({ length: dn }, (_, i) => { const d = i + 1, key = mk(d); return h('button', { key, type: 'button', class: 'zg-cal__d', tabIndex: d === fd ? 0 : -1, 'data-date': key, 'aria-pressed': String(!!same(s, d)), 'aria-current': same(today, d) ? 'date' : undefined, 'data-today': String(!!same(today, d)), 'data-ev': ev[key] ? '' : undefined, title: ev[key] || undefined, disabled: blocked(d) || undefined, onFocus: () => state.fd !== key && set({ fd: key }), onClick: e => { if (blocked(d)) return; if (e.currentTarget.closest('[data-zg-pick]')) toTrigger(e); p.onChange && p.onChange(new Date(y, m, d)); } }, d); }))); } },
+  DatePicker: { state: { open: false }, render: ({ C, h, props: p, state, set }) => lab(h, p, h('div', { class: 'zg-select' }, h('button', { type: 'button', class: 'zg-btn zg-select__trigger', 'aria-haspopup': 'dialog', 'aria-expanded': String(state.open && !p.disabled), disabled: p.disabled, style: { height: 'var(--zg-h-lg)' }, onClick: () => set({ open: !state.open }), onKeydown: openKeys(state.open && !p.disabled, () => set({ open: true })) }, h('span', { style: { display: 'flex', gap: '10px', alignItems: 'center' } }, icon(h, 'calendar', 16), p.modelValue ? new Intl.DateTimeFormat(dloc(p), { dateStyle: 'medium' }).format(pd(p.modelValue) || new Date()) : (p.placeholder || t('DatePicker', 'placeholder'))), h('span', { style: { display: 'flex', alignItems: 'center', gap: '6px' } }, p.clearable && p.modelValue && !p.disabled ? h('span', { role: 'button', tabIndex: 0, class: 'zg-ibtn zg-ibtn--sm zg-ibtn--ghost', 'aria-label': t('DatePicker', 'clear'), onClick: e => { e.stopPropagation(); p.onChange && p.onChange(null); }, onKeydown: e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); e.stopPropagation(); p.onChange && p.onChange(null); } } }, icon(h, 'x', 14)) : null, icon(h, 'chevron-down', 16))),
+    state.open && !p.disabled ? h('div', { class: 'zg-select__list', role: 'dialog', 'aria-label': p.label || p.placeholder || t('DatePicker', 'placeholder'), 'data-zg-dd': '', 'data-zg-pick': '', ref: ddRef(() => set({ open: false }), { focus: true }), style: { padding: '12px' }, onFocusout: e => { const r = e.currentTarget.parentElement; if (e.relatedTarget && r && !r.contains(e.relatedTarget)) set({ open: false }); } }, h(C.Calendar, { modelValue: p.modelValue, locale: p.locale, weekStartsOn: p.weekStartsOn, min: p.min, max: p.max, today: p.today, disabledDate: p.disabledDate, onChange: d => { set({ open: false }); p.onChange && p.onChange(d); } })) : null)) },
   TimePicker: { render: ({ C, h, props: p }) => { const [H0, M0] = (p.modelValue || '09:00').split(':'), H = String(H0 ?? '00').padStart(2, '0'), M = String(M0 ?? '00').padStart(2, '0'); const hs = Array.from({ length: 24 }, (_, i) => { const v = String(i).padStart(2, '0'); return { value: v, label: v }; }), st = Math.max(1, Math.min(60, Math.floor(+p.minuteStep) || 15)), mv = Array.from({ length: Math.ceil(60 / st) }, (_, i) => String(i * st).padStart(2, '0')); if (!mv.includes(M)) { mv.push(M); mv.sort(); } const ms = mv.map(v => ({ value: v, label: v }));
     return h('div', { class: 'zg-field' }, p.label ? h('span', { class: 'zg-label' }, p.label) : null, h('div', { style: { display: 'flex', gap: '8px', alignItems: 'center' } }, h('div', { style: { flex: 1 } }, h(C.Select, { options: hs, disabled: p.disabled, modelValue: H, onChange: v => p.onChange && p.onChange(v + ':' + M) })), h('b', null, ':'), h('div', { style: { flex: 1 } }, h(C.Select, { options: ms, disabled: p.disabled, modelValue: M, onChange: v => p.onChange && p.onChange(H + ':' + v) })))); } },
   FormField: { render: ({ h, props: p, children }) => h('div', { class: 'zg-field' }, p.label ? h('span', { class: 'zg-label' }, p.label, p.required ? h('span', { style: { color: 'var(--zg-red)' } }, ' *') : null) : null, ...children, p.error ? h('span', { class: 'zg-hint zg-hint--error' }, p.error) : p.hint ? h('span', { class: 'zg-hint' }, p.hint) : null) },

package/src/core/keys.js

@@ -53,3 +53,40 @@ export const openKeys = (isOpen, open) => e => { if (!isOpen && !mod(e) && (e.ke
 
 /** Focus the entry point of a freshly opened popup: the item with tabindex 0, else the first one. */
 export const focusIn = el => { const t = el.querySelector('[tabindex="0"]') || el.querySelector('button:not([disabled])'); if (t && t.focus) t.focus({ preventScroll: true }); };
+
+const pad2 = n => String(n).padStart(2, '0');
+/** YYYY-MM-DD of a local date, the value of a day cell's data-date attribute. */
+export const dateKey = d => d.getFullYear() + '-' + pad2(d.getMonth() + 1) + '-' + pad2(d.getDate());
+/**
+ * Month grid of day buttons carrying data-date="YYYY-MM-DD" and a roving tabindex. Put it on the grid element.
+ * Arrows move one day (Left/Right mirrored in RTL) or one week, Home/End jump to the start/end of the week, PageUp/PageDown change month (Shift: year).
+ * Blocked days are skipped. When the target day is in another month, show(date, key) must make that month visible; the cell is focused once it renders.
+ */
+export const calKeys = o => e => {
+  if (mod(e)) return;
+  const root = e.currentTarget, cell = e.target.closest && e.target.closest('[data-date]');
+  if (!cell) return;
+  const [Y, M, D] = cell.getAttribute('data-date').split('-').map(Number), ws = o.ws ?? 1, rtl = isRtl(root), day = (n) => new Date(Y, M - 1, D + n);
+  const month = n => { const f = new Date(Y, M - 1 + n, 1); return new Date(f.getFullYear(), f.getMonth(), Math.min(D, new Date(f.getFullYear(), f.getMonth() + 1, 0).getDate())); };
+  const wk = (new Date(Y, M - 1, D).getDay() - ws + 7) % 7;
+  let t, unit = 1;
+  switch (e.key) {
+    case 'ArrowRight': t = day(rtl ? -1 : 1); unit = rtl ? -1 : 1; break;
+    case 'ArrowLeft': t = day(rtl ? 1 : -1); unit = rtl ? 1 : -1; break;
+    case 'ArrowDown': t = day(7); unit = 7; break;
+    case 'ArrowUp': t = day(-7); unit = -7; break;
+    case 'Home': t = day(-wk); break;
+    case 'End': t = day(6 - wk); unit = -1; break;
+    case 'PageUp': t = month(e.shiftKey ? -12 : -1); break;
+    case 'PageDown': t = month(e.shiftKey ? 12 : 1); break;
+    default: return;
+  }
+  e.preventDefault();
+  for (let i = 0; i < 62 && o.blocked && o.blocked(t); i++) t = new Date(t.getFullYear(), t.getMonth(), t.getDate() + unit);
+  if (o.blocked && o.blocked(t)) return;
+  const k = dateKey(t), find = () => root.querySelector('[data-date="' + k + '"]:not(:disabled)');
+  const el = find();
+  if (el) { el.focus(); return; }
+  o.show(t, k);
+  let n = 0; const tick = () => { const x = find(); if (x) x.focus(); else if (++n < 12) setTimeout(tick, 16); }; setTimeout(tick, 0);
+};

package/src/internal.js

@@ -2,7 +2,7 @@
 // It re-exports the helpers the component definitions are built from, so a plugin does not copy them.
 export { cx, pick, INPUT_ATTRS, DZ, dzp, dzf, dzb, ddRef, icon, fmt } from './core/components.js';
 export { trap, life } from './core/dialog.js';
-export { rove, tabIdx, listKeys, openKeys, focusIn, toTrigger, trigger } from './core/keys.js';
+export { rove, tabIdx, listKeys, openKeys, focusIn, toTrigger, trigger, calKeys, dateKey } from './core/keys.js';
 export { rules } from './core/components4.js';
 export { page } from './core/pages.js';
 export { t, getUiLocale, intlLocale, defineMessages } from './i18n/index.js';

package/src/meta/forms.js

@@ -207,7 +207,7 @@ export default {
       size: size(),
     },
     events: change('Called with the value of the chosen option.'),
-    notes: ['Selecting from the list is the only way to set a value: free text is never emitted.', 'The list closes on outside click and on Escape.'],
+    notes: ['Selecting from the list is the only way to set a value: free text is never emitted.', 'The list closes on outside click and on Escape.', 'Keyboard (WAI-ARIA combobox): the input has role=combobox with aria-expanded, aria-controls and aria-activedescendant; focus stays in the input, Arrow Down and Up open the list and move the active option (wraps, skips disabled), Enter chooses it, Escape closes.'],
   },
   TreeSelect: {
     description: 'Dropdown with a searchable tree. Use for hierarchical choices such as regions, categories or org units.',
@@ -359,11 +359,12 @@ export default {
       min: { type: 'Date | string | number', description: 'Earliest selectable day; earlier days are disabled.' },
       max: { type: 'Date | string | number', description: 'Latest selectable day; later days are disabled.' },
       disabledDate: { type: '(date: Date) => boolean', description: 'Return true to disable a specific day.' },
+      today: { type: 'Date | string | number', description: 'The day marked as today. By default it is read from the browser clock after mount (nothing is marked in server-rendered HTML), so server and client never disagree near midnight or across time zones. Pass it to mark a day in the HTML too.' },
       events: { type: 'Record<string, string>', default: '{}', description: 'Marked days: keys are YYYY-MM-DD, values are the tooltip text.' },
       size: size('Day cell and header size.'),
     },
     events: change('Called with a Date object (local time) for the clicked day.'),
-    notes: ['The event payload is a Date, not a string: convert to ISO yourself if the model is a string.'],
+    notes: ['The event payload is a Date, not a string: convert to ISO yourself if the model is a string.', 'Keyboard: one tab stop on the day grid; arrows move by day or week, Home and End to the week start and end, PageUp and PageDown change month (Shift: year), Enter or Space picks. Without a selected date the visible month is the current month, which server and client can disagree on right at a month boundary; pass modelValue or today to make it deterministic.'],
   },
   RangeCalendar: {
     description: 'Month grid for picking a date range with hover preview. Use for stays, trips and report periods.',
@@ -387,6 +388,7 @@ export default {
       min: { type: 'Date | string | number', forwarded: true, description: 'Earliest selectable day, forwarded to the calendar.' },
       max: { type: 'Date | string | number', forwarded: true, description: 'Latest selectable day, forwarded to the calendar.' },
       disabledDate: { type: '(date: Date) => boolean', forwarded: true, description: 'Return true to disable a specific day, forwarded to the calendar.' },
+      today: { type: 'Date | string | number', forwarded: true, description: 'The day marked as today in the calendar; by default read from the browser clock after mount. Forwarded to the calendar.' },
       required: { type: 'boolean', default: false, forwarded: true, description: 'Adds a red asterisk to the label. Does not validate.' },
       label, hint, error,
       placeholder: placeholder('Shown when no date is set. Defaults to "Select date".'),
@@ -394,7 +396,7 @@ export default {
       size: size(),
     },
     events: change('Called with a Date object (local midnight) for the chosen day. The popup closes after picking.'),
-    notes: ['The event payload is a Date, not a string: convert to ISO yourself if the model is a string.', 'The popup closes on outside click and on Escape.'],
+    notes: ['The event payload is a Date, not a string: convert to ISO yourself if the model is a string.', 'The popup closes on outside click and on Escape (focus returns to the trigger). Arrow Down or Up on the trigger opens it and focus moves into the calendar, which uses the Calendar keys.'],
   },
   TimePicker: {
     description: 'Hour and minute selects for a time of day. Use for opening hours and appointment times.',

package/src/meta/overlay.js

@@ -155,7 +155,7 @@ export default {
       size: size('bubble padding and font'),
     },
     slots: { default: 'The element the tooltip is attached to.' },
-    notes: ['Pure CSS bubble; it cannot contain markup. For rich content use HoverCard.'],
+    notes: ['Pure CSS bubble; it cannot contain markup. For rich content use HoverCard.', 'Escape hides the bubble while it is shown (hover or focus) without moving focus; it stays visible while the pointer is over the trigger or the bubble, and returns on the next hover or focus.'],
   },
 
   Dropdown: {
@@ -257,11 +257,12 @@ export default {
   },
 
   Screensaver: {
-    description: 'Full-screen idle screen with a large clock, date and the brand mark; show it after inactivity.',
+    description: 'Full-screen idle screen with a large clock, date and an optional logo; show it after inactivity.',
     props: {
       open: open('screensaver'),
       locale: { type: 'string', default: 'en-GB', description: 'BCP 47 locale for the date line.' },
       hint: { type: 'string', description: 'Small hint under the date, e.g. "Tap to continue".' },
+      logo: { type: 'string', description: 'URL of an image shown above the clock. Use an absolute URL or a root-relative path such as "/brand/logo.svg". Nothing is shown when it is not set, so the screensaver never requests a missing file.' },
       idleMs: { type: 'number', default: 0, description: 'When greater than 0 and the screensaver is closed, a hidden sentinel listens for pointer, key, wheel and touch activity and calls idle after this many milliseconds without any. 0 disables it.' },
     },
     events: { close: 'Called on click or any key (including Escape) while open.', idle: 'Called once the idleMs period passes without activity while closed; set open to true in the handler.' },

package/src/react/index.js

@@ -6,7 +6,7 @@ import { components, registerComponents, subscribeUiLocale, getUiVersion } from
 
 const C = {};
 const useIsoLayoutEffect = typeof document === 'undefined' ? useEffect : useLayoutEffect;
-const EV = { keydown: 'KeyDown', keyup: 'KeyUp', dragenter: 'DragEnter', dragover: 'DragOver', dragleave: 'DragLeave', pointerdown: 'PointerDown', pointerup: 'PointerUp', pointermove: 'PointerMove', mousedown: 'MouseDown', mouseup: 'MouseUp', mouseenter: 'MouseEnter', mouseleave: 'MouseLeave', mousemove: 'MouseMove', mouseover: 'MouseOver', mouseout: 'MouseOut', dragstart: 'DragStart', dragend: 'DragEnd', dblclick: 'DoubleClick', contextmenu: 'ContextMenu', pointerenter: 'PointerEnter', pointerleave: 'PointerLeave', pointercancel: 'PointerCancel', touchstart: 'TouchStart', touchend: 'TouchEnd', touchmove: 'TouchMove', focusin: 'FocusIn', focusout: 'FocusOut' };
+const EV = { keydown: 'KeyDown', keyup: 'KeyUp', dragenter: 'DragEnter', dragover: 'DragOver', dragleave: 'DragLeave', pointerdown: 'PointerDown', pointerup: 'PointerUp', pointermove: 'PointerMove', mousedown: 'MouseDown', mouseup: 'MouseUp', mouseenter: 'MouseEnter', mouseleave: 'MouseLeave', mousemove: 'MouseMove', mouseover: 'MouseOver', mouseout: 'MouseOut', dragstart: 'DragStart', dragend: 'DragEnd', dblclick: 'DoubleClick', contextmenu: 'ContextMenu', pointerenter: 'PointerEnter', pointerleave: 'PointerLeave', pointercancel: 'PointerCancel', touchstart: 'TouchStart', touchend: 'TouchEnd', touchmove: 'TouchMove', focusin: 'Focus', focusout: 'Blur' };
 const hh = (t, p, ...k) => {
   if (p && typeof t === 'string') { const q = {}; for (const key in p) { const m = /^on([A-Za-z]+)$/.exec(key), n = m && EV[m[1].toLowerCase()]; q[n ? 'on' + n : key] = p[key]; } p = q; }
   if (p && 'class' in p) { const { class: cls, ...rest } = p; p = { ...rest, className: cls }; }

package/src/styles/components8.css

@@ -113,3 +113,10 @@
 .zg-sr{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0}
 .zg-select__opt:focus-visible{outline:3px solid var(--zg-brand-soft);outline-offset:-3px;background:var(--zg-s2)}
 .zg-seg button:focus-visible,.zg-tabs button:focus-visible,.zg-code-b pre:focus-visible{outline:3px solid var(--zg-brand-soft);outline-offset:2px}
+.zg-select__opt[data-active],.zg-select__opt[data-active]:hover{background:var(--zg-s2);outline:3px solid var(--zg-brand-soft);outline-offset:-3px}
+.zg-tip:hover::after,.zg-tip:focus-visible::after{pointer-events:auto}
+.zg-tip:hover::before{content:"";position:absolute;left:0;right:0;bottom:100%;height:10px}
+.zg-tip--bottom:hover::before{bottom:auto;top:100%}
+.zg-tip--left:hover::before,.zg-tip--right:hover::before{top:0;bottom:0;height:auto;width:10px}
+.zg-tip--left:hover::before{left:auto;right:100%}.zg-tip--right:hover::before{right:auto;left:100%}
+.zg-tip[data-tip-off]::after{opacity:0!important;pointer-events:none!important}.zg-tip[data-tip-off]::before{display:none}

package/types/react.d.ts

@@ -382,6 +382,7 @@ export const UiButton: ComponentType<UiButtonProps>;
 /**
  * Month grid for picking one date. Use inline, or inside a popover via DatePicker.
  * Note: The event payload is a Date, not a string: convert to ISO yourself if the model is a string.
+ * Note: Keyboard: one tab stop on the day grid; arrows move by day or week, Home and End to the week start and end, PageUp and PageDown change month (Shift: year), Enter or Space picks. Without a selected date the visible month is the current month, which server and client can disagree on right at a month boundary; pass modelValue or today to make it deterministic.
  */
 export interface UiCalendarProps {
   /** Selected date: a Date, ISO string or timestamp. Also sets the visible month. A date-only string like "2026-10-21" is read as a local date, so the day does not shift with the time zone. */
@@ -402,6 +403,8 @@ export interface UiCalendarProps {
   max?: Date | string | number;
   /** Return true to disable a specific day. */
   disabledDate?: (date: Date) => boolean;
+  /** The day marked as today. By default it is read from the browser clock after mount (nothing is marked in server-rendered HTML), so server and client never disagree near midnight or across time zones. Pass it to mark a day in the HTML too. */
+  today?: Date | string | number;
   /**
    * Marked days: keys are YYYY-MM-DD, values are the tooltip text.
    * @default {}
@@ -630,6 +633,7 @@ export const UiCodeInput: ComponentType<UiCodeInputProps>;
  * Searchable single-choice dropdown. Use for long option lists where typing to filter is faster than scrolling.
  * Note: Selecting from the list is the only way to set a value: free text is never emitted.
  * Note: The list closes on outside click and on Escape.
+ * Note: Keyboard (WAI-ARIA combobox): the input has role=combobox with aria-expanded, aria-controls and aria-activedescendant; focus stays in the input, Arrow Down and Up open the list and move the active option (wraps, skips disabled), Enter chooses it, Escape closes.
  */
 export interface UiComboboxProps {
   /** Value of the selected option. */
@@ -926,7 +930,7 @@ export const UiDataTable: ComponentType<UiDataTableProps>;
 /**
  * Field with a calendar popup for choosing a date. Use in forms where a single date is needed.
  * Note: The event payload is a Date, not a string: convert to ISO yourself if the model is a string.
- * Note: The popup closes on outside click and on Escape.
+ * Note: The popup closes on outside click and on Escape (focus returns to the trigger). Arrow Down or Up on the trigger opens it and focus moves into the calendar, which uses the Calendar keys.
  */
 export interface UiDatePickerProps {
   /** Selected date (ISO string recommended, e.g. 2026-10-21). */
@@ -961,6 +965,11 @@ export interface UiDatePickerProps {
    * @remarks Forwarded to the inner element.
    */
   disabledDate?: (date: Date) => boolean;
+  /**
+   * The day marked as today in the calendar; by default read from the browser clock after mount. Forwarded to the calendar.
+   * @remarks Forwarded to the inner element.
+   */
+  today?: Date | string | number;
   /**
    * Adds a red asterisk to the label. Does not validate.
    * @default false
@@ -3663,6 +3672,7 @@ export const UiToggleGroup: ComponentType<UiToggleGroupProps>;
 /**
  * Short text bubble shown on hover or focus of the wrapped element; use for icon-only controls and hints.
  * Note: Pure CSS bubble; it cannot contain markup. For rich content use HoverCard.
+ * Note: Escape hides the bubble while it is shown (hover or focus) without moving focus; it stays visible while the pointer is over the trigger or the bubble, and returns on the next hover or focus.
  */
 export interface UiTooltipProps {
   /** Tooltip text. */

package/types/vue.d.ts

@@ -402,6 +402,7 @@ export const UiButton: UiVueComponent<UiButtonProps, UiButtonSlots>;
 /**
  * Month grid for picking one date. Use inline, or inside a popover via DatePicker.
  * Note: The event payload is a Date, not a string: convert to ISO yourself if the model is a string.
+ * Note: Keyboard: one tab stop on the day grid; arrows move by day or week, Home and End to the week start and end, PageUp and PageDown change month (Shift: year), Enter or Space picks. Without a selected date the visible month is the current month, which server and client can disagree on right at a month boundary; pass modelValue or today to make it deterministic.
  */
 export interface UiCalendarProps {
   /** Selected date: a Date, ISO string or timestamp. Also sets the visible month. A date-only string like "2026-10-21" is read as a local date, so the day does not shift with the time zone. */
@@ -422,6 +423,8 @@ export interface UiCalendarProps {
   max?: Date | string | number;
   /** Return true to disable a specific day. */
   disabledDate?: (date: Date) => boolean;
+  /** The day marked as today. By default it is read from the browser clock after mount (nothing is marked in server-rendered HTML), so server and client never disagree near midnight or across time zones. Pass it to mark a day in the HTML too. */
+  today?: Date | string | number;
   /**
    * Marked days: keys are YYYY-MM-DD, values are the tooltip text.
    * @default {}
@@ -656,6 +659,7 @@ export const UiCodeInput: UiVueComponent<UiCodeInputProps, UiCodeInputSlots>;
  * Searchable single-choice dropdown. Use for long option lists where typing to filter is faster than scrolling.
  * Note: Selecting from the list is the only way to set a value: free text is never emitted.
  * Note: The list closes on outside click and on Escape.
+ * Note: Keyboard (WAI-ARIA combobox): the input has role=combobox with aria-expanded, aria-controls and aria-activedescendant; focus stays in the input, Arrow Down and Up open the list and move the active option (wraps, skips disabled), Enter chooses it, Escape closes.
  */
 export interface UiComboboxProps {
   /** Value of the selected option. */
@@ -963,7 +967,7 @@ export const UiDataTable: UiVueComponent<UiDataTableProps, UiDataTableSlots>;
 /**
  * Field with a calendar popup for choosing a date. Use in forms where a single date is needed.
  * Note: The event payload is a Date, not a string: convert to ISO yourself if the model is a string.
- * Note: The popup closes on outside click and on Escape.
+ * Note: The popup closes on outside click and on Escape (focus returns to the trigger). Arrow Down or Up on the trigger opens it and focus moves into the calendar, which uses the Calendar keys.
  */
 export interface UiDatePickerProps {
   /** Selected date (ISO string recommended, e.g. 2026-10-21). */
@@ -998,6 +1002,11 @@ export interface UiDatePickerProps {
    * @remarks Forwarded to the inner element.
    */
   disabledDate?: (date: Date) => boolean;
+  /**
+   * The day marked as today in the calendar; by default read from the browser clock after mount. Forwarded to the calendar.
+   * @remarks Forwarded to the inner element.
+   */
+  today?: Date | string | number;
   /**
    * Adds a red asterisk to the label. Does not validate.
    * @default false
@@ -3692,6 +3701,7 @@ export const UiToggleGroup: UiVueComponent<UiToggleGroupProps, UiToggleGroupSlot
 /**
  * Short text bubble shown on hover or focus of the wrapped element; use for icon-only controls and hints.
  * Note: Pure CSS bubble; it cannot contain markup. For rich content use HoverCard.
+ * Note: Escape hides the bubble while it is shown (hover or focus) without moving focus; it stays visible while the pointer is over the trigger or the bubble, and returns on the next hover or focus.
  */
 export interface UiTooltipProps {
   /** Tooltip text. */