@cdx-ui/components 0.1.5 → 0.1.7

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/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/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/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/index.tsx

@@ -1,4 +1,13 @@
-import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  Children,
+  forwardRef,
+  isValidElement,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import { Platform, View } from 'react-native';
 import { GestureDetector } from 'react-native-gesture-handler';
 import Animated from 'react-native-reanimated';
@@ -27,6 +36,7 @@ import {
   toastDescriptionVariants,
   toastIconVariants,
   toastStyleSheet,
+  toastTextVariants,
   toastWrapperVariants,
 } from './styles';
 import type {
@@ -64,6 +74,26 @@ type ToastDataState = 'entering' | 'open' | 'closed';
 
 // --------------------------------------------------
 
+const isTrailingChild = (child: ReactNode) =>
+  isValidElement(child) && (child.type === ToastAction || child.type === ToastClose);
+
+const renderToastRow = (children: ReactNode) => {
+  const childArray = Children.toArray(children);
+  const iconChild = childArray.find((child) => isValidElement(child) && child.type === ToastIcon);
+  const trailingChildren = childArray.filter(isTrailingChild);
+  const textChildren = childArray.filter(
+    (child) => !(isValidElement(child) && child.type === ToastIcon) && !isTrailingChild(child),
+  );
+
+  return (
+    <>
+      {iconChild}
+      {textChildren.length > 0 ? <View className={toastTextVariants()}>{textChildren}</View> : null}
+      {trailingChildren}
+    </>
+  );
+};
+
 const ToastRoot = forwardRef<View, ToastProps>((props, ref) => {
   const globalConfig = useToastConfig();
 
@@ -225,6 +255,10 @@ const ToastRoot = forwardRef<View, ToastProps>((props, ref) => {
 
   const wrapperClassName = cn(toastWrapperVariants({ placement }));
 
+  // Shared by the visible toast and the native measuring node so the measured
+  // height matches what is on screen.
+  const content = renderToastRow(children);
+
   return (
     <AnimationSettingsProvider value={animationSettingsContextValue}>
       <ParentContext.Provider value={ctx}>
@@ -256,7 +290,7 @@ const ToastRoot = forwardRef<View, ToastProps>((props, ref) => {
                 }),
               )}
             >
-              {children}
+              {content}
               {/*
                 When visible toasts have different heights, the toast adapts to the last visible toast height.
                 In cases where a toast originally has one height and gets smaller when a new toast comes to stack,
@@ -286,7 +320,7 @@ const ToastRoot = forwardRef<View, ToastProps>((props, ref) => {
                 }}
                 {...restProps}
               >
-                {children}
+                {content}
               </AnimatedToastRoot>
             )}
           </Animated.View>
@@ -494,18 +528,15 @@ export function DefaultToast(props: DefaultToastProps) {
       placement={placement}
       isSwipeable={isSwipeable}
       animation={animation}
-      className="flex-row gap-3"
       hide={hide}
       show={show}
       {...(color === 'danger' && { role: 'alert' as const })}
       {...toastComponentProps}
     >
       {icon ? <ToastIcon as={icon} /> : null}
-      <View className="flex-1">
-        {label && <ToastTitle>{label}</ToastTitle>}
-        {description && <ToastDescription>{description}</ToastDescription>}
-      </View>
-      {actionLabel && <ToastAction onPress={handleActionPress}>{actionLabel}</ToastAction>}
+      {label ? <ToastTitle>{label}</ToastTitle> : null}
+      {description ? <ToastDescription>{description}</ToastDescription> : null}
+      {actionLabel ? <ToastAction onPress={handleActionPress}>{actionLabel}</ToastAction> : null}
     </ToastRoot>
   );
 }
@@ -527,6 +558,21 @@ type ToastCompoundComponent = typeof ToastRoot & {
   Close: typeof ToastClose;
 };
 
+/**
+ * Presentational toast root, rendered inside a `toast.show({ component })`
+ * render function with the supplied props spread onto it.
+ *
+ * The root lays out its direct children as a fixed row regardless of JSX
+ * order: the first `Toast.Icon` at the start, every `Toast.Action` and
+ * `Toast.Close` at the end in source order, and every other child
+ * (`Toast.Title`, `Toast.Description`, custom content) in a text column
+ * between them. Additional `Toast.Icon` children are dropped.
+ *
+ * `Toast.Icon`, `Toast.Action`, and `Toast.Close` must be direct children.
+ * They are matched by component identity, so wrapping them in `memo()`, an
+ * HOC, or a custom component hides them from the root and they render in the
+ * text column instead.
+ */
 export const Toast = Object.assign(ToastRoot, {
   Title: ToastTitle,
   Description: ToastDescription,

package/src/components/Toast/styles.ts

@@ -40,7 +40,7 @@ export const toastRootVariants = cva(
     // shadow and clips the child's transform mid-transition, producing a
     // visual "cut off" during enter/exit. Consumers that need clipping for
     // custom child content (e.g. a background image) can add it themselves.
-    'flex-row items-center gap-2 rounded-[var(--border-radius-default)] min-h-12 px-4 py-2 shadow-lg bg-surface-primary border border-stroke-secondary',
+    'flex-row items-center gap-3 rounded-[var(--border-radius-default)] min-h-12 px-4 py-2 shadow-lg bg-surface-primary border border-stroke-secondary',
     'native:overflow-hidden',
   ],
   {
@@ -72,6 +72,10 @@ export const toastRootVariants = cva(
  * on the `top-*` / `bottom-*` variants also seeds the entering-state offset synchronously
  * — CSS transitions to `translate-y-0` when `data-state` flips to `open`.
  *
+ * Centered placements span the row (`inset-x-0`) and center a `w-fit` box with auto margins.
+ * Do not center with `left-1/2` + `-translate-x-1/2`: an absolute box that starts at the
+ * midpoint shrink-to-fits into half the container, so short labels wrap long before 460px.
+ *
  * `motion-reduce:transition-none` collapses the transition for users with
  * `prefers-reduced-motion: reduce`. In that case `transitionend` may never fire, so
  * the Toast component's safety timeout handles removal.
@@ -96,7 +100,7 @@ export const toastWrapperVariants = cva(
         ],
         top: [
           'top-0 native:left-0 native:right-0',
-          'web:left-1/2 web:-translate-x-1/2 web:max-w-[460px]',
+          'web:inset-x-0 web:mx-auto web:w-fit web:max-w-[460px]',
           'web:data-[state=entering]:-translate-y-2',
           'web:data-[state=closed]:-translate-y-2',
         ],
@@ -114,7 +118,7 @@ export const toastWrapperVariants = cva(
         ],
         bottom: [
           'bottom-0 native:left-0 native:right-0',
-          'web:left-1/2 web:-translate-x-1/2 web:max-w-[460px]',
+          'web:inset-x-0 web:mx-auto web:w-fit web:max-w-[460px]',
           'web:data-[state=entering]:translate-y-2',
           'web:data-[state=closed]:translate-y-2',
         ],
@@ -132,6 +136,13 @@ export const toastWrapperVariants = cva(
   },
 );
 
+/**
+ * Internal text column the root renders between the leading icon and the
+ * trailing controls. Holds `Toast.Title`, `Toast.Description`, and any
+ * unrecognized children.
+ */
+export const toastTextVariants = cva(['flex-1 flex-col min-w-0']);
+
 export const toastLabelVariants = cva(['text-base font-medium'], {
   variants: {
     color: {

package/src/components/Toast/types.ts

@@ -186,6 +186,15 @@ export interface ToastProps extends ToastRootProps, Omit<ToastComponentProps, 'i
    * @default true
    */
   isAnimatedStyleActive?: boolean;
+  /**
+   * Laid out automatically: the first `Toast.Icon` at the start, `Toast.Action`
+   * and `Toast.Close` at the end, and everything else in a text column between
+   * them. Additional `Toast.Icon` children are dropped. `Toast.Icon`,
+   * `Toast.Action`, and `Toast.Close` must be **direct** children — wrapping
+   * them in `memo()` or an HOC hides them from the layout, and they render in
+   * the text column instead.
+   */
+  children?: React.ReactNode;
 }
 
 /**