@womp/kookie-ui 0.14.0 → 0.14.1

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

@@ -0,0 +1,90 @@
+'use client';
+
+/**
+ * A pane's own chrome: a header row, a scrolling region and a footer row.
+ *
+ * Shell.Sidebar and Shell.Panel render these as `Shell.PaneHeader`, `Shell.Scroll` and
+ * `Shell.PaneFooter`. The pane renders anything; with these parts it is the presentation, so
+ * Sidebar's menu parts work inside it with no `Sidebar.Root`. The index comes from the nearest
+ * Shell (`Shell.Root size`), or from a deprecated `Sidebar.Root` that still wraps them.
+ */
+
+import * as React from 'react';
+import classNames from 'classnames';
+
+import { ScrollArea } from '../scroll-area.js';
+
+type PaneSize = '1' | '2' | '3';
+
+type SidebarVisualContextValue = {
+  size: PaneSize;
+  menuVariant: 'solid' | 'soft';
+  presentation?: 'thin' | 'expanded';
+  color?: string;
+};
+
+/** Size, menu highlight and presentation for the Sidebar parts. Internal: not exported. */
+const SidebarVisualContext = React.createContext<SidebarVisualContextValue | null>(null);
+
+function useSidebarVisual() {
+  return React.useContext(SidebarVisualContext);
+}
+
+/** The Shell's index. `Shell.Root size` sets it; panes hand it to their chrome. */
+const ShellSizeContext = React.createContext<PaneSize>('2');
+
+/**
+ * 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.
+ */
+function PaneChromeScope({ children, presentation }: { children: React.ReactNode; presentation?: 'thin' }) {
+  const size = React.useContext(ShellSizeContext);
+  const value = React.useMemo<SidebarVisualContextValue>(() => ({ size, menuVariant: 'soft', presentation }), [size, presentation]);
+  return <SidebarVisualContext.Provider value={value}>{children}</SidebarVisualContext.Provider>;
+}
+
+function useChromeClasses() {
+  const visual = useSidebarVisual();
+  const size = visual?.size ?? '2';
+  const menuVariant = visual?.menuVariant ?? 'soft';
+  return ['rt-ShellPaneChrome', `rt-r-size-${size}`, `rt-menu-variant-${menuVariant}`];
+}
+
+interface PaneHeaderProps extends React.ComponentPropsWithoutRef<'div'> {}
+
+/** A pane's header row, pinned above its scrolling region. */
+const PaneHeader = React.forwardRef<HTMLDivElement, PaneHeaderProps>(({ className, ...props }, forwardedRef) => {
+  const chrome = useChromeClasses();
+  return <div {...props} ref={forwardedRef} className={classNames('rt-ShellPaneHeader', 'rt-SidebarHeader', 'rt-SidebarHeader--container', ...chrome, className)} />;
+});
+PaneHeader.displayName = 'Shell.PaneHeader';
+
+interface PaneFooterProps extends React.ComponentPropsWithoutRef<'div'> {}
+
+/** A pane's footer row, pinned below its scrolling region. */
+const PaneFooter = React.forwardRef<HTMLDivElement, PaneFooterProps>(({ className, ...props }, forwardedRef) => {
+  const chrome = useChromeClasses();
+  return <div {...props} ref={forwardedRef} className={classNames('rt-ShellPaneFooter', 'rt-SidebarFooter', 'rt-SidebarFooter--container', ...chrome, className)} />;
+});
+PaneFooter.displayName = 'Shell.PaneFooter';
+
+interface ScrollProps extends React.ComponentPropsWithoutRef<'div'> {}
+
+/**
+ * The one region of a pane that scrolls; it takes the room the header and footer leave.
+ * It is not a landmark: for navigation, pass `role="navigation"` and an `aria-label`.
+ */
+const Scroll = React.forwardRef<HTMLDivElement, ScrollProps>(({ className, children, ...props }, forwardedRef) => {
+  const chrome = useChromeClasses();
+  return (
+    <ScrollArea type="hover" className="rt-ShellScroll">
+      <div {...props} ref={forwardedRef} className={classNames('rt-BaseMenuContent', 'rt-SidebarContent', ...chrome, className)}>
+        <div className="rt-BaseMenuViewport">{children}</div>
+      </div>
+    </ScrollArea>
+  );
+});
+Scroll.displayName = 'Shell.Scroll';
+
+export { SidebarVisualContext, useSidebarVisual, ShellSizeContext, PaneChromeScope, PaneHeader, PaneFooter, Scroll };
+export type { SidebarVisualContextValue, PaneSize, PaneHeaderProps, PaneFooterProps, ScrollProps };

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

@@ -10,14 +10,17 @@ import { splitHandles, useResizablePane, type SizeChangeMeta } from './shell-res
 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 { warnDeprecated } from '../../helpers/warn-deprecated.js';
+import { PaneChromeScope } from './pane-chrome.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, Responsive, SidebarMode } from '../shell.types.js';
 
 type SidebarStateChangeMeta = { reason: 'init' | 'toggle' | 'responsive' | 'dismiss' };
 type SidebarControlledProps = { state: Responsive<SidebarMode>; onStateChange?: (state: SidebarMode, meta: SidebarStateChangeMeta) => void; defaultState?: never };
 type SidebarUncontrolledProps = { defaultState?: SidebarMode | Partial<Record<Breakpoint, SidebarMode>>; onStateChange?: (state: SidebarMode, meta: SidebarStateChangeMeta) => void; state?: never };
 type SidebarPublicProps = PaneBaseProps & {
+  /** @deprecated Thin mode is removed in 0.15.0. Use `Shell.Rail`. */
   thinSize?: number;
-  /** `both` toggles through collapsed, thin and expanded; `single` between collapsed and the default. */
+  /** `both` (deprecated with thin mode; `single` is the 0.15.0 behaviour) toggles through collapsed, thin and expanded; `single` between collapsed and the default. */
   toggleModes?: 'both' | 'single';
   size?: number | string;
   defaultSize?: number | string;
@@ -109,6 +112,12 @@ export const Sidebar = React.forwardRef<HTMLDivElement, SidebarPublicProps>((pro
   });
   useInsetRegistration('sidebar', inset);
 
+  if (props.thinSize !== undefined || pane.value === 'thin') {
+    warnDeprecated(
+      "Shell.Sidebar's thin mode is deprecated and will be removed in 0.15.0. Put the rows in Shell.Rail, which draws them as tiles, and use toggleModes=\"single\" so the toggle skips thin.",
+    );
+  }
+
   React.useEffect(() => {
     if (snapPoints !== undefined || collapseThreshold !== undefined || paneId !== undefined || persistence !== undefined) {
       warnOnce('Shell.Sidebar: `snapPoints`, `collapseThreshold`, `paneId` and `persistence` are deprecated and are removed in 1.0. Keep the size in your own state with `size`/`onSizeChange`.');
@@ -184,7 +193,9 @@ export const Sidebar = React.forwardRef<HTMLDivElement, SidebarPublicProps>((pro
         } as CSSPropertiesWithVars
       }
     >
-      <div className="rt-ShellSidebarContent">{content}</div>
+      <div className="rt-ShellSidebarContent">
+        <PaneChromeScope>{content}</PaneChromeScope>
+      </div>
       {handle}
     </div>
   );

package/src/components/shell.css

@@ -207,6 +207,12 @@
   gap: var(--space-2);
 }
 
+/* Shell.Scroll takes the room a pane's header and footer leave, and scrolls inside it. */
+.rt-ShellScroll {
+  flex: 1;
+  min-height: 0;
+}
+
 /* Closed is closed, in every posture: out of the layout, the tab order and the accessibility tree. */
 .rt-ShellPane[data-state='closed'] {
   display: none;

package/src/components/shell.tsx

@@ -47,6 +47,8 @@ import { navigationRest, detailRest, toPaneValue, startAnchoredGrowth, withoutRe
 import { useShell, useSidebarMode } from './shell.context.js';
 import { useResponsivePresentation } from './shell.hooks.js';
 import { readBreakpoint } from '../hooks/use-breakpoint.js';
+import { PaneChromeScope, PaneFooter, PaneHeader, Scroll, ShellSizeContext } from './_internal/pane-chrome.js';
+import type { PaneSize } from './_internal/pane-chrome.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, PaneMode, PaneName, PaneTarget, ResponsivePresentation, SidebarMode } from './shell.types.js';
 
 /* ── Root ──────────────────────────────────────────────────────────────────── */
@@ -54,6 +56,8 @@ import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, PaneMode, PaneNa
 export interface ShellRootProps extends React.ComponentPropsWithoutRef<'div'> {
   children: React.ReactNode;
   height?: 'full' | 'auto' | string | number;
+  /** The index the panes' chrome takes: `Shell.PaneHeader`, `Shell.Scroll`, `Shell.PaneFooter` and the Sidebar rows in them. Default `2`. */
+  size?: PaneSize;
 }
 
 /**
@@ -92,7 +96,7 @@ function triggerFor(doc: Document, id: string, within?: HTMLElement[]): HTMLElem
 
 type LivePane = { name: PaneName; id: string; el: HTMLElement };
 
-const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', style, onKeyDown, onFocus, ...props }, ref) => {
+const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', size = '2', style, onKeyDown, onFocus, ...props }, ref) => {
   const [store] = React.useState(createShellStore);
   const subscribe = React.useCallback((listener: () => void) => subscribeShellStore(store, listener), [store]);
   // Subscribed for the re-render, not for a value: a pane opening or closing
@@ -354,6 +358,7 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
 
   return (
     <ShellStoreContext.Provider value={store}>
+      <ShellSizeContext.Provider value={size}>
       <ShellInsetContext.Provider value={insetContext}>
         {/* The Root is not a widget: it hears Escape bubbling up from the panes,
             after their own handlers, to close the overlays. */}
@@ -376,6 +381,7 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
           <div className="rt-ShellScrim" aria-hidden onClick={closeOverlays} />
         </div>
       </ShellInsetContext.Provider>
+      </ShellSizeContext.Provider>
     </ShellStoreContext.Provider>
   );
 });
@@ -480,12 +486,22 @@ const Rail = React.forwardRef<HTMLDivElement, RailProps>((props, ref) => {
       tabIndex={pane.overlaying ? -1 : domProps.tabIndex}
       style={{ ...style, '--rail-size': `${expandedSize}px` } as CSSPropertiesWithVars}
     >
-      <div className="rt-ShellRailContent">{children}</div>
+      <RailContent>{children}</RailContent>
     </div>
   );
 });
 Rail.displayName = 'Shell.Rail';
 
+/** The Rail's content carries the index, so the thin row styles can size themselves by it. */
+function RailContent({ children }: { children: React.ReactNode }) {
+  const size = React.useContext(ShellSizeContext);
+  return (
+    <div className={classNames('rt-ShellRailContent', `rt-r-size-${size}`)}>
+      <PaneChromeScope presentation="thin">{children}</PaneChromeScope>
+    </div>
+  );
+}
+
 /* ── Panel ─────────────────────────────────────────────────────────────────── */
 
 type HandleComponent = React.ForwardRefExoticComponent<React.ComponentPropsWithoutRef<'div'> & React.RefAttributes<HTMLDivElement>>;
@@ -640,7 +656,9 @@ const Panel = React.forwardRef<HTMLDivElement, PanelPublicProps>((props, ref) =>
         } as CSSPropertiesWithVars
       }
     >
-      <div className="rt-ShellPanelContent">{content}</div>
+      <div className="rt-ShellPanelContent">
+        <PaneChromeScope>{content}</PaneChromeScope>
+      </div>
       {handle}
     </div>
   );
@@ -750,6 +768,9 @@ export {
   Inspector,
   Bottom,
   Trigger,
+  PaneHeader,
+  PaneFooter,
+  Scroll,
   useShell,
   useSidebarMode,
   useResponsivePresentation,