@womp/kookie-ui 0.7.0 → 0.8.0

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

@@ -0,0 +1,204 @@
+'use client';
+
+/**
+ * The Shell's state model (0.8.0), ported from kookie-ui-v2's Shell.
+ *
+ * - State lives on the pane. Each pane holds `auto | open | closed` (the
+ *   Sidebar adds `thin`). `auto` means untouched: the stylesheet decides what
+ *   it shows at each breakpoint, so first paint is right with no script, the
+ *   server and the client render the same markup, and no open-state callback
+ *   can fire on mount or on a resize.
+ * - The one thing that crosses the Shell is a registry keyed by pane name.
+ *   Each pane registers what it is and how to drive it; a Trigger looks its
+ *   pane up, and the Root reads the set of live overlays. Nothing scans
+ *   children and nothing checks `displayName`.
+ * - The responsive props are resolved into a table with one value per
+ *   breakpoint, from the props alone, with no window. The table is written to
+ *   the DOM as data attributes for the stylesheet, and read again in JS by the
+ *   mirror that sets `aria-expanded`. One table, two readers, so they agree by
+ *   construction.
+ */
+import * as React from 'react';
+import { SHELL_BREAKPOINTS } from '../shell.types.js';
+import type { Breakpoint, PaneName, PresentationValue } from '../shell.types.js';
+
+/* ── Breakpoint tables ─────────────────────────────────────────────────────── */
+
+export type Table<T> = Record<Breakpoint, T>;
+
+/** What a pane shows: open, open at its thin width (Sidebar only), or closed. */
+export type PaneValue = 'open' | 'thin' | 'closed';
+
+type ResponsiveInput<T> = T | Partial<Record<Breakpoint, T>> | undefined;
+
+function isMap<T>(value: ResponsiveInput<T>): value is Partial<Record<Breakpoint, T>> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * A responsive value at every breakpoint. A breakpoint takes the largest key
+ * at or below it, the same fallback `useResponsiveValue` used; a breakpoint
+ * below every key takes `fallback`.
+ */
+export function tableOf<T>(value: ResponsiveInput<T>, fallback: (bp: Breakpoint) => T): Table<T> {
+  const table = {} as Table<T>;
+  let carried: { value: T } | null = null;
+  for (const bp of SHELL_BREAKPOINTS) {
+    if (value !== undefined && !isMap(value)) {
+      table[bp] = value;
+      continue;
+    }
+    const entry = isMap(value) ? value[bp] : undefined;
+    if (entry !== undefined) carried = { value: entry };
+    table[bp] = carried ? carried.value : fallback(bp);
+  }
+  return table;
+}
+
+/** The table's one value, when it has only one. */
+export function constantOf<T>(table: Table<T>): T | undefined {
+  const first = table.initial;
+  return SHELL_BREAKPOINTS.every((bp) => table[bp] === first) ? first : undefined;
+}
+
+/**
+ * The table as data attributes: `data-<name>` when it holds one value, one
+ * `data-<name>-<bp>` per breakpoint when it holds several. The stylesheet has
+ * a rule for each spelling.
+ */
+export function tableAttributes(name: string, table: Table<string>): Record<string, string> {
+  const constant = constantOf(table);
+  if (constant !== undefined) return { [`data-${name}`]: constant };
+  const attributes: Record<string, string> = {};
+  for (const bp of SHELL_BREAKPOINTS) attributes[`data-${name}-${bp}`] = table[bp];
+  return attributes;
+}
+
+/**
+ * A responsive prop object is usually an inline literal, a new identity every
+ * render. Keying memoisation on its contents keeps the tables, and so the
+ * registry entries, stable across renders that change nothing.
+ */
+export function useStableKey(value: unknown): string {
+  return typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+}
+
+export const FIXED_TABLE: Table<PresentationValue> = tableOf<PresentationValue>('fixed', () => 'fixed');
+
+/* ── The registry ──────────────────────────────────────────────────────────── */
+
+export type OpenChangeReason = 'toggle' | 'dismiss';
+
+export type PaneEntry = {
+  name: PaneName;
+  id: string;
+  el: HTMLElement | null;
+  /** What the pane shows now; `undefined` while an untouched pane cannot know (before the breakpoint is known). */
+  value: PaneValue | undefined;
+  /** How the pane is presented now, when known. */
+  presentation: PresentationValue | undefined;
+  /** The pane's own presentation at every breakpoint. A Panel with none of its own follows the Rail's. */
+  presentationTable: Table<PresentationValue>;
+  /** Open and presented as an overlay: what the scrim and Escape close, and what containment exempts. */
+  overlayLive: boolean;
+  /** The pane's designed open width, for panes that sit beside it when floating. */
+  size: number;
+  setValue: (value: PaneValue, reason: OpenChangeReason) => void;
+  toggle: (reason: OpenChangeReason) => void;
+};
+
+export type ShellStore = {
+  entries: Map<PaneName, PaneEntry>;
+  listeners: Set<() => void>;
+  /**
+   * What a subscriber reads. useSyncExternalStore needs a value that is stable
+   * between notifications, and a number is; the Map, or anything derived from
+   * it, would be a new identity on every read.
+   */
+  version: number;
+  /** The pane a hovered Trigger is previewing, if any. Layout only. */
+  peek: PaneName | null;
+};
+
+export function createShellStore(): ShellStore {
+  return { entries: new Map(), listeners: new Set(), version: 0, peek: null };
+}
+
+export function notifyShellStore(store: ShellStore) {
+  store.version += 1;
+  for (const listener of store.listeners) listener();
+}
+
+export function subscribeShellStore(store: ShellStore, listener: () => void) {
+  store.listeners.add(listener);
+  return () => {
+    store.listeners.delete(listener);
+  };
+}
+
+export function setShellPeek(store: ShellStore, peek: PaneName | null) {
+  if (store.peek === peek) return;
+  store.peek = peek;
+  notifyShellStore(store);
+}
+
+export const ShellStoreContext = React.createContext<ShellStore | null>(null);
+
+export function useShellStore(part: string): ShellStore {
+  const store = React.useContext(ShellStoreContext);
+  if (!store) throw new Error(`${part} must be used within <Shell.Root>`);
+  return store;
+}
+
+/** One pane's registry entry. Re-renders only when that entry is replaced. */
+export function usePaneEntry(store: ShellStore, name: PaneName): PaneEntry | undefined {
+  const subscribe = React.useCallback((listener: () => void) => subscribeShellStore(store, listener), [store]);
+  const getSnapshot = React.useCallback(() => store.entries.get(name), [store, name]);
+  return React.useSyncExternalStore(subscribe, getSnapshot, () => undefined);
+}
+
+/**
+ * Whether this pane is the one being previewed. A boolean per pane rather than
+ * the peek target itself, so hovering one Trigger re-renders one pane, not all.
+ */
+export function usePeeking(store: ShellStore, name: PaneName): boolean {
+  const subscribe = React.useCallback((listener: () => void) => subscribeShellStore(store, listener), [store]);
+  return React.useSyncExternalStore(
+    subscribe,
+    () => store.peek === name,
+    () => false,
+  );
+}
+
+/* ── Inset ─────────────────────────────────────────────────────────────────── */
+
+export type InsetPaneId = 'rail' | 'panel' | 'sidebar' | 'content' | 'inspector' | 'bottom';
+
+export const ShellInsetContext = React.createContext<{
+  registerInset: (id: InsetPaneId) => void;
+  unregisterInset: (id: InsetPaneId) => void;
+} | null>(null);
+
+/** Registers a pane's `inset` with the Root, which paints the backdrop while any pane is inset. */
+export function useInsetRegistration(id: InsetPaneId, inset: boolean | undefined) {
+  const ctx = React.useContext(ShellInsetContext);
+  if (!ctx) throw new Error('Shell panes must be used within <Shell.Root>');
+  const { registerInset, unregisterInset } = ctx;
+  React.useLayoutEffect(() => {
+    if (!inset) return;
+    registerInset(id);
+    return () => unregisterInset(id);
+  }, [id, inset, registerInset, unregisterInset]);
+}
+
+/* ── Development warnings ──────────────────────────────────────────────────── */
+
+const warned = new Set<string>();
+
+/** A deprecation warning, once per message per page load. Development only. */
+export function warnOnce(message: string) {
+  if (process.env.NODE_ENV === 'production') return;
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[kookie-ui] ${message}`);
+}

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

@@ -1,112 +1,118 @@
 import { z } from 'zod';
 
 /**
- * Shell Zod schema - Single source of truth for Shell component props
+ * Shell Zod schema: the Shell's props, for tools that read a schema
+ * (editors, assistants, documentation).
  *
- * The Shell component is a layout engine that provides structural patterns for building
- * application interfaces. It manages layout state, composition rules, and responsive
- * behavior across seven core slots.
+ * Shell is the frame of an application. Each pane holds its own open state;
+ * a pane nobody has touched follows the window, and the stylesheet resolves
+ * it at each breakpoint. Callbacks report user actions only.
  *
  * @example
  * ```tsx
- * // Basic shell validation
  * const props = ShellRootSchema.parse({ height: 'full' });
  *
- * // Shell with responsive sidebar
  * const sidebarProps = ShellSidebarSchema.parse({
- *   defaultMode: { initial: 'collapsed', md: 'expanded' },
- *   presentation: { initial: 'overlay', lg: 'fixed' }
+ *   defaultState: { initial: 'collapsed', md: 'expanded' },
+ *   presentation: { initial: 'overlay', sm: 'fixed' },
  * });
  * ```
  */
 
 // Common types
 const PaneModeSchema = z.enum(['expanded', 'collapsed']).describe('Pane state mode');
-const SidebarModeSchema = z.enum(['collapsed', 'thin', 'expanded']).describe('Sidebar state mode');
+const SidebarModeSchema = z.enum(['collapsed', 'thin', 'expanded']).describe('Sidebar state');
 const PresentationValueSchema = z.enum(['fixed', 'overlay', 'stacked']).describe('Presentation mode');
 const _BreakpointSchema = z.enum(['initial', 'xs', 'sm', 'md', 'lg', 'xl']).describe('Responsive breakpoint');
-const PaneTargetSchema = z.enum(['left', 'rail', 'panel', 'sidebar', 'inspector', 'bottom']).describe('Pane target');
+const PaneTargetSchema = z.enum(['left', 'rail', 'panel', 'sidebar', 'inspector', 'bottom']).describe('Pane target. `left` is deprecated: use `rail`.');
 const TriggerActionSchema = z.enum(['toggle', 'expand', 'collapse']).describe('Trigger action');
+const OpenChangeReasonSchema = z.enum(['toggle', 'dismiss']).describe('Why the state changed: `toggle` for a trigger or the resize handle, `dismiss` for Escape or the scrim');
+const SizeChangeReasonSchema = z.enum(['init', 'resize', 'controlled']).describe('Why the size changed');
 
-// Responsive schemas
-const ResponsiveModeSchema = z
-  .union([
-    PaneModeSchema,
+function responsive<T extends z.ZodTypeAny>(value: T) {
+  return z.union([
+    value,
     z.object({
-      initial: PaneModeSchema.optional(),
-      xs: PaneModeSchema.optional(),
-      sm: PaneModeSchema.optional(),
-      md: PaneModeSchema.optional(),
-      lg: PaneModeSchema.optional(),
-      xl: PaneModeSchema.optional(),
+      initial: value.optional(),
+      xs: value.optional(),
+      sm: value.optional(),
+      md: value.optional(),
+      lg: value.optional(),
+      xl: value.optional(),
     }),
-  ])
-  .describe('Responsive pane mode configuration');
-
-const ResponsiveSidebarModeSchema = z
-  .union([
-    SidebarModeSchema,
-    z.object({
-      initial: SidebarModeSchema.optional(),
-      xs: SidebarModeSchema.optional(),
-      sm: SidebarModeSchema.optional(),
-      md: SidebarModeSchema.optional(),
-      lg: SidebarModeSchema.optional(),
-      xl: SidebarModeSchema.optional(),
-    }),
-  ])
-  .describe('Responsive sidebar mode configuration');
+  ]);
+}
 
-const ResponsivePresentationSchema = z
-  .union([
-    PresentationValueSchema,
-    z.object({
-      initial: PresentationValueSchema.optional(),
-      xs: PresentationValueSchema.optional(),
-      sm: PresentationValueSchema.optional(),
-      md: PresentationValueSchema.optional(),
-      lg: PresentationValueSchema.optional(),
-      xl: PresentationValueSchema.optional(),
-    }),
-  ])
-  .describe('Responsive presentation configuration');
+// Responsive schemas
+const _ResponsiveModeSchema = responsive(PaneModeSchema).describe('Responsive pane mode configuration');
+const ResponsiveSidebarModeSchema = responsive(SidebarModeSchema).describe('Responsive sidebar state');
+const ResponsivePresentationSchema = responsive(PresentationValueSchema).describe('Responsive presentation configuration');
+const ResponsiveOpenSchema = responsive(z.boolean()).describe('Responsive open state');
 
-// Size persistence adapter
+// Size persistence adapter (deprecated)
 const PaneSizePersistenceSchema = z
   .object({
     load: z.function({ output: z.union([z.number(), z.promise(z.number()), z.undefined()]) }).optional(),
     save: z.function({ input: [z.number()], output: z.union([z.void(), z.promise(z.void())]) }).optional(),
   })
-  .describe('Size persistence adapter');
+  .describe('Deprecated, removed in 1.0. Keep the size in your own state with `size`/`onSizeChange`.');
 
-// Common pane props
-const PanePropsSchema = z
-  .object({
-    presentation: ResponsivePresentationSchema.optional(),
-    mode: PaneModeSchema.optional(),
-    defaultMode: ResponsiveModeSchema.optional(),
-    onModeChange: z.function({ input: [PaneModeSchema], output: z.void() }).optional(),
-    expandedSize: z.number().optional(),
-    minSize: z.number().optional(),
-    maxSize: z.number().optional(),
-    resizable: z.boolean().optional(),
-    collapsible: z.boolean().optional(),
-    onExpand: z.function({ output: z.void() }).optional(),
-    onCollapse: z.function({ output: z.void() }).optional(),
-    onResize: z.function({ input: [z.number()], output: z.void() }).optional(),
-    resizer: z.any().optional(),
-    onResizeStart: z.function({ input: [z.number()], output: z.void() }).optional(),
-    onResizeEnd: z.function({ input: [z.number()], output: z.void() }).optional(),
-    snapPoints: z.array(z.number()).optional(),
-    snapTolerance: z.number().optional(),
-    collapseThreshold: z.number().optional(),
-    paneId: z.string().optional(),
-    persistence: PaneSizePersistenceSchema.optional(),
-    className: z.string().optional(),
-    style: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
-    children: z.any().optional(),
-  })
-  .strict();
+const StyleSchema = z
+  .record(z.string(), z.union([z.string(), z.number()]))
+  .optional()
+  .describe('Inline styles');
+
+const OpenPropsSchema = {
+  open: z.union([z.boolean(), ResponsiveOpenSchema]).optional().describe('The open state, when controlled. A responsive object is deprecated.'),
+  defaultOpen: z
+    .union([z.boolean(), ResponsiveOpenSchema])
+    .optional()
+    .describe('The starting state. A responsive object leaves the pane untouched, with that object as the answer at each breakpoint.'),
+  onOpenChange: z
+    .function({ input: [z.boolean(), z.object({ reason: OpenChangeReasonSchema })], output: z.void() })
+    .optional()
+    .describe('Called when a user opens or closes the pane. Never called on mount or on a resize.'),
+};
+
+// Props shared by every pane
+const PaneBaseShape = {
+  id: z.string().optional().describe('The pane id. A Trigger points `aria-controls` at it.'),
+  presentation: ResponsivePresentationSchema.optional(),
+  expandedSize: z.number().optional(),
+  inset: z.boolean().optional().describe('Lifts the pane off the frame and paints the backdrop behind it'),
+  onExpand: z.function({ output: z.void() }).optional().describe('Deprecated: use `onOpenChange`'),
+  onCollapse: z.function({ output: z.void() }).optional().describe('Deprecated: use `onOpenChange`'),
+  className: z.string().optional().describe('Additional CSS class name'),
+  style: StyleSchema,
+  children: z.any().optional(),
+};
+
+// Props of a pane that resizes
+const ResizeShape = {
+  minSize: z.number().optional(),
+  maxSize: z.number().optional().describe('The largest size. A drag also stops before the handle leaves the frame.'),
+  resizable: z.boolean().optional(),
+  collapsible: z.boolean().optional().describe('A double-click on the handle closes the pane'),
+  size: z.union([z.number(), z.string()]).optional().describe('The size, when controlled'),
+  defaultSize: z.union([z.number(), z.string()]).optional().describe('The starting size'),
+  onSizeChange: z.function({ input: [z.number(), z.object({ reason: SizeChangeReasonSchema })], output: z.void() }).optional(),
+  sizeUpdate: z
+    .enum(['throttle', 'debounce'])
+    .optional()
+    .describe('Rate-limits onSizeChange across repeated resize ends, such as key presses on the handle. A drag calls it once, when the drag ends; use onResize for live sizes.'),
+  sizeUpdateMs: z.number().optional(),
+  onResize: z
+    .function({ input: [z.number()], output: z.void() })
+    .optional()
+    .describe('Called during a drag, at most once per animation frame'),
+  onResizeStart: z.function({ input: [z.number()], output: z.void() }).optional(),
+  onResizeEnd: z.function({ input: [z.number()], output: z.void() }).optional(),
+  snapPoints: z.array(z.number()).optional().describe('Deprecated, removed in 1.0'),
+  snapTolerance: z.number().optional().describe('Deprecated, removed in 1.0'),
+  collapseThreshold: z.number().optional().describe('Deprecated, removed in 1.0'),
+  paneId: z.string().optional().describe('Deprecated, removed in 1.0'),
+  persistence: PaneSizePersistenceSchema.optional(),
+};
 
 /**
  * Shell.Root component schema
@@ -116,13 +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 shell container'),
+      .describe('Height of the frame. `full` is 100dvh, with 100vh where dvh is not supported.'),
     className: z.string().optional().describe('Additional CSS class name'),
-    style: z
-      .record(z.string(), z.union([z.string(), z.number()]))
-      .optional()
-      .describe('Inline styles'),
-    children: z.any().optional().describe('Shell components'),
+    style: StyleSchema,
+    children: z.any().optional().describe('The Shell parts, and anything else, rendered in order'),
   })
   .strict();
 
@@ -131,12 +134,9 @@ export const ShellRootSchema = z
  */
 export const ShellHeaderSchema = z
   .object({
-    height: z.union([z.string(), z.number()]).default(64).describe('Height of the header'),
+    height: z.number().default(64).describe('Height of the header, in pixels'),
     className: z.string().optional().describe('Additional CSS class name'),
-    style: z
-      .record(z.string(), z.union([z.string(), z.number()]))
-      .optional()
-      .describe('Inline styles'),
+    style: StyleSchema,
     children: z.any().optional().describe('Header content'),
   })
   .strict();
@@ -146,59 +146,63 @@ export const ShellHeaderSchema = z
  */
 export const ShellRailSchema = z
   .object({
-    presentation: ResponsivePresentationSchema.optional(),
-    mode: PaneModeSchema.optional(),
-    defaultMode: ResponsiveModeSchema.optional(),
-    onModeChange: z.function({ input: [PaneModeSchema], output: z.void() }).optional(),
-    expandedSize: z.number().default(64).describe('Default width in pixels'),
+    ...PaneBaseShape,
+    ...OpenPropsSchema,
+    presentation: ResponsivePresentationSchema.default('fixed').describe('Presentation mode'),
+    expandedSize: z.number().default(64).describe('Width in pixels'),
     collapsible: z.boolean().optional(),
-    onExpand: z.function({ output: z.void() }).optional(),
-    onCollapse: z.function({ output: z.void() }).optional(),
-    className: z.string().optional().describe('Additional CSS class name'),
-    style: z
-      .record(z.string(), z.union([z.string(), z.number()]))
-      .optional()
-      .describe('Inline styles'),
-    children: z.any().optional().describe('Rail content'),
   })
   .strict();
 
 /**
  * Shell.Panel component schema
  */
-export const ShellPanelSchema = PanePropsSchema.extend({
-  expandedSize: z.number().default(288).describe('Default width in pixels'),
-  minSize: z.number().default(200).describe('Minimum width when resizing'),
-  maxSize: z.number().default(800).describe('Maximum width when resizing'),
-  resizable: z.boolean().default(false).describe('Whether the panel can be resized'),
-  collapsible: z.boolean().default(true).describe('Whether the panel can be collapsed via resize handle'),
-}).strict();
+export const ShellPanelSchema = z
+  .object({
+    ...PaneBaseShape,
+    ...OpenPropsSchema,
+    ...ResizeShape,
+    presentation: ResponsivePresentationSchema.optional().describe("Presentation mode. With no value the panel follows the Rail's."),
+    expandedSize: z.number().default(288).describe('Open width in pixels'),
+    minSize: z.number().default(100).describe('Minimum width when resizing'),
+    maxSize: z.number().default(800).describe('Maximum width when resizing'),
+    resizable: z.boolean().default(false).describe('Whether the panel can be resized'),
+    collapsible: z.boolean().default(true).describe('Whether a double-click on the handle closes the panel'),
+  })
+  .strict();
 
 /**
  * Shell.Sidebar component schema
  */
-export const ShellSidebarSchema = PanePropsSchema.extend({
-  mode: SidebarModeSchema.optional(),
-  defaultMode: ResponsiveSidebarModeSchema.default('expanded').describe('Initial sidebar mode'),
-  expandedSize: z.number().default(288).describe('Default width in pixels'),
-  minSize: z.number().default(200).describe('Minimum width when resizing'),
-  maxSize: z.number().default(400).describe('Maximum width when resizing'),
-  thinSize: z.number().default(64).describe('Width in thin mode'),
-  toggleModes: z.enum(['both', 'single']).optional().describe('Available modes in toggle sequence'),
-  resizable: z.boolean().default(false).describe('Whether the sidebar can be resized'),
-  collapsible: z.boolean().default(true).describe('Whether the sidebar can be collapsed via resize handle'),
-}).strict();
+export const ShellSidebarSchema = z
+  .object({
+    ...PaneBaseShape,
+    ...ResizeShape,
+    state: z.union([SidebarModeSchema, ResponsiveSidebarModeSchema]).optional().describe('The state, when controlled. A responsive object is deprecated.'),
+    defaultState: ResponsiveSidebarModeSchema.optional().describe('The starting state. With no value the sidebar is open where it is in the frame and closed where it is an overlay.'),
+    onStateChange: z
+      .function({ input: [SidebarModeSchema, z.object({ reason: OpenChangeReasonSchema })], output: z.void() })
+      .optional()
+      .describe('Called when a user changes the state. Never called on mount or on a resize.'),
+    presentation: ResponsivePresentationSchema.default({ initial: 'overlay', sm: 'fixed' }).describe('Presentation mode'),
+    expandedSize: z.number().default(288).describe('Open width in pixels'),
+    minSize: z.number().default(200).describe('Minimum width when resizing'),
+    maxSize: z.number().default(400).describe('Maximum width when resizing'),
+    thinSize: z.number().default(64).describe('Width in the thin state'),
+    toggleModes: z.enum(['both', 'single']).default('both').describe('`both` goes collapsed, thin, expanded; `single` goes between collapsed and one open state'),
+    resizable: z.boolean().default(false).describe('Whether the sidebar can be resized'),
+    collapsible: z.boolean().default(true).describe('Whether a double-click on the handle closes the sidebar'),
+  })
+  .strict();
 
 /**
  * Shell.Content component schema
  */
 export const ShellContentSchema = z
   .object({
+    inset: z.boolean().optional().describe('Lifts the pane off the frame and paints the backdrop behind it'),
     className: z.string().optional().describe('Additional CSS class name'),
-    style: z
-      .record(z.string(), z.union([z.string(), z.number()]))
-      .optional()
-      .describe('Inline styles'),
+    style: StyleSchema,
     children: z.any().optional().describe('Main content'),
   })
   .strict();
@@ -206,42 +210,50 @@ export const ShellContentSchema = z
 /**
  * Shell.Inspector component schema
  */
-export const ShellInspectorSchema = PanePropsSchema.extend({
-  presentation: ResponsivePresentationSchema.default({ initial: 'overlay', lg: 'fixed' }).describe('Presentation mode'),
-  expandedSize: z.number().default(320).describe('Default width in pixels'),
-  minSize: z.number().default(200).describe('Minimum width when resizing'),
-  maxSize: z.number().default(500).describe('Maximum width when resizing'),
-  resizable: z.boolean().default(false).describe('Whether the inspector can be resized'),
-  collapsible: z.boolean().default(true).describe('Whether the inspector can be collapsed via resize handle'),
-}).strict();
+export const ShellInspectorSchema = z
+  .object({
+    ...PaneBaseShape,
+    ...OpenPropsSchema,
+    ...ResizeShape,
+    presentation: ResponsivePresentationSchema.default({ initial: 'overlay', sm: 'fixed' }).describe('Presentation mode'),
+    expandedSize: z.number().default(320).describe('Open width in pixels'),
+    minSize: z.number().default(200).describe('Minimum width when resizing'),
+    maxSize: z.number().default(500).describe('Maximum width when resizing'),
+    resizable: z.boolean().default(false).describe('Whether the inspector can be resized'),
+    collapsible: z.boolean().default(true).describe('Whether a double-click on the handle closes the inspector'),
+  })
+  .strict();
 
 /**
  * Shell.Bottom component schema
  */
-export const ShellBottomSchema = PanePropsSchema.extend({
-  presentation: ResponsivePresentationSchema.default('fixed').describe('Presentation mode'),
-  expandedSize: z.number().default(200).describe('Default height in pixels'),
-  minSize: z.number().default(100).describe('Minimum height when resizing'),
-  maxSize: z.number().default(400).describe('Maximum height when resizing'),
-  resizable: z.boolean().default(false).describe('Whether the bottom panel can be resized'),
-  collapsible: z.boolean().default(true).describe('Whether the bottom panel can be collapsed via resize handle'),
-}).strict();
+export const ShellBottomSchema = z
+  .object({
+    ...PaneBaseShape,
+    ...OpenPropsSchema,
+    ...ResizeShape,
+    presentation: ResponsivePresentationSchema.default('fixed').describe('Presentation mode'),
+    expandedSize: z.number().default(200).describe('Open height in pixels'),
+    minSize: z.number().default(100).describe('Minimum height when resizing'),
+    maxSize: z.number().default(400).describe('Maximum height when resizing'),
+    resizable: z.boolean().default(false).describe('Whether the bottom panel can be resized'),
+    collapsible: z.boolean().default(true).describe('Whether a double-click on the handle closes the panel'),
+  })
+  .strict();
 
 /**
  * Shell.Trigger component schema
  */
 export const ShellTriggerSchema = z
   .object({
-    target: PaneTargetSchema.describe('Which pane to control'),
+    target: PaneTargetSchema.describe('Which pane to drive'),
     action: TriggerActionSchema.default('toggle').describe('Action to perform'),
-    peekOnHover: z.boolean().default(false).describe('Whether to show peek preview on hover when collapsed'),
+    peekOnHover: z.boolean().default(false).describe('Deprecated, removed in 1.0. Shows a preview of a closed pane on hover.'),
+    type: z.enum(['button', 'submit', 'reset']).default('button').describe('The button type'),
     className: z.string().optional().describe('Additional CSS class name'),
-    style: z
-      .record(z.string(), z.union([z.string(), z.number()]))
-      .optional()
-      .describe('Inline styles'),
+    style: StyleSchema,
     children: z.any().optional().describe('Trigger content'),
-    onClick: z.function().optional().describe('Click handler'),
+    onClick: z.function().optional().describe('Runs before the trigger acts. Call `event.preventDefault()` to cancel it.'),
     onMouseEnter: z.function().optional().describe('Mouse enter handler'),
     onMouseLeave: z.function().optional().describe('Mouse leave handler'),
     'aria-label': z.string().optional().describe('ARIA label for accessibility'),
@@ -256,10 +268,7 @@ export const ShellTriggerSchema = z
 export const ShellHandleSchema = z
   .object({
     className: z.string().optional().describe('Additional CSS class name'),
-    style: z
-      .record(z.string(), z.union([z.string(), z.number()]))
-      .optional()
-      .describe('Inline styles'),
+    style: StyleSchema,
     children: z.any().optional().describe('Handle content'),
   })
   .strict();
@@ -283,7 +292,7 @@ export type PresentationValue = z.infer<typeof PresentationValueSchema>;
 export type Breakpoint = z.infer<typeof _BreakpointSchema>;
 export type PaneTarget = z.infer<typeof PaneTargetSchema>;
 export type TriggerAction = z.infer<typeof TriggerActionSchema>;
-export type ResponsiveMode = z.infer<typeof ResponsiveModeSchema>;
+export type ResponsiveMode = z.infer<typeof _ResponsiveModeSchema>;
 export type ResponsiveSidebarMode = z.infer<typeof ResponsiveSidebarModeSchema>;
 export type ResponsivePresentation = z.infer<typeof ResponsivePresentationSchema>;
 export type PaneSizePersistence = z.infer<typeof PaneSizePersistenceSchema>;