@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/components/stepper/stepper.tsx

@@ -0,0 +1,554 @@
+"use client";
+
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+import {
+  createContext,
+  type KeyboardEvent,
+  type ReactNode,
+  useContext,
+} from "react";
+
+import { cn } from "../../lib";
+
+type StepperOrientation = "horizontal" | "vertical";
+type StepState = "active" | "completed" | "inactive" | "loading";
+type StepIndicators = Partial<Record<StepState, ReactNode>>;
+type StepperTriggerMode = "both" | "forward-only" | "backward-only" | "none";
+
+function isStepNavigable(
+  step: number,
+  activeStep: number,
+  triggerMode: StepperTriggerMode,
+): boolean {
+  if (triggerMode === "none") return false;
+  if (triggerMode === "both") return true;
+  if (triggerMode === "backward-only") return step <= activeStep;
+  return step >= activeStep;
+}
+
+interface StepperContextValue {
+  activeStep: number;
+  setActiveStep: (step: number) => void;
+  orientation: StepperOrientation;
+  indicators: StepIndicators;
+  triggerMode: StepperTriggerMode;
+}
+
+const StepperContext = createContext<StepperContextValue | undefined>(
+  undefined,
+);
+
+function useStepper() {
+  const context = useContext(StepperContext);
+  if (!context) {
+    throw new Error("useStepper must be used within a StepperRoot");
+  }
+  return context;
+}
+
+interface StepItemContextValue {
+  step: number;
+  state: StepState;
+  isDisabled: boolean;
+  isLoading: boolean;
+}
+
+const StepItemContext = createContext<StepItemContextValue | undefined>(
+  undefined,
+);
+
+function useStepItem() {
+  const context = useContext(StepItemContext);
+  if (!context) {
+    throw new Error("useStepItem must be used within a StepperItem");
+  }
+  return context;
+}
+
+interface StepperRootProps extends useRender.ComponentProps<"div"> {
+  defaultValue?: number;
+  value?: number;
+  onValueChange?: (value: number) => void;
+  orientation?: StepperOrientation;
+  indicators?: StepIndicators;
+  triggerMode?: StepperTriggerMode;
+}
+
+export function StepperRoot({
+  defaultValue = 1,
+  value,
+  onValueChange,
+  orientation = "horizontal",
+  indicators = {},
+  triggerMode = "both",
+  className,
+  render,
+  children,
+  ...props
+}: StepperRootProps) {
+  const [activeStep = 1, setActiveStep] = useControllableState<number>({
+    prop: value,
+    defaultProp: defaultValue,
+    onChange: onValueChange,
+  });
+
+  const defaultProps = {
+    className: cn(
+      "flex w-full data-[orientation=horizontal]:flex-col data-[orientation=vertical]:flex-row data-[orientation=vertical]:gap-8",
+      className,
+    ),
+    "data-orientation": orientation,
+    "data-slot": "stepper",
+    children,
+  };
+
+  return (
+    <StepperContext.Provider
+      value={{
+        activeStep,
+        setActiveStep,
+        orientation,
+        indicators,
+        triggerMode,
+      }}
+    >
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </StepperContext.Provider>
+  );
+}
+
+export function StepperNav({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"nav">) {
+  const { orientation } = useStepper();
+
+  const defaultProps = {
+    role: "tablist",
+    "aria-orientation": orientation,
+    "data-orientation": orientation,
+    "data-slot": "stepper-nav",
+    className: cn(
+      "group/stepper-nav inline-flex data-[orientation=horizontal]:w-full data-[orientation=horizontal]:flex-row data-[orientation=vertical]:flex-col",
+      className,
+    ),
+    children,
+  };
+
+  return useRender({
+    defaultTagName: "nav",
+    render,
+    props: mergeProps<"nav">(defaultProps, props),
+  });
+}
+
+interface StepperItemProps extends useRender.ComponentProps<"div"> {
+  step: number;
+  disabled?: boolean;
+  loading?: boolean;
+}
+
+export function StepperItem({
+  step,
+  disabled = false,
+  loading = false,
+  className,
+  render,
+  children,
+  ...props
+}: StepperItemProps) {
+  const { activeStep } = useStepper();
+
+  const state: StepState =
+    step < activeStep
+      ? "completed"
+      : step === activeStep
+        ? "active"
+        : "inactive";
+
+  const isLoading = loading && step === activeStep;
+
+  const defaultProps = {
+    "data-state": state,
+    "data-loading": isLoading || undefined,
+    "data-slot": "stepper-item",
+    className: cn(
+      "group/step flex items-center justify-center not-last:flex-1",
+      "group-data-[orientation=horizontal]/stepper-nav:flex-row group-data-[orientation=vertical]/stepper-nav:flex-col",
+      className,
+    ),
+    children,
+  };
+
+  return (
+    <StepItemContext.Provider
+      value={{ step, state, isDisabled: disabled, isLoading }}
+    >
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </StepItemContext.Provider>
+  );
+}
+
+export function StepperTrigger({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"button">) {
+  const { activeStep, setActiveStep, triggerMode } = useStepper();
+  const { step, state, isDisabled, isLoading } = useStepItem();
+  const isSelected = activeStep === step;
+  const isNavigable = isStepNavigable(step, activeStep, triggerMode);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+    const triggers = Array.from(
+      event.currentTarget
+        .closest('[data-slot="stepper-nav"]')
+        ?.querySelectorAll<HTMLButtonElement>(
+          '[data-slot="stepper-trigger"]:not([disabled]):not([aria-disabled="true"])',
+        ) ?? [],
+    );
+    const index = triggers.indexOf(event.currentTarget);
+    if (index === -1) return;
+
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowDown":
+        event.preventDefault();
+        triggers[(index + 1) % triggers.length]?.focus();
+        break;
+      case "ArrowLeft":
+      case "ArrowUp":
+        event.preventDefault();
+        triggers[(index - 1 + triggers.length) % triggers.length]?.focus();
+        break;
+      case "Home":
+        event.preventDefault();
+        triggers[0]?.focus();
+        break;
+      case "End":
+        event.preventDefault();
+        triggers[triggers.length - 1]?.focus();
+        break;
+    }
+  };
+
+  const defaultProps = {
+    type: "button" as const,
+    role: "tab",
+    id: `stepper-tab-${step}`,
+    "aria-selected": isSelected,
+    "aria-controls": `stepper-panel-${step}`,
+    "aria-disabled": !isNavigable || undefined,
+    tabIndex: isSelected ? 0 : -1,
+    disabled: isDisabled,
+    "data-state": state,
+    "data-loading": isLoading || undefined,
+    "data-slot": "stepper-trigger",
+    className: cn(
+      "inline-flex items-center gap-2.5 rounded-full outline-none",
+      isNavigable ? "cursor-pointer" : "cursor-default",
+      "focus-visible:z-10 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50",
+      "disabled:pointer-events-none disabled:opacity-60",
+      className,
+    ),
+    onClick: () => {
+      if (!isNavigable) return;
+      setActiveStep(step);
+    },
+    onKeyDown: handleKeyDown,
+    children,
+  };
+
+  return useRender({
+    defaultTagName: "button",
+    render,
+    props: mergeProps<"button">(defaultProps, props),
+  });
+}
+
+export function StepperIndicator({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"div">) {
+  const { state, isLoading } = useStepItem();
+  const { indicators } = useStepper();
+
+  const override =
+    (isLoading && indicators.loading) ||
+    (state === "completed" && indicators.completed) ||
+    (state === "active" && indicators.active) ||
+    (state === "inactive" && indicators.inactive);
+
+  const defaultProps = {
+    "data-state": state,
+    "data-loading": isLoading || undefined,
+    "data-slot": "stepper-indicator",
+    className: cn(
+      "relative flex size-6 shrink-0 items-center justify-center overflow-hidden rounded-full border-background bg-accent text-accent-foreground text-xs",
+      "data-[state=active]:bg-primary data-[state=active]:text-primary-foreground",
+      "data-[state=completed]:bg-primary data-[state=completed]:text-primary-foreground",
+      className,
+    ),
+    children: <div className="absolute">{override || children}</div>,
+  };
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  });
+}
+
+export function StepperSeparator({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"div">) {
+  const { state } = useStepItem();
+
+  const defaultProps = {
+    "aria-hidden": true,
+    "data-state": state,
+    "data-slot": "stepper-separator",
+    className: cn(
+      "m-0.5 rounded-sm bg-muted data-[state=completed]:bg-primary",
+      "group-data-[orientation=horizontal]/stepper-nav:h-0.5 group-data-[orientation=horizontal]/stepper-nav:flex-1",
+      "group-data-[orientation=vertical]/stepper-nav:h-12 group-data-[orientation=vertical]/stepper-nav:w-0.5",
+      className,
+    ),
+    children,
+  };
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  });
+}
+
+export function StepperTitle({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"h3">) {
+  const { state } = useStepItem();
+
+  const defaultProps = {
+    "data-state": state,
+    "data-slot": "stepper-title",
+    className: cn("font-medium text-sm leading-none", className),
+    children,
+  };
+
+  return useRender({
+    defaultTagName: "h3",
+    render,
+    props: mergeProps<"h3">(defaultProps, props),
+  });
+}
+
+export function StepperDescription({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"p">) {
+  const { state } = useStepItem();
+
+  const defaultProps = {
+    "data-state": state,
+    "data-slot": "stepper-description",
+    className: cn("text-muted-foreground text-sm", className),
+    children,
+  };
+
+  return useRender({
+    defaultTagName: "p",
+    render,
+    props: mergeProps<"p">(defaultProps, props),
+  });
+}
+
+export function StepperPanel({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"div">) {
+  const { activeStep } = useStepper();
+
+  const defaultProps = {
+    "data-state": activeStep,
+    "data-slot": "stepper-panel",
+    className: cn("w-full", className),
+    children,
+  };
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  });
+}
+
+interface StepperContentProps extends useRender.ComponentProps<"div"> {
+  value: number;
+  forceMount?: boolean;
+}
+
+export function StepperContent({
+  value,
+  forceMount = false,
+  className,
+  render,
+  children,
+  ...props
+}: StepperContentProps) {
+  const { activeStep } = useStepper();
+  const isActive = value === activeStep;
+
+  if (!forceMount && !isActive) return null;
+
+  const defaultProps = {
+    role: "tabpanel",
+    id: `stepper-panel-${value}`,
+    "aria-labelledby": `stepper-tab-${value}`,
+    hidden: !isActive,
+    "data-state": isActive ? "active" : "inactive",
+    "data-slot": "stepper-content",
+    className: cn("w-full", className, !isActive && "hidden"),
+    children,
+  };
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  });
+}
+
+interface StepperItemData {
+  title?: ReactNode;
+  description?: ReactNode;
+  indicator?: ReactNode;
+  content?: ReactNode;
+  disabled?: boolean;
+  loading?: boolean;
+}
+
+interface StepperProps extends Omit<StepperRootProps, "children"> {
+  items: StepperItemData[];
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Navigation list that holds every step. */
+    nav?: string;
+    /** Single step container (indicator + label + separator). */
+    item?: string;
+    /** Clickable step button. */
+    trigger?: string;
+    /** Round indicator (number, icon, or check). */
+    indicator?: string;
+    /** Step title above the description. */
+    title?: string;
+    /** Step description below the title. */
+    description?: string;
+    /** Line between steps. */
+    separator?: string;
+    /** Panel below the nav that holds the active step's content. */
+    panel?: string;
+    /** Single step content rendered when the step is active. */
+    content?: string;
+  };
+}
+
+export function Stepper({ items, classNames, ...props }: StepperProps) {
+  const hasContent = items.some((item) => item.content != null);
+
+  return (
+    <StepperRoot {...props}>
+      <StepperNav className={classNames?.nav}>
+        {items.map((item, i) => {
+          const step = i + 1;
+          return (
+            <StepperItem
+              key={step}
+              step={step}
+              disabled={item.disabled}
+              loading={item.loading}
+              className={classNames?.item}
+            >
+              <StepperTrigger className={classNames?.trigger}>
+                <StepperIndicator className={classNames?.indicator}>
+                  {item.indicator ?? step}
+                </StepperIndicator>
+                {(item.title || item.description) && (
+                  <div className="flex flex-col gap-0.5 text-left">
+                    {item.title ? (
+                      <StepperTitle className={classNames?.title}>
+                        {item.title}
+                      </StepperTitle>
+                    ) : null}
+                    {item.description ? (
+                      <StepperDescription className={classNames?.description}>
+                        {item.description}
+                      </StepperDescription>
+                    ) : null}
+                  </div>
+                )}
+              </StepperTrigger>
+              {i < items.length - 1 ? (
+                <StepperSeparator className={classNames?.separator} />
+              ) : null}
+            </StepperItem>
+          );
+        })}
+      </StepperNav>
+
+      {hasContent ? (
+        <StepperPanel className={classNames?.panel}>
+          {items.map((item, i) =>
+            item.content != null ? (
+              <StepperContent
+                key={i + 1}
+                value={i + 1}
+                className={classNames?.content}
+              >
+                {item.content}
+              </StepperContent>
+            ) : null,
+          )}
+        </StepperPanel>
+      ) : null}
+    </StepperRoot>
+  );
+}
+
+export { useStepper, useStepItem };
+export type {
+  StepperRootProps,
+  StepperItemProps,
+  StepperContentProps,
+  StepperOrientation,
+  StepperTriggerMode,
+  StepState,
+  StepIndicators,
+  StepperItemData,
+  StepperProps,
+};

package/src/components/switch/index.ts

@@ -0,0 +1 @@
+export * from "./switch";

package/src/components/switch/switch.stories.tsx

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useArgs } from "storybook/preview-api";
+import { Button, Switch, SwitchRoot, SwitchThumb } from "../../components";
+
+/**
+ * Toggle switch built on Base UI. Built on `@base-ui/react/switch`.
+ *
+ * The composite `Switch` accepts a label via `label` prop or `children` —
+ * both work, `label` takes priority when both are provided.
+ * `controlFirst` (default `true`) places the switch before the label.
+ *
+ * Supports controlled state via `checked` + `onCheckedChange`, and native
+ * form integration via `name` + `required`.
+ *
+ * Reference: [Switch – Base UI](https://base-ui.com/react/components/switch)
+ */
+const meta: Meta<typeof Switch> = {
+  title: "Components/Switch",
+  component: Switch,
+  parameters: { layout: "centered" },
+  args: {
+    label: "Enable notifications",
+  },
+  argTypes: {
+    children: { control: false },
+    onCheckedChange: { control: false },
+    classNames: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Switch>;
+
+export const Default: Story = {};
+
+/**
+ * `className` estila el switch (root visible). `classNames` expone los slots
+ * `wrapper` (flex outer), `thumb` (perilla) y `label` (texto al costado).
+ */
+export const WithClassNames: Story = {
+  args: {
+    classNames: {
+      wrapper: "gap-x-4",
+      thumb: "bg-primary-foreground",
+      label: "text-primary",
+    },
+  },
+};
+
+/**
+ * Pass `label` or `children` — both render an accessible label next to the switch.
+ * `label` takes priority when both are provided.
+ */
+export const WithLabel: Story = {
+  args: {
+    label: "Dark mode",
+  },
+};
+
+/**
+ * `controlFirst={false}` places the label before the switch.
+ * Default is `true` (switch → label).
+ */
+export const ControlFirst: Story = {
+  args: {
+    controlFirst: false,
+    label: "Dark mode",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+};
+
+/**
+ * Use `checked` + `onCheckedChange` for controlled mode.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [{ checked }, updateArgs] = useArgs();
+    return (
+      <Switch
+        {...args}
+        checked={checked}
+        onCheckedChange={(value) => updateArgs({ checked: value })}
+      />
+    );
+  },
+  args: {
+    defaultChecked: true,
+  },
+};
+
+/**
+ * Base UI injects a hidden `<input type="checkbox">` so `name` and `required`
+ * work with native `FormData` out of the box.
+ */
+export const Required: Story = {
+  args: {
+    name: "notifications",
+    required: true,
+    label: "I agree to receive marketing emails",
+  },
+  render: (args) => (
+    <form
+      className="space-y-2"
+      onSubmit={(event) => {
+        event.preventDefault();
+        const data = new FormData(event.currentTarget);
+        alert(`Value: ${data.get("notifications")}`);
+      }}
+    >
+      <Switch {...args} />
+      <Button type="submit">Submit</Button>
+    </form>
+  ),
+};
+
+/**
+ * Direct composition with primitives for full structural control.
+ *
+ * ```tsx
+ * <SwitchRoot>
+ *   <SwitchThumb />
+ * </SwitchRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <SwitchRoot>
+      <SwitchThumb />
+    </SwitchRoot>
+  ),
+};