@womp/kookie-ui 0.13.3 → 0.14.1

package/src/components/tab-nav.tsx

@@ -1,3 +1,4 @@
+import { useDeprecatedPanelBackgroundWarning } from '../helpers/use-deprecation-warning.js';
 import * as React from 'react';
 import classNames from 'classnames';
 import { NavigationMenu } from 'radix-ui';
@@ -20,11 +21,13 @@ interface TabNavRootProps
     MarginProps,
     TabNavOwnProps {}
 const TabNavRoot = React.forwardRef<TabNavRootElement, TabNavRootProps>((props, forwardedRef) => {
-  const { children, className, color, panelBackground, ...rootProps } = extractProps(
+  const { children, className, color, material: materialProp, panelBackground, ...rootProps } = extractProps(
     props,
     tabNavRootPropDefs,
     marginPropDefs,
   );
+  useDeprecatedPanelBackgroundWarning(props.panelBackground);
+  const material = materialProp ?? panelBackground;
   return (
     <NavigationMenu.Root
       className="rt-TabNavRoot"
@@ -35,7 +38,8 @@ const TabNavRoot = React.forwardRef<TabNavRootElement, TabNavRootProps>((props,
     >
       <NavigationMenu.List
         className={classNames('rt-reset', 'rt-BaseTabList', 'rt-TabNavList', className)}
-        data-panel-background={panelBackground}
+        data-panel-background={material}
+        data-material={material}
       >
         {children}
       </NavigationMenu.List>

package/src/components/tabs.tsx

@@ -1,3 +1,4 @@
+import { useDeprecatedPanelBackgroundWarning } from '../helpers/use-deprecation-warning.js';
 import * as React from 'react';
 import classNames from 'classnames';
 import { Tabs as TabsPrimitive } from 'radix-ui';
@@ -36,15 +37,18 @@ interface TabsListProps
     MarginProps,
     TabsListOwnProps {}
 const TabsList = React.forwardRef<TabsListElement, TabsListProps>((props, forwardedRef) => {
-  const { className, color, panelBackground, ...listProps } = extractProps(
+  const { className, color, material: materialProp, panelBackground, ...listProps } = extractProps(
     props,
     tabsListPropDefs,
     marginPropDefs,
   );
+  useDeprecatedPanelBackgroundWarning(props.panelBackground);
+  const material = materialProp ?? panelBackground;
   return (
     <TabsPrimitive.List
       data-accent-color={color}
-      data-panel-background={panelBackground}
+      data-panel-background={material}
+      data-material={material}
       {...listProps}
       asChild={false}
       ref={forwardedRef}

package/src/components/text-area.css

@@ -6,7 +6,7 @@
  * - Sizes: Responsive sizing and typography
  * - Variant palettes: Each variant defines its color scale as CSS variables
  * - Shared state logic: Single set of hover/focus/disabled selectors
- * - Special variants: classic (unique behavior, kept separate)
+ * - Special variants: raised (unique behavior, kept separate)
  * - Error states: Override colors for error styling
  */
 
@@ -185,6 +185,19 @@
         letter-spacing: var(--letter-spacing-3);
       }
     }
+    &:where(.rt-r-size-4) {
+      min-height: var(--space-10);
+      border-radius: var(--radius-4);
+
+      & :where(.rt-TextAreaInput) {
+        /* Clip text to border */
+        --text-area-padding-y: calc(var(--space-3) - var(--text-area-border-width));
+        --text-area-padding-x: calc(var(--space-4) - var(--text-area-border-width));
+        font-size: var(--font-size-4);
+        line-height: var(--line-height-4);
+        letter-spacing: var(--letter-spacing-4);
+      }
+    }
   }
 }
 
@@ -413,8 +426,8 @@
  *                                                                                                 *
  ***************************************************************************************************/
 
-/* Classic variant - uses --color-surface and shadow */
-.rt-TextAreaRoot:where(.rt-variant-classic) {
+/* Raised variant - uses --color-surface and shadow */
+.rt-TextAreaRoot:where(.rt-variant-raised) {
   --text-area-border-width: 0px;
   --v-selection-color: var(--focus-a5);
   --v-focus-color: var(--focus-8);
@@ -570,8 +583,8 @@
   }
 }
 
-/* Error classic variant */
-.rt-TextAreaRoot:where(.rt-error.rt-variant-classic) {
+/* Error raised variant */
+.rt-TextAreaRoot:where(.rt-error.rt-variant-raised) {
   box-shadow: var(--shadow-2), inset 0 0 0 1px var(--red-6);
   
   @media (hover: hover) {

package/src/components/text-area.props.tsx

@@ -1,10 +1,11 @@
+import { parseVariant } from '../helpers/parse-variant.js';
 import { colorPropDef } from '../props/color.prop.js';
 import { radiusPropDef } from '../props/radius.prop.js';
 
 import type { PropDef } from '../props/prop-def.js';
 
-const sizes = ['1', '2', '3'] as const;
-const variants = ['classic', 'surface', 'soft', 'outline', 'ghost'] as const;
+const sizes = ['1', '2', '3', '4'] as const;
+const variants = ['raised', 'surface', 'soft', 'outline', 'ghost', 'classic'] as const;
 const resizeValues = ['none', 'vertical', 'horizontal', 'both'] as const;
 const panelBackgrounds = ['solid', 'translucent'] as const;
 const materials = ['solid', 'translucent'] as const;
@@ -12,14 +13,15 @@ const materials = ['solid', 'translucent'] as const;
 // prettier-ignore
 const textAreaPropDefs = {
   size: { type: 'enum', className: 'rt-r-size', values: sizes, default: '2', responsive: true },
-  variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'surface' },
+  variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'raised', parseValue: parseVariant },
   resize: { type: 'enum', className: 'rt-r-resize', values: resizeValues,  responsive: true },
   panelBackground: { type: 'enum', values: panelBackgrounds, default: undefined },
   material: { type: 'enum', values: materials, default: undefined },
   // Error and validation props
   error: { type: 'boolean', default: false },
   errorMessage: { type: 'string', default: undefined },
-  isInvalid: { type: 'boolean', default: false },
+  /** @deprecated Use `error`. Removed in 0.15.0. */
+  isInvalid: { type: 'boolean' },
   required: { type: 'boolean', default: false },
   // Accessibility props
   'aria-describedby': { type: 'string', default: undefined },

package/src/components/text-area.tsx

@@ -1,3 +1,4 @@
+import { warnDeprecated } from '../helpers/warn-deprecated.js';
 import * as React from 'react';
 import classNames from 'classnames';
 
@@ -31,6 +32,9 @@ const TextArea = React.forwardRef<TextAreaElement, TextAreaProps>((props, forwar
 
   // Determine invalid state
   const isInvalid = textAreaProps.error || textAreaProps.isInvalid;
+  if (textAreaProps.isInvalid !== undefined && textAreaProps.isInvalid !== false) {
+    warnDeprecated('`isInvalid` is deprecated and will be removed in 0.15.0. Use `error`, the one name every field uses for an invalid value.');
+  }
 
   // Build aria-describedby string
   const describedBy = React.useMemo(() => {
@@ -79,7 +83,7 @@ const TextArea = React.forwardRef<TextAreaElement, TextAreaProps>((props, forwar
         {...ariaProps}
       />
       {textAreaProps.errorMessage && (
-        <div id={errorId} className="rt-TextAreaErrorMessage" role="alert" aria-live="polite">
+        <div id={errorId} className="rt-TextAreaErrorMessage" role="alert">
           {textAreaProps.errorMessage}
         </div>
       )}

package/src/components/text-field.css

@@ -314,6 +314,39 @@
         }
       }
     }
+
+    /* Size 4 sits on the same ladder step as Button size 4. */
+    &:where(.rt-r-size-4) {
+      --text-field-height: var(--control-height-4);
+      --text-field-padding: calc(var(--space-4) - var(--text-field-border-width));
+      --text-field-border-radius: var(--radius-pill-4);
+      --text-field-native-icon-size: var(--space-5);
+      font-size: var(--font-size-4);
+      letter-spacing: var(--letter-spacing-4);
+
+      & :where(.rt-TextFieldInput) {
+        padding-bottom: 0px;
+
+        /* Safari credentials autofill icon */
+        &::-webkit-textfield-decoration-container {
+          padding-right: 5px;
+          margin-right: 0px;
+        }
+      }
+
+      & :where(.rt-TextFieldSlot) {
+        gap: var(--space-3);
+        padding-left: var(--space-4);
+        padding-right: var(--space-4);
+
+        /* stylelint-disable-next-line selector-max-type */
+        & :where(svg) {
+          width: var(--content-icon-size-4);
+          height: var(--content-icon-size-4);
+          flex-shrink: 0;
+        }
+      }
+    }
   }
 }
 
@@ -401,9 +434,9 @@
   }
 }
 
-/* classic */
+/* raised */
 
-.rt-TextFieldRoot:where(.rt-variant-classic) {
+.rt-TextFieldRoot:where(.rt-variant-raised) {
   --text-field-selection-color: var(--focus-a5);
   --text-field-focus-color: var(--focus-8);
   --text-field-border-width: 0px;
@@ -804,7 +837,7 @@
   }
 }
 
-.rt-TextFieldRoot:where(.rt-error.rt-variant-classic) {
+.rt-TextFieldRoot:where(.rt-error.rt-variant-raised) {
   box-shadow: var(--shadow-2), inset 0 0 0 1px var(--red-6);
   
   @media (hover: hover) {

package/src/components/text-field.props.tsx

@@ -1,3 +1,4 @@
+import { parseVariant } from '../helpers/parse-variant.js';
 import { colorPropDef } from '../props/color.prop.js';
 import { paddingPropDefs } from '../props/padding.props.js';
 import { radiusPropDef } from '../props/radius.prop.js';
@@ -5,18 +6,19 @@ import { flexPropDefs } from './flex.props.js';
 
 import type { PropDef } from '../props/prop-def.js';
 
-const sizes = ['1', '2', '3'] as const;
-const variants = ['classic', 'surface', 'soft', 'ghost', 'outline'] as const;
+const sizes = ['1', '2', '3', '4'] as const;
+const variants = ['raised', 'surface', 'soft', 'ghost', 'outline', 'classic'] as const;
 const panelBackgrounds = ['solid', 'translucent'] as const;
 const materials = ['solid', 'translucent'] as const;
 
 const textFieldRootPropDefs = {
   size: { type: 'enum', className: 'rt-r-size', values: sizes, default: '2', responsive: true },
-  variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'surface' },
+  variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'raised', parseValue: parseVariant },
   // Error and validation props
   error: { type: 'boolean', default: false },
   errorMessage: { type: 'string', default: undefined },
-  isInvalid: { type: 'boolean', default: false },
+  /** @deprecated Use `error`. Removed in 0.15.0. */
+  isInvalid: { type: 'boolean' },
   required: { type: 'boolean', default: false },
   // Accessibility props
   'aria-describedby': { type: 'string', default: undefined },

package/src/components/text-field.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { warnDeprecated } from '../helpers/warn-deprecated.js';
 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
 import classNames from 'classnames';
@@ -32,6 +33,9 @@ const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>
 
   // Determine invalid state
   const isInvalid = inputProps.error || inputProps.isInvalid;
+  if (inputProps.isInvalid !== undefined && inputProps.isInvalid !== false) {
+    warnDeprecated('`isInvalid` is deprecated and will be removed in 0.15.0. Use `error`, the one name every field uses for an invalid value.');
+  }
 
   const { 'aria-describedby': ariaDescribedby, 'aria-labelledby': ariaLabelledby } = inputProps;
 
@@ -97,7 +101,7 @@ const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>
       <input spellCheck="false" {...nativeInputProps} {...ariaProps} ref={composeRefs(inputRef, forwardedRef)} className="rt-reset rt-TextFieldInput" />
       {children}
       {inputProps.errorMessage && (
-        <div id={errorId} className="rt-TextFieldErrorMessage" role="alert" aria-live="polite">
+        <div id={errorId} className="rt-TextFieldErrorMessage" role="alert">
           {inputProps.errorMessage}
         </div>
       )}

package/src/components/theme.props.tsx

@@ -32,14 +32,14 @@ const themePropDefs = {
    * @link
    * https://www.radix-ui.com/themes/docs/theme/color
    */
-  accentColor: { type: 'enum', values: accentColors, default: 'blue' },
+  accentColor: { type: 'enum', values: accentColors, default: 'gray' },
   /**
    * Selects one of the gray color options to use in the Theme.
    *
    * @link
    * https://www.radix-ui.com/themes/docs/theme/color
    */
-  grayColor: { type: 'enum', values: grayColors, default: 'slate' },
+  grayColor: { type: 'enum', values: grayColors, default: 'gray' },
   /**
    * Controls whether to use a solid or translucent background color on panelled
    * elements such as Card or Table is solid or translucent.
@@ -47,7 +47,7 @@ const themePropDefs = {
    * @link
    * https://www.radix-ui.com/themes/docs/theme/visual-style
    */
-  material: { type: 'enum', values: materials, default: 'translucent' },
+  material: { type: 'enum', values: materials, default: 'solid' },
   /**
    * Controls whether to use a solid or translucent background color on panelled
    * elements such as Card or Table is solid or translucent.
@@ -57,7 +57,7 @@ const themePropDefs = {
    * @link
    * https://www.radix-ui.com/themes/docs/theme/visual-style
    */
-  panelBackground: { type: 'enum', values: panelBackgrounds, default: 'translucent' },
+  panelBackground: { type: 'enum', values: panelBackgrounds, default: 'solid' },
   /**
    * Sets the default radius of the components.
    *

package/src/components/toggle-button.tsx

@@ -64,24 +64,39 @@ type ToggleButtonElement = React.ElementRef<typeof Button>;
  * ```
  */
 const ToggleButton = React.forwardRef<ToggleButtonElement, ToggleButtonProps>(({ pressed, onPressedChange, defaultPressed, children, ...buttonProps }, forwardedRef) => {
+  const { 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, iconOnly } = buttonProps;
+
+  // The label behind aria-labelledby is read once per id, not on every press.
+  const cachedLabelRef = React.useRef<string | null>(null);
+  React.useEffect(() => {
+    cachedLabelRef.current = null;
+  }, [ariaLabelledBy]);
+
   /**
-   * Extract accessible name from button content for announcements.
-   * This ensures screen readers announce meaningful state changes.
+   * The name announced when the pressed state changes: aria-label, then the label
+   * aria-labelledby points at, then visible text.
    */
   const getAccessibleName = React.useCallback(() => {
+    if (ariaLabel) return ariaLabel;
+    if (ariaLabelledBy) {
+      if (cachedLabelRef.current === null) {
+        cachedLabelRef.current = document.getElementById(ariaLabelledBy)?.textContent || 'Toggle button';
+      }
+      return cachedLabelRef.current;
+    }
     if (typeof children === 'string') return children;
     if (React.isValidElement(children) && typeof (children.props as any)?.children === 'string') {
       return (children.props as any).children;
     }
     return 'Toggle button';
-  }, [children]);
+  }, [ariaLabel, ariaLabelledBy, children]);
 
   // Use shared toggle state hook for accessibility announcements and warnings
   const { handlePressedChange } = useToggleState({
     pressed,
     onPressedChange,
     getAccessibleName,
-    componentName: 'ToggleButton',
+    componentName: iconOnly ? 'ToggleIconButton' : 'ToggleButton',
   });
 
   // Render the toggle button using Radix UI's Toggle primitive

package/src/components/toggle-icon-button.tsx

@@ -1,8 +1,7 @@
 import * as React from 'react';
 import { Toggle } from 'radix-ui';
-import { IconButton } from './icon-button.js';
+import { ToggleButton } from './toggle-button.js';
 import { BaseButton } from './_internal/base-button.js';
-import { useToggleState } from '../hooks/use-toggle-state.js';
 import type { IconButtonProps } from './icon-button.js';
 
 type ToggleIconButtonElement = React.ElementRef<typeof BaseButton>;
@@ -47,7 +46,8 @@ interface ToggleIconButtonProps extends Omit<IconButtonProps, 'as'> {
 type ToggleIconButtonPropsWithAccessibility = ToggleIconButtonProps & AccessibilityProps;
 
 /**
- * ToggleIconButton component for icon buttons that can be pressed/unpressed
+ * ToggleIconButton component for icon buttons that can be pressed/unpressed. It is
+ * `ToggleButton` with `iconOnly` set, kept as its own name for its stricter type.
  *
  * The ToggleIconButton component extends IconButton with toggle functionality
  * using Radix UI's Toggle primitive. It provides proper accessibility announcements,
@@ -104,63 +104,9 @@ type ToggleIconButtonPropsWithAccessibility = ToggleIconButtonProps & Accessibil
  * <span id="notifications-label">Toggle notifications</span>
  * ```
  */
-const ToggleIconButton = React.forwardRef<ToggleIconButtonElement, ToggleIconButtonPropsWithAccessibility>(({ pressed, onPressedChange, defaultPressed, ...iconButtonProps }, forwardedRef) => {
-  // Extract specific props for stable dependency array
-  const { 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, children } = iconButtonProps;
-
-  // Cache the label lookup from aria-labelledby to avoid repeated DOM queries
-  const cachedLabelRef = React.useRef<string | null>(null);
-
-  // Clear cached label when ariaLabelledBy changes
-  React.useEffect(() => {
-    cachedLabelRef.current = null;
-  }, [ariaLabelledBy]);
-
-  /**
-   * Extract accessible name from various sources for announcements.
-   * This ensures screen readers announce meaningful state changes.
-   * Priority: aria-label > aria-labelledby > children > fallback
-   */
-  const getAccessibleName = React.useCallback(() => {
-    // First priority: direct aria-label
-    if (ariaLabel) return ariaLabel;
-
-    // Second priority: referenced label element (cached)
-    if (ariaLabelledBy) {
-      if (cachedLabelRef.current === null) {
-        const labelElement = document.getElementById(ariaLabelledBy);
-        cachedLabelRef.current = labelElement?.textContent || 'Toggle icon button';
-      }
-      return cachedLabelRef.current;
-    }
-
-    // Third priority: visible text children
-    if (typeof children === 'string') return children;
-    if (React.isValidElement(children) && typeof (children.props as any)?.children === 'string') {
-      return (children.props as any).children;
-    }
-
-    // Fallback for edge cases
-    return 'Toggle icon button';
-  }, [ariaLabel, ariaLabelledBy, children]);
-
-  // Use shared toggle state hook for accessibility announcements and warnings
-  const { handlePressedChange } = useToggleState({
-    pressed,
-    onPressedChange,
-    getAccessibleName,
-    componentName: 'ToggleIconButton',
-  });
-
-  // Render the toggle icon button using Radix UI's Toggle primitive
-  // This provides proper ARIA attributes and keyboard navigation
-  // The IconButton component handles accessibility validation internally
-  return (
-    <Toggle.Root pressed={pressed} onPressedChange={handlePressedChange} defaultPressed={defaultPressed} asChild>
-      <IconButton {...iconButtonProps} ref={forwardedRef} />
-    </Toggle.Root>
-  );
-});
+const ToggleIconButton = React.forwardRef<ToggleIconButtonElement, ToggleIconButtonPropsWithAccessibility>((props, forwardedRef) => (
+  <ToggleButton {...(props as React.ComponentPropsWithoutRef<typeof ToggleButton>)} iconOnly ref={forwardedRef} />
+));
 ToggleIconButton.displayName = 'ToggleIconButton';
 
 export { ToggleIconButton };

package/src/components/user-card.props.tsx

@@ -1,18 +1,21 @@
+import { parseVariant } from '../helpers/parse-variant.js';
+import { avatarPropDefs } from './avatar.props.js';
 import { asChildPropDef } from '../props/as-child.prop.js';
-import { accentColorPropDef } from '../props/color.prop.js';
+import { grayAccentColorPropDef } from '../props/color.prop.js';
 import { radiusPropDef } from '../props/radius.prop.js';
 
 import type { PropDef } from '../props/prop-def.js';
 
 const sizes = ['1', '2', '3', '4'] as const;
-const variants = ['ghost', 'surface', 'classic'] as const;
-const avatarVariants = ['solid', 'soft', 'surface', 'outline'] as const;
+const variants = ['raised', 'ghost', 'surface', 'classic'] as const;
+// The same list as Avatar.
+const avatarVariants = avatarPropDefs.variant.values;
 const panelBackgrounds = ['solid', 'translucent'] as const;
 
 const userCardPropDefs = {
   ...asChildPropDef,
   size: { type: 'enum', className: 'rt-r-size', values: sizes, default: '2', responsive: true },
-  variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'surface' },
+  variant: { type: 'enum', className: 'rt-variant', values: variants, default: 'raised', parseValue: parseVariant },
 
   // Content props
   src: { type: 'string' },
@@ -25,7 +28,7 @@ const userCardPropDefs = {
   ...radiusPropDef,
 
   // Card styling
-  ...accentColorPropDef,
+  ...grayAccentColorPropDef,
   panelBackground: { type: 'enum', values: panelBackgrounds, default: undefined },
   flush: { type: 'boolean', default: false },
 } satisfies {

package/src/components/user-card.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { warnDeprecated } from '../helpers/warn-deprecated.js';
 import * as React from 'react';
 import classNames from 'classnames';
 
@@ -25,7 +26,11 @@ interface UserCardProps
     MarginProps,
     UserCardOwnProps {}
 
+/** @deprecated Removed from the package in 0.15.0. Copy the UserCard block from the docs instead. */
 const UserCard = React.forwardRef<UserCardElement, UserCardProps>((props, forwardedRef) => {
+  warnDeprecated(
+    'UserCard is deprecated as a package export and will be removed in 0.15.0. Copy the UserCard block from the docs into your project.',
+  );
   const themeContext = useThemeContext();
   const resolvedPanelBackground = props.panelBackground ?? themeContext.panelBackground;
 

package/src/helpers/parse-variant.ts

@@ -0,0 +1,21 @@
+import { warnDeprecated } from './warn-deprecated.js';
+
+/**
+ * `classic` was renamed `raised` in 0.14.0. The old name still renders, as `raised`, with a
+ * one-time warning in development. Button's `override` is not a look but a way out of the
+ * styles, so it warns too. Both are removed in 0.15.0.
+ */
+function parseVariant(value: string): string {
+  if (value === 'classic') {
+    warnDeprecated('`variant="classic"` is deprecated and will be removed in 0.15.0. Use `variant="raised"`.');
+    return 'raised';
+  }
+  if (value === 'override') {
+    warnDeprecated(
+      '`variant="override"` is deprecated and will be removed in 0.15.0. Style the component with `className`, `style` or its CSS variables instead.',
+    );
+  }
+  return value;
+}
+
+export { parseVariant };

package/src/helpers/warn-deprecated.ts

@@ -0,0 +1,13 @@
+const warned = new Set<string>();
+
+/**
+ * Warns once per session, in development only, that something a caller used is deprecated.
+ * `process.env.NODE_ENV` is a compile-time constant, so production bundles drop the body.
+ */
+function warnDeprecated(message: string) {
+  if (process.env.NODE_ENV === 'production' || warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[kookie-ui] ${message}`);
+}
+
+export { warnDeprecated };

package/src/props/color.prop.ts

@@ -27,8 +27,21 @@ const accentColorPropDef = {
   color: PropDef<(typeof accentColors)[number]>;
 };
 
+// For components whose colour comes from their content (Badge, Avatar, Code, Callout,
+// UserCard): they rest gray, and `color` picks a category when it means something.
+const grayAccentColorPropDef = {
+  color: {
+    type: 'enum',
+    values: accentColors,
+    default: 'gray' as (typeof accentColors)[number],
+  },
+} satisfies {
+  color: PropDef<(typeof accentColors)[number]>;
+};
+
 export {
   accentColorPropDef,
+  grayAccentColorPropDef,
   colorPropDef,
   //
   accentColors,