@womp/kookie-ui 0.26.2 → 0.27.0

package/src/components/_internal/pane-chrome.tsx

@@ -15,6 +15,7 @@ import classNames from 'classnames';
 import { ScrollArea } from '../scroll-area.js';
 import { ShellStoreContext } from './shell-store.js';
 import { PaneBandSizeContext, type BandSize } from './pane-band-context.js';
+import { usePageScrollMedia } from './shell-page-scroll.js';
 
 type PaneSize = '1' | '2' | '3';
 
@@ -42,6 +43,13 @@ const ShellSizeContext = React.createContext<PaneSize>('2');
  */
 const ShellContentContext = React.createContext(false);
 
+/**
+ * True inside a window Shell: one with no `contained` and no `height`, which lets the page scroll
+ * on a narrow touch screen. Each `Shell.Root` sets its own, so a Shell nested in another answers
+ * for itself.
+ */
+const ShellWindowContext = React.createContext(false);
+
 /**
  * Gives a Shell pane's children the Shell's index, so Sidebar parts size themselves. In a Rail
  * the rows are `thin`: icon tiles with a small label, sub-menus as dropdowns.
@@ -156,9 +164,14 @@ const Scroll = React.forwardRef<HTMLDivElement, ScrollProps>(({ className, style
   const contentPane = React.useContext(ShellContentContext);
   const visual = useSidebarVisual();
   const inContent = contentPane && visual === null;
+  // While the page scrolls, the content's viewport scrolls nothing: as a tab stop it would take a
+  // Tab, ring the whole page and move nothing. Resolved after mount; a `tabIndex` of the caller's wins.
+  const windowShell = React.useContext(ShellWindowContext);
+  const pageScrolls = usePageScrollMedia();
   if (inContent) {
+    const tabIndex = props.tabIndex ?? (windowShell && pageScrolls ? -1 : undefined);
     return (
-      <ScrollArea {...props} ref={forwardedRef} type="hover" fade={fade} className="kui-ShellScroll">
+      <ScrollArea {...props} tabIndex={tabIndex} ref={forwardedRef} type="hover" fade={fade} className="kui-ShellScroll">
         <div style={style} dir={dir} className={classNames('kui-ShellScrollContent', className)}>
           {children}
         </div>
@@ -178,5 +191,5 @@ const Scroll = React.forwardRef<HTMLDivElement, ScrollProps>(({ className, style
 });
 Scroll.displayName = 'Shell.Scroll';
 
-export { SidebarVisualContext, useSidebarVisual, ShellSizeContext, ShellContentContext, PaneChromeScope, PaneHeader, PaneFooter, Scroll, BAND_STEP, usePaneBandSize };
+export { SidebarVisualContext, useSidebarVisual, ShellSizeContext, ShellContentContext, ShellWindowContext, PaneChromeScope, PaneHeader, PaneFooter, Scroll, BAND_STEP, usePaneBandSize };
 export type { SidebarVisualContextValue, PaneSize, BandSize, PaneHeaderProps, PaneFooterProps, ScrollProps };

package/src/components/_internal/portal-theme.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+import { Theme } from '../theme.js';
+import { PaneBandSizeContext } from './pane-band-context.js';
+
+/**
+ * The Theme at the root of a portalled surface (Popover, Dialog, Sheet, menus, Tooltip). The
+ * surface renders outside any Shell pane even though context flows into it, so a Toolbar in it
+ * does not take the pane's band size. A `Theme asChild` an app nests in a pane keeps the band.
+ */
+const PortalTheme = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Theme>>((props, forwardedRef) => (
+  <PaneBandSizeContext.Provider value={null}>
+    <Theme {...props} ref={forwardedRef} />
+  </PaneBandSizeContext.Provider>
+));
+PortalTheme.displayName = 'PortalTheme';
+
+export { PortalTheme };

package/src/components/_internal/shell-page-scroll.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * When a window Shell lets the page scroll: a narrow window (below the `sm` breakpoint) under a
+ * coarse pointer. The stylesheet decides it (shell.css, the page-scroll block), so first paint is
+ * right with no script. This is the script's copy, for the few things only script can do when the
+ * answer changes: carry the reading position between the two scrollers, and take the content's
+ * unused viewport out of the tab order. A test holds it equal to the stylesheet's.
+ */
+export const PAGE_SCROLL_QUERY = '(max-width: 767.98px) and (pointer: coarse)';
+
+let list: MediaQueryList | undefined;
+const media = () => (list ??= window.matchMedia(PAGE_SCROLL_QUERY));
+
+function listen(m: MediaQueryList, handler: () => void): () => void {
+  // Safari below 14 has only the deprecated listener API.
+  if (typeof m.addEventListener === 'function') {
+    m.addEventListener('change', handler);
+    return () => m.removeEventListener('change', handler);
+  }
+  m.addListener?.(handler);
+  return () => m.removeListener?.(handler);
+}
+
+function subscribe(onChange: () => void): () => void {
+  return listen(media(), onChange);
+}
+
+/** True where a window Shell lets the page scroll. False on the server and through hydration. */
+export function usePageScrollMedia(): boolean {
+  return React.useSyncExternalStore(
+    subscribe,
+    () => media().matches,
+    () => false,
+  );
+}
+
+/** Whether the page scrolls right now. */
+export function pageScrollMatches(): boolean {
+  return media().matches;
+}
+
+/** Subscribes to the answer changing, outside React. */
+export function onPageScrollMediaChange(onChange: (matches: boolean) => void): () => void {
+  const m = media();
+  return listen(m, () => onChange(m.matches));
+}

package/src/components/alert-dialog.tsx

@@ -5,7 +5,7 @@ import { AlertDialog as AlertDialogPrimitive } from 'radix-ui';
 import { alertDialogContentPropDefs } from './alert-dialog.props.js';
 import { Heading } from './heading.js';
 import { Text } from './text.js';
-import { Theme } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
@@ -48,7 +48,7 @@ const AlertDialogContent = React.forwardRef<AlertDialogContentElement, AlertDial
 
   return (
     <AlertDialogPrimitive.Portal container={container} forceMount={forceMount}>
-      <Theme asChild>
+      <PortalTheme asChild>
         <AlertDialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-AlertDialogOverlay">
           <div className="kui-BaseDialogScroll kui-AlertDialogScroll">
             <div className={`kui-BaseDialogScrollPadding kui-AlertDialogScrollPadding ${alignClassName}`}>
@@ -67,7 +67,7 @@ const AlertDialogContent = React.forwardRef<AlertDialogContentElement, AlertDial
             </div>
           </div>
         </AlertDialogPrimitive.Overlay>
-      </Theme>
+      </PortalTheme>
     </AlertDialogPrimitive.Portal>
   );
 });

package/src/components/combobox.tsx

@@ -29,7 +29,8 @@ import { useThemeSize } from '../hooks/theme-size.js';
 import { comboboxRootPropDefs, comboboxTriggerPropDefs, comboboxContentPropDefs } from './combobox.props.js';
 import { ChevronDownIcon, ThickCheckIcon } from './icons.js';
 import { Spinner } from './spinner.js';
-import { Theme, useThemeContext } from './theme.js';
+import { useThemeContext } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
 import * as Popover from './popover.js';
 import { Slottable } from './slot.js';
@@ -543,7 +544,7 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
 
   return (
     <PopoverPrimitive.Portal container={container} forceMount={forceMount ? true : undefined}>
-      <Theme asChild>
+      <PortalTheme asChild>
         <PopoverPrimitive.Content
           data-accent-color={resolvedColor}
           align="start"
@@ -573,7 +574,7 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
             </CommandPrimitive>
           </ComboboxContentContext.Provider>
         </PopoverPrimitive.Content>
-      </Theme>
+      </PortalTheme>
     </PopoverPrimitive.Portal>
   );
 });

package/src/components/context-menu.tsx

@@ -17,7 +17,8 @@ import {
   contextMenuCheckboxItemPropDefs,
   contextMenuRadioItemPropDefs,
 } from './context-menu.props.js';
-import { Theme, useThemeContext } from './theme.js';
+import { useThemeContext } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { ThickCheckIcon, ThickChevronRightIcon, ThickDotIcon } from './icons.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
@@ -133,7 +134,7 @@ const ContextMenuContent = React.forwardRef<ContextMenuContentElement, ContextMe
 
     return (
       <ContextMenuPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <ContextMenuPrimitive.Content
             data-accent-color={resolvedColor}
             alignOffset={getMenuAlignOffset(scalarSize)}
@@ -159,7 +160,7 @@ const ContextMenuContent = React.forwardRef<ContextMenuContentElement, ContextMe
               </ScrollArea>
             )}
           </ContextMenuPrimitive.Content>
-        </Theme>
+        </PortalTheme>
       </ContextMenuPrimitive.Portal>
     );
   },
@@ -419,7 +420,7 @@ const ContextMenuSubContent = React.forwardRef<
 
   return (
     <ContextMenuPrimitive.Portal container={container} forceMount={forceMount}>
-      <Theme asChild>
+      <PortalTheme asChild>
         <ContextMenuPrimitive.SubContent
           data-accent-color={color}
           alignOffset={getMenuAlignOffset(scalarSize)}
@@ -449,7 +450,7 @@ const ContextMenuSubContent = React.forwardRef<
             </ScrollArea>
           )}
         </ContextMenuPrimitive.SubContent>
-      </Theme>
+      </PortalTheme>
     </ContextMenuPrimitive.Portal>
   );
 });

package/src/components/dialog.tsx

@@ -5,7 +5,7 @@ import { Dialog as DialogPrimitive } from 'radix-ui';
 import { dialogContentPropDefs } from './dialog.props.js';
 import { Heading } from './heading.js';
 import { Text } from './text.js';
-import { Theme } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
@@ -48,7 +48,7 @@ const DialogContent = React.forwardRef<DialogContentElement, DialogContentProps>
 
   return (
     <DialogPrimitive.Portal container={container} forceMount={forceMount}>
-      <Theme asChild>
+      <PortalTheme asChild>
         <DialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-DialogOverlay">
           <div className="kui-BaseDialogScroll kui-DialogScroll">
             <div className={`kui-BaseDialogScrollPadding kui-DialogScrollPadding ${alignClassName}`}>
@@ -67,7 +67,7 @@ const DialogContent = React.forwardRef<DialogContentElement, DialogContentProps>
             </div>
           </div>
         </DialogPrimitive.Overlay>
-      </Theme>
+      </PortalTheme>
     </DialogPrimitive.Portal>
   );
 });

package/src/components/dropdown-menu.tsx

@@ -13,7 +13,8 @@ import {
   dropdownMenuCheckboxItemPropDefs,
   dropdownMenuRadioItemPropDefs,
 } from './dropdown-menu.props.js';
-import { Theme, useThemeContext } from './theme.js';
+import { useThemeContext } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { ChevronDownIcon, ThickCheckIcon, ThickChevronLeftIcon, ThickChevronRightIcon, ThickDotIcon } from './icons.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
@@ -196,7 +197,7 @@ const DropdownMenuContent = React.forwardRef<DropdownMenuContentElement, Dropdow
 
     return (
       <DropdownMenuPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <DropdownMenuPrimitive.Content
             data-accent-color={resolvedColor}
             align="start"
@@ -227,7 +228,7 @@ const DropdownMenuContent = React.forwardRef<DropdownMenuContentElement, Dropdow
               </ScrollArea>
             )}
           </DropdownMenuPrimitive.Content>
-        </Theme>
+        </PortalTheme>
       </DropdownMenuPrimitive.Portal>
     );
   },
@@ -724,7 +725,7 @@ const CascadeSubContent = React.forwardRef<DropdownMenuSubContentElement, Dropdo
 
     return (
       <DropdownMenuPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <DropdownMenuPrimitive.SubContent
             data-accent-color={color}
             alignOffset={getMenuAlignOffset(scalarSize)}
@@ -754,7 +755,7 @@ const CascadeSubContent = React.forwardRef<DropdownMenuSubContentElement, Dropdo
               </ScrollArea>
             )}
           </DropdownMenuPrimitive.SubContent>
-        </Theme>
+        </PortalTheme>
       </DropdownMenuPrimitive.Portal>
     );
   },

package/src/components/popover.tsx

@@ -6,7 +6,7 @@ import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
 import { popoverContentPropDefs } from './popover.props.js';
-import { Theme } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 
 import type { PopoverContentOwnProps } from './popover.props.js';
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
@@ -69,7 +69,7 @@ const PopoverContent = React.forwardRef<PopoverContentElement, PopoverContentPro
 
     return (
       <PopoverPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <PopoverPrimitive.Content
             align="start"
             sideOffset={8}
@@ -84,7 +84,7 @@ const PopoverContent = React.forwardRef<PopoverContentElement, PopoverContentPro
               {props.children}
             </PopoverContentContext.Provider>
           </PopoverPrimitive.Content>
-        </Theme>
+        </PortalTheme>
       </PopoverPrimitive.Portal>
     );
   },

package/src/components/schemas/shell.schema.ts

@@ -122,7 +122,10 @@ export const ShellRootSchema = z
     height: z
       .union([z.literal('full'), z.literal('auto'), z.string(), z.number()])
       .default('full')
-      .describe('Height of the frame. `full` is 100dvh, with 100vh where dvh is not supported.'),
+      .describe(
+        'Height of the frame. `full` is the window: 100dvh, with 100vh where dvh is not supported, and on a narrow touch screen the page scrolls. Any value other than `full` or `auto` makes the Shell contained.',
+      ),
+    contained: z.boolean().default(false).describe('Fills the parent instead of the window and always scrolls inside itself. An explicit `height` implies it.'),
     size: z.enum(['1', '2', '3']).default('2').describe('Index of the pane chrome and the Sidebar rows in it'),
     className: z.string().optional().describe('Additional CSS class name'),
     style: StyleSchema,

package/src/components/select.tsx

@@ -13,7 +13,8 @@ import {
   selectTriggerPropDefs,
   selectContentPropDefs,
 } from './select.props.js';
-import { useThemeContext, Theme } from './theme.js';
+import { useThemeContext } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { useThumbSync } from '../hooks/use-thumb-sync.js';
 
 import type { GetPropDefTypes } from '../props/prop-def.js';
@@ -203,7 +204,7 @@ const SelectContent = React.forwardRef<SelectContentElement, SelectContentProps>
     const resolvedColor = color || themeContext.accentColor;
     return (
       <SelectPrimitive.Portal container={container}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <SelectPrimitive.Content
             data-accent-color={resolvedColor}
             sideOffset={4}
@@ -220,7 +221,7 @@ const SelectContent = React.forwardRef<SelectContentElement, SelectContentProps>
           >
             <SelectScrollArea>{children}</SelectScrollArea>
           </SelectPrimitive.Content>
-        </Theme>
+        </PortalTheme>
       </SelectPrimitive.Portal>
     );
   },

package/src/components/sheet.tsx

@@ -38,7 +38,7 @@ import { Dialog as DialogPrimitive } from 'radix-ui';
 
 import { dialogContentPropDefs } from './dialog.props.js';
 import type { DialogContentOwnProps } from './dialog.props.js';
-import { Theme } from './theme.js';
+import { PortalTheme } from './_internal/portal-theme.js';
 import { Heading } from './heading.js';
 import { Text } from './text.js';
 import { extractProps } from '../helpers/extract-props.js';
@@ -147,7 +147,7 @@ const Content = React.forwardRef<SheetContentElement, SheetContentProps>((allPro
   return (
     <DialogPrimitive.Portal container={container} forceMount={forceMount}>
       <SheetTitleCountContext.Provider value={titleCountRef}>
-        <Theme asChild>
+        <PortalTheme asChild>
           <DialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-DialogOverlay kui-SheetOverlay">
             <DialogPrimitive.Content
               {...contentProps}
@@ -157,7 +157,7 @@ const Content = React.forwardRef<SheetContentElement, SheetContentProps>((allPro
               aria-modal="true"
             />
           </DialogPrimitive.Overlay>
-        </Theme>
+        </PortalTheme>
       </SheetTitleCountContext.Provider>
     </DialogPrimitive.Portal>
   );