@enonic/ui 1.1.0 → 1.2.0

package/dist/types/components/time-picker/time-picker.d.ts

@@ -1,4 +1,5 @@
 import { ComponentPropsWithoutRef, ReactElement, ReactNode, RefObject } from 'react';
+import { FloatingProps } from '../../hooks';
 export type TimePickerHourSelectProps = {
     className?: string;
     contentClassName?: string;
@@ -22,12 +23,11 @@ export type TimePickerTriggerProps = {
     children?: ReactNode;
 } & Omit<ComponentPropsWithoutRef<'button'>, 'className' | 'children'>;
 export type TimePickerContentProps = {
-    align?: 'start' | 'end';
     /** Optional reference to an anchor element for positioning (defaults to trigger) */
     anchorRef?: RefObject<HTMLElement>;
     className?: string;
     children?: ReactNode;
-} & Omit<ComponentPropsWithoutRef<'div'>, 'className' | 'children'>;
+} & FloatingProps & Omit<ComponentPropsWithoutRef<'div'>, 'className' | 'children'>;
 export type TimePickerRootProps = {
     value?: string | null;
     defaultValue?: string | null;

package/dist/types/hooks/index.d.ts

@@ -4,7 +4,7 @@ export { type UseBlinkAttentionConfig, useBlinkAttention } from './use-blink-att
 export { type UseClickOutsideConfig, useClickOutside } from './use-click-outside';
 export { useControlledState } from './use-controlled-state';
 export { useControlledStateWithNull } from './use-controlled-state-with-null';
-export { type FloatingPosition, type FloatingSide, type UseFloatingPositionConfig, useFloatingPosition, } from './use-floating-position';
+export { type CollisionStrategy, type FloatingPosition, type FloatingProps, type FloatingSide, toFloatingStyle, type UseFloatingPositionConfig, useFloatingPosition, } from './use-floating-position';
 export { type ActiveCell, type GridNavigationConfig, type UseGridNavigationReturn, useGridNavigation, } from './use-grid-navigation';
 export { type ItemMetadata, type UseItemRegistryReturn, useItemRegistry } from './use-item-registry';
 export { type UseItemTextRegistryReturn, useItemTextRegistry } from './use-item-text-registry';

package/dist/types/hooks/use-floating-position.d.ts

@@ -1,11 +1,30 @@
-import { RefObject } from 'react';
+import { CSSProperties, RefObject } from 'react';
 export type FloatingSide = 'top' | 'bottom' | 'left' | 'right';
+export type CollisionStrategy = 'flip' | 'shrink';
 export type FloatingPosition = {
     top: number;
     left?: number;
     right?: number;
-    /** Which side the popup is positioned relative to the anchor (post-flip) */
+    /**
+     * The side the popup is actually positioned on. Equals `preferredSide`
+     * unless `collisionStrategy` is `'flip'` and the popup was flipped to fit.
+     */
     side: FloatingSide;
+    /** The `side` requested via config — useful when `flipped` is true. */
+    preferredSide: FloatingSide;
+    /** True when the popup could not use `preferredSide`. */
+    flipped: boolean;
+    /**
+     * Maximum height the popup should be clamped to, in pixels. Set whenever
+     * `collisionStrategy` is `'shrink'`. Consumers apply it via inline style on
+     * the popup wrapper; it only takes effect when the content is taller.
+     *
+     * A popup whose items are direct children also needs `overflow-y-auto` to
+     * scroll. One that wraps a scrollable child (a listbox or viewport) must not:
+     * constraining the wrapper alone keeps the child the scroller, which is what
+     * scroll-active-into-view relies on.
+     */
+    maxHeight?: number;
 };
 export type UseFloatingPositionConfig = {
     /** Whether the floating element is open/visible */
@@ -15,8 +34,7 @@ export type UseFloatingPositionConfig = {
     /** Reference to the floating content element */
     contentRef: RefObject<HTMLElement> | null;
     /**
-     * Preferred side relative to the anchor. Flips to the opposite side when
-     * the content would overflow the viewport.
+     * Preferred side relative to the anchor.
      * @default 'bottom'
      */
     side?: FloatingSide;
@@ -27,16 +45,45 @@ export type UseFloatingPositionConfig = {
      * @default 'start'
      */
     align?: 'start' | 'end';
+    /**
+     * How to react when the preferred side cannot fit the popup:
+     * - `'flip'` (default) — flip to the opposite side if it fits; else stay on
+     *   the preferred side and overflow.
+     * - `'shrink'` — keep the preferred side and return the available space as
+     *   `maxHeight`, which the consumer applies to enable internal scroll. Falls
+     *   back to the opposite side when the preferred one is too cramped to use.
+     *
+     * @default 'flip'
+     */
+    collisionStrategy?: CollisionStrategy;
+};
+/**
+ * Projects a position into an inline style, keeping the coordinate fields and
+ * dropping the descriptive ones (`side`, `preferredSide`, `flipped`) that would
+ * otherwise leak into the DOM as invalid CSS.
+ */
+export declare function toFloatingStyle(position: FloatingPosition | null): CSSProperties;
+/**
+ * Shared prop surface for popup components that build on `useFloatingPosition`.
+ * Mix into a component's `*Props` type to expose consistent positioning controls
+ * across the library.
+ */
+export type FloatingProps = {
+    /** Preferred side relative to the anchor. @default 'bottom' */
+    side?: FloatingSide;
+    /** Alignment along the perpendicular axis. @default 'start' */
+    align?: 'start' | 'end';
+    /** Collision behavior when the preferred side does not fit. @default 'flip' */
+    collisionStrategy?: CollisionStrategy;
 };
 /**
  * Calculates optimal position for floating elements (menus, dropdowns, submenus) relative
- * to an anchor, with automatic viewport collision detection and flip behavior.
+ * to an anchor, with viewport collision handling controlled by `collisionStrategy`.
  *
- * Supports four preferred sides (top/bottom/left/right). When the content would overflow
- * the viewport on the preferred side, it flips to the opposite side. Perpendicular-axis
- * alignment is adjusted to keep the content within the viewport.
+ * Supports four preferred sides (top/bottom/left/right). Perpendicular-axis alignment is
+ * always adjusted to keep the content within the viewport, regardless of strategy.
  *
  * @param config - Configuration object for positioning behavior
- * @returns Position object with top and left/right coordinates, or null if not yet calculated
+ * @returns Position object with coordinates and side info, or null if not yet calculated
  */
-export declare function useFloatingPosition({ enabled, anchorRef, contentRef, side: preferredSide, align, }: UseFloatingPositionConfig): FloatingPosition | null;
+export declare function useFloatingPosition({ enabled, anchorRef, contentRef, side: preferredSide, align, collisionStrategy, }: UseFloatingPositionConfig): FloatingPosition | null;

package/dist/types/hooks/use-portal-focus-container.d.ts

@@ -11,11 +11,12 @@ import { RefObject } from 'react';
  * ```tsx
  * const contentRef = useRef<HTMLDivElement>(null);
  * const [isPortalMode, setIsPortalMode] = useState(false);
+ * const portalContainer = usePortalContainer();
  *
  * useLayoutEffect(() => {
  *   if (!open || !contentRef.current) return;
- *   setIsPortalMode(contentRef.current.parentElement === document.body);
- * }, [open]);
+ *   setIsPortalMode(contentRef.current.parentElement === portalContainer);
+ * }, [open, portalContainer]);
  *
  * usePortalFocusContainer(contentRef, isPortalMode);
  * ```

package/dist/types/hooks/use-radio-navigation.d.ts

@@ -1,7 +1,9 @@
+import { RefObject } from 'react';
 export type RadioNavigationConfig = {
     baseId: string;
     getItems: () => string[];
     getItemId?: (baseId: string, itemId: string) => string;
+    rootRef?: RefObject<HTMLElement>;
     value: string | undefined;
     onValueChange: (value: string) => void;
     isItemDisabled: (id: string) => boolean;

package/dist/types/hooks/use-step-navigation.d.ts

@@ -1,7 +1,9 @@
+import { RefObject } from 'react';
 export type StepNavigationConfig = {
     baseId: string;
     getItems: () => string[];
     getNextFocusable?: (baseId: string, itemId: string) => string;
+    rootRef?: RefObject<HTMLElement>;
     value: string | undefined;
     onValueChange: (value: string) => void;
     isItemDisabled: (id: string) => boolean;

package/dist/types/providers/combobox-provider.d.ts

@@ -2,6 +2,8 @@ import { ReactElement, ReactNode, RefObject } from 'react';
 export type ContentType = 'listbox' | 'tree' | 'auto';
 export type ComboboxOpenOptions = {
     restoreFocus?: boolean;
+    /** Whether this interaction should focus the input on open or restore it on close. */
+    focusInput?: boolean;
 };
 export type ComboboxContextValue = {
     baseId: string;
@@ -10,6 +12,7 @@ export type ComboboxContextValue = {
     applyRef: RefObject<HTMLButtonElement>;
     popupRef: RefObject<HTMLDivElement>;
     restoreFocusOnCloseRef: RefObject<boolean>;
+    inputFocusIntentRef: RefObject<boolean>;
     ignoreFocusExitCloseRef: RefObject<boolean>;
     open: boolean;
     setOpen: (next: boolean, options?: ComboboxOpenOptions) => void;

package/dist/types/providers/index.d.ts

@@ -12,6 +12,7 @@ export * from './listbox-provider';
 export * from './menu-provider';
 export * from './menubar-menu-provider';
 export * from './menubar-provider';
+export * from './portal-provider';
 export * from './radio-provider';
 export * from './search-field-provider';
 export * from './selector-provider';

package/dist/types/providers/portal-provider.d.ts

@@ -0,0 +1,21 @@
+import { ReactElement, ReactNode } from 'react';
+export type PortalProviderProps = {
+    children: ReactNode;
+    /** The element every overlay in the subtree portals into. `null` falls back to `document.body`. */
+    container: HTMLElement | null;
+};
+/**
+ * Overrides where overlays (dialogs, menus, tooltips, popups) portal to. Without a provider they
+ * portal to `document.body`, which lies outside any shadow root.
+ */
+export declare const PortalProvider: {
+    ({ children, container }: PortalProviderProps): ReactElement;
+    displayName: string;
+};
+/**
+ * Resolves the portal container: an explicit `container` prop wins, then the nearest
+ * `PortalProvider`, then `document.body`.
+ *
+ * `null` means there is no document (server render) — callers must not portal until it is set.
+ */
+export declare const usePortalContainer: (container?: HTMLElement | null) => HTMLElement | null;

package/dist/types/style.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The package's compiled stylesheet as text, for consumers without a Tailwind build rendering
+ * inside a shadow root: construct a sheet from it once and pass that to `AppRoot`'s `stylesheets`.
+ * With your own Tailwind v4 build, pass your compiled CSS instead — never both.
+ */
+export declare const styleText: string;
+/** `styleText` as a constructed stylesheet, built once on first call. Browser-only. */
+export declare const getStyleSheet: () => CSSStyleSheet;

package/dist/types/utils/dom.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether a node is a shadow root. Checked by shape rather than `instanceof`, which only recognises
+ * the realm the library was loaded in — a root owned by an iframe document would not match.
+ */
+export declare const isShadowRoot: (node: Node | null | undefined) => node is ShadowRoot;
+/**
+ * The document or shadow root a node lives in — the scope id and selector lookups must go through,
+ * since `document.getElementById` stops at a shadow boundary.
+ *
+ * `null` when there is nothing to resolve against: no node, and no document either, as on a server.
+ */
+export declare const getRoot: (node: Node | null | undefined) => Document | ShadowRoot | null;
+/**
+ * The deeply focused element. From outside a shadow root `document.activeElement` reports the host
+ * rather than the focused element inside it. Stops at a closed root, whose `shadowRoot` is hidden.
+ */
+export declare const getActiveElement: () => Element | null;
+/**
+ * Whether a container holds a node, crossing shadow boundaries. `Node.contains` stops at them, so a
+ * node focused inside a nested root reads as outside the host that holds it.
+ */
+export declare const containsDeep: (container: Node | null | undefined, node: Node | null | undefined) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enonic/ui",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Enonic UI Component Library",
   "author": "Enonic",
   "license": "Apache-2.0",
@@ -33,6 +33,8 @@
   "files": [
     "dist/enonic-ui.es.js",
     "dist/enonic-ui.cjs",
+    "dist/style.es.js",
+    "dist/style.cjs",
     "dist/styles/",
     "dist/types/"
   ],
@@ -42,6 +44,11 @@
       "import": "./dist/enonic-ui.es.js",
       "require": "./dist/enonic-ui.cjs"
     },
+    "./style": {
+      "types": "./dist/types/style.d.ts",
+      "import": "./dist/style.es.js",
+      "require": "./dist/style.cjs"
+    },
     "./style.css": "./dist/styles/style.css",
     "./preset.css": "./dist/styles/preset.css",
     "./tokens.css": "./dist/styles/tokens.css",
@@ -91,13 +98,16 @@
     "@storybook/addon-docs": "~10.5.5",
     "@storybook/addon-themes": "~10.5.5",
     "@storybook/preact-vite": "~10.5.5",
+    "@storybook/test-runner": "^0.24.4",
     "@tailwindcss/vite": "~4.3.3",
     "@types/node": "~24.13.3",
     "@types/react": "~19.2.18",
     "@types/react-dom": "~19.2.4",
     "@typescript/typescript6": "~6.0.2",
     "focus-trap-react": "^12.0.3",
-    "lucide-preact": "~1.28.0",
+    "http-server": "^14.1.1",
+    "lucide-preact": "~1.31.0",
+    "playwright": "^1.62.1",
     "react-virtuoso": "^4.18.11",
     "rollup-plugin-visualizer": "~7.0.1",
     "size-limit": "~13.0.3",
@@ -106,10 +116,11 @@
     "terser": "~5.49.0",
     "tw-animate-css": "^1.4.0",
     "typescript": "~7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@^0.2.7",
+    "vite": "npm:@voidzero-dev/vite-plus-core@^0.2.8",
     "vite-plugin-dts": "~5.0.3",
     "vite-plugin-environment": "~1.1.3",
-    "vite-plus": "^0.2.7"
+    "vite-plus": "^0.2.8",
+    "wait-on": "^9.1.0"
   },
   "engines": {
     "node": ">=24.16.0",
@@ -128,6 +139,10 @@
       "path": "dist/styles/style.css",
       "limit": "15 KB"
     },
+    {
+      "path": "dist/style.es.js",
+      "limit": "20 KB"
+    },
     {
       "path": "dist/styles/preset.css",
       "limit": "2 KB"
@@ -151,9 +166,9 @@
     "format:check": "vp fmt --check",
     "test": "exit 0",
     "test:ci": "exit 0",
+    "test:storybook": "test-storybook --includeTags shadow-smoke",
     "release:dry": "pnpm publish --dry-run --no-git-checks",
     "analyze": "pnpm build && open dist/stats.html",
-    "size": "size-limit",
-    "preview": "pnpm dlx serve . -p 4000"
+    "size": "size-limit"
   }
 }