@ztwoint/z-ui 0.1.44 → 0.1.45

package/dist/components/avatar/avatar.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Props for the Avatar Root component.
+ * @interface RootProps
+ */
+interface RootProps {
+    /** Size variant of the avatar. Affects width, height, border radius, and text size */
+    size: 'xxs' | 'xs' | 'sm' | 'md';
+    /** Color theme of the avatar using design system color tokens */
+    color: 'orange' | 'purple' | 'green' | 'blue';
+    /** Child components, typically Avatar.Label or Avatar.Element */
+    children: React.ReactNode;
+    /** Additional CSS classes for custom styling */
+    className?: string;
+    /** Ref object for the root div element */
+    ref?: React.RefObject<HTMLDivElement>;
+}
+/**
+ * Avatar Root component - the container for avatar content.
+ *
+ * @param props - The component props
+ * @param props.size - Size variant (xxs: 18px, xs: 22px, sm: 26px, md: 30px)
+ * @param props.color - Color theme using design system tokens
+ * @param props.children - Child components (typically Avatar.Label)
+ * @param props.className - Additional CSS classes
+ * @param props.ref - Ref for the root div element
+ * @returns The rendered avatar container
+ *
+ * @example
+ * ```tsx
+ * <Avatar.Root size="sm" color="orange">
+ *   <Avatar.Label label="JD" />
+ * </Avatar.Root>
+ * ```
+ */
+declare function Root({ size, color, children, className, ref, ...props }: RootProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Props for the Avatar Element component.
+ * @interface ElementProps
+ */
+interface ElementProps {
+    /** Text content to display in the avatar (typically initials) */
+    label: string;
+    /** Additional CSS classes for custom styling */
+    className?: string;
+    /** Ref object for the span element */
+    ref?: React.RefObject<HTMLSpanElement>;
+    /** When true, merges props with the first child instead of rendering a span */
+    asChild?: boolean;
+    /** Child components (only used when asChild is true) */
+    children?: React.ReactNode;
+}
+/**
+ * Avatar Element component - flexible text/content renderer with asChild support.
+ *
+ * @param props - The component props
+ * @param props.label - Text to display (typically user initials)
+ * @param props.className - Additional CSS classes
+ * @param props.ref - Ref for the element
+ * @param props.asChild - When true, uses Radix Slot to merge with first child
+ * @param props.children - Child components (only when asChild is true)
+ * @returns The rendered element with avatar text styling
+ *
+ * @example
+ * ```tsx
+ * <Avatar.Element label="JD" />
+ *
+ * // With asChild for custom elements
+ * <Avatar.Element label="JD" asChild>
+ *   <button>Custom Button</button>
+ * </Avatar.Element>
+ * ```
+ */
+declare function Element({ label, className, ref, asChild, children, ...props }: ElementProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Props for the Avatar Label component.
+ * @interface LabelProps
+ */
+interface LabelProps {
+    /** Text content to display in the avatar (typically user initials) */
+    label: string;
+    /** Additional CSS classes for custom styling */
+    className?: string;
+    /** Ref object for the span element */
+    ref?: React.RefObject<HTMLSpanElement>;
+}
+/**
+ * Avatar Label component - simplified wrapper around Avatar.Element.
+ *
+ * @param props - The component props
+ * @param props.label - Text to display (typically user initials)
+ * @param props.className - Additional CSS classes
+ * @param props.ref - Ref for the span element
+ * @returns The rendered label with avatar text styling
+ *
+ * @example
+ * ```tsx
+ * <Avatar.Label label="JD" />
+ * <Avatar.Label label="AB" className="text-yellow-300" />
+ * ```
+ */
+declare function Label({ label, className, ref, ...props }: LabelProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Props for the AvatarWithLabel convenience component.
+ * @interface AvatarWithLabelProps
+ */
+interface AvatarWithLabelProps {
+    /** Text content to display in the avatar (typically user initials) */
+    label: string;
+    /** Size variant of the avatar. Affects width, height, border radius, and text size */
+    size: 'xxs' | 'xs' | 'sm' | 'md';
+    /** Color theme of the avatar using design system color tokens */
+    color: 'orange' | 'purple' | 'green' | 'blue';
+    /** Additional CSS classes for custom styling */
+    className?: string;
+    /** Ref object for the root div element */
+    ref?: React.RefObject<HTMLDivElement>;
+}
+/**
+ * AvatarWithLabel - A convenience component that combines Avatar.Root and Avatar.Label.
+ * Perfect for simple use cases where you just need an avatar with text.
+ *
+ * @param props - The component props
+ * @param props.label - Text to display (typically user initials)
+ * @param props.size - Size variant (xxs: 18px, xs: 22px, sm: 26px, md: 30px)
+ * @param props.color - Color theme using design system tokens
+ * @param props.className - Additional CSS classes
+ * @param props.ref - Ref for the root div element
+ * @returns The rendered avatar with label
+ *
+ * @example
+ * ```tsx
+ * <AvatarWithLabel label="JD" size="sm" color="orange" />
+ * <AvatarWithLabel label="AB" size="md" color="blue" className="rounded-full" />
+ * ```
+ */
+declare function AvatarWithLabel({ label, size, color, className, ref, ...props }: AvatarWithLabelProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Avatar compound component with multiple variants for flexible usage.
+ *
+ * @namespace Avatar
+ * @property {React.ComponentType<RootProps>} Root - Container component for avatar content
+ * @property {React.ComponentType<ElementProps>} Element - Flexible text/content renderer with asChild support
+ * @property {React.ComponentType<LabelProps>} Label - Simplified text renderer (wrapper around Element)
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Avatar.Root size="sm" color="orange">
+ *   <Avatar.Label label="JD" />
+ * </Avatar.Root>
+ *
+ * // With custom styling
+ * <Avatar.Root size="md" color="blue" className="rounded-full border-2 border-white">
+ *   <Avatar.Label label="AB" className="text-yellow-300" />
+ * </Avatar.Root>
+ *
+ * // Using Element with asChild for custom components
+ * <Avatar.Root size="sm" color="green">
+ *   <Avatar.Element label="CD" asChild>
+ *     <button onClick={handleClick}>Clickable Avatar</button>
+ *   </Avatar.Element>
+ * </Avatar.Root>
+ * ```
+ */
+declare const Avatar: {
+    Root: typeof Root;
+    Element: typeof Element;
+    Label: typeof Label;
+};
+/**
+ * @fileoverview Avatar component library providing both compound and convenience components.
+ *
+ * This module exports:
+ * - Avatar: A compound component with Root, Element, and Label sub-components
+ * - AvatarWithLabel: A convenience component that combines Root and Label
+ *
+ * Features:
+ * - Multiple sizes (xxs, xs, sm, md) with responsive scaling
+ * - Color themes using design system tokens
+ * - Customizable styling via className
+ * - Radix Slot support for advanced composition
+ * - TypeScript support with comprehensive prop types
+ * - Optimized typography for readability at all sizes
+ */
+export { Avatar, AvatarWithLabel, ElementProps, LabelProps, RootProps, AvatarWithLabelProps };

package/dist/components/avatar/avatar.js

@@ -0,0 +1,55 @@
+import { jsx as o } from "react/jsx-runtime";
+import { cva as i } from "class-variance-authority";
+import { cn as l } from "../../lib/utils.js";
+import { Slot as f } from "@radix-ui/react-slot";
+const d = i("px-[.375rem] aspect-square flex items-center justify-center", {
+  variants: {
+    size: {
+      xxs: "size-[1.125rem] rounded-[.3125rem] text-[8px]",
+      xs: "size-[1.375rem] rounded-md text-sm",
+      sm: "size-[1.625rem] rounded-lg text-sm",
+      md: "size-[1.875rem] rounded-[.625rem] text-base"
+    },
+    color: {
+      orange: "bg-[var(--surface-warning-default)]",
+      purple: "bg-[var(--surface-purple-default)]",
+      green: "bg-[var(--surface-success-default)]",
+      blue: "bg-[var(--surface-accent-default)]"
+    }
+  },
+  defaultVariants: {
+    size: "sm",
+    color: "orange"
+  }
+});
+function p({ size: t, color: a, children: r, className: e, ref: n, ...s }) {
+  const m = d({ size: t, color: a });
+  return /* @__PURE__ */ o("div", { "data-slot": "avatar-root", className: l(m, e), ref: n, ...s, children: r });
+}
+function u({ label: t, className: a, ref: r, asChild: e = !1, children: n, ...s }) {
+  return /* @__PURE__ */ o(
+    e ? f : "span",
+    {
+      "data-slot": "avatar-element",
+      className: l(e ? "" : "text-white text-center font-primary text-xs font-[450] leading-none tracking-[-0.0125rem] uppercase", a),
+      ref: r,
+      ...s,
+      children: e ? n : t
+    }
+  );
+}
+function x({ label: t, className: a, ref: r, ...e }) {
+  return /* @__PURE__ */ o(u, { label: t, className: a, ref: r, ...e });
+}
+function C({ label: t, size: a, color: r, className: e, ref: n, ...s }) {
+  return /* @__PURE__ */ o(c.Root, { size: a, color: r, className: e, ref: n, ...s, children: /* @__PURE__ */ o(c.Label, { label: t }) });
+}
+const c = {
+  Root: p,
+  Element: u,
+  Label: x
+};
+export {
+  c as Avatar,
+  C as AvatarWithLabel
+};