@emara/ui 1.1.0

package/components/ui/input.tsx

@@ -0,0 +1,208 @@
+"use client";
+
+import { forwardRef, useId, useRef, useState } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { RiCloseLine, RiLoader2Line } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-1-components.md §2.
+
+const inputWrapperVariants = cva(
+  [
+    "relative flex items-center w-full gap-2 ps-3 pe-3",
+    "rounded-md border border-input bg-background text-foreground",
+    "transition-colors",
+    "focus-within:outline-none focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background",
+    "has-[input:disabled]:cursor-not-allowed has-[input:disabled]:opacity-50",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        xs: "h-7 text-xs",
+        sm: "h-8 text-xs",
+        md: "h-9 text-sm",
+        lg: "h-10 text-base",
+        xl: "h-12 text-base",
+      },
+      invalid: {
+        true: "border-destructive focus-within:ring-destructive",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+      invalid: false,
+    },
+  },
+);
+
+const inputFieldVariants = cva(
+  [
+    // The wrapper owns horizontal padding + gap. The field itself is flush
+    // inside the wrapper so adornments sit at the natural visual distance.
+    "block w-full min-w-0 bg-transparent text-foreground placeholder:text-muted-foreground",
+    "focus:outline-none disabled:cursor-not-allowed",
+    // Hide the spinner only for type=number. Other types keep their native
+    // chrome (search's clear button, date pickers, etc.).
+    "[&[type='number']]:[appearance:textfield]",
+    "[&[type='number']::-webkit-outer-spin-button]:appearance-none",
+    "[&[type='number']::-webkit-inner-spin-button]:appearance-none",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        xs: "h-7",
+        sm: "h-8",
+        md: "h-9",
+        lg: "h-10",
+        xl: "h-12",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);
+
+type InputWrapperVariants = VariantProps<typeof inputWrapperVariants>;
+
+type InputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> & {
+  size?: InputWrapperVariants["size"];
+  type?: "text" | "email" | "password" | "number" | "tel" | "url" | "search";
+  invalid?: boolean;
+  startAdornment?: React.ReactNode;
+  endAdornment?: React.ReactNode;
+  clearable?: boolean;
+  loading?: boolean;
+  onClear?: () => void;
+  asChild?: boolean;
+  wrapperClassName?: string;
+};
+
+const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  {
+    className,
+    wrapperClassName,
+    size,
+    type = "text",
+    invalid = false,
+    startAdornment,
+    endAdornment,
+    clearable = false,
+    loading = false,
+    onClear,
+    asChild = false,
+    value,
+    defaultValue,
+    onChange,
+    disabled,
+    readOnly,
+    id,
+    children,
+    "aria-describedby": ariaDescribedBy,
+    ...props
+  },
+  forwardedRef,
+) {
+  const isControlled = value !== undefined;
+  const [uncontrolledValue, setUncontrolledValue] = useState<string>(
+    typeof defaultValue === "string" ? defaultValue : "",
+  );
+  const currentValue = isControlled ? String(value ?? "") : uncontrolledValue;
+  const showClear = clearable && !disabled && !readOnly && !loading && currentValue.length > 0;
+
+  const innerRef = useRef<HTMLInputElement>(null);
+  const setRefs = (node: HTMLInputElement | null) => {
+    innerRef.current = node;
+    if (typeof forwardedRef === "function") forwardedRef(node);
+    else if (forwardedRef) forwardedRef.current = node;
+  };
+
+  const reactId = useId();
+  const inputId = id ?? reactId;
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (!isControlled) setUncontrolledValue(e.target.value);
+    onChange?.(e);
+  };
+
+  const handleClear = () => {
+    if (!isControlled) setUncontrolledValue("");
+    onClear?.();
+    const node = innerRef.current;
+    if (node) {
+      const nativeSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        "value",
+      )?.set;
+      nativeSetter?.call(node, "");
+      node.dispatchEvent(new Event("input", { bubbles: true }));
+      node.focus();
+    }
+  };
+
+  const hasEndContent = showClear || loading || endAdornment;
+  // When `asChild` is true the consumer provides their own input-like element
+  // as `children`; Slot forwards Input's props onto it. Otherwise we render a
+  // native <input>.
+  const Field = asChild ? Slot : "input";
+
+  return (
+    <div className={cn(inputWrapperVariants({ size, invalid }), wrapperClassName)}>
+      {startAdornment ? (
+        <span
+          className="text-muted-foreground pointer-events-none flex shrink-0 items-center [&_svg]:size-4 [&_svg]:shrink-0"
+          aria-hidden={typeof startAdornment !== "string"}
+        >
+          {startAdornment}
+        </span>
+      ) : null}
+
+      <Field
+        ref={setRefs}
+        id={inputId}
+        type={type}
+        className={cn(inputFieldVariants({ size }), className)}
+        disabled={disabled}
+        readOnly={readOnly}
+        aria-invalid={invalid || undefined}
+        aria-describedby={ariaDescribedBy}
+        value={isControlled ? currentValue : undefined}
+        defaultValue={isControlled ? undefined : defaultValue}
+        onChange={handleChange}
+        {...props}
+      >
+        {asChild ? children : null}
+      </Field>
+
+      {hasEndContent ? (
+        <span className="text-muted-foreground flex shrink-0 items-center gap-1 [&_svg]:size-4 [&_svg]:shrink-0">
+          {showClear ? (
+            <button
+              type="button"
+              onClick={handleClear}
+              aria-label="Clear"
+              className={cn(
+                "inline-flex items-center justify-center rounded p-0.5",
+                "text-muted-foreground hover:text-foreground",
+                "focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none",
+              )}
+            >
+              <RiCloseLine />
+            </button>
+          ) : null}
+          {loading ? <RiLoader2Line className="animate-spin" /> : null}
+          {endAdornment ? (
+            <span aria-hidden={typeof endAdornment !== "string"}>{endAdornment}</span>
+          ) : null}
+        </span>
+      ) : null}
+    </div>
+  );
+});
+Input.displayName = "Input";
+
+export { Input, inputWrapperVariants, inputFieldVariants };
+export type { InputProps };

package/components/ui/label.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Input } from "./input";
+import { Label } from "./label";
+import { TooltipProvider } from "./tooltip";
+
+const meta: Meta<typeof Label> = {
+  title: "Foundations/Label",
+  component: Label,
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <TooltipProvider delayDuration={200}>
+        <Story />
+      </TooltipProvider>
+    ),
+  ],
+  argTypes: {
+    size: { control: "select", options: ["sm", "md"] },
+    required: { control: "boolean" },
+    optional: { control: "boolean" },
+  },
+  args: { children: "Email address" },
+};
+
+export default meta;
+type Story = StoryObj<typeof Label>;
+
+export const Default: Story = {};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="space-y-2">
+      <Label {...args} size="sm">
+        Small label
+      </Label>
+      <Label {...args} size="md">
+        Medium label
+      </Label>
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  args: { required: true, children: "Email address" },
+};
+
+export const Optional: Story = {
+  args: { optional: true, children: "Phone number" },
+};
+
+export const PairedWithInput: Story = {
+  render: () => (
+    <div className="w-72 space-y-1.5">
+      <Label htmlFor="email" required>
+        Email address
+      </Label>
+      <Input id="email" type="email" placeholder="alice@example.com" />
+    </div>
+  ),
+};
+
+export const InheritsDisabled: Story = {
+  render: () => (
+    <div className="w-72 space-y-1.5">
+      <Label htmlFor="dis">
+        Username <span className="text-muted-foreground font-normal">(disabled control below)</span>
+      </Label>
+      <Input id="dis" disabled defaultValue="locked" className="peer" />
+    </div>
+  ),
+};
+
+/** `hint` adds a focusable info-icon at the end of the label with a tooltip. */
+export const WithHint: Story = {
+  render: () => (
+    <div className="w-72 space-y-1.5">
+      <Label htmlFor="pw" required hint="Must be 8+ characters and include a number.">
+        Password
+      </Label>
+      <Input id="pw" type="password" />
+    </div>
+  ),
+};

package/components/ui/label.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+import { forwardRef } from "react";
+import * as LabelPrimitive from "@radix-ui/react-label";
+import { RiInformationLine } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip";
+
+// Per docs/emara-ui-phase-1-components.md §4.
+
+const labelVariants = cva(
+  [
+    "inline-flex items-center gap-1 font-medium text-foreground select-none",
+    // Inherits disabled appearance from the associated control.
+    "peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+    "group-data-[disabled=true]:cursor-not-allowed group-data-[disabled=true]:opacity-50",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        sm: "text-xs",
+        md: "text-sm",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);
+
+type LabelVariants = VariantProps<typeof labelVariants>;
+
+type LabelProps = Omit<React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>, "asChild"> &
+  LabelVariants & {
+    required?: boolean;
+    optional?: boolean;
+    /**
+     * Localized text shown when `optional` is true. Defaults to "(optional)".
+     */
+    optionalText?: string;
+    /**
+     * Info-icon-with-tooltip rendered at the end of the label. The hint must
+     * itself sit inside a `<TooltipProvider>` somewhere up the tree —
+     * `AppShell` provides one for the whole app; otherwise wrap a section.
+     */
+    hint?: React.ReactNode;
+  };
+
+const Label = forwardRef<React.ElementRef<typeof LabelPrimitive.Root>, LabelProps>(function Label(
+  { className, size, required, optional, optionalText = "(optional)", hint, children, ...props },
+  ref,
+) {
+  if (required && optional) {
+    throw new Error("Label: `required` and `optional` are mutually exclusive.");
+  }
+
+  return (
+    <LabelPrimitive.Root ref={ref} className={cn(labelVariants({ size }), className)} {...props}>
+      <span>{children}</span>
+      {required ? (
+        <span aria-hidden="true" className="text-destructive ms-0.5">
+          *
+        </span>
+      ) : null}
+      {optional ? (
+        <span className="text-muted-foreground ms-1 font-normal">{optionalText}</span>
+      ) : null}
+      {hint !== undefined && hint !== null ? (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              tabIndex={0}
+              aria-label="More info"
+              className={cn(
+                "ms-1 inline-flex items-center justify-center rounded-full",
+                "text-muted-foreground hover:text-foreground",
+                "focus-visible:ring-ring focus-visible:ring-offset-background focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none",
+                "[&_svg]:size-3.5 [&_svg]:shrink-0",
+              )}
+            >
+              <RiInformationLine />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent multiline maxWidth={240}>
+            {hint}
+          </TooltipContent>
+        </Tooltip>
+      ) : null}
+    </LabelPrimitive.Root>
+  );
+});
+Label.displayName = "Label";
+
+export { Label, labelVariants };
+export type { LabelProps };

package/components/ui/page-header.stories.tsx

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiAddLine, RiHome4Line } from "@remixicon/react";
+
+import { Badge } from "./badge";
+import { Breadcrumbs } from "./breadcrumb";
+import { Button } from "./button";
+import {
+  PageHeader,
+  PageHeaderActions,
+  PageHeaderBadge,
+  PageHeaderBreadcrumb,
+  PageHeaderDescription,
+  PageHeaderTitle,
+  PageHeaderTop,
+} from "./page-header";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "./tabs";
+
+const meta: Meta<typeof PageHeader> = {
+  title: "Layout/PageHeader",
+  component: PageHeader,
+  parameters: { layout: "padded" },
+  argTypes: {
+    variant: { control: "select", options: ["default", "compact", "splash"] },
+    size: { control: "select", options: ["sm", "md", "lg"] },
+    divider: { control: "boolean" },
+    sticky: { control: "boolean" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PageHeader>;
+
+export const Default: Story = {
+  args: {
+    title: "Customers",
+    description: "Manage customers and their billing details.",
+    actions: (
+      <>
+        <Button variant="outline">Import</Button>
+        <Button leftIcon={<RiAddLine />}>Add customer</Button>
+      </>
+    ),
+    divider: true,
+  },
+};
+
+export const Compact: Story = {
+  args: { variant: "compact", title: "Settings", divider: true },
+};
+
+export const Splash: Story = {
+  args: {
+    variant: "splash",
+    title: "Welcome back",
+    description: "Here's what's happening with your business today.",
+  },
+};
+
+export const WithBreadcrumb: Story = {
+  args: {
+    title: "Order #1248",
+    description: "Created 3 days ago",
+    breadcrumb: (
+      <Breadcrumbs
+        items={[
+          { label: "Home", href: "/", icon: <RiHome4Line /> },
+          { label: "Orders", href: "/orders" },
+          { label: "Order #1248" },
+        ]}
+      />
+    ),
+    actions: <Button>Update</Button>,
+    divider: true,
+  },
+};
+
+export const WithBackButton: Story = {
+  args: {
+    title: "Edit customer",
+    description: "Update billing and contact info.",
+    backHref: "/customers",
+    actions: <Button>Save</Button>,
+    divider: true,
+  },
+};
+
+export const WithTabs: Story = {
+  render: () => (
+    <PageHeader
+      title="Project Apollo"
+      description="Long-running platform initiative."
+      divider
+      tabs={
+        <Tabs defaultValue="overview" variant="line">
+          <TabsList>
+            <TabsTrigger value="overview">Overview</TabsTrigger>
+            <TabsTrigger value="activity">Activity</TabsTrigger>
+            <TabsTrigger value="settings">Settings</TabsTrigger>
+          </TabsList>
+          <TabsContent value="overview" />
+          <TabsContent value="activity" />
+          <TabsContent value="settings" />
+        </Tabs>
+      }
+      actions={<Button>Invite</Button>}
+    />
+  ),
+};
+
+export const Composed: Story = {
+  render: () => (
+    <PageHeader variant="default" size="md" divider>
+      <PageHeaderBreadcrumb>
+        <Breadcrumbs
+          items={[{ label: "Home", href: "/", icon: <RiHome4Line /> }, { label: "Team" }]}
+        />
+      </PageHeaderBreadcrumb>
+      <PageHeaderTop>
+        <PageHeaderTitle as="h1">Team</PageHeaderTitle>
+        <PageHeaderBadge>
+          <Badge size="sm" variant="info">
+            12 members
+          </Badge>
+        </PageHeaderBadge>
+        <span className="flex-1" />
+        <PageHeaderActions>
+          <Button variant="outline">Filter</Button>
+          <Button>Invite</Button>
+        </PageHeaderActions>
+      </PageHeaderTop>
+      <PageHeaderDescription>
+        Manage roles and access for everyone on the workspace.
+      </PageHeaderDescription>
+    </PageHeader>
+  ),
+};