@womp/kookie-ui 0.29.2 → 0.31.0

package/src/components/_internal/page-scope.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * What page is in a pane, and whether its title has scrolled away (from v2, 2026-11-03).
+ *
+ * A page's large title lives inside the scroller and the band that shows it again lives beside
+ * it, so context, which only flows down, cannot carry it from one to the other. The store sits
+ * at their common ancestor, the pane. Each pane provides its own, so two panes can each hold a
+ * titled page; `Shell.Header` provides none, so a `Toolbar.Title` there always speaks for itself.
+ * Outside a Shell there is no scope: a `Page` still draws its heading and a `Toolbar.Title` still
+ * shows its own words.
+ */
+type PageStore = {
+  /** The words of the page in this pane, or null while nothing has claimed it. */
+  title: string | null;
+  /** Every `Toolbar.Title` mirroring this pane's page, as elements: the collapse is written onto them. */
+  mirrors: Set<HTMLElement>;
+  /** Whether the page's own title has scrolled up behind the band. */
+  collapsed: boolean;
+  listeners: Set<() => void>;
+  /** What a subscriber reads: a stable value between notifications. */
+  version: number;
+};
+
+const PageScopeContext = React.createContext<PageStore | null>(null);
+
+function notify(store: PageStore) {
+  store.version += 1;
+  for (const listener of store.listeners) listener();
+}
+
+/**
+ * The collapse is an attribute write, not a render: only CSS reads it, and an observer sends it
+ * twice per visit to a page.
+ */
+function setPageCollapsed(store: PageStore, collapsed: boolean): void {
+  if (store.collapsed === collapsed) return;
+  store.collapsed = collapsed;
+  for (const el of store.mirrors) {
+    if (collapsed) el.setAttribute('data-collapsed', '');
+    else el.removeAttribute('data-collapsed');
+  }
+}
+
+/** Every pane renders one. It draws nothing. */
+function PageScope({ children }: { children: React.ReactNode }) {
+  const store = React.useMemo<PageStore>(() => ({ title: null, mirrors: new Set(), collapsed: false, listeners: new Set(), version: 0 }), []);
+  return <PageScopeContext.Provider value={store}>{children}</PageScopeContext.Provider>;
+}
+
+/** Cuts the scope off below a portal: a panel over a pane is not in it, so its title must not take the pane's band. */
+function NoPageScope({ children }: { children: React.ReactNode }) {
+  return <PageScopeContext.Provider value={null}>{children}</PageScopeContext.Provider>;
+}
+
+function usePageScope(): PageStore | null {
+  return React.useContext(PageScopeContext);
+}
+
+/** A `Page` claims the pane it is in, in an effect, so no subscriber's snapshot changes mid-render. */
+function useClaimPage(store: PageStore | null, title: string): void {
+  React.useEffect(() => {
+    if (!store) return;
+    store.title = title;
+    notify(store);
+    return () => {
+      if (store.title === title) {
+        store.title = null;
+        notify(store);
+      }
+    };
+  }, [store, title]);
+}
+
+/** What a `Toolbar.Title` shows when it is given no words of its own. */
+function usePageTitle(store: PageStore | null): string | null {
+  const subscribe = React.useCallback(
+    (cb: () => void) => {
+      if (!store) return () => {};
+      store.listeners.add(cb);
+      return () => {
+        store.listeners.delete(cb);
+      };
+    },
+    [store],
+  );
+  // The version is read so the subscription re-renders this consumer; the title itself is the value.
+  React.useSyncExternalStore(
+    subscribe,
+    () => store?.version ?? 0,
+    () => 0,
+  );
+  return store?.title ?? null;
+}
+
+/**
+ * Registers a mirroring title's element, stamped with what the page is doing now: a title that
+ * mounts after its page has scrolled arrives collapsed.
+ */
+function usePageMirror(store: PageStore | null): React.RefCallback<HTMLElement> {
+  const current = React.useRef<HTMLElement | null>(null);
+  return React.useCallback(
+    (el: HTMLElement | null) => {
+      if (!store) return;
+      if (current.current) store.mirrors.delete(current.current);
+      current.current = el;
+      if (!el) return;
+      store.mirrors.add(el);
+      if (store.collapsed) el.setAttribute('data-collapsed', '');
+      else el.removeAttribute('data-collapsed');
+    },
+    [store],
+  );
+}
+
+export { PageScope, NoPageScope, usePageScope, useClaimPage, usePageTitle, usePageMirror, setPageCollapsed };
+export type { PageStore };

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

@@ -2,15 +2,19 @@ import * as React from 'react';
 
 import { Theme } from '../theme.js';
 import { PaneBandSizeContext } from './pane-band-context.js';
+import { NoPageScope } from './page-scope.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.
+ * does not take the pane's band size, and a title in it does not take over the pane's page. A
+ * `Theme asChild` an app nests in a pane keeps both.
  */
 const PortalTheme = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Theme>>((props, forwardedRef) => (
   <PaneBandSizeContext.Provider value={null}>
-    <Theme {...props} ref={forwardedRef} />
+    <NoPageScope>
+      <Theme {...props} ref={forwardedRef} />
+    </NoPageScope>
   </PaneBandSizeContext.Provider>
 ));
 PortalTheme.displayName = 'PortalTheme';

package/src/components/_internal/shell-bottom.tsx

@@ -9,6 +9,7 @@ import { usePane, paneAttributes, usePresentationTable } from './shell-pane.js';
 import { splitHandles, useInitialPaneSize, useResizablePane, type SizeChangeMeta } from './shell-resizable.js';
 import { useInsetRegistration, warnOnce } from './shell-store.js';
 import { bottomAnchoredGrowth, detailRest, toPaneValue, withoutRemovedPaneProps } from './shell-rest.js';
+import { PageScope } from './page-scope.js';
 import { readBreakpoint } from '../../hooks/use-breakpoint.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps } from '../shell.types.js';
 
@@ -148,7 +149,9 @@ export const Bottom = React.forwardRef<HTMLDivElement, BottomPublicProps>((props
         } as CSSPropertiesWithVars
       }
     >
-      <div className="kui-ShellBottomContent">{content}</div>
+      <div className="kui-ShellBottomContent">
+        <PageScope>{content}</PageScope>
+      </div>
       {handle}
     </div>
   );

package/src/components/_internal/shell-inspector.tsx

@@ -9,6 +9,7 @@ import { usePane, paneAttributes, usePresentationTable } from './shell-pane.js';
 import { splitHandles, useInitialPaneSize, useResizablePane, type SizeChangeMeta } from './shell-resizable.js';
 import { useInsetRegistration, warnOnce } from './shell-store.js';
 import { detailRest, endAnchoredGrowth, toPaneValue, withoutRemovedPaneProps } from './shell-rest.js';
+import { PageScope } from './page-scope.js';
 import { readBreakpoint } from '../../hooks/use-breakpoint.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps } from '../shell.types.js';
 
@@ -150,7 +151,9 @@ export const Inspector = React.forwardRef<HTMLDivElement, InspectorPublicProps>(
         } as CSSPropertiesWithVars
       }
     >
-      <div className="kui-ShellInspectorContent">{content}</div>
+      <div className="kui-ShellInspectorContent">
+        <PageScope>{content}</PageScope>
+      </div>
       {handle}
     </div>
   );

package/src/components/_internal/shell-sidebar.tsx

@@ -11,6 +11,7 @@ import { useInsetRegistration, warnOnce, type PaneValue } from './shell-store.js
 import { navigationRest, startAnchoredGrowth, withoutRemovedPaneProps } from './shell-rest.js';
 import { readBreakpoint } from '../../hooks/use-breakpoint.js';
 import { PaneChromeScope } from './pane-chrome.js';
+import { PageScope } from './page-scope.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, Responsive, SidebarMode } from '../shell.types.js';
 
 type SidebarStateChangeMeta = { reason: 'init' | 'toggle' | 'responsive' | 'dismiss' };
@@ -171,7 +172,9 @@ export const Sidebar = React.forwardRef<HTMLDivElement, SidebarPublicProps>((pro
       }
     >
       <div className="kui-ShellSidebarContent">
-        <PaneChromeScope>{content}</PaneChromeScope>
+        <PaneChromeScope>
+          <PageScope>{content}</PageScope>
+        </PaneChromeScope>
       </div>
       {handle}
     </div>

package/src/components/dialog.tsx

@@ -6,6 +6,7 @@ import { dialogContentPropDefs } from './dialog.props.js';
 import { Heading } from './heading.js';
 import { Text } from './text.js';
 import { PortalTheme } from './_internal/portal-theme.js';
+import { NavigatorHostContext, type NavigatorHost } from './_internal/navigator-host.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
@@ -37,6 +38,12 @@ type DialogContentElement = React.ElementRef<typeof DialogPrimitive.Content>;
 interface DialogContentProps extends ComponentPropsWithout<typeof DialogPrimitive.Content, RemovedProps>, DialogContentOwnProps {
   container?: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Portal>['container'];
 }
+/** What a Navigator screen in this panel uses: its title names the panel, its close closes it. */
+const dialogNavigatorHost: NavigatorHost = {
+  Title: ({ children }) => <DialogPrimitive.Title asChild>{children}</DialogPrimitive.Title>,
+  Close: ({ children }) => <DialogPrimitive.Close asChild>{children}</DialogPrimitive.Close>,
+};
+
 const DialogContent = React.forwardRef<DialogContentElement, DialogContentProps>(({ align, ...ownProps }, forwardedRef) => {
   const props = useThemeSizeProps(ownProps, contentPropDefs.size);
   const { className: alignClassName } = extractProps({ align }, alignPropDefs);
@@ -56,6 +63,7 @@ const DialogContent = React.forwardRef<DialogContentElement, DialogContentProps>
                 {...contentProps}
                 ref={forwardedRef}
                 className={classNames('kui-BaseDialogContent', 'kui-DialogContent', className)}
+                children={<NavigatorHostContext.Provider value={dialogNavigatorHost}>{contentProps.children}</NavigatorHostContext.Provider>}
                 aria-modal="true"
                 onCloseAutoFocus={(event) => {
                   // Radix returns focus to the trigger unless the caller prevents it.

package/src/components/index.css

@@ -43,6 +43,8 @@
 @import './text-area.css';
 @import './text-field.css';
 @import './toolbar.css';
+@import './navigator.css';
+@import './page.css';
 @import './tooltip.css';
 @import './virtual-menu.css';
 @import './chatbar.css';

package/src/components/index.tsx

@@ -68,6 +68,21 @@ export {
   type ToolbarSlotProps,
   type ToolbarFillProps,
 } from './toolbar.js';
+export { Page, type PageProps } from './page.js';
+export {
+  Navigator,
+  NavigatorOutlet,
+  NavigatorBack,
+  NavigatorTitle,
+  NavigatorScreen,
+  NavigatorLink,
+  useNavigator,
+  type NavigatorProps,
+  type NavigatorBackProps,
+  type NavigatorScreenProps,
+  type NavigatorLinkProps,
+  type NavigatorApi,
+} from './navigator.js';
 export { Tooltip, TooltipProvider, type TooltipProps, type TooltipProviderProps } from './tooltip.js';
 export { VirtualMenu, type VirtualMenuProps, type VirtualMenuItemProps, type VirtualMenuRenderItemProps } from './virtual-menu.js';
 export { VisuallyHidden, type VisuallyHiddenProps } from './visually-hidden.js';

package/src/components/navigator.css

@@ -0,0 +1,85 @@
+/* Navigator (from v2, 2026-11-03): a stack of screens. It paints nothing; the host is the region.
+ * No motion: v1 has none, so a screen changes at once. */
+.kui-Navigator,
+.kui-NavigatorLevel,
+.kui-NavigatorScreen {
+  display: flex;
+  flex-direction: column;
+  min-block-size: 0;
+}
+
+/* A screen outside a pane: the band, holding Back, the title and Close, then the body. The band
+   sits one step closer to the panel's edge than the content, stated against the panel's own
+   padding so it moves with the panel's size; the body starts a section's distance under it. */
+.kui-NavigatorBar {
+  margin-block-start: calc(-1 * var(--layout-space-2));
+  margin-inline: calc(-1 * var(--layout-space-2));
+  margin-block-end: var(--layout-space-6);
+}
+
+/* The title stays beside Back at the leading edge, and Close goes to the far end. This sheet
+   loads after the toolbar's, so the same specificity wins. */
+.kui-NavigatorBarTitle {
+  margin-inline-end: auto;
+  min-inline-size: 0;
+}
+
+/* With no Back before it, the title lines up with the content under it. */
+.kui-NavigatorBarTitle:where(:first-child) {
+  padding-inline-start: var(--layout-space-2);
+}
+
+.kui-NavigatorBackGlyph,
+.kui-NavigatorLinkGlyph {
+  inline-size: 1em;
+  block-size: 1em;
+}
+
+.kui-NavigatorBackGlyph:where(:dir(rtl)),
+.kui-NavigatorLinkGlyph:where(:dir(rtl)) {
+  transform: scaleX(-1);
+}
+
+/* A row that opens the next screen: its label, and a quiet chevron at the end. */
+.kui-NavigatorLink {
+  display: flex;
+  align-items: center;
+  gap: var(--layout-space-3);
+  inline-size: 100%;
+  min-block-size: var(--control-height-3);
+  padding-inline: var(--layout-space-3);
+  border-radius: var(--radius-control-3);
+  color: var(--gray-12);
+  font-size: var(--font-size-3);
+  line-height: var(--line-height-3);
+  text-align: start;
+  cursor: var(--cursor-button);
+}
+
+.kui-NavigatorLinkLabel {
+  display: flex;
+  align-items: center;
+  gap: var(--layout-space-3);
+  flex: 1;
+  min-inline-size: 0;
+}
+
+.kui-NavigatorLinkGlyph {
+  flex-shrink: 0;
+  color: var(--gray-a10);
+}
+
+@media (hover: hover) {
+  .kui-NavigatorLink:where(:hover) {
+    background-color: var(--gray-a3);
+  }
+}
+
+.kui-NavigatorLink:where(:active) {
+  background-color: var(--gray-a4);
+}
+
+.kui-NavigatorLink:where(:focus-visible) {
+  outline: 2px solid var(--focus-8);
+  outline-offset: -2px;
+}