@emara/ui 1.1.0

package/components/ui/empty-state.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiAddLine, RiInboxLine, RiRocketLine, RiSearchLine } from "@remixicon/react";
+
+import { Button } from "./button";
+import {
+  EmptyState,
+  EmptyStateActions,
+  EmptyStateDescription,
+  EmptyStateIllustration,
+  EmptyStateTitle,
+} from "./empty-state";
+
+const meta: Meta<typeof EmptyState> = {
+  title: "Data/EmptyState",
+  component: EmptyState,
+  parameters: { layout: "padded" },
+  argTypes: {
+    variant: { control: "select", options: ["default", "compact", "splash"] },
+    size: { control: "select", options: ["sm", "md", "lg"] },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof EmptyState>;
+
+export const Default: Story = {
+  args: {
+    variant: "default",
+    icon: <RiInboxLine />,
+    title: "No charges yet",
+    description: "When customers pay, their charges will appear here.",
+    actions: <Button leftIcon={<RiAddLine />}>Create charge</Button>,
+  },
+  render: (args) => (
+    <div className="border-border w-xl rounded-md border">
+      <EmptyState {...args} />
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="w-xl space-y-4">
+      {(["sm", "md", "lg"] as const).map((size) => (
+        <div key={size} className="border-border rounded-md border">
+          <EmptyState
+            size={size}
+            icon={<RiInboxLine />}
+            title={`Size: ${size}`}
+            description="The illustration, title, and description all scale with size."
+          />
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const Compact: Story = {
+  args: {
+    variant: "compact",
+    icon: <RiSearchLine />,
+    title: "No matches",
+    description: "Try a different search term.",
+    actions: (
+      <Button size="sm" variant="ghost">
+        Clear
+      </Button>
+    ),
+  },
+  render: (args) => (
+    <div className="border-border w-lg rounded-md border">
+      <EmptyState {...args} />
+    </div>
+  ),
+};
+
+export const Splash: Story = {
+  args: {
+    variant: "splash",
+    icon: <RiRocketLine />,
+    title: "Welcome to Emara",
+    description: "Let's get you set up with the tools you need.",
+    actions: (
+      <>
+        <Button size="lg">Get started</Button>
+        <Button size="lg" variant="outline">
+          View docs
+        </Button>
+      </>
+    ),
+  },
+  render: (args) => (
+    <div className="border-border w-full max-w-3xl rounded-md border">
+      <EmptyState {...args} />
+    </div>
+  ),
+};
+
+/**
+ * Composition with sub-components instead of convenience props.
+ * Use this when you need more layout control.
+ */
+export const Composed: Story = {
+  render: () => (
+    <div className="border-border w-xl rounded-md border">
+      <EmptyState variant="default" size="md">
+        <EmptyStateIllustration>
+          <RiInboxLine />
+        </EmptyStateIllustration>
+        <EmptyStateTitle as="h2">Inbox empty</EmptyStateTitle>
+        <EmptyStateDescription>
+          Compose your first message — you&apos;ll see it here when sent.
+        </EmptyStateDescription>
+        <EmptyStateActions>
+          <Button leftIcon={<RiAddLine />}>Compose</Button>
+          <Button variant="outline">Learn more</Button>
+        </EmptyStateActions>
+      </EmptyState>
+    </div>
+  ),
+};

package/components/ui/empty-state.tsx

@@ -0,0 +1,289 @@
+"use client";
+
+import { createContext, forwardRef, useContext, useMemo } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-4-components.md §5.
+
+type EmptyStateVariant = "default" | "compact" | "splash";
+type EmptyStateSize = "sm" | "md" | "lg";
+
+interface EmptyStateContextValue {
+  variant: EmptyStateVariant;
+  size: EmptyStateSize;
+}
+
+const EmptyStateContext = createContext<EmptyStateContextValue | null>(null);
+
+function useEmptyStateContext(): EmptyStateContextValue {
+  const ctx = useContext(EmptyStateContext);
+  if (!ctx) throw new Error("EmptyState subcomponents must be used inside <EmptyState>");
+  return ctx;
+}
+
+// --- Root ------------------------------------------------------------------
+
+const emptyStateVariants = cva("text-foreground", {
+  variants: {
+    variant: {
+      default: "flex w-full flex-col items-center text-center",
+      compact: "flex w-full items-start gap-3 text-start",
+      splash: "flex min-h-[60vh] w-full flex-col items-center justify-center text-center",
+    },
+    size: {
+      sm: "",
+      md: "",
+      lg: "",
+    },
+  },
+  compoundVariants: [
+    { variant: "default", size: "sm", class: "py-6 gap-2" },
+    { variant: "default", size: "md", class: "py-10 gap-3" },
+    { variant: "default", size: "lg", class: "py-16 gap-4" },
+    { variant: "compact", size: "sm", class: "p-3" },
+    { variant: "compact", size: "md", class: "p-4" },
+    { variant: "compact", size: "lg", class: "p-6" },
+    { variant: "splash", size: "sm", class: "gap-4" },
+    { variant: "splash", size: "md", class: "gap-6" },
+    { variant: "splash", size: "lg", class: "gap-8" },
+  ],
+  defaultVariants: { variant: "default", size: "md" },
+});
+
+type EmptyStateRootVariants = VariantProps<typeof emptyStateVariants>;
+
+type EmptyStateProps = React.HTMLAttributes<HTMLDivElement> &
+  EmptyStateRootVariants & {
+    asChild?: boolean;
+    /** Convenience: provided icon is rendered inside Illustration. */
+    icon?: React.ReactNode;
+    /** Convenience: provided string is rendered as the Title. */
+    title?: React.ReactNode;
+    /** Convenience: provided node is rendered as the Description. */
+    description?: React.ReactNode;
+    /** Convenience: provided node is rendered inside Actions. */
+    actions?: React.ReactNode;
+  };
+
+const EmptyState = forwardRef<HTMLDivElement, EmptyStateProps>(function EmptyState(
+  {
+    className,
+    variant = "default",
+    size = "md",
+    asChild = false,
+    icon,
+    title,
+    description,
+    actions,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const Comp = asChild ? Slot : "div";
+  const ctx = useMemo(
+    () => ({ variant: variant ?? "default", size: size ?? "md" }),
+    [variant, size],
+  );
+
+  // When convenience props are used, render the composed structure
+  // automatically. Otherwise just render children.
+  const usingConvenience =
+    icon !== undefined ||
+    title !== undefined ||
+    description !== undefined ||
+    actions !== undefined;
+
+  return (
+    <EmptyStateContext.Provider value={ctx}>
+      <Comp
+        ref={ref}
+        role="status"
+        className={cn(emptyStateVariants({ variant, size }), className)}
+        {...props}
+      >
+        {usingConvenience ? (
+          variant === "compact" ? (
+            <>
+              {icon ? <EmptyStateIllustration>{icon}</EmptyStateIllustration> : null}
+              <div className="flex-1 min-w-0">
+                {title ? <EmptyStateTitle>{title}</EmptyStateTitle> : null}
+                {description ? (
+                  <EmptyStateDescription>{description}</EmptyStateDescription>
+                ) : null}
+              </div>
+              {actions ? <EmptyStateActions>{actions}</EmptyStateActions> : null}
+            </>
+          ) : (
+            <>
+              {icon ? <EmptyStateIllustration>{icon}</EmptyStateIllustration> : null}
+              {title ? <EmptyStateTitle>{title}</EmptyStateTitle> : null}
+              {description ? (
+                <EmptyStateDescription>{description}</EmptyStateDescription>
+              ) : null}
+              {actions ? <EmptyStateActions>{actions}</EmptyStateActions> : null}
+            </>
+          )
+        ) : (
+          children
+        )}
+      </Comp>
+    </EmptyStateContext.Provider>
+  );
+});
+EmptyState.displayName = "EmptyState";
+
+// --- Illustration ----------------------------------------------------------
+
+const illustrationVariants = cva(
+  "text-muted-foreground [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "[&_svg]:size-12",
+        compact: "[&_svg]:size-5 mt-0.5",
+        splash: "[&_svg]:size-20",
+      },
+      size: {
+        sm: "",
+        md: "",
+        lg: "",
+      },
+    },
+    compoundVariants: [
+      { variant: "default", size: "sm", class: "[&_svg]:size-10" },
+      { variant: "default", size: "lg", class: "[&_svg]:size-16" },
+      { variant: "splash", size: "sm", class: "[&_svg]:size-16" },
+      { variant: "splash", size: "lg", class: "[&_svg]:size-24" },
+    ],
+    defaultVariants: { variant: "default", size: "md" },
+  },
+);
+
+type EmptyStateIllustrationProps = React.HTMLAttributes<HTMLDivElement>;
+
+const EmptyStateIllustration = forwardRef<HTMLDivElement, EmptyStateIllustrationProps>(
+  function EmptyStateIllustration({ className, ...props }, ref) {
+    const { variant, size } = useEmptyStateContext();
+    return (
+      <div
+        ref={ref}
+        aria-hidden="true"
+        className={cn(illustrationVariants({ variant, size }), className)}
+        {...props}
+      />
+    );
+  },
+);
+EmptyStateIllustration.displayName = "EmptyStateIllustration";
+
+// --- Title ------------------------------------------------------------------
+
+const titleVariants = cva("font-semibold text-foreground", {
+  variants: {
+    variant: {
+      default: "",
+      compact: "",
+      splash: "",
+    },
+    size: {
+      sm: "text-sm",
+      md: "text-base",
+      lg: "text-lg",
+    },
+  },
+  compoundVariants: [
+    { variant: "splash", size: "sm", class: "text-lg" },
+    { variant: "splash", size: "md", class: "text-2xl" },
+    { variant: "splash", size: "lg", class: "text-3xl" },
+  ],
+  defaultVariants: { variant: "default", size: "md" },
+});
+
+type EmptyStateTitleProps = React.HTMLAttributes<HTMLHeadingElement> & {
+  as?: "h2" | "h3" | "h4" | "h5" | "h6";
+};
+
+const EmptyStateTitle = forwardRef<HTMLHeadingElement, EmptyStateTitleProps>(
+  function EmptyStateTitle({ as: Heading = "h3", className, ...props }, ref) {
+    const { variant, size } = useEmptyStateContext();
+    return (
+      <Heading
+        ref={ref}
+        className={cn(titleVariants({ variant, size }), className)}
+        {...props}
+      />
+    );
+  },
+);
+EmptyStateTitle.displayName = "EmptyStateTitle";
+
+// --- Description ------------------------------------------------------------
+
+const descriptionVariants = cva("text-muted-foreground", {
+  variants: {
+    size: {
+      sm: "text-xs",
+      md: "text-sm",
+      lg: "text-base",
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+type EmptyStateDescriptionProps = React.HTMLAttributes<HTMLParagraphElement>;
+
+const EmptyStateDescription = forwardRef<HTMLParagraphElement, EmptyStateDescriptionProps>(
+  function EmptyStateDescription({ className, ...props }, ref) {
+    const { size } = useEmptyStateContext();
+    return (
+      <p
+        ref={ref}
+        className={cn(descriptionVariants({ size }), "max-w-prose", className)}
+        {...props}
+      />
+    );
+  },
+);
+EmptyStateDescription.displayName = "EmptyStateDescription";
+
+// --- Actions ----------------------------------------------------------------
+
+type EmptyStateActionsProps = React.HTMLAttributes<HTMLDivElement>;
+
+const EmptyStateActions = forwardRef<HTMLDivElement, EmptyStateActionsProps>(
+  function EmptyStateActions({ className, ...props }, ref) {
+    const { variant } = useEmptyStateContext();
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "flex flex-wrap items-center gap-2",
+          variant === "compact" ? "ms-auto" : "justify-center mt-2",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+EmptyStateActions.displayName = "EmptyStateActions";
+
+export {
+  EmptyState,
+  EmptyStateIllustration,
+  EmptyStateTitle,
+  EmptyStateDescription,
+  EmptyStateActions,
+  emptyStateVariants,
+};
+export type {
+  EmptyStateProps,
+  EmptyStateIllustrationProps,
+  EmptyStateTitleProps,
+  EmptyStateDescriptionProps,
+  EmptyStateActionsProps,
+};

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

@@ -0,0 +1,201 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { Checkbox } from "./checkbox";
+import { FieldGroup } from "./field-group";
+import { Input } from "./input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "./select";
+import { Textarea } from "./textarea";
+import { TooltipProvider } from "./tooltip";
+
+const meta: Meta<typeof FieldGroup> = {
+  title: "Forms/FieldGroup",
+  component: FieldGroup,
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <TooltipProvider delayDuration={200}>
+        <div className="w-96">
+          <Story />
+        </div>
+      </TooltipProvider>
+    ),
+  ],
+  argTypes: {
+    required: { control: "boolean" },
+    optional: { control: "boolean" },
+    invalid: { control: "boolean" },
+    disabled: { control: "boolean" },
+    orientation: { control: "select", options: ["vertical", "horizontal"] },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FieldGroup>;
+
+export const Default: Story = {
+  render: (args) => (
+    <FieldGroup {...args}>
+      <FieldGroup.Label>Full name</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Input placeholder="Alice Bouchaib" />
+      </FieldGroup.Control>
+      <FieldGroup.HelpText>As it appears on your ID.</FieldGroup.HelpText>
+    </FieldGroup>
+  ),
+};
+
+export const Required: Story = {
+  args: { required: true },
+  render: (args) => (
+    <FieldGroup {...args}>
+      <FieldGroup.Label>Email address</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Input type="email" placeholder="alice@example.com" />
+      </FieldGroup.Control>
+    </FieldGroup>
+  ),
+};
+
+export const Optional: Story = {
+  args: { optional: true },
+  render: (args) => (
+    <FieldGroup {...args}>
+      <FieldGroup.Label>Phone number</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Input type="tel" placeholder="+212 6 12 34 56 78" />
+      </FieldGroup.Control>
+      <FieldGroup.HelpText>We&apos;ll only use this for security alerts.</FieldGroup.HelpText>
+    </FieldGroup>
+  ),
+};
+
+export const Invalid: Story = {
+  args: { invalid: true, required: true },
+  render: (args) => (
+    <FieldGroup {...args}>
+      <FieldGroup.Label>Email address</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Input type="email" defaultValue="not-an-email" />
+      </FieldGroup.Control>
+      <FieldGroup.HelpText>Enter the address you signed up with.</FieldGroup.HelpText>
+      <FieldGroup.ErrorText>That doesn&apos;t look like a valid email.</FieldGroup.ErrorText>
+    </FieldGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+  render: (args) => (
+    <FieldGroup {...args}>
+      <FieldGroup.Label>Workspace slug</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Input defaultValue="emara-ui" />
+      </FieldGroup.Control>
+      <FieldGroup.HelpText>Contact support to change this.</FieldGroup.HelpText>
+    </FieldGroup>
+  ),
+};
+
+export const HorizontalLayout: Story = {
+  args: { orientation: "horizontal" },
+  render: (args) => (
+    <FieldGroup {...args}>
+      <FieldGroup.Label>Username</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Input placeholder="alice" />
+      </FieldGroup.Control>
+    </FieldGroup>
+  ),
+};
+
+export const WithTextarea: Story = {
+  args: { required: true },
+  render: (args) => (
+    <FieldGroup {...args}>
+      <FieldGroup.Label>Bio</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Textarea placeholder="Tell us a bit about yourself…" />
+      </FieldGroup.Control>
+      <FieldGroup.HelpText>Markdown is supported.</FieldGroup.HelpText>
+    </FieldGroup>
+  ),
+};
+
+export const WithSelect: Story = {
+  render: () => (
+    <FieldGroup required>
+      <FieldGroup.Label>Country</FieldGroup.Label>
+      <FieldGroup.Control>
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="Pick a country" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="ma">Morocco</SelectItem>
+            <SelectItem value="fr">France</SelectItem>
+            <SelectItem value="de">Germany</SelectItem>
+          </SelectContent>
+        </Select>
+      </FieldGroup.Control>
+    </FieldGroup>
+  ),
+};
+
+export const WithCheckbox: Story = {
+  render: () => (
+    <FieldGroup invalid>
+      <FieldGroup.Control>
+        <Checkbox label="I accept the terms and conditions" />
+      </FieldGroup.Control>
+      <FieldGroup.ErrorText>You must accept the terms to continue.</FieldGroup.ErrorText>
+    </FieldGroup>
+  ),
+};
+
+/** Real-world form composition: 4 fields, one with a validation error. */
+export const Form: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [email, setEmail] = useState("not-an-email");
+      const invalidEmail = !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email);
+      return (
+        <form className="space-y-4">
+          <FieldGroup required>
+            <FieldGroup.Label>Full name</FieldGroup.Label>
+            <FieldGroup.Control>
+              <Input placeholder="Alice Bouchaib" />
+            </FieldGroup.Control>
+          </FieldGroup>
+
+          <FieldGroup required invalid={invalidEmail}>
+            <FieldGroup.Label>Email</FieldGroup.Label>
+            <FieldGroup.Control>
+              <Input
+                type="email"
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+              />
+            </FieldGroup.Control>
+            <FieldGroup.HelpText>We&apos;ll never share your email.</FieldGroup.HelpText>
+            <FieldGroup.ErrorText>Enter a valid email address.</FieldGroup.ErrorText>
+          </FieldGroup>
+
+          <FieldGroup optional>
+            <FieldGroup.Label>Bio</FieldGroup.Label>
+            <FieldGroup.Control>
+              <Textarea placeholder="Tell us a bit about yourself…" />
+            </FieldGroup.Control>
+          </FieldGroup>
+        </form>
+      );
+    };
+    return <Wrapper />;
+  },
+};