@emara/ui 1.1.0

package/components/ui/popover.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { forwardRef } from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+import { Skeleton } from "./skeleton";
+
+// Per docs/emara-ui-phase-3-components.md §3. Brought forward into v0.1 per
+// docs/emara-ui-implementation-plan.md §5 so Combobox / DatePicker / Label's
+// hint prop have the dependency they need.
+
+const Popover = PopoverPrimitive.Root;
+const PopoverTrigger = PopoverPrimitive.Trigger;
+const PopoverAnchor = PopoverPrimitive.Anchor;
+const PopoverClose = PopoverPrimitive.Close;
+
+// ----------------------------------------------------------------------------
+// PopoverContent
+// ----------------------------------------------------------------------------
+
+const popoverContentVariants = cva(
+  [
+    "z-popover outline-none",
+    "rounded-md border border-border bg-popover text-popover-foreground shadow-md",
+    // Enter/exit animations driven by Radix data-state. Slide direction
+    // depends on the resolved `side` so the panel "drops" from its trigger.
+    "data-[state=open]:animate-[scale-in_var(--duration-fast)_var(--ease-out)]",
+    "data-[state=closed]:animate-[scale-out_var(--duration-fast)_var(--ease-in)]",
+    "data-[side=top]:data-[state=open]:animate-[slide-in-from-bottom_var(--duration-fast)_var(--ease-out)]",
+    "data-[side=bottom]:data-[state=open]:animate-[slide-in-from-top_var(--duration-fast)_var(--ease-out)]",
+    "data-[side=left]:data-[state=open]:animate-[slide-in-from-end_var(--duration-fast)_var(--ease-out)]",
+    "data-[side=right]:data-[state=open]:animate-[slide-in-from-start_var(--duration-fast)_var(--ease-out)]",
+  ].join(" "),
+  {
+    variants: {
+      padding: {
+        none: "p-0",
+        sm: "p-2",
+        md: "p-3",
+        lg: "p-4",
+      },
+    },
+    defaultVariants: { padding: "md" },
+  },
+);
+
+type PopoverWidth = "fit" | "trigger" | "sm" | "md" | "lg" | "xl" | number;
+
+const WIDTH_TO_PX: Record<Exclude<PopoverWidth, "fit" | "trigger" | number>, number> = {
+  sm: 192,
+  md: 256,
+  lg: 320,
+  xl: 448,
+};
+
+function resolveWidthStyle(width: PopoverWidth | undefined): React.CSSProperties | undefined {
+  if (width === undefined) return undefined;
+  if (width === "fit") return { width: "max-content" };
+  if (width === "trigger") {
+    return { width: "var(--radix-popover-trigger-width)" };
+  }
+  if (typeof width === "number") return { width: width };
+  return { width: WIDTH_TO_PX[width] };
+}
+
+function resolveMaxHeight(maxHeight: number | string | undefined): React.CSSProperties | undefined {
+  if (maxHeight === undefined) return undefined;
+  return { maxHeight: typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight };
+}
+
+type PopoverContentProps = React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> &
+  VariantProps<typeof popoverContentVariants> & {
+    width?: PopoverWidth;
+    maxHeight?: number | string;
+    arrow?: boolean;
+    loading?: boolean;
+  };
+
+const PopoverContent = forwardRef<
+  React.ElementRef<typeof PopoverPrimitive.Content>,
+  PopoverContentProps
+>(function PopoverContent(
+  {
+    className,
+    align = "center",
+    sideOffset = 8,
+    width,
+    maxHeight,
+    arrow = false,
+    loading = false,
+    padding,
+    style,
+    children,
+    ...props
+  },
+  ref,
+) {
+  // If maxHeight is set the content scrolls internally.
+  const overflowStyle = maxHeight !== undefined ? { overflowY: "auto" as const } : undefined;
+  const merged: React.CSSProperties = {
+    ...resolveWidthStyle(width),
+    ...resolveMaxHeight(maxHeight),
+    ...overflowStyle,
+    ...style,
+  };
+
+  // Loading skeleton mimics a small panel of text rows.
+  const loadingNode = (
+    <div className="space-y-2">
+      <Skeleton className="h-3 w-3/4" />
+      <Skeleton className="h-3 w-full" />
+      <Skeleton className="h-3 w-5/6" />
+    </div>
+  );
+
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        ref={ref}
+        align={align}
+        sideOffset={sideOffset}
+        style={merged}
+        aria-busy={loading || undefined}
+        aria-live={loading ? "polite" : undefined}
+        className={cn(popoverContentVariants({ padding }), className)}
+        {...props}
+      >
+        {loading ? loadingNode : children}
+        {arrow ? <PopoverArrow /> : null}
+      </PopoverPrimitive.Content>
+    </PopoverPrimitive.Portal>
+  );
+});
+PopoverContent.displayName = "PopoverContent";
+
+// ----------------------------------------------------------------------------
+// PopoverArrow — standalone export so consumers can place it manually.
+// ----------------------------------------------------------------------------
+
+const PopoverArrow = forwardRef<
+  React.ElementRef<typeof PopoverPrimitive.Arrow>,
+  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Arrow>
+>(function PopoverArrow({ className, width = 12, height = 6, ...props }, ref) {
+  return (
+    <PopoverPrimitive.Arrow
+      ref={ref}
+      width={width}
+      height={height}
+      className={cn("fill-popover stroke-border", className)}
+      {...props}
+    />
+  );
+});
+PopoverArrow.displayName = "PopoverArrow";
+
+export {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverArrow,
+  PopoverAnchor,
+  PopoverClose,
+  popoverContentVariants,
+};
+export type { PopoverContentProps };

package/components/ui/radio-group.stories.tsx

@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Radio, RadioGroup } from "./radio-group";
+
+const meta: Meta<typeof RadioGroup> = {
+  title: "Forms/RadioGroup",
+  component: RadioGroup,
+  parameters: { layout: "centered" },
+  argTypes: {
+    size: { control: "select", options: ["sm", "md", "lg"] },
+    orientation: { control: "select", options: ["vertical", "horizontal"] },
+    variant: { control: "select", options: ["default", "card"] },
+    invalid: { control: "boolean" },
+    disabled: { control: "boolean" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof RadioGroup>;
+
+export const Default: Story = {
+  render: (args) => (
+    <RadioGroup {...args} defaultValue="email" className="w-72">
+      <Radio value="email" label="Email" />
+      <Radio value="sms" label="SMS" />
+      <Radio value="push" label="Push notification" />
+    </RadioGroup>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="grid grid-cols-3 gap-6">
+      {(["sm", "md", "lg"] as const).map((s) => (
+        <RadioGroup key={s} size={s} defaultValue="a">
+          <Radio value="a" label={`${s} option A`} />
+          <Radio value="b" label={`${s} option B`} />
+        </RadioGroup>
+      ))}
+    </div>
+  ),
+};
+
+export const Horizontal: Story = {
+  render: () => (
+    <RadioGroup orientation="horizontal" defaultValue="ltr">
+      <Radio value="ltr" label="LTR" />
+      <Radio value="rtl" label="RTL" />
+      <Radio value="auto" label="Auto" />
+    </RadioGroup>
+  ),
+};
+
+export const WithDescriptions: Story = {
+  render: () => (
+    <RadioGroup defaultValue="standard" className="w-80">
+      <Radio
+        value="standard"
+        label="Standard shipping"
+        description="Arrives in 5-7 business days. Free."
+      />
+      <Radio value="express" label="Express" description="Arrives in 2-3 business days. $9.99." />
+      <Radio value="overnight" label="Overnight" description="Next business day. $19.99." />
+    </RadioGroup>
+  ),
+};
+
+export const CardVariant: Story = {
+  render: () => (
+    <RadioGroup variant="card" defaultValue="pro" className="w-80">
+      <Radio value="starter" label="Starter" description="Up to 3 projects. Free forever." />
+      <Radio value="pro" label="Pro" description="Unlimited projects. $12/mo." />
+      <Radio value="team" label="Team" description="Seats and roles. $48/mo." />
+    </RadioGroup>
+  ),
+};
+
+export const Invalid: Story = {
+  args: { invalid: true },
+  render: (args) => (
+    <RadioGroup {...args} className="w-72">
+      <Radio value="a" label="Option A" />
+      <Radio value="b" label="Option B" />
+    </RadioGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <RadioGroup defaultValue="b" className="w-72">
+      <Radio value="a" label="Option A" disabled />
+      <Radio value="b" label="Option B" />
+      <Radio value="c" label="Option C" disabled />
+    </RadioGroup>
+  ),
+};

package/components/ui/radio-group.tsx

@@ -0,0 +1,250 @@
+"use client";
+
+import { createContext, forwardRef, useContext, useId } from "react";
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
+import { cva } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-2-components.md §2.
+
+// ----------------------------------------------------------------------------
+// Group-level context — propagates size/variant/invalid to children.
+// ----------------------------------------------------------------------------
+
+type RadioSize = "sm" | "md" | "lg";
+type RadioVariant = "default" | "card";
+
+interface RadioGroupContextValue {
+  size: RadioSize;
+  variant: RadioVariant;
+  invalid: boolean;
+}
+const RadioGroupContext = createContext<RadioGroupContextValue>({
+  size: "md",
+  variant: "default",
+  invalid: false,
+});
+
+function useRadioGroupContext(): RadioGroupContextValue {
+  return useContext(RadioGroupContext);
+}
+
+// ----------------------------------------------------------------------------
+// RadioGroup
+// ----------------------------------------------------------------------------
+
+const radioGroupRootVariants = cva("grid gap-2", {
+  variants: {
+    orientation: {
+      vertical: "grid-flow-row",
+      horizontal: "grid-flow-col auto-cols-max gap-3",
+    },
+  },
+  defaultVariants: { orientation: "vertical" },
+});
+
+type RadioGroupProps = Omit<
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>,
+  "orientation"
+> & {
+  orientation?: "vertical" | "horizontal";
+  variant?: RadioVariant;
+  invalid?: boolean;
+  size?: RadioSize;
+  loop?: boolean;
+};
+
+const RadioGroup = forwardRef<React.ElementRef<typeof RadioGroupPrimitive.Root>, RadioGroupProps>(
+  function RadioGroup(
+    {
+      className,
+      orientation = "vertical",
+      variant = "default",
+      invalid = false,
+      size = "md",
+      loop,
+      ...props
+    },
+    ref,
+  ) {
+    return (
+      <RadioGroupContext.Provider value={{ size, variant, invalid }}>
+        <RadioGroupPrimitive.Root
+          ref={ref}
+          orientation={orientation}
+          loop={loop}
+          aria-invalid={invalid || undefined}
+          className={cn(radioGroupRootVariants({ orientation }), className)}
+          {...props}
+        />
+      </RadioGroupContext.Provider>
+    );
+  },
+);
+RadioGroup.displayName = "RadioGroup";
+
+// ----------------------------------------------------------------------------
+// Radio
+// ----------------------------------------------------------------------------
+
+const radioCircleVariants = cva(
+  [
+    "aspect-square shrink-0 rounded-full border border-input bg-background text-primary",
+    "transition-colors",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+    "data-[state=checked]:border-primary",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        sm: "size-4",
+        md: "size-5",
+        lg: "size-6",
+      },
+      invalid: {
+        true: "border-destructive focus-visible:ring-destructive data-[state=checked]:border-destructive",
+        false: "",
+      },
+    },
+    defaultVariants: { size: "md", invalid: false },
+  },
+);
+
+const indicatorDot: Record<RadioSize, string> = {
+  sm: "size-1.5",
+  md: "size-2",
+  lg: "size-2.5",
+};
+
+const labelSize: Record<RadioSize, string> = {
+  sm: "text-xs",
+  md: "text-sm",
+  lg: "text-base",
+};
+
+const descriptionSize: Record<RadioSize, string> = {
+  sm: "text-2xs",
+  md: "text-xs",
+  lg: "text-sm",
+};
+
+const radioCardVariants = cva(
+  [
+    "relative flex w-full items-start gap-3 rounded-md border bg-background p-3",
+    "cursor-pointer select-none",
+    "transition-colors transition-shadow",
+    "hover:bg-accent/30",
+    "focus-within:outline-none focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background",
+    // Selected ring driven by the inner radio's data-state via the `in-` modifier.
+    "in-data-[state=checked]:border-primary in-data-[state=checked]:ring-2 in-data-[state=checked]:ring-primary",
+    "has-[button:disabled]:cursor-not-allowed has-[button:disabled]:opacity-50",
+  ].join(" "),
+  {
+    variants: {
+      invalid: {
+        true: "border-destructive in-data-[state=checked]:border-destructive in-data-[state=checked]:ring-destructive focus-within:ring-destructive",
+        false: "border-input",
+      },
+    },
+    defaultVariants: { invalid: false },
+  },
+);
+
+type RadioProps = Omit<
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>,
+  "children"
+> & {
+  label?: React.ReactNode;
+  description?: React.ReactNode;
+};
+
+const Radio = forwardRef<React.ElementRef<typeof RadioGroupPrimitive.Item>, RadioProps>(
+  function Radio({ className, label, description, id, ...props }, ref) {
+    const ctx = useRadioGroupContext();
+    const reactId = useId();
+    const radioId = id ?? reactId;
+    const descriptionId = description ? `${radioId}-description` : undefined;
+
+    const circle = (
+      <RadioGroupPrimitive.Item
+        ref={ref}
+        id={radioId}
+        aria-describedby={descriptionId}
+        className={cn(radioCircleVariants({ size: ctx.size, invalid: ctx.invalid }), className)}
+        {...props}
+      >
+        <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
+          <span
+            className={cn(
+              "bg-primary block rounded-full",
+              indicatorDot[ctx.size],
+              ctx.invalid && "bg-destructive",
+            )}
+          />
+        </RadioGroupPrimitive.Indicator>
+      </RadioGroupPrimitive.Item>
+    );
+
+    if (ctx.variant === "card") {
+      return (
+        <label htmlFor={radioId} className={cn(radioCardVariants({ invalid: ctx.invalid }))}>
+          {circle}
+          <span className="flex flex-1 flex-col gap-1 leading-none">
+            {label ? (
+              <span className={cn("font-medium select-none", labelSize[ctx.size])}>{label}</span>
+            ) : null}
+            {description ? (
+              <span
+                id={descriptionId}
+                className={cn("text-muted-foreground", descriptionSize[ctx.size])}
+              >
+                {description}
+              </span>
+            ) : null}
+          </span>
+        </label>
+      );
+    }
+
+    // Default variant — circle + label + description in a row.
+    if (!label && !description) return circle;
+
+    return (
+      <div className="inline-flex items-start gap-2">
+        {circle}
+        <div className="space-y-0.5 leading-none">
+          {label ? (
+            <label
+              htmlFor={radioId}
+              className={cn(
+                "cursor-pointer font-medium select-none",
+                labelSize[ctx.size],
+                props.disabled && "cursor-not-allowed opacity-50",
+              )}
+            >
+              {label}
+            </label>
+          ) : null}
+          {description ? (
+            <p
+              id={descriptionId}
+              className={cn(
+                "text-muted-foreground",
+                descriptionSize[ctx.size],
+                props.disabled && "opacity-50",
+              )}
+            >
+              {description}
+            </p>
+          ) : null}
+        </div>
+      </div>
+    );
+  },
+);
+Radio.displayName = "Radio";
+
+export { RadioGroup, Radio, radioGroupRootVariants, radioCircleVariants };
+export type { RadioGroupProps, RadioProps };