@mihcm/ui 0.14.1

package/src/Avatar.native.tsx

@@ -0,0 +1,142 @@
+/**
+ * Avatar (React Native variant).
+ *
+ * Composable image + fallback. The image uses RN `<Image>` and falls
+ * back via the `onError` callback the same way the web variant does.
+ *
+ * Wiki: docs/components/Avatar.md
+ */
+import { forwardRef, useState, type ReactNode } from 'react';
+import { Image, Text, View, type ImageProps, type TextProps, type ViewProps } from 'react-native';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+
+export const avatarVariants = cva('relative overflow-hidden rounded-full bg-muted', {
+  variants: {
+    size: {
+      sm: 'h-8 w-8',
+      md: 'h-10 w-10',
+      lg: 'h-12 w-12',
+      xl: 'h-16 w-16',
+    },
+  },
+  defaultVariants: { size: 'md' },
+});
+
+export interface AvatarProps
+  extends Omit<ViewProps, 'style'>,
+    VariantProps<typeof avatarVariants> {
+  className?: string;
+}
+
+export const Avatar = forwardRef<View, AvatarProps>(function Avatar(
+  { className, size, ...props },
+  ref,
+) {
+  return <View ref={ref} className={cn(avatarVariants({ size }), className)} {...props} />;
+});
+
+export interface AvatarImageProps extends Omit<ImageProps, 'style'> {
+  className?: string;
+}
+
+export const AvatarImage = forwardRef<Image, AvatarImageProps>(function AvatarImage(
+  { className, onError, ...props },
+  ref,
+) {
+  const [errored, setErrored] = useState(false);
+  if (errored) return null;
+  return (
+    <Image
+      ref={ref as never}
+      onError={(e) => {
+        setErrored(true);
+        onError?.(e);
+      }}
+      className={cn('h-full w-full', className)}
+      resizeMode="cover"
+      {...props}
+    />
+  );
+});
+
+export interface AvatarFallbackProps extends Omit<TextProps, 'style'> {
+  className?: string;
+}
+
+export const AvatarFallback = forwardRef<View, AvatarFallbackProps>(function AvatarFallback(
+  { className, children, ...props },
+  ref,
+) {
+  return (
+    <View ref={ref} className="absolute inset-0 items-center justify-center">
+      <Text
+        className={cn('font-medium text-muted-foreground', className)}
+        {...props}
+      >
+        {children}
+      </Text>
+    </View>
+  );
+});
+
+/* ── Status indicator ────────────────────────────────────────────── */
+
+const STATUS_COLORS: Record<string, string> = {
+  online: 'bg-success',
+  offline: 'bg-muted-foreground',
+  busy: 'bg-destructive',
+  away: 'bg-warning',
+};
+
+export interface AvatarStatusProps extends Omit<ViewProps, 'style'> {
+  status: 'online' | 'offline' | 'busy' | 'away';
+  className?: string;
+}
+
+export const AvatarStatus = forwardRef<View, AvatarStatusProps>(function AvatarStatus(
+  { className, status, ...props },
+  ref,
+) {
+  return (
+    <View
+      ref={ref}
+      accessibilityLabel={status}
+      className={cn(
+        'absolute bottom-0 right-0 h-2.5 w-2.5 rounded-full border-2 border-card',
+        STATUS_COLORS[status],
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+/* ── AvatarGroup ─────────────────────────────────────────────────── */
+
+export interface AvatarGroupProps extends Omit<ViewProps, 'style'> {
+  max?: number;
+  className?: string;
+  children?: ReactNode;
+}
+
+export const AvatarGroup = forwardRef<View, AvatarGroupProps>(function AvatarGroup(
+  { className, max = 4, children, ...props },
+  ref,
+) {
+  const items = Array.isArray(children) ? children : children ? [children] : [];
+  const visible = items.slice(0, max);
+  const overflow = items.length - max;
+  return (
+    <View ref={ref} className={cn('flex-row items-center', className)} {...props}>
+      {visible.map((child, i) => (
+        <View key={i} className={cn(i > 0 && '-ml-2', 'rounded-full border-2 border-card')}>{child}</View>
+      ))}
+      {overflow > 0 && (
+        <View className="-ml-2 h-10 w-10 items-center justify-center rounded-full bg-muted border-2 border-card">
+          <Text className="text-xs font-semibold text-muted-foreground">+{overflow}</Text>
+        </View>
+      )}
+    </View>
+  );
+});

package/src/Avatar.tsx

@@ -0,0 +1,155 @@
+'use client';
+
+/**
+ * Avatar (web variant — React DOM).
+ *
+ * Composable user/entity portrait. Three pieces:
+ *
+ *   <Avatar>
+ *     <AvatarImage src={user.photo} alt={user.name} />
+ *     <AvatarFallback>{user.initials}</AvatarFallback>
+ *   </Avatar>
+ *
+ * The image is rendered first; if it fails to load, the fallback
+ * shows. The fallback is always present in the DOM so layout stays
+ * stable while the image loads.
+ *
+ * Wiki: docs/components/Avatar.md
+ */
+import { forwardRef, useState, type HTMLAttributes, type ImgHTMLAttributes } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+
+export const avatarVariants = cva(
+  'relative inline-flex shrink-0 overflow-hidden rounded-full bg-primary-50 dark:bg-primary-950',
+  {
+    variants: {
+      size: {
+        sm: 'h-8 w-8 text-xs',
+        md: 'h-10 w-10 text-sm',
+        lg: 'h-12 w-12 text-base',
+        xl: 'h-16 w-16 text-lg',
+      },
+    },
+    defaultVariants: { size: 'md' },
+  },
+);
+
+export interface AvatarProps
+  extends HTMLAttributes<HTMLSpanElement>,
+    VariantProps<typeof avatarVariants> {}
+
+export const Avatar = forwardRef<HTMLSpanElement, AvatarProps>(function Avatar(
+  { className, size, ...props },
+  ref,
+) {
+  return (
+    <span ref={ref} className={cn(avatarVariants({ size }), className)} {...props} />
+  );
+});
+
+export interface AvatarImageProps extends ImgHTMLAttributes<HTMLImageElement> {}
+
+export const AvatarImage = forwardRef<HTMLImageElement, AvatarImageProps>(function AvatarImage(
+  { className, alt = '', onError, ...props },
+  ref,
+) {
+  const [errored, setErrored] = useState(false);
+  if (errored) return null;
+  return (
+    <img
+      ref={ref}
+      alt={alt}
+      onError={(e) => {
+        setErrored(true);
+        onError?.(e);
+      }}
+      className={cn('absolute inset-0 h-full w-full object-cover transition-opacity duration-150', className)}
+      {...props}
+    />
+  );
+});
+
+export interface AvatarFallbackProps extends HTMLAttributes<HTMLSpanElement> {}
+
+export const AvatarFallback = forwardRef<HTMLSpanElement, AvatarFallbackProps>(function AvatarFallback(
+  { className, ...props },
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      aria-hidden
+      className={cn(
+        'absolute inset-0 grid place-items-center bg-primary-50 font-bold text-primary dark:bg-primary-950 dark:text-primary-300 transition-colors duration-150',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+/* ── Status indicator ────────────────────────────────────────────── */
+
+const STATUS_COLORS: Record<string, string> = {
+  online: 'bg-success',
+  offline: 'bg-muted-foreground',
+  busy: 'bg-destructive',
+  away: 'bg-warning',
+};
+
+export interface AvatarStatusProps extends HTMLAttributes<HTMLSpanElement> {
+  status: 'online' | 'offline' | 'busy' | 'away';
+}
+
+/** Small colored dot anchored to the bottom-right of `<Avatar>`. */
+export const AvatarStatus = forwardRef<HTMLSpanElement, AvatarStatusProps>(function AvatarStatus(
+  { className, status, ...props },
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      role="img"
+      aria-label={status}
+      className={cn(
+        'absolute bottom-0 right-0 block h-2.5 w-2.5 rounded-full ring-2 ring-card',
+        STATUS_COLORS[status],
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+/* ── AvatarGroup ─────────────────────────────────────────────────── */
+
+export interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /** Maximum avatars to show before the "+N" counter. */
+  max?: number;
+}
+
+/**
+ * Stacks `<Avatar>` children with negative overlap.
+ * Shows a "+N" counter when children exceed `max`.
+ */
+export const AvatarGroup = forwardRef<HTMLDivElement, AvatarGroupProps>(function AvatarGroup(
+  { className, max = 4, children, ...props },
+  ref,
+) {
+  const items = Array.isArray(children) ? children : children ? [children] : [];
+  const visible = items.slice(0, max);
+  const overflow = items.length - max;
+  return (
+    <div ref={ref} className={cn('flex items-center -space-x-2', className)} {...props}>
+      {visible.map((child, i) => (
+        <span key={i} className="ring-2 ring-card rounded-full">{child}</span>
+      ))}
+      {overflow > 0 && (
+        <span className="relative inline-flex h-10 w-10 items-center justify-center rounded-full bg-muted text-xs font-semibold text-muted-foreground ring-2 ring-card">
+          +{overflow}
+        </span>
+      )}
+    </div>
+  );
+});

package/src/AvatarGroup.native.tsx

@@ -0,0 +1,81 @@
+/**
+ * AvatarGroup (React Native variant).
+ *
+ * Stacked row of Avatar children with negative marginLeft overlap
+ * and a "+N" overflow badge.
+ *
+ * Wiki: docs/components/AvatarGroup.md
+ */
+import {
+  Children,
+  cloneElement,
+  forwardRef,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { Text, View, type ViewProps } from 'react-native';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+import type { AvatarProps } from './Avatar.js';
+
+const overflowVariants = cva(
+  'items-center justify-center rounded-full bg-muted border-2 border-card',
+  {
+    variants: {
+      size: {
+        sm: 'h-8 w-8',
+        md: 'h-10 w-10',
+        lg: 'h-12 w-12',
+      },
+    },
+    defaultVariants: { size: 'md' },
+  },
+);
+
+export interface AvatarGroupProps extends Omit<ViewProps, 'style'> {
+  max?: number;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+  children?: ReactNode;
+}
+
+export const AvatarGroup = forwardRef<View, AvatarGroupProps>(function AvatarGroup(
+  { className, max = 4, size, children, ...props },
+  ref,
+) {
+  const items = Children.toArray(children).filter(isValidElement);
+  const visible = items.slice(0, max);
+  const overflow = items.length - max;
+
+  return (
+    <View
+      ref={ref}
+      accessibilityRole="summary"
+      accessibilityLabel={`Group of ${items.length} avatars`}
+      className={cn('flex-row items-center', className)}
+      {...props}
+    >
+      {visible.map((child, i) => {
+        const avatar = size
+          ? cloneElement(child as ReactElement<AvatarProps>, { size })
+          : child;
+        return (
+          <View
+            key={i}
+            className={cn(i > 0 && '-ml-2', 'rounded-full border-2 border-card')}
+          >
+            {avatar}
+          </View>
+        );
+      })}
+      {overflow > 0 && (
+        <View className={cn('-ml-2', overflowVariants({ size }))}>
+          <Text className="text-xs font-semibold text-muted-foreground">
+            +{overflow}
+          </Text>
+        </View>
+      )}
+    </View>
+  );
+});

package/src/AvatarGroup.tsx

@@ -0,0 +1,114 @@
+'use client';
+
+/**
+ * AvatarGroup (web variant — React DOM).
+ *
+ * Stacked/overlapping row of Avatar components with an overflow "+N"
+ * count. The `size` prop is forwarded to Avatar children via
+ * cloneElement. `max` controls how many avatars are visible before
+ * the "+N" badge appears.
+ *
+ * Wiki: docs/components/AvatarGroup.md
+ */
+import { Children, cloneElement, forwardRef, isValidElement, type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+import type { AvatarProps } from './Avatar.js';
+
+const overflowVariants = cva(
+  'relative inline-flex shrink-0 items-center justify-center rounded-full bg-muted font-semibold text-muted-foreground ring-2 ring-card',
+  {
+    variants: {
+      size: {
+        sm: 'h-8 w-8 text-xs',
+        md: 'h-10 w-10 text-xs',
+        lg: 'h-12 w-12 text-sm',
+      },
+    },
+    defaultVariants: { size: 'md' },
+  },
+);
+
+export interface AvatarGroupProps
+  extends HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof overflowVariants> {
+  /** Maximum avatars to show before the "+N" counter. */
+  max?: number;
+  /** Direction of the visible stack. */
+  direction?: 'row' | 'row-reverse';
+  /** Visual overlap density. */
+  overlap?: 'none' | 'sm' | 'md' | 'lg';
+  /** Whether later avatars appear above earlier avatars. */
+  stackOrder?: 'first-on-top' | 'last-on-top';
+  /** Accessible label for the group. */
+  label?: string;
+  /** Custom overflow renderer. */
+  renderOverflow?: ((count: number) => ReactNode) | undefined;
+}
+
+const OVERLAP_CLASS = {
+  none: 'space-x-0',
+  sm: '-space-x-1',
+  md: '-space-x-2',
+  lg: '-space-x-3',
+} as const;
+
+export const AvatarGroup = forwardRef<HTMLDivElement, AvatarGroupProps>(function AvatarGroup(
+  {
+    className,
+    max = 4,
+    size,
+    direction = 'row',
+    overlap = 'md',
+    stackOrder = 'last-on-top',
+    label,
+    renderOverflow,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const items = Children.toArray(children).filter(isValidElement);
+  const visible = items.slice(0, max);
+  const overflow = items.length - max;
+  const orderedVisible = direction === 'row-reverse' ? [...visible].reverse() : visible;
+
+  return (
+    <div
+      ref={ref}
+      role="group"
+      aria-label={label ?? `Group of ${items.length} avatars`}
+      className={cn(
+        'flex items-center',
+        direction === 'row-reverse' && 'flex-row-reverse',
+        OVERLAP_CLASS[overlap],
+        className,
+      )}
+      {...props}
+    >
+      {orderedVisible.map((child, i) => {
+        const avatar = size
+          ? cloneElement(child as ReactElement<AvatarProps>, { size })
+          : child;
+        const zIndex = stackOrder === 'last-on-top' ? i + 1 : orderedVisible.length - i;
+        return (
+          <span
+            key={(child as ReactElement).key ?? i}
+            className="relative inline-flex shrink-0 rounded-full leading-none ring-2 ring-card"
+            style={{ zIndex }}
+          >
+            {avatar}
+          </span>
+        );
+      })}
+      {overflow > 0 && (
+        <span
+          aria-label={`${overflow} more`}
+          className={overflowVariants({ size })}
+        >
+          {renderOverflow ? renderOverflow(overflow) : `+${overflow}`}
+        </span>
+      )}
+    </div>
+  );
+});

package/src/Badge.native.tsx

@@ -0,0 +1,85 @@
+/**
+ * Badge (React Native variant).
+ *
+ * Small status / labelling pill rendered as `<View>` + `<Text>`.
+ * Same prop API as the web variant.
+ *
+ * Wiki: docs/components/Badge.md
+ */
+import { forwardRef, type ReactNode } from 'react';
+import { Pressable, Text, View, type ViewProps } from 'react-native';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+
+export const badgeVariants = cva(
+  'flex-row items-center rounded-full px-2 py-0.5 border',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary border-transparent',
+        secondary: 'bg-secondary border-transparent',
+        destructive: 'bg-destructive border-transparent',
+        success: 'bg-success border-transparent',
+        warning: 'bg-warning border-transparent',
+        outline: 'bg-transparent border-border',
+        dot: 'bg-transparent border-transparent',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+const TEXT_TONE: Record<NonNullable<VariantProps<typeof badgeVariants>['variant']>, string> = {
+  default: 'text-primary-foreground',
+  secondary: 'text-secondary-foreground',
+  destructive: 'text-destructive-foreground',
+  success: 'text-success-foreground',
+  warning: 'text-warning-foreground',
+  outline: 'text-foreground',
+  dot: 'text-foreground',
+};
+
+const DOT_COLORS: Record<string, string> = {
+  default: 'bg-primary',
+  destructive: 'bg-destructive',
+  success: 'bg-success',
+  warning: 'bg-warning',
+};
+
+export interface BadgeProps
+  extends Omit<ViewProps, 'style'>,
+    VariantProps<typeof badgeVariants> {
+  className?: string;
+  children?: ReactNode;
+  icon?: ReactNode;
+  dotTone?: 'default' | 'destructive' | 'success' | 'warning';
+  onRemove?: () => void;
+}
+
+export const Badge = forwardRef<View, BadgeProps>(function Badge(
+  { className, variant = 'default', icon, dotTone = 'default', onRemove, children, ...props },
+  ref,
+) {
+  const tone = TEXT_TONE[variant ?? 'default'];
+  return (
+    <View ref={ref} className={cn(badgeVariants({ variant }), className)} {...props}>
+      {variant === 'dot' && (
+        <View className={cn('h-1.5 w-1.5 rounded-full mr-1', DOT_COLORS[dotTone])} />
+      )}
+      {icon && <View className="mr-1">{icon}</View>}
+      <Text className={cn('text-xs font-medium leading-none', tone)}>{children}</Text>
+      {onRemove && (
+        <Pressable
+          onPress={onRemove}
+          accessibilityRole="button"
+          accessibilityLabel="Remove"
+          className="ml-1 opacity-60"
+        >
+          <Text className={cn('text-xs', tone)}>✕</Text>
+        </Pressable>
+      )}
+    </View>
+  );
+});

package/src/Badge.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+/**
+ * Badge (web variant — React DOM).
+ *
+ * Small status / labelling pill. Renders a `<span>` by default so it
+ * composes inline with text; pass `as` if you need a different element
+ * (e.g., `<a>` for a clickable badge link).
+ *
+ * Wiki: docs/components/Badge.md
+ */
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+
+export const badgeVariants = cva(
+  'inline-flex items-center gap-1 rounded-card ' +
+    'text-caption font-semibold leading-none ' +
+    'border border-transparent transition-colors duration-150',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary-50 text-primary dark:bg-primary-950 dark:text-primary-300',
+        accent: 'bg-accent-50 text-accent-600 dark:bg-accent-950 dark:text-accent-300',
+        secondary: 'bg-brand-neutral-66 text-secondary-foreground',
+        destructive: 'bg-red-100 text-destructive',
+        success: 'bg-green-100 text-success',
+        warning: 'bg-yellow-100 text-warning',
+        outline: 'border-border bg-transparent text-foreground',
+        dot: 'bg-transparent text-foreground pl-0',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+type BadgeVariantProps = VariantProps<typeof badgeVariants>;
+
+const DOT_COLORS: Record<string, string> = {
+  default: 'bg-primary',
+  secondary: 'bg-secondary-foreground',
+  destructive: 'bg-destructive',
+  success: 'bg-success',
+  warning: 'bg-warning',
+};
+
+export interface BadgeProps
+  extends HTMLAttributes<HTMLSpanElement>,
+    BadgeVariantProps {
+  /** Icon rendered before the label. */
+  icon?: ReactNode;
+  /** Tone of the dot indicator (only used with variant="dot"). */
+  dotTone?: 'default' | 'destructive' | 'success' | 'warning';
+  /** When provided, renders a remove (×) button. */
+  onRemove?: () => void;
+}
+
+export const Badge = forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
+  { className, variant, icon, dotTone = 'default', onRemove, children, ...props },
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      className={cn(
+        badgeVariants({ variant }),
+        variant === 'dot' ? 'px-1.5 py-0.5' : 'px-2 py-0.5',
+        className,
+      )}
+      {...props}
+    >
+      {variant === 'dot' && (
+        <span className={cn('inline-block h-1.5 w-1.5 rounded-full', DOT_COLORS[dotTone])} />
+      )}
+      {icon && <span className="[&>svg]:h-3 [&>svg]:w-3 flex-shrink-0">{icon}</span>}
+      {children}
+      {onRemove && (
+        <button
+          type="button"
+          onClick={(e) => { e.stopPropagation(); onRemove(); }}
+          aria-label="Remove"
+          className="ml-0.5 rounded-full p-0.5 opacity-60 hover:opacity-100 transition-opacity focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        >
+          <svg aria-hidden viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth={2} className="h-2.5 w-2.5">
+            <path strokeLinecap="round" d="M4 12L12 4M4 4l8 8" />
+          </svg>
+        </button>
+      )}
+    </span>
+  );
+});