@womp/kookie-ui 0.6.2 → 0.8.0

package/src/components/radio-cards.props.tsx

@@ -1,6 +1,5 @@
 import { asChildPropDef } from '../props/as-child.prop.js';
 import { colorPropDef } from '../props/color.prop.js';
-import { highContrastPropDef } from '../props/high-contrast.prop.js';
 import { gridPropDefs } from './grid.props.js';
 
 import type { PropDef } from '../props/prop-def.js';
@@ -15,7 +14,6 @@ const radioCardsRootPropDefs = {
   variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'surface' },
   panelBackground: { type: 'enum', values: panelBackgrounds, default: undefined },
   ...colorPropDef,
-  ...highContrastPropDef,
   columns: { ...gridPropDefs.columns, default: 'repeat(auto-fit, minmax(160px, 1fr))' },
   gap: { ...gridPropDefs.gap, default: '4' },
 } satisfies {

package/src/components/radio-group.props.tsx

@@ -1,6 +1,5 @@
 import { asChildPropDef } from '../props/as-child.prop.js';
 import { colorPropDef } from '../props/color.prop.js';
-import { highContrastPropDef } from '../props/high-contrast.prop.js';
 
 import type { PropDef } from '../props/prop-def.js';
 
@@ -12,7 +11,6 @@ const radioGroupRootPropDefs = {
   size: { type: 'enum', className: 'rt-r-size', values: sizes, default: '2', responsive: true },
   variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'solid' },
   ...colorPropDef,
-  ...highContrastPropDef,
 } satisfies {
   size: PropDef<(typeof sizes)[number]>;
   variant: PropDef<(typeof variants)[number]>;

package/src/components/radio-group.tsx

@@ -40,7 +40,6 @@ const RadioGroupRoot = React.forwardRef<RadioGroupRootElement, RadioGroupRootPro
   (
     {
       color = radioGroupRootPropDefs.color.default,
-      highContrast = radioGroupRootPropDefs.highContrast.default,
       size = radioGroupRootPropDefs.size.default,
       variant = radioGroupRootPropDefs.variant.default,
       ...props
@@ -53,7 +52,6 @@ const RadioGroupRoot = React.forwardRef<RadioGroupRootElement, RadioGroupRootPro
       <RadioGroupProvider
         scope={__scopeRadioGroup}
         color={color}
-        highContrast={highContrast}
         size={size}
         variant={variant}
       >

package/src/components/schemas/base-button.schema.ts

@@ -99,16 +99,6 @@ export const BaseButtonSchema = z
       .optional()
       .describe('Accent color for the button'),
 
-    /**
-     * High contrast mode for better accessibility
-     * @default false
-     */
-    highContrast: z
-      .boolean()
-      .optional()
-      .default(false)
-      .describe('High contrast mode for better accessibility'),
-
     /**
      * Border radius for the button
      */

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>;