@emara/ui 1.1.0

package/components/ui/toast.stories.tsx

@@ -0,0 +1,169 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Button } from "./button";
+import { Toaster, toast } from "./toast";
+
+const meta: Meta = {
+  title: "Overlays/Toast",
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <div>
+        <Story />
+        <Toaster />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <Button onClick={() => toast("Saved your changes")}>Show toast</Button>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Button onClick={() => toast("Plain notification")}>default</Button>
+      <Button
+        variant="success"
+        onClick={() => toast.success("Item saved", { description: "Saved 2 seconds ago." })}
+      >
+        success
+      </Button>
+      <Button
+        variant="warning"
+        onClick={() => toast.warning("Storage nearly full")}
+      >
+        warning
+      </Button>
+      <Button variant="info" onClick={() => toast.info("New release available")}>
+        info
+      </Button>
+      <Button
+        variant="destructive"
+        onClick={() => toast.error("Couldn't save — try again", { description: "Network error." })}
+      >
+        error
+      </Button>
+      <Button variant="outline" onClick={() => toast.loading("Saving…")}>
+        loading
+      </Button>
+    </div>
+  ),
+};
+
+export const WithAction: Story = {
+  render: () => (
+    <Button
+      onClick={() =>
+        toast("Email archived", {
+          description: "Moved to All Mail.",
+          action: { label: "Undo", onClick: () => toast.success("Restored") },
+        })
+      }
+    >
+      Toast with action
+    </Button>
+  ),
+};
+
+export const PromiseToast: Story = {
+  name: "Promise",
+  render: () => (
+    <Button
+      onClick={() => {
+        const p = new globalThis.Promise<{ id: string }>((resolve, reject) => {
+          setTimeout(() => {
+            if (Math.random() > 0.3) resolve({ id: "42" });
+            else reject(new Error("Network timeout"));
+          }, 1500);
+        });
+        toast.promise(p, {
+          loading: "Saving order…",
+          success: (data) => `Order #${data.id} placed`,
+          error: (err) => `Failed: ${(err as Error).message}`,
+        });
+      }}
+    >
+      Run promise
+    </Button>
+  ),
+};
+
+export const Dismissible: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Button onClick={() => toast.info("Click the X to dismiss me")}>Default</Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.info("Sticky — explicitly dismissible=false", { dismissible: false })
+        }
+      >
+        Sticky
+      </Button>
+      <Button variant="ghost" onClick={() => toast.dismiss()}>
+        Dismiss all
+      </Button>
+    </div>
+  ),
+};
+
+export const Positions: Story = {
+  decorators: [],
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      {(
+        [
+          "top-start",
+          "top-center",
+          "top-end",
+          "bottom-start",
+          "bottom-center",
+          "bottom-end",
+        ] as const
+      ).map((pos) => (
+        <div key={pos} className="rounded-md border border-border p-3 text-sm">
+          <p className="mb-2 text-xs text-muted-foreground">{pos}</p>
+          <Toaster position={pos} />
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => toast.info(`Toast at ${pos}`)}
+          >
+            Show
+          </Button>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const RichColors: Story = {
+  decorators: [
+    (Story) => (
+      <div>
+        <Story />
+        <Toaster richColors />
+      </div>
+    ),
+  ],
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Button variant="success" onClick={() => toast.success("Looks great")}>
+        success
+      </Button>
+      <Button variant="destructive" onClick={() => toast.error("Looks worse")}>
+        error
+      </Button>
+      <Button variant="warning" onClick={() => toast.warning("Pay attention")}>
+        warning
+      </Button>
+    </div>
+  ),
+};

package/components/ui/toast.tsx

@@ -0,0 +1,250 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+  RiCheckLine,
+  RiCloseCircleLine,
+  RiErrorWarningLine,
+  RiInformationLine,
+  RiLoader2Line,
+} from "@remixicon/react";
+import {
+  Toaster as SonnerToaster,
+  toast as sonnerToast,
+  type ToasterProps as SonnerToasterProps,
+} from "sonner";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-3-components.md §7. Wraps sonner with Emara
+// variants, RTL-aware positions, and per-toast options.
+
+// ----------------------------------------------------------------------------
+// Toaster
+// ----------------------------------------------------------------------------
+
+type LogicalPosition =
+  | "top-start"
+  | "top-end"
+  | "top-center"
+  | "bottom-start"
+  | "bottom-end"
+  | "bottom-center";
+
+const positionToSonner: Record<LogicalPosition, NonNullable<SonnerToasterProps["position"]>> = {
+  "top-start": "top-left",
+  "top-end": "top-right",
+  "top-center": "top-center",
+  "bottom-start": "bottom-left",
+  "bottom-end": "bottom-right",
+  "bottom-center": "bottom-center",
+};
+
+/**
+ * Sonner uses `left`/`right` physical sides for positions. In RTL,
+ * `top-start` should mean visually top-right, and `top-end` should mean
+ * top-left. We resolve at runtime based on `<html dir>`.
+ */
+function resolveDir(): "ltr" | "rtl" {
+  if (typeof document === "undefined") return "ltr";
+  return document.documentElement.dir === "rtl" ? "rtl" : "ltr";
+}
+
+function resolvePosition(p: LogicalPosition): NonNullable<SonnerToasterProps["position"]> {
+  const dir = resolveDir();
+  if (dir === "rtl") {
+    if (p === "top-start") return "top-right";
+    if (p === "top-end") return "top-left";
+    if (p === "bottom-start") return "bottom-right";
+    if (p === "bottom-end") return "bottom-left";
+  }
+  return positionToSonner[p];
+}
+
+type ToasterProps = Omit<SonnerToasterProps, "position"> & {
+  position?: LogicalPosition;
+  // ---- Emara additions ----
+  /**
+   * Whether hovering a toast pauses its dismiss timer. Sonner's default
+   * is `true`; that matches our spec default. **Known limitation:**
+   * Sonner doesn't expose a Toaster-level override today, so flipping
+   * this prop to `false` is currently a no-op. Tracked for v1.x.
+   */
+  pauseOnHover?: boolean;
+  /**
+   * Whether clicking a toast dismisses it. Spec default `false` matches
+   * Sonner's default (click is inert). **Known limitation:** same as
+   * `pauseOnHover` — flipping to `true` is currently a no-op.
+   */
+  closeOnClick?: boolean;
+  /**
+   * Whether touch-swipe gestures dismiss a toast. Sonner's default is
+   * `true` on touch, matching spec. **Known limitation:** flipping
+   * to `false` is currently a no-op.
+   */
+  swipeToDismiss?: boolean;
+  /** Cap on concurrent visible toasts. Maps to Sonner's `visibleToasts`. */
+  maxVisible?: number;
+  /** Default dismiss timer in ms. */
+  defaultDuration?: number;
+};
+
+function Toaster({
+  position = "bottom-end",
+  pauseOnHover = true,
+  closeOnClick = false,
+  swipeToDismiss = true,
+  maxVisible,
+  defaultDuration = 4000,
+  expand,
+  gap,
+  richColors,
+  className,
+  toastOptions,
+  ...rest
+}: ToasterProps) {
+  // Sonner already handles pause-on-hover, no-close-on-click, and swipe on
+  // touch natively. These props are accepted in the public API for
+  // forward-compatibility but currently have no Sonner override. The voids
+  // declare intent without leaking the props through `...rest`.
+  void pauseOnHover;
+  void closeOnClick;
+  void swipeToDismiss;
+  // Re-resolve position on dir change. Sonner's `position` is set once at
+  // mount, but consumers may flip dir at runtime — re-mount the Toaster by
+  // keying on the resolved position.
+  const [resolved, setResolved] = useState(() => resolvePosition(position));
+
+  useEffect(() => {
+    setResolved(resolvePosition(position));
+    if (typeof document === "undefined") return;
+    const obs = new MutationObserver(() => setResolved(resolvePosition(position)));
+    obs.observe(document.documentElement, { attributes: true, attributeFilter: ["dir"] });
+    return () => obs.disconnect();
+  }, [position]);
+
+  // exactOptionalPropertyTypes: don't forward optional props with `undefined`.
+  const passthrough: Partial<SonnerToasterProps> = {};
+  if (expand !== undefined) passthrough.expand = expand;
+  if (gap !== undefined) passthrough.gap = gap;
+  if (richColors !== undefined) passthrough.richColors = richColors;
+  if (maxVisible !== undefined) passthrough.visibleToasts = maxVisible;
+
+  return (
+    <SonnerToaster
+      key={resolved}
+      position={resolved}
+      duration={defaultDuration}
+      closeButton
+      // Anchor sonner's stack layer to the design-token --z-toast (1700) so
+      // toasts always sit above tooltips, popovers, and modals.
+      style={{ zIndex: "var(--z-toast)" } as React.CSSProperties}
+      // Emara-tinted defaults — colors track the active theme.
+      toastOptions={{
+        ...toastOptions,
+        className: cn(
+          "border border-border bg-popover text-popover-foreground shadow-md",
+          (toastOptions as { className?: string } | undefined)?.className,
+        ),
+      }}
+      className={cn(className)}
+      {...passthrough}
+      {...rest}
+    />
+  );
+}
+
+// ----------------------------------------------------------------------------
+// toast() API — variant-keyed shortcuts + promise helper.
+// ----------------------------------------------------------------------------
+
+type EmaraToastOptions = {
+  id?: string | number;
+  description?: React.ReactNode;
+  duration?: number;
+  icon?: React.ReactNode;
+  action?: { label: string; onClick: () => void };
+  cancel?: { label: string; onClick?: () => void };
+  /**
+   * Show a countdown progress bar. Sonner's underlying option is `closeButton`
+   * and built-in progress; we expose the spec name.
+   */
+  progress?: boolean;
+  dismissible?: boolean;
+};
+
+function variantIcon(variant: "default" | "success" | "warning" | "info" | "error" | "loading") {
+  switch (variant) {
+    case "success":
+      return <RiCheckLine className="text-success size-4" />;
+    case "warning":
+      return <RiErrorWarningLine className="text-warning size-4" />;
+    case "info":
+      return <RiInformationLine className="text-info size-4" />;
+    case "error":
+      return <RiCloseCircleLine className="text-destructive size-4" />;
+    case "loading":
+      return <RiLoader2Line className="size-4 animate-spin" />;
+    default:
+      return undefined;
+  }
+}
+
+function toSonnerOptions(
+  options?: EmaraToastOptions,
+  variant?: "default" | "success" | "warning" | "info" | "error" | "loading",
+) {
+  if (!options && !variant) return undefined;
+  const out: Record<string, unknown> = {};
+  if (options?.id !== undefined) out.id = options.id;
+  if (options?.description !== undefined) out.description = options.description;
+  if (options?.duration !== undefined) out.duration = options.duration;
+  if (options?.action) out.action = options.action;
+  if (options?.cancel) out.cancel = options.cancel;
+  if (options?.dismissible !== undefined) out.dismissible = options.dismissible;
+  if (options?.icon !== undefined) {
+    out.icon = options.icon;
+  } else if (variant && variant !== "default") {
+    out.icon = variantIcon(variant);
+  }
+  return out;
+}
+
+/**
+ * `toast(message, options)` and its variant-shortcut siblings. Wraps sonner's
+ * imperative API so consumers don't import sonner directly.
+ */
+function toastBase(message: React.ReactNode, options?: EmaraToastOptions) {
+  return sonnerToast(message as string, toSonnerOptions(options, "default"));
+}
+
+const toast = Object.assign(toastBase, {
+  success: (message: React.ReactNode, options?: EmaraToastOptions) =>
+    sonnerToast.success(message as string, toSonnerOptions(options, "success")),
+  warning: (message: React.ReactNode, options?: EmaraToastOptions) =>
+    sonnerToast.warning(message as string, toSonnerOptions(options, "warning")),
+  info: (message: React.ReactNode, options?: EmaraToastOptions) =>
+    sonnerToast.info(message as string, toSonnerOptions(options, "info")),
+  error: (message: React.ReactNode, options?: EmaraToastOptions) =>
+    sonnerToast.error(message as string, toSonnerOptions(options, "error")),
+  loading: (message: React.ReactNode, options?: EmaraToastOptions) =>
+    sonnerToast.loading(message as string, toSonnerOptions(options, "loading")),
+  promise: <T,>(
+    promise: Promise<T> | (() => Promise<T>),
+    msgs: {
+      loading: React.ReactNode;
+      success: React.ReactNode | ((data: T) => React.ReactNode);
+      error: React.ReactNode | ((err: unknown) => React.ReactNode);
+    },
+  ) =>
+    sonnerToast.promise(promise, {
+      loading: msgs.loading as string,
+      success: msgs.success as (data: T) => string,
+      error: msgs.error as (err: unknown) => string,
+    }),
+  dismiss: (id?: string | number) => sonnerToast.dismiss(id),
+  custom: sonnerToast.custom,
+});
+
+export { Toaster, toast };
+export type { ToasterProps, EmaraToastOptions, LogicalPosition };

package/components/ui/tooltip.stories.tsx

@@ -0,0 +1,146 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiInformationLine } from "@remixicon/react";
+
+import { Button } from "./button";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip";
+
+const meta: Meta = {
+  title: "Foundations/Tooltip",
+  decorators: [
+    (Story) => (
+      <TooltipProvider delayDuration={200}>
+        <Story />
+      </TooltipProvider>
+    ),
+  ],
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Hover me</Button>
+      </TooltipTrigger>
+      <TooltipContent>Add to your library</TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex gap-3">
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline" size="sm">
+            default
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent variant="default">Dark bubble</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline" size="sm">
+            inverse
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent variant="inverse">Light bubble</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline" size="sm">
+            kbd
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent kbd={["⌘", "K"]}>Search</TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+};
+
+export const Sides: Story = {
+  render: () => (
+    <div className="grid grid-cols-2 gap-8">
+      {(["top", "right", "bottom", "left"] as const).map((side) => (
+        <Tooltip key={side}>
+          <TooltipTrigger asChild>
+            <Button variant="outline" size="sm">
+              {side}
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side={side}>side={side}</TooltipContent>
+        </Tooltip>
+      ))}
+    </div>
+  ),
+};
+
+export const Multiline: Story = {
+  render: () => (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="ghost" size="icon-sm" aria-label="More info">
+          <RiInformationLine />
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent multiline maxWidth={220}>
+        This tooltip wraps over multiple lines so longer help text remains readable.
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const KeyboardShortcut: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button>Save</Button>
+        </TooltipTrigger>
+        <TooltipContent kbd={["⌘", "S"]} />
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Open command palette</Button>
+        </TooltipTrigger>
+        <TooltipContent kbd={["⌘", "K"]}>Command palette</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Undo</Button>
+        </TooltipTrigger>
+        <TooltipContent kbd={["⌘", "Z"]}>Undo last action</TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+};
+
+export const NoArrow: Story = {
+  render: () => (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">No arrow</Button>
+      </TooltipTrigger>
+      <TooltipContent arrow={false}>Plain bubble</TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const OpensOnFocus: Story = {
+  render: () => (
+    <div className="text-muted-foreground text-sm">
+      Tab to the button below — the tooltip should open on focus too.
+      <div className="mt-3">
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>Focus me with Tab</Button>
+          </TooltipTrigger>
+          <TooltipContent>Visible on hover AND keyboard focus.</TooltipContent>
+        </Tooltip>
+      </div>
+    </div>
+  ),
+};