@cdx-ui/components 0.1.6 → 0.2.0

package/src/components/ListItem/index.tsx

@@ -19,6 +19,7 @@ import {
   listItemSectionHeaderVariants,
   listItemTitleVariants,
   listItemTrailingSlotVariants,
+  type ListItemSectionHeaderVariantProps,
   type ListItemVariantProps,
 } from './styles';
 
@@ -34,6 +35,28 @@ const useListItemStyleContext = (): Pick<ListItemVariantProps, 'crossAlign'> =>
 // =============================================================================
 
 export interface ListItemProps extends Omit<IListItemProps, 'crossAlign'>, ListItemVariantProps {
+  /**
+   * Vertical density. `compact` reduces padding and min-height; typography stays the same.
+   * @default 'default'
+   * @remarks `'default' | 'compact'`
+   * @fumadocsType `'default' | 'compact'`
+   */
+  size?: 'default' | 'compact' | null | undefined;
+  /**
+   * Bottom border between rows. Set `false` on the last row to avoid a trailing border.
+   * @default true
+   * @remarks `boolean`
+   * @fumadocsType `boolean`
+   */
+  showSeparator?: boolean | null | undefined;
+  /**
+   * Vertical alignment of the leading, content, and trailing slots.
+   * `start` top-aligns them so trailing text lines up with the title.
+   * @default 'center'
+   * @remarks `'center' | 'start'`
+   * @fumadocsType `'center' | 'start'`
+   */
+  crossAlign?: 'center' | 'start' | null | undefined;
   className?: string;
 }
 
@@ -82,6 +105,7 @@ ListItemRoot.displayName = 'ListItem';
 const leadingSlotStyle = { flexShrink: 0 as const };
 
 export interface ListItemLeadingSlotProps extends ViewProps {
+  /** Renders the consumer's child element in place of the default `View` host. */
   asChild?: boolean;
   className?: string;
   /**
@@ -119,6 +143,7 @@ const contentStyle = {
 };
 
 export interface ListItemContentProps extends ViewProps {
+  /** Renders the consumer's child element in place of the default `View` host. */
   asChild?: boolean;
   className?: string;
 }
@@ -143,6 +168,7 @@ const ListItemContent = forwardRef<View, ListItemContentProps>(
 ListItemContent.displayName = 'ListItem.Content';
 
 export interface ListItemTitleProps extends TextProps {
+  /** Renders the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
   className?: string;
 }
@@ -166,6 +192,7 @@ const ListItemTitle = forwardRef<Text, ListItemTitleProps>(
 ListItemTitle.displayName = 'ListItem.Title';
 
 export interface ListItemDescriptionProps extends TextProps {
+  /** Renders the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
   className?: string;
 }
@@ -188,6 +215,7 @@ const ListItemDescription = forwardRef<Text, ListItemDescriptionProps>(
 ListItemDescription.displayName = 'ListItem.Description';
 
 export interface ListItemMetaProps extends TextProps {
+  /** Renders the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
   className?: string;
 }
@@ -211,6 +239,7 @@ const ListItemMeta = forwardRef<Text, ListItemMetaProps>(
 ListItemMeta.displayName = 'ListItem.Meta';
 
 export interface ListItemTrailingSlotProps extends ViewProps {
+  /** Renders the consumer's child element in place of the default `View` host. */
   asChild?: boolean;
   className?: string;
 }
@@ -267,15 +296,29 @@ const sectionHeaderTrailingCell = {
   alignSelf: 'center' as const,
 };
 
+export type ListItemSectionHeaderVariant = NonNullable<
+  ListItemSectionHeaderVariantProps['variant']
+>;
+
 export interface ListItemSectionHeaderProps extends ViewProps {
+  /** Renders the consumer's child element in place of the default `View` host. */
   asChild?: boolean;
   className?: string;
-  /** Primary section label (e.g. date heading). */
+  /** Primary section label. String or number children are styled as an uppercase label. */
   children: ReactNode;
   /** Optional right-aligned adornment (e.g. section Chip). */
   trailing?: ReactNode;
   /**
-   * Whether to expose the top divider marker for styling.
+   * Background treatment. `ghost` has no fill and a bottom border; `subtle` adds a neutral fill
+   * (matching `subtle` on Avatar, Chip, and IconButton) and drops the bottom border.
+   * Label typography is the same for both.
+   * @default 'ghost'
+   * @remarks `'ghost' | 'subtle'`
+   * @fumadocsType `'ghost' | 'subtle'`
+   */
+  variant?: ListItemSectionHeaderVariant;
+  /**
+   * Accent top border above the header.
    * @default true
    */
   showDivider?: boolean;
@@ -287,6 +330,7 @@ const ListItemSectionHeader = forwardRef<View, ListItemSectionHeaderProps>(
       asChild,
       children,
       className,
+      variant = 'ghost',
       showDivider = true,
       style,
       trailing,
@@ -300,7 +344,7 @@ const ListItemSectionHeader = forwardRef<View, ListItemSectionHeaderProps>(
       <Comp
         ref={ref}
         accessibilityRole={accessibilityRole}
-        className={cn(listItemSectionHeaderVariants({ showDivider }), className)}
+        className={cn(listItemSectionHeaderVariants({ variant, showDivider }), className)}
         style={[sectionHeaderRow, style]}
         {...props}
         {...mergeDataAttributes(
@@ -341,7 +385,7 @@ export const ListItem = Object.assign(ListItemRoot, {
   SectionHeader: ListItemSectionHeader,
 }) as ListItemCompound;
 
-export type { ListItemCrossAlign, ListItemVariantProps };
+export type { ListItemCrossAlign, ListItemSectionHeaderVariantProps, ListItemVariantProps };
 export {
   listItemContentVariants,
   listItemDescriptionVariants,

package/src/components/ListItem/styles.ts

@@ -110,12 +110,18 @@ export const listItemSectionHeaderVariants = cva(
   ],
   {
     variants: {
+      variant: {
+        ghost: [],
+        // The fill separates the header from its rows, so the bottom border is dropped.
+        subtle: 'bg-surface-neutral-subtle border-b-0',
+      },
       showDivider: {
         true: ['border-t-4 border-solid border-t-surface-brand-strong/40', 'border-x-0'],
         false: 'border-t-0',
       },
     },
     defaultVariants: {
+      variant: 'ghost',
       showDivider: true,
     },
   },
@@ -127,3 +133,4 @@ export const listItemSectionHeaderLabelVariants = cva(
 );
 
 export type ListItemVariantProps = VariantProps<typeof listItemRootVariants>;
+export type ListItemSectionHeaderVariantProps = VariantProps<typeof listItemSectionHeaderVariants>;

package/src/components/Menu/index.tsx

@@ -422,7 +422,7 @@ const MenuItemLabel = forwardRef<Text, MenuItemLabelProps>(
 
 MenuItemLabel.displayName = 'Menu.ItemLabel';
 
-export interface MenuItemIconProps extends Omit<IconProps, 'as' | 'children'> {
+export interface MenuItemIconProps extends Omit<IconProps, 'as' | 'children' | 'color'> {
   asChild?: boolean;
   as?: IconProps['as'];
   position?: IconSlotPosition;
@@ -508,7 +508,7 @@ const MenuItemShortcut = forwardRef<Text, MenuItemShortcutProps>(
 
 MenuItemShortcut.displayName = 'Menu.ItemShortcut';
 
-export interface MenuItemIndicatorProps extends Omit<IconProps, 'as' | 'children'> {
+export interface MenuItemIndicatorProps extends Omit<IconProps, 'as' | 'children' | 'color'> {
   asChild?: boolean;
   as?: IconProps['as'];
   isChecked?: boolean;

package/src/components/ProgressSegmented/index.tsx

@@ -8,18 +8,25 @@ import {
 } from './styles';
 
 export interface ProgressSegmentedProps extends ViewProps, ProgressSegmentedVariants {
-  /** Current step (1-based index into the segment count) */
+  /**
+   * Current step (1-based index into the segment count).
+   * Clamped to `[0, segments]` (`0` leaves every segment incomplete).
+   */
   readonly step: number;
   /**
    * Number of segments in the bar. Matches the Figma `segments` variant (2–6 in the design
    * system file); the prop accepts any positive integer for backward compatibility.
+   * @default 5
    */
   readonly segments?: number;
-  /** When true, the current step segment is marked as complete rather than in-progress */
+  /**
+   * When true, the current step segment is marked as complete rather than in-progress.
+   * @default false
+   */
   readonly isStepComplete?: boolean;
   /**
    * Returns the accessibility value text announced by screen readers. Receives the clamped
-   * step, segment count, and whether the step is complete.
+   * step, segment count, and whether the step is complete. Replaces the English default.
    */
   readonly getAccessibilityText?: (
     step: number,

package/src/components/Radio/index.tsx

@@ -180,6 +180,7 @@ export interface RadioGroupProps extends ViewProps {
   isDisabled?: boolean;
   isInvalid?: boolean;
   isRequired?: boolean;
+  /** Makes every radio in the group read-only. Items stay focusable, but the selection cannot be changed. */
   isReadOnly?: boolean;
   direction?: 'column' | 'row';
   name?: string;

package/src/components/ScopedTheme/index.tsx

@@ -10,8 +10,16 @@ export type ScopedThemeProps = ComponentProps<typeof UniwindScopedTheme>;
  *
  * Wraps Uniwind's `ScopedTheme` to keep `uniwind` an internal implementation detail.
  *
- * Web requires `@custom-variant dark (&:where(.dark, .dark *));` in the consuming
- * app's `global.css`. See the Storybook story (`Theming/ScopedTheme`) for the full
- * mechanism, light-vs-dark asymmetry, and dynamic-switch caveat.
+ * On web, the consuming app's `global.css` must include
+ * `@custom-variant dark (&:where(.dark, .dark *));`. Without that directive,
+ * `theme="dark"` does not flip CSS variables. Native applies the scoped theme
+ * through React context and does not use the directive.
+ *
+ * On web, `theme="dark"` forces dark tokens inside a light app. `theme="light"`
+ * applies when no `.dark` ancestor is present; there is no `@custom-variant light`
+ * to override one. Native honors either value through context.
+ *
+ * Pass a static `theme`. Changing `theme` on an already-mounted instance can leave
+ * stale styles; remount to switch.
  */
 export const ScopedTheme = (props: ScopedThemeProps) => <UniwindScopedTheme {...props} />;

package/src/components/Select/index.tsx

@@ -191,7 +191,7 @@ SelectValue.displayName = 'Select.Value';
 // STYLED ICON (styled-only, reads context for state=open / invalid)
 // =============================================================================
 
-export interface SelectIconProps extends Omit<IconProps, 'children' | 'as'> {
+export interface SelectIconProps extends Omit<IconProps, 'children' | 'as' | 'color'> {
   asChild?: boolean;
   /**
    * Forge icon component to render. Required unless `asChild` is set, in which

package/src/components/Skeleton/index.tsx

@@ -12,7 +12,11 @@ import { skeletonVariants } from './styles';
 
 export interface SkeletonProps extends ViewProps {
   className?: string;
-  /** Pulse animation duration in milliseconds. @default 1000 */
+  /**
+   * Half-cycle of the opacity pulse (`1` → `0.35`) in milliseconds.
+   * A full pulse takes `duration × 2`.
+   * @default 1000
+   */
   duration?: number;
 }
 

package/src/components/Stack/HStack.tsx

@@ -6,7 +6,13 @@ import { hStackRootVariants, type StackSpace } from './styles';
 
 export interface HStackProps extends ViewProps {
   className?: string;
+  /** Token-based gap between children. */
   space?: StackSpace;
+  /**
+   * Reverses the visual order of children along the stack axis.
+   * Source order and screen-reader order stay unchanged.
+   * @default false
+   */
   reversed?: boolean;
 }
 

package/src/components/Stack/VStack.tsx

@@ -6,7 +6,13 @@ import { vStackRootVariants, type StackSpace } from './styles';
 
 export interface VStackProps extends ViewProps {
   className?: string;
+  /** Token-based gap between children. */
   space?: StackSpace;
+  /**
+   * Reverses the visual order of children along the stack axis.
+   * Source order and screen-reader order stay unchanged.
+   * @default false
+   */
   reversed?: boolean;
 }
 

package/src/components/Switch/index.tsx

@@ -10,7 +10,7 @@ import { BaseSwitch } from './BaseSwitch';
 
 export interface SwitchProps extends ISwitchProps {
   /**
-   * Track and thumb size.
+   * Track and thumb size on web. iOS and Android render the system switch, so `size` has no effect.
    * @default 'md'
    */
   size?: 'sm' | 'md' | 'lg';

package/src/components/Tabs/index.tsx

@@ -154,8 +154,8 @@ export interface TabsListProps extends ITabsListProps {
   className?: string;
   /**
    * When `orientation="horizontal"`, scroll tab triggers if they overflow the list width.
-   * Vertical lists do not scroll — tabs stack in a column (matches HeroUI / ARIA scrollable
-   * tablist patterns, which are horizontal-only).
+   * On native, selecting a tab scrolls it into view. On web, edge fades and paging
+   * controls appear when more tabs are off-screen. Vertical lists do not scroll.
    * @default true
    */
   scrollable?: boolean;

package/src/components/Text/index.tsx

@@ -1,16 +1,43 @@
 import { forwardRef, type ComponentPropsWithoutRef, type ComponentRef } from 'react';
 import { Text as RNText } from 'react-native';
+import { useHasTextAncestor } from '@cdx-ui/primitives';
 import { cn } from '@cdx-ui/utils';
-import { textStyle, TextVariantProps } from './styles';
+import { nestedTextStyle, textStyle, type TextVariantProps } from './styles';
 
-export type TextProps = TextVariantProps &
-  ComponentPropsWithoutRef<typeof RNText> & { className?: string };
+export type TextColor = NonNullable<TextVariantProps['color']>;
+export type TextSize = NonNullable<TextVariantProps['size']>;
+export type TextWeight = NonNullable<TextVariantProps['weight']>;
+
+export type TextProps = Omit<TextVariantProps, 'color' | 'size' | 'weight'> &
+  ComponentPropsWithoutRef<typeof RNText> & {
+    /**
+     * Semantic content color, mapped to the matching `text-content-*` token.
+     * A `Text` nested inside another text element inherits its parent's color when omitted.
+     * @default 'primary'
+     */
+    color?: TextColor;
+    /**
+     * Body typography style. A nested `Text` inherits its parent's size when omitted, and
+     * setting it keeps the parent's font family and weight.
+     * @default 'md'
+     */
+    size?: TextSize;
+    /**
+     * Font weight. A nested `Text` inherits its parent's weight when omitted.
+     * @default 'normal'
+     */
+    weight?: TextWeight;
+    className?: string;
+  };
 
 export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(function Text(
-  { className, size = 'md', ...props },
+  { className, color, size, weight, italic, ...props },
   ref,
 ) {
-  return <RNText className={cn(textStyle({ size }), className)} {...props} ref={ref} />;
+  const variants = { color, size, weight, italic };
+  const classes = useHasTextAncestor() ? nestedTextStyle(variants) : textStyle(variants);
+
+  return <RNText className={cn(classes, className)} {...props} ref={ref} />;
 });
 
 Text.displayName = 'Text';

package/src/components/Text/styles.ts

@@ -1,9 +1,20 @@
 import { Platform } from 'react-native';
 import { cva, type VariantProps } from '@cdx-ui/utils';
+import { CONTENT_COLOR } from '../../styles/constants';
+
+const TEXT_WEIGHT = {
+  normal: 'font-normal',
+  medium: 'font-medium',
+  semibold: 'font-semibold',
+  bold: 'font-bold',
+} as const;
+
+const TEXT_ITALIC = {
+  true: 'italic',
+} as const;
 
 export const textStyle = cva(
   [
-    'text-content-primary',
     Platform.select({
       web: 'font-body my-0 bg-transparent no-underline',
       default: '',
@@ -11,6 +22,7 @@ export const textStyle = cva(
   ],
   {
     variants: {
+      color: CONTENT_COLOR,
       size: {
         xl: 'body-xl',
         lg: 'body-lg',
@@ -18,8 +30,34 @@ export const textStyle = cva(
         sm: 'body-sm',
         xs: 'body-xs',
       },
+      weight: TEXT_WEIGHT,
+      italic: TEXT_ITALIC,
+    },
+    defaultVariants: {
+      color: 'primary',
+      size: 'md',
+      weight: 'normal',
     },
   },
 );
 
 export type TextVariantProps = VariantProps<typeof textStyle>;
+
+// A `Text` inside another text element emits only the props it is given, with no
+// base classes or defaults, so everything it omits inherits from the parent. Its
+// sizes use the `-size` companions of the body styles, which leave the font
+// family and weight to inherit too.
+export const nestedTextStyle = cva([], {
+  variants: {
+    color: CONTENT_COLOR,
+    size: {
+      xl: 'body-xl-size',
+      lg: 'body-lg-size',
+      md: 'body-md-size',
+      sm: 'body-sm-size',
+      xs: 'body-xs-size',
+    } satisfies Record<NonNullable<TextVariantProps['size']>, string>,
+    weight: TEXT_WEIGHT,
+    italic: TEXT_ITALIC,
+  },
+});

package/src/components/Textarea/index.tsx

@@ -40,6 +40,7 @@ export interface TextareaProps
     Omit<TextInputProps, 'multiline' | 'children' | 'style'>,
     IInputFieldProps,
     TextareaVariantProps {
+  /** Additional Tailwind classes, applied to the root shell rather than the inner field. */
   className?: string;
   placeholderTextColorClassName?: string;
   /** Initial / minimum visible rows. Defaults to 2 on web and 8 on native. */

package/src/components/Tile/index.tsx

@@ -66,11 +66,39 @@ const useTileGroupStyleContext = (): TileGroupStyleContext => {
  */
 export interface TileGroupSingleProps extends ITileGroupSingleProps, TileGroupVariantProps {
   className?: string;
+  /**
+   * Layout axis. `row` places tiles side by side.
+   * @default 'column'
+   * @remarks `'column' | 'row'`
+   * @fumadocsType `'column' | 'row'`
+   */
+  direction?: 'column' | 'row' | null | undefined;
+  /**
+   * Gap between tiles. `none` removes it so rows touch.
+   * @default 'default'
+   * @remarks `'default' | 'none'`
+   * @fumadocsType `'default' | 'none'`
+   */
+  spacing?: 'default' | 'none' | null | undefined;
   /** Visual shape inherited by child `Tile`s. Per-tile `shape` overrides this. */
   shape?: TileVariantProps['shape'];
 }
 export interface TileGroupMultipleProps extends ITileGroupMultipleProps, TileGroupVariantProps {
   className?: string;
+  /**
+   * Layout axis. `row` places tiles side by side.
+   * @default 'column'
+   * @remarks `'column' | 'row'`
+   * @fumadocsType `'column' | 'row'`
+   */
+  direction?: 'column' | 'row' | null | undefined;
+  /**
+   * Gap between tiles. `none` removes it so rows touch.
+   * @default 'default'
+   * @remarks `'default' | 'none'`
+   * @fumadocsType `'default' | 'none'`
+   */
+  spacing?: 'default' | 'none' | null | undefined;
   /** Visual shape inherited by child `Tile`s. Per-tile `shape` overrides this. */
   shape?: TileVariantProps['shape'];
 }
@@ -104,6 +132,21 @@ TileGroup.displayName = 'Tile.Group';
 // =============================================================================
 
 export interface TileProps extends ITileProps, TileVariantProps {
+  /**
+   * Visual shape. Overrides the shape inherited from `Tile.Group`.
+   * `card` is a bordered surface; `flat` is a borderless row.
+   * @default 'card'
+   * @remarks `'card' | 'flat'`
+   * @fumadocsType `'card' | 'flat'`
+   */
+  shape?: 'card' | 'flat' | null | undefined;
+  /**
+   * Renders a bottom border. Omit it on the last row of a tight list.
+   * @default false
+   * @remarks `boolean`
+   * @fumadocsType `boolean`
+   */
+  showSeparator?: boolean | null | undefined;
   className?: string;
 }
 
@@ -196,6 +239,11 @@ const noUnderlineStyle = { textDecorationLine: 'none' as const };
 export interface TileTitleProps extends TextProps {
   asChild?: boolean;
   className?: string;
+  /**
+   * Maximum lines before the title truncates.
+   * @default 1
+   */
+  numberOfLines?: number;
 }
 
 const TileTitle = forwardRef<Text, TileTitleProps>(
@@ -276,6 +324,7 @@ const indicatorStyle = { flexShrink: 0 as const, pointerEvents: 'none' as const
 export interface TileIndicatorProps extends ITileIndicatorProps {
   asChild?: boolean;
   className?: string;
+  /** Replaces the default radio or checkbox visual when provided. */
   children?: ReactNode;
 }
 

package/src/components/Toast/hooks.ts

@@ -12,7 +12,6 @@ export function useButtonColor({
   color: ButtonProps['color'];
   toastColor: ToastColorInternal;
 }) {
-  // TODO: Add toastActionVariants to styles.ts to restore color-aware action styling
   return useMemo(() => {
     if (color) return color;