@arolariu/components 0.5.0 → 1.0.0

package/src/components/ui/textarea.tsx

@@ -1,21 +1,41 @@
-"use client";
-
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./textarea.module.css";
+
+/**
+ * Props for the shared textarea wrapper.
+ */
+interface TextareaProps extends React.ComponentPropsWithoutRef<"textarea"> {
+  /** Additional CSS classes merged with the textarea styles. @default undefined */
+  className?: string;
+}
 
-const Textarea = React.forwardRef<HTMLTextAreaElement, React.ComponentProps<"textarea">>(({className, ...props}, ref) => {
-  return (
+/**
+ * Renders a multi-line text area for longer free-form text input.
+ *
+ * @remarks
+ * - Renders a `<textarea>` element by default
+ * - Built on {@link https://base-ui.com/react/components/textarea | Base UI Textarea}
+ * - Supports the `render` prop for element composition through standard React composition patterns
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Textarea placeholder="Add additional details" />
+ * ```
+ *
+ * @see {@link https://base-ui.com/react/components/textarea | Base UI Documentation}
+ */
+const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({className, ...props}: Readonly<TextareaProps>, ref): React.JSX.Element => (
     <textarea
-      className={cn(
-        "flex min-h-[60px] w-full rounded-md border border-neutral-200 bg-transparent px-3 py-2 text-base shadow-sm placeholder:text-neutral-500 focus-visible:ring-1 focus-visible:ring-neutral-950 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:border-neutral-800 dark:placeholder:text-neutral-400 dark:focus-visible:ring-neutral-300",
-        className,
-      )}
       ref={ref}
+      className={cn(styles.textarea, className)}
       {...props}
     />
-  );
-});
+  ),
+);
 Textarea.displayName = "Textarea";
 
 export {Textarea};

package/src/components/ui/timeline.module.css

@@ -0,0 +1,43 @@
+.timeline {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
+.item {
+  position: relative;
+  display: flex;
+  gap: var(--ac-space-3);
+  padding-bottom: var(--ac-space-4);
+}
+
+.item:last-child {
+  padding-bottom: 0;
+}
+
+.item:not(:last-child)::before {
+  content: "";
+  position: absolute;
+  left: 0.5625rem;
+  top: 1.5rem;
+  bottom: 0;
+  width: 2px;
+  background-color: var(--ac-border);
+}
+
+.dot {
+  width: 1.25rem;
+  height: 1.25rem;
+  margin-top: 0.125rem;
+  border: 2px solid var(--ac-primary);
+  border-radius: 50%;
+  background-color: var(--ac-background);
+  flex-shrink: 0;
+}
+
+.content {
+  flex: 1;
+  min-width: 0;
+  padding-bottom: var(--ac-space-1);
+}

package/src/components/ui/timeline.tsx

@@ -0,0 +1,153 @@
+import * as React from "react";
+
+import {cn} from "@/lib/utilities";
+import styles from "./timeline.module.css";
+
+/**
+ * Represents the configurable props for the {@link Timeline} component.
+ *
+ * @remarks
+ * Extends native `<div>` attributes so timelines can expose test hooks, ARIA metadata,
+ * and layout overrides while delegating item composition to child components.
+ */
+interface TimelineProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Timeline items composed as children.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Represents the configurable props for the {@link TimelineItem} component.
+ */
+interface TimelineItemProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The composed timeline dot and content for an individual event.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Represents the configurable props for the {@link TimelineDot} component.
+ */
+type TimelineDotProps = React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Represents the configurable props for the {@link TimelineContent} component.
+ */
+interface TimelineContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Content rendered alongside the timeline marker.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * A vertical timeline container for displaying chronological events.
+ *
+ * @remarks
+ * **Rendering Context**: Server- and client-compatible presentational component.
+ *
+ * Compose it with {@link TimelineItem}, {@link TimelineDot}, and {@link TimelineContent}
+ * to render milestones, release notes, audit trails, or journey steps in order.
+ *
+ * @example
+ * ```tsx
+ * <Timeline>
+ *   <TimelineItem>
+ *     <TimelineDot />
+ *     <TimelineContent>Account created</TimelineContent>
+ *   </TimelineItem>
+ * </Timeline>
+ * ```
+ *
+ * @see {@link TimelineItem}
+ * @see {@link TimelineContent}
+ */
+const Timeline = React.forwardRef<HTMLDivElement, TimelineProps>(({className, ...props}, ref) => (
+  <div
+    ref={ref}
+    role='list'
+    className={cn(styles.timeline, className)}
+    {...props}
+  />
+));
+Timeline.displayName = "Timeline";
+
+/**
+ * A single event row within a {@link Timeline}.
+ *
+ * @remarks
+ * Renders a flex row that aligns a marker with its corresponding content block.
+ *
+ * @example
+ * ```tsx
+ * <TimelineItem>
+ *   <TimelineDot />
+ *   <TimelineContent>Invoice submitted</TimelineContent>
+ * </TimelineItem>
+ * ```
+ *
+ * @see {@link Timeline}
+ */
+const TimelineItem = React.forwardRef<HTMLDivElement, TimelineItemProps>(({className, ...props}, ref) => (
+  <div
+    ref={ref}
+    role='listitem'
+    className={cn(styles.item, className)}
+    {...props}
+  />
+));
+TimelineItem.displayName = "TimelineItem";
+
+/**
+ * A visual marker used to indicate a timeline event point.
+ *
+ * @remarks
+ * The dot is decorative by default and is removed from the accessibility tree with
+ * `aria-hidden="true"`.
+ *
+ * @example
+ * ```tsx
+ * <TimelineDot />
+ * ```
+ *
+ * @see {@link TimelineItem}
+ */
+const TimelineDot = React.forwardRef<HTMLDivElement, TimelineDotProps>(({className, ...props}, ref) => (
+  <div
+    ref={ref}
+    aria-hidden='true'
+    className={cn(styles.dot, className)}
+    {...props}
+  />
+));
+TimelineDot.displayName = "TimelineDot";
+
+/**
+ * The content container rendered beside a {@link TimelineDot}.
+ *
+ * @remarks
+ * Use this wrapper for text, metadata, or richer composed content associated with a
+ * timeline event.
+ *
+ * @example
+ * ```tsx
+ * <TimelineContent>
+ *   <strong>Version 1.0 released</strong>
+ * </TimelineContent>
+ * ```
+ *
+ * @see {@link Timeline}
+ */
+const TimelineContent = React.forwardRef<HTMLDivElement, TimelineContentProps>(({className, ...props}, ref) => (
+  <div
+    ref={ref}
+    className={cn(styles.content, className)}
+    {...props}
+  />
+));
+TimelineContent.displayName = "TimelineContent";
+
+export {Timeline, TimelineContent, TimelineDot, TimelineItem};
+export type {TimelineContentProps, TimelineDotProps, TimelineItemProps, TimelineProps};

package/src/components/ui/toggle-group.module.css

@@ -0,0 +1,5 @@
+.root {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ac-space-1);
+}

package/src/components/ui/toggle-group.tsx

@@ -1,53 +1,134 @@
 "use client";
 
-import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
-import {type VariantProps} from "class-variance-authority";
+import {mergeProps} from "@base-ui/react/merge-props";
+import {ToggleGroup as BaseToggleGroup} from "@base-ui/react/toggle-group";
+import {useRender} from "@base-ui/react/use-render";
 import * as React from "react";
 
-import {toggleVariants} from "@/components/ui/toggle";
 import {cn} from "@/lib/utilities";
+import {Toggle, toggleVariants, type ToggleProps, type ToggleSize, type ToggleVariant} from "./toggle";
+import styles from "./toggle-group.module.css";
 
-const ToggleGroupContext = React.createContext<VariantProps<typeof toggleVariants>>({
-  size: "default",
-  variant: "default",
-});
-
-const ToggleGroup = React.forwardRef<
-  React.ComponentRef<typeof ToggleGroupPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root> & VariantProps<typeof toggleVariants>
->(({className, variant, size, children, ...props}, ref) => (
-  <ToggleGroupPrimitive.Root
-    ref={ref}
-    className={cn("flex items-center justify-center gap-1", className)}
-    {...props}>
-    <ToggleGroupContext.Provider value={{variant, size}}>{children}</ToggleGroupContext.Provider>
-  </ToggleGroupPrimitive.Root>
-));
-
-ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName;
-
-const ToggleGroupItem = React.forwardRef<
-  React.ComponentRef<typeof ToggleGroupPrimitive.Item>,
-  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> & VariantProps<typeof toggleVariants>
->(({className, children, variant, size, ...props}, ref) => {
+interface ToggleGroupContextValue {
+  size?: ToggleSize;
+  variant?: ToggleVariant;
+}
+
+const ToggleGroupContext = React.createContext<ToggleGroupContextValue>({});
+
+export interface ToggleGroupProps extends Omit<React.ComponentPropsWithRef<typeof BaseToggleGroup>, "className"> {
+  /**
+   * Additional CSS classes merged with the toggle-group root styles.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Shared visual variant inherited by descendant toggle items when not explicitly overridden.
+   * @default undefined
+   */
+  variant?: ToggleVariant;
+  /**
+   * Shared size inherited by descendant toggle items when not explicitly overridden.
+   * @default undefined
+   */
+  size?: ToggleSize;
+}
+
+/**
+ * Props for an individual toggle-group item.
+ *
+ * @remarks
+ * Inherits the shared toggle API except for pressed-state props, which are controlled
+ * by the surrounding {@link ToggleGroup}.
+ */
+export interface ToggleGroupItemProps extends Omit<ToggleProps, "pressed" | "defaultPressed" | "onPressedChange"> {}
+
+/**
+ * Groups related toggles into a single multi-select or single-select control.
+ *
+ * @remarks
+ * - Renders a `<div>` element by default
+ * - Built on Base UI Toggle Group primitives
+ * - Provides shared `size` and `variant` values to descendant items
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup
+ *   defaultValue={["bold"]}
+ *   toggleMultiple>
+ *   <ToggleGroupItem value='bold'>Bold</ToggleGroupItem>
+ *   <ToggleGroupItem value='italic'>Italic</ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ *
+ * @see {@link https://base-ui.com/react/components/toggle-group | Base UI Toggle Group Docs}
+ */
+function ToggleGroup(props: Readonly<ToggleGroup.Props>): React.ReactElement {
+  const {className, children, render, size, variant, ...otherProps} = props;
+
+  return (
+    <BaseToggleGroup
+      {...otherProps}
+      render={useRender({
+        defaultTagName: "div",
+        render: render as never,
+        props: mergeProps({className: cn(styles.root, className)}, {}),
+      })}>
+      <ToggleGroupContext.Provider value={{variant, size}}>{children}</ToggleGroupContext.Provider>
+    </BaseToggleGroup>
+  );
+}
+
+/**
+ * Renders an individual toggle item within a toggle group.
+ *
+ * @remarks
+ * - Renders a styled toggle button
+ * - Built on the shared `Toggle` component and Base UI Toggle Group state
+ * - Inherits `size` and `variant` from the nearest {@link ToggleGroup} when omitted
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup defaultValue={["left"]}>
+ *   <ToggleGroupItem value='left'>Left</ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ *
+ * @see {@link https://base-ui.com/react/components/toggle-group | Base UI Toggle Group Docs}
+ */
+function ToggleGroupItem(props: Readonly<ToggleGroupItem.Props>): React.ReactElement {
+  const {className, size, variant, ...otherProps} = props;
   const context = React.useContext(ToggleGroupContext);
 
   return (
-    <ToggleGroupPrimitive.Item
-      ref={ref}
+    <Toggle
       className={cn(
         toggleVariants({
-          variant: context.variant || variant,
-          size: context.size || size,
+          variant: variant ?? context.variant,
+          size: size ?? context.size,
         }),
         className,
       )}
-      {...props}>
-      {children}
-    </ToggleGroupPrimitive.Item>
+      size={size ?? context.size}
+      variant={variant ?? context.variant}
+      {...otherProps}
+    />
   );
-});
+}
+
+// eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
+namespace ToggleGroup {
+  export type Props = ToggleGroupProps;
+  export type State = BaseToggleGroup.State;
+}
+
+// eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
+namespace ToggleGroupItem {
+  export type Props = ToggleGroupItemProps;
+  export type State = Toggle.State;
+}
 
-ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName;
+ToggleGroup.displayName = "ToggleGroup";
+ToggleGroupItem.displayName = "ToggleGroupItem";
 
 export {ToggleGroup, ToggleGroupItem};

package/src/components/ui/toggle.module.css

@@ -0,0 +1,57 @@
+.root {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--ac-space-2);
+  border: 1px solid transparent;
+  border-radius: var(--ac-radius-md);
+  background-color: transparent;
+  color: var(--ac-foreground);
+  font-size: var(--ac-text-sm);
+  font-weight: 500;
+  cursor: pointer;
+  outline: none;
+  transition: background-color var(--ac-transition-fast), color var(--ac-transition-fast), border-color var(--ac-transition-fast);
+}
+
+.root:focus-visible {
+  outline: 2px solid var(--ac-ring);
+  outline-offset: 2px;
+}
+
+.root[data-disabled] {
+  pointer-events: none;
+  opacity: 0.5;
+}
+
+.root[data-pressed] {
+  background-color: var(--ac-accent);
+  color: var(--ac-accent-foreground);
+}
+
+.default {
+  background-color: transparent;
+}
+
+.outline {
+  border-color: var(--ac-border);
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.04);
+}
+
+.sizeDefault {
+  min-width: var(--ac-size-default);
+  height: var(--ac-size-default);
+  padding: 0 var(--ac-space-2);
+}
+
+.sizeSm {
+  min-width: var(--ac-size-md);
+  height: var(--ac-size-md);
+  padding: 0 var(--ac-space-2);
+}
+
+.sizeLg {
+  min-width: var(--ac-size-lg);
+  height: var(--ac-size-lg);
+  padding: 0 var(--ac-space-3);
+}

package/src/components/ui/toggle.tsx

@@ -1,44 +1,100 @@
 "use client";
 
-import * as TogglePrimitive from "@radix-ui/react-toggle";
-import {cva, type VariantProps} from "class-variance-authority";
+import {mergeProps} from "@base-ui/react/merge-props";
+import {Toggle as BaseToggle} from "@base-ui/react/toggle";
+import {useRender} from "@base-ui/react/use-render";
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./toggle.module.css";
 
-const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors hover:bg-neutral-100 hover:text-neutral-500 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-neutral-950 disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-neutral-100 data-[state=on]:text-neutral-900 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 dark:hover:bg-neutral-800 dark:hover:text-neutral-400 dark:focus-visible:ring-neutral-300 dark:data-[state=on]:bg-neutral-800 dark:data-[state=on]:text-neutral-50",
-  {
-    variants: {
-      variant: {
-        default: "bg-transparent",
-        outline:
-          "border border-neutral-200 bg-transparent shadow-sm hover:bg-neutral-100 hover:text-neutral-900 dark:border-neutral-800 dark:hover:bg-neutral-800 dark:hover:text-neutral-50",
-      },
-      size: {
-        default: "h-9 px-2 min-w-9",
-        sm: "h-8 px-1.5 min-w-8",
-        lg: "h-10 px-2.5 min-w-10",
-      },
-    },
-    defaultVariants: {
-      variant: "default",
-      size: "default",
-    },
+export type ToggleVariant = "default" | "outline";
+export type ToggleSize = "default" | "sm" | "lg";
+
+export interface ToggleVariantOptions {
+  /**
+   * Controls the rendered visual variant.
+   * @default "default"
+   */
+  variant?: ToggleVariant;
+  /**
+   * Controls the rendered size variant.
+   * @default "default"
+   */
+  size?: ToggleSize;
+  /**
+   * Applies additional CSS classes to the component root element.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/** Returns the CSS module classes used by the toggle wrapper. */
+export function toggleVariants({variant = "default", size = "default", className}: Readonly<ToggleVariantOptions> = {}): string {
+  const variantClass = variant === "outline" ? styles.outline : styles.default;
+  const sizeClass = size === "sm" ? styles.sizeSm : size === "lg" ? styles.sizeLg : styles.sizeDefault;
+
+  return cn(styles.root, variantClass, sizeClass, className);
+}
+
+export interface ToggleProps extends Omit<React.ComponentPropsWithRef<typeof BaseToggle>, "className"> {
+  /**
+   * Applies additional CSS classes to the component root element.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Controls the rendered visual variant.
+   * @default "default"
+   */
+  variant?: ToggleVariant;
+  /**
+   * Controls the rendered size variant.
+   * @default "default"
+   */
+  size?: ToggleSize;
+}
+
+/**
+ * Renders the toggle control.
+ *
+ * @remarks
+ * - Renders a `<button>` element by default
+ * - Built on {@link https://base-ui.com/react/components/toggle | Base UI Toggle}
+ * - Supports the `render` prop for element composition
+ *
+ * @example
+ * ```tsx
+ * <Toggle>Content</Toggle>
+ * ```
+ *
+ * @see {@link https://base-ui.com/react/components/toggle | Base UI Documentation}
+ */
+const Toggle = React.forwardRef<React.ComponentRef<typeof BaseToggle>, Toggle.Props>(
+  (props: Readonly<Toggle.Props>, ref): React.ReactElement => {
+    const {className, children, render, size, variant, ...otherProps} = props;
+
+    return (
+      <BaseToggle
+        ref={ref}
+        {...otherProps}
+        render={useRender({
+          defaultTagName: "button",
+          render: render as never,
+          props: mergeProps({className: toggleVariants({variant, size, className})}, {}),
+        })}>
+        {children}
+      </BaseToggle>
+    );
   },
 );
 
-const Toggle = React.forwardRef<
-  React.ComponentRef<typeof TogglePrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>
->(({className, variant, size, ...props}, ref) => (
-  <TogglePrimitive.Root
-    ref={ref}
-    className={cn(toggleVariants({variant, size, className}))}
-    {...props}
-  />
-));
+// eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
+namespace Toggle {
+  export type Props = ToggleProps;
+  export type State = BaseToggle.State;
+}
 
-Toggle.displayName = TogglePrimitive.Root.displayName;
+Toggle.displayName = "Toggle";
 
-export {Toggle, toggleVariants};
+export {Toggle};